@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/audit-docs/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: audit-docs
+user-invocable: true
+version: 2.0.1
+argument-hint: "[--fix]"
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Audit cross-document coherence: docs ↔ roadmap ↔ code ↔ fix index ↔ issues.
+  Finds drift — features in docs/ not in the roadmap (or vice versa), fix-index
+  entries already merged/closed, broken documentation-map links, dependency
+  cycles, artifacts in the wrong language, naming-convention violations — and
+  reports them ranked by severity, fixing only low-risk items on request.
+  On Claude Code and want hand-tuned per-skill model/effort tiers? Install the `#claude` branch instead (`npx skills add gtrabanco/agentic-workflow#claude`) — see the README. This branch is model-agnostic: the skill inherits whatever model and effort your agent session is already using.
+  Triggers: "check doc consistency", "are the docs in sync", "audit the docs",
+  "doc coherence review", "did the docs drift", "validate the roadmap".
+---
+
+# Audit Docs
+
+A read-first audit answering "do the docs still match reality?" Produces a
+findings report; it does not silently rewrite docs.
+
+## Turn contract — verify before ending the turn
+
+```
+✓ The AUDIT DOCS fixed-format report was printed, ending in `Decision: PASS | FAIL`
+✓ No doc was rewritten without explicit --fix / user go-ahead
+✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
+```
+
+About to end the turn with any box unchecked? The turn is NOT done — complete
+the missing box first (weak models drop end-of-document duties; this list is
+first on purpose).
+
+## When to use
+
+- Before a release or milestone, after merging several features/fixes, or
+  whenever the doc set might have drifted from the code and issues.
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, then read
+what THIS skill needs: the roadmap, the fix index + template, and the feature
+folder layout — the map tells you which links and invariants to check.
+
+## Checks
+
+Run these and collect findings (cite paths/lines/issue numbers each):
+
+1. **Roadmap ↔ feature folders.** Every `docs/features/<NN>-<slug>/` is in the
+   roadmap, and every roadmap entry has a folder (or is explicitly "scheduled").
+2. **Feature dependencies.** SPEC `Depends on` / `Branch` fields are valid; no
+   dependency cycles; ordering is consistent with the roadmap.
+3. **Fix index hygiene.** Every entry maps to an **open** issue and an unmerged
+   branch; flag entries whose issue is closed or whose PR merged (should have
+   been removed). Flag open fix branches missing from the index.
+4. **Documentation-map links resolve.** Every file the map references exists;
+   flag "scheduled, not yet authored" items so they aren't mistaken for drift.
+5. **Broken intra-doc links.** Relative links/anchors point at real
+   files/sections.
+6. **Issue references.** Acceptance/known-issues lines referencing `#N` aren't
+   pointing at long-closed issues without note.
+7. **Language & naming conventions.** Artifacts in the project's docs language
+   (this repo: **English**); file/dir naming matches conventions (e.g.
+   kebab-case TS files, PascalCase components).
+8. **Invariant tags.** If the project uses invariant/decision IDs (e.g.
+   INV-/D-/KI-), spot-check that referenced IDs exist where claimed.
+9. **PR-link integrity on `done` rows.** Every roadmap row (and fix-index
+   entry) with status `done` carries a linked PR reference —
+   `done · [#<pr>](<pr-url>)`. For each bare `done`, find its PR in the forge
+   (`gh pr list --state all --head feat/<NN>-<slug>` or by title) and propose
+   the row update; a `done` with no PR found at all is HIGH severity (the unit
+   may never have been closed out).
+
+**Workflow discipline (checks 10–14)** — the executor skills enforce these at
+write time; this audit verifies they actually held. Each check is mechanical:
+run the command shown, don't infer.
+
+10. **Phase naming.** `grep -rnE '\bS[0-9]+\b|\bStep [0-9]' docs/features/*/{PLAN,TASKS,progress}.md`
+    must return nothing — plans use `P1, P2, …` ("phases") only. Any hit: LOW
+    (rename), plus check the executor argument still resolves.
+11. **Per-phase doc discipline.** For every M/L feature `in-progress`/`done`:
+    completed phases are ticked in `TASKS.md`, `progress.md` has one entry per
+    completed phase, and (features planned under the current template) the
+    final phase ends with the literal close-out tasks (open PR + print URL,
+    link roadmap row, push the link commit). A `done` feature with unticked
+    tasks or a phase missing from `progress.md`: HIGH.
+12. **Branch & PR discipline vs the forge.** For every `done` unit: its PR
+    exists, targets the default branch, has a non-empty body, and carries
+    `Closes #<n>` when the unit is issue-born (SPEC references an issue).
+    Also scan recent default-branch history (`git log --first-parent`) for
+    feature/fix-scoped changes committed directly without a PR: HIGH.
+13. **Generated-docs provenance (only when the documentation map declares a
+    `Docs site` block; otherwise state n/a).** Scan the declared content dir
+    for pages carrying `generated-by: agentic-workflow/generate-docs`. For
+    each: (a) its `source-unit` exists in the roadmap or fix index — no match
+    is an **orphan** (MEDIUM: propose deletion or re-attribution); (b) the
+    unit's PR merged **after** the page's `updated` date with commits touching
+    the page's subject paths — that page is **stale** (LOW: propose
+    `/generate-docs <unit>` to refresh). Cite page path + unit per finding.
+14. **Commit format & dependency discipline.** Sample the unit branches'
+    commits: `<type>(<scope>): <summary>` conventional format (violations:
+    LOW). Every `in-progress`/`done` row's `Depends on:` closure was merged —
+    a unit built on unmerged deps is HIGH unless `decisions.md` records a
+    user-forced override (`--force`), which downgrades it to LOW (documented
+    risk).
+
+Adapt the list to what the project has; skip checks for absent structures and
+say so.
+
+## Process
+
+1. Discover, then run the checks with `grep`, file reads, and the forge CLI
+   (per Workflow conventions; examples use `gh`).
+2. Produce the findings report — **return exactly** (fixed output contract):
+
+   ```
+   AUDIT DOCS — scope: <docs tree / roadmap / fix index / issues checked>
+
+   | # | Check (1-13) | Finding | Sev | Evidence | Proposed fix |
+   |---|-------------|---------|-----|----------|--------------|
+   | 1 | <which>     | <what>  | high|low | <path:line / #issue> | <smallest action> |
+
+   Checks run: <n>/13 (skipped: <which + why — absent structures only>)
+   Summary: <1-2 sentences>
+   Decision: PASS | FAIL   (FAIL if any high-severity finding is open)
+   ```
+
+   Sev: **high** = misleading or broken; **low** = cosmetic.
+3. **Fix only on request.** With explicit `--fix` (or user go-ahead), apply the
+   low-risk corrections (remove a merged fix-index row, fix a dead link, register
+   a missing roadmap entry, add a verified PR link to a bare `done` row). Leave judgment calls to the user.
+
+## Guardrails
+
+- Read-first; never bulk-rewrite docs unprompted.
+- Distinguish genuine drift from intentionally "scheduled/deferred" items —
+  don't report deliberate tradeoffs as errors.
+- Keep changes surgical and within docs; no code or behavior changes.
+
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **No slash-command menu** — where this skill says `/<skill>`, open that
+  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
+  literally, in a fresh conversation: hand-offs assume a clean context.
+- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+  these are mostly mechanical cross-document checks — a mid-tier model is
+  enough; escalate to your strongest only for a deep audit.
+
+## Relationship to other skills
+
+- Complements `plan-feature` (which *creates* the docs this audits) and
+  `triage-issue` (which keeps the fix index honest).
+- Run standalone anytime; no required predecessor.
+
+## Done when
+
+- A severity-ranked findings report exists, and any approved low-risk fixes are
+  applied — with genuine deferrals left untouched and labeled as such.
+- **The closing `→ Next:` block is printed:**
+
+  ```
+  → Next: apply the approved low-risk fixes, then re-run /audit-docs to confirm clean
+    · real drift (not cosmetic) → /triage-issue   · a concrete defect → /plan-fix
+    · already clean → nothing to do
+  ```

package/skills/audit-pr/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: audit-pr
+user-invocable: true
+version: 4.3.1
+argument-hint: <pr-number> (optional — defaults to the current branch's PR)
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Audit a whole PR against the delivery contract and return MERGE-READY or
+  evidenced blockers with the full URL. Consumes the current review-change
+  REVIEW-PASS receipt instead of re-running review axes; posts a SHA-bound
+  ready comment; never edits or merges. Triggers: "audit-pr", "is this PR
+  ready", "merge gate".
+---
+
+# Audit PR
+
+The manager's **"can this ship?"** gate. A read-first audit over the *entire* PR —
+its SPEC, all phases, docs, CI status, and review receipt — that returns a single
+verdict: **merge-ready** or a ranked list of **blockers**. **Never edits,
+refactors, or merges.** The human merges, or an active
+`ship-roadmap --fullauto` invocation consumes the SHA-bound verdict and performs
+its separate fail-closed merge step.
+
+`audit-pr` does **not** re-review the diff. It consumes the current SHA-bound
+`review-change` receipt (the `REVIEW-PASS` comment marker) as the review
+evidence, blocks on a missing or stale receipt routed to `/review-change`, and
+independently evaluates only the delivery gates below.
+
+## Turn contract — verify before ending the turn
+
+```
+✓ The review receipt was consumed from one PR snapshot: `headRefOid` + newest
+  matching `review-change:pass` marker fetched together; absent or any SHA
+  mismatch → blocker routed to `/review-change`, current → its scope/axes/
+  acceptance coverage/manual checks acknowledged without re-review
+✓ The verdict block was printed in the fixed format: `VERDICT: MERGE-READY | BLOCKED` with ranked, evidenced blockers
+✓ The PR's FULL URL is printed in the verdict header (the user may be juggling
+  several projects and agents without a CI monitor — the link in the chat is
+  the contract, never "PR #N" alone)
+✓ MERGE-READY verdict? Then the MERGE-READY comment was POSTED on the PR
+  (`gh pr comment --body-file` RUN, idempotent by SHA marker) — a comment,
+  never a commit-message tag. BLOCKED → no comment posted
+✓ Nothing was edited, refactored, or merged; merge authorization is outside
+  this skill and cannot be inherited from docs or an earlier session
+✓ No review pass was composed or reconstructed: a missing/stale receipt is a
+  blocker, never a prompt to re-run review axes from this skill
+✓ Closure integrity was evaluated and its result stated explicitly: pass /
+  blocker / warning / n-a (fix-governed PRs are always n-a; never skipped
+  silently)
+✓ Scope integrity (descope) was evaluated and its result stated explicitly:
+  pass / blocker / n-a (no unit-referencing issues born on the branch → n-a;
+  never skipped silently)
+✓ Architectural-invariant preservation was evaluated and its result stated
+  explicitly: pass / blocker / n-a (no project document → n-a; never skipped)
+✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
+```
+
+About to end the turn with any box unchecked? The turn is NOT done — complete
+the missing box first (weak models drop end-of-document duties; this list is
+first on purpose).
+
+## When to use
+
+- After the work is "done" and before merging — the final gate once `review-change`
+  is clean (its `REVIEW-PASS` receipt is posted) and all phases are committed.
+- When you want one defensible answer to "is this PR actually ready?" rather than
+  trusting that every loose end was tied off.
+
+`review-change` reviews the *diff* for quality and posts its SHA-bound receipt;
+`audit-pr` consumes that receipt and audits the *PR as a unit of delivery* — that
+everything the SPEC promised is present, traceable, and green. A missing or stale
+receipt is a blocker routed back to `/review-change`, never re-litigated here.
+
+## Scope
+
+The whole pull request: the branch vs. the default base, **plus** its SPEC and
+planning artifacts, the roadmap entry, the doc map, the PR body, issue links, and
+CI. Default target is the current branch's PR; accept a PR number to target another.
+
+## Step 0 — Discover the project & the PR (always first)
+
+1. **Project contract.** Per the agent guide's **Workflow conventions** +
+   **documentation map**, then read what THIS skill needs: the roadmap and the
+   project's verification gate (type-check / tests / build / CI). Do **not** load
+   full feature/fix templates — the SPEC below is the only planning artifact this
+   audit reads (AC 14).
+2. **The PR.** Identify it and read it in full (forge CLI per the project's
+   Workflow conventions — examples use `gh`):
+   ```sh
+   gh pr view <N> --json number,url,title,body,baseRefName,headRefName,headRefOid,isDraft,mergeable,mergeStateStatus,files,commits,statusCheckRollup,closingIssuesReferences
+   ```
+   If no PR number is given, resolve the current branch's PR
+   (`gh pr view --json ...`). If none exists yet, audit the branch vs. the default
+   base and say "no PR open yet" — the contract still applies.
+3. **The SPEC.** Locate the governing SPEC — `docs/features/<NN>-<slug>/` (feature)
+   or `docs/fix/<n>-<topic>/` (fix) — and its planning artifacts (`PLAN.md`,
+   `TASKS.md`, `progress.md`, `testing.md`, `known-issues.md`, `decisions.md`) when
+   present. The SPEC is the source of truth for what "done" means.
+
+## Step 1 — Consume the review receipt (always, before any gate)
+
+The review evidence is the SHA-bound `REVIEW-PASS` receipt `review-change` posts
+on the PR — **never** a re-review composed here. Fetch `headRefOid` and the PR's
+comments together, then find the **newest** comment carrying the marker
+`<!-- review-change:pass sha=<40-hex> contract=v1 -->`:
+
+```sh
+gh pr view <N> --json headRefOid,comments
+```
+
+- **current** — marker `sha` equals that snapshot's `headRefOid` (the current
+  head SHA). Acknowledge
+  its scope/axes, acceptance coverage, invariant result, and manual checks as the
+  review evidence, then evaluate the delivery gates below.
+- **absent** — no matching marker on the PR → **BLOCKER**: no review evidence at
+  the head; route to `/review-change`.
+- **stale** — a marker exists but its `sha` does not equal `headRefOid`. Any SHA
+  mismatch voids the receipt → **BLOCKER**: route to `/review-change` for a
+  re-review. Do not use a local `git diff` to override the PR-head comparison.
+
+Never compose, reconstruct, or "spot-check" the review from the diff to clear a
+missing/stale receipt — that is `review-change`'s turn, and re-litigating axes
+here is exactly what the receipt gate removes (AC 13).
+
+
+## Progressive loading — mandatory audit route
+
+The reference allowlist is exactly the six linked paths below. Never invent or
+read another `references/` path. After discovery and the Step 1 receipt check,
+every audit loads and applies exactly these five mandatory resources in order:
+
+1. [01 merge gates](references/01_MERGE_GATES.md) for delivery, CI, traceability,
+   review-receipt, and mergeability evidence.
+2. [02 closure and scope gates](references/02_CLOSURE_AND_SCOPE_GATES.md) for
+   capability closure and descope provenance.
+3. [03 audit process](references/03_AUDIT_PROCESS.md) to gather, decide, persist
+   blockers, and post the SHA-bound MERGE-READY comment.
+4. [04 verdict](references/04_VERDICT.md) before output, then
+   [05 routing and guardrails](references/05_ROUTING_AND_GUARDRAILS.md). These
+   mandatory resources own the `docs/workflow/REPOSITORY_STATE.md` evidence
+   rules and Architectural invariants gate.
+
+Read [portability](references/PORTABILITY.md) only when the declared forge or
+agent actually lacks a named primitive; otherwise skip it. The project artifact
+`docs/workflow/REPOSITORY_STATE.md` is evidence, not a skill reference. All
+resources are one hop from this file. Missing evidence or a missing required
+resource is a blocker; never infer a pass.
+
+## Merge ownership
+
+This skill **never merges**, including when project docs contain `merge: auto`,
+the user previously approved a merge, or a tool retained an earlier permission.
+Those signals cannot change this skill's read-first boundary.
+
+The **sole automated merge authority** is the AUDIT stage of an actively invoked
+`ship-roadmap --continue --fullauto` run. Its MERGE-READY comment is evidence,
+not permission; the repository wrapper independently verifies that comment,
+the forge's current head/default base, green checks, and the `merge: fullauto`
+decision fetched at that head. The wrapper owns fresh sync checks, transient
+state, merge execution, cleanup, and the automerge PR comment. A standalone/
+manual call to this skill always hands the MERGE-READY URL to the human.
+
+
+## Portability
+
+Translate forge commands, never the gate semantics. Use the explicit fallbacks
+in [portability](references/PORTABILITY.md).
+
+## Relationship to other skills
+
+```
+execute-phase (all phases done) ─▶ review-change (REVIEW-PASS receipt posted) ─▶ audit-pr ─▶ merge
+                                                                                │
+                     blockers ─┬─ receipt absent/stale ──▶ /review-change ──────┘ (re-review, re-audit)
+                               ├─ in-scope            ──▶ execute-phase ────────┘ (fold, re-audit)
+                               ├─ out-of-scope        ──▶ plan-fix
+                               └─ deferral            ──▶ triage-issue
+```
+
+- Consumes the `review-change` `REVIEW-PASS` receipt (its scope/axes, acceptance
+  coverage, invariant result, manual checks) plus the artifacts of `plan-feature` /
+  `plan-fix` / `execute-phase` (SPEC, phases, docs, `Closes #N`).
+- `audit-docs` is the cross-document coherence check; `audit-pr` is per-PR merge
+  readiness; `product-audit` is the periodic, product-wide full sweep.
+
+## Done when
+
+- The review receipt was consumed: a current marker was acknowledged, or a
+  missing/stale one became a blocker routed to `/review-change` (never re-reviewed
+  here).
+- Every applicable gate has a pass / blocker / n-a verdict backed by cited evidence.
+- A single top-line verdict (**MERGE-READY** or **BLOCKED** with ranked blockers) is
+  reported **with the PR's full URL in the header**, each blocker routed, with the
+  human's manual-verification list explicit.
+- On MERGE-READY the merge owner is explicit: a standalone audit hands the URL
+  to the human; an active `ship-roadmap --fullauto` AUDIT stage receives the
+  SHA-bound verdict and owns every later merge check.
+- The **closing `→ Next:` block is printed** (merge link → then the next unit via
+  `/plan-feature --next` or `/triage-issue`; BLOCKED → the routed fix, then re-audit).
+- Nothing was edited, refactored, or merged.

package/skills/audit-pr/references/01_MERGE_GATES.md

@@ -0,0 +1,24 @@
+## Merge-readiness contract
+
+Check each gate; cite evidence (file:line, criterion, check name, issue number).
+A gate that can't be confirmed is a **blocker**, not a pass — never assume green.
+
+| Gate | What it means | Blocker when |
+|---|---|---|
+| **Acceptance coverage** | The receipt's acceptance-coverage field accounts for every SPEC acceptance criterion (review-change verified the mapping). This gate confirms the receipt *names* the criteria — it never remaps diff hunks to criteria itself. | The receipt omits a criterion the SPEC lists, or its coverage field is absent/generic. |
+| **All phases complete** | Feature: every phase in `PLAN.md`/`TASKS.md` is done and logged in `progress.md`. Fix: the SPEC is fully implemented. | Any unchecked task or unimplemented phase without an explicit, tracked deferral. |
+| **Scope integrity (creep)** | The PR implements the SPEC and no more; out-of-scope work was split out. | Undocumented scope creep, or in-scope work missing. |
+| **Docs updated** | Every "Affected docs" criterion is satisfied; per-phase docs (`progress`/`testing`/`known-issues`/`decisions`) reflect reality; the doc map still resolves. **Never merge with documentation still pending.** | A doc the map or SPEC requires is stale, missing, pending, or contradicts the code. |
+| **Traceability** | `Closes #N` is in the PR body when the work is issue-born (from `plan-feature-from-issue` or `plan-fix`); the roadmap/fix-index entry matches, is **still present** (removed only *after* merge, never before), and carries the linked PR reference (`done · [#<pr>](<pr-url>)`). | Issue-born work without `Closes #N`; a roadmap/index entry out of sync; the entry dropped before merge; or a `done` row without its PR link. |
+| **Verification gate / CI** | The project's gate passes — type-check, tests, build — and `statusCheckRollup` is green at the current head. | Any required check failing, pending, or absent where the project requires one. |
+| **Mergeability** | Branch is off the default base, independently mergeable (no conflicts), not stacked on another PR, not draft. | Wrong base, conflicts, stacked dependency, or still draft. |
+| **Review receipt** | A current `REVIEW-PASS` receipt is posted on the PR: the newest comment carrying `<!-- review-change:pass sha=<40-hex> contract=v1 -->` whose `sha` equals the PR's current head SHA. Its scope/axes, acceptance coverage, invariant result, and manual checks are the review evidence this audit consumes. | Receipt absent, or its marker `sha` predates the current head (any later commit voids it). The blocker routes to `/review-change`; never re-review the diff from here (AC 13). |
+| **Closure integrity** | The governing **feature** SPEC's capability closure was taken and recorded — `design-feature` was actually run, not bypassed. Fix-governed PRs: `n/a` (no closure block by design). | A present `Capability closure` block has a blank row, or a resolved non-`n/a` row with no matching acceptance criterion. |
+| **Scope integrity (descope)** | An issue born during this unit that maps to an unmet SPEC acceptance criterion or phase task has a matching, user-approved, dated `## Amendments` entry — descoped scope was recorded, not silently exported. Detection is two-path: a slug/issue-number text match, **or** an issue linked from an `## Amendments` row (`#89`) — either is sufficient to enumerate the issue, so a descoped issue with a generic title/body is not invisible to the gate. | An issue born since branch divergence that references this unit (by either detection path) maps to an unmet criterion/task with no matching `## Amendments` entry, or an `## Amendments` row that is undated, unapproved, or unlinked to an issue. |
+| **Architectural invariants** | The **receipt** records the invariant result review-change took against the optional project invariant document; this gate confirms that result is explicit (`pass | blocker | n-a`) and does not reclassify it (AC 13). No document → `n/a: no project invariants declared`, not a blocker. | The receipt's invariant result is absent/ambiguous, or a recorded `blocker`/`violates`/`introduces`/`changes` lacks the cited decision the review surfaced. |
+
+> The review evidence is the receipt, never a re-review: verify the newest
+> `review-change:pass` marker's `sha` against the PR's head (Step 1). A current
+> receipt passes this gate regardless of its axes' content — the audit consumes,
+> it does not re-litigate. A missing or stale receipt is a blocker routed to
+> `/review-change`.

package/skills/audit-pr/references/02_CLOSURE_AND_SCOPE_GATES.md

@@ -0,0 +1,83 @@
+## Closure and scope gates
+
+> **Closure integrity — fixed output.** Detection is purely mechanical: grep the
+> governing SPEC for a `Capability closure` heading — match the heading text, not
+> a fixed level (SPECs nest it as `### Capability closure` under `## Product half`;
+> older ones use `## Capability closure`) — never dates, never versions, never
+> judgment.
+> - **Fix-governed PR** (`docs/fix/<n>-<topic>/SPEC.md`) → **n/a**, always. Fix
+>   SPECs carry no closure block by design; never emit a warning for one.
+> - **Feature SPEC, block present** → evaluate the three boxes, each a blocker
+>   on failure:
+>   1. the block exists in the SPEC (true whenever this path is reached)
+>   2. zero blank rows — every entity/capability/role row is either filled
+>      (UI + API + test) or carries an explicit `n/a: <reason>`
+>   3. every resolved non-`n/a` row maps to a listed acceptance criterion
+>   `n/a: <reason>` is a **fully valid, passing** row — the gate verifies the
+>   decision was *taken and recorded*, never that UI/API surface exists. Never
+>   push a blank row into inventing surface to pass this gate.
+> - **Feature SPEC, block absent** → the SPEC predates or bypassed
+>   `design-feature`. Never a blocker — emit a dated **warning**, PR still
+>   merges:
+>   ```
+>   design-debt: closure absent, SPEC predates the rule (dated <YYYY-MM-DD>)
+>   ```
+>   This warning is itself the **retrofit trigger**: the next unit of work that
+>   touches this feature must fill the closure via `/design-feature <slug>`
+>   (upsert — fills only the missing rows, destroys nothing recorded) *before*
+>   that new work is planned. See `design-feature`'s upsert semantics for the
+>   other half of this contract.
+
+> **`done` ≠ merge-ready.** A unit flips to `done` when its PR opens (built, not
+> merged — merge state lives in the forge). So a `done` roadmap row is *not* evidence
+> of merge-readiness: this gate still has to pass on its own. The two things this gate
+> most often catches on a `done`-but-unmerged unit are **pending docs** and a
+> **prematurely-removed issue/fix-index entry** — both are blockers.
+
+> **Scope integrity (descope) — fixed output.** A cheap way to look finished is
+> to quietly convert unfinished SPEC scope into a follow-up issue — the unit
+> reads as done, the scope silently moved to the backlog. This gate catches it
+> mechanically, keyed off the same `## Amendments` log `execute-phase`'s
+> descope guard writes to (single source — see that skill's *Descope guard*
+> section):
+> 1. List issues **born since the branch diverged**
+>    (`git log <base>..HEAD --format=%ad --date=short | tail -1` for the
+>    earliest commit date, then `gh issue list --state all --search
+>    "created:>=<date>"`) that **reference this unit**, via **either** of two
+>    detection paths — a hit on either is sufficient, run both, never only the
+>    first:
+>    - **text match** — title/body mentions the feature/fix slug or issue
+>      number, or
+>    - **`## Amendments` link** (`#89`) — the issue is linked from a row in
+>      the governing SPEC's `## Amendments` section (the same log
+>      `execute-phase`'s descope guard writes to — single source, see that
+>      skill's *Descope guard*), **regardless of the issue's own title/body
+>      text**. This closes the coverage gap a generic-titled or slug-unaware
+>      descoped issue leaves in the text-match path alone: an issue linked
+>      from an amendment row is unambiguously about this unit no matter what
+>      it's titled.
+> 2. For each such issue (from either path), run the per-issue checklist:
+>    - ✓ the SPEC criterion/task it touches is still **met in the PR** — pass,
+>      it's discovered work or already covered, or
+>    - ✓ a matching `## Amendments` entry exists in the governing SPEC
+>      (dated, **user-approved**, and **linked** to this issue's number) — pass,
+>      the descope was properly recorded
+>    - neither holds → **BLOCKER**.
+> 3. Symmetrically, every `## Amendments` row in the governing SPEC must itself
+>    be dated, user-approved, and link a real, existing issue — an `## Amendments`
+>    row missing any of those is also a **BLOCKER** (a hollow amendment is the
+>    same failure as no amendment at all).
+> - **Scope:** any SPEC-governed PR — **feature and fix** alike, both carry
+>   acceptance criteria a lazy run could export. No issues born during the unit,
+>   or none referencing it → the gate **passes** (nothing was exported).
+> - This gate never re-litigates whether the *original* criterion was reasonable
+>   — only whether its descope, if any, was recorded and approved before the
+>   issue was filed.
+> - **Backstop, not primary.** `execute-phase`'s creation-time descope guard
+>   (`skills/execute-phase/SKILL.md` *Descope guard*) is the **primary**
+>   control — it stops a descope from ever reaching an issue without an
+>   approved `## Amendments` entry first. This gate is the **backstop** that
+>   catches what the primary control missed (a descope-filed issue from a
+>   session that bypassed the guard, or a hand-filed issue). The `## Amendments`
+>   -link detection path (`#89`) widens this backstop's *coverage* only — it
+>   changes nothing about `execute-phase`'s own contract or precedence.

package/skills/audit-pr/references/03_AUDIT_PROCESS.md

@@ -0,0 +1,69 @@
+## Process
+
+1. **Gather** — Step 0: project contract, PR, SPEC + artifacts, CI status.
+2. **Consume the review receipt** — Step 1: fetch the PR's `headRefOid` and
+   comments in one query (`gh pr view <N> --json headRefOid,comments`) and take
+   the **newest** marker
+   `<!-- review-change:pass sha=<40-hex> contract=v1 -->`. Its `sha` must equal
+   that query's `headRefOid` current head SHA. Any mismatch is stale; do not
+   use a local diff to preserve a receipt for a different PR head.
+   - **current** → acknowledge scope/axes, acceptance coverage, invariant result,
+     manual checks; continue to the gates.
+   - **absent / stale** → **BLOCKER** (no review evidence at the head), routed to
+     `/review-change`; never re-review from here.
+3. **Walk the contract** — evaluate every gate above against evidence. For each,
+   record pass / blocker / n-a with the specific artifact or check that proves it.
+4. **Confirm deferrals are real** — for anything postponed (an unchecked task, a
+   review finding, a known issue), verify a tracked issue + trigger exists. A
+   deferral with no destination is a blocker, not a pass.
+5. **Decide** — one verdict:
+   - **MERGE-READY** — every applicable gate passes (including a current receipt);
+     list the few things the human should still eyeball (the manual-verification
+     items the receipt surfaced).
+   - **BLOCKED** — one or more gates fail; output the ranked blocker list.
+6. **Persist blockers to the fold ledger (BLOCKED verdict only).** Every blocker
+   on a **BLOCKED** verdict is, by definition, fix-now — merge is gated on it.
+   Append each to the unit's fix-now fold ledger `review-findings.md` (same
+   location and fixed schema
+   `| id | file:line | axis | severity | class | route | folded |` as
+   `review-change`'s persist step) — the **same ledger**, not a separate one
+   (D4: the fold cycle consumes one list). **Merged unit → no write** — check
+   `gh pr view --json state`; `MERGED` skips the persist step entirely. For
+   each blocker: `file:line` = the cited evidence location (the gate name
+   when no single line applies); `axis` = the gate name (e.g. `Review
+   receipt`, `Docs`, `Traceability`); `severity` = `high` (a blocker gates
+   the merge by definition); `class` = `fix-now`; `route` = the routing this
+   skill's own Routing section assigns to that kind of blocker; `folded`
+   starts `no`.
+   Re-runs **dedupe by `file:line` + axis**, identical to `review-change`'s
+   rule — a blocker already on the ledger at that `file:line`+axis is not
+   re-appended; a genuinely new blocker gets the next `Fn` id.
+7. **Post the MERGE-READY comment on the PR (MERGE-READY only).** The verdict
+   must be visible on the PR itself — as a **comment**, never in a commit
+   message (a commit trailing "MERGE-READY" pollutes history and goes stale
+   the moment the branch moves). Write the body to a file (Markdown rule —
+   see Guardrails) and run
+   `gh pr comment <N> --body-file <path>` with exactly this body:
+
+   ```markdown
+   <!-- audit-pr:merge-ready sha=<head SHA> -->
+   ## ✅ audit-pr: MERGE-READY
+
+   - **Audited head:** `<head SHA>` · CI: <green|local-gate-green>
+   - **Review receipt:** `REVIEW-PASS` at `<head SHA>` (consumed, not re-reviewed)
+   - **Date:** <YYYY-MM-DD>
+   - **Before merge, a human should still verify:**
+     - <manual-verification item — or "nothing">
+
+   Any commit after `<head SHA>` voids this verdict — re-run `audit-pr`.
+   ```
+
+   **Idempotent:** first check the existing comments
+   (`gh pr view <N> --json comments`) for the `<!-- audit-pr:merge-ready -->`
+   marker — same SHA already commented → skip (say so); older SHA → post the
+   new comment (the newest marker wins). Never post a comment for a BLOCKED
+   verdict — blockers go in the chat report only, so the PR page never shows
+   a stale green flag.
+8. **Report** — the verdict block below, always headed by the PR's full URL.
+   In an active `ship-roadmap --fullauto` AUDIT stage, return the verdict to the
+   conductor; never run its merge wrapper from this skill.

package/skills/audit-pr/references/04_VERDICT.md

@@ -0,0 +1,69 @@
+## Verdict format
+
+```
+PR #<N> — <title>
+URL: <full PR URL — always printed; the user works across several projects
+     and not every agent shows a CI monitor or PR list>
+Base: <default> ← Head: <branch> @ <head SHA>   CI: <green|failing|pending>
+
+VERDICT: MERGE-READY | BLOCKED (<count> blockers)
+
+Blockers (ranked):
+  1. [<gate>] <what's wrong> — evidence: <file:line | check | criterion>
+     → fix: <smallest action to clear it> (<route>)
+  ...
+
+Warnings (non-blocking — never change the verdict):
+  - design-debt: closure absent, SPEC predates the rule (dated <YYYY-MM-DD>)
+
+Non-blocking nits:
+  - <minor item> — <pointer>
+
+Before merge, a human should still verify:
+  - <manual-verification item from the review-change receipt>
+
+→ Next:
+  Print the ONE verdict bullet that matches, THEN — if a closure warning fired —
+  also print the closure bullet (a warning never blocks, so it co-occurs with a
+  MERGE-READY verdict; the two lines print together, never one instead of the other):
+  · MERGE-READY, standalone/manual audit → you merge: <full PR URL>, then
+    /plan-feature --next (the next roadmap unit) or pick an issue with /triage-issue
+  · MERGE-READY inside active ship-roadmap --fullauto → return this SHA-bound
+    verdict to the conductor; it runs the transient merge wrapper
+  · BLOCKED → clear the top blocker (routed above), then re-run /audit-pr
+  · Receipt absent/stale blocker → /review-change (re-review at the head), then
+    re-run /audit-pr — never re-review from this audit
+  · Closure warning (in addition to the verdict above) or a closure blocker →
+    /design-feature <slug> — fills the missing closure rows (upsert, destroys
+    nothing) before further work on this feature is planned; re-run /audit-pr after
+  · Scope-bleed blocker → record the missing `## Amendments` entry (user-approved,
+    dated, linking the issue) in the governing SPEC, or re-classify the issue as
+    genuinely discovered work via /triage-issue; re-run /audit-pr after
+```
+
+If MERGE-READY, omit the blocker list and state it plainly: nothing blocks merge.
+The `→ Next:` block is always printed — on MERGE-READY it repeats the **full PR
+URL** (merge it yourself, or the merged link) and points the user at the next
+concrete unit so a finished feature never dead-ends at the merge.
+
+Example (generic — substitute your project's numbers and gates):
+
+```
+PR #142 — Add CSV export to the reports view
+Base: main ← Head: feat/14-csv-export   CI: green
+
+VERDICT: BLOCKED (2 blockers)
+
+Blockers (ranked):
+  1. [Tests] Export handler has no test — acceptance criterion "export
+     round-trips the rows" is unverified
+     → fix: add an integration test for the handler (fold into the current phase)
+  2. [Traceability] PR body is missing `Closes #131` for issue-born work
+     → fix: add `Closes #131` to the PR body (execute-phase)
+
+Non-blocking nits:
+  - Help text wording diverges from the other commands — docs/USAGE.md
+
+Before merge, a human should still verify:
+  - The exported file opens cleanly in a spreadsheet app (visual)
+```