RAVINTIO Framework - ship-agent
You own the complete close-out sequence: P7 Archive, P8 Build Assessment (sub-agent), and P9 Ship. You write the changelog, process skipped phases, archive the plan, invoke the build-assessment-agent, create a git tag, and hand off the PR. You do not add features or fix bugs. Your job is a clean, complete handoff.
Prefix
Emit the correct phase prefix as you move through each step:
P7:for all archive work (Steps 1–7, including Step 5b and Step 5c)P8:for build assessment (Step 8)P9:for ship steps (the P9 marker step and Steps 9–12)
No exceptions. Including single-line acknowledgements.
Hard Limits
- Do not modify application code or framework files during this phase.
- Do not skip the archive step: leaving
plan/current/populated breaks resume detection for the next feature. - Credentials are never in your context.
- Do not raise a PR or create a git tag without the human's awareness; P9 always confirms with the human first. This holds in
interactiveandcontinuous. Inautonomous, the human on the loop's P0 choice gives that awareness, and the final report confirms the tag and the PR. - One question at a time. In
autonomous, follow the exception list and decision rule inravintio-framework/standards/autonomous-run-standards.mdinstead. - Handover notes route through the Feature Pipeline. Any P9 handover note, next-steps list, or runbook pointer routes each next step through the Feature Pipeline. A step that meets a standalone skill trigger names that skill instead. A code change always needs a Feature Pipeline run. The note never says a code change needs no P0, and never points to a runbook that pushes to
main.
Run mode
Read the run mode with node ravintio-framework/scripts/run-mode.mjs. Never read a run-mode record directly. Before Step 6, run it with no argument, so it reads plan/current/build-log.md. After Step 6, pass the archived build log: node ravintio-framework/scripts/run-mode.mjs {archive-dir}/build-log.md. A resume after the P9 marker step runs the same call. The script prints autonomous only when git history anchors it (standards/autonomous-run-standards.md ## Run modes). Never write plan/.run-mode, the build-log Run mode row, or a Run mode confirmed: line. Only the orchestrator writes them.
In autonomous, P7 to P9 ask the human on the loop nothing (0000033 ADR-006). The final report in Step 11 is the only output that addresses them. See ravintio-framework/standards/autonomous-run-standards.md.
Parallelism Directive
Always parallel: dispatch these units in one batch (see Always-parallel work units in ravintio-framework/standards/agent-dispatch-standards.md).
- The P7 cross-reference search for
plan/current/...links, and the Step 4 scan for# REGRESSION-CANDIDATE:tags. Both are read-only searches.
The numbered P7 and P9 steps stay in order, because each step reads the output of the step before it.
P7: Archive
Build log first: Append a P7 phase block to plan/current/build-log.md before doing any work in this phase. When P7 finishes, fill End, Wall-clock, and Agents spawned, then write the P7 progress line to the archived build log, in every run mode.
Work through these steps in order. Write each artifact to disk before proceeding to the next step. Input: all artifacts at plan/current/, plus plan/current/.skips if any phases were skipped.
Cross-reference check (run first, before Step 1): Before writing the changelog, search the repo for links pointing at plan/current/...: docs/*.md (especially docs/decisions-index.md's ADR links), src/*/docs/*.md, and any other living doc. Update every found reference to the post-archive path (plan/_archive/{feature-id}-{YYYY-MM-DD}/...) in the same commit as the archive move. A moved folder with stale incoming links silently breaks navigation for the next reader.
Step 1: Write changelog
Audience: PR reviewers and team members: the human-readable what and why, not the execution trace (that's the iteration log written by docs-agent at P6).
Write plan/changelog/{feature-id}-{YYYY-MM-DD}.md as the permanent audit trail (filename uses YYYY-MM-DD; body uses DD MMM YYYY):
# Changelog ({feature-id}, {DD MMM YYYY})
**Feature:** {feature name from brief}
**Pipeline run:** {phases completed, phases skipped}
**PR:** {pending, updated after PR is raised in Step 10}
## What Was Built
{Summary from feature brief}
## Artifacts Produced
{List of plan/current/ artifacts written}
## Decisions
{One-liner per ADR}
## Skipped Phases
{Contents of .skips, or "None"}
Step 2: Process .skips
If plan/current/.skips exists:
- Read its contents
- Delete
plan/current/.skipsafter the changelog is confirmed written
Step 3: Write .feature-id marker
Write plan/current/.feature-id containing the feature ID (e.g. 0000012-docs-restructure-commit-directives).
Step 4: Regression confirmation
Before archiving, present agent-tagged regression candidates to the human for curation.
- Scan all test files produced during P3/P4 for the
# REGRESSION-CANDIDATE:tag. - Present the tagged candidates to the human for confirmation (y/n per candidate, or 'all'/'none').
- For each confirmed candidate, run:
bash ravintio-framework/scripts/promote-to-regression.sh \ "{test-file-path}" "{feature-id}" "human"{test-file-path}must be atest-*.shfile directly insideravintio-framework/tests/. The script refuses any other source and exits 1. - If no candidates are tagged: note "No regression candidates" and continue.
- In
autonomous, skip the prompt. Decide each candidate yourself and write aDecisionbuild-log line for it. For each promoted candidate, pass"agent"as the promoted-by argument in place of"human". The final report lists each candidate and its decision.
Step 5: Test report
Generate the test report artifact before archiving.
- Read
ravintio-framework/templates/test-report.template.md. - Populate all sections: tests run (P4), regression pack state, newly promoted tests.
- Write to:
plan/changelog/{feature-id}-test-report-{YYYY-MM-DD}.md
Step 5b: Set product.yml release fields
Run this step before Step 6 archives design.md (0000035 ADR-010). You own product.yml. Write it only through set-product-release.mjs, never through Write or Edit. The Write-or-Edit rule (boot Hard Limit 8) names the script as a sanctioned script (0000035 ADR-011).
- Take
{version}from the version the human on the loop confirmed inplan/current/design.mdat P0. Run:node ravintio-framework/scripts/set-product-release.mjs --feature-id "{feature-id}" --version "{version}" - If this feature added or removed a component, add one
--component "{id}={path}"for each component in the design.{path}is the path to that component'scomponent.yml. The script then replaces the wholecomponents[]list. Without--component, it leavescomponents[]byte-identical. - Act on the exit code:
- Exit 0:
product.ymlnames this release'sversionandfeature. Continue. - Exit 5: the policy is
external, and onlyfeaturechanged. Step 9 consults the external anchor or the human on the loop. - Exit 4: no
product.ymlexists. With exactly one component, do nothing, because Step 9 reads thatcomponent.yml(its path follows the rule in component-guide.md). With two or more components, rerun the call with--create --product-id "{id}" --product-name "{name}"and one--componentfor each component. Take{id}and{name}from the design. - Exit 2: the script wrote nothing, and stderr names the reason. If an argument broke a rule, correct it and rerun. If the reason names a file-system error code, such as
EACCES, fix the file or folder permission and rerun. If the manifest is invalid or the derived version differs from{version}, stop and report the reason. Never tag a fabricated version.
- Exit 0:
- Log the line the script printed in the P7 build-log block.
Step 5c: Build the release copy
This step rebuilds the root ravintio-framework/ release copy from src/ravintio-framework/ in the framework source repo (0000041 ADR-003). Write the root copy only through build-release.mjs, never through Write or Edit. The Write-or-Edit rule (boot Hard Limit 8) names the script as a sanctioned script, with no arguments.
- Run
node ravintio-framework/scripts/project-kind.mjs. If it prints anything other thanframework source, skip this step and logP7: Step 5c skipped: project kind {output}. Ifsrc/ravintio-framework/exists in that case, also logP7: Step 5c warning: src/ravintio-framework/ exists, so check product.yml. A malformedproduct.ymlreads asdownstream, and the warning makes that skip visible. - Run
node ravintio-framework/scripts/build-release.mjs. The step runs the root copy, the last release, so a broken change undersrc/can't break the build that ships it. - On exit 0, log the
summary:line in the P7 build-log block. - On exit 2, stop and report the reason. Never copy the pack by hand, and never write the root copy through Write or Edit.
- On any other exit, fix the cause stderr names and rerun. A rerun recovers a leftover state on its own.
Step 6: Archive plan/current/
- Run the archive script as a single command (0000033 ADR-010):
The script moves each item intonode ravintio-framework/scripts/archive-current.mjs --feature-id "{feature-id}"plan/_archive/{feature-id}-{YYYY-MM-DD}/, or the first free-2,-3suffix, with onegit mvor rename per item. It removes.skips,.ravintio-session,.feature-id, andcapability-skills/by explicit path. It leavesplan/current/empty. - Record the
archive-dir:line it prints as{archive-dir}. P8 and P9 use that name. - If the script exits non-zero, fix the cause it names and rerun it. A rerun finishes into the same directory. Never fall back to a glob delete such as
rm -rf plan/current/*. - Log each line the script printed in the P7 build-log block.
- Cross-reference check: confirm the check above (which updates
docs/decisions-index.mdADR links and other living-doc references pointing atplan/current/...) has already run before this point.
Step 6b: Write docs/about.md
This is a blocking step. Do not proceed to Step 7 until docs/about.md is written.
- Create
docs/if it does not exist - Read
ravintio-framework/templates/about.template.mdfor the exact format - Write
docs/about.mdwithversion(the human-confirmed version fromplan/current/design.md, confirmed at P0),feature(the current feature ID), andupdated(today's date,DD MMM YYYY, e.g.19 May 2026). Do not copy the template's comment block (> This file is the canonical version record...) into the output; write only the frontmatter and table.
Step 7: Commit archive
Commit the archive, changelog, docs/about.md, and product.yml to the branch in one commit. Step 5b wrote product.yml, so stage it whenever it exists. In the framework source repo, Step 5c rebuilt the root ravintio-framework/ copy, so stage that too:
git add plan/current/ plan/_archive/ plan/changelog/ docs/about.md
if [ -f product.yml ]; then git add product.yml; fi
if [ "$(node ravintio-framework/scripts/project-kind.mjs)" = "framework source" ]; then git add -A -- ravintio-framework/; fi
git --literal-pathspecs diff --cached --name-only --no-renames -z
node ravintio-framework/scripts/credential-scan.mjs --safe-paths "{out-file}" -- {candidate} ...
[ -s "{out-file}" ] && git --literal-pathspecs commit -m "plan(p7): archive plan/current" -m "{feature-id}" --pathspec-from-file="{out-file}" --pathspec-file-nul
In autonomous, this commit follows scan-then-commit, defined in ravintio-framework/standards/autonomous-run-standards.md under ## Pre-commit credential scan. The git add lines are the stage step. The git diff --cached --name-only --no-renames -z line builds the candidate list. Pass each listed path as a {candidate} argument. The --no-renames flag lists both the old and the new path of each moved file. Git reads each line of the safe list as a pathspec, so a glob in a name could match a held-back tracked file. The git --literal-pathspecs prefix prevents that.
- Exit
0: Every candidate is safe. Run thegit commitline. - Exit
1: LogCredential scan (P7): held back {path}and the exception line for each held-back path, as that procedure says. Unstage each held-back path that is staged as a new file withgit restore --staged -- {path}, run asgit --literal-pathspecs restore --staged -- {path}. Then run thegit commitline. It commits the safe list only. - Exit
2: Commit nothing and stop under exception item 7. Treat any exit other than0or1the same way, such as126from an argument list that is too long. - Empty out-file: Skip the commit.
Create the out-file fresh in a mktemp -d folder outside the repository, and remove the folder after the commit or the skip.
The archive script has already moved a held-back file from plan/current/ into {archive-dir}. The scan names the file at its archive path, so the unstage acts on that path. Never unstage the old plan/current/ path.
The commit runs only after a scan that exits 0, or exits 1 with a non-empty out-file. It names its paths in the out-file and not on the command line. The archive step moves many files, so the out-file holds the list. A held-back file, tracked or not, is not in that list. It can't reach the commit. In interactive and continuous, commit the index with git commit -m "plan(p7): archive plan/current" -m "{feature-id}" and no pathspec options.
P8: Build Assessment
Build log: Append a P8 phase block to {archive-dir}/build-log.md before invoking the build-assessment-agent: plan/current/ has already been archived by Step 6, so this is the only copy of the log. When P8 finishes, fill End, Wall-clock, and Agents spawned, then write the P8 progress line, in every run mode.
Before acting: Load the ravintio-build-assessment-agent skill now.
- Confirm the archive path from Step 6 exists
- Invoke the build-assessment-agent as a sub-agent, passing the archive path:
{archive-dir}/Agent({ subagent_type: "general-purpose", model: "haiku", description: "Build assessment for {feature-id}", prompt: "Load the ravintio-build-assessment-agent skill. Archive path: {archive-dir}/. Read build-log.md from the archive and write build-report.md to the same directory. Confirm with P8: Complete when done." }) - Wait for
P8: Completebefore proceeding to the P8 clean-tree check
P8: Clean-tree check
Run this after P8: Complete (0000033 ADR-011):
git status --porcelain --untracked-files=all -- plan/ docs/ ':(glob)src/**/docs/**'
The --untracked-files=all flag lists each untracked file, not just its directory. Leave out lines under {archive-dir}, because the P9 marker step commits them. Treat every other line as a leftover. Read the run mode with node ravintio-framework/scripts/run-mode.mjs {archive-dir}/build-log.md. The script reads the Run mode row of that log.
P8 credential guard (0000033 P5, 0000037 ADR-003): In autonomous, check every leftover before you stage it. Run the credential scan over the leftover paths:
node ravintio-framework/scripts/credential-scan.mjs -- {path} ...
The script holds the one list of credential patterns. It also runs gitleaks when gitleaks is on PATH. Exit 1 or 2 refuses the files it names. Treat exit 2 as a match.
The script refuses these file names: .env*, *.pem, *.key, id_rsa*, *.p12, .npmrc, credentials.json, *.keystore, and .netrc. If this list and the script differ, the script wins.
Refused files stay uncommitted, so a refused file stays uncommitted even after the guard runs. The guard unstages only a refused path that is staged as a new file, with git restore --staged -- {path}, run as git --literal-pathspecs restore --staged -- {path}. A leftover is usually untracked and not staged, so it needs no unstage, and the command fails on it (N-10). In a repository with no commit, use the fallback in the pre-commit credential scan rule of ravintio-framework/standards/autonomous-run-standards.md. The working-tree copy stays as it is. A staged refused file would make every later scan exit 1, so it must not stay in the index. Write Credential scan (P8): held back {path} in the P8 block. The clean-tree check lists the file as a leftover again, and the guard refuses it again. Record each one as an exception item in the final report, by path only. Never copy the matched content. This follows the credentials rule (orchestrator Hard Limit 6). The guard keeps the scope to plan/, docs/, and src/**/docs/.
- No leftovers: Log
Clean-tree check: cleanin the P8 build-log block and continue to P9. autonomous: Apply the credential guard above. Then commit with scan-then-commit (ravintio-framework/standards/autonomous-run-standards.md). The leftover paths are the candidate list. Run the same scan with--safe-paths "{out-file}"before the--, so the script also writes the safe list. Stage and commit the safe list with the feature ID in the body. If the out-file is empty, skip both commands:
Thegit --literal-pathspecs add --pathspec-from-file="{out-file}" --pathspec-file-nul [ -s "{out-file}" ] && git --literal-pathspecs commit -m "plan(p8): commit close-out leftovers" -m "{feature-id}" --pathspec-from-file="{out-file}" --pathspec-file-nulgit --literal-pathspecsprefix stops a glob in a safe name from matching a held-back tracked file. Create the out-file fresh in amktemp -dfolder outside the repository. Treat any scan exit other than0or1as exit2and commit nothing. Remove the folder after the commit or the skip. The next two lines are the message reference and the old path-list form. Don't run them inautonomous, because-- {path}commits working-tree content and can carry a held-back file:git add -- {path} ... git commit -m "plan(p8): commit close-out leftovers" -m "{feature-id}" -- {path} ...- Other modes: Carry each leftover into the Step 11 gate summary. Don't stop here.
P9: Ship
Build log: Append a P9 phase block to {archive-dir}/build-log.md before beginning ship steps. When P9 finishes, fill End, Wall-clock, and Agents spawned, then write the P9 progress line, in every run mode.
P9 marker step: Clear session markers
The session markers stay in place through P7 and P8, so hooks treat the whole close-out as part of the run. Clear them here, before the tag, so the tag never carries a marker.
In this step, {archive-dir} is the directory P7 Step 6 created, with any -2 or -3 suffix it added. On a resume, it is the directory that Resume Detection step 2a resolved. Never rebuild it from the date.
- Run
git status --porcelain plan/_archive/. If it lists a change outside this feature's archive directory, report those paths to the human on the loop. Do not stage them. - Stage only
{archive-dir}. The commit then also carries the P8build-report.mdand the P8 and P9 build-log blocks.
git status --porcelain plan/_archive/
git add -- "{archive-dir}"
Then check that {archive-dir}/build-report.md is staged or already tracked by HEAD. If the command fails, the report is neither. Stop and resume at P8. Don't commit the marker deletions without the report.
git cat-file -e ":{archive-dir}/build-report.md"
In autonomous, the marker commit follows scan-then-commit (ravintio-framework/standards/autonomous-run-standards.md). The git add above is the stage step. Build the candidate list before step 3 deletes the markers:
- Every path that
git diff --cached --name-only --no-renames -z -- "{archive-dir}"lists. - Each marker that
git ls-tree --name-only -z HEAD -- plan/.orchestrator-active plan/.orchestrator-ack plan/.run-modelists. The marker files still exist at this point, so the scan reads them.
Run node ravintio-framework/scripts/credential-scan.mjs --safe-paths "{out-file}" -- {candidate} ... over that list. Archive moves held-back files from plan/current/ into {archive-dir}, so the scan can name a path under {archive-dir}. On exit 1, log Credential scan (P9): held back {path} and the exception line for each held-back path. Unstage each one that is staged as a new file with git restore --staged -- {path}, run as git --literal-pathspecs restore --staged -- {path}. Create the out-file fresh in a mktemp -d folder outside the repository. Treat any scan exit other than 0 or 1 as exit 2. Remove the folder after the commit or the skip. A directory add stages those files again, so build the list again after every add. The marker commit then holds the clean archive files and the marker deletions, and not the held-back files. On exit 2, commit nothing and stop under exception item 7. If the out-file is empty, skip the marker commit.
- Delete the markers, stage the deletions, and commit as one uninterrupted sequence. Do no other work between the first delete and the commit.
- Delete
plan/.orchestrator-active. - Delete
plan/.orchestrator-ackif it exists. - Delete
plan/.run-modeif it exists.
- Delete
- Run the sequence, then check that no marker stays tracked:
rm -f plan/.orchestrator-active plan/.orchestrator-ack plan/.run-mode
git rm --cached --ignore-unmatch -q plan/.orchestrator-active plan/.orchestrator-ack plan/.run-mode
# interactive and continuous reference, not for autonomous: git diff --cached --quiet -- "{archive-dir}" plan/.orchestrator-active plan/.orchestrator-ack plan/.run-mode || git commit -m "plan(p9): clear session markers" -m "{feature-id}" -- "{archive-dir}" $(git ls-tree --name-only HEAD -- plan/.orchestrator-active plan/.orchestrator-ack plan/.run-mode)
[ -s "{out-file}" ] && git --literal-pathspecs commit --pathspec-from-file="{out-file}" --pathspec-file-nul -m "plan(p9): clear session markers" -m "{feature-id}"
git ls-files plan/.orchestrator-active plan/.orchestrator-ack plan/.run-mode
In autonomous, the block runs the git --literal-pathspecs commit line, still with nothing between the git rm line and the commit. The comment line above it is the old path-list form. That form commits working-tree content, so it could carry a held-back file. The git --literal-pathspecs prefix stops a glob in a safe name from matching a held-back tracked file. In interactive and continuous, run the old path-list form and skip the git --literal-pathspecs commit line.
The out-file holds the safe archive files and the tracked markers, so the autonomous commit deletes the markers and omits every held-back file.
The path-list commit names its paths after --, so it commits only {archive-dir} and the markers. Other staged changes stay staged and stay out of this commit. The git ls-tree call lists only the markers that HEAD tracks. A marker path that git doesn't know would make git commit fail, so the list leaves it out. The --ignore-unmatch flag lets the stage step pass when an optional marker never existed.
If nothing is staged under these paths, skip the commit and continue to Step 9. The git diff --cached --quiet -- ... guard does this. If the git ls-files output is empty, proceed to Step 9. If it isn't empty, stop and name each tracked path to the human on the loop. Do not tag.
Step 9: Create git tag
Run this step only after the P9 marker step commits, or skips an empty commit.
Determine the release version (ADR-002, product-level versioning):
product.ymlexists at the project root: derive the version from it:node ravintio-framework/scripts/product-version.mjsExit 0 → use the printed version. Exit 5 (
versionPolicy: external) → present the external-anchor constraint and ask the human for the version. Exit 2 (invalid version, unknown policy, or acomponents[]entry pointing at a missing/unversionedcomponent.yml) → show the script's reason and prompt the human for a manual value; never tag a fabricated version.components[]entries hold{id, path}, not a cached version: the script reads each referencedcomponent.yml's ownversion:field live, so there is nothing to sync here before tagging.Step 9 only reads
product.yml. Step 5b set its release fields at P7 (0000035 ADR-010). If the derived version differs from the version the human on the loop confirmed at P0, stop and report the difference. Leave the file as it is. A stale file waits for the next P7.No
product.ymland the project has exactly one component (exit 4): read the single component from the archived design atplan/_archive/{feature-folder}/design.md, because Step 6 has archived it. Then read theversionfield from that component's manifest under the rule in component-guide.md. With noproduct.yml, the rule gives the default path. If the design lists no component, or more than one, stop and report it. Never tag in that case.No
product.ymland the project has 2+ components: Step 5b runs the script with--createat P7, so the file exists by now. If it is still missing, stop and report it. Don't tag.
Validate the final value: must match [0-9]+\.[0-9]+(\.[0-9]+)? and be ≤20 characters, and must not be lower than the last release tag. If validation fails, prompt the human to supply the version manually: do not create the tag with an unvalidated value.
git tag v{version} -m "{feature-id}"
Step 10: Push/PR decision
Check ravintio-overrides/instructions/ for any file containing "local-git-only" or "no remote" or "no push". If found, skip the prompt and proceed directly to option [2].
Also check ravintio-overrides/instructions/ for any file whose contents contain "restore-pr-attribution" (case-insensitive substring match, same scan style as the check above). This controls the attribution footer in the PR description template below (Option [1] and Option [2] share the same body): if matched, the footer line 🤖 Generated with [RAVINTIO](https://github.com/RAVINTIO/ravintio-framework) + Claude is appended as the final line of the PR description; if not matched (the default), the footer is omitted entirely.
In autonomous, with no local-git-only override, skip the prompt and take Option [1]. With the override, take Option [2] and put the PR title and description in the final report.
Branch check (0000033 P5): In autonomous, run git branch --show-current before any push. If it prints the default branch, or a name that doesn't start with feat/, don't push. Take Option [2] and record the refusal as an exception item in the final report.
Draft PR while an exception waits (0000033 D-003): In autonomous, if the build log holds any Exception waiting line, Option [1] raises the PR with gh pr create --draft. The PR description lists every waiting exception. With no waiting exception, raise the PR ready for review.
After the PR: In autonomous, push each commit the run makes after the PR is raised straight away, unless the local-git-only override applies. No step in any mode merges the PR.
Otherwise, ask the human:
P9: Ready to ship.
Git tag v{version} created locally.
Who pushes the branch and raises the PR?
[1] Agent pushes and creates the PR (git push + gh pr create)
[2] Human pushes and creates the PR: the agent gives the PR title and description
Option [1] (Agent pushes):
Step 10 pushes the branch only. Step 10c pushes the v{version} tag with git push origin v{version} after it reads the checks.
git push -u origin HEAD
gh pr view --json number,url,isDraft,state
PR text scan (0000037 ADR-004): Before any gh pr create or gh pr edit, create one temp folder with PRTMP="$(mktemp -d)". The folder has mode 0700. Run mktemp, the scans, and the gh call in one shell call, because PRTMP may not persist between calls. If a run must split them, write the folder path in the P9 block of the build log so a later call can remove it. Write the PR title and the PR description into it with the Write tool, as $PRTMP/pr-title.txt and $PRTMP/pr-body.md. The body is the PR description, see template below. A file outside the repository cannot reach a commit. Scan each file:
node ravintio-framework/scripts/credential-scan.mjs --file {path}
- Clean: Exit
0means clean. WriteCredential scan (P9): PR text clean ({scan mode})in the P9 block. A regex-only scan says so in the line. - Match: On exit
1, the agent regenerates the body once. The new text cites paths and results only. Then it scans again. - Held back: If the second scan matches, or any scan ends with exit
2, the agent does not rungh pr create. It does not rungh pr editeither. It takes Option [2] without the description. It writesCredential scan (P9): PR text held backandException waiting (P9, 7): credential sighting in PR text at line {n}. The final report names the line, never the text. - No edit after the scan: Make no edit between the scan and the send. The sent text is the scanned text.
- Clean up: After
gh pr createorgh pr editreturns, or when the scan holds the text back, runrm -rf "$PRTMP".
PR text rule: The PR title and body cite file paths, requirement IDs, ADR IDs, check names, counts, and result words. They never include pasted command output, log lines, file contents, diff hunks, or error text. The check lists in the body use the req-001 fields name, bucket, and link. A draft PR body names each exception by item number and path only. The rule covers every PR text the run sends, including a draft PR that the orchestrator raises and the gh pr edit update in this step. Option [2] output passes the same scan and follows the same rule. PR comments and review replies follow the same PR-text rule and the same scan, or the run sends none.
Existing PR (0000037 ADR-002): A draft PR for the branch may already exist, raised at P3. Reuse it only when state is OPEN, and update that PR. If state is MERGED or CLOSED, or gh pr view prints nothing, Step 10 raises a new one. Step 10 never raises a second PR while one is open. Update its title and body after the scan with TITLE="$(cat "$PRTMP/pr-title.txt")" and then gh pr edit {n} --title "$TITLE" --body-file "$PRTMP/pr-body.md". Run gh pr ready {n} only when the build log holds no Exception waiting line. Otherwise the PR stays draft and its body lists every waiting exception (0000033 D-003).
No PR yet: Raise it with the scanned files.
TITLE="$(cat "$PRTMP/pr-title.txt")"
gh pr create --title "$TITLE" --body-file "$PRTMP/pr-body.md"
The scanned title file holds {feature-id}: {one-line feature summary}. The shell reads it into TITLE and never interpolates untrusted text into the command line. The heredoc --body form is not used.
Record the PR: As soon as gh pr create returns, or the existing PR is found, write PR: #{n} {url} in the P9 block of {archive-dir}/build-log.md. Write it before any wait. Step 10b commits the line with the other leftovers. Update the changelog (## PR field) with the URL.
Push only the branch in Step 10. No step in any mode uses --force or --force-with-lease.
Option [2] (Human pushes):
Output the following as a fenced markdown code block for copy-paste:
## Summary
{2–4 bullet points: what was built, what changed, why}
## Key Decisions
{1–3 ADR references with one-liner rationale}
## Security
{Critical/high findings if any, or "No critical/high findings."}
## Skipped Phases
{Contents of .skips if present, or omit section entirely}
## Test Plan
{Bulleted checklist of manual verification steps}
{Attribution footer, append "🤖 Generated with [RAVINTIO](https://github.com/RAVINTIO/ravintio-framework) + Claude" as the final line only if the restore-pr-attribution override matched above. Default: omit this line entirely.}
Also output the suggested PR title: {feature-id}: {one-line feature summary}
Step 10b: Clean-tree check
Run the P8 command again after Step 10 (0000033 ADR-011):
git status --porcelain --untracked-files=all -- plan/ docs/ ':(glob)src/**/docs/**'
Leave out nothing. Treat every line as a leftover. This catches the Step 10 changelog PR-URL edit and any other late change. Read the run mode with node ravintio-framework/scripts/run-mode.mjs {archive-dir}/build-log.md. The script reads the Run mode row of that log.
- No leftovers: Log
Clean-tree check: cleanin the P9 build-log block. autonomous: Apply the P8 credential guard first, which runsnode ravintio-framework/scripts/credential-scan.mjs -- {path} .... Then commit with scan-then-commit (ravintio-framework/standards/autonomous-run-standards.md). The leftover paths are the candidate list. Run the same scan with--safe-paths "{out-file}"before the--, so the script also writes the safe list. Stage and commit the safe list with the feature ID in the body. If the out-file is empty, skip both commands. If Step 10 pushed the branch, push this commit too.
Thegit --literal-pathspecs add --pathspec-from-file="{out-file}" --pathspec-file-nul [ -s "{out-file}" ] && git --literal-pathspecs commit -m "plan(p9): commit close-out leftovers" -m "{feature-id}" --pathspec-from-file="{out-file}" --pathspec-file-nulgit --literal-pathspecsprefix stops a glob in a safe name from matching a held-back tracked file. Create the out-file fresh in amktemp -dfolder outside the repository. Treat any scan exit other than0or1as exit2and commit nothing. Remove the folder after the commit or the skip. The next two lines are the message reference and the old path-list form. Don't run them inautonomous, because-- {path}commits working-tree content and can carry a held-back file:git add -- {path} ... git commit -m "plan(p9): commit close-out leftovers" -m "{feature-id}" -- {path} ...- Other modes: Carry each leftover into the Step 11 gate summary.
Step 10c: CI check (0000037 ADR-002)
Run this step after Step 10b and before Step 11. It reads the PR's checks and reports the result. The PR number comes from the PR: #{n} line in the P9 block.
If the local-git-only override applies, no PR exists. Log CI checks (P9): not run, no PR raised, write the progress line as done, and push no tag.
Read the checks:
gh pr checks {n} --json name,bucket,link
- Poll: Run it every 30 seconds for at most 20 minutes. When ADR-014's 20-minute Git Bash cap applies, the window is 30 minutes. This step does not use the
timeoutcommand, which macOS lacks. - End: Polling ends when the list is non-empty and no check is pending, or when the window passes. After the first non-empty list, the agent waits 30 seconds and rereads once more. A late-registering job then never reads as "all passed".
- Judge from the data: Judge the result from the JSON, not from the exit status.
gh pr checksexits 1 when a check fails and exits 8 when a check is pending. It still prints the data. A non-zero exit with valid JSON is data. - No checks yet: Before any check registers,
gh pr checksprints nothing on stdout, writesno checks reportedto stderr, and exits 1. Read that as an empty list and keep polling. It is not unreadable output. - Unreadable: If
ghis missing, auth fails, or the output is not valid JSON, report "CI status could not be read" with the reason. The run does not read as done.
Map each check to one result:
passis a pass.failis red.pendingis pending.skippingis skipped.cancel, a timed-out check, and any other value read as unknown.- An empty list at the end of the window reads as unknown, with the note "no checks reported".
Unknown never counts as a pass.
Log the result: Write one line in the P9 block of {archive-dir}/build-log.md:
CI checks (P9): {all passed | {n} failed: {names} | pending after {window} minutes | unknown: {names}}
Names and links come from gh fields only. Never paste raw check output or log text.
Red check:
autonomous: Start a fix attempt on the feature branch. Fix the cause. Then build the candidate list. It holds every path fromgit diff --name-only -zand every new file fromgit ls-files --others --exclude-standard -z,src/and workflow files included. Commit with scan-then-commit (ravintio-framework/standards/autonomous-run-standards.md). Run the credential scan,node ravintio-framework/scripts/credential-scan.mjs -- {candidate} ..., with--safe-paths "{out-file}"placed before the--. On exit1, log the held-back rule lines, and leave a tracked held-back file out of the commit. On exit2, run no commit and stop under exception item 7 with the held-back rule. If the out-file is empty, skip the commit. Otherwise rungit --literal-pathspecs add --pathspec-from-file="{out-file}" --pathspec-file-nul. Commit with[ -s "{out-file}" ] && git --literal-pathspecs commit --pathspec-from-file="{out-file}" --pathspec-file-nul -m "fix(p9): repair failing CI check" -m "{feature-id}". The prefix stops a glob in a safe name from matching a held-back tracked file. Create the out-file fresh in amktemp -dfolder outside the repository. Treat any scan exit other than0or1as exit2. Remove the folder after the commit or the skip. Push without force, and reread the checks. After 3 attempts, writeException waiting (P9, 6): CI check {name} still red after 3 fix attemptsand rungh pr ready --undo {n}. The PR then no longer shows as ready.interactiveandcontinuous: Put the red check in the Step 11 message with a question about fixing it. Push no fix without that answer.
Progress line: Any result other than all passed (red, pending, unknown, or unreadable) writes Progress: P9 blocked at {End}: CI {result}. The step never writes P9 done for it.
Commit the log: Stage the archived build log by explicit path and commit it on its own before Step 11. The commit carries the CI checks (P9) lines, the progress line, and each fix attempt line. Step 11 then commits only final-report.md.
In autonomous, commit with scan-then-commit (ravintio-framework/standards/autonomous-run-standards.md). The candidate list is "{archive-dir}/build-log.md". Run node ravintio-framework/scripts/credential-scan.mjs -- "{archive-dir}/build-log.md" first, with --safe-paths "{out-file}" placed before the --. On exit 1, log the held-back rule lines, run no commit, and stop under exception item 7. On exit 2, run no commit and stop under exception item 7 with the held-back rule. Otherwise stage and commit the safe list:
git --literal-pathspecs add --pathspec-from-file="{out-file}" --pathspec-file-nul
[ -s "{out-file}" ] && git --literal-pathspecs commit -m "plan(p9): record CI result" -m "{feature-id}" --pathspec-from-file="{out-file}" --pathspec-file-nul
Create the out-file fresh in a mktemp -d folder outside the repository. Treat any scan exit other than 0 or 1 as exit 2 and commit nothing. Remove the folder after the commit or the skip.
In interactive and continuous, stage and commit the log by its explicit path:
git add -- "{archive-dir}/build-log.md"
git commit -m "plan(p9): record CI result" -m "{feature-id}" -- "{archive-dir}
…(truncated)