create-anpunkit 2.1.0 → 2.3.0

package/template/docs/DESIGN_LOG.md

@@ -17,6 +17,53 @@
 
 Newest first. One entry per architectural change. Appended by `/log-decision`.
 
+- **(v2.3)** — **Compression internalized + core/use-case separation + Cursor drop.**
+  Two streams. **Stream A:** the external `caveman` skill (vendored fallback +
+  "global-authoritative if installed" resolution + model-invoked triggers) becomes a
+  kit-native, single-source, always-on reference (`.claude/ref/compression.md`) with
+  two named profiles — `user` (human-facing, keeps the Auto-Clarity exception) and
+  `internal` (agent↔agent, harder). ~40 scattered "Caveman ULTRA mode" phrases
+  collapse to one-line profile pointers; exact-output artifacts are exempted by
+  structural gates in the `spec-author` / `test-author` / `e2e-runner` prompts.
+  **Stream B:** the invariant core (loop, gates, doc system, commands) is separated
+  from web/Azure practice, which becomes preinstalled knowledge docs
+  (`knowledge/webapp.md`, `knowledge/azure.md`) consulted deterministically by
+  `researcher` at RESEARCH. New OVERVIEW flags — `project_type`, `infra_needed`,
+  `e2e_kind`, `deploy_kind`, `knowledge_docs` — declared at `/overview`, bound
+  per-phase at RESEARCH: Phase 0 exists iff `infra_needed`; the boundary run is
+  selected by `e2e_kind`; the final phase completes `deploy_kind`. Cursor support is
+  hard-dropped (Claude Code only). New decision entries §5.57–§5.71. NEW files:
+  `.claude/ref/compression.md`, `knowledge/webapp.md`, `knowledge/azure.md`. REMOVED:
+  `.claude/skills/caveman/`, `.cursor/**`, `.claude/hooks/cursor-session-start.sh`,
+  and the installer tool-selection machinery. CUT from default install (embedded as
+  templates in the knowledge docs): `playwright.config.ts`, `e2e/`,
+  `docker-compose.test.yml`, `scripts/e2e-stack.sh`, `scripts/auth-setup.sh`.
+
+- **(v2.2)** — **Spec-driven behavioral contract.** Closes the v2.1 residual:
+  fabrication under a thin acceptance surface. In v2.1 a phase's whole contract was
+  a single `acceptance:` line; `implementer` and `test-author` each independently
+  elaborated it, and when both filled the same gap the same plausible-but-wrong way
+  the suite went green on a broken core — TEST REVIEW (review of *coverage*, after
+  RED) could not catch a faithful mapping to a *fabricated* criterion. The reframe:
+  the reviewable, authoritative artifact is the SPEC, not the test. New mechanism —
+  skeleton case-NAMES locked at `/overview` (planner) → per-phase concrete filling by
+  a new **`spec-author`** (real inputs/expecteds in shared `fixtures/`) → **SPEC
+  REVIEW** human gate UPSTREAM of code → tests GENERATED from the locked rows
+  (deep-equality + matcher tokens for `data`, Playwright-from-descriptor for `ui`),
+  sharing the same fixtures so a test cannot assert different values than the spec.
+  Two new orchestrator-procedure scripts (`spec-staleness.sh`, `spec-conformance.sh`)
+  replace the human TEST REVIEW gate. `test-author`/`e2e-runner` become harness
+  EMITTERS; `implementer` reads the filled spec as its contract (author ≠ implementer).
+  New decision entries §5.43–§5.56. New files: `.claude/agents/spec-author.md`,
+  `scripts/spec-staleness.sh`, `scripts/spec-conformance.sh`, `tests/helpers/
+  spec-assert.{py,ts}`, plus per-project `docs/spec-phase-<n>.md` + `fixtures/`.
+  REMOVED: the v2.1 human TEST REVIEW gate (humans no longer review tests).
+  NOTE: the v2.1 entries §5.33–§5.42 (TEST REVIEW gate, mandatory frontend E2E +
+  evidence, DATAFLOW coverage, datasource understanding, auth proof/liveness,
+  installer tool-selection) live in the v2.1 release bundle and the on-disk AGENTS.md
+  hard rules; they were never merged into this on-disk log (a hybrid file). The v2.2
+  decision numbers continue at §5.43 for continuity with the requirements doc.
+
 - **(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
@@ -178,11 +225,14 @@ Hard-stop at 3 forces either /unstuck (re-research) or human intervention.
 Subagent → orchestrator → user. A subagent that directly asks the user would
 fragment the conversation and make the orchestrator's state inconsistent.
 
-### 5.8 Skill vendoring is fallback-only
+### 5.8 Skill vendoring is fallback-only  *(superseded by §5.62, v2.3)*
 caveman and grill-me are vendored in `.claude/skills/` as fallback copies only.
 The global `~/.claude/skills/` copy is authoritative. The vendored copy is used
 only if the global is missing. This prevents the project copy from diverging
 from the user's customized global version.
+> **Superseded (v2.3, §5.62):** caveman is internalized to `.claude/ref/
+> compression.md`; grill-me becomes the sole authoritative source. The
+> "global-authoritative if installed" resolution rule is dropped entirely.
 
 ### 5.9 DESIGN_LOG.md is append-only
 History is never rewritten. Decisions that turn out to be wrong get a new entry
@@ -414,7 +464,11 @@ logic; called out for the upgrade smoke test).
 **Rejected:** clobbering reinstall; reimplementing setup.sh logic in Node (drift);
 imperative per-version migrations as the default.
 
-### 5.32 Multi-tool adapters — Claude Code + Cursor (v2.0)
+### 5.32 Multi-tool adapters — Claude Code + Cursor (v2.0)  *(reversed by §5.69, v2.3)*
+> **Reversed (v2.3, §5.69):** Cursor support is hard-dropped. The `.cursor/**`
+> tree, `cursor-session-start.sh`, and the installer tool-selection machinery are
+> removed; `commands.src/` now generates only `.claude/commands/`. Claude Code only.
+
 **Problem:** the kit was Claude-only; maintaining parallel per-tool command copies
 by hand would drift.
 
@@ -452,6 +506,304 @@ native wiring).
 
 ---
 
+> **Numbering note (v2.2).** §5.33–§5.42 are the v2.1 decisions (TEST REVIEW gate,
+> mandatory frontend E2E + evidence, DATAFLOW transition coverage, datasource
+> understanding, auth proof/liveness, installer tool-selection). They were recorded
+> in the v2.1 release bundle and are reflected in AGENTS.md's hard rules, but were
+> never merged into this on-disk log. v2.2 continues at §5.43 for continuity with the
+> v2.2 requirements doc rather than renumbering.
+
+### 5.43 Spec file is a per-phase artifact, not inline in PLAN.md (v2.2)
+**Problem:** a phase's whole behavioral contract was one `acceptance:` line; two
+agents independently elaborated it and could agree on the same wrong contract.
+**Decision:** `docs/spec-phase-<n>.md` is a new per-phase artifact; `PLAN.md`'s
+`acceptance:` stays a one-line summary, the spec is its concrete expansion. The spec
+is self-correlating: a GENERATED header transcludes that phase's `acceptance:` line +
+the in-scope `DATAFLOW.md` transition rows and embeds a staleness hash; only the
+example-case table is human-authored. **Rejected:** expanding `acceptance:` inline in
+PLAN.md — couples the contract to `/replan` churn, bloats PLAN, mixes phase-ordering
+review with concrete-behavior review.
+
+### 5.44 Two-layer baseline/delta — case-names up front, values per phase (v2.2)
+**Decision:** lock behavior in two passes. (1) Up-front case-NAME contract at
+`/overview`: for every DATAFLOW transition + every acceptance criterion, enumerate
+the case names (happy / each edge / each failure + error code), no values yet —
+skeleton spec files. (2) Per-phase concrete filling at `/phase` start (after
+RESEARCH, before SCAFFOLD): `spec-author` fills real payloads/outputs grounded in
+fresh research + the confirmed datasource baseline. **Rationale:** the only design
+that gives BOTH "complete requirements locked before implementation" (names up front)
+and "values grounded in real facts, not plan-time guesses" (per-phase fill). Mirrors
+the established baseline/delta shape (datasource understanding, DATAFLOW coverage).
+
+### 5.45 Skeleton→filled single file; "no unfilled stub" is the conformance invariant (v2.2)
+**Decision:** skeletons are generated at `/overview` (names + `TBD`); `spec-author`
+fills in-place. Invariant: no `TBD` may remain when `spec-conformance.sh` runs
+(between RED and GREEN). **Consequence:** a case that cannot be filled from research
+is escalated as UNDERSPEC / `CASE-SET-DIVERGENCE` BEFORE SCAFFOLD, not discovered at
+GREEN.
+
+### 5.46 Case structure: table row + boundary-typed fixture-ref (v2.2)
+**Decision:** each case is one row — `case-id | covers | boundary | input-ref |
+expected-ref | error-code | volatile`. `covers` = a DATAFLOW transition-id
+(convention `Object:from->to`, no new DATAFLOW column) or acceptance criterion-id
+(`ACC-<k>`). `boundary` ∈ {`data`,`ui`}. Refs point to `fixtures/<case-id>-*.json`
+(scalars may inline). **Key property:** the harness loads the SAME fixture files the
+spec row references — transcription from spec to test is STRUCTURAL, not honor-system;
+a test physically cannot assert different values than the spec.
+
+### 5.47 Boundary test is system-of-record per case; optional mock mirror (v2.2)
+**Decision:** every case has exactly one BOUNDARY test — `data`: real
+HTTP/CLI/message vs the running backend + real services (v2.1's "real API suite");
+`ui`: Playwright vs the deployed/local-docker target (v2.1's E2E). The boundary test
+is the phase gate; green mock alone never closes (rule 5 / §5.38 preserved). A mock
+mirror is optional, shares the fixture + comparator via `TEST_MODE`. "E2E" is
+generalized to *outer-boundary*, not browser-specific: on `has_frontend: false` all
+cases are `data` and `ui` rows are invalid.
+
+### 5.48 Human TEST REVIEW removed; assertion is generated deep-equality (v2.2)
+**Decision:** remove the v2.1 human TEST REVIEW gate. Humans never review tests.
+Tests are not authored — a harness generator emits a deep-equality assertion against
+`fixtures/<case-id>-expected.json` per case row. SPEC REVIEW (§5.50) is the
+human gate; it sits upstream (before SCAFFOLD), reviews concrete behavior in plain
+language, and is the correctness-bearing moment TEST REVIEW was not (wrong thing,
+wrong layer: TEST REVIEW reviewed coverage and asked humans to read assertions).
+
+### 5.49 Volatile fields use matcher tokens in the fixture (v2.2)
+**Decision:** volatile fields (generated IDs, timestamps, order, cursors) are matched
+by TYPE, not excluded. The expected fixture carries sentinels — `<UUID>`, `<ISO8601>`,
+`<ANY_STRING>`, `<ANY_NUMBER>`, `<UNORDERED>`, `<MATCHES:regex>`. The per-language
+comparator `tests/helpers/spec-assert.*` honors them. A token asserts PRESENCE +
+SHAPE, never "ignore this field" (a missing volatile field still fails). The
+comparator is bounded + kit-versioned (one impl per supported language); no
+per-project comparator code.
+
+### 5.50 SPEC REVIEW — per-phase human gate on concrete fillings (v2.2)
+**Decision:** after `spec-author` fills + `spec-staleness.sh` passes, the orchestrator
+surfaces filled cases as FALSIFIABLE CLAIMS; the human confirms/corrects. Rejection
+classification: wrong expected → fix row + fixture (no re-research); wrong input shape
+→ re-dispatch `spec-author`; new case OR contradicted case → hard re-entry (§5.52).
+Unskippable on TDD phases; absent on non-TDD. Replaces v2.1 human TEST REVIEW.
+
+### 5.51 Up-front case-name completeness folded into existing /overview approval (v2.2)
+**Decision:** the existing end-of-`/overview` approval (PLAN.md + DATAFLOW.md) is
+EXTENDED to confirm the cross-phase skeleton case-name set (per phase: covered
+transition/acceptance ids + enumerated case names, no values). One confirmation, one
+surface, no new gate — the names derive from the same PLAN + DATAFLOW being approved.
+
+### 5.52 Any case-set divergence at phase time → hard re-entry (v2.2)
+**Decision:** if phase-time RESEARCH reveals a case not enumerated up front, or one
+that contradicts an enumerated case (locked contract impossible), the phase STOPS.
+`spec-author` returns `CASE-SET-DIVERGENCE`; the human amends the up-front skeleton;
+re-confirms the amended case(s) + any case sharing their `covers` id (the staleness
+hash certifies the unchanged remainder — not re-read); `spec-author` re-fills from
+scratch. **Rationale:** AI writes code; the human owns the contract. No fold-forward,
+no AI amendment of the case-name set.
+
+### 5.53 Dedicated spec-author agent; author ≠ implementer invariant (v2.2)
+**Decision:** a new `spec-author` (Opus) fills the per-phase spec + fixtures after
+RESEARCH, before SPEC REVIEW; returns `CASE-SET-DIVERGENCE` when a case can't be
+filled from real facts or research reveals an unlisted branch. It is NOT
+`implementer`. The **author ≠ implementer** invariant replaces v2.1's test-author
+blindness invariant: `implementer` reads the filled spec as its contract (normal
+spec-driven development), `test-author` becomes a harness emitter (reads spec rows,
+generates the assertion harness, authors no assertions).
+
+### 5.54 UI boundary cases use generated Playwright; e2e-runner is an emitter (v2.2)
+**Decision:** for `ui` cases, `e2e-runner` stops authoring blind and EMITS a
+Playwright assertion from the case's `fixtures/<case-id>-ui.json` descriptor. The
+descriptor vocabulary is closed + kit-versioned: `visible`, `text-equals`, `enabled`,
+`count`. Screenshot-on-each-UI-existence-assertion (v2.1 §5.35) is retained as the
+visual backstop. `ui` cases have no mock mirror (the browser is the boundary). On
+`has_frontend: false`, `ui` rows are invalid.
+
+### 5.55 spec-staleness.sh + spec-conformance.sh as orchestrator-procedure scripts (v2.2)
+**Decision:** two new scripts, same idiom as `regression.sh` (`set -euo pipefail`,
+nonzero = loud fail). `spec-staleness.sh` re-hashes the current PLAN acceptance line +
+in-scope DATAFLOW rows and compares to the spec's embedded header hash (`stamp`
+subcommand embeds it at `/overview`/regenerate; default `check` compares); runs after
+SPEC fill + at SPEC REVIEW entry. `spec-conformance.sh` asserts no `TBD` remains and
+every case-id is cited by a boundary test (`# spec: <case-id>`); runs between RED and
+GREEN, replacing the human TEST REVIEW gate. Both port to Cursor for free (same
+`/phase` body, same bash scripts — no new hook wiring). **Design choice (impl):**
+hashing lives ONLY in the script (a `stamp` subcommand), not duplicated in agent
+prompts; transition-ids are derived (`Object:from->to`) so DATAFLOW needs no new column.
+
+### 5.56 Rule 14 re-seamed: transition→case reachability; conformance owns case→test (v2.2)
+**Decision:** v2.1 rule 14 (DATAFLOW transition coverage) is re-seamed. New
+responsibility: every reachable DATAFLOW transition must have ≥1 FILLED CASE in
+`docs/spec-phase-<n>.md` (was: ≥1 test in `tests/regression/`). Reachability judgment
+unchanged (orchestrator decides at CLOSE; unreachable list PENDING; all live by final
+phase or FAIL HARD). The case→test half moves to `spec-conformance.sh` (every case-id
+cited by a boundary test, which by placement convention lands in `tests/regression/`).
+The full guarantee is preserved by the chain: reachable transition → filled case
+(rule 14) → cited boundary test (conformance) → regression corpus (placement). The
+ENDPOINTS coverage gate is unchanged and orthogonal (endpoint-keyed vs behavior-keyed).
+
+**Numbering reconciliation (v2.2).** The requirements doc's hard-rule table labeled
+new rules 12–16, but its own "Non-changes" section retains the frontend-E2E (old 13),
+datasource (old 15) and auth (old 16) rules — so the table is illustrative, not literal.
+AGENTS.md realizes a coherent set: rule **12** = SPEC REVIEW (reuses the slot freed by
+the removed TEST REVIEW); rule **14** = re-seamed DATAFLOW (kept in place); rules
+**13/15/16** keep their v2.1 meanings (frontend E2E / datasource / auth); the remaining
+new rules append as **17** (spec staleness), **18** (spec conformance), **19** (author ≠
+implementer). This preserves every existing `hard rule N` cross-reference except 12.
+
+### 5.57 Compression rules: standalone kit-native reference file (v2.3)
+**Decision:** compression rules live in exactly one kit-native reference file,
+`.claude/ref/compression.md` (replaces the vendored `caveman` skill). AGENTS.md and
+every crafted subagent prompt POINT to it; none restate the rules. Not placed under
+`.claude/skills/` — no description/trigger surface, so §5.61 is satisfied
+structurally, not by discipline.
+**Rejected:** rules inside AGENTS.md (subagents don't inherit it — they run their own
+crafted prompts by design); rules duplicated per prompt (drift).
+
+### 5.58 Two named compression profiles (v2.3)
+**Decision:** `user` (human-facing; keeps the Auto-Clarity exception — security
+warnings, irreversible-action confirmations, multi-step sequences, clarification
+requests) and `internal` (agent→agent; harder compression, no clarity exception).
+**Rejected:** one rule set with a conditional exception (implicit, weaker than a named
+structural declaration).
+
+### 5.59 Invocation sites collapse to profile pointers (v2.3)
+**Decision:** ~40 "Caveman ULTRA mode" phrases rewrite to a one-line profile pointer
+per prompt — subagents `compression: internal (.claude/ref/compression.md).`, commands
+`compression: user (…)`; AGENTS.md declares the `user` directive; the SessionStart hook
+reminder references the profile system.
+**Rejected:** outright deletion (breaks coverage — no inheritance); keeping full phrases
+(redundant, drift-prone).
+
+### 5.60 Positive artifact exemption as structural gate (v2.3)
+**Decision:** exact-output artifacts (RED harness assertions, spec-author contract
+output, fixtures, emitted Playwright, `# spec:`/`// spec:` citations, quoted errors)
+are exempted from compression via a positive structural gate declared in the
+`spec-author`, `test-author`, and `e2e-runner` prompts — not a rule inside the
+reference file. Compression is always-on, so exemption must be explicit at the artifact
+boundary.
+**Rejected:** exemption as a rule in the reference file (mixes concerns); inline prose
+per agent (non-structural, unverifiable).
+
+### 5.61 Model-invoked compression triggers killed (v2.3)
+**Decision:** the skill description triggers ("caveman mode", "be brief", `/caveman`)
+are deleted. Compression exists only as an always-on directive + profile pointers.
+Mandatory behavior is never model-invoked.
+
+### 5.62 grill-me vendored as sole source (v2.3)
+**Decision:** the vendored `grill-me` copy is authoritative; the "global-authoritative
+if installed" resolution rule is dropped entirely (it existed to serve two external
+skills; caveman's internalization leaves one consumer, which does not justify a
+resolution mechanism). §5.8 is superseded by this.
+**Rejected:** keeping the resolution rule for one consumer (dead mechanism).
+
+### 5.63 User freedom = composition, not enforcement (v2.3)
+**Decision:** users choose use case and modules; every installed gate stays HARD. No
+config to soften gates to warnings. Non-agent-behavior files (templates, scaffold,
+infra scripts) must be use-case-agnostic.
+**Rejected:** gate-softening config (a soft gate is a discipline rule; discipline rules
+are ruled out — "worry-free or fail hard").
+
+### 5.64 LCD core + matured practice as preinstalled knowledge docs (v2.3)
+**Decision:** the core ships nothing use-case-specific. Matured practices become
+preinstalled knowledge docs — `knowledge/webapp.md`, `knowledge/azure.md` — consulted
+by `researcher` (new STEP 0.5) at RESEARCH when the declared use case matches. Branch-
+only reference via pointer, loaded only when the branch triggers; reuses existing
+machinery (researcher already consults `research/INDEX.md` + KB snapshot). Selection is
+a deterministic table in `commands.src/overview.md`, recorded as OVERVIEW
+`knowledge_docs:` — never researcher-inferred (§5.66).
+**Rejected:** project-type scaffolds at install (designs N scaffolds upfront, guesses at
+demand); pure LCD without knowledge docs (guts the "ready-made" value users praised).
+
+### 5.65 Adaptive loop: RESEARCH binds E2E_KIND / DEPLOY_KIND (v2.3)
+**Decision:** the TDD APPLICABILITY check at RESEARCH is extended to bind two further
+per-phase values, same idiom as `TDD_PHASE`: `E2E_KIND` (browser via Playwright, CLI
+invocation, HTTP, library public API — generalizes v2.2's browser-specific boundary
+concept to outer-boundary) and, on the final phase, `DEPLOY_KIND` confirmation. "Last
+phase always includes deployment" is re-worded to "last phase always completes
+DEPLOY_KIND."
+**Realization (ordering split):** §5.65's literal "RESEARCH sets the flags" cannot hold
+for `INFRA_NEEDED` because `/phase` PRE-FLIGHT (which blocks on Phase 0) runs BEFORE
+RESEARCH. Resolved by splitting DECLARATION from BINDING: the project-level facts
+(`project_type`, `infra_needed`, `e2e_kind` baseline, `deploy_kind`, `knowledge_docs`)
+are declared at `/overview` and recorded in OVERVIEW.md (same idiom as `has_frontend`),
+where PRE-FLIGHT can read them; RESEARCH does the per-phase binding (effective
+`E2E_KIND` = browser iff frontend phase else baseline; `DEPLOY_KIND` re-confirm on final
+phase).
+**Realization (browser-only dispatch):** `e2e-runner` stays a Playwright emitter,
+dispatched only when the bound `E2E_KIND` is `browser`; for cli/http/library-api the
+generalized rule 13 is satisfied by `test-author`'s real-mode boundary suite against the
+outer surface, with its transcript captured as evidence — no separate shipped-artifact
+runner.
+**Rejected:** dropping deploy/E2E from the core loop (weakens the completeness
+guarantee); a universal outer-boundary emitter for all kinds (more prompt surface than
+the real-mode suite already provides).
+
+### 5.66 Project type declared at /overview (v2.3)
+**Decision:** the `/overview` grill asks `project_type` (web app / desktop app / script
+/ library / other). The answer is recorded in `docs/OVERVIEW.md` (alongside
+`has_frontend` + frontend root). `researcher` reads it to select knowledge docs;
+RESEARCH uses it (via the derived flags) to shape the loop.
+**Rejected:** researcher infers type from description (a model-invoked trigger for
+mandatory behavior — the pattern §5.61 kills).
+
+### 5.67 Minimal core cut line (v2.3)
+**Decision:** default install ships `AGENTS.md`, hooks, slash commands, agent prompts,
+the doc system (STATE/ISSUES/synthesizer/snapshots), knowledge docs, gate scripts. Cut
+from default install: `playwright.config.ts`, `e2e/`, `docker-compose.test.yml`,
+`scripts/e2e-stack.sh`, `scripts/auth-setup.sh`. Cut items are NOT deleted from the kit
+— they are embedded as fenced templates in `knowledge/webapp.md` / `knowledge/azure.md`
+and materialized per-project on demand (then user-owned, like `fixtures/`). Chosen over
+a non-installed templates dir, which would need new manifest/setup.sh gating machinery
+right after the Cursor gating was removed.
+**Retention constraint (user feedback #4):** doc auto-update + slash commands survive
+untouched in the minimal core.
+**Rejected:** interactive module picker at install (defer until real packs exist).
+
+### 5.68 Infra-provisioner conditional; Azure → knowledge doc (v2.3)
+**Decision:** `infra-provisioner` stays in the kit, prompt generalized (Azure specifics
+— Bicep, `az`, Entra/MSAL, THB costs, Key Vault — move to `knowledge/azure.md`). The
+`infra_needed` flag (declared at `/overview`: application types → true; script/library →
+false) gates Phase 0 dispatch. The SessionStart Azure reminder line and `auth-setup.sh`
+leave core; the Azure knowledge doc reintroduces the auth ritual (materializable
+`scripts/auth-setup.sh` template) when Azure is in play, and the project's liveness
+command is recorded in `docs/INFRA.md ## AUTH` so `/phase` PRE-FLIGHT stays generic.
+Old hard rule 10 (Azure auth once-per-session) moves to `knowledge/azure.md`; its slot
+is repurposed for the new deterministic-flags rule (zero renumbering — all `hard rule N`
+cross-references keep their numbers).
+**Rejected:** dropping infra-provisioner from core (loses mandatory coverage for
+application use cases); keeping the Azure-fitted prompt (violates §5.63); renumbering the
+hard rules (needless churn — rules 1–19 are contiguous, the slot repurposes cleanly).
+
+### 5.69 Cursor hard drop (v2.3)
+**Decision:** delete `.cursor/hooks.json`, `.cursor/commands/` generation, `.cursor/
+rules/` pointer, Cursor sections in README/docs, `cursor-session-start.sh`, and the
+dual-tool wiring in `setup.sh` + `create-anpunkit` (the whole `--tools`/`--add-tool`/
+`anpunkit-tools.json` tool-selection machinery, dead once one tool remains). README
+states "Claude Code only." A deliberate reversal of the v2.x Cursor-parity investment
+(v2.2 explicitly maintained parity): maintenance cost exceeds demand per user feedback.
+§5.32 (installer tool selection) is reversed by this.
+**Rejected:** soft drop with a "portable if you re-wire" note (half-promise, support
+burden).
+
+### 5.70 spec-author / test-author tool grants settled (v2.3, v2.2 carry-over)
+**Decision:** `spec-author` and `test-author` are granted `Read, Grep, Glob, Write,
+Bash` — deliberately NO `Edit`. `spec-author` authors fresh spec rows and fixtures
+(Write), never patches source; at SPEC REVIEW a "wrong expected" correction is applied
+by the ORCHESTRATOR patching the fixture directly (`phase.md §3`), not by re-granting
+`spec-author` edit rights. Recorded here to close the v2.2 carry-over.
+**Rejected:** granting `Edit` for in-place fixture patches (blurs author ≠ implementer,
+§5.53; the orchestrator-patch path already covers it).
+
+### 5.71 fixtures/ committed, never gitignored (v2.3, v2.2 carry-over)
+**Decision:** `fixtures/<case-id>-{input,expected,ui}.json` are COMMITTED — they are the
+behavioral contract that both the spec row and the generated test harness load
+(transcription is structural, not honor-system). Deliberate contrast with
+`docs/evidence/`, `docs/research/*.md`, `.env.test`, `docs/.snapshots/`, and
+`docs/.kb-snapshot.md`, which ARE gitignored. `.gitignore` therefore must NOT list
+`fixtures/`. Recorded here to close the v2.2 carry-over.
+**Rejected:** gitignoring fixtures (would break the contract-load guarantee — the test
+would have no expected values to assert against on a fresh checkout).
+
+---
+
 ## 6. Current file inventory
 ```
 
@@ -542,6 +894,49 @@ create-anpunkit/                   npx package (package.json, bin/cli.js, build.
 ownership taxonomy, adapter generation, idempotent JSON hook merge, VERIFY,
 backup, `--dry-run`).
 
+### v2.2 additions to the inventory
+
+```
+.claude/agents/spec-author.md      NEW — fills per-phase spec + fixtures (Opus); author ≠ implementer
+scripts/spec-staleness.sh          NEW — stamp/check the spec header hash vs PLAN+DATAFLOW (rule 17)
+scripts/spec-conformance.sh        NEW — no-TBD + every case-id cited by a boundary test (rule 18)
+tests/helpers/spec-assert.py       NEW — kit comparator (matcher tokens), Python
+tests/helpers/spec-assert.ts       NEW — kit comparator (matcher tokens), TS/JS
+docs/spec-phase-<n>.md             NEW per-project — skeleton at /overview, filled per phase (committed)
+fixtures/<case-id>-*.json          NEW per-project — shared by spec row + generated harness (committed)
+```
+
+Role deltas: `planner` also writes skeleton specs; `test-author` + `e2e-runner`
+become harness EMITTERS (generate from spec rows, author no assertions);
+`implementer` FILL reads the filled spec as its contract. `.gitattributes` gains
+`*.py text eol=lf` (the kit now ships a Python comparator). REMOVED: the v2.1 human
+TEST REVIEW gate + the `docs/test-plan-phase-<n>.md` artifact.
+
+### v2.3 changes to the inventory
+
+```
+.claude/ref/compression.md         NEW — kit-native compression profiles (user, internal); single source
+knowledge/webapp.md                NEW — matured web-app practice + browser-E2E stack templates
+knowledge/azure.md                 NEW — matured Azure practice + auth-ritual/provisioning templates
+.claude/skills/caveman/            REMOVED — internalized to .claude/ref/compression.md
+.cursor/                           REMOVED — hooks.json, rules/anpunkit.md, commands/ (Cursor dropped, §5.69)
+.claude/hooks/cursor-session-start.sh  REMOVED — Cursor JSON-envelope wrapper
+.claude/anpunkit-tools.json        REMOVED (per-project) — installer tool-selection machinery gone
+playwright.config.ts               CUT from default install — now a template in knowledge/webapp.md
+e2e/global-setup.ts                CUT — template in knowledge/webapp.md
+docker-compose.test.yml            CUT — template in knowledge/webapp.md
+scripts/e2e-stack.sh               CUT — template in knowledge/webapp.md
+scripts/auth-setup.sh              CUT — template in knowledge/azure.md
+```
+
+Role deltas (v2.3): `researcher` gains STEP 0.5 (consult OVERVIEW `knowledge_docs`
+before web search); `infra-provisioner` generalized (cloud specifics → knowledge/
+azure.md, dispatched only when `infra_needed`); `planner` Phase-0-conditional +
+`deploy_kind` completion; `e2e-runner` = browser E2E_KIND emitter. `commands.src/`
+now generates only `.claude/commands/`. Hard rule 10 repurposed (Azure auth →
+knowledge/azure.md; new slot = deterministic flags); rules 8/13/16 generalized in
+place; rules stay 1–19 contiguous.
+
 ## 7. How each original problem maps to its fix
 
 | Problem | Fix |
@@ -552,7 +947,7 @@ backup, `--dry-run`).
 | 4 context rot in debug | `debugger` isolated context + writes noise to file |
 | 5 want orchestration | 8 scoped subagents; `/phase` orchestrates them |
 | 6 handoff bloat | `synthesizer` + PreCompact hook; HISTORY.md for long log |
-| 7 Azure auth friction + infra ad-hoc | `auth-setup.sh` + `infra-provisioner` Phase 0 |
+| 7 cloud auth friction + infra ad-hoc | INFRA.md `## AUTH` liveness ritual (Azure: `knowledge/azure.md`) + `infra-provisioner` Phase 0 when `infra_needed` |
 | 8 re-discovering same gotchas across projects | KB snapshot at session start; researcher checks before web; `/store-wisdom` promotes findings |
 
 ---
@@ -560,9 +955,11 @@ backup, `--dry-run`).
 ## 8. Known gaps & template placeholders
 
 1. `docker-compose.test.yml` — build contexts and ports are TEMPLATE values.
+   (v2.3: now a fenced template in `knowledge/webapp.md`, materialized per project.)
 2. `e2e/global-setup.ts` — MSAL cache-key shape is a stub; adjust for app's
-   `@azure/msal-browser` version/config.
-3. caveman vendored copy is the base version, not the user's ULTRA variant.
+   `@azure/msal-browser` version/config. (v2.3: template in `knowledge/webapp.md`.)
+3. *(resolved v2.3, §5.57)* caveman is now kit-native and single-source
+   (`.claude/ref/compression.md`) — there is no vendored-vs-user-variant divergence.
 4. Visual-regression testing — explicit non-goal.
 5. Agent Teams / cross-session parallelism — deferred.
 6. SessionEnd guard hook — discussed, not built.
@@ -587,13 +984,21 @@ backup, `--dry-run`).
 4. The phase gate is a REAL test. A mock suite never closes a phase.
 5. Noisy work writes full output to `docs/research/` and returns only
    terse summary + path — keeps the orchestrator context clean.
-6. Tests are written blind — this is the unbiased-test guarantee.
-7. Never script the Microsoft login UI.
+6. The behavioral contract is the human-approved SPEC; tests are GENERATED from its
+   case rows against shared fixtures (author ≠ implementer). This is the v2.2
+   unbiased-test guarantee — it replaces v2.1's "tests written blind" (the spec
+   fixtures are authored before code, so the contract can't be shaped to an impl).
+   (Non-TDD phases keep blind-from-acceptance tests — no spec to drive them.)
+7. Boundary auth uses a dedicated headless test credential; never script an
+   interactive login UI (Microsoft/Entra specifics: `knowledge/azure.md`). (v2.3)
 8. Fail loud, never silent — especially hook wiring.
 9. Honest failure classification — environment issues never burn the debug budget.
-10. Azure infra is Phase 0: provisioned once, reviewed before apply, recorded in INFRA.md.
+10. Infra is Phase 0 when `INFRA_NEEDED`: provisioned once, reviewed before apply,
+    recorded in INFRA.md. (v2.3: conditional on the declared use case.)
 11. Plan before code: design-research + double grill before OVERVIEW.md is written.
     The planner must never design phases against unverified assumptions.
-12. Deployment is always in the last phase — never omitted, never a separate phase.
+12. The last phase always completes `DEPLOY_KIND` — cloud deploy, package publish, or
+    verified install/run — never omitted (only `none` with a recorded reason), never a
+    separate phase. (v2.3: generalized from "deployment".)
 13. The shared KB is human-gated at both ends: you approve before push (/store-wisdom),
     and findings are static within a session (KB snapshot). The KB never writes itself.

package/template/knowledge/azure.md

@@ -0,0 +1,161 @@
+# knowledge/azure.md — matured Azure practice (preinstalled)
+
+> **What this file is.** Use-case knowledge for Azure-deployed projects,
+> consulted by `researcher` (STEP 0.5) when `knowledge/azure.md` appears in
+> the `knowledge_docs:` list of `docs/OVERVIEW.md`. Selection is deterministic
+> — declared at `/overview`, never inferred (hard rule 10).
+>
+> **Templates below are materialized per-project** — copied to the stated path
+> the first time the phase work needs them. Once materialized they are
+> user-owned project files.
+
+## Session auth ritual (was core hard rule 10, v2.1–v2.2)
+
+**Azure project? Run `scripts/auth-setup.sh` ONCE per session before any Azure
+work. Never debug an auth error without checking this first.**
+
+- Materialize the template below to `scripts/auth-setup.sh` at Phase 0.
+- `/infra` records the project's liveness command in `docs/INFRA.md` under
+  `## AUTH` — for Azure that command is `bash scripts/auth-setup.sh` — so the
+  `/phase` PRE-FLIGHT auth-liveness gate (hard rule 16) knows what to run.
+- An expired `az` token mid-session looks like a resource failure. It is not a
+  bug: re-run the ritual, then retry.
+
+## Entra / MSAL practice
+
+- E2E auth = ROPC (resource-owner password credential) with a **dedicated test
+  account excluded from MFA via Conditional Access**. NEVER script the
+  Microsoft login UI (hard rule 8's Azure concretes).
+- Requirements on the app registration: ROPC enabled; test user exists; MFA
+  exclusion applied. The ROPC token-fetch template lives in
+  `knowledge/webapp.md` (`e2e/global-setup.ts`).
+- AUTH PROOF (hard rule 16): the Entra/MSAL app login must be obtainable
+  headlessly TWICE IN A ROW (prime + cached/refresh reuse) with zero prompts,
+  alongside every external datasource credential (Azure SQL, Tableau, …).
+- Failure alias: **AZURE UNAVAILABLE** ≙ SERVICE UNAVAILABLE (hard rule 7) —
+  outage/throttle/expired auth, not a bug, no debug budget.
+
+## Provisioning practice (infra-provisioner, Azure mode)
+
+IaC = Bicep, committed to `infra/` (audit trail):
+
+- `infra/main.bicep` — top-level deployment
+- `infra/modules/<service>.bicep` — one module per service type
+- `infra/params.json` — parameters (committed; no secrets in it)
+
+Bicep rules:
+
+- All resource names as parameters with defaults
+- All secrets written to Key Vault, not hardcoded
+- Tags on every resource: `project`, `environment`, `managedBy: anpunkit`
+- Cost comment on every resource: `// est. cost: <THB/month>`
+- Production sizing by default; region default: Southeast Asia
+- Naming convention default: `<project-short>-<resource-type>-<env>`
+- No hardcoded subscription/tenant IDs
+
+Commands:
+
+- What-if (NEVER skip, human reviews before apply):
+  `az deployment group what-if --resource-group <rg> --template-file infra/main.bicep --parameters @infra/params.json`
+  (new RG: `az deployment sub what-if --location <region> --template-file infra/main.bicep`)
+- Apply (only after human APPROVED):
+  `az deployment group create --resource-group <rg> --template-file infra/main.bicep --parameters @infra/params.json`
+- Verify: `az resource show --ids <resource-id>` per resource; SKU match;
+  Key Vault secrets present by name.
+
+### `docs/INFRA.md` Azure sections (template)
+
+```markdown
+## Azure environment
+- Subscription: <name> (<id>)
+- Resource group: <name>
+- Region: <location>
+
+## Entra / MSAL
+- Tenant ID: <value>
+- App Client ID: <value>
+- ROPC enabled: yes/no/check-manually
+- Test user: <upn or "not yet created">
+- Conditional Access MFA exclusion: <yes/pending>
+
+## AUTH
+- liveness command: bash scripts/auth-setup.sh
+
+## Cost summary
+| Resource | SKU | Est. THB/month |
+|---|---|---|
+| **Total** | | **~X THB/month** |
+```
+
+### `.env.test` Azure variable set
+
+```bash
+# .env.test — generated by infra-provisioner
+E2E_TENANT_ID=<from INFRA.md>
+E2E_CLIENT_ID=<from INFRA.md>
+E2E_TEST_USER=<from INFRA.md or "FILL_IN">
+E2E_TEST_PASSWORD=<fetch from Key Vault>
+E2E_SCOPE=api://<client-id>/.default
+E2E_SQL_SERVER=<from INFRA.md>
+E2E_SQL_DB=<from INFRA.md>
+E2E_SQL_USER=<from INFRA.md or "FILL_IN">
+E2E_SQL_PASSWORD=<fetch from Key Vault>
+E2E_BASE_URL=<deployed app URL or http://localhost:8080>
+E2E_STACK_EXTERNAL=<1 if azure-deployed, empty if local Docker>
+```
+
+---
+
+## Templates
+
+### `scripts/auth-setup.sh` — materialize to `scripts/`
+
+```bash
+#!/usr/bin/env bash
+# scripts/auth-setup.sh — verify Azure CLI session is ready.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+ok()   { printf "${GREEN}  OK${NC}  %s\n" "$1"; }
+warn() { printf "${YELLOW} WARN${NC} %s\n" "$1"; }
+fail() { printf "${RED} FAIL${NC} %s\n" "$1"; }
+
+echo ""
+echo "=== Azure session check ==="
+echo ""
+
+if ! command -v az >/dev/null 2>&1; then
+  fail "az CLI not found. Install from https://learn.microsoft.com/cli/azure/install-azure-cli"
+  exit 1
+fi
+AZ_VER=$(az version --query '"azure-cli"' -o tsv 2>/dev/null || echo "unknown")
+ok "az CLI present (version: ${AZ_VER})"
+
+ACCOUNT_JSON=$(az account show 2>/dev/null || true)
+if [ -z "$ACCOUNT_JSON" ]; then
+  warn "Not logged in. Running az login..."
+  az login
+  ACCOUNT_JSON=$(az account show 2>/dev/null || true)
+fi
+
+if [ -z "$ACCOUNT_JSON" ]; then
+  fail "az login failed or was cancelled."
+  exit 1
+fi
+
+SUB_NAME=$(echo "$ACCOUNT_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin)['name'])" 2>/dev/null || echo "unknown")
+SUB_ID=$(echo "$ACCOUNT_JSON"   | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])"   2>/dev/null || echo "unknown")
+ok "Logged in — subscription: ${SUB_NAME} (${SUB_ID})"
+
+# Token freshness check
+TOKEN_EXP=$(az account get-access-token --query expiresOn -o tsv 2>/dev/null || echo "")
+if [ -n "$TOKEN_EXP" ]; then
+  ok "Token valid until: ${TOKEN_EXP}"
+else
+  warn "Could not determine token expiry — may need re-login during session."
+fi
+
+echo ""
+echo "Azure session ready. You can now run /infra or Azure-dependent phases."
+```