@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/ship-roadmap/references/GUARDRAILS.md

@@ -0,0 +1,56 @@
+## Guardrails
+
+- **Never work on the default branch** — the empty-repo initial scaffold commit
+  is the single exception. One PR per unit, never stacked; roadmap status flips
+  ride PR-bound commits only.
+- **Forge bodies are Markdown, not shell — never hand-escape.** Every explicitly
+  authorized issue, PR, or comment the run creates (subagent PRs, triage
+  comments) carries a body of **real Markdown**: backticks / `*` / `_` are
+  formatting, and a `\` before them renders literally (`` \`code\` `` instead
+  of `` `code` ``). Write the body to a file and pass **`--body-file <path>`**
+  to `gh issue create` / `gh pr create` / `gh issue comment` (or the declared
+  forge's equivalent) — never inline `--body "…"` or a quoted heredoc. Verify
+  with `gh … --json body` that no literal `` \` `` survived. (execute-phase
+  subagents already follow this; the conductor must too.)
+- **Never commit red; never merge red.** The gate and the floors are
+  unconditional — no flag, mode, or interview answer disables them.
+- **Never request or retain a direct-merge permission.** Fullauto calls only
+  the repository wrapper with command-scoped variables; a missing wrapper or
+  active guard blocks the run and routes to `init-workspace` upgrade.
+- **No stage ends dirty or unpushed.** The clean close-out check (Mode B
+  step 5) is part of every stage: tracked modifications — docs included — are
+  committed with the stage, and a PR-backed branch is pushed before the
+  iteration logs the stage complete. Merging while anything is uncommitted,
+  unpushed, or unpulled is forbidden: push, wait for CI, re-audit, then merge.
+- **The conductor never writes application code.** All implementation flows
+  through fresh cheap-tier `execute-phase` workers, one phase per context —
+  that keeps the cost model honest and `execute-phase` the single pathway.
+- **Tier discipline.** Compose in-turn only skills at ≤ opus/high;
+  implementation goes below the turn tier via explicit subagent model
+  overrides; `product-audit` is never run by this skill. `ultracode` is a
+  user-owned session setting — recommended, never claimed.
+- **Interview once, then silence.** Mid-run gaps — including a mid-run
+  `idea`/`defined` unit's product-half gaps in the DESIGN stage — are resolved
+  from the decision record and logged; contradictions park the feature with
+  the evidence recorded. Re-interviewing mid-run is forbidden, in DESIGN as in
+  every other stage: an undesignable unit is parked (`NEEDS_INPUT` on that
+  unit, `state: CONTINUE` on the run), never asked about. The recovery from a
+  wrong founding call is a reported stop and a human-restarted run.
+- **Scope discipline.** Defects and ideas discovered mid-run become report
+  proposals — never automatically-created issues or in-run side quests. Only
+  existing user/forge issues enter the issue sweep.
+- **Stack/architecture/forge agnostic; English artifacts** regardless of the
+  interview language; recommendations proportional to the interviewed scale,
+  recorded in the project's own docs so every sub-skill discovers them through
+  its normal Step 0.
+
+**Known limits (stated, not hidden):** subagent overrides pin the model but
+not the effort, so execution subagents inherit the session's effort — cost can
+drift if the session runs high. `/loop`'s stop-on-banner matching should be
+treated as a convenience, not a guarantee — iterations after a terminal banner
+are idempotent no-ops, and the loop can always be stopped manually. Budget caps
+count iterations, not tokens — and the count lives in the machine-local log, so
+it bounds each machine's run, not the run's lifetime across machines. Verdicts
+persist in the run log and feature docs,
+but a crash between PR close-out and review may re-run one receipt check —
+accepted cost, never a correctness risk.

package/skills/ship-roadmap/references/MODEL_ROUTING.md

@@ -0,0 +1,14 @@
+### Model routing
+
+| Stage | Tier | Mechanism |
+|---|---|---|
+| Interview, founding, roadmap creation | opus/high | this skill's frontmatter; composes `init-workspace` (equal tier), answers pre-fed |
+| Recovery, routing, logging | opus/high | in-turn (tiny token volume; a subagent would add cost, not save it) |
+| JIT feature design (mid-run `idea`/`defined` unit) | opus/high | compose `design-feature` + `plan-feature-scaffold` in-turn (equal tier, deriving only from `SHIP_DECISIONS.md` — no new questions) |
+| JIT feature planning | opus/high | compose `plan-feature` in-turn (its internals are opus/high–medium: ≥ holds) |
+| Phase execution, single-pass, fixes | **cheap worker** | fresh context per phase following `execute-phase`; Claude branch maps this role to `sonnet`, portable drivers use their validated worker tier |
+| Final review/correction loop | opus/high | compose `loop-review-fold`; it selects review or fold from persisted evidence and routes unresolved findings to `triage-issue --prioritize-now` |
+| Merge gate | opus/high | compose `audit-pr` in-turn (the highest-stakes automated verdict; must share one turn with the floor checks) |
+| Forge/git mechanics | — | Bash tool calls; no model judgment involved |
+| Final-report evidence gathering | haiku (optional) | fan-out subagents for grep-shaped per-feature log collection when ultracode is on; synthesis stays opus |
+| `product-audit` | opus/max | **never composed, never imitated by a subagent** — its effort (max) exceeds the conductor's (high) and a subagent override cannot carry `effort: max`. Hand-off only: the report prescribes when to run it. |

package/skills/ship-roadmap/references/PORTABILITY.md

@@ -0,0 +1,34 @@
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. This skill
+leans on them harder than any other — here is the manual equivalent of each:
+
+- **No `/loop`** — two equivalent replacements, both vendor-neutral: (a) an
+  **external orchestrator** loops `/ship-roadmap --continue` headless and
+  routes its native fixed `SHIP:` banner plus closing `→ Next:` block (full
+  protocol + driver skeleton in `docs/workflow/ORCHESTRATION.md`); (b) manual
+  re-invocation after each iteration. Iterations are
+  stateless-by-reconstruction, so any driver is exactly equivalent; stop when
+  the first line is a terminal `SHIP:` banner. **Every iteration ending is
+  announced** — "iteration complete (normal; re-invoke to continue)" vs a
+  parked/terminal reason — so a stop is never ambiguous.
+- **No subagents** — execute phases sequentially: for each phase, one **fresh
+  headless invocation (or conversation) on a cheaper model** following the
+  installed `execute-phase` SKILL.md for exactly one phase (same two autopilot
+  overrides) — the external-driver pattern in `docs/workflow/ORCHESTRATION.md`
+  does exactly this. The conductor stages (recover/plan/PR/review/audit) stay
+  on your strongest model.
+- **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 the conversation the routing table assigns it (in-turn = this
+  conversation; subagent/hand-off = a fresh one).
+- **No per-skill `model:`/`effort:`** — the `#claude` branch's routing table pins these tiers; here, pick tiers yourself:
+  judgment stages on your **strongest** model, implementation on a cheaper one,
+  and `product-audit` always as its own maximum-effort run.
+- **Provider concurrency limits** — when spawning parallel subagents (or
+  parallel headless invocations), cap concurrency at the provider's documented
+  parallel-request limit per API key, leaving one slot free for the conductor
+  (e.g. a provider allowing 5 concurrent requests → at most 3–4 parallel
+  executors). An agentic loop spends one request per tool round-trip, so
+  parallel executors also eat the per-minute request budget fast; on a 429,
+  reduce parallelism before retrying rather than hammering the limit.

package/skills/ship-roadmap/references/RECOVERY_AND_SELECTION.md

@@ -0,0 +1,93 @@
+### Mode B — One loop iteration: `/ship-roadmap --continue [--fullauto]`
+
+Every iteration is stateless-by-reconstruction — no memory is assumed between
+turns:
+
+1. **RECOVER.** Read `SHIP_DECISIONS.md` (missing → `SHIP: STOPPED — no run
+   policy; run /ship-roadmap first`) and `.ship-run.log` (missing on this
+   machine → recreate empty; policy lives in the committed record). **Verify
+   the substrate landed:** `SHIP_DECISIONS.md` must exist on the default
+   branch — an open `docs/ship-founding` PR means the substrate isn't merged
+   yet → `SHIP: BLOCKED` with "merge the founding PR" as the unblock map.
+   Read ROADMAP.md; query the forge for open/merged PRs on `feat/*`, `fix/*`,
+   `docs/ship-founding` and `docs/ship-report` heads; check git state.
+   Reconcile: a feature flips to `done` when its **PR opens** (built, not merged
+   — see the PR stage), so a `done` row with an open PR is awaiting a human merge
+   (default mode), not finished shipping. A **merged** PR needs no status change
+   (already `done`) — it means *shipped*, and **unblocks its dependents** + counts
+   toward `SHIP: COMPLETE`. The done-flip rides the PR-bound commit, never a lone
+   commit on the default branch. A dirty feature branch from a crashed phase
+   is handed to the next phase subagent to finish or restart (counts against
+   the red-gate retry cap). Uncommitted changes on the default branch confined
+   to `docs/features/<NN-slug>/` + ROADMAP.md that match an in-flight roadmap
+   row are the loop's own planning output — resume that feature; the
+   dirty-default stop fires only for changes matching no roadmap unit.
+2. **STOP-CHECK.** Evaluate the stop conditions (below). Terminal → write or
+   refresh the final report, open the report PR, print the `SHIP:` banner +
+   status table, end the turn.
+3. **SELECT one unit.** Priority order, first match wins:
+   1. **Urgency labels first (feature 15, injection-safe).** Read
+      `workflow-status`'s `detail.urgent` (labels-only, presence-only —
+      never derived from issue text; see `skills/triage-issue/SKILL.md`, the
+      sole owner of the `urgent`/`fix-next` vocabulary):
+      - Any open issue labeled **`fix-next`** → its fix jumps to the head of
+        the queue exactly like a blocking fix below (`plan-fix` →
+        `execute-phase --fix`), **no interrupt** of the in-flight unit — it
+        waits for the current stage to finish this iteration, then is
+        SELECTed next.
+      - Any open issue labeled **`urgent`** → run the canonical pause-vs-finish
+        rubric in `docs/workflow/ORCHESTRATION.md` **by reference, never
+        forked here** — feed it the issue content plus `detail.urgent
+        .interruptibility` for the current in-flight unit.
+        `INTERRUPT_NOW` → park the in-flight unit (WIP commit + `progress.md`
+        note, same as any voluntary park) and SELECT the urgent issue's fix as
+        this iteration's unit instead. `FINISH_FIRST` → this iteration
+        proceeds normally (steps below); the urgent fix is queued head-of-line
+        for the **next** iteration, same as `fix-next`.
+      - No `urgent`/`fix-next` issues in `detail.urgent` → fall through to the
+        normal priority order below.
+   2. **Blocking fixes first.** A fix-index entry classified fix-now whose
+      subject blocks the next startable feature (same module, a dependency's
+      defect, or a red gate cause) → its fix is the selected unit
+      (`plan-fix` → `execute-phase --fix` through the normal stages). Fixes
+      that block nothing wait for the report's triage batch.
+   3. An in-progress feature's next pending stage.
+   4. The next feature at status `idea` **or** `planned` whose depends-on rows
+      are all **merged** (forge state, not merely `done` — a `done` dep with
+      an open PR isn't on the default branch yet, so a dependent cut from it
+      would lack its code). A `defined`-but-not-`planned` row is treated the
+      same as `idea` here — its design exists but its planning artifacts
+      don't, so it still needs a scaffold pass before PLAN.
+      **Verify the closure transitively:** a dep row marked merged whose own
+      dependencies aren't merged means the roadmap's statuses are inconsistent
+      → `SHIP: STOPPED` (substrate invariant broken), never build on top of it.
+      → `idea`/`defined`: DESIGN first (see ADVANCE). `planned`: → PLAN
+      directly.
+   5. **Issue sweep — features exhausted, run NOT over.** Every roadmap feature
+      is `done` **and merged** but the sweep hasn't completed → the run
+      continues with issues; finishing the features is not finishing the run:
+      1. **INVENTORY (once per run, its own iteration).** Enumerate (a) every
+         open forge issue and fix-index entry; (b) every *documented residue*
+         the run itself generated — each feature's `known-issues.md`, the
+         trade-offs in `decisions.md`, and every review report's
+         proposals/trade-offs. Residue without an existing issue remains a
+         deduplicated **proposal** in the report; the run never creates backlog
+         to make inventory look complete. Log existing issue numbers and
+         proposal sources separately.
+      2. **TRIAGE (compose `triage-issue` in-turn, equal tier).** Classify
+         each existing inventoried issue against the CURRENT codebase. fix-now → it
+         becomes a selectable unit; postpone / wontfix / promote-to-feature →
+         the dated verdict is recorded on the issue and carried into the
+         report (promotions and untracked residue become report proposals,
+         never in-run scope or automatically-created issues).
+      3. **SHIP the fix-now issues** one unit at a time through the normal
+         stages (`plan-fix` → EXECUTE (`--fix`) → PR → REVIEW → AUDIT), same
+         budget caps, floors, and merge policy as features.
+   6. Nothing startable → `SHIP: BLOCKED` with the **unblock map** ("merging
+      #12 unblocks 05 and 07") and the resume command.
+
+   `execute-phase`'s own dependency gate stays active inside every subagent —
+   it's the belt to this braces. **The autopilot never passes `--force`:** a
+   gate stop inside a subagent parks the feature with the unmet chain recorded;
+   forcing through unmet dependencies is a human-only decision, made outside
+   the loop.

package/skills/ship-roadmap/references/STOP_CONDITIONS.md

@@ -0,0 +1,9 @@
+### Stop conditions
+
+| Banner | Fires when |
+|---|---|
+| `SHIP: COMPLETE` | Every roadmap feature is `done` **and its PR merged** (default mode: the human merged them all; `--fullauto`: merged under the floors) — `done` alone is not enough, since it only means *built + PR open* — **AND the issue sweep ran to completion**: existing issues inventoried/triaged, every fix-now issue shipped or parked, and untracked residue deduplicated as report proposals without creating backlog. Features merged but sweep pending → the run is NOT complete. Report written, report PR open. |
+| `SHIP: BLOCKED` | Everything remaining is `done`-but-pr-open awaiting human merges, or planned with unmerged deps (default mode); or a parked feature transitively blocks the rest. Always includes the unblock map. |
+| `SHIP: STOPPED` | Budget/iteration cap; a Round-5 milestone stop line; substrate invariant broken (gate unrunnable, roadmap unparseable, unexplained dirty default branch, decision record missing); forge unavailable (no stage that depends on PR state may proceed on guesses). |
+| (feature parked, run continues) | Repeated red gate (retry cap), review ping-pong (2 cycles), audit ping-pong (2 cycles), capacity guard (3 partials), planning contradiction, **undesignable-from-record** (DESIGN stage `NEEDS_INPUT` — the recorded gap is a human-only unpark, never a mid-run re-ask). |
+| **Systemic drift stop** | `review-change` flags SPEC drift on **two consecutive features** → the locked founding assumptions are probably stale; the whole run stops rather than auto-merging a compounding error. |

package/skills/ship-roadmap/references/TERMINAL_REPORT.md

@@ -0,0 +1,34 @@
+### Final report
+
+Written by the terminal iteration to `docs/features/SHIP_REPORT_<date>.md` on a
+`docs/ship-report` branch as a docs-only PR (default: human merges; `--fullauto`:
+audit-gated like any PR), and printed in full under the banner:
+
+1. **Run summary** — mode, iterations used vs cap, stop reason, feature counts
+   (merged / `done`-awaiting-merge / parked / not started).
+2. **Per-feature outcomes** — size planned vs final, phases, gate history,
+   review findings folded vs postponed, audit verdict + SHA, PR + final state,
+   merged by human or autopilot.
+3. **Issues** — the sweep's existing-issue inventory and outcomes: fix-now issues
+   shipped (PR links), postponed/wontfix verdicts with the trigger that
+   should reopen each (feeds `triage-issue`'s verification model), and
+   anything the sweep could not finish (budget/parked) as the explicit
+   remaining triage batch. Untracked residue is listed separately as proposals;
+   the run created no backlog for it.
+4. **New feature proposals** — capabilities discovered during the build that
+   serve the product goal (Round 1 quoted as the yardstick), each sized with a
+   suggested roadmap slot. Recommend-only.
+5. **Residual risks** — weak test areas, `--fullauto` merges deserving a second
+   look, parked features and why, silent decisions with outsized consequences.
+6. **Manual-verification checklist** — the deduplicated union of every review
+   checkpoint's manual checks plus audit notes: what no gate proved.
+7. **Going forward** — concrete `product-audit` cadence for this project
+   (first one now if ≥2–3 features merged; then ~every 5 or pre-release), and
+   the suggested command sequence to continue, closed with the canonical block:
+
+   ```
+   → Next: <merge the open PRs | /triage-issue <batch> | /plan-feature --next>
+     · accepted proposals → /plan-feature   · product-audit due → /product-audit
+   ```
+
+Closing line, verbatim policy: **this report recommends; the human decides.**

package/skills/triage-issue/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: triage-issue
+user-invocable: true
+version: 2.6.0
+argument-hint: <issue-number> [more issue numbers…] | <audit-id> F<k> [F<j>…] | --prioritize-now <unit> F<k> [F<j>…]
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Verify an issue, persisted audit finding, or unresolved review finding against
+  current code, classify it, and write only the contracted forge/ledger
+  outcome. Supports independent batches and an immediate-fix review-finding
+  route. Triggers: "triage-issue", "triage issue N", "triage this finding",
+  "is this trigger met".
+---
+
+# Triage Issue
+
+Decide what happens to an issue, grounded in evidence — not vibes. Prevents both
+premature work (acting on a deferred item whose trigger is unmet) and silent rot
+(a fix-now bug left to drift).
+
+## Turn contract — verify before ending the turn
+
+```
+✓ One fixed-format verdict block per issue (Trigger / Checked / Evidence / VERDICT / Action) — plus the summary table when batched
+✓ Nothing deferred was implemented inline
+✓ Audit-finding mode (`<audit-id> F<k>`): the audit file carries its `↳ triaged` note, and any opened issue cites `Origin: product audit <id>, finding F<k>`
+✓ Review-finding mode (`--prioritize-now <unit> F<k>`): every named unresolved finding gets a verdict, an immediate-fix attempt, or an explicit replan/user-decision route
+✓ Batched input? The closing recommendation maps every issue/finding ID to its own next command, joined with ` + `; it never collapses to one generic action
+✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
+✓ 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
+
+- Any issue needing a decision: a freshly filed bug, a `postpone`/`needs-triage`
+  item, or a periodic re-confirmation of a deferred tradeoff.
+- **Batch triage** — pass several numbers (`triage-issue 12 14 17`): each issue
+  gets its own independent verdict + evidence, then one summary table at the
+  end. Batching applies to *triage only* — any resulting fix still gets its own
+  branch and PR.
+- **Audit findings** — `triage-issue <audit-id> F<k> [F<j> …]` triages findings
+  from a persisted `product-audit` report instead of existing issues (see
+  *Audit-finding mode* below). Batching works the same way.
+- **Review findings** — `triage-issue --prioritize-now <unit> F<k> [F<j> …]`
+  triages unresolved rows from the current feature/fix unit's
+  `review-findings.md`. This route is for findings that `fold-findings` could
+  not close. `--prioritize-now` means attempt to resolve every named finding
+  immediately; it does not permit a downgrade, postponement, or silent drop.
+
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, then read
+what THIS skill needs: the fix index (e.g. `docs/fix/README.md`) and fix SPEC
+template, and the roadmap. In review-finding mode, read the target unit's SPEC,
+acceptance, `review-findings.md`, current diff, and PR instead of looking for an
+issue comment. Otherwise read the issue in full, including comments and labels
+(forge CLI per the project's Workflow conventions — examples use `gh`):
+
+```sh
+gh issue view <N> --json number,title,body,labels,state,comments
+```
+
+
+## Progressive loading — select the triage source
+
+The reference allowlist is exactly the five linked paths below. Never invent or
+read another `references/` path. After Step 0:
+
+- Forge issue number(s): read [issue process](references/ISSUE_PROCESS.md).
+- Review finding(s): read [review finding process](references/REVIEW_FINDING_PROCESS.md).
+- Persisted audit finding(s): first read
+  [audit findings](references/AUDIT_FINDINGS.md), then use the verification and
+  decision steps in [issue process](references/ISSUE_PROCESS.md).
+- Before applying an urgency or disposition label, read
+  [label vocabulary](references/LABELS.md); this file is the sole definition of
+  names, colors, and mutation rules.
+- Only when the verdict is `fix-in-unit`, read
+  [fold ledger](references/FOLD_LEDGER.md) before writing the row.
+
+Every resource is one hop from this file. A missing source artifact or required
+resource stops that item; batch items remain independent. Never invent a label,
+trigger, ledger row, verdict shape, or reference filename. A forge-issue
+`postpone` route loads exactly issue process then label vocabulary; it skips
+audit findings and fold ledger.
+
+## Guardrails
+
+- Don't build deferred work just because asked to "look at" the issue — surface
+  that the trigger is unmet and stop.
+- Keep issues, the fix index, and docs in sync with reality.
+- Otherwise per the project's **Workflow conventions** (docs-language, evidence):
+  state exactly what you checked.
+
+
+## Portability
+
+Use the project's declared forge CLI and translate commands one-for-one. The
+classification, label ownership, and persisted-output contracts do not change.
+
+## Relationship to other skills
+
+```
+                 ┌─ fix-now ─────────▶ plan-fix ─▶ execute-phase --fix
+                 ├─ fix-in-unit ─────▶ execute-phase <NN> P<k> (fold into phase)
+triage-issue ────┤                    or fold-findings (ledger row)
+                 │                    or design-feature / plan-feature (replan)
+                 ├─ promote ─────────▶ plan-feature (router → from-issue)
+                 ├─ postpone ────────▶ dated comment, leave open
+                 └─ wontfix ─────────▶ propose close
+```
+
+In review-finding mode, `replan-in-unit` routes to `/plan-feature` for a
+feature or `/plan-fix` for a fix, with new `P<n>` phases appended to the same
+unit. The user manually runs those phases; this skill never implements them.
+
+## Done when
+
+- The issue has a clear verdict with cited evidence.
+- Each review finding has a clear verdict with cited evidence; an oversized
+  finding has an explicit planning command and a manual `/execute-phase` hand-off.
+- The verdict is recorded (routed, commented, and/or index-updated), and nothing
+  deferred was implemented inline.
+- **The closing `→ Next:` block is printed** per verdict:
+
+  ```
+  Single issue:
+  → Next: <command for the recorded verdict> — act on the issue's evidence-backed action
+
+  Batch:
+  → Next: apply every verdict: #<n1> → <command> + #<n2> → <command> + #<n3> → <command>
+    · fix-now → /plan-fix <n>   · promote → /plan-feature <n>
+    · fix-in-unit → /execute-phase <NN> P<k> or /fold-findings — never /plan-fix
+    · postpone → dated comment, leave open   · wontfix → propose close
+    · same inconsistency across several issues → /product-audit (a recurring pattern,
+      not isolated tickets — sweep the product rather than triaging one by one)
+  ```
+
+  Replace every placeholder with every actual issue/finding ID and its recorded
+  route before printing; never print `<n2>`, `<command>`, or `…` in a live batch.
+
+  The `/product-audit` line fires **only on a recurring inconsistency** — the same
+  underlying problem behind multiple issues, not any single triage.

package/skills/triage-issue/references/AUDIT_FINDINGS.md

@@ -0,0 +1,35 @@
+## Audit-finding mode (`triage-issue <audit-id> F<k> …`)
+
+When the first argument is an **audit id** (a plain integer matching a
+`docs/audits/<id>-*.md` file) followed by one or more `F<k>` finding ids, the
+input is a `product-audit` finding, not an existing issue. Detection is
+mechanical: `F`-prefixed second argument → audit-finding mode; otherwise every
+argument is an issue number, unchanged.
+
+1. **Read the audit report** `docs/audits/<id>-*.md` (exactly one file matches;
+   zero or several → stop and report the mismatch). Locate each requested
+   `F<k>` row in `## Findings` and any proposal citing it (`from: F<k>`).
+2. **Verify against current code** — same as Process step 2: the audit may be
+   stale; re-check its evidence (paths, counts, repro) before acting. An
+   already-fixed finding → verdict **wontfix** (obsolete), no issue opened.
+3. **Check for an existing issue** — `gh issue list --search "Audit <id> F<k>"`
+   plus a title match; if one exists, triage THAT issue via the normal Process
+   (never open a duplicate).
+4. **Classify** with the same four verdicts (plus `fix-in-unit` via step 3 of
+   the Process). Then:
+   - **fix-now / postpone / promote** → this is the moment the GitHub issue is
+     **opened** (the audit itself never files issues): body written with the
+     Write tool and `gh issue create --body-file`, citing provenance on its
+     first line — `Origin: product audit <id>, finding F<k>
+     (docs/audits/<id>-<date>.md)` — plus the finding's evidence, severity, and
+     class. Then apply the verdict's labels/comment/routing exactly as the
+     normal Process dictates for that verdict.
+   - **wontfix / already-fixed** → open nothing; the verdict block is the record.
+5. **Mark the finding triaged** in the audit file: append directly under the
+   `F<k>` line one indented note —
+   `↳ triaged <YYYY-MM-DD>: <verdict> — issue #<n> | no issue (<why>)` —
+   and commit with `docs(audits): triage audit <id> F<k>`. Never renumber or
+   rewrite the finding itself.
+6. **Report** the same fixed verdict block, with
+   `ISSUE #<n>` replaced by `AUDIT <id> F<k> — <finding title>` when no issue
+   ends up existing.

package/skills/triage-issue/references/FOLD_LEDGER.md

@@ -0,0 +1,32 @@
+## Ledger-append mechanism (`fix-in-unit` → fold-into-ledger sub-route)
+
+When the *fold into the unit's ledger* sub-route (step 3 above) applies,
+append one row to the open unit's `review-findings.md` — the same fold ledger
+`review-change` and `audit-pr` write to, in their **fixed 7-column schema,
+never redefined here**:
+
+```
+| id | file:line | axis | severity | class | route | folded |
+```
+
+The appended row: `folded` starts `no` (this skill never sets `folded: yes` —
+that transition belongs solely to `/fold-findings`), and the `route` cell
+carries a **provenance marker** identifying this row was born from a triage
+verdict, not a review/audit pass: `triage #<n> <YYYY-MM-DD>` (the issue number
+and today's date), e.g. `route: fold into phase — triage #86 2026-07-18`. The
+marker sits **inside the existing `route` cell** — no new column, so
+`fold-findings`, `workflow-status`, and the npm schema mirror all keep reading
+the same 7 columns unchanged.
+
+This is **not** a silent reclassification: the row's `severity`/`class`/`route`
+are set once, here, by the disposition-owning skill's own dated, evidence-
+grounded verdict — exactly the frozen-classification guarantee
+`fold-findings` already enforces on rows `review-change`/`audit-pr` write.
+`fold-findings` then processes the row like any other `folded: no` row in its
+next run — one queue, no separate lane.
+
+**`Closes #<n>` on the unit's own PR.** A `fix-in-unit` verdict never opens a
+new PR: the issue closes via the **open unit's** existing PR — its body gains
+a `Closes #<n>` line for this issue (or, if the unit's PR isn't open yet,
+whoever opens it later adds the line then). State this explicitly in the
+verdict's `Action taken:` field.

package/skills/triage-issue/references/ISSUE_PROCESS.md

@@ -0,0 +1,101 @@
+## Process
+
+1. **Parse the issue's own contract.** Extract its severity and any "When to
+   fix" / "Trigger" / "Acceptance (when triggered)" clause. Many issues carry an
+   explicit signal-based trigger — honor it.
+2. **Verify the trigger against current code.** Do the actual check, e.g.:
+   - count real consumers of a duplicated helper (is the "3rd consumer" here?),
+   - check a threshold (article count, p95 latency, row count),
+   - reproduce a reported defect, or confirm it's already fixed.
+   Use `grep`/`gh`/tests — cite the evidence (paths, counts, line refs).
+3. **Scope-membership check.** Before classifying, decide whether this issue
+   already belongs to a unit that is currently open, per this fixed checklist
+   (every item independently checkable):
+   - List candidate open units mechanically: roadmap/fix-index rows with
+     status `in-progress` or `planned`, plus any unit with an open PR
+     (`gh pr list --state open`).
+   - For each candidate, compare the issue against it: membership = ✓ the
+     issue's ask overlaps a SPEC **acceptance criterion** or a **phase task**
+     — quote **both** sides (the issue's own line and the matching SPEC/phase
+     line) before calling it a match; no quote pair means not a member.
+   - **Member of an open unit → verdict `fix-in-unit <unit>`.** Resolve the
+     issue on that unit's own branch, never as a new standalone unit. Pick
+     exactly one of these sub-routes:
+     - *repairable as-is* → **fold into the unit's** current/next phase, or
+       append a provenance-marked row to the unit's `review-findings.md` (see
+       *Ledger-append mechanism* below).
+     - *changes the unit's shape* → **incremental replan** on the same unit:
+       name the exact command — `design-feature <slug> "<instruction>"`
+       (product half, upsert) for a product-shape change, `plan-feature
+       <slug>` (re-run, engineering half) for an engineering-shape change, or
+       a user-approved, dated `## Amendments` entry per #66's mechanism (fix
+       units). Never write "replan if needed" — always name which of the
+       three applies and why.
+     - *born as an un-amended descope of an unmerged unit* →
+       **scope-bleed restore**: the route is restore-the-criterion-in-the-unit
+       (no matching `## Amendments` entry); the issue closes as
+       scope-returned, not as new work.
+   - No candidate matched → fall through to today's four-verdict
+     classification below, unchanged.
+4. **Classify** into one of:
+   - **fix-now** — defect or trigger met → route to `plan-fix` then
+     `execute-phase --fix`; add the entry to the fix index. **High severity** →
+     apply the urgency label per *Urgency label vocabulary* above (`urgent` by
+     default; `fix-next` when the call is "queue it next" rather than "maybe
+     interrupt now" — see that section's table). Non-high severity → no label.
+   - **promote-to-feature** — really new capability → route to `plan-feature`
+     (the router handles the issue path). Apply the `promoted` disposition
+     label per *Disposition label vocabulary* above.
+   - **postpone** — valid but trigger unmet → leave open; post a **dated
+     re-confirmation** comment stating what you checked and why it stays
+     deferred. Do **not** implement deferred work inline. Apply the
+     `postponed` disposition label per *Disposition label vocabulary* above.
+   - **wontfix** — obsolete or explicitly bounded by the issue → propose closing,
+     with rationale. Apply the `wontfix` disposition label per *Disposition
+     label vocabulary* above.
+5. **When the call is the user's, ask.** If the decision hinges on product/risk
+   judgment rather than evidence, present the verdict and options and let the
+   user choose before acting.
+6. **Report and keep docs coherent.** Post the decision as a dated issue comment
+   with evidence. **The comment is Markdown, not shell — never hand-escape it:**
+   backticks / `*` / `_` in the body are formatting; a `\` before them renders
+   literally (`` \`code\` `` instead of `` `code` ``). Write the comment body to
+   a file with the Write tool (plain Markdown, real backticks, zero backslashes)
+   and post it with **`gh issue comment <n> --body-file <path>`** (or the
+   declared forge's equivalent) — never an inline `--body "…"` or a quoted
+   heredoc, which mangle backticks. After posting, `gh issue view <n> --json
+   comments` must show the backticks rendering, no literal `` \` ``. On a
+   fix-now + high-severity verdict, the comment also states the urgency label
+   applied (or the failure to apply it — see *Apply-on-verdict (urgency)*
+   above); on a **postpone**, **promote**, or **wontfix** verdict, the comment
+   states the disposition label applied instead (or its failure — see
+   *Apply-on-verdict (disposition)* above). Either way this is
+   the one GitHub-state mutation this skill makes without separate
+   confirmation, because it is fully determined by the verdict just reached,
+   never by issue text. If it
+   becomes an active fix, register it in the fix index; if
+   closed, remove any stale index entry. Any **other** GitHub state mutation
+   (closing, unrelated labels) still needs confirmation when ambiguous.
+7. **Return exactly, per issue** (fixed verdict format — batch runs repeat it,
+   then add one summary table):
+
+   ```
+   ISSUE #<n> — <title>
+   Trigger (the issue's own): <quoted clause | "none stated">
+   Checked: <the exact commands/counts/repro run>
+   Evidence: <paths, counts, line refs, output>
+   VERDICT: fix-now | fix-in-unit | promote | postpone | wontfix
+   Action taken: <fix-index entry + route | dated comment posted + disposition label applied | close proposed + disposition label applied>
+   ```
+
+   No member unit matched a `fix-in-unit` candidate for this issue → the
+   verdict, evidence, and action above are exactly what they would have been
+   without the scope-membership step — today's four-verdict classification,
+   unchanged.
+
+   **Batch summary table — group by home unit.** When triaging several issues
+   in one run, the closing summary table groups every `fix-in-unit` issue
+   under its home unit's heading (one heading per unit, its member issues
+   listed beneath), with any issue that matched no open unit listed last under
+   a plain "no member unit" heading — this is the signal that surfaces N
+   issues sharing one open unit at a glance, not N separate rows.