create-anpunkit 2.0.3 → 2.1.0

package/bin/cli.js

@@ -61,7 +61,8 @@ if (!bash) {
 }
 
 // Pass through recognised flags only; setup.sh validates the rest.
-const passthrough = ['--kb-path', '--kb-remote', '--no-kb', '--force', '--dry-run'];
+const passthrough = ['--kb-path', '--kb-remote', '--no-kb', '--force', '--dry-run', '--tools', '--add-tool'];
+const valueFlags = ['--kb-path', '--kb-remote', '--tools', '--add-tool'];
 const argv = process.argv.slice(2);
 // Git Bash is happiest with forward slashes; Windows APIs accept them too.
 const fwd = p => p.split(path.sep).join('/');
@@ -70,7 +71,7 @@ for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (passthrough.includes(a)) {
     args.push(a);
-    if (a === '--kb-path' || a === '--kb-remote') { args.push(argv[++i]); }
+    if (valueFlags.includes(a)) { args.push(argv[++i]); }
   } else {
     console.error(`create-anpunkit: unknown flag '${a}'. Allowed: ${passthrough.join(' ')}`);
     process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-anpunkit",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Scaffold the anpunkit AI-coding workflow (Claude Code + Cursor) into a project. Upgrade-safe, non-destructive.",
   "bin": {
     "create-anpunkit": "bin/cli.js"

package/template/.claude/agents/e2e-runner.md

@@ -24,6 +24,12 @@ CRITICAL constraint: you are BLIND to the implementation. Read only:
 
 2. Read docs/ENDPOINTS.md for the known API surface.
 
+   UI-EXISTENCE CHECK (v2.1): the acceptance spec MUST name at least one
+   user-visible interactive element this phase introduces (a button, a route
+   landing, a form control) — not merely "page renders 200". If it does not,
+   return UNDERSPEC so the orchestrator can sharpen the spec. "Page renders" can
+   pass while the signin button is missing; that is the exact gap this closes.
+
 3. Write Playwright specs under `e2e/` from the phase's acceptance criteria.
    Test observable user-visible behavior only. No internals.
 
@@ -32,6 +38,12 @@ CRITICAL constraint: you are BLIND to the implementation. Read only:
    - `npx playwright test`
    - `scripts/e2e-stack.sh down` when done
 
+   EVIDENCE (v2.1, mandatory): at EACH UI-existence assertion, capture a
+   screenshot REGARDLESS of pass/fail (override Playwright's failure-only
+   default) to `docs/evidence/e2e-phase-<n>/<element-slug>.png`. One shot per
+   asserted element — evidence maps 1:1 to an acceptance criterion. This is the
+   proof the element was actually on screen, captured on green as well as red.
+
 5. FAILURE CLASSIFICATION — for every failure:
    - **LOGIC FAIL** — app behavior is wrong. Reaches the debugger.
    - **AZURE UNAVAILABLE** — Azure outage/throttle/auth expired.
@@ -54,10 +66,12 @@ Append one line to `docs/research/INDEX.md`.
 E2E DONE: phase <n>
 
 - target: <azure-deployed | local-docker> at <URL>
+- ui-existence asserted: <named element(s) | UNDERSPEC if none>
 - specs: <files written>
 - result: <X pass / Y fail>
+- evidence: docs/evidence/e2e-phase-<n>/ (<count> screenshots, one per assertion)
 - failures: <step + classification>
-- PHASE GATE: PASS | FAIL (LOGIC FAIL present) | BLOCKED (<reason>)
+- PHASE GATE: PASS | FAIL (LOGIC FAIL present) | BLOCKED (<reason>) | UNDERSPEC
 - full detail: docs/research/e2e-<phase-slug>.md
 
 ```

package/template/.claude/agents/infra-provisioner.md

@@ -1,6 +1,6 @@
 ---
 name: infra-provisioner
-description: Provisions and verifies Azure infrastructure. Generates Bicep templates, runs what-if diff for human review, applies on approval, writes docs/INFRA.md and .env.test. Never applies without orchestrator confirming human approval.
+description: Provisions and verifies Azure infrastructure. Generates Bicep templates, runs what-if diff for human review, applies on approval, writes docs/INFRA.md and .env.test, and runs the AUTH PROOF that every credential is reusable headlessly. Never applies without orchestrator confirming human approval.
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: opus
 ---
@@ -18,6 +18,8 @@ apply only after human approval, write the manifest.
 - VERIFY: check existing infra matches docs/INFRA.md. Report drift.
 - UPDATE <what changed>: add/remove/change a resource. Produce a delta Bicep.
 - REGENERATE-ENV: re-read docs/INFRA.md and rewrite .env.test only.
+- AUTH-PROOF: prove every credential the project's real tests use is reusable
+  headlessly (see Step 8). Run after PROVISION and on demand.
 
 ---
 
@@ -104,6 +106,14 @@ Run: `az deployment group create --resource-group <rg> --template-file infra/mai
 - Test user: <upn or "not yet created">
 - Conditional Access MFA exclusion: <yes/pending>
 
+## AUTH PROOF
+- status: <PASS | FAIL | not-yet-run>  (Phase 0 incomplete until PASS)
+- last run: <ISO timestamp>
+- credentials proven reusable (headless, twice in a row):
+  - Entra/MSAL app login: <pass/fail>
+  - <datasource name> (<type>): <pass/fail>
+  …
+
 ## Cost summary
 | Resource | SKU | Est. THB/month |
 |---|---|---|
@@ -150,10 +160,31 @@ INFRA VERIFY DONE
 - recommendation: <"all good" | "run /infra UPDATE <description>">
 ```
 
+### Step 8 — AUTH PROOF (v2.1, mode AUTH-PROOF; also runs after APPLY)
+
+Prove every credential the project's real tests will use is REUSABLE without
+interaction. "Reusable" = obtainable headlessly TWICE IN A ROW with zero prompts.
+
+1. Enumerate credentials in scope: the Entra/MSAL app login (ROPC, dedicated
+   MFA-excluded test account — NEVER drive the Microsoft login UI), plus every
+   external datasource credential in docs/DATAFLOW.md external rows +
+   docs/ENDPOINTS.md auth column (Azure SQL, Tableau, etc.).
+2. For each credential: obtain it headlessly (prime), then obtain it AGAIN — the
+   second obtain must succeed from cache/refresh with no prompt. A prompt or a
+   second-obtain failure means NOT reusable.
+3. Write the result to docs/INFRA.md `## AUTH PROOF` (PASS only if every
+   credential passed twice). Return:
+```
+AUTH PROOF: PASS | FAIL
+- proven reusable: <list>
+- failed: <credential + reason, or "none">
+```
+A FAIL means Phase 0 is not complete; the orchestrator stops until it passes.
+
 -----
 
 ## RETURN FORMAT
 
-WHAT-IF READY | APPLIED | VERIFY DONE | UNDERSPEC | ERROR
+WHAT-IF READY | APPLIED | VERIFY DONE | AUTH PROOF: PASS/FAIL | UNDERSPEC | ERROR
 Full detail always in docs/research/infra-<slug>-<timestamp>.md.
 Keep return terse — file path for detail.

package/template/.claude/agents/planner.md

@@ -1,13 +1,13 @@
 ---
 name: planner
-description: Turns research findings and OVERVIEW into a vertical-slice phase plan. Phase 0 always first. Last code phase always includes deployment. Writes docs/PLAN.md.
+description: Turns research findings, OVERVIEW, and DATAFLOW into a vertical-slice phase plan. Phase 0 always first. Last code phase always includes deployment. Frontend phases carry a named UI-existence criterion. Writes docs/PLAN.md.
 tools: Read, Grep, Glob, Write
 model: opus
 ---
 
 You are the PLANNER. Caveman ULTRA mode.
 
-Job: convert FINDINGS + OVERVIEW.md into an ordered phase plan. You only write docs/PLAN.md.
+Job: convert FINDINGS + OVERVIEW.md + DATAFLOW.md into an ordered phase plan. You only write docs/PLAN.md.
 
 Hard rules:
 - PHASE 0 IS ALWAYS FIRST. Every plan starts with Phase 0: infra setup:
@@ -27,6 +27,15 @@ testable, ships a real user-visible behavior.
 window. If a phase feels big, split it.
 - Each phase declares its acceptance test in plain language BEFORE code exists.
 - If a phase touches an external service, note it — its test must hit the real service.
+- FRONTEND phases (changes touch the OVERVIEW.md frontend root): the acceptance
+  MUST include ≥1 UI-EXISTENCE criterion that NAMES the specific user-visible
+  interactive element the phase introduces (e.g. "the Sign in button is present
+  and clickable on /login") — never just "page renders". (Hard rule 13; the
+  e2e-runner returns UNDERSPEC if this is missing.)
+- DATAFLOW: for each phase, list the docs/DATAFLOW.md transitions it makes
+  reachable in a `- dataflow:` line. Every transition in DATAFLOW.md must become
+  reachable by some phase; none may be stranded (hard rule 14, "no PENDING at
+  final phase").
 
 LAST PHASE RULE — the final code phase (the highest-numbered phase you write)
 MUST contain a deployment task block:
@@ -35,7 +44,7 @@ MUST contain a deployment task block:
 - deploy task:
   - deploy app to Azure (az deployment or container push per INFRA.md)
   - smoke-test the deployed base URL: GET /health (or equivalent) returns 200
-  - write the confirmed deployed base URL back to docs/INFRA.md under “Deployed base URL”
+  - write the confirmed deployed base URL back to docs/INFRA.md under "Deployed base URL"
   - update docs/ENDPOINTS.md with the final deployed base URL
 
 ```
@@ -58,8 +67,9 @@ docs/PLAN.md format:
 
 - slice: <what works end-to-end after this phase>
 - changes: <files/areas, high level>
-- acceptance: <observable behavior the test must verify>
-- external: <service name, or “none”>
+- acceptance: <observable behavior the test must verify; if frontend, NAME the UI element>
+- external: <service name, or "none">
+- dataflow: <DATAFLOW.md transitions this phase makes reachable, or "none">
   …
 
 ## Phase N: <name — final code phase>  [status: pending]

package/template/.claude/agents/researcher.md

@@ -52,8 +52,18 @@ Before any web search or local investigation:
    - Unknowns that the grill-me questions raised but did not answer.
 3. Use WebSearch/WebFetch to get REAL, current documentation — not assumptions.
    Skip web search for a topic if KB step 0 returned a fresh (non-stale) hit.
-4. Write FULL findings to `docs/research/design-<topic-slug>.md`.
-5. Append one line per topic to docs/research/INDEX.md:
+4. EXTERNAL DATASOURCE — DATA UNDERSTANDING (v2.1): for every external datasource
+   in scope, write `docs/research/datasource-<name>.md` proposing a FALSIFIABLE
+   understanding the human can confirm or correct in the RESEARCH REVIEW:
+   - grain (one row = what?)
+   - the fields likely under test, each with its meaning + real-world
+     nullability/range (not just the declared type)
+   - a sample-fixture shape (so a wrong understanding shows up as an obviously
+     wrong sample)
+   - the ASSUMPTION that, if wrong, makes a test meaningless (stated explicitly)
+   Do NOT invent values you cannot ground; mark them as the human's to confirm.
+5. Write FULL findings to `docs/research/design-<topic-slug>.md`.
+6. Append one line per topic to docs/research/INDEX.md:
    `YYYY-MM-DD | design-<slug> | <one-sentence conclusion> | docs/research/design-<slug>.md`
 
 RETURN (terse — orchestrator reads the file only if needed):
@@ -62,11 +72,12 @@ RETURN (terse — orchestrator reads the file only if needed):
 DESIGN RESEARCH DONE: <slug>
 
 - topics covered: <list>
-- kb hits: <slugs that matched from KB snapshot, or “none”>
-- stale kb entries: <slugs that were stale and re-researched, or “none”>
+- kb hits: <slugs that matched from KB snapshot, or "none">
+- stale kb entries: <slugs that were stale and re-researched, or "none">
 - key findings: <3-5 bullets — constraints, limits, surprises>
 - new questions raised: <questions the research surfaced that grill-me should probe>
-- unknowns: <what could not be confirmed, or “none”>
+- datasource understanding: <datasource-<name>.md drafted for confirm, or "none">
+- unknowns: <what could not be confirmed, or "none">
 - full detail: docs/research/design-<slug>.md
 
 ```
@@ -92,11 +103,11 @@ RETURN (terse):
 
 RESEARCH DONE: <topic-slug>
 
-- kb hits: <slugs that matched, or “none”>
-- stale kb entries: <slugs that were stale and re-researched, or “none”>
+- kb hits: <slugs that matched, or "none">
+- stale kb entries: <slugs that were stale and re-researched, or "none">
 - summary: <3-5 bullet conclusions>
 - hypothesis (bugs only): <root cause + key evidence, 1-2 lines>
-- unknowns: <what still needs checking, or “none”>
+- unknowns: <what still needs checking, or "none">
 - full detail: docs/research/<topic-slug>.md
 
 ```

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

@@ -39,9 +39,29 @@ peek at, your blindness is STRUCTURAL, not honor-system.
 
 - Public-contract / ENDPOINTS-surface tests -> `tests/regression/` (the
   cross-phase corpus). A regression test must NOT depend on phase-local fixtures.
+- DATAFLOW transition tests (one per `docs/DATAFLOW.md` transition this phase makes
+  reachable) -> also `tests/regression/`. Name them so the transition is obvious
+  (e.g. `test_order_draft_to_submitted`).
 - Phase-local tests -> `tests/phase-<n>/`.
 - mock vs real is a fixture/env FLAG on the SAME test, not duplicated files.
 
+## TEST PLAN — the TEST REVIEW artifact (v2.1)
+
+Always emit `docs/test-plan-phase-<n>.md` so the orchestrator can gate GREEN on a
+human review. It must map each acceptance criterion to the test name(s) covering
+it, list the ENDPOINTS and DATAFLOW transitions covered, and — MANDATORY — a
+"## NOT covered / assumptions" section stating what you deliberately did not test
+and every assumption that, if wrong, makes a test meaningless. The NOT-covered
+section is where silent-gap bugs hide; an empty one is almost always a defect.
+
+## DATASOURCE DELTA (v2.1)
+
+If a phase tests against an external datasource, you are given the confirmed
+BASELINE (`docs/research/datasource-<name>.md`). If your tests touch a table/column
+BEYOND the baseline, do NOT invent its meaning — return DATA-UNDERSTANDING-DELTA
+with the specific new field(s) so the orchestrator can get a human confirm before
+the real suite runs. Real-suite tests against unconfirmed data are blocked.
+
 ## Rules
 
 - Test observable behavior from `acceptance`. Cover happy path + edge + failure.
@@ -61,11 +81,14 @@ TESTS WRITTEN: phase <n>
 
 - red-first: <yes (TDD) | n/a (non-TDD)>
 - files: <mock suite files> | <real suite files>  (note regression vs phase-local)
+- test plan: docs/test-plan-phase-<n>.md  (incl. NOT-covered/assumptions)
+- dataflow transitions covered: <list, or none>
 - 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>
+- real API result: <X pass / Y fail | BLOCKED (datasource unconfirmed)>
+- datasource delta: <none | DATA-UNDERSTANDING-DELTA: field(s) needing confirm>
 - failures: <behavior, expected vs actual, + LOGIC FAIL or SERVICE UNAVAILABLE>
 - external service hit: <name / none>
-- PHASE GATE: PASS | FAIL | BLOCKED (service unavailable)
+- PHASE GATE: PASS | FAIL | BLOCKED (service unavailable / datasource unconfirmed)
 
 ```

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

@@ -1,9 +1,9 @@
 {
-  "version": "2.0.3",
+  "version": "2.1.0",
   "files": [
     {
       "path": "AGENTS.md",
-      "sha256": "638d0c19fbc614e162d83b8b5e315c9f38180eaec8d8a88c825d36d6d9ec416b"
+      "sha256": "e33c8290f6a5aa15a744721d435944d49552b08428c91f83be4cf02b2a4fbda4"
     },
     {
       "path": "CLAUDE.md",
@@ -11,7 +11,7 @@
     },
     {
       "path": "README.md",
-      "sha256": "0335a0cecb86b57d01e63f564206cdf6d189ac873fce5c69d0f5081facfec964"
+      "sha256": "bd33dd8be4b1b20ab4ea9444f60094a8ee125681e6f1073e3ed7f06c1f5a5f4c"
     },
     {
       "path": ".gitattributes",
@@ -19,7 +19,7 @@
     },
     {
       "path": "setup.sh",
-      "sha256": "85c4aab58c83bf7b62344bbc04b94a4b49f90df0840b5e20660546b540889d6e"
+      "sha256": "77e994cbd6db69dde57fbdd8ce1460bc61cd24ad338e816303f7243165001e32"
     },
     {
       "path": ".claude/agents/debugger.md",
@@ -27,7 +27,7 @@
     },
     {
       "path": ".claude/agents/e2e-runner.md",
-      "sha256": "9d1f1134092abc28a23a3e48a2fda3aa74b7644267692edad464498e776445f7"
+      "sha256": "4e914d20022be58f3915526f91ac6df54cb5efd4836c12b97fd042cce90e8ddc"
     },
     {
       "path": ".claude/agents/implementer.md",
@@ -35,15 +35,15 @@
     },
     {
       "path": ".claude/agents/infra-provisioner.md",
-      "sha256": "56fa8dd1a6bc526a8d73f71b8e0b5980aec71ca6610070f222cbb77d348c66fb"
+      "sha256": "52a54a2aaaf7e53d28e261f5e01f2693fd0a4883fd93f844a112a742a91f9149"
     },
     {
       "path": ".claude/agents/planner.md",
-      "sha256": "3ba23521d9f1190a16402ad900d90932519517711fc3ec783eee21ff920a0042"
+      "sha256": "b74951f53ddfebba5d2255d164ef4b1b6fa8544f3e8d9ae3ff7d23e2f3198650"
     },
     {
       "path": ".claude/agents/researcher.md",
-      "sha256": "01b25384b6b6743c60e79e1cc9a2997895c86a6b509375b527a1aa8b70be4306"
+      "sha256": "aa54503f8c9998d3aa97aa322c0ba47d23cae8aea6236530ddc2dfc44e7c4658"
     },
     {
       "path": ".claude/agents/synthesizer.md",
@@ -51,7 +51,7 @@
     },
     {
       "path": ".claude/agents/test-author.md",
-      "sha256": "9af796a9d8e7302847e57fb61e484d0e3f26325586ebbb7e1a79ba20ead1057b"
+      "sha256": "d8ccd98ced9a77c7da6c40c12b7b3108f302f4cc5956ea8b516f6384203c9c13"
     },
     {
       "path": ".claude/hooks/cursor-session-start.sh",
@@ -83,7 +83,7 @@
     },
     {
       "path": "commands.src/infra.md",
-      "sha256": "ca4e826889bd0a1bcf5298d3da5d453c3eecdb514bc50ba0d735b7f024a58dc0"
+      "sha256": "fe0e6ba6cf0c2fc3826ab67cd882752e9450677b1ffef440388349f0ba3c4fb6"
     },
     {
       "path": "commands.src/log-decision.md",
@@ -95,11 +95,11 @@
     },
     {
       "path": "commands.src/overview.md",
-      "sha256": "522a091e3e0513dbc15d7f856aca77e18ff70304ac3689f312a3f578e9f3e684"
+      "sha256": "841dad7d2765f4240900d18cd57a6c5a4cbc6c1f19f0568f5e14d4e098f60ab8"
     },
     {
       "path": "commands.src/phase.md",
-      "sha256": "6cd48c2bbc87e01175594682d22cd7cf652cee84790b8a5677fd4d774679d6f3"
+      "sha256": "de910c499acf6f3d27353b2594a4ff8d7b650ee90b35ceb8dabf1e3244f4851b"
     },
     {
       "path": "commands.src/quick.md",
@@ -107,7 +107,7 @@
     },
     {
       "path": "commands.src/replan.md",
-      "sha256": "0a599f7c223a8c82cf3f3296ed5d60e5feb97396960e959190d5872f51a602a2"
+      "sha256": "57597623a2118e5867963aa61a04cff7808eb5ce8e2aed5bebb5247cff6be8ad"
     },
     {
       "path": "commands.src/store-wisdom.md",
@@ -123,7 +123,7 @@
     },
     {
       "path": ".claude/commands/infra.md",
-      "sha256": "ca4e826889bd0a1bcf5298d3da5d453c3eecdb514bc50ba0d735b7f024a58dc0"
+      "sha256": "fe0e6ba6cf0c2fc3826ab67cd882752e9450677b1ffef440388349f0ba3c4fb6"
     },
     {
       "path": ".claude/commands/log-decision.md",
@@ -135,11 +135,11 @@
     },
     {
       "path": ".claude/commands/overview.md",
-      "sha256": "522a091e3e0513dbc15d7f856aca77e18ff70304ac3689f312a3f578e9f3e684"
+      "sha256": "841dad7d2765f4240900d18cd57a6c5a4cbc6c1f19f0568f5e14d4e098f60ab8"
     },
     {
       "path": ".claude/commands/phase.md",
-      "sha256": "6cd48c2bbc87e01175594682d22cd7cf652cee84790b8a5677fd4d774679d6f3"
+      "sha256": "de910c499acf6f3d27353b2594a4ff8d7b650ee90b35ceb8dabf1e3244f4851b"
     },
     {
       "path": ".claude/commands/quick.md",
@@ -147,7 +147,7 @@
     },
     {
       "path": ".claude/commands/replan.md",
-      "sha256": "0a599f7c223a8c82cf3f3296ed5d60e5feb97396960e959190d5872f51a602a2"
+      "sha256": "57597623a2118e5867963aa61a04cff7808eb5ce8e2aed5bebb5247cff6be8ad"
     },
     {
       "path": ".claude/commands/store-wisdom.md",
@@ -163,7 +163,7 @@
     },
     {
       "path": ".cursor/commands/infra.md",
-      "sha256": "24a6290a0905e744cc3d0adaf6f0d385b859e99eb8326367b6d55c7bcd66d559"
+      "sha256": "d6f7a7ee93f76a4d68aeb74c1f43aa76b969043ac59fbc22b02675e05a6dfee5"
     },
     {
       "path": ".cursor/commands/log-decision.md",
@@ -175,11 +175,11 @@
     },
     {
       "path": ".cursor/commands/overview.md",
-      "sha256": "33710e166d3fb4e9894df709708cd5dec997dfd7fb293931e3f9212567ee06cf"
+      "sha256": "8cd54af27fa63ccfa714c7ecfa48476664fa3407b46cb708ddbc4ad2ebbb0a58"
     },
     {
       "path": ".cursor/commands/phase.md",
-      "sha256": "759d2d5946a9c05ade60dd5e8e47d8d94b7ab6b923be214eb5f5a9979ea6e94e"
+      "sha256": "693e4edca20374441c876ac58994863949fb8f364e72e8a0dc32670d4550fc69"
     },
     {
       "path": ".cursor/commands/quick.md",
@@ -187,7 +187,7 @@
     },
     {
       "path": ".cursor/commands/replan.md",
-      "sha256": "36b47315ba813702f71530402a6ffa7c4c404bbc946c0cda571ead61ddc28874"
+      "sha256": "3ad268b74c0218ae3530e3e7b86b75d9fd26bd98a79a74760efe767a63c251a2"
     },
     {
       "path": ".cursor/commands/store-wisdom.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,115 @@ 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.
+   - 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.
 
-7. Create docs/STATE.md:
+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.
 
-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."