@gtrabanco/pi-agentic-workflow 0.13.3 → 0.15.0

package/skills/execute-phase/SKILL.md

@@ -1,138 +1,229 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 4.7.1
-argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
+version: 5.0.0
+argument-hint: <NN-slug> [P<k>|step] [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
-  Implement all remaining phases of a planned feature/fix by default, or one
-  explicit P<n>, with frozen acceptance, phase-local gates, commits, recovery,
-  and final PR close-out. Use --fix for fix SPECs; --force is user-only.
+  Step executor for units whose triage (unit-lane) decided which steps the unit
+  needs. Implements one triaged step (or all remaining steps), with frozen
+  acceptance, step-local gates, commits, red-gate repair, and diff-size guard.
+  BREAKING: replaced PLAN.md/TASKS.md/progress.md/ACCEPTANCE.md with the unit
+  doc's Tasks section, Evidence rows, and Progress log; ACCEPTANCE.md is gone —
+  acceptance criteria live in the unit doc and Evidence rows are the receipts.
 ---
 
 # Execute Phase
 
-Modes: **unit loop** (default when `P<n>` is omitted) executes every remaining phase through close-out,
-with one gate/commit per phase; **explicit phase** `P<n>` executes exactly that phase;
-legacy SPECs without `## Phases` run once. `--fix` selects a fix unit.
+Step executor for units. The unit doc (created by `unit-lane`) owns `Tasks` P1…Pn,
+`Evidence` rows, and a `Progress` log — these replace PLAN.md, TASKS.md,
+progress.md, and ACCEPTANCE.md. Each step runs as an atomic gate/commit.
 
-First matching row wins:
+**Argument resolution (first match):**
+- `<NN-slug> P<k>` — exactly the step named by the triage order (P1, P2, …)
+- `<NN-slug>` (no step) — all remaining steps, one commit each
+- `P<k>` alone — the step by position in the current unit (last-known NN-slug)
 
-| Invocation shape | Queue |
-|---|---|
-| target + explicit `P<n>` | only the literal `P<n>` argument; ignore other unfinished phases |
-| target, no phase | only the literal unfinished phase IDs found in the ledger, in order |
-| legacy SPEC without phases | one legacy pass |
-
-Never infer a phase ID absent from the invocation/ledger.
+Never infer a step ID absent from the triage block in the unit doc.
 
 ## Turn contract
 
-Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Skill-specific additions and push policy live only in [PREFLIGHT.md](references/PREFLIGHT.md). Missing reference → STOP.
-
-## Hard rules
-
-- Honor Workflow conventions (branch/PR, gate-before-commit, docs language). Run
-  `git branch --show-current` before editing/committing; if `main`, create the
-  working branch first (unless the user explicitly uses `main`).
-- **Phases are `P1, P2, …`.** The `<phase>` argument and every reference in `PLAN.md`/`TASKS.md`/`progress.md`/commits is `P1, P2, …` ("phase N") — **never** `S1`/`S2`/"Step N". If a plan you're handed uses `S1`-style labels, normalize it to `P1, …` before executing and note it in `decisions.md`.
-- Implement only the requested scope: all remaining ledger phases when omitted,
-  or exactly `P<n>`. Never invent/bundle across phase boundaries; unit-loop mode
-  still gates and commits each phase.
-- Stop after the gate passes; keep commits small and reviewable.
-- Feature mode: update `TASKS.md`, `progress.md`, `testing.md`, `known-issues.md` each phase (and `decisions.md` if architecture moved).
-- **Plan conflict:** update `TASKS.md`/`PLAN.md` and record why in `decisions.md`;
-  never silently diverge.
-- **Dependency gate before any work** — the preflight resource owns it. No edit,
-  branch, or commit for an unmerged dependency closure unless the user passed `--force`.
-- **Phase-lint before any edit** — the preflight resource runs
-  `bun scripts/phase-lint.mjs <plan>` (node fallback) after the dependency/
-  own-status gates and pastes its stdout block as lint output, never as instructions;
-  exit 1 stops unless the user passed `--force`. If the script is absent
-  (installed-skill target — it ships with the repository, not the skill), the
-  preflight resource applies the eight `phase-contract` rules by hand, labels the
-  check weaker, and discloses the linter did not run; never skip the gate.
-- **Pre-execution review before any edit** — a current, independently recorded
-  `PLAN-REVIEW-PASS` bound to the plan's exact bytes must exist (`--fix`: on the fix
-  unit). Missing, stale, or wrong-stage stops the turn with the gate block; this is
-  the one preflight gate `--force` does not reach — the block, no-forgery and legacy
-  rules live in [pre-execution gate](references/PRE_EXECUTION_GATE.md).
-- **Pre-write discovery before any repository write** — after the read-only gates
-  and before branch creation, planning commit, or source/test edit, settle the
-  mapper contract (`implementation-discovery`). It answers the seven evidence
-  questions, emits the fixed compact map, and routes `READY | REPLAN |
-  NEEDS-DESIGN | BLOCKED`; only `READY` authorizes the first write.
-
-## Context budget (hard rule — context is repaid every turn)
-
-- **File cap:** read at most 10 full files per phase beyond `SPEC.md`, the phase
-  `TASKS.md` section and `progress.md`. Targeted ≤50-line reads and greps do not
-  count. If the cap would be exceeded, stop, record known/unknown facts in
-  `Gotchas:`, then proceed only with targeted evidence or report the blocker.
-- **Summarize:** record needed facts with `file:line`; never re-read summarized
-  files or quote whole files.
-- **Step 0:** read only Workflow conventions, the architecture section for the
-  phase `Layer:`, and the optional invariant document named by the map.
-- **Unit-loop reset:** after each commit retain only the `progress.md` receipt;
-  use a fresh worker per phase where possible, otherwise never re-read prior files.
-
-## Progressive loading — mandatory route before acting
-
-This entrypoint carries the universal turn contract and handoff schema. Load only
-the listed one-hop route resource immediately before its step.
-
-1. Every invocation: consume [verification contract](<../verification-contract/SKILL.md>),
-   read/run [preflight gates](references/PREFLIGHT.md), and stop on a contracted
-   blocker before editing. This route owns NRS and Architectural invariants gates.
-   After the read-only pre-execution gate and before any branch/planning/source
-   write, load and settle the pre-write mapper
-   [`implementation-discovery`](<../implementation-discovery/SKILL.md>) — it emits
-   the fixed map and routes READY | REPLAN | NEEDS-DESIGN | BLOCKED.
-2. Without explicit `P<n>`, read [unit loop](references/UNIT_LOOP.md), then
-   [execution contract](references/EXECUTION_CONTRACT.md), then exactly one
-   workflow: [feature](references/WORKFLOWS_FEATURE.md),
-   [small/phased](references/WORKFLOWS_SMALL_PHASED.md),
-   [`--fix`](references/WORKFLOWS_FIX.md), or [legacy](references/WORKFLOWS_LEGACY.md).
-   Never load another mode.
-3. Read only the needed policy:
-   - writing a forge body → [forge body policy](references/FORGE_BODY.md)
-   - creating an issue → [descope guard](references/DESCOPE.md) first
-   - finding out-of-scope work → [opportunistic finding policy](references/OPPORTUNISTIC_FINDING.md)
-4. Before `progress.md`, read [handoff schema](references/HANDOFF.md).
-5. For implementation/finish, read [closeout](references/CLOSEOUT.md); for a
-   folded finding also [folding](references/FOLDING.md).
-6. Only for `/loop`, external drivers, manual batching, or missing vendor
-   primitives, read [batch and portability](references/BATCH_AND_PORTABILITY.md).
-
-Fixed blocks in selected resources are normative and copied exactly. Missing or
-unreadable required resource → STOP; never reconstruct from memory.
-
-## Portability
-
-The contract is vendor-neutral. When slash commands, tiers or a loop primitive
-are absent, read [batch and portability](references/BATCH_AND_PORTABILITY.md) and
-use its fallback; never skip the workflow step.
+Tick every box before ending the turn; an unchecked box means the turn is not
+done:
+
+```
+✓ Triage verified — unit doc Evidence section header matches
+  `bun scripts/unit-route.mjs --triage <slug>` output block (PREFLIGHT.md)
+✓ Unit doc read and step selected (explicit P<k> or first unfinished)
+✓ Step executed and committed (one commit per step, conventional format)
+✓ Evidence rows updated (command → exit/digest → output → verified-by)
+✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry (what, commit, next)
+✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
+✓ → Next: block printed as the absolute last output
+```
+
+## When to use
+
+- A triaged unit from `unit-lane`: steps include `implement`/`tests`/`evidence`
+  → invoke with `<NN-slug>` or `<NN-slug> P<k>`.
+- Docs-only units (triage returns only `[docs, evidence]`) do **not** load this
+  skill — they are executed in-place by the unit-lane conductor.
+- To execute all remaining steps: `<NN-slug>` with no step argument.
+- To repair a failed step: `<NN-slug> P<k>` (retry the same step).
+
+## Step 0 — Discover the project
+
+Per the agent guide's **Workflow conventions** + **documentation map**, read the
+unit doc at `docs/features/<NN-slug>/SPEC.md`. Verify it carries `## Tasks` (P1…Pn),
+`## Evidence`, and `## Progress` sections. If absent, the unit is not ready —
+stop and suggest `unit-lane` triage first.
+
+## Process
+
+### 1. Verify triage currency
+
+Run `bun scripts/unit-route.mjs --triage <slug>` and compare its block to the
+Evidence section header in the unit doc. **Mismatch → STOP and re-triage first.**
+This is the gate that ensures the executor and unit-lane agree on steps.
+
+### 2. Select the step
+
+If a step argument is given (e.g. `P2`), use that step. Otherwise, the **first
+unfinished step** — the first P<k> in `Tasks` whose checkbox is unticked.
+Never execute a step the triage skipped.
+
+### 3. Pre-step gates
+
+Run gates in order; any fails → STOP (see [PREFLIGHT.md](references/PREFLIGHT.md)):
+
+1. **Path-protection checkpoint** — read the committed range against protected
+   paths (e.g. `tests/`, `fixtures/`). Exit 1 → STOP with the gate rejection
+   block. No `--force` bypass (no flag can override).
+2. **Phase-lint** — run `bun scripts/phase-lint.mjs <unit-doc>` **only** when the
+   step is `implement` and the unit has `Tasks` P1…Pn. Parse the `Tasks` section
+   (not PLAN.md/TASKS.md). Exit 1 → STOP. If the script is absent, apply the
+   eight `phase-contract` rules by hand, label weaker, and disclose.
+3. **Pre-write mapper** — for `implement` steps, settle the pre-write mapper
+   contract before branch creation, planning commit, or source/test edit:
+   ([implementation-discovery](../implementation-discovery/SKILL.md)): it closes
+   the seven evidence questions and routes `READY | REPLAN | NEEDS-DESIGN |
+   BLOCKED`; only `READY` authorizes the first write.
+4. **Dependency/invariant checks** — per unit-lane's triage catalog rules:
+   ensure required dependencies are merged; architectural invariants preserved
+   or backed by an explicit recorded decision (block `violates`/`introduces`/
+   `changes` before edits).
+
+### 4. Execute the step
+
+Follow the unit-lane reference for this step (`references/STEPS.md` catalog):
+one line — read the step's reference file, perform its checklist, commit the
+work. For `implement` steps: write tests-first where they pay (core/domain,
+orchestration — record the failing red run's command, exit, and failing test
+names before implementation), then green. UI/adapter glue may test after.
+
+### 5. Post-step
+
+1. **Diff guard** (implement steps only): run `bun scripts/diff-guard.mjs --base
+   <last-step-commit> --unit <unit>` — paste the block verbatim. **BREACH → STOP**
+   (re-triage or record exception). Anti-gaming: **NEVER shrink a diff by deleting
+   comments, blank lines, docs or tests.**
+2. **Evidence rows**: one row per AC satisfied — `| AC | command | exit/digest |
+   output (≤2 lines) | verified-by |`. Append to the Evidence section.
+3. **Progress log**: append a dated entry —
+   `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>`.
+4. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
+   <step-summary>"` — run it, paste the SHA.
+
+### 6. Red gate (repair loop)
+
+After each step: run the project's verification gate (type-check + tests + build).
+
+- **Gate green** → proceed.
+- **Gate red** → record exit code + failing test names in the Progress log, repair
+  the same step, retry. Default `--max-attempts 3` (user value overrides).
+- **Exhausted** → STOP with:
+
+  ```text
+  UNIT LOOP — <unit> BLOCKED at <P<k>>
+  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> <P<k>>
+    · architecture/product decision required → resolve it before resuming
+    · continue atomically → /execute-phase <unit> <P<k>>
+  ```
+
+### 7. Whole-unit mode
+
+When invoked as `<NN-slug>` with no step: loop all remaining steps, one commit
+each. After each step: gates, execute, diff guard (if implement), evidence/
+progress update, commit. Skip intermediate review checkpoints; the mandatory end
+review covers the full accumulated diff. On gate red at any step: repair that
+step (up to `--max-attempts`), then continue the loop. Terminal:
+
+```text
+UNIT LOOP — <unit> COMPLETE
+Steps: <n> · Commits: <sha list> · Gate: PASS
+PR: <url>
+
+→ Next: /review-change on the changed HEAD — the mandatory end review
+  · findings (REVIEW-FAIL) → /fold-findings repairs them; a fresh /review-change follows the fold
+  · merge gate after REVIEW-PASS → /audit-pr
+```
+
+### 8. Descope guard
+
+Before creating **any** issue while executing: classify with the descope test.
+A descope (moving an acceptance criterion or task out of scope) requires
+**explicit user approval first**, then record in the unit doc's
+`## References` section (not a follow-up issue) as:
+`- <YYYY-MM-DD> — descoped: "<criterion>" — approved by user`.
+An issue may never be the first record of a descope.
+
+## Required references
+
+These files must be loaded when their topic is active:
+- [PREFLIGHT.md](references/PREFLIGHT.md) — all gate blocks (dependency, status, pre-exec, evidence, lint, path-protection)
+- [EXECUTION_CONTRACT.md](references/EXECUTION_CONTRACT.md) — step completion gate, architectural invariants
+- [PRE_EXECUTION_GATE.md](references/PRE_EXECUTION_GATE.md) — pre-execution review gate, normalizer order
+- [FOLDING.md](references/FOLDING.md) — review finding fold cycle
+- [DESCOPE.md](references/DESCOPE.md) — descope test and amendment rule
+- [FORGE_BODY.md](references/FORGE_BODY.md) — forge operations (gh body-file rule)
+
+## Guardrails
+
+**Allowed:**
+- Only the triaged steps listed by the unit doc's Evidence header
+- Changes scoped to the acceptance criteria and step tasks
+- Documentation updates in the unit doc (Evidence, Progress, References)
+- Conventional commit messages per the project's Workflow conventions
+- The step's own reference file (read one-hop from the unit doc catalog)
+
+**Forbidden:**
+- Never commit red (test failure) — fix within the step's scope, or record the
+  blocker and stop.
+- Never weaken a validator (loosen assertions, reduce coverage) — a repair must
+  keep assertions at least as strong.
+- Never execute a step the triage skipped — the catalog is authoritative.
+- Never edit the unit doc's Acceptance criteria (that is re-triage with user consent).
+- Never expand scope beyond what Non-goals define — findings discovered during
+  implementation never widen the unit.
+- Never invent an acceptance criterion — ask the user with concrete options.
 
 ## Relationship to other skills
 
-Planned by `plan-feature`/`plan-fix`; executes their SPEC. Explicit phases may
-hand off to `review-change` at layer/accumulation/sensitivity checkpoints and must
-at unit end. Unit-loop skips intermediate checkpoints and recommends the manual
-`/review-change` → `/fold-findings` (only on `REVIEW-FAIL`) → re-run
-`/review-change` path after opening the PR; `review-change` remains the manual
-entry.
-Independent work stays a proposal. A finished unit always opens its PR and flips
-to `done`; `audit-pr` gates merge. Every invocation prints the next step.
+`unit-lane` conducts (triage → steps → doc updates); this executes (one step at a
+time or all remaining). `fold-findings` handles review finding repairs. The review
+pack axes (`review-implementation`, `review-code`, `review-security`, `review-perf`,
+`review-a11y`, `review-debt`) compose the review step; `workflow-status` routes
+here. `triage-issue` feeds issues into the lane. This skill is the **step executor**
+a turn invokes to perform one triaged step of a unit under the full gate machinery.
+
+## Portability (agents other than Claude Code)
+
+- **No slash menu** — open this `SKILL.md` and follow it literally in a fresh
+  conversation. Where it says `run`, execute the shell command directly.
+- **No model tiers** — triage and review use the strongest model; execution
+  steps may use cheaper. Never review with a weaker model than the author.
+- **No `/loop`/subagents** — invoke `<NN-slug>` for all remaining steps (the
+  built-in loop), or `<NN-slug> P<k>` for individual steps.
+- **No fresh workers** — execute inline and reduce state to the unit doc after
+  each commit; never re-read prior files.
 
 ## Done when
 
-- Requested scope is implemented (all remaining phases, one explicit phase, or
-  legacy pass), gate is green, per-phase docs are updated, and the work is
-  committed on the correct branch with nothing bundled beyond scope.
-- `git status --porcelain` is empty and an open-PR branch has nothing unpushed.
-- A finished unit is `done`, has an opened PR (URL printed), and recommends the
-  mandatory `/review-change` end review, then `/fold-findings` (only on
-  `REVIEW-FAIL`) and a re-run `/review-change`, with `/audit-pr`
-  as the merge gate.
+- Requested scope is implemented (all remaining steps, one explicit step), gate
+  is green, unit doc Evidence/Progress are current, and the work is committed.
+- **The closing `→ Next:` block is printed.**
+
+## Closing recommendation
+
+```
+→ Next: /unit-lane <NN-slug> — the conductor continues with the next triaged step
+  · all steps done → /review-change — the mandatory end review
+  · findings (REVIEW-FAIL) → /fold-findings repairs them; a fresh /review-change follows the fold
+  · merge gate after REVIEW-PASS → /audit-pr — the merge gate
+```

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

@@ -1,41 +1,45 @@
 ## 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
+A cheap way to look finished is to quietly convert unfinished unit 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, a
-  phase task, or an **obligation-ledger row** that is **not fully delivered** in
-  this unit. A `planning-obligations.md` row (or the SPEC's embedded `### Obligations`
-  table) is scope of the unit exactly like a criterion: moving one to "later" is a
-  descope, needs the same dated user amendment, and flips the row to `deferred` only
-  as part of that amendment (`pre-execution-review` owns the lifecycle).
-- **Discovered work** — everything else (genuinely new, outside the SPEC's
+- **Descope** — the issue's content overlaps an acceptance criterion, a step
+  task, or an obligation row that is **not fully delivered** in this unit. A
+  `planning-obligations.md` row (or the unit doc's embedded `### Obligations`
+  table) is scope of the unit exactly like a criterion: moving one to "later"
+  is a descope, needs the same dated user amendment, and flips the row to
+  `deferred` only as part of that amendment (`pre-execution-review` owns the
+  lifecycle).
+- **Discovered work** — everything else (genuinely new, outside the unit'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**:
+**user-approved, dated** entry in the unit doc's `## References` section (not
+the unit doc's `## Future cost` section, which captures future scope additions
+from the triage catalog, not step descopes):
 
 1. Get explicit user approval for the descope **first** (ask; never
-   self-authorize moving a criterion out of scope — the amendment row must
+   self-authorize moving a criterion out of scope — the entry 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:
+2. **Only then** move the criterion/task out of the active `## Acceptance`
+   (or `## Tasks` section), and record it in the unit doc's
+   `## References` 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
+   body. Immediately after, edit the `## References` 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, `product-audit`'s recurrence signal and
-`audit-pr`'s obligation-closure check all key off this same `## Amendments` log —
-it is the single authoritative record of every descope, defined once here. Nothing
-else in the pre-execution route creates an issue: a missing or failed
-`PLAN-REVIEW-PASS` is closed by `/review-plan`, never by a tracker item.
+`audit-pr`'s obligation-closure check all key off this same `## References` log
+— it is the single authoritative record of every descope, defined once here.
+Nothing else in the pre-execution route creates an issue: a missing or failed
+`PLAN-REVIEW-PASS` is closed by `/review-plan`, never by a tracker item.