@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/execute-phase/references/BATCH_AND_PORTABILITY.md

@@ -0,0 +1,54 @@
+## Whole-unit execution and portability
+
+The normal omitted-phase command is already the batch:
+
+```text
+/execute-phase <NN>
+/execute-phase --fix <n>
+```
+
+It selects every unfinished phase, gates and commits each one, skips
+intermediate review stops, opens the PR, then recommends
+`/loop-review-fold`. An explicit `P<n>` keeps the atomic/manual path.
+
+### Fresh-context driver (recommended for cheap models)
+
+When the host has subagents or headless invocation, the unit-loop conductor
+uses one fresh worker per phase and carries only `ACCEPTANCE.md`, the phase task
+slice, and compact receipts. An external driver may implement the same contract:
+
+1. Call `workflow-status` and choose the next unfinished phase.
+2. Invoke `/execute-phase <unit> P<n>` on the cheap tool-capable tier.
+3. Repeat `CONTINUE`; route `READY_FOR_REVIEW` to `/loop-review-fold` on the
+   required review/fold tiers.
+4. Stop on `NEEDS_INPUT`, `HALT`, repeated unchanged evidence, or the declared
+   attempt budget.
+
+The protocol and envelope repair loop live in
+`docs/workflow/ORCHESTRATION.md`. The user still starts one driver run; fresh
+contexts are an implementation detail.
+
+### Inline fallback
+
+A host without fresh-worker primitives executes the same queue inline. After
+each phase it reduces state to `progress.md`'s unit-loop receipt and never
+re-reads prior raw context. This is less context-efficient but behaviorally
+equivalent. A user who wants maximum control may pass explicit phases manually.
+
+### Model routing
+
+- Planning and acceptance freezing use the strongest available model.
+- Mechanical phase execution may use a cheaper tool-capable model.
+- Review is never weaker than the writer and should use a different family
+  where practical.
+- A subtle security/logic fold uses the strongest required tier even when
+  surrounding mechanical folds are cheap.
+- Cap parallel workers below the provider's concurrency limit; on 429 reduce
+  fan-out rather than retrying at the same concurrency.
+
+### Missing platform features
+
+- No slash menu → open the named `SKILL.md` and follow it literally.
+- No model tiers → select tiers manually using the rules above.
+- No subagents/headless runs → use the inline fallback.
+- No external driver → the built-in omitted-phase loop remains available.

package/skills/execute-phase/references/CLOSEOUT.md

@@ -0,0 +1,74 @@
+## Implementation guidance (single-pass & per-phase)
+
+**Tests first where they pay.** For core/domain and orchestration phases, write
+the phase's acceptance/integration tests first (red), then implement to green —
+the SPEC's dev scenarios are the test list, so its failure modes get exercised,
+not just documented. UI and adapter glue may test after implementation.
+
+Map each change to the project's layers per its architecture doc; build inner layers first, outer last:
+
+1. **Persistence/schema** (if any) — update where defined, generate migrations with the project's tooling, never hand-edit generated output.
+2. **Core/domain** — no outer-layer imports; use the project's value objects/rules.
+3. **Orchestration/use-case** — inject dependencies, idempotent if re-callable, typed errors.
+4. **Adapters** — implement the project's ports; never leak raw external errors inward.
+5. **Controller/endpoint** — map errors to responses; webhooks: verify signature, enqueue, return fast.
+6. **UI** (if any) — follow the design-system/i18n/accessibility docs; no hardcoded strings.
+7. **Tests** — whatever wasn't written first (see above): light mocks of the project's interfaces; test orchestration, not adapters.
+
+## Completion checklist (single-pass)
+
+Write `docs/features/<NN>-<slug>/CHECKLIST.md`: schema migration applied (if any) · core layer has no outer imports · orchestration idempotent + typed errors · adapters implement ports · tests pass · type-check/lint green · UI strings localized (if UI) · domain value-object rules respected · user-facing limitations disclosed · new deps pinned. Note any decisions not captured in the SPEC.
+
+## Review checkpoint & finishing a unit
+
+**Independent final review is mandatory — every unit gets one before merge.**
+Recommend `loop-review-fold` because it preserves fresh review contexts while
+handling bounded corrections; direct `review-change` is the manual path. Review
+runs in its own turn (hand-off, not composed): a skill's model and
+effort are fixed at turn start, so invoking `review-change` from here would run it at
+execute-phase's `sonnet`/`medium` rather than its own `opus`/`high` — under-powering
+the review. So **suggest** it; don't compose it. (General rule: across a model/effort
+boundary, hand off; don't compose.) On agents without per-skill model config the same
+rule holds by hand: run the review as a **separate, fresh invocation** on your
+strongest model — never inline in the implementation run.
+
+**Cadence.** Explicit-phase feature mode: after each completed phase, the closing block
+**recommends** the hand-off whenever a *Review checkpoint trigger* fires
+(layer boundary, accumulation, or sensitivity — see above), naming which one —
+a suggestion the user may skip to keep executing phases. Whole-unit mode records
+triggers and continues without intermediate hand-offs; the skill never blocks
+on an intermediate review. What is **never optional** is the end: every
+unit gets one `review-change` pass before merge (single-pass and `--fix`
+included — they have no intermediate phases, so the end review is their only
+one).
+
+**Finishing a unit (single-pass, `--fix`, or a feature's final phase): the last step
+is always an open PR.** Mark the unit `done`, commit the flip, push, and `gh pr create`
+(see the mode steps above) — regardless of the review/audit still to come. Then hand
+off to `/loop-review-fold` (recommended) or direct `/review-change`, which feeds
+`audit-pr` (the merge gate).
+
+**Adversarial pass at that mandatory end review.** `review-change` evaluates its
+own recommendation checklist there (`L`/sensitive change, reviewer not the
+fleet's strongest or weaker than the author, or a single model family on a
+`≥M` change) and — only when a box fires — recommends `--adversarial N`
+(N=2 default, N=3 on a security/auth surface or a single-family fleet) instead
+of its default single-reviewer pass. This is evaluated once, at that mandatory
+end review; it does not change the trigger-based checkpoint cadence above.
+
+Checkpoint hand-off (print it — every invocation ends by suggesting the next
+step; when a trigger fires, the review is the recommendation, continuing is a
+listed alternative — the user picks):
+
+```
+Phase <N> done and committed. Review checkpoint (recommended) — <trigger name> fired: <one-line reason>.
+→ Next: /review-change — it reviews the branch at its own model/effort
+  · skip the checkpoint → /execute-phase <NN> <next phase> (the mandatory end review still covers everything)
+  · findings (if you review) → fold fix-now into the branch; independent work stays a proposal until user triage; then re-review
+```
+
+`<trigger name>` is one of `layer boundary`, `accumulation`, or `sensitivity`
+(see *Review checkpoint triggers*); `<one-line reason>` cites the evidence
+(e.g. "next phase declares `api`, this one was `domain`", "612 lines / 11
+files since `a1b2c3d`", "phase touched auth middleware"). No trigger fired?
+Omit the checkpoint line entirely and go straight to naming the next phase.

package/skills/execute-phase/references/DESCOPE.md

@@ -0,0 +1,35 @@
+## Descope guard (run before creating any issue during this unit)
+
+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. Before creating **any** issue while executing this unit, classify it
+with the fixed **descope test**:
+
+- **Descope** — the issue's content overlaps a SPEC acceptance criterion or a
+  phase task that is **not fully delivered** in this unit.
+- **Discovered work** — everything else (genuinely new, outside the SPEC's
+  promises) — record it as a proposal; only explicit user triage may file it.
+
+**On a descope → STOP before creating the issue.** An issue may never be the
+first record of a descope. The descope must first be recorded as an explicit,
+**user-approved, dated SPEC amendment**:
+
+1. Get explicit user approval for the descope **first** (ask; never
+   self-authorize moving a criterion out of scope — the amendment row must
+   never be written before approval is in hand).
+2. **Only then** move the criterion/task out of the active `## Acceptance` (or
+   `## Phases` ledger), and log it in the governing SPEC's `## Amendments`
+   section (create the section if absent) with this canonical row format:
+   ```
+   - <YYYY-MM-DD> — descoped: "<criterion/task>" — approved by user — follow-up: #<n>
+   ```
+3. **Only when the user explicitly requests backlog creation**, create the
+   follow-up issue and **link the amendment** in its
+   body. Immediately after, edit the `## Amendments` row to replace the
+   `#<n>` placeholder with the real issue number, and commit that edit — a
+   row still reading the literal `#<n>` placeholder is unlinked and fails
+   `audit-pr`'s symmetric check.
+
+`audit-pr`'s scope-bleed gate and `product-audit`'s recurrence signal both key
+off this same `## Amendments` log — it is the single authoritative record of
+every descope, defined once here.

package/skills/execute-phase/references/EXECUTION_CONTRACT.md

@@ -0,0 +1,147 @@
+## Review checkpoint triggers (feature mode)
+
+The recommended, skippable checkpoint fires on **what accumulated since the
+last checkpoint**, not on a phase count — a phase-counter cadence re-miscalibrates
+whenever phase size changes (see `#77`). After each phase commit, check all
+three; recommend the checkpoint (naming which trigger fired) the moment any
+one does:
+
+1. **Layer boundary** — the phase about to start declares a different
+   `Layer:` (the phase-lint enum) than the phase just committed. The just-closed
+   layer is a coherent reviewable unit.
+2. **Accumulation** — the unreviewed diff since the last-reviewed marker
+   exceeds **> 400 changed lines (insertions + deletions) OR > 8 changed
+   files**, measured with `git diff --stat <baseline>..HEAD`. Covers a long run
+   of small same-layer phases the layer-boundary trigger would miss.
+3. **Sensitivity** — the phase just committed touches auth, payments,
+   destructive migrations, secrets, or CI config → recommend an **immediate**
+   checkpoint on closing it, regardless of the other two triggers. This is a
+   **single-reviewer** recommendation and does not change `review-change`'s
+   own once-per-unit adversarial cadence (`skills/review-change/SKILL.md`
+   "Cadence — once per unit") — the two are independent mechanisms.
+
+**Last-reviewed marker.** Home: `progress.md`'s header line
+`Last reviewed: <sha>`. Sole writer: `execute-phase` — stamped with the
+just-committed phase's sha immediately after a checkpoint is taken (review
+happens in a separate turn, so this skill records the marker at the start of
+the *next* phase it executes, using the sha the user confirmed was reviewed).
+If the marker is absent (unit's first checkpoint, or a legacy `progress.md`
+predating this rule), the baseline is `git merge-base <default-branch> HEAD` —
+never treat a missing marker as a blocker or crash condition.
+
+## Allowed & forbidden (fixed lists — no interpretation)
+
+**Allowed changes in a phase:**
+- The phase's own tasks (from `TASKS.md`, or the SPEC for single-pass/fix)
+- Tests for the behavior this phase adds or alters
+- The per-phase doc updates listed in the completion gate below
+- The smallest refactor strictly required to land a task (state why in the commit)
+- An `Autofix` or `Opportunistic Fix` that passes every box in the
+  *Opportunistic finding policy* below
+
+**Forbidden — never, even if it "would help":**
+- New abstractions beyond what the SPEC names (an interface with one
+  implementation is a violation)
+- New dependencies not justified in the SPEC
+- Public API / contract changes the SPEC doesn't name
+- Architecture changes (layers, boundaries, patterns)
+- Refactoring unrelated code
+- Building future phases or features early
+- Folding a discovered finding into the branch before it passes the
+  *Opportunistic finding policy*
+- Creating an issue that descopes a SPEC acceptance criterion or phase task
+  without a user-approved, dated `## Amendments` entry (see *Descope guard*
+  under *Issue policy* below) — an issue may never be the first record of a
+  descope
+
+Something forbidden looks necessary → stop, record it in `decisions.md` or
+`known-issues.md`, and surface it — never do it silently.
+
+## Phase completion gate — pass only if (every box, every phase)
+
+```
+✓ Verification gate green — type-check + tests + build actually RUN (paste exit
+  status), never assumed
+✓ Every task of this phase checked off in TASKS.md, each mapped to evidence
+  (code path or test name)
+✓ Tests updated/added for every behavior this phase changed
+✓ No TODO/FIXME/HACK markers left in the diff
+✓ No duplicated logic (reuse the existing helper — cite it if one existed)
+✓ No dead code introduced (unused imports, functions, unreachable branches)
+✓ No hidden breaking change (changed public contracts diffed against their
+  consumers)
+✓ Architecture doc respected (dependency directions, layer boundaries)
+✓ Architectural invariants preserved or backed by an explicit recorded decision
+✓ Docs updated — at minimum verify each of: TASKS.md (checkboxes),
+  progress.md (one handoff entry in the fixed schema — Done / Remains /
+  Gotchas / Files / Next), testing.md, known-issues.md, decisions.md (if any
+  decision was taken), SPEC.md (only if scope/acceptance changed — with the
+  change logged), docs/CAPABILITIES.md (only if this phase introduced a new
+  cross-cutting subsystem, role, or permission — append the row, additive,
+  never rewrite existing ones; explicitly n/a when the project has no
+  inventory file)
+✓ Docs COMMITTED with the phase — after the phase commit,
+  `git status --porcelain -- docs/` returns nothing. Doc updates ride the
+  phase commit (same `git add`), never sit uncommitted "for later"
+```
+
+A phase that cannot tick every box is **not done**: fix within the phase's
+scope, or record the blocker in `known-issues.md`, leave the work uncommitted,
+and stop with a clear report. Never commit red; never tick a box you didn't
+verify.
+
+## Branch
+
+| Mode | Format |
+|------|--------|
+| feature / single-pass | `feat/<NN>-<slug>` |
+| `--fix` | `fix/<issue-number>-<topic>` |
+
+Read the SPEC's `Branch` field; create with `git switch -c <name>`. If absent/ambiguous, ask. Never commit, amend, or force-push on `main`.
+
+**Honor the project's declared Git workflow** (Workflow conventions — `branches`
+or `worktrees`). Default and assumption everywhere: **`branches`** — one active
+unit at a time, sequential, plain `git switch -c`; **never create a worktree**.
+Only when the project explicitly declares `worktrees` may a unit get its own
+checkout — and then one worktree per unit, removed after merge.
+
+## Normalized Repository State
+
+When present, consume frozen facts and decisions in
+`docs/workflow/REPOSITORY_STATE.md`. Inspect directly only for an absent fact;
+route contradictory evidence to `resolve-repository-state`. Documentation,
+planned work, and inference never prove implementation. A present ledger whose
+status is `draft`, `contradicted`, or `resolved` stops implementation and routes
+to discovery or resolution first. If no ledger exists, inspect the repository
+directly and record `n/a: no normalized repository state`; NRS is optional.
+
+## Architectural invariants
+
+Before any edit, discover the optional project invariant document declared in
+the documentation map (normally
+`docs/architecture/ARCHITECTURAL_INVARIANTS.md`). If absent, record
+`n/a: no project invariants declared` and continue. For every applicable rule,
+cite its ID and repository evidence and classify the phase as `preserves`,
+`violates`, `introduces`, or `changes`. Use frozen NRS facts when present, but
+the repository remains authoritative and conflicting evidence routes to the
+resolver.
+
+Only `preserves` may continue. A `violates`, `introduces`, or `changes` result
+stops before edits and requires an explicit architectural decision through the
+project's declared authority. A decision record alone is not sufficient: the
+declared authority must apply the decision to the invariant document, and the
+resulting rule must be re-evaluated and evidenced as `preserves` before the
+phase can resume. The executor does not edit the invariant document itself.
+Do not alter the SPEC or tests to make the phase pass, and do not convert the
+decision into phase work. Return exactly:
+
+```
+ARCHITECTURAL INVARIANT GATE — <NN|fix n> <P<k>|single-pass> BLOCKED
+Invariant: <ID> — <violates|introduces|changes>
+Evidence: <repository path:line or command result>
+Decision required: <project-declared architectural authority>
+
+→ Next: <decision path> — record the explicit architectural decision, then re-run this phase
+  · evidence conflict → /resolve-repository-state — reconcile the frozen fact first
+  · no invariant document → record n/a and continue only when no other rule applies
+```

package/skills/execute-phase/references/FOLDING.md

@@ -0,0 +1,73 @@
+### Folding review / audit findings (a first-class mini-cycle)
+
+**`/fold-findings` is the standalone skill for this cycle** — it carries the
+full frozen-classification rule and forbidden list (no known-issues dump, no
+severity downgrade, no test loosening, no suppression-as-fix) as a fixed,
+independently-invocable contract; prefer it as a fresh hand-off (its own
+turn, its own model/effort) whenever one is available. The checklist below is
+the in-context / portability fallback for folding inline within this skill's
+own turn (e.g. no slash-command menu, or an agent that folds without leaving
+its current context).
+
+When `review-change` findings (fix-now) or `audit-pr` blockers are folded back
+into a branch that already has an open PR, the fold is complete **only** when
+every step below ran — fixing the code and stopping is the classic way findings
+end up "solved" locally but absent from the merged PR:
+
+```
+✓ Fixes implemented (scope: only the routed findings — nothing extra)
+✓ Gate RUN and green (exit codes pasted)
+✓ Per-phase / unit docs updated where the finding touched them
+  (known-issues.md entry resolved? progress.md notes the fold)
+✓ Each folded finding's row in the unit's `review-findings.md` ledger (if one
+  exists — the ledger is optional; a unit with no fix-now findings has none)
+  flipped `folded: no → yes` — the one and only ledger state transition, owned
+  solely by this fold cycle
+✓ `git add` + `git commit` RUN (sha pasted) — e.g.
+  `fix(<scope>): fold review findings — <summary>`
+✓ `git push` RUN (PR is open → every commit pushes immediately)
+✓ `git status --porcelain` RUN → empty; `git status -sb` → not ahead of remote
+```
+
+Then hand back to the gate that sent you (`/review-change` re-review, or
+`/audit-pr` re-audit). Never report findings as resolved while any box is
+unchecked — an unpushed fix does not exist for CI, the reviewer, or the merge.
+
+Final-phase / single-pass / fix hand-off:
+
+```
+<unit> implemented, gate green, marked done.
+PR opened: <FULL PR URL — always printed here; not every agent shows open PRs>
+Roadmap/fix-index row: done · #<n> (linked and pushed)
+→ Next: /loop-review-fold <unit> (recommended review/fold router; unresolved findings go to triage/replan)
+  · manual path → /review-change
+  · clean    → /audit-pr (merge gate) → human merges
+  · findings → fold fix-now into this PR; independent work remains a proposal until user triage; re-review
+  · docs site declared (documentation map has a `Docs site` block) →
+    /generate-docs <unit> — document what this unit changed; the generated
+    pages ride this same PR (commit + push them before the merge gate)
+```
+
+The `/generate-docs` line appears **only** when the project's documentation
+map declares a `Docs site` block — never suggest it otherwise (a project
+without a docs site has nowhere to publish).
+
+This never auto-merges. Explicit `P<n>` stops after one phase; omitted-phase
+mode gates and commits every remaining phase before the same final review.
+
+### Marking done (status semantics)
+
+A unit flips to **`done` when its last step runs — opening the PR — even though it
+isn't merged yet.** `done` means *built and PR-open*; merge state lives in the forge
+(the open/merged PR), not in the status. **A `done` row always carries its PR
+reference** — `done · [#<pr>](<pr-url>)` — added right after `gh pr create`
+returns the URL (follow-up `docs: link PR #<n>` commit on the same branch);
+`done` without a PR link is the tell-tale of an unfinished close-out. The flip is a doc change, so it rides the
+PR-bound commit (never a lone commit on the default branch). **Never merge with docs
+still pending, and never drop the issue / fix-index entry before merge** — those are
+`audit-pr`'s gates, not removed at done-time.
+
+**One phase = one worker context when available.** Whole-unit mode is one user
+invocation, not one growing raw context: subagent/headless hosts use a fresh
+worker per phase; inline-only hosts reduce state to compact receipts. Explicit
+phase invocation remains the strict fresh-conversation fallback.

package/skills/execute-phase/references/FORGE_BODY.md

@@ -0,0 +1,24 @@
+## Forge body policy
+
+Forge operations use the project's declared forge CLI (Workflow conventions —
+examples use `gh`; translate if the project declares another forge).
+
+> **Forge bodies are Markdown, not shell — never hand-escape them.** Backticks,
+> `*`, `_`, `#`, `|` in an issue / PR / comment body are **formatting**; a `\`
+> before them renders **literally** (`` \`code\` `` instead of `` `code` ``) —
+> the #1 forge-formatting bug (worse on some agents than others). Fix it at the
+> source: **never pass a Markdown body inline** (`--body "…"`, a quoted
+> `<<'EOF'` heredoc, or single quotes — all of these preserve a stray `\` or
+> mangle backticks). Instead **write the body to a file with the Write tool**
+> (plain Markdown — real backticks, zero backslashes; scratchpad is fine) and
+> pass **`--body-file <path>`**: `gh issue create --body-file <path>`,
+> `gh pr create --body-file <path>`, `gh issue comment <n> --body-file <path>`
+> (or the declared forge's equivalent). Short one-liners with no Markdown (e.g.
+> a bare `Closes #12`) may stay inline. **Verify after creating:**
+> `gh issue view <n> --json body` / `gh pr view <n> --json body` must show
+> backticks rendering — a literal `` \` `` in the output means redo it with
+> `--body-file`.
+
+- **`--fix`:** every fix needs a tracked issue; create with `gh issue create --template fix.yml --body-file <path>` if missing, populating the body from the SPEC (body as a Markdown file — see the Markdown rule above). Use the returned number for branch and folder.
+- **feature:** if it came from an issue, include `Closes #<n>` in the PR body. Don't create issues for features that didn't originate from one.
+- **Language precedence for every artifact** (issues, PRs, commits, SPECs, docs): (1) an explicit user instruction in the prompt, else (2) the project's declared docs language (Workflow conventions), else (3) English. The conversation language is NOT a signal — being asked in Spanish never makes the PR Spanish. Non-matching source material gets translated first.

package/skills/execute-phase/references/HANDOFF.md

@@ -0,0 +1,21 @@
+## Phase handoff record (`progress.md` — fixed schema)
+
+Every phase ends by APPENDING one entry to the unit's `progress.md`. Feature
+mode: the file `plan-feature-scaffold` created. Phased XS/S single-pass and
+`--fix` units: create `progress.md` beside the SPEC on P1 (the SPEC's
+checkboxes stay the task ledger; this file is the **handoff channel**).
+Fixed schema — all five lines present, `none` is valid, free prose is not:
+
+```
+## P<k> — <YYYY-MM-DD>
+- Done: <the phase's delivered tasks, one line>
+- Remains: <in-unit work still open, or none>
+- Gotchas: <surprises, workarounds, or decisions the NEXT phase must know, or none>
+- Files: <paths touched>
+- Next: P<k+1> — <its title> | unit finished
+```
+
+The entry rides the phase commit (no sha in the entry — the carrying commit is
+the phase sha; `git log` resolves it). The next phase starts in a fresh
+conversation and reads only `SPEC.md`, its phase's `TASKS.md` section (or SPEC
+`## Phases`), and `progress.md`. Never rely on prior-session memory.

package/skills/execute-phase/references/OPPORTUNISTIC_FINDING.md

@@ -0,0 +1,45 @@
+## Opportunistic finding policy
+
+Use this only for genuinely out-of-scope work discovered while implementing the
+current unit. Missing acceptance, correctness, security, accessibility, required
+UX/error behavior, or a phase task remains current-unit work — fix/replan/decide
+inside the unit; it is never a proposal or issue.
+
+### Closed decision ladder
+
+Evaluate rows in order; every box in a selected row must pass. Estimates include
+tests and docs.
+
+| Decision | Pass only if every box is true | Action |
+|---|---|---|
+| **Autofix** | ≤15 lines; ≤2 files; files already touched; low risk; no public API/schema/migration/dependency/permission/architecture/user-visible change; objective unchanged | Fix in the current phase commit and run its gate. |
+| **Opportunistic Fix** | ≤40 lines; ≤3 files; files touched or directly covered by the phase test; supports touched behavior/consistency; low risk; no public API/schema/migration/dependency/permission/architecture/acceptance change; objective unchanged | Fix in the phase commit, add focused behavior coverage, run the gate. |
+| **Proposal** | Either fix row fails, evidence is uncertain, work is independent, or product/risk judgment is needed | Do not edit or create an issue. Record a compact proposal with evidence and trigger for explicit user batch triage. |
+
+`≤` is inclusive. Check Opportunistic Fix even after a non-size Autofix failure.
+More than 40 lines/3 files is a Proposal unless it is current-unit work, in
+which case it is `replan-in-unit` and stays on the same branch/PR.
+
+### Record before acting
+
+Append one row to `decisions.md` before editing/recording:
+
+```markdown
+| Date | Finding | Evidence | Estimate | Risk | Local files | Decision | Why | Trigger | Record |
+|---|---|---|---|---|---|---|---|---|---|
+| <date> | <finding> | <file:line/command> | <lines/files> | <low/med/high> | <yes/no + paths> | <Autofix/Opportunistic Fix/Proposal> | <boxes> | <when to reconsider> | <commit sha|proposal> |
+```
+
+For a Proposal, `Record` stays `proposal`; no forge operation runs. Batch the
+proposal in the unit's final report. Only an explicit user invocation of
+`triage-issue`/the project's backlog intake may create tracked work, where it
+must dedupe against existing issues first.
+
+### Guardrails
+
+- No automatic `gh issue create` or equivalent from execution, review, fold,
+  audit, or their loops.
+- Never use Proposal to move unfinished SPEC/task scope out of the unit.
+- An uncertain classification becomes Proposal and may stop for user judgment;
+  it never authorizes adjacent edits.
+- `known-issues.md` records blockers, not a substitute backlog.

package/skills/execute-phase/references/PREFLIGHT.md

@@ -0,0 +1,152 @@
+## Dependency gate (always, before any other step)
+
+Run this check for **every** mode (feature phase, single-pass, and `--fix`)
+before touching anything:
+
+1. Read the unit's `Depends on:` (SPEC) and its roadmap/fix-index row.
+2. Build the **transitive closure**: for each dependency, read *its* roadmap
+   row and collect its dependencies too, until none remain.
+3. For each entry in the closure, its status must be **merged in the forge**
+   (`gh pr view` on its PR, or the row's PR reference) — `done`-but-PR-open is
+   NOT met (its code isn't on the default branch), and a missing folder/row is
+   NOT met.
+4. **All met** → proceed to the **own-status precondition** below.
+5. **Any unmet → STOP before any edit** and print exactly:
+
+   ```
+   DEPENDENCY GATE — <NN>-<slug> BLOCKED
+   Unmet chain (deepest first is the one to start):
+     <NN> ← <dep> (<status>) [← <dep-of-dep> (<status>) …]
+   Build order to unblock: <deepest> → … → <NN>
+
+   → Next: /execute-phase <deepest> P1 — the deepest unmet dependency (plan it
+     first with /plan-feature <deepest> if it has no SPEC)
+     · fix-type dependency → /plan-fix then /execute-phase --fix
+     · proceed anyway, at your own risk → /execute-phase <NN> <phase> --force
+       (the override is recorded in decisions.md — never silent)
+   ```
+
+6. **`--force`** skips the stop (never the check): the gate still runs and its
+   result is **recorded in `decisions.md`** ("started with unmet deps: <list>,
+   user-forced <date>") before implementation begins. `--force` is a
+   user-only escape hatch — the autopilot (`ship-roadmap`) must never pass it.
+
+### Dependency receipt (v1) + fail-closed fast path
+
+After a full pass with every dependency merged, append to the unit's `progress.md`:
+
+```
+## Dependency receipt v1
+- Fingerprint: <sha> · Closure: <NN>-<slug> ← <dep> …
+- Merged PRs: <dep> #<n> @ <merge sha> · Fully merged: yes · Verified: <date>
+```
+
+Fingerprint = `git hash-object --stdin` over the SPEC `Depends on:` line and
+each closure roadmap row (rows encode the merged PR, e.g. `22-other #7 @ a1b2c3
+merged`). PR identities are provenance in the receipt, never fingerprint input —
+the fingerprint covers only inputs the fast path can re-derive locally.
+
+**Fast path (local only, no forge calls):** recompute the fingerprint (SPEC +
+roadmap rows). Skip forge traversal **only when** a `v1` receipt exists, the
+recomputed fingerprint matches, it records `Fully merged: yes`, and no `--force`
+is recorded in `decisions.md` after the receipt date.
+
+**Fail closed — invalidate and rerun the full gate** on any of: fingerprint
+mismatch (graph changed), missing or older-version receipt (format drift), a
+later `--force`, or the full gate itself finding an unmet dependency. On any
+ambiguity never skip forge traversal; rewrite the receipt after every full pass.
+
+### Own-status precondition (runs after the dependency closure is met, still before any edit)
+
+Feature mode only (a fix has no roadmap-status equivalent — its own state is
+the fix-index entry, unaffected). Read this unit's own roadmap row status
+(the five-state machine — `docs/features/ROADMAP.md` → Status legend):
+
+1. **`idea`** (or no `SPEC.md` with `## Design status: designed`) → STOP,
+   before any edit:
+
+   ```
+   OWN-STATUS GATE — <NN>-<slug> BLOCKED (idea)
+   This unit has no completed product design yet.
+
+   → Next: /design-feature <slug> — write the product half first
+     · proceed anyway, at your own risk → /execute-phase <NN> <phase> --force
+       (the override is recorded in decisions.md — never silent)
+   ```
+
+2. **`defined`** (product half designed, engineering half / planning
+   artifacts not yet scaffolded) → STOP:
+
+   ```
+   OWN-STATUS GATE — <NN>-<slug> BLOCKED (defined)
+   Product half designed; engineering half + planning artifacts not yet scaffolded.
+
+   → Next: /plan-feature <NN>-<slug> — scaffold the engineering half + TASKS.md
+     · proceed anyway, at your own risk → /execute-phase <NN> <phase> --force
+       (the override is recorded in decisions.md — never silent)
+   ```
+
+3. **`planned`+** → proceed to the normal workflow.
+4. **Legacy compat.** A row still reading a plain `planned` with no
+   five-state history: check its `SPEC.md` product half. Complete
+   (`## Design status: designed`) → treat as `defined`+`planned`, no
+   redirect. Incomplete/absent → treat as `idea`, redirect per step 1. See
+   `docs/workflow/MIGRATION.md`.
+5. **`--force`** skips the STOP (never the check), same rule as the
+   dependency gate: recorded in `decisions.md` before implementation begins;
+   the autopilot (`ship-roadmap`) must never pass it.
+
+## Acceptance-manifest gate (after dependency/own-status, before phase-lint)
+
+Consume `skills/verification-contract/SKILL.md`. For a current-format unit,
+validate sibling `ACCEPTANCE.md`, run `git hash-object` on it, and compare the
+blob to `progress.md`'s `Acceptance receipt v1`.
+
+- No receipt on the first phase → append the receipt before edits; it rides the
+  first phase/planning-artifact commit. The just-computed blob is the baseline.
+- Exact receipt match → continue.
+- Missing/mismatched manifest → print the verification contract's fixed
+  `ACCEPTANCE GATE` block and stop. `--force` never bypasses a changed finish line.
+- Legacy unit with no manifest reference in its planning artifacts → hash the
+  committed `SPEC.md`, record `Manifest: legacy SPEC.md`, and apply the same
+  exact-blob rule.
+
+Run this check again immediately before each phase in whole-unit mode and before
+final close-out. The executor may add tests but may not narrow commands, weaken
+assertions, or edit acceptance to make a candidate pass.
+
+## Phase-lint pre-flight guard (always, before any edit — after the dependency/own-status gates)
+
+**Legacy-SPEC carve-out (check this first, before anything else in this
+section):** if the target SPEC has **no `## Phases` section**, skip this
+guard entirely — no lint run, no STOP — and fall straight through to the
+legacy single-pass flow ("A SPEC without `## Phases`
+… runs the legacy flow … end-to-end in one pass" — see
+[legacy workflow](WORKFLOWS_LEGACY.md)). The guard below applies
+only to a SPEC that carries a `## Phases` ledger.
+
+Before touching any code, run the canonical 8-box phase-lint owned by
+`skills/phase-contract/SKILL.md` (the fixed PASS/BLOCKED block and the
+normalized phase fingerprint) against the **target phase** (its title,
+declared layer, task list, and done-when).
+
+1. **All 8 boxes tick** → proceed to the normal workflow.
+2. **Any box FAILs → STOP before any edit** and print exactly:
+
+   ```
+   PHASE-LINT GATE — <NN|n>-<slug> <phase> BLOCKED
+   Failed boxes:
+     ✗ <box label> — <one-line reason>
+     [✗ <box label> — <one-line reason>] …
+
+   → Next: /plan-feature <NN> — re-cut or split the phase (feature)
+     · fix-type unit → /plan-fix — re-cut or split the phase
+     · proceed anyway, at your own risk → /execute-phase <NN|--fix n> <phase> --force
+       (the override is recorded in decisions.md — never silent)
+   ```
+
+3. **`--force`** skips the STOP (never the check): the lint still runs and its
+   result is **recorded in `decisions.md`** (feature mode) or the fix SPEC's
+   own notes / `progress.md` if present ("executed non-atomic phase: <failed
+   boxes>, user-forced <date>") before implementation begins. `--force` is a
+   user-only escape hatch — the autopilot (`ship-roadmap`) must never pass it.