create-anpunkit 2.0.1 → 2.1.0

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

package/template/docs/DESIGN_LOG.md

@@ -17,6 +17,17 @@
 
 Newest first. One entry per architectural change. Appended by `/log-decision`.
 
+- **(v2.0.2)** — KB setup stays PATH-FIRST: the user clones the KB repo
+  themselves (`git clone ... ~/anpunkit-kb`) and passes `--kb-path` (or the
+  interactive prompt). New: the remote URL is auto-recorded from the clone's
+  `origin`, so `--kb-remote` is optional metadata. After setup, no manual git:
+  the session-start hook pulls; `/store-wisdom` commits and pushes (human-gated).
+  REJECTED: URL-first setup where anpunkit runs `git clone` itself — it was built
+  and tested, then dropped: it entangles a fresh install with the user's GitHub
+  authentication (SSH keys / gh auth), and a clone failure mid-setup is a worse
+  failure mode than asking a developer to run one clone command they already
+  understand. Setup records state; it does not acquire credentials.
+
 - **(v2.0.1)** — Windows portability fix for the npx installer. (1) `cli.js` no
   longer trusts bare `bash` on win32: PowerShell resolves it to the System32 WSL
   relay, which fails with `execvpe(/bin/bash)` when no distro is installed. The