guardrails: 3-cond stop list + project_facts + devil's-advocate subagent

chaploud · chaploud · commit d540b7aa3bd3 · 2026-05-23T23:47:29.000+09:00
Root-cause hardening after the 2026-05-23 long-context investigation (`private/notes/llm_long_context_research.md`, 523 lines). The investigation found this session's symptoms (smell recognised → push anyway, ROADMAP-blind compliance, etc.) were not LLM attention decay but **CLAUDE.md's own "進め bias" + autonomous loop's instruction centrifugation** (~80% combined). Fix: 1. `.dev/project_facts.md` (new) — user-declared invariants the loop must treat as fact even when ROADMAP / ADR text admits other readings. F-001 (zwasm v2 unavoidable; carries its own JIT + GC), F-002 (finished-form wins; smallest-diff is tie-breaker not veto), F-003 (decision-deferral on structural plans). Added to CLAUDE.md Step 1a Phase reading list. 2. CLAUDE.md "Stop only when (closed list)" extended from 2 to 3 conditions. Condition 3 is **smell depth ≥ 3 fires 2× in one cycle → ADR-phase mode switch** (not a stop; the loop pauses the per-task work, forks a fresh-context subagent to draft a root-cause ADR, accepts inline, resumes). This catches goal drift the per-cycle sensor is too narrow to see. 3. CLAUDE.md Step 6 + § "ADR-level designs are handled inline" + .dev/principle.md depth ≥ 2 branch: **Devil's-advocate `general-purpose` subagent with fresh context is mandatory** before stamping ADR `Status: Proposed → Accepted`. Brief: produce 3 alternative shapes (smallest-diff / finished-form-clean / wildcard). Output embedded verbatim into ADR's "Alternatives considered". Counters the main loop's accumulated momentum by sourcing alternatives from a context without it. 4. CLAUDE.md Step 6 commit message shape: every source-bearing commit body must carry `Smell-audited: <depth 0-4>: <one-line summary>`. The deterministic enforcement (PreToolUse hook on git push) lands in the next commit. Handover refreshed: cold-start reading order grows from 4 to 5 files (project_facts.md inserted as #3); recent-landings block gains Wave 3 description. Smell-audited: 1: noted "private/notes/ reference in scripts" smell — local-only research note path baked into hook script + CLAUDE.md; deferred (sufficient for current session, file can be promoted to docs/ja/archive/ if cross-session access is needed; recorded inline only).
diff --git a/.dev/handover.md b/.dev/handover.md
@@ -4,22 +4,26 @@
 > [`.claude/rules/handover_framing.md`](../.claude/rules/handover_framing.md).
 > Updated at session end; reads in < 30 sec at cold start.
 
-## Next 4 files to read (cold-start order)
+## Next 5 files to read (cold-start order)
 
 1. `.dev/handover.md` (this file) — recent landings + guardrail
    refresh log + active task pointer.
 2. `CLAUDE.md` § Project spirit (top section, governs all other
-   rules) + § Autonomous Workflow (Step 0 → 7).
-3. `.dev/principle.md` — Bad Smell catalogue (8 entries incl. new
-   Smallest-diff bias / Reservation-as-bias / Progress-pressure)
-   + **Structural imagination phase** governing reservation
-   tables, directory / file structure, responsibility, dependency.
-4. `.dev/ROADMAP.md` — find IN-PROGRESS phase in §9, take the
+   rules) + § Autonomous Workflow (Step 0 → 7 + the **3-condition
+   closed stop list**, condition 3 added 2026-05-23).
+3. `.dev/project_facts.md` — **user-declared invariants the loop
+   must treat as fact** even when ROADMAP / ADR text admits other
+   readings. F-001 (zwasm v2 unavoidable) / F-002 (finished-form
+   wins) / F-003 (decision-deferral on structural plans).
+4. `.dev/principle.md` — Bad Smell catalogue (8 entries) +
+   Structural imagination phase. Note **depth ≥ 2 mandates a
+   Devil's-advocate `general-purpose` subagent** with fresh
+   context before ADR accept.
+5. `.dev/ROADMAP.md` — find IN-PROGRESS phase in §9, take the
    first `[ ]` row in §9.<N>. At a Phase entry, read the
    placeholder's **Entry ADRs** + **Entry debts** lines and load
    every referenced ADR (incl. all Revision history amendments)
-   and `D-NNN` row. (§9.6 row table carries a cleanup-wave smell
-   banner — D-028 owns the per-row audit at each owning Phase.)
+   and `D-NNN` row.
 
 ## Current state
 
@@ -83,6 +87,33 @@ output)**:
 - `src/runtime/binding_stack.zig` deleted (env.zig is the
   authoritative location for the dynamic-binding stack).
 
+**Wave 3 — root-cause hardening (post-research)**:
+
+User asked "why did all this happen on top of an already-laid
+ROADMAP + guardrails?". A `general-purpose` subagent investigated
+LLM long-context behaviour (2026-05-23, 24 tool uses, output at
+`private/notes/llm_long_context_research.md` 523 lines) and
+concluded the symptoms are not attention decay (CLAUDE.md is
+re-injected every turn) but **CLAUDE.md's own "進め bias" +
+autonomous loop's instruction centrifugation** (~80% combined).
+Fix landed:
+
+- **`.dev/project_facts.md`** (new) — user-declared invariants
+  (F-001 zwasm / F-002 finished-form wins / F-003 deferral)
+  read at every Phase entry (CLAUDE.md Step 1a).
+- **CLAUDE.md stop list extended to 3 conditions** — condition 3
+  is "smell depth ≥ 3 fires 2× in one cycle → ADR-phase mode
+  switch" (not a stop, a mode change).
+- **CLAUDE.md Step 6 + principle.md depth ≥ 2** — Devil's-advocate
+  subagent with fresh context is mandatory before ADR accept;
+  output embedded verbatim in "Alternatives considered".
+- **`scripts/check_smell_audit.sh`** (new PreToolUse hook) —
+  `git push` is physically blocked unless every unpushed
+  source-bearing commit body contains `Smell-audited: <depth>:
+  <one-line>`. This is the deterministic enforcement layer
+  behind the probabilistic CLAUDE.md rule
+  ("CLAUDE.md is a suggestion, hooks make it law").
+
 ## Active task — §9.6 / 4.25
 
 `src/runtime/dispatch/method_table.zig` — `MethodEntry` struct
diff --git a/.dev/principle.md b/.dev/principle.md
@@ -102,6 +102,16 @@ continues. The AI drafts and accepts the ADR itself — there is no
 external review gate. See CLAUDE.md § Autonomous Workflow
 "ADR-level designs are handled inline, not as a stop".
 
+**Devil's-advocate subagent is mandatory at depth ≥ 2.** Before
+the ADR is accepted, a `general-purpose` subagent is forked with
+**fresh context** to produce 3 alternative shapes (smallest-diff /
+finished-form-clean / wildcard). The output is embedded verbatim
+into the ADR's "Alternatives considered" section. This is the
+antidote to the loop's accumulated goal-drift / instruction
+centrifugation — alternatives sourced from a context without the
+main loop's momentum surface options the main loop is
+attention-suppressed against.
+
 ## Three questions to picture the finished form
 
 When you stop, ask:
diff --git a/.dev/project_facts.md b/.dev/project_facts.md
@@ -0,0 +1,118 @@
+# Project facts — user-declared invariants
+
+> **What this file is for.** ClojureWasm v2's ROADMAP / ADRs /
+> rules describe the *engineering decisions* the project has
+> committed to. This file captures the **invariants the user has
+> declared** that those documents may not yet reflect — facts the
+> autonomous loop must treat as load-bearing even when ROADMAP /
+> ADR text appears to admit other readings.
+>
+> The autonomous loop must read this file as part of every Phase
+> entry's reading list (CLAUDE.md Step 1a) and consult it whenever
+> a planned change touches the topics below.
+>
+> This file is **append-only history** — entries are dated and
+> never silently rewritten. A later fact that supersedes an
+> earlier one is added as a new entry with a `Supersedes: <id>`
+> line; the earlier entry stays, annotated `Superseded by: <id>`.
+
+## How to add an entry
+
+User declares a project-level invariant in chat that the loop
+should treat as fact. The loop captures it here as the next
+`F-NNN` entry with verbatim or near-verbatim quoting + a one-line
+"why this matters for the loop" + cross-reference to the ROADMAP
+section / ADR / debt row it interacts with. The user reviews the
+entry at end of session.
+
+---
+
+## F-001 — zwasm v2 integration is unavoidable
+
+**Declared**: 2026-05-23 (user chat).
+**Verbatim**: 「このプロジェクトがzwasmと連携するのは確実です。zwasm
+v1は今それなりの完成度ですが、zwasm v2と連携するつもりです。
+$My/zwasm_from_scratchはまだ開発途上ですが、wasm FFIは欠かせない
+要素だということは自覚してください。また、zwasmはそれ自体がJITや
+メモリ管理の機能を持っています」
+
+**What this changes for the loop**:
+
+1. ADR-0006 frames Wasm FFI as "deferred to Phase 16 via Pod
+   boundary". The Pod-boundary framing remains the **default
+   protocol shape**, but the inline-vs-Pod choice **is not closed**.
+   Phase 16 entry must re-open it with the user (D-036).
+2. ADR-0006 amendment 1 (NaN-box slot release for big_int /
+   ratio) assumed Pod-boundary. If Phase 16 chooses inline
+   NaN-box Values, those slots cannot be reclaimed — Phase 16
+   must mint fresh slots, co-ordinated with D-027 (NaN-box
+   layout 第二世代).
+3. zwasm v2 carries its own JIT + GC. cw v2's Phase 5 mark-sweep
+   GC and Phase 17 JIT (ADR-0005 3rd backend) **overlap
+   territorially**. Phase 16 entry resolves heap-boundary and
+   JIT-coordination design (cw-heap vs wasm-heap, JIT handoff).
+4. The counterparty is **zwasm v2**, not zwasm v1. zwasm v1 is
+   reasonably complete, but cw v2 targets zwasm v2.
+   `~/Documents/MyProducts/zwasm_from_scratch/` is the in-progress
+   counterparty repo.
+
+**Cross-references**: ADR-0006 amendment 3 (records this fact in
+the ADR); debt D-036 (Phase 16 inline-vs-Pod decision); ROADMAP
+§9.18 Phase 16 placeholder (Entry debts).
+
+---
+
+## F-002 — Finished-form cleanliness wins; shipping fast / avoiding rework are second-tier
+
+**Declared**: 2026-05-23 (user chat).
+**Verbatim**: 「完成した時の綺麗さ、 が何よりも優先されています。
+さっさと作る、 手戻りしない、 は二の次です(もちろん少ないに越した
+ことはないので事前ロードマップを敷いているが)」
+
+**What this changes for the loop**:
+
+1. Big surgery (depth 3-4 in `.dev/principle.md`) is welcome when
+   the plan misses something. The autonomous loop must not
+   hesitate at ADR-level revisions.
+2. ROADMAP P5 ("smallest-diff first") is a tie-breaker, not a
+   veto. If smallest-diff and finished-form collide, finished-form
+   wins.
+3. Skeleton-then-rewrite is endorsed (per
+   `permanent_noop_forbidden.md`), but excessive skeletons are a
+   smell (Smallest-diff bias smell in principle.md).
+4. Reservations (ADR numbers, NaN-box slots, debt rows promising
+   future ADRs) are memos, not contracts. ADR numbers are
+   time-ordered (`max + 1` at issue).
+
+**Cross-references**: CLAUDE.md § Project spirit (top); ADR-0029
+→ ADR-0025 rename history; D-021 retirement; principle.md Bad
+Smell catalogue.
+
+---
+
+## F-003 — Decision-deferral over decision-seizure on structural plans
+
+**Declared**: 2026-05-23 (user chat).
+**Verbatim**: 「すでにロードマップが将来にわたるまであるのだから、
+テーブル予約についてどれくらいありそうかを省略せずにしっかり
+想像するフェーズを入れて、 どうするかを決めるのはその担当のとき
+にやってください」
++ 「あと、 ついでにディレクトリ構造、 ファイル構造の予測や責務
+分離や依存関係でも将来にわたり無理がこないのかを想像・シミュレート
+して考えてみて」
+
+**What this changes for the loop**:
+
+1. The loop's job at any task touching a reservation table /
+   directory or file structure / responsibility / dependency
+   graph is **imagine, record, defer** — not decide.
+2. Decisions belong to the owning Phase entry's owner. The
+   current loop records the imagination output as debt rows
+   scheduled at the owning Phase.
+3. This is the antidote to the Progress-pressure smell on
+   structural work.
+
+**Cross-references**: principle.md "Structural imagination
+phase"; CLAUDE.md Step 0.5 (Phase-entry debt read) + Step 1
+(Structural imagination trigger); debt rows D-027 / D-029 /
+D-031 / D-032 / D-034 / D-035 / D-036.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -169,17 +169,20 @@ entry, and **defer the structural decision to that owner**; do not
 resolve here. If something feels off, adjust before Step 2.
 
 **Step 1a — Phase reading list** (every Phase entry)
-Read in order: `.dev/handover.md`, `.dev/ROADMAP.md` §9.<N>
-placeholder (Entry ADRs / **Entry debts** / Reference / Skeletons
-to activate / Deliverables / Final activation step), each ADR
-listed in the placeholder's "Entry ADRs:" line **including the
-Phase N+ migration note section AND every Revision history
-amendment if present** (this is where existing-code rewrite scope
-and inter-Phase corrections are narrated per §A25), each `D-NNN`
-debt row listed in the placeholder's "Entry debts:" line (full row
-text in `.dev/debt.md`), `compat_tiers.yaml` entry for the
-function, and the JVM Clojure source (`~/Documents/OSS/clojure/`)
-for the function.
+Read in order: `.dev/handover.md`, **`.dev/project_facts.md`**
+(user-declared invariants the loop must treat as fact, even when
+ROADMAP / ADR text admits other readings), `.dev/ROADMAP.md`
+§9.<N> placeholder (Entry ADRs / **Entry debts** / Reference /
+Skeletons to activate / Deliverables / Final activation step),
+each ADR listed in the placeholder's "Entry ADRs:" line
+**including the Phase N+ migration note section AND every
+Revision history amendment if present** (this is where
+existing-code rewrite scope and inter-Phase corrections are
+narrated per §A25), each `D-NNN` debt row listed in the
+placeholder's "Entry debts:" line (full row text in
+`.dev/debt.md`), `compat_tiers.yaml` entry for the function, and
+the JVM Clojure source (`~/Documents/OSS/clojure/`) for the
+function.
 
 **Step 2 — Red**
 Write the failing test (Edit / Write). Run; confirm red.
@@ -205,7 +208,7 @@ Run both in a single message with two parallel Bash tool calls:
 Both must be green. If either output exceeds ~200 lines, delegate
 to a Bash subagent and ask for "pass/fail + first failure only".
 
-**Step 6 — Source commit + push (atomic)**
+**Step 6 — Source commit + push (atomic, smell-audited)**
 
 Before staging:
 
@@ -215,22 +218,40 @@ Before staging:
 3. If a smell triggers, choose depth 1-4:
    - depth 1: add a one-line note in the commit message.
    - depth 2-4: land the ADR amendment / new ADR / `debt.md` row
-     / `private/notes/` entry **autonomously** (the AI gathers
-     the "should-be" materials, drafts the ADR with
-     `Status: Proposed → Accepted`, fills Affected files,
-     Alternatives, Consequences), commits the doc change first,
+     / `private/notes/` entry **autonomously**. Before drafting
+     the ADR, **fork a `general-purpose` subagent with fresh
+     context as Devil's advocate**: brief the subagent on the
+     decision and ask for 3 alternative shapes (one smallest-diff,
+     one finished-form-clean, one "wildcard"). Reflect the
+     subagent's output verbatim into the ADR's "Alternatives
+     considered" section before stamping
+     `Status: Proposed → Accepted`. Commits the doc change first,
      then commits + pushes the source separately. No external
-     review gate — ADR history is the rationale record.
+     review gate — ADR history (plus the Devil's-advocate output
+     embedded in it) is the rationale record.
 
 Then:
 
-4. `git add` source files; `git commit -m "<type>(<scope>):
-   <one line>"`. The pre-commit gate auto-aligns any Markdown
-   tables that drifted and re-stages the fix transparently;
-   only genuine table-syntax errors block.
+4. `git add` source files; `git commit` with **a two-line message
+   shape**:
+   ```
+   <type>(<scope>): <one line summary>
+   
+   Smell-audited: <depth 0-4>: <one-line summary of audit outcome>
+   <optional further body>
+   ```
+   `Smell-audited:` is **mandatory** on every commit that stages
+   source-bearing files (`src/**/*.zig`, `build.zig`,
+   `build.zig.zon`, `.dev/decisions/NNNN_*.md`). It records that
+   Step 6's self-audit was actually performed. The pre-commit gate
+   auto-aligns Markdown tables; only genuine table-syntax errors
+   block.
 5. `git push origin cw-from-scratch` runs immediately on the
-   commit's success. The push is not optional and not deferred —
-   commit and push are one Step.
+   commit's success. **The `scripts/check_smell_audit.sh` PreToolUse
+   hook physically blocks pushes that include any source-bearing
+   commit missing a `Smell-audited:` line.** Re-audit, amend the
+   commit message, push again. Push is not optional and not
+   deferred.
 
 **Step 7 — Per-task note** (written from hot context)
 
@@ -263,20 +284,36 @@ rows:
 
 ### Stop only when (closed list)
 
-Two conditions, exhaustive:
+Three conditions, exhaustive:
 
 1. **User explicitly requests stop** (any direct instruction).
 2. **Physically blocked** — build broken with no identifiable root
    cause, or test failure that cannot be diagnosed after honest
    investigation.
-
-Anything outside these two is continued through. The loop's quality
-discipline lives in `.dev/principle.md` (Bad Smell sensor, depth
-1-4) and is applied per cycle — quality is a *how*, not a stop
-condition.
+3. **Smell-cluster trip** — a Bad Smell at depth ≥ 3 fires twice
+   within the same per-task TDD cycle (Step 0 → 7). This is
+   "patterned smell": the plan is structurally off, not just
+   locally smelly. **Don't stop the project** — the loop transitions
+   into **ADR-phase mode**: pause the current task at its last
+   green state, commit nothing more, fork a `general-purpose`
+   subagent with fresh context to draft a root-cause ADR
+   (`Supersedes <NNNN>` or net-new), accept it inline per the
+   ADR-phase rules below, then resume the per-task loop with the
+   ADR's verdict applied. This is a **mode switch, not a stop** —
+   the autonomous loop continues; only its current activity
+   changes.
+
+Anything outside these three is continued through. The loop's
+quality discipline lives in `.dev/principle.md` (Bad Smell sensor,
+depth 1-4) and is applied per cycle — quality is a *how*, not a
+stop condition.
 
 This list intentionally avoids enumerating non-stop reasons. Closed
-stop conditions + open continue is the design.
+stop conditions + open continue is the design. Condition 3 above
+exists because **depth ≥ 3 firing twice in one cycle indicates
+goal drift the per-cycle sensor is too narrow to catch** (per the
+2026-05-23 investigation into instruction centrifugation, recorded
+in `private/notes/llm_long_context_research.md`).
 
 ### ADR-level designs are handled inline, not as a stop
 
@@ -291,6 +328,19 @@ source change. Rationale survives in the ADR's history; the loop
 does not need an external accept gate. Step 6's depth 2-4 branch
 is the runway for this.
 
+**Devil's-advocate subagent is mandatory at depth ≥ 2.** Before
+stamping `Status: Proposed → Accepted`, fork a `general-purpose`
+subagent with **fresh context** and brief it: "Devil's advocate
+this ADR. Produce 3 alternative shapes (one smallest-diff, one
+finished-form-clean, one wildcard); for each, name what it does
+better than the current draft and what it breaks." The subagent's
+output is reflected verbatim into the ADR's "Alternatives
+considered" section. This counters goal-drift / instruction
+centrifugation by sourcing the alternatives from a context
+without the main loop's accumulated momentum. The subagent's
+recommendation is **not binding** — the main loop still chooses
+— but the alternatives must appear in the ADR.
+
 The phrases "this needs human judgement" / "cannot be
 self-decided" / "user touchpoint required" are forbidden framings
 in the autonomous loop. If the choice is between candidate
