@tyroneross/build-loop 0.36.0 → 0.43.0

package/plugin-artifacts/codex/BUILD-ARTIFACT.md

@@ -1,5 +0,0 @@
-# Codex Build Loop Artifact
-
-Generated by `python3 scripts/build_codex_plugin_artifact.py`.
-This artifact is the Codex marketplace install surface.
-It exposes exactly one public skill: `build-loop`.

package/plugin-artifacts/codex/LICENSE

@@ -1,202 +0,0 @@
-
-                                 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/plugin-artifacts/codex/README.md

@@ -1,313 +0,0 @@
-<!-- build-loop@tyroneross:canary:build-loop -->
-<!-- canary-end -->
-# build-loop
-
-A portable, multi-phase build loop for AI coding agents. It gives Claude Code, Codex, and any AGENTS.md-aware tool the same disciplined operating loop: assess, plan, execute, review, iterate, then learn.
-
-> **Summary:** build-loop helps AI coding agents and the developers who run them ship multi-step code changes by running every change through a planned, reviewed, verified loop. Best for non-trivial features, refactors, migrations, and bug hunts across more than one file. Skip it for one-line edits, pure Q&A, or status checks.
-
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![npm](https://img.shields.io/badge/npm-%40tyroneross%2Fbuild--loop-cb3837.svg)](https://github.com/tyroneross/build-loop/pkgs/npm/build-loop)
-[![hosts](https://img.shields.io/badge/hosts-Claude_Code_%C2%B7_Codex_%C2%B7_AGENTS.md-5b21b6.svg)](#install)
-
-## Why build-loop
-
-Hand an agent a multi-step task and it tends to dive straight into edits, with no plan, no scope boundary, and no independent check that the result matches the goal. The failures compound: wrong assumptions ride into code, fixes patch symptoms, and "it compiles" gets reported as "it works."
-
-build-loop replaces that with a **structured loop every change runs through**: it assesses live repo state and memory, plans with explicit file ownership and pass/fail criteria, executes within scope, then runs an adversarial review (a critic, a fact-checker, a mock-data scanner) before iterating to green. The differentiator is portability and verification: the **same loop runs across Claude Code, Codex, and host-neutral AGENTS.md tools**, it is **multi-model by tier** (a frontier model plans and judges, a coding model executes), and **no completion claim ships without a verification step behind it**.
-
-## The loop
-
-```mermaid
-flowchart LR
-    A[Assess] --> P[Plan]
-    P --> E[Execute]
-    E --> R[Review]
-    R -->|fail| I[Iterate]
-    I --> R
-    R -->|pass| L[Learn]
-    subgraph Review
-        direction LR
-        R1[Critic] --> R2[Validate] --> R3[Optimize] --> R4[Fact-Check] --> R5[Simplify] --> R6[Auto-Resolve] --> R7[Report]
-    end
-```
-
-Assess → Plan → Execute → Review → Iterate (5x max) → Learn (always emits an outcome). Review runs seven ordered sub-steps; Iterate loops back to Review on failure.
-
-For the **living, auto-generated diagram** of how the loop actually wires up in this repo, covering every phase, gate, agent, skill, and script and regenerated from source so it cannot drift, open [`docs/build-loop-flow-mockup.html`](docs/build-loop-flow-mockup.html) in a browser. Format spec and drift gate: [`architecture/README.md`](architecture/README.md).
-
-## Quick start
-
-Install for all three host surfaces on macOS:
-
-```bash
-npm install -g @tyroneross/build-loop@0.36.0
-build-loop-install --host all
-```
-
-Then, in a Claude Code session inside your project, hand the loop a task:
-
-```text
-/build-loop:run add billing settings with tests
-```
-
-What you observe: the agent prints a short status line per phase (`[Phase 1: Assess]`, `[Phase 2: Plan]`, `[Phase 3: Execute]`, then each Review sub-step), then ends with a scorecard marking every acceptance criterion ✅ / ⚠️ / ❓. Completed, verified work is committed automatically; the only human-confirmation gates are production push, irreversible delete, and major user-impacting decisions.
-
-You do not pick a mode. `/build-loop:run` auto-routes build, fix, refactor, optimize, research, and test requests to the right path.
-
-## Install
-
-`build-loop-install` runs the package's helpers from the installed npm package:
-
-- Syncs the Claude Code cache from the package root.
-- Syncs the Codex cache from `plugin-artifacts/codex`, the slim Codex install artifact.
-- Bootstraps the build-loop memory root with public templates.
-- Leaves publishing, GitHub releases, and production deploys to explicit release commands.
-
-For GitHub Packages, authenticate first and point the `@tyroneross` scope at the GitHub registry:
-
-```bash
-npm config set @tyroneross:registry https://npm.pkg.github.com
-npm login --scope=@tyroneross --registry=https://npm.pkg.github.com
-npm install -g @tyroneross/build-loop@0.36.0
-build-loop-install --host all
-```
-
-Installer options:
-
-| Option | Use |
-|---|---|
-| `--host claude` | Sync only the Claude Code cache. |
-| `--host codex` | Sync only the Codex cache. |
-| `--host all` | Sync both caches. This is the default. |
-| `--project <slug>` | Ensure `projects/<slug>/raw/` exists in build-loop memory. Repeatable. |
-| `--memory-dest <path>` | Override the memory root. |
-| `--skip-memory` | Sync plugin caches only. |
-| `--dry-run` | Show cache sync actions without writing. |
-| `--json` | Emit one machine-readable result. |
-
-Local development install:
-
-```bash
-git clone https://github.com/tyroneross/build-loop.git
-cd build-loop
-npm install
-npm run build
-python3 scripts/sync_plugin_cache.py --source . --host claude
-npm run codex:sync-cache
-python3 scripts/install_memory.py --ensure-project build-loop
-```
-
-## Commands
-
-`/build-loop:run` is the only command. Describe the task in plain language — build, fix, refactor, optimize, research, debug, test, root-cause, retrospective, or plan — and the orchestrator classifies intent and routes to the right internal mode. You never pick a mode or a flag.
-
-```text
-/build-loop:run add billing settings with tests
-/build-loop:run tests pass locally but fail in CI        # routes to deep debugging
-/build-loop:run reduce API latency                       # routes to the optimize loop
-/build-loop:run compare queue providers                  # routes to research (no commits)
-/build-loop:run self-improve against recent runs         # runs Phase 6 Learn alone
-```
-
-Debugging is also auto-invoked by the loop itself on a review failure. The former mode and utility commands (`debug`, `research-run`, `test`, `self-improve`, `debugger*`, `assess`) are now internal, reached by intent rather than as separate commands.
-
-## Host surfaces
-
-The repo ships three agent surfaces from one source:
-
-- **Claude Code plugin**: plugin metadata, commands, hooks, and `agents/*.md`.
-- **Codex plugin**: Codex metadata plus a slim public skill entrypoint (`plugin-artifacts/codex/`).
-- **Host-neutral [`AGENTS.md`](AGENTS.md)**: the same loop methodology for any AGENTS.md-aware tool (Copilot, Cursor, and others), with no Claude-specific integration required.
-
-Surface counts in this release: one command (`/build-loop:run`), 44 skills, 28 agents.
-
-## Agent start protocol
-
-Start every build-loop repo session by checking Rally for coordination state: peers, claims, handoffs, and soft file conflicts. Rally verifies nothing on its own, so confirm code, package, version, and release truth from git, tests, manifests, registries, or GitHub directly.
-
-```bash
-rally enter --tool claude_code --json
-rally next --tool claude_code --json
-rally check before-write --tool claude_code --path README.md --strict --json
-```
-
-If the Rally binary is not installed, proceed without it. Full coordination rules: [`references/coordination-rules.md`](references/coordination-rules.md).
-
-Codex-specific delegation is opt-in. build-loop planning language such as "parallel-safe groups" does not by itself authorize Codex subagents. Spawn them only when the user explicitly asks for parallel delegation or passes a parallel flag.
-
-## How it works
-
-build-loop routes work through a lead orchestrator, invokes bounded subagents with scoped context, and accepts output only after verification. It is **multi-model by tier**: each role maps to an abstract tier (Frontier / Thinking / Code / Pattern), and any model that meets the tier's benchmark contract can fill it. The Anthropic mapping is the default; equivalents from other providers substitute when their benchmarks meet the tier contract.
-
-| Phase | Agent obligation |
-|---|---|
-| Assess | Read live repo state, tooling, memory, Rally, and current docs. Define the goal and pass/fail criteria. |
-| Plan | Produce a dependency-ordered plan with MECE file ownership, validation gates, and approach tradeoffs. |
-| Execute | Implement the accepted plan. Keep edits scoped to owned files. |
-| Review | Run critic, validate, fact-check, simplify, auto-resolve, and report steps. |
-| Iterate | Fix review failures until pass or a real blocker is reached. |
-| Learn | Always emit the Learn outcome and capture durable lessons when warranted. |
-
-<details>
-<summary><strong>Agent roles (full index)</strong></summary>
-
-These tables index agent roles. None of them are commands you run directly. Core authority follows [`references/agent-role-taxonomy.md`](references/agent-role-taxonomy.md): an agent is **core** when a pipeline step is contingent on its verdict, regardless of whether it is top-level or expensive. Model tier follows role; it does not define authority. Deterministic judge surfaces also exist outside `agents/` (`scripts/plan_verify.py`, `scripts/judgment_gate.py`, release verifiers); the tables below are the LLM-side surfaces.
-
-Each agent declares a `(segment, tier)` role that resolves to a concrete model at dispatch. Selection runs on two axes: a work-role **segment** (Generative Reasoning, Agentic Execution, Representation/Retrieval, Governance/Evaluation, plus dormant Realtime, Perception, and Generative Media lanes) and a seven-rung **capability tier** ladder (T0 through T5, plus T-S for specialist infrastructure). Both axes are encoded as data in [`references/model-taxonomy.json`](references/model-taxonomy.json), the **index** that is the durable source of truth. The `(segment, tier)` role is the KEY into that index; an agent's `model:` frontmatter is the index-DERIVED recommended fallback for the active host, kept in sync by [`scripts/sync_agent_model_defaults.py`](scripts/sync_agent_model_defaults.py) (never hand-edited). At dispatch the orchestrator resolves the role LIVE through [`scripts/resolve_agent_model.py`](scripts/resolve_agent_model.py) and OVERRIDES the frontmatter, so the running model always reflects the current index + availability. The `Tier` column below shows the legacy token (`Frontier`, `Thinking`, `Code`, `Pattern`), which aliases onto `T1`, `T2`, `T3`, `T4`, and the concrete model is an Anthropic fresh-install default. The index is **user-editable and chat-maintainable**: a new or different-provider model is adopted by classifying it once and reordering the cell, with no agent edits. Then `sync_agent_model_defaults.py --apply` regenerates the recommended `model:` values. Full mapping: [`references/model-tier-mapping.md`](references/model-tier-mapping.md).
-
-Resolution is availability-aware across dispatches: a model observed unavailable at dispatch (a provider outage) is recorded so the role falls back to the next host-reachable model in its tier — a frontier/judgment role degrades at most to the thinking tier, and a model the current host cannot dispatch is never offered. Outage records carry a timestamp and auto-expire after a TTL (`BUILD_LOOP_OUTAGE_TTL_SECONDS`, default 1800s), so a recovered model is picked up again without a manual clear. Recording and clearing run through [`scripts/dispatch_fallback.py`](scripts/dispatch_fallback.py); expiry is pruned on read in [`scripts/model_resolver.py`](scripts/model_resolver.py).
-
-### Lead / workflow agents
-
-| Agent | Description | Tier |
-|---|---|---|
-| `build-orchestrator` | Lead workflow owner for Assess → Plan → Execute → Review → Iterate → Learn; owns dispatch, phase transitions, commits, and report. | Thinking |
-| `assessment-orchestrator` | Multi-domain debugging coordinator for unclear symptoms across database, frontend, API, and performance lanes. | Thinking |
-| `optimize-runner` | Optimization-loop coordinator for metric-driven experiments, measurement, and regression handling. | Code |
-
-### Judgment / review agents
-
-| Agent | Description | Tier |
-|---|---|---|
-| `advisor` | Frontier planning author or re-planner when Phase 2 needs deeper synthesis. | Frontier |
-| `plan-critic` | Plan critique for dependencies, scope drift, validation, ownership, alternatives, and MECE quality. | Frontier |
-| `scope-auditor` | Plan-to-Execute boundary check and public-signature caller coverage. | Frontier |
-| `independent-auditor` | Independent adversarial review for chunk and build-scope completion claims. | Frontier |
-| `fix-critique` | Root-cause and regression pressure-test after a proposed fix. | Frontier |
-| `fact-checker` | Claim, metric, and rendered-data provenance checks before completion. | Frontier |
-| `security-reviewer` | Security review for auth, secrets, trust boundaries, injection, and adjacent risks. | Frontier |
-| `overfitting-reviewer` | Optimization review for test gaming, Goodhart effects, and overfitting. | Frontier |
-| `promotion-reviewer` | Review of proposed skill, agent, or enforcement promotions before activation. | Frontier |
-| `synthesis-critic` | Advisory coherence review for synthesis-heavy outputs across multiple dimensions. | Code |
-| `alignment-checker` | Advisory queue-item alignment check against current intent, goal, and non-goals. | Code |
-
-### Worker / specialist agents
-
-| Agent | Description | Tier |
-|---|---|---|
-| `implementer` | Bounded coding worker for one Phase 5 fix plan or criterion-targeted implementation packet. | Code |
-| `api-assessor` | API, route, auth, rate-limit, CORS, and request/response failure assessment. | Code |
-| `database-assessor` | Query, migration, schema, connection, vector index, and data integrity failure assessment. | Code |
-| `frontend-assessor` | React, rendering, hydration, state, component, and client performance assessment. | Code |
-| `performance-assessor` | Latency, memory, CPU, timeout, and bottleneck assessment. | Code |
-| `architecture-scout` | Read-only architecture baseline, impact, rules, iterate subgraph, and learn-sync tasks. | Code |
-| `design-contract-specialist` | UI/data input-output contracts, design direction, and traceability artifacts. | Code |
-| `ui-validator` | UI behavior, state, accessibility, layout, console, and rendering evidence validation. | Code |
-| `root-cause-investigator` | Causal-tree investigation for persistent or ambiguous failures. | inherit |
-| `mock-scanner` | Production-path scan for placeholder, fake, fixture, and mock data. | Pattern |
-
-### Learning agents
-
-| Agent | Description | Tier |
-|---|---|---|
-| `recurring-pattern-detector` | Repeated run-pattern and Learn-candidate detection from run history and retro signals. | Pattern |
-| `retrospective-synthesizer` | Background post-build retrospective and enforce-candidate summary. | Code |
-| `self-improvement-architect` | Experimental skill, agent, and workflow drafts from recurring lessons. | Code |
-| `transcript-pattern-miner` | Transcript mining for repeated patterns and self-improvement candidates. | Pattern |
-
-</details>
-
-## FAQ
-
-### What problem does it solve?
-
-Agents handed multi-step work tend to skip planning and verification, so wrong assumptions ride into code and "it compiles" gets reported as "it works." build-loop forces every change through a planned, reviewed, verified loop and refuses to claim completion without evidence behind it.
-
-### Who is it for, and who is it not for?
-
-It is for developers running AI coding agents on non-trivial changes: features, refactors, migrations, and bug hunts that touch more than one file. It is not for one-line edits, pure Q&A, or status checks; those skip the loop by design.
-
-### What is the fastest way to try it?
-
-`npm install -g @tyroneross/build-loop@0.36.0`, then `build-loop-install --host all`, then `/build-loop:run <your task>` inside a project. See [Quick start](#quick-start).
-
-### How is it different from just letting an agent code directly?
-
-A direct agent edit has no scope boundary and no independent check. build-loop adds explicit file ownership, pass/fail criteria, an adversarial review pass (critic, fact-checker, mock-data scanner), and automatic iteration to green. It also runs the same loop across Claude Code, Codex, and AGENTS.md tools, and routes planning/judging to a frontier model while execution runs on a coding model.
-
-## Runtime data
-
-Consumer projects store run state under `.build-loop/`:
-
-```text
-.build-loop/
-  goal.md
-  intent.md
-  config.json
-  state.json
-  feedback.md
-  evals/
-  issues/
-  backlog/
-```
-
-Add `.build-loop/` to a consumer project's `.gitignore` unless the repo intentionally tracks selected backlog or plan files.
-
-build-loop memory defaults to `~/.build-loop-memory` on a fresh machine, or an existing `~/dev/git-folder/build-loop-memory` when present. Bootstrap or inspect it:
-
-```bash
-python3 scripts/install_memory.py
-python3 scripts/install_memory.py --check
-```
-
-## Codex surface
-
-The Codex package exposes one public entrypoint skill through the slim artifact:
-
-```text
-plugin-artifacts/codex/
-  .codex-plugin/plugin.json
-  skills/build-loop/SKILL.md
-```
-
-The full `skills/` tree still ships for Claude Code and for internal references. Codex loads helper instructions only when the public build-loop skill asks for them.
-
-Check installed cache sync and prune stale versions:
-
-```bash
-python3 scripts/check_cache_sync.py --host codex --source plugin-artifacts/codex
-python3 scripts/check_cache_sync.py --host claude --source .
-python3 scripts/prune_plugin_cache.py --source . --host all --apply
-```
-
-## Release checklist
-
-For a plugin/package release, keep these version surfaces in lockstep:
-
-- `package.json`
-- `package-lock.json`
-- `.claude-plugin/plugin.json`
-- `.claude-plugin/marketplace.json`
-- `.codex-plugin/plugin.json`
-- `.agents/plugins/marketplace.json`
-- `plugin-artifacts/codex/.codex-plugin/plugin.json`
-
-Build and verify, then verify the release surface after tag/push:
-
-```bash
-npm run build
-python3 scripts/test_plugin_manifest.py
-python3 scripts/test_agent_surface_policy.py
-npm run codex:build-artifact
-npm pack --dry-run --json
-python3 scripts/verify_release_surface.py --version v0.36.0 --branch main --remote origin --json
-```
-
-Publishing to GitHub Packages, npmjs, or GitHub Releases is a release action. Run it only when explicitly requested by the human owner.
-
-## Limitations and known issues
-
-See [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md). Notably, the bare `/build-loop` command form is deprecated in favor of `/build-loop:run` because of a namesake collision with the skill of the same qualified name.
-
-## Architecture
-
-Short overview: [`ARCHITECTURE.md`](ARCHITECTURE.md). The living, auto-generated diagram and its drift gate are described under [The loop](#the-loop). Regenerate the diagram with `python3 scripts/architecture_diagram/generate.py`.
-
-## Contributing
-
-See [`CONTRIBUTING.md`](CONTRIBUTING.md). Agent build/test conventions for this repo live in [`AGENTS.md`](AGENTS.md) and [`CLAUDE.md`](CLAUDE.md).
-
-## License
-
-Apache-2.0. See [`LICENSE`](LICENSE), [`NOTICE`](NOTICE), and [`CONTRIBUTING.md`](CONTRIBUTING.md).

package/plugin-artifacts/codex/docs/agent-surface-policy.md

@@ -1,63 +0,0 @@
-# Agent Surface Policy
-
-Build Loop keeps one user-facing Codex entrypoint while preserving the richer
-Claude Code skill tree for hosts that can route helpers internally.
-
-## Public Entry Points
-
-Codex must expose exactly one user-facing Build Loop choice:
-
-- `build-loop` — main workflow and router for build, fix, debug, optimize,
-  research, knowledge capture, handoff, and plugin-test work
-
-Claude Code may expose advanced direct overrides in its command/skill surface
-where useful:
-
-- `build-loop`
-- `debug-loop`
-- `optimize`
-- `research`
-- `knowledge`
-- `handoff`
-
-## Host Rules
-
-Codex and ChatGPT install from `plugin-artifacts/codex`, not from the source
-repo root. Codex auto-discovers root `skills/*/SKILL.md` files and manifest
-skill paths supplement that default, so installing the source root leaks every
-internal helper into the picker. The artifact is generated by:
-
-```bash
-python3 scripts/build_codex_plugin_artifact.py --source . --target plugin-artifacts/codex
-```
-
-The artifact contains one `skills/build-loop/SKILL.md` copied from the
-canonical workflow and `.codex-plugin/plugin.json` rewritten to
-`"skills": "./skills"`. It must not contain any other `SKILL.md` files.
-
-The local Codex marketplace (`.agents/plugins/marketplace.json`) points at this
-artifact. Release and marketplace updates must do the same.
-
-Claude Code keeps `.claude-plugin/plugin.json` pointed at `./skills` because
-commands and orchestrator agents load internal skills by qualified name. Helper
-skills must set `user-invocable: false`; the public entrypoints set
-`user-invocable: true`.
-
-Cursor and other AGENTS.md-style tools should treat `AGENTS.md` plus this file
-as the routing contract. Start from `build-loop`. Read helper files under
-`skills/` only when the active entrypoint, a command, or an orchestrator
-instruction explicitly references them.
-
-## Cache Hygiene
-
-Plugin cache pruning is explicit and auditable:
-
-```bash
-npm run codex:sync-cache
-python3 scripts/prune_plugin_cache.py --source . --apply
-```
-
-`npm run codex:sync-cache` rebuilds the slim artifact first, then syncs that
-artifact into the Codex cache. The prune command keeps the current host manifest
-version and deletes older verified cache directories for the same plugin. Use
-`--host codex` or `--host claude` for a single host.

package/plugin-artifacts/codex/references/advisor-dispatch-ladder.md

@@ -1,62 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Advisor dispatch ladder (Phase 2 plan synthesis at Frontier)
-
-The Advisor (Fable) is the Frontier standing role that **authors and re-plans** the Phase 2 plan synthesis. Generating a plan is harder than evaluating one, so the deepest reasoning pays here — but the Advisor is **pull-based**: summoned only when stakes-gating trips, not every run. This ladder enforces that the plan is authored at Frontier *when it matters*, without breaking the runs where it doesn't.
-
-It deliberately **mirrors the GAP-1 independent-auditor ladder** (`phase-4-review.md` §"Sub-step A"). Same shape, same honesty discipline, an analogous `advisor_status` field. If you know that ladder, you know this one.
-
-## When the ladder is evaluated (stakes-gating)
-
-The orchestrator walks this ladder at the Phase 2 plan-synthesis step **only when** any of these objective triggers fire:
-
-- `state.json.synthesisDensity > 5` (synthesis-dense plan), or
-- `triggers.riskSurfaceChange` (security/persistence/runtime/deploy/trust boundary), or
-- `stakes >= medium` (from the commander's-intent posture / charter), or
-- an explicit `dispatch_tier: frontier` on any work item in the draft plan.
-
-If none trips, the ladder is skipped entirely — the orchestrator synthesizes the plan inline as today (most runs stay single-context; this respects the multi-agent-handoff risk by not decomposing more than needed). **Triggers are objective signals, never self-reported confidence** (models are systematically overconfident).
-
-## The four rungs (record `advisor_status` honestly)
-
-Dispatching the Advisor via `Agent(subagent_type="build-loop:advisor")` requires the Agent tool. A *nested* orchestrator (dispatched as a subagent — Mode B — or running per-commit mode) does **not** have the Agent tool, because the harness blocks sub-subagents. Walk the ladder and record `advisor_status`:
-
-1. **Rung 0 — own context already Frontier** (the orchestrator is itself running on Fable, e.g. `/build-loop:run` while the session model is Fable): **synthesize the plan inline** — it is *already* Frontier, no handoff needed. → `advisor_status: inline-frontier`. Zero added cost.
-
-2. **Rung 1 — Agent tool present** (top-level / Mode A, own context not already Frontier): **dispatch the Fable Advisor** (`Agent(subagent_type="build-loop:advisor")`) to author/re-plan, then verify via plan-critic + scope-auditor. → `advisor_status: ran:dispatched-agent`.
-
-3. **Rung 2 — no Agent tool, peer host reachable** (nested Mode B, but a peer host — rally channel / `codex exec` — can execute; reachable because the orchestrator retains Bash even when nested): **run the Advisor as a peer process** over the same channel the cross-vendor reviewer uses. Reconcile the peer's plan + envelope into the plan artifact. → `advisor_status: ran:peer-host(<host>)`. Prefer this over the fallback whenever a peer host can execute (fresh-context synthesis is plausibly *higher quality*, not merely cheaper — see "Quality, not only cost" below).
-
-4. **Rung 3 — none reachable** (no Agent tool, no peer host): **synthesize inline on the orchestrator's own model (Opus)**, labeled honestly. → `advisor_status: fallback:inline-opus`.
-
-## Non-breaking guarantee
-
-**Rung 3 IS today's behavior** — the orchestrator synthesizing the plan inline on Opus. The floor of this ladder equals the current state; it is strictly better whenever a dispatch path (Rung 1/2) or an already-Frontier context (Rung 0) is reachable. The handoff cost fires *only* in Rung 1/2 — i.e., only when the active context isn't already Frontier — so you pay it exactly where it buys an upgrade and never where planning is already Frontier. Worst case equals current; there is no regression path.
-
-## Quality, not only cost
-
-Dispatch is a **quality lever**, not just a cost knob. Context-separation evidence (⚠️ 2026 cross-context-review lead, directionally consistent with the corroborated self-correction literature: correction needs *external* feedback; intrinsic self-correction degrades accuracy) indicates synthesis in a *fresh* context beats same-session work. So Rungs 1/2 (fresh-context dispatch) are plausibly *higher quality* than Rung 0/3 inline — inline is a genuine quality compromise, taken only when dispatch is unreachable. The Advisor is a **separate agent**, never the executor self-reflecting.
-
-## Ledger row per Advisor action (the instrument)
-
-The orchestrator (single writer) appends one row to `.build-loop/agent-ledger.jsonl` per Advisor action via `scripts/agent_ledger.py`:
-
-```
-action: author | re-plan
-agent: advisor · tier: frontier · model: <resolved id (fable / gpt-5.x / …)>
-rung: 0|1|2|3 · status: pass|fail|partial · trigger: <synthesisDensity>5 | riskSurfaceChange | stakes>=medium | dispatch_tier:frontier>
-refs: {output: docs/plans/<slug>.md, input: <prior plan / failure evidence>}
-note: <on re-plan: failure evidence + why a retry is justified>
-```
-
-This closes the unmeasured quality-delta: the A/B test reads the ledger to compare plan outcomes by `rung`/`model` and find whether Frontier planning actually pays.
-
-## Re-plan mode (the remediation contract, v1)
-
-When the orchestrator diagnoses a **planning miss** during Iterate (the plan itself no longer fits, on an objective signal — test/build failure, auditor verdict, retry-count, scope breach), it re-enters this ladder with `action: re-plan`. The Advisor reads the **failure evidence + the diff vs the current plan**, diagnoses planning-miss vs execution-miss (*its* Frontier call, never the failing executor's self-report), and on a planning miss issues **corrected instructions** — a diff against the prior plan + the evidence — so execution resumes at the cheap tier on a sound plan.
-
-**v1 scope:** author + re-plan only. The **take-over-execution rung** (the Advisor executing a chunk directly) and **proactive mid-run checkpoint check-ins** are **v2** — land after the A/B confirms the core pays.
-
-## Always verified — never self-certifying
-
-The Advisor's authored/re-planned plan is checked by the existing Frontier critics before any implementer runs: `plan_verify.py` (deterministic) → `plan-critic` (reasoning; **blocking on the same stakes triggers**, advisory otherwise) → `scope-auditor` at the Plan→Execute boundary. Frontier-authored output does not get a pass on review. Keep the verification panel multi-specialist — do not collapse it to a single judge.