# Ravintio Ship Agent

> RAVINTIO Framework - ship-agent

- Skill: `planifest/ravintio-ship-agent` (Agent Skill)
- Install (CLI): `npx get-skill add planifest/ravintio-ship-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/planifest/ravintio-ship-agent/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: planifest (https://skillmd.com/u/planifest)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/planifest/ravintio-ship-agent

---


# 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

1. Do not modify application code or framework files during this phase.
2. Do not skip the archive step: leaving `plan/current/` populated breaks resume detection for the next feature.
3. Credentials are never in your context.
4. 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 `interactive` and `continuous`. In `autonomous`, the human on the loop's P0 choice gives that awareness, and the final report confirms the tag and the PR.
5. **One question at a time.** In `autonomous`, follow the exception list and decision rule in `ravintio-framework/standards/autonomous-run-standards.md` instead.
6. **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`):

```markdown
# 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:
1. Read its contents
2. Delete `plan/current/.skips` after 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.

1. Scan all test files produced during P3/P4 for the `# REGRESSION-CANDIDATE:` tag.
2. Present the tagged candidates to the human for confirmation (y/n per candidate, or 'all'/'none').
3. For each confirmed candidate, run:
   ```bash
   bash ravintio-framework/scripts/promote-to-regression.sh \
     "{test-file-path}" "{feature-id}" "human"
   ```
   `{test-file-path}` must be a `test-*.sh` file directly inside `ravintio-framework/tests/`. The script refuses any other source and exits 1.
4. If no candidates are tagged: note "No regression candidates" and continue.
5. In `autonomous`, skip the prompt. Decide each candidate yourself and write a `Decision` build-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.

1. Read `ravintio-framework/templates/test-report.template.md`.
2. Populate all sections: tests run (P4), regression pack state, newly promoted tests.
3. 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).

1. Take `{version}` from the version the human on the loop confirmed in `plan/current/design.md` at P0. Run:
   ```bash
   node ravintio-framework/scripts/set-product-release.mjs --feature-id "{feature-id}" --version "{version}"
   ```
2. 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's `component.yml`. The script then replaces the whole `components[]` list. Without `--component`, it leaves `components[]` byte-identical.
3. Act on the exit code:
   - Exit 0: `product.yml` names this release's `version` and `feature`. Continue.
   - Exit 5: the policy is `external`, and only `feature` changed. Step 9 consults the external anchor or the human on the loop.
   - Exit 4: no `product.yml` exists. With exactly one component, do nothing, because Step 9 reads that `component.yml` (its path follows the rule in [component-guide.md](../../templates/component-guide.md)). With two or more components, rerun the call with `--create --product-id "{id}" --product-name "{name}"` and one `--component` for 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.
4. 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.

1. Run `node ravintio-framework/scripts/project-kind.mjs`. If it prints anything other than `framework source`, skip this step and log `P7: Step 5c skipped: project kind {output}`. If `src/ravintio-framework/` exists in that case, also log `P7: Step 5c warning: src/ravintio-framework/ exists, so check product.yml`. A malformed `product.yml` reads as `downstream`, and the warning makes that skip visible.
2. Run `node ravintio-framework/scripts/build-release.mjs`. The step runs the root copy, the last release, so a broken change under `src/` can't break the build that ships it.
3. On exit 0, log the `summary:` line in the P7 build-log block.
4. On exit 2, stop and report the reason. Never copy the pack by hand, and never write the root copy through **Write** or **Edit**.
5. 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/

1. Run the archive script as a single command (0000033 ADR-010):
   ```bash
   node ravintio-framework/scripts/archive-current.mjs --feature-id "{feature-id}"
   ```
   The script moves each item into `plan/_archive/{feature-id}-{YYYY-MM-DD}/`, or the first free `-2`, `-3` suffix, with one `git mv` or rename per item. It removes `.skips`, `.ravintio-session`, `.feature-id`, and `capability-skills/` by explicit path. It leaves `plan/current/` empty.
2. Record the `archive-dir:` line it prints as `{archive-dir}`. P8 and P9 use that name.
3. 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/*`.
4. Log each line the script printed in the P7 build-log block.
5. Cross-reference check: confirm the check above (which updates `docs/decisions-index.md` ADR links and other living-doc references pointing at `plan/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.

1. Create `docs/` if it does not exist
2. Read `ravintio-framework/templates/about.template.md` for the exact format
3. Write `docs/about.md` with `version` (the human-confirmed version from `plan/current/design.md`, confirmed at P0), `feature` (the current feature ID), and `updated` (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 the `git commit` line.
- **Exit `1`:** Log `Credential 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 with `git restore --staged -- {path}`, run as `git --literal-pathspecs restore --staged -- {path}`. Then run the `git commit` line. It commits the safe list only.
- **Exit `2`:** Commit nothing and stop under exception item 7. Treat any exit other than `0` or `1` the same way, such as `126` from 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.

1. Confirm the archive path from Step 6 exists
2. 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."
   })
   ```
3. Wait for `P8: Complete` before proceeding to the P8 clean-tree check

### P8: Clean-tree check

Run this after `P8: Complete` (0000033 ADR-011):

```bash
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:

```bash
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: clean` in 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:
  ```bash
  git --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-nul
  ```
  The `git --literal-pathspecs` prefix stops a glob in a safe name from matching a held-back tracked file. 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.
  The next two lines are the message reference and the old path-list form. Don't run them in `autonomous`, because `-- {path}` commits working-tree content and can carry a held-back file:
  ```bash
  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.

1. 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.
2. Stage only `{archive-dir}`. The commit then also carries the P8 `build-report.md` and the P8 and P9 build-log blocks.

```bash
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.

```bash
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-mode` lists. 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.

3. 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-ack` if it exists.
   - Delete `plan/.run-mode` if it exists.
4. Run the sequence, then check that no marker stays tracked:

```bash
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):

1. **`product.yml` exists at the project root**: derive the version from it:
   ```bash
   node ravintio-framework/scripts/product-version.mjs
   ```
   Exit 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 a `components[]` entry pointing at a missing/unversioned `component.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 referenced `component.yml`'s own `version:` 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.
2. **No `product.yml` and the project has exactly one component** (exit 4): read the single component from the archived design at `plan/_archive/{feature-folder}/design.md`, because Step 6 has archived it. Then read the `version` field from that component's manifest under the rule in [component-guide.md](../../templates/component-guide.md). With no `product.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.
3. **No `product.yml` and the project has 2+ components**: Step 5b runs the script with `--create` at 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.

```bash
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.

```bash
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:

```bash
node ravintio-framework/scripts/credential-scan.mjs --file {path}
```

- **Clean:** Exit `0` means clean. Write `Credential 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 run `gh pr create`. It does not run `gh pr edit` either. It takes Option [2] without the description. It writes `Credential scan (P9): PR text held back` and `Exception 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 create` or `gh pr edit` returns, or when the scan holds the text back, run `rm -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.

```bash
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:

```markdown
## 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):

```bash
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: clean` in the P9 build-log block.
- **`autonomous`:** Apply the P8 credential guard first, which runs `node 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.
  ```bash
  git --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-nul
  ```
  The `git --literal-pathspecs` prefix stops a glob in a safe name from matching a held-back tracked file. 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.
  The next two lines are the message reference and the old path-list form. Don't run them in `autonomous`, because `-- {path}` commits working-tree content and can carry a held-back file:
  ```bash
  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:**

```bash
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 `timeout` command, 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 checks` exits 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 checks` prints nothing on stdout, writes `no checks reported` to stderr, and exits 1. Read that as an empty list and keep polling. It is not unreadable output.
- **Unreadable:** If `gh` is 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:**

- `pass` is a pass.
- `fail` is red.
- `pending` is pending.
- `skipping` is 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 from `git diff --name-only -z` and every new file from `git 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 exit `1`, log the held-back rule lines, and leave a tracked held-back file out of the commit. On exit `2`, run no commit and stop under exception item 7 with the held-back rule. If the out-file is empty, skip the commit. Otherwise run `git --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 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. Push without force, and reread the checks. After 3 attempts, write `Exception waiting (P9, 6): CI check {name} still red after 3 fix attempts` and run `gh pr ready --undo {n}`. The PR then no longer shows as ready.
- **`interactive` and `continuous`:** 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:

```bash
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:

```bash
git add -- "{archive-dir}/build-log.md"
git commit -m "plan(p9): record CI result" -m "{feature-id}" -- "{archive-dir}

…(truncated)
