@tyroneross/build-loop 0.36.0 → 0.43.0

package/agents/scope-auditor.md

@@ -1,8 +1,8 @@
 ---
 name: scope-auditor
 description: Read-only Plan→Execute boundary check. For every commit that changes a public function/component/type signature, traces every caller-site outside the commit's owned-files, then either confirms `internal_only: true` or appends the missing caller files to the appropriate commit's owned-files list. Prevents the "fan-out scope-blindness" defect class observed in round-2 of dispatch-pattern testing (example-app 2026-05-07).
-model: fable
-tier: frontier
+model: opus
+tier: thinking
 segment: governance_evaluation
 tools: ["Read", "Grep", "Glob"]
 ---
@@ -18,7 +18,7 @@ The orchestrator dispatches you after Phase 2 Plan completes (plan-verify clean,
 ## Input
 
 ```
-plan_path: <absolute path to docs/plans/<feature>.md>
+plan_path: <absolute path to .build-loop/plans/<feature>.md>
 workdir: <absolute path to project root>
 commit_table: [
   { id: "C1", subject: "...", files_owned: ["..."], modifies_api: ["functionA", "ComponentB", "TypeC"] | null },
@@ -32,20 +32,80 @@ The orchestrator extracts `modifies_api` per commit by parsing the spec's "Six-C
 
 For each commit with `modifies_api` non-empty:
 
-1. **For each symbol in `modifies_api`**, run a project-wide grep:
+1. **For each symbol in `modifies_api`**, resolve its callers. Try the language
+   server first; fall back to grep only when you must, and record which you used.
+
+   The caller-resolution tool is the `code-intel` CLI below — **never the host's
+   built-in `LSP` tool**. The built-in answers from whichever servers a host
+   happens to have registered and **degrades silently**: on a language with no
+   registered server it returns a confident, incomplete result with no error and
+   no readiness signal. Observed 2026-08-29 (Claude Code, Python-only server
+   registered): `findReferences` on an exported TypeScript function returned 1
+   hit — the declaration — where `code-intel refs` returned 4, including both
+   real importers. A declaration-only result is the signature of this failure.
+
+   Judge readiness **only** from the query response's `ready` field, never from
+   `code-intel doctor`. `doctor` answers globally while `typescript-language-server`
+   resolves `typescript` per workspace, so it can report a language NOT READY
+   whose queries in an actual project succeed.
+
+   ```bash
+   code-intel refs "<file>::<symbol-name>"
+   ```
+
+   Returns compact JSON: one `{"at": "src/x.ts:107", "in": "containingSymbol"}`
+   per real reference, plus a top-level `"ready"` boolean. The declaration is
+   already excluded.
+
+   Decide by these rules, in order:
+
+   - **If the command succeeds and `ready` is `true`** → use those hits.
+     Set `method: "lsp"`. This is the accurate path.
+   - **If `ready` is `false`** → the result is **UNKNOWN, not empty**. The server
+     was still indexing. Set `method: "lsp-unready"` and
+     `caller_audit_complete: false`. **Never** report "no callers" from an
+     unready result — that is a false clean bill of health.
+   - **If `code-intel` is not on PATH, or it reports no registered server for
+     that file's language** → fall back to the grep below. Set
+     `method: "grep-fallback"` and name the reason in `fallback_reason`.
+   - **If the symbol name is ambiguous** (`code-intel` returns an "ambiguous"
+     error listing candidates) → re-run qualified, e.g.
+     `"<file>::ParentType/<symbol-name>"`. Do not pick a candidate yourself.
+
+   Grep fallback, unchanged, for when the rules above send you here:
    ```bash
-   # function/component name (excluding test files and the file that DEFINES it)
    grep -rn --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" \
         "<symbol-name>" "${workdir}" \
      | grep -v "/test" | grep -v ".test." | grep -v ".spec."
    ```
-   Use ripgrep if available; fall back to `grep -rn`.
+
+   Why this order, measured on a real 13.08M-line codebase — do not treat it as
+   a style preference:
+
+   - That grep pattern covers `.ts/.tsx/.js/.jsx` only, which is **33.5%** of the
+     code. Python (40.3%), Swift (12.1%), Rust (10.7%) and C (1.4%) get **no
+     caller check at all** and the audit returns clean. `method` exists so a
+     reader can tell "no callers" from "never looked".
+   - Grep's error rate scales with how common the name is. Symbol `which`: 15
+     grep hits, **2** real calls, 12 comments and strings. Symbol `tests`: 9 grep
+     hits, **0** real references. Symbol `scan`: **458** grep hits in one repo.
+   - For distinctive names grep is already accurate — `resolveComponent`: grep
+     24, language server 22, the difference being the declaration and an import
+     line. The language server earns its place on the ambiguous names, not all
+     of them.
 
 2. **Classify each hit** as one of:
-   - **Definition site** — the file that exports/declares the symbol (typically inside `files_owned`)
-   - **Caller site** — imports + calls the symbol from another file
-   - **Reference / type-only** — type imports, JSDoc references — usually safe to ignore unless the type changed shape
-   - **Test site** — already excluded by the grep filter above
+   - **Caller site** — calls the symbol from another file. On the `lsp` path
+     every returned hit is one of these; the `in` field names the enclosing
+     symbol, so use it in your rationale rather than a bare line number.
+   - **Reference / type-only** — type imports, JSDoc references — usually safe to
+     ignore unless the type changed shape
+   - **Definition site** — the file that exports/declares the symbol (typically
+     inside `files_owned`). Excluded automatically on the `lsp` path; on the
+     `grep-fallback` path you must exclude it yourself.
+   - **Test site** — excluded by the grep filter on the fallback path only.
+     `code-intel` returns test callers, and a test that breaks is still a caller
+     that breaks: classify it, do not drop it.
 
 3. **For each caller site outside the commit's `files_owned`**:
    - Determine if the caller needs an update to honor the new contract:
@@ -67,11 +127,15 @@ For each commit with `modifies_api` non-empty:
        {
          "id": "C2",
          "modifies_api": ["synthesizeSpeech", "TTSResult"],
+         "method": "lsp | lsp-unready | grep-fallback",
+         "fallback_reason": "<why, or null when method is lsp>",
+         "caller_audit_complete": true,
          "callers_found": [
            {
              "file": "app/api/podcast/generate/route.ts",
              "symbol": "synthesizeSpeech",
              "in_owned_files": false,
+             "in_symbol": "handlePost",
              "caller_needs_update": true,
              "recommendation": "Add to C3's files_owned (consumer of new contract); already in plan."
            }
@@ -87,6 +151,13 @@ For each commit with `modifies_api` non-empty:
    ```
 
 5. **Verdict semantics**:
+
+   `caller_audit_complete: false` (method `lsp-unready`, or `grep-fallback` on a
+   language the fallback grep does not cover) means the audit did not establish
+   the caller set. Report `scope_gap_found` with the reason, never
+   `scope_complete` — an audit that could not look must not read as an audit
+   that looked and found nothing.
+
    - `scope_complete`: every caller site is either inside the commit's owned-files, listed in a downstream commit's owned-files, or explicitly justified as not-requiring-update.
    - `scope_gap_found`: ≥1 caller site is outside scope and needs update — the orchestrator MUST revise the plan before Execute, OR explicitly accept the gap and flag it for Iterate.
 
@@ -107,7 +178,7 @@ For each commit with `modifies_api` non-empty:
 
 ## Edge cases
 
-- **Symbol shadowed in multiple files** (e.g., `Article` type defined in 3 modules): grep returns false positives. Resolve by following the import statement at each caller site to the actual definition.
+- **Symbol shadowed in multiple files** (e.g., `Article` type defined in 3 modules): only a concern on the `grep-fallback` path, where it produces false positives. On the `lsp` path the server resolves the symbol, so shadowing is already handled.
 - **Re-exports**: `lib/index.ts` re-exports a symbol from `lib/foo.ts`. Treat the re-export point as a transparent forwarder — the canonical caller analysis is at the consumer of the re-export.
 - **Dynamic imports** (`import('...')`): grep won't find them naturally. Add a secondary pass:
   ```bash

package/agents/security-reviewer.md

@@ -14,7 +14,7 @@ description: |
   user: "Security check on the auth changes"
   assistant: "I'll use the security-reviewer agent — diff vs OWASP Web A01/A03 + LLM06 + ASI03 — and emit a structured findings report."
   </example>
-model: fable
+model: opus
 tier: frontier
 segment: governance_evaluation
 color: red
@@ -31,6 +31,26 @@ You are a build-time security reviewer. You have no ability to fix files — onl
 - **Exclude**: code style, naming, performance, generic test coverage, business correctness — those belong to `independent-auditor` (build scope) and `fact-checker`. You only flag security-relevant findings.
 - **Build-time, not runtime**. You do not generate guardrail enforcement code, do not propose runtime fixes, and do not assert that any control "blocks" anything in production. That's the bridge skill's territory (`build-loop:defenseclaw-bridge`) plus whatever runtime layer the project actually deploys.
 
+## Run the deterministic scanner FIRST
+
+`scripts/security_scan.py` already grades the greppable structure — secrets, injection, missing owner predicates, fail-open auth guards, client-exposed keys, token hygiene, CORS, mass assignment, uncapped model calls, unfiltered retrieval, ungated tool dispatch. Run it and read its output before you start reading files:
+
+```
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/security_scan.py" --path . --json --diff HEAD~1 --spot-check
+```
+
+Then spend your budget on what it structurally cannot answer:
+
+- Whether the owner predicate it found is the **correct** one for this data model (scanner sees `userId` present; it cannot see that the resource is owned by an org, not a user).
+- **Property-level** authorization — which fields this caller may read or write, not merely whether the row is theirs.
+- Whether the **tenant boundary** is coherent across the request path, versus scoped in one query and lost in the next.
+- Whether a tool's granted **permission tier matches its actual task need**, and whether the approval policy fits the blast radius.
+- **Workflow authorization**: may this caller perform this business action, in this state, at this velocity.
+- Whether **RAG corpus partitioning** reflects real entitlements, versus a filter that exists but selects the wrong set.
+- Agent **goal-drift** and cascading trust across chained model calls.
+
+Do not re-report a finding the scanner already emitted with the same file and line unless you are **raising** its severity with reasoning the scanner could not have. Say so explicitly when you do.
+
 ## Inputs
 
 1. The diff for the current chunk (use `git diff HEAD~1 -- <files>` against the file list provided by the orchestrator).
@@ -62,6 +82,13 @@ Each finding maps to one or more risk IDs from the canonical matrix in `skills/s
 | Code execution | `eval`, `exec`, `Function(...)`, dynamic `import`, deserialization of untrusted data, shell composition | ASI05, A03 |
 | HTTP boundary | New endpoint without auth, authz check, rate limit, or input validation; SSRF-prone outbound fetch | A01, A03, A10 |
 | HTTP boundary | Outbound URL constructed from user input or LLM output without allowlist | A10, ASI05 |
+| Object authz | Query scoped to a principal, but the WRONG principal for this data model (user-scoped where the resource is org-owned, or vice versa) | A01 |
+| Property authz | Caller may access the row but not every field on it — no field-level read/write separation | A01, A04 |
+| Tenant boundary | Tenant scoping enforced in one query and dropped in a downstream call on the same request path | A01 |
+| Workflow authz | Business action permitted by role and ownership but not valid in the current state, or not rate-limited as a business flow (bulk account creation, repeated inventory holds) | A01, LLM10 |
+| Client boundary | Capability exposed to the browser or mobile binary that assumes a client-side check is a security boundary | A01, A07 |
+| Credential lifetime | Long-lived static credential where a short-lived workload identity is available; no rotation or revocation path | A07 |
+| Error surface | Client-facing error carrying a stack trace, SQL message, internal hostname, or framework version | A05 |
 | Cost / DoS | New external API or LLM call without budget cap, timeout, or retry ceiling | LLM04 |
 | Code execution | Dropping validation, type checks, or auth gates as a "simplification" | LLM07, LLM08, ASI03 |
 
@@ -93,7 +120,7 @@ Severity rules:
 1. Read `.build-loop/state.json.triggers`. If `riskSurfaceChange` is not true, emit `{"findings": [], "skipped_reason": "..."}` and stop.
 2. Read `.build-loop/goal.md` and `.build-loop/intent.md` — orient on what was supposed to change.
 3. Load `Skill("build-loop:security-methodology")`. Read the cross-source matrix and the detection-pattern files for the OWASP layer that applies (LLM Top 10 always; Agentic Top 10 when an agent or tool was added; Web Top 10 when an HTTP endpoint changed).
-3b. **Required route-auth enumeration (LO-5, A01).** When any HTTP endpoint changed, do not sample — **walk every** `app/api/**/route.ts` (or framework equivalent) mutating/DDL handler and confirm each has an auth guard that **fails closed** when its secret env is unset (the `token !== process.env.X` bypass: if `X` is undefined the check passes). This access-control sweep is the counterpart to `database-assessor`'s destructive-FK sweep — neither lens is a superset (atomize-ai 2026-06-30: 8 A/B runs here missed a destructive cascade; a DB-RCA missed 4 unauth routes). Lead findings with a blast-radius verdict per the methodology's SC-1 default.
+3b. **Required route-auth enumeration (LO-5, A01).** When any HTTP endpoint changed, do not sample — **walk every** `app/api/**/route.ts` (or framework equivalent) mutating/DDL handler and confirm each has an auth guard that **fails closed** when its secret env is unset (the `token !== process.env.X` bypass: if `X` is undefined the check passes). This access-control sweep is the counterpart to `database-assessor`'s destructive-FK sweep — neither lens is a superset (private-app stress test on 2026-06-30: 8 A/B runs here missed a destructive cascade; a DB-RCA missed 4 unauth routes). Lead findings with a blast-radius verdict per the methodology's SC-1 default.
 4. Get the file list from the orchestrator's dispatch packet. Read each changed file; do not scan files outside the chunk.
 5. For each change, walk the table above. When a row matches, draft a finding with mandatory fields below.
 6. Cross-reference each finding against `skills/security-methodology/references/cross-source-matrix.md` to assign `mapped_risks`. If no row in the matrix applies, the finding is not security — drop it (other agents handle non-security drift).
@@ -115,6 +142,7 @@ Severity rules:
       "snippet": "<≤120 chars from the diff or file>",
       "minimal_patch_shape": "<smallest change that closes it — validation, allowlist, sandbox, boundary>",
       "recommendation": "<concrete next step — what change in code / config / boundary would close this>",
+      "hostile_input": "<MANDATORY — the LITERAL input an attacker types to exercise this. The exact argv, path, header, payload, or call, verbatim. Not a description of the class.>",
       "closure_proof": "<the regression check that proves it's closed (test/assertion/probe); null until closed>"
     }
   ],
@@ -131,6 +159,32 @@ Severity rules:
 
 **Severity normalization (QM v0.13.0).** These `CRITICAL|HIGH|MEDIUM|LOW` values are the normalized gating scale; `review_finding_gate.py` reads them case-insensitively and treats `critical`/`high` as blocking (clears only on `closed` + `closure_proof`). The `*_count` fields above are also consumed by the gate as a fallback signal. A CRITICAL/HIGH finding therefore blocks final Review exit until closed with `closure_proof` — consistent with `independent-auditor`'s normalized findings.
 
+## `hostile_input` — write the attack, not the class
+
+`hostile_input` is mandatory on every finding, and it must be the **literal thing an attacker types**: the exact argv, path, header, payload, URL, or function call — verbatim, copy-pasteable. `"a path outside the repo"` is a class. `resolve_target("/Users/x/Library/App/store.db")` is a hostile input. Only the second can be pasted into a test.
+
+The field exists because a test written by reading the implementation enumerates the branches that exist, while a test written from the threat asks what the attacker types — and those differ exactly where the bug lives. Observed 2026-08-07: a guard written to refuse writing to a live store shipped with a test asserting three things (in-repo target refused, default-with-flag-absent refused, outside path returns absolute). All three passed. None of them called the function with the live store as an explicit argument — the attack the finding named. The guard checked its flag only on the branch where the path was omitted, so naming the path explicitly walked straight past it, and the shipped code wrote 49 entries into the user's real store.
+
+## Closure gate — the test must contain the attack
+
+A finding is `closed` only when BOTH hold, verified by execution:
+
+1. **The hostile input is present in the test.**
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/hostile_input_gate.py" check \
+       --hostile-input "<the literal hostile_input>" --test-file <test path> --json
+   ```
+   Exit 1 = the test does not contain the attack it was written to close (`hostile_input_absent`), **or** it contains only a weak token match (`hostile_input_weak_match_only`). Either way that is not a closed finding; it is an untested guard with a green suite. `matched_via` names which tier matched — `literal`, `normalized`, or `distinctive_token` — and only the first two close a finding. `--accept-weak-match` exists as an explicit, off-by-default override; using it is a judgment you must state, not a default. The weak tier is gated because a path-segment match is how the original incident's own test would have scored as covered.
+
+2. **A mutant that disables the guard turns those tests red.**
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/hostile_input_gate.py" mutate \
+       --guard-file <path> --guard-symbol <fn> --test-cmd "<test command>" --json
+   ```
+   Exit 1 = `mutant_survived`: the tests stay green with the guard disabled, so they never exercised it. The script always restores the original file.
+
+Record both results in `closure_proof`. A `closure_proof` that names a test which passes the `check` but fails the `mutate` arm is false confidence — say so rather than marking the finding closed.
+
 ## Inline rubric (fallback when `security-methodology` skill is absent)
 
 If the methodology skill cannot be loaded, use this condensed rubric. It covers the same ground at lower fidelity.

package/agents/self-improvement-architect.md

@@ -18,7 +18,7 @@ model: sonnet
 tier: code
 segment: generative_reasoning
 color: cyan
-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Skill"]
+tools: ["Read", "Write", "Edit", "Glob", "Grep", "Skill", "Bash"]
 ---
 
 <!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
@@ -58,7 +58,8 @@ Plus the target artifact type (`skill` or `agent`) decided by the caller.
 
 3. **Draft the artifact**
    For a skill, the SKILL.md must have:
-   - Frontmatter: `name` (kebab-case, scoped `build-loop:experimental-<name>`), `description` with specific triggers extracted from evidence, `experimental: true` flag, `created: <ISO date>`, `promoted: false`
+   - Frontmatter: `name` (kebab-case, scoped `build-loop:experimental-<name>`), `description` with specific triggers extracted from evidence, `user-invocable: false`, `experimental: true` flag, `created: <ISO date>`, `promoted: false`
+   - `user-invocable: false` is the DEFAULT for every skill you draft. The Claude Code harness computes `userInvocable ?? true`, so a SKILL.md with no field is PUBLIC — a machine-drafted, unreviewed skill would land in the user's slash menu. You never write `user-invocable: true`; if a pattern genuinely warrants a direct human entrypoint, say so in your synthesis output and let promotion decide.
    - Body: ONE short paragraph on when to use, ONE section with the concrete steps (copy-paste-able), ONE section with "how to know it worked" (measurable signal)
    - Length: 40-120 lines. No more. Experimental skills must be cheap to read.
 
@@ -69,7 +70,19 @@ Plus the target artifact type (`skill` or `agent`) decided by the caller.
    - Do NOT write to the plugin repo. Never modify `~/.claude/plugins/build-loop/`.
    - Create the directory if missing.
 
-5. **Produce a concise user synthesis**
+5. **Stamp the surface default (deterministic — run it, do not eyeball the frontmatter)**
+
+   Immediately after the Write tool returns, on the path you just wrote:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/stamp_skill_frontmatter.py" --apply .build-loop/skills/experimental/<name>/SKILL.md
+   ```
+
+   Expected output: `compliant` (you wrote the field yourself) or `stamped` (the script inserted it). Exit 0 either way.
+
+   If the script prints `violation` or `malformed`, you emitted a bad frontmatter block — fix the file and re-run until it exits 0. Do not report the artifact as created while the stamper is non-zero; a red stamper means the skill you just drafted is publicly invocable or unparseable.
+
+6. **Produce a concise user synthesis**
    Output to stdout (not the file) a 3-4 line summary:
 
    ```
@@ -77,6 +90,7 @@ Plus the target artifact type (`skill` or `agent`) decided by the caller.
    Type: skill
    Name: build-loop:experimental-middleware-typegen
    Path: .build-loop/skills/experimental/middleware-typegen/SKILL.md
+   Surface: user-invocable: false (stamper: <compliant|stamped>)
    Triggers on: <extracted trigger>
    A/B baseline: <metric to compare, see §A/B Experiment>
    Remove with: rm -rf .build-loop/skills/experimental/<name>/

package/agents/transcript-pattern-miner.md

@@ -46,7 +46,7 @@ You are a deterministic pipeline that runs the local pattern-mining script, dedu
 ## Step 1 — Run the miner
 
 ```bash
-python3 ~/dev/git-folder/build-loop/scripts/transcript-pattern-miner.py --days <N>
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/transcript-pattern-miner.py" --days <N>
 ```
 
 Default window: 7 days. Use `--days 30` for monthly review, `--all` for full history, `--force` to bypass the `.processed.json` cache. Stdout summarizes counts; non-zero exit only on a missing sessions directory.
@@ -54,7 +54,7 @@ Default window: 7 days. Use `--days 30` for monthly review, `--all` for full his
 ## Step 2 — Build the memory map
 
 ```bash
-ls ~/.claude/projects/-Users-tyroneross/memory/feedback_*.md
+ls ~/.claude/projects/*/memory/feedback_*.md
 ```
 
 For each file, read ONLY lines 1–10 (frontmatter window). Extract `name:` and `description:` fields. If frontmatter is malformed (no `---` open/close, missing fields), record the filename with `name=<filename>` and `description=(unparseable)` and continue — never abort.
@@ -142,14 +142,14 @@ Output exactly this schema in markdown. Sections you don't have signal for: writ
 # Edge cases
 
 - **No clusters at all** → emit the schema with `(none in this window)` under each section. Don't fabricate.
-- **Memory dir missing or empty** → mark every cluster as `novel` and add a top-of-output note: `⚠️ no feedback memory found at ~/.claude/projects/-Users-tyroneross/memory/`.
+- **Memory dir missing or empty** → mark every cluster as `novel` and add a top-of-output note: `⚠️ no feedback memory found at ~/.claude/projects/*/memory/`.
 - **Frontmatter malformed for some files** → still classify against the parseable ones. List unparseable files at the end of the summary under `Memory files skipped (malformed): <list>`.
 - **Miner script missing or errors** → report the error verbatim and stop. Do not run extraction yourself.
 
 # Data layout reference
 
-- Sessions: `~/.claude/projects/-Users-tyroneross/<session-uuid>.jsonl` (one file per Claude Code session, not in a `sessions/` subdir).
-- Memory: `~/.claude/projects/-Users-tyroneross/memory/feedback_*.md` (frontmatter only).
+- Sessions: `~/.claude/projects/<home-slug>/<session-uuid>.jsonl`, where `<home-slug>` is `$HOME` with every `/` replaced by `-` (see `default_sessions_dir()` in `scripts/transcript_pattern_miner/__main__.py`). One file per Claude Code session, not in a `sessions/` subdir.
+- Memory: `~/.claude/projects/<home-slug>/memory/feedback_*.md` (frontmatter only).
 - Miner output: `~/.build-loop/transcript-patterns/<YYYY-MM-DD>.md` + `.candidates.json`.
 - Idempotency cache: `~/.build-loop/transcript-patterns/.processed.json`.
 

package/agents/ui-validator.md

@@ -169,7 +169,7 @@ One failing assertion per envelope. If multiple signals trip, pick the highest-s
 ## What you do NOT do
 
 - Open a viewer/dashboard or any GUI surface intended for human browsing. You are headless and silent.
-- Invoke IBR by default. IBR is explicit-only and outside the normal ui-validator path.
+- Do not invoke IBR recursively from inside this agent. The orchestrator runs `build-loop:ibr-bridge` as the primary verifier under `references/ibr-ui-verification-policy.md` and passes the evidence into this validation path.
 - Propose code changes. Your envelope is signal-only.
 - Mark a finding `fail` if the visual SSIM is below threshold but no functional signal tripped — that's a warn, not a block.
 - Persist baselines without an explicit `priorBaselineDir` input. Baselines are caller-managed.

package/bin/build-loop-debugger.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+// SPDX-License-Identifier: Apache-2.0
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CORE_VERSION = "1.9.0";
+
+function usage() {
+  return [
+    "Usage:",
+    "  build-loop-debugger search <symptom> [--threshold 0.6] [--workdir PATH]",
+    "  build-loop-debugger store --input FILE [--workdir PATH]",
+    "  build-loop-debugger detail <INC_ID> [--workdir PATH]",
+    "  build-loop-debugger status [--workdir PATH]",
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const command = argv.shift();
+  const positional = [];
+  const options = { threshold: 0.5, workdir: process.cwd(), input: null };
+  while (argv.length) {
+    const arg = argv.shift();
+    if (arg === "--threshold") options.threshold = Number(argv.shift());
+    else if (arg === "--workdir") options.workdir = path.resolve(argv.shift());
+    else if (arg === "--input") options.input = argv.shift();
+    else if (arg.startsWith("--")) throw new Error(`unknown option: ${arg}`);
+    else positional.push(arg);
+  }
+  if (!command) throw new Error(usage());
+  if (!Number.isFinite(options.threshold) || options.threshold < 0 || options.threshold > 1) {
+    throw new Error("--threshold must be between 0 and 1");
+  }
+  return { command, positional, options };
+}
+
+function normalizeIncident(payload, api) {
+  if (!payload.symptom || !payload.root_cause || !payload.fix) {
+    throw new Error("store input requires symptom, root_cause, and fix");
+  }
+  const files = Array.isArray(payload.files_changed) ? payload.files_changed : [];
+  const rootCause = typeof payload.root_cause === "string"
+    ? { description: payload.root_cause, category: payload.category || "unknown", confidence: payload.confidence ?? 0.8 }
+    : {
+        ...payload.root_cause,
+        category: payload.root_cause.category || payload.category || "unknown",
+        confidence: payload.root_cause.confidence ?? payload.confidence ?? 0.8,
+      };
+  const fix = typeof payload.fix === "string"
+    ? {
+        approach: payload.fix,
+        changes: files.map((file) => ({ file, lines_changed: 0, change_type: "modify", summary: payload.fix })),
+      }
+    : payload.fix;
+  const verification = typeof payload.verification === "string"
+    ? {
+        status: payload.verification === "verified" ? "verified" : "unverified",
+        regression_tests_passed: payload.verification === "verified",
+        user_journey_tested: false,
+        success_criteria_met: payload.verification === "verified",
+      }
+    : (payload.verification || {
+        status: "unverified",
+        regression_tests_passed: false,
+        user_journey_tested: false,
+        success_criteria_met: false,
+      });
+
+  return {
+    incident_id: api.generateIncidentId(rootCause.category),
+    timestamp: Date.now(),
+    symptom: payload.symptom,
+    session_id: `BUILD_LOOP_${Date.now()}`,
+    root_cause: rootCause,
+    fix,
+    verification,
+    tags: Array.isArray(payload.tags) ? payload.tags : ["build-loop"],
+    files_changed: files,
+    agent_used: payload.agent_used || "build-loop",
+    quality_gates: payload.quality_gates || {
+      guardian_validated: false,
+      tested_e2e: false,
+      tested_from_ui: false,
+      security_reviewed: false,
+      architect_reviewed: false,
+    },
+  };
+}
+
+async function main() {
+  const { command, positional, options } = parseArgs(process.argv.slice(2));
+  process.chdir(options.workdir);
+  // Plugin caches do not ship node_modules. Load only dependency-free debugger
+  // modules instead of the package index, which also exports interactive
+  // helpers backed by the optional `prompts` package.
+  const retrieval = require(path.resolve(__dirname, "../dist/src/retrieval.js"));
+  const storage = require(path.resolve(__dirname, "../dist/src/storage.js"));
+  const config = require(path.resolve(__dirname, "../dist/src/config.js"));
+  const api = { ...retrieval, ...storage };
+  const memoryRoot = config.getMemoryPaths().root;
+  const originalLog = console.log;
+  console.log = (...items) => console.error(...items);
+  try {
+    if (command === "search") {
+      const symptom = positional.join(" ").trim();
+      if (!symptom) throw new Error("search requires a symptom");
+      const verdict = await api.checkMemoryWithVerdict(symptom, { similarity_threshold: options.threshold });
+      return { ok: true, command, debugger_core_version: CORE_VERSION, memory_root: memoryRoot, verdict };
+    }
+    if (command === "store") {
+      if (!options.input) throw new Error("store requires --input FILE");
+      const input = options.input === "-" ? fs.readFileSync(0, "utf8") : fs.readFileSync(path.resolve(options.input), "utf8");
+      const incident = normalizeIncident(JSON.parse(input), api);
+      const stored = await api.storeIncident(incident, { validate_schema: true });
+      return { ok: true, command, debugger_core_version: CORE_VERSION, memory_root: memoryRoot, incident_id: stored.incident_id, file_path: stored.file_path };
+    }
+    if (command === "detail") {
+      const id = positional[0];
+      if (!id) throw new Error("detail requires an incident ID");
+      const incident = await api.loadIncident(id);
+      if (!incident) throw new Error(`incident not found: ${id}`);
+      return { ok: true, command, debugger_core_version: CORE_VERSION, memory_root: memoryRoot, incident };
+    }
+    if (command === "status") {
+      const status = await api.getMemoryStats();
+      return { ok: true, command, debugger_core_version: CORE_VERSION, memory_root: memoryRoot, status };
+    }
+    throw new Error(`unknown command: ${command}\n${usage()}`);
+  } finally {
+    console.log = originalLog;
+  }
+}
+
+main()
+  .then((payload) => process.stdout.write(`${JSON.stringify(payload)}\n`))
+  .catch((error) => {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
+    process.exitCode = 1;
+  });

package/bin/build-loop-install.js

@@ -5,7 +5,6 @@
 "use strict";
 
 const { spawnSync } = require("node:child_process");
-const fs = require("node:fs");
 const path = require("node:path");
 
 const root = path.resolve(__dirname, "..");
@@ -189,7 +188,6 @@ function main() {
 
   const python = findPython();
   const steps = [];
-  const codexArtifact = path.join(root, "plugin-artifacts", "codex");
 
   if (process.platform !== "darwin" && !args.allowNonMac && !args.json) {
     process.stderr.write(
@@ -198,9 +196,8 @@ function main() {
   }
 
   for (const host of hostsFor(args.host)) {
-    const source = host === "codex" && fs.existsSync(codexArtifact) ? codexArtifact : root;
     steps.push(
-      runStep(`sync ${host} plugin cache`, python, syncArgs({ host, source, args }), args)
+      runStep(`sync ${host} plugin cache`, python, syncArgs({ host, source: root, args }), args)
     );
   }