create-anpunkit 2.0.3 → 2.2.0

package/template/AGENTS.md

@@ -1,9 +1,10 @@
 # anpunkit — portable agent methodology (single source of truth)
 
-<!-- ANPUNKIT-AGENTS-SENTINEL-v2.0 -->
-> **SENTINEL.** The HTML comment above (`ANPUNKIT-AGENTS-SENTINEL-v2.0`) 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 -> GREEN -> TEST(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,7 +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.
+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, `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)
 
 -----
 
@@ -53,21 +91,58 @@ 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).
-  IMPL: per-phase codebase + service investigation. Checks the shared KB snapshot
-  first (step 0). Writes findings to `docs/research/`; returns terse summary + path.
+  (service limits, API contracts, architectural constraints, cost surprises);
+  for any external datasource, drafts a falsifiable DATA UNDERSTANDING (grain,
+  fields-under-test with meaning + real nullability/range, sample-fixture shape,
+  the assumption that if wrong makes a test meaningless) to `docs/research/
+  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.
+  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
+  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`.
+  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.
-- **e2e-runner** — writes/runs functional browser E2E (Playwright) BLIND. Reads
-  `docs/INFRA.md` for the target.
+  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
@@ -83,12 +158,21 @@ Named procedures, each with a canonical body in `commands.src/<name>.md` and a
 generated copy per tool (`.claude/commands/`, `.cursor/commands/`).
 
 - **overview** — bootstrap a project: design-research → grill r1 → design-research
-  → re-grill r2 → `OVERVIEW.md` → planner → `PLAN.md` (Phase 0 always first).
+  → 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)
+  + 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`.
+  → `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. CLOSE runs the regression guard + ENDPOINTS
-  coverage gate.
+  TDD or non-TDD order at RESEARCH. PRE-FLIGHT runs the auth liveness check. TDD
+  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).
@@ -126,7 +210,7 @@ recover: current phase, next action, open blocker.
 
 -----
 
-## Hard rules (1–11)
+## 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.
@@ -135,26 +219,94 @@ 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 AND the accumulated mock regression corpus stays green AND
-   every `docs/ENDPOINTS.md` entry has at least one test in `tests/regression/`.
-   The final phase additionally runs the full REAL regression corpus. 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.
 8. E2E auth = ROPC with a dedicated MFA-excluded test account. NEVER script the
    Microsoft login UI.
 9. Architectural change (new/removed agent, hook, command, or a changed workflow
-   rule)? -> run `log-decision` before closing.
+   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.
-11. **No-rationalization (scoped).** Do not downgrade a TDD phase to non-TDD to
-    dodge the RED gate, and do not route phase-worthy work through `quick` to
-    dodge it. (Scoped deliberately to these two seams; this is not a broad
-    "never make excuses" rule.)
+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); 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 (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. 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.
+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.
 
 -----
 
@@ -176,13 +328,36 @@ the KB. The kit works normally without a KB.
 - `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.
+- `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/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.
+  E2E target, 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.
   `design-<slug>.md` (design research), `<slug>.md` (impl research),
-  `debug-<slug>.md` (debugger traces).
+  `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.
@@ -191,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      |

package/template/README.md

@@ -25,8 +25,12 @@ npx create-anpunkit            # non-destructive: never clobbers your files
 # then open Claude Code or Cursor — the session-start hook fires automatically
 /overview                      # bootstrap the project (includes Phase 0 infra)
 ```
-Useful flags: `--dry-run` (print the plan, write nothing), `--force` (overwrite
-user-modified kit files), `--kb-path <dir>` (your pre-cloned KB repo; remote auto-recorded from its origin) / `--no-kb`.
+Useful flags: `--dry-run` (print the per-tool plan, write nothing), `--force`
+(overwrite user-modified kit files), `--tools <claude,cursor>` (install only the
+selected tools' files; interactive menu if omitted on a fresh TTY install),
+`--add-tool <name>` (lay down an additional tool's files into an existing
+project), `--kb-path <dir>` (your pre-cloned KB repo; remote auto-recorded from
+its origin) / `--no-kb`.
 
 Upgrading an existing anpunkit project? Re-run `npx create-anpunkit`. It refreshes
 kit-owned files, preserves anything you modified as `<file>.anpunkit-new`, merges
@@ -46,38 +50,63 @@ cd my-project && bash setup.sh
 
 |Command          |Does                                                                          |
 |-----------------|------------------------------------------------------------------------------|
-|`/overview`      |design-research → grill (×2) → OVERVIEW → PLAN (Phase 0 always first) → STATE |
-|`/infra`         |provision Azure infra: Bicep → what-if → review → apply → INFRA.md + .env.test|
-|`/phase [n]`     |run one phase: research → implement → blind test, with circuit breaker        |
+|`/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 → 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                           |
-|`/replan`        |revise PLAN.md when it drifts                                                 |
+|`/replan`        |revise PLAN.md when it drifts (reconciles regression corpus + DATAFLOW)        |
 |`/log-issue`     |append an error with root cause + failed attempts                             |
 |`/log-decision`  |record an architectural change in DESIGN_LOG.md                               |
 |`/store-wisdom`  |promote resolved issues + research findings to shared KB                      |
 
 ## 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.0: TDD-first + regression guard)
-
-Phases that add a public callable surface run test-first:
-`RESEARCH -> SCAFFOLD -> RED -> GREEN -> TEST -> 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); the implementer
-then fills to green. Pure infra/config/doc phases keep the direct
-`RESEARCH -> IMPLEMENT -> TEST` order.
+## 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
+under the frontend root, **E2E is mandatory**, the acceptance spec must name the
+specific user-visible element it introduces (not "page renders 200"), and the
+`e2e-runner` captures a screenshot at each such assertion — on success too — to a
+gitignored `docs/evidence/` dir. That's the fix for shipping a missing sign-in button.
 
 Every phase CLOSE runs the accumulated **mock regression corpus**
-(`tests/regression/`, via `scripts/regression.sh`) and a hard ENDPOINTS coverage
-gate — so a contract built in an early phase cannot be silently broken later. The
-final phase additionally runs the full real corpus.
+(`tests/regression/`, via `scripts/regression.sh`) plus a hard ENDPOINTS coverage
+gate AND a **DATAFLOW transition-coverage gate** — every reachable state
+transition in `docs/DATAFLOW.md` (the data-side analogue of `ENDPOINTS.md`,
+grilled out at `/overview`) must have a regression test. The final phase
+additionally runs the full real corpus and allows zero PENDING transitions.
+
+External datasources get a confirmed, falsifiable **DATA UNDERSTANDING** (grain,
+fields, sample shape, meaning-breaking assumption) before real tests run, and auth
+is proven reusable once at `/infra` (obtainable headlessly twice in a row) with a
+cheap liveness check each phase.
 
 Methodology lives in one place: the portable **`AGENTS.md`** at the repo root.
 `CLAUDE.md` is a thin `@AGENTS.md` shim with Claude-native wiring only.
@@ -142,6 +171,10 @@ home-dir custom-prompts with a divergent UX).
 - `docs/PLAN.md` — vertical-slice phase plan (Phase 0 always first)
 - `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)
@@ -206,6 +239,7 @@ phase starts, owned by the `infra-provisioner` subagent.
 /infra             # generates Bicep -> what-if diff -> you review -> "go" -> apply
                    # writes docs/INFRA.md (resource manifest + cost estimates)
                    # writes .env.test (generated, never fill manually)
+                   # runs AUTH PROOF (every credential proven reusable headlessly)
 /phase 1           # PRE-FLIGHT checks Phase 0 is done before starting
 ```
 
@@ -225,13 +259,15 @@ Prompts `az login` only if stale. No credential storage — your account only.
 1. `infra-provisioner` reads `docs/OVERVIEW.md` for the system design
 1. Generates `infra/main.bicep` + per-service modules under `infra/modules/`
 1. Runs `az deployment what-if` — shows exactly what will be created
-1. **Stops and waits for your “go”** — nothing applied without your review
+1. **Stops and waits for your "go"** — nothing applied without your review
 1. Applies the deployment
 1. Writes `docs/INFRA.md` — resource IDs, endpoints, cost estimates (THB, SEA region)
 1. Generates `.env.test` from the manifest
+1. Runs the **AUTH PROOF** — proves every credential (Entra/MSAL + datasources) is obtainable headlessly twice in a row
 
 Re-run `/infra` any time infra drifts or a new resource is needed.
 Re-run `/infra regenerate-env` to refresh `.env.test` only.
+Re-run `/infra auth-proof` to re-prove credentials on demand.
 
 ### Cost awareness
 
@@ -257,7 +293,7 @@ Three layers: unit/integration (mock suite), real API (`test-author`), and
 functional browser E2E (`e2e-runner`, Playwright).
 
 **Phase gate:** a frontend-touching phase closes only when the real API suite
-AND the browser E2E suite pass. Mock-green alone never closes a phase.
+AND the browser E2E suite pass with screenshot evidence. Mock-green alone never closes a phase.
 
 **MSAL / Entra ID auth.** Browser E2E never drives the Microsoft login UI.
 `e2e/global-setup.ts` uses ROPC flow with a dedicated test account (MFA excluded
@@ -265,7 +301,7 @@ via Conditional Access) to fetch a real token and inject it into the MSAL cache.
 
 **E2E setup (one-time per project):**
 
-1. Run `/infra` — it generates `.env.test` automatically.
+1. Run `/infra` — it generates `.env.test` automatically and runs the AUTH PROOF.
 1. Provision the Entra test user + Conditional Access MFA exclusion.
 1. `npm i -D @playwright/test && npx playwright install chromium`
 

package/template/commands.src/infra.md

@@ -1,6 +1,6 @@
 ---
-description: Provision or verify Azure infrastructure. Generates Bicep, shows what-if diff for your review, applies only after your approval, writes docs/INFRA.md and .env.test.
-argument-hint: [provision | verify | update <what changed> | regenerate-env]
+description: Provision or verify Azure infrastructure. Generates Bicep, shows what-if diff for your review, applies only after your approval, writes docs/INFRA.md and .env.test. Runs the one-time AUTH PROOF.
+argument-hint: [provision | verify | update <what changed> | regenerate-env | auth-proof]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR.
@@ -36,6 +36,31 @@ Action: $ARGUMENTS (default: "provision" if INFRA.md missing, "verify" if presen
 4. On "make changes": dispatch UPDATE with feedback. Loop to step 2.
 
 5. On APPLIED: tell me INFRA.md ✓, .env.test ✓, and any manual steps remaining.
+   Then run AUTH PROOF (below) before declaring Phase 0 complete.
+
+---
+
+## AUTH PROOF (one-time, hard rule 16)
+
+Runs after a successful PROVISION (and on demand via `/infra auth-proof`). Proves
+every credential the project's real tests will use is reusable WITHOUT interaction.
+"Reusable" is defined falsifiably: obtainable headlessly TWICE IN A ROW.
+
+1. Enumerate the credentials in scope: the Entra/MSAL app login, plus every
+   external datasource credential referenced in docs/DATAFLOW.md (external rows)
+   and docs/ENDPOINTS.md (auth column) — Azure SQL, Tableau, etc.
+
+2. Dispatch `infra-provisioner` to run, for EACH credential, a headless obtain
+   twice in a row: first call primes (token fetch / connect), second call must
+   succeed from cache/refresh with ZERO prompts. The Microsoft login UI is never
+   driven (ROPC + dedicated MFA-excluded test account; hard rule 8).
+
+3. Result:
+   - All credentials pass twice headlessly -> write `AUTH PROOF: PASS <timestamp>`
+     to docs/INFRA.md with the per-credential list. Phase 0 may complete.
+   - Any credential prompts or fails the second obtain -> NOT reusable. Write
+     `AUTH PROOF: FAIL` + which credential, STOP, tell me what to fix. Phase 0 is
+     not complete until the proof passes.
 
 ---
 
@@ -43,7 +68,7 @@ Action: $ARGUMENTS (default: "provision" if INFRA.md missing, "verify" if presen
 
 1. Check INFRA.md exists. If missing: tell me to run `/infra provision` first.
 2. Dispatch `infra-provisioner` VERIFY mode.
-3. Return drift report.
+3. Return drift report. If the AUTH PROOF marker is missing or stale, re-run AUTH PROOF.
 
 ---