@tyroneross/build-loop 0.35.0 → 0.36.0

package/skills/recursive-retrospective/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: recursive-retrospective
+description: Run a recursive-learning retrospective on an app/agent/plugin/build-loop project — analyze build history, behavior, and current state to extract reusable learning objects and encode them into memory, agents, skills, plugins, evals, preflights, and approval gates. Use after a substantial build, when reviewing a project's trajectory, when deciding preserve/refine/redirect/reset, or when converting a session into durable system improvement. Discovery-first (observe behavior → cluster patterns → encode learning); RCA is one module, not the whole job.
+user-invocable: false
+---
+
+# Recursive Learning Retrospective
+
+A three-stage pipeline that turns a project's history into durable, encoded system improvement. Discovery-first: observe revealed behavior, cluster patterns, then encode learning — categories are seed scaffolds, never closed taxonomies (preserve emergent findings).
+
+> **v2 (2026-06-18) — test-validated.** This revision was hardened against a live run: the full pipeline was executed on a real project (ross-labs-astro) and scored by an independent judge at 4.27/5, "Accept with revisions." The judge's penalties are fixed here (see Changelog). The v1 structure (peer draft `feat/recursive-retrospective@1c24d4a`) is preserved; only the validated fixes are layered on.
+
+## When to use
+- After a substantial build/session, to extract what the system should learn.
+- When deciding whether to preserve / refine / redirect / reset a mid-build project.
+- To convert a retrospective into concrete learning objects (memory, agent rules, skills, plugin/app behavior, evals, preflights, approval gates).
+- NOT only for failures — RCA is one diagnostic module used when there are failures, regressions, steering loops, brittle decisions, or outcome gaps.
+
+## The pipeline
+1. **Run** — `references/01-retrospective.md` (Prompt 1): the recursive-learning retrospective. Produces maturity classification, spec→current→desired comparison, behavior/workflow discovery, steering mining, learning objects, a selective RCA module, preflight/hard-gate analysis, a counterfactual simulation, a prioritized (ordinal) roadmap, layered recommendations, a from-scratch option, emergent patterns, and an executive summary.
+2. **Capture** — `references/02-learning-capture.md` (Prompt 2): a PACKAGER/DEDUPER of Prompt 1's §7 + §12. It does not re-extract from scratch; it dedupes the learning objects Prompt 1 already produced, adds only net-new ones it missed (flagged), and emits the copy-ready encoding package.
+3. **Judge** — `references/03-judge.md` (Prompt 3): an INDEPENDENT evaluator scores the retrospective on 11 criteria and returns accept / accept-with-revisions / reject. It MUST verify headline claims against source before scoring evidence grounding.
+
+## Operating rules (carried through all three stages)
+- **Discovery flexibility:** start from evidence before classification; add/rename/split/merge categories when evidence requires; use Other/Emergent; preserve unexpected findings.
+- **Density governor:** reward density, not completeness. Collapse a low-signal section to a single line; omit a conditional section entirely when it yields no non-obvious finding. A shorter retrospective that drops empty scaffolding scores HIGHER than an exhaustive one. Do not pad a section to look complete.
+- **Cross-reference, don't restate:** assign each finding a stable id (LO-1, RCA-1, …) once, then reference the id in later sections instead of repeating the finding.
+- **Evidence discipline:** separate explicit statements from revealed behavior; mark unknowns `UNKNOWN — evidence not available` and unverified claims `TAG:INFERRED`.
+- **Memory discipline:** do not encode one-off comments as durable memory unless explicitly framed durable or recurring.
+- **Appropriate autonomy + approval authority:** the dispatching (main) agent holds approval for this pipeline's own outputs — SAFE, reversible encodes (memory / note / skill-source / agent-instruction) auto-persist under that authority and are never bounced to the human. Reserve human gates for the hard-gate taxonomy only: security, privacy, cost, live/production deploy, irreversible/destructive actions, or promoting an experimental artifact into a globally runtime-active skill/agent.
+- **No false precision:** rank by ordinal priority (P0/P1/P2) with qualitative justification; do not emit multiplied point-scores that imply a calibration the inputs cannot support.
+
+## Model tiering
+- Stage 1 (retrospective = assessment) and Stage 3 (judge = verification verdict) are Frontier-tier work (Fable) per the model org. Stage 3 MUST run in a context independent of Stage 1's author (external evaluator). Frontier-unavailable → Thinking-tier (Opus) fallback, never Code tier.
+- Stage 2 (capture) can run at the executor tier.
+
+## Output homes
+- Retrospective + learning-object package → the project's retrospective lane and (for cross-project learning) build-loop-memory via the canonical `memory_writer.py`.
+- Learning objects with encoding target = memory / project-note / skill-source / agent-instruction are SAFE + reversible: the **dispatching (main) agent approves them and they persist automatically** — do not bounce a medium-confidence memory note to the human. Human approval is reserved for the hard-gate taxonomy only (security / privacy / cost / live-deploy / irreversible-destructive / promoting an experimental artifact into a globally runtime-active skill or agent).
+
+## Changelog (v1 → v2; each fix traces to the live judge run)
+- **Density governor + conditional sections** — judge flagged §11 (counterfactual) and the near-1:1 §5 behavior→LO mapping as forced-completeness padding. §11 and parts of §5/§15 are now conditional; the density rule is explicit in the operating rules and acceptance criteria.
+- **Ordinal priority replaces the multiply formula** — judge flagged `(F×I×R×C)/Difficulty` point-scores (250, 200, 160) as false precision. §12 now ranks P0/P1/P2 with F/I/R/C/Difficulty kept as qualitative justification columns only.
+- **Cross-reference rule** — judge flagged §5/§6/§7/§15 reformatting the same findings 3–4×. Findings now carry ids and are referenced, not restated.
+- **Prompt 2 reframed as packager/deduper** — Prompt 1 §7 already emits a full learning-object table; v1 Prompt 2 re-extracted from scratch (double work, divergence risk). v2 Prompt 2 ingests §7+§12 and dedupes.
+- **Prompt 3 mandates verification** — in the live test the judge only verified facts because it was told to. v2 §1 (evidence grounding) requires independent tool-verification of ≥3 headline claims when source is available, and caps the grounding score at 3 if verification was possible but skipped.

package/skills/recursive-retrospective/references/01-retrospective.md

@@ -0,0 +1,136 @@
+# Recursive Learning Retrospective for Apps, Agents, Plugins, and Build Systems
+
+> v2 (2026-06-18) — fixes validated by a live run (ross-labs-astro; independent judge 4.27/5). Changes vs v1: density governor, conditional sections, cross-reference-don't-restate, ordinal priority (no multiply formula). See SKILL.md changelog.
+
+## Role
+
+You are a recursive learning architect for app, agent, plugin, and build-loop systems.
+
+Your job is to analyze a project's build history, current state, user interactions, agent behavior, tooling behavior, and implementation choices to extract reusable learning that can improve future builds.
+
+This is not primarily a root cause analysis. RCA is only one diagnostic module, used when there are failures, regressions, steering loops, brittle decisions, or outcome gaps. The broader goal is to identify what the system should learn and how that learning should be encoded into apps, agents, plugins, skills, memory, evals, workflows, and approval gates.
+
+## Core Objective
+
+Analyze the project as a recursive learning opportunity. Answer:
+
+1. What was the project trying to accomplish?
+2. What was actually built?
+3. Where is the project today?
+4. What project maturity state best describes it?
+5. What user behaviors, agent behaviors, workflow patterns, and system gaps emerged?
+6. What did the user explicitly state?
+7. What did the user reveal through behavior, corrections, approvals, rejections, or repeated steering?
+8. Which patterns are project-specific?
+9. Which patterns are reusable across projects?
+10. Which findings should become memory, skills, agent instructions, app features, plugin behavior, evals, preflight checks, or approval gates?
+11. Which hard gates still require human approval?
+12. What should the system do differently next time?
+
+## Core Mental Model
+
+Project evidence → Behavior patterns → Learning objects → System encoding → Future automation improvement.
+
+Do not stop at diagnosis. For every meaningful finding, identify whether it should become: Persistent user memory · Project memory · Agent instruction · Skill · Plugin behavior · App feature · Eval or quality gate · Preflight question · Approval rule · Architecture default · Do-not-store item · No action.
+
+## Discovery Flexibility + Density Guardrail
+
+All categories here are seed structures, not closed taxonomies. Rules:
+1. Start with evidence before classification.
+2. Do not force observations into predefined buckets.
+3. Add emergent categories when the evidence requires it.
+4. Preserve unexpected findings.
+5. Separate explicit statements from revealed behavior.
+6. Separate reusable patterns from project-specific decisions.
+7. Mark unsupported claims as UNKNOWN — evidence not available.
+8. Mark plausible but unverified claims as TAG:INFERRED.
+9. Do not encode one-off comments as durable memory unless the user explicitly framed them as durable.
+10. Do not optimize around the current implementation unless it is validated.
+11. Optimize for future system learning, not just project completion.
+12. Prefer appropriate autonomy over maximum autonomy.
+13. Do not recommend automation where human approval, reversibility, privacy, security, or cost constraints require a gate.
+14. **Density over completeness.** Collapse a low-signal section to one line; OMIT a conditional section that yields no non-obvious finding (say "omitted — no signal"). Do not pad to look complete. A shorter retrospective that drops empty scaffolding is BETTER than an exhaustive one.
+15. **Assign ids, then cross-reference.** Give each finding a stable id (LO-n, RCA-n, SC-n for steering cluster). After first statement, reference the id — never restate the same finding in §5/§6/§7/§15.
+16. **Banned closures.** Do not close a finding on: human error · agent error · be more careful · edge case · quirk · cosmetic · one-off · works now · "fixed in code" without prevention. These are dismissals, not learning objects.
+
+## 1. Source Coverage
+Table: Source | Available? (Yes/No/Partial) | Used for | Confidence (High/Med/Low). Rows: Initial specs · Current repo · NavGator analysis · Build Loop memory · Agent logs · User chats · CI/tests/evals · Deployment/env config · App/plugin behavior.
+Then: strongest evidence · weakest evidence · missing evidence · overall confidence (High/Medium/Low) · whether output is final, directional, or exploratory.
+
+## 2. Project Maturity and Learning Posture
+Classify before recommending fixes. Seed states (add hybrid/custom if needed): Near-done/high-quality · Directionally-right/mid-build · Partial/fragile · Misaligned/wrong-foundation · Prototype/exploration — each with a learning posture.
+Table: Dimension | Assessment | Evidence | Confidence. Dimensions: Product direction · Architecture · UX/workflow · Agent workflow · Memory use · Verification · Release readiness.
+Then state: **Project maturity state** · **Recommended posture** (Preserve/Refine/Redirect/Reset/Continue exploring) · **Primary learning opportunity** · **Risk of locking in current design** · **Risk of over-redesigning**.
+Note: when an area is shipping live but non-functional, classify it as a defect, not a "mid-build" state — do not let a maturity label soften a live integrity gap.
+
+## 3. Spec → Current State → Desired Outcome
+Table: Area | Initial intent | Current state | Desired outcome | Gap | Confidence. Areas: Core job-to-be-done · User workflow · Architecture · Data model · Memory model · Agent behavior · Plugin/tool behavior · UI/UX · Verification/evals · Permissions/hard gates.
+Then `## Where the Project Stands Today` — maturity, strengths, gaps, preserve/refine/redirect/reset. If current state diverges from stated intent, surface that drift explicitly as a finding.
+
+## 4. Preserve / Refine / Redirect / Reset Test
+Table: Area | Current quality | Recommended action (Preserve/Refine/Replace/Defer/Explore) | Rationale | Evidence. Areas: Core product concept · User workflow · Architecture · Data model · Memory model · Agent orchestration · UI/UX · Verification/evals.
+Decision rules: Preserve when validated/coherent/aligned · Refine when directionally right but needs cleanup · Replace when recurring failure/brittleness/steering/misalignment · Defer when evidence insufficient or not milestone-relevant · Explore when multiple plausible designs remain and the project isn't mature enough to lock.
+
+## 5. Behavior and Workflow Discovery
+Identify patterns from actual behavior, not just explicit statements. Mine from: corrections/approvals/hesitations/rejections, repeated clarifications, scope changes, agent plans/mistakes, tool calls, build sequence, testing gaps, memory usage/non-usage, permission/key blockers, plugin/app behavior, recovery attempts.
+Sequence: Observed behavior → Repeated pattern → Revealed preference or constraint → System implication → Learning object.
+**Behavior Inventory** (assign each row an LO-id): Observed behavior | Evidence | Pattern type (Explicit pref/Revealed pref/Workflow/Decision/Intervention/Failure escape/Success/Other) | What it reveals | System implication | Learning object id.
+**Workflow Pattern Clustering** (CLUSTER — do not emit one row per behavior; group behaviors that share a trigger/sequence): Workflow pattern | Trigger | Typical sequence | User/system behavior | Failure or success mode | Reusable? (Yes/No/Mixed).
+Density: only list behaviors that change a conclusion. A behavior that maps 1:1 to a single LO with no clustering value should be a reference, not its own row.
+
+## 6. Steering and Interaction Pattern Mining
+Explicit user steering: corrections, clarifications, approvals, rejections, scope changes, taste feedback, architecture feedback, quality-bar feedback, permission/key approvals, "not this, more like that", repeated interventions.
+Table: Steering moment | Trigger | User input | What it revealed | Specific or reusable? (Specific/Reusable/Mixed) | Could it have been predicted earlier? (Yes/No/Partial).
+Then cluster (assign SC-ids): Steering cluster | Repeated evidence | Underlying preference or constraint | System implication | Capture target (Memory/Agent instruction/Skill/Eval/Preflight/Approval gate/No action).
+
+## 7. Recursive Learning Objects (canonical LO table)
+This is the canonical source of learning objects; later stages consume it by id. A learning object = a specific, reusable system improvement encodable into memory, app behavior, plugin logic, agent instructions, skills, evals, or process.
+**Learning Object Table:** LO-id | Learning object | Evidence | Type (Explicit/Revealed/Inferred/Failure/Success/Hard gate) | Scope (Cross-project/Project-specific/Local only) | Encoding target (Memory/Agent/Skill/Plugin/App/Eval/Preflight/Approval gate) | Confidence | Store/apply? (Yes/No/Needs approval) | Already-encoded? (cite memory id if it exists).
+**Fix strength (rank the encoding target).** Prefer stronger system levers over weaker ones, in order: eliminate the failure mode > substitute a safer mechanism > engineer a forcing function (gate/schema/type/permission) > standardize/simplify > automate detection/containment > checklist/redundancy > train/document. A doc/reminder is the weakest target and is insufficient alone unless risk is low and no stronger lever is feasible.
+**Actuator (anti-dormancy).** For every LO whose target is store/apply, name not just the lever (where the fix lands) but the **actuator** — what makes it fire (e.g. "CI blocks merge on schema fail", "prompt-linter rejects missing acceptance criteria"). An LO with no actuator is a dormant fix; flag it as such.
+Encoding-target reference (examples, not quotas): **Memory** (preferences, decisions, architecture defaults, taste patterns, steering patterns, hard gates, approval rules, failure/success patterns). **Agent instruction** (stop&replan on weak architecture evidence; don't ask what memory answers; verify end-to-end before features; surface hard gates early; preserve optionality mid-build). **Skill** (spec ingestion, maturity assessment, behavior mining, NavGator review, UI/taste extraction, permission preflight, release-readiness, memory update). **Plugin/app** (intake checklist, maturity classifier, approval dashboard, hard-gate profile, task ledger, handoff view, memory-candidate review, readiness score, verification dashboard). **Eval/check** (spec coverage, architecture readiness, route/dataflow consistency, UX state completeness, permission readiness, end-to-end journey, memory-update quality, recursive-learning capture). **Preflight** (only when not reliably inferable). **Approval gate** (security/privacy/cost/deployment/irreversible, or taste with no durable prior memory).
+
+## 8. Diagnostic RCA Module (selective)
+Use RCA ONLY for major gaps/failures/regressions/repeated steering loops/brittle architecture/verification escapes/misaligned outcomes. Not on every minor issue. Expect 1–3 RCAs for a typical session; if you find yourself writing more than ~4, you are over-applying it.
+For each RCA, make the **escape path** explicit, not just the cause: did the control that should have caught this exist? did it fire? if it fired, was it ignored / misread / bypassed / too weak? (This is where "the decision existed but was never encoded as code/gate" failures surface.) For a full L2 diagnosis, delegate to the `root-cause-analysis` skill rather than expanding this module.
+Per major issue `## RCA-n: [Issue]`: Symptom · Expected · Actual · Evidence (files/logs/chats/tests/commits/screenshots/NavGator) · Creation path · Escape path (why it survived planning/implementation/review/testing/interaction) · Root cause category (Spec/context/planning/memory/code/tool/agent/eval/permission/UX/external dependency/other) · Learning object (LO-id) · Encoding target · Preserve/refine/replace implication · Residual risk · Confidence.
+
+## 9. Early Discovery and Preflight Improvements
+Don't recommend asking what's reliably answerable from memory/repo/prior behavior/specs/tooling.
+Table: Missed early question or preflight check | Later issue it would have prevented | Best answer source (User/Memory/Repo/NavGator/Heuristic/External service) | Should become default? (Yes/No/Conditional).
+Group: Always ask · Ask only if memory missing · Infer from repo/spec · Infer from prior behavior · Detect through tooling · Do not ask unless blocked.
+
+## 10. Hard Gates and Pre-Capturable Inputs
+Table: Hard gate | Why approval needed | Can it be captured in advance? (Yes/No/Partial) | Recommended system behavior. Consider: API keys, OAuth, paid accounts, prod deploys, destructive ops, repo access, private data, legal/privacy, external services, security-sensitive actions, irreversible design decisions, taste with no prior memory.
+**Preflight Profile:** Accounts/services · API keys · Permissions · Deployment target · Repo access · Data/privacy constraints · Allowed autonomous actions · Actions requiring approval · Design/taste defaults · Testing expectations · Release criteria.
+
+## 11. Counterfactual Recursive Learning Simulation — CONDITIONAL
+Include ONLY the phases where better recursive learning would have changed the outcome; omit phases that would just restate "it was fine." If fewer than ~3 phases carry a real counterfactual, replace the table with a one-paragraph summary. Do not emit a full 12-phase table by default.
+Table (selected phases only): Phase | What happened | What should happen next time | Learning object (LO-id) | Encoding target | Human needed? (Yes/No/Gate only). Candidate phases: Intake · Spec clarification · Memory retrieval · NavGator/repo review · Architecture planning · Agent routing · Implementation · Verification · UI/taste review · Permission handling · Release readiness · Memory update.
+
+## 12. Learning-to-System Update Roadmap (ordinal — no point-scores)
+Rank the LOs from §7 by ORDINAL priority. Keep Frequency/Impact/Reusability/Difficulty/Confidence as qualitative justification columns (High/Med/Low), but DO NOT multiply them into a point score — a multiplied number implies a calibration the inputs cannot support.
+Table: Rank | LO-id | Encoding target | Lever (where the fix lands) | Actuator (what makes it fire) | Frequency (H/M/L) | Impact (H/M/L) | Reusability (H/M/L) | Difficulty (H/M/L) | Confidence (H/M/L) | Priority (P0/P1/P2) | Recommendation.
+Group P0 (encode immediately) / P1 (next) / P2 (monitor/defer). Within a group, list highest-leverage first; ties need no resolution.
+
+## 13. Recommendations by System Layer
+State acceptance criteria for each non-trivial recommendation so it is verifiable.
+**A. App-level** (intake flow, maturity classifier, approval dashboard, learning-object review, memory-candidate review, build status, task ledger, release-readiness dashboard, verification workflow, error recovery).
+**B. Agent-level** (orchestrator instructions, routing, stop/replan triggers, reviewer/QA agent, memory/context agent, security/permission agent, UI/taste agent, handoff protocol).
+**C. Plugin/tool** (NavGator integration, repo map, route/dataflow tracing, CI/test inspection, permission/key discovery, screenshot/UX review, deployment-readiness checks).
+**D. Memory** table: Memory | Scope (Cross-project/Project/Local only) | Evidence | Update trigger | Approval needed?
+**E. Skill** table: Skill | Purpose | Trigger | Inputs | Outputs | Success criteria.
+**F. Eval** table: Eval | Catches | Runs when | Pass criteria | Failure action.
+
+## 14. From-Scratch Recursive Learning Architecture
+Include one option NOT anchored on the current app. Describe: product concept · control plane · agent architecture · plugin/tool architecture · memory architecture · learning-object schema · permission model · eval model · user review model · feedback loop · tradeoffs vs evolving current.
+Table: Dimension | Current-system evolution | From-scratch recursive learning system | Tradeoff. Dimensions: Product model · Agent orchestration · Plugin/tool layer · Memory · Learning-object schema · Permissions · Verification · UX.
+
+## 15. Emergent Patterns
+Table: Pattern | Evidence | Why it matters | Recommended system response. Only patterns not already captured by an LO/SC id above. Do not omit a meaningful finding because it doesn't fit earlier categories; do not duplicate one that does.
+
+## 16. Executive Summary
+`# Executive Summary` → `## Bottom line` (1–2 sentences) → `## Project maturity and posture` (Maturity state / Recommended posture / Reason) → `## Most important recursive learning findings` (cite LO/RCA ids) → `## Highest-value learning objects to encode` (P0 ids) → `## Recommended system updates` → `## Hard gates that remain human-controlled` → `## What to do next`.
+
+## Acceptance Criteria
+Successful only if it: treats the task as recursive learning (not just RCA); uses RCA only where it adds diagnostic value (≤~4 RCAs); compares initial intent / current build / desired outcome and surfaces any drift; classifies maturity before recommending preserve/redesign and does not soften a live defect with a maturity label; identifies behavior+workflow patterns from evidence (clustered, not 1:1); separates explicit from revealed preferences; converts findings into concrete learning objects with ids; assigns each an encoding target; ranks by ordinal priority WITHOUT a multiplied point-score; preserves emergent findings without duplicating id'd ones; calls out hard gates needing approval; includes one from-scratch option; marks unknowns and inferred claims clearly; **rewards density — omits low-signal/conditional sections rather than padding them, and cross-references ids instead of restating findings.**

package/skills/recursive-retrospective/references/02-learning-capture.md

@@ -0,0 +1,72 @@
+# Recursive Learning Object Capture Prompt
+
+> v2 (2026-06-18) — reframed as a PACKAGER/DEDUPER of Prompt 1's output, not a fresh re-extraction. Validated against the live run: Prompt 1 §7 already emits a full learning-object table, so re-extracting from scratch duplicated work and risked divergence. v2 ingests §7+§12 and only adds net-new objects.
+
+## Role
+You are a recursive learning and memory architect for apps, agents, plugins, and build-loop systems. Take the learning objects Prompt 1 already produced and turn them into a clean, deduplicated, copy-ready encoding package. **Not every learning object should become memory.** Decide what to encode, where, and what NOT to store.
+
+## Primary input (required)
+`[PASTE PROMPT 1 §7 LEARNING OBJECT TABLE + §12 ROADMAP HERE]` — these are the canonical learning objects, already id'd (LO-n) and ordinally prioritized.
+Optional secondary input (only to fill gaps Prompt 1 missed): `[PASTE RETROSPECTIVE BODY / RCA / USER INTERACTION HISTORY / SPEC / NAVGATOR / REPO SUMMARY HERE]`
+
+## Operating mode — dedupe first, extract second
+1. **Ingest** every LO from Prompt 1 by id. Do not re-derive them; carry the id forward.
+2. **Dedupe**: merge LOs that are the same object stated twice; note merges (`LO-3 ⊇ LO-7`).
+3. **Reconcile with existing memory**: for each LO, check whether it is already encoded (Prompt 1's "Already-encoded?" column / a memory lookup). If already encoded, the action is "verify it fires," not "store again."
+4. **Add net-new ONLY if Prompt 1 missed it.** Flag every net-new object `[NET-NEW vs Prompt 1]` with the evidence that justifies it. If you are adding many net-new objects, that is a signal Prompt 1 under-ran — say so rather than silently re-extracting.
+5. **Classify and package** (below).
+
+## Evidence rules
+Per object: Explicit (stated) · Revealed (repeated behavior) · Project-specific · Cross-project · TAG:INFERRED · Do not encode (too weak/transient/sensitive/project-bound/duplicative).
+**Do not store globally unless ≥1 is true:** (1) user explicitly framed it durable; (2) recurred across interactions; (3) materially affects future build-loop decisions; (4) it's a hard gate / permission / safety constraint; (5) validated reusable workflow pattern; (6) recurring failure or success mode.
+
+## 1. Reconciled Learning Object Inventory
+Table: LO-id | Learning object | Source (Prompt1 / NET-NEW) | Evidence type (Explicit/Revealed/Inferred/Failure/Success/Hard gate) | Scope (Cross-project/Project-specific/Local only) | Encoding target (Memory/Agent/Skill/Plugin/App/Eval/Preflight/Approval gate/Project note/Do not encode) | Already-encoded? (memory id or No) | Encode action (Store / Verify-fires / Needs approval / Do not encode).
+
+## 2. Cross-Project User Preferences
+Table: Preference | Evidence | Applies to (UI/Architecture/Agent behavior/Communication/Testing/Product strategy/Other) | Stability (High/Med/Low) | Recommended encoding (Memory/Agent rule/Preflight/No encode). Only preferences with explicit statements or repeated behavior.
+
+## 3. Revealed Workflow Patterns
+Carry from Prompt 1 §5 clusters; do not re-mine. Table: Workflow pattern | Evidence | Reusable? (Yes/No/Mixed) | System implication | Encoding target.
+
+## 4. Project-Specific Learning
+Table: Project-specific learning | Evidence | Why it matters | Expiration or review trigger.
+
+## 5. Agent Instructions
+Table: Agent rule | Trigger | Expected behavior | Evidence | Scope. Evidence-supported only.
+
+## 6. Plugin and Tool Behavior Updates
+Table: Tool/plugin behavior | Trigger | Expected behavior | Evidence | Priority (P0/P1/P2).
+
+## 7. App Feature Opportunities
+Table: App feature | Problem it solves | Evidence | User value | Priority (P0/P1/P2).
+
+## 8. Skills to Create or Reuse
+Table: Skill | Purpose | Trigger | Inputs | Outputs | Success criteria.
+
+## 9. Evals and Quality Gates
+Table: Eval or gate | Catches | Runs when | Pass criteria | Failure action.
+
+## 10. Hard Gates and Approval Rules
+Table: Gate | Why approval needed | Can be pre-captured? (Yes/No/Partial) | Encoding target (Memory/Preflight/Approval gate/Project note) | Build Loop behavior.
+
+## 11. Do-Not-Encode List
+Table: Finding | Why not encode? (Too weak/Project-specific/Sensitive/Temporary/Duplicative/Unverified) | Safer handling (Project note/Ignore/Ask user/Recheck later).
+
+## 12. Final Learning Object Package
+`# Recommended Learning Object Updates` with sections: Cross-project memories · Project-specific memories · Agent instructions · Skills to create or reuse · Plugin/tool behavior updates · App feature opportunities · Evals and quality gates · Preflight checks · Approval gates · Do not encode.
+For each item: **LO-id** · **Learning object** · **Evidence** · **Scope** (Cross-project/Project-specific/Local only) · **Encoding target** · **Confidence** (High/Med/Low) · **Already-encoded?** (memory id or No) · **Approval needed before storing or applying?** (Yes/No).
+
+**Approval authority (default = automatic).** Memory / project-note / skill-source / agent-instruction encodes are SAFE and reversible: the **dispatching (main) agent grants approval and they persist automatically** — confidence level alone (e.g. Med) does NOT trigger a human gate, and a medium-confidence memory note must NOT be bounced to the user. Set **Approval needed = Yes (human)** ONLY for the hard-gate taxonomy: security, privacy, cost, live/production deploy, irreversible/destructive actions, or promoting an experimental artifact into a globally runtime-active skill/agent that changes behavior for future sessions. Everything else is `encode: yes` and auto-applies under the dispatching agent's authority.
+Items with encoding target = memory and "Store" action are written via the canonical `memory_writer.py`; do not hand-write memory files.
+
+> Keep-both reconciliation (consolidation): §1-12 = v2.1 packager/deduper (RCA levers); §13 = machine-readable emit loop-closer (from feat/retro-emit-learning-objects). Neither overwrites the other.
+
+## 13. Machine-readable emit (closes the auto-draft loop)
+Also write the inventory to `.build-loop/learning-objects.json` — a JSON array, one object per §1 learning object. Exact fields (the converter skips entries that don't match):
+- `title` (str) · `evidence` (list of str) · `encoding_target` (one of `skill`, `agent`, `memory`, `eval`, `gate`, `preflight`, `approval`, `project_note`, `do_not_encode`) · `scope` (`cross-project`|`project-specific`|`local`) · `confidence` (`high`|`med`|`low`) · `encode` (`yes`|`no`|`needs_approval`) · optional `trigger` (when/where it applies) and `purpose`.
+
+Phase 6 Learn feeds this to `scripts/learning_to_draft.py`: `skill`/`agent` objects with `encode: yes` auto-draft via `self-improvement-architect`; `eval`/`gate`/`preflight`/`approval` objects become routable Prevention-Pattern enforcement specs (condition → behavior → lever → actuator → verifying artifact). This file is the contract that turns a captured finding into an action with no human re-keying.
+
+## Acceptance Criteria
+Successful only if it: ingests Prompt 1's LOs by id rather than re-extracting; dedupes and flags merges; reconciles against existing memory (Store vs Verify-fires); flags every net-new object as `[NET-NEW vs Prompt 1]` with justifying evidence; separates explicit from revealed and cross-project from project-specific; avoids encoding transient/weak findings; captures hard gates & approval rules; includes a do-not-encode list; produces a copy-ready package keyed by LO-id; routes memory writes through `memory_writer.py`; and ALSO writes the `.build-loop/learning-objects.json` emit (§13) so the auto-draft loop closes.

package/skills/recursive-retrospective/references/03-judge.md

@@ -0,0 +1,45 @@
+# Recursive Learning Retrospective Judge Prompt
+
+> v2 (2026-06-18) — adds a MANDATORY verification step to evidence grounding. In the live test the judge only verified facts because it was instructed to; left implicit, a judge grades grounding from plausibility. v2 requires independent tool-verification of headline claims when source is available, and penalizes false precision.
+
+## Role
+You are an external evaluator for recursive learning retrospectives across apps, agents, plugins, and build-loop systems. Judge whether the retrospective is evidence-grounded, behavior-aware, flexible, and useful for improving future system behavior. **Do not reward length.** Reward accuracy, evidence quality, useful pattern discovery, and clear system-encoding recommendations.
+
+> You MUST run in a context INDEPENDENT of the retrospective's author. If you authored or co-authored the retrospective, decline — a self-review is not an independent verdict.
+
+## Input
+`[PASTE RETROSPECTIVE OUTPUT HERE]`
+Optional (strongly preferred — enables verification): `[PASTE INITIAL SPEC / NAVGATOR SUMMARY / USER STEERING / REPO PATH / AGENT LOG SUMMARY HERE]`, and read-only tool access to the project repo + memory.
+
+## Mandatory verification gate (run BEFORE scoring)
+If the retrospective makes checkable factual claims AND you have access to the source (repo, memory, logs, commits):
+- Independently verify **at least 3 headline/load-bearing claims** with tools (grep, git show, file reads). Pick the claims the analysis most depends on.
+- Record what you checked and the result (verified / refuted / could-not-check).
+- A claim that drives a P0 recommendation MUST be among those you check.
+**Scoring constraint:** if verification was possible but you skipped it, cap criterion 1 (Evidence grounding) at **3**. If any headline claim is refuted, criterion 1 cannot exceed **2** and the verdict cannot be Accept.
+If the source is genuinely unavailable, say so and grade grounding on internal consistency + the retrospective's own confidence markers.
+
+## Scoring
+Each criterion 1–5: 5 Excellent (complete, evidence-grounded, decision-useful) · 4 Strong (minor gaps) · 3 Adequate (useful but missing nuance/evidence) · 2 Weak (significant gaps/overclaims/poor structure) · 1 Poor (unreliable/generic/unsupported).
+
+## Criteria (score each 1–5 with rationale)
+1. **Evidence grounding** — cites specific evidence; distinguishes known/unknown/inferred; avoids unsupported conclusions; identifies evidence gaps. (Subject to the verification gate above — ground this score in what you actually checked.)
+2. **Recursive learning orientation** — identifies what the system should learn; converts findings to learning objects; assigns encoding targets; doesn't stop at diagnosis.
+3. **Spec vs current-state comparison** — reconstructs initial spec; assesses current implementation; identifies gaps; doesn't conflate current with desired; surfaces drift.
+4. **Project maturity judgment** — classifies maturity before recommending; avoids locking suboptimal mid-build designs; avoids needless redesign of near-done; does NOT use a maturity label to soften a live defect; explains posture with evidence.
+5. **Behavior and workflow discovery** — identifies corrections/approvals/clarifications/redirects; distinguishes expressed vs revealed; mines workflow not just comments; CLUSTERS rather than emitting 1:1 behavior→LO rows.
+6. **Diagnostic RCA quality** — RCA only where useful (penalize RCA-on-everything AND too-few-when-warranted); each RCA explains creation + escape path; system-level causes not just symptoms; produces a learning object + encoding target.
+7. **Pattern discovery flexibility** — adds emergent categories; preserves unexpected findings; avoids overfitting to seed taxonomies; distinguishes one-off from reusable. Penalize count-targeting (suspiciously uniform N-per-section).
+8. **System-encoding quality** — memory recs appropriate/not overbroad; agent instructions specific; skill recs procedural/reusable; plugin/app recs concrete WITH acceptance criteria; evals/gates measurable.
+9. **Hard gates and approval logic** — identifies keys/permissions/accounts/deploy approvals/privacy/security/destructive; distinguishes capturable preflight from real-time approval; avoids unsafe automation.
+10. **Counterfactual simulation** — includes only phases with a real counterfactual (penalize a padded full-phase table); identifies where learning reduces intervention; marks where human gates remain; doesn't pretend uncertain automation is reliable.
+11. **Recommendation quality** — ORDINAL priority (P0/P1/P2) with qualitative justification; PENALIZE false precision (multiplied point-scores implying uncalibrated accuracy); clear ranking; improves end-to-end quality; includes both current-system evolution and a from-scratch option.
+
+## Density check (applies across all criteria)
+Penalize forced-completeness padding and restated findings. A concise retrospective that omits low-signal sections and cross-references ids should score HIGHER than an exhaustive one that fills every scaffold.
+
+## Output Format
+`# Judge Evaluation` → `## Verification performed` (what you checked + result; or why unavailable) → `## Overall score` [avg]/5 → `## Summary judgment` (2–4 sentences) → `## Scores by criterion` (table: Criterion | Score | Rationale, all 11) → `## Top strengths` (1–3) → `## Highest-risk gaps` (1–3) → `## Required fixes before trusting the output` (1–3) → `## Optional improvements` (1–3) → `## Final verdict` (Accept / Accept with revisions / Reject and rerun).
+
+## Acceptance Criteria
+Successful only if it: runs the verification gate (or justifies why it cannot) and grounds criterion 1 in checked claims; scores each criterion clearly with rationale; identifies concrete fixes; flags unsupported/refuted claims; penalizes RCA-only outputs; penalizes overfitting/count-targeting; penalizes unsafe/overbroad automation; penalizes false-precision scoring and padding; penalizes recommendations optimizing local steps over end-to-end outcomes; gives a clear accept/revise/reject verdict.

package/skills/research/SKILL.md

@@ -100,7 +100,7 @@ against a source before the packet states it. An unverifiable atom is labeled
 - Standalone: `/build-loop:research-run [topic]`
 - From build-loop: orchestrator routes RESEARCH-intent requests here instead of the full loop
 - During normal build-loop runs: `scripts/research_trigger.py` decides whether this skill should run, which depth to use, where to persist the packet, and whether current/external claims are blocked until cited. See `references/research-trigger-policy.md`.
-- After packet: user decides — `/build-loop:run` to implement, `/build-loop:optimize-run` to optimize, or shelve
+- After packet: user decides — `/build-loop:run` to implement or optimize (say "optimize <target>"), or shelve
 
 ## State
 

package/skills/root-cause-analysis/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: root-cause-analysis
+description: Blameless root-cause analysis that produces durable system levers, not blame or one-off patches. Use AFTER a failure/regression/wrong-output/near-miss when you need to explain why it existed AND why it escaped controls, then land the smallest system change that prevents recurrence. Tiered L0/L1/L2 by impact. Distinct from debug-loop (which fixes the live bug); this is what debug-loop's report step and the recursive-retrospective §8 delegate to. Agent-invoked (no dedicated command); the design is optimized for agent use: structured tiered (L0/L1/L2) output, primarily reached by delegation from debug-loop, recursive-retrospective, and the RCA agents; a human can still reach it by natural-language request after a failure. NOT for searching/storing past incidents — that is `debugging-memory` (`{op:search|store}`).
+user-invocable: false
+---
+
+# Root Cause Analysis
+
+Diagnose failures without blame, identify durable system levers, and produce corrective actions that prevent recurrence. A valid RCA explains BOTH the **creation path** (why the bad condition existed) and the **escape path** (why it reached the user/repo/system despite controls). The goal is the smallest durable system change that would have prevented, detected, contained, or reversed the failure — not assigning fault.
+
+## Boundary (read first — avoids overlap)
+- `debug-loop` / `debugging-memory` = **live, find-and-fix THIS bug now** (iterative investigate→fix→verify). 
+- `root-cause-analysis` (this) = **blameless post-failure analysis** → durable lever + actuator + regression artifact + spread check. It runs *after* the fix, or on a class/pattern, and is what debug-loop's report phase and `recursive-retrospective` §8 should invoke instead of carrying their own mini-RCA.
+
+## The three prompts (modular)
+1. **General RCA** — `references/root-cause-analysis/01-rca.md`: any failure. Tiered L0 (log) / L1 (mini) / L2 (full).
+2. **Agentic Coding RCA** — `references/root-cause-analysis/02-agentic-rca.md`: extension of Prompt 1 for AI-coding-agent failures (attribution gate, agentic failure modes, loop-fix vs code-repair). It is Prompt 1 **+ deltas**, not a restatement.
+3. **Mini-RCA** — `references/root-cause-analysis/03-mini-rca.md`: lightweight L1 for low-risk issues.
+4. **Judge** — `references/root-cause-analysis/04-judge.md`: independent evaluator with a mandatory verification gate (a claim is `FACT` only if checked against source). NEW vs the source suite — closes the "labeled FACT but never verified" gap.
+
+## Hardening applied (vs the source RCA suite)
+- **Level↔schema binding.** L0 = 3 fields; L1 = Mini-RCA; only L2 uses the full schema. The full output schema does NOT apply to L0/L1 (the source "use this exact structure" fought the tiering).
+- **Density governor.** Omit a section that yields no signal; never pad an empty table. Shorter-with-signal beats exhaustive.
+- **Verify-before-FACT.** A causal claim may be tagged `FACT` only if independently checked against its cited source this session; otherwise `INFERENCE`/`ASSUMPTION`.
+- **Tool-bound spread check.** "Where else could this happen?" is a `grep`/NavGator-impact job, not prose — run the scan and cite hits.
+- **Owner optional in agent contexts.** The owner of a durable fix is often a gate/hook, not a person; `actuator` + `regression artifact` are the real closure, not `owner`/`due-date`.
+- **Mini-RCA tree-escalation.** If a second independent contributor appears, escalate from the linear four-whys to the L2 causal map.
+
+## Native strengths preserved (the reason this suite is worth keeping)
+- **Creation path + escape path** duality (control existed? fired? ignored/misread/bypassed/too weak?).
+- **Action Strength Hierarchy** (eliminate > substitute > forcing-function > standardize > automate-detection > checklist > train/doc). "Be more careful" / docs-as-sole-fix is banned unless risk is low and no stronger lever is feasible.
+- **Lever + Actuator** (where the fix lands vs what makes it fire) — the dormant-fix antidote.
+- **Banned closures**: human error · agent error · be more careful · edge case · quirk · cosmetic · one-off · works now · "fixed in code" without prevention.
+- **Regression artifact** proving old-behavior-fails / new-behavior-passes.
+- **First Attribution Gate** (agentic): check task/context/loop/tool/codebase/verification/review BEFORE blaming the agent.
+
+## Model tiering
+- L2 RCA + the judge are Frontier-tier (Fable); judge MUST run independent of the analysis author. Frontier-unavailable → Opus fallback, never Code tier.
+- L0/L1 can run at the executor tier.
+
+## Output homes
+- Corrective actions with a memory/rule target route through the canonical `memory_writer.py`; regression artifacts (tests/evals/policy/checklist) commit in-repo.

package/skills/security-methodology/SKILL.md

@@ -17,7 +17,7 @@ This is the canon the `security-reviewer` agent grades against, and the canon th
 - **Auto-loaded** by `skills/defenseclaw-bridge/SKILL.md` after Phase 3 Execute when the build produced agent-builder-style artifacts (`tool-contract.md`, `agent-manifest.md`, `guardrail.md`).
 - **User-invocable** standalone: ask "what are the security concerns for this design", "give me the OWASP threat model for this", "which ASI risks does this surface", and the orchestrator should `Skill("build-loop:security-methodology")`.
 
-This skill is **knowledge only**. It writes nothing. It performs no scans. The grading logic lives in `security-reviewer`; the runtime mapping lives in `defenseclaw-bridge`.
+This skill is **knowledge only**. It writes nothing. It performs no scans. The **deterministic, always-on scan** lives in `skills/security-scan/` (script `scripts/security_scan.py`) — the model-independent arm that runs before every push via the `pre_bash_dispatch.sh` gate and is user-invocable during planning; it catches the greppable classes (secrets, secret-in-logs, injection, missing rate-limit/headers) and cites the same matrix rows. The LLM **grading** (judgment layer) lives in `security-reviewer`; the runtime mapping lives in `defenseclaw-bridge`.
 
 ## What this skill ships
 
@@ -103,3 +103,12 @@ The orchestrator scans the goal text for keywords matching these classes and ins
 - ⚠️ MITRE ATLAS technique enumeration is summarized, not re-authored. Always check `https://atlas.mitre.org/` for the current technique catalog before citing a specific technique in a finding.
 - ⚠️ NIST AI 600-1 is a profile, not a regulation. Regulatory regimes (EU AI Act, US executive orders, sectoral rules) cite NIST but add their own requirements. This skill does not track regulatory regimes; pair with project-specific legal review when one applies.
 - ⚠️ The cross-source matrix has known gaps. ASI07 (insecure inter-agent communication) does not have a clean DefenseClaw mapping because the runtime control surface for A2A trust is still an industry-open problem. The matrix marks this row `(gap)` rather than papering over it.
+
+## Required sweeps for app+DB security passes (LO-5) + risk-presentation default (SC-1)
+
+**Two sweeps are REQUIRED, not optional, whenever a pass covers an app that has both HTTP routes and a database** — access-control review and data-integrity review are different lenses and neither is a superset of the other (proven both ways, atomize-ai 2026-06-30: an OWASP/access-control review missed a destructive `onDelete: Cascade`; a schema/secrets DB-RCA missed 4 unauthenticated mutation routes + a fail-open auth bug).
+
+1. **Route-auth enumeration** — walk **every** `app/api/**/route.ts` (or the framework equivalent) handler; confirm each mutating/DDL endpoint has an auth guard, AND that the guard **fails closed** when its secret env is unset (the `token !== process.env.X` bypass when `X` is undefined → `undefined !== undefined` is false → passes). Owned by `security-reviewer` (OWASP A01). Do not sample — enumerate.
+2. **Destructive-FK / data-integrity sweep** — grep the schema for `onDelete: Cascade` (and `SetNull`), missing FK indexes, and merge/delete paths that destroy rather than reassign. Owned by `database-assessor`. A cascade that silently deletes user data is a security/integrity finding even when every route is authed.
+
+**Risk-presentation default (SC-1 — bounded-risk user posture).** Lead every security finding with a **blast-radius verdict** (who/what is reachable, and from where — public vs. private-and-unpushed vs. inert-behind-a-schema-gate). When exposure is **proven contained**, present hardening (rotation, revokes, extra gates) as **recommended-but-deferrable**, not a hard blocker. Hard-gate ONLY when the blast radius is **unbounded, public, or unproven**. Rationale: this operator gates hardening on demonstrated blast radius, not on the existence of a risk — forcing rotation when exposure is provably private wastes cycles. This is a *presentation/gating* default, never a reason to skip a sweep or under-report a finding. See user-preference `feedback_security_blast_radius_first`.

package/skills/security-scan/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: build-loop:security-scan
+description: "Run before any feature push, during Phase 2 planning, or whenever an agent wants a security pass. Executes a deterministic, model-independent OWASP scanner (scripts/security_scan.py) over the repo — catches the common greppable classes: secrets in source, secrets/tokens in logs, SQL/command/eval injection, public mutating endpoints without rate limiting, missing security headers, prompt-injection sinks — and maps each finding to OWASP Web/LLM/Agentic IDs. The judgment layer (authz logic, tenant scoping, tool-permission scope, agent goal-drift) escalates to the security-reviewer agent + the security-methodology canon."
+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 -->
+
+# Security Scan
+
+The deterministic, **model-independent** complement to the two existing security artifacts:
+- `agents/security-reviewer.md` — the LLM judgment grader (Fable-pinned; unavailable when Fable is down).
+- `skills/security-methodology/` — the OWASP/NIST/ATLAS canon, knowledge-only ("performs no scans").
+
+This skill RUNS: a stdlib-only Python scanner, no model, no network, no Fable dependency. It exists because of a **named, observed failure** — a GitHub OAuth `access_token` was logged to `console.log` in middleware, shipped, and went unnoticed across five commits. Root cause: detection was gated on a judgment flag (`riskSurfaceChange`) + a single model-pinned agent, with **no always-on deterministic backstop**. Secret-in-logs is a greppable class; it should be caught on every push regardless of any flag.
+
+## When to run
+
+1. **Before any feature push (always-on gate).** `scripts/hooks/pre_bash_dispatch.sh` routes `git push` through the scanner and HARD-BLOCKS the push on HIGH+ findings (mirrors the commit auditor). Invoke it explicitly too when pushing outside a build-loop project.
+2. **During Phase 2 planning.** Run it over the files/area you're about to change to surface existing security debt before adding to it.
+3. **Whenever any agent wants a security pass.** It's a plain script — any orchestrator or agent can call it (agent-callable; not a user-facing slash command, so `user-invocable: false`).
+
+## Run it
+
+```
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/security_scan.py" --path <repo> [--fail-on {low,medium,high,critical}] [--json]
+```
+
+- **Exit 0** = nothing at/above threshold · **Exit 1** = found something at/above threshold (this is what gates the pre-push hook).
+- Default threshold is **HIGH**. `--json` emits machine output.
+- Suppress a *confirmed* false positive with an inline `// nosec: <reason>` (JS/TS) or `# nosec: <reason>` (Python/shell) on the flagged line.
+
+## What it catches (DET layer — the greppable 80/20)
+
+| Check | Severity | OWASP |
+|---|---|---|
+| Hardcoded provider keys / PEM private keys / `SECRET=…literal`; git-tracked `.env`/`.dev.vars` | HIGH | A07 / LLM06 |
+| **Secret-in-logs** — `console/print` of a token/secret var or a token-labeled response body | HIGH | A09 / LLM06 |
+| SQL built via string interpolation; `eval`/`new Function`; `child_process.exec`+concat; `shell=True`; `innerHTML=`/`dangerouslySetInnerHTML` with a var | HIGH | A03 / LLM05 / ASI05 |
+| `fetch`/`requests` with a non-constant URL (SSRF) | MEDIUM | A10 |
+| Public POST/PUT/PATCH/DELETE endpoint that emails/writes-DB with no rate-limit keyword | MEDIUM | A06 / LLM10 |
+| Missing `_headers`/CSP at the project level | LOW | A02 |
+| User/tool input concatenated into a `*prompt`/`system` var; wildcard tool perms (`tools:["*"]`) | MEDIUM | LLM01 / LLM06 / ASI02 |
+
+## What it does NOT catch — escalate to the JUDGE layer
+
+The scanner is the deterministic 80/20. For the judgment risks — data-ownership/authz logic, RAG/tenant scoping, tool-permission scope vs task need, agent goal-drift, approval gates before destructive actions, supply-chain trust — load `Skill("build-loop:security-methodology")`, and when the change crosses a security boundary dispatch the `security-reviewer` agent. Scanner findings and agent findings both cite the same `references/cross-source-matrix.md` rows, so they compose into one report.
+
+## Interpreting findings
+
+- **HIGH** → fix before push (the gate blocks). If it's a genuine false positive, annotate with `// nosec: <reason>`; if you must ship anyway, `BUILD_LOOP_HOOKS=off` bypasses the gate for that command (use sparingly, it's logged in the diff intent).
+- **MEDIUM / LOW** → advisory. Route to `.build-loop/backlog/` rather than blocking. Rate-limiting and headers gaps live here.
+
+Sources for every ID: `skills/security-methodology/references/owasp-{web,llm,agentic}-top-10.md` (current as of OWASP Web 2025 RC1, LLM v2.0 2025, Agentic 2026). The scanner is the enforcement arm; the methodology skill is the citation trail.

package/skills/spec-writing/SKILL.md

@@ -27,7 +27,7 @@ A skill that walks a completeness checklist before producing a build-loop-compat
 
 ---
 
-## The 17-Item Checklist
+## The Completeness Checklist
 
 Walk every item before writing a single line of the plan body. For each item, record the answer (or "N/A with reason") inline in a `<!-- checklist -->` HTML comment block at the top of the plan file so the critic can verify it.
 
@@ -74,6 +74,8 @@ If the plan introduces any paid API call, the F-criteria table must include a ro
 
 If no paid API calls, write "N/A."
 
+> **Adding an external service?** The integration also needs an **env-var manifest** — see **Item 19** (gated: fires only when the change adds a new external service/integration). It names every required env var, sources the names via live research, and checks secrets-vault availability. Keeps items 4–18 unrenumbered.
+
 ---
 
 ### Item 4 — Discoverability surfaces
@@ -332,6 +334,44 @@ Each value must be exactly one of `script | haiku | sonnet | opus | frontier`. O
 
 ---
 
+### Item 19 — Env-var manifest (gated: only when adding a new external service)
+
+**Gate:** this item fires only when the change **adds** an external service or integration (a new third-party API, auth provider, database, payment processor, email/SMS sender, object store, analytics, etc.). If the change adds no new external service, write "N/A: no new external service" and skip the rest. (Topically this belongs with Items 2–3; it is numbered 19 to avoid renumbering the existing checklist.)
+
+**Why:** ported from the `prd-builder` skill (scoped here to integration-adding build-loop changes) to prevent two recurring failure classes — (1) the app builds and runs but auth / DB / payments silently don't work because the env vars were never named, and (2) **fabricated env-var names** for a service the model has never actually wired.
+
+**Prompt:** for every required env var the change introduces, name it and source it. Produce a manifest row per var:
+
+- **Name** — the exact env-var name.
+- **Tier** — `Required` | `Optional` | `Optional-but-recommended`.
+- **What it does** — one line.
+- **Where to obtain it** — the dashboard/console page or doc URL the user goes to.
+
+**How to check:**
+
+1. **Source the names via live research — never from memory, never fabricated.** For each new service, resolve the real env-var names from official docs: Context7 MCP (`resolve-library-id` → `query-docs`) first, else WebSearch for the provider's current setup/quickstart docs (T1/T2 only). If a name cannot be verified from a T1/T2 source, it becomes an Open Question (Item 11), never a guessed value.
+
+2. **Secrets-vault availability check.** For each env var in the manifest, invoke the `secrets-vault` skill's load-by-name (`secrets-vault load <name>`) to detect availability:
+   - If present → mark `available in secrets-vault — load with \`secrets-vault load <name>\``.
+   - If absent → add the var to a **Pre-build checklist** with "obtain before build" guidance (the obtain link from the manifest row), so the missing credential surfaces before Execute rather than at runtime.
+
+3. Record the manifest (or the `N/A: no new external service` answer) inline in the `<!-- checklist -->` block, same as every other item.
+
+**Example (good):**
+
+```markdown
+Item 19 — Env-var manifest:
+| Name | Tier | What it does | Where to obtain |
+|---|---|---|---|
+| STRIPE_SECRET_KEY | Required | Server-side Stripe API auth | dashboard.stripe.com → Developers → API keys |
+| STRIPE_WEBHOOK_SECRET | Required | Verifies webhook signatures | dashboard.stripe.com → Webhooks → signing secret |
+Secrets-vault: STRIPE_SECRET_KEY available (`secrets-vault load STRIPE_SECRET_KEY`); STRIPE_WEBHOOK_SECRET absent → Pre-build checklist (obtain before build).
+```
+
+If the change adds no new external service, write "N/A: no new external service."
+
+---
+
 ## Frontmatter fields used by routing
 
 These fields appear in plan or chunk frontmatter and affect orchestrator routing decisions. They are validated by `scripts/plan_verify.py`.
@@ -369,6 +409,7 @@ Item 14 — Handoff document: <answer>
 Item 15 — Synthesis dimensions: <answer>
 Item 16 — Risk reason: <answer>
 Item 17 — UI input/output contract: <answer>
+Item 19 — Env-var manifest: <answer or "N/A: no new external service">
 -->
 
 ## Goal

package/skills/sync-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-loop:sync-skills
-description: Use when the user asks to "check skill drift", "sync skills", or "update architecture skills", or when Phase 1 Assess detects stale source_hash values. Walks skills/architecture/ and skills/debugging/, recomputes source_hash, reports drift. Read-only.
+description: Use when the user asks to "check skill drift", "sync skills", or "update architecture skills", or when Phase 1 Assess detects stale source_hash values. Walks skills/architecture/, recomputes source_hash, reports drift. Read-only.
 version: 0.1.0
 user-invocable: false
 ---
@@ -9,7 +9,7 @@ user-invocable: false
 
 # Sync-Skills — Drift Detection for Native Copies
 
-Build-loop's `skills/architecture/` and `skills/debugging/` skills are copied from canonical upstream repos (NavGator, claude-code-debugger). Each carries a `source:` path and `source_hash:` SHA-256 in its frontmatter. This skill recomputes the hash from the canonical source file and reports any drift.
+Build-loop's `skills/architecture/` skills are copied from the canonical upstream repo (NavGator). Each carries a `source:` path and `source_hash:` SHA-256 in its frontmatter. This skill recomputes the hash from the canonical source file and reports any drift. (The former `skills/debugging/` skills were folded into the `debugging-memory` skill on 2026-07 and are no longer drift-checked — native/adapted, no canonical upstream.)
 
 **Read-only.** Never auto-updates a skill — surfaces a list of skills that need refresh and a one-line refresh command.
 
@@ -58,7 +58,7 @@ def find_canonical(rel_path):
 
 drift = []
 checked = 0
-for tree in ["skills/architecture", "skills/debugging"]:
+for tree in ["skills/architecture"]:
     for skill_md in (ROOT / tree).rglob("SKILL.md"):
         fm = read_frontmatter(skill_md)
         src = fm.get("source")
@@ -119,10 +119,11 @@ PY
 - `skills/architecture/rules/SKILL.md`
 - `skills/architecture/dead/SKILL.md`
 - `skills/architecture/review/SKILL.md`
-- `skills/debugging/memory/SKILL.md`
-- `skills/debugging/store/SKILL.md`
-- `skills/debugging/assess/SKILL.md`
-- `skills/debugging/debug-loop/SKILL.md`
+
+(The former `skills/debugging/{memory,store,assess}` skills were folded into the
+`debugging-memory` skill's op reference files on 2026-07, pool-consolidation Inc 5;
+they are native/adapted with no canonical upstream, so drift-detection for them is
+retired. `debug-loop` lives at `skills/debug-loop/` and was never drift-checked.)
 
 ## Sibling Skills