create-anpunkit 2.0.3 → 2.2.0

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

@@ -1,5 +1,5 @@
 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.
 
@@ -24,8 +24,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.
 
 ---
 
@@ -35,52 +48,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)
@@ -95,16 +176,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`.
@@ -112,17 +196,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:
@@ -135,19 +219,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:
 
@@ -170,6 +267,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 +287,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.

package/template/.gitattributes

@@ -5,6 +5,7 @@
 *.js    text eol=lf
 *.mjs   text eol=lf
 *.ts    text eol=lf
+*.py    text eol=lf
 *.json  text eol=lf
 *.md    text eol=lf
 *.ps1   text eol=crlf