@tyroneross/build-loop 0.30.3 → 0.35.0

package/plugin-artifacts/codex/references/memory.md

@@ -0,0 +1,299 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Memory — Global and Project-Scoped (full protocol)
+
+> Loaded from `skills/build-loop/SKILL.md` summary. Contains the full memory system: global vs project stores, routing rules, and read/write policies.
+
+## Memory — Global and Project-Scoped
+
+Build-loop maintains one canonical long-term memory store at `~/dev/git-folder/build-loop-memory/`. Every build reads canonical indexes/folders; writes go to exactly one lane based on scope.
+
+### Recall-optimized memory discipline
+
+Canonical reference: `build-loop-memory/references/2026-06-11-memory-discipline-prompt.md` (`version: 2026-06-11.1`). Apply it to every non-trivial memory-relevant read or write.
+
+Operational contract:
+
+- Recall first for significant repo work, debugging, planning, and any memory write. Read the store-root `INDEX.md` first, then project context such as `projects/<slug>/context/CONTEXT.md` and generated `CURRENT.*`, plus `constitution.md` / `MEMORY.md` where present. Search `indexes/INDEX.jsonl`, scan `chronology.jsonl`, read the matching lane, and verify any remembered file/flag/API/script still exists before relying on it.
+- Write only durable facts that aid future recall: decisions + rationale, lessons, reusable references, gotchas, experiment results, product opportunities, and durable operational patterns. Do not write restated code, git-derivable facts, transient status, or handoff-only state.
+- Before writing, search `indexes/INDEX.jsonl` for an existing slug/title, update instead of duplicating, then check `indexes/duplicates.jsonl` after indexing. Use title and `description` as the recall hooks.
+- Do not hand-write project decisions. Use `scripts/write_decision/__main__.py`; it writes the decision lane and updates that lane's `INDEX.md` / update ledger. Generated master-index reachability is still incomplete for new `projects/<slug>/decisions/` files, so verify decisions through `memory_facade` or the decision lane until the scanner/map split is reconciled.
+- Current reference gap: `memory_writer.py` has `research` as a project sublane but not `references`; `reference_capture` writes to `projects/<slug>/research/`, while `build-loop-memory/scripts/rebuild_memory_indexes.py` scans `references/` and not `research/`. For generated-index recall today, write `type: reference` content under `projects/<slug>/lessons/references/`, or update both writer and indexer to agree on `references` or `research`.
+- After any memory write, run the relevant host index/check step when mutation is in scope and verify the entry is reachable from the proper recall surface: `INDEX.jsonl` for generated-index lanes, decision lane/index or `memory_facade` for decisions, or the host system's equivalent.
+
+**Cross-project memory**: `build-loop-memory/lessons/` plus the sibling top-level lanes `design/`, `debugging/`, and `product/`
+
+- Applies across every project this user builds.
+- Examples: "Deployment to Vercel uses `vercel deploy --prebuilt` when `ENABLE_AUTH=true`"; "Neon is the default Postgres for Next.js 16 projects"; "TestFlight upload uses ASC API key from `~/.appstoreconnect/private_keys/`"; "User prefers zero-dep scripts over package additions".
+- Structure: one file per fact/lesson/tool-discovery. Generated recall indexes live in `build-loop-memory/indexes/`.
+- Types: `tool`, `deployment`, `library-choice`, `user-preference`, `pattern`.
+
+**Project memory**: `build-loop-memory/projects/<slug>/` (slug derived via `scripts/_paths.derive_slug_from_cwd`)
+
+- Applies only to the current project.
+- Examples: "This app's design system lives in `src/styles/tokens.css`, not Tailwind"; "Routes under `/admin/` require `requireAdmin()` guard"; "The `custom_themes` table has a user_id VarChar bug from 2026-04-13 — see migration note".
+- Same lane structure as top level: `decisions/`, `lessons/`, `debugging/`, `design/`, `product/`, and related domain folders.
+- Types: `design`, `convention`, `gotcha`, `decision`, `contract`.
+
+### Routing rule (always ask this question)
+
+**"Would this apply to a different project?"**
+
+- **Yes** → top-level canonical lane (`build-loop-memory/lessons/`, `design/`, `debugging/`, or `product/`). Deployment tools, library choices, general user preferences, reusable patterns.
+- **No** → project canonical lane (`build-loop-memory/projects/<slug>/...`). Design tokens, internal APIs, project-specific gotchas, per-repo conventions.
+- **Ambiguous** → ask the user once, then save. Don't guess.
+
+### Artifact lanes & segmentation (issues / backlog / lessons)
+
+Three work/knowledge artifact types, each with a clear WRITE → READ → TRACK lane. **Every lane is repo-segmented; the segmentation is mechanical, not discretionary** — so work on repo X never reads or writes repo Y's items.
+
+| Artifact | Write (where) | Read / Track | Lifetime |
+|---|---|---|---|
+| **issues** | `<repo>/.build-loop/issues/<id>.md` — current-run bugs | Phase 5 Iterate drains them; repo-local so inherently scoped | short-lived (resolve → delete) |
+| **backlog** | durable: `build-loop-memory/projects/<slug>/backlog.md` (slug folder = repo scope); active: `<repo>/.build-loop/backlog/<id>.md` | read before planning self-work; Phase 5 drains active items | long-lived |
+| **backlog-archive** | `build-loop-memory/projects/<slug>/backlog-archive.md` | closed/moved/superseded items land here **with rationale + ref** — never deleted silently | durable |
+| **lessons** | `projects/<slug>/lessons/` (project) OR top-level `lessons/` (cross-project, stored `_unscoped`) — via `memory_writer.py` | `context_bootstrap` recall scopes to `(slug OR _unscoped)` — never other projects | durable |
+
+**Segmentation contract (binding):**
+- The **slug folder** (`projects/<slug>/`) is the repo key; the **`repo` + `branch` frontmatter** on each issue/backlog item is the explicit scope tag (template: `templates/backlog-item.md`). Both must agree.
+- When working repo X on branch B, **read and write only** items where `repo == X` (and `branch == B` or unscoped). A cross-repo item discovered mid-work is recorded in **its** repo's scope, **never** the current repo's tracker.
+- **No shared/freeform cross-repo trackers.** (The retired `OPEN-ITEMS.md` was exactly this anti-pattern — one file that accreted rows from unrelated app repos into build-loop's scope. Replaced by the slug-segmented `projects/<slug>/backlog.md`.)
+- Reads are already enforced: `context_bootstrap` queue reads are repo-local `.build-loop/`, and lessons recall passes the resolved `project` so the query scopes to `(project OR _unscoped)` — `project=None` (all-projects) is never used for current-work context.
+
+### When to write memory
+
+- User states a preference or convention: save immediately.
+- A build surfaces a new tool/library/deployment pattern worth reusing: save after Review-F.
+- A project-specific gotcha or decision emerges: save during Review-F Report.
+- Do NOT save: ephemeral task details, things already derivable from code or git log, state that changes per build.
+
+### When to read memory
+
+- Always during Phase 1 ASSESS.
+- Before deploying: check global deployment memory.
+- Before UI work: check project design memory.
+- Before adopting a new library: check global library-choice memory.
+
+## Cross-session memory propagation + provenance schema (multi-process / multi-host)
+
+Multiple build-loop sessions can run concurrently. Two scripts own the cross-session model end-to-end:
+
+- `scripts/memory_writer.py` — canonical WRITER. Adds provenance frontmatter and appends to the index in one atomic operation.
+- `scripts/memory_index.py` — append-only discovery log in the selected canonical lane.
+- `scripts/memory_update_ledger.py` — global append-only audit/freshness log for the whole configured memory root.
+
+### Provenance frontmatter (every memory file)
+
+```yaml
+---
+name: <slug>
+description: <one-line summary>
+type: tool | deployment | library-choice | user-preference | pattern | feedback | reference | design | convention | gotcha | decision | contract
+source_repo: "<git remote url or null>"
+source_workdir: "<abs path>"
+source_run_id: "run_<UTC>_<hash>"
+source_host: "claude_code | codex | gemini | other"
+cross_repo_validated: false          # flips to true once a DIFFERENT repo applies it
+applied_in_repos: []                  # appended entries: {repo, workdir, run_id, applied_at}
+created_at: "ISO8601 UTC"
+last_updated_at: "ISO8601 UTC"
+---
+```
+
+### Writer side — use the canonical writer for normal memory writes
+
+**Top-level (cross-project) write** — `--scope top-level` routes to `build-loop-memory/lessons/` (or a sibling lane when `--file <lane>/x.md` is used):
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py \
+  --scope top-level \
+  write \
+  --file "<rel-path>" \
+  --name "<slug>" \
+  --description "<one-line>" \
+  --type feedback \
+  --run-id "$RUN_ID" \
+  --workdir "$PWD" \
+  --host claude_code \
+  --body-file /tmp/memory-body.md
+```
+
+**Project-scoped write** — `--scope project --project <slug>` routes to `build-loop-memory/projects/<slug>/lessons/` (or a sublane when `--file <sublane>/x.md` is used):
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py \
+  --scope project --project "$PROJECT_SLUG" \
+  write \
+  --file "<rel-path>" \
+  --name "<slug>" \
+  --description "<one-line>" \
+  --type gotcha \
+  --run-id "$RUN_ID" \
+  --workdir "$PWD" \
+  --host claude_code \
+  --body-file /tmp/memory-body.md
+```
+
+The writer auto-detects `source_repo` from the workdir's git remote, appends a row to the lane-local `INDEX.jsonl`, appends a row to the global update ledger at `indexes/updates.jsonl`, and (on update) preserves `created_at` + `applied_in_repos` so cross-repo validation history survives edits. Direct writes are repair/fallback work only: use them only when no canonical writer exists or the current task is explicitly a memory-system repair, then run the host index/check step and verify reachability.
+
+### Reader side — surface peer writes via INDEX.jsonl
+
+Between phases (or at every M2 heartbeat), tail since your last check:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_index.py tail \
+  --since "$LAST_INDEX_CHECK_TS" \
+  --exclude-run-id "$RUN_ID" \
+  --json
+```
+
+For each row:
+1. Read the underlying memory file.
+2. If `source_workdir` ≠ this `$PWD` AND `source_repo` ≠ this repo's git remote — tag `[CROSS-REPO — requires scrutiny]` in the phase brief.
+3. Surface to the user with the memory's `description` field as the hook.
+
+### Store side — global update ledger
+
+Every canonical memory mutation should also append one JSONL row to:
+
+```
+<memory-root>/indexes/updates.jsonl
+```
+
+This is the store-wide ledger. It is not a replacement for lane-local `INDEX.jsonl`; the two logs have different jobs:
+
+| Log | Scope | Primary job |
+|---|---|---|
+| `<lane>/INDEX.jsonl` | One memory lane | Peer discovery inside that lane |
+| `indexes/updates.jsonl` | Whole memory root | Audit trail, freshness baseline, repair inventory |
+
+Row schema:
+
+```json
+{
+  "ts": "2026-06-01T12:00:00Z",
+  "schema_version": 1,
+  "event_id": "<sha256-prefix>",
+  "project": "build-loop",
+  "lane": "decisions",
+  "action": "write",
+  "path": "projects/build-loop/decisions/0001-example.md",
+  "writer": "write_decision.py",
+  "run_id": "run_...",
+  "source_repo": "<git remote or omitted>",
+  "source_workdir": "<absolute workdir or omitted>",
+  "source_commit": "<repo HEAD represented by this memory update>",
+  "source_host": "codex",
+  "memory_id": "0001",
+  "summary": "Short human hook",
+  "sha256": "<content hash when available>",
+  "metadata": {}
+}
+```
+
+`memory_writer.py`, `write_decision.py`, and `append_milestone.py` emit this ledger row automatically. Direct writes to memory files should be treated as legacy or repair work because they bypass provenance, discovery, and freshness.
+
+CLI:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_update_ledger.py tail \
+  --project "$PROJECT_SLUG" \
+  --limit 20 \
+  --json
+```
+
+### Trust gradient — mark-applied flow
+
+When a memory written elsewhere is successfully applied in the current repo, record it:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py mark-applied \
+  --file "<rel-path>" \
+  --applying-repo "$THIS_REPO_REMOTE" \
+  --applying-workdir "$PWD" \
+  --applying-run-id "$RUN_ID"
+```
+
+Appends to `applied_in_repos[]` (deduped by `(repo, workdir)`) and flips `cross_repo_validated` to `true` once at least one applying repo differs from the source. Memories with `cross_repo_validated: true` AND `len(applied_in_repos) >= 2` have earned higher trust — independently verified to hold across distinct repos. Surface that distinction in Phase 1 Assess briefs as `[VALIDATED — applied in N repos]`.
+
+### Migration — existing memory files
+
+`memory_writer.py migrate` is an idempotent backfill that adds provenance frontmatter to existing memory files. Safe to re-run; skips any file that already has all required provenance keys.
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py migrate \
+  --run-id "$RUN_ID" \
+  --workdir "$PWD" \
+  --host claude_code \
+  --dry-run    # inspect first; remove the flag to apply
+```
+
+Run once after this version of build-loop is installed; the migration completes immediately for memory dirs of ordinary size (the user's global memory at ~80 files migrates in well under a second).
+
+### Concurrency
+
+- `memory_writer.py write` — atomic tmpfile + os.replace; the memory file IS the lock.
+- `memory_index.py append` — `fcntl.flock(LOCK_EX)` on `INDEX.jsonl.lock`; multi-writer safe across hosts.
+- `memory_update_ledger.py append` — `fcntl.flock(LOCK_EX)` on `updates.jsonl.lock`; append-only and multi-writer safe.
+
+## Append-only milestones (anti-rewrite-drift)
+
+### The problem this solves
+
+"Current state" files that are rewritten in place rot: the writer overwrites without fully reading, summaries drift from reality, and no one can tell which run produced a given snapshot. The fix is append-only by construction — a log that can only grow forward.
+
+### What gets appended and when
+
+Every build-loop run appends a single milestone record at **Review-G** via `scripts/append_milestone.py`. Each record captures what shipped and the repo HEAD sha at write time.
+
+The milestone (durable `milestones.jsonl` in build-loop-memory) is **distinct from** `state.json.runs[]`, which Phase 6 Learn scans for pain signals. The orchestrator's Review-G writes both; an **inline run or the closeout** writes neither unless it calls them explicitly. So at run-close, in addition to the milestone, record the run for Learn with `python3 scripts/append_run.py --workdir "$PWD" --run-id <id> --goal "..." --outcome <done|partial|blocked>` (append-only, idempotent on `run_id`; capture `--manual-intervention "<phase>:<note>"` for any step the user had to re-prompt). Without it, inline work never reaches the `runs[] >= 3` Learn threshold. See `references/phase-6-learn.md` §Detect.
+
+JSONL contract (frozen — sibling staleness-check reads this):
+
+```
+<memory-root>/projects/<slug>/milestones.jsonl
+```
+
+Each line:
+
+```json
+{"ts": "2026-05-30T12:00:00Z", "commit": "<sha>", "repo": "<dir-name>", "summary": "<what shipped>", "run_id": "<id|null>"}
+```
+
+### How to append
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/append_milestone.py \
+  --workdir "$PWD" \
+  --summary "feat: shipped auth + dashboard" \
+  --run-id "$RUN_ID" \
+  --json
+```
+
+`--commit` and `--project` override the defaults (git HEAD and slug derived from `--workdir`). `--memory-root` overrides the default `~/dev/git-folder/build-loop-memory`.
+
+Output: `{"appended": true, "path": "...", "line": "..."}` on success; `{"appended": false, "reason": "..."}` on fail-soft (non-git workdir, unwritable root). Exit 0 in both cases.
+
+Idempotency: if the last line already has the same `commit` AND `summary`, the call is a no-op. Safe to re-run on retry.
+
+### The core principle: pointer not duplicate
+
+The milestone log is the **durable, never-rewritten** record of project progress. Other memory files (`lessons/`, `decisions/`, etc.) remain the authoritative content store. The milestone is a pointer — "at this commit, this run shipped this" — not a duplicated copy of their content.
+
+> The rewrite-in-place pattern is what rots. Append-only logs + pointers resist drift by construction: you can always `tail` to see the latest state, `grep` to find when something shipped, and the sibling staleness-check can compare the latest milestone commit against the current HEAD to detect stale memory instantly.
+
+Decisions use the existing `decisions/` lane (also append-only files, one file per decision). The milestone log adds the run-level "what shipped" layer that `decisions/` doesn't track.
+
+### Staleness detection
+
+`memory_staleness_check.py` now prefers the latest `source_commit` in `indexes/updates.jsonl` for the current project, then falls back to the latest milestone's `commit` field. It compares that baseline against `git rev-parse HEAD` in the project workdir. If HEAD has moved past the last memory update by the configured commit threshold, the project's memory is potentially stale and Phase 1 Assess should flag it.
+
+Impact:
+
+- A decision, lesson, migration, mark-applied, or milestone can refresh the memory baseline when it records `source_commit`.
+- Older memory stores without `indexes/updates.jsonl` keep working because milestone fallback is unchanged.
+- A stale warning means "no durable memory update has been recorded for this project at or near HEAD"; it does not prove every individual memory file is stale.
+
+### Concurrency
+
+`fcntl.flock(LOCK_EX)` on `milestones.jsonl.lock` — same pattern as `memory_index.py`. Multi-writer safe.

package/plugin-artifacts/codex/references/model-tier-mapping.md

@@ -0,0 +1,257 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Model Tier Mapping — Multi-Provider Substitution Reference
+
+Build-loop is provider-agnostic at the tier level. Agent frontmatter uses Anthropic aliases (`fable`, `opus`, `sonnet`, `haiku`) by default because Claude Code is the primary host, but the **tier abstraction** (Frontier / Thinking / Code / Pattern) is what governs the role assignment. This reference documents how to swap providers cleanly.
+
+## Canonical tier definitions
+
+### Frontier tier
+- **Role:** Planning synthesis AND verification verdicts. **Phase 2 Plan synthesis reaches Fable via the stakes-gated Advisor dispatch ladder** (`advisor` agent / peer host / already-Fable session; honestly-labeled inline-Opus fallback otherwise — `skills/build-loop/references/advisor-dispatch-ladder.md`); the Advisor v1 ladder is Phase 2 only, so Phase 1 Assess synthesis runs inline as today until v2. Plan content: frame goal, draft spec/ADRs, F-criteria, MECE partition. Verification-shaped agents whose verdicts gate downstream work: plan-critic, scope-auditor, independent-auditor, fix-critique, fact-checker, security-reviewer, overfitting-reviewer, promotion-reviewer.
+- **Why this tier exists (above Thinking):** wrong plans dispatch N implementers into the wrong work, and wrong verdicts ship regressions. The user's standing priority is Accuracy > Speed > Cost; the compounding-risk surfaces pay the Frontier premium.
+- **Benchmark contract:** clears the Thinking-tier contract AND benchmarks above the prior-generation Thinking-tier ceiling on at least one of SWE-bench Verified / ARC-AGI / GPQA Diamond.
+- **Cost expectation:** highest. Use only on the planning + verification surface; never default for execution or coordination.
+- **Anthropic default:** Fable 5 (`claude-fable-5`)
+- **Verified equivalents (2026 Q2, advisory):** GPT-5.5 (`gpt-5.5`, OpenAI's frontier Codex model — complex coding, agentic, 1.1M ctx), GPT-5.4 (`gpt-5.4`, lower-cost frontier); future Claude generations above Opus
+- **Local equivalents:** none — Frontier-class capability is not yet matched locally
+
+### Thinking tier
+- **Role:** Coordination + escalation. Routes work between subagents, ladders severity, runs causal-tree on stuck iterations, writes audit/learnings when no Frontier verdict is being rendered.
+- **Benchmark contract:** SWE-bench Verified ≥78% AND competitive on ARC-AGI / GPQA Diamond / MMLU-Pro.
+- **Cost expectation:** middle-high tier. Use for orchestration and the escalation target when execution hits ambiguity. Never default to Thinking for bounded execution.
+- **Anthropic default:** Opus 4.8 (`claude-opus-4-8`; alias `opus` auto-tracks the latest Opus generation)
+- **Verified equivalents (2026 Q2, advisory):** GPT-5.4 (`gpt-5.4`), Gemini 2.5 Pro
+- **Local equivalents:** none yet — Thinking-tier work needs frontier-class context length and judgment; local models lag
+
+### Code tier
+- **Role:** Application. Apply a known rule, spec, or pattern to bounded input. Scoped implementation per a commit's owned-files. Adversarial critic vs rubric. Mechanical simplify. The "how" decisions when the "what" is already settled.
+- **Benchmark contract:** SWE-bench Verified ≥75% AND tool-use accuracy ≥85% AND multi-turn coding rollout ≥80%.
+- **Cost expectation:** ~3-5× cheaper than Thinking tier per token. The default for the bulk of build-loop work.
+- **Anthropic default:** Sonnet 4.6 (`claude-sonnet-4-6`)
+- **Verified equivalents:** Sonnet 4.7+ (when available), GPT-5.4 Mini (`gpt-5.4-mini` — fast coding + subagents)
+- **Local equivalents:** qwen2.5-coder-32B-instruct (mid-quality), Codestral 22B (reasonable substitute for bounded refactor work)
+
+### Pattern tier (a.k.a. Recognition)
+- **Role:** Pure regex/syntactic match. Classify into known buckets. Log scan. Deterministic checklist verification. No judgment. No gradient — match-or-not.
+- **Benchmark contract:** none formal. Empirical: doesn't hallucinate on bounded structured tasks; runs fast.
+- **Cost expectation:** ~10-20× cheaper than Thinking tier. Use for high-volume mechanical sweeps.
+- **Anthropic default:** Haiku 4.5 (`claude-haiku-4-5-20251001`)
+- **Verified equivalents:** Haiku 4.6+ (when available), GPT-5 Nano (`gpt-5-nano` — fastest/cheapest, classify + summarize)
+- **Local equivalents:** llama3.2-3b, qwen2.5-3b
+
+## Substitution table (advisory, 2026 Q2)
+
+| Provider | Frontier | Thinking | Code | Pattern |
+|---|---|---|---|---|
+| Anthropic (default) | Fable 5 (`fable`) | Opus 4.8 (`opus`) | Sonnet 4.6 (`sonnet`) | Haiku 4.5 (`haiku`) |
+| OpenAI | `gpt-5.5` (Codex) | `gpt-5.4` | `gpt-5.4-mini` | `gpt-5-nano` |
+| Google | next-gen Gemini Ultra (when it clears the contract) | `gemini-2.5-pro` | `gemini-2.5-flash` | `gemini-flash-lite` |
+| Local (Ollama / MLX) | n/a — none meets contract yet | n/a — none meets contract yet | `qwen2.5-coder-32b` | `llama3.2-3b` |
+
+⚠️ **Always verify benchmarks before swapping.** Table cells are best-effort as of build-loop's last update; model versions and rankings drift. Use `Skill("research")` or Context7 MCP to confirm current SWE-bench Verified scores before relying.
+
+### Selectable model registry (the machine-readable source of truth)
+
+The cells above are mirrored by `MODEL_REGISTRY` in `scripts/model_overrides.py`. List the selectable models per tier (and feed any tool) with:
+
+```bash
+python3 scripts/model_overrides.py --list-models          # all tiers
+python3 scripts/model_overrides.py --list-models --tier frontier --json
+```
+
+The registry is **advisory**: override resolution still accepts any model id, so a brand-new model works the moment you put it in `modelOverrides` — it is simply flagged `registered: false` on the resolve envelope until it is added here. `TIER_DEFAULTS` (the Anthropic mapping) stays the fallback; registering a model makes it *selectable*, not the default.
+
+## Three ways to swap
+
+### 1. Edit agent frontmatter (one-time, per-host)
+
+Each `agents/*.md` carries a `model:` field. Replace `opus` / `sonnet` / `haiku` with your provider's identifier. Example for OpenAI on a Codex host:
+
+```yaml
+# agents/build-orchestrator.md
+---
+name: build-orchestrator
+model: gpt-5.4             # was: opus (Thinking tier)
+---
+
+# agents/implementer.md
+---
+name: implementer
+model: gpt-5.4-mini        # was: sonnet (Code tier)
+---
+```
+
+This is durable but requires re-editing on every plugin update. Prefer #2 below.
+
+### 2. Runtime override via `.build-loop/config.json` (recommended)
+
+```json
+{
+  "modelOverrides": {
+    "frontier": "gpt-5.5",
+    "thinking": "gpt-5.4",
+    "code": "gpt-5.4-mini",
+    "pattern": "gpt-5-nano"
+  }
+}
+```
+
+Configs that predate the `frontier` tier resolve `frontier` → `fable` automatically (built-in tier default in `scripts/model_overrides.py`), so older repos keep working without edits.
+
+The orchestrator resolves this before dispatching each subagent with
+`scripts/model_overrides.py`. Frontmatter `model:` becomes the fallback when an
+override is absent for that tier.
+
+```bash
+python3 scripts/model_overrides.py \
+  --workdir "$PWD" \
+  --tier code \
+  --fallback sonnet \
+  --json
+```
+
+Resolution order is repo config first, then `.build-loop/state.json`
+`config.modelOverrides`, then the supplied fallback. Use `--require` when a
+tier must resolve to a concrete model before dispatch.
+
+### 3. Per-dispatch override
+
+When dispatching a subagent for a one-off task that needs a different tier:
+
+```
+Agent({
+  subagent_type: "build-loop:implementer",
+  model: "claude-opus-4-7",   // override Sonnet → Opus for this dispatch
+  prompt: "..."
+})
+```
+
+This is what happens during escalation (e.g. "2 consecutive failures on the same chunk → escalate to Thinking tier per `model-tiering`").
+
+## Tier-vs-task quick reference
+
+When you see a task in build-loop, classify it before assigning a tier:
+
+| Task | Reasoning shape | Tier |
+|---|---|---|
+| Frame goal, ADRs, scope, MECE-partition | Planning synthesis | Frontier |
+| Plan-critic vs rubric | Verification synthesis | Frontier |
+| Implement commit's owned files | Application | Code |
+| Severity-rank findings (post-verdict routing) | Coordination synthesis | Thinking |
+| Mock-data scan | Recognition | Pattern |
+| Trace caller-paths (scope-auditor) | Verification synthesis | Frontier |
+| Independent-auditor vs diff | Verification synthesis | Frontier |
+| Audit / learnings write (no verdict being rendered) | Coordination synthesis | Thinking |
+| Recurring-pattern detection | Recognition | Pattern |
+
+The decision tree (from `model-tiering/SKILL.md`):
+1. "Single-correct answer derivable from a rule applied to bounded input?" → Application / Code tier
+2. Else "Pure pattern-match, no gradient?" → Recognition / Pattern tier
+3. Else, Synthesis. Then: "Is this a planning decision (what to build) or a verification verdict (did it hold)?" → Frontier tier
+4. Else (routing, escalation, audit-synthesis without a verdict) → Thinking tier
+
+## Dual-mode A/B test design (preserved)
+
+Build-loop intentionally supports two dispatch modes to enable continued A/B testing on tier-mix tradeoffs:
+
+### Mode A — Top-level / fan-out (default)
+- **Invocation:** `/build-loop:run` invoked as a Skill from user session
+- **Tier mix:** Thinking orchestrator + up to 4 Code-tier implementer subagents in parallel + Code-tier critic + Thinking-tier severity ranking + Thinking-tier audit
+- **Anthropic mapping:** Opus orchestrator + Sonnet implementer fan-out
+- **Best for:** features with ≥3 truly parallel-safe chunks, large feature size (≥10 commits), repetitive patterns
+
+### Mode B — Inline / single-context (preserved for A/B comparison + small features)
+- **Invocation:** `Agent(subagent_type="build-loop:build-orchestrator", ...)` from any session
+- **Tier mix:** Thinking-tier orchestrator handles ALL phases inline (no-sub-sub-agents rule kicks in)
+- **Anthropic mapping:** all-Opus single context
+- **Best for:** small/medium features (≤6 commits), cross-cutting refactors where catching all-the-callsites matters more than per-token cost, sequential dependency chains, comparison runs against Mode A
+
+The orchestrator detects which mode it's in via the dispatch path (top-level message vs subagent invocation) and adapts behavior at `agents/build-orchestrator.md:529-530`. **Both modes share the same plan, the same Phase 1-4 logic, and the same Phase 6 Learn signals.** The only difference is whether implementer work fans out to Code-tier subagents (Mode A) or runs inline in the Thinking-tier orchestrator's context (Mode B).
+
+This dual-mode design is **not deprecated** — it's the intentional architecture for tier-comparison telemetry. Future build-loop changes that affect dispatch must preserve both modes.
+
+## Multi-model implications for the dispatch test
+
+When swapping providers, the dispatch-pattern A/B test should be re-run because:
+- **Wall-clock per tier varies by provider.** GPT-5 Codex may be faster or slower than Sonnet 4.6 at scoped code application.
+- **Cost ratios shift.** Some providers price the Thinking tier closer to the Code tier (smaller multiplier); others price wider.
+- **Cross-context-window effects.** Mode B's "single Opus context" wins partly come from full-file-system visibility; the same effect may differ on a model with a smaller context window.
+- **Tool-use fidelity.** Mode A's parallel implementer fan-out depends on the Code tier reliably calling Read/Edit/Bash tools without hallucination. This varies materially across providers.
+
+When introducing a new provider to a project, prefer Mode B for the first 2-3 builds to establish a quality baseline, then enable Mode A once the new Code-tier model has shown stable tool-use behavior.
+
+## Dynamic tier assignment (guide, not a fixed rule)
+
+The orchestrator **judges each subtask's complexity at dispatch time** and assigns the tier that fits. This is adaptive, not a fixed table.
+
+**Priority order: accuracy > speed > cost.** Pick the tier that does the work CORRECTLY first — never trade accuracy for a cheaper or faster model. Among accuracy-equivalent options, prefer the faster path (spawn Opus subagents to accelerate complex work; fan out in parallel). Optimize cost only after accuracy and speed are both satisfied — cost is the last lever, never the first. This is why every subagent's output is verified (accuracy) and why Opus subagents are used freely on hard tasks (speed on complexity beats pinching tier cost).
+
+**Tier assignment guide:**
+
+| Task shape | Tier |
+|---|---|
+| Pure recognition, extraction, classification, mechanical sweep — "find X", "list/grep Y", "scan for Z", "extract these fields", "run detector + summarize its JSON", "does this match the pattern". No rule-application, no cross-file reasoning. | **Pattern / Haiku** |
+| Apply a known rule or spec to bounded input. Scoped implementation per owned-files. The "how" when the "what" is settled. | **Code / Sonnet** — default workhorse; prefer Sonnet over Haiku when in doubt |
+| Coordination, routing, ambiguous-spec interpretation, novel architecture decision mid-execution, causal-tree on stuck iterations, user-trust prose where no verification verdict is being rendered. | **Thinking / Opus** — orchestrator default, AND available to accelerate genuinely complex execution subtasks |
+| Planning synthesis (frame goal, draft spec/ADRs, F-criteria, MECE partition) **when stakes-gated via the Advisor dispatch ladder** (`synthesisDensity > 5`, `riskSurfaceChange`, `stakes >= medium`, or `dispatch_tier: frontier`) OR verification verdicts (plan-critic, scope-auditor, independent-auditor, fix-critique, fact-checker, security-reviewer, overfitting-reviewer, promotion-reviewer). | **Frontier / Fable** — wrong plans and wrong verdicts compound; pays the premium. Plan synthesis reaches Fable through the `advisor` agent / peer host / already-Fable session; when no trigger fires or no dispatch path is reachable it runs inline on the orchestrator's model (Opus), labeled honestly — the floor equals today's behavior. See `skills/build-loop/references/advisor-dispatch-ladder.md`. |
+
+**Prefer Sonnet.** Sonnet is the workhorse for the bulk of build-loop's work. Down-tier to Haiku only for tasks that are genuinely trivial/mechanical — pure pattern-match, no judgment, no gradient. When in doubt, use Sonnet.
+
+**Opus subagents are allowed** to accelerate complex subtasks — cross-file reasoning, novel design, ambiguous specs, hard refactors. Opus is no longer reserved for the orchestrator alone. The orchestrator MAY spawn an Opus subagent when a subtask is complex enough that a stronger model would produce materially better or faster results. Use Opus to accelerate complex work, not only for top-level synthesis.
+
+Both escalation directions are active on every dispatch decision: escalate up when complexity exceeds the assigned tier; down-tier when the task is genuinely below it.
+
+For `model: inherit` agents (fact-checker, fix-critique, root-cause-investigator), the **caller** passes the appropriate tier — the agent inherits what the caller assigned.
+
+### Verify every subagent (the safety net for dynamic tiering)
+
+Because tiers are assigned adaptively, every subagent's output is **checked before it is accepted**. The cheaper the tier, the stronger the check. This per-subagent verification is what makes dynamic (and occasionally cheaper) assignment safe.
+
+Verification ties to build-loop's existing mechanisms:
+- **verify-scope / verify-landed** (Phase 3 commit step) — confirms the implementer only touched owned files and the commit landed cleanly.
+- **independent-auditor** (Phase 4 Review-A) — adversarial LLM-grade read of the full build's output.
+- **implementer return envelope** — every subagent returns a structured envelope; `status: blocked | partial` routes to Iterate before the output is accepted.
+
+No subagent output is trusted unchecked. The verification chain is a first-class requirement, not a backstop.
+
+### Fan-out / workflow agents
+
+When fanning out bounded agents via the Workflow tool, a dynamic-workflow, or a rallyflow mini-loop, assign each agent by the same guide:
+
+- **Recognition/extraction/scan-and-summarize** → Haiku (Pattern tier) — genuinely trivial mechanical work
+- **Apply rules or reason across files** → **Sonnet** (Code tier) — default for fan-out agents
+- **Cross-file, novel, or ambiguous subtask** → Opus (Thinking tier) — when the subtask warrants it
+- **Single synthesis agent** (aggregates fan-out results, cross-agent judgment) → Opus only when synthesis dimensions exceed the Code-tier contract
+
+Fan-out breadth multiplies token cost linearly — but the right fix is matching tier to task complexity, not defaulting every agent to the cheapest tier. Prefer Sonnet for fan-out agents; drop to Haiku only for the genuinely mechanical bounded ones.
+
+Concrete dispatch pattern:
+
+```
+Agent({
+  subagent_type: "build-loop:implementer",
+  model: "haiku",          // recognition task — scan for mock-data patterns
+  prompt: "Scan files X..Z for hardcoded test data. Return a JSON list of findings."
+})
+
+Agent({
+  subagent_type: "build-loop:implementer",
+  model: "sonnet",         // default for rule-application / scoped implementation
+  prompt: "Implement the auth middleware per the spec in intent.md. Owned files: ..."
+})
+
+Agent({
+  subagent_type: "build-loop:implementer",
+  model: "opus",           // complex subtask — cross-file refactor, ambiguous spec
+  prompt: "Refactor the session management layer across auth/* and middleware/*. ..."
+})
+```
+
+## Round-3 evidence (2026-05-07) — preserved for context
+
+| Mode | Wall-clock | Tokens | Notes |
+|---|---|---|---|
+| A (Opus + Sonnet fan-out, 4-parallel Wave 1) | ~11 min | ~600K total (~50/50 Thinking/Code) | parallel-commit race required orchestrator-side recovery (~3-4 min of 11-min total) |
+| B (Opus inline, serial) | ~23 min | ~150K Thinking only | 0 iterations, caught a schema field bug A's scoped implementer missed |
+
+A's wall-clock advantage on round 3 was real (parallel structure exists in the feature); cost ratio is ~4× (A burns more tokens). Both modes shipped working features.

package/plugin-artifacts/codex/references/modular-systems-pack.md

@@ -0,0 +1,96 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Modular Systems Pack
+
+Use this pack on every non-trivial build. It makes modular, scalable structure the default while allowing a simpler or more integrated approach when that better serves the use case.
+
+## Default
+
+Build-loop should prefer systems that are:
+
+- **Modular**: each module hides one important design decision behind a stable interface.
+- **Scalable**: the design can grow in data volume, user volume, feature count, or team ownership without immediate redesign.
+- **MECE**: task groups, file ownership, and agent scopes are mutually exclusive and collectively exhaustive.
+- **Pyramid-structured**: plans, handoffs, reports, and repo organization lead with the governing thought, then supporting groups, then details.
+
+This is a default, not dogma. The goal is durable user value, not extra architecture.
+
+## Exception Rule
+
+Do not add modularity for its own sake. Choose a simpler or more integrated approach when:
+
+- The change is a one-off script, short-lived migration, or isolated fix.
+- A new boundary would add indirection without reducing real complexity.
+- A performance hot path needs a tightly integrated implementation.
+- The repo is small and the added module structure would obscure the core workflow.
+- The product need is intentionally limited and extra optionality would confuse users.
+
+When taking an exception, record:
+
+```text
+MODULARITY EXCEPTION: <why simpler/integrated is better for this use case>
+```
+
+## MECE File And Agent Partition
+
+Phase 2 Plan must partition work so every changed file has exactly one owner and every required responsibility has an owner.
+
+For each task group, use this packet:
+
+```md
+Group: <name>
+Dimension: <domain | layer | workflow | bounded context | adapter | test surface>
+Owns files: <paths>
+Does not own: <paths handled elsewhere>
+Interface contract: <exports/events/API/schema it may change>
+Integration checkpoint: <command or review step>
+Intent link: <north-star or user-value rule this group supports>
+```
+
+MECE checks:
+
+- No overlap: a file or interface is not owned by two agents unless the plan defines a handoff point.
+- No gaps: every required behavior, state, migration, test, and user-facing surface has an owner.
+- One dimension per level: avoid mixing domains, layers, and workflows in the same grouping level.
+- Stable interfaces: agents can change internals, but cross-group contracts are explicit.
+- Integration checkpoint: every boundary has a test, build, visual check, schema check, or reviewer step.
+
+## Modular Design Heuristics
+
+- Hide volatile decisions behind small interfaces: data shape, provider choice, algorithm, storage, rendering strategy, or external API.
+- Prefer high cohesion: code that changes for the same reason lives together.
+- Prefer loose coupling: callers depend on published interfaces, not internal data structures or side effects.
+- Design around business/domain capabilities when the system is large enough for domains to matter.
+- Keep boundaries small enough to understand and large enough to own a useful capability.
+- Separate deploy/runtime config from code when values vary by environment.
+- Preserve directness when extra layers make the core workflow harder to read, test, or operate.
+
+## Pyramid Structure
+
+Use pyramid structure for plans, reports, repo notes, and agent handoffs:
+
+1. Governing thought: the one decision, result, or recommendation.
+2. MECE key lines: 3-5 non-overlapping supporting claims or work groups.
+3. Evidence/details: commands, files, risks, interfaces, and validation.
+
+For repo structure, this means names should communicate purpose, folders should group by one clear dimension, and cross-cutting utilities should stay genuinely shared rather than becoming a junk drawer.
+
+## Review Gates
+
+Critic and final review should flag:
+
+- Avoidable tight coupling or weak cohesion.
+- Hidden cross-file ownership overlap between agents.
+- Missing owner for a required behavior, state, migration, test, or user-facing surface.
+- Abstraction added without user, scalability, testability, security, or maintainability benefit.
+- Simplification that collapses a boundary needed for accuracy, security, scale, testability, or future optionality.
+- Missing `MODULARITY EXCEPTION` when the plan intentionally chooses an integrated shortcut.
+
+## Source Basis
+
+- Parnas, "On the Criteria to Be Used in Decomposing Systems into Modules" (CACM, 1972): https://cacm.acm.org/research/on-the-criteria-to-be-used-in-decomposing-systems-into-modules/
+- AWS Well-Architected REL04-BP02, "Implement loosely coupled dependencies": https://docs.aws.amazon.com/wellarchitected/2024-06-27/framework/rel_prevent_interaction_failure_loosely_coupled_system.html
+- Microsoft Azure Architecture Center, domain analysis for microservices: https://learn.microsoft.com/en-us/azure/architecture/microservices/model/domain-analysis
+- Microsoft Azure Architecture Center, design principles for Azure applications: https://learn.microsoft.com/en-gb/azure/architecture/guide/design-principles/
+- Twelve-Factor App config guidance: https://12factor.net/config
+- MECE framework overview: https://www.casestar.io/guides/mece