@tyroneross/build-loop 0.36.0 → 0.43.0

package/plugin-artifacts/codex/skills/build-loop/references/refactor-history/scenarios/01-simple-bugfix.md

@@ -1,32 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Scenario 1: Simple bugfix
-
-## Setup
-
-- **Project**: mid-size Next.js app, no NavGator, no claude-code-debugger installed
-- **Goal**: "Fix the `TypeError: Cannot read properties of undefined (reading 'email')` in `src/api/users.ts:42`"
-- **Scope**: 1-2 files, ~15 lines
-- **Criteria**:
-  1. Tests pass (`npm test`)
-  2. Lint clean (`npm run lint`)
-  3. No new type errors (`tsc --noEmit`)
-
-## Expected failure modes at test time
-
-None — single-file fix, plan reveals the bug is an unchecked optional. Implementer fixes on first try.
-
-## What should fire
-
-- Critic (A) — scope drift check on the diff
-- Validate (B) — tests + lint + type check
-- Fact-Check (D) — no rendered data, mock scan clean
-- Report (F) — scorecard written
-
-## What should NOT fire
-
-- Iterate (no failures)
-- Memory-first gate (debugger not installed)
-- NavGator sub-steps (NavGator not installed)
-- Optimize (no mechanical metric)
-- Learn (no prior runs)

package/plugin-artifacts/codex/skills/build-loop/references/refactor-history/scenarios/02-ui-build-with-iteration.md

@@ -1,48 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Scenario 2: UI build with one iteration cycle
-
-## Setup
-
-- **Project**: Next.js + IBR installed + claude-code-debugger installed (via `availablePlugins`)
-- **Goal**: "Add a dashboard card showing total active users with a sparkline of the last 7 days"
-- **Scope**: 3 files (`DashboardCard.tsx`, `useActiveUsers.ts`, `dashboard.module.css`), ~120 lines
-- **Criteria**:
-  1. Tests pass
-  2. IBR scan verdict: PASS (no Calm Precision violations)
-  3. Lint/type check clean
-  4. No mock data in production paths
-
-## Expected failure mode at test time
-
-First Review pass: Validate (sub-step B) sees the IBR scan flag a `gestalt` violation (the card has individual borders on list items). Routes to Iterate.
-
-## What should fire
-
-**First Review:**
-- Critic (A) — reviews diff, probably clean
-- Validate (B) — tests pass, but IBR scan flags Gestalt violation → FAIL. Memory-first gate queries debugger for similar UI pattern; verdict `NO_MATCH` (first time).
-- Route to Iterate
-
-**Iterate (attempt 1):**
-- Debugger-bridge Iterate step — no evidence_gap, no prior-failure escalation yet
-- Diagnose: "individual borders on list items"
-- Fix plan: consolidate into single outer border, add dividers
-- Execute fix (targeted)
-- Loop back to Review
-
-**Second Review:**
-- Critic — skipped (same files, no new scope drift risk)
-- Validate (B) — IBR scan PASS this time
-- Optimize (C) — skipped (no mechanical metric)
-- Fact-Check (D) — no rendered metrics, mock scan clean
-- Simplify (E) — trim any over-abstracted helpers
-- Report (F) — scorecard written; debugger `store` called with the Gestalt fix; `outcome` N/A (no prior memory to evaluate)
-
-**Learn (6)**: skipped if < 3 prior runs, else scans `runs[]`.
-
-## What should NOT fire
-
-- NavGator bridges (not installed)
-- Logging-tracer-bridge repair path (no silent failure)
-- More than 1 iteration cycle

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

@@ -1,60 +0,0 @@
-<!-- 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/plugin-artifacts/codex/skills/build-loop/references/refactor-history/scenarios/04-ui-build-ibr-absent.md

@@ -1,51 +0,0 @@
-<!-- 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/plugin-artifacts/codex/skills/build-loop/references/refactor-history/scenarios/05-refactor-navgator-absent.md

@@ -1,71 +0,0 @@
-<!-- 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/plugin-artifacts/codex/skills/build-loop/references/refactor-history/scenarios/06-recurring-bug-debugger-absent.md

@@ -1,52 +0,0 @@
-<!-- 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/plugin-artifacts/codex/skills/build-loop/references/refactor-history/trace-comparison.md

@@ -1,202 +0,0 @@
-<!-- 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/plugin-artifacts/codex/skills/build-loop/references/self-recursive-dev.md

@@ -1,77 +0,0 @@
-<!-- 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`.