@tyroneross/build-loop 0.30.3

package/skills/build-loop/references/refactor-history/scenarios/03-multi-failure-escalation.md

@@ -0,0 +1,60 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Scenario 3: Multi-failure stuck iteration with logging-tracer rescue
+
+## Setup
+
+- **Project**: Node.js backend + NavGator installed + claude-code-debugger installed
+- **Goal**: "Add rate limiting to `/api/search` endpoint — 100 req/min per IP, Redis-backed"
+- **Scope**: 4 files, ~200 lines, touches middleware, Redis client, tests
+- **Criteria**:
+  1. Integration tests pass
+  2. Rate-limit correctness (custom assertion: burst of 101 requests → first 100 succeed, 101st returns 429)
+  3. Lint/type clean
+  4. NavGator rules pass (no new layer violations)
+
+## Expected failure trajectory
+
+**First Review:**
+- Critic (A) clean
+- Validate (B): criterion 2 (rate-limit correctness) FAILS with test output: `assertion failed: expected 429, got 500`. No stack trace, no error message — the server returned 500 but the test didn't capture the cause. Memory-first gate synthesizes "500 on 101st request, no stack". `read_logs` MCP returns 0 entries (project is silent — `console.log` only). `evidence_gap: true` flagged.
+- Fact-Check (D) and later sub-steps skipped due to B fail
+- Route to Iterate
+
+**Iterate attempt 1:**
+- Debugger-bridge Iterate sees `evidence_gap: true` from previous attempt
+- Invokes logging-tracer-bridge with `{phase: "iterate", action: "repair"}`. Ephemeral mechanism A: wraps new `trace(...)` calls in the Redis client behind `DEBUG_TRACE=1` env gate.
+- Re-runs criterion 2 with `DEBUG_TRACE=1 npm test`. Now stderr captures: `Redis connection dropped after 98 ops, reconnect latency > 1s, causes burst to fail at 98 not 100`.
+- Now a real root cause. Fix plan: add connection keep-alive + retry wrapper.
+- Execute fix.
+
+**Second Review:**
+- Validate: criterion 2 now passes. But criterion 3 (lint) fails — the retry wrapper introduced `any` types.
+- Route to Iterate.
+
+**Iterate attempt 2:**
+- Same criterion? No, different (lint vs rate-limit). No debugger escalation triggered (not 2 same-root-cause).
+- Fix types.
+- Execute.
+
+**Third Review:**
+- Validate all pass.
+- Optimize (C): has mechanical metric (test runtime), runs 3-5 iterations. One win: -12% test time after connection pooling tuned.
+- Fact-Check (D): NavGator rules check — new `database-isolation` violation? No, Redis already in allowed db layer. Clean.
+- Simplify (E): remove an unused retry-count parameter.
+- Report (F): scorecard PASS with notes. Debugger `store` called for the Redis burst bug. Logging-tracer instrumentation reverted per "ephemeral by default" (no user approval sought to keep). NavGator `dead` orphan scan: 1 new resolved orphan (the keep-alive wrapper is now wired in).
+
+## What should fire vs NOT
+
+**Fires:**
+- Critic, Validate, Fact-Check, Simplify, Report across two final-Review passes
+- Logging-tracer repair (evidence_gap trigger)
+- NavGator sub-steps (Assess blast-radius + Review-D rules + Report dead scan)
+- Debugger gate + store; outcome N/A (no prior KNOWN_FIX applied)
+- Optimize (C) — mechanical metric exists
+- 2 Iterate attempts
+
+**Does NOT fire:**
+- Parallel `/assess` domain assessors (not 2+ same-root-cause failures on one criterion)
+- `debug-loop` causal-tree (not 3+ same-criterion failures)
+- Learn (skipped unless `runs[] >= 3`)

package/skills/build-loop/references/refactor-history/scenarios/04-ui-build-ibr-absent.md

@@ -0,0 +1,51 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Scenario 4: UI build, IBR absent (exercises `fallbacks.md#web-ui`)
+
+## Setup
+
+- **Project**: Next.js app, no IBR installed, no claude-code-debugger, no NavGator
+- **Goal**: "Add a settings-panel nav item with active-state indicator"
+- **Files to touch**: `src/components/SettingsNav.tsx` (new), `src/styles/nav.module.css` (new)
+- **Criteria**:
+  1. Tests pass
+  2. Lint/type check clean
+  3. UI meets Calm Precision principles (a11y, touch targets, handlers)
+  4. No mock data
+
+## Pre-fallback behavior (before commit 76f9a26)
+
+**Review sub-step B Validate**:
+- `availablePlugins.ibr` is false
+- Bridge: (no bridge existed — IBR path skipped silently)
+- Criterion 3 (Calm Precision): orchestrator had `fallbacks.md#web-ui` available but no explicit instruction to paste it into the validation subagent. Default behavior: subagent does a best-effort review without structured guidance.
+- Output: "Criterion 3 reviewed informally; recommend installing IBR for deep verification." No specific findings.
+- Verdict: **soft pass** — nothing concrete flagged, but nothing verified either.
+
+## Post-fallback behavior (after commit 76f9a26)
+
+**Review sub-step B Validate**:
+- `availablePlugins.ibr` is false AND build touched UI files (`*.tsx`, `*.module.css`)
+- Orchestrator pastes `fallbacks.md#web-ui` into the validation subagent prompt
+- Subagent runs the 10 grep checks against the diff:
+  - Check 5 (icon-only buttons missing aria-label) matches: `<button><ChevronIcon /></button>` in SettingsNav.tsx:24
+  - Check 6 (status as background pill) matches: `bg-blue-500 text-white` on the active-state indicator in nav.module.css — suspicious, could be a signal-to-noise violation
+  - Check 3 (button missing onClick/submit) clean
+  - Check 7 (hardcoded hex) clean
+  - Remaining 6 checks clean
+- Findings written to Review-F with paths + line numbers
+- Verdict: **fail** on criterion 3 with 2 concrete findings → routes to Iterate
+- Flag in report: `⚠️ static-analysis only — install IBR for computed-CSS verification`
+
+## Concrete delta
+
+| Aspect | Pre-fallback | Post-fallback |
+|---|---|---|
+| Criterion 3 result | Soft pass ("recommend install") | Fail with 2 specific file:line findings |
+| Orchestrator action | None | Route to Iterate, fix aria-label + reconsider pill |
+| User visibility | "IBR would have found issues" | "File X line Y is missing aria-label" |
+| False positives | 0 (no findings emitted) | 1-2 possible (pill check is heuristic) |
+| Time to catch | Post-deploy user bug report | Phase 4 Review, before merge |
+| Install IBR? | Recommended | Still recommended for computed-CSS verification |
+
+**Net**: fallback catches real bugs that would otherwise ship. False-positive tolerance is acceptable because findings are file:line-specific and the user can trivially dismiss.

package/skills/build-loop/references/refactor-history/scenarios/05-refactor-navgator-absent.md

@@ -0,0 +1,71 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Scenario 5: Large refactor, NavGator absent (exercises `fallbacks.md#architecture`)
+
+## Setup
+
+- **Project**: Node.js + Next.js monorepo, no NavGator, no debugger, no IBR
+- **Goal**: "Rename `User.email` → `User.primaryEmail` across the codebase"
+- **Expected scope**: ~40 files across db models, API routes, frontend components
+- **Criteria**:
+  1. Tests pass
+  2. Type check clean
+  3. No orphan references to old field name (grep audit)
+
+## Pre-fallback behavior
+
+**Assess (Phase 1)**:
+- `.navgator/architecture/index.json` doesn't exist
+- navgator-bridge `Pre-flight`: "NO_NAVGATOR" → emit "NavGator: no architecture snapshot found" → skip
+- `.build-loop/state.json.navgator` not written
+- Phase 2 Plan proceeds blind: no blast-radius data, scoping based on goal text only
+
+**Plan (Phase 2)**:
+- Breaks work by grep of current field usage: finds ~40 files
+- No signal about layer crossings or hotspots
+- Dispatches one subagent per directory cluster
+
+**Review-D Fact-Check** (after Execute):
+- No NavGator rules check (bridge skipped silently pre-fallback)
+- Other gates (fact-checker, mock-scanner) run normally
+- Scorecard PASS if tests + types clean
+
+**Risk**: the rename touches `src/db/User.ts` + `src/components/Profile.tsx` directly without going through `src/api/` — a potential `frontend-direct-db` violation is **not detected**.
+
+## Post-fallback behavior
+
+**Assess (Phase 1)**:
+- navgator-bridge `Pre-flight`: "NO_NAVGATOR" → runs `fallbacks.md#architecture`
+- Executes the grep/git commands:
+  - Check 1 (changed files): ~40 files enumerated
+  - Check 2 (layer classification): 12 db / 8 backend / 18 frontend / 2 test
+  - Check 3 (1-hop dependents): for each changed file, grep import paths
+  - Check 4 (hotspot churn): top-10 includes `src/db/User.ts` and `src/lib/auth.ts` — both touched
+  - Check 5 (circular-import): defer to type check
+- Risk flags:
+  - ≥3 layers crossed (db + backend + frontend) → "high blast radius"
+  - `src/db/User.ts` is a top-5 hotspot → "concentration risk"
+  - `src/db/User.ts` imported directly from `src/components/Profile.tsx` without going through API → "possible frontend-direct-db layer violation"
+- Writes to `.build-loop/state.json.architecture.standalone` with these flags
+
+**Plan (Phase 2)**:
+- Reads the standalone state. Sees blast radius + layer violation flag.
+- Splits work into 3 chunks with explicit integration tests between them (normally would have been one monolithic PR).
+- Adds a plan task: "Introduce API layer between Profile.tsx and User model before renaming" — the layer violation would have shipped without this.
+
+**Review-F report**:
+- Includes `⚠️ architecture analysis via static fallback — install NavGator for AST-aware dependency graph + rule enforcement`
+- Flags the possible layer violation as an observed concern
+
+## Concrete delta
+
+| Aspect | Pre-fallback | Post-fallback |
+|---|---|---|
+| Assess architecture output | Nothing | Layer counts + hotspots + risk flags |
+| Layer violation detection | Missed | Flagged (frontend-direct-db pattern) |
+| Plan scoping | Monolithic subagent dispatch | Chunked with integration checkpoints |
+| Cost if violation ships | Future bug + refactor | Caught pre-commit |
+| Analysis quality | None | Directional — false positives possible, but useful |
+| Install NavGator? | Silent loss | Explicit report note |
+
+**Net**: fallback converts a silent gap into a surfaced risk. Heuristic rather than authoritative (NavGator would be exact), but 10× better than nothing.

package/skills/build-loop/references/refactor-history/scenarios/06-recurring-bug-debugger-absent.md

@@ -0,0 +1,52 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Scenario 6: Recurring bug, debugger absent (exercises `fallbacks.md#bug-memory`)
+
+## Setup
+
+- **Project**: Node.js backend, no claude-code-debugger, no NavGator, no IBR
+- **Prior state**: `.build-loop/issues/2026-03-18-redis-reconnect.md` exists from a prior build, recording a Redis connection reset bug with fix notes
+- **Goal**: "Add a batch-process job that pushes to Redis in a loop"
+- **Criteria**: standard tests + lint + type
+
+## First failure (during Review-B Validate)
+
+Integration test fails: `Error: Connection is closed` when the batch hits 50 items. Same error class as the prior recorded bug, different call site.
+
+## Pre-fallback behavior
+
+**Review-B memory-first gate**:
+- `availablePlugins.claudeCodeDebugger` is false
+- debugger-bridge Pre-flight: "Debugger memory: not installed. Using inline debug fallback." → skip with generic message
+- Verdict: none — falls through to standard Iterate with no memory context
+- Orchestrator begins from scratch: reproduce, isolate, hypothesize
+- Eventually rediscovers the same Redis-disconnect root cause. Cost: 2-3 Iterate attempts, ~6-10 min wall clock.
+
+## Post-fallback behavior
+
+**Review-B memory-first gate**:
+- debugger-bridge Pre-flight: runs `fallbacks.md#bug-memory`
+- Extracts tokens from symptom: `Error`, `Connection`, `closed`, `batch`, `Redis`
+- Greps `.build-loop/issues/`, `feedback.md`, `.bookmark/` for each token
+- `.build-loop/issues/2026-03-18-redis-reconnect.md` matches 4 tokens (`Error`, `Connection`, `closed`, `Redis`)
+- Verdict: `LOCAL_HIT_PARTIAL` (≥2 tokens co-occur in the same file)
+- Orchestrator reads the prior issue file: includes a recorded fix (add keep-alive config, retry wrapper)
+- Iterate plan: adapt the prior fix to this call site. No direct-apply (the new call path is different), but informed starting point.
+- Iterate attempt 1 succeeds on first try.
+
+## Concrete delta
+
+| Aspect | Pre-fallback | Post-fallback |
+|---|---|---|
+| Memory lookup | Disabled | Enabled via local file grep |
+| Verdict granularity | None | 4 states mirroring upstream shape |
+| Iterate attempts to resolve | 2-3 | 1 |
+| Cross-session learning | None even within this project | Yes, per-project (no cross-project) |
+| Prior fix notes surfaced | No — rediscovered from scratch | Yes — read and adapted |
+| Install debugger? | Strong recommend for cross-project | Still recommend for classifier + cross-project memory |
+
+**Net**: fallback cuts recurring-bug resolution time roughly in half on projects with any prior `.build-loop/issues/` history. The upstream debugger adds cross-project memory and a classifier; the fallback has neither but captures most of the per-project value.
+
+## Where the fallback gives up
+
+When the project has no prior `.build-loop/issues/` files, there's nothing to grep. Fallback returns `LOCAL_NO_MATCH` and orchestrator proceeds normally. This is correct behavior — no false-positive reuse of unrelated prior issues.

package/skills/build-loop/references/refactor-history/trace-comparison.md

@@ -0,0 +1,202 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Old 9-Phase vs New 5-Phase Trace Comparison
+
+For each scenario, the linear sequence of orchestrator actions. "→" = sequential; indentation = sub-step.
+
+## Scenario 1: Simple bugfix (no failures, no plugins installed)
+
+### Old 9-phase
+
+```
+Phase 1 ASSESS       → detect tooling, no plugins, load memory
+Phase 2 DEFINE       → write goal.md with 3 criteria
+Phase 3 PLAN         → 1-task plan
+Phase 4 EXECUTE      → sonnet implementer dispatched
+Phase 4.5 CRITIC     → sonnet-critic on diff: pass
+Phase 4.7 OPTIMIZE   → skipped (no mechanical metric)
+Phase 5 VALIDATE     → 3 graders, all pass; memory-first gate skipped (no debugger)
+Phase 6 ITERATE      → skipped (all passed)
+Phase 7 FACT CHECK   → fact-checker + mock-scanner parallel; clean
+Phase 8 REPORT       → scorecard, append runs[], store (no debugger — noop)
+Phase 8.5 SIMPLIFY   → trim diff
+Phase 9 REVIEW       → skipped (runs[] < 3)
+```
+**Headings touched**: 9. **Transitions**: 9 (each phase logs a header).
+
+### New 5-phase
+
+```
+Phase 1 Assess       → detect tooling, no plugins, write goal.md with 3 criteria
+Phase 2 Plan         → 1-task plan
+Phase 3 Execute      → sonnet implementer dispatched
+Phase 4 Review
+  4A Critic          → sonnet-critic on diff: pass
+  4B Validate        → 3 graders, all pass
+  4C Optimize        → skipped
+  4D Fact-Check      → fact-checker + mock-scanner parallel; clean
+  4E Simplify        → trim diff
+  4F Report          → scorecard, append runs[]
+Phase 5 Iterate      → skipped
+Phase 6 Learn        → skipped (runs[] < 3)
+```
+**Headings touched**: 5 phases + 6 sub-steps. **Transitions**: 5 top-level.
+
+### Fidelity check
+
+| Old artifact | New location | Preserved? |
+|---|---|---|
+| Phase 1 state summary | Phase 1 Assess output | ✅ |
+| Phase 2 goal.md | Phase 1 Assess (define sub-section) | ✅ — same file |
+| Phase 3 plan | Phase 2 Plan | ✅ |
+| Phase 4 diff | Phase 3 Execute | ✅ |
+| Phase 4.5 critic output | Review 4A | ✅ — same agent |
+| Phase 5 scorecard | Review 4B evidence | ✅ |
+| Phase 7 fact-check report | Review 4D | ✅ — same gates |
+| Phase 8 scorecard file | Review 4F | ✅ — same path `.build-loop/evals/YYYY-MM-DD-<topic>.md` |
+| Phase 8.5 simplified diff | Review 4E | ✅ |
+| state.json.runs[] append | Review 4F | ✅ — same schema |
+
+**Result**: zero regression. New flow produces all old artifacts.
+
+---
+
+## Scenario 2: UI build with one iteration (IBR + debugger installed)
+
+### Old 9-phase
+
+```
+Phase 1 ASSESS       → detect IBR + debugger. Debugger list MCP: 0 recent. IBR capture UI baseline.
+Phase 2 DEFINE       → 4 criteria
+Phase 3 PLAN         → 3-task plan
+Phase 4 EXECUTE      → sonnet implementers
+Phase 4.5 CRITIC     → pass
+Phase 4.7 OPTIMIZE   → skipped
+Phase 5 VALIDATE     → tests pass, IBR scan FAILS (Gestalt violation on card)
+  └ memory-first gate → NO_MATCH → fallthrough
+Phase 6 ITERATE      → diagnose "individual borders"; fix plan; execute fix
+Phase 5 VALIDATE (re-run) → all 4 criteria pass
+Phase 7 FACT CHECK   → clean
+Phase 8 REPORT       → scorecard, runs[] append, store(Gestalt fix)
+Phase 8.5 SIMPLIFY   → trim
+Phase 9 REVIEW       → runs[] count check
+```
+**Transitions**: 9+1 (Phase 5 re-enters after Iterate) = 10 top-level.
+
+### New 5-phase
+
+```
+Phase 1 Assess       → detect IBR + debugger. Debugger list MCP: 0 recent. IBR capture UI baseline. Write goal.md with 4 criteria.
+Phase 2 Plan         → 3-task plan
+Phase 3 Execute      → sonnet implementers
+Phase 4 Review (first pass)
+  4A Critic          → pass
+  4B Validate        → tests pass, IBR scan FAILS (Gestalt violation)
+    └ memory-first gate → NO_MATCH → route to Iterate
+  (4C-4F skipped, failure routed)
+Phase 5 Iterate (attempt 1)
+  └ debugger-bridge Iterate → no evidence_gap, no escalation trigger
+  └ diagnose: "individual borders"
+  └ fix plan + execute
+Phase 4 Review (second pass, final)
+  4A Critic          → skipped (same files)
+  4B Validate        → all 4 pass
+  4C Optimize        → skipped
+  4D Fact-Check      → clean
+  4E Simplify        → trim
+  4F Report          → scorecard, runs[] append, debugger store(Gestalt fix), outcome N/A
+Phase 6 Learn        → runs[] count check
+```
+**Transitions**: 5 top-level (Review fires twice but as the same heading).
+
+### Fidelity check
+
+All artifacts preserved. One behavior change:
+- **Old**: `Phase 5 VALIDATE` re-runs just failed criteria after Iterate.
+- **New**: `Review 4B Validate` re-runs just failed criteria after Iterate (same behavior). Critic 4A skipped on re-runs — this is new and intentional; avoids burning tokens re-reviewing an unchanged scope. Documented in SKILL.md.
+
+**Result**: zero regression; one optimization (skip Critic on re-runs).
+
+---
+
+## Scenario 3: Multi-failure with logging-tracer rescue (NavGator + debugger)
+
+### Old 9-phase
+
+```
+Phase 1 ASSESS       → detect NavGator + debugger. navgator-bridge.phase1 writes blast radius. debugger list: 2 prior. observability: "silent" (project uses console.log).
+Phase 2 DEFINE       → 4 criteria
+Phase 3 PLAN         → 4-task plan
+Phase 4 EXECUTE      → sonnet implementers
+Phase 4.5 CRITIC     → pass
+Phase 4.7 OPTIMIZE   → defer (post-validation)
+Phase 5 VALIDATE     → tests fail, criterion 2 assertion 429 vs 500; read_logs empty → evidence_gap: true; memory-first NO_MATCH
+Phase 6 ITERATE (1)  → sees evidence_gap → logging-tracer-bridge repair (Mechanism A, DEBUG_TRACE gate)
+                     → re-validate with trace: real cause Redis disconnect
+                     → fix plan + execute
+Phase 5 VALIDATE     → criterion 2 passes; criterion 3 (lint) fails
+Phase 6 ITERATE (2)  → different root cause, no escalation
+                     → fix types
+Phase 5 VALIDATE     → all pass
+Phase 4.7 OPTIMIZE   → runs (mechanical metric exists): test runtime -12%
+Phase 7 FACT CHECK   → fact + mock + NavGator rules; clean
+Phase 8 REPORT       → scorecard, runs[] append, store(Redis bug), outcome N/A, NavGator dead: 1 resolved orphan
+Phase 8.5 SIMPLIFY   → trim retry-count arg
+Phase 9 REVIEW       → runs[] < 3, skip
+```
+**Transitions**: 9 + 2 Phase 5 re-entries + 1 Phase 4.7 delayed = ~12.
+
+### New 5-phase
+
+```
+Phase 1 Assess       → NavGator + debugger detected; blast radius; debugger list (2); observability=silent; goal.md + 4 criteria
+Phase 2 Plan         → 4-task plan
+Phase 3 Execute      → sonnet implementers
+Phase 4 Review (first pass)
+  4A Critic          → pass
+  4B Validate        → criterion 2 FAIL; read_logs empty; evidence_gap: true; NO_MATCH → Iterate
+Phase 5 Iterate (attempt 1)
+  └ evidence_gap detected → logging-tracer-bridge repair (Mechanism A)
+  └ re-validate trigger criterion with DEBUG_TRACE=1 → informative output
+  └ diagnose: Redis disconnect → fix plan → execute
+Phase 4 Review (second pass)
+  4A skipped (same files)
+  4B Validate        → criterion 2 pass, criterion 3 (lint) FAIL → Iterate
+Phase 5 Iterate (attempt 2)
+  └ different criterion, no escalation
+  └ fix types → execute
+Phase 4 Review (third pass, final)
+  4A skipped
+  4B Validate        → all 4 pass
+  4C Optimize        → mechanical metric (test runtime): runs, -12%
+  4D Fact-Check      → fact + mock + NavGator rules; clean
+  4E Simplify        → trim retry-count arg
+  4F Report          → scorecard, runs[] append, debugger store(Redis bug), NavGator dead: 1 resolved orphan, logging-tracer instrumentation reverted (no keep-in-diff approval sought)
+Phase 6 Learn        → runs[] < 3, skip
+```
+**Transitions**: 5 top-level (Review fires 3x, Iterate 2x).
+
+### Fidelity check
+
+All artifacts preserved. Behavior differences:
+
+1. **Old Phase 4.7 Optimize** ran pre-Validate deferred to post-Validate. New 4C runs **inside** Review, after Validate passes. Same effective ordering.
+2. **Old Phase 7 NavGator rules** was Gate C of Phase 7. New 4D NavGator rules is one of three parallel gates in sub-step D. Same.
+3. **Old Phase 8 orphan scan** ran after scorecard. New 4F orphan scan runs as part of Report. Same artifacts.
+4. **Old Phase 8.5 Simplify** ran after Report. New 4E Simplify runs **before** Report. Semantic change: Report now reflects the simplified diff, not the pre-simplified diff. Arguably better — the scorecard matches what actually ships. Document in SKILL.md as intentional.
+
+**Result**: zero regression. One semantic improvement (scorecard reflects simplified diff).
+
+---
+
+## Summary verdict
+
+| Check | Result |
+|---|---|
+| Every old artifact has a new-flow equivalent | ✅ |
+| No silent phase elimination | ✅ (everything rehoused as sub-step) |
+| Intentional behavior changes documented | ✅ (Critic-skip on re-run, Simplify-before-Report) |
+| Transition count reduced | ✅ (9 → 5 top-level headings) |
+| Flow comprehensibility | Better (one Review heading, sub-steps clearly ordered) |
+
+**No regressions detected across 3 scenarios.** PR #4 safe to merge on this criterion.

package/skills/build-loop/references/self-recursive-dev.md

@@ -0,0 +1,77 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+# Self-recursive build-loop dev (dogfooding)
+
+A run is **self-recursive** when the build-loop working tree IS the loaded runtime. That's the signal that arms per-commit mode and the self-modification safety machinery — without it, both stay dormant.
+
+## How to load the working tree as the live runtime
+
+Recommended: pass the working tree directly to Claude Code at session start.
+
+```sh
+claude --plugin-dir ~/dev/git-folder/build-loop
+```
+
+`--plugin-dir` takes session precedence over any cached marketplace copy, and Claude Code sets `CLAUDE_PLUGIN_ROOT` to that directory. The detector reads it. No symlink, no `~/.claude/` mutation.
+
+Convenience alias (optional, in `~/.zshrc` or `~/.bashrc`):
+
+```sh
+alias claude-bl='claude --plugin-dir ~/dev/git-folder/build-loop'
+```
+
+Use the alias when you intend to dogfood build-loop changes; use plain `claude` for normal work that should run against the released cache version.
+
+## Why not symlink into `~/.claude/plugins/`
+
+Marketplace plugins are installed by **copy**, not symlink, into `~/.claude/plugins/cache/<marketplace>/<name>/<version>/`. A manual symlink there is fragile:
+
+- Auto-update GC removes orphans after 7 days.
+- A version bump replaces the cache directory and clobbers the symlink.
+- `~/.claude/` is a per-user config surface — drift between machines breaks reproducibility.
+
+The detector still walks the symlink layout as a **fallback** so existing setups keep working, but it is not the recommended path.
+
+## How detection works
+
+`scripts/detect_self_recursive.py` (called from Phase 1 Assess) checks signals in precedence:
+
+1. **`--runtime-root <path>` arg** (Phase 1 passes `"$CLAUDE_PLUGIN_ROOT"`). `self_recursive = (realpath(runtime_root) == realpath(workdir))`. Method = `runtime_root_arg`.
+2. **`CLAUDE_PLUGIN_ROOT` env var** when the arg is absent. Same check. Method = `plugin_root_env`.
+3. **`__file__` self-location** — `Path(__file__).resolve().parents[1]` gives the plugin root of the running script copy (the script lives at `<plugin_root>/scripts/<name>.py`). If that resolves to `workdir`, this is ground truth — env-independent, because `CLAUDE_PLUGIN_ROOT` is not propagated to Bash-tool subprocesses. Mismatch falls through (heuristic, not operator assertion). Method = `self_location`.
+4. **Legacy fallback** — walk `~/.claude/plugins/` for a symlink resolving to the workdir. Method = `cache_symlink`.
+
+Both manifest (`.claude-plugin/plugin.json` with a `name`) and `.git/` must be present in the workdir regardless of method.
+
+When an explicit signal (arg or env) is present and **does not** match the workdir, detection returns `self_recursive: false` with `reason_if_false: no_runtime_link` — the explicit signal has answered the question and we do not fall through to the symlink walk.
+
+Output JSON keys: `self_recursive`, `plugin_name`, `runtime_symlink_path`, `working_copy_branch`, `working_copy_sha`, `reason_if_false`, `detection_method`.
+
+## Restart-boundary caveat
+
+Changing how build-loop is loaded (cache → `--plugin-dir`, or vice versa) takes effect **only at a fresh Claude Code session**. Do not switch mid-session: the live cache copy continues to serve your skills/agents until restart, and switching can GC the in-use cache and break the current session (`Agent not found` mid-run). Deploy plugin updates at a restart boundary; the same rule applies here.
+
+## Dogfood reload checkpoint
+
+When a self-recursive stage changes skills, agents, commands, hooks, MCP,
+Rally, memory/research, plugin manifests, or the self-recursive detector, the
+next stage must prove it is using the updated runtime. Use
+`references/dogfood-reload-checkpoint.md` and
+`scripts/dogfood_reload_checkpoint.py`:
+
+1. Finish and validate the runtime-changing stage.
+2. Create the checkpoint and post its path/instructions to Rally.
+3. Restart or reload each participating terminal.
+4. ACK with runtime root, runtime commit, reload method, and Rally status.
+5. Continue only after all expected tools ACK, or after an explicit fallback
+   decision records the stale/unmanaged terminal.
+
+## Quick verification
+
+After launching with `--plugin-dir`, from inside the working tree:
+
+```sh
+python3 "$CLAUDE_PLUGIN_ROOT/scripts/detect_self_recursive.py" \
+  --workdir "$PWD" --runtime-root "$CLAUDE_PLUGIN_ROOT" --json
+```
+
+Expect `"self_recursive": true` and `"detection_method": "runtime_root_arg"`. Phase 1 surfaces the same in `.build-loop/state.json.selfRecursive`.