@tyroneross/build-loop 0.30.3 → 0.35.0

package/plugin-artifacts/codex/skills/build-loop/references/capability-routing.md

@@ -0,0 +1,182 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Capability Routing (full protocol)
+
+> Loaded from `skills/build-loop/SKILL.md` summary. Contains the full capability routing table, trigger conditions, and plugin/hook/skill/agent mandatory routing rules.
+
+## Capability Routing
+
+Build-loop prefers repo-owned agents and bundled skills for core loop decisions. External plugins are accelerators only when explicitly requested or when a row below names them as secondary. Each capability has three tiers: **preferred** (build-loop-owned surface) → **secondary** (another installed plugin or skill that can partially cover) → **inline fallback** (guidance text from `fallbacks.md`, injected verbatim into subagent prompts).
+
+Phase 1 runs `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs` and writes the result to `.build-loop/state.json` under `availablePlugins`. All routing consults that object.
+
+### Core loop skills/assets (always check)
+
+| Skill | Used In | Fallback |
+|-------|---------|----------|
+| `writing-plans` | Phase 2 (Plan) | Write a structured plan directly: goal, tasks with exact file paths, dependency order, test commands |
+| `subagent-driven-development` | Phase 3 (Execute) | Dispatch parallel agents manually using the host's available delegation tool for independent file groups |
+| `verification-before-completion` | Phase 4 sub-step G (Report) | Run all test/build/lint commands and confirm output before claiming completion. For app/UI changes this is NOT sufficient alone — also run the runtime UI⇄source-of-truth parity check (`runtime-parity-verification`); compile-green and a screenshot do not prove the running flow works |
+| `runtime-parity-verification` | Phase 4 Review-B + Phase 5 Iterate (any `uiTarget != null` or user-visible flow) | Cross-check the rendered/queryable UI against the authoritative backend (DB/API/daemon/tool-state), screen-independently, and keep a validated per-repo smoke. Catches the "action does nothing / not showing / shows empty despite real data / stale projection" class. Drivers: web `ui-validator`; macOS `native-ax-driver` / IBR `scan_macos`; iOS `idb`; agent = tool-result vs rendered output. Reference smoke: easy-terminal `tools/smoke_launch.py` |
+| `simplify` (slash: `/simplify`) | Phase 4 sub-step E (Simplify) | Self-review the diff: remove scaffolding, inline single-use helpers, delete dead branches |
+| `complexity_detector.py` (accelerator, not a gate) | Phase 4 sub-step E (Simplify) | Diff-scoped stdlib-AST hotspot detector for changed Python; surfaces high-severity hotspots for a simpler rewrite, apply-vs-advise via existing Review-B + independent-auditor. Optional Python aid — the default Simplify pass reasons over the diff language-agnostically (see `phase-4-review.md` §"Sub-step E: Simplify") |
+| `build-loop:self-improve` | Phase 6 (Learn) | Scan recent runs for recurring patterns, auto-draft experimental skills/agents with A/B tracking, notify user for keep/remove decisions |
+| Intent capability pack | Phases 1-4 | Read `references/intent-capability-pack.md`; write `.build-loop/intent.md`; pass the intent packet to every subagent |
+| Modular systems pack | Phases 1-4 | Read `references/modular-systems-pack.md`; partition files/tasks MECE; prefer modular scalable boundaries unless an exception is documented |
+| Codex subagent adapter | Phase 3 (Execute, Codex only) | Read `references/codex-subagents.md`; use `templates/codex-worker-prompt.md` for authorized Codex workers |
+
+### Phase quick reference
+
+| # | Phase | Purpose | Sub-steps / key actions |
+|---|---|---|---|
+| 1 | **Assess** | Understand state + define goal & criteria | detect tools, map architecture, load memory, write `intent.md` + `goal.md` |
+| 2 | **Plan** | Break work, identify parallel-safe, optimize | writing-plans skill → dependency graph |
+| 3 | **Execute** | Build per plan | parallel subagents, Sonnet default, Opus escalation |
+| 4 | **Review** | Critic → Validate → Optimize (opt-in) → Fact-Check → Simplify → Auto-Resolve → Report | sub-steps A-G; B-D can route to Iterate; F drains non-destructive items via autonomy_gate; G runs only on final pass |
+| 5 | **Iterate** | Fix Review failures, loop back to Review | max 5x; orchestrator stuck-iteration cascade (evidence-gap repair → memory re-check → parallel assess at 2 fails → causal-tree at 3 fails) |
+| 6 | **Learn** | Cross-build pattern detection + experimental skill drafting | optional; requires `runs[] >= 3`; auto-promote opt-in |
+
+### Capability routing table
+
+| Capability | Preferred | Secondary | Inline fallback section |
+|---|---|---|---|
+| Web UI build | `build-loop:ui-design` + `build-loop:design-contract-specialist` (`trigger_point: phase2-design-direction`) + `calm-precision` + `templates/ui-subagent-prompt.md` | `frontend-design:frontend-design` only when explicitly requested | `fallbacks.md#web-ui` |
+| Web UI validation | `ui-validator` agent + `audit-design-rules.mjs` + browser/screenshot artifact | `showcase:capture` for visual evidence | `fallbacks.md#web-ui` |
+| Orchestrated UI build | `build-loop:ui-design` → build-loop-owned design direction → implementer fan-out → ui-validator/design-contract reconciliation | explicit user-invoked design tool artifacts passed to `design-contract-specialist` | `fallbacks.md#web-ui` |
+| Mobile UI build (`uiTarget: "mobile"` — iOS/watchOS sim) | `build-loop:ui-design` + `build-loop:design-contract-specialist` + `calm-precision` + `apple-dev` | — | `fallbacks.md#mobile-ui` + `fallbacks.md#apple-dev` |
+| Mobile UI validation (iOS sim) | `xcrun simctl io booted screenshot` for static; `idb ui tap` for interaction | `showcase:capture` | `fallbacks.md#mobile-ui` |
+| macOS desktop UI build (`uiTarget: "macos"`) | `build-loop:ui-design` + `build-loop:design-contract-specialist` + `calm-precision` + `apple-dev` | — | `fallbacks.md#mobile-ui` + `fallbacks.md#apple-dev` |
+| macOS desktop UI validation | IBR `scan_macos` when `availablePlugins.ibr == true`; else `native-ax-driver` against the running `.app` (pid-anchored). NEVER `xcrun simctl` (no macOS simulator). NEVER `nm`/`strings` as substitute. | `showcase:capture` for screenshot evidence | `fallbacks.md#mobile-ui` |
+| Design system tokens | `design-contract-specialist` reads project token/theme/component files and records the source in `.build-loop/app-contract/ui.md` | — | `fallbacks.md#design-tokens` (reads consumer project's token files — never hardcodes) |
+| Recent design structures | `design-contract-specialist` reads `references/recent-design-structures.md` and selects by product/workflow/data fit | explicit design-tool artifacts passed as evidence | `fallbacks.md#web-ui` |
+| Screenshot / visual evidence | `showcase:capture`, `showcase:record` | `screenshot` MCP tool | `fallbacks.md#screenshot` |
+| Web content fetching (low LLM) | `scraper-app:web-scraper` SDK | — | `fallbacks.md#web-fetch` (flags LLM cost in report) |
+| Deep debugging | `build-loop:debug-loop` + `build-loop:debugging-memory` native search/store | standalone Coding Debugger only when explicitly installed for cross-project memory | `fallbacks.md#debug` |
+| Bug-pattern memory | `build-loop:debugging-memory` | — | `fallbacks.md#bug-memory` (greps `.build-loop/issues/` + `.bookmark/`) |
+| Agent authoring | `agent-builder:agent-builder-anthropic` | `plugin-dev:agent-development` (if plugin work) | `fallbacks.md#agent-authoring` |
+| DeepAgents / local-LLM agent work | `build-loop:building-with-deepagents` (SubAgent API, middleware stack, per-agent tool scoping, anti-patterns) | — | Read installed `deepagents` source: `python3 -c 'import deepagents, os; print(os.path.dirname(deepagents.__file__))'` then `graph.py` + `middleware/subagents.py` |
+| Structured reports / handoffs | `pyramid-principle:pyramid-short-form` (Review-F reports), `pyramid-long-form` (design docs) | — | `fallbacks.md#structured-writing` (SCQA + MECE skeleton) |
+| Hosted-IDE migration (Replit / Lovable / Bolt / v0) | `replit-migrate:migration-scan`, `migrate-web`, `migrate-ios`; MCP tools `migrate_scan`, `migrate_plan_web`, `migrate_plan_native`, `migrate_map_apis`, `migrate_map_models`, `migrate_check_progress` | — | `fallbacks.md#migration` (manual inventory + stack-translation) |
+| Prompt authoring / review / audit (system prompts, agent prompts, eval judges) | `prompt-builder:prompt-builder` skill; slash commands `/prompt-builder:optimize`, `/score`, `/compare`, `/save`, `/list`. Calibrates to model tier (T1/T2/T3) and deployment (interactive, backend, rag_pipeline, agent, plugin, eval_judge, personal_mobile). Returns 6-Part-Stack prompt + 5-dim score + diagnosis + `[ASSUMED:]` tags + `TEMPERATURE_HINT` | `prompt-builder` (personal skill, same name, loaded via Skill tool) | `fallbacks.md#prompt` |
+| iOS / watchOS / macOS dev + deploy | `apple-dev` personal skill (via `Skill("apple-dev")`) | `replit-migrate:migrate-ios` (when migrating *to* native) | `fallbacks.md#apple-dev` |
+| Web deploy verification (Vercel) | Vercel MCP (`mcp.vercel.com` remote OAuth, only if user adds it to `.mcp.json`) | Vercel CLI via `scripts/verify_deploy.py` | `fallbacks.md#web-deploy-verify` |
+| Strategic frame / PRD grounding (Assess + Review) | `build-loop:prd-bridge` — reads `docs/prd-*.md` frontmatter (`core_principles`, `load_when`) + Navigation Map + Section Index in Phase 1; verifies diff doesn't violate principles in Phase 5 Fact-Check; recommends `prd-builder` skill if no PRD exists. Falls back to grep on principle keywords if frontmatter parser unavailable. | `prd-builder` skill direct invocation | Phase 1 captures north-star + intent fresh into `intent.md` (existing fallback) |
+| Architecture scan / impact trace (Assess + Review) | `build-loop:architecture-scan` (Assess refresh), `build-loop:architecture-impact` (blast-radius), `build-loop:architecture-rules` (Review violation check), `build-loop:architecture-dead` (orphan scan) — read `.navgator/architecture/` JSON; native skills sourced from NavGator with provenance and drift-detection via `build-loop:sync-skills` | `gator:*` commands if installed | Read component → edit → re-read downstream |
+| Debugger memory-first gate (Review + Iterate) | `build-loop:debugging-memory` — verdict gate (`KNOWN_FIX` / `LIKELY_MATCH` / `WEAK_SIGNAL` / `NO_MATCH`) with strict direct-apply triple-gate (file + version + secondary signal) and Review-F outcome feedback. Orchestrator owns the when-to-fire policy (Review-B + every Iterate attempt) and routes to this skill. | `build-loop:debug-loop` direct (when memory says enter the loop or 3 same-criterion failures) | `fallbacks.md#debug` |
+| Runtime visibility / observability (Assess + reactive Review/Iterate) | `build-loop:logging-tracer` — generates stack-appropriate structured logging / OTel with ephemeral-by-default policy (Mechanism A: `DEBUG_TRACE=1` runtime gate; Mechanism B: `git-stash` throwaway). Invoked reactively when an Iterate attempt flags `evidence_gap: true`. Orchestrator runs the passive Assess scan inline (no skill call needed) and only loads this skill when instrumentation is actually being added. | — | `fallbacks.md#logging-fallback` (inline Tier-1 zero-dep JSON logger per stack) |
+| Self-improvement / recurring pattern detection (Phase 6 Learn) | `build-loop:self-improve` — runs after every build; detects recurring failures and manual interventions; drafts experimental skills/agents to `.build-loop/skills/experimental/`. Auto-promote to `.build-loop/skills/active/` requires opt-in (`autoPromote: true`) plus effective non-confounded sample ≥ 8; regressions and inconclusive results write proposals to `.build-loop/proposals/` for user confirmation — never auto-remove. Cross-project promotion via `/build-loop:promote-experiment <name>` | — | Manual review of `.build-loop/state.json.runs[]` |
+| Context recovery after compaction | `bookmark:*` commands | — | Re-read last plan file in `.build-loop/` |
+| Claude Code plugin authoring / review | `plugin-builder` (personal skill), `plugin-dev:*` family | `build-loop:plugin-hygiene-lessons.md` enforces manifest/hook/marketplace rules in Review-D | Read `plugin-hygiene-lessons.md` verbatim |
+
+### Sub-routers (set during Phase 1)
+
+**UI target**: prefer the most specific match — order matters.
+
+1. **macOS desktop (`uiTarget: "macos"`, `platform: "apple"`)** — `*.xcodeproj` or `Package.swift` is present AND any of: (a) project has NO `ios/` directory AND has `Sources/` / `App/` with `*.swift`; (b) Xcode project's `SUPPORTED_PLATFORMS` / deployment target indicates macOS; (c) repo grep shows `import AppKit` or `import SwiftUI` paired with `WindowGroup`/`Window` (macOS scene types) and no `UIKit` import. macOS has no simulator; validation routes to `native-ax-driver` or IBR `scan_macos`, never to `xcrun simctl`.
+2. **iOS/watchOS mobile (`uiTarget: "mobile"`, `platform: "apple"`)** — `ios/` directory present, OR `*.xcodeproj`/`Package.swift` with `UIKit` import / `iOS` deployment target. Validation uses the iOS simulator screenshot path.
+3. **React Native mobile (`uiTarget: "mobile"`, `platform: "react-native"`)** — `app.json` (Expo) or `App.tsx` with `react-native` import.
+4. **Web (`uiTarget: "web"`, `platform: "web"`)** — fallback for everything else with a UI surface.
+
+Tie-breaker: if signals are mixed (an Apple project with both `ios/` and a macOS target), set `uiTarget: "mobile"` and surface a one-line note in Assess; the build can override via `state.json.uiTarget` if the goal targets the macOS surface.
+
+**Migration source**: if `.replit` / `replit.nix` present → `migrationSource: "replit"`. Lovable / Bolt / v0 export markers (e.g. `lovable.config`, `bolt.config`, `v0.dev` in comments) → corresponding source. `replit-migrate` skills generalize — load `migration-scan` for any of the above, override hints as needed.
+
+**Apple deploy**: when `platform: "apple"` AND goal includes "deploy", "TestFlight", or "App Store" → Phase 7/8 invoke `apple-dev` deploy flow using ASC creds from your harness memory store (e.g. `~/.claude/projects/<project-slug>/memory/reference_asc_credentials.md`). Apply deployment policy first: TestFlight/App Store Connect upload/export defaults to `auto`; App Store production release/submission defaults to `confirm`.
+
+**Web deploy verify**: fires when `.vercel/project.json` or `vercel.json` is present AND the build performed a push/deploy → Phase 4 Review-B invokes `scripts/verify_deploy.py` (preferred-tier upgrade: Vercel MCP only if the user has added it to `.mcp.json`). Infra failures return `skipped`, never block the build.
+
+## Trigger Conditions
+
+Some capabilities should fire proactively based on goal phrasing or files touched. Phase 1 ASSESS sets these flags in `.build-loop/state.json.triggers`, and Phase 4 EXECUTE consults them before dispatching each subagent.
+
+**pyramid-principle** (structured writing)
+
+Fires whenever the build produces user-visible prose or professional writing. Even small text should follow pyramid structure, and the logical ordering principle applies to design flow too.
+
+Trigger if any of:
+
+- Task touches user-visible text inside the app: copy, microcopy, empty-state messages, error messages, onboarding flow, help content, tooltips, toasts, form labels, email templates, notification text.
+- Task creates or edits: `README.md`, `CHANGELOG.md`, `docs/**/*.md`, PR descriptions, release notes, design docs, status updates, exec summaries, handoff documents.
+- Goal contains: "write", "draft", "summarize", "document", "one-pager", "brief", "memo", "deck", "slides", "presentation", "status update".
+- Designing information architecture or section ordering: use the pyramid logic for top-down flow (governing thought, then MECE key lines, then support).
+
+Action: load `pyramid-principle:pyramid-principle-core` first for ground rules, then the specific skill matching length and format. If absent, use `fallbacks.md#structured-writing`.
+
+**prompt-builder** (prompt authoring or audit)
+
+Fires when prompts are a core part of the product, not when prompts appear incidentally in code comments or test fixtures.
+
+Trigger if any of:
+
+- Building or editing prompts that the app sends to an LLM at runtime: document-generation prompts (Example App style), chat-with-user system prompts, voice-interaction prompts (example app style), reranker prompts, eval-judge prompts.
+- Robust agent or prompt pipeline present in the product: multi-step prompts, RAG, tool-use flows.
+- Semantic search over user queries: use `prompt-builder` to revise the query before embedding or retrieval.
+- Authoring a new agent's instructions (the body of an `agents/*.md` file serving as LLM guidance).
+- File signals: `prompts/`, `system-prompt.*`, strings passed to `messages[{role:"system"}]`, `anthropic.messages.create`, `openai.chat.completions.create`, prompt templates in `.prompt` or `.txt` held as product assets.
+- Goal contains: "system prompt", "agent prompt", "prompt engineering", "rewrite this prompt", "improve this prompt", "audit prompts", "eval judge".
+
+Existing prompt guardrail: if the task touches an **existing** in-product prompt (not a new one), pause and ask the user before running `prompt-builder`. Prompts are often tuned against real evals; silent rewrites can regress quality. Offer the option, do not auto-apply.
+
+Action: load `prompt-builder:prompt-builder` (plugin) if installed, else the personal `prompt-builder` skill, else `fallbacks.md#prompt`. For existing-prompt edits, capture before-and-after in `.build-loop/prompts/` with version suffixes so regressions are detectable.
+
+**building-with-deepagents** (DeepAgents / local-LLM agent work)
+
+Fires whenever the project uses the open-source `deepagents` package. DeepAgents has subtle API shape (SubAgent dict, middleware stack, per-agent tool scoping) that makes hand-rolled focus modes and flat-tool-list designs silently wrong — small local models exhibit tool-call hallucinations in ways that scoping fixes and prompt injection doesn't.
+
+Trigger if any of:
+
+- Repo grep: `from deepagents` or `import deepagents` in any Python source file
+- `deepagents` in `pyproject.toml`, `requirements*.txt`, `uv.lock`, or `poetry.lock`
+- Goal mentions: "agent", "sub-agent", "subagent", "planner/researcher/writer", "focus mode", "tool-call hallucination", "LangGraph agent", "ChatOllama", "local LLM agent"
+- File signals: `create_deep_agent`, `SubAgent`, `AGENT_ROLES`, `agent_focus_prompt`
+- Pain symptoms in the conversation: "`<namespace>.<tool>` is not a valid tool", "silent thinking", "model loaded forever", "threads vanish on restart"
+
+Existing-agent guardrail: treat agent definitions like existing prompts — pause before rewriting, capture before-and-after in `.build-loop/agents/` with version suffixes. Tool scoping changes downstream behavior for every query; regressions are expensive to spot.
+
+Action: load `build-loop:building-with-deepagents` before any code edit involving agent construction, tool binding, or streaming. The skill's `references/anti-patterns.md` lists 12 concrete bugs we've hit — verify none of your planned changes reintroduce them.
+
+**Judgment: prompt-builder vs inline prompt**
+
+Not every prompt needs the full engine. Use `prompt-builder` when the prompt is load-bearing. Craft a simple inline prompt when it is throwaway.
+
+Use `prompt-builder` when any of these are true:
+
+- The prompt ships in the product and runs at scale.
+- The prompt is sent to end users or generates user-visible output.
+- The prompt is part of an agent, eval judge, RAG pipeline, or semantic-search query rewriter.
+- Output correctness is measured (evals exist or are planned).
+- The prompt will be reused across features, or maintained over time.
+- Token cost matters because it runs millions of times.
+
+Roll your own inline prompt when all of these are true:
+
+- One-shot usage inside the current build loop (dispatching a subagent, asking Claude to transform a file, generating a migration script).
+- Not persisted to the product codebase.
+- Output is checked once by the orchestrator, not by an eval.
+- A short direct instruction is clearer than a 6-Part Stack.
+
+Default when uncertain: if the prompt text will exist in the repo after the build, use `prompt-builder`. If it only exists as a line in an orchestrator message during this build, inline is fine.
+
+### Plugin / hook / skill / agent work — mandatory
+
+If Phase 1 detects that the task touches plugin components, Phase 3 must map each task to the authoritative skill below and Phase 4 must load that skill. **Do not infer plugin formats from memory or by reading another plugin's config.**
+
+| Task surface | Skill (authoritative) | Fallback |
+|---|---|---|
+| `.claude-plugin/plugin.json` | `plugin-dev:plugin-structure` | Read `RossLabs-AI-Toolkit/LESSONS-LEARNED.md` — paths must start with `./` |
+| `hooks/hooks.json` or hook scripts | `plugin-dev:hook-development` + run `plugin-dev/scripts/hook-linter.sh` | Command hooks default; Stop stdout must be valid JSON; advisory/non-blocking unless an explicit safety/security/integrity gate opts into blocking; NO prompt hooks on PostToolUse/Stop/SessionStart |
+| Slash commands (`commands/*.md`) | `plugin-dev:command-development` | — |
+| Subagents (`agents/*.md`) | `plugin-dev:agent-development` + `RossLabs-AI-Toolkit/agents/` | `fallbacks.md#agent-authoring` |
+| MCP servers (`.mcp.json`) | `plugin-dev:mcp-integration` | `.mcp.json` must NOT wrap with `mcpServers` key (Method 1) |
+| `~/.claude/settings.json` | `plugin-dev:plugin-settings` | — |
+| New skill (SKILL.md) | `plugin-dev:skill-development` + `skill-builder` (personal) | Official skill format; SKILL.md ≤200 lines |
+| New plugin end-to-end | `plugin-builder` (personal) → delegates into `plugin-dev:*` | — |
+
+### External knowledge — check before coding
+
+| Source | When | How |
+|---|---|---|
+| `/cookbook` | Claude API patterns: tool calling, PTC, code execution, Agent SDK, RAG, thinking, structured output, batch, caching | Invoke `/cookbook` or read `reference_claude_cookbook.md` from your harness memory store (`~/.claude/projects/<project-slug>/memory/`) |
+| `RossLabs-AI-Toolkit/LESSONS-LEARNED.md` | Any plugin work | Read during Phase 1 ASSESS |
+| `context7` MCP | Any library/framework use | `query-docs` / `resolve-library-id` — do NOT code from training data |
+| `research` skill | Factual claims, pricing, versions | Run `scripts/research_trigger.py` first; T1 official docs → T4 forums; 2-source minimum |

package/plugin-artifacts/codex/skills/build-loop/references/codex-subagents.md

@@ -0,0 +1,106 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Codex Subagent Adapter
+
+Use this adapter when Build Loop runs inside Codex. It translates Build Loop's host-neutral "parallel subagents" concept into Codex-native delegation without changing Claude Code's `agents/*.md` runtime.
+
+## Core Rule
+
+Codex may use subagents only when the user explicitly authorizes delegation or parallel agent work. Examples: "use subagents", "parallelize this", "delegate", "spin up workers", or `/build-loop --parallel ...`.
+
+If authorization is absent, keep the work local in the lead Codex session. Still write the same MECE plan and ownership packets, but do not spawn workers.
+
+## Role Mapping
+
+| Build Loop need | Codex role | Use when |
+|---|---|---|
+| Codebase question | `explorer` | The answer can be read-only, bounded, and returned as facts with file paths. |
+| Implementation slice | `worker` | The write set is disjoint from other workers and the interface contract is clear. |
+| Phase 4 review passes | lead session inline, or `explorer` if authorized | See the enumerated passes below — the lead owns these whether or not delegation is allowed. |
+| Final integration | lead session | The lead must own merge, validation, and final judgment. |
+
+**Phase 4 review is not one pass — it is a set.** Whether run inline (default) or via an authorized `explorer`, the lead must cover all of these every non-trivial build; do not skip a pass just because Codex lacks a dedicated agent file for it:
+
+- **Adversarial audit (independent-auditor)** — read the diff against intent/goal/PRD/constitution; verdict `yay`/`nay`/`suggest_correction`/`look_again`. Advisory at chunk close, gating at build scope.
+- **Fact-check** — trace every rendered metric (%, $, score, count) to its source; flag absolute claims. *Blocking* when a rendered number is unverifiable.
+- **Mock-data scan** — production paths only; lorem/faker/hardcoded/`Math.random()`-in-display. *Blocking* when it renders to the user.
+- **Security review** — only when Assess flagged a risk-surface change (auth, network, persistence, secrets, external input); OWASP LLM/Agentic/Web top-10. *Blocking* on critical/high (feeds the exit gate).
+
+The first row's "read-only, does not block" applies to the adversarial-audit *critic* pass; the fact-check, mock-scan, and security passes CAN block and route to Iterate.
+
+## Permission Gate
+
+Before spawning any Codex subagent:
+
+1. Confirm user authorization is explicit in the current request or command flags.
+2. Confirm the task is not on the immediate critical path.
+3. Confirm the subtask has a bounded write set or read-only question.
+4. Confirm the prompt includes a MECE ownership packet.
+
+If any condition fails, do the work locally.
+
+## When Not To Delegate
+
+- Ambiguous product decisions.
+- Final integration or final report.
+- Destructive git operations.
+- Push/deploy confirmation.
+- A task whose result is required before the lead can make the next local move.
+- Files already owned by another active worker.
+- Cross-file architecture decisions that were not settled in the plan.
+
+## Prompt Packet Required
+
+Every Codex worker prompt must include:
+
+- `task`: one concrete outcome.
+- `owns`: exact files or directories the worker may edit.
+- `does_not_own`: files, directories, or responsibilities the worker must avoid.
+- `context`: condensed facts from Phase 1 and Phase 2.
+- `interface_contract`: functions, routes, schemas, props, CLI flags, or docs the worker must preserve or expose.
+- `integration_checkpoint`: what the lead will verify before merging the worker result.
+- `validation`: commands the worker should run if feasible.
+- `return_format`: changed files, summary, validation, unresolved risks, integration notes.
+
+Tell every worker: "You are not alone in the codebase. Do not revert edits made by others; adapt around them and report conflicts."
+
+## Context Policy
+
+Prefer explicit prompt packets over full context forks. Use full context only when the worker genuinely needs the thread history to avoid a wrong implementation.
+
+Shared reads should happen once in the lead session, then be condensed into worker prompts. This keeps workers focused and reduces contradictory interpretations.
+
+### Prompt Cache Discipline
+
+OpenAI prompt caching is automatic, so Build Loop cannot call the cache directly from Codex. The lever the Codex adapter controls is prompt shape: keep the reusable prefix stable, and move volatile task state later.
+
+For Codex CLI and Codex app runs, put reusable role rules, output contracts, validation expectations, and ownership schema before task-specific facts. Put Rally state, timestamps, command output, diffs, browser comments, thread IDs, worktree metadata, current claims, and task IDs after the stable contract.
+
+Do not reorder stable sections between worker prompts. Monitoring cached-token counters only detects prefix churn; the improvement comes from preserving the prefix and reducing noisy context before dispatch.
+
+## Parallel Pattern
+
+1. Lead creates the plan and identifies parallel-safe groups.
+2. Lead spawns only independent sidecar work.
+3. Lead continues non-overlapping local work while workers run.
+4. Lead waits only when blocked on a worker result.
+5. Lead reviews changed files and integrates deliberately.
+6. Lead runs final validation locally.
+
+## Return Format
+
+Workers should finish with:
+
+```text
+Changed files:
+- <path>: <what changed>
+
+Validation:
+- <command or "not run">: <result or reason>
+
+Integration notes:
+- <contract, migration, or ordering notes>
+
+Unresolved risks:
+- <risk or "none known">
+```

package/plugin-artifacts/codex/skills/build-loop/references/coordination.md

@@ -0,0 +1,161 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Coordination — How build-loop consumes agent-rally
+
+Build-loop is a **consumer** of the agent-rally architecture, but it currently
+vendors native embedded copies of the substrate and watcher while the standalone
+repos mature. Treat `agent-rally-point` and `agent-rally-watcher` as
+mini-plugins inside build-loop: grouped scripts, skills, docs, tests, and thin
+build-loop adapters first; full spin-out later. Cross-reference the upstream
+architecture docs before changing how build-loop reads or writes events, but do
+not make build-loop depend on those external repos at runtime yet.
+
+> **Binding constitution** (verdict-gating, MECE briefs, Phase D closeout, peer-no-mutate, release-surface verification) lives in [`references/coordination-rules.md`](../../../references/coordination-rules.md). This file documents the **integration shape**, not the rules of engagement.
+
+## Build-loop's position in the three-layer model
+
+```
+Layer 3 — CONSUMERS (build-loop, codex, claude_code, ...)
+              ▲
+              │  build-loop is one of many
+              ▼
+Layer 2 — agent-rally-watcher (embedded watcher namespace; optional listener)
+              ▲
+              │  build-loop CAN subscribe, OR poll Layer 1 directly
+              ▼
+Layer 1 — agent-rally-point (embedded substrate; channel, schema, post API)
+```
+
+Build-loop **always** uses Layer 1 (it posts events and calls `checkpoint_read`). It uses Layer 2 **opportunistically** — when a peer session is detected via Rally Point presence, the coordination polling gate spins up a `coordination_watch.py` loop or installs a watcher subscription so chunk-close, commit, and feedback events surface within seconds rather than at the next phase boundary.
+
+Native skill entrypoints:
+
+- `skills/agent-rally-point/SKILL.md` — substrate workflow, CLI, boundary,
+  run identity, and spin-out rules.
+- `skills/agent-rally-watcher/SKILL.md` — watcher workflow, JSONL sensor
+  behavior, closeout, and spin-out rules.
+
+The machine-readable boundary is `scripts/rally_point/plugin_boundary.json`.
+
+## What build-loop posts
+
+Every cross-session signal goes through `scripts/rally_point/post.py::post()` (the canonical writer that bumps revision *before* appending — see [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md) for the field-by-field record format). Raw `append_change(...)` without a subsequent `bump_revision(...)` is a silent-no-op for peers (`feedback_codex_pass_is_gate_not_comment`).
+
+| When                                  | `kind`       | `payload` shape                                                  | Triggered by                       |
+|---------------------------------------|--------------|------------------------------------------------------------------|------------------------------------|
+| Chunk closes and lands on the branch  | `phase`      | `{phase: "chunk-close", chunk_id, commit_sha, files_changed}`    | Phase 3 commit step                |
+| Phase boundary (Phase 1, 4, 5)        | `phase`      | `{phase: "<phase-name>", summary, ...}`                          | Orchestrator phase entry           |
+| Build run closes (Phase D)            | `phase`      | `{phase: "run-closeout", session_id, coord_file, outcomes}`      | Phase D closeout sequence          |
+| Peer hands off work to a verifier     | `handoff`    | `{from_tool, to_tool, work_item, deadline_ts}`                   | Sub-step F when a peer is present  |
+| Verifier returns a verdict            | `feedback`   | `{step, verdict: PASS|VARIANCE|BLOCKED, rationale, evidence}`    | After verifier runs on a step      |
+| Architecture scan completes           | `arch-scan-complete` | `{digest_path, files_scanned}`                            | Phase 1 architecture baseline      |
+| Dependency manifest changed           | `dep-change` | `{manifest, added, removed, session_id}`                         | Phase 3 commit step on manifest    |
+| Coordination announcement / take-over | `phase`      | `{phase: "leadership", role, scope}`                             | Multi-orchestrator handoff         |
+
+All writes are fire-and-forget — a coordination failure must never crash the build.
+
+## What build-loop reads
+
+### Phase 1 Assess — inbox pickup + presence check
+
+At Phase 1 entry, the orchestrator (see `agents/build-orchestrator.md` §"Phase 1: Assess") runs:
+
+```bash
+python3 scripts/coordination_status.py --workdir "$PWD" --session-id "$SESSION_ID" --json
+```
+
+The status reports: active peers (live sessions in the channel's `sessions/`), session-ack-aware unread inbox messages (`inbox/<my-tool>.jsonl`, `inbox/all.jsonl`), task-heartbeat health when `--task-ref` is set, and any active coordination file. If `active_peers > 0` OR `inbox_unread_count > 0`, the orchestrator MUST drain the inbox before dispatching any chunk; otherwise the peer's last verdict/handoff is invisible to the new run. After acting on the inbox payload, run `python3 scripts/agent_rally.py ack-inbox --workdir "$PWD" --session-id "$SESSION_ID" --tool "$TOOL_ID" --json` so stale notes stop ringing the doorbell.
+
+### Coordination polling gate — watcher install when a peer is present
+
+When the Phase 1 status returns peers, build-loop installs a cheap continuous watcher:
+
+```bash
+python3 scripts/coordination_watch.py --workdir "$PWD" --session-id "$SESSION_ID" --tool claude_code --task-ref "$TASK_REF" --interval 5 --jsonl --baseline-current
+```
+
+The watcher reports revision changes, inbox deltas, and task-heartbeat health as line-delimited JSON. The orchestrator polls it before commits, before final responses, and after any 30-second work interval. When a peer posts (e.g. a verifier returns a `feedback` verdict), the orchestrator routes the response into the active coordination file's "Codex feedback log" section rather than asking the user to paste it.
+
+For long-running work, write `agent_rally.py heartbeat --task-ref "$TASK_REF"`
+at task start and at least every 10 minutes. Presence says the session is live;
+task heartbeat says it is still on the claimed task.
+
+The watcher process is OPTIONAL — if the daemon process can't start (no FS-watch support, sandboxed environment), the orchestrator falls back to per-checkpoint `coordination_status.py` polls. The same flow works; latency is higher.
+
+### Chunk-close — checkpoint read for downstream chunks
+
+After each chunk's commit step closes, the orchestrator runs `checkpoint_read` against this session's cursor to surface any peer events that landed during the chunk. Reactions (`reinstall`, `re-baseline`, `soft-claim`) are documented in [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md). Reactions are **awareness only** — `soft-claim` warns when a peer touched files this session also plans to touch; the orchestrator decides whether to wait, rebase, or proceed.
+
+## Peer-no-mutate rule
+
+When a peer presence record indicates active work AND that work isn't already merged (`branch_merge_status: unmerged` AND files differ from `origin/main`), build-loop's orchestrator MUST NOT modify the same files. The rule and the merge-status pre-check are in [`references/coordination-rules.md`](../../../references/coordination-rules.md) §"Peer-no-mutate" and `feedback_verify_peer_merged_before_blocking`.
+
+Read-only operations (Phase 1 architecture baseline, plan drafting, fact-check) are always safe and do not invoke the rule.
+
+## Embedded mini-plugin boundary
+
+For now, the Rally Point substrate and watcher still ship inside the
+build-loop plugin, but they are treated as embedded mini-plugins with
+explicit extraction edges:
+
+| Future plugin | Embedded namespace | Build-loop compatibility entrypoints |
+|---|---|---|
+| `agent-rally-point` | `scripts/rally_point/**` | `scripts/agent_rally.py`, `commands/rally-point.md`, `hooks/*rally-point.sh`, `scripts/coordination_status.py`, `scripts/coordination_rally.py`, `scripts/coordination_bootstrap.py` |
+| `agent-rally-watcher` | `scripts/agent_rally_watcher/**` | `scripts/coordination_watch.py` |
+
+The machine-readable contract lives at
+`scripts/rally_point/plugin_boundary.json` and is validated by:
+
+```bash
+python3 scripts/rally_point/boundary.py --repo "$PWD" --check --json
+python3 scripts/agent_rally.py boundary --workdir "$PWD" --check --json
+```
+
+Boundary rule: put substrate behavior in `scripts/rally_point/**`, watcher
+behavior in `scripts/agent_rally_watcher/**`, and leave build-loop files as
+thin adapters. Do not import build-loop memory-store or orchestration internals
+from those namespaces unless the dependency is explicitly isolated as an
+adapter in the boundary manifest.
+
+## Discovery integration (current)
+
+Build-loop uses `scripts/rally_point/discovery_bridge.py` as the shared
+channel resolver. It prefers the standalone `agent-rally-point` discovery
+surface when installed and falls back to build-loop's embedded resolver only
+when needed. Both native discovery and the embedded fallback default to
+`~/.agent-rally-point/apps/...`; the fallback uses the local worktree-aware
+`<slug>` when no native `<repo-id>` is available.
+
+The discovery layer (see
+[`agent-rally-point/docs/DISCOVERY.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/DISCOVERY.md))
+provides:
+
+```python
+from agent_rally_point.discover import discover
+info = discover()  # returns dict with channel_dir, channel_layout, active_revision, active_peers, ...
+channel_dir = info["channel_dir"]   # canonical OR legacy-fallback path
+```
+
+Current build-loop callers route through the bridge:
+
+1. `scripts/agent_rally.py` resolves `where`, `presence`, `handoff`, `lead`,
+   and `boundary` through the shared namespace.
+2. `scripts/coordination_status.py` reads status from the resolved channel
+   instead of deriving a parallel channel path.
+3. `scripts/rally_point/session_probe.py` and `scripts/rally_point/hooks.py`
+   use the resolved channel for session-start and pre-edit hook behavior.
+4. `scripts/coordination_watch.py` remains a compatibility wrapper; watcher
+   behavior lives under `scripts/agent_rally_watcher/`.
+
+## Cross-references
+
+- **Substrate (channel format, post API, presence, lifecycle)** — [`agent-rally-point/ARCHITECTURE.md`](https://github.com/tyroneross/agent-rally-point/blob/main/ARCHITECTURE.md)
+- **Record schema (all 6 kinds + payloads)** — [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md)
+- **Discovery protocol (manifest, CLI, `discover()`)** — [`agent-rally-point/docs/DISCOVERY.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/DISCOVERY.md)
+- **Push-based daemon (consumers.toml, sinks)** — [`agent-rally-watcher/ARCHITECTURE.md`](https://github.com/tyroneross/agent-rally-watcher/blob/main/ARCHITECTURE.md)
+- **Binding constitution (verdicts gating, MECE briefs, Phase D closeout)** — [`references/coordination-rules.md`](../../../references/coordination-rules.md)
+- **Per-run coordination file template** — [`references/coordination-file-template.md`](../../../references/coordination-file-template.md)
+
+## Why a separate doc
+
+`coordination-rules.md` is the binding *constitution* — operating rule, verdict gating, MECE field list, closeout sequence. This file is the *integration map* — where build-loop sits in the three-layer architecture, what it posts, what it reads, where the path-hardcoding lives, and what the discovery migration looks like. Conceptually distinct audiences: the rules file is for any participant; this file is for build-loop's orchestrator and anyone modifying how build-loop talks to rally-point.

package/plugin-artifacts/codex/skills/build-loop/references/correction-aware-capture.md

@@ -0,0 +1,177 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Correction-aware lesson capture — three-tier design
+
+## Why
+
+Two gaps in the prior capture stack:
+
+1. **`scan_transcript_for_decisions.py` no-ops entirely without Ollama.**
+   The script gates on `shutil.which("ollama")`; absent the binary, an
+   entire session's worth of decisions is silently dropped.
+2. **No lessons / feedback lane from live conversation.** The decisions
+   scanner captures decisions only. A user correcting the assistant's
+   just-taken action — the highest-signal lesson event in a session —
+   had no trigger and no destination.
+
+The three-tier design closes both gaps without disrupting the existing
+decisions pipeline.
+
+## Three tiers
+
+### Tier 1 — Deterministic Stop-hook (always runs, no LLM)
+
+**Script:** `scripts/scan_corrections/`
+**Hook:** `hooks/hooks.json` Stop entry, fires alongside (not instead of)
+the decisions scanner.
+
+Detects three classes of high-signal patterns in USER turns:
+
+| Class | Patterns | Confidence |
+|---|---|---|
+| Correction | `revert that`, `don't X`, `undo`, `stop X`, `back that out`, `wrong approach` | `confirmed` (extra: `prior_assistant_acted: true` when assistant just used tools) |
+| Preference | `always X`, `never X`, `must X`, `default to X`, `we use X for Y`, `prefer X` | `confirmed` |
+| Tradeoff | `X instead of Y`, `actually X not Y`, `X over Y because Z` | `confirmed` |
+
+Scope routing: keywords like `across projects`, `globally`, `for all projects`,
+`as a rule`, `standing rule` flag the candidate as `scope: global` (otherwise
+`project`). Anti-false-positive: wh-question turns ending in `?` are skipped
+by hard-skip patterns; greetings/thanks/ok are skipped.
+
+Writes one `.build-loop/pending-lessons/<ts>-<kind>-<id>.md` per candidate
+with YAML frontmatter:
+
+```yaml
+---
+id: <16-char sha1>
+kind: correction|preference|tradeoff
+signal_type: <named pattern>
+confidence: confirmed
+scope: project|global
+turn_index: <int>
+captured_chars: <int>
+tier: 1-deterministic
+source: stop-hook
+captured_at: <iso8601>
+extras:
+  prior_assistant_acted: true|false
+---
+
+## Quote
+> <verbatim user span>
+
+## Context (±200 chars)
+```
+
+Idempotent: `id_hash` is a SHA-1 of (kind, signal_type, normalized quote),
+so re-running the scanner on the same transcript does not duplicate files.
+Promoted/discarded subdirs are also checked for dedup.
+
+Fail-open contract: any exception logs to stderr and exits 0. The
+`.build-loop/.no-capture` opt-out short-circuits before any work.
+`SCAN_CORRECTIONS_BUDGET_S` (default 10s) caps wall-clock.
+
+### Tier 2 — Optional Ollama accelerator (existing path, unchanged)
+
+**Script:** `scripts/scan_transcript_for_decisions.py` (the existing
+decisions scanner, untouched). When Ollama is installed AND the
+transcript is large enough to benefit from clustering, this path
+distills/dedups decisions and writes to
+`build-loop-memory/projects/<slug>/decisions/` (or `_review/` for
+quarantine).
+
+Tier 2 is **strictly optional**. The user installed Ollama on this
+machine, so it runs; on a fresh machine without Ollama, tier 1 alone
+guarantees capture and the session continues uninterrupted.
+
+### Tier 3 — Host-agent refinement (the primary intelligence)
+
+**Script:** `scripts/surface_pending_lessons.py`
+**Consumed by:** the host coding agent (Claude Code in this build,
+Codex on a Codex host, etc.) at SessionStart.
+
+Per the user's standing "host-agent-is-the-LLM" rule, the host coding
+agent is the primary refinement layer. Each session, the host reads
+`.build-loop/pending-lessons/` (and optionally
+`build-loop-memory/projects/<slug>/decisions/_review/`), classifies each
+candidate, and promotes via:
+
+- `scripts/memory_writer.py` — for `kind=lesson|feedback|preference`
+  (routes to `build-loop-memory/lessons/` for `scope=global` or
+  `build-loop-memory/projects/<slug>/lessons/` for `scope=project`)
+- `scripts/write_decision/__main__.py` — for `kind=decision`
+
+Discarded candidates move into
+`.build-loop/pending-lessons/discarded/` (any file there is silently
+skipped on re-runs, so the discard is durable).
+
+The same surface also exposes the existing Ollama `_review/` quarantine
+when `--include-decisions-review` is set, so the host agent has one
+queue to drain.
+
+## Store bridge (harness ↔ build-loop-memory)
+
+**Script:** `scripts/bridge_lesson_to_harness.py`
+
+Once a lesson lands in build-loop-memory (via tier-3 promotion or any
+other path), it can be mirrored into the harness auto-memory store the
+host coding agent auto-loads at session start
+(`~/.claude/projects/-Users-<u>/memory/`). The bridge:
+
+- Resolves a deterministic target basename `<kind>_<slug>.md` matching
+  the harness convention
+- Augments the bridged copy's frontmatter with `bridged_from`,
+  `bridged_at`, `source_store: build-loop-memory`
+- Appends a one-line entry to harness `MEMORY.md` under
+  `## Bridged from build-loop-memory` (creates the section if absent;
+  preserves other sections; dedup'd on target basename)
+
+Idempotent and reversible. Only `lesson | feedback | preference | convention | gotcha`
+types bridge; decisions stay in their own canonical store.
+
+## Triggers — what fires when
+
+| Event | Tier | Effect |
+|---|---|---|
+| Session ends (Stop hook) | 1 | tier-1 scanner writes raw candidates to `.build-loop/pending-lessons/` |
+| Session ends (Stop hook) | 2 | tier-2 scanner (Ollama, if present) writes distilled decisions |
+| Session starts (host agent reads context-bootstrap) | 3 | pending-lessons queue count surfaces in queue summary; host agent runs `surface_pending_lessons.py` to refine |
+| Lesson promoted to build-loop-memory | — | `bridge_lesson_to_harness.py` mirrors to harness auto-memory |
+
+## File layout summary
+
+```
+scripts/
+  scan_corrections/
+    __init__.py
+    detect.py             — patterns + Candidate dataclass + JSONL parser
+    __main__.py           — Stop-hook CLI (tier 1)
+    test_detect.py        — 26 unit tests
+    test_cli.py           — 8 CLI integration tests
+  surface_pending_lessons.py     — tier 3 host-agent surface
+  test_surface_pending_lessons.py — 10 tests
+  bridge_lesson_to_harness.py    — store bridge
+  test_bridge_lesson_to_harness.py — 11 tests
+  scan_transcript_for_decisions.py — UNCHANGED (tier 2)
+
+hooks/hooks.json — Stop hook now runs both scanners in parallel
+
+scripts/context_bootstrap.py — QUEUE_NAMES extended with "pending-lessons"
+
+.build-loop/pending-lessons/   — tier-1 candidate queue (this run)
+                  /promoted/    — host-agent promoted (silenced)
+                  /discarded/   — host-agent discarded (silenced)
+```
+
+## Non-goals + tradeoffs
+
+- **Not a replacement for `auto-decision-capture`.** That skill is for
+  the host agent's in-session reasoning — explicit captures during the
+  conversation. Tier-1 + tier-3 fire at session boundaries; the skill
+  fires inline. They compose.
+- **Tier 1 is intentionally narrow.** Adding fuzzy patterns would
+  produce false positives. The host agent (tier 3) is where ambiguous
+  cases get judged — that's the design intent of "host-agent-is-the-LLM."
+- **Bridge runs on demand, not automatically.** A future enhancement
+  could fire it via a post-promotion hook; the durable lesson lives in
+  build-loop-memory either way, and the bridge is reversible.