create-anpunkit 2.0.3 → 2.2.0

package/template/.claude/agents/test-author.md

@@ -1,70 +1,103 @@
 ---
 name: test-author
-description: Writes tests for a phase WITHOUT reading the implementation logic. On TDD phases, writes the suite BEFORE logic exists (RED-first). Tests behavior from the plan's acceptance spec only.
+description: Harness emitter (v2.2). Reads the locked docs/spec-phase-<n>.md case rows and GENERATES a deep-equality assertion harness against the shared fixtures — one boundary test per case, citing it with a `# spec: <case-id>` comment. Does not author assertions and does not read implementation logic.
 tools: Read, Grep, Glob, Write, Bash
 model: opus
 ---
 
-You are the TEST-AUTHOR. Caveman ULTRA mode. You write UNBIASED tests.
+You are the TEST-AUTHOR. Caveman ULTRA mode. In v2.2 you are a HARNESS EMITTER,
+not a blind assertion author. There is nothing for a human to review at the test
+layer — the human already reviewed the SPEC (SPEC REVIEW, upstream).
 
-## RED-FIRST (TDD phases)
+## What changed (v2.1 → v2.2)
 
-On a TDD phase you are dispatched BEFORE any logic exists — only interface stubs
-are present. You read the stub signatures (allowed) and the acceptance spec, and
-write the REAL API suite (+ mock) against them. Because there is no logic body to
-peek at, your blindness is STRUCTURAL, not honor-system.
+The authoritative artifact is now `docs/spec-phase-<n>.md` (human-approved). You do
+NOT invent assertions from a one-line acceptance. You MECHANICALLY emit one
+deep-equality assertion per spec case row, loading the SAME fixture files the spec
+row references. Because the spec row and your test share the fixture, your test
+physically cannot assert different values than the locked spec.
 
-- The suite MUST collect/import cleanly AND FAIL (assertion failure or
-  NotImplemented). That is the RED gate.
-- A test that PASSES on bare stubs is wrong — the spec is trivial or the test is
-  broken. Fix the test; NEVER ship green-on-stubs.
-- Cannot tell what to assert from the spec? Return UNDERSPEC (do not invent a
-  contract).
+## INPUT
 
-## Blind constraint (all phases)
+- `docs/spec-phase-<n>.md` — the FILLED, human-approved case table (read every row).
+- `fixtures/<case-id>-input.json`, `fixtures/<case-id>-expected.json` — per case.
+- public interface signatures / stubs (allowed — not logic). Do NOT read logic.
+- `tests/helpers/spec-assert.*` — the kit comparator. USE it; never reimplement.
 
-- You may read: docs/PLAN.md (acceptance + slice), public interface signatures /
-  stubs, test framework config.
-- You must NOT read implementation LOGIC bodies. Do not open source files for
-  their internals.
-- Cannot tell what to test without reading the logic? Return UNDERSPEC.
+You handle `data` boundary cases. `ui` cases are emitted by `e2e-runner`.
 
-## TWO SUITES — write BOTH
+## EMIT — one boundary test per `data` case row
 
-1. MOCK suite — fast, no external dependency. Mocks ONLY the external boundary.
-2. REAL API suite — real HTTP against running backend + real Azure services.
-   No mocks on the external boundary. Code/API-level — not browser E2E.
+For each `data` row, generate a test that:
 
-## Test placement (regression layout)
+1. Carries a `# spec: <case-id>` comment (Python `#`, JS/TS `//`) — the citation
+   `scripts/spec-conformance.sh` checks. Every case-id MUST be cited or GREEN is
+   blocked.
+2. Loads `fixtures/<case-id>-input.json` as the request body / args (or the inline
+   scalar from the row).
+3. Exercises the OUTER BOUNDARY: real HTTP call / CLI invocation / real message
+   against the running backend + real services. No mocks on the external boundary.
+4. Loads `fixtures/<case-id>-expected.json` and asserts via the kit comparator
+   `spec_assert(actual, expected)` — deep equality that HONORS MATCHER TOKENS
+   (`<UUID>`, `<ISO8601>`, `<ANY_STRING>`, `<ANY_NUMBER>`, `<UNORDERED>`,
+   `<MATCHES:regex>`). Never hand-roll token logic.
+5. For a failure case (`error-code` non-empty): assert the error code matches.
 
-- Public-contract / ENDPOINTS-surface tests -> `tests/regression/` (the
-  cross-phase corpus). A regression test must NOT depend on phase-local fixtures.
-- Phase-local tests -> `tests/phase-<n>/`.
-- mock vs real is a fixture/env FLAG on the SAME test, not duplicated files.
+You emit STRUCTURE, not judgment. You do not decide what is correct — the spec did.
+
+## MOCK MIRROR (optional, same fixture)
+
+A fast mock mirror is optional and uses the SAME test with a `TEST_MODE` flag
+(`mock` vs `real`/`boundary`), sharing the comparator and fixture so it can never
+assert different values than the boundary test. The boundary test — not the mock —
+is the phase gate. Green mock alone never closes a phase.
+
+## RED gate (still applies)
+
+You are dispatched after SCAFFOLD (stubs only), before logic. The emitted suite
+MUST collect/import cleanly AND FAIL (assertion / NotImplemented). A test that
+PASSES on bare stubs means a trivial spec or a broken emitter — fix it; never ship
+green-on-stubs. Collection/import error → stub signature mismatch; report it so the
+orchestrator re-dispatches SCAFFOLD to fix SIGNATURES.
+
+## NON-TDD PHASES (no spec file)
+
+A `TDD_PHASE=false` phase (pure infra/config/doc) has NO `docs/spec-phase-<n>.md`.
+There you fall back to the legacy behavior: write a MOCK suite + a boundary suite
+from docs/PLAN.md `acceptance` only, BLIND — never read implementation logic
+(structural blindness does not apply here, so it is honor-system; do not open
+source bodies). No fixtures, no `# spec:` citations, no conformance gate. This path
+is unchanged from v2.1.
+
+## Test placement (regression layout — unchanged)
+
+- Boundary tests for public-contract / ENDPOINTS-surface / DATAFLOW-transition
+  cases → `tests/regression/` (the cross-phase corpus; no phase-local fixtures).
+- Phase-local cases → `tests/phase-<n>/`.
+- mock-vs-boundary is a `TEST_MODE` flag on the SAME test, not duplicated files.
 
 ## Rules
 
-- Test observable behavior from `acceptance`. Cover happy path + edge + failure.
-- Run both suites. Report honestly. Never edit a test to make it pass.
-- FAILURE CLASSIFICATION for every real-suite failure:
-  - LOGIC FAIL: code's behavior is wrong.
+- One boundary test per spec case. Do NOT add, drop, or "improve" cases — the spec
+  is locked. A gap you notice is escalated to the orchestrator, not silently filled.
+- Run the suite. Report honestly. Never edit a fixture or a spec to make a test pass.
+- FAILURE CLASSIFICATION for every boundary failure:
+  - LOGIC FAIL: code's behavior is wrong (reaches the debugger).
   - SERVICE UNAVAILABLE: outage / rate limit / auth / network — not our code.
 
-PHASE GATE: your part = REAL API suite passing AND the accumulated mock regression
-corpus staying green. For frontend phases, e2e-runner adds the browser gate on
-top. Green mock alone CANNOT close a phase.
-
 RETURN:
 ```
 
-TESTS WRITTEN: phase <n>
+HARNESS EMITTED: phase <n>
 
-- red-first: <yes (TDD) | n/a (non-TDD)>
-- files: <mock suite files> | <real suite files>  (note regression vs phase-local)
-- RED gate: <COLLECTS+FAILS as required | passed-on-stubs=BAD | n/a>
-- mock result: <X pass / Y fail>
-- real API result: <X pass / Y fail>
-- failures: <behavior, expected vs actual, + LOGIC FAIL or SERVICE UNAVAILABLE>
+- spec read: docs/spec-phase-<n>.md (<N> data cases)
+- files: <test files> (note regression vs phase-local)
+- citations: every case-id cited by `# spec: <case-id>`? yes/no  (no = conformance FAIL)
+- comparator: tests/helpers/spec-assert.<py|ts>
+- RED gate: <COLLECTS+FAILS as required | passed-on-stubs=BAD>
+- mock result: <X pass / Y fail | not emitted>
+- boundary result: <X pass / Y fail | BLOCKED (service unavailable)>
+- failures: <case-id, expected vs actual, + LOGIC FAIL or SERVICE UNAVAILABLE>
 - external service hit: <name / none>
 - PHASE GATE: PASS | FAIL | BLOCKED (service unavailable)
 

package/template/.claude/anpunkit-manifest.json

@@ -1,25 +1,25 @@
 {
-  "version": "2.0.3",
+  "version": "2.2.0",
   "files": [
     {
       "path": "AGENTS.md",
-      "sha256": "638d0c19fbc614e162d83b8b5e315c9f38180eaec8d8a88c825d36d6d9ec416b"
+      "sha256": "0e4bdc92e8e33355fdfca8d7c3f644bd5f6b91d8b11b1837c65241c25a8dd695"
     },
     {
       "path": "CLAUDE.md",
-      "sha256": "e9d84381044c68d1b7289708de20bc6d2202eca3f39a2f63e7824a36fa18e299"
+      "sha256": "132e64b4a9a5a178deb4db810324f79338c2af65d598fd5e26f183225c2a4d98"
     },
     {
       "path": "README.md",
-      "sha256": "0335a0cecb86b57d01e63f564206cdf6d189ac873fce5c69d0f5081facfec964"
+      "sha256": "ca353eea88978b65dab78355ec304de0b8fb5d8ecb54d4316ee493de4459f002"
     },
     {
       "path": ".gitattributes",
-      "sha256": "51ca20efd556b51644b3fd938cd07ff86a17170edd09f7c9caf718911a56b0a2"
+      "sha256": "5362db7bc5f0639f80bb191f5d6436a2c54b1ca8a398362fba14136eca4014bf"
     },
     {
       "path": "setup.sh",
-      "sha256": "85c4aab58c83bf7b62344bbc04b94a4b49f90df0840b5e20660546b540889d6e"
+      "sha256": "77e994cbd6db69dde57fbdd8ce1460bc61cd24ad338e816303f7243165001e32"
     },
     {
       "path": ".claude/agents/debugger.md",
@@ -27,23 +27,27 @@
     },
     {
       "path": ".claude/agents/e2e-runner.md",
-      "sha256": "9d1f1134092abc28a23a3e48a2fda3aa74b7644267692edad464498e776445f7"
+      "sha256": "c454ad3217d6adc21e0e6cda5746e3094ea299cd7e71f761e1f417a7d6a2391e"
     },
     {
       "path": ".claude/agents/implementer.md",
-      "sha256": "9c2d5e166bac94bfff31a775766094a4275c5a8d1da9bae7823e824f5c307fe6"
+      "sha256": "e6598fdb77657616f821695323653cfdded44db85a428597d1c8074a56bbf816"
     },
     {
       "path": ".claude/agents/infra-provisioner.md",
-      "sha256": "56fa8dd1a6bc526a8d73f71b8e0b5980aec71ca6610070f222cbb77d348c66fb"
+      "sha256": "52a54a2aaaf7e53d28e261f5e01f2693fd0a4883fd93f844a112a742a91f9149"
+    },
+    {
+      "path": ".claude/agents/spec-author.md",
+      "sha256": "3e352514bfd5eb32f966cfa12014d706d17b3a12ad2155e2f826243c03fb7d0c"
     },
     {
       "path": ".claude/agents/planner.md",
-      "sha256": "3ba23521d9f1190a16402ad900d90932519517711fc3ec783eee21ff920a0042"
+      "sha256": "a1a2b86aa5a88d8b9fee9af3a8d10c7f1f09e5a2fb32f831dce38b010c507771"
     },
     {
       "path": ".claude/agents/researcher.md",
-      "sha256": "01b25384b6b6743c60e79e1cc9a2997895c86a6b509375b527a1aa8b70be4306"
+      "sha256": "aa54503f8c9998d3aa97aa322c0ba47d23cae8aea6236530ddc2dfc44e7c4658"
     },
     {
       "path": ".claude/agents/synthesizer.md",
@@ -51,7 +55,7 @@
     },
     {
       "path": ".claude/agents/test-author.md",
-      "sha256": "9af796a9d8e7302847e57fb61e484d0e3f26325586ebbb7e1a79ba20ead1057b"
+      "sha256": "adc53adb326424dcb215a5f074c7df3dfcb6644f2c63ce1e9ed68d2810dc8398"
     },
     {
       "path": ".claude/hooks/cursor-session-start.sh",
@@ -83,7 +87,7 @@
     },
     {
       "path": "commands.src/infra.md",
-      "sha256": "ca4e826889bd0a1bcf5298d3da5d453c3eecdb514bc50ba0d735b7f024a58dc0"
+      "sha256": "fe0e6ba6cf0c2fc3826ab67cd882752e9450677b1ffef440388349f0ba3c4fb6"
     },
     {
       "path": "commands.src/log-decision.md",
@@ -95,11 +99,11 @@
     },
     {
       "path": "commands.src/overview.md",
-      "sha256": "522a091e3e0513dbc15d7f856aca77e18ff70304ac3689f312a3f578e9f3e684"
+      "sha256": "85a300dcdd94d95c87c25c84d06619a38b5b3679631f68b511da11d7010e5cb8"
     },
     {
       "path": "commands.src/phase.md",
-      "sha256": "6cd48c2bbc87e01175594682d22cd7cf652cee84790b8a5677fd4d774679d6f3"
+      "sha256": "60a0e6442c2a3945afc4aec991cd44d48705eb8c142f3c2284db7095bb5441d9"
     },
     {
       "path": "commands.src/quick.md",
@@ -107,7 +111,7 @@
     },
     {
       "path": "commands.src/replan.md",
-      "sha256": "0a599f7c223a8c82cf3f3296ed5d60e5feb97396960e959190d5872f51a602a2"
+      "sha256": "57597623a2118e5867963aa61a04cff7808eb5ce8e2aed5bebb5247cff6be8ad"
     },
     {
       "path": "commands.src/store-wisdom.md",
@@ -123,7 +127,7 @@
     },
     {
       "path": ".claude/commands/infra.md",
-      "sha256": "ca4e826889bd0a1bcf5298d3da5d453c3eecdb514bc50ba0d735b7f024a58dc0"
+      "sha256": "fe0e6ba6cf0c2fc3826ab67cd882752e9450677b1ffef440388349f0ba3c4fb6"
     },
     {
       "path": ".claude/commands/log-decision.md",
@@ -135,11 +139,11 @@
     },
     {
       "path": ".claude/commands/overview.md",
-      "sha256": "522a091e3e0513dbc15d7f856aca77e18ff70304ac3689f312a3f578e9f3e684"
+      "sha256": "85a300dcdd94d95c87c25c84d06619a38b5b3679631f68b511da11d7010e5cb8"
     },
     {
       "path": ".claude/commands/phase.md",
-      "sha256": "6cd48c2bbc87e01175594682d22cd7cf652cee84790b8a5677fd4d774679d6f3"
+      "sha256": "60a0e6442c2a3945afc4aec991cd44d48705eb8c142f3c2284db7095bb5441d9"
     },
     {
       "path": ".claude/commands/quick.md",
@@ -147,7 +151,7 @@
     },
     {
       "path": ".claude/commands/replan.md",
-      "sha256": "0a599f7c223a8c82cf3f3296ed5d60e5feb97396960e959190d5872f51a602a2"
+      "sha256": "57597623a2118e5867963aa61a04cff7808eb5ce8e2aed5bebb5247cff6be8ad"
     },
     {
       "path": ".claude/commands/store-wisdom.md",
@@ -163,7 +167,7 @@
     },
     {
       "path": ".cursor/commands/infra.md",
-      "sha256": "24a6290a0905e744cc3d0adaf6f0d385b859e99eb8326367b6d55c7bcd66d559"
+      "sha256": "d6f7a7ee93f76a4d68aeb74c1f43aa76b969043ac59fbc22b02675e05a6dfee5"
     },
     {
       "path": ".cursor/commands/log-decision.md",
@@ -175,11 +179,11 @@
     },
     {
       "path": ".cursor/commands/overview.md",
-      "sha256": "33710e166d3fb4e9894df709708cd5dec997dfd7fb293931e3f9212567ee06cf"
+      "sha256": "9ee65f44d44362aaa37e5df7ed95eb7d386cec6e2045a2f87a81b80da343ac00"
     },
     {
       "path": ".cursor/commands/phase.md",
-      "sha256": "759d2d5946a9c05ade60dd5e8e47d8d94b7ab6b923be214eb5f5a9979ea6e94e"
+      "sha256": "5a2bac0d8dc36892256e49ddfd6bccac36e1d71dbc4cc0602ac337e398a0733e"
     },
     {
       "path": ".cursor/commands/quick.md",
@@ -187,7 +191,7 @@
     },
     {
       "path": ".cursor/commands/replan.md",
-      "sha256": "36b47315ba813702f71530402a6ffa7c4c404bbc946c0cda571ead61ddc28874"
+      "sha256": "3ad268b74c0218ae3530e3e7b86b75d9fd26bd98a79a74760efe767a63c251a2"
     },
     {
       "path": ".cursor/commands/store-wisdom.md",
@@ -229,17 +233,33 @@
       "path": "scripts/regression.sh",
       "sha256": "711bf59c9a1aa66846e1efd4a2127476edd8d92010207807e11e4080d430006e"
     },
+    {
+      "path": "scripts/spec-staleness.sh",
+      "sha256": "1a2b2cad55ba0500c84ce8c2e582ccc4b735bb2fc7d7152969e37c6653297de4"
+    },
+    {
+      "path": "scripts/spec-conformance.sh",
+      "sha256": "932be0e02c47dba0d56bc3600cc8ad80031e54a13e65ba4e474fd957bab9f9fa"
+    },
+    {
+      "path": "tests/helpers/spec-assert.py",
+      "sha256": "dd63f979cecdfa54e808ace01da038f44acb3a29ea65c928bf0458fd2d44c8d8"
+    },
+    {
+      "path": "tests/helpers/spec-assert.ts",
+      "sha256": "feda86755bb58af7f75323e182136eb4e5d43e813358ed1a3d712bbc4e069069"
+    },
     {
       "path": "create-anpunkit/package.json",
-      "sha256": "4b16cdfd4d9a22379147338664530fd7ce7f0e7566bf63d097f7b8f8f76dcdd8"
+      "sha256": "e283531b788e94cf9ca604a119e9d581e9cede3e1276770087f2c4874927e567"
     },
     {
       "path": "create-anpunkit/bin/cli.js",
-      "sha256": "129dae04923b6d380d3ca4601b5dcd2baa6ad4c51c827dddae3e43ea6a9c50e2"
+      "sha256": "f96460757110e6a0f81cef750c5b39442ea5589f53ae83b69951555632cce7ec"
     },
     {
       "path": "create-anpunkit/build.sh",
-      "sha256": "01fb6d1bb8866db54b0942d341b43e3f0ef96b97f7904909d77393fec49dbb58"
+      "sha256": "3a5062e46ba09ff23736de08545cefd1c0f30b216c3820bd2ada22e3d0db5b79"
     },
     {
       "path": "create-anpunkit/README.md",

package/template/.claude/commands/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.
 
 ---
 

package/template/.claude/commands/overview.md

@@ -1,5 +1,5 @@
 ---
-description: Bootstrap a new project. Runs design-research, double grill, and planning. Run once per project.
+description: Bootstrap a new project. Runs design-research, research review, double grill (incl. data/state flow), datasource-understanding baseline, and planning. Run once per project.
 ---
 
 Caveman ULTRA mode.
@@ -18,7 +18,9 @@ Goal: stand up a fresh project workspace with a well-grounded plan.
 1. Run the `grill-me` skill to interrogate me. Goal: understand initial scope.
    Cover: project purpose, success criteria, external services, Azure services
    needed (type + sizing), region, deployment target (Azure or local for E2E),
-   known constraints, unknowns.
+   known constraints, unknowns. ALSO establish:
+   - **has_frontend**: is there a browser-facing UI? If yes, what is the frontend
+     root path (e.g. `src/web/`, `app/`)? This drives the mandatory-E2E path match.
    Do not stop early. Do not write OVERVIEW.md yet.
 
 Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
@@ -33,74 +35,132 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
      Quotas, rate limits, known gaps?
    - Azure services: any sizing or SKU constraints relevant to the use case?
    - Auth patterns: any MSAL/Entra constraints for this scenario?
+   - Each external DATASOURCE: its DATA UNDERSTANDING (see step 4).
    - Any other architectural assumption in the round-1 answers worth verifying.
 
 3. Dispatch `researcher` in DESIGN mode with the DESIGN TOPICS list.
-   It returns a terse summary + file paths. Read the design-<slug>.md files
-   only if needed.
+   It returns a terse summary + file paths. For every external datasource it
+   drafts a DATA UNDERSTANDING to `docs/research/datasource-<name>.md`:
+   grain (one row = what?), the fields likely under test with their meaning and
+   real-world nullability/range, a sample-fixture shape, and the assumption that
+   if wrong makes a test meaningless. Read the design-<slug>.md files only if needed.
+
+---
+
+### RESEARCH REVIEW (v2.1 — read-and-confirm, not a grill)
+
+4. Surface the design-research findings to me DIRECTLY, phrased as FALSIFIABLE
+   CLAIMS about my systems — not a passive findings dump. For example:
+   "I understand your Tableau extract refreshes nightly and the API is read-only;
+   the `orders` grain is one row per line-item; `status` is never null in practice."
+   For each external datasource, present its drafted DATA UNDERSTANDING for me to
+   confirm or correct. Then:
+   - Minor corrections -> fold forward as seed context for round-2 grill.
+   - A MATERIAL error (wrong service tier, wrong data model, wrong grain) ->
+     re-dispatch `researcher` with the correction, then re-present. Do not carry
+     a known-wrong research file into grill or OVERVIEW.md.
+   A confirmed datasource understanding is recorded as the BASELINE in its
+   `datasource-<name>.md`. (Per-phase delta-confirms happen later in `/phase`.)
 
 ---
 
 ### Round 2 — Research-informed re-grill
 
-4. Run `grill-me` again — a second focused pass. Seed it with:
+5. Run `grill-me` again — a second focused pass. Seed it with:
    - The round-1 answers (already established — do not re-ask these)
    - The design-research key findings and new questions raised
+   - The RESEARCH REVIEW corrections
 
-   The re-grill asks whatever it needs to build complete understanding. It is
-   not limited to "gaps from research" — research context makes new questions
-   relevant even if it found no blockers. Do not re-ask what round 1 already
-   established clearly.
+   This pass MUST explicitly cover DATA STRUCTURE and DATAFLOW, especially the
+   STATE FLOW of each key object: what are the core entities, what states does
+   each move through, what transition triggers each change, who writes it, and
+   does any state map to an external system. The re-grill asks whatever else it
+   needs for complete understanding. Do not re-ask what round 1 established.
 
 ---
 
-### Write OVERVIEW.md
+### Write OVERVIEW.md + DATAFLOW.md
 
-5. Write docs/OVERVIEW.md from the COMBINED output of round-1 + design-research
-   + round-2. Include:
+6. Write docs/OVERVIEW.md from the COMBINED output of round-1 + design-research
+   + research review + round-2. Include:
    - Project purpose and success criteria
    - Scope and constraints (informed by research findings)
    - External services with confirmed capabilities/limits
    - "Azure services" section: every service with expected SKU
    - Deployment target (azure-deployed or local-docker for E2E)
+   - `has_frontend: true|false` and, if true, the frontend root path
    - Known risks / open questions (if any remain)
 
    OVERVIEW.md is written HERE — after the re-grill, not before.
 
+7. Write docs/DATAFLOW.md — a state-transition table per key object, driven by the
+   round-2 data/state-flow grill. The data-side analogue of ENDPOINTS.md. Columns:
+ ```
+ # Dataflow — <project name>
+ > Maintained from /overview; updated each phase that changes an object lifecycle.
+ > Each transition row is one testable unit (drives the CLOSE coverage gate).
+
+ | object | states | transition (from→to) | trigger | who writes | external system |
+ |--------|--------|----------------------|---------|------------|-----------------|
+ | Order  | draft,submitted,fulfilled | draft→submitted | POST /orders/submit | order-svc | — |
+ ```
+   Any row whose `external system` is populated ties to a `datasource-<name>.md`.
+
 ---
 
 ### Plan
 
-6. Hand OVERVIEW.md + design-research findings to the `planner` subagent.
-   PLAN.md MUST:
+8. Hand OVERVIEW.md + DATAFLOW.md + design-research findings to the `planner`
+   subagent. PLAN.md MUST:
    - Start with Phase 0 (infra setup) as the first entry (always).
    - End with a final code phase that contains the deploy task block.
-
-7. Create docs/STATE.md:
+   - For any phase whose `changes` touch the frontend root: include ≥1
+     UI-existence acceptance criterion naming the specific user-visible
+     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:
 ```
 
 # STATE
 
 phase: 0 (pending)
-completed: project bootstrapped — design research done, double grill done
+completed: project bootstrapped — design research, research review, double grill (incl. data/state flow) done
 next: run /infra to provision Azure infrastructure
 blocker: none
 
 ```
-8. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
+10. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
 
-9. Create empty docs/HISTORY.md.
+11. Create empty docs/HISTORY.md.
 
-10. Create docs/INFRA.md from the template (populated by /infra).
+12. Create docs/INFRA.md from the template (populated by /infra).
 
-11. Create docs/ENDPOINTS.md:
+13. Create docs/ENDPOINTS.md:
  ```
  # Endpoints — <project name>
  > Maintained by implementer. Updated each phase.
  > Base URL: (populated after deployment phase)
  ```
 
-Then stop and show me PLAN.md for approval before any phase starts.
+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)
-before starting Phase 1."
+Remind me: "Run `/infra` next to provision the Azure environment (Phase 0) and
+run the one-time AUTH PROOF before starting Phase 1."