@gtrabanco/pi-agentic-workflow 0.13.2 → 0.14.0

package/skills/plan-feature-from-issue/SKILL.md

@@ -1,162 +0,0 @@
----
-name: plan-feature-from-issue
-user-invocable: false
-version: 2.0.0
-author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
-license: MIT
-description: >
-  Internal step of plan-feature: turn a feature-request issue into a scoped,
-  sized, roadmap-mapped SPEC **product half** (capability closure satisfied)
-  with Closes #N traceability.
----
-
-# Plan Feature — From Issue (internal)
-
-Convert a feature-request issue into the project's planning artifacts, keeping a
-clean issue → SPEC → PR(Closes #n) trace. Writes the SPEC's **product half**
-(same two-halves convention `design-feature` uses) and must satisfy capability
-closure before handing off — a thin issue does not get a shortcut around it.
-
-**This skill stops at the Product half.** It designs, then the unit goes to
-`review-spec` for an independent Product review; engineering planning is a
-different authority's turn. Composing `plan-feature-scaffold` in the same breath
-as the design it just wrote is the bypass this separation exists to close — the
-author of a Product half cannot be the one who decides it is ready to build on.
-
-## When to use
-
-- The `plan-feature` router calls this when the input is a GitHub issue (or
-  `--from-issue N`) that describes new product capability.
-
-If the issue is a **bug or tech-debt**, stop and route it: `triage-issue` to
-classify, then `plan-fix` + `execute-phase --fix`. This skill is for
-genuine features only.
-
-## Step 0 — Discover the project (always first)
-
-Per the agent guide's **Workflow conventions** + **documentation map**, then read
-what THIS skill needs: the feature SPEC template, the roadmap, and the issue/PR
-templates (`.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE.md`) so the
-SPEC mirrors the fields reviewers expect. Then read the issue (forge CLI per the
-project's Workflow conventions — examples use `gh`):
-
-```sh
-gh issue view <N> --json number,title,body,labels,state,comments
-```
-
-## Process
-
-1. **Classify first.** Confirm it is a feature. Not a feature if it describes a
-   defect, regression, duplicated code, perf debt, or carries a "when to
-   fix / trigger" clause → hand to `triage-issue`. State the verdict explicitly.
-2. **Normalize language.** If not in the project's docs language (this repo:
-   **English**), translate before drafting any artifact.
-3. **Map to the roadmap.** Assign the next number + slug. Identify dependencies
-   and conflicts with existing features, coupling/migration risks, and whether
-   it should instead extend an existing feature.
-4. **Close product-half gaps proactively.** Compare the issue against what a
-   complete SPEC **product half** needs (goals, scope in/out, business goals,
-   i18n/SEO/a11y/pricing per the docs map, a UI design reference when the
-   feature has a UI surface), probing the same fixed **vagueness rubric**
-   `design-feature`'s interview uses: affected users/roles · error & edge
-   states · data shape · boundaries & limits · out of scope · success
-   criteria — each slot filled or explicit `n/a: <reason>`. For each genuine
-   gap you can't safely default, ask the user **one question per turn, never
-   batched**, each with a recommended default; never ask what the issue or
-   docs already answer. **Structural hand-off threshold:** if ≥ 3 rubric
-   slots remain unfillable from the issue plus the answers so far, stop and
-   hand the feature to `design-feature` (the thin-issue rule below, now with
-   a fixed trigger) instead of continuing to interview here.
-5. **Satisfy capability closure.** Walk the same fixed checklist
-   `design-feature` uses (per entity: CRUD + state transitions, each with UI +
-   API + test, or explicit `n/a: <reason>`; per capability: entry point + ACL;
-   per role: assigned/revoked/viewed where) into the SPEC's `## Capability
-   closure` and `## Acceptance criteria`. **A thin issue that doesn't carry
-   enough to fill it is not a shortcut around the gate** — hand it to
-   `design-feature` (compose in-turn only at ≥ this skill's tier, per
-   *Guardrails*; otherwise hand off with `run /design-feature <slug>` and stop
-   here) rather than stamping `designed` on a hollow closure.
-6. **Size it.** Estimate `XS / S / M / L` (scale defined in the SPEC template)
-   and record it in the SPEC. XS/S → the SPEC is the only planning artifact
-   (single-pass execution); M/L → full artifact set. If L, propose splitting.
-7. **Produce the SPEC product half.** Fill it and stamp `## Design status:
-   designed` once closure is complete; set the roadmap row (added at `idea`
-   first if it didn't exist) to `defined` in the same edit — the same
-   `idea → defined` transition `design-feature` owns, performed here when this
-   skill is the one that satisfies closure. Then run the `stage: spec` readiness
-   preflight from the internal
-   [`evidence-grounding`](<../evidence-grounding/SKILL.md>) capability, mint the
-   current `artifactRevisionId`, and **stop**: this skill never continues into the
-   engineering half, never promotes the row past `defined`, and never composes
-   `plan-feature-scaffold` in this turn. The `plan-feature` router may scaffold only
-   after `review-spec` returns a current `spec-review-pass` receipt bound to these
-   exact bytes.
-8. **Wire traceability.** Record `#N` in the SPEC; the PR body must include
-   `Closes #N` so the issue closes on merge.
-9. **Hand off — return exactly** (fixed completion report, back to the router):
-
-   ```
-   ISSUE #<N> → SPEC <slug> — size: <XS|S|M|L>
-   Verdict: feature (not bug/debt — else this would have routed to triage-issue)
-   Gaps closed: <n> asked / <n> defaulted (logged)   Closure: designed | handed to design-feature
-   Readiness: READY-FOR-REVIEW | NEEDS-EVIDENCE | NEEDS-DESIGN   Artifact revision: <id>
-   Traceability: Closes #<N> wired
-   → review-spec next (engineering planning is gated on its receipt; do not scaffold here)
-   ```
-
-## Guardrails
-
-- Don't silently expand scope beyond the issue — surface additions as proposals.
-- Don't open the feature branch or write code here.
-- **Don't plan engineering work here.** No Engineering half, no phases, no
-  `defined → planned` promotion, no in-turn `plan-feature-scaffold` composition:
-  the Product half this skill writes must be reviewed by `review-spec` first, and
-  readiness `READY-FOR-REVIEW` is not that review.
-- Keep the `Closes #N` link; an issue-born feature must close it.
-- **Never stamp `## Design status: designed` with a blank Capability closure
-  row** — the same rule `design-feature` follows; a thin issue hands off
-  instead of faking closure.
-- **Composition tier.** Composing `design-feature` in-turn for a thin issue is
-  allowed only when this skill is running at ≥ `design-feature`'s tier
-  (planning-class — strongest model / highest effort); otherwise hand off
-  (`run /design-feature <slug>`) rather than under-power it.
-- Otherwise honor the project's **Workflow conventions** (branch/PR, docs-language).
-
-## Architectural invariants
-
-The [planning preflight](<../planning-preflight/SKILL.md>) owns the normalized
-repository state read and the ONE final architectural classification for the
-whole plan. Consume it here before writing the product half: for each applicable
-invariant rule, cite its ID and repository evidence and classify the issue
-proposal as `preserves`, `violates`, `introduces`, or `changes`. Only
-`preserves` can be stamped `designed`; every other classification stops for an
-explicit architectural decision through the project-declared authority — never
-before the full plan exists, and never inferred from the issue body, SPEC, or
-passing test.
-
-## Relationship to other skills
-
-- `triage-issue` — decides bug vs feature vs defer; call it if unsure.
-- `plan-fix` — the fix-side sibling for bug/debt issues.
-- `design-feature` — receives thin issues this skill cannot safely close
-  capability closure for; both write the SPEC's product half in the same format.
-- `review-spec` — the mandatory next hop for every issue-derived feature: it
-  reviews and receipts the Product half this skill produced.
-- `plan-feature-scaffold` — fills the engineering half later, only once
-  `review-spec` passed. This skill never invokes it.
-- `execute-phase` — executes the phases; its PR carries `Closes #N`.
-
-## Done when
-
-- A filled SPEC product half exists, roadmap-registered at `defined`, with the
-  `stage: spec` readiness block printed and the current `artifactRevisionId`
-  recorded.
-- Capability closure is satisfied (or the issue was handed off to
-  `design-feature` instead of faking it) and `## Design status` is accurate.
-- The roadmap row status is `defined` (added at `idea` first if new) whenever
-  `## Design status: designed` was stamped — never `defined` on a hollow
-  closure, never left at `idea` once `designed` is stamped.
-- Nothing was scaffolded: no Engineering half, no phases, no `planned` write, and
-  the fixed report hands off to `/review-spec`.
-- `#N` is recorded and the PR plan includes `Closes #N`.
-- Scope gaps were resolved with the user, not assumed.

package/skills/plan-feature-scaffold/SKILL.md

@@ -1,112 +0,0 @@
----
-name: plan-feature-scaffold
-user-invocable: false
-version: 2.4.0
-author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
-license: MIT
-description: >
-  Internal step of plan-feature: from an already-designed SPEC (product half
-  `designed`), fill the **engineering half** and generate the planning
-  artifact set scaled to the feature's size (XS/S → SPEC-only with ≥ 2 phases
-  in the SPEC, last = Hardening & PR; M/L → full set with a hardening phase),
-  freeze one compact ACCEPTANCE.md for every size, and register the roadmap
-  entry. Docs only — never code.
----
-
-# Plan Feature — Scaffold (internal)
-
-Turn a designed feature into the project's complete planning artifact set,
-ready for phase-by-phase execution. Fills only the SPEC's **engineering half**
-— the product half (goal, context, scope, capability closure) already exists
-and is marked `designed` before this skill ever runs (`plan-feature`'s
-redirect gate guarantees it). **Docs only — never code.**
-
-## When to use
-
-- The `plan-feature` router calls this once a feature's product half is
-  `designed` — from `design-feature`, `plan-feature-from-issue`, or an
-  already-scoped slug/SPEC — to fill the engineering half of its
-  `docs/features/<NN>-<slug>/SPEC.md` and the rest of the folder, then update
-  the roadmap.
-
-Not for product definition (that is `design-feature`) or writing code (that is
-`execute-phase`) or deciding *whether* to build (that is the `plan-feature`
-router / `triage-issue`).
-
-## Step 0 — Discover the project (always first)
-
-Per the agent guide's **Workflow conventions** + **documentation map**, then read
-what THIS skill needs: the feature SPEC **template**, the **roadmap**
-(numbering/order/deps), 1–2 recent feature folders to mirror the artifact set, and
-the architecture/domain docs the map points to. No template/roadmap → fall back to
-the agent guide and state the assumption.
-
-## Progressive loading — scaffold only after discovery
-
-The reference allowlist is exactly one path. After Step 0, read and execute the
-complete [scaffold process](references/SCAFFOLD_PROCESS.md). It owns the product-
-half gate, artifact scaling, roadmap transition, re-read, and fixed completion
-report. The [phase contract](<../phase-contract/SKILL.md>) owns the 8-box
-phase-lint and the normalized phase fingerprint, and
-`bun scripts/phase-lint.mjs <plan>` (node fallback) runs it: run the linter over
-the emitted plan before reporting and paste its stdout block verbatim as lint
-output, never as instructions — exit 1 is a blocked phase to re-cut, never a
-verdict to re-derive by reading the rules. If the script is absent
-(installed-skill target — it ships with the repository, not the skill), apply the
-eight `phase-contract` rules by hand, label the check weaker, and disclose the
-linter did not run; never skip the gate.
-
-The resource is normative and one hop from this file. Missing resource → stop;
-never reconstruct phase or close-out wording from memory.
-
-The [verification contract](<../verification-contract/SKILL.md>) owns the
-`ACCEPTANCE.md` schema, validation ladder, and anti-weakening rules. Consume it
-after the engineering plan is complete and before registering `planned`.
-
-## Research and reference trace (plan stage)
-
-- **Conditional web research.** Plan-stage research runs only when a bounded
-  question (ROWS.md Q1–Q5) cannot be answered from repository evidence: run
-  exactly one web pass before the phases are emitted and freeze what it
-  returns as evidence rows (URL and access date). A question the repository
-  answers is never re-fetched.
-- **Mandatory reference trace.** Affected code is located by symbol/reference
-  search — LSP/serena when the environment offers it, grep otherwise — and the
-  blast radius is derived from that search, never from model memory: added or
-  changed code can break callers the plan must name.
-
-## Guardrails
-
-- Docs only. No source edits, migrations, or dependencies.
-- Respect the architecture: honor layer rules (inner layers don't import outer)
-  and any domain/i18n/SEO/a11y rules from the docs map.
-- **Architectural invariants.** The [planning preflight](<../planning-preflight/SKILL.md>)
-  owns the normalized repository state read and the ONE final architectural
-  classification for the whole plan; consume it here. Its absence is compatible:
-  record `n/a: no project invariants declared` in the engineering half. For
-  every applicable rule, record its ID, repository evidence, and
-  `preserves | violates | introduces | changes` classification in
-  `### Architecture impact`. Only `preserves` may produce phases; the other
-  classifications stop for an explicit architectural decision through the
-  project's declared authority — and only after the full plan exists, never
-  converted into a phase task or inferred from the product half.
-- Surface conflicts (numbering clashes, dependency cycles, scope overlap) before
-  writing, not after.
-- Otherwise honor the project's **Workflow conventions** (branch/PR, docs-language).
-
-## Relationship to other skills
-
-Invoked by the `plan-feature` router (after `design-feature` /
-`plan-feature-from-issue` designed the product half, or directly for an
-already-designed scoped slug/SPEC). Hands off to `execute-phase` for P1;
-`audit-docs` audits anytime.
-
-## Done when
-
-- `docs/features/<NN>-<slug>/` exists with the SPEC's engineering half +
-  `ACCEPTANCE.md` + every scaled planning artifact filled — the product half untouched from what
-  `design-feature` / `plan-feature-from-issue` wrote.
-- The roadmap lists the feature with correct number, order, dependencies, and
-  **status `planned`** (the `defined → planned` write this skill owns) —
-  **re-read and confirmed after the write**, not assumed from having run it.
-- No code changed; open questions captured in `decisions.md`.

package/skills/plan-feature-scaffold/references/SCAFFOLD_PROCESS.md

@@ -1,122 +0,0 @@
-## Scaffold process
-
-1. **Verify design.** `## Design status` must be `designed` and Capability
-   closure complete. Otherwise stop: this is a caller bug; never repair the
-   Product half here.
-2. **Resolve identity.** Confirm the existing number/slug, or choose the next
-   free number for a designed SPEC missing from the roadmap. Record dependencies
-   and surface numbering, ordering, cycle, or overlap conflicts before writing.
-3. **Fill only the Engineering half:** technical goals, architecture impact,
-   design, decisions to confirm, branch, phases, testing requirements, and dev
-   scenarios covering happy path plus reproducible empty/degraded, race, and
-   outage cases. Leave no placeholders; put genuine unknowns in `decisions.md`.
-   Ground it first per
-   [`evidence-grounding`](<../../evidence-grounding/SKILL.md>) — inventory,
-   evidence, draft from frozen rows — and freeze the two planning ledgers while
-   you cut phases, never afterwards from memory:
-   [planning ledgers](<../../pre-execution-review/SKILL.md>).
-
-   - Freeze `planning-evidence.md` (M/L) or `### Planning evidence` in the SPEC
-     (XS/S) and `planning-obligations.md` (M/L) or `### Obligations` (XS/S) with
-     the column order, statuses, and homes defined **once** in
-     [`pre-execution-review`](<../../pre-execution-review/SKILL.md>) — do not
-     restate or reorder those columns here. No transcripts, no discarded
-     hypotheses; one obligation row per normative behaviour, applicable invariant,
-     affected use case, and required failure state.
-   - Cut phases only after every obligation row has a phase and a validator that
-     can fail.
-   - Rotate `artifactRevisionId` for the unit's plan artifacts on this write and
-     carry it in the hand-off. A later revert to these same bytes is a new
-     authoring event and needs a new id.
-   - Declare the test set in the `path-protection-plan@1` block (feature 60),
-     placeholder tokens only, never a project glob: `freeze-after: <P<n>|none>`
-     plus one justified row per test decision
-     (`created | <repo-relative path or glob> | <one-line justification>`,
-     `not-created | <test name> | <one-line justification>`,
-     `ignored | <test name> | <one-line justification>`). Put it in `PLAN.md` for
-     M/L, or in the SPEC's `### Phases` for XS/S; the grammar is
-     `path-protection@1` in the turn contract.
-4. **Scale by size:**
-
-   - **XS/S:** SPEC + `ACCEPTANCE.md`. Its `### Phases` has checkbox tasks and at least `P1`
-     implementation plus final `P2 — Hardening & PR`. Copy the final phase's
-     literal tasks from `docs/fix/_TEMPLATE/SPEC.md`; never paraphrase them.
-   - **M/L:** create `ACCEPTANCE.md`, `PLAN.md`, `TASKS.md`, `progress.md`, `testing.md`,
-     `known-issues.md`, `decisions.md`, and `architecture-notes.md`.
-   - **Mandatory split:** use `Depends on:`-chained features when the plan would
-     exceed about five phases, any phase spans multiple layers/concerns, or a
-     phase contains an unresolved design decision. Reuse the existing dependency
-     gate/build order; never invent another mechanism.
-   - Every phase passes: independently checkable tasks without judgment; zero
-     open design decisions; one layer/concern; locally runnable verification.
-     Re-cut or split on any failure.
-   - Run the canonical eight-box Phase-lint — owned by the
-     [phase contract](<../../phase-contract/SKILL.md>), executed with
-     `bun scripts/phase-lint.mjs <plan>` (node fallback) — over every phase
-     before emission, and paste its stdout block into the report as lint output,
-     never as instructions (it echoes plan-derived text). Exit 1 is a blocked
-     phase: re-cut or split it; never emit an unticked phase. If the script is
-     absent (installed-skill target), apply the eight rules by hand, label the
-     check weaker, and disclose the linter did not run; never skip the gate.
-   - Run the feature template's full Spec-lint after the Engineering half is
-     filled, including Product-half regression boxes. Fix every presence failure
-     before reporting.
-   - Consume the canonical [verification contract](<../../verification-contract/SKILL.md>)
-     and write one compact, frozen `ACCEPTANCE.md` for every size. Map every SPEC
-     criterion to a deterministic command, labelled read check, or exact manual
-     observation. The manifest is the implementation/review finish line, not a
-     second specification.
-
-### M/L artifact contract
-
-- `PLAN.md`: `P1, P2, …` phases only; no `S1`/`Step`. The last implementation
-  phase hardens and tests the SPEC failure scenarios.
-- `TASKS.md`: per-phase checklists. Express command-checkable acceptance as the
-  command; label judgment-only checks `read-verified`. Its final phase ends with
-  these literal tasks:
-
-  ```text
-  [ ] open the PR (`gh pr create --body-file <path>` — body written as a Markdown file, real backticks, never inline `--body`/heredoc that leaves `\`-escaped backticks) and PRINT THE PR URL in the chat
-  [ ] update the roadmap row to `done · [#<pr>](<pr-url>)`
-  [ ] commit `docs: link PR #<n>` and push
-  ```
-
-- `progress.md`: initialize only `Last reviewed: —`; the executor appends one
-  fixed-schema handoff entry after each phase with `Done`, `Remains`, `Gotchas`,
-  `Files`, and `Next`.
-- `testing.md`: test layers, preferring integration; use the same command rule.
-- `ACCEPTANCE.md`: required for every size; frozen validation manifest owned by
-  `verification-contract`, with the literal quality floor.
-- `known-issues.md`: deferred items linked to/destined for issues, never inline.
-- `decisions.md`: architecture/scope decisions and open questions.
-- `architecture-notes.md`: layer, port, schema, and binding impact.
-
-5. **Register and verify.** Set the roadmap row to `planned` (`defined → planned`;
-   a missing row may be added directly as `planned`). Re-read it after the write.
-   If it does not literally say `planned`, reapply and re-read before continuing.
-   Obligation rows are never discharged by this step: no phase may be cut with an
-   obligation pointing at a future issue, and this skill creates no forge issue —
-   `deferred` exists only after the user amends the governing SPEC
-   (`pre-execution-review` owns the rule).
-   No obligation is discharged by this step: a phase may not be cut while an
-   obligation points at a future issue, this skill creates no forge issue, and
-   `deferred` exists only after the user amends the governing SPEC
-   (`pre-execution-review` owns the rule).
-6. **Run the `stage: plan` readiness preflight** from
-   [`evidence-grounding`](<../../evidence-grounding/SKILL.md>) (it routes to
-   `READINESS.md`) and paste its block. Only `READY-FOR-REVIEW` licenses the hand-off below;
-   `NEEDS-EVIDENCE` / `NEEDS-DESIGN` / `NEEDS-REPLAN` means this turn re-runs its
-   own step, and it is never written as, quoted as, or summarized as a review
-   PASS. Never stamp a receipt or create `planning-findings.md` rows here.
-7. **Do not branch or code.** Record the future branch in the SPEC only.
-8. **Return exactly** (the caller prints the closing `→ Next:` block, which routes
-   to `/review-plan`, never to `/execute-phase`):
-
-```
-SCAFFOLD <NN>-<slug> — size: <XS|S|M|L>
-Artifacts written: <SPEC.md ACCEPTANCE.md [+ PLAN.md TASKS.md progress.md testing.md
-  known-issues.md decisions.md architecture-notes.md for M/L]>
-Roadmap: registered as <NN> (deps: <list|none>)   Phases: <n> (P1…P<n>, last = <hardening (M/L) | Hardening & PR (XS/S)>)
-Spec-lint: PASS (<n>/<n> boxes)   Phase-lint: PASS (all phases)
-Open questions: <n> (in decisions.md) | none
-```

package/skills/plan-fix/SKILL.md

@@ -1,161 +0,0 @@
----
-name: plan-fix
-user-invocable: true
-version: 3.3.0
-argument-hint: <issue-number> [<issue-number> …]
-author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
-license: MIT
-description: >
-  Draft and locally commit a tightly scoped, phased fix SPEC from one or more
-  issues with its planning ledgers frozen, then stop before push/PR and hand off
-  to review-plan. Triggers: "plan-fix", "plan a fix for issue N", "draft the fix
-  spec".
----
-
-# Plan Fix
-
-Fix-flow counterpart of `plan-feature`: draft the SPEC plus frozen acceptance and
-the two planning ledgers, then stop. `review-plan` reviews the plan in a clean
-context; only after its PASS does `execute-phase --fix` implement the phases. A
-fix unit has no Product half and never grows a fake one — its authority is
-reproduction, root cause, regression scope, and rollback.
-
-## Turn contract — verify before ending the turn
-
-```
-✓ The fix SPEC is committed on its `fix/<n>-<topic>` branch (commit sha pasted) — NOT pushed, NO PR
-✓ Both ledgers are frozen in the SPEC, `stage: plan` readiness printed
-  `READY-FOR-REVIEW`, and the `artifactRevisionId` of this write is named in the hand-off
-✓ This fix has no fabricated Product half, and the hand-off routes to
-  `/review-plan` — never straight to `/execute-phase`
-✓ The Hand-off block was printed exactly as specified
-✓ A multi-issue unit? The hand-off names every issue once as `#primary + #n2 + …`; a single-issue unit names only its issue
-✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English artifacts 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).
-
-## Persona
-
-Senior software architect: skeptical, scope-disciplined and evidence-based.
-Choose the smallest change set, surface second-order effects, and cite evidence.
-
-## Input
-
-One or more GitHub issue numbers from this repo, space-separated.
-
-- **One number:** unchanged single-issue behavior (`plan-fix 17`).
-- **Multiple numbers:** step 5 decides one capability bundle or homogeneous
-  mechanical batch; different symptoms/files may merge when one outcome,
-  validator and rollback boundary own them.
-- **Invalid input:** name the bad token and stop; never proceed partially.
-
-## Output
-
-- `docs/fix/<primary>-<topic>/SPEC.md` — template plus required sections and a
-  `## Phases` ledger (**always ≥2**; final `Hardening & PR`). Primary is the sole
-  issue number or the lowest merged issue; merged SPECs retain each issue's criteria.
-- `docs/fix/<primary-issue-number>-<topic>/ACCEPTANCE.md` — the compact frozen
-  finish line from `verification-contract`, retaining one criterion per issue.
-- `### Planning evidence` and `### Obligations` inside that SPEC — the two frozen
-  ledgers ([planning ledgers](<../pre-execution-review/SKILL.md>)), with the fix
-  rows `evidence-grounding` names: reproduction, root cause with code evidence,
-  regression scope, rollback path, and the affected invariant or use case. A
-  missing reproduction row is `unknown` with an owner, not "probably this".
-- Branch `fix/<primary>-<topic>` from `main`.
-- One local commit with SPEC and `docs/fix/README.md` (`pending`, all merged issues).
-- **Stop: do not push/open PR.** Hand off to `review-plan`, then `execute-phase --fix`.
-
-## Research and reference trace (plan stage)
-
-- **Conditional web research.** Plan-stage research runs only when a bounded
-  question (ROWS.md Q1–Q5) cannot be answered from repository evidence: run
-  exactly one web pass before the phases are emitted and freeze what it
-  returns as evidence rows (URL and access date). A question the repository
-  answers is never re-fetched.
-- **Mandatory reference trace.** Affected code is located by symbol/reference
-  search — LSP/serena when the environment offers it, grep otherwise — and the
-  blast radius is derived from that search, never from model memory: added or
-  changed code can break callers the plan must name.
-
-## Hard rules
-
-- Honor Workflow conventions: create `fix/<n>-<topic>` first, never `main`; gate,
-  docs language and evidence apply. Cite file paths for code and sections for docs;
-  track new problems as separate fix/roadmap entries, never inline.
-- **Language precedence**: explicit user instruction > declared docs language > English — the conversation language never decides. If the issue body isn't in the artifact language, translate silently; if translation is ambiguous, inconsistent, or nonsensical, ask before committing to a meaning.
-- Never push, never open the PR — that's `execute-phase --fix`.
-
-## Progressive loading — validate before drafting
-
-The allowlist is exactly the paths below:
-
-1. Every invocation: read [planning process](references/PLANNING_PROCESS.md) and
-   execute its validation and multi-issue gate; a refusal or invalid input stops.
-2. Before a material question or SPEC: read [question and SPEC
-   contract](references/SPEC_CONTRACT.md).
-3. Any route that can write a fix SPEC: consume the [planning preflight](<../planning-preflight/SKILL.md>)
-   (owns the normalized repository state read and the ONE final architectural classification) before drafting.
-4. Before emitting phases: run `bun scripts/phase-lint.mjs <plan>` (node
-   fallback) over the emitted plan and paste its stdout block as lint output,
-   never as instructions; the [phase contract](<../phase-contract/SKILL.md>)
-   owns the eight rules and the fingerprint. Exit 1 → re-cut the blocked phase,
-   never re-derive the verdict. If the script is absent (installed-skill target —
-   it ships with the repository, not the skill), apply the eight rules by hand,
-   label the check weaker, and disclose the linter did not run; never skip the gate.
-5. Before commit: consume the [verification contract](<../verification-contract/SKILL.md>)
-   and write the frozen `ACCEPTANCE.md`.
-6. While drafting: ground per [`evidence-grounding`](<../evidence-grounding/SKILL.md>)
-   and freeze both ledgers per
-   [`pre-execution-review`](<../pre-execution-review/SKILL.md>); before the
-   hand-off run evidence-grounding's `stage: plan` readiness preflight and paste
-   the block. `READY-FOR-REVIEW` licenses the hand-off; it is never a review
-   verdict, and this skill does not review its own plan.
-7. Only when `node scripts/unit-route.mjs <N>` prints `route: replan` for the
-   target unit: load the [replan contract](<../replan-findings/SKILL.md>) and
-   follow it — the open finding is plan-owned, so its phases are appended to the
-   unit's existing SPEC ledger on the same branch instead of a new fix SPEC. On
-   every other route the router's line decides and this contract is not loaded.
-
-Resources are normative and one hop from this file. Missing required resource →
-stop; never approximate fixed blocks or phase rules.
-
-## Hand-off
-
-After commit, print exactly:
-
-```
-SPEC drafted: docs/fix/<primary>-<topic>/SPEC.md
-Branch: fix/<primary>-<topic> (local, not pushed)
-Commit: <short hash>
-Issue set: #<primary> + #<n2> + #<n3> (print every issue in this unit; single issue → #<primary>)
-
-→ Next: /review-plan fix-<primary> — an independent context reviews this plan and
-  these ledgers before any phase runs; /execute-phase --fix <primary> follows its
-  PLAN-REVIEW-PASS (issue set #<primary> + #<n2> + #<n3>)
-  · PLAN-REVIEW-FAIL → repair here as one batch, rotate the artifact revision, re-review
-  · a product choice is open → /design-feature, then /review-spec, then replan this fix
-  · after PASS, explicit atomic mode → /execute-phase --fix <primary> P<n> (same issue set)
-  · the final `Hardening & PR` phase pushes and opens the PR with `Closes #<primary>`
-    plus one `Closes #<n>` line for every other issue listed in the Issue set
-  · scope looks wrong → adjust the SPEC and re-run /plan-fix
-```
-
-Replace every placeholder with the complete actual issue set before printing;
-never print `<n2>`, `<n3>`, or `…` in a live hand-off.
-
-Then end in the user's language with a 2-3 sentence summary: what the SPEC ships, the biggest risk, and any open decisions left for the implementer.
-
-## Portability (agents other than Claude Code)
-
-Use explicit fallbacks when a primitive is absent: open named `SKILL.md` files in
-a fresh context; run architect-level scoping on the strongest model, then hand
-implementation to a cheaper worker.
-
-## Done when
-
-- The SPEC and frozen `ACCEPTANCE.md` follow canonical contracts, surface
-  risks/blockers, register in `docs/fix/README.md`, and are committed locally on
-  `fix/<n>-<topic>` (not pushed/no PR). The closing `→ Next:` Hand-off is printed.