@tyroneross/build-loop 0.30.3

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025-2026 Tyrone Ross, Jr
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,403 @@
+<!-- build-loop@tyroneross:canary:build-loop -->
+<!-- canary-end -->
+# build-loop
+
+A plugin for Claude Code that turns big code changes into a checked, repeatable workflow.
+
+## What it is
+
+Build-loop runs your code change through five phases — plan, execute, review, iterate — plus a mandatory Learn step that runs after every build. It splits the work into safe parallel chunks where it can. A critic reads the diff before tests run, so cheap checks catch the obvious mistakes first. Tests must actually pass. Every number on the page traces back to a real source. Fake data in production paths gets flagged. The build stops if what you shipped does not match what you said you would build. The plugin picks the right model for each task: a strong model to plan and review, a faster model to write code, a small model for pattern checks.
+
+## Why use it
+
+Big changes break things. You forget an edge case. You skip the test pass. The diff drifts from the plan. The implementer makes a quiet design call you never see. Build-loop catches all of that before the change ships.
+
+- **One source of truth.** The plan lists every design decision up front. The implementer must say which decisions it made. A lint compares the claim to the actual diff. If the two do not match, the loop stops.
+- **Speed where you can, depth where you must.** Mechanical work runs in parallel on a fast model. Work with five or more design decisions auto-routes to the strong model in one pass. Five is the cutoff measured in our testing where the fast model lost cross-decision context.
+- **Real evidence, not vibes.** Every pass or fail has a code-based grader. Every metric on a page traces back to its data source. Tests must run. Output must render. Placeholders get flagged.
+- **Less rework.** A read-only critic runs before full validation. Cheap checks catch the obvious mistakes first.
+- **A way to actually improve a number.** Run multiple tests in a single experiment using Design of Experiments and other statistical methods. You can test six variables at once instead of one. The optimize mode plans the test matrix, runs each combination, and tells you which variable actually moved the number.
+
+You ship fewer regressions. You get a clean record of what changed and why. You can trust the workflow on changes that touch many files at once.
+
+## Get started
+
+Install the plugin via the RossLabs AI Toolkit marketplace (recommended) or directly from the build-loop repo.
+
+```
+# Recommended — via the RossLabs AI Toolkit marketplace (includes companion plugins):
+/plugin marketplace add tyroneross/RossLabs-AI-Toolkit
+/plugin install build-loop@rosslabs-ai-toolkit
+
+# Or direct — install from the build-loop source repo alone:
+/plugin marketplace add tyroneross/build-loop
+/plugin install build-loop@build-loop
+```
+
+Run a build.
+
+```
+/build-loop:run add user notification system with email and push
+```
+
+Skip the loop for small fixes (under about 20 lines, single file, no new endpoint). For everything else, run it through the loop. That includes features, refactors, migrations, schema changes, and anything that crosses a file or system boundary.
+
+Debug a failing system.
+
+```
+/build-loop:debug tests pass locally but fail in CI
+```
+
+Detail on each phase, the model tier rules, the synthesis-decision lint, the architecture engine, and the debugger is below.
+
+## Phases
+
+| # | Phase | Purpose |
+|---|-------|---------|
+| 1 | **Assess** | Understand state (project type, architecture, tools, prior state) AND define goal + 3-5 scoring criteria with pass/fail conditions |
+| 2 | **Plan** | Task breakdown with dependency order and parallel-safe groups |
+| 3 | **Execute** | Build it — parallel subagents for independent work |
+| 4 | **Review** | Critic → Validate → Optimize (opt-in) → Fact-Check → Simplify → Report — six ordered sub-steps, single exit point; routes to Iterate on failure |
+| 5 | **Iterate** | Fix Review failures, loop back to Review (max 5x) |
+| 6 | **Learn** *(mandatory)* | Always runs and always emits a `## Learn` outcome line in the Review-G report. Three states: `accruing` (`runs[] < 3` — detector + memory consolidation only), `deferred` (debug-only or budget-exhausted — writes a marker, skips Sonnet draft), or `full` (`runs[] >= 3` + a pattern crossed threshold — detector + Sonnet draft + Opus signoff). Reads two signal sources: `state.json.runs[]` and `proposals/enforce-from-retro/` (recurring enforce-candidates across runs). |
+
+## Supply-chain: dependency cooldown
+
+Build-loop refuses to install third-party JS packages (or version bumps) until the resolved version has been published for at least **7 days**, mitigating smash-and-grab npm compromises (a malicious version published then yanked within hours-to-days never reaches your lifecycle scripts). Defense-in-depth, three layers:
+
+1. **Native config injection** (primary gate) — Phase 1 Assess runs `scripts/inject_dependency_cooldown.py`, idempotently writing the package manager's native publish-age key: npm ≥ 11.10.0 → `.npmrc` `min-release-age` (days); pnpm → `pnpm-workspace.yaml` `minimumReleaseAge` (minutes) + `.npmrc` `minimum-release-age` for pnpm 10.x; yarn ≥ 4.10 → `.yarnrc.yml` `npmMinimalAgeGate` (numeric minutes). npm has **no** native exclude ([npm/cli#8994](https://github.com/npm/cli/issues/8994)) so the user-authored allowlist is enforced by layer 2 on npm; pnpm/yarn carry it natively.
+2. **PreToolUse backstop hook** — for ungated projects, rewrites `npm`/`yarn add` with `--before=<7d ago>` and denies `npm ci`/`pnpm add` with an actionable message. On npm **with** native config it stays engaged for the allowlist: all-allowlisted installs get a command-scoped `--min-release-age=0`; third-party installs are left to the native gate (never `--before` — npm rejects it alongside native config).
+3. **Constitution + commit-auditor** — `C-SUPPLY/dependency_cooldown` rule; advisory flag on `<7d`-old deps in lockfile diffs.
+
+User-authored scopes are exempt via a config-driven allowlist (`.build-loop/config.json` → `dependencyCooldown.allowlist`, default `["@tyroneross/*"]`). See KNOWN-ISSUES for the older-toolchain fallback caveat. pip/cargo not covered in v1.
+
+## Installation
+
+### From GitHub (recommended)
+
+Via the RossLabs AI Toolkit marketplace (includes companion plugins such as bookmark, Coding Debugger, research, etc.):
+
+```
+/plugin marketplace add tyroneross/RossLabs-AI-Toolkit
+/plugin install build-loop@rosslabs-ai-toolkit
+```
+
+Or direct from the build-loop source repo alone (build-loop only, no companions):
+
+```
+/plugin marketplace add tyroneross/build-loop
+/plugin install build-loop@build-loop
+```
+
+build-loop does not register its own MCP server. Deep debugging is native to the build-loop skills; cross-project incident memory can be supplied separately by the standalone Coding Debugger plugin when installed.
+
+### Manual (local development)
+
+```bash
+git clone https://github.com/tyroneross/build-loop.git
+```
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "build-loop": {
+      "source": {
+        "source": "directory",
+        "path": "/path/to/build-loop"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "build-loop@build-loop": true
+  }
+}
+```
+
+### Memory setup (one-time, per machine)
+
+Build-loop's advisory judges read from the canonical `build-loop-memory` store
+(`~/dev/git-folder/build-loop-memory` by default). Plugin writers also maintain
+a global update ledger at `<memory-root>/indexes/updates.jsonl` for audit and
+freshness. Bootstrap with templates:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_memory.py
+```
+
+This seeds `constitution.md` + `MEMORY.md`; `indexes/updates.jsonl` is created on first memory mutation. The build-loop public repo ships only the templates — your actual lessons, constitution rules, and patterns belong in a private repo because they reference specific projects and decisions. See [`docs/memory-setup.md`](docs/memory-setup.md) for the full guide including private repos, root overrides, and repo-local ignored stores.
+
+```bash
+# Status check anytime
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_memory.py --check
+```
+
+## Usage
+
+`/build-loop:run` is the one command for any coding task — build, fix, refactor, optimize, research, or test. The orchestrator reads your goal, classifies intent, and routes to the right mode. You don't choose the mode.
+
+```
+/build-loop:run [goal description]
+```
+
+Examples:
+
+```
+/build-loop:run add user notification system with email and push
+/build-loop:run refactor auth middleware to use JWT
+/build-loop:run migrate database from SQLite to PostgreSQL
+/build-loop:run tests pass locally but fail in CI
+/build-loop:run --parallel add billing settings
+```
+
+Skip the loop for single-file edits, config changes, or fixes under ~20 lines.
+
+### Advanced / direct-mode commands
+
+These commands force a specific mode. Normal usage only needs `/build-loop:run`.
+
+**`/build-loop:debug <symptom>`** — force debug mode directly. `/build-loop:run` auto-routes to this on symptom language ("broken", "doesn't work", "failing", etc.), so you usually don't need it. Useful when you want to skip the full loop and go straight to causal-tree investigation.
+
+Examples:
+
+```
+/build-loop:debug tests pass locally but fail in CI
+/build-loop:debug login works once then breaks on refresh
+/build-loop:debug API returns wrong data intermittently
+```
+
+Runs deep iterative root-cause investigation (causal-tree analysis, fix, verify, critique — up to 5 iterations). The build orchestrator also auto-invokes `Skill("build-loop:debug-loop")` on Review-B Validate failures and Iterate retries (attempts 2 and 3) — you don't have to call it manually during a build.
+
+**`/build-loop:optimize [target]`** — force optimize mode. Auto-routed from `/build-loop:run` on metric-improvement language.
+
+**`/build-loop:research [topic]`** — force research mode. Auto-routed from `/build-loop:run` on evaluation/comparison language.
+
+**`/build-loop:test [--strict] [test-name]`** — force plugin-test static analysis. Auto-routed from `/build-loop:run` on "test plugin"/"validate plugin" language.
+
+Quick incident-memory lookup: `/build-loop:debugger`. Multi-domain assessment: `/build-loop:assess`. Memory stats: `/build-loop:debugger-status`.
+
+## Deployment Policy
+
+Build-loop uses a repo-local policy before running push/deploy commands. If `.build-loop/config.json` is absent, the default is:
+
+```json
+{
+  "deploymentPolicy": {
+    "preview": "auto",
+    "testflight": "auto",
+    "production": "confirm",
+    "unknown": "confirm"
+  }
+}
+```
+
+Meaning: preview deploys and TestFlight/App Store Connect upload/export flows can run automatically after review passes; production deploys, releases, publishes, protected-branch pushes, and unknown targets require explicit confirmation. Repos can override each target with `auto`, `confirm`, or `block`.
+
+## Components
+
+### Intent Capability Pack
+
+Build-loop captures a north star before planning: app/repo purpose, primary users, core jobs, update intent, user value, and non-goals. It writes this to `.build-loop/intent.md` and passes a compact intent packet to every subagent.
+
+Decision rule: prefer the simplest durable approach that creates user value. UI work should be intentional and polished in the basics: every button, option, nav item, chart, and message must have meaning and working behavior. Preview or prototype-looking surfaces must not use fake data in production/user decision paths.
+
+### Modular Systems Pack
+
+Build-loop defaults to modular, scalable, MECE structure: high cohesion, loose coupling, stable interfaces, and one clear owner per changed file. Plans and reports use pyramid structure: governing thought first, MECE support lines second, evidence/details third.
+
+This is a decision rule, not architecture for its own sake. When a simpler or more integrated approach is better for the use case, the plan records `MODULARITY EXCEPTION: <reason>` and explains the user, performance, clarity, or delivery benefit.
+
+### Agents
+
+| Agent | Role | Model |
+|-------|------|-------|
+| **build-orchestrator** | Drives the 5-phase loop plus mandatory Phase 6 Learn, dispatches subagents | opus (overridable) |
+| **commit-auditor** | Advisory judge — chunk scope (Phase 3) + build scope (Phase 4-A, replaces retired sonnet-critic) | opus |
+| **fact-checker** | Traces rendered metrics to data sources | inherit (sonnet recommended) |
+| **mock-scanner** | Scans for placeholder/fake data in production code | haiku |
+
+**Pin vs inherit philosophy**: pin when the task has a clear right tier (critic needs Sonnet, mock-scanner needs Haiku, orchestrator benefits from Opus judgment). Use `inherit` when user intent should flow through (fact-checker — recommended Sonnet, but respects main-session choice). Override an agent's pin by passing `model:` at spawn time or editing frontmatter.
+
+### Model Tiering
+
+Build-loop assigns models per task, not per phase, guided by the `model-tiering` skill:
+
+- **Opus** at boundaries: planning, final review, novel architecture, ambiguity resolution, user-visible prose
+- **Sonnet** inside: bounded code execution, adversarial critic, first-pass debugging, fact-checking
+- **Haiku** for pattern-matching only (mock scanning)
+
+Escalation triggers (mid-flow switch to Opus): 2 consecutive failures, ambiguous spec, cross-file architectural decision, critic `strong-checkpoint` finding, novel error, user-visible prose. See `skills/model-tiering/SKILL.md` and `agents/build-orchestrator.md §Escalation Triggers`.
+
+The pattern amortizes Opus cost across many Sonnet subagents. Typical build: Opus plans once, 6 to 12 Sonnet implementer runs, 1 Sonnet critic per chunk, Opus final review. Estimated 4x cheaper than single-pass Opus end-to-end.
+
+### Eval Methodology
+
+- **Binary pass/fail only** — no partial credit, no Likert scales
+- **Code-based graders first** — test pass/fail, lint, type check, build (fast, deterministic)
+- **LLM-as-judge second** — for nuanced criteria code can't evaluate
+- **One evaluator per dimension** — no multi-dimension "God Evaluator"
+- **Pytest-collection gate at Review-B** — `scripts/pytest_collect_gate.py` runs `pytest --collect-only` (with `PYTHONPATH` stripped) on Python-bearing repos before LLM judges. The bar is collection only — db/live tests still skip at execution time via their markers — but every test module must *load*. A run can't report success while any test module fails to import. Closes the silent-coverage-loss gap where a broken import quietly removes whole modules from coverage. Skipped on library-only repos with no test paths.
+
+### Iteration Rules
+
+- Diagnose root cause before fixing
+- Re-validate only failed criteria
+- 3 failures on same criterion with same cause → escalate to user
+- Fixing one criterion breaks another → stop, reassess
+- No improvement after 2 consecutive iterations → change strategy
+- **Hard stop at 5 iterations**
+
+### Post-build retrospective & backlog drain
+
+- **Post-push retrospective** — after the Phase 4 Report closing push, the `retrospective-synthesizer` agent runs non-gating in the background and writes a 9-section lessons-learned file (`.build-loop/retrospectives/<YYYY-MM-DD>/<run-id>.md`) plus a ≤5-line summary surfaced inline. Anything prompted ≥2× in the thread, or surfaced for "what should be enforced", becomes an auto-drafted enforce-candidate at `.build-loop/proposals/enforce-from-retro/` — a candidate for human review, never silently promoted. The closing run does not wait for it.
+- **Backlog auto-iterate** — product-impacting work that gets descoped during a build is triaged on capture (via `scripts/backlog/triage.py` + `assess.py`) into `.build-loop/backlog/<id>.md` using `templates/backlog-item.md` (mandatory `repo` + `branch` segmentation keys plus `classify`, `effort`, `status`). Phase 5 Iterate drains the backlog at end-of-run alongside `issues/` and `ux-queue/` by default; the durable cross-run backlog of record lives at `build-loop-memory/projects/<slug>/backlog.md`. Cross-repo items are never mixed into one tracker.
+- **Retro → Learn wiring** — `scripts/enforce_retro_signals.py` normalizes the enforce-candidates and counts recurrence across distinct run-ids; the `recurring-pattern-detector` agent reads it as a second signal source (alongside `state.json.runs[]`) and emits `enforce_recurrence` patterns when the same candidate signature appears across ≥2 runs. Delivers "anything prompted or needed repeatedly → enforce" across sessions, not just within one.
+
+## Native Architecture & Debugging Skills
+
+Architecture and debugging are used on nearly every build, so build-loop ships native skills under:
+
+- `skills/architecture/{scan,impact,trace,rules,dead,review}/` — sourced from NavGator
+- `skills/debugging/{memory,store,assess,debug-loop}/` — build-loop-native RCA, investigation, memory, and storage workflows adapted from the debugger lineage
+
+Each sourced native SKILL.md frontmatter carries `source:` (relative path from `~/dev/git-folder/`) and `source_hash:` (SHA-256 at copy time). The orchestrator calls them directly in Phase 1 Assess, Review-B Validate, Review-D Fact-Check, Review-F Report, and Phase 5 Iterate cross-layer pre-step.
+
+Deep debugging remains first-class inside build-loop: causal-tree investigation, 5 Whys, fishbone categories, fault-tree branching, Kepner-Tregoe style problem boundaries, hypothesis falsification, fix verification, scorecards, and critique all live in native skills rather than an MCP process.
+
+Drift detection is a deliberate, opt-in pass:
+
+```bash
+python3 scripts/sync_skills.py
+# or
+Skill("build-loop:sync-skills")
+```
+
+The script recomputes each `source_hash` against the canonical upstream file and reports drift. Read-only — never auto-updates a SKILL.md. The legacy `skills/navgator-bridge/` and `skills/debugger-bridge/` deprecation stubs were removed in v0.10.0 — the orchestrator and downstream skills call the native skills directly.
+
+## Architecture awareness
+
+Build-loop owns native architecture awareness end-to-end. NavGator is now an optional escalation adapter, not a hard dependency.
+
+**Native engine** (`src/build_loop/architecture/`)
+Python-native scanner: `.gitignore`-aware walk, Python via `ast`, TS/JS via tree-sitter, plus Gator-style runtime edges for manifest package use, Next.js frontend API fetches, path-alias imports, and conservative service/LLM calls. Pure-function `compute_impact / trace_dataflow / check_rules / find_dead`. Output schema-parity with NavGator (component/connection JSON shapes verbatim) under `.build-loop/architecture/`.
+
+```bash
+uv run python -m build_loop.architecture {scan|impact|trace|rules|dead|connections|acp|acp-slice|llm-map|schema|diagram} \
+    [--mode auto|native|navgator] [--json] [--incremental|--full]
+```
+
+**`architecture-scout` subagent** (`agents/architecture-scout.md`)
+Sonnet, read-only, dispatched by the orchestrator at six phase points with one of five task types: `baseline`, `chunk-impact`, `review-rules`, `iterate-subgraph`, `learn-sync`. Decides native-vs-NavGator escalation per task. Returns ≤500-word JSON envelope; owns architecture-related side effects (violation capture, lessons sync).
+
+**Architecture Context Pack (ACP)** (`scripts/build_acp.py`, `scripts/slice_acp.py`)
+Compact JSON summary of current architecture state: top hotspots, recent violations, lessons-in-scope. Sliceable per file set with reverse-deps depth=1 + 4 KB cap. Embedded in subagent briefs at Phase 2 / 3 / 4 / 5.
+
+**Aggressive freshness** (`hooks/session-start-architecture.sh`, `hooks/pre-edit-architecture.sh`)
+SessionStart fires an incremental scan when manifest > 24 h old. PreToolUse Edit/Write triggers an async incremental scan when the touched file is parseable (extension allowlist: `.py .ts .tsx .js .jsx .mjs .cjs`); single-flight via `fcntl.flock`. Doc-only edits never fire scans.
+
+**Capability registry + ≤8 shortlist** (`scripts/build_capability_registry.py`, `scripts/capability_shortlist.py`, `skills/capabilities/SKILL.md`)
+116 capabilities indexed across 6 kinds (agent / skill / command / hook / mcp_tool / script) and 10 categories. Phase 1 invocation is **mandatory** — populates `state.json.activeCapabilities[<phase>]` with ≤8 relevant entries via plugin-surface collapse + trigger-aware demotion, keeping the orchestrator below the empirical tool-selection ceiling. Phase 2 / 3 dispatchers read the cache instead of re-scoring.
+
+**Memory facade** (`scripts/memory_facade.py`)
+Unified `recall(query, kind, project, limit, skip_postgres)` over file-backed and optional database surfaces — `state.json.runs[]` · canonical `~/dev/git-folder/build-loop-memory/projects/<project>/decisions/` plus migration-mode legacy decisions · local SQLite `indexes/semantic_facts.sqlite` · optional Postgres `semantic_facts` mirror. Debugging incident recall is native and file-backed by default; standalone Coding Debugger can provide cross-project MCP-backed recall when installed separately. Graceful degradation throughout; CLI accepts both `memory_facade.py --query ...` and the compatibility form `memory_facade.py recall --query ...`, including `--skip-postgres` for the optional Postgres path.
+
+**Backend health probe** (`scripts/backend_health.py`)
+Phase 1 sub-step probes each memory backend with per-backend 5 s timeout. Output: `runs: OK N | decisions: OK <legacy> + <canonical> | semantic: ok|down | debugger: ok|down`. Envelope cached at `state.json.architecture.backendHealth`. Phase 5 Iterate consumes it to short-circuit Postgres lookups when down.
+
+**Plan-verify rules** (`scripts/plan_verify.py`)
+Now includes `schema-migration-full-chain` — flags any commit touching writer/storage/schema files without matching test fixture or reader-path co-change. Catches the recurring drift pattern where writer keys diverge from reader expectations.
+
+**Web deploy verification** (`scripts/verify_deploy.py`)
+Phase 4 Review-B gate that runs after a deploy actually executed. Detects a Vercel link (`.vercel/project.json` or `vercel.json`), resolves the latest production deployment, polls `vercel inspect` to a terminal state, then probes the prod root + each changed route. An auth-gated `401`/`403` on a protected route is treated as **healthy** (the function deployed and is running) — only a `5xx`/build-error fails. Infra trouble (CLI missing, not authed) returns `skipped` and never blocks the build. Optional preferred-tier upgrade: the remote Vercel MCP, only if the user adds it to `.mcp.json` (build-loop does not add it). Inline degraded path: `fallbacks.md#web-deploy-verify`.
+
+**Decision capture loop**
+Every architecture violation surfaced by `rules` becomes a deduplicated decision in the canonical episodic store via `scripts/capture_arch_violation.py`. Recurring violations (≥3× across runs) get promoted to project-local lessons by `scripts/promote_violation_to_lesson.py` and one-way-synced into local SQLite `semantic_facts` for cross-project recall by `scripts/sync_navgator_lessons.py`. Postgres mirroring is explicit with `--postgres-mirror`.
+
+## External Skill Dependencies
+
+These skills enhance the loop when available but are not required:
+
+| Skill | Used In | Without It |
+|-------|---------|------------|
+| `writing-plans` | Phase 2 (Plan) | Write plan directly with file paths and dependency order |
+| `subagent-driven-development` | Phase 3 (Execute) | Dispatch parallel agents manually |
+| `calm-precision` | Phase 3 (Execute, UI) | Use standard UI best practices |
+| `verification-before-completion` | Phase 4 (Review sub-step B) | Run test/build/lint and confirm output manually |
+
+## Cross-Tool Support
+
+This repo includes `AGENTS.md` — the open-standard version of the build loop methodology. If you use Codex, Copilot, Cursor, Jules, or any other AI coding tool, that file provides the same 5-phase + mandatory Phase 6 Learn workflow without Claude-specific integration.
+
+Codex-specific subagent behavior lives in `skills/build-loop/references/codex-subagents.md` and `skills/build-loop/templates/codex-worker-prompt.md`. These files are additive: Claude Code continues to use the existing `agents/*.md` runtime, while Codex maps Build Loop ownership packets to explorer/worker-style delegation only when the user explicitly authorizes subagents or parallel work.
+
+## Project Data
+
+Build loop stores runtime data in `.build-loop/` within consumer projects:
+
+```
+.build-loop/
+├── goal.md          # Current build goal
+├── intent.md        # North star, update intent, user value, non-goals
+├── config.json      # Optional repo flags, including deploymentPolicy
+├── state.json       # Iteration state, including compact intent/structure summaries
+├── feedback.md      # Post-build lessons
+├── evals/           # Scorecard archives
+└── issues/          # Discovered issues
+```
+
+Add `.build-loop/` to your project's `.gitignore`.
+
+## License & Attribution
+
+This project is licensed under the [Apache License 2.0](LICENSE).
+
+- [`LICENSE`](LICENSE) — full license text.
+- [`NOTICE`](NOTICE) — attribution notices that, per Apache 2.0 §4(d), must travel with any redistribution of this work.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution conventions: per-file SPDX headers (REUSE 3.3), AI co-author trailer, signed commits, conventional commits.
+
+Per-file `SPDX-FileCopyrightText` and `SPDX-License-Identifier` headers are required on shipped source files. Files that cannot carry inline comments (JSON, generated assets) are annotated in [`REUSE.toml`](REUSE.toml). Validate compliance locally with `uvx reuse lint`.
+
+## Codex
+
+This package now ships an additive Codex plugin surface alongside the existing Claude Code package. The Claude package remains authoritative for Claude behavior; the Codex package adds a parallel `.codex-plugin/plugin.json` install surface without changing the Claude runtime.
+
+Package root for Codex installs:
+- the repository root (`.`)
+
+Primary Codex surface:
+- public entrypoint skills from `./codex-skills` when present
+- public entrypoint skill metadata only; build-loop does not expose a Codex MCP server
+
+Codex adapter files:
+- `skills/build-loop/references/codex-subagents.md`
+- `skills/build-loop/templates/codex-worker-prompt.md`
+
+The full `./skills` tree still ships with the package for Claude Code and for
+Build Loop's internal references. Codex only exposes the compact public
+entrypoint set in `./codex-skills` so helper skills do not crowd the `#` picker.
+Claude Code keeps the full tree addressable for commands/orchestrator internals,
+but helper skills are marked `user-invocable: false`. Cursor and other
+AGENTS.md-style tools should follow [`docs/agent-surface-policy.md`](docs/agent-surface-policy.md).
+
+Install the package from this package root using your current Codex plugin install flow. The Codex package is additive only: Claude-specific hooks, slash commands, and agent wiring remain unchanged for Claude Code.
+
+To check whether an installed Codex cache is using the current source instructions:
+
+```bash
+python3 scripts/check_cache_sync.py --host codex --source .
+```
+
+To remove stale Claude Code and Codex cache versions after a marketplace
+upgrade installs the current version:
+
+```bash
+python3 scripts/prune_plugin_cache.py --source . --apply
+```
+
+Host-specific variants are also available:
+
+```bash
+python3 scripts/prune_plugin_cache.py --source . --host codex --apply
+python3 scripts/prune_plugin_cache.py --source . --host claude --apply
+```