@gtrabanco/pi-agentic-workflow 0.13.3 → 0.14.0

package/skills/evidence-grounding/references/ROWS.md

@@ -1,93 +0,0 @@
-## The evidence row contract
-
-The row is the unit of grounding. One row per material claim or obligation,
-columns in this exact order:
-
-```text
-claim-or-obligation | authority-kind | source-and-location | observed-revision |
-freshness | status: proven|decision|unknown | owner-or-next-evidence
-```
-
-### Plan-stage table — one declared extension
-
-The Plan-stage evidence table (`planning-evidence.md`, or the XS/S embed) is the
-row above with exactly two changes, declared here and nowhere else: a prefixed
-stable `id` column (`PE-001`, … — renumbering is a replan, not an edit) and one
-extension column, `affected-decision-or-obligation` (the frozen decision,
-obligation, or acceptance row the claim resolves), inserted after
-`observed-revision`. Full Plan-stage header order:
-
-```text
-id | claim-or-obligation | authority-kind | source-and-location | observed-revision | affected-decision-or-obligation | freshness | status | owner-or-next-evidence
-```
-
-### Closed vocabularies
-
-`authority-kind` — exactly one:
-
-| Value | Means | Acceptable `source-and-location` |
-|---|---|---|
-| `repository` | observed in tracked source, config, or a generated artifact | `path:line` or `path` + symbol/test name |
-| `document` | a project doc, template, SPEC, roadmap or fix-index row, or fetched external documentation | `path:section`, or the URL plus access date for a fetched source (`https://… (fetched YYYY-MM-DD)`) |
-| `ledger` | a frozen Normalized Repository State fact/decision, or an accepted architectural decision | `REPOSITORY_STATE.md` row ID (`F0nn`/`AD-nnn`) |
-| `forge` | an issue, PR, review, or CI record | absolute issue/PR URL |
-| `user` | an explicit user decision recorded this unit or in `decisions.md` | dated `decisions.md` / SPEC `## Amendments` row |
-| `derived` | a conclusion computed from rows above by a stated rule | the rule plus its input row ids |
-
-`status` — exactly one:
-
-- `proven` — the cited source was actually read and answers the claim.
-- `decision` — a human/ledger authority fixed it; no further evidence exists or
-  is needed. Cite the `user` or `ledger` row.
-- `unknown` — not established. **Required:** `owner-or-next-evidence` names who
-  closes it and what evidence would close it. An `unknown` may stay open only if
-  the artifact states the consequence of it staying open.
-
-`freshness` — exactly one:
-
-- `current` — read at the revision the artifact will be bound to.
-- `drifted` — the cited source changed after the row was written; re-read before
-  readiness.
-- `stale` — the cited source no longer exists or no longer says this.
-- `not-applicable` — `status: decision` rows that cannot drift.
-
-A `drifted` or `stale` row is not evidence. It must be re-acquired (step 2) or
-demoted to `unknown` with an owner; carrying it into a draft is how a plausible
-but false rationale gets written.
-
-### Bounded question set
-
-Ask these, in order, once per inventory item. This is the whole set — do not
-grow it into an open-ended research brief.
-
-1. What must be true for this claim/obligation to hold?
-2. Which authority kind can prove it, and where does that authority live here?
-3. What did I actually observe there (`source-and-location`, `observed-revision`)?
-4. Does anything in the repository, roadmap, or ledger contradict it?
-5. If it cannot be answered: who owns the unknown, and what single next read
-   would answer it?
-
-Questions 1–5 map onto the columns. A question already answered by a frozen
-ledger row is not re-asked — cite the row.
-
-### Where the rows are frozen
-
-Rows survive compaction, so they must land in the artifact the reviewer reads —
-never in chat history.
-
-| Authoring stage | Frozen home | Bound by |
-|---|---|---|
-| Product half (`design-feature`, issue-derived design) | the SPEC's Product half plus `decisions.md` for non-obvious calls | the SPEC snapshot via `spec-product-v1` |
-| Engineering half (`plan-feature*`, `plan-fix`) | `planning-evidence.md` for M/L units; `### Planning evidence` inside the SPEC for XS/S | the Plan snapshot (kind `planning-evidence`) |
-
-Compaction rules: keep the conclusion row, drop raw search output, discarded
-hypotheses, and narrative. One row per claim, no prose padding, no transcripts.
-The table is an argument index, not a work log — a reviewer must be able to
-audit each row against its `source-and-location` in one read.
-
-### Fix units
-
-A fix has no Product half (D6). Its rows cover: the reproduction, the root cause
-with code evidence, the regression scope, the rollback path, and the affected
-invariant or use case. Each remains a row with the same vocabulary — a missing
-reproduction row is `unknown`, not "probably this".

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

@@ -1,57 +0,0 @@
-## 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 the manual
-`/review-change` → `/fold-findings` (only on `REVIEW-FAIL`) → re-run
-`/review-change` path. 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 `/review-change`, then
-   `/fold-findings` (only on `REVIEW-FAIL`), then re-run `/review-change`, 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

@@ -1,77 +0,0 @@
-## 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 the mandatory `/review-change` → `/fold-findings` (only on
-`REVIEW-FAIL`) → re-run `/review-change` path because it preserves fresh review
-contexts while handling bounded corrections; direct `review-change` remains the
-manual entry. 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 `/review-change` (the mandatory end review) → `/fold-findings` (only
-on `REVIEW-FAIL`) → re-run `/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/HANDOFF.md

@@ -1,21 +0,0 @@
-## 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

@@ -1,45 +0,0 @@
-## 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/UNIT_LOOP.md

@@ -1,88 +0,0 @@
-## Whole-unit execution loop
-
-This route runs only when the user omitted `P<n>`. One user invocation advances
-every remaining planned phase; phase boundaries still own scope, gates,
-documentation, and commits.
-
-### Dispatch
-
-- `execute-phase <NN>` → all remaining feature phases.
-- `execute-phase --fix <n>` → all remaining fix phases.
-- An explicit `P<n>` never loads this route and executes exactly one phase.
-- Default `--max-attempts 3` limits repair attempts for the same unchanged gate
-  failure inside one phase. A positive user value overrides it.
-
-### Queue
-
-Read the unit ledger once and select unfinished phases in ascending order. A
-phase is unfinished when any task is unticked or its evidence/commit is absent.
-Reconcile ticks against repository evidence before selection; contradictory
-state with no unique next phase returns `AMBIGUOUS` and stops.
-
-Materialize the queue before work as explicit phase IDs (`P2, P3, P4`), never
-an empty array, ellipsis, or template placeholder. Every terminal report names
-the phases actually attempted/completed.
-
-The final `Hardening & PR`/close-out phase remains last. Never run it while an
-earlier phase is unfinished.
-
-### Loop — one transaction per phase
-
-For each queued phase:
-
-1. Recompute the frozen `ACCEPTANCE.md` blob and compare it with the acceptance
-   receipt. Mismatch/missing → `ACCEPTANCE GATE BLOCKED`; no edits.
-2. Run phase-lint, architectural-invariant, dependency/own-status fast paths,
-   and the selected mode workflow for this phase. A fail-closed gate ends the
-   whole invocation with its existing fixed block.
-3. Prefer a fresh worker context when the host supports subagents/headless
-   workers; give it only `ACCEPTANCE.md`, `SPEC.md`, this phase's tasks, the last
-   `progress.md` receipt, and the selected workflow contracts. The conductor
-   keeps receipts, never raw source context. Without that primitive, execute
-   inline and apply the same input cap.
-4. Implement the phase, run its exact validators and normal project gate, update
-   unit docs, and commit. Never commit red and never weaken a validator.
-5. On a red gate, feed back only the failing command, exit status, failing test
-   names, and smallest relevant output. Repair the same phase and retry. Same
-   failure with no diff twice, or `--max-attempts` exhausted, stops:
-
-   ```text
-   UNIT LOOP — <unit> BLOCKED at <P<n>>
-   Reason: <NO-PROGRESS|ATTEMPT-BUDGET> · Attempts: <n>
-   Last validator: <command> → <exit/status + compact failure>
-   Preserved: no red commit; acceptance blob <sha> unchanged
-
-   → Next: inspect the named blocker, then re-run /execute-phase <unit>
-     · architecture/product decision required → resolve it before resuming
-     · continue atomically → /execute-phase <unit> <P<n>>
-   ```
-
-6. Before the commit append a compact cycle receipt to `progress.md`:
-
-   ```text
-   ## Unit-loop receipt — <P<n>>
-   - Commit: pending · Gate: <command> (exit 0) · Acceptance blob: <sha>
-   - Next: <P<n+1>|close-out|none> · Attempts: <n>
-   ```
-
-   Commit it with the phase, then replace `pending` with the resulting SHA in
-   the next phase's reconciliation note (never amend an already-published
-   commit only to self-reference it). Reduce working state to the receipt.
-7. Do **not** stop for intermediate review checkpoint triggers. Record any
-   trigger in the receipt for final risk selection; the mandatory independent
-   end review covers the frozen final candidate once.
-
-### Terminal
-
-When the last implementation phase is green, run the existing close-out phase:
-mark done, push, open/link the PR, and leave the branch remote-current. Then:
-
-```text
-UNIT LOOP — <unit> COMPLETE
-Phases: <n> · Commits: <sha list> · Acceptance: <blob> · Gate: PASS
-PR: <url>
-
-→ Next: /review-change on the changed HEAD — the mandatory end review (fold-findings only after a REVIEW-FAIL)
-  · findings → /fold-findings (only on a REVIEW-FAIL), then re-run /review-change — triage or replan unresolved findings
-  · merge gate after REVIEW-PASS → /audit-pr
-```

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

@@ -1,37 +0,0 @@
-## Feature mode workflow
-
-**Atomic feature phase** — `docs/features/<NN>-<slug>/`. An explicit `P<n>`
-runs this once; whole-unit mode calls it once per remaining phase.
-
-1. Verify branch (create if on `main`). **P1 only:** if the planning artifacts
-   (`docs/features/<NN>-<slug>/`) are still uncommitted, commit them first on the
-   feature branch — `git add docs/features/<NN>-<slug> && git commit -m "docs(<NN>-<slug>): planning artifacts"` —
-   so planning history stays separate from implementation.
-2. Read `progress.md` first (the phase handoff record — fixed schema above;
-   the last entry's `Remains:`/`Gotchas:` lines are the previous phase's
-   message to you), then `SPEC.md` + the requested phase's `TASKS.md`
-   section. That is the whole handoff — never rely on session memory from a
-   previous phase, and honor the *Context budget* for everything beyond
-   these files.
-3. Implement only that phase (see *Implementation guidance*).
-4. Run the gate (type-check, tests, build). **If red:** fix within the phase's
-   scope and re-run — never commit red. If the failure can't be fixed within
-   this phase's scope, record it in `known-issues.md`, leave the work
-   uncommitted, and stop with a clear report.
-5. Update the per-phase docs.
-6. Stage and commit: `git add <changed files>` then `git commit -m "<type>(<scope>): <summary>"` — one commit per phase, conventional format. Run this; don't just describe what should be committed.
-7. **Explicit-phase mode only:** check the review checkpoint triggers and make
-   the existing non-blocking recommendation when one fires. Whole-unit mode
-   records the trigger in its phase receipt and continues; it never interrupts
-   for an intermediate review. The end review stays mandatory.
-
-**Resuming an interrupted phase (stated contract — any agent must honor it).**
-If, on entry, the unit branch already carries dirty files or commits belonging
-to the requested phase (a prior run died mid-turn — e.g. the driver process
-restarted), do **not** restart the phase from scratch: reconcile against
-`TASKS.md` first — verify each ticked task's evidence actually exists (code
-path / test present), untick any tick without evidence, then continue from the
-first unticked task. Idempotent re-entry is the contract `workflow-status`'s
-crash-recovery verdict `RESUMABLE` relies on. If the ledger contradicts the
-commits in a way that has no unique next task, stop and report instead of
-guessing (that is its `AMBIGUOUS` verdict — a human decides).

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

@@ -1,43 +0,0 @@
-## Fix mode workflow
-
-**`--fix`** — `docs/fix/<n>-<topic>/`, template `docs/fix/_TEMPLATE/SPEC.md`,
-index `docs/fix/README.md`. A phased fix runs every remaining phase when `P<k>`
-is omitted and one phase when it is explicit. The final `Hardening & PR` phase
-runs close-out (steps 7–9) after prior phases are green; legacy SPECs run once.
-
-1. Verify the issue exists (`gh issue view <n>`); if it doesn't, create it
-   (`gh issue create --template fix.yml --body-file <path>`, body from the SPEC
-   written to a Markdown file — per the Markdown rule above).
-2. **If `docs/fix/<n>-<topic>/SPEC.md` already exists (e.g. from `plan-fix`), use it — do not re-draft.** Otherwise copy the template, fill every section, and register the entry in `docs/fix/README.md`.
-3. Verify branch (`fix/<n>-<topic>`).
-4. Implement the fix (no separate planning artifacts; the SPEC and its `## Phases` ledger are enough).
-5. Run the gate.
-6. Stage and commit: `git add <changed files>` then `git commit -m "fix(<scope>): <summary>"`. An explicit implementation phase **STOPs here — no push, no PR**; whole-unit mode continues to the next phase.
-7. **Mark done + open the PR — always (the close-out; in a phased SPEC these
-   are the final `Hardening & PR` phase's tasks).** Set the
-   `docs/fix/README.md` entry's status to `done` (built, not yet merged), commit,
-   `git push`, then open the PR with the body written to a Markdown file (per the
-   Markdown rule above): `gh pr create --base main --title "fix(<scope>): <summary>" --body-file <path>`
-   (the body includes `Closes #<n>`). Run the commands. Then, with the returned URL: **print it in the chat**,
-   set the `docs/fix/README.md` entry to `done · [#<pr>](<pr-url>)`, commit
-   (`docs: link PR #<n>`), and push again. A fix **never ends branch-only** —
-   it always leaves an open, chat-linked PR.
-8. **Mandatory review hand-off** → `/review-change`, then `audit-pr` as the merge gate.
-   Print the next step. **Keep the fix-index entry** until the PR is actually merged
-   (don't drop issue tracking early; the merge gate also blocks on pending docs).
-9. **After merge only:** remove the `docs/fix/README.md` entry (or archive it to the
-   project's fix history per its convention) — never before the merge.
-
-**Resuming an interrupted phase (stated contract — any agent must honor it).**
-If, on entry, the fix branch already carries dirty files or commits belonging
-to the requested phase (a prior run died mid-turn — e.g. the driver process
-restarted), do **not** restart the phase from scratch: reconcile against the
-SPEC's `## Phases` checkboxes first — verify each ticked task's evidence
-actually exists (code path / test present), untick any tick without evidence,
-then continue from the first unticked task. Idempotent re-entry is the contract
-`workflow-status`'s crash-recovery verdict `RESUMABLE` relies on. If the ledger
-contradicts the commits in a way that has no unique next task, stop and report
-instead of guessing (that is its `AMBIGUOUS` verdict — a human decides).
-
-(The `Depends on:` check for fixes is the same Dependency gate above — it runs
-before step 1, transitively, and blocks unless `--force`.)

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

@@ -1,26 +0,0 @@
-## Legacy mode workflow
-
-**Legacy single-pass** — a SPEC **without** a `## Phases` section (drafted
-before `plan-feature-scaffold` 1.8.0 / `plan-fix` 2.1.0) runs the whole unit
-end-to-end in **one pass**. This is the fallback shared by small-feature and
-`--fix` modes; a SPEC that carries `## Phases` never runs it.
-
-1. Verify branch.
-2. Read `SPEC.md` (+ `DECISIONS.md` if present) and the docs its documentation map points to.
-3. If the SPEC is ambiguous on scope / edge cases / UI, ask first — one question at a time, nothing it already answers.
-4. Implement end-to-end (see *Implementation guidance*).
-5. Run the gate; write `CHECKLIST.md` (below).
-6. Stage and commit: `git add <changed files>` then `git commit -m "<type>(<scope>): <summary>"`.
-7. **Mark done + open the PR — always (the close-out).** Flip the roadmap
-   row to `done` (it's *built*; merge state lives in the forge, not the status —
-   see *Marking done*), commit that flip, then `git push` and open the PR
-   (body written to a file as Markdown, per the Markdown rule above):
-   `gh pr create --base main --title "<type>(<scope>): <summary>" --body-file <path>`
-   (put `Closes #<n>` in that body when issue-born). Then, with the URL `gh pr create`
-   returned: **print it in the chat**, update the roadmap row to
-   `done · [#<pr>](<pr-url>)`, commit (`docs: link PR #<n>`), and push again —
-   the link commit rides the same open PR. A single-pass unit **never ends
-   branch-only** — it always leaves an open, chat-linked PR, regardless of the
-   review/audit still to come.
-8. **Mandatory review hand-off** → `/review-change` (the required final quality step;
-   see *Review checkpoint*), then `audit-pr` as the merge gate. Print the next step.

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

@@ -1,38 +0,0 @@
-## Small/phased mode workflow
-
-**Phased single-pass units — the default for small (XS/S) feature SPECs.**
-Every current XS/S feature SPEC carries `## Phases` (**≥ 2 phases**; final =
-`Hardening & PR`). `execute-phase <NN>` runs every remaining phase; explicit
-`P<k>` runs one. The SPEC's checkboxes are the execution ledger (there is no
-`TASKS.md`): tick each task with evidence.
-
-**Resuming an interrupted phase (stated contract — any agent must honor it).**
-If, on entry, the unit branch already carries dirty files or commits belonging
-to the requested phase (a prior run died mid-turn — e.g. the driver process
-restarted), do **not** restart the phase from scratch: reconcile against the
-SPEC's checkboxes first — verify each ticked task's evidence actually exists
-(code path / test present), untick any tick without evidence, then continue
-from the first unticked task. Idempotent re-entry is the contract
-`workflow-status`'s crash-recovery verdict `RESUMABLE` relies on. If the ledger
-contradicts the commits in a way that has no unique next task, stop and report
-instead of guessing (that is its `AMBIGUOUS` verdict — a human decides).
-
-Each phase appends its handoff entry to a `progress.md` beside the SPEC
-(created on P1 — see *Phase handoff record*). An implementation phase runs the
-per-phase steps below. Explicit-phase mode **STOPs after the phase commit — no
-push, no PR** (the turn contract's box 5 "unit not finished" rule); unit-loop
-mode continues. The final `Hardening & PR` phase runs close-out after every
-prior phase is green; its pre-written tasks ARE the close-out chain.
-
-Per-phase steps (implementation phases only):
-
-1. Verify branch.
-2. Read `SPEC.md` (+ `DECISIONS.md` if present) and the docs its documentation map points to.
-3. If the SPEC is ambiguous on scope / edge cases / UI, ask first — one question at a time, nothing it already answers.
-4. Implement end-to-end (see *Implementation guidance*).
-5. Run the gate; write `CHECKLIST.md` (below).
-6. Stage and commit: `git add <changed files>` then `git commit -m "<type>(<scope>): <summary>"`. **STOP** — no push, no PR until the final phase.
-
-A SPEC **without** `## Phases` (drafted before those versions) runs the
-**legacy single-pass flow** unchanged, end-to-end in one pass — see
-[legacy workflow](WORKFLOWS_LEGACY.md).