create-anpunkit 2.0.3 → 2.2.0

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,132 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
      Quotas, rate limits, known gaps?
    - Azure services: any sizing or SKU constraints relevant to the use case?
    - Auth patterns: any MSAL/Entra constraints for this scenario?
+   - Each external DATASOURCE: its DATA UNDERSTANDING (see step 4).
    - Any other architectural assumption in the round-1 answers worth verifying.
 
 3. Dispatch `researcher` in DESIGN mode with the DESIGN TOPICS list.
-   It returns a terse summary + file paths. Read the design-<slug>.md files
-   only if needed.
+   It returns a terse summary + file paths. For every external datasource it
+   drafts a DATA UNDERSTANDING to `docs/research/datasource-<name>.md`:
+   grain (one row = what?), the fields likely under test with their meaning and
+   real-world nullability/range, a sample-fixture shape, and the assumption that
+   if wrong makes a test meaningless. Read the design-<slug>.md files only if needed.
+
+---
+
+### RESEARCH REVIEW (v2.1 — read-and-confirm, not a grill)
+
+4. Surface the design-research findings to me DIRECTLY, phrased as FALSIFIABLE
+   CLAIMS about my systems — not a passive findings dump. For example:
+   "I understand your Tableau extract refreshes nightly and the API is read-only;
+   the `orders` grain is one row per line-item; `status` is never null in practice."
+   For each external datasource, present its drafted DATA UNDERSTANDING for me to
+   confirm or correct. Then:
+   - Minor corrections -> fold forward as seed context for round-2 grill.
+   - A MATERIAL error (wrong service tier, wrong data model, wrong grain) ->
+     re-dispatch `researcher` with the correction, then re-present. Do not carry
+     a known-wrong research file into grill or OVERVIEW.md.
+   A confirmed datasource understanding is recorded as the BASELINE in its
+   `datasource-<name>.md`. (Per-phase delta-confirms happen later in `/phase`.)
 
 ---
 
 ### Round 2 — Research-informed re-grill
 
-4. Run `grill-me` again — a second focused pass. Seed it with:
+5. Run `grill-me` again — a second focused pass. Seed it with:
    - The round-1 answers (already established — do not re-ask these)
    - The design-research key findings and new questions raised
+   - The RESEARCH REVIEW corrections
 
-   The re-grill asks whatever it needs to build complete understanding. It is
-   not limited to "gaps from research" — research context makes new questions
-   relevant even if it found no blockers. Do not re-ask what round 1 already
-   established clearly.
+   This pass MUST explicitly cover DATA STRUCTURE and DATAFLOW, especially the
+   STATE FLOW of each key object: what are the core entities, what states does
+   each move through, what transition triggers each change, who writes it, and
+   does any state map to an external system. The re-grill asks whatever else it
+   needs for complete understanding. Do not re-ask what round 1 established.
 
 ---
 
-### Write OVERVIEW.md
+### Write OVERVIEW.md + DATAFLOW.md
 
-5. Write docs/OVERVIEW.md from the COMBINED output of round-1 + design-research
-   + round-2. Include:
+6. Write docs/OVERVIEW.md from the COMBINED output of round-1 + design-research
+   + research review + round-2. Include:
    - Project purpose and success criteria
    - Scope and constraints (informed by research findings)
    - External services with confirmed capabilities/limits
    - "Azure services" section: every service with expected SKU
    - Deployment target (azure-deployed or local-docker for E2E)
+   - `has_frontend: true|false` and, if true, the frontend root path
    - Known risks / open questions (if any remain)
 
    OVERVIEW.md is written HERE — after the re-grill, not before.
 
+7. Write docs/DATAFLOW.md — a state-transition table per key object, driven by the
+   round-2 data/state-flow grill. The data-side analogue of ENDPOINTS.md. Columns:
+ ```
+ # Dataflow — <project name>
+ > Maintained from /overview; updated each phase that changes an object lifecycle.
+ > Each transition row is one testable unit (drives the CLOSE coverage gate).
+
+ | object | states | transition (from→to) | trigger | who writes | external system |
+ |--------|--------|----------------------|---------|------------|-----------------|
+ | Order  | draft,submitted,fulfilled | draft→submitted | POST /orders/submit | order-svc | — |
+ ```
+   Any row whose `external system` is populated ties to a `datasource-<name>.md`.
+
 ---
 
 ### Plan
 
-6. Hand OVERVIEW.md + design-research findings to the `planner` subagent.
-   PLAN.md MUST:
+8. Hand OVERVIEW.md + DATAFLOW.md + design-research findings to the `planner`
+   subagent. PLAN.md MUST:
    - Start with Phase 0 (infra setup) as the first entry (always).
    - End with a final code phase that contains the deploy task block.
-
-7. Create docs/STATE.md:
+   - For any phase whose `changes` touch the frontend root: include ≥1
+     UI-existence acceptance criterion naming the specific user-visible
+     interactive element the phase introduces (not "page renders 200").
+   - Map each phase to the DATAFLOW transitions it is expected to make reachable.
+
+   The planner ALSO writes the up-front SKELETON spec files (v2.2, §5.44/§5.51):
+   one `docs/spec-phase-<n>.md` per public-surface phase (skip Phase 0 + pure
+   infra/config/doc phases), enumerating the case NAMES — happy path, each named
+   edge, each named failure + error code — for every `dataflow:` transition and
+   every `acceptance` criterion, with `TBD` values. The generated header transcludes
+   that phase's `acceptance:` line + in-scope `DATAFLOW.md` transition rows verbatim.
+
+8b. STAMP each skeleton's staleness hash: for every `docs/spec-phase-<n>.md` the
+   planner wrote, run `bash scripts/spec-staleness.sh stamp <n>`. This embeds the
+   hash of the transcluded acceptance line + transition rows so phase-time
+   `/phase` can detect upstream drift. (Values are filled per phase by `spec-author`.)
+
+9. Create docs/STATE.md:
 ```
 
 # STATE
 
 phase: 0 (pending)
-completed: project bootstrapped — design research done, double grill done
+completed: project bootstrapped — design research, research review, double grill (incl. data/state flow) done
 next: run /infra to provision Azure infrastructure
 blocker: none
 
 ```
-8. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
+10. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
 
-9. Create empty docs/HISTORY.md.
+11. Create empty docs/HISTORY.md.
 
-10. Create docs/INFRA.md from the template (populated by /infra).
+12. Create docs/INFRA.md from the template (populated by /infra).
 
-11. Create docs/ENDPOINTS.md:
+13. Create docs/ENDPOINTS.md:
  ```
  # Endpoints — <project name>
  > Maintained by implementer. Updated each phase.
  > Base URL: (populated after deployment phase)
  ```
 
-Then stop and show me PLAN.md for approval before any phase starts.
+Then stop and show me PLAN.md + DATAFLOW.md for approval before any phase starts.
+EXTEND the approval surface (v2.2, §5.51 — one confirmation, no new gate): for each
+public-surface phase, list the transition/acceptance ids it covers and the enumerated
+case NAMES (no values). I confirm the case-name set is COMPLETE here — these names
+are the up-front behavioral contract; values get filled + reviewed per phase at
+`/phase` SPEC REVIEW.
 
-Remind me: "Run `/infra` next to provision the Azure environment (Phase 0)
-before starting Phase 1."
+Remind me: "Run `/infra` next to provision the Azure environment (Phase 0) and
+run the one-time AUTH PROOF before starting Phase 1."

package/template/commands.src/phase.md

@@ -1,10 +1,10 @@
 ---
-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 SPEC fill -> SPEC REVIEW -> SCAFFOLD -> RED -> conformance -> GREEN -> boundary/E2E; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression + dataflow + evidence guards at CLOSE.
 argument-hint: [phase number]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
-you do NOT implement or debug yourself.
+you do NOT implement, fill specs, or debug yourself.
 
 Note: subagents cannot talk to the user. Only YOU can.
 
@@ -29,8 +29,21 @@ 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): if this phase will run a boundary/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 -> boundary/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 — it gates the
+   `ui` boundary run + evidence at CLOSE.
 
 ---
 
@@ -40,52 +53,120 @@ 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. Boundary/E2E against an UNCONFIRMED
+datasource is HARD-BLOCKED (mock still runs). The confirmed baseline is what
+`spec-author` grounds fixtures in.
+
 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 → §3 → §4 → §5 → §6 → §7).
 - 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
-  to me, so I can override to non-TDD BEFORE SCAFFOLD fires. (Hard rule 11: never
-  downgrade a TDD phase just to dodge the RED gate.)
+  to me, so I can override to non-TDD BEFORE SPEC fill fires. (Hard rule 11: never
+  downgrade a TDD phase just to dodge the gates.)
 
 =====================================================================
 ## TDD PATH  (TDD_PHASE=true)
 =====================================================================
 
-## 2. SCAFFOLD
+## 2. SPEC FILL + STALENESS
+
+a. SKELETON CHECK: confirm docs/spec-phase-<n>.md exists (planner generated it at
+   /overview). If MISSING (planner classified it non-TDD, or it's a new phase from
+   /replan): generate the skeleton NOW from this phase's PLAN.md `acceptance` +
+   `dataflow:` transitions in the planner skeleton format (generated header + named
+   `TBD` rows), then `bash scripts/spec-staleness.sh stamp <n>` to stamp its hash.
+
+b. Dispatch `spec-author`. It fills each case row with a real input payload
+   (`fixtures/<case-id>-input.json`), concrete expected output
+   (`fixtures/<case-id>-expected.json`), matcher tokens for volatile fields,
+   `error-code` for failures, and `selector/assert/value` `ui` descriptors —
+   grounded in the RESEARCH findings + the confirmed datasource baseline.
+
+c. CASE-SET-DIVERGENCE (hard re-entry, hard rule 12 / §5.52): if `spec-author`
+   returns `CASE-SET-DIVERGENCE` (a required case can't be filled from real facts,
+   or research revealed an unlisted/contradicted case) -> STOP. Surface the finding.
+   I amend the up-front case-name contract in the skeleton; you re-stamp
+   (`bash scripts/spec-staleness.sh stamp <n>`); then re-dispatch `spec-author` to
+   re-fill from scratch. AI never amends the case-name set — I own the contract.
+
+d. STALENESS (hard rule 17): run `bash scripts/spec-staleness.sh <n>`. Nonzero
+   (upstream PLAN acceptance line / DATAFLOW rows drifted since the skeleton was
+   stamped, e.g. via /replan) -> regenerate the skeleton header from current
+   PLAN/DATAFLOW, re-stamp, re-dispatch `spec-author`. Do NOT hand-edit the hash.
+
+## 3. SPEC REVIEW — human gate (hard rule 12)
+
+STOP. Surface the FILLED cases to me as FALSIFIABLE CLAIMS in plain language, e.g.:
+  - "POST /orders/submit with an empty line-item list → 422 EMPTY_ORDER."
+  - "Successful submit of a 3-line order → 201; order.id is a UUID; order.status is
+    'submitted'."
+Re-run `bash scripts/spec-staleness.sh <n>` at entry (nonzero -> back to §2d).
+SCAFFOLD cannot begin until I confirm. Classify any rejection WITH me (§5.50):
+  - WRONG EXPECTED -> fix the case row + `fixtures/<case-id>-expected.json`; no
+    re-research. (You may patch the fixture directly per my correction.)
+  - WRONG INPUT SHAPE -> re-dispatch `spec-author` with the correction.
+  - NEW CASE or CONTRADICTED CASE -> hard re-entry (§2c): I amend the skeleton, you
+    re-stamp, re-confirm the amended case(s) + any case sharing their `covers` id
+    (the staleness hash certifies the unchanged remainder — not re-read), re-fill.
+Loop until I approve. Unskippable on TDD phases.
+
+## 4. SCAFFOLD
 
 Dispatch `implementer` in SCAFFOLD mode: interface stubs only (signatures +
-types; bodies raise NotImplementedError / return 501); NO logic, NO tests.
-Returns the stub files + the interface surface.
+types; bodies raise NotImplementedError / return 501); NO logic, NO tests, NO
+edits to the spec or fixtures. Returns the stub files + the interface surface.
+
+## 5. RED
 
-## 3a. RED
+Dispatch `test-author` to EMIT the boundary harness from the locked spec `data`
+rows: one deep-equality assertion per case against `fixtures/<case-id>-expected.json`
+via the kit comparator `tests/helpers/spec-assert.*`, each citing its case with a
+`# spec: <case-id>` comment. It does NOT author assertions — it generates them from
+the spec. Place contract/ENDPOINTS/transition tests in `tests/regression/`,
+phase-local in `tests/phase-<n>/`.
 
-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.
+If FRONTEND_PHASE (and the phase has `ui` cases): also dispatch `e2e-runner` to EMIT
+Playwright assertions from each `ui` case's `fixtures/<case-id>-ui.json` descriptor,
+each citing `// spec: <case-id>`. Run the suites.
 
-RED GATE = every acceptance test COLLECTS cleanly AND FAILS (assertion /
-NotImplemented).
-- Any test PASSES on stubs -> STOP (spec trivial or test wrong); show me.
+RED GATE = every case test COLLECTS cleanly AND FAILS (assertion / NotImplemented).
+- Any test PASSES on stubs -> STOP (spec trivial or emitter wrong); show me.
 - Collection / import / syntax error -> stub mismatch; re-dispatch SCAFFOLD to
   fix SIGNATURES (not logic); re-run.
-- UNDERSPEC -> STOP; ask me to sharpen the acceptance spec.
 
-## 3b. GREEN
+## 6. CONFORMANCE GATE (hard rule 18) — replaces the v2.1 human TEST REVIEW
+
+Run `bash scripts/spec-conformance.sh <n>`. It loud-fails (and BLOCKS GREEN) if:
+  - any `TBD` marker remains in docs/spec-phase-<n>.md or a referenced fixture, OR
+  - any case-id in the spec table has no boundary test citing it (`# spec: <case-id>`).
+Nonzero -> fix the gap (re-dispatch `spec-author` for a stray TBD, or `test-author`/
+`e2e-runner` for a missing citation) and re-run. GREEN cannot start until it passes.
+
+## 7. GREEN + BOUNDARY/E2E
 
-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 `implementer` in FILL mode with the FILLED docs/spec-phase-<n>.md + its
+fixtures + research + the generated test file paths (it MAY read the tests — frozen
+before logic, no overfit — but must NOT edit tests, spec, or fixtures). Fill to
+green against the spec. 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`).
+Run the BOUNDARY suite (real HTTP/CLI/message; `TEST_MODE=real`). If FRONTEND_PHASE,
+`e2e-runner` runs its emitted `ui` specs — MANDATORY (hard rule 13) — 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.
 
-PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
+PHASE GATE (rule 5) -> go to §8/§9/§10 (see GATE below).
 
 =====================================================================
 ## NON-TDD PATH  (TDD_PHASE=false)
@@ -100,16 +181,19 @@ 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.)
+Dispatch `test-author`. It writes MOCK + boundary suites from the acceptance
+spec — never reads the logic. (No spec file, SPEC REVIEW, or conformance gate on
+the non-TDD path — no public surface to contract. 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 BOUNDARY suite passes AND (FRONTEND_PHASE) the `ui`
+boundary passes WITH evidence captured AND the accumulated mock regression corpus
+stays green AND every docs/ENDPOINTS.md entry has a regression test AND (TDD)
+`spec-conformance.sh` passed AND every REACHABLE docs/DATAFLOW.md transition has a
+filled case in the phase spec (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`.
@@ -117,17 +201,17 @@ entry has a regression test (checked at CLOSE).
 
 ---
 
-## 4. FIX
+## 8. FIX
 
 Dispatch `debugger` (isolated context) on the specific failure.
-- FIXED -> re-run TEST (and the regression corpus).
+- FIXED -> re-run the boundary suite (and the regression corpus).
 - SERVICE UNAVAILABLE -> tell me, wait. Suggest `/infra verify` if Azure.
 - WARN (2 attempts failed) -> relay immediately, then let debugger finish attempt 3.
 - STUCK -> go to ESCALATE.
 
 ---
 
-## 5. ESCALATE — circuit breaker. Mode B.
+## 9. ESCALATE — circuit breaker. Mode B.
 
 FIRST STUCK: STOP. Present to me: the problem, 3 failed hypotheses, the
 debugger's recommendation, the debug file path. Ask what to do. Wait. Options:
@@ -140,19 +224,32 @@ what to try next. Hand control to me.
 
 ---
 
-## 6. CLOSE
+## 10. CLOSE
 
-REGRESSION GATE (before closing — Feature 3):
-- Run `scripts/regression.sh` (mock corpus). A failure BLOCKS close -> route to FIX.
+REGRESSION + COVERAGE GATES (before closing — all FAIL HARD, do not close):
+- Run `bash 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.
-- IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
+  `tests/regression/`. Zero coverage -> FAIL HARD.
+- DATAFLOW COVERAGE (hard rule 14, re-seamed v2.2): every `docs/DATAFLOW.md`
+  transition whose trigger is REACHABLE in the code shipped so far MUST have >=1
+  FILLED CASE in docs/spec-phase-<n>.md. 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. (The case→test half is
+  already enforced by `spec-conformance.sh` at §6 — every case-id is cited by a
+  boundary test, which by placement lands in tests/regression/.)
+- 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 `bash 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 by a filled case. NO -> state why not.
 
 IF IS_FINAL_PHASE — FINAL CLOSE sequence:
 
@@ -175,6 +272,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 +292,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/commands.src/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.