create-anpunkit 2.1.0 → 2.2.0

package/template/README.md

@@ -52,7 +52,7 @@ cd my-project && bash setup.sh
 |-----------------|------------------------------------------------------------------------------|
 |`/overview`      |design-research → RESEARCH REVIEW → grill (×2, incl. data/state flow) → OVERVIEW + DATAFLOW → PLAN (Phase 0 first) → STATE|
 |`/infra`         |provision Azure infra: Bicep → what-if → review → apply → INFRA.md + .env.test → AUTH PROOF|
-|`/phase [n]`     |run one phase: research → SCAFFOLD → RED → TEST REVIEW → GREEN → E2E, with circuit breaker|
+|`/phase [n]`     |run one phase: research → SPEC fill → SPEC REVIEW → SCAFFOLD → RED → conformance → GREEN → boundary/E2E, with circuit breaker|
 |`/quick [change]`|small obvious change, direct, no agent chain                                  |
 |`/unstuck`       |deep re-research after a circuit breaker (you trigger it)                     |
 |`/synthesize`    |compress STATE.md, dedup ISSUES.md, prune snapshots                           |
@@ -63,23 +63,31 @@ cd my-project && bash setup.sh
 
 ## Subagents
 
-`researcher` (Haiku, two modes: design + impl) · `planner` (Opus) · `infra-provisioner` (Opus) ·
-`implementer` (Opus, SCAFFOLD/FILL modes) · `test-author` (Opus, blind, RED-first) · `debugger` (Opus, isolated) ·
-`e2e-runner` (Opus, blind, Playwright) · `synthesizer` (Haiku)
+`researcher` (Haiku, two modes: design + impl) · `planner` (Opus, also writes skeleton specs) ·
+`infra-provisioner` (Opus) · `spec-author` (Opus, fills per-phase spec + fixtures) ·
+`implementer` (Opus, SCAFFOLD/FILL modes) · `test-author` (Opus, harness emitter) · `debugger` (Opus, isolated) ·
+`e2e-runner` (Opus, Playwright emitter) · `synthesizer` (Haiku)
 
 The main session is the orchestrator — it routes, it does not implement.
 
-## The loop (v2.1: TDD-first + human gates + coverage guards)
-
-Phases that add a public callable surface run test-first:
-`RESEARCH -> SCAFFOLD -> RED -> TEST REVIEW -> GREEN -> E2E -> FIX -> CLOSE`. The
-implementer writes interface stubs only; the `test-author` writes the suite blind
-against those stubs (it must collect cleanly and FAIL — the RED gate) and emits a
-`docs/test-plan-phase-<n>.md` with a mandatory "NOT covered / assumptions"
-section. **TEST REVIEW** is a human gate: you approve the test plan before the
-implementer fills to green — so "all tests passed but the core was broken" can't
-slip through silently. Pure infra/config/doc phases keep the direct
-`RESEARCH -> IMPLEMENT -> TEST` order (no TEST REVIEW — no public surface).
+## The loop (v2.2: spec-driven contract + upstream human gate + generated tests)
+
+Phases that add a public callable surface run spec-first:
+`RESEARCH -> SPEC fill -> spec-staleness -> SPEC REVIEW -> SCAFFOLD -> RED -> spec-conformance -> GREEN -> boundary/E2E -> FIX -> CLOSE`.
+The reviewable, authoritative artifact is the **spec**, not the test. At `/overview`
+the planner enumerates the case *names* per phase (skeleton `docs/spec-phase-<n>.md`).
+At phase start the new `spec-author` fills them with concrete cases — real inputs,
+real expected outputs, matcher tokens for volatile fields — written to shared
+`fixtures/` files. **SPEC REVIEW** is a human gate that sits *upstream* (before any
+code): you confirm falsifiable claims in plain language ("empty order → 422
+EMPTY_ORDER"). Tests are then GENERATED from the locked spec rows (deep-equality +
+matcher tokens for `data`; Playwright from the descriptor for `ui`) loading the
+*same* fixtures — so a test physically cannot assert different values than the spec.
+`spec-conformance.sh` blocks GREEN until no `TBD` remains and every case-id is cited
+by a boundary test. This is the v2.2 fix for "both agents independently fabricated
+the same wrong contract from a one-line acceptance and the suite went green on a
+broken core." Pure infra/config/doc phases keep the direct
+`RESEARCH -> IMPLEMENT -> TEST` order (no spec, no SPEC REVIEW — no public surface).
 
 Frontend phases are detected by a **deterministic path match** (`has_frontend` +
 the frontend root, both set in `docs/OVERVIEW.md`): if a phase changes a file
@@ -164,6 +172,9 @@ home-dir custom-prompts with a divergent UX).
 - `docs/HISTORY.md` — one line per finished phase
 - `docs/OVERVIEW.md` — project scope, written after double-grill
 - `docs/DATAFLOW.md` — state-transition table per key object (grilled at /overview; drives CLOSE coverage gate)
+- `docs/spec-phase-<n>.md` — per-phase behavioral contract (skeleton at /overview, filled by spec-author; human-reviewed at SPEC REVIEW)
+- `fixtures/<case-id>-{input,expected,ui}.json` — shared by the spec row and the generated test harness (committed; part of the contract)
+- `tests/helpers/spec-assert.{py,ts}` — kit-versioned matcher-aware comparator (honors `<UUID>`, `<ISO8601>`, … tokens)
 - `docs/INFRA.md` — Azure resource manifest + cost estimates (written by infra-provisioner)
 - `docs/ENDPOINTS.md` — API/service endpoint catalogue (maintained by implementer)
 - `docs/.snapshots/` — pre-compact recovery markers (auto-pruned, gitignored)

package/template/commands.src/overview.md

@@ -119,6 +119,18 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
      interactive element the phase introduces (not "page renders 200").
    - Map each phase to the DATAFLOW transitions it is expected to make reachable.
 
+   The planner ALSO writes the up-front SKELETON spec files (v2.2, §5.44/§5.51):
+   one `docs/spec-phase-<n>.md` per public-surface phase (skip Phase 0 + pure
+   infra/config/doc phases), enumerating the case NAMES — happy path, each named
+   edge, each named failure + error code — for every `dataflow:` transition and
+   every `acceptance` criterion, with `TBD` values. The generated header transcludes
+   that phase's `acceptance:` line + in-scope `DATAFLOW.md` transition rows verbatim.
+
+8b. STAMP each skeleton's staleness hash: for every `docs/spec-phase-<n>.md` the
+   planner wrote, run `bash scripts/spec-staleness.sh stamp <n>`. This embeds the
+   hash of the transcluded acceptance line + transition rows so phase-time
+   `/phase` can detect upstream drift. (Values are filled per phase by `spec-author`.)
+
 9. Create docs/STATE.md:
 ```
 
@@ -144,6 +156,11 @@ blocker: none
  ```
 
 Then stop and show me PLAN.md + DATAFLOW.md for approval before any phase starts.
+EXTEND the approval surface (v2.2, §5.51 — one confirmation, no new gate): for each
+public-surface phase, list the transition/acceptance ids it covers and the enumerated
+case NAMES (no values). I confirm the case-name set is COMPLETE here — these names
+are the up-front behavioral contract; values get filled + reviewed per phase at
+`/phase` SPEC REVIEW.
 
 Remind me: "Run `/infra` next to provision the Azure environment (Phase 0) and
 run the one-time AUTH PROOF before starting Phase 1."

package/template/commands.src/phase.md

@@ -1,10 +1,10 @@
 ---
-description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> TEST REVIEW -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression + dataflow + evidence guards at CLOSE.
+description: Run one phase end-to-end. TDD phases run SPEC fill -> SPEC REVIEW -> SCAFFOLD -> RED -> conformance -> GREEN -> boundary/E2E; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression + dataflow + evidence guards at CLOSE.
 argument-hint: [phase number]
 ---
 
 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.
 
@@ -29,20 +29,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.
 
 ---
 
@@ -57,8 +58,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:
 
@@ -66,63 +68,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)
@@ -137,18 +181,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`.
@@ -156,17 +201,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:
@@ -179,20 +224,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.
@@ -202,7 +249,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/docs/DESIGN_LOG.md

@@ -17,6 +17,31 @@
 
 Newest first. One entry per architectural change. Appended by `/log-decision`.
 
+- **(v2.2)** — **Spec-driven behavioral contract.** Closes the v2.1 residual:
+  fabrication under a thin acceptance surface. In v2.1 a phase's whole contract was
+  a single `acceptance:` line; `implementer` and `test-author` each independently
+  elaborated it, and when both filled the same gap the same plausible-but-wrong way
+  the suite went green on a broken core — TEST REVIEW (review of *coverage*, after
+  RED) could not catch a faithful mapping to a *fabricated* criterion. The reframe:
+  the reviewable, authoritative artifact is the SPEC, not the test. New mechanism —
+  skeleton case-NAMES locked at `/overview` (planner) → per-phase concrete filling by
+  a new **`spec-author`** (real inputs/expecteds in shared `fixtures/`) → **SPEC
+  REVIEW** human gate UPSTREAM of code → tests GENERATED from the locked rows
+  (deep-equality + matcher tokens for `data`, Playwright-from-descriptor for `ui`),
+  sharing the same fixtures so a test cannot assert different values than the spec.
+  Two new orchestrator-procedure scripts (`spec-staleness.sh`, `spec-conformance.sh`)
+  replace the human TEST REVIEW gate. `test-author`/`e2e-runner` become harness
+  EMITTERS; `implementer` reads the filled spec as its contract (author ≠ implementer).
+  New decision entries §5.43–§5.56. New files: `.claude/agents/spec-author.md`,
+  `scripts/spec-staleness.sh`, `scripts/spec-conformance.sh`, `tests/helpers/
+  spec-assert.{py,ts}`, plus per-project `docs/spec-phase-<n>.md` + `fixtures/`.
+  REMOVED: the v2.1 human TEST REVIEW gate (humans no longer review tests).
+  NOTE: the v2.1 entries §5.33–§5.42 (TEST REVIEW gate, mandatory frontend E2E +
+  evidence, DATAFLOW coverage, datasource understanding, auth proof/liveness,
+  installer tool-selection) live in the v2.1 release bundle and the on-disk AGENTS.md
+  hard rules; they were never merged into this on-disk log (a hybrid file). The v2.2
+  decision numbers continue at §5.43 for continuity with the requirements doc.
+
 - **(v2.0.2)** — KB setup stays PATH-FIRST: the user clones the KB repo
   themselves (`git clone ... ~/anpunkit-kb`) and passes `--kb-path` (or the
   interactive prompt). New: the remote URL is auto-recorded from the clone's
@@ -452,6 +477,150 @@ native wiring).
 
 ---
 
+> **Numbering note (v2.2).** §5.33–§5.42 are the v2.1 decisions (TEST REVIEW gate,
+> mandatory frontend E2E + evidence, DATAFLOW transition coverage, datasource
+> understanding, auth proof/liveness, installer tool-selection). They were recorded
+> in the v2.1 release bundle and are reflected in AGENTS.md's hard rules, but were
+> never merged into this on-disk log. v2.2 continues at §5.43 for continuity with the
+> v2.2 requirements doc rather than renumbering.
+
+### 5.43 Spec file is a per-phase artifact, not inline in PLAN.md (v2.2)
+**Problem:** a phase's whole behavioral contract was one `acceptance:` line; two
+agents independently elaborated it and could agree on the same wrong contract.
+**Decision:** `docs/spec-phase-<n>.md` is a new per-phase artifact; `PLAN.md`'s
+`acceptance:` stays a one-line summary, the spec is its concrete expansion. The spec
+is self-correlating: a GENERATED header transcludes that phase's `acceptance:` line +
+the in-scope `DATAFLOW.md` transition rows and embeds a staleness hash; only the
+example-case table is human-authored. **Rejected:** expanding `acceptance:` inline in
+PLAN.md — couples the contract to `/replan` churn, bloats PLAN, mixes phase-ordering
+review with concrete-behavior review.
+
+### 5.44 Two-layer baseline/delta — case-names up front, values per phase (v2.2)
+**Decision:** lock behavior in two passes. (1) Up-front case-NAME contract at
+`/overview`: for every DATAFLOW transition + every acceptance criterion, enumerate
+the case names (happy / each edge / each failure + error code), no values yet —
+skeleton spec files. (2) Per-phase concrete filling at `/phase` start (after
+RESEARCH, before SCAFFOLD): `spec-author` fills real payloads/outputs grounded in
+fresh research + the confirmed datasource baseline. **Rationale:** the only design
+that gives BOTH "complete requirements locked before implementation" (names up front)
+and "values grounded in real facts, not plan-time guesses" (per-phase fill). Mirrors
+the established baseline/delta shape (datasource understanding, DATAFLOW coverage).
+
+### 5.45 Skeleton→filled single file; "no unfilled stub" is the conformance invariant (v2.2)
+**Decision:** skeletons are generated at `/overview` (names + `TBD`); `spec-author`
+fills in-place. Invariant: no `TBD` may remain when `spec-conformance.sh` runs
+(between RED and GREEN). **Consequence:** a case that cannot be filled from research
+is escalated as UNDERSPEC / `CASE-SET-DIVERGENCE` BEFORE SCAFFOLD, not discovered at
+GREEN.
+
+### 5.46 Case structure: table row + boundary-typed fixture-ref (v2.2)
+**Decision:** each case is one row — `case-id | covers | boundary | input-ref |
+expected-ref | error-code | volatile`. `covers` = a DATAFLOW transition-id
+(convention `Object:from->to`, no new DATAFLOW column) or acceptance criterion-id
+(`ACC-<k>`). `boundary` ∈ {`data`,`ui`}. Refs point to `fixtures/<case-id>-*.json`
+(scalars may inline). **Key property:** the harness loads the SAME fixture files the
+spec row references — transcription from spec to test is STRUCTURAL, not honor-system;
+a test physically cannot assert different values than the spec.
+
+### 5.47 Boundary test is system-of-record per case; optional mock mirror (v2.2)
+**Decision:** every case has exactly one BOUNDARY test — `data`: real
+HTTP/CLI/message vs the running backend + real services (v2.1's "real API suite");
+`ui`: Playwright vs the deployed/local-docker target (v2.1's E2E). The boundary test
+is the phase gate; green mock alone never closes (rule 5 / §5.38 preserved). A mock
+mirror is optional, shares the fixture + comparator via `TEST_MODE`. "E2E" is
+generalized to *outer-boundary*, not browser-specific: on `has_frontend: false` all
+cases are `data` and `ui` rows are invalid.
+
+### 5.48 Human TEST REVIEW removed; assertion is generated deep-equality (v2.2)
+**Decision:** remove the v2.1 human TEST REVIEW gate. Humans never review tests.
+Tests are not authored — a harness generator emits a deep-equality assertion against
+`fixtures/<case-id>-expected.json` per case row. SPEC REVIEW (§5.50) is the
+human gate; it sits upstream (before SCAFFOLD), reviews concrete behavior in plain
+language, and is the correctness-bearing moment TEST REVIEW was not (wrong thing,
+wrong layer: TEST REVIEW reviewed coverage and asked humans to read assertions).
+
+### 5.49 Volatile fields use matcher tokens in the fixture (v2.2)
+**Decision:** volatile fields (generated IDs, timestamps, order, cursors) are matched
+by TYPE, not excluded. The expected fixture carries sentinels — `<UUID>`, `<ISO8601>`,
+`<ANY_STRING>`, `<ANY_NUMBER>`, `<UNORDERED>`, `<MATCHES:regex>`. The per-language
+comparator `tests/helpers/spec-assert.*` honors them. A token asserts PRESENCE +
+SHAPE, never "ignore this field" (a missing volatile field still fails). The
+comparator is bounded + kit-versioned (one impl per supported language); no
+per-project comparator code.
+
+### 5.50 SPEC REVIEW — per-phase human gate on concrete fillings (v2.2)
+**Decision:** after `spec-author` fills + `spec-staleness.sh` passes, the orchestrator
+surfaces filled cases as FALSIFIABLE CLAIMS; the human confirms/corrects. Rejection
+classification: wrong expected → fix row + fixture (no re-research); wrong input shape
+→ re-dispatch `spec-author`; new case OR contradicted case → hard re-entry (§5.52).
+Unskippable on TDD phases; absent on non-TDD. Replaces v2.1 human TEST REVIEW.
+
+### 5.51 Up-front case-name completeness folded into existing /overview approval (v2.2)
+**Decision:** the existing end-of-`/overview` approval (PLAN.md + DATAFLOW.md) is
+EXTENDED to confirm the cross-phase skeleton case-name set (per phase: covered
+transition/acceptance ids + enumerated case names, no values). One confirmation, one
+surface, no new gate — the names derive from the same PLAN + DATAFLOW being approved.
+
+### 5.52 Any case-set divergence at phase time → hard re-entry (v2.2)
+**Decision:** if phase-time RESEARCH reveals a case not enumerated up front, or one
+that contradicts an enumerated case (locked contract impossible), the phase STOPS.
+`spec-author` returns `CASE-SET-DIVERGENCE`; the human amends the up-front skeleton;
+re-confirms the amended case(s) + any case sharing their `covers` id (the staleness
+hash certifies the unchanged remainder — not re-read); `spec-author` re-fills from
+scratch. **Rationale:** AI writes code; the human owns the contract. No fold-forward,
+no AI amendment of the case-name set.
+
+### 5.53 Dedicated spec-author agent; author ≠ implementer invariant (v2.2)
+**Decision:** a new `spec-author` (Opus) fills the per-phase spec + fixtures after
+RESEARCH, before SPEC REVIEW; returns `CASE-SET-DIVERGENCE` when a case can't be
+filled from real facts or research reveals an unlisted branch. It is NOT
+`implementer`. The **author ≠ implementer** invariant replaces v2.1's test-author
+blindness invariant: `implementer` reads the filled spec as its contract (normal
+spec-driven development), `test-author` becomes a harness emitter (reads spec rows,
+generates the assertion harness, authors no assertions).
+
+### 5.54 UI boundary cases use generated Playwright; e2e-runner is an emitter (v2.2)
+**Decision:** for `ui` cases, `e2e-runner` stops authoring blind and EMITS a
+Playwright assertion from the case's `fixtures/<case-id>-ui.json` descriptor. The
+descriptor vocabulary is closed + kit-versioned: `visible`, `text-equals`, `enabled`,
+`count`. Screenshot-on-each-UI-existence-assertion (v2.1 §5.35) is retained as the
+visual backstop. `ui` cases have no mock mirror (the browser is the boundary). On
+`has_frontend: false`, `ui` rows are invalid.
+
+### 5.55 spec-staleness.sh + spec-conformance.sh as orchestrator-procedure scripts (v2.2)
+**Decision:** two new scripts, same idiom as `regression.sh` (`set -euo pipefail`,
+nonzero = loud fail). `spec-staleness.sh` re-hashes the current PLAN acceptance line +
+in-scope DATAFLOW rows and compares to the spec's embedded header hash (`stamp`
+subcommand embeds it at `/overview`/regenerate; default `check` compares); runs after
+SPEC fill + at SPEC REVIEW entry. `spec-conformance.sh` asserts no `TBD` remains and
+every case-id is cited by a boundary test (`# spec: <case-id>`); runs between RED and
+GREEN, replacing the human TEST REVIEW gate. Both port to Cursor for free (same
+`/phase` body, same bash scripts — no new hook wiring). **Design choice (impl):**
+hashing lives ONLY in the script (a `stamp` subcommand), not duplicated in agent
+prompts; transition-ids are derived (`Object:from->to`) so DATAFLOW needs no new column.
+
+### 5.56 Rule 14 re-seamed: transition→case reachability; conformance owns case→test (v2.2)
+**Decision:** v2.1 rule 14 (DATAFLOW transition coverage) is re-seamed. New
+responsibility: every reachable DATAFLOW transition must have ≥1 FILLED CASE in
+`docs/spec-phase-<n>.md` (was: ≥1 test in `tests/regression/`). Reachability judgment
+unchanged (orchestrator decides at CLOSE; unreachable list PENDING; all live by final
+phase or FAIL HARD). The case→test half moves to `spec-conformance.sh` (every case-id
+cited by a boundary test, which by placement convention lands in `tests/regression/`).
+The full guarantee is preserved by the chain: reachable transition → filled case
+(rule 14) → cited boundary test (conformance) → regression corpus (placement). The
+ENDPOINTS coverage gate is unchanged and orthogonal (endpoint-keyed vs behavior-keyed).
+
+**Numbering reconciliation (v2.2).** The requirements doc's hard-rule table labeled
+new rules 12–16, but its own "Non-changes" section retains the frontend-E2E (old 13),
+datasource (old 15) and auth (old 16) rules — so the table is illustrative, not literal.
+AGENTS.md realizes a coherent set: rule **12** = SPEC REVIEW (reuses the slot freed by
+the removed TEST REVIEW); rule **14** = re-seamed DATAFLOW (kept in place); rules
+**13/15/16** keep their v2.1 meanings (frontend E2E / datasource / auth); the remaining
+new rules append as **17** (spec staleness), **18** (spec conformance), **19** (author ≠
+implementer). This preserves every existing `hard rule N` cross-reference except 12.
+
+---
+
 ## 6. Current file inventory
 ```
 
@@ -542,6 +711,24 @@ create-anpunkit/                   npx package (package.json, bin/cli.js, build.
 ownership taxonomy, adapter generation, idempotent JSON hook merge, VERIFY,
 backup, `--dry-run`).
 
+### v2.2 additions to the inventory
+
+```
+.claude/agents/spec-author.md      NEW — fills per-phase spec + fixtures (Opus); author ≠ implementer
+scripts/spec-staleness.sh          NEW — stamp/check the spec header hash vs PLAN+DATAFLOW (rule 17)
+scripts/spec-conformance.sh        NEW — no-TBD + every case-id cited by a boundary test (rule 18)
+tests/helpers/spec-assert.py       NEW — kit comparator (matcher tokens), Python
+tests/helpers/spec-assert.ts       NEW — kit comparator (matcher tokens), TS/JS
+docs/spec-phase-<n>.md             NEW per-project — skeleton at /overview, filled per phase (committed)
+fixtures/<case-id>-*.json          NEW per-project — shared by spec row + generated harness (committed)
+```
+
+Role deltas: `planner` also writes skeleton specs; `test-author` + `e2e-runner`
+become harness EMITTERS (generate from spec rows, author no assertions);
+`implementer` FILL reads the filled spec as its contract. `.gitattributes` gains
+`*.py text eol=lf` (the kit now ships a Python comparator). REMOVED: the v2.1 human
+TEST REVIEW gate + the `docs/test-plan-phase-<n>.md` artifact.
+
 ## 7. How each original problem maps to its fix
 
 | Problem | Fix |
@@ -587,7 +774,11 @@ backup, `--dry-run`).
 4. The phase gate is a REAL test. A mock suite never closes a phase.
 5. Noisy work writes full output to `docs/research/` and returns only
    terse summary + path — keeps the orchestrator context clean.
-6. Tests are written blind — this is the unbiased-test guarantee.
+6. The behavioral contract is the human-approved SPEC; tests are GENERATED from its
+   case rows against shared fixtures (author ≠ implementer). This is the v2.2
+   unbiased-test guarantee — it replaces v2.1's "tests written blind" (the spec
+   fixtures are authored before code, so the contract can't be shaped to an impl).
+   (Non-TDD phases keep blind-from-acceptance tests — no spec to drive them.)
 7. Never script the Microsoft login UI.
 8. Fail loud, never silent — especially hook wiring.
 9. Honest failure classification — environment issues never burn the debug budget.