create-anpunkit 2.1.0 → 2.2.0

package/template/.cursor/commands/phase.md

@@ -1,5 +1,5 @@
 Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
-you do NOT implement or debug yourself.
+you do NOT implement, fill specs, or debug yourself.
 
 Note: subagents cannot talk to the user. Only YOU can.
 
@@ -24,20 +24,21 @@ b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
 c. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
    pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
 
-d. AUTH LIVENESS GATE (hard rule 16 — replaces the old soft nudge): if this phase
-   will run a real/E2E suite, confirm every credential it needs is live NOW.
+d. AUTH LIVENESS GATE (hard rule 16): if this phase will run a boundary/E2E suite,
+   confirm every credential it needs is live NOW.
    - If INFRA.md has no `AUTH PROOF: PASS` marker -> STOP: "Auth never proven
      reusable. Run `/infra` first."
    - Run `scripts/auth-setup.sh --check` (Entra token obtainable + not expired)
      and, for each external system this phase touches (docs/DATAFLOW.md external
      rows + docs/ENDPOINTS.md auth column), confirm its credential is obtainable
-     headlessly. Any failure -> real/E2E is BLOCKED; tell me what to run; the
+     headlessly. Any failure -> boundary/E2E is BLOCKED; tell me what to run; the
      MOCK suite may still proceed.
 
 e. FRONTEND TRIGGER (hard rule 13): read docs/OVERVIEW.md `has_frontend` + the
    frontend root. Set FRONTEND_PHASE=true iff `has_frontend: true` AND this
    phase's `changes` (docs/PLAN.md) include any path under the frontend root.
-   This is a PATH MATCH, not a judgment call. Record FRONTEND_PHASE for the GATE.
+   This is a PATH MATCH, not a judgment call. Record FRONTEND_PHASE — it gates the
+   `ui` boundary run + evidence at CLOSE.
 
 ---
 
@@ -52,8 +53,9 @@ datasource, compare what it touches to the confirmed BASELINE in
 docs/research/datasource-<name>.md. If it touches a NEW table/column beyond the
 baseline -> surface my understanding of just that delta as a falsifiable claim;
 WAIT for confirm; append it to datasource-<name>.md. If it touches only confirmed
-data -> proceed with a one-line note, no stop. Real/E2E against an UNCONFIRMED
-datasource is HARD-BLOCKED (mock still runs).
+data -> proceed with a one-line note, no stop. Boundary/E2E against an UNCONFIRMED
+datasource is HARD-BLOCKED (mock still runs). The confirmed baseline is what
+`spec-author` grounds fixtures in.
 
 Then classify the phase:
 
@@ -61,63 +63,105 @@ Then classify the phase:
   exported function/class, CLI command, message contract) assertable from the
   acceptance spec. Size is NOT the criterion.
 
-- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3a → §3r → §3b).
+- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3 → §4 → §5 → §6 → §7).
 - Pure infra/config/doc, no public surface -> `TDD_PHASE=false` -> run the
   non-TDD path (§2N → §3N).
 - AMBIGUOUS -> default `TDD_PHASE=true`, but STATE the classification + the reason
-  to me, so I can override to non-TDD BEFORE SCAFFOLD fires. (Hard rule 11: never
-  downgrade a TDD phase just to dodge the RED gate.)
+  to me, so I can override to non-TDD BEFORE SPEC fill fires. (Hard rule 11: never
+  downgrade a TDD phase just to dodge the gates.)
 
 =====================================================================
 ## TDD PATH  (TDD_PHASE=true)
 =====================================================================
 
-## 2. SCAFFOLD
+## 2. SPEC FILL + STALENESS
+
+a. SKELETON CHECK: confirm docs/spec-phase-<n>.md exists (planner generated it at
+   /overview). If MISSING (planner classified it non-TDD, or it's a new phase from
+   /replan): generate the skeleton NOW from this phase's PLAN.md `acceptance` +
+   `dataflow:` transitions in the planner skeleton format (generated header + named
+   `TBD` rows), then `bash scripts/spec-staleness.sh stamp <n>` to stamp its hash.
+
+b. Dispatch `spec-author`. It fills each case row with a real input payload
+   (`fixtures/<case-id>-input.json`), concrete expected output
+   (`fixtures/<case-id>-expected.json`), matcher tokens for volatile fields,
+   `error-code` for failures, and `selector/assert/value` `ui` descriptors —
+   grounded in the RESEARCH findings + the confirmed datasource baseline.
+
+c. CASE-SET-DIVERGENCE (hard re-entry, hard rule 12 / §5.52): if `spec-author`
+   returns `CASE-SET-DIVERGENCE` (a required case can't be filled from real facts,
+   or research revealed an unlisted/contradicted case) -> STOP. Surface the finding.
+   I amend the up-front case-name contract in the skeleton; you re-stamp
+   (`bash scripts/spec-staleness.sh stamp <n>`); then re-dispatch `spec-author` to
+   re-fill from scratch. AI never amends the case-name set — I own the contract.
+
+d. STALENESS (hard rule 17): run `bash scripts/spec-staleness.sh <n>`. Nonzero
+   (upstream PLAN acceptance line / DATAFLOW rows drifted since the skeleton was
+   stamped, e.g. via /replan) -> regenerate the skeleton header from current
+   PLAN/DATAFLOW, re-stamp, re-dispatch `spec-author`. Do NOT hand-edit the hash.
+
+## 3. SPEC REVIEW — human gate (hard rule 12)
+
+STOP. Surface the FILLED cases to me as FALSIFIABLE CLAIMS in plain language, e.g.:
+  - "POST /orders/submit with an empty line-item list → 422 EMPTY_ORDER."
+  - "Successful submit of a 3-line order → 201; order.id is a UUID; order.status is
+    'submitted'."
+Re-run `bash scripts/spec-staleness.sh <n>` at entry (nonzero -> back to §2d).
+SCAFFOLD cannot begin until I confirm. Classify any rejection WITH me (§5.50):
+  - WRONG EXPECTED -> fix the case row + `fixtures/<case-id>-expected.json`; no
+    re-research. (You may patch the fixture directly per my correction.)
+  - WRONG INPUT SHAPE -> re-dispatch `spec-author` with the correction.
+  - NEW CASE or CONTRADICTED CASE -> hard re-entry (§2c): I amend the skeleton, you
+    re-stamp, re-confirm the amended case(s) + any case sharing their `covers` id
+    (the staleness hash certifies the unchanged remainder — not re-read), re-fill.
+Loop until I approve. Unskippable on TDD phases.
+
+## 4. SCAFFOLD
 
 Dispatch `implementer` in SCAFFOLD mode: interface stubs only (signatures +
-types; bodies raise NotImplementedError / return 501); NO logic, NO tests.
-Returns the stub files + the interface surface.
+types; bodies raise NotImplementedError / return 501); NO logic, NO tests, NO
+edits to the spec or fixtures. Returns the stub files + the interface surface.
 
-## 3a. RED
+## 5. RED
 
-Dispatch `test-author` to write the REAL API suite (+ mock) BLIND against the
-stubs + acceptance, AND emit docs/test-plan-phase-<n>.md (acceptance criteria →
-test names, plus a mandatory "NOT covered / assumptions" section). Place
-contract/ENDPOINTS/DATAFLOW-transition tests in `tests/regression/`, phase-local
-tests in `tests/phase-<n>/`. Run the suite.
+Dispatch `test-author` to EMIT the boundary harness from the locked spec `data`
+rows: one deep-equality assertion per case against `fixtures/<case-id>-expected.json`
+via the kit comparator `tests/helpers/spec-assert.*`, each citing its case with a
+`# spec: <case-id>` comment. It does NOT author assertions — it generates them from
+the spec. Place contract/ENDPOINTS/transition tests in `tests/regression/`,
+phase-local in `tests/phase-<n>/`.
 
-RED GATE = every acceptance test COLLECTS cleanly AND FAILS (assertion /
-NotImplemented).
-- Any test PASSES on stubs -> STOP (spec trivial or test wrong); show me.
+If FRONTEND_PHASE (and the phase has `ui` cases): also dispatch `e2e-runner` to EMIT
+Playwright assertions from each `ui` case's `fixtures/<case-id>-ui.json` descriptor,
+each citing `// spec: <case-id>`. Run the suites.
+
+RED GATE = every case test COLLECTS cleanly AND FAILS (assertion / NotImplemented).
+- Any test PASSES on stubs -> STOP (spec trivial or emitter wrong); show me.
 - Collection / import / syntax error -> stub mismatch; re-dispatch SCAFFOLD to
   fix SIGNATURES (not logic); re-run.
-- UNDERSPEC -> STOP; ask me to sharpen the acceptance spec.
 
-## 3r. TEST REVIEW — human gate (hard rule 12)
+## 6. CONFORMANCE GATE (hard rule 18) — replaces the v2.1 human TEST REVIEW
 
-STOP. Surface docs/test-plan-phase-<n>.md to me: what each acceptance criterion
-maps to, and the "NOT covered / assumptions" section. GREEN cannot begin until I
-approve. On rejection, classify with me:
-  - MISREAD of an adequate spec -> re-dispatch `test-author` with my feedback as
-    added constraint; re-run RED; re-present the test plan.
-  - UNDERSPEC (the acceptance spec itself is too vague) -> sharpen the acceptance
-    spec in docs/PLAN.md, then re-dispatch `test-author` fresh.
-Loop until I approve. This gate is unskippable on TDD phases.
+Run `bash scripts/spec-conformance.sh <n>`. It loud-fails (and BLOCKS GREEN) if:
+  - any `TBD` marker remains in docs/spec-phase-<n>.md or a referenced fixture, OR
+  - any case-id in the spec table has no boundary test citing it (`# spec: <case-id>`).
+Nonzero -> fix the gap (re-dispatch `spec-author` for a stray TBD, or `test-author`/
+`e2e-runner` for a missing citation) and re-run. GREEN cannot start until it passes.
 
-## 3b. GREEN
+## 7. GREEN + BOUNDARY/E2E
 
-Dispatch `implementer` in FILL mode with the phase spec + research + the test
-file paths (it MAY read the tests — frozen before logic, no overfit — but must
-NOT edit them). Fill to green. Budget 3, WARN@2, STUCK@3.
+Dispatch `implementer` in FILL mode with the FILLED docs/spec-phase-<n>.md + its
+fixtures + research + the generated test file paths (it MAY read the tests — frozen
+before logic, no overfit — but must NOT edit tests, spec, or fixtures). Fill to
+green against the spec. Budget 3, WARN@2, STUCK@3.
 
-If FRONTEND_PHASE (from PRE-FLIGHT e): dispatch `e2e-runner` — MANDATORY, not
-optional (hard rule 13). It reads INFRA.md target, runs `scripts/e2e-stack.sh up`
-/ Playwright / `down`, and captures a screenshot at EACH UI-existence assertion
-regardless of pass/fail to docs/evidence/e2e-phase-<n>/, with a summary in
-docs/research/e2e-<slug>.md. Acceptance spec has no UI-existence criterion ->
-e2e-runner returns UNDERSPEC -> STOP, sharpen the spec.
+Run the BOUNDARY suite (real HTTP/CLI/message; `TEST_MODE=real`). If FRONTEND_PHASE,
+`e2e-runner` runs its emitted `ui` specs — MANDATORY (hard rule 13) — reads INFRA.md
+target, runs `scripts/e2e-stack.sh up` / Playwright / `down`, and captures a
+screenshot at EACH UI-existence assertion regardless of pass/fail to
+docs/evidence/e2e-phase-<n>/, with a summary in docs/research/e2e-<slug>.md.
 
-PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
+PHASE GATE (rule 5) -> go to §8/§9/§10 (see GATE below).
 
 =====================================================================
 ## NON-TDD PATH  (TDD_PHASE=false)
@@ -132,18 +176,19 @@ includes "deployed URL" before proceeding.
 
 ## 3N. TEST (blind)
 
-Dispatch `test-author`. It writes MOCK + REAL API suites from the acceptance
-spec — never reads the logic. (No TEST REVIEW gate on the non-TDD path — no
-public surface to mis-test. e2e-runner only if FRONTEND_PHASE.)
+Dispatch `test-author`. It writes MOCK + boundary suites from the acceptance
+spec — never reads the logic. (No spec file, SPEC REVIEW, or conformance gate on
+the non-TDD path — no public surface to contract. e2e-runner only if FRONTEND_PHASE.)
 
 =====================================================================
 
 ## GATE (both paths)
 
-PHASE GATE = current-phase REAL API suite passes AND (FRONTEND_PHASE) E2E passes
-WITH evidence captured AND the accumulated mock regression corpus stays green AND
-every docs/ENDPOINTS.md entry has a regression test AND every REACHABLE
-docs/DATAFLOW.md transition has a regression test (all checked at CLOSE).
+PHASE GATE = current-phase BOUNDARY suite passes AND (FRONTEND_PHASE) the `ui`
+boundary passes WITH evidence captured AND the accumulated mock regression corpus
+stays green AND every docs/ENDPOINTS.md entry has a regression test AND (TDD)
+`spec-conformance.sh` passed AND every REACHABLE docs/DATAFLOW.md transition has a
+filled case in the phase spec (all checked at CLOSE).
 - GATE PASS -> go to CLOSE.
 - GATE BLOCKED (SERVICE UNAVAILABLE, STACK NOT READY, AZURE UNAVAILABLE, FLAKE)
   -> tell me, wait. Not a code bug. For AZURE UNAVAILABLE: suggest `/infra verify`.
@@ -151,17 +196,17 @@ docs/DATAFLOW.md transition has a regression test (all checked at CLOSE).
 
 ---
 
-## 4. FIX
+## 8. FIX
 
 Dispatch `debugger` (isolated context) on the specific failure.
-- FIXED -> re-run TEST (and the regression corpus).
+- FIXED -> re-run the boundary suite (and the regression corpus).
 - SERVICE UNAVAILABLE -> tell me, wait. Suggest `/infra verify` if Azure.
 - WARN (2 attempts failed) -> relay immediately, then let debugger finish attempt 3.
 - STUCK -> go to ESCALATE.
 
 ---
 
-## 5. ESCALATE — circuit breaker. Mode B.
+## 9. ESCALATE — circuit breaker. Mode B.
 
 FIRST STUCK: STOP. Present to me: the problem, 3 failed hypotheses, the
 debugger's recommendation, the debug file path. Ask what to do. Wait. Options:
@@ -174,20 +219,22 @@ what to try next. Hand control to me.
 
 ---
 
-## 6. CLOSE
+## 10. CLOSE
 
 REGRESSION + COVERAGE GATES (before closing — all FAIL HARD, do not close):
-- Run `scripts/regression.sh` (mock corpus). A failure BLOCKS close -> route to FIX.
+- Run `bash scripts/regression.sh` (mock corpus). A failure BLOCKS close -> route to FIX.
 - ENDPOINTS COVERAGE: every `docs/ENDPOINTS.md` entry MUST have >=1 test in
   `tests/regression/`. Zero coverage -> FAIL HARD.
-- DATAFLOW COVERAGE (hard rule 14): every `docs/DATAFLOW.md` transition whose
-  trigger is REACHABLE in the code shipped so far MUST have >=1 test in
-  `tests/regression/`. Zero coverage on a reachable transition -> FAIL HARD.
-  Unreachable transitions list as PENDING (not failed). IF IS_FINAL_PHASE: any
-  transition still PENDING -> FAIL HARD (everything must be live by the last phase).
+- DATAFLOW COVERAGE (hard rule 14, re-seamed v2.2): every `docs/DATAFLOW.md`
+  transition whose trigger is REACHABLE in the code shipped so far MUST have >=1
+  FILLED CASE in docs/spec-phase-<n>.md. Zero coverage on a reachable transition ->
+  FAIL HARD. Unreachable transitions list as PENDING (not failed). IF
+  IS_FINAL_PHASE: any transition still PENDING -> FAIL HARD. (The case→test half is
+  already enforced by `spec-conformance.sh` at §6 — every case-id is cited by a
+  boundary test, which by placement lands in tests/regression/.)
 - EVIDENCE (FRONTEND_PHASE only, hard rule 13): docs/evidence/e2e-phase-<n>/ must
   contain at least the per-UI-existence-assertion screenshots. Empty -> FAIL HARD.
-- IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
+- IF IS_FINAL_PHASE: additionally run `bash scripts/regression.sh --real` (full real
   corpus). A failure blocks close.
 
 Mark phase `done` in docs/PLAN.md.
@@ -197,7 +244,7 @@ ARCHITECTURE / DATAFLOW SELF-CHECK:
   workflow rule? YES -> run `/log-decision`. NO -> state why not.
 - Did this phase add/change an object's STATE LIFECYCLE? YES -> update
   docs/DATAFLOW.md (hard rule 9) in this CLOSE, and confirm new reachable
-  transitions are covered. NO -> state why not.
+  transitions are covered by a filled case. NO -> state why not.
 
 IF IS_FINAL_PHASE — FINAL CLOSE sequence:
 

package/template/.gitattributes

@@ -5,6 +5,7 @@
 *.js    text eol=lf
 *.mjs   text eol=lf
 *.ts    text eol=lf
+*.py    text eol=lf
 *.json  text eol=lf
 *.md    text eol=lf
 *.ps1   text eol=crlf

package/template/AGENTS.md

@@ -1,9 +1,10 @@
 # anpunkit — portable agent methodology (single source of truth)
 
-<!-- ANPUNKIT-AGENTS-SENTINEL-v2.1 -->
-> **SENTINEL.** The HTML comment above (`ANPUNKIT-AGENTS-SENTINEL-v2.1`) is a
-> load-bearing marker. `setup.sh` greps for it to confirm this file resolved on
-> disk and was not clobbered. Do not remove or rename it.
+<!-- ANPUNKIT-AGENTS-SENTINEL-v2.2 -->
+> **SENTINEL.** The HTML comment above (`ANPUNKIT-AGENTS-SENTINEL-v2.2`) is a
+> load-bearing marker. `setup.sh` greps for the bare prefix `ANPUNKIT-AGENTS-SENTINEL`
+> to confirm this file resolved on disk and was not clobbered. Do not remove or
+> rename it.
 
 > **What this file is.** The complete, tool-agnostic methodology for the anpunkit
 > workflow: the loop, the roles, the procedures, the rituals, and the hard rules.
@@ -31,7 +32,7 @@ A phase runs in one of two orders, chosen at RESEARCH time by the TDD
 APPLICABILITY check (see Procedures → `phase`):
 
 - **TDD phase** (`TDD_PHASE=true`):
-  `RESEARCH -> SCAFFOLD -> RED -> TEST REVIEW -> GREEN -> E2E -> FIX -> CLOSE`
+  `RESEARCH -> SPEC fill -> spec-staleness -> SPEC REVIEW -> SCAFFOLD -> RED -> spec-conformance -> GREEN -> boundary/E2E -> FIX -> CLOSE`
 - **Non-TDD phase** (pure infra / config / doc — `TDD_PHASE=false`):
   `RESEARCH -> IMPLEMENT -> TEST -> FIX -> CLOSE`
 
@@ -39,23 +40,44 @@ APPLICABILITY check (see Procedures → `phase`):
 exported function/class, CLI command, or message contract) that is assertable
 from the acceptance spec." Size is NOT the criterion. On ambiguity, default
 `TDD_PHASE=true` AND state the classification + reason so a human can override to
-non-TDD before SCAFFOLD fires.
-
-**TEST REVIEW (v2.1)** is a mandatory human gate on every TDD phase, sitting
-between RED and GREEN. After `test-author` writes the suite it emits a
-`docs/test-plan-phase-<n>.md` (acceptance criteria → test names, plus a mandatory
-"NOT covered / assumptions" section). The orchestrator surfaces it; FILL cannot
-fire until the human approves. A rejected coverage map is classified at the gate:
-a misread of an adequate spec → re-dispatch `test-author` with feedback; an
-underspecified acceptance spec → sharpen `PLAN.md` and re-dispatch fresh. The gate
-is unskippable on TDD phases and absent on the non-TDD path (no public surface to
-mis-test). This is the fix for "all tests green, core still broken." (§5.33)
-
-**E2E is mandatory, not a judgment call (v2.1).** If the project is frontend-bearing
+non-TDD before SPEC fill fires.
+
+**SPEC REVIEW (v2.2)** is the mandatory human gate on every TDD phase, sitting
+UPSTREAM — between RESEARCH and SCAFFOLD, before any code. The reviewable,
+authoritative artifact is the SPEC, not the test. After RESEARCH, `spec-author`
+fills `docs/spec-phase-<n>.md` (skeleton case-names generated at `/overview`) with
+concrete observable behavior — real input payloads, real expected outputs, matcher
+tokens for volatile fields — grounded in fresh per-phase research and the confirmed
+datasource baseline. `scripts/spec-staleness.sh` then loud-fails if the upstream
+`acceptance:` line or `DATAFLOW.md` transition rows drifted since the skeleton was
+generated. The orchestrator surfaces the filled cases as FALSIFIABLE CLAIMS
+("POST /orders/submit with an empty line-item list → 422 EMPTY_ORDER"); SCAFFOLD
+cannot fire until the human confirms. Rejection is classified at the gate (§5.50):
+wrong expected → fix the case row + fixture; wrong input shape → re-dispatch
+`spec-author`; a new or contradicted case → hard re-entry to amend the up-front
+case-name contract (§5.52). Tests are then GENERATED from the locked spec rows
+(deep-equality + matcher tokens for `data`; Playwright from the descriptor for
+`ui`) — humans never review test code. This is the fix for "both agents
+independently fabricated the same wrong contract from a one-line acceptance and the
+suite went green on a broken core." (§5.43–§5.50)
+
+**Boundary test is the system-of-record per case (v2.2).** Every spec case has
+exactly one OUTER-BOUNDARY test — `data` cases: a real HTTP call / CLI invocation /
+real message against the running backend + real services (v2.1's "real API suite");
+`ui` cases: a Playwright assertion against the deployed (or local-docker) target
+(v2.1's "E2E"). The boundary test is the phase gate; green mock alone never closes a
+phase. A mock mirror is optional and shares the SAME fixture + comparator via a
+`TEST_MODE` flag, so it cannot assert different values than the boundary test. (§5.47)
+
+**E2E is mandatory, not a judgment call.** If the project is frontend-bearing
 (`has_frontend: true` in `docs/OVERVIEW.md`) AND the phase's `changes` touch the
-frontend root recorded in OVERVIEW.md, `e2e-runner` MUST run before CLOSE. The
-trigger is a deterministic path match, not "does this phase feel frontend-y." A
-frontend file changed with no E2E run is a loud CLOSE failure. (§5.34)
+frontend root recorded in OVERVIEW.md, `ui` boundary cases MUST run before CLOSE.
+The trigger is a deterministic path match, not "does this phase feel frontend-y." A
+frontend file changed with no `ui` boundary run is a loud CLOSE failure. `e2e-runner`
+EMITS the Playwright assertion from each case's `ui` descriptor (it no longer authors
+blind) and retains screenshot-on-each-UI-existence-assertion as the visual backstop.
+On `has_frontend: false` projects there is no browser: `ui` case rows are invalid and
+all cases are `data` boundary. (§5.34, §5.54)
 
 -----
 
@@ -81,24 +103,46 @@ can. Escalation is at most two hops.
   `changes` touch the frontend root, the `acceptance` MUST include ≥1 UI-existence
   criterion naming the specific user-visible interactive element introduced (not
   "page renders 200"). Populates each phase's expected `DATAFLOW.md` transitions.
+  At `/overview` it ALSO enumerates the up-front CASE-NAME contract (§5.44): for
+  every `DATAFLOW.md` transition and every `acceptance:` criterion in a TDD phase,
+  the case *names* that must exist (happy path, each named edge, each named failure
+  + error code) — no fixture values yet — written as skeleton `docs/spec-phase-<n>.md`
+  files (generated header + named rows, values `TBD`).
+- **spec-author** — fills the per-phase spec. Runs AFTER RESEARCH, BEFORE SPEC
+  REVIEW. Reads the skeleton `spec-phase-<n>.md`, the confirmed
+  `datasource-<name>.md` baseline, and per-phase RESEARCH for the real API shape;
+  fills each case row with a real input payload (`fixtures/<case-id>-input.json`),
+  concrete expected output (`fixtures/<case-id>-expected.json`), matcher tokens for
+  volatile fields, `error-code` for failures, and `selector/assert/value` for `ui`
+  cases. Returns `CASE-SET-DIVERGENCE` if a required case cannot be filled from real
+  facts, or research reveals an unlisted branch/failure-mode. `spec-author` is NOT
+  `implementer` (author ≠ implementer invariant, §5.53) and never reads
+  implementation logic.
 - **infra-provisioner** — generates Bicep, runs `az deployment what-if`, applies
   only on human approval, writes `docs/INFRA.md` + `.env.test`. Runs the one-time
   AUTH PROOF (§5.37): proves every credential the project's real tests will use is
   obtainable headlessly twice in a row (prime + reuse) with zero prompts.
 - **implementer** — builds ONE phase. Two MODES for TDD phases (SCAFFOLD: stubs
   only; FILL: logic to green) plus a legacy full-build mode for non-TDD phases.
-  Writes code, never tests. Maintains `docs/ENDPOINTS.md` each phase.
-- **test-author** — writes tests BLIND (never reads implementation logic). On TDD
-  phases it is dispatched BEFORE logic exists (RED-first), so blindness is
-  structural, not honor-system. Writes a MOCK suite + a REAL API suite, and emits
-  `docs/test-plan-phase-<n>.md` (the TEST REVIEW artifact) with a mandatory "NOT
-  covered / assumptions" section. For phases touching an external datasource,
-  surfaces any DATA UNDERSTANDING delta (new table/column beyond the confirmed
-  baseline) for confirmation before the real suite runs.
-- **e2e-runner** — writes/runs functional browser E2E (Playwright) BLIND. Reads
-  `docs/INFRA.md` for the target. Captures a screenshot at EACH UI-existence
-  assertion regardless of pass/fail (capture-on-success, not just on-failure) to
-  `docs/evidence/e2e-phase-<n>/`, plus a summary in `docs/research/e2e-<slug>.md`.
+  Writes code, never tests. On TDD phases it reads the human-approved filled
+  `docs/spec-phase-<n>.md` as its behavioral contract (normal spec-driven
+  development) — it never authors spec fixtures (author ≠ implementer, §5.53).
+  Maintains `docs/ENDPOINTS.md` each phase.
+- **test-author** — now a HARNESS EMITTER, not a blind assertion author (§5.53). On
+  TDD phases it reads the locked spec rows and GENERATES the assertion harness: one
+  deep-equality assertion against `fixtures/<case-id>-expected.json` per `data` case,
+  citing the case with a `# spec: <case-id>` comment, using the kit-versioned
+  comparator `tests/helpers/spec-assert.*` (which honors matcher tokens). It does
+  not invent assertions — there is nothing for a human to review at the test layer.
+  Places contract/transition tests in `tests/regression/`, phase-local in
+  `tests/phase-<n>/`; mock-vs-boundary is a `TEST_MODE` flag on the SAME test.
+- **e2e-runner** — now a Playwright EMITTER for `ui` boundary cases, not a blind
+  author (§5.54). Reads `docs/INFRA.md` for the target and each `ui` case's
+  `fixtures/<case-id>-ui.json` descriptor (`selector / assert / value`, closed
+  vocabulary: `visible | text-equals | enabled | count`), and emits the assertion.
+  Captures a screenshot at EACH UI-existence assertion regardless of pass/fail
+  (capture-on-success) to `docs/evidence/e2e-phase-<n>/`, plus a summary in
+  `docs/research/e2e-<slug>.md`.
 - **debugger** — debugs in an ISOLATED context. Writes a trace to
   `docs/research/debug-<slug>.md`; returns a summary.
 - **synthesizer** — compresses `docs/STATE.md` / `docs/ISSUES.md`, prunes
@@ -116,14 +160,19 @@ generated copy per tool (`.claude/commands/`, `.cursor/commands/`).
 - **overview** — bootstrap a project: design-research → grill r1 → design-research
   → RESEARCH REVIEW → re-grill r2 (covers data structures, dataflow, and object
   state flow) → `OVERVIEW.md` (+ `has_frontend`/frontend-root, `DATAFLOW.md`,
-  confirmed datasource understanding) → planner → `PLAN.md` (Phase 0 always first).
+  confirmed datasource understanding) → planner → `PLAN.md` (Phase 0 always first)
+  + skeleton `docs/spec-phase-<n>.md` case-name files. The end-of-`/overview` human
+  approval is EXTENDED to confirm the cross-phase skeleton case-name set in the same
+  surface (no new gate, §5.51).
 - **infra** — provision/verify Azure infra: Bicep → what-if → human review → apply
   → `INFRA.md` + `.env.test`. Runs the one-time AUTH PROOF.
 - **phase [n]** — run one phase end-to-end with the circuit breaker. Chooses the
   TDD or non-TDD order at RESEARCH. PRE-FLIGHT runs the auth liveness check. TDD
-  phases stop at TEST REVIEW before GREEN. Frontend phases run mandatory E2E with
-  screenshot evidence. CLOSE runs the regression guard + ENDPOINTS coverage gate +
-  DATAFLOW transition-coverage gate + evidence-present check.
+  phases: `spec-author` fills the spec → `spec-staleness.sh` → SPEC REVIEW (human,
+  before SCAFFOLD) → SCAFFOLD → RED (generated harness) → `spec-conformance.sh` →
+  GREEN → boundary/E2E. Frontend phases run mandatory `ui` boundary with screenshot
+  evidence. CLOSE runs the regression guard + ENDPOINTS coverage gate + DATAFLOW
+  transition→case coverage gate + evidence-present check.
 - **quick [change]** — small, obvious, non-phase change; no agent chain. Stays
   non-TDD. Runs the mock regression corpus after the change.
 - **unstuck** — deep re-research after a circuit breaker (human-triggered).
@@ -161,7 +210,7 @@ recover: current phase, next action, open blocker.
 
 -----
 
-## Hard rules (1–16)
+## Hard rules (1–19)
 
 1. Before debugging ANY error: grep `docs/ISSUES.md` AND `docs/research/INDEX.md`.
    The SESSION-OPEN ritual surfaces ISSUES.md — there is no excuse to miss it.
@@ -170,15 +219,21 @@ recover: current phase, next action, open blocker.
 3. Every resolved error -> logged to `docs/ISSUES.md` with root cause + failed
    attempts.
 4. End of phase -> synthesize -> context reset -> next phase.
-5. **PHASE GATE** = the current-phase REAL API suite passes AND (frontend phase)
-   the E2E suite passes with screenshot evidence captured AND the accumulated mock
-   regression corpus stays green AND every `docs/ENDPOINTS.md` entry has at least
-   one test in `tests/regression/` AND every REACHABLE `docs/DATAFLOW.md` transition
-   has at least one test in `tests/regression/`. The final phase additionally runs
-   the full REAL regression corpus and requires zero PENDING transitions. A green
-   mock suite alone can never close a phase.
-6. Tests are written by `test-author`, which never sees the implementation logic
-   (unbiased). On TDD phases the suite is written before the logic (RED-first).
+5. **PHASE GATE** = every current-phase spec case's BOUNDARY test passes (`data`:
+   real HTTP/CLI/message; `ui`: Playwright with screenshot evidence) AND the
+   accumulated mock regression corpus stays green AND every `docs/ENDPOINTS.md`
+   entry has at least one test in `tests/regression/` AND `spec-conformance.sh`
+   passed (no TBD, every case-id cited by a boundary test) AND every REACHABLE
+   `docs/DATAFLOW.md` transition has at least one filled case in the phase spec
+   (rule 14). The final phase additionally runs the full REAL regression corpus and
+   requires zero PENDING transitions. A green mock suite alone can never close a phase.
+6. On TDD phases the behavioral contract is the human-approved
+   `docs/spec-phase-<n>.md`; tests are GENERATED from its case rows (not authored):
+   `test-author` emits a deep-equality harness against the shared fixtures for
+   `data` cases, `e2e-runner` emits Playwright from the `ui` descriptor. Because the
+   spec row and the test load the SAME fixture, a test physically cannot assert
+   different values than the locked spec. Humans review the spec (SPEC REVIEW), never
+   the tests.
 7. Service outage is not a bug — `SERVICE UNAVAILABLE` / `AZURE UNAVAILABLE` /
    `STACK NOT READY` / `FLAKE` do not spend the debug budget. Only `LOGIC FAIL`
    reaches the debugger.
@@ -192,24 +247,36 @@ recover: current phase, next action, open blocker.
 11. **No-rationalization (scoped).** Do not, in order to dodge a gate:
     downgrade a TDD phase to non-TDD or route phase-worthy work through `quick`
     (RED gate); set `has_frontend: false` or keep a touched element out of the
-    acceptance spec (E2E / UI-existence gate); mark a reachable transition PENDING
-    (DATAFLOW gate); or skip evidence capture. (Scoped deliberately to these named
-    seams; this is not a broad "never make excuses" rule.)
-12. **TEST REVIEW (TDD phases).** GREEN cannot begin until the human approves
-    `docs/test-plan-phase-<n>.md`. Rejection is classified at the gate (misread
-    spec → re-dispatch test-author with feedback; underspec → sharpen PLAN.md and
-    re-dispatch fresh). Unskippable on TDD phases; absent on the non-TDD path.
+    acceptance spec (E2E / UI-existence gate); fabricate a fixture value or leave a
+    `TBD` to slip past SPEC REVIEW / conformance instead of escalating UNDERSPEC or
+    `CASE-SET-DIVERGENCE`; mark a reachable transition PENDING (DATAFLOW gate); or
+    skip evidence capture. (Scoped deliberately to these named seams; this is not a
+    broad "never make excuses" rule.)
+12. **SPEC REVIEW (TDD phases).** SCAFFOLD cannot begin until the human confirms the
+    filled `docs/spec-phase-<n>.md` cases, surfaced as falsifiable claims. Rejection
+    is classified at the gate (§5.50): wrong expected → fix case row + fixture; wrong
+    input shape → re-dispatch `spec-author`; new or contradicted case → hard re-entry
+    to amend the up-front case-name contract, re-confirm the amended + same-`covers`
+    neighbor cases (staleness-hash certifies the unchanged remainder), then re-fill
+    (§5.52). Unskippable on TDD phases; absent on the non-TDD path (no behavioral
+    contract to review). Replaces the v2.1 human TEST REVIEW gate (removed — humans
+    no longer review tests).
 13. **Mandatory frontend E2E + evidence.** When `has_frontend: true` and the
     phase's `changes` touch the frontend root recorded in OVERVIEW.md, E2E MUST
     run. Each UI-existence assertion captures a screenshot (on success too) to
     `docs/evidence/e2e-phase-<n>/`. Frontend files changed with no E2E run, or a
     closed frontend phase with no evidence on disk, fails CLOSE hard. (Evidence is
     gitignored — present-on-disk at CLOSE is the check, not committed history.)
-14. **DATAFLOW transition coverage.** Every transition in `docs/DATAFLOW.md` whose
-    trigger is reachable in the code shipped so far MUST have ≥1 test in
-    `tests/regression/`; zero coverage on a reachable transition fails CLOSE hard.
+14. **DATAFLOW transition coverage (re-seamed v2.2, §5.56).** Every transition in
+    `docs/DATAFLOW.md` whose trigger is reachable in the code shipped so far MUST
+    have ≥1 FILLED CASE in `docs/spec-phase-<n>.md` (was: ≥1 test in
+    `tests/regression/`); zero coverage on a reachable transition fails CLOSE hard.
     Unreachable transitions list as PENDING. Any transition still PENDING at the
-    final phase fails hard. Peer to the ENDPOINTS coverage gate.
+    final phase fails hard. The case→test half of the old guarantee now lives in
+    `spec-conformance.sh` (rule 18: every case-id is cited by a boundary test, which
+    by placement convention lands in `tests/regression/`). Peer to the ENDPOINTS
+    coverage gate, which is unchanged and orthogonal (endpoint-keyed, not
+    behavior-keyed).
 15. **Datasource data understanding.** Real-suite / E2E tests against an external
     datasource are HARD-BLOCKED until that datasource's DATA UNDERSTANDING is
     confirmed (baseline at `/overview`; per-phase delta-confirm for any
@@ -221,6 +288,25 @@ recover: current phase, next action, open blocker.
     zero prompts; "reusable without interaction" means exactly this. Each `/phase`
     PRE-FLIGHT runs a cheap liveness check (token obtainable, not expired) before
     dispatching real/E2E. Both fail loud; the mock suite proceeds regardless.
+17. **Spec staleness (§5.55).** `scripts/spec-staleness.sh <n>` runs immediately
+    after `spec-author` fills the spec AND again at SPEC REVIEW entry. It re-hashes
+    the current `PLAN.md` `acceptance:` line + the in-scope `DATAFLOW.md` transition
+    rows and compares to the hash embedded in the spec's generated header. A
+    mismatch (upstream drifted since the skeleton was generated) exits nonzero and
+    blocks SPEC REVIEW — the spec must be regenerated/re-filled. The generated
+    header is never hand-edited.
+18. **Spec conformance (§5.55).** `scripts/spec-conformance.sh <n>` runs between RED
+    and GREEN, replacing the removed human TEST REVIEW gate. It loud-fails (blocks
+    GREEN) if any `TBD` marker remains in the spec or its fixtures, or if any case-id
+    in the spec table has no boundary test citing it via the `# spec: <case-id>`
+    convention.
+19. **Author ≠ implementer (§5.53).** `spec-author` and `implementer` are distinct
+    roles. `spec-author` fills the spec + fixtures and NEVER reads implementation
+    logic; `implementer` reads the filled spec as its contract and NEVER authors spec
+    fixtures. `test-author` / `e2e-runner` are harness EMITTERS, not assertion
+    authors. This replaces the v2.1 test-author RED-first blindness invariant: spec
+    fixtures are written before code, so the contract cannot be shaped toward an
+    implementation.
 
 -----
 
@@ -247,8 +333,21 @@ the KB. The kit works normally without a KB.
   transition (from→to) | trigger | who writes | external system`). Living doc,
   grill-driven; drives the CLOSE transition-coverage gate. The data-side analogue
   of `ENDPOINTS.md`. (v2.1)
-- `docs/test-plan-phase-<n>.md` — the TEST REVIEW artifact: acceptance → test names
-  + mandatory "NOT covered / assumptions" section. Human-approved before GREEN. (v2.1)
+- `docs/spec-phase-<n>.md` — the per-phase behavioral contract (v2.2). Skeleton
+  (case names + `TBD` values) generated at `/overview`; filled by `spec-author` per
+  phase. Generated self-correlating header transcludes the phase's `PLAN.md`
+  `acceptance:` line + in-scope `DATAFLOW.md` transition rows and embeds a staleness
+  hash (never hand-edited). The only human-authored region is the example-case table.
+  Human-approved at SPEC REVIEW before SCAFFOLD. (Committed.)
+- `fixtures/<case-id>-input.json` / `-expected.json` / `-ui.json` — the shared
+  fixtures a spec row references AND the generated test harness loads (transcription
+  is structural, not honor-system). `-expected.json` carries matcher tokens for
+  volatile fields; `-ui.json` is the `[{selector,assert,value}]` UI descriptor.
+  (Committed — part of the contract.) (v2.2)
+- `tests/helpers/spec-assert.*` — the kit-versioned per-language comparator that
+  honors matcher tokens (`<UUID>`, `<ISO8601>`, `<ANY_STRING>`, `<ANY_NUMBER>`,
+  `<UNORDERED>`, `<MATCHES:regex>`). One implementation per supported test language;
+  NO per-project comparator code. (v2.2)
 - `docs/evidence/e2e-phase-<n>/` — screenshot evidence captured at each UI-existence
   assertion (gitignored; present-on-disk at CLOSE is the gate). (v2.1)
 - `docs/INFRA.md` — Azure infra manifest: resource IDs, endpoints, cost estimates,
@@ -267,6 +366,10 @@ the KB. The kit works normally without a KB.
 - `tests/phase-<n>/` — phase-local test suites.
 - `tests/regression/` — cross-phase contract tests (the regression corpus). Run by
   `scripts/regression.sh` (default mock; `--real` runs the real corpus).
+- `scripts/spec-staleness.sh <n>` — loud-fails if the spec's generated header drifted
+  from the current `PLAN.md` acceptance line + `DATAFLOW.md` rows (rule 17). (v2.2)
+- `scripts/spec-conformance.sh <n>` — loud-fails on any remaining `TBD` or any
+  case-id with no citing boundary test (rule 18). Runs between RED and GREEN. (v2.2)
 - `scripts/auth-setup.sh` — session Azure credential check. Run once per session.
 - `.claude/kb-config.json` — shared KB path + remote (optional, written by setup.sh).
 - `docs/.kb-snapshot.md` — KB INDEX loaded this session (auto-generated, gitignored).

package/template/CLAUDE.md

@@ -17,6 +17,7 @@ The roles defined in AGENTS.md map to these Claude Code subagent files:
 |researcher        |`.claude/agents/researcher.md`        |haiku     |
 |planner           |`.claude/agents/planner.md`           |opus      |
 |infra-provisioner |`.claude/agents/infra-provisioner.md` |opus      |
+|spec-author       |`.claude/agents/spec-author.md`       |opus      |
 |implementer       |`.claude/agents/implementer.md`       |opus      |
 |test-author       |`.claude/agents/test-author.md`       |opus      |
 |e2e-runner        |`.claude/agents/e2e-runner.md`        |opus      |