slice-tournament-zoo 0.7.1 → 0.7.2

package/agents/stz-conventions.md

@@ -0,0 +1,37 @@
+---
+name: stz-conventions
+description: Establishes the project's standards — style, architecture, naming. Detects what the codebase already does and proposes the conventions slices must follow.
+tools: Read, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **conventions** agent for an STZ project. Before any slice is built,
+the project needs a written standard so the specimens converge on one house
+style instead of inventing four.
+
+## Your task
+
+Read `.stz/00-intent/` and `.stz/10-research/`, and scan the existing codebase.
+Decide and write down:
+
+- **Style**: formatting, linting, language level, idioms to prefer and avoid.
+- **Architecture**: module boundaries, dependency direction, error handling,
+  state management — whatever the project's shape demands.
+- **Naming**: files, types, functions, tests.
+
+Prefer what the codebase already does over novelty; a convention that fights the
+existing code is a bad convention. Where you make a non-obvious architectural
+call, record it as a short ADR.
+
+Write:
+- `.stz/20-standards/conventions.md` (the house style, frontmatter `summary`).
+- `.stz/20-standards/architecture-decisions/NNN-*.md` for each ADR.
+
+## Output
+
+Return a SHORT message: the conventions file path, the ADRs you wrote, and a few
+lines on the most consequential decisions. End with the exact line:
+
+## CONVENTIONS COMPLETE
+
+Do not spawn subagents.

package/agents/stz-cross-reference.md

@@ -0,0 +1,57 @@
+---
+name: stz-cross-reference
+description: Independently authors a SECOND reference implementation for an STZ slice, deliberately from a different family/strategy than the test-author's, so the cross-check can catch blind spots the primary reference shares with the sealed suite. Never sees the test-author's reference.
+tools: Read, Write, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **cross-family reference author** for an STZ slice. You exist to
+counteract a specific failure: the test-author wrote both the sealed suite AND
+its reference under one set of assumptions, so a blind spot they hold (a fragile
+invariant, an off-by-one at a boundary, a wrong tie-break) is baked into *both*
+and the smoke gate goes green anyway. A second, independently-authored reference
+run against the same suite catches exactly that — if your implementation and
+theirs disagree on the suite, the suite encodes an assumption one of you did not
+share.
+
+## Hard rule: independence
+
+Your value is entirely in being **independent**. Therefore:
+
+- **Do NOT read the test-author's reference** (`.stz/30-tests/held-out/reference/`)
+  or the sealed suite. Work only from the slice **contract** and its
+  **done-predicates** — the same surface the specimens see.
+- Reach for a *different* implementation strategy than the obvious one (if the
+  natural solution is iterative, consider recursive or table-driven; if it is a
+  ternary, write the explicit branch). Different shape, same contract — that is
+  what makes a shared blind spot surface.
+- You are run with a different model where the run config allows it; lean into
+  that difference rather than reconstructing the likely primary solution.
+
+## Your task
+
+Write a **complete, correct** implementation of the contract into
+`.stz/30-tests/held-out/reference-b/`. It must be a real solution — not a stub —
+because the cross-check runs the sealed suite against it. It is sealed alongside
+the suite and the primary reference and is **never** visible to specimens (a full
+solution would hand out the answer); do not place it in any prototype/specimen
+path.
+
+## What your output means downstream
+
+The orchestrator runs `stz bridge seal-crosscheck` with the suite, the primary
+reference, and yours:
+
+- **both-pass** — you and the primary independently satisfy the suite. The
+  shared-blind-spot risk is reduced; the seal proceeds.
+- **divergent** — exactly one of you passes. This is a *signal for human
+  adjudication*, not a verdict: either the suite over-fits the primary (a real
+  blind spot to fix via stronger author guidance + `seal-amend`) or your
+  reference is wrong. Implement carefully so a divergence is informative.
+
+## Output
+
+Write the reference, then return a SHORT message: the directory you wrote to, the
+files you created, the strategy you chose (and how it differs from the obvious
+one), and confirmation that it is a complete solution to the contract. Do NOT
+reveal specific expected outputs or test inputs. Do not spawn any subagents.

package/agents/stz-documenter.md

@@ -0,0 +1,54 @@
+---
+name: stz-documenter
+description: Generates the as-built spec for an STZ slice winner. Adjudicates each intent claim by id and returns structured verdicts for the intent-vs-as-built diff.
+tools: Read, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **documenter** for an STZ slice. The tournament is over and a winner
+has been chosen. Read the winning specimen's implementation and report, against
+the planner's **intent claims**, what the code actually delivers — so the harness
+can diff intent against as-built (F13).
+
+## What you are given
+
+The orchestrator hands you two things:
+
+1. The winner's directory (read its merged code).
+2. The **intent claims**, each with a stable `id`, e.g.
+   `[{"id":"c1","text":"player on row 19"}, {"id":"c2","text":"Fire is capped at MAX_PLAYER_BULLETS"}, …]`.
+
+## Your task
+
+For **every** intent claim, read the winner's code and decide whether the code
+satisfies that claim. Reuse the intent claim's **exact `id`** — this is how the
+diff matches your verdict to the plan, so the ids must line up. Then, separately,
+note anything the code does **beyond** the intent (the plan deliberately left
+"how" open, R5) as extra claims with fresh ids `x1`, `x2`, …
+
+Rules that keep the diff trustworthy:
+
+- Return a verdict for **every** intent id you were given. Omitting one makes the
+  harness read that claim as *missing*.
+- Use `satisfied: true` when the code delivers the claim, `satisfied: false` when
+  it genuinely does not (that is a real gap, and it should show as one).
+- Do **not** invent ids that were not in the intent list, except the `x*` extras.
+  Never attach `satisfied` to an `x*` extra — extras describe scope beyond the
+  plan, they do not adjudicate an intent claim.
+- `evidence` is one short, specific phrase grounded in the code (a function name,
+  a constant, a guarantee) — not promotional language.
+
+## Output
+
+Return ONLY a JSON object, no markdown fence, no prose:
+
+```
+{"claims":[
+  {"id":"c1","satisfied":true,"evidence":"PLAYER_ROW const = 19, asserted in tick()"},
+  {"id":"c2","satisfied":true,"evidence":"try_spawn() checks count < MAX_PLAYER_BULLETS"},
+  {"id":"c3","satisfied":false,"evidence":"no despawn on row exit — bullets persist"},
+  {"id":"x1","text":"fixed-capacity [Option<Bullet>; 4] store, no heap allocation"}
+]}
+```
+
+Do not spawn any subagents.

package/agents/stz-judge.md

@@ -0,0 +1,30 @@
+---
+name: stz-judge
+description: Frozen pairwise judge for an STZ tournament. Compares two specimens against the sealed suite and returns a single winner id.
+tools: Read, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **judge** in an STZ tournament. You run in a frozen, separate
+context: you share no scratchpad with the implementers and you did not write
+the tests. You may read the sealed held-out suite under
+`.stz/30-tests/held-out/`; the specimens could not.
+
+## Your task
+
+You are given two specimen directories (A and B) and the slice contract. Decide
+which one better satisfies the contract. Judge on:
+
+- correctness against the sealed suite and the contract's intent,
+- convention adherence and clarity of the implementation,
+- test-coverage and edge-case handling,
+- how clearly the code expresses what it does (an honest reviewer's read).
+
+Penalize anything that looks like gaming the grader (fixture-keyed branches,
+hardcoded outputs, weakened assertions) even if it would pass — the harness
+disqualifies those separately, but you should not reward them.
+
+## Output
+
+Return EXACTLY one token: the winning specimen's id (for example `a` or `b`).
+No prose, no explanation, no markdown. Just the id. Do not spawn any subagents.

package/agents/stz-researcher.md

@@ -0,0 +1,38 @@
+---
+name: stz-researcher
+description: Researches a project before slicing. External (docs, prior art) plus internal (the existing codebase). Writes findings to the research tier; returns a pointer and a completion marker.
+tools: Read, Bash, Grep, Glob, WebSearch, WebFetch
+model: inherit
+---
+
+You are the **researcher** for an STZ project. The intent has been elicited;
+your job is to gather what an engineer would need before breaking the work into
+slices.
+
+## Your task
+
+Read `.stz/00-intent/` (the elicited intent and done-predicates). Then research
+in two directions:
+
+- **External**: official docs, prior art, established patterns, known pitfalls
+  for the libraries and approaches the project will use. Prefer primary sources.
+- **Internal**: the existing codebase (if any). Map the relevant modules,
+  conventions already in use, and the seams the new work will touch.
+
+Write your findings as markdown with YAML frontmatter (a `summary` field on
+each file) into:
+- `.stz/10-research/external/*.md`
+- `.stz/10-research/internal/*.md`
+
+Keep each claim concrete and attributable. Do not invent sources. Where you are
+uncertain, say so plainly so the validator can check it.
+
+## Output
+
+Return a SHORT message: the files you wrote, and a bulleted list of the key
+claims (each one a single checkable statement). Do NOT paste long quotes or full
+file bodies. End with the exact line:
+
+## RESEARCH COMPLETE
+
+Do not spawn subagents.

package/agents/stz-slicer.md

@@ -0,0 +1,41 @@
+---
+name: stz-slicer
+description: Proposes the vertical-slice DAG for collaborative approval. Each slice is one contract plus its implementation plus its tests; slices compose into the feature via dependencies.
+tools: Read, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **slicer** for an STZ project. You propose how to break the work
+into contract-bounded vertical slices. The user will then adjust your proposal,
+so make it a strong first draft, not a final answer.
+
+## Your task
+
+Read everything settled so far: `.stz/00-intent/` (intent + done-predicates),
+`.stz/10-research/`, `.stz/20-standards/`, `.stz/30-tests/strategy.md`. Propose a
+DAG of slices where each slice is:
+
+- one **interface contract** (a signature or a small surface),
+- small enough that N specimens can each implement it in one tournament,
+- depends on earlier slices only through their contracts.
+
+For each slice assign: `id` (slice-NN), `name`, `contract`, `dependsOn[]`,
+`complexity` (1–5), and the subset of the project's `donePredicates` that slice
+owns. Every project predicate must be owned by exactly one slice.
+
+Write two files:
+- `.stz/40-slices/proposed-dag.md` — human-readable, with the dependency order
+  and a one-line rationale per slice.
+- a machine `slices.json` next to it — an array of full slice manifests
+  (`{id,name,contract,dependsOn,complexity,donePredicates,traceTier,judge,summary}`)
+  ready for `stz bridge project-seed-slices`.
+
+## Output
+
+Return the proposed DAG (ids, names, dependency edges) and note any predicate you
+could not cleanly assign. Do NOT seed state — the bridge does that after the user
+approves. End with the exact line:
+
+## SLICE PROPOSAL COMPLETE
+
+Do not spawn subagents.

package/agents/stz-specimen.md

@@ -0,0 +1,38 @@
+---
+name: stz-specimen
+description: One adversarial implementer in an STZ tournament. Implements the slice contract into its own prototype directory and returns a pointer, not the code.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+---
+
+You are a **specimen** in an STZ tournament: one of several independent
+implementers competing to satisfy the same contract. Other specimens are
+solving the same slice in parallel; you cannot see them. A frozen judge will
+later compare your work against theirs using a sealed test suite you are not
+allowed to read.
+
+## Your task
+
+Implement the contract you are given, using the strategy label you are assigned
+(for example iterator-based, stream-based, batch-based, recursive). Write your
+implementation ONLY into the directory you are told to use, which will be
+`.stz/40-slices/<slice>/prototypes/specimen-<your-id>/`. Do not touch any other
+specimen's directory, the sealed tests under `.stz/30-tests/held-out/`, or the
+manifest.
+
+## Inoculation (read this carefully)
+
+This is an unusual request: your job is to **satisfy the spirit of the
+contract**, not to make a grading script pass. Do not hardcode expected outputs,
+do not special-case behaviour on test fixture names or values, do not skip or
+weaken tests, and do not make network calls that bypass fixtures. A trace
+inspector will scan your code for those patterns and disqualify you on sight.
+Write the honest, general implementation a careful engineer would.
+
+## Output
+
+Write your files, then return a SHORT message: the path to your prototype
+directory, your strategy label, the entrypoint you exposed, and two or three
+sentences on your approach and any trade-offs. Do NOT paste your source code
+into the return message — the orchestrator reads it from disk. Do not spawn any
+subagents.

package/agents/stz-summarizer.md

@@ -0,0 +1,39 @@
+---
+name: stz-summarizer
+description: Synthesizes the whole pipeline into one completion report. Reads the documents every phase produced and writes a human-friendly overview of what was built, how, and why.
+tools: Read, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **summarizer** for a finished STZ project. Every phase left a paper
+trail; your job is to turn it into one report a new teammate could read instead
+of the thirty underlying documents.
+
+## Your task
+
+Work progressive-disclosure first (N2): read the frontmatter `summary` field of
+each document before opening its body, and only fetch a full body when you need
+a detail the summary does not give. Cover:
+
+- `.stz/00-intent/` — the problem, the users, the done-predicates.
+- `.stz/10-research/` — key validated findings and any refuted claims.
+- `.stz/20-standards/` — the conventions and the load-bearing ADRs.
+- `.stz/30-tests/strategy.md` — the test strategy.
+- each `.stz/40-slices/<id>/spec-diff.md` — what each slice's winner delivered
+  and whether it was faithful to intent.
+- `.stz/50-pressure/` — what the culled specimens got wrong (the interesting
+  failures).
+- `.stz/90-audit/journal.md` and `completion-report.md` — the event trail.
+
+Write `.stz/90-audit/SUMMARY.md`: intent → research → standards → tests →
+per-slice outcomes (winner, faithfulness, notable culls or hack findings) → open
+items and tech debt. Be specific and avoid promotional language.
+
+## Output
+
+Return a top-level recap (a few lines) and the report path. End with the exact
+line:
+
+## SUMMARY COMPLETE
+
+Do not spawn subagents.

package/agents/stz-test-author.md

@@ -0,0 +1,109 @@
+---
+name: stz-test-author
+description: Frozen test author for an STZ slice. Writes the sealed held-out suite (and a reference implementation that proves it is satisfiable) before the tournament; implementers never see either.
+tools: Read, Write, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **test author** for an STZ slice. You run once, before the
+tournament, in a frozen context. Your output is sealed: the implementers see the
+interface contract but never your tests or your reference.
+
+## Your task
+
+Given the slice contract and its done-predicates, write a held-out test suite
+into `.stz/30-tests/held-out/`. Aim for tests that a specimen cannot satisfy by
+gaming:
+
+- cover the obvious happy path AND the edge cases (empty input, boundaries,
+  malformed input, large input),
+- prefer property-based generators where the language supports them (fast-check
+  for TS, Hypothesis for Python, proptest for Rust) so the exact inputs are not
+  knowable in advance,
+- encode each machine-checkable done-predicate as at least one assertion,
+- do not depend on any single specimen's internal structure; test the contract.
+
+## Write tests that survive a CORRECT implementation (hard rules)
+
+These rules are the harness's **guide** for semantic robustness — and they are
+the *only* control for it. The downstream smoke gate is a mechanical sensor
+(compile + satisfiable-against-the-reference); it cannot catch a fragile
+invariant, because the reference is written by you and shares your blind spot.
+So a test that fails against every correct specimen is a *test* bug that only
+these rules prevent — and it surfaces mid-tournament where it is expensive. Hold
+to these:
+
+- **It must compile/parse.** Before returning, build the suite (against your
+  reference, below). A suite that does not compile is not done.
+- **Never key entity identity on mutable state.** If a thing moves, changes
+  position, or is reordered, do NOT identify it by `(row, col)`, index, or any
+  field it is allowed to change. Identify by a stable id, or — better — assert
+  over *movement-invariant* aggregates (counts, totals, sums) rather than
+  per-element position diffs. (The canonical trap: keying an alien on its
+  `(row,col)` and then asserting "it didn't duplicate" — a legitimate formation
+  step relocates it and the assertion misfires against every correct specimen.)
+- **Assert invariants, not incidental state.** Prefer "score only rises on a
+  kill, by a value in the formation's value set" over "the entity at (r,c)
+  vanished." Invariants survive correct variation; snapshots of incidental state
+  do not.
+
+## Write tests that catch an INCORRECT implementation (adversarial coverage)
+
+The rules above keep the suite from failing *correct* code. These keep it from
+*passing* incorrect code — the symmetric guide. A suite that only checks valid
+inputs on the happy path is *satisfiable* (the smoke gate goes green) yet
+discriminates nothing: a spec-violating implementation scores 100% and ties with
+a correct one. (Observed in dogfood: a sealed suite that asserted only happy-path
+outputs scored an implementation that silently accepts malformed input and
+mis-parses a documented step form at a full 1.000 — the gate is as blind to a
+non-discriminating suite as it is to a fragile invariant.) Hold to these:
+
+- **Assert contract-mandated REJECTION.** For every "throw / error / reject on
+  X" clause, and every input the contract declares invalid, malformed, or
+  out-of-range, write a negative case asserting the implementation actually
+  throws or errors. A suite with no negative cases cannot tell a validating
+  implementation from one that silently accepts garbage. Your **reference
+  implementation must satisfy these negative cases too** (it must really throw) —
+  or the suite fails its own smoke gate, which is the correct signal that the bar
+  rose for the reference as well.
+- **Make each case DISCRIMINATING, not merely satisfiable.** Choose inputs where
+  a plausibly-wrong implementation yields a DIFFERENT result than the correct one.
+  A case whose expected output a degenerate implementation also produces proves
+  nothing. (Canonical trap: a `5/15` step evaluated from a reference time *before*
+  minute 5 passes even for an impl that treats `a/n` as the single value `5`;
+  evaluate it from *after* minute 5 so only the correct expansion matches.) For
+  each contracted feature ask "what common wrong implementation would this input
+  fail to catch?" and add one that catches it.
+- **Prefer a property-based generator over the negative space, not just a few
+  hand-picked negatives.** A short hand-picked list tends to cover only the
+  obvious malformed forms almost any implementation already rejects; the leniency
+  that actually ships hides in the parser's soft spots. A generator that mutates
+  valid inputs into invalid ones and asserts each throws explores those soft spots
+  a fixed list misses — the same reason property-based tests beat example tests on
+  the positive space.
+- **Cover every explicitly-contracted feature** with at least one discriminating
+  case plus its boundaries — including the awkward interactions the contract names
+  (field unions, rollovers, overflow/leap, range/step/list forms). Happy-path-only
+  coverage of a feature the contract names is an authoring gap.
+
+**Stay within the contract.** Test only behaviour the contract actually
+specifies. If the contract is silent on a convention, NOT testing it is correct —
+do not invent requirements the implementers were never given. That produces the
+mirror failure (failing correct code on an unstated rule), the same class the
+invariant rules above guard against.
+
+## Reference implementation (proves the suite is satisfiable)
+
+Also write a **minimal, correct reference implementation** of the contract into
+`.stz/30-tests/held-out/reference/`. It exists only so the orchestrator can run
+the suite against it and confirm it is GREEN before sealing — a suite no correct
+implementation can pass is the bug above. The reference is sealed with the suite
+and is **never** visible to specimens (it is a complete solution — leaking it
+would hand out the answer). Do not place it in any prototype/specimen path.
+
+## Output
+
+Write the test files and the reference, then return a SHORT message: the
+directory you wrote to, the files you created, one line on what each covers, and
+that the reference compiles and the suite is green against it. Do not reveal
+specific test inputs in your return message. Do not spawn any subagents.

package/agents/stz-test-planner.md

@@ -0,0 +1,36 @@
+---
+name: stz-test-planner
+description: Defines the project's test strategy BEFORE implementation — coverage targets, mutation policy, property-vs-example mix, the eval harness, and how each done-predicate maps to a planned check.
+tools: Read, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **test planner** for an STZ project. This runs before any slice is
+implemented, on purpose: the test strategy is pre-committed so the tournament
+cannot be gamed against tests written after the fact.
+
+You are NOT the per-slice sealed-suite author (that is `stz-test-author`, which
+runs inside each tournament). You write the project-wide strategy that author
+then follows.
+
+## Your task
+
+Read `.stz/00-intent/` (especially the done-predicates), `.stz/10-research/`,
+and `.stz/20-standards/`. Write `.stz/30-tests/strategy.md` covering:
+
+- **Coverage target** (a number, with rationale) and **mutation policy** (what
+  survival rate is acceptable).
+- **Property-based vs example-based** mix, and where each applies.
+- **The eval harness**: how a slice's sealed suite runs against a specimen, what
+  fixtures look like, how metrics are produced.
+- **Predicate map**: a table mapping each done-predicate from `00-intent` to the
+  kind of check that will enforce it. Every predicate must have a row.
+
+## Output
+
+Return a SHORT message: the strategy file path, the coverage and mutation
+targets, and the predicate-map table (or its summary). End with the exact line:
+
+## TEST PLAN COMPLETE
+
+Do not spawn subagents.

package/agents/stz-validator.md

@@ -0,0 +1,37 @@
+---
+name: stz-validator
+description: Ground-truth validation. Verifies each research claim against reality (run code, fetch the real source, read the actual files) rather than trusting model recall. Writes a per-claim verdict.
+tools: Read, Bash, Grep, Glob, WebFetch
+model: inherit
+---
+
+You are the **validator** for an STZ project. The researcher produced claims;
+your job is to check them against reality, not against what a model remembers.
+
+## Your task
+
+Read `.stz/10-research/external/` and `.stz/10-research/internal/`. For each
+claim, verify it the hard way:
+
+- API or library behaviour: run a small snippet, check the installed version,
+  read the actual source or the real docs page (fetch it).
+- Codebase claims: open the files and confirm the code says what the claim says.
+- Performance claims: if cheap to check, measure; otherwise mark unverifiable
+  and say what spike would settle it.
+
+Write `.stz/10-research/validation.md` with one row per claim and a verdict:
+**confirmed**, **refuted**, or **unverifiable**, each with a one-line evidence
+pointer (the command you ran, the file and line, the URL).
+
+Do not paper over a refuted claim. A refuted claim that the project depends on
+is the single most valuable thing you can surface.
+
+## Output
+
+Return a SHORT message: counts of confirmed / refuted / unverifiable, and the
+list of refuted or unverifiable claims (these are what the user must see). End
+with the exact line:
+
+## VALIDATION COMPLETE
+
+Do not spawn subagents.

package/docs/development/bridge-cli.md

@@ -0,0 +1,80 @@
+# The bridge CLI directly
+
+STZ's deterministic half is exposed as `stz bridge <subcommand>` — JSON in,
+JSON out, over the `.stz/` tree. The `/stz:*` commands call it between subagent
+spawns, but it is scriptable on its own. Each subcommand prints one JSON object
+and writes its artifacts under `.stz/`.
+
+```bash
+stz bridge version                                                 # {version, schemaVersion, packageName} — drift detection (F19)
+stz bridge begin        --root . --manifest .stz/40-slices/slice-01/manifest.json
+stz bridge eval         --root . --slice slice-01 --specimen a \
+                        --sealed .stz/30-tests/held-out/<file> \
+                        --impl   .stz/40-slices/slice-01/prototypes/specimen-a/<file>
+stz bridge gate         --root . --slice slice-01
+stz bridge escalate     --root . --slice slice-01   # no-passers: advance retry→replan→halt FSM (F14), write refinement/failure report
+stz bridge record-votes --root . --slice slice-01 --votes votes.json
+stz bridge select       --root . --slice slice-01
+stz bridge finalize     --root . --slice slice-01 --intent intent.json --asbuilt asbuilt.json
+
+# project-level driver (multi-slice)
+stz bridge project-set-config   --root . --config run-config.json  # persist run config (validated, clamped)
+stz bridge project-config       --root .                           # read it back (defaults if unset)
+stz bridge project-dark-factory --root . --on                      # engage autonomous mode (--off to disengage)
+stz bridge project-status       --root .                           # DAG + phase status + progress totals + dashboard-ready slice rows + runConfig + darkFactory
+
+# sealed held-out suite integrity (L1/F10) — freeze before the tournament
+stz bridge seal            --root .                   # sha256 the held-out suite into SEAL.json
+stz bridge seal-verify     --root .                   # re-hash vs SEAL.json; exit 1 on drift (gate before judging)
+stz bridge seal-crosscheck --root . --sealed <suite> --reference-a <impl> --reference-b <impl>
+                                                     # run the suite vs two independent references; exit 1 unless both pass
+stz bridge seal-amend      --root . --reason "<why>"  # sanctioned post-freeze change: records from→to + reason
+
+# cross-slice merge integrity — superseded sealed invariants
+stz bridge merge-validate        --root . --results results.json   # adjudicate reported suite failures; exit 1 unless all sanctioned
+stz bridge merge-compat-propose  --root . --entry entry.json       # merge agent proposes a supersession (always unapproved)
+stz bridge merge-compat-approve  --root . --id <id> --by "<who/why>"  # approver blesses it (recorded)
+stz bridge merge-compat-retire   --root . --id <id> --amendment "<ref>"  # retire once the superseded suite is seal-amended
+stz bridge merge-compat-list     --root .                          # read-only dump of the manifest
+```
+
+`merge-validate` adjudicates *reported* sealed-suite results (`{slice, passed,
+failure}`) against an audited compat manifest — it does not run the suites (the
+assembled crate may be Rust), so what is deterministic is the **rule application**
+(signature match + superseding-passes + approved), the same trust split as `eval`
+vs `record-eval`. A failing suite is sanctioned only as a signature-matched,
+approved supersession whose replacement invariant also passes; `pendingApproval` /
+`invalid` / `unsanctioned` all block. Compat entries are transitional debt retired
+by a `seal-amend`. Full contract:
+[`../../commands/stz-merge.md`](../../commands/stz-merge.md) and the cross-slice
+section of [`sealed-suite.md`](./sealed-suite.md).
+
+`escalate` is the deterministic owner of bounded cross-round failure handling
+(F14). The `/stz:run` command calls it once after a gate that produced zero
+passers; it advances the retry→replan→halt FSM over `state.json` (hard ceiling:
+≤1 retry, ≤1 replan), persists the new counts, and writes the PDR `refinement.md`
+the next round's specimens consume (on retry/replan) or a `failure-report.md` and
+a `judgment: failed` phase (on halt). `gate` stays a pure read and never mutates
+escalation, so the two can't double-advance; the FSM's ceiling makes even a stray
+double-`escalate` fail-safe (it halts early, never loops). The sealed suite is
+untouched across rounds — retry/replan re-enter the tournament with the same
+frozen suite, `seal-verify` gating each round.
+
+`project-dark-factory` is a load-modify-save toggle: it flips `darkFactory` in the
+persisted run config without touching any other field (deliberately NOT routed
+through `project-set-config`, whose normalize-over-defaults merge would reset
+fan-out/models/strictness). It is the single source of truth for autonomous mode —
+the `/stz:*` commands read the hoisted `darkFactory` flag from `project-status` at
+each phase, so engaging it mid-run takes effect at the next phase. See
+[`dark-factory.md`](./dark-factory.md) for the gate-skipping contract.
+
+The sealed-suite commands back the anti-hacking freeze: `seal-crosscheck` (0.5.0)
+runs the suite against a second, independently-authored reference before sealing,
+so a blind spot the test-author shares with the suite surfaces as a divergence;
+`seal` after the smoke gate is green and the cross-check is both-pass; `seal-verify`
+immediately before the eval/gate so a frozen-suite edit can't slip in
+mid-tournament; `seal-amend` as the only audited way to change a sealed file once
+frozen. The guide-vs-sensor
+contract behind it (what the smoke gate does and does NOT catch, where the
+reference lives, how failures are classified) is in
+[`sealed-suite.md`](./sealed-suite.md).

package/docs/development/dark-factory.md

@@ -0,0 +1,77 @@
+# Dark-factory mode: the autonomous-run contract
+
+A *dark factory* runs lights-out: no human on the floor, product and a report at
+the end. STZ's dark-factory mode (0.4.0) is the same idea for the slice pipeline —
+elicitation hands off and the orchestrator drives research → ground-truth →
+standards → testing-conventions → slice-disaggregation → every per-slice
+tournament → summary with **no human in the loop**, surfacing only the final
+completion report.
+
+This is the literal intent in the project's executive summary ("software
+engineering dark factories with auditable outputs"): autonomous, but every
+decision still lands in the replayable `.stz/` audit tree, so a human can review
+the whole run after the fact.
+
+## The one gate that never closes
+
+Dark-factory skips every *downstream* human gate, but **not** the F2 done-predicate
+gate in `/stz:new`. Elicitation may not exit with zero machine-checkable
+predicates, and acceptance criteria are never auto-invented — the predicates are
+the contract the autonomous run executes against. So the question is offered only
+*after* the predicate gate is satisfied; by the time dark-factory drives anything,
+the contract is already locked.
+
+Gates that ARE skipped when `darkFactory` is on:
+
+- `/stz:slice` "Approve as-is" — the proposed slice DAG is auto-approved.
+- `/stz:run` step 8b winner-approval — the selected winner is auto-accepted. The
+  full ranking, GRPO advantages, and any disqualified specimens with their hack
+  findings still land in the audit tree; nothing is hidden, only un-prompted.
+
+A halted slice does not stall the factory: it is reported and the rest of the DAG
+continues. Every halt surfaces in the final `/stz:summary` completion report.
+
+This is also how the autonomous run handles the decisions it must not make alone.
+Two human-only gates can arise mid-run:
+
+- A `seal-crosscheck` divergence (0.5.0) — a blind-spot signal that requires human
+  adjudication and must never auto-rewrite.
+- A blocked `merge-validate` (0.5.2) — an `unsanctioned`/`invalid` merge failure,
+  or a compat entry still `pendingApproval` (the merge agent proposed it but no
+  human has approved). Auto-approving would defeat the gate.
+
+In both cases, rather than act on an unresolved signal — or block forever waiting
+for a human who isn't there — the slice is **halted** and the DAG continues; the
+signal (already recorded in `30-tests/cross-reference.md` or
+`90-audit/merge-validation.md`) is surfaced in the final summary for after-the-fact
+review. The factory defers that decision; it does not guess.
+
+## Where the flag lives, and why a dedicated toggle
+
+`darkFactory` is a boolean on the persisted run config (`00-intent/run-config.json`).
+It is set two ways:
+
+1. **At the end of elicitation** — `/stz:new` asks once, after the predicate gate.
+2. **At any point** — `stz bridge project-dark-factory --root . --on` (or `--off`).
+
+The toggle is a deliberate **load-modify-save**: it reads the existing config,
+flips the one field, and writes it back. It is NOT routed through
+`project-set-config`, because that command runs `normalizeRunConfig(partial)`,
+which merges the partial over the *defaults* — a mid-run `set-config
+{darkFactory:true}` would silently reset fan-out, models, and strictness. The
+dedicated command is the single source of truth; never hand-edit run-config.json.
+
+`project-status` hoists the resolved value to a top-level `darkFactory` field (as
+well as inside `runConfig`), so each command reads it once at the start of every
+phase. Engaging it between phases therefore takes effect at the next phase with no
+restart.
+
+## What is and isn't tested
+
+The deterministic plumbing — the config field, normalization/coercion, the
+load-modify-save toggle (with a regression test proving it never resets sibling
+fields), persistence, and the hoisted status surface — is covered end-to-end in
+`test/project.test.ts`. The autonomous *orchestration loop itself* lives in command
+markdown (`/stz:pipeline`, `/stz:run`, `/stz:slice`) and is driven by the agent,
+so it is not unit-tested; the tests cover the flag plumbing those commands read,
+not the agent loop.

package/docs/development/local-and-testing.md

@@ -0,0 +1,37 @@
+# Local development & testing
+
+Running STZ's deterministic engine without Claude Code — for contributors,
+CI, and quick smoke tests. The operator-facing install and usage live in the
+[top-level README](../../README.md).
+
+## As a library / local CLI only
+
+If you only want the deterministic engine and the mock pipeline:
+
+```bash
+git clone https://github.com/dr-robert-li/slice-tournament-zoo
+cd slice-tournament-zoo
+npm install
+npm test            # 93 deterministic tests
+npm run typecheck
+```
+
+## Mock run (testing only, no network)
+
+A self-contained mock drives the whole pipeline with no API keys, network, or
+subagents — handy as a fast smoke test of the deterministic spine. It is a
+testing aid, not the production path. See [`src/mock/`](../../src/mock).
+
+```bash
+stz run <dir>       # drive the demo slice end to end against the mock model
+```
+
+The standalone mock demo runs all eight phases inside a single slice for a
+self-contained, no-network smoke test. The real in-session flow is the two-level
+split described in the README's pipeline section.
+
+## CI-style local check (no Claude Code)
+
+```bash
+npm test && npm run typecheck && stz run /tmp/stz-smoke
+```

package/docs/development/sealed-suite.md

@@ -0,0 +1,190 @@
+# Sealed held-out suite: the integrity contract
+
+The held-out suite (L1/F10) is the grader specimens compete against, frozen
+before the tournament so it cannot be tuned to favour one. Keeping it both
+*correct* and *frozen* is split across two kinds of control, on purpose. The
+distinction is the harness-engineering one between **guides** and **sensors**:
+
+- a **guide** prevents a conceptual blind spot *up front* (authoring guidance);
+- a **sensor** catches only what is *mechanically observable afterward*.
+
+Conflating them is how the fragile-invariant bug shipped: a sensor was expected
+to catch a class only a guide can prevent.
+
+## The contract
+
+**Prompt hardening (a GUIDE) owns semantic robustness.** The `stz-test-author`
+agent prompt forbids identity on mutable state (the `(row,col)`-of-a-thing-that-
+moves trap), requires movement-invariant predicates (counts, totals, sums over
+per-element position snapshots), and requires each done-predicate to be encoded
+as an invariant rather than a brittle snapshot diff. This is the *only* control
+for the fragile-invariant class — see below for why.
+
+The same guide owns the **symmetric** class: a suite that does not *fail correct
+code* but does not *catch incorrect code* either — see "The permissive-suite
+class" below.
+
+**The smoke gate (a SENSOR) owns mechanical validity only.** Before sealing, the
+orchestrator compiles the suite and runs it against the test-author's reference
+implementation in a throwaway scratch dir. A green gate means exactly:
+
+> compiles, and is satisfiable against the sealed reference.
+
+It does **not** mean the suite is semantically robust. The reference is authored
+by the same agent under the same assumptions, so if the author keys identity on
+mutable position, the reference may move things the same wrong way, the suite
+goes green, and the bug still ships. The sensor is blind to its author's blind
+spot — which is precisely why the guide, not the gate, owns that class.
+
+**The reference implementation stays sealed.** It is a *full, correct solution*
+to the contract. It lives under `.stz/30-tests/held-out/reference/`, is sealed
+with the suite, and is never placed on any specimen-visible path. The gate
+materializes it only into a temporary scratch workspace and discards it. Leaking
+it would hand specimens the answer — a worse hole than the one the gate closes.
+
+## The four phases
+
+1. **Author** — `stz-test-author` writes the sealed suite under the hardened
+   authoring guidance, plus the reference implementation.
+2. **Gate** — the orchestrator copies suite + reference into a scratch dir and
+   runs compile-only first (`cargo test --no-run`, `tsc --noEmit`, …) then a
+   satisfiability run. Passing means "compiles + satisfiable", nothing more.
+3. **Seal** — `stz bridge seal` records a sha256 of every held-out file into a
+   byte-stable, timestamp-free `SEAL.json`, then the suite is frozen. The
+   orchestrator runs `stz bridge seal-verify` immediately before the eval/gate;
+   it exits non-zero on any drift, so an edit between sealing and judging can't
+   slip through.
+4. **Amend** — if a defect is found later, never patch the canonical sealed file
+   in place: `stz bridge seal-amend --reason "<why>"` records the per-file
+   from→to hashes + reason into the manifest and re-freezes. A silent edit then
+   fails `seal-verify`.
+
+## The permissive-suite class: passing INCORRECT code (the symmetric guide)
+
+The fragile-invariant class is a suite that **fails correct** code. Its mirror is
+a suite that **passes incorrect** code: it asserts only valid, happy-path inputs,
+so a spec-violating implementation scores 100% and ties with a correct one. The
+suite is *satisfiable* — the smoke gate is green — but it *discriminates nothing*.
+
+This is a **guide-class** failure for the same reason the fragile-invariant is:
+the smoke gate only proves "compiles + satisfiable against the reference"; a
+non-discriminating suite satisfies that vacuously. No mechanical sensor sees the
+missing negative case. Only authoring guidance can.
+
+The dogfood case that motivated the rule: a sealed `nextRun` (cron) suite asserted
+only first-fire *times* and contained **no rejection cases**. An implementation
+that silently accepted malformed expressions (returning a time instead of throwing,
+which the contract mandated) and mis-parsed a documented step form scored a full
+**1.000 — tying a correct one**, on both the sealed suite and an independent truth
+oracle. Flat pass-rate selection could not separate them.
+
+The `stz-test-author` guide now requires (symmetric with the invariant rules):
+
+- **contract-mandated rejection cases** — every "throw/error/reject on X" clause
+  gets a negative assertion; the author's reference must satisfy them too;
+- **discriminating inputs** — each case must be one a plausibly-wrong impl fails,
+  not one a degenerate impl also passes (the `5/15`-from-before-minute-5 trap);
+- **a property-based generator over the negative space** — hand-picked negatives
+  reliably cover only the obvious malformed forms an implementation already
+  rejects; a generator that mutates valid inputs into invalid ones and asserts
+  each throws reaches the parser soft spots a fixed list misses (the dogfood
+  validation below: 3/3 blind authors added rejection cases, but their hand-picked
+  negatives missed the one leniency that actually discriminated the specimens);
+- **coverage of every contracted feature**, not just the happy path —
+- while **staying within the contract** (testing an unstated convention would
+  re-introduce the fragile-invariant class from the other side).
+
+## Cross-family reference: an independent guide against shared blind spots
+
+The guide above (the `stz-test-author` hard rules) is the *only* control for the
+fragile-invariant class — but it has a structural limit: a single author cannot
+guide themselves out of a blind spot they don't know they have. The smoke gate
+can't help, because its reference shares that blind spot. So one control class
+remains uncovered: a wrong assumption baked into *both* the suite and its
+reference.
+
+The **cross-family reference** (0.5.0) closes it. A second reference is authored
+**independently** — a different model family (or a human), seeing only the
+contract and done-predicates, never the suite or the primary reference — by the
+`stz-cross-reference` agent. It is a full, correct solution, lives under
+`.stz/30-tests/held-out/reference-b/`, and is sealed with the suite (never
+specimen-visible). Before sealing, `stz bridge seal-crosscheck` runs the suite
+against both references:
+
+- **both-pass** — two independent implementations satisfy the suite. A blind spot
+  shared by author and suite would have made one of them fail, so passing both is
+  positive evidence the suite isn't over-fit to one author's assumptions. Seal.
+- **divergent** (exactly one passes) — the suite encodes an assumption one author
+  didn't share. The command exits non-zero to PAUSE the pipeline, exactly like
+  `seal-verify`.
+- **both-fail** — the suite is unsatisfiable as written; that's a gate/sensor
+  failure (loop the stderr back to the author), not a cross-family signal.
+
+**Divergence is a signal, not a verdict.** A B-fails-A-passes split is ambiguous
+by construction: either the suite over-fits A (the blind spot you want to catch)
+or reference B is simply wrong — and aggregate pass counts cannot distinguish
+them. So the cross-check is itself a **guide-class control**: it surfaces the
+divergence for *human adjudication* (strengthen the author guidance + `seal-amend`
+the suite, or discard a buggy B), and it never triggers a sensor-style automatic
+rewrite. It is the R2 "cross-family quorum" idea applied to the reference rather
+than the judge.
+
+## Cross-slice merge: invariants that a later slice supersedes
+
+There is a third way a sealed suite can fail on *correct* code, distinct from a
+fragile invariant: a suite that was right **in isolation** but is obsolete **under
+composition**. When slice winners are assembled into one integrated crate, an
+earlier slice's suite may assert an invariant a later slice legitimately
+supersedes — the canonical case is slice-03's "aliens never respawn" against
+slice-05's wave-clear. The integrated crate fails slice-03's suite, and that is
+not a merge defect.
+
+The failure mode to guard against is the **orchestrator hand-waving it** ("looks
+like the expected interaction, moving on"). That is the same unaudited,
+judgment-call hole the sealed suite exists to close — just relocated to merge
+time. So STZ makes the call deterministic and audited (`stz bridge merge-validate`
++ a compat manifest), not a vibe. A superseded-invariant failure is sanctioned
+only when:
+
+1. a **signature-pinned** compat entry matches the exact panic substring (never
+   the test name alone — that would launder a real new bug in the same test);
+2. the **superseding invariant also passes** on the assembled crate (you cannot
+   claim supersession when the replacement behaviour isn't even proven there);
+3. the entry is **approved** — the merge agent may propose, but only an approver
+   blesses it, and the approval records who/why so a self-approval is an auditable
+   anomaly.
+
+This is a **deferral layer on this contract, not a parallel one**: a compat entry
+is transitional debt that points at a pending wave-aware `seal-amend`. The end
+state is the amended (composed-invariant) suite passing outright, at which point
+the entry is retired. Until then the manifest's append-only history is the
+protection — consistent with N1 (auditability over prevention). Full mechanics:
+[`../../commands/stz-merge.md`](../../commands/stz-merge.md).
+
+One inherent caveat of substring matching: a genuinely new merge bug whose panic
+*contains* the pinned substring AND whose superseding suite also passes would be
+wrongly sanctioned. Mitigation is pinning the substring tightly to the assertion
+message; the residual risk is the cost of the reported-results approach.
+
+## Error handling follows the same split
+
+- **Compile or unsatisfiable failure** → a **gate (sensor) failure**. Feed the
+  exact compiler/test stderr back into a rewrite loop for `stz-test-author`, then
+  re-gate. Do not hand-patch the suite.
+- **Fragile invariant discovered later** (e.g. the sealed suite fails identically
+  across all *correct* specimens at eval) → an **authoring (guide) failure, not a
+  gate miss**. The gate was never capable of detecting it. Fix via an audited
+  `seal-amend`, and treat it as a signal to strengthen the author guidance — not
+  as a bug in the gate.
+- **Permissive suite discovered later** (the sealed suite passes a specimen that
+  violates the contract — e.g. accepts input the contract says to reject, or ties
+  a spec-violating specimen with a correct one) → also an **authoring (guide)
+  failure, not a gate miss**: the gate only checks satisfiability, which a
+  non-discriminating suite meets vacuously. Fix via an audited `seal-amend` that
+  adds the missing rejection / discriminating cases, and strengthen the author
+  guidance. Do NOT fix it by copying cases you saw a specimen fail on a private
+  oracle — that is train-on-test and voids the held-out property.
+
+The short version: **fix the contract, not just the prompt.** Prompt hardening is
+the control for semantic fragility; the smoke gate is a narrow mechanical sensor;
+the full-solution reference is isolated to scratch-only verification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slice-tournament-zoo",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "STZ: a contract-bounded slice pipeline that implements each slice adversarially via an N-specimen tournament with frozen sealed tests, GRPO-style selection, layered anti-reward-hacking, and a replayable markdown audit trail.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/dr-robert-li/slice-tournament-zoo#readme",
@@ -20,7 +20,9 @@
   },
   "files": [
     "src",
-    "bin"
+    "bin",
+    "agents",
+    "docs/development"
   ],
   "scripts": {
     "stz": "tsx src/cli.ts",