Harness

---
name: harness
owner: baseline
description: End-to-end workflow orchestrator. Walks the 11-phase pipeline, invoking each phase skill in order inside an internal loop, yielding at consent gates (/approve-direction, /approve-swarm, /grant-commit), and exiting cleanly on yield/failure/done. Decides swarm-vs-solo at Phase 6. Auto-loops /tdd on integrate failures that don't require a spec change. The harness_continuation Stop hook is a safety net that re-fires harness only when the loop exited mid-flow.
argument-hint: "[optional: \"<request in plain English>\" on fresh start]"
---

# harness — workflow orchestrator with internal loop

User-invokable and model-invokable. The harness chains the 11-phase pipeline by **looping internally through non-gated phases** until the loop hits one of four exit conditions: consent gate, phase-skill failure, integrate-failure-needs-spec-change, or workflow done. The user types only at consent gates (`/approve-direction`, `/approve-swarm`, `/grant-commit`) and at integrate-failure decisions that need a spec change.

## Internal loop atomicity (the contract)

A single `Skill(harness)` invocation **loops through every non-gated phase boundary** in one user turn. Inside the loop, each iteration invokes exactly one phase skill via the `Skill` tool, updates state and TaskList, then re-enters the loop. The loop exits — and the model emits its terminal message — only when one of these four conditions holds:

- **Yield**: the next pending task carries `metadata.needs_user: true` (consent gate, or integrate-failure-needs-spec-change). Write `harness_state: yielded`; surface the gate; exit.
- **Phase-skill failure**: a `Skill(<phase>)` call returned error. Write `harness_state: yielded` with `reason: "<phase> failed: <summary>"`; surface; exit.
- **Done**: `workflow.json → completed` now contains every non-excepted phase. Write `harness_state: done`; surface completion; exit.
- **(Rare) Mid-loop interruption**: the model decides to stop emitting before any of the above (context pressure, runtime limit, external interruption). The on-disk state stays `state: continue` with the marker present — the Stop hook safety net handles this.

`.claude/state/harness_state` is flat JSON with one of four states:

- `continue` — the harness is in the loop body (or was interrupted mid-loop). The Stop hook safety net is armed.
- `yielded` — the loop exited cleanly at a gate or failure. Stop hook stays silent.
- `done` — the loop exited cleanly at workflow completion. Stop hook stays silent.
- `parked` — a caller owns this session and the loop is not to be resumed. Stop hook stays silent, and stays silent even with the marker present, because a park happens inside an armed loop. Preflight step 6 clears it on the next `/harness`.

The state file shape:

```json
{
  "state": "continue|yielded|done|parked",
  "slug": "<workflow slug>",
  "reason": "<one sentence>"
}
```

**Parking (the fourth state).** `swarm-dispatch` sets `parked` before it raises a wave barrier and clears it on every exit from that wave. It exists because `run_in_background: true` workers keep running past the turn boundary, so Path A would re-fire the loop into a phase whose predecessor has not finished.

The rule is **declare, don't detect**. The rejected alternative was a registry the hook reads to infer whether work is in flight; every version of that fails in the wrong direction, because a registry left behind by a crashed wave silences the Stop hook permanently with no signal. A park left behind by a crashed wave costs the human one `/harness`.

Anything that needs to own the session uses this same state. Do not add a per-blocker boolean.

Exactly three fields. No `written_at`, no `tick_count` — those tunables were removed in the active-marker redesign. The internal-loop redesign retains the shape; the meaning of `state: continue` shifted from "next tick will be auto-fired by the hook" to "the harness is inside the loop body (or was interrupted)".

### The safety net

The `harness_continuation` Stop hook (Article VIII) is a **disjunctive** gate with two emission paths, neither of which is the primary phase-driver — the loop is. Both are gated by rung 1 (`stop_hook_active` absent on the payload).

- **Path A — the safety net** (rungs 2+3): `.harness_active` marker exists AND `state == "continue"`. It emits `{"decision":"block","reason":"…invoke Skill(harness)…"}` **only when the loop exited mid-flow** without writing `yielded`/`done` — the arm-but-did-not-exit-cleanly path. When the loop runs to gate/failure/done, Path A sees `state != continue` or the marker absent and stays silent.
- **Path B — consent-resume** (rung 4): `state == "yielded"` AND `workflow.json` parses AND a consent/approval token (`commit_consent`, `push_consent`, `spec_approvals/<slug>.approval`, `swarm_approvals/<slug>.approval`) has mtime newer than `harness_state`. This is the **normal case at a satisfied gate**: the user's just-typed `/grant-commit` (or `/approve-direction`, `/approve-swarm`, `/grant-push`) resumes the workflow on the same turn, with no second `/harness`. A gate that is still *pending* has no fresh token, so Path B cannot fire early.

Expect Path B to fire every time you resume from a consent gate — it is not a misfire. The hook logs which path it took to `.claude/state/logs/harness_continuation.log`; read that before diagnosing. Authoritative text: `seed.md` §4.1 + §4.2. Drift history: `docs/rca/2026-08-06-harness-continuation-false-misfire.md`.

### Marker-then-state ordering (every state-write)

Before writing `harness_state`, do the marker op FIRST:

- On `state: "continue"` → `echo "<slug>" > .claude/state/.harness_active` (creates or refreshes the marker).
- On `state: "yielded"` or `state: "done"` → `rm -f .claude/state/.harness_active` (deletes; safe if absent).

THEN write `harness_state`. The marker is the session-scoped "in the loop" signal; partial-write resilience requires marker-first ordering so a crash between steps leaves the conservative state on disk.

### Yield notifier (CO-D)

Whenever the harness writes `harness_state` with `state: "yielded"` — at **any** of the three yield exits (the consent-gate yield in loop step 4, the phase-skill-failure yield, and the integrate-needs-spec-change surface) — it SHALL, immediately after that write, run:

```
node .claude/skills/harness/notify.mjs emit --slug <slug>
```

This pings the human that their attention is needed (a consent gate or a failure), batched into one message naming the workflow and what to do — an action-first body (`<slug> needs your attention: /approve-direction`) under a clean `Claude Code` title. The emit path fires **only** on `yielded` — never on a `state: "continue"` refresh or a `state: "done"` completion. It is **best-effort and non-blocking**: it always exits 0, even when no notifier is present, so it can never stall the loop. Delivery is **OS-agnostic**, degrading through a probed chain: on macOS the optional `terminal-notifier` (clickable — a click focuses the terminal running Claude Code, via `-activate` on the `$TERM_PROGRAM` bundle id) when it is on `PATH`, then the platform's native notifier (`osascript` on macOS, `notify-send` on Linux, a PowerShell balloon on Windows), then a universal terminal fallback (BEL + a one-line stderr banner) on any other platform or when nothing native exists. `terminal-notifier` is probed like every channel and **never required** — no dependency is added and the notifier is fully functional without it (just without the click affordance; Linux/Windows click-to-focus is deferred). Gated by `project.json → velocity.notifier.enabled` (default on; set false to silence, e.g. in CI). `notify.mjs` is a baseline-owned, manifest-hashed helper.

**Stop-event mode (`on_stop` policy).** Beyond the yield ping, `notify.mjs` is also wired as a third **`Stop`** hook command (`node .claude/skills/harness/notify.mjs stop`, after `memory_stop` and `harness_continuation`; order-independent — it reads state files, not other hooks' decisions), so the human can be pinged when the session goes **idle**, not only when it needs attention. The `stop` sub-command reads the Stop payload from stdin and honours `project.json → velocity.notifier.on_stop`:

- `yielded` — **read-time default** (absent key resolves here). No stop-mode notifications; today's yield-only behaviour is preserved for any config predating the key.
- `idle` — notify when the session genuinely hands control back. This is the **inverse of `harness_continuation`'s re-fire decision**: it stays silent when the loop is alive (`stop_hook_active` truthy, or `state: "continue"` with the `.harness_active` marker present) and when `state` is already `"yielded"` (the emit path announced that). It pings on `state: "done"`, a missing `harness_state` (plain chat turn end), or a `continue`-without-marker (interrupted-terminal). No double-notify at a yield.
- `always` — ping on every real stop.

Same `enabled` gate, same delivery chain, same always-exit-0 contract. The **shipped template** (`src/project.template.json`) sets `on_stop: "idle"`, so a project taking the new template opts into idle pings by default; the read-time default keeps un-upgraded configs unchanged.

**Attention mode (input-wait pings).** The yield and stop modes both miss the moment the session blocks *mid-turn* on the human — an `AskUserQuestion` prompt, a permission dialog, or 60s of idle input. `notify.mjs` is therefore also wired as `node .claude/skills/harness/notify.mjs attention` on three seams: the **`Notification`** event (matchers `permission_prompt` + `idle_prompt`) and a **`PreToolUse`** matcher on `AskUserQuestion` (which does *not* fire the `Notification` event — confirmed gap, so the PreToolUse seam is required). The `attention` sub-command reads the payload from stdin and composes the body from `payload.message` (Notification) or `tool_input.questions[0].header` (AskUserQuestion), falling back to a generic "waiting for your input". Gated by `velocity.notifier.attention` (default `true`). Like the Stop wiring, `notify.mjs` lives under `.claude/skills/` so these seams add **no hook file** and no count cascade.

**Presence-aware suppression (`presence` policy).** To avoid pinging the human when they are already watching, the **idle-stop and attention** pings pass through a presence gate (the emit/yield path is exempt — a consent-gate yield is rare and high-value, so it always pings). Gated by `velocity.notifier.presence`:

- `always` — **read-time default** and the shipped-template default. No presence probe; every idle/attention ping fires. Un-upgraded and consumer configs are unchanged.
- `aware` — suppress the ping only when the probe proves the user is watching: the frontmost app is the session's own terminal (`bundleIdFor($TERM_PROGRAM)`) **and** HID idle ≤ `velocity.notifier.present_idle_seconds` (default 60). Any unknown signal — probe failure, non-macOS, `$TERM_PROGRAM` absent, a different frontmost app, or idle beyond the threshold — **fails open and notifies**. macOS-first: `probePresence` shells out to `ioreg` (HID idle) and `lsappinfo` (frontmost bundle id); off-darwin it returns nulls, so `presence: "aware"` degrades to today's always-notify there. This repo's `.claude/project.json` opts into `aware`; the shipped template stays `always`.

**State-write discipline (binding — see `.claude/CONSTITUTION.md` §2 "State-write discipline").** `.harness_active`, `harness_state`, and `harness/<slug>.log` are **Tier 2 workflow state** — not consent paths, not guard-blocked. The marker *refresh* (`echo "<slug>" > .claude/state/.harness_active`) uses a shell **builtin** redirect and is PATH-independent; the marker *delete* (`rm -f`) is the sole sanctioned external-binary exception (there is no builtin delete). Prefer the **Write tool** for the `harness_state` JSON. Never use `tee` or `sed -i`, and resolve any paths with Read/Glob, never `dirname`/`basename`.

## Preflight (once per Skill(harness) invocation, before entering the loop)

1. **Project configured?** Read `.claude/project.json`. If `configured: false` → stop with: "Run `/init-project` first. The baseline hooks are in guide mode until the project is configured."
2. **Continuity check.** Read `.claude/memory/_resume.md` if present. This is the cross-session snapshot written by the PreCompact and Stop hooks; it tells you what the prior session was actually doing in conversational terms.
3. **Fresh start or resume?**
   - `.claude/state/workflow.json` exists → **resume**.
   - Absent → **fresh start**. The argument (or surrounding conversation) is the request; proceed to Pillar 1.
3a. **Pre-§18 workflow.json migrator (post-§18 baseline).** If `workflow.json` carries the pre-§18 shape (has `entry_phase`, no `track_id`), run a one-shot migrator before continuing: `node .claude/skills/harness/cli.mjs migrate .claude/state/workflow.json` (wraps `workflow-migrator.js -> migrateWorkflowJsonInPlace`). The migrator derives `track_id` from `entry_phase` via the canonical map (intake → intake-full, spec → spec-entry, tdd → tdd-quickfix, chore → chore), remaps `completed[]` phase-names to node-ids, initializes `skipped_alternates: []`, refreshes `updated_at`, and removes `entry_phase`. Idempotent: already-post-§18 input is a no-op. Unmapped `entry_phase` throws; halt with the migrator's error message and tell the user to re-run `/triage` to restart this workflow.
4. **Ground the user before acting.** When `_resume.md` is present, open with one sentence summarizing where things stood. Grounding only — do not invent state not in `workflow.json`.
5. **Detect divergence.** If `_resume.md`'s recent prompts contradict `workflow.json` (e.g., the user said "actually skip security" mid-session and `exceptions` doesn't reflect it), do **not** auto-proceed. Surface as a clarifying question. Memory accelerates triage; it never authorizes a skip.
6. **Arm the safety net.** Marker FIRST: `echo "<slug>" > .claude/state/.harness_active`. Then write `harness_state` with `{state: "continue", slug, reason: "loop armed; preflight passed"}`. This pair stays in place for the entire loop; mid-loop crashes are now covered by the Stop hook. **This is also the rearm after a park** — the write replaces `parked` unconditionally, which is what makes typing `/harness` the whole recovery from a swarm wave that died mid-flight. Say so in the terminal message when the state you replaced was `parked`, so the user knows the loop resumed rather than started over.
6a. **Capture the right-size baseline (first arm only).** Run `node .claude/skills/harness/rightsize-gate.mjs baseline --slug <slug>`. This records the set of paths already dirty/untracked at the workflow's first arm into `workflow.json → rightsize_base[]`, and is **idempotent** — a resume finds the field present and no-ops, so the baseline is fixed at the true start. The gate later excludes these paths from its measure, so pre-existing cruft (prior-`/memory-sync` shards, scratch files) and the workflow's own scaffolding do not inflate the change size; the workflow's real source/test files, written later by `/tdd`, are created after the snapshot and are always measured. Fail-open: any error leaves the field absent, and the gate falls back to the whole-tree measure.

Log every transition to `.claude/state/harness/<slug>.log` with timestamp + `entered <phase>` / `completed <phase>` / `yielded at <gate>`.

## The loop body

Inside each iteration:

1. **TaskList.** If empty (first invocation in a fresh session, or session-bound state was reset), **re-seed** from `workflow.json → track_id` (post-§18) via the materializer: run `node .claude/skills/triage/seed-tasklist.mjs <track_id> <slug>` to emit the canonical TaskList JSON for the track. Skip nodes whose `metadata.phase` is in `workflow.json → completed` or in `exceptions`. Wire `addBlockedBy` from each emitted entry's `blockedBy` ordinals (translated to session task_ids of predecessors). Pre-§18 workflow.json files (`entry_phase` set, no `track_id`) SHALL have been migrated by preflight Step 3a before re-seed runs; if `track_id` is still absent here, fall back to the canonical templates documented in `triage/SKILL.md` Step 5's "Reference: canonical track shapes" subsection.
2. **Pick the next action.** Find the lowest-id `pending` task whose `blockedBy` list is empty. Then check for a **parallel cluster** (SP-002 / Article IV invariant supporting `can_parallel: true`): if the picked task carries `can_parallel: true` in its metadata AND one or more SIBLING pending tasks share both (a) identical `blockedBy` lists AND (b) `can_parallel: true`, group the picked task + every such sibling into a single cluster for this iteration. If no siblings share both conditions, proceed with the single task as today.
3. **If no pending task remains** (workflow complete), **EXIT LOOP with DONE**:
   - Marker FIRST: `rm -f .claude/state/.harness_active`.
   - Write `harness_state` with `{state: "done", slug, reason: "workflow complete"}`.
   - Break out of the loop; the terminal message is emitted after loop exit.
4. **If `task.metadata.needs_user == true`** (consent-gate placeholder), **EXIT LOOP with YIELD**:
   - Marker FIRST: `rm -f .claude/state/.harness_active`.
   - Write `harness_state` with `{state: "yielded", slug, reason: "yielded at /<gate>"}` — exactly three fields.
   - **Emit the attention notification (CO-D):** immediately after the `yielded` write, run `node .claude/skills/harness/notify.mjs emit --slug <slug>`. Best-effort — it never blocks and always exits 0 (even with no notifier). See "Yield notifier" below.
   - Break out of the loop; the terminal message names the consent command for the user to run.
   - **Gate-A open-questions consolidation.** When the gate being yielded at is `approve-direction` (the `/approve-direction` consent task), first run `node .claude/skills/harness/consolidate-open-questions.mjs --slug <slug>` and include its stdout in the yield terminal message, above the `/approve-direction` instruction. The helper extracts the `## Open questions` bullets from `docs/intake/<slug>.md`, `docs/research/<slug>.md`, and `docs/specs/<slug>.md`, dedupes them across phases (a question restated downstream collapses to one line tagged with every phase it appeared in), and buckets them spec-first so the reviewer settles the still-open items before approving. Zero questions → it prints a single "No open questions found" line; surface that too. This readout is advisory context for the human; it never gates or auto-approves.
   - **Gate-C no-yield carve-out (AC-003).** This yield step only fires when a `needs_user` task exists; under a github-flow autonomous feature landing the gate-C task was omitted at seed time. Full rule: see the gate-C carve-out bullet under "Phase ordering" below.
5. **Otherwise INVOKE the phase skill(s):**
   - **Single-task path** (no parallel cluster detected at step 2):
     - `TaskUpdate` to `in_progress` (set `activeForm` to the imperative-progressive form, e.g. "Running scout").
     - Log `entered <phase>` to `.claude/state/harness/<slug>.log`.
     - Invoke the matching phase skill via the **`Skill` tool — one invocation per loop iteration**.
   - **Parallel-cluster path** (cluster of ≥2 tasks all with `can_parallel: true` + identical blockedBy detected at step 2):
     - `TaskUpdate` every cluster task to `in_progress`.
     - Log `entered cluster: <ids>` to the harness log.
     - Dispatch the cluster via the `Task` tool, one `Task` invocation per cluster member — typically `swarm-worker` with a recipe per node, but the `skill:` field on each Node decides the worker target. All `Task` invocations go in a SINGLE assistant message so the runtime dispatches them concurrently.
     - Wait for all cluster members to return.
     - On all-success: mark each cluster task `completed`; refresh the marker + state once (NOT per-cluster-member); continue loop.
     - On any cluster member's failure: EXIT LOOP with YIELD; `reason: "cluster <ids>: <failed-id> failed: <summary>"`. Leave succeeded members `completed` and the failed member `in_progress` for inspection.
   - On phase-skill success:
     - `TaskUpdate` to `completed`.
     - Append the phase name to `workflow.json → completed`; update `updated_at`. **Skip this append when `.claude/state/workflow.json` no longer exists** — the `commit` skill's Step 1 moves it into `docs/archive/<date>/<slug>/`, and the archived bundle is immutable. Never resolve `workflow.json` to the archived copy: writing there re-dirties a file the commit just landed. This is the terminal phase; there is nothing left to record.
     - Log `completed <phase>`.
     - Refresh the marker (`echo "<slug>" > .claude/state/.harness_active`) and rewrite `harness_state` with `{state: "continue", slug, reason: "<phase> done; next: <next phase>"}`.
     - For tdd worker-ticks specifically, also append the tick's short label to `workflow.json → tdd_ticks[]` (Edit tool) so `phase_timer` captures per-tick sub-timing (see `tdd/SKILL.md` → Sub-tick timing protocol).
     - **Continue the loop** to the next iteration (return to step 1).
   - On phase-skill failure (non-integrate):
     - Leave the task `in_progress` (do NOT mark `completed`).
     - Do NOT append to `workflow.json → completed`.
     - **EXIT LOOP with YIELD**: marker FIRST (`rm -f .claude/state/.harness_active`), then write `harness_state` with `{state: "yielded", slug, reason: "<phase> failed: <one-line summary>"}`.
     - Surface the error; break out of the loop.
   - On `/integrate` failure: classify per the **Integrate-failure decision tree** below. If auto-loop, re-invoke `Skill(tdd)` and `Skill(integrate)` inside this same loop iteration (the auto-loop happens in-place, not via a new loop iteration). If stop-and-surface, **EXIT LOOP with YIELD** as above.

After the loop exits, emit a single terminal message naming the workflow state. Do not emit per-iteration terminal messages — those would invite the model to stop emitting mid-loop and trigger the safety net unnecessarily.

**Resume after a `needs_user` yield**: the user runs the consent command, then `/harness` again. The next Skill(harness) invocation re-enters preflight, finds the consent-gate task with its `needs_user` flag still set but the gate now satisfied (token on disk), marks that task `completed`, and proceeds into the loop body.

**Gate-A content re-check on resume (content-hash, D3/CO-E gate-collapse D-4).** When the satisfied gate is `approve-direction`, before marking it `completed` the harness recomputes the approved artifact's content hash and compares it to the token. The token is written at intake, so it hashes the **intake** doc — but the check is track-agnostic: read line 3 (the absolute artifact path the user approved) and line 5 (the content hash) of `.claude/state/spec_approvals/<slug>.approval`; recompute `computeSpecContentHash` of the current bytes at that line-3 path via `.claude/hooks/lib/spec-content-hash.mjs` (the hasher is content-agnostic — intake or spec); compare with `compareSpecHash(tokenHash, artifactBytes)`. On **match**, proceed as above. On **mismatch** — the approved artifact was amended after approval — **re-yield at gate A**: remove `approve-direction` from `workflow.json → completed`, set the gate task back to pending, and write `harness_state: yielded` (`reason: "direction artifact amended after approval; re-approve"`). This mechanizes the manual revoke discipline: an untracked (first-time) artifact whose git SHA is `N/A` still carries a content hash, so a post-approval edit is detected structurally rather than by hand. Fail-safe: an absent or `N/A` content hash (a token predating this feature) compares false and re-yields, so a stale token never silently satisfies the gate.

**Drift between TaskList and `workflow.json → completed`**: `workflow.json → completed` is durable across sessions; TaskList is session-bound. When they disagree, trust `workflow.json` and rebuild the task state to match.

## Phase ordering — the 11-phase pipeline

The phases the harness loops through, in order:

```
intake → scout → research → spec → /approve-direction → tdd → simplify →
security → integrate → document → archive → memory-sync →
/grant-commit → commit
```

- Phases listed in `workflow.json → exceptions` are skipped.
- Non-git projects auto-except `grant-commit` and `commit`; the workflow ends after `/archive`.
- **Gate-C no-yield carve-out (AC-003, seed.md §18.4 + §11).** Every commits-track's `grant-commit` node carries `condition: {name: "requires_commit_consent"}`, resolved at seed time — `seed-tasklist.mjs` passes `ctx.commitConsentRequired = !isAutonomousFeatureLanding()` to the materializer. Under a github-flow autonomous feature landing (primary tree, named branch neither in `git.release_branches` nor protected) the grant-commit task is OMITTED and `commit` chains directly after the preceding phase — the loop does not yield at gate C; the commit skill performs the landing (`git push -u origin <branch>` + `gh pr create --base <release>`) and yields on any push/PR/`gh`-absent failure. Everywhere else (fail-safe: protected branch, `ask`/`direct-to-main`, non-git, detached HEAD, linked worktree, missing ctx) the node materializes as today and gate C yields unchanged. The predicate is evaluated at SEED time; if branch topology changed since, `git_commit_guard`'s Bash leg remains the commit-time backstop — a consent-requiring commit still blocks without `/grant-commit` regardless of what the TaskList says. Never add or remove a gate task by hand to force either path.
- The four-pillar framing (Intake analysis · Track alignment · Implementation · Tying open ends) is documentary; the actual execution model is one phase per loop iteration, with the loop continuing through every non-gated boundary until it exits cleanly.
- Inside `/tdd`'s seeded worker chain, the harness inlines a **drift-check-tick** task between the last `design-ui-tick` (or `verify-tick` when no design rows) and `tdd-finalize`. It invokes `node .claude/skills/tdd/drift_check.mjs --slug <slug>` against the approved spec and the branch diff. Exit 0 (zero unresolved) → continue to `tdd-finalize`; exit 1 (≥ 1 unresolved) → EXIT LOOP with YIELD (`reason: "drift analysis: <N> unresolved items"`). Drift failures stop-and-surface (NO auto-loop) — the user fixes the impl gap or amends the spec + re-`/approve-direction`s. The drift report lands at `.claude/state/drift/<slug>.md`. `chore`-track workflows (no spec on disk) exit 0 with "no spec; skipped" and proceed to `tdd-finalize`.
- **Drift reverify-skip (velocity Component 2; `velocity.drift_reverify_skip.enabled`, default on).** On the `verify-tick` binding PASS the harness runs `node .claude/skills/tdd/drift-reverify-guard.mjs capture --slug <slug>`. The `drift-check-tick` then runs `drift-reverify-guard.mjs check --slug <slug>` first: exit 3 (tree provably unchanged since verify PASS) → skip the model's re-reading of the drift report; exit 0 (changed / missing / error) → full drift interpretation. The mechanical `drift_check.mjs` still runs and still yields on its own exit 1 regardless — the skip suppresses only model re-reading of a CLEAN result. Full protocol: `tdd/SKILL.md`.
- **Post-`tdd` work-planner checkpoint (`velocity.work_planner.enabled`, default off; Art. IV unaffected — it skips no phase).** After `tdd-finalize` and **before** the right-size gate below, the harness runs `node .claude/skills/harness/work-planner.mjs check --slug <slug> --json` and reads the verdict `{state, ratio, shortfall_tokens, envelope, payload, proposal?}`. The ordering is load-bearing and is pinned by AC-009: the planner decides whether the payload should **grow**, the right-size gate then decides which tail phases the **final** payload warrants. Running them the other way round would size the tail to a payload the operator is about to add to. States: `optimal` (ratio >= 4) and `acceptable` (>= 3) continue silently; `under-floor` (< 3) surfaces the shortfall and continues **only** on an operator override, which the harness records via `recordOverride` so the bypass rides into the archived bundle; `not-applicable` (a track with no payload phase, e.g. `chore`) and `unfitted`/`disabled` continue unchanged. Below the 4x target the verdict carries a `proposal` naming open backlog entries sized to close the gap — the harness presents it, and **adds nothing without approval**; on approval it calls `applyProposal`, which writes the keys to `workflow.json → source_backlog_keys` so `/commit` stamps their closure in the same landing. **Fail-open**: flag off or absent, an unreadable corpus, or any runner error → the verdict is a no-op and the loop proceeds exactly as today. The envelope reports `fitted` and `sample_count` on every call, so a shipped default is never mistaken for the operator's own measurement.
- **Re-entry recording (`reentry.mjs` — the sole writer of `attempts`).** Every re-entry — the integrate auto-loop, a gate-A content-hash re-yield, an explicit user re-run — SHALL be recorded with `node -e "import('./.claude/skills/harness/reentry.mjs').then(m => m.recordReentry({rootDir: process.cwd(), slug: '<slug>', phase: '<phase>'}))"` **before** the re-entry is made. Nothing else may assign to `workflow.json → attempts`; `tests/reentry.test.mjs` greps the tree for a second writer. The counter starts at 2, because the first recorded re-entry is the second entry. This replaces the hand edit that produced zero records across 117 archived bundles, and it does **not** make the counter oracle-bound: `phase_timer` observes `completed[]`, which a re-entry never changes. The residual risk is recorded in `docs/specs/work-planner-envelope.md` Open questions.
- **Post-`tdd` right-size gate (velocity Lever 2; `velocity.rightsize.enabled`, default on; Art. IV second skip mechanism).** After `tdd-finalize` and before `simplify`, the harness runs `node .claude/skills/harness/rightsize-gate.mjs check --slug <slug>` and reads its stdout JSON `{skip,keep,advisories,measured}`. For each phase in `skip` (a hard subset of `{simplify, document}`) it appends the phase to `workflow.json → exceptions[]` AND records a provenance row in `workflow.json → auto_skipped[]` (`{phase, reason, oracle:"rightsize-gate", measured}`); those phases are then skipped by the normal `exceptions` path. It surfaces any `advisories[]` (e.g. `sensitive_surface_unreviewed`) to the user as non-blocking notes, then continues to the next non-excepted phase. The gate is **additive-only** (it never removes an existing `/triage`/`chore` exception), **fail-open** (empty stdout / error / disabled → skip nothing), and **never skips `security`** or any phase outside `{simplify, document}`. **What `check` measures** — the diff is scoped to *this workflow's own change*: rows matching `project.json → tdd.test_globs` are excluded (test/fixture lines gauge no change risk, and under TDD every change ships with a test, so counting them kept the gate permanently over threshold), and rows whose path is in `workflow.json → rightsize_base[]` (the first-arm snapshot from step 6a) are excluded (pre-existing dirt the workflow did not produce). Absent `tdd.test_globs` and absent `rightsize_base` → the whole-tree measure, preserving prior behavior. The gate goes live the first full workflow AFTER the one that introduces it (the in-flight harness predates this SOP, same as the drift-check-tick introduction).
- **Spec-review checker fan-out (velocity Lever 1; `velocity.checker_fanout.enabled`, default on).** At the spec-review boundary — after `spec`, before `implementation`, alongside the `spec-shippability-review` node — the harness runs `node .claude/skills/harness/checker-fanout.mjs run <slug>` when the flag is enabled. The runner fans the mechanized read-only spec-review oracles named in `velocity.checker_fanout.checkers` (currently `spec-diagram`, `spec-traceability`) out in parallel and deterministically merges their verdicts (`mergeVerdicts`). It prints the merged JSON and exits 0 on `CLEAN`/skipped, 2 on `BLOCKED`; the harness surfaces any BLOCKER findings to the user **before** `implementation` (a BLOCKER is a spec defect to fix). **Fail-open**: flag disabled/absent, a missing spec, or any runner error → the harness falls back to the existing per-skill review (the runner prints a skip marker and exits 0). This is a velocity optimization in the **same class as drift reverify-skip** — it skips no phase, touches no consent token, and adds **no** subagent (parallel SCRIPTS are not subagents), so it needs **no** Article II / Article IV amendment. The extension point is `DEFAULT_CHECKER_REGISTRY` in `checker-fanout.mjs`; `spec-lint`/`spec-shippability` adapters are deferred (backlog `-d186`). Goes live the first spec-track workflow AFTER this one introduces it (introduction-workflow pattern; `tdd-quickfix`/`chore` tracks have no spec phase and never reach it).
- **Pre-implementation checkpoint (gate-collapse D3/CO-E, D-6 — the relocated machine BLOCKED gate).** After `spec-shippability-review` and the checker fan-out complete, and **before invoking `implementation`**, the harness calls `checkImplementationReady({slug, rootDir})` from `.claude/skills/harness/pre-implementation-gate.mjs`. This is the enforcement point that REPLACES the removed gate-A token BLOCKED cross-check (with the human spec gate gone, the direction token is written at intake before these verdicts exist, so the check cannot live on the guard). On `ready:false` (any `spec-shippability` or `checker-fanout` verdict reads `BLOCKED`) → **EXIT LOOP with YIELD** (`reason: "spec-review BLOCKED: <sources>"`), surfacing the blocker findings so the user fixes the spec defect and re-runs. On `ready:true` (verdicts CLEAN, or absent/malformed → fail-safe ready) → proceed to `implementation`. This is NOT a consent gate — no token, no human approval — it is a mechanical integrity checkpoint; a BLOCKED spec must never reach code. The slug is validated (`assertSafeSlug`, CWE-22 REJECT) before any path read. Non-spec tracks (`tdd-quickfix`/`chore`, no shippability/checker verdict on disk) fall through ready.
- **Durable plan state (v1 piece `-424f`; `velocity.durable_plan.enabled`, default on).** After `approve-direction` (plan-mode entry, vision §1.2), the harness calls `ensurePlanAtPlanMode({slug, rootDir, goal, tasklist, tier})` from `.claude/skills/harness/plan-wiring.mjs` to create the durable plan object at `.claude/state/plan/<slug>.json` (idempotent — returns the existing plan on resume), and on each phase completion calls `recordPhaseTransition({slug, rootDir, phase})` to append an auditable revision (every replan/transition is a recorded diff, never a silent mutation — `workflow.json` lineage). The plan is **additive Tier-2 orchestration state** in the **same class as `harness_state`/`checker-fanout`** — it adds no phase and no consent gate, so it needs **no** Article II/IV amendment. **Fail-open**: flag disabled/absent or an unreadable config → no plan writes (today's behavior). The two shipped consumers persist through it when a plan exists: `evidence-ledger.recordRoundTripOnPlan` (round-trips) and `checker-fanout`'s `mirrorVerdictToPlan` (verdicts), each still writing their on-disk projection for back-compat. Per-node frame reads (`plan-frame.readFrame`), the visible replan diff (`plan-diff.diffVersions`), the record-only replanner (`replan.applyReplan`), and the merge-oracle input (`plan-store.mergeInput`) are the consumer surface; the decide-*when*-to-replan loop is `-4c43` (not wired here). Goes live the first workflow AFTER this one introduces it. **Slug guard (fail-CLOSED, orthogonal to the fail-open flag above):** `plan-store` exports `assertSafeSlug` and calls it inside `planPath`, so every plan read and write **throws** on a slug not matching `/^[a-z0-9][a-z0-9-]*$/` **before any path is constructed** (CWE-22); `checker-fanout` calls the same guard at `runCheckerFanout`'s entry, which covers its `docs/specs/` + `docs/intake/` reads as well as its own projection write. This is **REJECT, never repair** — do NOT "fix" a malformed slug by normalizing it (`canonicalSlug` in `common.mjs` is a NORMALIZER, not a validator; using it here would MASK a traversal by silently writing to a different path). A disabled flag still means no plan writes; a malformed slug is always an error. **The durable-plan mirror is BEST-EFFORT and the write order in `persistVerdict` is load-bearing:** the `checker-fanout` projection is written FIRST and is **canonical** (`pre-implementation-gate.mjs` reads `.claude/state/checker-fanout/<slug>.json` to gate implementation entry on a BLOCKED verdict — gate-collapse D-6 relocated this off the direction gate, NOT the plan); `mirrorVerdictToPlan` runs after, inside a `try/catch` that reports to stderr and swallows. Do NOT "clean up" that `try/catch` — without it a plan-write hiccup propagates into the live verdict path and takes the spec-review verdict down with it. Full analysis: `docs/security/durable-plan-slug-guard-2026-07-12.md`.

### Epic / epic-child tracks (§18.9)

Two tracks change the loop shape:

- **`epic`** runs discovery only: `intake → scout → research → spec → approve-direction → memory-sync → grant-commit → commit` (plus any per-project review node like `spec-shippability-review` before `approve-direction`). It has **no implementation phases** — the loop exits cleanly after `commit`, leaving the sliced spec live at `docs/specs/<epic>.md`. Do **not** route an `epic` track into `tdd`/swarm; its children do the implementation on separate `epic-child` workflows.
- **When the `epic` track's `approve-direction` phase completes** (the user has run `/approve-direction` and you are recording it in `completed`), also set `approved: true` and refresh `updated_at` in `.claude/state/epic/<epic>.json`. This is gated by the real gate-A consent that just happened — never set it ahead of the gate. The flag is a **human-readable marker only**: what unblocks `epic-child` writes is the `.claude/state/spec_approvals/<epic>.approval` token, which `track_guard` reads directly (`track_guard.mjs:55-56`). Retiring the trusted boolean is what closed the read surface the write-side detectors alone could not; `epic_approval_guard` still gates the flip as defense in depth.
- **`epic-child`** starts at `tdd` with discovery inherited (pins in `workflow.json`, enforced by `track_guard`). Its effective loop is `tdd → integrate → archive → grant-commit → commit`; `simplify`/`security`/`document` run only when `/triage` left them out of `exceptions` (slice risk-escalation). At Phase 6 an `epic-child` resolves its `implementation` selector like every other code-generating track: the swarm alternate when the pinned slice exposes ≥ `swarm.min_tasks_worth_swarming` independent components, the solo chain otherwise. A one-component slice therefore still runs solo — that is now the predicate's answer rather than a hard-coded rule. `/tdd` reads the pinned spec's `## Slice <id>` section as its contract either way. The slice's `children[]` flip to `status: "committed"` is owned by the `commit` skill, which performs it **pre-commit** (commit/SKILL.md Step 2.8) so the epic-close fold (`epic_close.mjs`) can ride that same commit when this is the last open child. The harness's own post-commit flip is now only an **idempotent backstop**: re-asserting `status: "committed"` (and re-invoking `epic_close.mjs`, itself idempotent) covers a child committed outside the commit-skill path, and is a no-op when the commit skill already flipped + closed.

### Swarm vs solo at Phase 6

Once the spec approval token is present on resume, count C4 Components in the approved spec:

```
grep -cE '^\s*Component\(' docs/specs/<slug>.md
```

- Count ≥ `project.json → swarm.min_tasks_worth_swarming` (default 1) **and** the components are genuinely independent (their dependency graph has ≥ 2 nodes with no cross-edge) **and** the project is a git repository (`git rev-parse --is-inside-work-tree` exits 0) → **swarm path**: `swarm-plan` → `/approve-swarm` → `swarm-dispatch`.
- Otherwise → **solo path**: `tdd` directly.
- Non-git projects never reach the swarm path: `/triage` auto-excepts `swarm-plan`, `approve-swarm`, and `swarm-dispatch` at workflow-creation time per CLAUDE.md Article IV ("Phase 6c and Phase 11 are git-conditional"), so the harness sees them in `exceptions` and routes Phase 6 straight to `/tdd`.
- User can override in conversation: "run /tdd solo for this one" or "use swarm." Log the override. A "use swarm" override on a non-git project SHALL be refused with the reason `swarm requires git; swarm phases are excepted on this workflow`.

## Integrate-failure decision tree

When `/integrate` fails inside the loop, judge: is this a simple bug (auto-retryable in-place) or does it need human input on scope/spec?

**Auto-loop to `/tdd`** when **all** of these hold:
- The failing tests are assertions on behavior the spec clearly defines.
- The failure is localized (one component, one AC, no cross-spec contract conflict).
- The fix is mechanical (implementation mismatch, edge case missed, off-by-one).

On auto-loop: invoke `Skill(tdd)` with a brief telling it to focus on the failing test(s) only, then invoke `Skill(integrate)` again — **both calls happen inside the same loop iteration** (no Stop-hook hop, no new user `/harness` invocation needed). Cap at 3 auto-loops within one iteration; if still red after 3, stop and surface (exit loop with yield).

**Count the re-entry before you make it.** Immediately before each auto-loop's `Skill(tdd)` call, increment `workflow.json → attempts` for **both** `tdd` and `integrate`: `attempts` is an object of `{"<phase>": <n>}` where `n` counts how many times the phase has been ENTERED, so the first entry is 1 and the first auto-loop takes each to 2. Create the field (and seed a phase at 1) when it is absent. Also increment the phase's own counter on any other re-entry — the gate-A content-hash re-yield that removes `approve-direction` from `completed`, and an explicit user-requested re-run.

This is the only record the auto-loop leaves. Because it re-invokes both skills in place without touching `completed[]`, and `stampFromWorkflow` deduplicates on the stamp label, retries were previously invisible: across 67 archived spec runs the timing logs recorded zero phase re-entries, while the post-approval implementation span was consuming 60-75% of every heavy run. `phase_timer` reads `attempts` and appends one `{"phase":"<phase>:attempt-<k>","event":"retry"}` row per counted re-entry, which is what makes that span measurable. Writing the counter is not optional bookkeeping — skip it and the retry is unmeasured.

**Stop and surface** when **any** of these hold:
- The failing test expects behavior the spec doesn't define → spec change needed.
- The test exposes a contradiction between two spec ACs → spec change needed.
- The failure reveals a component or interaction the spec doesn't name → scope expansion.
- A swarm-dispatch integration failure spans components dispatched in different waves (coupling the spec missed).

On surface: exit the loop with `harness_state` `state: "yielded"`, `reason: "integrate failed: needs spec change"`. Show the failing test output, name which criterion tripped, and tell the user: "This needs a spec change / scope decision. Update `docs/specs/<slug>.md`, re-run `/approve-direction`, then `/harness` to resume."

## State machine (resume logic)

On each `/harness` invocation, read `workflow.json` and decide whether to enter the loop and at which task:

| Condition | Action |
|---|---|
| No `workflow.json` | Fresh start → Pillar 1 |
| `completed` contains all non-excepted phases | Enter loop; loop exits immediately with `state: done` |
| `completed` contains `intake` but no `spec_approvals/<slug>.approval` token | Enter loop; loop exits at first iteration with `state: yielded` (approve-direction gate) |
| `completed` contains `spec` **and** approval token present, but `tdd`/`swarm-dispatch` not in `completed` | Enter loop; decide swarm-vs-solo at first iteration; invoke the next phase |
| `completed` contains `swarm-plan` but no `swarm_approvals/<slug>.approval` | Enter loop; loop exits with `state: yielded` (approve-swarm gate) |
| `completed` contains `archive` but no `commit_consent` (git project) | Enter loop; loop exits with `state: yielded` (grant-commit gate) |
| `completed` contains `grant-commit` consent (token fresh) but no commit yet (git project) | Enter loop; invoke `Skill(commit)` (Phase 11) |
| Phase skill returned an error this invocation | Loop exits with phase-failure reason; user investigates |

## Constraints

- **Never skip a consent gate.** If the approval/consent token is missing, the loop exits with `state: yielded`. Never generate the token yourself.
- **Never auto-proceed past an integrate failure** outside the decision-tree criteria above.
- **Never re-run a phase already in `workflow.json → completed`** unless the user explicitly asks.
- **Every phase invocation inside the loop uses the Skill tool — one invocation per loop iteration.** Do not re-implement phase logic here.
- **Always refresh `harness_state` after each successful phase invocation** (still `state: continue` during the loop body). The safety net depends on the marker + state being consistent.
- **Log every transition** to `.claude/state/harness/<slug>.log`.
- **If the user overrides a decision in conversation** (e.g., "skip security", "force swarm"), honor the override and log it as a manual adjustment.