@gtrabanco/pi-agentic-workflow 0.13.2 → 0.14.0

package/README.md

@@ -7,8 +7,8 @@ that gives your session back afterwards.
 
 - **Canonical skills, unchanged.** The package ships the same `SKILL.md` files as
   this repository, byte for byte — no Pi-specific fork to drift.
-- **Friendly commands.** Type `/plan-feature --next`, not
-  `/skill:plan-feature --next`.
+- **Friendly commands.** Type `/unit-lane <slug>`, not
+  `/skill:unit-lane <slug>`.
 - **Routing you can forget about.** Nothing is configured by default: every
   command runs on the model you already have.
 
@@ -36,21 +36,15 @@ their own — they are composed by the ones above:
 | --- | --- |
 | `/audit-docs` | Check that docs, roadmap, code and the fix index agree. |
 | `/audit-pr` | The merge gate: is this PR ready? |
-| `/design-feature` | Turn a raw idea into a designed SPEC. |
 | `/discover-repository-state` | Freeze verified repository facts. |
 | `/execute-phase` | Implement the remaining phases of a planned unit. |
 | `/fold-findings` | Repair persisted fix-now findings. |
-| `/generate-docs` | Generate incremental, diff-driven developer guides. |
 | `/init-workspace` | Adapt the workflow scaffold to a repository. |
 | `/log-session` | Append a structured session entry to `docs/LOGS.md`. |
-| `/plan-feature` | Route designed work into planning and the roadmap. |
-| `/plan-fix` | Draft a phased fix SPEC from one or more issues. |
 | `/product-audit` | Audit the product surface, not just the diff. |
 | `/resolve-repository-state` | Resolve a contradiction in frozen facts. |
 | `/review-change` | Review a change with the applicable axes. |
-| `/review-plan` | Review a frozen plan in a clean context. |
-| `/review-spec` | Review a designed SPEC in a clean context. |
-| `/ship-roadmap` | Find or continue a roadmap, one stage per run. |
+| `/unit-lane` | Run the adaptive lane on a unit: triage, steps, evidence, release. |
 | `/triage-issue` | Verify an issue or finding against current code. |
 | `/workflow-status` | Read-only state of the repository and roadmap. |
 

package/dist/routing/catalogue.d.ts

@@ -10,7 +10,7 @@ export interface SkillMeta {
  * Minimal frontmatter reader: `name`, `description`, `user-invocable` only.
  *
  * `user-invocable` must say `true` to count: this repository's own rule
- * (CLAUDE.md — the key "REQUIRED for it to appear in the agent's /command menu")
+ * (AGENTS.md — the key "REQUIRED for it to appear in the agent's /command menu")
  * makes absence mean internal, and `scripts/bundle-skills.mjs` reads it the same
  * way. The two scanners agree because the rule is stated once per scanner and
  * pinned by `test/alias-coverage.test.mjs`, not because either default is safe.

package/dist/routing/catalogue.js

@@ -16,7 +16,7 @@ const SKILL_FILE = "SKILL.md";
  * Minimal frontmatter reader: `name`, `description`, `user-invocable` only.
  *
  * `user-invocable` must say `true` to count: this repository's own rule
- * (CLAUDE.md — the key "REQUIRED for it to appear in the agent's /command menu")
+ * (AGENTS.md — the key "REQUIRED for it to appear in the agent's /command menu")
  * makes absence mean internal, and `scripts/bundle-skills.mjs` reads it the same
  * way. The two scanners agree because the rule is stated once per scanner and
  * pinned by `test/alias-coverage.test.mjs`, not because either default is safe.

package/dist/runtime.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Runtime resolver — determines what runtime pi itself runs under so
+ * spawned children inherit the same choice.
+ *
+ * The current process is always pi (this module lives inside the package
+ * that ships with pi). Whichever runtime launched pi decides what
+ * children get:
+ *  - pi installed via `bun add -g` → bun
+ *  - pi installed via `npm install -g` → node
+ *
+ * `AGENTIC_WORKFLOW_RUNTIME` env override is the highest priority: it
+ * always wins, letting the operator force a specific runtime regardless
+ * of how pi was installed.
+ *
+ * Exported from the package's public entry (compiled from src/ → dist/).
+ * Intended call site: wherever the extension spawns a `.mjs` script,
+ * use `runtimeBin()` + `runtimeEnv()` instead of a hardcoded `"node"`
+ * or `"bun"`.
+ */
+/**
+ * Detect the runtime of the *current process* (which is pi).
+ * Returns `"bun"` when `globalThis.Bun` exists, or when
+ * `process.execPath` contains the substring `"bun"`; otherwise `"node"`.
+ */
+export declare function detectRuntime(): "bun" | "node";
+/**
+ * Return an environment object for spawned children that ensures
+ * `AGENTIC_WORKFLOW_RUNTIME` is set.
+ *
+ * Priority:
+ * 1. If the caller passes an explicit value, use it (user override).
+ * 2. If `AGENTIC_WORKFLOW_RUNTIME` is already in `process.env`, use it.
+ * 3. Fall back to the detected runtime.
+ *
+ * Returns `{ AGENTIC_WORKFLOW_RUNTIME: "bun" | "node" }`.
+ */
+export declare function runtimeEnv(overrides?: {
+    AGENTIC_WORKFLOW_RUNTIME?: "bun" | "node";
+}): Record<string, string>;
+/**
+ * Return the executable name to spawn for running a script.
+ * Returns `"bun"` or `"node"` based on the detected runtime,
+ * respecting the `AGENTIC_WORKFLOW_RUNTIME` env override.
+ */
+export declare function runtimeBin(): "bun" | "node";

package/dist/runtime.js

@@ -0,0 +1,62 @@
+/**
+ * Runtime resolver — determines what runtime pi itself runs under so
+ * spawned children inherit the same choice.
+ *
+ * The current process is always pi (this module lives inside the package
+ * that ships with pi). Whichever runtime launched pi decides what
+ * children get:
+ *  - pi installed via `bun add -g` → bun
+ *  - pi installed via `npm install -g` → node
+ *
+ * `AGENTIC_WORKFLOW_RUNTIME` env override is the highest priority: it
+ * always wins, letting the operator force a specific runtime regardless
+ * of how pi was installed.
+ *
+ * Exported from the package's public entry (compiled from src/ → dist/).
+ * Intended call site: wherever the extension spawns a `.mjs` script,
+ * use `runtimeBin()` + `runtimeEnv()` instead of a hardcoded `"node"`
+ * or `"bun"`.
+ */
+/**
+ * Detect the runtime of the *current process* (which is pi).
+ * Returns `"bun"` when `globalThis.Bun` exists, or when
+ * `process.execPath` contains the substring `"bun"`; otherwise `"node"`.
+ */
+export function detectRuntime() {
+    if (globalThis.Bun !== undefined) {
+        return "bun";
+    }
+    const execPath = process.execPath ?? "";
+    if (execPath.includes("bun")) {
+        return "bun";
+    }
+    return "node";
+}
+/**
+ * Return an environment object for spawned children that ensures
+ * `AGENTIC_WORKFLOW_RUNTIME` is set.
+ *
+ * Priority:
+ * 1. If the caller passes an explicit value, use it (user override).
+ * 2. If `AGENTIC_WORKFLOW_RUNTIME` is already in `process.env`, use it.
+ * 3. Fall back to the detected runtime.
+ *
+ * Returns `{ AGENTIC_WORKFLOW_RUNTIME: "bun" | "node" }`.
+ */
+export function runtimeEnv(overrides) {
+    const value = overrides?.AGENTIC_WORKFLOW_RUNTIME ??
+        process.env.AGENTIC_WORKFLOW_RUNTIME ??
+        detectRuntime();
+    return { AGENTIC_WORKFLOW_RUNTIME: value };
+}
+/**
+ * Return the executable name to spawn for running a script.
+ * Returns `"bun"` or `"node"` based on the detected runtime,
+ * respecting the `AGENTIC_WORKFLOW_RUNTIME` env override.
+ */
+export function runtimeBin() {
+    const env = process.env.AGENTIC_WORKFLOW_RUNTIME;
+    if (env === "bun" || env === "node")
+        return env;
+    return detectRuntime();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -44,18 +44,20 @@
   "scripts": {
     "build": "tsc",
     "bundle:skills": "bun scripts/bundle-skills.mjs",
-    "bundle:skills:check": "bun scripts/bundle-skills.mjs --check",
-    "test": "tsc && bun test test/*.test.mjs",
-    "test:node": "tsc && node --test test/*.test.mjs",
-    "prepublishOnly": "bun run build && bun run test",
-    "mutation": "bun scripts/mutation-check.mjs",
-    "prepare": "bun run build"
+    "clean:skills": "bun scripts/bundle-skills.mjs --clean",
+    "test": "bun run bundle:skills && tsc && bun test test/*.test.mjs",
+    "test:node": "bun run bundle:skills && tsc && node --test test/*.test.mjs",
+    "prepublishOnly": "bun run build && bun run bundle:skills && bun run test",
+    "postpack": "bun run clean:skills",
+    "mutation": "bun run bundle:skills && bun scripts/mutation-check.mjs",
+    "prepare": "bun run build && bun run bundle:skills"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.87.0"
   },
   "dependencies": {
-    "@earendil-works/pi-tui": "0.87.0"
+    "@earendil-works/pi-tui": "0.87.0",
+    "@gtrabanco/agentic-workflow": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

package/skills/audit-docs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-docs
 user-invocable: true
-version: 2.1.0
+version: 2.1.1
 argument-hint: "[--fix]"
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -11,7 +11,8 @@ description: >
   entries already merged/closed, broken documentation-map links, dependency
   cycles, artifacts in the wrong language, naming-convention violations — and
   reports them ranked by severity, fixing only low-risk items on request.
-  On Claude Code and want hand-tuned per-skill model/effort tiers? Install the `#claude` branch instead (`npx skills add gtrabanco/agentic-workflow#claude`) — see the README. This branch is model-agnostic: the skill inherits whatever model and effort your agent session is already using.
+  Model-agnostic: the skill inherits whatever model and effort your agent
+  session is already using.
   Triggers: "check doc consistency", "are the docs in sync", "audit the docs",
   "doc coherence review", "did the docs drift", "validate the roadmap".
 ---
@@ -93,12 +94,12 @@ run the command shown, don't infer.
     feature/fix-scoped changes committed directly without a PR: HIGH.
 13. **Generated-docs provenance (only when the documentation map declares a
     `Docs site` block; otherwise state n/a).** Scan the declared content dir
-    for pages carrying `generated-by: agentic-workflow/generate-docs`. For
+    for orphan pages
     each: (a) its `source-unit` exists in the roadmap or fix index — no match
     is an **orphan** (low: propose deletion or re-attribution); (b) the
     unit's PR merged **after** the page's `updated` date with commits touching
     the page's subject paths — that page is **stale** (LOW: propose
-    `/generate-docs <unit>` to refresh). Cite page path + unit per finding.
+). Cite page path + unit per finding.
 14. **Commit format & dependency discipline.** Sample the unit branches'
     commits: `<type>(<scope>): <summary>` conventional format (violations:
     LOW). Every `in-progress`/`done` row's `Depends on:` closure was merged —
@@ -149,7 +150,7 @@ enables:
 - **No slash-command menu** — where this skill says `/<skill>`, open that
   skill's `SKILL.md` (wherever your agent installed the skills) and follow it
   literally, in a fresh conversation: hand-offs assume a clean context.
-- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+- **No per-skill `model:`/`effort:`** — no skill pins a tier; pick tiers yourself:
   these are mostly mechanical cross-document checks — a mid-tier model is
   enough; escalate to your strongest only for a deep audit.
 

package/skills/audit-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-pr
 user-invocable: true
-version: 5.3.0
+version: 5.3.1
 argument-hint: <pr-number> (optional — defaults to the current branch's PR)
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/audit-pr/references/PORTABILITY.md

@@ -7,7 +7,7 @@ enables:
 - **No slash-command menu** — where this skill says `/<skill>`, open that
   skill's `SKILL.md` (wherever your agent installed the skills) and follow it
   literally, in a fresh conversation: hand-offs assume a clean context.
-- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+- **No per-skill `model:`/`effort:`** — no skill pins a tier; pick tiers yourself:
   the merge gate is the highest-stakes automated verdict — run it on your
   **strongest** model, never on the cheap tier that wrote the code.
 - **Receipt consumption is comment-based, not forge-branded.** The

package/skills/execute-phase/SKILL.md

@@ -1,138 +1,229 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 4.7.0
-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
+```