@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/ship/references/adr-ordinal-collision.md

@@ -0,0 +1,47 @@
+# ADR-Ordinal Collision Gate
+
+Moved verbatim out of `ship/SKILL.md` Phase 5.5 to stay under the SKILL.md body ceiling (ADR-229); SKILL.md keeps the trigger and a load directive.
+
+Blocks PR-ready when the branch adds a NEW `ADR-NNN-*.md` whose ordinal `NNN` is already taken on `origin/main` by a DIFFERENT file. The ordinal was free when the ADR was authored at plan/brainstorm time, but a sibling PR claimed it during the pipeline. A collision cannot reach `main` through the queued auto-merge (the `--admin` hatch in Phase 7 bypasses the whole `required_status_checks` rule, which is why its step 2 exists): `adr-ordinals` is a required status check and `main` is strict-up-to-date, so a sibling's ADR arriving through a Phase 7 sync reds the PR's own `adr-ordinals` job and the poll loop's required-check-failure exit stops there (Phase 7, "ADR-ordinal collision after a sync", cites the SSOT). This gate is defense-in-depth: catching the collision at PR-ready costs one commit, while catching it in Phase 7 costs a sync plus a full CI cycle (the ~35-minute figure the settle paragraph measures), and a renumber done inside the poll loop is the one most likely to leave the plan/tasks sweep undone.
+
+**Detection.** Run the canonical sentinel named on the Trigger line in `ship/SKILL.md` (fetch `origin/main` first, run from the branch root).
+
+`check-adr-ordinals.sh` exits 1 with `NEW ADR ordinal collision (not in pre-existing allowlist): ADR-NNN` when two files share ordinal `NNN` (it does NOT heading-check a new ADR — its layer-3 heading check is pinned to ADR-041/ADR-042 only, per the script header; ADR-210 shipped without a `## Status` heading and it passed). Exit 0 → pass silently.
+
+**If it exits 1 on an ADR THIS branch introduced:** renumber to the next free ordinal BEFORE merge — never merge a colliding ADR:
+
+1. Next free ordinal — **`max + 1`, after a fresh fetch. Never a presence check.**
+
+   ```bash
+   git fetch -q origin main
+   HI=$(git ls-tree -r --name-only origin/main -- knowledge-base/engineering/architecture/decisions/ \
+        | grep -oE 'ADR-[0-9]+' | grep -oE '[0-9]+' | sort -n | tail -1)
+   echo "highest=ADR-$HI  next free=ADR-$((HI+1))"
+   ```
+
+   The previous form here ended at `tail -1` and was labelled "next free" while returning
+   the **highest** — follow it literally and you re-take the ordinal you just measured.
+   And do not substitute a presence check: `grep -c 'ADR-<n>'` returns a **match count**,
+   so a `|| echo FREE` fallback fires only when grep *fails*, and a successful match prints
+   a number that is easy to read as the fallback's absence. **Why:** #7190/PR #7195 — three
+   ordinals in one session (158 taken at plan time, 160 and 161 both claimed by siblings
+   mid-pipeline); the second collision was nearly shipped on exactly that misread.
+2. `git mv` the branch's ADR to `ADR-<next>-<slug>.md`, fix its `# ADR-NNN:` header, and sweep every reference in the SAME feature's artifacts (plan, `tasks.md`, `session-state.md`, learning, PR/issue bodies). Scope the sweep to YOUR ADR so the sibling that legitimately holds the ordinal is untouched: `grep -rln 'ADR-<old>' knowledge-base/ | xargs grep -l '<feature-slug>'`.
+
+   **That `knowledge-base/`-scoped sweep is necessary but NOT sufficient — an ADR ordinal
+   can be cited from CODE.** Sweep the branch's whole diff, then classify each hit:
+   `for f in $(git diff --name-only origin/main...HEAD); do [[ -f $f ]] && grep -Hn 'ADR-<old>' "$f"; done`.
+   Hits in a hook, a script or a test are the dangerous ones — an ADR reference inside a
+   runtime **deny reason string** ships to the agent (or the operator) pointing at whatever
+   unrelated ADR now holds that ordinal. Check the CLAUSE LABEL too: a provisional ADR
+   drafted with `D1/D2/D3` sections that ships restructured leaves `ADR-<n> D3` dangling on
+   both halves, and a pure ordinal bump does not fix it. **Why:** #7195 — nine `ADR-158 D3`
+   citations shipped in a hand-ported hook mirror, five inside the agent-facing deny string;
+   the plan's prescribed sweep globbed a per-feature `plans/` directory that does not exist
+   (it holds flat files) and never covered that mirror at all. (The mirror itself was retired
+   2026-09-23 — ADR-245 — but the lesson is about the sweep's reach, not that directory.)
+3. Re-run `check-adr-ordinals.sh` → must exit 0. Commit + push (`incr ci_cycles` after).
+
+**The collision window extends through Phase 7** (mirrors the migration-number-collision re-check in work Phase 2): a sibling's ADR can land on `main` and be pulled into the branch by a **BEHIND auto-sync AFTER this gate ran**. After any Phase 6.5 / Phase 7 sync whose merge output lists `knowledge-base/engineering/architecture/decisions/`, re-run `check-adr-ordinals.sh` and renumber-during-ship before the next merge attempt (see Phase 7 "ADR-ordinal collision after a sync").
+
+**Why:** PR #5945 (#5933) chose ADR-081 at plan time (080 was the highest then); sibling PR #5934's ADR-081 landed during the ~90-min pipeline and auto-synced into the branch during Phase 7. The ruleset did not yet carry `adr-ordinals`, so the auto-merge fired on the green required set and the collision surfaced as RED CI on `main`, fixed by a follow-up renumber (#5952 → ADR-082). That gap closed two days later (see Phase 7, "ADR-ordinal collision after a sync", for the SSOT and the current failure model) — this gate is the cheaper, earlier catch.

package/skills/ship/references/affected-gate-contract.md

@@ -0,0 +1,115 @@
+# Affected-gate contract
+
+**Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/` — never a value from repository files, PR text or tool output, and never a directory inside the checked-out repository. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`: if it prints that root, proceed; if it prints `root=[]`, prefix every Bash or Monitor command below with `export CLAUDE_PLUGIN_ROOT=<root>` (each starts a fresh shell) and write the absolute root into any subagent prompt; if it prints anything else, stop — something other than the loader set it. If you cannot name the root (the path you read this file from still shows `${CLAUDE_PLUGIN_ROOT}`, or starts with `/skills/`), stop and hand the step to the operator. Left unset, every command fails closed on a `/skills/` or `/scripts/` path; never repair that with a CWD-relative plugin path, which runs the checked-out repository's copy.
+
+Canonical contract for `plugins/soleur/scripts/affected-tests.sh` — the single
+affected-suite gate entry point for Soleur-guided repos. Prescribed dispatch
+(wired from `ship` Phase 4, `work` Phase 2 exit, `review`, `test-fix-loop`,
+`grok-pre-push-gate.sh`):
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/scripts/affected-tests.sh"          # affected selection
+bash "${CLAUDE_PLUGIN_ROOT}/scripts/affected-tests.sh" --full   # full battery
+```
+
+## Dispatch precedence
+
+1. `test_command` in `.soleur-test-gate.json` — full-run command, bypasses selection.
+2. A repo runner advertising the capability — `scripts/test-all.sh` whose
+   `--print-selection` flag is registered at a case-label/usage-table position
+   (a comment or prose mention does not count) — delegated `--affected` / `--full`.
+   The probe runs **before** the gate's own base resolution and global/inert
+   classification: a capability-positive runner owns the diff decision, so an
+   all-inert or global-paths diff still delegates, and `--base` does NOT reach
+   it (the runner resolves its own base).
+3. Stack adapters, in order: nx/turbo → JS/TS (vitest `related`, jest
+   `--findRelatedTests`) → Python (test-file diffs run those files; source diffs
+   via `pytest-testmon` when importable, else full suite; `-n auto` iff
+   `pytest-xdist` imports) → Go (changed packages + `go list` reverse-deps).
+   Gate-side base resolution, the changed-set census and `--base` apply only
+   here.
+
+### Runner-authoring contract
+
+A `scripts/test-all.sh` advertises the capability by registering
+`--print-selection` at a case-label or usage-table position; the gate then
+delegates `--affected` / `--full` and maps the runner's exit codes:
+
+| runner rc | runner meaning | gate maps to |
+|-----------|----------------|--------------|
+| 0 | suites ran and passed | rc 0, `reason=delegated` |
+| 1 | a selected suite failed | rc 1 |
+| 2 | usage error / unrecognized flag | rc 4 `runner-refused` |
+| 3 | zero failed but ≥1 suite signal-killed or declined | rc 1 `runner-signal` |
+| 4 | refused — nothing ran | rc 4 `runner-refused` |
+
+`--print-selection` must print the affected selection and exit before any suite
+runs. A runner that cannot honour this table must not register the flag — the
+gate probes registration, not presence.
+
+## Exit contract
+
+| rc | Meaning | Skill action |
+|----|---------|--------------|
+| 0 | Selected tests passed, or `NO_TESTS_AFFECTED` (all-inert diff) | proceed |
+| 1 | A selected test failed / runner signal-killed | stop; report failures |
+| 4 | `AFFECTED_GATE_REFUSED reason=<no-stack\|bad-config\|vacuous-test-command\|no-base-ref\|not-a-repo\|toolchain-missing\|runner-refused>` + a `remedy:` line | stop; fix the named cause — never retry blindly |
+| 6 | `AFFECTED_GATE_BUDGET_DEFERRED` — budget expired AND a CI test workflow exists | proceed to CI; record CI as the authoritative gate; never label the run passed |
+| 7 | No test suite detected at all | proceed with the disclosed note; never label passed |
+
+Multi-stack aggregation: worst-of `1 > 4 > 6 > 0`; `7` only when every adapter
+finds no suite. Delegated-runner codes map in: runner `4` → `reason=runner-refused`,
+runner `3` → rc 1 `reason=runner-signal`.
+
+## Output
+
+- Human line: `Ran X of the repo's N test files affected by this change:
+  passed.` — N is the repo-wide test-file census, not the affected subset; the
+  sentence is suppressed when either count is `-` (a run in
+  selected/full/custom mode with opaque tallies still prints
+  `affected-suite gate passed.`).
+- Machine line: `AFFECTED_GATE ran=X of=N skipped=Y mode=<selected|full|custom|explain|none|help> reason=… stack=… ci=<file|none>`
+  on every verdict path, including refusals and non-run paths (`explain`,
+  `help`, `self-check`) — counts are `-` where no honest count exists.
+- `NO_TESTS_AFFECTED` + `No tests ran: docs-only change.` for an all-inert diff
+  (adapter arm only — a capability-positive runner decides inertness itself).
+- `--explain` prints the selection and per-path reasons without running; under
+  `test_command` it reports `mode=custom` plus the configured command, and under
+  a capable runner it reports `mode=delegated` (the runner's own
+  `scripts/test-all.sh --print-selection` prints its selection).
+- `--self-check` validates config + toolchain and prints
+  `AFFECTED_GATE_SELF_CHECK ok`; a detected stack whose toolchain cannot run
+  downgrades it to `AFFECTED_GATE_SELF_CHECK toolchain-missing` with rc 4, and
+  outside a repository the refusal reason is `not-a-repo`. Bounded — worst
+  case is the per-stack `--version` timeout sum (~80 s), the happy path seconds.
+- `--base <ref>` overrides base-ref resolution — **adapter arm only**; a
+  delegated runner resolves its own base.
+- Malformed (unparseable) `.soleur-test-gate.json` is `rc 4
+  reason=bad-config key=.soleur-test-gate.json` — the filename stands in for
+  the key because no key can be read from a file that does not parse.
+- Wording is always "affected-suite gate passed" — never "tests verified". CI
+  stays the authoritative merge gate.
+
+## `.soleur-test-gate.json` (committed repo root; every key optional; unknown key or wrong type → rc 4 `bad-config key=<k>`)
+
+| Key | Type | Effect |
+|-----|------|--------|
+| `test_command` | string | Full-run command via `bash -c` from repo root; vacuous (`true`, `:`, `exit 0`, bare `echo`, or a vacuous LAST `;`/`&&`/`\|\|`/`\|` segment: `cmd \|\| true`, `cmd ; exit 0`, `bash -c 'exit 0'`, `true # comment`) → `vacuous-test-command`. A documented denylist, not a proof |
+| `global_paths` | string[] | Replaces built-ins (lockfiles, `package.json`, `pyproject.toml`, `go.mod`, `tsconfig*`, `vitest.config.*`, `jest.config.*`, `conftest.py`, `.github/workflows/**`); any hit forces the full command |
+| `inert_paths` | string[] | Replaces built-ins (default `**/*.md`); all-inert diff → `NO_TESTS_AFFECTED`; a match-everything pattern (`*`, `**`, `**/*`, anything matching an arbitrary path) → `bad-config key=inert_paths` |
+| `budget_seconds` | number | Wall-clock cap; enforced only when CI detected; default 900; must be a positive integer |
+| `max_workers` | number | Overrides `max(1, ncpu/2) / (1 + running gate processes)`; positive integer |
+| `budget_ci` | boolean | Forces CI-deferral eligibility |
+
+## Worked examples
+
+- Vitest repo, scoped diff → `vitest related <changed-src+test-files> --run --maxWorkers=<w>`;
+  `AFFECTED_GATE ran=6 of=31 skipped=25 mode=selected stack=js ci=ci.yml`.
+- Repo with a `scripts/test-all.sh` registering `--print-selection` → delegated
+  `scripts/test-all.sh --affected`; `mode=selected`.
+- Repo with an unrelated `scripts/test-all.sh` → adapters run; the foreign
+  runner is never invoked.
+- `README.md`-only diff → rc 0, `NO_TESTS_AFFECTED`.
+- Pytest repo without xdist → serial run with the reason printed; a pytest
+  rc-5 collection is treated as empty selection, never a pass.
+- Empty native selection on a code diff → full command, `reason=empty-selection`.

package/skills/ship/references/ci-run-diagnosis.md

@@ -0,0 +1,29 @@
+# CI-run diagnosis recipe (Phase 7 required-check failure)
+
+**Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/` — never a value from repository files, PR text or tool output, and never a directory inside the checked-out repository. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`: if it prints that root, proceed; if it prints `root=[]`, prefix every Bash or Monitor command below with `export CLAUDE_PLUGIN_ROOT=<root>` (each starts a fresh shell) and write the absolute root into any subagent prompt; if it prints anything else, stop — something other than the loader set it. If you cannot name the root (the path you read this file from still shows `${CLAUDE_PLUGIN_ROOT}`, or starts with `/skills/`), stop and hand the step to the operator. Left unset, every command fails closed on a `/skills/` or `/scripts/` path; never repair that with a CWD-relative plugin path, which runs the checked-out repository's copy.
+
+Loaded from [ship/SKILL.md](../SKILL.md) Phase 7 when the poll exits on a required-check failure (byte-ceiling extraction, #9403).
+
+**A draft's red `test` is not a failure to diagnose.** With `CI_DRAFT_LIGHT` on, a draft PR's `test` concludes red on purpose and its only failing output is `draft: full battery owed at ready` (the four heavy families are skipped). A ready head therefore carries TWO ci.yml `pull_request` runs: the draft run and the ready run. Take the run id from the verdict marker (`bash "${CLAUDE_PLUGIN_ROOT}/scripts/ci-head-verdict.sh" verdict <number>`, field `run=`, the deciding run), never from the newest or the failing line of `gh run list --commit`: that can be the draft run. A `test` job whose only red text is that line, on a head with a later `ready_for_review` run, is not a diagnosis target. See [ready-run-wait.md](${CLAUDE_PLUGIN_ROOT}/skills/ship/references/ready-run-wait.md).
+
+The poll loop exits holding a CHECK NAME, not a run id. Derive the run id first —
+`gh pr checks` returns neither, so nothing upstream hands it to you:
+
+```bash
+gh run list --commit "$(gh pr view <number> --json headRefOid --jq .headRefOid)" \
+  -L 200 --json databaseId,name,conclusion
+
+# <job-id> is NOT the run id. `--paginate` is load-bearing, not decoration:
+# `gh api` does NOT auto-paginate and the API defaults to 30 jobs per page, so a
+# run with more jobs than that silently returns a partial set — the same
+# truncated-page false-clean this file fixes for `gh run list` below. Measured on
+# this repo: 23-24 jobs on a ci.yml run, i.e. 6 jobs of headroom. `--paginate`
+# raises the request to per_page=100. Keep the `.jobs[]` STREAM shape: --jq runs
+# per page, so an aggregate (`.jobs | length`) would print one number per page.
+gh api --paginate repos/{owner}/{repo}/actions/runs/<run-id>/jobs \
+  --jq '.jobs[] | select(.conclusion=="failure" or .conclusion=="timed_out" or .conclusion=="cancelled") | {id, name, conclusion}'
+gh api repos/{owner}/{repo}/actions/jobs/<job-id> \
+  --jq '{conclusion, failed: [.steps[] | select(.conclusion=="failure") | {name, conclusion}]}'
+```
+
+Both work **while the run is still in progress**, which `gh run view --log-failed` refuses to do — use that to start diagnosing early. But **an in-progress snapshot is not a verdict**: a run with jobs still `queued` can fail later for an unrelated reason, so re-run the classification once the run reaches `completed` and classify on THAT result before acting. Measured on one live run: 5 jobs completed, 2 in progress, 14 queued — two thirds of the run had not executed, so a "setup failure" read at that moment could be superseded by a real red. Note also that neither command returns log text, so the output test below is only decidable once the failing job completes.

package/skills/ship/references/ci-workflow-authoring.md

@@ -0,0 +1,68 @@
+# CI Workflow Authoring
+
+Rules governing GitHub Actions workflow edits and shell snippets inside CI. Load this reference whenever editing `.github/workflows/*.yml`, `.github/actions/**`, or any shell step that runs in CI.
+
+These rules were migrated out of AGENTS.md because they only fire when CI-adjacent files are edited — keeping them in AGENTS.md wasted per-turn tokens on sessions that never touch CI. Retired IDs are preserved as breadcrumbs; the authoritative constraint lives here.
+
+## Hard
+
+- In GitHub Actions `run:` blocks, never use heredocs or multi-line shell strings that drop below the YAML literal block's base indentation. Column-0 heredoc terminators and multi-line `--body` / `--comment` args break YAML parsing (zero jobs run). Use `{ echo "..."; } > file` for multi-line content and `$'\n'` for CLI args. (ex-`hr-in-github-actions-run-blocks-never-use`; #974 indented heredoc → `<pre>`; #1358 broke YAML parser entirely)
+- GitHub Actions workflow notifications must use email via `.github/actions/notify-ops-email`, not chat webhooks. Carve-out (a closed list; a new notification defaults to `notify-ops-email`): release, mirror, pin, publish-refused, mint-failure and deploy-gate push signals post to the internal team Slack channel (redundant with the email-to-ops signal) from inline steps — "Post to Slack (release)" and "Post to Slack (release BLOCKED)" in `reusable-release.yml` (#5079, #7256), "Post deploy-gated notification to Slack" in `web-platform-release.yml`, the publish-refused (#8747), mirror-status and pin-bump-failure steps in `build-inngest-bootstrap-image.yml`, and "Post to Slack (auto-mint failure)" in `mint-inngest-bootstrap-tag.yml`. Re-derive the set with `git grep -n -E 'name: .*Slack' -- .github/workflows`. Discord is for community content only. For custom bodies, construct HTML in a preceding step and pass as the `body` input. (ex-`hr-github-actions-workflow-notifications`)
+
+## Code Quality
+
+- CI steps polling JSON endpoints under `bash -e` must precede every `jq -r` call with a `jq -e . >/dev/null 2>&1` guard that `continue`s on non-JSON bodies. Without it, plaintext 404s, HTML 503s, or connection errors kill the step before the retry loop reacts. Do NOT use `jq empty` (passes `null` through) or drop `-e` (silences real failures). (ex-`cq-ci-steps-polling-json-endpoints-under`; #2214; `knowledge-base/project/learnings/bug-fixes/2026-04-15-signed-get-verify-step-tolerate-non-json-bodies.md`)
+- When a PR changes `--model <name>` in `.github/workflows/*.yml`, verify every `anthropics/claude-code-action` pin in the modified files is within ~3 weeks of release tip. SDK lags the API by days — old pins send deprecated `thinking.type.enabled` and fail 4xx. Audit pin age via `gh api repos/anthropics/claude-code-action/releases`. When bumping the pin, check release notes for default-model flips. (ex-`cq-claude-code-action-pin-freshness`; #2540 v1.0.75 pin + opus-4-6 → 4-7 bump failed 4 workflow runs)
+- When extending a GitHub Actions workflow by duplicating an existing job's pattern, scan the source for known-buggy idioms before duplicating. Common: piped `| while` loops swallow counter updates (subshell scope), missing `set -uo pipefail`, unguarded `gh api` calls. Fix in BOTH the new and source jobs per `wg-when-fixing-a-workflow-gates-detection`. (ex-`cq-workflow-pattern-duplication-bug-propagation`; PR #2631 propagated the `check-alerts` subshell-counter bug into `close-orphans`)
+- Doppler service tokens are per-config — use config-specific GitHub secret names (`DOPPLER_TOKEN_PRD`, `DOPPLER_TOKEN_CI`), never bare `DOPPLER_TOKEN`. The `-c` flag is silently ignored with service tokens. (ex-`cq-doppler-service-tokens-are-per-config`; `knowledge-base/project/learnings/2026-03-29-doppler-service-token-config-scope-mismatch.md`)
+- When a CI step disables `set -e` to capture an exit code (typical pattern: `set -uo pipefail` + `rc=$?` from `terraform plan`, `gh api`, etc.), the `-e` re-enable window MUST close before any `[[ "$VAR" -gt|-lt|-eq|-ne N ]]` arithmetic test where `$VAR` is assigned from a piped command. Bash arithmetic coerces empty-string → 0 silently, so a failed `jq` or upstream pipe produces an empty `$VAR` and bypasses the guard (e.g., a destroy-guard that lets destructive plans through). Either re-enable `set -e` immediately after the rc-capture window closes, OR add an explicit `[[ ! "$VAR" =~ ^[0-9]+$ ]]` validation before the arithmetic test. Belt-and-braces (both) is preferred for destroy/blast-radius guards. (PR #3903 review; `knowledge-base/project/learnings/2026-05-16-adr-amendment-required-when-reversing-and-destroy-guard-empty-string-bypass.md`)
+- A `continue-on-error: true` step reports **`conclusion: success` (green in the UI) while its true `outcome` is `failure`**. Any dependent step gated `if: steps.<id>.outcome == 'success'` therefore **silently skips** on a green-looking run — an invisible, indefinite degradation. When authoring or reviewing a `continue-on-error` "belt" step: (a) read `outcome`, never `conclusion`, to judge whether it worked (`gh run view <id> --json jobs` shows only `conclusion` — a skipped dependent step is the tell); (b) emit a **monitored** marker (Sentry / `SOLEUR_*` stdout consumed by the log pipeline) on the degraded path — an `echo "⚠️ … degraded"` into the job log is not an alarm, it is an artifact nobody reads; (c) if the skipped step maintains redundancy (a mirror, a replica, a backup), pair it with an alarm on the *fallback's* sustained use, because the primary can then die silently. **Why:** #6400 — `Bridge to zot registry` was `continue-on-error`, so `Mirror image GHCR→zot` skipped on **every release for 14 days** while releases stayed green; zot served 0 pulls, the fleet silently rode the GHCR fallback, and the freeze only surfaced as a compound P1 when GHCR *also* degraded. (`knowledge-base/project/learnings/2026-07-15-silent-fallback-masked-a-dead-primary-for-14-days.md`)
+
+## Slack mrkdwn formatting
+
+Slack messages do **not** render GitHub-flavored Markdown. Slack uses "mrkdwn", a different syntax. Posting raw GFM (PR-body changelogs, `CHANGELOG.md` text) to a Slack webhook renders the markers as **literal characters** (`**bold**`, `## heading`, `[text](url)` all show verbatim). Any CI step that composes a message for a Slack webhook MUST convert GFM → mrkdwn first.
+
+**Use the shared converter, never re-derive a sed pipeline.** `scripts/md-to-mrkdwn.mjs` (self-contained, zero-dependency Node ESM; runs under stock ubuntu-latest `node`, no `setup-node`) is the canonical transform. Invoke it from the `run:` block: `node scripts/md-to-mrkdwn.mjs --max 3000 < "$NOTES_FILE"`. It exports `toSlackMrkdwn(md)` + `truncateMrkdwn(text, max)` for reuse. Precedent wiring: the "Post to Slack (release)" step in `reusable-release.yml`.
+
+### GFM → mrkdwn mapping (the converter's contract)
+
+<!-- markdownlint-disable MD038 -->
+| GFM input | Slack mrkdwn output | Notes |
+|---|---|---|
+| `**bold**` / `__bold__` | `*bold*` | single asterisk |
+| `*italic*` / `_italic_` | `_italic_` | single underscore |
+| `~~strike~~` | `~strike~` | single tilde |
+| `` `code` `` / ` ```fence``` ` | same | escape `&<>` inside, NO GFM convert |
+| `[text](url)` / `[text][ref]` | `<url\|text>` | delimiters raw; url+label sub-escaped (incl. `\|`) |
+| `<https://x>` autolink / bare url | `https://x` | Slack auto-links bare URLs; do NOT wrap |
+| `![alt](url)` image | `<url\|alt>` | no inline image → degrade to link |
+| `# H1` … `###### H6`, Setext | `*H1*` | no headings in mrkdwn |
+| `- `/`* `/`+ ` bullet | `• item` | canonical Slack bullet |
+| `1.` ordered | `1.` | Slack renders ordered lists |
+| `- [ ]` / `- [x]` task | `• ☐ ` / `• ☑ ` | no native checkbox |
+| `> quote` | `> quote` | same as GFM |
+| GFM pipe table | wrap in ` ``` ` | no table support; monospace degrade |
+| `---` / `***` thematic break | blank line | no HR in mrkdwn |
+| raw `<!channel>` / `<@U…>` in prose | `&lt;!channel&gt;` etc. | escaped → inert (injection safety) |
+<!-- markdownlint-enable MD038 -->
+
+### Escape-vs-emit ordering invariant (security-critical)
+
+The transform is **one context-aware tokenizing pass**, not two string passes. Slack has **no** API-level mention suppression (unlike Discord's `allowed_mentions`), so escaping `&`, `<`, `>` is the only defense against a changelog author's `<!channel>` mass-ping or `<url|label>` disguised link:
+
+- **Text nodes** (prose, including any author-typed mention): escape `&<>`. This keeps injection inert.
+- **Converter-minted link syntax** (`<`, `>`, `|` of a `<url|label>` from a genuine `[text](url)`): the delimiters are raw, but the url + label segments are sub-escaped, and `|` is stripped (label) / percent-encoded (url) — a raw `|` would re-open the grammar, and Slack's 3-entity escape does NOT cover `|`. Only `http(s)`/`mailto` URLs are minted (never `javascript:`).
+- **Code spans / fences**: **escape-only** (`&<>`), no GFM convert — but **not verbatim**: Slack renders `<!channel>`/`<@U…>` inside backticks in a `text` payload, so a verbatim copy would be a live mass-ping hole.
+- **Keystone fail-closed invariant**: the converter output contains **zero** `<!`, `<@`, `<#`, `<subteam^` sequences (the only raw `<` begins a URL scheme inside a minted link). This single assertion backstops every smuggling path and is enforced in both `scripts/md-to-mrkdwn.test.mjs` and the `plugins/soleur/test/reusable-release-idempotency.test.sh` T7 contract test.
+- **Truncate AFTER conversion** at a token boundary (no dangling `<url|`, close any open fence) — `truncateMrkdwn` / the `--max` flag does this. Truncating raw GFM first would sever tokens the converter then mangles.
+
+When wiring the converter, guard the call so a non-zero exit cannot fail the release: `if ! BODY=$(node scripts/md-to-mrkdwn.mjs --max 3000 < "$F"); then …sed-escape fallback…; fi`. The `if !` form is load-bearing — a bare `BODY=$(node …)` assignment masks the exit code under `bash -e`. The fallback is for **availability**, not safety (safety lives in the converter's escaping + the keystone invariant).
+
+## When to Load This File
+
+- Editing any `.github/workflows/*.yml`
+- Editing any `.github/actions/**`
+- Adding or modifying CI shell steps in `bash -e` / `set -euo pipefail` mode
+- Changing `anthropics/claude-code-action` pins or model strings
+- Adding new Doppler secrets consumed by CI
+- Composing any message for a Slack webhook in CI (use `scripts/md-to-mrkdwn.mjs`, never raw GFM)

package/skills/ship/references/cleanup-merged-archival.md

@@ -0,0 +1,39 @@
+# Why `cleanup-merged` is not the KB-archival point
+
+Loaded from ship Phase 7 Step 4's archival note. `cleanup-merged` carries an
+archive step, but its own header scopes it: *"Backward-compat for legacy
+pre-#2815 worktrees that created specs at the bare root. New layout commits
+the spec inside the worktree (git history is the canonical archive); the
+`[[ -d ]]` guard silently skips when the bare-root dir does not exist."* Two
+independent reasons it cannot durably archive a modern spec dir:
+
+1. **It usually does not run at all.** The step guards on
+   `[[ -d "$GIT_ROOT/knowledge-base/project/specs/<branch>" ]]` against the
+   BARE ROOT's on-disk files, and it executes *before* the "Updated main to
+   latest" step. On a just-merged branch the bare root is therefore still at
+   the pre-merge commit, where the spec dir does not exist — it arrives only
+   with the merge being cleaned up. Guard false, silent skip. Measured on PR
+   #7240: the dir is ABSENT at `5133e3cb` (main at archival time) and PRESENT
+   at `933635603` (the merge commit).
+2. **Even when it runs it commits nothing.** It is a plain `mv` of the bare
+   root's working files, so it produces no commit and leaves the spec dir
+   tracked at its LIVE path on `main`.
+
+The archives that actually exist under `specs/archive/` were committed by
+**compound's** automatic consolidation (`git mv` + commit on the feature
+branch), which is the only mechanism that persists.
+
+The practical consequence: **ship's Phase 6.45 (KB Artifact Archival) is the
+in-PR archival point** — the named phase both PR arms run before any
+`gh pr ready` / `gh pr merge` site, backed by the `ship-kb-archive-gate.sh`
+PreToolUse hook. Compound's Step E archives eagerly when no live-path reader
+remains, but a deferred archival — the legitimate choice when
+`specs/<branch>/decision-challenges.md` must stay live for Phase 6 step 2.5's
+Model Dissents render or the plan file's `## Operator Holds` for step 5 — no
+longer strands the artifacts: Phase 6.45 runs `archive-kb.sh` AFTER those
+last reads and the `git mv` rides the same PR. A follow-up PR is never
+required for archival. **Why the ordering is load-bearing:** PR #7240
+deferred compound's archival so Phase 6 step 2.5 could read
+`decision-challenges.md`, on the strength of `cleanup-merged` archiving
+post-merge — it did not, and the spec dir shipped unarchived; #9768 shipped
+unarchived the same way in 2026-10.

package/skills/ship/references/counsel-review-clo-attestation.md

@@ -0,0 +1,38 @@
+# Counsel-Review CLO-Attestation Gate
+
+Moved verbatim out of `ship/SKILL.md` Phase 5.5 to stay under the SKILL.md body ceiling (ADR-229); SKILL.md keeps the trigger and a load directive.
+
+**The reviewing authority for legal-doc attestation is the `soleur:legal:clo` agent, NOT the human operator.** The Soleur user is a non-lawyer founder; deferring legal sign-off to them bottlenecks indefinitely and mis-allocates expertise (the `soleur:legal:clo` agent orchestrates `soleur:legal:legal-compliance-auditor` + `soleur:legal:legal-document-generator` and can cross-check prose against statute and against the implementing migration in one cycle). This is symmetric to how `soleur:plan` routes CPO sign-off to the CPO agent. See `knowledge-base/project/learnings/workflow-patterns/2026-05-18-clo-attestation-auto-route-instead-of-human-task.md` (the operator has corrected human-routed legal sign-off ≥3×).
+
+**Trigger:** the PR diff touches a legal-doc directory AND the change is legal-attestation-bearing:
+
+```bash
+legal_touch=$(git diff main...HEAD --name-only \
+  | grep -E '^(docs/legal/|plugins/soleur/docs/pages/legal/|knowledge-base/legal/)' | head -n 1)
+# Scope the marker grep to legal-doc dirs ONLY — otherwise it self-fires on
+# this gate's own prose in ship/SKILL.md or on spec/tasks.md that quotes the
+# literal descriptively (false positive).
+draft_marker=$(git diff main...HEAD -- docs/legal/ plugins/soleur/docs/pages/legal/ knowledge-base/legal/ \
+  | grep -E '^\+.*\[DRAFT — pending CLO/counsel review' | head -n 1 || true)
+sui_plan=$(gh pr view --json body --jq .body \
+  | grep -oE 'knowledge-base/project/(plans|specs)/[^[:space:])]+' | head -n 1 || true)
+sui_threshold=""
+if [[ -n "$sui_plan" && -f "$sui_plan" ]]; then
+  sui_threshold=$(grep -E '^brand_survival_threshold:\s*single-user incident' "$sui_plan" || true)
+fi
+# Gate fires when legal docs changed AND (single-user-incident OR a DRAFT marker is present)
+```
+
+**If triggered (`legal_touch` non-empty AND (`sui_threshold` OR `draft_marker` non-empty)):**
+
+1. **Invoke the `soleur:legal:clo` agent via Task** with: the diff, every changed legal artifact, and the implementing files it must cross-check against (migrations, RPC bodies, the consuming TS). Instruct it to produce/attest the counsel-review audit at `knowledge-base/legal/audits/<YYYY-MM>-counsel-review-<issue>.md` (house style: `2026-05-counsel-review-4353.md`), resolving lawful-basis, consent, retention, and Art. 6(1)(f) LIA questions, and to return a per-artifact verdict + an overall disposition (DISCHARGED or BLOCKED).
+2. **On DISCHARGED** — the CLO agent is the authority, so proceed without a human sign-off:
+   - Apply any in-PR conditions the CLO agent names (prose corrections, LIA-test updates).
+   - Remove the `[DRAFT — pending CLO/counsel review per #<issue>]` markers across `docs/legal/ plugins/soleur/docs/pages/legal/ knowledge-base/legal/` (derive the file list via `grep -rl`; do NOT strip the literal from spec/`tasks.md` descriptive references). Keep each canonical doc and its Eleventy mirror in lockstep, then regenerate `apps/web-platform/lib/legal/legal-doc-shas.ts` for each changed canonical doc. Non-T&C edits → no `TC_VERSION` bump. **Re-run `legal-doc-shas-guard.test.ts` + `legal-doc-consistency.test.ts` AFTER this marker-clearing mutation and confirm green** — Phase 4 ran the suite BEFORE this gate, so these post-mutation edits are otherwise unverified within the pipeline (a stale SHA or broken mirror lockstep would slip to CI otherwise).
+   - Set the audit frontmatter `status: SIGNED-OFF (CLO-agent-attested, Soleur-as-tenant-zero v1)`.
+   - **Optional human veto (not a block).** Emit exactly one line: `COUNSEL-REVIEW: soleur:legal:clo agent DISCHARGED #<issue> (audit: <path>). Reply "veto" to hold for external counsel; otherwise ship proceeds.` Then continue the pipeline. Do NOT wait for an ack — the veto is an interrupt the operator may raise, not a gate that blocks on their input (matches the operator's chosen v1 model). If the operator vetoes, halt and route the named concern back to the `soleur:legal:clo` agent. (Headless mode: there is no veto channel — emit the line and proceed.)
+3. **On BLOCKED** — the CLO agent found prose that misstates the implementation, a weak/absent lawful basis, or a missing disclosure. Halt the ship pipeline and surface the agent's named blocker + recommended fix. This is the ONLY block path, and it is an agent verdict — never "waiting on the human to do legal review."
+
+**If not triggered:** Skip silently.
+
+**Why:** PR #4559 (#4558, ADR-044) shipped legal amendments under a `single-user incident` threshold with `[DRAFT — pending CLO/counsel review]` markers and an issue (#4564) framed as "a genuine human CLO/CPO sign-off." That framing is the recurring bug the 2026-05-18 learning already named — legal review is a CLO-agent function. This gate closes it at ship time: the `soleur:legal:clo` agent attests and the DRAFT markers clear automatically, with the operator retaining an optional veto rather than being the bottleneck. External counsel re-review is reserved for the audit's frontmatter re-evaluation triggers (first arms-length user, EEA-out, regulated industry), not routine review.

package/skills/ship/references/cto-ruling-armed-push.md

@@ -0,0 +1,5 @@
+# CTO ruling: an operator's "ask before pushing to an armed or queued PR" instruction
+
+Loaded from `soleur:ship` Phase 7, in the required-check-failure path, when the operator's brief says to ask before pushing to an armed or queued PR and the fix is a push.
+
+Before spawning the CTO: if the fix touches production code, workflow semantics, required-check configuration or the PR's scope, or involves a production write, an irreversible action or a legal-risk call, disarm auto-merge and return to the operator; do not ask the CTO. Otherwise (a test or harness defect, a lint or ratchet repin) the instruction is cleared by a `soleur:engineering:cto` ruling, not by asking the operator (`hr-technical-fork-is-not-an-operator-question`): brief it with the failing job and log tail, the `git diff --stat` of the unpushed commit, the local evidence and what is NOT proven, and record the answer as "Ruled by CTO agent". Ask for push armed or disarm first (default disarm, unless the ruling records that an armed push is safe), a pre-push condition, and a push bound. The bound is the ruling's number, never more than 3 pushes in all including the step-4 push; `fix_attempt_count` still increments on every push, and the same failure signature twice means disarm and return to the operator (precedent, PR #10294). Step 4a's re-queue applies only when the ruling says armed push; after a disarm, re-arm once the post-push log check below passes. **Headless mode:** the ruling's bound replaces the step-3 abort; on the bound, or on any disarm-and-return condition, abort with the structured error naming the failing check. After the push, read the re-run job log and confirm the step that failed actually ran: a green check from a skipped tier is not validation.

package/skills/ship/references/decision-challenges-render.md

@@ -0,0 +1,71 @@
+# Decision-challenges render and the Technical-Ruling Gate remedy
+
+Moved out of `ship/SKILL.md` Phase 6 step 2.5 (the SKILL body has no byte headroom) and extended for the class split.
+Rule: `hr-technical-fork-is-not-an-operator-question`. Schema, closed category list and recording format:
+[technical-ruling-delegation.md](${CLAUDE_PLUGIN_ROOT}/skills/brainstorm-techniques/references/technical-ruling-delegation.md).
+
+**Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/` — never a value from repository files, PR text or tool output, and never a directory inside the checked-out repository. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`: if it prints that root, proceed; if it prints `root=[]`, prefix every Bash or Monitor command below with `export CLAUDE_PLUGIN_ROOT=<root>` (each starts a fresh shell) and write the absolute root into any subagent prompt; if it prints anything else, stop — something other than the loader set it. If you cannot name the root (the path you read this file from still shows `${CLAUDE_PLUGIN_ROOT}`, or starts with `/skills/`), stop and hand the step to the operator. Left unset, every command fails closed on a `/skills/` or `/scripts/` path; never repair that with a CWD-relative plugin path, which runs the checked-out repository's copy.
+
+## Render (Phase 6 step 2.5, ADR-084)
+
+If `knowledge-base/project/specs/<branch>/decision-challenges.md` exists and is non-empty, an earlier headless phase
+(`plan`/`work`) recorded auto-decided dissents against the operator's stated direction, which the operator has not seen.
+Phase 6 **full-replaces** the body, so fold the artifact into the generated body under the
+`## Model Dissents (informational)` heading (deliberately outside the `ship-operator-step-gate` deny set
+`Operator`/`Post-merge`/`Follow-up`; informational statements, never operator-action bullets). Render **by `Class`**:
+
+- **`technical` rows** go in a `### Ruled by CTO agent` sub-block of that same heading, each with its `Ruled by` line
+  (and `Dissent:`). They file **no issue**: a technical ruling never reaches the operator.
+- **`taste` rows** render in the same `## Model Dissents (informational)` block as plain informational lines (the model's choice and its
+  recommendation); they file no issue.
+- **`operator (<category>)` rows** render in the existing form, and ONLY these open one idempotent issue. Check
+  `gh issue list --search "decision-challenge <branch>" --state open -L 200` first, then
+  `gh issue create --label action-required --label decision-challenge --milestone "Post-MVP / Later"` with a plain-language
+  title linking the PR, because `operator-digest` Section 4 harvests `action-required` issues, not PR bodies. A split
+  item yields both a technical row and an operator row.
+- **A delegated row** (`operator (production-mutating)` with Ruling `Authorized by delegation <comment-url>, envelope <path>[, ran <ISO 8601 UTC time>]`) renders as an informational line naming the act and the delegation link, and files NO issue: the operator already authorised it in the epic's recorded Standing Delegation. The gate verifies it (below). A row WITHOUT `ran` authorises an act that has not happened yet and is verified as of now; a row WITH `ran` records an act that did and is verified as of that time, and also needs its execution receipt. See [standing-delegation.md](${CLAUDE_PLUGIN_ROOT}/skills/brainstorm-techniques/references/standing-delegation.md).
+  - `delegation-invalid` / `delegation-unverifiable`: fix the row or the envelope. When the delegation itself is the problem (edited, expired, gone, the epic closed), say the plain sentence for its reason from standing-delegation.md section 7 (Reason tokens); the CALLING skill asks the epic-start question again and only a fresh Yes re-records it. Never re-record a delegation yourself and never put a technical question to the operator. Headless (`HEADLESS_MODE=true`, no TTY, `soleur:one-shot`, `soleur:go --headless`): nobody can be asked, so leave the PR draft, file ONE `action-required` issue that names the ACTION, print one plain sentence, and continue to the draft PR.
+  - **Who records the `ran` row:** right after posting the receipt for EVERY delegated act, the CTO itself records `| <act> | operator (production-mutating) | Authorized by delegation <url>, envelope <path>, ran <ISO UTC time> |` in `decision-challenges.md` (this is what the CTO agent definition says; the calling skill does not write it). Without that row nothing demands the receipt (a row without `ran` is verified strictly as of now and needs none), so a delegated act with no `ran` row is an unrecorded act: record it. `ran` must not be in the future: the gate says so in plain words (`delegation-invalid`, "the act ran in the future") and the operator-facing wording is in [standing-delegation.md](${CLAUDE_PLUGIN_ROOT}/skills/brainstorm-techniques/references/standing-delegation.md) section 7. A delegation row needs a time-limit tool (`timeout` or `gtimeout`); without one it is `delegation-unverifiable`, never an unbounded call.
+  - **The receipt (a `ran` row):** the epic must carry a comment whose first line is `<!-- soleur-delegated-act v1 delegation=<url> envelope=<path> sha256=<verified-envelope-sha256> result=ok|rolled-back run=<url|none> -->` (standing-delegation.md section 8), written by an owner, member or collaborator, naming this row's delegation URL, this row's envelope path and the fingerprint the verifier just reported (every field is compared exactly). It must have been created at or after the `ran` time it vouches for (a receipt posted in advance is refused), inside the delegation's life and not in the future, never edited, and posted by a person rather than a bot; one receipt satisfies one row, so each act needs its own. `receipt-missing` (none left for this delegation), `receipt-mismatch` (one exists but not for this envelope and fingerprint, with that result and author, inside that window) and `receipt-unreadable` (the epic's comments could not be read) are each exit 2: write or correct the receipt, then re-run the gate. The check proves a receipt exists, is attributable and matches the row. It does not prove what ran; a receipt-checking hook is the stronger follow-up (#10361).
+  - When the gate prints `SOLEUR_RULE_APPLIED rule=hr-menu-option-ack-not-prod-write-auth note=delegation-verified` on stdout, repeat that exact line in your own `echo` so the telemetry capture hook (which reads the command text, not script output) sees it.
+- **The `overlap vehicle` row** written at the start of Phase 6.45 is not in the PR body already folded in this step; the PR body line for it is refreshed after Phase 6.45 by the normal body update, then the body check below runs again on that body.
+- No new top-level PR-body heading: that keeps the diff and the `ship-operator-step-gate` deny-token surface unchanged.
+- `guardrails.sh`'s filing gate refuses the `gh issue create` unless the body names a user-visible consequence; when the
+  dissent is about a hook/gate/guard the honest exit is `--label meta/machinery` (measured on PR #8354), which the digest
+  excludes, so the PR-body section is then the operator-visible surface. See
+  [decision-principles.md](../../brainstorm-techniques/references/decision-principles.md).
+
+## The gate: three call sites, one parser
+
+`bash "${CLAUDE_PLUGIN_ROOT}/skills/ship/scripts/technical-ruling-gate.sh" <mode>` (exit 0 pass or `[WARN]`, 1 fail, 2 could not measure; any other status, such as 127 script not found, 124 timed out or 137 killed, means the gate did not run: treat it as 2):
+
+1. **one-shot, after the plan phase and before `work`:** `--branch`. A `pending - assumed: <default>` row is resolved
+   here, in the main context, so a wrong assumption does not ride through `work` and `review`.
+2. **ship Phase 5.5:** `--branch` (the artifact check; it also looks under `specs/archive/` for this branch).
+3. **ship Phase 6, right after the `gh pr edit` that writes the final body and before `gh pr ready`:**
+   `b=$(mktemp -p "$(mktemp -d -t soleur-run.$$.XXXXXXXX)" pr-body.XXXXXXXX); if gh pr view PR_NUMBER --json body --jq .body > "$b"; then bash "${CLAUDE_PLUGIN_ROOT}/skills/ship/scripts/technical-ruling-gate.sh" --pr-body "$b"; rc=$?; else rc=2; fi; rm -f "$b"; echo "gate-rc=$rc"`
+   Read the printed `gate-rc=`; no `gate-rc=0` line means do not proceed. Exit 0: go on to `gh pr ready`. Exit 1: remedy item 4 below, then
+   `gh pr edit` and re-run. Exit 2 (the fetch failed, the body is empty or whitespace-only, an unclosed fence, or an unreadable file):
+   fix the fetch and re-run (at most three tries, then stop with the PR draft); never `gh pr ready` past it.
+   Phase 6 full-replaces the body, so the body must be checked after it is written.
+
+The plugin root is `${CLAUDE_PLUGIN_ROOT}` (cloud shells do not export it: resolve it as the Cloud Mode paragraph of ship/SKILL.md does).
+An absent artifact is `[PASS] no decision-challenges artifact`. An artifact that `--branch` finds under `specs/archive/` has its delegation rows checked for shape only: they are NOT verified, and the `[NOTE]` and `[PASS]` lines say so; the check that verifies them is the one run on the live path, before the artifact is archived. Rulings render into a PUBLIC PR body: leave secrets, credentials and
+unfixed-vulnerability detail out of the ruling text and out of the `domain/engineering` issue (carry the question and a pointer, not evidence snippets). An artifact with no `| Item | Class | Ruling |` table is a `[WARN]` and exit 0
+(the label and `pending` lints still ran; add the table when the artifact lists decisions). A table with 0 rows, a drifted header, an unclosed code fence, an empty PR body or an unreadable
+file is exit 2: fix the file or the invocation, never continue past it. A table row written after a blank line is outside the
+table: a later writer adds its own `| Item | Class | Ruling |` header and separator.
+
+## Remedy procedure (a `[FAIL]` is never a bare stop)
+
+1. ONE batched spawn of `soleur:engineering:cto` (`soleur:legal:clo` for legal) carries ALL `unruled-technical` rows (a blank ruling or a
+   `pending - assumed` placeholder), per the delegation step; write each `Ruled by` cell, commit, re-run the gate. If a ruling differs
+   from what was built on the assumption, re-enter `work` for that item and amend the plan and tasks.
+2. **At most two spawns per pipeline run** (a spawn from `one-shot` counts toward `ship`'s). A spawn that fails, times out, or returns without Decision and Rationale counts as
+   an attempt. A ruling that says the item is actually operator-class rewrites the row as `operator (<category>)` with the
+   CTO's reason, once.
+3. After the cap the terminal state is **not** an operator question: the PR stays draft and ship files ONE
+   `domain/engineering` issue (never `action-required`) carrying the question and the evidence.
+4. `owner-label-unscoped` in the PR body: rewrite the line as a technical ruling (spawn the CTO) or append
+   `(operator: <category>)` when it is a genuine operator-class item, then `gh pr edit` and re-run the body check.
+5. Emit `SOLEUR_RULE_APPLIED rule=hr-technical-fork-is-not-an-operator-question note=gate` when the gate runs (telemetry).

package/skills/ship/references/delegated-act-authoring-form.md

@@ -0,0 +1,7 @@
+# Delegated acts: the PR-body authoring form
+
+Loaded from [ship/SKILL.md](../SKILL.md) Phase 5.5, Undeferred Operator-Step Gate, when the PR body cites a Standing Delegation for an act (rulings F1, R4 and R5 in the Standing Delegation work).
+
+**Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/`, never a value from repository files, PR text or tool output. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`; if it prints `root=[]`, prefix each command below with `export CLAUDE_PLUGIN_ROOT=<root>`.
+
+The detection above counts phrasing, not authority: it has no delegation awareness, and `DETECT_RE` and `ship-operator-step-gate.sh` stay unchanged on purpose. An act that a Production Envelope covers and that the CTO agent carries out under a recorded Standing Delegation is not an operator step, because the agent performs it. Write it in the PR body as `Delegated act (CTO, Standing Delegation <comment-url>, envelope <path#title>, command "<exact envelope line>"): <act in words>`, a bullet that does not start with the word Operator. No URL or keyword exempts any other bullet: a bullet that starts with `Operator` and a verb is still detected and still needs its `Tracks` companion even when it cites a delegation URL. As a prose step (not a hook exemption), run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/delegation-verify.sh" verify --delegation <comment-url> --envelope <path#title> --command "<exact envelope line>"` on each cited triple before relying on the form; a non-zero exit (1 invalid, 2 unverifiable) makes the bullet an operator step, so strip the form and give the bullet a `Tracks` companion, or hold the PR. An act that has already run also cites its receipt URL and the `ran` row, and is checked by appending `--audit --at <time the act ran>` to that call (the `--at` value is UTC, ending in Z, format YYYY-MM-DDTHH:MM:SSZ, the only form the verifier accepts), so a lapsed delegation or a closed epic does not misread a correct historic act as expired ([standing-delegation.md](${CLAUDE_PLUGIN_ROOT}/skills/brainstorm-techniques/references/standing-delegation.md) section 1); an act that has not run yet keeps its `Tracks` companion. Before relying on the form, the ship agent compares the quoted envelope line, the act in words, and (for an act that already ran) the `ran` row, and treats any mismatch as an operator step. Never use the form for any act the envelope or the Standing Delegation Excluded list names (the A1b environment approval, A5, A6 and A7 of the Inngest TLS envelope are instances), nor for any act whose text names an owner-human act (a signing key, `SIGNED BY OWNER`, approving an environment or the inngest-cutover approval, a credential, money, a force-push): such a bullet is an operator step whatever its prefix, so strip the form and add `Tracks`.

package/skills/ship/references/detached-battery-verdict.md

@@ -0,0 +1,13 @@
+# Reading a detached `test-all.sh` battery verdict
+
+Load this when Phase 4's detached run has landed (or failed to land) its rc file
+and the verdict needs forensic reading. The launch recipe and the rc-file
+contract live inline in SKILL.md; this file carries the trap catalogue.
+
+**Identify the runner by its rc file, never by a pid and never by shape.** `tc_acquire` forks its heartbeat as a background subshell, so during a lock wait there are two `bash scripts/test-all.sh` processes with the same argv, cwd and fds; the heartbeat's fingerprint is a lone `sleep <n>` child and a silent self-exit at exactly the lock budget. If the wrapper's rc file reads 143 while such a process is still writing heartbeats, the runner is dead and the rc file is its verdict — a live runner whose budget expired would have printed `LOCK_CONTENDED_PROCEEDING` and run the battery unserialized beside the holder (the false-RED shape; expiry never aborts).
+
+**Do NOT watch `$!` — it does not track the runner.** `setsid` forks when it is not already a process-group leader, so `$!` is a short-lived parent that exits in under a second while the battery runs on, and a `kill -0 $!` loop falls through immediately: every line after it then reports a verdict for a run that has not finished. Measured 2026-09-17 with both controls — under `setsid` the pid was gone after 1 s with the runner still working, and the same launch WITHOUT `setsid` kept `$!` alive and tracking correctly, which is what makes the cause the fork rather than the timing. Observed live: `BATTERY COMPLETE rc=1` printed for a battery that had died in under a second on a mise shim fault and never ran a single suite — rc=1 with no `[FAIL]` lines reads exactly like "the battery ran and one suite failed". This is the #8137 trap below one level up: there the watched process was the runner's own heartbeat subshell, here it is `setsid`'s forked parent, and in both the pid you can see is not the runner. The rc file is already this skill's stated source of truth ("Read the rc file, never the background-task completion notification"), so polling it is what makes the wait agree with the verdict.
+
+**And rc is only a test verdict once the toolchain started:** grep the log for `mise ERROR|command not found` first — a shim with no resolved version exits 1 emitting no `[FAIL]` lines at all, and `rc=4` is REFUSED (nothing ran), not a reap. If you do queue inside the lock (`SOLEUR_ALLOW_FULL_GATE=1`) and raise `TC_LOCK_TIMEOUT`, raise `TC_RUNTIME_CEILING_S` with it (`$((TC_LOCK_TIMEOUT + 10800))`): the wait is charged against the ceiling, so `10800` under the 14400 s default leaves 3600 s of execution, under the contended readings the lib records.
+
+**Why:** #8137 merge tail — the runner was SIGTERM'd an hour into a queue; its orphaned heartbeat (same argv, `sleep 60` child, same log) was watched as the runner for another hour and exited at 3600 s with no banner. See `knowledge-base/project/learnings/workflow-issues/2026-09-14-the-runner-i-watched-was-its-own-heartbeat-subshell-and-ci-tested-a-tree-i-had-never-built.md`.

package/skills/ship/references/epic-close-sweep.md

@@ -0,0 +1,62 @@
+# Epic-Close Domain-Leader Sweep — full spec
+
+Loaded by ship Phase 7 Step 3.9 when its trigger fires. The body keeps only the
+trigger and the load directive; this file is the executable spec.
+
+Phase 5.5's CMO gate is PR-scoped; three classes of opportunity exist only at
+epic scope — (a) **aggregate claims** ("shipped the whole checklist in four
+days" lives in no single diff), (b) **cross-child meta-findings** (the pattern
+across children is often the arc's strongest claim), (c) **deadline-shaped
+timing** (a synthesis pegged to an external article/launch decays on a
+calendar no per-PR slotting asks about).
+
+## Trigger
+
+This merge completed a tracked epic — an issue it closed is a child of an epic
+whose other children are all CLOSED (the epic issue itself closing also fires).
+
+## Detection
+
+1. `gh pr view <PR> --json closingIssuesReferences` — the issues the merge
+   closed (covers `Closes`/`Fixes`/`Resolves`, multiple issues).
+2. `gh issue view <N> --json parent` for each issue's epic; empty `parent` →
+   grep the issue's body and comments for `Tracked by #N`.
+3. `gh issue view <epic> --json body` — extract child task-list rows
+   (`- [ ] #N` / `- [x] #N`); when the body carries none, fall back to
+   `gh issue view <epic> --json subIssues` and read each child's `state`.
+
+Fire only when ALL hold: a closed `#N` appears among the children (or is the
+epic), the child count is ≥2, and every child is closed. An empty child list
+is "cannot confirm" — report "epic-close sweep inconclusive for #<epic>";
+never fire on a vacuous truth, never skip silently.
+
+## If triggered
+
+1. **Per-child disposition census.** For each child, confirm a Phase 5.5
+   disposition exists — a filed brief, a `content-strategy.md` row, or an
+   explicit skip-with-reason. A child whose ship tail was resumed manually or
+   after a runner failure silently skips Phase 5.5; the census catches that.
+2. **Arc-level CMO assessment.** Spawn the CMO agent: "Assess content and
+   distribution opportunities from the COMPLETED epic, not any single PR:
+   aggregate claims, cross-child meta-findings, external news pegs the epic
+   cites, and whether a synthesis piece complements or supersedes the
+   per-child briefs. For each child with no disposition, produce a
+   retroactive brief."
+3. **Interactive:** ask create-now / schedule / skip (Phase 5.5's options).
+   **Headless:** auto-file the arc brief + retroactive child briefs (do not
+   block). This runs post-merge — a `content-strategy.md` edit lands on a
+   reaped worktree, so embed proposed rows in each filed brief's body or land
+   them in a follow-up PR from fresh `origin/main`. An issue without a
+   strategy row is an orphan (#1173).
+
+## If not triggered
+
+Skip to Step 4 silently.
+
+## Why
+
+Epic #10397 (7 children × 7 PRs) closed with 5/7 per-PR briefs and no
+arc-level assessment — the synthesis surfaced only because the operator
+asked. The two missed children (#10400, #10404) were both partial-ship tails
+— paths a per-PR gate cannot cover. "Gate fixed" is not done — "gate fixed
+AND missed case remediated" is done.

package/skills/ship/references/feature-tweet-draft.md

@@ -0,0 +1,42 @@
+# Feature-Tweet Draft (pre-merge bundle)
+
+Loaded on demand by `soleur:ship` Phase 6, at the named step below. Extracted from the
+skill body under ADR-229: this is a content-generation step, not a correctness gate, and it
+runs only for a PR whose labels and title make it eligible — so carrying it in every ship
+invocation costs every operator bytes for a step most PRs skip.
+
+Generate any eligible feature-tweet draft NOW — after the semver/`app:*` labels
+are applied (eligibility reads the PR labels + title) — and **commit it to the
+feature branch** so it rides this PR into `main`, where `content-publisher.sh`
+reads from. This replaces the old post-merge generation, which wrote the draft
+into a worktree that `cleanup-merged` reaps before it ever reaches `main` (so
+the cron never saw it). The draft is **inert** (`status: draft`, empty
+`publish_date`) and never posts until the operator sets `publish_date` +
+`status: scheduled` — their post-deploy confirmation gate — so bundling it
+pre-merge does NOT weaken the "only tweet what actually deployed" property;
+`soleur:postmerge` Phase 3.8 still verifies deploy health and warns before the
+operator schedules.
+
+1. **Eligibility is already decided.** `bash scripts/lib/tweet-eligibility.sh <PR_NUMBER>`
+   ran in the skill body and exited 0; that is what loaded this file. It stays there rather
+   than here because a gate whose invocation lives inside the document you only open after
+   deciding is not a gate. Re-running it here is harmless but redundant.
+2. **Eligible →** invoke `skill: soleur:feature-tweet #<PR_NUMBER>` (writes +
+   displays the draft for approval per its §Output contract).
+3. **Commit + push the draft to the feature branch** so it lands on `main` with
+   the squash merge (stage ONLY the draft file — never `git add -A`):
+
+   ```bash
+   git add knowledge-base/marketing/distribution-content/<draft-file>.md
+   git commit -m "content: feature-tweet draft for #<PR_NUMBER> (inert — operator schedules post-deploy)"
+   git push
+   ```
+
+   The draft is a NEW commit, so the Phase 6.4 Unpushed-Commits Gate re-checks
+   clean before merge. Headless mode: same — generate + commit + push; never
+   schedule (the inert draft + operator gate are the publish control).
+
+If `soleur:ship` is hand-rolled and this step is skipped, the draft never reaches
+`main`; `soleur:postmerge` Phase 3.8 detects the missing on-`main` draft and
+runs the standalone catch-up (which then needs its own follow-up commit to land
+on `main`).