create-anpunkit 2.0.1 → 2.1.0

package/template/AGENTS.md

@@ -1,7 +1,7 @@
 # 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
+<!-- ANPUNKIT-AGENTS-SENTINEL-v2.1 -->
+> **SENTINEL.** The HTML comment above (`ANPUNKIT-AGENTS-SENTINEL-v2.1`) is a
 > load-bearing marker. `setup.sh` greps for it to confirm this file resolved on
 > disk and was not clobbered. Do not remove or rename it.
 
@@ -31,7 +31,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 -> SCAFFOLD -> RED -> TEST REVIEW -> GREEN -> E2E -> FIX -> CLOSE`
 - **Non-TDD phase** (pure infra / config / doc — `TDD_PHASE=false`):
   `RESEARCH -> IMPLEMENT -> TEST -> FIX -> CLOSE`
 
@@ -41,6 +41,22 @@ from the acceptance spec." Size is NOT the criterion. On ambiguity, default
 `TDD_PHASE=true` AND state the classification + reason so a human can override to
 non-TDD before SCAFFOLD fires.
 
+**TEST REVIEW (v2.1)** is a mandatory human gate on every TDD phase, sitting
+between RED and GREEN. After `test-author` writes the suite it emits a
+`docs/test-plan-phase-<n>.md` (acceptance criteria → test names, plus a mandatory
+"NOT covered / assumptions" section). The orchestrator surfaces it; FILL cannot
+fire until the human approves. A rejected coverage map is classified at the gate:
+a misread of an adequate spec → re-dispatch `test-author` with feedback; an
+underspecified acceptance spec → sharpen `PLAN.md` and re-dispatch fresh. The gate
+is unskippable on TDD phases and absent on the non-TDD path (no public surface to
+mis-test). This is the fix for "all tests green, core still broken." (§5.33)
+
+**E2E is mandatory, not a judgment call (v2.1).** If the project is frontend-bearing
+(`has_frontend: true` in `docs/OVERVIEW.md`) AND the phase's `changes` touch the
+frontend root recorded in OVERVIEW.md, `e2e-runner` MUST run before CLOSE. The
+trigger is a deterministic path match, not "does this phase feel frontend-y." A
+frontend file changed with no E2E run is a loud CLOSE failure. (§5.34)
+
 -----
 
 ## Roles (fresh-context workers)
@@ -53,21 +69,36 @@ 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.
 - **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.
+  structural, not honor-system. Writes a MOCK suite + a REAL API suite, and emits
+  `docs/test-plan-phase-<n>.md` (the TEST REVIEW artifact) with a mandatory "NOT
+  covered / assumptions" section. For phases touching an external datasource,
+  surfaces any DATA UNDERSTANDING delta (new table/column beyond the confirmed
+  baseline) for confirmation before the real suite runs.
 - **e2e-runner** — writes/runs functional browser E2E (Playwright) BLIND. Reads
-  `docs/INFRA.md` for the target.
+  `docs/INFRA.md` for the target. Captures a screenshot at EACH UI-existence
+  assertion regardless of pass/fail (capture-on-success, not just on-failure) to
+  `docs/evidence/e2e-phase-<n>/`, plus a summary in `docs/research/e2e-<slug>.md`.
 - **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 +114,16 @@ 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).
 - **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 stop at TEST REVIEW before GREEN. Frontend phases run mandatory E2E with
+  screenshot evidence. CLOSE runs the regression guard + ENDPOINTS coverage gate +
+  DATAFLOW transition-coverage gate + evidence-present check.
 - **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 +161,7 @@ recover: current phase, next action, open blocker.
 
 -----
 
-## Hard rules (1–11)
+## Hard rules (1–16)
 
 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.
@@ -136,9 +171,11 @@ recover: current phase, next action, open blocker.
    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
+   the E2E suite passes with screenshot evidence captured AND the accumulated mock
+   regression corpus stays green AND every `docs/ENDPOINTS.md` entry has at least
+   one test in `tests/regression/` AND every REACHABLE `docs/DATAFLOW.md` transition
+   has at least one test in `tests/regression/`. The final phase additionally runs
+   the full REAL regression corpus and requires zero PENDING transitions. A green
    mock suite alone can never close a phase.
 6. Tests are written by `test-author`, which never sees the implementation logic
    (unbiased). On TDD phases the suite is written before the logic (RED-first).
@@ -148,13 +185,42 @@ recover: current phase, next action, open blocker.
 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); mark a reachable transition PENDING
+    (DATAFLOW gate); or skip evidence capture. (Scoped deliberately to these named
+    seams; this is not a broad "never make excuses" rule.)
+12. **TEST REVIEW (TDD phases).** GREEN cannot begin until the human approves
+    `docs/test-plan-phase-<n>.md`. Rejection is classified at the gate (misread
+    spec → re-dispatch test-author with feedback; underspec → sharpen PLAN.md and
+    re-dispatch fresh). Unskippable on TDD phases; absent on the non-TDD path.
+13. **Mandatory frontend E2E + evidence.** When `has_frontend: true` and the
+    phase's `changes` touch the frontend root recorded in OVERVIEW.md, E2E MUST
+    run. Each UI-existence assertion captures a screenshot (on success too) to
+    `docs/evidence/e2e-phase-<n>/`. Frontend files changed with no E2E run, or a
+    closed frontend phase with no evidence on disk, fails CLOSE hard. (Evidence is
+    gitignored — present-on-disk at CLOSE is the check, not committed history.)
+14. **DATAFLOW transition coverage.** Every transition in `docs/DATAFLOW.md` whose
+    trigger is reachable in the code shipped so far MUST have ≥1 test in
+    `tests/regression/`; zero coverage on a reachable transition fails CLOSE hard.
+    Unreachable transitions list as PENDING. Any transition still PENDING at the
+    final phase fails hard. Peer to the ENDPOINTS coverage gate.
+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.
 
 -----
 
@@ -176,13 +242,23 @@ 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/test-plan-phase-<n>.md` — the TEST REVIEW artifact: acceptance → test names
+  + mandatory "NOT covered / assumptions" section. Human-approved before GREEN. (v2.1)
+- `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.

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>` / `--kb-remote <url>` / `--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,13 +50,13 @@ 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 → SCAFFOLD → RED → TEST REVIEW → GREEN → 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                      |
@@ -65,19 +69,36 @@ cd my-project && bash setup.sh
 
 The main session is the orchestrator — it routes, it does not implement.
 
-## The loop (v2.0: TDD-first + regression guard)
+## The loop (v2.1: TDD-first + human gates + coverage guards)
 
 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.
+`RESEARCH -> SCAFFOLD -> RED -> TEST REVIEW -> GREEN -> E2E -> FIX -> CLOSE`. The
+implementer writes interface stubs only; the `test-author` writes the suite blind
+against those stubs (it must collect cleanly and FAIL — the RED gate) and emits a
+`docs/test-plan-phase-<n>.md` with a mandatory "NOT covered / assumptions"
+section. **TEST REVIEW** is a human gate: you approve the test plan before the
+implementer fills to green — so "all tests passed but the core was broken" can't
+slip through silently. Pure infra/config/doc phases keep the direct
+`RESEARCH -> IMPLEMENT -> TEST` order (no TEST REVIEW — no public surface).
+
+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 +163,7 @@ 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/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)
@@ -157,14 +179,20 @@ re-discovering the same Azure/Databricks gotchas project after project.
 **Setup (one-time per machine):**
 
 ```bash
-# 1. Create a GitHub repo: anpunkit-kb (empty)
-# 2. Clone it somewhere permanent on your machine
-git clone git@github.com:your-username/anpunkit-kb.git ~/anpunkit-kb
+# 1. Create a GitHub repo: anpunkit-kb (empty is fine)
+# 2. Clone it yourself, somewhere permanent — you own the git auth
+git clone git@github.com:<you>/anpunkit-kb.git ~/anpunkit-kb
 
-# 3. During setup.sh, provide the path when prompted
-bash setup.sh
+# 3. Point anpunkit at it
+npx create-anpunkit --kb-path ~/anpunkit-kb
+# (or paste the path at the interactive prompt)
 ```
 
+That's the last manual git you'll run against the KB. From then on the
+**session-start hook pulls** each session and **`/store-wisdom` commits and
+pushes** (always with your approval). The remote URL is recorded automatically
+from the clone's `origin`; `--kb-remote <url>` overrides it if needed.
+
 **Usage:**
 
 ```
@@ -200,6 +228,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
 ```
 
@@ -219,13 +248,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
 
@@ -251,7 +282,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
@@ -259,7 +290,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.
 
 ---
 

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