@tyroneross/build-loop 0.30.3

package/skills/security-methodology/references/owasp-llm-top-10.md

@@ -0,0 +1,144 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# OWASP Top 10 for LLM Applications (v1.1, 2025)
+
+Component-and-content-level risks. Frames the LLM as a component inside a wider application — these risks apply to any LLM-backed feature, agent or otherwise.
+
+**Source.** `https://owasp.org/www-project-top-10-for-large-language-model-applications/` — T1, OWASP project page. Retrieved 2026-05-02.
+
+## Reading these tables
+
+Each row is one risk. The **Detection patterns** column lists what to grep for in a diff or look for during code review — these are signals, not proofs. Some signals are unambiguous (eval of LLM output → LLM02 + ASI05); most are necessary-not-sufficient and pair with a judgment call about the surrounding code.
+
+## LLM01 — Prompt Injection
+
+**What it covers.** Crafted inputs hijack the model's behavior. Two flavors: **direct** (attacker controls the user input) and **indirect** (attacker controls retrieved content, tool output, file contents, or upstream LLM output that the target LLM later reads).
+
+**Detection patterns.**
+- Template strings or string concatenation that puts a user-controlled value into a system prompt position. Look for `f"...{user_input}..."`, `` `${...}` `` in template literals, `prompt.format(...)`, or any direct interpolation of unsanitized strings into the request body.
+- Tool output, search results, web content, RAG snippets, file contents, or another agent's output appended to the LLM context with no separator, no provenance tag, and no instruction-vs-data delimiter.
+- A `system` and `user` message constructed from a single concatenated string instead of distinct roles.
+- Use of `system` content sourced from a database or external store without integrity check (poisoned-system-prompt vector).
+
+**Adjacent agentic risk.** Pairs with **ASI01** (Agent Goal Hijack) when the prompt-injectable LLM is an agent that takes actions.
+
+## LLM02 — Insecure Output Handling
+
+**What it covers.** Treating LLM output as trusted input downstream — XSS, SQL injection, command injection, SSRF, or RCE *because* the application trusts what the model returned.
+
+**Detection patterns.**
+- LLM output rendered with `dangerouslySetInnerHTML`, `innerHTML`, `v-html`, or `{@html ...}` without sanitization.
+- LLM output passed to `exec`, `Function(...)`, dynamic `import`, `child_process.exec`, `subprocess.run(..., shell=True)`, `eval`, or any string-to-code path.
+- LLM output concatenated into SQL/NoSQL queries, OS commands, file paths, URLs (especially for `fetch` / `requests.get`), or shell scripts.
+- LLM output used as a redirect target, an Open Graph URL, or a webhook URL without an allowlist.
+- LLM output deserialized via `pickle`, `yaml.load(..., Loader=yaml.Loader)`, `JSON.parse` followed by no schema validation, or any unsafe deserializer.
+
+**Adjacent agentic risks.** Pairs with **ASI05** (Unexpected Code Execution) and **ASI08** (Cascading Failures, when the unsanitized output is the input to a downstream agent).
+
+## LLM03 — Training Data Poisoning
+
+**What it covers.** Tampered training data corrupts model behavior. For most product teams, the *training* surface is owned by the model provider (OpenAI / Anthropic / etc.), so this risk shifts toward **fine-tuning** and **RAG corpus** poisoning.
+
+**Detection patterns.**
+- Fine-tuning data ingested from a user-writable source without curation, sampling review, or provenance tags.
+- RAG corpus ingestion that accepts uploads from end users into a shared index used across users.
+- A mechanism to update embeddings or retrieval weights without an approval gate.
+- Memory or "learned preferences" persisted across sessions for one user but reachable from another user's queries (related to ASI06).
+
+**Adjacent agentic risk.** Pairs with **ASI10** (Rogue Agents) at the most severe end — a poisoned fine-tune produces an agent whose alignment drift is invisible at deploy time.
+
+## LLM04 — Model Denial of Service
+
+**What it covers.** Resource-exhaustion attacks: token bombs, recursive prompts, expensive tool chains, infinite loops between agents.
+
+**Detection patterns.**
+- New LLM call without a `max_tokens` ceiling, request timeout, or per-run budget.
+- New agent loop without an iteration cap.
+- Tool that calls LLM that calls tool, with no circuit breaker.
+- User input length not bounded before being placed in the prompt.
+- Multiple parallel LLM calls without a concurrency cap.
+- Recursive/self-calling agent without a depth limit.
+
+**Cost angle.** Cost runaway is the boring twin of DoS — same root cause (no ceiling), different victim (your wallet). Treat them as one finding.
+
+## LLM05 — Supply Chain Vulnerabilities
+
+**What it covers.** Compromised model weights, datasets, libraries, plugins, MCP servers, prompt templates, A2A peers. Provenance, pinning, scanning.
+
+**Detection patterns.**
+- New `pip install` / `npm install` / `cargo add` of an LLM-adjacent package without a pinned version (`==X.Y.Z` for Python, exact version for npm).
+- New MCP server or plugin pulled from a non-organization source (random GitHub user, npm registry without an internal mirror).
+- Model loaded by name from Hugging Face or similar without a hash pin (organization-confusion attack vector).
+- Skill, agent, or prompt template imported from an external repository without a SHA pin.
+- Generated code (Codex, Cursor, Copilot output) committed without a review pass.
+
+**Adjacent agentic risk.** Pairs with **ASI04** (Agentic Supply Chain) and **OWASP Web A06** (Vulnerable & Outdated Components).
+
+## LLM06 — Sensitive Information Disclosure
+
+**What it covers.** The model reveals sensitive content from the training set, the system prompt, the context window, or another user's conversation.
+
+**Detection patterns.**
+- Secrets (API keys, tokens, DB URLs) injected into the system prompt or request body. Anything matching `sk-`, `Bearer `, `password=`, `api_key=`, or environment variables landing in prompt strings.
+- PII or regulated data (SSN, payment, health) included in prompt context without a redaction pass.
+- A single LLM context shared across users (cache key based on prompt content alone, not user-scoped).
+- LLM output streamed to a log without redaction.
+- Internal tool documentation or schema dumped into the prompt where attackers could exfiltrate it via prompt injection.
+
+**Cross-map.** This is the **NIST Data Privacy** + **Information Security** intersection.
+
+## LLM07 — Insecure Plugin Design
+
+**What it covers.** Plugins/tools accept LLM-generated input without validation, lack access control, or have over-broad scopes.
+
+**Detection patterns.**
+- Tool schema accepts `string` for a parameter that should be a typed enum, validated path, or scoped ID.
+- Tool uses ambient credentials (the agent's keys, not the user's) for an action that should be scoped to a user identity.
+- Tool action that writes/deletes/external-calls without a `requires_human_approval: true` or equivalent gate.
+- Tool that takes a URL/path/SQL string and passes it through to the underlying system without validation.
+- Tool catalog exposes more capabilities to the agent than the workflow needs ("just expose all of GitHub" pattern).
+
+**Cross-map.** Heavy overlap with **ASI02** (Tool Misuse) and **ASI03** (Privilege Abuse). When in doubt, cite both LLM07 and ASI02/ASI03 — they're not redundant, they describe the same surface from different angles.
+
+## LLM08 — Excessive Agency
+
+**What it covers.** The damaging-action vector. The agent has more functionality, more permissions, or more autonomy than it needs to perform its job, and an attacker (via LLM01) or a confused state turns that into harm.
+
+**Detection patterns.**
+- Tool list larger than the role description requires.
+- Permission tier higher than the action class requires (T5 for a read; T4 when no user comms is needed).
+- Autonomy level above what the use case requires (A3 "execute reversible" when A1 "draft" would do).
+- No human-in-the-loop checkpoint at the autonomy/permission boundary where one is plausible.
+- "Just give the agent admin" style provisioning.
+
+**Cross-map.** This is the cross-cutting agentic risk in the LLM Top 10. The OWASP Agentic Top 10 (ASI02 + ASI03) replaced and refined this in 2026; both still apply at design-time review.
+
+## LLM09 — Overreliance
+
+**What it covers.** A human-in-the-loop reviewer who doesn't critically assess LLM output and approves harm.
+
+**Detection patterns.**
+- "Confirm" / "Approve" UX with the model's reasoning displayed prominently and the underlying evidence buried.
+- No diff or provenance shown alongside an LLM-suggested change.
+- Default-yes confirm flows for non-trivial actions.
+- Confidence claims surfaced from the model directly ("I'm 95% sure") without independent calibration.
+- Auto-approval thresholds set against the model's self-reported confidence.
+
+**Cross-map.** Pairs with **ASI09** (Human-Agent Trust Exploitation), which is the more pointed framing in the agentic taxonomy.
+
+## LLM10 — Model Theft
+
+**What it covers.** Unauthorized access to proprietary model weights or architecture.
+
+**Detection patterns.**
+- Public-facing endpoint that returns logits, embeddings, or fine-tuned model state without auth/rate limiting.
+- API key leakage in client-bundled code or git history.
+- Weight files committed to a public repo.
+
+**Most product teams don't host weights.** For agent-builder-style apps that consume hosted models (OpenAI, Anthropic, Bedrock, Vertex), LLM10 collapses to "don't leak the API key" — which is LLM06 in practice. Flag it explicitly only when fine-tuned weights or self-hosted models are in play.
+
+## What this file does not contain
+
+- Fix code. The agent that finds an LLM01 vulnerability does not patch it; it routes to Iterate with the finding.
+- The full OWASP write-up. For the canonical text, citation, and authority lineage, follow the source URL above.
+- Scoring guidance. Severity is set by `agents/security-reviewer.md` based on exploitability and consequence; this file lists detection signals, not severity heuristics.

package/skills/security-methodology/references/owasp-web-top-10.md

@@ -0,0 +1,65 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# OWASP Top 10 (Web) 2025 — relevant subset for LLM-backed apps
+
+The web Top 10 still applies under any agent that exposes HTTP endpoints, calls APIs, or processes user-controlled URLs. This file enumerates the four risks that materially overlap with LLM/agentic concerns. The other six (A02 Cryptographic Failures, A04 Insecure Design, A05 Security Misconfiguration, A07 Identification and Authentication Failures, A08 Software and Data Integrity Failures, A09 Security Logging and Monitoring Failures) still apply in their classic form — they're not LLM-specific. This file does not re-enumerate them; the canonical write-up lives at the source.
+
+**Source.** `https://owasp.org/www-project-top-ten/` — T1, OWASP project page. Retrieved 2026-05-02.
+
+## A01 — Broken Access Control
+
+**Why it matters for agents.** An agent acting on behalf of user A must not access user B's data. Authorization must be enforced **downstream of the LLM** — the LLM cannot be the auth layer. The most common modern failure is "the agent passes a user ID parameter to the tool, the tool trusts that ID."
+
+**Detection patterns.**
+- Tool implementation that uses an `agent_supplied_user_id` parameter to scope access without verifying it against the authenticated session/JWT.
+- Endpoint that authenticates the request (good) but doesn't authorize the *target* (the user whose data is being read or written).
+- LLM-generated SQL or query string that includes a tenant/user ID without parameterization or row-level security.
+- Multi-tenant agent deployments where the tenant boundary lives in the prompt ("you are working for tenant X") rather than in the data layer.
+- Public-by-default share links generated by the agent without expiry, scope, or revocation path.
+
+**Cross-map.** Pairs with **ASI03** (Identity and Privilege Abuse). A finding that's both A01 and ASI03 is the canonical "the LLM crossed a tenant boundary" failure.
+
+## A03 — Injection
+
+**Why it matters for agents.** Classic SQL/command/template injection still applies whenever an LLM-generated string ends up in a query, shell, template, or evaluator. The agentic twist: the attacker doesn't write the injection directly — the attacker writes a prompt that gets the LLM to write the injection.
+
+**Detection patterns.**
+- LLM output concatenated into a SQL/NoSQL query (no parameterized queries, no ORM scope).
+- LLM output passed to `subprocess.run(..., shell=True)`, `child_process.exec`, or any string-based shell composition.
+- LLM output rendered through a templating engine that allows expression evaluation (`{{ ... }}` patterns in Jinja-style templates).
+- LLM output used as a path component in `fetch`, `requests.get`, `open`, or any file/URL accessor.
+- LLM output used as part of an LDAP query, XPath, or a serialized binary command frame.
+
+**Cross-map.** Pairs with **LLM02** (Insecure Output Handling) and **ASI05** (Unexpected Code Execution). The sequence is: LLM01 enables A03; A03 escalates to ASI05 if RCE is reachable.
+
+## A06 — Vulnerable and Outdated Components
+
+**Why it matters for agents.** The agent's surface includes its model SDK, the orchestration framework, the tool plugins, the MCP servers it connects to, the prompt templates it loads. All of those have versions; all of those drift; all of those publish CVEs.
+
+**Detection patterns.**
+- New `pip install` / `npm install` / `cargo add` of an LLM-adjacent package without a pinned version.
+- Lockfile not committed alongside the manifest.
+- Dependency on a model SDK or orchestration framework with no upgrade plan and no `dependabot` / `renovate` / equivalent.
+- MCP server pulled from a public registry without an internal mirror or scan.
+- Generated code (Codex, Cursor, Copilot output) committed without a review pass.
+
+**Cross-map.** Pairs with **LLM05** (Supply Chain) and **ASI04** (Agentic Supply Chain). LLM05 is the *content* angle (the model could have been poisoned); ASI04 is the *agent system* angle (the entire agent could have been compromised); A06 is the *traditional dependency* angle (CVE in the SDK). All three apply to the same install.
+
+## A10 — Server-Side Request Forgery
+
+**Why it matters for agents.** Agents that fetch URLs are SSRF-prone by default. The attacker writes a prompt; the agent decides to fetch a URL; the URL points at internal infrastructure.
+
+**Detection patterns.**
+- Tool / endpoint that takes a URL and `fetch`es it with no allowlist, no DNS rebinding protection, no IP-range restriction.
+- Outbound URL constructed from LLM output without validation.
+- Agent that "browses the web" without an egress proxy, allowlist, or scope.
+- Webhook URL stored from user/agent input and called server-side later.
+- Image/file/preview-fetcher that takes a URL parameter and returns the bytes.
+
+**Cross-map.** Pairs with **ASI05** (Unexpected Code Execution) when the SSRF reaches an internal RCE-prone endpoint, and with **LLM07** (Insecure Plugin Design) when the SSRF tool is a plugin without scope.
+
+## What this file does not contain
+
+- The other six web risks. They apply in classic form; cite the OWASP source URL when one of them is the issue.
+- Guidance on which boundary owns the fix (frontend, gateway, BFF, downstream service). That depends on the project's architecture; this file enumerates risk and detection only.
+- Severity scoring. `agents/security-reviewer.md` assigns severity using the rubric in its own SKILL frontmatter; this file lists detection signals.

package/skills/self-improve/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: build-loop:self-improve
+description: Use when Phase 6 Learn fires automatically after Report, the user runs `/build-loop:self-improve`, or asks to "scan recent runs" or "improve build-loop". Scans recent runs for recurring patterns, auto-drafts experimental skills/agents with A/B tracking.
+version: 0.1.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Build-Loop Self-Improvement (Phase 6 Learn)
+
+This skill runs after Review sub-step F (Report) completes, or on demand. It detects recurring patterns across recent build-loop runs, drafts experimental skills/agents to address them, and notifies the user for keep/remove decisions.
+
+**Principle:** auto-draft, notify, experiment, decide based on evidence. User can always remove. A/B comparison is small and focused — one metric, short sample, clear decision rule.
+
+## When This Skill Runs
+
+- Automatically at end of every build-loop run (Phase 6 Learn, after Review sub-step F (Report))
+- On demand via `/build-loop:self-improve`
+- Skipped if `.build-loop/state.json.runs` has fewer than 3 entries — not enough signal
+
+## Flow
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ Phase 6 Learn: REVIEW (this skill)                                  │
+├──────────────────────────────────────────────────────────────┤
+│ 1. DETECT   → recurring-pattern-detector (Haiku)              │
+│              emits patterns[] JSON                            │
+│ 2. FILTER   → keep only confidence:high or count >= threshold │
+│ 3. DRAFT    → for each kept pattern:                          │
+│              self-improvement-architect (Sonnet)              │
+│              writes .build-loop/skills/experimental/<name>/   │
+│ 4. SIGNOFF  → build-orchestrator (Opus 4.7) reviews each:     │
+│              approve, revise, or discard                      │
+│ 5. TRACK    → record baseline in .build-loop/experiments/     │
+│ 6. NOTIFY   → synthesize 3-5 line summary to user             │
+│              (include removal command + A/B plan)             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Steps
+
+### 1. Detect recurring patterns
+
+```
+Agent: recurring-pattern-detector (haiku)
+Input: read .build-loop/state.json
+Output: {scannedRuns, patterns: [...]}
+```
+
+If `patterns.length === 0`, skip to step 6 (notify with "no patterns detected, N runs scanned"). End.
+
+### 2. Filter
+
+Keep patterns matching any of:
+- `confidence === "high"`
+- `count >= 4` regardless of confidence
+- `type === "manual_intervention"` (user time is expensive; lower threshold)
+
+Drop the rest. Log skipped patterns in `.build-loop/experiments/skipped.jsonl` with date + reason — lets us tune thresholds later without losing signal.
+
+### 3. Draft experimental artifacts
+
+For each kept pattern, dispatch:
+
+```
+Agent: self-improvement-architect (sonnet)
+Input: the pattern object + target type (skill or agent)
+Output:
+  - writes .build-loop/skills/experimental/<name>/SKILL.md (or agents/experimental/<name>.md)
+  - returns concise 3-4 line synthesis
+```
+
+The architect agent includes an A/B Experiment section in every artifact it writes.
+
+### 4. Opus 4.7 signoff
+
+Build-orchestrator (Opus 4.7) reads each drafted artifact and decides:
+
+- **APPROVE** — artifact is coherent, pattern is real, A/B plan is measurable → proceed to track
+- **REVISE** — core idea is right, execution needs tightening → re-dispatch architect with specific feedback, max 1 revision pass
+- **DISCARD** — pattern is noise or artifact is unusable → delete the file, log to `.build-loop/experiments/discarded.jsonl` with reason
+
+Opus signoff is the quality gate. Sonnet drafts fast; Opus ensures no garbage ships into `.build-loop/skills/experimental/`.
+
+### 5. Track baseline
+
+For each APPROVED artifact, write to `.build-loop/experiments/<name>.jsonl`:
+
+```jsonl
+{"event": "created", "date": "2026-04-19T14:22:00Z", "artifact": "experimental-middleware-typegen", "baseline_metric": "Review-B pass rate on middleware edits", "baseline_value": 0.6, "target_value": 0.9, "sample_size_target": 5}
+```
+
+The experimental skill's description triggers it on matching runs. Each subsequent run that matches the skill's trigger appends to this file:
+
+```jsonl
+{"event": "applied", "date": "...", "run_date": "2026-04-20", "triggered": true, "metric_value": 1.0, "outcome": "phase_5_pass"}
+```
+
+After `sample_size_target` applied entries, Phase 6 Learn computes delta and emits a decision recommendation (promote / remove / extend sample).
+
+### 6. Notify user (concise synthesis)
+
+Emit exactly this format to the Review sub-step F report tail:
+
+```
+## Phase 6 Learn: Self-Improvement Review
+
+Scanned: N runs over last M days
+Detected: X high-confidence patterns, Y filtered out (low signal)
+
+Created experimental artifacts (all in .build-loop/, easy to remove):
+  • <name-1>     — <one-line purpose>     — A/B on: <metric>
+  • <name-2>     — <one-line purpose>     — A/B on: <metric>
+
+Monitor: `cat .build-loop/experiments/<name>.jsonl`
+Remove: `rm -rf .build-loop/skills/experimental/<name>/`
+```
+
+If nothing was created, emit:
+
+```
+## Phase 6 Learn: Self-Improvement Review
+Scanned N runs. No recurring patterns crossed confidence threshold. Nothing created.
+```
+
+### 7. Episodic memory consolidation (Phase 4 wiring)
+
+After steps 1-6 complete, run the memory-consolidation pass. This is the
+hook that wires recurring-pattern detection into the four-memory-types
+framework — when the orchestrator sees the same root cause N times, it
+becomes both an experimental skill (above) AND a procedural-memory
+candidate (below).
+
+Run in this order:
+
+```bash
+# Promote any pending semantic candidates into agent_memory.semantic_facts
+# (no-op if .semantic/_candidates.jsonl is missing)
+python3 scripts/consolidate_memory.py --workdir "$PWD"
+
+# Surface recurring root_causes as procedural candidates
+# (writes .procedural/_candidates.jsonl entries crossing the 3-incident threshold)
+python3 scripts/procedural_governance.py --workdir "$PWD" --mode detect-patterns
+```
+
+Both are safe to re-run; both no-op when nothing qualifies. The first
+fans out the auto-capture batch sweep results into the indexed
+`semantic_facts` table; the second draws from the same
+`state.json.runs[]` that step 1 just scanned, so the procedural
+candidates align with the experimental skills drafted in steps 3-5.
+
+Auto-drafting of procedures (`procedural_governance.py --mode auto-draft`)
+remains gated until 5 hand-authored procedures exist in `.procedural/`
+— the third phase of the procedural learning curve from design ref §14.
+
+If consolidation surfaces a CONFLICT, the orchestrator surfaces the
+count in the Phase 6 summary — never auto-resolves.
+
+## Data Contracts
+
+### `.build-loop/state.json.runs[]` extensions (writer: build-orchestrator during Review sub-step F)
+
+Review sub-step F (Report) must now append a run entry to `state.json.runs[]` before Phase 6 Learn runs. Schema:
+
+```json
+{
+  "date": "ISO-8601 UTC",
+  "goal": "short goal text",
+  "outcome": "pass" | "fail" | "partial",
+  "phases": {
+    "1": { "status": "pass|fail", "duration_s": number, "root_cause": "string?" },
+    "...": "..."
+  },
+  "diagnosticCommands": ["shell commands run during build"],
+  "filesTouched": ["absolute paths edited"],
+  "manualInterventions": [
+    { "phase": number, "note": "short description" }
+  ]
+}
+```
+
+The orchestrator is responsible for capturing `diagnosticCommands` (hook or transcript review), `filesTouched` (git diff after build), and `manualInterventions` (any AskUserQuestion response that overrode default flow).
+
+### `.build-loop/experiments/<name>.jsonl`
+
+Append-only log per experimental artifact. Schema:
+
+```jsonl
+{"event": "created", "date": "ISO", "artifact": "name", "baseline_metric": "...", "baseline_value": N, "target_value": N, "sample_size_target": 8}
+{"event": "applied", "date": "ISO", "run_id": "run_YYYYMMDDTHHMMSSZ_hash8", "triggered": true, "metric_value": N, "outcome": "pass|fail", "co_applied_experimental_artifacts": ["other-name"], "confounded": true}
+{"event": "applied", "date": "ISO", "run_id": "...", "triggered": true, "metric_value": N, "outcome": "pass", "co_applied_experimental_artifacts": [], "confounded": false}
+{"event": "decision", "date": "ISO", "verdict": "promote|remove|extend", ...}
+```
+
+`applied` rows with `confounded: true` are preserved for audit but excluded from the effective sample count. The effective sample is `count(rows where confounded == false)`. A sample only passes the floor when effective count >= 8 (or the user's custom `sample_size_target`, whichever is larger).
+
+## Promotion decisions (after sample complete)
+
+**Default behavior is opt-in.** `autoPromote` defaults to **`false`** in `.build-loop/config.json` — Phase 6 Learn drafts experimental artifacts and tracks A/B evidence but stops at "propose promote" until the user enables the auto mode. This changed after an adversarial review flagged that small-sample auto-promotion can flip on flake and delete good work during temporary regressions.
+
+### Enabling auto-promote
+
+To opt in, create `.build-loop/config.json` with:
+
+```json
+{ "autoPromote": true }
+```
+
+Even with the flag on, auto-promotion requires **`sample_size_target >= 8`** and passing the promotion rules below. Below the floor, Phase 6 Learn always writes a proposal to `.build-loop/proposals/<name>.md` and blocks promotion until the user reviews. The architect agent initializes new experiments with `sample_size_target: 8` by default; only raise it when noise demands more power.
+
+### Promotion rules
+
+When `autoPromote` is true AND `sample_size_target >= 8` AND the experiment's applied entries are all `confounded: false` (see §Confound tracking below):
+
+| Delta vs baseline | Action | Location |
+|---|---|---|
+| Metric improves ≥ target (non-confounded) | **Auto-promote**: `git mv .build-loop/skills/experimental/<name> .build-loop/skills/active/<name>`, update SKILL.md frontmatter `experimental: false` + `promoted_at: <ISO>`, append `{event: "promoted", ...}` to the experiment's jsonl | `.build-loop/skills/active/<name>/` |
+| Metric improves < target (partial win) | **Extend sample** to 2N; re-evaluate after additional runs | unchanged |
+| Metric flat (±10% of baseline) | **Extend sample** to 2N; re-evaluate | unchanged |
+| Metric regresses | **Write proposal** to `.build-loop/proposals/<name>-remove.md` with evidence. Removal requires user confirmation via `AskUserQuestion` in the next Phase 6 Learn run (not immediate `rm -rf`). Avoids single-build regressions deleting useful skills. | experimental (intact) |
+| Sample at 2N still flat | **Write proposal** to `.build-loop/proposals/<name>-inconclusive.md`; same user confirmation gate for removal | experimental (intact) |
+
+If the opt-in flag is off, every row above becomes "write proposal, no file moves/deletes." Proposals accumulate in `.build-loop/proposals/` for manual review.
+
+**Below the sample-size floor** (`applied_count < 8`): Phase 6 Learn records evidence but never acts. The architect may still author new experimental artifacts in this state — the floor only gates promotion/removal decisions.
+
+### Confound tracking
+
+Every Review-B applied-run log line MUST include:
+- `run_id` — a canonical identifier for the build run (the orchestrator generates it at Review-F, e.g. `run_20260419T143022Z_<goalHash8>`)
+- `co_applied_experimental_artifacts[]` — full list of experimental artifact names that also triggered on this run
+
+**Rule**: a run with `co_applied_experimental_artifacts.length > 0` is **confounded** — no single artifact can claim credit for the metric delta. Phase 6 Learn marks all such runs with `confounded: true` and **excludes them from promotion math**. The confound state is sticky: removing an entry from the jsonl does not uncontaminate it.
+
+**Enforcement**: at most one experimental artifact should trigger per build by design. If two fire (because their descriptions both matched the goal), log both measurements with the confound flag and continue the build, but the A/B accounting discounts all co-applied rows. Extending the sample to 2N must count only `confounded: false` rows toward the new target.
+
+**Why we keep both artifacts active rather than disabling one**: silently disabling a co-applied artifact alters future behavior without user awareness. Keeping them both on + marking runs confounded produces honest (if slower) evidence and a surfacable signal that the skills are overlapping and should be merged or one retired.
+
+**A note on precedent**: Karpathy's autoresearch auto-accepts metric wins *within a single optimization run*, not across runs. Cross-run auto-promotion is a new layer. The adversarial review correctly pointed out that small-sample cross-run promotion without isolation is not the same claim of rigor — so the default is opt-in, the floor is 8, and confounded runs don't count.
+
+### Decision log format
+
+Write to `.build-loop/experiments/decisions.jsonl` (append-only) one entry per auto-decision:
+
+```jsonl
+{"event": "auto_promote", "date": "ISO", "name": "middleware-typegen", "baseline": 0.6, "observed": 0.94, "delta": "+56%", "target": 0.9, "sample_size": 5, "artifacts_moved": 2}
+{"event": "auto_remove", "date": "ISO", "name": "aggressive-dedup", "reason": "regression", "baseline": 3.2, "observed": 4.1, "delta": "+28% (worse)", "sample_size": 5}
+{"event": "extend_sample", "date": "ISO", "name": "memo-scope", "reason": "flat", "baseline": 0.72, "observed": 0.75, "delta": "+4%", "new_target_size": 10}
+{"event": "auto_remove", "date": "ISO", "name": "eager-typegen", "reason": "inconclusive", "sample_size": 10, "note": "flat after 2N"}
+```
+
+### User override / reversal
+
+- **Stop an auto-promote**: if the user disagrees with an auto-promotion, `git mv .build-loop/skills/active/<name> .build-loop/skills/experimental/<name>` or `rm -rf .build-loop/skills/active/<name>/`. Phase 6 Learn will not re-promote a name listed in `.build-loop/skills/.demoted` (one name per line — create this file to block re-promotion).
+- **Restore a removed artifact**: logs preserve the original SKILL.md content in `discarded.jsonl` under `{artifact_content: "..."}`. Restoration is manual (grab the content, write back). Only the last 30 discards are preserved; older entries keep metadata only.
+- **Auto-promote is OFF by default**. To enable: `.build-loop/config.json` → `{"autoPromote": true}`. Even when on, promotion requires effective non-confounded sample >= 8 and non-regression. Below the floor or with confounded-only evidence, proposals accumulate in `.build-loop/proposals/` for manual review regardless of the flag.
+
+## Cross-Project Promotion
+
+Auto-promote stays inside the project. Moving an experimental or active artifact into the build-loop plugin repo — where it affects every user on every project — requires explicit invocation:
+
+```
+/build-loop:promote-experiment <name>
+```
+
+The command reads the experiment's track record across this and other projects (if global `~/.build-loop/experiments/` index exists), checks the artifact quality, asks the user for confirmation, and commits to the plugin repo on a feature branch for user review. See `commands/promote-experiment.md` for the full protocol.
+
+## Removal
+
+Users can remove any experimental artifact at any time:
+
+```bash
+rm -rf .build-loop/skills/experimental/<name>/
+rm .build-loop/experiments/<name>.jsonl    # optional, keeps history
+```
+
+The skill stops triggering immediately (no orchestrator restart needed).
+
+## What This Skill Will NOT Do
+
+- Will not modify the build-loop plugin repo
+- Will not promote skills across projects without explicit user approval
+- Will not run if state.json has < 3 runs — insufficient signal
+- Will not retry pattern detection more than once per run
+- Will not write skills for patterns with confidence "low"
+
+## Model Tiering (this skill)
+
+| Step | Agent / Model |
+|---|---|
+| 1. Detect | recurring-pattern-detector (haiku) |
+| 3. Draft | self-improvement-architect (sonnet) |
+| 4. Signoff | build-orchestrator (opus 4.7) |
+| 6. Notify | inline, no model |
+
+Haiku detect is the floor — scanning JSON for counts. Sonnet drafts because authoring SKILL.md needs judgment about trigger phrases and structure. Opus 4.7 signs off because a bad experimental skill silently contaminates future runs; wrong spec is catastrophic.