create-anpunkit 2.1.0 → 2.3.0

package/template/README.md

@@ -1,14 +1,18 @@
 # anpunkit — AI-coding system development workflow
 
-A reusable, self-navigating workflow for **Claude Code and Cursor**. Install with
-one `npx` command, or clone it directly into your project.
+A reusable, self-navigating workflow for **Claude Code**. Install with one `npx`
+command, or clone it directly into your project.
 
 ## Why
 
 Codifies a `design-research -> grill -> plan -> implement -> test -> deploy` loop
-with vertical-slice phases, blind testing, agent orchestration, automatic context
-hygiene, and Azure infrastructure as a first-class Phase 0 — so the workflow runs
-itself instead of being hand-steered every session.
+with vertical-slice phases, blind testing, agent orchestration, and automatic
+context hygiene — so the workflow runs itself instead of being hand-steered every
+session. The invariant core (loop, gates, doc system, commands) is use-case
+agnostic; web/Azure practice ships as **preinstalled knowledge docs**
+(`knowledge/webapp.md`, `knowledge/azure.md`) that the researcher consults only
+when your declared project type calls for them. Works for web apps, desktop apps,
+scripts, and libraries alike.
 
 ## The core idea
 
@@ -22,20 +26,22 @@ Putting "read the issue log" in a hook is why it stops getting skipped.
 ```bash
 cd my-project
 npx create-anpunkit            # non-destructive: never clobbers your files
-# then open Claude Code or Cursor — the session-start hook fires automatically
-/overview                      # bootstrap the project (includes Phase 0 infra)
+# then open Claude Code — the session-start hook fires automatically
+/overview                      # bootstrap the project (declares project type + flags)
 ```
-Useful flags: `--dry-run` (print the per-tool plan, write nothing), `--force`
-(overwrite user-modified kit files), `--tools <claude,cursor>` (install only the
-selected tools' files; interactive menu if omitted on a fresh TTY install),
-`--add-tool <name>` (lay down an additional tool's files into an existing
-project), `--kb-path <dir>` (your pre-cloned KB repo; remote auto-recorded from
-its origin) / `--no-kb`.
+Useful flags: `--dry-run` (print the plan, write nothing), `--force` (overwrite
+user-modified kit files), `--kb-path <dir>` (your pre-cloned KB repo; remote
+auto-recorded from its origin) / `--no-kb`.
 
 Upgrading an existing anpunkit project? Re-run `npx create-anpunkit`. It refreshes
 kit-owned files, preserves anything you modified as `<file>.anpunkit-new`, merges
-hook config into your existing `settings.json` / `.cursor/hooks.json`, and writes a
-timestamped `.anpunkit-backup-*/` first.
+hook config into your existing `.claude/settings.json`, and writes a timestamped
+`.anpunkit-backup-*/` first.
+
+> **Upgrading from v2.2 (Cursor dropped):** v2.3 is Claude Code only. After
+> upgrading you may safely delete the now-orphaned `.cursor/`,
+> `.claude/hooks/cursor-session-start.sh`, and `.claude/anpunkit-tools.json` —
+> setup.sh no longer manages them.
 
 **Kit developers — clone + `setup.sh`:**
 ```bash
@@ -50,9 +56,9 @@ cd my-project && bash setup.sh
 
 |Command          |Does                                                                          |
 |-----------------|------------------------------------------------------------------------------|
-|`/overview`      |design-research → RESEARCH REVIEW → grill (×2, incl. data/state flow) → OVERVIEW + DATAFLOW → PLAN (Phase 0 first) → STATE|
-|`/infra`         |provision Azure infra: Bicep → what-if → review → apply → INFRA.md + .env.test → AUTH PROOF|
-|`/phase [n]`     |run one phase: research → SCAFFOLD → RED → TEST REVIEW → GREEN → E2E, with circuit breaker|
+|`/overview`      |design-research → RESEARCH REVIEW → grill (×2, incl. data/state flow) → OVERVIEW (+ project flags) + DATAFLOW → PLAN → STATE|
+|`/infra`         |provision infra (when `infra_needed`): IaC → what-if → review → apply → INFRA.md + .env.test → AUTH PROOF|
+|`/phase [n]`     |run one phase: research → SPEC fill → SPEC REVIEW → SCAFFOLD → RED → conformance → GREEN → boundary/E2E, with circuit breaker|
 |`/quick [change]`|small obvious change, direct, no agent chain                                  |
 |`/unstuck`       |deep re-research after a circuit breaker (you trigger it)                     |
 |`/synthesize`    |compress STATE.md, dedup ISSUES.md, prune snapshots                           |
@@ -63,23 +69,40 @@ cd my-project && bash setup.sh
 
 ## Subagents
 
-`researcher` (Haiku, two modes: design + impl) · `planner` (Opus) · `infra-provisioner` (Opus) ·
-`implementer` (Opus, SCAFFOLD/FILL modes) · `test-author` (Opus, blind, RED-first) · `debugger` (Opus, isolated) ·
-`e2e-runner` (Opus, blind, Playwright) · `synthesizer` (Haiku)
+`researcher` (Haiku, two modes: design + impl) · `planner` (Opus, also writes skeleton specs) ·
+`infra-provisioner` (Opus) · `spec-author` (Opus, fills per-phase spec + fixtures) ·
+`implementer` (Opus, SCAFFOLD/FILL modes) · `test-author` (Opus, harness emitter) · `debugger` (Opus, isolated) ·
+`e2e-runner` (Opus, Playwright emitter) · `synthesizer` (Haiku)
 
 The main session is the orchestrator — it routes, it does not implement.
 
-## The loop (v2.1: TDD-first + human gates + coverage guards)
-
-Phases that add a public callable surface run test-first:
-`RESEARCH -> SCAFFOLD -> RED -> TEST REVIEW -> GREEN -> E2E -> FIX -> CLOSE`. The
-implementer writes interface stubs only; the `test-author` writes the suite blind
-against those stubs (it must collect cleanly and FAIL — the RED gate) and emits a
-`docs/test-plan-phase-<n>.md` with a mandatory "NOT covered / assumptions"
-section. **TEST REVIEW** is a human gate: you approve the test plan before the
-implementer fills to green — so "all tests passed but the core was broken" can't
-slip through silently. Pure infra/config/doc phases keep the direct
-`RESEARCH -> IMPLEMENT -> TEST` order (no TEST REVIEW — no public surface).
+## The loop (v2.3: adaptive to project type + spec-driven contract + upstream human gate)
+
+**Project flags (declared at `/overview`).** The grill asks your `project_type`
+(web app / desktop app / script / library / other) and what "shipped" means. From
+that it derives `infra_needed`, `e2e_kind` (browser / cli / http / library-api),
+`deploy_kind` (cloud-deploy / package-publish / install-run-verified / none), and
+which `knowledge_docs` to consult — all recorded in `docs/OVERVIEW.md`, never
+inferred mid-phase. Phase 0 (infra) exists only when `infra_needed`; the boundary
+run is selected by `e2e_kind`; the final phase completes `deploy_kind`.
+
+
+Phases that add a public callable surface run spec-first:
+`RESEARCH -> SPEC fill -> spec-staleness -> SPEC REVIEW -> SCAFFOLD -> RED -> spec-conformance -> GREEN -> boundary/E2E -> FIX -> CLOSE`.
+The reviewable, authoritative artifact is the **spec**, not the test. At `/overview`
+the planner enumerates the case *names* per phase (skeleton `docs/spec-phase-<n>.md`).
+At phase start the new `spec-author` fills them with concrete cases — real inputs,
+real expected outputs, matcher tokens for volatile fields — written to shared
+`fixtures/` files. **SPEC REVIEW** is a human gate that sits *upstream* (before any
+code): you confirm falsifiable claims in plain language ("empty order → 422
+EMPTY_ORDER"). Tests are then GENERATED from the locked spec rows (deep-equality +
+matcher tokens for `data`; Playwright from the descriptor for `ui`) loading the
+*same* fixtures — so a test physically cannot assert different values than the spec.
+`spec-conformance.sh` blocks GREEN until no `TBD` remains and every case-id is cited
+by a boundary test. This is the v2.2 fix for "both agents independently fabricated
+the same wrong contract from a one-line acceptance and the suite went green on a
+broken core." Pure infra/config/doc phases keep the direct
+`RESEARCH -> IMPLEMENT -> TEST` order (no spec, no SPEC REVIEW — no public surface).
 
 Frontend phases are detected by a **deterministic path match** (`has_frontend` +
 the frontend root, both set in `docs/OVERVIEW.md`): if a phase changes a file
@@ -107,37 +130,22 @@ Methodology lives in one place: the portable **`AGENTS.md`** at the repo root.
 
 |Tool          |What you get                                                                                          |
 |--------------|------------------------------------------------------------------------------------------------------|
-|**Claude Code** (full, reference)|commands, all 3 lifecycle hooks **with context injection**, named subagents, shared KB, `@AGENTS.md` import|
-|**Cursor** (full)|generated commands (`.cursor/commands/`), lifecycle hooks (`.cursor/hooks.json`: sessionStart / preCompact / subagentStop), methodology via a `.cursor/rules/` pointer to `AGENTS.md`|
-|**Other tools**|read `AGENTS.md` if they support the open standard; no generated adapters; not claimed as supported in v2.0|
-
-One canonical command body in `commands.src/<name>.md` generates both tools' command sets at install.
-
-**Cursor — verified against cursor.com/docs (June 2026):**
-- **sessionStart context injection: works.** Cursor's `sessionStart` hook accepts an
-  `additional_context` JSON output field injected into the conversation's initial
-  context. Cursor expects JSON (Claude injects raw stdout), so the shipped wiring
-  runs the shared body through `cursor-session-start.sh`, a thin JSON-envelope
-  wrapper. The hook is fire-and-forget (non-blocking).
-- **Named subagents: work natively.** Cursor reads `.claude/agents/*.md` directly
-  (documented Claude-compatibility path), with `/name` invocation and
-  description-based delegation — one set of role files serves both tools.
-  Caveat: `model: haiku/opus` tiers are Claude-specific; Cursor falls back to
-  `inherit`/a compatible model.
-- **Hook path resolution: project hooks run from the project root** (not
-  `.cursor/`), so the shipped wiring uses `bash .claude/hooks/<script>.sh`. Cursor
-  sets `CLAUDE_PROJECT_DIR` as a compatibility alias, so the shared scripts run
-  unchanged.
-- **preCompact is observational** in Cursor (cannot modify compaction); the
-  snapshot side-effect still runs, which is all the COMPRESS ritual needs.
-
-> Note: Cursor can also load `.claude/settings.json` hooks directly ("Third-party
-> skills" toggle). anpunkit does not rely on this — it requires a manual settings
-> toggle (silent no-op if forgotten) and would double-fire hooks alongside
-> `.cursor/hooks.json`. The explicit native wiring is the supported path.
-
-Codex is **not** a target in v2.0 (its repo-committed command path is deprecated
-home-dir custom-prompts with a divergent UX).
+|**Claude Code** (the supported target)|commands, all 3 lifecycle hooks **with context injection**, named subagents, shared KB, `@AGENTS.md` import|
+|**Other tools**|read `AGENTS.md` if they support the open standard; no generated adapters, no support claim|
+
+The canonical command bodies live in `commands.src/<name>.md`, copied to
+`.claude/commands/` at install. **Cursor support was dropped in v2.3** (§5.69) —
+the maintenance cost exceeded demand. v2.3 is Claude Code only.
+
+## Compression
+
+Output compression is a kit-native, always-on facility (`.claude/ref/compression.md`),
+not a skill and never model-invoked. Two profiles: `user` (human-facing, keeps the
+Auto-Clarity exception for security warnings, irreversible-action confirmations,
+multi-step sequences, and clarification requests) and `internal` (agent↔agent,
+harder). `AGENTS.md` declares `user`; every subagent prompt points at `internal`.
+Exact-output artifacts (fixtures, spec rows, generated tests) are exempted by
+structural gates in the emitter prompts.
 
 ## How each problem is solved
 
@@ -149,10 +157,10 @@ home-dir custom-prompts with a divergent UX).
 |Context rot during debugging               |`researcher` + `debugger` write full output to `docs/research/`, return only a summary + path|
 |Want orchestration                         |8 scoped subagents; `/phase` is the orchestrator routing them                                |
 |Handoff / memory keeps growing             |`synthesizer` + PreCompact hook compress and dedup                                           |
-|Azure auth friction per session            |`scripts/auth-setup.sh` — one token check, once per session                                  |
-|Infra created ad-hoc mid-phase             |`infra-provisioner` + Phase 0 — provisioned once, reviewed before apply                      |
-|Planning without domain knowledge          |design-researcher runs before planning; double grill absorbs findings                        |
-|Deployment not in the plan                 |planner always puts deploy task in last phase                                                |
+|Cloud auth friction per session            |liveness ritual recorded in INFRA.md `## AUTH` (Azure: `knowledge/azure.md`) — one check per session|
+|Infra created ad-hoc mid-phase             |`infra-provisioner` + Phase 0 when `infra_needed` — provisioned once, reviewed before apply  |
+|Planning without domain knowledge          |design-researcher runs before planning; consults matching `knowledge/*.md`; double grill absorbs findings|
+|Deployment not in the plan                 |planner always puts the `deploy_kind` completion task in the last phase                      |
 |No endpoint summary at project end         |final-phase close shows usage endpoints from docs/ENDPOINTS.md                               |
 |Re-discovering same gotchas across projects|`/store-wisdom` promotes findings to shared KB; researcher checks KB before web              |
 
@@ -160,14 +168,19 @@ home-dir custom-prompts with a divergent UX).
 
 - `docs/STATE.md` — current position, kept small (rewritten each phase)
 - `docs/ISSUES.md` — error log, deduped by synthesizer
-- `docs/PLAN.md` — vertical-slice phase plan (Phase 0 always first)
+- `docs/PLAN.md` — vertical-slice phase plan (Phase 0 first when `infra_needed`)
 - `docs/HISTORY.md` — one line per finished phase
 - `docs/OVERVIEW.md` — project scope, written after double-grill
 - `docs/DATAFLOW.md` — state-transition table per key object (grilled at /overview; drives CLOSE coverage gate)
-- `docs/INFRA.md` — Azure resource manifest + cost estimates (written by infra-provisioner)
+- `docs/spec-phase-<n>.md` — per-phase behavioral contract (skeleton at /overview, filled by spec-author; human-reviewed at SPEC REVIEW)
+- `fixtures/<case-id>-{input,expected,ui}.json` — shared by the spec row and the generated test harness (committed; part of the contract)
+- `tests/helpers/spec-assert.{py,ts}` — kit-versioned matcher-aware comparator (honors `<UUID>`, `<ISO8601>`, … tokens)
+- `docs/INFRA.md` — infra resource manifest + cost estimates (when `infra_needed`; written by infra-provisioner)
 - `docs/ENDPOINTS.md` — API/service endpoint catalogue (maintained by implementer)
 - `docs/.snapshots/` — pre-compact recovery markers (auto-pruned, gitignored)
-- `infra/` — Bicep templates (generated by infra-provisioner, committed to git)
+- `knowledge/webapp.md`, `knowledge/azure.md` — preinstalled matured practice + materializable templates
+- `.claude/ref/compression.md` — kit-native compression profiles (`user`, `internal`)
+- `infra/` — IaC templates (generated by infra-provisioner, committed to git)
 
 ## Shared Knowledge Base (optional)
 
@@ -205,8 +218,8 @@ See `docs/KB_GUIDE.md` in the anpunkit-kb repo (created by first `/store-wisdom`
 
 ```
 /overview                    once per project (design-research + double grill)
-/infra                       once per project (Phase 0) — after /overview
-scripts/auth-setup.sh        once per session (Azure projects)
+/infra                       once per project (Phase 0) — only when infra_needed
+<INFRA.md AUTH command>      once per session (infra projects; Azure: scripts/auth-setup.sh)
 /phase 1   ->  /synthesize  ->  /clear
 /phase 2   ->  /synthesize  ->  /clear
 ...
@@ -216,83 +229,50 @@ scripts/auth-setup.sh        once per session (Azure projects)
 # learned something worth keeping?  ->  /store-wisdom
 ```
 
-## Azure infrastructure (Phase 0)
+## Use-case knowledge (infra, E2E, deploy)
+
+The invariant core ships nothing use-case specific. Matured web/Azure practice
+lives in **preinstalled knowledge docs** that the `researcher` consults at RESEARCH
+when your declared `project_type` matches (recorded in OVERVIEW `knowledge_docs`):
 
-The kit treats Azure infra as **Phase 0** — provisioned once before any code
-phase starts, owned by the `infra-provisioner` subagent.
+- **`knowledge/webapp.md`** — browser E2E practice (Playwright, closed assert
+  vocabulary, screenshot evidence) plus the E2E stack ritual and the
+  `playwright.config.ts` / `e2e/global-setup.ts` / `docker-compose.test.yml` /
+  `scripts/e2e-stack.sh` templates, materialized into your project on demand.
+- **`knowledge/azure.md`** — the once-per-session auth ritual (`scripts/auth-setup.sh`
+  template), Entra/MSAL ROPC + MFA-excluded test account practice, and the Bicep /
+  `az` provisioning patterns (Key Vault, THB cost annotations, SEA region default).
 
-### Phase 0 flow
+### Infra (Phase 0, when `infra_needed`)
+
+Application project types (web app, desktop app, service) set `infra_needed: true`;
+scripts and libraries set it false and skip Phase 0 entirely. When present, Phase 0
+is provisioned once before any code phase, owned by `infra-provisioner`:
 
 ```
-/overview          # includes Phase 0 in PLAN.md automatically
-/infra             # generates Bicep -> what-if diff -> you review -> "go" -> apply
-                   # writes docs/INFRA.md (resource manifest + cost estimates)
+/overview          # declares infra_needed; includes Phase 0 in PLAN.md when true
+/infra             # generates IaC -> what-if diff -> you review -> "go" -> apply
+                   # writes docs/INFRA.md (resource manifest + cost estimates + ## AUTH)
                    # writes .env.test (generated, never fill manually)
                    # runs AUTH PROOF (every credential proven reusable headlessly)
 /phase 1           # PRE-FLIGHT checks Phase 0 is done before starting
 ```
 
-### Session startup (Azure projects)
-
-Run once per session before any Azure work:
-
-```bash
-scripts/auth-setup.sh
-```
-
-Checks your `az` token is fresh and the right subscription is active.
-Prompts `az login` only if stale. No credential storage — your account only.
-
-### What /infra does
-
-1. `infra-provisioner` reads `docs/OVERVIEW.md` for the system design
-1. Generates `infra/main.bicep` + per-service modules under `infra/modules/`
-1. Runs `az deployment what-if` — shows exactly what will be created
-1. **Stops and waits for your "go"** — nothing applied without your review
-1. Applies the deployment
-1. Writes `docs/INFRA.md` — resource IDs, endpoints, cost estimates (THB, SEA region)
-1. Generates `.env.test` from the manifest
-1. Runs the **AUTH PROOF** — proves every credential (Entra/MSAL + datasources) is obtainable headlessly twice in a row
-
-Re-run `/infra` any time infra drifts or a new resource is needed.
-Re-run `/infra regenerate-env` to refresh `.env.test` only.
-Re-run `/infra auth-proof` to re-prove credentials on demand.
-
-### Cost awareness
-
-`infra-provisioner` annotates every resource in `INFRA.md` with an estimated
-monthly cost. It uses production-appropriate SKUs by default — not artificially
-cheap dev tiers that need resizing before go-live.
-
-### E2E target
-
-`infra-provisioner` determines the E2E target from the system design:
-
-- **azure-deployed**: `E2E_STACK_EXTERNAL=1` — Playwright hits your deployed Azure app.
-- **local-docker**: Containers run the app, pointed at real Azure services.
-
-### Test data
-
-Seeding and cleanup are **deployment phase** concerns, not E2E concerns.
-`e2e-stack.sh` has no seed/cleanup commands.
-
-## End-to-end testing
-
-Three layers: unit/integration (mock suite), real API (`test-author`), and
-functional browser E2E (`e2e-runner`, Playwright).
+Cloud specifics (Azure `az`/Bicep commands, region/cost conventions, the session
+auth ritual) live in `knowledge/azure.md`, consulted by `infra-provisioner`.
 
-**Phase gate:** a frontend-touching phase closes only when the real API suite
-AND the browser E2E suite pass with screenshot evidence. Mock-green alone never closes a phase.
+### Boundary testing (per `e2e_kind`)
 
-**MSAL / Entra ID auth.** Browser E2E never drives the Microsoft login UI.
-`e2e/global-setup.ts` uses ROPC flow with a dedicated test account (MFA excluded
-via Conditional Access) to fetch a real token and inject it into the MSAL cache.
+The boundary run is selected by the phase's bound `e2e_kind`:
 
-**E2E setup (one-time per project):**
+- **browser** (frontend phases): `e2e-runner` emits Playwright from each `ui` case's
+  descriptor and captures a screenshot at every UI-existence assertion — on success
+  too — to a gitignored `docs/evidence/` dir. Stack ritual + templates:
+  `knowledge/webapp.md`.
+- **cli / http / library-api**: the phase's real-mode boundary suite runs against
+  the shipped outer surface, transcript captured as evidence.
 
-1. Run `/infra` — it generates `.env.test` automatically and runs the AUTH PROOF.
-1. Provision the Entra test user + Conditional Access MFA exclusion.
-1. `npm i -D @playwright/test && npx playwright install chromium`
+Mock-green alone never closes a phase.
 
 ## Windows / Git Bash
 

package/template/commands.src/infra.md

@@ -3,16 +3,20 @@ description: Provision or verify Azure infrastructure. Generates Bicep, shows wh
 argument-hint: [provision | verify | update <what changed> | regenerate-env | auth-proof]
 ---
 
-Caveman ULTRA mode. You are the ORCHESTRATOR.
+compression: user (.claude/ref/compression.md). You are the ORCHESTRATOR.
 
 Action: $ARGUMENTS (default: "provision" if INFRA.md missing, "verify" if present)
 
+Only meaningful when docs/OVERVIEW.md has `infra_needed: true`. If
+`infra_needed: false`, tell me this project has no infra phase and STOP.
+
 ---
 
 ## PRE-FLIGHT
 
-1. Check `az account show` — if it fails, STOP.
-   Tell me: "Run `scripts/auth-setup.sh` first."
+1. Confirm cloud CLI auth per the project's knowledge doc (Azure:
+   `knowledge/azure.md` ritual — `bash scripts/auth-setup.sh`; materialize it if
+   absent). If it fails, STOP and tell me the exact command to run.
 
 2. Determine mode from $ARGUMENTS or default logic.
 

package/template/commands.src/log-decision.md

@@ -3,7 +3,7 @@ description: Record an architectural decision in docs/DESIGN_LOG.md. Use only wh
 argument-hint: [what changed]
 ---
 
-Caveman ULTRA mode.
+compression: user (.claude/ref/compression.md).
 
 Append an architectural decision to docs/DESIGN_LOG.md. Change: $ARGUMENTS
 

package/template/commands.src/log-issue.md

@@ -3,7 +3,7 @@ description: Log an error to docs/ISSUES.md with root cause + solution, in the c
 argument-hint: [short error description]
 ---
 
-Caveman ULTRA mode.
+compression: user (.claude/ref/compression.md).
 
 Append an entry to docs/ISSUES.md. Error: $ARGUMENTS
 

package/template/commands.src/overview.md

@@ -2,7 +2,7 @@
 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.
+compression: user (.claude/ref/compression.md).
 
 Recommended: run from plan mode (Shift+Tab). Planning agents are read-only by
 tool grant; plan mode adds a read-only gate on the main session too. Optional.
@@ -16,11 +16,17 @@ Goal: stand up a fresh project workspace with a well-grounded plan.
 ### Round 1 — Initial grill
 
 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. ALSO establish:
+   Cover: project purpose, success criteria, external services, cloud/infra
+   services needed (type + sizing, if any), region, known constraints, unknowns.
+   ALSO establish:
+   - **project_type**: web app / desktop app / script / library / other. This
+     drives the deterministic flag derivation (step 6) and knowledge-doc
+     selection.
    - **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.
+   - **deploy meaning**: what does "done and shipped" mean for this project —
+     cloud deploy (where?), package publish (which registry?), verified
+     install/run instructions, or none (why)? This sets `deploy_kind`.
    Do not stop early. Do not write OVERVIEW.md yet.
 
 Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
@@ -86,11 +92,23 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
    - 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)
+   - Cloud/infra services section: every service with expected SKU (if any)
    - `has_frontend: true|false` and, if true, the frontend root path
    - Known risks / open questions (if any remain)
 
+   PROJECT FLAGS (hard rule 10 — declared once here, recorded verbatim, never
+   re-derived later):
+   - `project_type: web app|desktop app|script|library|other` (declared in round 1)
+   - `infra_needed: true|false` — derived: application types (web app, desktop
+     app, service) → true; script / library → false. Overridable here with a
+     stated reason.
+   - `e2e_kind: browser|cli|http|library-api` — derived: has_frontend → browser;
+     backend/API service → http; script → cli; library → library-api.
+   - `deploy_kind: cloud-deploy|package-publish|install-run-verified|none(<reason>)`
+     (from the round-1 "deploy meaning" answer).
+   - `knowledge_docs:` — derived list: web app or has_frontend → `knowledge/webapp.md`;
+     Azure services declared OR Azure cloud-deploy → `knowledge/azure.md`; else empty.
+
    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
@@ -112,13 +130,27 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 
 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.
+   - Start with Phase 0 (infra setup) as the first entry IFF `infra_needed: true`;
+     when `infra_needed: false` there is no Phase 0 — Phase 1 is the first entry.
+   - End with a final code phase whose deploy task completes `deploy_kind`
+     (cloud deploy / package publish / verified install-run / none-with-reason).
    - 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:
 ```
 
@@ -126,15 +158,18 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 
 phase: 0 (pending)
 completed: project bootstrapped — design research, research review, double grill (incl. data/state flow) done
-next: run /infra to provision Azure infrastructure
+next: <if infra_needed: "run /infra to provision infrastructure (Phase 0)"; else "run /phase 1">
 blocker: none
 
 ```
+   When `infra_needed: false`, set `phase: 1 (pending)` and the next line to
+   "run /phase 1".
 10. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
 
 11. Create empty docs/HISTORY.md.
 
-12. Create docs/INFRA.md from the template (populated by /infra).
+12. Create docs/INFRA.md from the template (populated by /infra). Skip when
+    `infra_needed: false`.
 
 13. Create docs/ENDPOINTS.md:
  ```
@@ -144,6 +179,13 @@ blocker: none
  ```
 
 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) and
-run the one-time AUTH PROOF before starting Phase 1."
+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 of the next step per `infra_needed`:
+- `infra_needed: true` → "Run `/infra` next to provision the environment (Phase 0)
+  and run the one-time AUTH PROOF before starting Phase 1."
+- `infra_needed: false` → "No infra phase — run `/phase 1` to start."