create-anpunkit 2.1.0 → 2.3.0

package/template/AGENTS.md

@@ -1,14 +1,16 @@
 # 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.3 -->
+> **SENTINEL.** The HTML comment above (`ANPUNKIT-AGENTS-SENTINEL-v2.3`) 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.
-> This is the ONE place every rule lives. Claude Code, Cursor, and any tool that
-> reads the open `AGENTS.md` standard get the full methodology from here.
+> This is the ONE place every rule lives. Claude Code reads the full methodology
+> from here (as can any tool supporting the open `AGENTS.md` standard). v2.3 is
+> Claude Code only.
 
 > **Anti-drift invariant (load-bearing).** Every rule lives in exactly ONE place:
 > this file. `CLAUDE.md` restates NO rule — it only maps roles to Claude-native
@@ -16,8 +18,10 @@
 > its automation may never contradict. Duplication between files is an
 > architectural defect, not a convenience.
 
-Caveman ULTRA mode always on. Apply the `karpathy-guidelines` skill (engineering
-discipline) on every coding and debugging task.
+Compression is always on: profile `user` from `.claude/ref/compression.md`
+governs all human-facing output; every subagent prompt declares profile
+`internal`. Apply the `karpathy-guidelines` skill (engineering discipline) on
+every coding and debugging task.
 
 -----
 
@@ -25,13 +29,13 @@ discipline) on every coding and debugging task.
 
 `design-research -> grill (×2) -> plan -> implement -> test -> deploy`, one
 VERTICAL SLICE per phase. Implement AND test a phase before the next. The last
-phase always includes deployment.
+phase always includes DEPLOY_KIND completion.
 
 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,34 +43,68 @@ 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
-(`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)
+non-TDD before SPEC fill fires.
+
+**Project flags (adaptive loop, hard rule 10).** DECLARED once at `/overview` and
+recorded in `docs/OVERVIEW.md`: `project_type`, `has_frontend` (+ root),
+`infra_needed`, `e2e_kind` (browser | cli | http | library-api), `deploy_kind`
+(cloud-deploy | package-publish | install-run-verified | none), `knowledge_docs`.
+Per-phase bindings happen at RESEARCH (same idiom as `TDD_PHASE`): the effective
+`E2E_KIND` (browser iff the phase is a frontend phase, else the baseline) and,
+on the final phase, `DEPLOY_KIND` confirmation. Derivation is deterministic
+(tables live in `commands.src/overview.md`); nothing is inferred mid-phase.
+These branch the loop: Phase 0 exists iff `infra_needed`; the boundary run is
+selected by `E2E_KIND`; the final phase completes `DEPLOY_KIND`.
+
+**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)
+
+**The boundary run is mandatory, not a judgment call (per E2E_KIND).** Every phase
+that ships or changes its outer surface MUST run the boundary suite before CLOSE,
+selected by the phase's bound `E2E_KIND`. **Browser** (`has_frontend: true` AND the
+phase's `changes` touch the frontend root recorded in OVERVIEW.md — a deterministic
+path match, not "does this feel frontend-y"): `ui` boundary cases MUST run; 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
+(browser practice + stack ritual: `knowledge/webapp.md`). **cli / http /
+library-api**: the phase's real-mode boundary suite is the outer run, executed
+against the shipped artifact with its transcript captured as evidence. On a project
+whose `e2e_kind` is not `browser` there is no browser: `ui` case rows are invalid.
+(§5.34, §5.54, §5.65)
 
 -----
 
 ## Roles (fresh-context workers)
 
-Each role is a fresh-context worker. Where the host tool supports named subagents
-(Claude Code natively; Cursor reads the same `.claude/agents/` files via its
-Claude-compatibility path), each maps to a definition file. Where it does not, the role
-degrades to a bounded sub-task that dumps its noise to a file and returns only a
-terse summary + path. Workers cannot address the user — only the orchestrator
-can. Escalation is at most two hops.
+Each role is a fresh-context worker. On Claude Code each maps to a named subagent
+definition file (`.claude/agents/*.md`). Each worker dumps its noise to a file and
+returns only a terse summary + path. Workers cannot address the user — only the
+orchestrator can. Escalation is at most two hops.
 
 - **researcher** — two modes. DESIGN: domain/constraint research before planning
   (service limits, API contracts, architectural constraints, cost surprises);
@@ -76,29 +114,57 @@ can. Escalation is at most two hops.
   datasource-<name>.md`. IMPL: per-phase codebase + service investigation. Checks
   the shared KB snapshot first (step 0). Writes findings to `docs/research/`;
   returns terse summary + path.
-- **planner** — research → vertical-slice `docs/PLAN.md`. Phase 0 (infra) always
-  first; the last phase always contains the deploy task. For any phase whose
-  `changes` touch the frontend root, the `acceptance` MUST include ≥1 UI-existence
+- **planner** — research → vertical-slice `docs/PLAN.md`. Phase 0 (infra) first
+  iff `infra_needed: true`; the last phase always completes `deploy_kind`. For any
+  phase whose `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.
-- **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.
+  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** — dispatched only when `infra_needed: true` (Phase 0).
+  Generates IaC, runs the provider's what-if/plan diff, 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. Cloud-specific
+  practice (Azure Bicep/`az`, Entra/MSAL) lives in `knowledge/azure.md`.
 - **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** — the browser boundary emitter (E2E_KIND `browser`), dispatched
+  only for frontend phases; 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`. Stack ritual + config templates: `knowledge/webapp.md`.
+  (Non-browser E2E_KINDs — cli/http/library-api — have no separate emitter; the
+  real-mode boundary suite is the outer run.)
 - **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
@@ -110,20 +176,27 @@ The orchestrator ROUTES. It does not implement or debug.
 
 ## Procedures (the slash-command set)
 
-Named procedures, each with a canonical body in `commands.src/<name>.md` and a
-generated copy per tool (`.claude/commands/`, `.cursor/commands/`).
+Named procedures, each with a canonical body in `commands.src/<name>.md`, copied
+to `.claude/commands/` at install.
 
 - **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).
-- **infra** — provision/verify Azure infra: Bicep → what-if → human review → apply
-  → `INFRA.md` + `.env.test`. Runs the one-time AUTH PROOF.
+  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). Also declares the project flags (`project_type`,
+  `infra_needed`, `e2e_kind`, `deploy_kind`, `knowledge_docs`).
+- **infra** — provision/verify infra (only when `infra_needed: true`): IaC →
+  what-if/plan → human review → apply → `INFRA.md` + `.env.test`. Runs the one-time
+  AUTH PROOF. Cloud specifics in `knowledge/azure.md`.
 - **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).
@@ -139,9 +212,8 @@ generated copy per tool (`.claude/commands/`, `.cursor/commands/`).
 
 ## Rituals (model-run fallback for hooks)
 
-Where the host tool can run lifecycle hooks (Claude Code, Cursor), these rituals
-are AUTOMATED by hook scripts and must NOT be run by hand. Where the tool cannot
-inject context, the model performs them itself.
+On Claude Code these rituals are AUTOMATED by hook scripts and must NOT be run by
+hand. Where a host tool cannot inject context, the model performs them itself.
 
 ### SESSION-OPEN (start / clear / compact-resume)
 
@@ -149,7 +221,7 @@ At the start of every session, before any other work, surface:
 1. git state (branch, uncommitted count, last 3 commits).
 2. `docs/STATE.md` — the current position. READ THIS FIRST.
 3. open items in `docs/ISSUES.md`.
-4. `docs/research/INDEX.md` (research map) + infra status + auth nudge.
+4. `docs/research/INDEX.md` (research map) + infra status (when `infra_needed`).
 5. shared KB: pull latest + load `docs/.kb-snapshot.md` if `.claude/kb-config.json`
    exists.
 6. a one-line reminder of the hard rules below.
@@ -161,7 +233,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,57 +242,103 @@ 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).
-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.
-8. E2E auth = ROPC with a dedicated MFA-excluded test account. NEVER script the
-   Microsoft login UI.
+5. **PHASE GATE** = every current-phase spec case's BOUNDARY test passes (`data`:
+   real HTTP/CLI/message; `ui` (browser E2E_KIND): 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 (browser
+   E2E_KIND). 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` / `STACK NOT READY` /
+   `FLAKE` (plus cloud-specific aliases like `AZURE UNAVAILABLE` per the knowledge
+   doc) do not spend the debug budget. Only `LOGIC FAIL` reaches the debugger.
+8. E2E auth = a dedicated headless-capable test credential. NEVER script an
+   interactive login UI. (Provider specifics — Azure ROPC + MFA-excluded account —
+   in `knowledge/azure.md`.)
 9. Architectural change (new/removed agent, hook, command, or a changed workflow
    rule)? -> run `log-decision` before closing. A phase that changes an object's
    state lifecycle MUST update `docs/DATAFLOW.md` in the same CLOSE.
-10. Azure project? Run `scripts/auth-setup.sh` ONCE per session before any Azure
-    work. Never debug an auth error without checking this first.
+10. **Deterministic flags.** `project_type` / `has_frontend` / `infra_needed` /
+    `e2e_kind` / `deploy_kind` / `knowledge_docs` are DECLARED at `/overview` and
+    recorded in `docs/OVERVIEW.md`; per-phase `TDD_PHASE` + effective `E2E_KIND`
+    are bound at RESEARCH and stated. No flag is ever inferred silently mid-phase;
+    changing one is a `/replan`-level event.
 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.
-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.
+    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 boundary run + evidence (per E2E_KIND).** Browser: 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>/`. Other kinds
+    (cli/http/library-api): the phase's boundary tests MUST run in real mode against
+    the outer surface with output captured to the same evidence dir. Boundary-relevant
+    files changed with no boundary run, or a closed 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 (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
     new table/column). The mock suite still runs. No testing against data you
     never confirmed understanding of.
-16. **Auth proof + liveness.** A one-time AUTH PROOF at `/infra` proves every
-    credential the real tests use — Entra/MSAL app login AND external datasource
-    credentials — is obtainable headlessly twice in a row (prime + reuse) with
-    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.
+16. **Auth proof + liveness.** A one-time AUTH PROOF at `/infra` (when
+    `infra_needed`) proves every credential the real tests use — the app login AND
+    every external datasource credential — is obtainable headlessly twice in a row
+    (prime + reuse) with zero prompts; "reusable without interaction" means exactly
+    this. Each `/phase` PRE-FLIGHT runs a cheap liveness check (the command recorded
+    in `docs/INFRA.md ## AUTH`) 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.
 
 -----
 
@@ -237,22 +355,42 @@ the KB. The kit works normally without a KB.
 
 - `docs/STATE.md` — current position. Small. Rewritten, not appended.
 - `docs/ISSUES.md` — error log. Deduped by synthesizer.
-- `docs/PLAN.md` — the phase plan. Phase 0 (infra) always first; last phase has
-  the deploy task.
+- `docs/PLAN.md` — the phase plan. Phase 0 (infra) first iff `infra_needed`; last
+  phase completes `deploy_kind`.
 - `docs/HISTORY.md` — one line per finished phase.
 - `docs/DESIGN_LOG.md` — kit architectural rationale (§5.x decision log).
 - `docs/OVERVIEW.md` — project scope. Written after the double-grill in `overview`.
-  Carries `has_frontend` + the frontend root path, and the data/state-flow summary.
+  Carries the project flags (`project_type`, `has_frontend` + frontend root,
+  `infra_needed`, `e2e_kind`, `deploy_kind`, `knowledge_docs`) and the
+  data/state-flow summary.
+- `knowledge/<usecase>.md` — preinstalled matured practice (`webapp.md`,
+  `azure.md`), consulted by `researcher` when listed in OVERVIEW `knowledge_docs`.
+  Ships use-case templates materialized per project on demand.
+- `.claude/ref/compression.md` — kit-native compression profiles (`user`,
+  `internal`), single source, always-on. Not a skill.
 - `docs/DATAFLOW.md` — state-transition table per key object (`object | states |
   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,
-  E2E target, AUTH PROOF result.
+- `docs/INFRA.md` — infra manifest (when `infra_needed`): resource IDs, endpoints,
+  cost estimates, E2E target, `## AUTH` liveness command, AUTH PROOF result.
 - `docs/ENDPOINTS.md` — API/service endpoint catalogue. Maintained by implementer
   each phase. Drives the CLOSE coverage gate.
 - `docs/research/` — full research + debug files. `INDEX.md` is the searchable map.
@@ -260,14 +398,19 @@ the KB. The kit works normally without a KB.
   `debug-<slug>.md` (debugger traces), `datasource-<name>.md` (confirmed data
   understanding, referenced from DATAFLOW.md external rows).
 - `docs/.snapshots/` — pre-compact recovery markers (auto-pruned, gitignored).
-- `infra/` — Bicep templates. Committed (IaC audit trail). `infra/params.json`
-  holds no secrets.
-- `e2e/`, `scripts/e2e-stack.sh`, `docker-compose.test.yml`, `playwright.config.ts`
-  — the E2E stack.
+- `infra/` — IaC templates, generated per project by `infra-provisioner`. Committed
+  (audit trail). `infra/params.json` holds no secrets. (Azure Bicep specifics:
+  `knowledge/azure.md`.)
+- `knowledge/webapp.md` owns the browser E2E stack templates (`playwright.config.ts`,
+  `e2e/global-setup.ts`, `docker-compose.test.yml`, `scripts/e2e-stack.sh`) —
+  materialized into the project only when a browser phase needs them, then user-owned.
 - `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/auth-setup.sh` — session Azure credential check. Run once per session.
+- `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)
 - `.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).
 
@@ -275,18 +418,9 @@ the KB. The kit works normally without a KB.
 
 ## Capability matrix (which tools get what)
 
-- **Claude Code — full (reference implementation).** Generated commands; all three
-  lifecycle hooks WITH context injection (SessionStart / PreCompact / SubagentStop);
-  named subagents (`.claude/agents/*.md`); `@AGENTS.md` import; shared KB.
-- **Cursor — full (verified against cursor.com/docs, 2026-06).** Generated
-  commands (`.cursor/commands/`); the three lifecycle hooks via `.cursor/hooks.json`
-  (sessionStart / preCompact / subagentStop) wired to the SAME shared hook scripts —
-  sessionStart injects context via a JSON-envelope wrapper
-  (`cursor-session-start.sh`); named subagents work natively because Cursor reads
-  `.claude/agents/*.md` directly (no duplication); methodology via a
-  `.cursor/rules/` pointer at this file. Known degradations: `model: haiku/opus`
-  tiers are Claude-specific (Cursor falls back to inherit/compatible), and Cursor's
-  preCompact is observational (the snapshot side-effect still runs; no context
-  modification).
+- **Claude Code — full (the only supported target, v2.3).** Generated commands
+  (`.claude/commands/`); all three lifecycle hooks WITH context injection
+  (SessionStart / PreCompact / SubagentStop); named subagents (`.claude/agents/*.md`);
+  `@AGENTS.md` import; shared KB.
 - **Everything else.** Reads this `AGENTS.md` if it supports the open standard.
-  No generated adapters. Not claimed as supported in v2.0.
+  No generated adapters, no support claim (Cursor parity was dropped in v2.3, §5.69).

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      |
@@ -34,12 +35,6 @@ hooks (wired in `.claude/settings.json`) perform them:
   live position before compaction.
 - **SubagentStop** (`.claude/hooks/subagent-stop.sh`) writes a subagent trace.
 
-The same script bodies are wired for Cursor in `.cursor/hooks.json`; only the
-wiring differs (Cursor's sessionStart expects JSON output, so it runs the shared
-body through the `cursor-session-start.sh` envelope wrapper). Cursor also reads
-`.claude/agents/*.md` natively for subagents — one set of role files serves both
-tools.
-
 ## /clear keeps hooks
 
 `/clear` does not drop hooks — the wiring lives in `settings.json`, not in
@@ -47,9 +42,10 @@ context. After `/clear`, SessionStart fires again and re-injects state.
 
 ## Skills resolution
 
-- `karpathy-guidelines` — kit-owned (`.claude/skills/karpathy-guidelines/`).
-- `caveman`, `grill-me` — global-authoritative if installed; the vendored copies
-  under `.claude/skills/` are a fallback only.
+- `karpathy-guidelines`, `grill-me` — kit-owned (`.claude/skills/…`), the sole
+  source. No "global-authoritative if installed" resolution.
+- Compression is kit-native (`.claude/ref/compression.md`), NOT a skill — always
+  on, single source, never model-invoked.
 
 ## Platform notes