create-anpunkit 2.0.1 → 2.1.0

package/template/.claude/commands/phase.md

@@ -1,5 +1,5 @@
 ---
-description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression guard at CLOSE.
+description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> TEST REVIEW -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression + dataflow + evidence guards at CLOSE.
 argument-hint: [phase number]
 ---
 
@@ -29,8 +29,20 @@ b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
 c. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
    pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
 
-d. AUTH NUDGE: if INFRA.md exists and auth marker absent, remind me to run
-   `scripts/auth-setup.sh`. Not a gate — just a reminder.
+d. AUTH LIVENESS GATE (hard rule 16 — replaces the old soft nudge): if this phase
+   will run a real/E2E suite, confirm every credential it needs is live NOW.
+   - If INFRA.md has no `AUTH PROOF: PASS` marker -> STOP: "Auth never proven
+     reusable. Run `/infra` first."
+   - Run `scripts/auth-setup.sh --check` (Entra token obtainable + not expired)
+     and, for each external system this phase touches (docs/DATAFLOW.md external
+     rows + docs/ENDPOINTS.md auth column), confirm its credential is obtainable
+     headlessly. Any failure -> real/E2E is BLOCKED; tell me what to run; the
+     MOCK suite may still proceed.
+
+e. FRONTEND TRIGGER (hard rule 13): read docs/OVERVIEW.md `has_frontend` + the
+   frontend root. Set FRONTEND_PHASE=true iff `has_frontend: true` AND this
+   phase's `changes` (docs/PLAN.md) include any path under the frontend root.
+   This is a PATH MATCH, not a judgment call. Record FRONTEND_PHASE for the GATE.
 
 ---
 
@@ -40,13 +52,21 @@ Dispatch `researcher` in IMPL mode scoped to this phase.
 Returns terse summary + path. Read the file only if needed.
 Unknowns block the phase -> re-dispatch narrowed. No guessing.
 
+DATASOURCE DELTA (hard rule 15): if this phase tests against an external
+datasource, compare what it touches to the confirmed BASELINE in
+docs/research/datasource-<name>.md. If it touches a NEW table/column beyond the
+baseline -> surface my understanding of just that delta as a falsifiable claim;
+WAIT for confirm; append it to datasource-<name>.md. If it touches only confirmed
+data -> proceed with a one-line note, no stop. Real/E2E against an UNCONFIRMED
+datasource is HARD-BLOCKED (mock still runs).
+
 Then classify the phase:
 
   `TDD_PHASE` = the phase adds or changes a PUBLIC CALLABLE SURFACE (endpoint,
   exported function/class, CLI command, message contract) assertable from the
   acceptance spec. Size is NOT the criterion.
 
-- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3a → §3b).
+- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3a → §3r → §3b).
 - Pure infra/config/doc, no public surface -> `TDD_PHASE=false` -> run the
   non-TDD path (§2N → §3N).
 - AMBIGUOUS -> default `TDD_PHASE=true`, but STATE the classification + the reason
@@ -66,8 +86,10 @@ Returns the stub files + the interface surface.
 ## 3a. RED
 
 Dispatch `test-author` to write the REAL API suite (+ mock) BLIND against the
-stubs + acceptance. Place contract/ENDPOINTS tests in `tests/regression/`,
-phase-local tests in `tests/phase-<n>/`. Run the suite.
+stubs + acceptance, AND emit docs/test-plan-phase-<n>.md (acceptance criteria →
+test names, plus a mandatory "NOT covered / assumptions" section). Place
+contract/ENDPOINTS/DATAFLOW-transition tests in `tests/regression/`, phase-local
+tests in `tests/phase-<n>/`. Run the suite.
 
 RED GATE = every acceptance test COLLECTS cleanly AND FAILS (assertion /
 NotImplemented).
@@ -76,14 +98,29 @@ NotImplemented).
   fix SIGNATURES (not logic); re-run.
 - UNDERSPEC -> STOP; ask me to sharpen the acceptance spec.
 
+## 3r. TEST REVIEW — human gate (hard rule 12)
+
+STOP. Surface docs/test-plan-phase-<n>.md to me: what each acceptance criterion
+maps to, and the "NOT covered / assumptions" section. GREEN cannot begin until I
+approve. On rejection, classify with me:
+  - MISREAD of an adequate spec -> re-dispatch `test-author` with my feedback as
+    added constraint; re-run RED; re-present the test plan.
+  - UNDERSPEC (the acceptance spec itself is too vague) -> sharpen the acceptance
+    spec in docs/PLAN.md, then re-dispatch `test-author` fresh.
+Loop until I approve. This gate is unskippable on TDD phases.
+
 ## 3b. GREEN
 
 Dispatch `implementer` in FILL mode with the phase spec + research + the test
 file paths (it MAY read the tests — frozen before logic, no overfit — but must
 NOT edit them). Fill to green. Budget 3, WARN@2, STUCK@3.
 
-Dispatch `e2e-runner` IF this phase touches the frontend (reads INFRA.md target;
-`scripts/e2e-stack.sh up` / Playwright / `down`).
+If FRONTEND_PHASE (from PRE-FLIGHT e): dispatch `e2e-runner` — MANDATORY, not
+optional (hard rule 13). It reads INFRA.md target, runs `scripts/e2e-stack.sh up`
+/ Playwright / `down`, and captures a screenshot at EACH UI-existence assertion
+regardless of pass/fail to docs/evidence/e2e-phase-<n>/, with a summary in
+docs/research/e2e-<slug>.md. Acceptance spec has no UI-existence criterion ->
+e2e-runner returns UNDERSPEC -> STOP, sharpen the spec.
 
 PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
 
@@ -101,15 +138,17 @@ includes "deployed URL" before proceeding.
 ## 3N. TEST (blind)
 
 Dispatch `test-author`. It writes MOCK + REAL API suites from the acceptance
-spec — never reads the logic. (e2e-runner only if frontend.)
+spec — never reads the logic. (No TEST REVIEW gate on the non-TDD path — no
+public surface to mis-test. e2e-runner only if FRONTEND_PHASE.)
 
 =====================================================================
 
 ## GATE (both paths)
 
-PHASE GATE = current-phase REAL API suite passes AND (if frontend) E2E passes AND
-the accumulated mock regression corpus stays green AND every docs/ENDPOINTS.md
-entry has a regression test (checked at CLOSE).
+PHASE GATE = current-phase REAL API suite passes AND (FRONTEND_PHASE) E2E passes
+WITH evidence captured AND the accumulated mock regression corpus stays green AND
+every docs/ENDPOINTS.md entry has a regression test AND every REACHABLE
+docs/DATAFLOW.md transition has a regression test (all checked at CLOSE).
 - GATE PASS -> go to CLOSE.
 - GATE BLOCKED (SERVICE UNAVAILABLE, STACK NOT READY, AZURE UNAVAILABLE, FLAKE)
   -> tell me, wait. Not a code bug. For AZURE UNAVAILABLE: suggest `/infra verify`.
@@ -142,17 +181,28 @@ what to try next. Hand control to me.
 
 ## 6. CLOSE
 
-REGRESSION GATE (before closing — Feature 3):
+REGRESSION + COVERAGE GATES (before closing — all FAIL HARD, do not close):
 - Run `scripts/regression.sh` (mock corpus). A failure BLOCKS close -> route to FIX.
 - ENDPOINTS COVERAGE: every `docs/ENDPOINTS.md` entry MUST have >=1 test in
-  `tests/regression/`. Zero coverage -> FAIL HARD; do not close.
+  `tests/regression/`. Zero coverage -> FAIL HARD.
+- DATAFLOW COVERAGE (hard rule 14): every `docs/DATAFLOW.md` transition whose
+  trigger is REACHABLE in the code shipped so far MUST have >=1 test in
+  `tests/regression/`. Zero coverage on a reachable transition -> FAIL HARD.
+  Unreachable transitions list as PENDING (not failed). IF IS_FINAL_PHASE: any
+  transition still PENDING -> FAIL HARD (everything must be live by the last phase).
+- EVIDENCE (FRONTEND_PHASE only, hard rule 13): docs/evidence/e2e-phase-<n>/ must
+  contain at least the per-UI-existence-assertion screenshots. Empty -> FAIL HARD.
 - IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
   corpus). A failure blocks close.
 
 Mark phase `done` in docs/PLAN.md.
 
-ARCHITECTURE SELF-CHECK: did this phase add/remove/rename an agent, hook, or
-command, or change a workflow rule? YES -> run `/log-decision`. NO -> state why not.
+ARCHITECTURE / DATAFLOW SELF-CHECK:
+- Did this phase add/remove/rename an agent, hook, or command, or change a
+  workflow rule? YES -> run `/log-decision`. NO -> state why not.
+- Did this phase add/change an object's STATE LIFECYCLE? YES -> update
+  docs/DATAFLOW.md (hard rule 9) in this CLOSE, and confirm new reachable
+  transitions are covered. NO -> state why not.
 
 IF IS_FINAL_PHASE — FINAL CLOSE sequence:
 
@@ -175,6 +225,7 @@ IF IS_FINAL_PHASE — FINAL CLOSE sequence:
 
      ## Docs
      - Full endpoint catalogue: docs/ENDPOINTS.md
+     - Object/state flow: docs/DATAFLOW.md
      - Infrastructure: docs/INFRA.md
      - Project history: docs/HISTORY.md
      ```
@@ -194,6 +245,7 @@ After each step, update docs/STATE.md:
 
 phase: <n> (in progress)
 tdd: <true|false>
+frontend_phase: <true|false>
 completed: <steps done so far>
 next: <exact next step>
 blocker: <none or open issue>

package/template/.claude/commands/replan.md

@@ -1,5 +1,5 @@
 ---
-description: Revise docs/PLAN.md when it no longer matches reality — add, cut, split, merge, or reorder phases.
+description: Revise docs/PLAN.md when it no longer matches reality — add, cut, split, merge, or reorder phases. Keeps the deploy-last, ENDPOINTS, and DATAFLOW invariants intact.
 argument-hint: [what changed about the plan]
 ---
 
@@ -25,10 +25,13 @@ Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
    - A new external service is mentioned (Stripe, Twilio, a new Azure service, etc.)
    - The change involves architecture (a new integration pattern, auth change, etc.)
    - A service tier or quota change is implied
+   - A new external DATASOURCE or a change to an object's STATE LIFECYCLE
 
    If ANY of these signals are present: dispatch `researcher` in DESIGN mode
-   with the specific new service/pattern as the DESIGN TOPICS list. Show me the
-   key findings before proceeding to step 3.
+   with the specific new service/pattern as the DESIGN TOPICS list. For a new
+   datasource, it drafts a DATA UNDERSTANDING; surface it to me as a falsifiable
+   claim and confirm (baseline) before proceeding. Show me the key findings
+   before step 3.
 
    If none: proceed directly to step 3 (impl-research may still be dispatched
    in step 3 for non-trivial changes per the original logic).
@@ -37,11 +40,13 @@ Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
    was not needed, dispatch `researcher` in IMPL mode to ground the re-plan
    in facts.
 
-4. RE-PLAN. Dispatch `planner` with the change + current PLAN.md. It must:
+4. RE-PLAN. Dispatch `planner` with the change + current PLAN.md + DATAFLOW.md.
+   It must:
    - Keep done phases untouched.
    - Insert / cut / split / merge / reorder only PENDING phases.
    - Place new phases in correct DEPENDENCY order.
    - Keep every phase a vertical slice with its own acceptance spec.
+   - Preserve the UI-existence criterion on any frontend-touching phase.
    - Ensure the LAST pending phase still contains the deploy task block.
    - Renumber pending phases if needed; update STATE.md `phase:` pointer.
 
@@ -54,11 +59,20 @@ Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
    reconciled corpus still passes against live services. A failure -> surface it
    and stop before approval.
 
-6. SHOW ME the revised phase list + the regression-corpus changes, and STOP for
-   approval.
+6. RECONCILE DATAFLOW.md (v2.1). If the re-plan adds, cuts, or re-scopes objects
+   or transitions, update docs/DATAFLOW.md in step:
+   - A CUT/removed object or transition -> remove its row(s) and retire the
+     matching regression test(s).
+   - A new object/transition -> add the row(s); mark them PENDING until the phase
+     that makes them reachable runs. The deploy-last / "no PENDING at final phase"
+     invariant (hard rule 14) still holds.
+   - A reorder must not strand a transition as permanently unreachable.
 
-7. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
+7. SHOW ME the revised phase list + the regression-corpus changes + the
+   DATAFLOW.md changes, and STOP for approval.
+
+8. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
    change. Only run /log-decision if the workflow itself changed (rare).
 
-Report what changed: phases added / cut / split / reordered, and regression
-tests retired / consolidated.
+Report what changed: phases added / cut / split / reordered, regression tests
+retired / consolidated, and DATAFLOW rows added / removed.

package/template/.cursor/commands/infra.md

@@ -31,6 +31,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.
 
 ---
 
@@ -38,7 +63,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/.cursor/commands/overview.md

@@ -14,7 +14,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.
@@ -29,74 +31,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."

package/template/.cursor/commands/phase.md

@@ -24,8 +24,20 @@ b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
 c. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
    pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
 
-d. AUTH NUDGE: if INFRA.md exists and auth marker absent, remind me to run
-   `scripts/auth-setup.sh`. Not a gate — just a reminder.
+d. AUTH LIVENESS GATE (hard rule 16 — replaces the old soft nudge): if this phase
+   will run a real/E2E suite, confirm every credential it needs is live NOW.
+   - If INFRA.md has no `AUTH PROOF: PASS` marker -> STOP: "Auth never proven
+     reusable. Run `/infra` first."
+   - Run `scripts/auth-setup.sh --check` (Entra token obtainable + not expired)
+     and, for each external system this phase touches (docs/DATAFLOW.md external
+     rows + docs/ENDPOINTS.md auth column), confirm its credential is obtainable
+     headlessly. Any failure -> real/E2E is BLOCKED; tell me what to run; the
+     MOCK suite may still proceed.
+
+e. FRONTEND TRIGGER (hard rule 13): read docs/OVERVIEW.md `has_frontend` + the
+   frontend root. Set FRONTEND_PHASE=true iff `has_frontend: true` AND this
+   phase's `changes` (docs/PLAN.md) include any path under the frontend root.
+   This is a PATH MATCH, not a judgment call. Record FRONTEND_PHASE for the GATE.
 
 ---
 
@@ -35,13 +47,21 @@ Dispatch `researcher` in IMPL mode scoped to this phase.
 Returns terse summary + path. Read the file only if needed.
 Unknowns block the phase -> re-dispatch narrowed. No guessing.
 
+DATASOURCE DELTA (hard rule 15): if this phase tests against an external
+datasource, compare what it touches to the confirmed BASELINE in
+docs/research/datasource-<name>.md. If it touches a NEW table/column beyond the
+baseline -> surface my understanding of just that delta as a falsifiable claim;
+WAIT for confirm; append it to datasource-<name>.md. If it touches only confirmed
+data -> proceed with a one-line note, no stop. Real/E2E against an UNCONFIRMED
+datasource is HARD-BLOCKED (mock still runs).
+
 Then classify the phase:
 
   `TDD_PHASE` = the phase adds or changes a PUBLIC CALLABLE SURFACE (endpoint,
   exported function/class, CLI command, message contract) assertable from the
   acceptance spec. Size is NOT the criterion.
 
-- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3a → §3b).
+- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3a → §3r → §3b).
 - Pure infra/config/doc, no public surface -> `TDD_PHASE=false` -> run the
   non-TDD path (§2N → §3N).
 - AMBIGUOUS -> default `TDD_PHASE=true`, but STATE the classification + the reason
@@ -61,8 +81,10 @@ Returns the stub files + the interface surface.
 ## 3a. RED
 
 Dispatch `test-author` to write the REAL API suite (+ mock) BLIND against the
-stubs + acceptance. Place contract/ENDPOINTS tests in `tests/regression/`,
-phase-local tests in `tests/phase-<n>/`. Run the suite.
+stubs + acceptance, AND emit docs/test-plan-phase-<n>.md (acceptance criteria →
+test names, plus a mandatory "NOT covered / assumptions" section). Place
+contract/ENDPOINTS/DATAFLOW-transition tests in `tests/regression/`, phase-local
+tests in `tests/phase-<n>/`. Run the suite.
 
 RED GATE = every acceptance test COLLECTS cleanly AND FAILS (assertion /
 NotImplemented).
@@ -71,14 +93,29 @@ NotImplemented).
   fix SIGNATURES (not logic); re-run.
 - UNDERSPEC -> STOP; ask me to sharpen the acceptance spec.
 
+## 3r. TEST REVIEW — human gate (hard rule 12)
+
+STOP. Surface docs/test-plan-phase-<n>.md to me: what each acceptance criterion
+maps to, and the "NOT covered / assumptions" section. GREEN cannot begin until I
+approve. On rejection, classify with me:
+  - MISREAD of an adequate spec -> re-dispatch `test-author` with my feedback as
+    added constraint; re-run RED; re-present the test plan.
+  - UNDERSPEC (the acceptance spec itself is too vague) -> sharpen the acceptance
+    spec in docs/PLAN.md, then re-dispatch `test-author` fresh.
+Loop until I approve. This gate is unskippable on TDD phases.
+
 ## 3b. GREEN
 
 Dispatch `implementer` in FILL mode with the phase spec + research + the test
 file paths (it MAY read the tests — frozen before logic, no overfit — but must
 NOT edit them). Fill to green. Budget 3, WARN@2, STUCK@3.
 
-Dispatch `e2e-runner` IF this phase touches the frontend (reads INFRA.md target;
-`scripts/e2e-stack.sh up` / Playwright / `down`).
+If FRONTEND_PHASE (from PRE-FLIGHT e): dispatch `e2e-runner` — MANDATORY, not
+optional (hard rule 13). It reads INFRA.md target, runs `scripts/e2e-stack.sh up`
+/ Playwright / `down`, and captures a screenshot at EACH UI-existence assertion
+regardless of pass/fail to docs/evidence/e2e-phase-<n>/, with a summary in
+docs/research/e2e-<slug>.md. Acceptance spec has no UI-existence criterion ->
+e2e-runner returns UNDERSPEC -> STOP, sharpen the spec.
 
 PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
 
@@ -96,15 +133,17 @@ includes "deployed URL" before proceeding.
 ## 3N. TEST (blind)
 
 Dispatch `test-author`. It writes MOCK + REAL API suites from the acceptance
-spec — never reads the logic. (e2e-runner only if frontend.)
+spec — never reads the logic. (No TEST REVIEW gate on the non-TDD path — no
+public surface to mis-test. e2e-runner only if FRONTEND_PHASE.)
 
 =====================================================================
 
 ## GATE (both paths)
 
-PHASE GATE = current-phase REAL API suite passes AND (if frontend) E2E passes AND
-the accumulated mock regression corpus stays green AND every docs/ENDPOINTS.md
-entry has a regression test (checked at CLOSE).
+PHASE GATE = current-phase REAL API suite passes AND (FRONTEND_PHASE) E2E passes
+WITH evidence captured AND the accumulated mock regression corpus stays green AND
+every docs/ENDPOINTS.md entry has a regression test AND every REACHABLE
+docs/DATAFLOW.md transition has a regression test (all checked at CLOSE).
 - GATE PASS -> go to CLOSE.
 - GATE BLOCKED (SERVICE UNAVAILABLE, STACK NOT READY, AZURE UNAVAILABLE, FLAKE)
   -> tell me, wait. Not a code bug. For AZURE UNAVAILABLE: suggest `/infra verify`.
@@ -137,17 +176,28 @@ what to try next. Hand control to me.
 
 ## 6. CLOSE
 
-REGRESSION GATE (before closing — Feature 3):
+REGRESSION + COVERAGE GATES (before closing — all FAIL HARD, do not close):
 - Run `scripts/regression.sh` (mock corpus). A failure BLOCKS close -> route to FIX.
 - ENDPOINTS COVERAGE: every `docs/ENDPOINTS.md` entry MUST have >=1 test in
-  `tests/regression/`. Zero coverage -> FAIL HARD; do not close.
+  `tests/regression/`. Zero coverage -> FAIL HARD.
+- DATAFLOW COVERAGE (hard rule 14): every `docs/DATAFLOW.md` transition whose
+  trigger is REACHABLE in the code shipped so far MUST have >=1 test in
+  `tests/regression/`. Zero coverage on a reachable transition -> FAIL HARD.
+  Unreachable transitions list as PENDING (not failed). IF IS_FINAL_PHASE: any
+  transition still PENDING -> FAIL HARD (everything must be live by the last phase).
+- EVIDENCE (FRONTEND_PHASE only, hard rule 13): docs/evidence/e2e-phase-<n>/ must
+  contain at least the per-UI-existence-assertion screenshots. Empty -> FAIL HARD.
 - IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
   corpus). A failure blocks close.
 
 Mark phase `done` in docs/PLAN.md.
 
-ARCHITECTURE SELF-CHECK: did this phase add/remove/rename an agent, hook, or
-command, or change a workflow rule? YES -> run `/log-decision`. NO -> state why not.
+ARCHITECTURE / DATAFLOW SELF-CHECK:
+- Did this phase add/remove/rename an agent, hook, or command, or change a
+  workflow rule? YES -> run `/log-decision`. NO -> state why not.
+- Did this phase add/change an object's STATE LIFECYCLE? YES -> update
+  docs/DATAFLOW.md (hard rule 9) in this CLOSE, and confirm new reachable
+  transitions are covered. NO -> state why not.
 
 IF IS_FINAL_PHASE — FINAL CLOSE sequence:
 
@@ -170,6 +220,7 @@ IF IS_FINAL_PHASE — FINAL CLOSE sequence:
 
      ## Docs
      - Full endpoint catalogue: docs/ENDPOINTS.md
+     - Object/state flow: docs/DATAFLOW.md
      - Infrastructure: docs/INFRA.md
      - Project history: docs/HISTORY.md
      ```
@@ -189,6 +240,7 @@ After each step, update docs/STATE.md:
 
 phase: <n> (in progress)
 tdd: <true|false>
+frontend_phase: <true|false>
 completed: <steps done so far>
 next: <exact next step>
 blocker: <none or open issue>

package/template/.cursor/commands/replan.md

@@ -20,10 +20,13 @@ Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
    - A new external service is mentioned (Stripe, Twilio, a new Azure service, etc.)
    - The change involves architecture (a new integration pattern, auth change, etc.)
    - A service tier or quota change is implied
+   - A new external DATASOURCE or a change to an object's STATE LIFECYCLE
 
    If ANY of these signals are present: dispatch `researcher` in DESIGN mode
-   with the specific new service/pattern as the DESIGN TOPICS list. Show me the
-   key findings before proceeding to step 3.
+   with the specific new service/pattern as the DESIGN TOPICS list. For a new
+   datasource, it drafts a DATA UNDERSTANDING; surface it to me as a falsifiable
+   claim and confirm (baseline) before proceeding. Show me the key findings
+   before step 3.
 
    If none: proceed directly to step 3 (impl-research may still be dispatched
    in step 3 for non-trivial changes per the original logic).
@@ -32,11 +35,13 @@ Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
    was not needed, dispatch `researcher` in IMPL mode to ground the re-plan
    in facts.
 
-4. RE-PLAN. Dispatch `planner` with the change + current PLAN.md. It must:
+4. RE-PLAN. Dispatch `planner` with the change + current PLAN.md + DATAFLOW.md.
+   It must:
    - Keep done phases untouched.
    - Insert / cut / split / merge / reorder only PENDING phases.
    - Place new phases in correct DEPENDENCY order.
    - Keep every phase a vertical slice with its own acceptance spec.
+   - Preserve the UI-existence criterion on any frontend-touching phase.
    - Ensure the LAST pending phase still contains the deploy task block.
    - Renumber pending phases if needed; update STATE.md `phase:` pointer.
 
@@ -49,11 +54,20 @@ Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
    reconciled corpus still passes against live services. A failure -> surface it
    and stop before approval.
 
-6. SHOW ME the revised phase list + the regression-corpus changes, and STOP for
-   approval.
+6. RECONCILE DATAFLOW.md (v2.1). If the re-plan adds, cuts, or re-scopes objects
+   or transitions, update docs/DATAFLOW.md in step:
+   - A CUT/removed object or transition -> remove its row(s) and retire the
+     matching regression test(s).
+   - A new object/transition -> add the row(s); mark them PENDING until the phase
+     that makes them reachable runs. The deploy-last / "no PENDING at final phase"
+     invariant (hard rule 14) still holds.
+   - A reorder must not strand a transition as permanently unreachable.
 
-7. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
+7. SHOW ME the revised phase list + the regression-corpus changes + the
+   DATAFLOW.md changes, and STOP for approval.
+
+8. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
    change. Only run /log-decision if the workflow itself changed (rare).
 
-Report what changed: phases added / cut / split / reordered, and regression
-tests retired / consolidated.
+Report what changed: phases added / cut / split / reordered, regression tests
+retired / consolidated, and DATAFLOW rows added / removed.