@tyroneross/build-loop 0.30.3

package/skills/build-loop/references/phase-6-learn.md

@@ -0,0 +1,56 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Phase 6: Learn (full protocol)
+
+> Loaded from `skills/build-loop/SKILL.md` summary. Contains the full Learn phase: pattern detection, experimental skill drafting, and sample review sweep.
+
+## Phase 6: Learn — Cross-Build Pattern Detection (mandatory; always runs and always reports)
+
+**Goal**: detect recurring patterns across recent runs, auto-draft experimental skills/agents to address them, surface them for keep/remove decisions. Closes the loop between "build N times" and "build N+1 is faster because we learned."
+
+**Load the `build-loop:self-improve` skill for the full protocol.** (Skill keeps its existing name for backward compatibility; this phase was named "Self-Improvement Review" in v0.2.0 — renamed here to avoid collision with Phase 4 Review.)
+
+**Mandatory contract (v0.30.0+).** Every Phase 6 always does three things: (a) dispatches the Haiku detector (cheap), (b) runs `consolidate_memory.py` + `procedural_governance.py --mode detect-patterns` (already unconditional), and (c) emits a `## Learn` outcome line in the Review-G report — even when nothing crosses threshold. Net marginal cost over the prior gated path is one cheap Haiku state-scan per run. The expensive arm (Sonnet draft + Opus signoff) stays conditional on `runs[] >= 3` AND a pattern crossing threshold AND not-deferred. Also user-invokable via `/build-loop:self-improve` to run a scan without a build.
+
+Quick flow:
+
+1. **Detect** — dispatch `recurring-pattern-detector` (Haiku). Reads **two signal sources**:
+   - **Signal 1**: `.build-loop/state.json.runs[]` — emits `phase_failure`, `manual_intervention`, and `security_finding` patterns (real pain signals; `diagnostic_repeat` and `file_churn` were removed to prevent skill sprawl).
+   - **Signal 2**: `.build-loop/proposals/enforce-from-retro/*.md` (the post-push retrospective's enforce-candidates) — emits `enforce_recurrence` patterns when the same normalized candidate signature appears across ≥ 2 distinct run-ids. The orchestrator may cite `python3 scripts/enforce_retro_signals.py --workdir "$PWD" --json` as pre-computed input to the agent. This delivers "anything prompted/needed repeatedly → enforce" **across** sessions, not just within one.
+2. **Filter** — keep only `confidence: high` or `count >= 4`; manual interventions at lower threshold. Dedupe against existing active/experimental skill names. Cap 2 artifacts per scan.
+3. **Draft** — for each kept pattern, dispatch `self-improvement-architect` (Sonnet). Writes to `.build-loop/skills/experimental/<name>/SKILL.md` with an A/B Experiment section including `run_id` and `co_applied_experimental_artifacts[]` schema.
+4. **Signoff** — orchestrator (Opus 4.7) reviews each draft: APPROVE / REVISE (1 retry) / DISCARD.
+5. **Sample review sweep** — for artifacts in `.build-loop/skills/experimental/` from prior runs: if `.build-loop/config.json.autoPromote` is true AND effective (non-confounded) sample ≥ 8 AND target met → eligible for promotion. **Promotion is no longer silent.** Each eligible candidate goes through (a) advisory review by `promotion-reviewer` (Opus, agent), (b) async user confirmation via PushNotification + TaskCreate fallback. The reviewer's variance verdict (approve / rethink / new_approach) becomes the body of the notification. Move from `experimental/` to `active/` happens only after the user confirms via `/build-loop:promote-experiment <name>`. Regressions and inconclusive-at-2N write proposals to `.build-loop/proposals/` for user confirmation — never auto-delete.
+
+   **Promotion-reviewer dispatch protocol** (per advisory-judge design, plan §12 / `agents/promotion-reviewer.md`):
+   - For each eligible candidate, dispatch `Agent(subagent_type="build-loop:promotion-reviewer", ...)` with brief fields: `artifact_path`, `experiment_log`, `sample_size`, `target_metric`, `triggering_run_id`, `recent_judge_decisions`.
+   - Append the returned verdict object to the run's `judge_decisions[]` via `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/write_run_entry/__main__.py --judge-decisions-json <verdict.json>` (combined with other Phase 4 verdicts if any).
+   - Compose the user-facing notification body from the verdict's `variances[]` and `meta_guidance`. Fire `PushNotification` if available; fall back to `TaskCreate` with subject `"[BUILD-LOOP] Promotion candidate <name>: <verdict> — review needed"`.
+   - Write a marker file at `.build-loop/proposals/<name>.pending.md` with the verdict + how-to-confirm so the user can resume context later (TTL 14 days; lapsed candidates auto-archive to `.build-loop/proposals/<name>.lapsed.md`).
+   - **Do not move the artifact.** The user-invoked `/build-loop:promote-experiment <name>` command performs the move after reading the pending verdict.
+
+6. **Notify** — concise synthesis appended to Review sub-step G report, including: (a) removal command for each artifact moved or proposed, (b) for each pending promotion: the reviewer verdict + confirmation command.
+
+**Always-run + report gating (v0.30.0)**
+
+Phase 6 has NO "skip entirely" condition. Three outcome states cover every run:
+
+| State | Trigger | What runs | Review-G `## Learn` line |
+|---|---|---|---|
+| **Accruing** | `runs[] < 3` | Detector + consolidation only (no Sonnet draft) | `Learn: accruing (N/3 runs)` |
+| **Deferred** | debug-only (`closeout: false` in dispatch envelope) OR budget-exhausted (`budget_check` envelope `action == "finalize_and_stop"` at Phase 6 entry) | Detector + consolidation; write `.build-loop/proposals/learn-deferred-<run-id>.md` marker with `{reason, runs_count, budget_action}`; skip Sonnet draft + Opus signoff | `Learn: deferred — <reason>` |
+| **Full** | `runs[] >= 3` AND detector returned a pattern AND not deferred | Detector + consolidation + Sonnet draft + Opus signoff + sample sweep | `Learn: <N> patterns drafted` (or `Learn: 0 patterns above threshold (N runs scanned)` when detector returned nothing) |
+
+**Deprecated escape hatch (migration no-op).** `.build-loop/config.json.autoSelfImprove: false` is no longer honored. It is read for migration safety: when present and `false`, the orchestrator appends a one-line `state.json.warnings[]` entry (`"autoSelfImprove: false is deprecated; ignored (migration no-op)"`) and proceeds as if the key were absent. Old user configs do not error. Remove the key at your convenience.
+
+**User control (unchanged safety boundary)**:
+- Remove any artifact: `rm -rf .build-loop/skills/experimental/<name>/` or `active/<name>/`
+- Block re-promotion of a name: add it to `.build-loop/skills/.demoted`
+- Inspect tracking: `cat .build-loop/experiments/<name>.jsonl`
+- Promotion to `active/` STILL requires explicit `/build-loop:promote-experiment <name>` (decision-3 safety boundary preserved — auto-promote of unreviewed drafts never happens).
+- Auto-promote defaults to OFF — set `"autoPromote": true` to enable (requires effective sample ≥ 8).
+
+**What this phase will NOT do**:
+- Modify the build-loop plugin repo
+- Promote artifacts cross-project without explicit `/build-loop:promote-experiment <name>`
+- Run more than once per build

package/skills/build-loop/references/recent-design-structures.md

@@ -0,0 +1,274 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Recent Design Structures
+
+Runtime reference for `design-contract-specialist` when choosing UI design direction. This file is a compact structure library, not a style mandate.
+
+## Use Rule
+
+Pick the structure that fits the current product job, workflow frequency, information density, data shape, platform, and risk. Do not apply a structure because it is recent, rated well, visually attractive, or available in this file.
+
+Every Phase 2 `## Design Direction` should record:
+
+1. `selected_structure`
+2. `why_it_fits`
+3. `rejected_structure`
+4. `why_rejected`
+5. `source_refs`
+6. `validation_implications`
+
+## Selection Axes
+
+Classify the surface before choosing structure:
+
+| Axis | Questions |
+|---|---|
+| Product job | Is the user operating, deciding, conversing, building, analyzing, configuring, recovering, or learning? |
+| Workflow frequency | Is this a repeated work surface, a one-time onboarding path, or an occasional settings/detail surface? |
+| Data shape | Is the core object a message, list, table, step sequence, chart, document, graph, timeline, or media artifact? |
+| Density | Does the user need scan, compare, decide, or deeply read? |
+| Platform | Web desktop, mobile web, native iOS, macOS, watchOS, or cross-platform? |
+| Risk | Could a wrong click, fake affordance, hidden source, or misleading chart cause harm? |
+
+## Structures
+
+### 1. Conversational Command Surface
+
+Use when the product starts from user intent in natural language but must produce a concrete artifact, decision, skill, or task output.
+
+Structure:
+- Header with product identity and one primary action.
+- Two-lane layout: conversation/input lane plus outcome/status lane.
+- Composer is prominent but not the whole product when outputs matter.
+- Suggested prompts are subordinate; they are accelerators, not competing primary actions.
+- Output cards show concrete value, feasibility, or next step.
+
+Good fit:
+- AI assistants that build artifacts.
+- Intake-to-plan flows.
+- "Tell me the problem, then ship the output" products.
+
+Reject when:
+- The user primarily monitors many standing objects.
+- The user needs direct table/list management more than conversation.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-01-sunrise-hero.html`
+- `UI Guidance/mockups/evaluation-workbench--v2-02-electric-mint.html`
+- `UI Guidance/mockups/evaluation-workbench--v2-05-bloom-organic.html`
+
+### 2. Bento Operating Dashboard
+
+Use when the product is a repeated home base with multiple live objects, one central creation/ask action, and several scannable operational tiles.
+
+Structure:
+- Hero ask/action tile dominates.
+- Secondary tiles show ledger, active objects, queue, and quick decisions.
+- Use a 12-column grid on desktop; cards span according to importance.
+- Keep the chat/action as one tile, not the whole app.
+- The dashboard should answer: what is active, what changed, what is next, what can I do now?
+
+Good fit:
+- Personal operating systems.
+- Product home screens where the user returns often.
+- Workflow dashboards with useful standing state.
+
+Reject when:
+- The user has one linear task.
+- The product has no real standing data.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-04-bento-dashboard.html` (rated yay)
+
+### 3. Pipeline Wizard
+
+Use when a multi-step process needs visible progress, traceable decisions, and contextual input for each step.
+
+Structure:
+- Top stepper with 3-5 named steps.
+- Current step panel owns the main content.
+- Contextual chat/input lives beside or below the current step.
+- Each step exposes criteria, intermediate output, and next action.
+- Final step produces a concrete artifact or decision.
+
+Good fit:
+- MCDA, evaluation, diagnosis, onboarding, build pipelines.
+- Workflows where the user should understand why the next step exists.
+
+Reject when:
+- Steps are decorative or could be one form.
+- The user needs fast repeated scanning instead of guidance.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-03-pipeline-wizard.html`
+
+### 4. Outcome Ledger List
+
+Use when the user needs to scan a collection of prior decisions, jobs, skills, or outcomes and understand value quickly.
+
+Structure:
+- Summary/ledger hero at top.
+- Filter chips directly below the hero.
+- List cards include title, category/status, primary outcome metric, and next affordance.
+- Rows must be scannable in about 2 seconds.
+- Empty state preserves layout height and names what will appear.
+
+Good fit:
+- Decision history, saved automations, skill libraries, task queues, project ledgers.
+
+Reject when:
+- The collection has no reliable outcome metric.
+- Detail reading is more important than list scanning.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-06-decisions-list-fun.html`
+
+### 5. Pyramid Detail Page
+
+Use when a detail view must replace a wall of text with a decision-first hierarchy.
+
+Structure:
+- Hero states the primary outcome in plain language.
+- Three MECE supporting cards explain why.
+- This-week/current-impact section makes near-term value concrete.
+- Paired paths section shows viable alternatives without nudging.
+- MCDA/math/provenance sit under disclosure.
+- Keep no more than 5 major chunks visible at once.
+
+Good fit:
+- Decision details, recommendation details, audit explanations, strategy outputs.
+
+Reject when:
+- The user needs raw source review as the primary job.
+- There is no actual decision, outcome, or rationale to explain.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-07-detail-fun.html`
+
+### 6. Glass Workspace
+
+Use for data-rich professional tools where the user manages structured information and needs craft without losing density.
+
+Structure:
+- Sidebar or stable navigation when object count is high.
+- Left-border accent as category/status signal.
+- Source dot plus text metadata, not separate badge clutter.
+- Card grid uses `repeat(auto-fill, minmax(300-320px, 1fr))` at desktop.
+- Optional third detail pane at 280-320px for focused review.
+
+Good fit:
+- Developer tools, knowledge bases, dashboards, pipeline monitors.
+
+Reject when:
+- The surface is mobile-first, reading-heavy, or calm/clinical.
+- Glass effects would reduce contrast or obscure content.
+
+Recent refs:
+- `UI Guidance/cross-platform-design-patterns.md`
+- `UI Guidance/aurora-deep.md`
+- `UI Guidance/aurora-glass.md`
+
+### 7. Warm Craft Workbench
+
+Use for reflective writing, document work, knowledge organization, or human-feeling tools where warmth helps trust and comprehension.
+
+Structure:
+- Warm neutral base with restrained amber/coral accents.
+- Left accent bar connects cards, navigation, and section headers.
+- Sectioned sidebar or grouped content blocks.
+- Generous but structured spacing.
+- Texture is enhancement only; content structure must work without it.
+
+Good fit:
+- Writing tools, personal knowledge systems, review surfaces, human-in-the-loop planning.
+
+Reject when:
+- The user needs dense operational monitoring.
+- Warm palette could make risk, status, or urgency ambiguous.
+
+Recent refs:
+- `UI Guidance/warm-craft.md`
+- `UI Guidance/cross-platform-design-patterns.md`
+
+### 8. Data Narrative
+
+Use when the UI presents research, trends, news, benchmarks, or evidence and needs to tell the user what matters before showing the raw data.
+
+Structure:
+- Decision-first title or subtitle above every chart.
+- Dark atmospheric hero is allowed only when it introduces the domain; dense content should move to a readable light or neutral area.
+- Bento/grid sections can organize evidence, but every chart needs a reason to exist.
+- Source attribution is visible near the chart or section.
+
+Good fit:
+- Market research, briefing, analytics, trend reporting, intelligence products.
+
+Reject when:
+- The data is too sparse or unreliable.
+- A sentence would communicate the answer better than a chart.
+
+Recent refs:
+- `UI Guidance/data-visualization-patterns.md`
+- `UI Guidance/cross-platform-design-patterns.md`
+
+### 9. Native Mobile Action System
+
+Use for native or mobile-web surfaces where touch certainty, safe areas, and progressive disclosure matter more than desktop density.
+
+Structure:
+- One hero CTA per home screen.
+- Touch targets: 44pt/px minimum; primary capture actions can be larger.
+- Every mobile-web touchable has a visible resting container; do not rely on hover/cursor.
+- Expandable cards beat sheets/modals when comparison and context retention matter.
+- Design tokens cover colors, radius, elevation, and typography; raw numbers are exceptions.
+- Haptics, button spring physics, and elevation communicate action feedback on native platforms.
+- Liquid Glass belongs on navigation-layer controls only, availability-gated for iOS 26+, not stacked on content cards.
+
+Good fit:
+- Native iOS/macOS companion apps, mobile web tools, timer/voice/drill/session surfaces.
+
+Reject when:
+- The app is desktop-primary and comparison density is the core job.
+- Touch affordance choices would add visual noise to a pointer-first surface.
+
+Recent refs:
+- `interface-built-right/mobile-ui/patterns/expandable-card-pattern.md`
+- `interface-built-right/mobile-ui/patterns/design-token-architecture.md`
+- `interface-built-right/mobile-ui/patterns/liquid-glass-ios26.md`
+- `interface-built-right/mobile-ui/lessons/mobile-web-action-affordance.md`
+- `interface-built-right/mobile-ui/lessons/home-screen-simplification.md`
+
+### 10. AI Artifact Canvas
+
+Use when the user is generating or editing a durable artifact, not just receiving a chat answer.
+
+Structure:
+- Split input/control lane from artifact canvas.
+- Artifact gets stable identity, autosave, status, and version/undo affordance.
+- Regeneration is scoped per section/block when possible.
+- Loading states preserve layout and show phase, not generic spinners.
+- Source/citation/provenance spine stays visible when claims matter.
+
+Good fit:
+- Document generation, research briefs, reports, code/spec generation, design drafts.
+
+Reject when:
+- Output is disposable or single-turn.
+- The product has no artifact lifecycle.
+
+Recent refs:
+- UI-guidance memory family: AI-generation UX additions, source-grounded trust, semantic zoom.
+
+## Cross-Cutting Rules
+
+- Typography and text hierarchy come before surface treatment.
+- Color tokens come before gradients, shadows, texture, or glass.
+- Left-border accents are useful categorical structure, but not mandatory on every product.
+- Status should not be a decorative pill by default; use text, weight, and placement unless a platform/system component requires a badge.
+- Charts require a confidence gate: at least 3 comparable points, trustworthy source, and a pattern/comparison/trend that text alone would not communicate as well.
+- Motion is final polish and must respect reduced-motion settings.
+- Empty, loading, error, disabled, success, permission, and overflow states are part of the structure, not afterthoughts.
+
+## Long-Term Memory Boundary
+
+This file is the short-horizon runtime reference. Durable cross-project lessons, rating history, and changes over time live in `build-loop-memory`, especially decisions under `decisions/build-loop/`. Update build-loop-memory when a new structure is repeatedly used, explicitly selected/rejected, or materially changes build-loop's design-selection policy.

package/skills/build-loop/references/refactor-history/ASSESSMENT.md

@@ -0,0 +1,85 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Assessment: 9→5 Phase Refactor (PR #4)
+
+**Date**: 2026-04-20
+**Branch**: `feat/5-phase-refactor` (stacked on #3 → #2 → #1)
+**Scope**: verify the refactor is safe to merge by comparing old vs new behavior across three representative scenarios, and confirm the bridge-cherry-pick principle holds.
+
+## Method
+
+Sandbox traces, not live execution. The installed build-loop plugin is still pre-PR-1 (no Phase 9, no bridges), so actually running `/build-loop` wouldn't exercise the new flow. Instead, three scenario fixtures with expected orchestration traces under OLD 9-phase vs NEW 5-phase, annotated for fidelity and any behavior changes.
+
+## Scenarios
+
+| # | Scenario | Plugins | Expected iterations | Sub-steps exercised |
+|---|---|---|---|---|
+| 1 | Simple bugfix | none | 0 | A, B, D, F |
+| 2 | UI build with one Iterate cycle | IBR, debugger | 1 | A, B (×2), D, E, F |
+| 3 | Multi-failure w/ logging-tracer rescue | NavGator, debugger | 2 | A, B (×3), C, D, E, F + logging-tracer bridge + debugger bridge |
+
+Details: `scenarios/01`, `scenarios/02`, `scenarios/03`. Side-by-side traces: `traces/comparison.md`.
+
+## Fidelity checks (all 3 scenarios)
+
+Every old-flow artifact has a new-flow equivalent:
+
+| Old artifact | New location | Preserved? |
+|---|---|---|
+| Phase 1 state summary + Phase 2 goal.md | Phase 1 Assess (combined) | ✅ |
+| Phase 3 plan | Phase 2 Plan | ✅ |
+| Phase 4 implementer diff | Phase 3 Execute | ✅ |
+| Phase 4.5 critic output | Review sub-step A | ✅ — same agent (`sonnet-critic`) |
+| Phase 4.7 optimize results | Review sub-step C | ✅ — opt-in preserved |
+| Phase 5 scorecard | Review sub-step B evidence | ✅ |
+| Phase 7 fact-check + mock-scan + navgator rules | Review sub-step D (three parallel gates) | ✅ |
+| Phase 8 scorecard file + state.json append | Review sub-step F | ✅ — same paths |
+| Phase 8.5 simplified diff | Review sub-step E | ✅ |
+| Phase 9 REVIEW (self-improve) | Phase 6 Learn | ✅ — skill file name preserved (`build-loop:self-improve`) |
+| Iterate loop back to Validate | Iterate → Review-B | ✅ — identical convergence rules |
+
+**Zero silent eliminations.** Two intentional semantic changes documented below.
+
+## Intentional behavior changes (not regressions)
+
+1. **Critic (A) skips on re-runs of Review after Iterate, unless Iterate touched different files.** Saves tokens on unchanged scope review. Old flow ran CRITIC Phase 4.5 only once pre-Validate anyway; new flow preserves that timing but makes it explicit for Iterate loops.
+
+2. **Simplify (E) runs BEFORE Report (F), not after.** Old flow: Phase 8.5 Simplify ran after Phase 8 Report — scorecard reflected pre-simplified diff. New flow: scorecard reflects the actually-shipped diff. Arguably a correctness improvement.
+
+3. **Iterate loops back to Review-B (Validate), not to its own re-validation.** Cleaner separation: Iterate = fix; Review = evaluate. Same convergence rules, same 5-attempt cap, same debugger escalation ladder.
+
+## Bridge cherry-pick audit (criterion C4)
+
+Source grep for embedded logic vs delegation:
+
+**navgator-bridge:** no function/class definitions. Only filesystem reads (`.navgator/architecture/*.json`) + CLI delegation (`navgator impact`, `rules`, `llm-map`, `dead`). Writes only to its own `state.json.navgator.*` namespace. ✅ cherry-pick clean.
+
+**debugger-bridge:** no function/class definitions. Only MCP delegation (`mcp__plugin_claude_code_debugger__{search,store,outcome,read_logs,list}`) + skill invocation (`build-loop:{debugging-memory,assess,debug-loop}`). Writes only to its own `state.json.debuggerGates.*` namespace. ✅ cherry-pick clean.
+
+**logging-tracer-bridge:** contains inline Tier-1 helper code (5-8 lines per language: Node, Python, Go, Rust). This is the fallback when `availablePlugins.claudeCodeDebugger` is false. When upstream IS available, bridge delegates (line 54 of SKILL.md). Tier 2 and Tier 3 are explicitly documented as requiring upstream. ✅ graceful degradation, not embedding.
+
+All three now have an explicit `## Cherry-pick principle` block (added in this commit) documenting what the bridge does and does not do.
+
+## Verdict
+
+| Criterion | Result |
+|---|---|
+| C1 Three scenarios covering diverse loop paths | ✅ |
+| C2 Old vs new traces side-by-side | ✅ |
+| C3 No silent regressions (fidelity check) | ✅ |
+| C4 Bridges cherry-pick, don't embed | ✅ |
+| C5 Each bridge states cherry-pick principle explicitly | ✅ |
+| C6 Amend PR #4 if C3/C4 fail | N/A (both passed) |
+
+**PR #4 safe to merge on sandbox evidence.** Next validation requires live consumer `/build-loop` execution — flagged as known gap in PR #4 body already.
+
+## Residual cleanup (known, not blocking)
+
+Secondary files still reference old phase numbers in spots:
+- `skills/build-loop/fallbacks.md`
+- `skills/build-loop/eval-guide.md`
+- `skills/build-loop/phases/fact-check.md`
+- `skills/optimize/SKILL.md`
+- `commands/optimize.md`
+
+Meanings still work (e.g., "during validation" reads correctly either way), but labels don't match new canonical names. Low-priority follow-up, not blocking for #4.

package/skills/build-loop/references/refactor-history/STANDALONE_TEST_RUN.md

@@ -0,0 +1,149 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Standalone Fallback Test Run — Live Output
+
+**Date**: 2026-04-20
+**Method**: Run each fallback's actual grep/git commands against real projects. This is not a trace simulation — the commands were executed and the output captured below.
+
+## 1. `fallbacks.md#web-ui` against example-app
+
+Target: `<example-app-repo>` — real Next.js app with `components/` and `app/` directories, no IBR installed at scan time. 5 of the 10 grep checks spot-checked.
+
+### Check 1: Gestalt violations (borders on `.map()` items)
+```
+grep -rn "\.map(" --include="*.tsx" --include="*.jsx" components/ app/ | grep -B1 -A5 "border\|rounded-"
+```
+**Result**: 0 matches in spot sample. (Narrower grep heuristic; a full scan against the `git diff` scope would catch more.)
+
+### Check 3: Buttons missing onClick/submit
+```
+grep -rnE "<button[^>]*>" --include="*.tsx" --include="*.jsx" components/ app/ | grep -v "onClick\|type=.submit.\|type=.reset."
+```
+**Result**: **9 real matches**. Actionable findings:
+
+- `components/v3/V3FeedPage.tsx:1024` — `<button className="text-sm hover:text-blue-300">Save All</button>`
+- `components/v3/V3FeedPage.tsx:1025` — `<button ...>Export</button>`
+- `components/v3/V3FeedPage.tsx:1026` — `<button ...>Hide All</button>`
+- `components/SearchTimeline.tsx:152` — `<button ...>See all</button>` (inferred from context)
+- `components/GroupedLayout.tsx:79`, `components/TrendingEntities.tsx:85`, `components/SidebarLayout.tsx:82`, `components/TabViewLayout.tsx:114`, `app/versions/claude-session/page.tsx:420`
+
+Three "Save All" / "Export" / "Hide All" buttons with no onClick — **these are real production bugs**. The fallback surfaced them.
+
+### Check 5: Icon-only buttons missing aria-label
+**Result**: 0 matches — example-app is clean on this.
+
+### Check 9: Console leftovers in production paths
+```
+grep -rnE "console\.(log|error|warn|debug)" --include="*.ts" --include="*.tsx" components/ app/ | grep -v "\.test\.\|\.spec\.\|__tests__/"
+```
+**Result**: 5 real matches. Actionable findings:
+
+- `components/visualization/ChartDecisionEngine.ts:390` — `console.log('[ChartDecisionEngine] Timeline intent detected...')`
+- `components/visualization/FactsChart.tsx:411` — `console.log('[FactsChart] Timeline intent detected...')`
+- `components/PyramidSummary.tsx:81` — `console.log('[PyramidSummary] Parsed markdown pyramid:', ...)`
+- `components/settings/SettingsPanel.tsx:112` + `:140` — `console.error('Failed to ...:', error)` (arguably OK for error paths, flag as warning)
+
+### Summary — `#web-ui`
+
+| Check | Matches | False positives | Real bugs |
+|---|---|---|---|
+| Gestalt borders | 0 | — | 0 |
+| Touch targets | skipped (Tailwind class-based, needs second pass) | — | — |
+| Button handlers | 9 | 0 (all real) | 3 clear bugs (Save/Export/Hide) + 6 likely bugs |
+| Anchors | skipped | — | — |
+| Icon aria-label | 0 | — | 0 |
+| Status pills | skipped | — | — |
+| Hex colors | skipped | — | — |
+| Non-8pt spacing | skipped | — | — |
+| Console leftovers | 5 | 2 (error paths) | 3 clear (log in production) |
+| Mock data | skipped | — | — |
+
+**Verdict**: fallback catches real bugs. Precision > 80% on the two checks run. Not browser-driven — IBR would catch more (hydration, computed CSS, render errors) — but this is 10× better than "skip silently."
+
+## 2. `fallbacks.md#architecture` against build-loop repo
+
+Target: build-loop itself, with 20 files changed on `feat/5-phase-refactor` vs main.
+
+### Check 1: Changed files
+```
+git diff --name-only origin/main..HEAD
+```
+**Result**: 20 files, all enumerated cleanly.
+
+### Check 2: Layer classification
+**Result**: (adapted case statement for plugin repo — the default fallback is web-app-centric)
+
+| Layer | Count |
+|---|---|
+| skill (skills/*/SKILL.md) | 5 |
+| agent (agents/*.md) | 5 |
+| command | 1 |
+| docs | 5 |
+| root-doc | 4 |
+
+Clean categorization. Note: the fallback's default layer classification is web-app-centric (`src/db/*`, `src/api/*`, etc.) — didn't match this plugin repo perfectly. For non-web-app targets, the fallback falls back to "other." Documented as a known limitation.
+
+### Check 4: Git-churn hotspots (last 100 commits)
+```
+git log --pretty=format: --name-only -100 | sort | uniq -c | sort -rn | head
+```
+**Result**:
+```
+16 skills/build-loop/SKILL.md
+14 agents/build-orchestrator.md
+ 7 skills/debugger-bridge/SKILL.md
+ 6 README.md
+ 6 CLAUDE.md
+ 5 skills/navgator-bridge/SKILL.md
+ 5 .claude-plugin/plugin.json
+```
+
+Hotspots match intuition: the two most-edited files in the refactor (SKILL.md and build-orchestrator.md) are correctly identified as hotspots. **This is exactly the signal Plan would use to chunk the work.**
+
+### Summary — `#architecture`
+
+**Verdict**: produces real signal. Git-churn hotspot detection is solid. Layer classification is limited by the web-app-centric case statement — works great for typical Next.js / Express apps, falls back gracefully for plugin/docs repos. For build-loop-on-build-loop (meta), the fallback says "other" a lot, which is honest.
+
+## 3. `fallbacks.md#bug-memory` against build-loop's `.build-loop/feedback.md`
+
+Simulated symptom: "YAML frontmatter invalid — description has unquoted colons" (the actual Codex adversarial-review finding from earlier in this session).
+
+### Token extraction
+```
+echo "YAML frontmatter invalid description has unquoted colons" | tr ' ' '\n' | grep -E '^[A-Z][a-zA-Z]+$|...'
+```
+**Result**: `YAML, invalid`
+
+### Grep matches
+**Result**: `.build-loop/feedback.md` matched. Actual content retrieved:
+
+```
+2026-04-20 | Hardening-validation build-loop run found 4 residual "8-phase" refs missed by previous 9-phase doc sweep | Add a pre-commit check that greps for "8-phase"|"eight phase" whenever .build-loop/goal.md references phase counts, so canonical phase-count drift surfaces before commit.
+```
+
+The fallback surfaced a relevant prior lesson (the hardening run that caught residual refs — analogous situation).
+
+### Verdict (4-state)
+**Result**: `LOCAL_WEAK` — 1-2 tokens matched. Would be referenced in the Iterate plan but not direct-applied.
+
+### Summary — `#bug-memory`
+
+**Verdict**: works. Produces a verdict in the correct shape (4 states mirroring upstream). Returns meaningful context from `feedback.md` when tokens hit. `LOCAL_NO_MATCH` when empty — no false-positive reuse.
+
+## Overall assessment
+
+All three fallbacks were executed live against real targets and produced actionable output:
+
+- **web-ui**: caught 3 clear production bugs + 3 log leftovers in example-app
+- **architecture**: correctly identified the two most-churned files as hotspots in build-loop
+- **bug-memory**: surfaced a relevant prior lesson from `feedback.md`
+
+**Nothing was silent that should have fired.** The "skip silently" pre-fallback behavior would have missed all of the above.
+
+### Known limitations (called out to users)
+
+1. **web-ui Tailwind**: touch-target check only catches explicit `w-*px` attributes, not Tailwind utility classes. Second-pass regex needed.
+2. **architecture layer classification**: web-app-centric. Plugin repos, docs repos, Python projects fall back to "other."
+3. **bug-memory token extraction**: simple regex. Misses multi-word phrases, foreign-language error messages.
+
+All three are documented in `fallbacks.md` with the `⚠️ install <plugin> for deeper analysis` flag. Users are never led to believe the fallback replaces the upstream — just that it catches the most common failures.

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

@@ -0,0 +1,32 @@
+<!-- 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/skills/build-loop/references/refactor-history/scenarios/02-ui-build-with-iteration.md

@@ -0,0 +1,48 @@
+<!-- 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