Claude Cursor opencode Skill

execute-phase

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.

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download gtrabanco-agentic-workflow-skills_execute-phase-88248cc.zip · 28 KB

Install

skills CLI npx skills add https://github.com/gtrabanco/agentic-workflow/tree/main/skills/execute-phase
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gtrabanco-agentic-workflow@llmmart
Git git clone https://github.com/gtrabanco/agentic-workflow.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gtrabanco/agentic-workflow collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Execute Phase

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.

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)

Never infer a step ID absent from the triage block in the unit doc.

Turn contract

Tick every box before ending the turn; an unchecked box means the turn is not done:

✓ Required user inputs were answered concretely (not defaulted). Nothing here
  is inferred: a gap runs `bun scripts/needs-input.mjs <unit-dir>` (node fallback
if bun is not installed) and the
  `open-questions@1` block is pasted, then the run stops.
✓ Tool choice re-made this turn — `bun` before `node` on manual invocation,
  `rg` before `grep` on search; availability checked once with
  `node scripts/setup-env.mjs --check` (node and grep stay the documented fallback)
✓ 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)
✓ Test impact derived — the phase's test set came from the hint's block
  (TEST_IMPACT.md), and a prose-only phase recorded its `empty` verdict
✓ Evidence rows updated (command → exit/digest → output → verified-by)
  — each row carries the command, observed output (reproduced, not typed by
  hand), and the verifying-by credit. (S5 — claim-evidence loop: mandatory
  reproduction, loop-until-green inside the same turn)
✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry that names the
  phase id (what, commit, next)
✓ Memory boundary ran — the phase's outcome saved under `unit/<NN-slug>/doc`,
  or the mirror marked pending when the layer is degraded
✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
✓ Self-audit box (S9 d): every claim the persist introduces was re-derived
  with pasted output before the commit lands.
✓ → 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).

Inputs — artifacts, never questions

This skill never interviews. It reads its inputs — the unit doc's Tasks, unit-route.mjs --triage's block, the route's tier — and a missing or ambiguous one is a gap, resolved in one fixed order and never by inference: (0) provenance (search the repo's own docs and record where) → (1) research (2–3 concrete options with trade-offs; asking for more research is a legitimate answer) → (2) halt: run bun scripts/needs-input.mjs <unit-dir> (node fallback if bun is not installed), paste the open-questions@1 block verbatim, stop. Interactive the block is the pause point, unattended it is a hard fail. Grammar and exit codes: orchestration-envelope's references/TURN_CONTRACT.md §Open questions.

Bare <NN-slug> runs all remaining steps — the phase is not an input. File targets are the unit doc's nested Relevant files: metadata plus the path-protection checkpoint. --max-attempts N defaults to 3; --force skips the stop on the dependency and phase-lint gates (never the check — PREFLIGHT.md records the override in the Progress log) and has no bypass on the path-protection checkpoint.

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) and the receipt sections of the shape it is written in (#308 accepts both): the legacy shape carries ## Evidence + ## Progress log, a re-cut unit doc carries ## Specs, ## Findings + ## Log (its evidence and gate runs are E/G log lines, its progress is P lines). If neither pair is present, the unit is not ready — stop and suggest unit-lane triage first. scripts/unit-route.mjs resolves the shape; never judge a re-cut unit by the legacy headings and stop it.

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

The ceremony belongs to the risk tier (risk-tiers.md owns that table). A phase never lowers its own tier.

3. Pre-step gates

Run gates in order; any fails → STOP (see 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): 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: derive the test set first (TEST_IMPACT.md owns the block and the RED-evidence shape) and write tests-first where they pay (core/domain, orchestration) — a new script+suite pair lands red-first: suite commits red (observed failing, naming the targeted suite), implementation green; UI/adapter glue may test after.

5. Claim-evidence loop (S5 — before post-step)

Before running post-step, verify every claim the step's repair introduces. This is the repairer-owned verification that prevents the unit 79 F50-class failure (closed gate-green with an unreproduced figure "170" without re-deriving via git diff --numstat).

  1. Claim ledger. Enumerate every claim: each new figure, cross-reference, "X is now Y"; in code: each behavior the step declares.
  2. Mandatory reproduction. Re-derive the figure with the command, resolve the reference with grep, reproduce the behavior. Paste command + observed output into the claim table — never type the expected result by hand.
  3. Loop until green. red → repair → re-run, inside the same turn, until every claim verifies.
  4. Admission rule. If no command can verify the sentence, it is not a claim, it is an opinion, and it does not get written.

Output:

| claim | command | output | status |
|---|---|---|---|
| <claim> | `<command>` | `<observed output>` | ✓ |

The row shape is published grammar (evidence-row@1 in @gtrabanco/agentic-workflow-schema), so a row missing its command, its observed output or a ✓/✗ verdict is a shape violation rather than a style nit.

Bounded checkpoint (S13/S14). The claim-evidence loop is only paid if it is cheap: bun scripts/test-route.mjs --check <changed path> names the minimal suite a path needs, so an intermediate verification costs seconds instead of the full gate. An unmatched path answers route: full-suite — never fewer tests — and the full gate stays what the merge gate and CI run.

6. 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, reproduced via command, not typed by hand) | verified-by | — append to the Evidence section. The evidence row is a reproduced receipt, not an assertion (S5: mandatory reproduction extends to doc artifacts).
  3. Progress log: append a dated entry — YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>.
  4. Memory boundary — this step is a phase transition. Follow the memory protocol: before the first memory read run agentic-workflow memory probe once and record its verdict in Evidence; after the step, save the phase id, what it changed, its Evidence outcome and any discovery under topic_key: "unit/<NN-slug>/doc", an explicit project and explicit session attribution (§5). A degraded verdict is recorded and the mirror marked pending — it never blocks the step.
  5. Commit: git add <changed files> then git commit -m "<type>(<scope>): <step-summary>" — run it, paste the SHA.

7. 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:

    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>>
    

8. Whole-unit mode

When invoked as <NN-slug> with no step: loop all remaining steps, one commit each. This is an explicit operator choice only — the lane's hand-offs always name exactly one phase (<NN-slug> P<k>), so a bare <NN-slug> from a lane hand-off is a defect; re-read the hand-off before looping. 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. The close-out is part of the last step's completion: open the PR on main with Closes #N, write - PR: <url> into References, and settle the index row with agentic-workflow roadmap <index> rowUpsert '<json>' (docs/ROADMAP.md; a fix unit edits its row in that document's ## Fixes table — no NN column, no rowUpsert). bun scripts/roadmap-settle.mjs exits 0 (#316). Terminal:

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

9. 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:

Guardrails

  • The all-stages no-assumption rule binds every step here — ask-don't-infer, owner skills/unit-lane/references/DESIGN.md (ask-dont-infer@1): an expectation the tree, the docs, or a prior owner decision does not evidence is asked, never invented.

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 write to docs/LOGS.md (S9 4b): LOGS.md must be pure code output — no model writes it. The journal is append-only: a wrong past line gets a new correcting line, never an edit. Machine-authored git-facts entries (the extension's autoLogSession: mechanical, #394) also kill the "hand-tallied figure" class.
  • Self-audit box (S9 d): before committing, re-derive every claim the step's persist introduces with pasted output. The turn does not end with unreproduced claims.
  • 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

unit-lane conducts (triage → judgment steps → close-out ladder) and hands execution off one phase per turn (<NN-slug> P<k> with the catalog tier); this executes the named phase — or, as an explicit operator choice only, all remaining steps. The closing hand-off names exactly one phase and the tier while phases remain, and resumes the lane after the last one. 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 (the named phase, or all remaining steps in an explicit operator run), gate is green, unit doc Evidence/Progress are current (the Progress entry names the phase id), and the work is committed.
  • The closing → Next: block is printed.

Closing recommendation

Exactly one end-state applies — pick by the unit's Tasks section, never print a phase id the Tasks section does not define:

Phases remain:

→ Next: /execute-phase <NN-slug> P<k+1> (tier: <tier>) — one phase per turn; <tier> is the catalog's implement entry
  · whole-unit operator run complete → /review-change (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

The last phase just closed (a lane-run unit):

→ Next: /unit-lane <NN-slug> — resume the conductor for the remaining judgment steps
  · whole-unit operator run complete → /review-change (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
Files (agentic-workflow)
  • references
    • DESCOPE.md 2.5 KB
      Loading…
    • EXECUTION_CONTRACT.md 8.4 KB
      Loading…
    • FOLDING.md 6.6 KB
      Loading…
    • FORGE_BODY.md 2 KB
      Loading…
    • PREFLIGHT.md 10.9 KB
      Loading…
    • PRE_EXECUTION_GATE.md 3.9 KB
      Loading…
    • risk-tiers.md 5.5 KB
      Loading…
    • TEST_IMPACT.md 3.9 KB
      Loading…
  • SKILL.md 18.3 KB
    ---
    name: execute-phase
    user-invocable: true
    version: 4.10.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: >
      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
    
    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.
    
    **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)
    
    Never infer a step ID absent from the triage block in the unit doc.
    
    ## Turn contract
    
    Tick every box before ending the turn; an unchecked box means the turn is not
    done:
    
    ```
    ✓ Required user inputs were answered concretely (not defaulted). Nothing here
      is inferred: a gap runs `bun scripts/needs-input.mjs <unit-dir>` (node fallback
    if bun is not installed) and the
      `open-questions@1` block is pasted, then the run stops.
    ✓ Tool choice re-made this turn — `bun` before `node` on manual invocation,
      `rg` before `grep` on search; availability checked once with
      `node scripts/setup-env.mjs --check` (node and grep stay the documented fallback)
    ✓ 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)
    ✓ Test impact derived — the phase's test set came from the hint's block
      (TEST_IMPACT.md), and a prose-only phase recorded its `empty` verdict
    ✓ Evidence rows updated (command → exit/digest → output → verified-by)
      — each row carries the command, observed output (reproduced, not typed by
      hand), and the verifying-by credit. (S5 — claim-evidence loop: mandatory
      reproduction, loop-until-green inside the same turn)
    ✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry that names the
      phase id (what, commit, next)
    ✓ Memory boundary ran — the phase's outcome saved under `unit/<NN-slug>/doc`,
      or the mirror marked pending when the layer is degraded
    ✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
    ✓ Self-audit box (S9 d): every claim the persist introduces was re-derived
      with pasted output before the commit lands.
    ✓ → 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).
    
    ## Inputs — artifacts, never questions
    
    This skill **never interviews**. It reads its inputs — the unit doc's `Tasks`,
    `unit-route.mjs --triage`'s block, the route's tier — and a missing or ambiguous
    one is a **gap**, resolved in one fixed order and never by inference:
    **(0) provenance** (search the repo's own docs and record where) →
    **(1) research** (2–3 concrete options with trade-offs; asking for more research
    is a legitimate answer) → **(2) halt**: run `bun scripts/needs-input.mjs
    <unit-dir>` (node fallback if bun is not installed), paste the `open-questions@1` block verbatim, stop. Interactive the
    block is the pause point, unattended it is a hard fail. Grammar and exit codes:
    `orchestration-envelope`'s `references/TURN_CONTRACT.md` §Open questions.
    
    Bare `<NN-slug>` runs **all remaining steps** — the phase is not an input. File
    targets are the unit doc's nested `Relevant files:` metadata plus the
    path-protection checkpoint. `--max-attempts N` defaults to 3; `--force` skips the
    *stop* on the dependency and phase-lint gates (never the check — `PREFLIGHT.md`
    records the override in the Progress log) and has **no bypass** on the
    path-protection checkpoint.
    
    ## 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)
    **and the receipt sections of the shape it is written in** (#308 accepts both):
    the legacy shape carries `## Evidence` + `## Progress log`, a re-cut unit doc carries
    `## Specs`, `## Findings` + `## Log` (its evidence and gate runs are `E`/`G` log
    lines, its progress is `P` lines). If neither pair is present, the unit is not ready —
    stop and suggest `unit-lane` triage first. `scripts/unit-route.mjs` resolves the
    shape; never judge a re-cut unit by the legacy headings and stop it.
    
    ## 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.
    
    **The ceremony belongs to the risk tier** ([risk-tiers.md](references/risk-tiers.md)
    owns that table). A phase never lowers its own tier.
    
    ### 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: derive the test set first ([TEST_IMPACT.md](references/TEST_IMPACT.md)
    owns the block and the RED-evidence shape) and write tests-first where they pay
    (core/domain, orchestration) — a new script+suite pair lands red-first: suite
    commits red (observed failing, naming the targeted suite), implementation green;
    UI/adapter glue may test after.
    
    ### 5. Claim-evidence loop (S5 — before post-step)
    
    Before running post-step, verify every claim the step's repair introduces. This
    is the repairer-owned verification that prevents the unit 79 F50-class failure
    (closed gate-green with an unreproduced figure "170" without re-deriving via
    `git diff --numstat`).
    
    1. **Claim ledger.** Enumerate every claim: each new figure, cross-reference,
       "X is now Y"; in code: each behavior the step declares.
    2. **Mandatory reproduction.** Re-derive the figure with the command, resolve
       the reference with grep, reproduce the behavior. Paste command + observed
       output into the claim table — never type the expected result by hand.
    3. **Loop until green.** red → repair → re-run, *inside the same turn*, until
       every claim verifies.
    4. **Admission rule.** If no command can verify the sentence, it is not a
       claim, it is an opinion, and it does not get written.
    
    Output:
    
    ```
    | claim | command | output | status |
    |---|---|---|---|
    | <claim> | `<command>` | `<observed output>` | ✓ |
    ```
    
    The row shape is published grammar (`evidence-row@1` in
    `@gtrabanco/agentic-workflow-schema`), so a row missing its command, its
    observed output or a ✓/✗ verdict is a shape violation rather than a style nit.
    
    **Bounded checkpoint (S13/S14).** The claim-evidence loop is only paid if it is
    cheap: `bun scripts/test-route.mjs --check <changed path>` names the minimal
    suite a path needs, so an intermediate verification costs seconds instead of the
    full gate. An unmatched path answers `route: full-suite` — never fewer tests —
    and the full gate stays what the merge gate and CI run.
    
    ### 6. 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, reproduced via command, not typed by hand) | verified-by |`
       — append to the Evidence section. The evidence row is a *reproduced receipt*,
       not an assertion (S5: mandatory reproduction extends to doc artifacts).
    3. **Progress log**: append a dated entry —
       `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>`.
    4. **Memory boundary** — this step is a phase transition. Follow
       [the memory protocol](../unit-lane/references/MEMORY.md): before the first
       memory read run `agentic-workflow memory probe` once and record its verdict
       in Evidence; after the step, save the phase id, what it changed, its Evidence
       outcome and any discovery under `topic_key: "unit/<NN-slug>/doc"`, an explicit
       `project` and explicit session attribution (§5). A `degraded` verdict is
       recorded and the mirror marked pending — it never blocks the step.
    5. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
       <step-summary>"` — run it, paste the SHA.
    
    ### 7. 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>>
      ```
    
    ### 8. Whole-unit mode
    
    When invoked as `<NN-slug>` with no step: loop all remaining steps, one commit
    each. This is an **explicit operator choice only** — the lane's hand-offs
    always name exactly one phase (`<NN-slug> P<k>`), so a bare `<NN-slug>` from a
    lane hand-off is a defect; re-read the hand-off before looping. 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. The close-out is part of the last
    step's completion: open the PR on `main` with `Closes #N`, write `- PR: <url>`
    into References, and settle the index row with `agentic-workflow roadmap
    <index> rowUpsert '<json>'` (`docs/ROADMAP.md`; a fix unit edits its row in that
    document's `## Fixes` table — no `NN` column, no `rowUpsert`).
    `bun scripts/roadmap-settle.mjs` exits 0 (#316).
    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
    ```
    
    ### 9. 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)
    - [TEST_IMPACT.md](references/TEST_IMPACT.md) — the impact set, its block, the empty-impact verdict and the RED-evidence shape
    - [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
    
    - The all-stages no-assumption rule binds every step here — **ask-don't-infer**,
      owner `skills/unit-lane/references/DESIGN.md` (`ask-dont-infer@1`): an
      expectation the tree, the docs, or a prior owner decision does not evidence
      is asked, never invented.
    
    **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 write to `docs/LOGS.md` (S9 4b): LOGS.md must be pure code output —
      no model writes it. The journal is append-only: a wrong past line gets a
      *new correcting line*, never an edit. Machine-authored git-facts entries
      (the extension's `autoLogSession: mechanical`, #394) also kill the
      "hand-tallied figure" class.
    - Self-audit box (S9 d): before committing, re-derive every claim the step's
      persist introduces with pasted output. The turn does not end with unreproduced
      claims.
    - 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
    
    `unit-lane` conducts (triage → judgment steps → close-out ladder) and hands
    execution off **one phase per turn** (`<NN-slug> P<k>` with the catalog tier);
    this executes the named phase — or, as an explicit operator choice only, all
    remaining steps. The closing hand-off names exactly one phase and the tier
    while phases remain, and resumes the lane after the last one.
    `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 (the named phase, or all remaining steps in an
      explicit operator run), gate is green, unit doc Evidence/Progress are current
      (the Progress entry names the phase id), and the work is committed.
    - **The closing `→ Next:` block is printed.**
    
    ## Closing recommendation
    
    Exactly one end-state applies — pick by the unit's Tasks section, never print a
    phase id the Tasks section does not define:
    
    Phases remain:
    
    ```
    → Next: /execute-phase <NN-slug> P<k+1> (tier: <tier>) — one phase per turn; <tier> is the catalog's implement entry
      · whole-unit operator run complete → /review-change (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
    ```
    
    The last phase just closed (a lane-run unit):
    
    ```
    → Next: /unit-lane <NN-slug> — resume the conductor for the remaining judgment steps
      · whole-unit operator run complete → /review-change (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
    ```

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.