@friedbotstudio/create-baseline 0.1.0

package/obj/template/.claude/skills/design-ui/references/orchestration.md

@@ -0,0 +1,121 @@
+# Orchestration — Stage 3 gates and loop logic
+
+Stage 3 of `design-ui` runs the impeccable recipe step-by-step in main context. This file documents the gates that decide when to continue, when to loop, when to surface to the user, and when to block.
+
+## The orchestration loop, top level
+
+```
+for each step in recipe:
+  pre-checkpoint   -> .claude/state/design/<slug>.json {step_index, next_cmd}
+  invoke           -> Skill(impeccable, "<cmd>", "<args>")
+  capture          -> read impeccable's structured result
+  branch           -> see gates below
+  post-checkpoint  -> .claude/state/design/<slug>.json {step_index++, invocations[]}
+```
+
+The state file is written *before* and *after* each step so a mid-step interruption (session end, context compact, user abort) is recoverable on next invocation per `state-machine.md`.
+
+## Gates within the orchestration
+
+### Gate 1 — P0 blocks
+
+If the previous step was `audit` (or `critique`) and its return value reports `P0 ≥ 1`:
+
+- Do **not** auto-chain to `polish`.
+- Surface the P0 list to the caller (or the user, on direct invocation).
+- Persist `state: "blocked"` to the state file.
+- Return `{ final_state: "blocked", reason: "P0 issues require user direction", audit_report_path }`.
+
+P0 issues are by definition blockers: accessibility failures (focus traps, missing labels, color contrast < 3:1), broken core functionality, semantic-HTML violations. Looping `polish` on a P0 risks compounding the issue; the user must direct the fix.
+
+### Gate 2 — P1 looping with cap 3
+
+If the previous step was `audit` and reports `P1 ≥ 1` and `P0 == 0`:
+
+- Run `polish` against the audit report.
+- Re-run `audit` to measure progress.
+- Repeat up to **3 iterations** (audit → polish → audit → polish → audit → polish → audit, where the final audit is the verification).
+- After iteration 3's verification audit, if P1 is still > 0:
+  - Terminate with `state: "needs_human"`.
+  - Persist `.claude/state/design/<slug>.json` with the audit history.
+  - Materialize `docs/design/<slug>.audit.md` (human-readable report).
+  - Emit a memory candidate via `memory_stop` so `_pending.md` carries the issue forward.
+  - Return `{ final_state: "needs_human", iterations: 3, audit_report_path, state_file }`.
+- After iteration 3, **no fourth polish runs**. The cap is hard. The user can re-invoke design-ui (resume from state) or invoke `/impeccable polish` directly for one-off iteration.
+
+The 3-iteration cap is a discipline: if three rounds of `polish` cannot clear P1, the issue likely needs a design call (a register change, a deliberate exception per CLAUDE.md Article X) or human judgement on tradeoffs. Continuing to loop would burn iteration budget without convergence.
+
+### Gate 3 — Recipe mode (auto vs ask)
+
+After Stage 2 (translate) returns a recipe, Stage 3 reads the recipe's `mode`:
+
+- **auto**: execute without prompting. Used for single-step recipes (`shape`, `live`, `extract`) and for atomic recipes (`audit → polish → audit` treated as one unit, mode-stamped `auto` by the intent-table).
+- **ask**: surface the plan, await user `proceed`. The prompt format:
+  > "Recipe: `[shape, craft, audit]`. Proceed? (or describe an override)"
+  
+  On `proceed` (or any non-negative response), continue. On override, re-invoke Stage 2 with the user's adjusted intent. On refusal, persist `state: "blocked"` and return `{ final_state: "blocked", reason: "user declined recipe" }`.
+
+### Gate 4 — Target-file existence
+
+Before invoking any impeccable subcommand that writes (`craft`, `polish`, refines, enhances, fixes), Stage 3 verifies each `target_files` path's *parent directory* exists. If a parent is missing:
+
+- Persist `state: "blocked"`.
+- Return `{ final_state: "blocked", reason: "target_files parent directory missing: <path>", state_file }`.
+
+This prevents impeccable from generating code with no home. design-ui never creates parent directories itself — that would be a write outside the thin-glue contract.
+
+For surface-less intents (`extract`, `live`, `shape`-only) this gate is skipped: `target_files` may be empty or `—` per the schema, and the impeccable subcommand handles its own output destination.
+
+### Gate 5 — Register conflict
+
+If `task_brief.register_override` is set and conflicts with `PRODUCT.md`'s declared register (e.g., override is `brand` but PRODUCT.md says `product`), Stage 3 surfaces:
+
+> "Register mismatch: task_brief requests `brand`, PRODUCT.md declares `product`. Proceed with override, or align?"
+
+On `proceed`, run the recipe with the override. On `align`, re-invoke Stage 2 with the PRODUCT.md register. On refusal, block.
+
+This gate is intentionally a soft yield — register overrides are legitimate (a product app's marketing splash page wants `brand` register), but they should be intentional.
+
+## Iteration accounting
+
+The state file records every invocation:
+
+```jsonc
+{
+  "invocations": [
+    { "cmd": "audit",  "iteration": 1, "started_at": "...", "completed_at": "...", "p0": 0, "p1": 3 },
+    { "cmd": "polish", "iteration": 1, "started_at": "...", "completed_at": "...", "files_written": [...] },
+    { "cmd": "audit",  "iteration": 2, "started_at": "...", "completed_at": "...", "p0": 0, "p1": 2 },
+    { "cmd": "polish", "iteration": 2, "started_at": "...", "completed_at": "...", "files_written": [...] },
+    { "cmd": "audit",  "iteration": 3, "started_at": "...", "completed_at": "...", "p0": 0, "p1": 1 }
+  ]
+}
+```
+
+The `iteration` counter increments inside a polish-atom loop (1, 2, 3). It is independent of `step_index` (which tracks position in the recipe). For non-loop recipes, `iteration` is 1 throughout.
+
+## Critique scoring loop (optional, recipe-driven)
+
+Some recipes (`bolder`, `quieter`, `distill`) pair with `critique` as the verification step. The same cap-3 rule applies, but the threshold is `critique` score:
+
+- If `critique` returns score < 14/20 after the refine step, loop with the same refine command (up to 2 additional iterations beyond the first).
+- If score still < 14/20 after 3 total iterations, terminate with `needs_human`.
+
+This is the same cap-3 shape as the polish loop, with `critique` as the gating signal instead of `audit`.
+
+## What the orchestrator never does
+
+- **Does not pick aesthetic direction.** Stage 2's recipe choice and Stage 3's gates are about *flow*, not *style*. Every style decision flows through `impeccable`.
+- **Does not write product code directly.** Thin glue only — state JSON, brief snapshots, audit snapshots under `docs/design/`. Product code is `impeccable`'s territory exclusively.
+- **Does not retry after `needs_human`.** Once the cap fires, the caller (or user) decides. design-ui's resume reads the state file and continues *only* if a user action has materially changed the inputs (e.g., the audit report has been addressed manually, the state has been moved to `in_progress` explicitly).
+- **Does not silently skip gates.** Every gate has an explicit branch with a recorded reason. Skipping is failure; surface always.
+- **Does not invoke more than one impeccable subcommand at a time.** Sequential only. The `∥` notation in the intent table for `critique ∥ audit` is shorthand for "call both, collect results, neither blocks the other" — but they remain two sequential `Skill(impeccable, …)` calls in main context.
+
+## Caller policy at `final_state`
+
+| State returned to caller | Caller policy (for `/tdd` Step 6 specifically) |
+|---|---|
+| `complete` | Mark the design call done; proceed to next call in design_calls; after all complete, re-invoke `verify`. |
+| `needs_human` | Warn and continue. design-ui has surfaced; the user can re-invoke later. /tdd Step 6 does NOT fail. The audit report path goes in /tdd's notes. |
+| `blocked` | Stop /tdd Step 6. Surface the blocker to the user. /tdd's `## 7. Decide on the result` step receives this and decides whether to escalate to a spec change. |
+| `not_a_design_task` | Stage 0 misroute. /tdd surfaces "design-ui returned not_a_design_task — was this design_call mis-classified in the spec?" and stops to reconcile. |

package/obj/template/.claude/skills/design-ui/references/state-machine.md

@@ -0,0 +1,125 @@
+# State machine — `.claude/state/design/<slug>.json`
+
+`design-ui` persists every orchestration to `.claude/state/design/<slug>.json`. The file is the resume point: a second invocation with the same `slug` reads the file, finds `step_index`, and continues from there without re-running completed steps.
+
+## File location
+
+`.claude/state/design/<slug>.json` — one file per orchestration, keyed by `slug`. The directory is gitignored (the whole `.claude/state/` tree is) so state files are local-only.
+
+The first invocation creates the directory if it does not exist (`mkdir -p`). Subsequent invocations write atomically (write to a tmp file, then rename). On read, malformed JSON triggers `state: "blocked"` with `reason: "state file is malformed"`.
+
+## File shape
+
+```jsonc
+{
+  "slug":         "<kebab-case>",
+  "started_at":   "<ISO 8601 UTC>",
+  "updated_at":   "<ISO 8601 UTC>",
+  "intent":       "<the natural-language intent from task_brief>",
+  "register":     "brand" | "product",
+  "recipe":       ["<impeccable_cmd>", ...],
+  "step_index":   <int, 0-based; index of the NEXT step to run>,
+  "invocations":  [InvocationRecord, ...],
+  "verifications": [VerificationRecord, ...],
+  "state":        "in_progress" | "complete" | "needs_human" | "blocked" | "not_a_design_task",
+  "next_actions": ["<human-readable action>", ...]
+}
+```
+
+### `InvocationRecord`
+
+One record per `Skill(impeccable, ...)` call:
+
+```jsonc
+{
+  "cmd":          "shape",            // impeccable subcommand name
+  "iteration":    1,                  // 1 for non-loop steps; counter inside polish atoms
+  "started_at":   "<ISO 8601 UTC>",
+  "completed_at": "<ISO 8601 UTC>",
+  "output_path":  "docs/design/<slug>.brief.md" | null,
+  "files_written": ["<path>", ...]
+}
+```
+
+### `VerificationRecord`
+
+One record per `audit` or `critique` invocation. These also appear in `invocations[]`; this list collates them for quick access:
+
+```jsonc
+{
+  "cmd":         "audit",
+  "iteration":   2,                   // matches the iteration in invocations[]
+  "score":       "17/20",
+  "p0":          0,
+  "p1":          2,
+  "report_path": "docs/design/<slug>.audit.md"
+}
+```
+
+## Required fields
+
+Every state file MUST carry these fields. Stage 3's checkpoint writes them all on each step. The audit-baseline check `state-file: shape` (if added) verifies their presence on any state file under `.claude/state/design/`.
+
+| Field | Required | Notes |
+|---|---|---|
+| `slug` | yes | The state file's basename. Self-referential check. |
+| `started_at` | yes | When the orchestration began. Never updated on subsequent steps. |
+| `intent` | yes | The natural-language intent. Used in resume to confirm the user is resuming the same orchestration. |
+| `recipe` | yes | The full step sequence. Set at Stage 2; never mutated. |
+| `step_index` | yes | The position to resume from. 0 = nothing run yet; N = N steps completed. |
+| `invocations` | yes | Append-only list. Each step's invocation appears here. |
+| `verifications` | yes | Subset of invocations[] limited to evaluation steps (audit, critique). |
+| `state` | yes | One of the five terminal/transitional states. |
+
+Optional fields:
+- `register`, `updated_at`, `next_actions` — present when the orchestration has produced them; absent before Stage 1 completes the capture.
+- `register_override`, `references`, `target_files`, `write_set` — echoed from the task_brief for traceability; not required.
+
+## Terminal states
+
+The five values of `state` and their meaning:
+
+| State | Meaning | Caller action |
+|---|---|---|
+| `in_progress` | Orchestration is mid-flight. Either Stage 3 is running or the session ended mid-step. | Resume on next invocation. |
+| `complete` | All recipe steps ran to completion. Final audit/critique passed thresholds. | Read `Report` and continue. |
+| `needs_human` | Loop cap fired (3 iterations on audit→polish or critique-driven refine). P1 issues remain unresolved. | Caller decides whether to surface and stop, or warn and continue. Per `/tdd` Step 6 policy: warn and continue. |
+| `blocked` | A gate fired. P0 blockers, register conflict declined, target_files parent missing, malformed state file, user refused recipe. | Caller surfaces the reason and stops the immediate flow. |
+| `not_a_design_task` | Stage 0 classified the intent as development or copy. Set on the first checkpoint write of the orchestration. | Caller routes to `correct_lane` (`/tdd` or `/document`). |
+
+## Resume logic
+
+On any `Skill(design-ui, task_brief)` invocation:
+
+1. Compute the slug (from `task_brief.slug`, or derive from `task_brief.intent` per the kebab-case-first-noun-phrase rule from `/intake`).
+2. Look for `.claude/state/design/<slug>.json`:
+   - **Not present** → fresh orchestration. Start Stage 0.
+   - **Present and `state` is `complete`** → return the existing Report; no work to redo.
+   - **Present and `state` is `in_progress`** → resume. Skip steps prior to `step_index`; start at `step_index`.
+   - **Present and `state` is `needs_human`** → caller must signal intent to resume. If `task_brief` is identical to the stored intent and the caller is re-invoking explicitly, restart the loop from `step_index` (which points at the audit that fired the cap). The user is asserting that conditions have changed (e.g., P1 issues were addressed externally) and the loop should re-run.
+   - **Present and `state` is `blocked`** → return the existing Report with the blocker reason. User must materially change the input (re-state intent, expand write_set, etc.) before progress.
+   - **Present and `state` is `not_a_design_task`** → return the existing Report; the misroute is sticky for this slug.
+   - **Present but malformed JSON** → return `Report { final_state: "blocked", reason: "state file malformed", state_file }`. Do NOT overwrite — preserve for human inspection.
+
+The resume rule: **skip steps prior to `step_index`; start at `step_index`**. Completed steps are never re-run unless the user explicitly requests it (e.g., by deleting the state file and re-invoking).
+
+## Atomic writes
+
+The state file is written via tmp-then-rename:
+
+```
+1. write .claude/state/design/<slug>.json.tmp.<pid>
+2. rename .tmp.<pid> → .json
+```
+
+This prevents partial-write corruption if the process is killed mid-write. Readers always see either the old version or the complete new version.
+
+## What the state file is NOT
+
+- Not a transcript of impeccable's design decisions — those live in `docs/design/<slug>.brief.md` and `<slug>.audit.md` (snapshots design-ui materializes from impeccable's returns).
+- Not a log — `_resume.md` carries the session-level continuity snapshot. The state file is specific to one orchestration.
+- Not user-readable as the primary surface — humans should read the brief and audit reports under `docs/design/`. The state file is the machine-readable resume point.
+
+## Related skill memory entry
+
+The `audit-baseline` skill checks that this state-machine documentation is present and aligned with any rule it enforces. If a future audit check verifies state-file shape on disk, it parses `.claude/state/design/*.json` and asserts the required fields above are present.

package/obj/template/.claude/skills/document/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: document
+owner: baseline
+description: Workflow Phase 10 — orchestrator for documentation work. Surveys the diff, routes technical writing through the `documentation` skill, tutorials through `technical-tutorials`, and all prose body work (inline docs, README updates, user-facing copy) through the `prose` skill (which mandates `humanizer` and conditionally `copywriting`). Verifies completeness and marks phase done.
+---
+
+# document — Phase 10 orchestrator
+
+This skill does **not** write docs directly. It surveys the diff, decides what kinds of doc work are needed, and delegates via the Skill tool.
+
+| Delegate skill | Kind | Runs on |
+|---|---|---|
+| `prose` | Prose body — any English writing that needs humanizing | inline docs, README surface, user-facing copy, summary/narrative sections |
+| `documentation` | Technical reference | API docs, architecture notes, operational runbooks |
+| `technical-tutorials` | Step-by-step narrative | quickstarts, walkthroughs, code tutorials |
+
+The key shift: **`prose` is the sole channel for prose-shaping work**. It owns the `humanizer` pass so every word we ship is filtered. The other two are technical specialists that produce structured reference material; when they output prose paragraphs that matter, they invoke `prose` themselves.
+
+## Prereq
+
+`integrate` in `completed` (or `exceptions`).
+
+## When each delegate fires
+
+- **`documentation`** — diff touches a public API, config surface, module architecture, or adds runbook-worthy operational behavior. Reference material a future engineer will look up.
+- **`technical-tutorials`** — diff adds a feature a *first-time user* must learn by doing. Hands-on-learning, not lookup-reference.
+- **`prose`** — when prose needs to be written or revised:
+  - Narrative sections inside docs the above two skills produce.
+  - README surface updates.
+  - User-facing marketing/product copy on landing, pricing, feature pages.
+  - One-paragraph summaries, migration narratives, release notes.
+
+Multiple can fire on one diff. A feature that ships an API, needs a quickstart, and updates the pricing page triggers all three.
+
+## Steps
+
+1. **Verify prereq.** `integrate` is in `completed` or `exceptions`. Otherwise stop and say which phase is missing.
+
+2. **Survey the diff.** `git diff --name-status <merge-base>..HEAD`. Classify touched files:
+   - Public API / CLI / contract surfaces → `documentation` candidate.
+   - New capability a user learns by doing → `technical-tutorials` candidate.
+   - Marketing / pricing / feature / landing pages → `prose` (persuasive register) candidate.
+   - README surface or prose anywhere in the diff → `prose` candidate.
+   - Internal-only refactor with no external surface → just inline docstrings + the README sanity check.
+
+3. **Always: inline docs.** For every changed public symbol — module-level docstring / header comment / doc comment appropriate to the language. Short. If you need a comment to explain *what*, the abstraction is wrong; comments are for non-obvious *why*.
+
+4. **Delegate.** For each matched category, invoke the delegate skill with a scoped brief:
+   - `documentation` / `technical-tutorials`: invoke via `Skill(...)`. Include the diff slice, upstream spec/intake, and the specific deliverable (e.g., "API reference for the new retry endpoint"). Read its output and incorporate it.
+   - `prose`: invoke via `Skill(prose)` with brief, source material (diff slice, spec excerpt), audience, register, and output target (file path or section). The `prose` skill applies `humanizer` always, plus the conditional skill you name.
+
+5. **README surface check.** If the root `README.md` or any top-level doc claims behavior the diff changed, update it — route through `prose` so the copy gets humanized.
+
+6. **Scrub.** No `TODO` / `FIXME` / `HACK` / `XXX` in files this phase touched. Seed.md forbids them; humanizer doesn't catch them.
+
+7. **Append `"document"` to `.claude/state/workflow.json → completed`.**
+
+8. Tell the user: "Documentation pass complete. Invoked: `<list of delegates>`. Next: `/archive`."
+
+## Constraints
+
+- **Delegation is mandatory.** You do not write prose here; `prose` does. You do not write API reference here; `documentation` does. You do not write tutorials here; `technical-tutorials` does. This skill decides *who* writes *what* and stitches the result.
+- **Do not skip the humanizer pass.** Everything in `prose` runs it. If you find yourself tempted to write a README paragraph inline to save a hop, don't — route it through `prose`.
+- **Do not invoke delegates that don't apply.** Internal refactor with no external surface? Don't fire `prose` (persuasive register) just because the skill is available. Step 2's survey gates the invocations.
+- **Keep this skill lightweight.** The body is mostly "decide → delegate → verify → mark done". Heavy lifting lives in the delegates.
+- **YAGNI on docs.** A doc exists because the code change made it necessary. No speculative documentation.

package/obj/template/.claude/skills/documentation/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: documentation
+owner: baseline
+description: Write and maintain technical documentation. Trigger with "write docs for", "document this", "create a README", "write a runbook", "onboarding guide", or when the user needs help with any form of technical writing — API docs, architecture docs, or operational runbooks.
+---
+
+# Technical Documentation
+
+Write clear, maintainable technical documentation for different audiences and purposes.
+
+## Document Types
+
+### README
+- What this is and why it exists
+- Quick start (< 5 minutes to first success)
+- Configuration and usage
+- Contributing guide
+
+### API Documentation
+- Endpoint reference with request/response examples
+- Authentication and error codes
+- Rate limits and pagination
+- SDK examples
+
+### Runbook
+- When to use this runbook
+- Prerequisites and access needed
+- Step-by-step procedure
+- Rollback steps
+- Escalation path
+
+### Architecture Doc
+- Context and goals
+- High-level design with diagrams
+- Key decisions and trade-offs
+- Data flow and integration points
+
+### Onboarding Guide
+- Environment setup
+- Key systems and how they connect
+- Common tasks with walkthroughs
+- Who to ask for what
+
+## Principles
+
+1. **Write for the reader** — Who is reading this and what do they need?
+2. **Start with the most useful information** — Don't bury the lede
+3. **Show, don't tell** — Code examples, commands, screenshots
+4. **Keep it current** — Outdated docs are worse than no docs
+5. **Link, don't duplicate** — Reference other docs instead of copying

package/obj/template/.claude/skills/harness/SKILL.md

@@ -0,0 +1,169 @@
+---
+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-spec, /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-spec`, `/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 three 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.
+
+The state file shape:
+
+```json
+{
+  "state": "continue|yielded|done",
+  "slug": "<workflow slug>",
+  "reason": "<one sentence>"
+}
+```
+
+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 safety net only. Its three-rung gate (`stop_hook_active` absent → `.harness_active` marker exists → `state == "continue"`) emits `{"decision":"block","reason":"…invoke Skill(harness)…"}` **only when the loop exited mid-flow** without writing `yielded`/`done` — i.e., the loop iteration completed an arm-but-did-not-exit-cleanly path. In normal operation (loop runs to gate/failure/done), the hook sees `state != continue` or marker absent, stays silent, and the turn ends naturally. The hook is unchanged by the internal-loop redesign; what changed is the harness skill, which now exits the loop with `yielded`/`done` in the common case, leaving the hook quiescent.
+
+### 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.
+
+## 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.
+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.
+
+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**: read `workflow.json → completed + exceptions + entry_phase` and recreate tasks for every remaining phase using the canonical templates from `triage`'s SKILL.md. Skip phases already in `completed`. Wire `addBlockedBy` so the dependency chain is preserved.
+2. **Pick the next action.** Find the lowest-id `pending` task whose `blockedBy` list is empty.
+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.
+   - Break out of the loop; the terminal message names the consent command for the user to run.
+5. **Otherwise INVOKE the phase skill:**
+   - `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**.
+   - On phase-skill success:
+     - `TaskUpdate` to `completed`.
+     - Append the phase name to `workflow.json → completed`; update `updated_at`.
+     - 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>"}`.
+     - **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.
+
+**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-spec → tdd → simplify →
+security → integrate → document → archive → /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`.
+- 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.
+
+### 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 3) **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).
+
+**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-spec`, 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 `spec` but no `spec_approvals/<slug>.approval` token | Enter loop; loop exits at first iteration with `state: yielded` (approve-spec 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) |
+| 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.