Harness writer

Harness Writer

Turn a mission ("activate a data standard", "fix the N flagged practices", "integrate a sandbox API") into a self-maintaining lane: a timestamped folder a fresh session can drive autonomously, with three model layers, loops-within-loops, and adversarial gates. Written by Fable (the session model) — do not delegate the authoring itself; delegate only research.

Version 2.3 (2026-06-14) — "The Composed Harness." Generated harnesses bind each loop ring to its matching agent-skills:* playbook (Addy Osmani's local pack) instead of re-deriving generic prompts, treating that pack as local verified canon (references/skill-rings.md). v2.0 (2026-06-13) added per-harness self-repair (7 mechanisms in references/self-repair.md) and the skill repairing its own doctrine each run (step 12). v2.2.1–v2.3 distilled new gate-wiring laws from dog-fooding real lanes (references/CHANGELOG.md).

Read before writing anything: references/design-principles.md (the distilled doctrine), references/doc-templates.md (every document skeleton), references/mjs-template.mjs (the engine template), references/self-repair.md (the 7 self-repair mechanisms), references/skill-rings.md (ring→agent-skills binding map — bind rings, don't re-derive playbooks), references/sources.md (verified doctrine ledger — read before citing ANY figure). Changelog: references/CHANGELOG.md.

The procedure (12 steps, in order)

1. Scope the lane

One mission, one lane. Name it: <slug>-harness_<YYYY-MM-DD>/ at the workspace root (or inside the worktree for repo-resident lanes). Record what is explicitly OUT of scope (other terminals' lanes) — this becomes the DriftGuard's first check.

2. Skeleton + resources

mkdir -p <folder>/{research,resources,harness,state}. Move (user preference: real files, not symlinks — ASK if unclear) any user-provided assets into resources/. Anything in /private/tmp, /var/folders, or Downloads is at risk — secure it FIRST, within the first minute.

3. Gather design inputs

Fan out cheap readers (Sonnet) in parallel for: (a) any articles/links the user provided — saved X/Twitter HTML is usually an empty JS shell, so recover content from the live web; (b) existing harness exemplars in the workspace (match the house DNA, don't invent a new one); (c) domain exploration — what already exists in the codebase (use a Workflow with adversarial verification of claims; file:line evidence mandatory). Archive every digest as research/<date>_input-<source>.md.

4. PLAN.md

Workstreams ("the angles") → task ledger with IDs (T1… for now-work, T20… for gated ship-work) → each task gets command-checkable acceptance criteria (verify the denominators exist! if the criterion says "100 samples", confirm 100 samples exist) → explicit human decision points (the Triage Inbox). Separate freeze-safe/local work from gated/ship work.

5. CLAUDE.md (lane home)

Folder map · three-layer model routing table (Sonnet = heavy lifting + coding; Opus = blind adversarial verification + decision judging; Fable = supervisor, driver loop, DriftGuard, design gate) · non-negotiables (inherit ALL house inviolables from references/design-principles.md §Rules, plus lane-specific ones) · knowledge sources with ABSOLUTE paths (use-don't-re-derive) · how to run.

6. HARNESS.md (architecture)

The three rings (Mission loop / Driver loop / Tick) · a table mapping every loop the user asked for (R&D, verify, simplify, build, git, refactor, fix, CI/CD, review-fix [harvest auto-reviewer comments — see design-principles.md §Review-feedback loop], closeout, housekeeping) to its ring and mechanism and its agent-skills:* binding (the skill column — bind each ring to its deep playbook per references/skill-rings.md; house-generic only where the pack is absent) · contract rules · patterns chosen AND rejected (with reasons) · when NOT to run the harness.

7. The engine — harness/<slug>-loop.mjs

Start from references/mjs-template.mjs. Invariants: meta block first (pure literal); design-comment block citing the doctrine; all paths as consts; reused prompt constants (CAP/RULES/KNOWLEDGE); SCREAMING_SNAKE schemas with additionalProperties:false; one task per tick; planner writes the rubric BEFORE the implementer starts; verifier is BLIND (artifacts only, never reasoning) and re-runs rubric commands; secretLeak/phiLeak → ABORT; exactly one repair then stop; Fable DriftGuard (no model override) checks the LANE not the rubric; every stop is a return with {stopped, violations, humanNext}, never a throw. NO Date.now()/Math.random()/fs in the script. v2.0 invariants: a Preflight phase runs first (env/mount + PLAN↔state lint + re-run the regression ratchet; fail-closed); the planner skips OPEN-breaker tasks, honors deps[] (DAG), and prefers kind:repair; a verified repair emits newRegressionCheck (the ratchet is non-decreasing — agents never delete a guard); see references/self-repair.md.

8. Driver protocol — harness/LOOP.md + harness/tick.sh

LOOP.md: numbered per-wake-up steps — cheap gate first (tick.sh), one tick, branch exactly on the return shape, driver-only state writes, local commits with explicit paths (push is human-only — give the exact command instead), reschedule guidance with cadence, explicit exit conditions, invariants block last. tick.sh: pure-read gate printing TICK / WAIT / SHIP from the state JSON (python3 inside bash; HUMAN-/FREEZE-prefixed blockers are never machine-satisfiable); v2.0 tick.sh also (still read-only) skips OPEN-breaker tasks, honors deps[] with a cycle guard, and reports ratchet=<n>. The LOOP.md driver — the only state writer — branches on stopped:'preflight' and stopped:'ratchet-red' (ratchet-red → enqueue a kind:repair task, M4); on any failed/blocked tick increments breakers[task].consecutiveFailures and at ≥3 OPENs the breaker + ESCALATEs (M2); appends newRegressionCheck to state on a verified repair (M1).

9. State seed + PROMPT.md + SESSION_HANDOFF.md

state/<slug>-state.json: tasks[], done[], triageInbox[] (HUMAN-prefixed items are gates), distilledRules[] (the Fail→Investigate→Verify→Distill→Consult ladder — verified lessons become rules the next tick consults). PROMPT.md: the 8-part house pattern (see templates) — a fresh session pasting it must need nothing else. SESSION_HANDOFF.md: what happened, what ran (usually "ZERO ticks — user decides"), open human items.

10. Verify (non-negotiable, all four)

1. bash harness/tick.sh runs and prints the expected next task.
2. State JSON parses (python3 -c "import json; json.load(open(...))").
3. .mjs syntax-checks inside an async wrapper AND with export stripped (top-level return is legal in the Workflow runtime; bare node --check false-alarms): { echo 'async function main(agent,pipeline,parallel,phase,log,args,budget,workflow){'; sed 's/^export const/const/' <file>; echo '}'; } > /tmp/c.mjs && node --check /tmp/c.mjs. The leading export const meta line false-fails the bare wrapper too — strip it (the runtime does; caught v2.0).
4. Opus adversarial review of the whole folder: path truth, cross-doc consistency (task IDs, models, dates, branches), workflow logic, rule holes (can an agent push? touch frozen branches? leak?), state-machine deadlocks, missing context for a fresh session. Verdict SHIP-READY or FIX-FIRST. Fix every finding in the same session and log the review in SESSION_HANDOFF.md.

11. Close out

Update auto-memory (lane assignment + asset locations) and MEMORY.md index. Re-verify after fixes. Then STOP and ask the user for the first move (selectable options: run first tick / start /loop driver / read docs first / force a different task). Never run the first tick unprompted — plan + harness first, the user decides.

12. Distill back (the skill repairs itself)

After authoring + the step-10 adversarial review, run the Fail→Investigate→Verify→Distill→Consult ladder on the skill ITSELF:

• If this run surfaced a new reusable lesson, append it to references/design-principles.md.
• If you used any figure or quote, it MUST already be (or become) an entry in references/sources.md with a URL + access status. No figure enters doctrine unverified — re-fetch or mark unverified-primary. This is the procedural form of "never fabricate". Generic check (not just the historical stat): grep -nE '[0-9]+%|\$[0-9]+' references/design-principles.md references/self-repair.md and confirm each figure maps to a sources.md row (or is tagged illustrative).
• Bump references/CHANGELOG.md. This is what makes the harness-writer itself a self-repairing harness. Additive only; never silently rewrite verified doctrine — log every change in the CHANGELOG. Fable (the session model) does this edit; do not delegate it to a subagent.

Red lines (refuse to cut these)

• No rubric → no implementer. No blind verifier → no PASS. No DriftGuard → no autonomous loop.
• Acceptance criteria with unverified denominators are fabrication pressure — check the data exists.
• A harness folder inside a gitignored workspace is LOCAL-ONLY — never instruct "commit harness artifacts" without checking .gitignore first.
• Push, PR-create, deploy, migrate = human-gated, always, in every phase including SHIP.
• One task per tick. The human must be able to read every tick's output (Orchestration Tax / Comprehension Debt).
• No figure or quote in the doctrine without a sources.md entry — the skill that forbids fabrication must not fabricate. The "89/62" stat was our own violation (v1); it is gone (v2.0).