@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/runtime-parity-verification/SKILL.md

@@ -35,6 +35,41 @@ This is stronger than "did it render" (which UI validators check). It is also st
 5. **Encode it as a per-repo smoke** (a script that returns non-zero on divergence). **Validate the smoke is real**: confirm it returns non-zero on a known-broken state, not just zero on green — a check that cannot fail is worthless.
 6. **Gate on it**: run the smoke before any "done" claim. Never substitute compile-green, a passing unit test, or a screenshot.
 
+## Doc ↔ interface parity (documented CLIs, tools & flows)
+
+A second parity gap, same shape: the **documented interface diverges from the
+runtime interface**, and the CLI **silently accepts malformed input**. A green
+unit-test suite over the core logic structurally **cannot** catch either — tests
+exercise the functions, not the CLI surface or the commands the docs tell a user
+to run. A tool/CLI/flow is not "done" until:
+
+1. **Every command in a flow doc runs against the live CLI.** Extract each
+   documented command (fenced shell blocks in the flow's `.md`) and validate its
+   subcommand + every `--flag` against the real interface — `--help` for a
+   Python/argparse CLI (side-effect-free), the parsed-flags list in source for a
+   node CLI. A documented flag/subcommand that doesn't exist is a FAIL. (This is
+   the "doc says `--params`, the CLI never had it" defect.)
+2. **Every CLI boundary rejects malformed input.** Feed each command a typo'd
+   sub-argument / unknown enum value and assert a **nonzero exit with an error** —
+   never a deadlock, never a silent default substitution. (A typo'd argument that
+   auto-creates a junk record and hangs the loop, or a bad value silently swapped
+   for a default, both ship a tool the user can't trust.)
+
+**Validate the check the same way step 5 demands** — mutate the real files (a
+bogus doc flag; a disabled validator) and confirm the check FAILS; a check that
+can't fail is worthless. A subtle trap seen in practice: input-validation cases
+that run against an **absent** state file pass even with validation disabled,
+because the missing-file crash also exits nonzero — the oracle confounds
+"rejected" with "crashed." Run the malformed-input cases against a **real, valid**
+state so a reject is the ONLY cause of a nonzero exit.
+
+**Reusable exemplar:** groundwork `designer/conformance/flow_cli_check.py` — scans
+`references/*.md` + `SKILL.md`, validates every documented `python3 -m …` / `node
+…` command against the live CLI, feeds each a malformed value, and
+`--selftest`-mutation-proves it bites. Wired to fire via `scripts/check.sh` →
+`npm test` + a committed `.githooks/pre-push` (a check that only runs when recalled
+is dormant — put it in the gate).
+
 ## Anti-patterns (each one shipped a real bug)
 
 - "Build is green, committed — done." → compile ≠ runtime; never exercised the flow.
@@ -45,7 +80,7 @@ This is stronger than "did it render" (which UI validators check). It is also st
 ## Build-loop integration
 
 - **Phase 4 Review sub-step B / Phase 5 Iterate**: when `uiTarget != null` OR the diff touches a user-visible flow, a runtime parity check is **required**. The existing drivers do the probing — web: `ui-validator`; macOS: `native-ax-driver` / IBR `scan_macos`; iOS: `idb`. THIS skill adds the missing step: **cross-check the probe against source-of-truth**, and keep a validated per-repo smoke.
-- **Phase 4 sub-step G (`verification-before-completion`)**: for app/UI changes, "confirm output" includes the runtime parity smoke, not only test/build/lint.
+- **Phase 4 sub-step G (`verification-before-completion`)**: for app/UI changes, "confirm output" includes the runtime parity smoke, not only test/build/lint. For a **CLI / tool / documented-flow** change, it also includes the doc↔interface parity smoke (every documented command runs; every boundary rejects malformed input), likewise validated by mutation.
 - The `verify` skill ("run the app and observe behavior") is the manual counterpart; this skill is the automatable, source-of-truth-anchored form.
 
 Origin lesson: build-loop-memory `lessons/2026-06-08-pattern-runtime-ui-source-of-truth-parity-verification.md` (easy-terminal launch/no-pane bug — UI projection diverged from daemon, missed across a whole UI pass because verification was compile-green + screenshot-only).

package/skills/security-methodology/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-loop:security-methodology
-description: "Use when a build crosses a security boundary (auth, authz, secrets handling, network exposure, persistence of sensitive data) or when Phase 1 Assess flags `triggers.riskSurfaceChange: true`. Provides the threat-modeling and scoped-permission methodology for build-loop's security-reviewer agent."
+description: "Threat-modeling and scoped-permission methodology for judgment-level security review, consumed by the security-reviewer agent. Use when the user asks to \"threat model this\" or \"review this for security issues\" beyond an automated scan, or a build touches auth/authz/secrets/network exposure. Not for the deterministic automated scan (use `security-scan`)."
 version: 0.1.0
 user-invocable: false
 ---
@@ -56,24 +56,21 @@ If you're grading a diff (as `security-reviewer` does):
 - Model theft (LLM10) at the deployment level. Agent-builder-style apps don't host weights.
 - CBRN, environmental, IP, obscene, and violent content from NIST 600-1 — those are policy/legal concerns, not engineering. They're referenced for completeness in `nist-600-1-mapping.md` but not deeply mapped.
 - The full MITRE ATLAS taxonomy. ATLAS has 16 tactics and 84 techniques as of v5.1.0 (Nov 2025) plus 14 agentic additions (Feb 2026). Re-authoring it would duplicate the project; the starter file points at the source.
-- Adversarial test corpora. Red-team corpora are out of build-loop's scope per `~/dev/research/topics/product-dev/product-dev.agentic-systems-original-synthesis.md` recommendation #4.
+- Adversarial test corpora. Red-team corpora are out of build-loop's scope per "Agentic Systems — Original Synthesis" (private research note — substance summarized here) recommendation #4.
 
 ## Where these references come from
 
 This skill packages and cross-maps four authoritative sources. Each reference file inside `references/` cites its own source. The canonical research file with full citation, retrieval dates, source tier, and the original cross-source matrix lives at:
 
-- `~/dev/research/topics/product-dev/product-dev.agentic-systems-security-references.md` — the verified canon. T1 sources throughout (OWASP project pages, NIST publication, MITRE ATLAS, Cisco DefenseClaw repo).
+- "Agentic Systems — Security References" (private research note — substance summarized here) — the verified canon. T1 sources throughout (OWASP project pages, NIST publication, MITRE ATLAS, Cisco DefenseClaw repo).
 
 The companion **gap analysis** that motivated shipping these artifacts inside build-loop:
 
-- `~/dev/research/topics/product-dev/product-dev.agentic-systems-original-synthesis.md` — recommendations table (security-related: #4 red-team playbook, #10 cost-budget enforcement, plus the new "govern/inspect/prove" recommendation).
+- "Agentic Systems — Original Synthesis" (private research note — substance summarized here) — recommendations table (security-related: #4 red-team playbook, #10 cost-budget enforcement, plus the new "govern/inspect/prove" recommendation).
 
-The agent-builder methodology that this skill cross-references when classifying agentic risks (autonomy ladder A0–A4, permission tiers T0–T5, role decomposition):
+The agent-builder methodology that this skill cross-references when classifying agentic risks (autonomy ladder A0–A4, permission tiers T0–T5, role decomposition) — "Agentic Product Development — Synthesis" (agent-builder plugin methodology, file 13; private research note — substance summarized here) and its companion "15 template files" set (`tool-contract.md`, `agent-manifest.md`, `guardrail.md`, `system-boundary.md`, `flow-topology.md`, `role-card.md` are the security-relevant subset; private, not shipped in this repo).
 
-- `~/dev/git-folder/agent-builder/plugin/references/methodology/13-agentic-product-dev-synthesis.md` — single canonical synthesis, A0–A4 autonomy ladder.
-- `~/dev/git-folder/agent-builder/plugin/references/templates/agentic-handoff/` — 15 template files; the security-relevant subset is `tool-contract.md`, `agent-manifest.md`, `guardrail.md`, `system-boundary.md`, `flow-topology.md`, `role-card.md`.
-
-If the agent-builder plugin is not installed locally, the research-folder pointer above is sufficient — file 13's substance is reproduced in the addendum-v2 research file (`~/dev/research/topics/product-dev/product-dev.agentic-systems-template-pack-addendum-v2.md`).
+**Working fallback (always available, no external plugin required):** `references/agentic-handoff-templates.md` — vendored into this repo so the skill has a real fallback on a fresh install. It reproduces the permission-tier table, the A0–A4 ladder, the default role-decomposition table, and the machine-readable YAML templates (role-card, tool-contract, guardrail, system-boundary, flow-topology, agent-output-contract) directly, with provenance notes. If the agent-builder plugin is installed locally, prefer its live templates; otherwise this file is the canon.
 
 ## Relationship to other build-loop skills
 
@@ -94,6 +91,9 @@ Phase 1 Assess sets the flag when any of these are introduced or modified:
 - An auth, authz, identity, or permission boundary change (LLM07, ASI03, A01).
 - An external API call introduced by the build (LLM05, ASI04, A06, A10).
 - Handling of new user data classes — PII, financial, health, credentials, regulated records (LLM06, NIST Data Privacy).
+- A lifecycle-hook registration or editor/agent auto-load surface — `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`, `hooks/*.json`, githooks, launchd/cron plists (ASI02, A06 supply chain).
+- An installer or provisioner path — anything that downloads, chmods, or executes a binary, or builds source, reachable from a hook or startup path (A06, ATLAS supply chain).
+- Code that interpolates stored or descriptor-supplied strings into shell commands or into model context — prompt-to-shell and prompt-to-context render paths (LLM01, ASI05, A03).
 
 The orchestrator scans the goal text for keywords matching these classes and inspects the planned file set. Either signal flips the trigger; the trigger is sticky for the rest of the build.
 
@@ -106,9 +106,22 @@ The orchestrator scans the goal text for keywords matching these classes and ins
 
 ## 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).
+**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 in a private-app stress test on 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.
 
+## Repo-trust audit sweep (from the Lattice audit of agent-rally-point, issue #52)
+
+An independent external audit found 3 Critical findings in agent-rally-point that this canon's OWASP/ATLAS grading never surfaced. The gap was the lens, not the frameworks. When a build touches any of the three new trigger signals above — hook registrations, installers, or string-to-shell/context render paths — the review MUST also run these four checks:
+
+1. **Trust-on-clone.** Ask what executes or gains authority when someone merely opens or trusts the repo: auto-loaded hooks, provisioners reachable from startup, tracked binaries, symlinks, SVG payloads, git bundles. Grade the repo as an attack vector, not just the diff.
+2. **Doc-claims vs implementation.** Extract security and behavior claims from docs ("does not install hooks", "proves the plan is safe", "the gate blocks X") and grade each against code. Fact-checking rendered data does not cover this; claims need their own pass.
+3. **False security boundaries.** For every gate, approval flow, or "blocked" message: name what it actually interposes on. A control that observes an event stream but cannot stop the child process is telemetry, not a boundary.
+4. **Render-path tracing.** Follow stored, descriptor-supplied, or peer-authored strings to every point where they become shell text or model context. Each such path needs quoting/allowlisting plus an adversarial test that proves a hostile string is rejected or neutralized.
+
+Report structure for these findings, borrowed from the exemplar (`gh issue view 52 -R tyroneross/agent-rally-point`): stable per-project finding IDs, severity, file:line citation for every claim, a per-finding required fix, plus two honesty sections — "positive containment observations" (explicitly scoped as not offsetting findings) and "unreviewed surface" (what the review skipped and why). The unreviewed-surface section is mandatory; a review that doesn't state its blind spots overstates its coverage.
+
+Assume at least two untrusted actors when grading multi-agent or shared-repo tooling: a second contributor to the repo, and a same-UID local process. "Single operator on one Mac" is a deployment fact, not a threat model — write the actual trust model down.
+
 **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-methodology/references/agentic-handoff-templates.md

@@ -0,0 +1,220 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Agentic system handoff — permission tiers, autonomy ladder, role decomposition
+
+Vendored substance from the agent-builder methodology (private research note — substance summarized here). This file exists so `skills/security-methodology/SKILL.md` has a working fallback on a fresh install where the `agent-builder` plugin is not present: rather than pointing at a second maintainer-only path, the load-bearing tables and templates are reproduced directly below.
+
+## Permission tiers (T0–T5)
+
+Used when classifying what a tool or agent action is allowed to do, and what approval it requires by default.
+
+| Tier | Capability | Examples | Default approval |
+|---|---|---|---|
+| T0 | No tool access | Draft text only | No approval |
+| T1 | Read-only local context | Read project docs, inspect state | No approval if data is in scope |
+| T2 | Read external systems | Search docs, query CRM, read GitHub issues | Approval depends on data sensitivity |
+| T3 | Write reversible changes | Create draft, stage file, update non-public record | Usually preview or undo required |
+| T4 | External communication | Send email, post Slack, create ticket, comment on PR | Human approval required |
+| T5 | Irreversible or high-impact action | Delete data, deploy production, spend money, change permissions | Strong human approval required |
+
+## Autonomy ladder (A0–A4)
+
+The canonical 5-level ladder (v2; supersedes an earlier 6-level A0–A5 variant that split "draft only" into two levels).
+
+| Level | Name | Agent may do | Approval required for |
+|---|---|---|---|
+| A0 | Draft only | Summarize, classify, draft, critique, recommend. | Any decision, write action, external call, or implementation. |
+| A1 | Reversible decisions | Choose low-risk defaults, mark assumptions, proceed on reversible choices. | Low-reversibility decisions, sensitive data, external services, paid resources. |
+| A2 | Bounded execution | Implement approved P0 scope in a sandbox, run tests, update local files, report. | Deployment, paid services, destructive actions, secrets, external communications. |
+| A3 | Controlled production action | Execute approved production tasks under guardrails and audit. | Migrations, deletion, permission changes, user-impacting changes, policy changes. |
+| A4 | Autonomous operation | Monitor and optimize within explicit policy, budgets, and rollback limits. | Material scope, policy, data, architecture, or cost changes. |
+
+Rationale: excessive agency — an LLM-based system performing damaging actions because it has too much functionality, permission, or autonomy — is one of the clearest agentic-system risk classes (OWASP LLM08, `genai.owasp.org/llmrisk2023-24/llm08-excessive-agency/`).
+
+### Default autonomy by phase
+
+| Phase | Default autonomy | Rationale |
+|---|---|---|
+| Sparse intake | A1 | The agent may infer obvious defaults but must log assumptions. |
+| Product spec generation | A1 | Product intent and scope require human validation. |
+| UX and requirements draft | A1-A2 | Drafts allowed; P0 scope reviewed. |
+| Architecture decisions | A0-A1 | Lower-reversibility; ADRs required. |
+| Data and permissions | A0-A1 | Sensitive data and retention need explicit constraints. |
+| Coding | A2 | Safe after approved handoff and sandbox boundaries. |
+| Testing and evaluation | A2 | Run tests, lint, report evidence. |
+| Deployment | A0-A2 | Depends on environment, user impact, rollback, approvals. |
+| Production operation | A0-A3 | Requires governance, monitoring, incident response, override. |
+
+### Ask-before policy
+
+An agent must ask before:
+
+- Storing personal, financial, medical, legal, confidential, regulated, or credential-like data.
+- Selecting a paid external service or creating recurring operational cost.
+- Introducing distributed services, microservices, irreversible migrations, or complex infrastructure.
+- Removing, weakening, or redefining a P0 requirement.
+- Deploying to a user-facing or production-like environment.
+- Executing delete, overwrite, migration, permission, or credential actions.
+- Taking actions that affect money, health, legal status, security posture, customer communications, or contractual commitments.
+
+## Default agent role decomposition
+
+| Agent | Primary job | Key inputs | Key outputs | Default autonomy |
+|---|---|---|---|---|
+| Intake / Triage Agent | Convert sparse human input into normalized product primitives. | Intake answers, prior project context, examples. | Product primitives, confidence map, open questions. | A1 |
+| Product Strategy Agent | Define user outcomes, North Star, scope, non-goals, and success metrics. | Product primitives, user context, constraints. | Product brief, outcome map, scope recommendation. | A1 |
+| User / JTBD Agent | Infer jobs, pains, workflow triggers, success moments, and user constraints. | Intake, interviews, examples, archetypes. | Persona and JTBD brief, pain/opportunity map. | A1 |
+| Requirements Agent | Convert goals into epics, stories, requirements, acceptance criteria, and test hooks. | Product brief, user context, UX constraints. | Requirements doc, story map, acceptance criteria. | A1-A2 |
+| UX Blueprint Agent | Define flows, screens, navigation, content intent, empty states, and error states. | Personas, requirements, design constraints. | UX blueprint, screen inventory, flow specs. | A1-A2 |
+| Architecture Agent | Recommend technical architecture and major architectural decision records. | Requirements, quality attributes, constraints, decision criteria. | Architecture recommendation, ADRs, implementation plan. | A0-A1 |
+| Data / Integration Agent | Define entities, permissions, integrations, lifecycle, and data-handling assumptions. | Requirements, target systems, security constraints. | Data semantics, integration specs, permission map. | A0-A1 |
+| Security / Compliance Agent | Identify sensitive data, misuse risks, guardrails, approval boundaries, and policy constraints. | Data spec, architecture, domain context. | Risk register, security checklist, ask-before rules. | A0 |
+| Spec Review Agent | Check ambiguity, traceability, scope, assumptions, risk, and handoff readiness. | Full draft pack. | Spec lint result, traceability gaps, revision requests. | A1 |
+| Coding Agent | Build implementation, tests, docs, setup, and local run instructions. | Approved handoff pack, repository, build plan. | Working code, tests, README, completion report. | A2 |
+| QA / Evaluation Agent | Verify behavior against requirements, tests, and quality bars. | Code, requirements, test plan, traces. | Test results, defect log, traceability report. | A2 |
+| Release / Completion Agent | Package output, known limitations, next iteration, and learning updates. | QA results, implementation notes, unresolved risks. | Release notes, known limitations, next-step plan. | A1-A2 |
+
+## Machine-readable templates
+
+### System boundary
+
+```yaml
+system_boundary:
+  agent_system_name:
+  primary_mission:
+  users_served:
+  in_scope_tasks:
+  out_of_scope_tasks:
+  external_tools:
+  external_agents:
+  human_roles:
+  data_sources:
+  systems_of_record:
+  actions_that_change_the_world:
+```
+
+### Flow topology
+
+```yaml
+flow_topology:
+  pattern: "sequential | parallel | router | orchestrator_worker | evaluator_optimizer | interactive | hybrid"
+  why_this_pattern:
+  state_owner:
+  stop_condition:
+  retry_policy:
+  human_checkpoint_policy:
+  parallel_branches:
+    - branch_name:
+      input:
+      output:
+      merge_rule:
+  feedback_loops:
+    - evaluator:
+      criterion:
+      max_iterations:
+      escalation:
+```
+
+### Role-card (agent-manifest equivalent)
+
+```yaml
+agent_id: "AGENT-001"
+name: "<Agent name>"
+mission: "<One-sentence mission>"
+primary_outputs:
+  - "<artifact>"
+input_artifacts:
+  - "<file or object>"
+allowed_decisions:
+  - "<decision this agent may make>"
+must_escalate:
+  - "<decision requiring human or orchestrator approval>"
+forbidden_actions:
+  - "<action>"
+tools_allowed:
+  - tool_name: "<tool>"
+    permission: "read | write | execute | approve-required"
+quality_bar:
+  - "<acceptance criterion for this agent's work>"
+completion_signal: "<what marks this agent's work complete>"
+```
+
+### Tool contract
+
+```yaml
+tool_contract:
+  tool_name:
+  purpose:
+  owner:
+  type: "function | MCP | hosted | shell | browser | external_api | agent"
+  input_schema:
+  output_schema:
+  allowed_actions:
+  forbidden_actions:
+  permission_tier:
+  auth_scope:
+  data_access_scope:
+  rate_limits:
+  timeout:
+  side_effects:
+  requires_human_approval:
+  approval_preview_fields:
+  rollback_strategy:
+  audit_log_fields:
+  failure_modes:
+  test_cases:
+```
+
+MCP tools expose external systems with unique names, input schemas, optional output schemas, and annotations; the MCP spec emphasizes input validation, access controls, rate limits, output sanitization, user confirmation for sensitive operations, timeouts, and usage logging (`modelcontextprotocol.io/specification/2025-11-25/server/tools`).
+
+### Guardrail
+
+```yaml
+guardrail_id: "GR-001"
+name: "Sensitive Data Storage Guardrail"
+applies_to:
+  - "Data Agent"
+  - "Coding Agent"
+trigger:
+  - "Artifact mentions PII, financial data, health data, legal data, credentials, or regulated records."
+check:
+  - "Is storage necessary for P0 workflow?"
+  - "Is retention defined?"
+  - "Are permissions defined?"
+action:
+  - "If missing, block build handoff and create OQ."
+severity: "high"
+escalation: "human approval required"
+```
+
+### Agent output contract
+
+```yaml
+agent_output:
+  agent_id: "<agent>"
+  task_id: "<task>"
+  status: "complete | partial | blocked | failed"
+  artifacts_created:
+    - "<artifact_id>@<version>"
+  decisions_made:
+    - "DEC-001"
+  assumptions_added:
+    - "ASSUMP-001"
+  risks_added:
+    - "RISK-001"
+  tests_or_checks_run:
+    - "CHECK-001"
+  blockers:
+    - "<blocker or none>"
+  confidence: "low | medium | high"
+  next_recommended_agent: "<agent or none>"
+```
+
+## Provenance
+
+This file reproduces the load-bearing tables and YAML templates from two private research notes (not shipped in this repo, not required to use this file):
+
+- "Agentic Product Development — Synthesis" (agent-builder plugin methodology, file 13) — role-card pattern, canonical A0–A4 autonomy ladder, permission-tier framing.
+- "Addendum v2: LLM-Readable Templates for Building Effective AI Agentic Systems" (private research note) — the T0–T5 permission-tier table, the A0–A4 revision, default-agent-role-decomposition table, and the machine-readable YAML templates above, transcribed verbatim from that note's §"Tool permissions and autonomy", §"Agent autonomy model — A0–A4", §"Default agent role decomposition", and §"Machine-readable templates to merge into ProductPilot".
+
+Both notes cite Anthropic, OpenAI Agents SDK, LangGraph, MCP spec, and OWASP LLM08 as their T1/T2 sources for the underlying claims (excessive agency, context engineering, tool-as-contract, durable state); this file does not re-verify those citations independently — treat table content here as a working reference, not a substitute for reading the primary sources when precision on a specific claim matters.

package/skills/security-methodology/references/cross-source-matrix.md

@@ -6,7 +6,7 @@ Single decision table mapping each risk class to its OWASP LLM ID, OWASP Agentic
 
 **Use.** This is the load-bearing artifact of the security-methodology skill. The `security-reviewer` agent cites a row from this matrix in every finding. The `defenseclaw-bridge` skill maps from this matrix to DefenseClaw config rows.
 
-**Source.** Adapted from `~/dev/research/topics/product-dev/product-dev.agentic-systems-security-references.md` §"Cross-source map: where each risk lives". The research file is the canonical citation trail; this file is the build-loop-internal copy.
+**Source.** Adapted from "Agentic Systems — Security References" (private research note — substance summarized here), §"Cross-source map: where each risk lives". This file is the build-loop-internal copy; it does not depend on the research note being present.
 
 ## Reading conventions
 

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

@@ -154,4 +154,4 @@ Three of the top four risks — **ASI02** (Tool Misuse), **ASI03** (Privilege Ab
 ## Verification status
 
 - ✅ ASI01–ASI10 verified (T1, OWASP GenAI Security Project release page; secondary confirmation via Aikido enumeration of the 2026 list).
-- The agent system that drove this skill's creation flipped ASI02–ASI06 from `[INFERRED]` to verified during this build — see `~/dev/research/topics/product-dev/product-dev.agentic-systems-security-references.md` §Verification status for the trail.
+- The agent system that drove this skill's creation flipped ASI02–ASI06 from `[INFERRED]` to verified during this build — see "Agentic Systems — Security References" (private research note — substance summarized here), §Verification status, for the trail.

package/skills/security-scan/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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
+description: "Run a deterministic, model-independent OWASP scan for secrets, injection, auth gaps, and unsafe AI tool calls, mapped to OWASP Web/LLM/Agentic IDs. Use before any push or deployment, or whenever an automated security pass is wanted. Not for business-rule/judgment-level review (use `security-methodology` + the security-reviewer agent)."
+version: 0.2.0
 user-invocable: false
 ---
 
@@ -18,38 +18,78 @@ This skill RUNS: a stdlib-only Python scanner, no model, no network, no Fable de
 ## 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`).
+2. **Before any DEPLOYMENT (always-on gate).** `git push` is only one way code reaches users. The same hook classifies the command with `deployment_policy.is_deploy_like()` and full-scans before `vercel deploy`, `wrangler deploy`, `wrangler pages deploy`, `flyctl deploy`, `railway up`, `render deploy`, `supabase functions deploy`, `eas submit`, `fastlane`, `kubectl apply`, `helm`, `terraform apply`, `pulumi up`, `gcloud`/`aws`/`sam`/`cdk` deploys, `gh workflow run`, `gh release create`, and `npm publish`. A deploy ships the whole tree, so this path never uses `--diff` — every file gets every check.
+3. **During Phase 2 planning.** Run it over the files/area you're about to change to surface existing security debt before adding to it.
+4. **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`).
+
+## Coverage model — deep on the change, sweep everywhere else
+
+`--diff` alone scans only what changed, which leaves the rest of the app unchecked on every ship. `--spot-check` closes that without making the gate unusable:
+
+- **Changed files → every check, fully enforced.** A HIGH here blocks.
+- **Unchanged files → the high-confidence subset** (secrets, secret-in-logs, injection, object-level authz, auth guards, client-exposed keys, token hygiene, CORS), tagged `scope: "spot"` and reported as **advisory**. Only a CRITICAL among them blocks.
+
+The asymmetry is deliberate. Blocking a ship on a stranger's years-old MEDIUM is how a gate becomes something people route around; a CRITICAL in any file is a reason not to ship regardless of who wrote it. The absence-of-control checks (rate limiting, headers, prompt hygiene, mass assignment) are excluded from the sweep — they fire on almost every older file and would bury the signal.
+
+The pre-push hook passes `--spot-check` automatically. The report header names the sweep and the summary separates advisory from blocking counts, so widened scope is visible rather than implied.
 
 ## Run it
 
 ```
-python3 "${CLAUDE_PLUGIN_ROOT}/scripts/security_scan.py" --path <repo> [--fail-on {low,medium,high,critical}] [--json]
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/security_scan.py" --path <repo> [--fail-on {low,medium,high,critical}] [--json] [--diff <ref>] [--spot-check] [--exclude <glob>] [--tracked-only]
 ```
 
 - **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.
+- **`--diff <ref>`** (opt-in) scopes the scan to files changed in `<ref>..HEAD` — scan what's being pushed, not the whole tree, so pre-existing unrelated debt doesn't block an unrelated push. Fail-safe: a bad ref / non-git path falls back to a full scan (never scans less than intended); an empty range scans nothing (exit 0). Delta discovery uses `git diff --name-only -z --relative` so non-ASCII/quoted filenames and subdirectory `--path` roots are handled correctly; a belt-and-braces guard also full-scans if the delta named changed files but the walk matched none. The pre-push hook derives `<ref>` from the upstream tracking branch (`@{u}`), and applies it **only to a plain current-branch → tracking push**: any refspec (`origin main:release`), non-tracking remote (`git push backup main`), or whole-repo flag (`--mirror`/`--all`/`--tags`) omits `--diff` and full-scans (fail-safe: never scan less than intended). No upstream → whole-repo scan.
+  - The named set is the UNION of `git diff --name-only <ref>..HEAD` and `git log --name-only <ref>..HEAD`. The second is load-bearing: `git diff` compares the two endpoint trees, so a file added in one commit and removed in a later one inside the same range is named by neither — yet `git push` ships its blob. Before 2026-09-05 such a file surfaced only as an advisory SPOT finding, so `commit a secret, then git rm --cached it` cleared the gate on the very push carrying it.
+  - **Scope limitation (working-tree vs pushed blob):** `--diff` names files, then reads each one's **current working-tree content**, not the exact pushed blobs. So a secret whose file still exists is caught, but one dirty-edited out of the working tree before the push still escapes. Shared with the pre-delta whole-tree gate. A future follow-up could read blobs directly (per-commit `git show`); tracked as backlog, not yet implemented.
+- **`--exclude <glob>`** (opt-in, repeatable) skips any file whose repo-relative path matches the fnmatch glob, in both full and `--diff` mode. The hook reads these from `.build-loop/config.json` → `securityScan.excludeGlobs` (best-effort; absent = no-op). The report always names the active globs and the count of files they removed, and a bare `*`/`**` (or a glob removing >50% of candidates) emits a stderr warning — an over-broad glob cannot silently bypass the whole scan unnoticed.
+- **`--tracked-only`** (opt-in) drops UNTRACKED files from the candidate set. The **push** gate passes it, because a push ships committed content only; the **deploy** gate does not, because `vercel deploy` and friends upload the working tree, where an untracked file genuinely ships. Named failure (2026-09-05): 54 of the 57 HIGH findings that hard-blocked a push lived in untracked `.designdoc/*.html` mockups that could never reach the remote.
+- With neither `--diff` nor `--exclude`, behavior is unchanged (whole-tree, git-tracked files).
+- Suppress a *confirmed* false positive with an inline `// nosec: <reason>` (JS/TS), `# nosec: <reason>` (Python/shell), or bandit's `# nosec B608` on the flagged line. A bare `# nosec` (no colon, no ID) does not suppress.
+  - **Suppression is LINE-scoped, not check-scoped.** `suppressed()` receives only the line, never a check id, so either spelling silences *every* check on that line — a bandit ID is a marker, not a scope. `AWS = "AKIA…"  # nosec B608` silences the hardcoded-secret finding even though B608 is bandit's SQL-injection test. `# nosec:` with nothing after the colon also suppresses, so the reason is a convention the pattern does not enforce. Accepted IDs are `B1xx`–`B7xx`, bandit's own range.
 
 ## What it catches (DET layer — the greppable 80/20)
 
+Checks A–G live in `scripts/security_scan.py`; the API and AI-boundary checks H–N live in `scripts/security_checks_api.py`. Shared primitives are in `scripts/security_common.py`.
+
+### Content classes (A–G)
+
 | 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 |
+| A · Hardcoded provider keys / PEM private keys / `SECRET=…literal`; git-tracked `.env`/`.dev.vars` | HIGH | A07 / LLM06 |
+| B · **Secret-in-logs** — `console/print` of a token/secret var or a token-labeled response body | HIGH | A09 / LLM06 |
+| C · SQL built via string interpolation; `eval`/`new Function`; `child_process.exec`+concat; `shell=True`; `innerHTML=`/`dangerouslySetInnerHTML` with a var | HIGH | A03 / LLM05 / ASI05 |
+| D · `fetch`/`requests` with a non-constant URL (SSRF) | MEDIUM | A10 |
+| E · Public POST/PUT/PATCH/DELETE endpoint that emails/writes-DB with no rate-limit keyword | MEDIUM | A06 / LLM10 |
+| F · Missing `_headers`/CSP at the project level | LOW | A02 |
+| G · User/tool input concatenated into a `*prompt`/`system` var; wildcard tool perms (`tools:["*"]`) | MEDIUM | LLM01 / LLM06 / ASI02 |
+
+### Authorization and boundary classes (H–N)
+
+| Check | Severity | OWASP |
+|---|---|---|
+| H · **Broken object-level authorization** — handler queries the data store with a request-supplied id and no owner/tenant predicate. CRITICAL when the handler mutates | CRITICAL / HIGH | A01 |
+| I · Mutating route with no auth reference at all; **fail-open env comparison** (`token !== process.env.X` with no assertion that `X` is set — unset env means the check passes for everyone) | CRITICAL / HIGH | A01 / A07 |
+| J · Privileged key behind a client-exposed prefix (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`, …) — service-role keys, provider API keys, signing secrets. Publishable/anon/DSN identifiers are allowlisted | CRITICAL / HIGH | A07 / LLM06 |
+| K · JWT `alg: none`, decode-without-verify, `verify_signature: False`; session cookie missing `httpOnly`/`secure`/`sameSite`; auth token in `localStorage` | CRITICAL–MEDIUM | A02 / A07 |
+| L · `Access-Control-Allow-Origin: *` or reflected origin, HIGH when paired with `Allow-Credentials: true` | HIGH / MEDIUM | A05 / A01 |
+| M · Request body spread into a DB write with no schema validation (mass assignment — caller sets `role`, `tenant_id`, `is_admin`); mutating route reading a body with no validation library present | HIGH / MEDIUM | A03 / A04 |
+| N · Model call with no output-token cap (HIGH when also untimed inside a loop); model output into an interpreter/shell/SQL/HTML sink; vector retrieval with no tenant/ACL filter; model-proposed tool calls dispatched with no authorization layer | HIGH / MEDIUM | LLM02 / LLM04 / LLM08 / ASI02 / ASI05 / ASI06 |
+
+Every H–N check requires **two** signals before it emits: a handler or sink match *and* the absence of the corresponding control. A gate that hard-blocks deploys cannot afford a noisy check, so single-signal heuristics are excluded even where they would catch more.
 
 ## 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.
+The scanner grades structure, not intent. It sees that a query has an owner predicate; it cannot see whether that predicate is the *right* one. Escalate for: business-rule and workflow authorization, property-level field permissions, whether a tenant boundary is correctly designed, RAG corpus partitioning, tool-permission scope versus actual task need, agent goal-drift, approval gates before destructive actions, and 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).
+- **CRITICAL** → blocks in every scope, including a spot finding in a file you did not touch. These are the shapes where shipping is the wrong move regardless of authorship: an unscoped mutating query, a fail-open auth guard, a service-role key in the client bundle, `alg: none`.
+- **HIGH** → fix before push (the gate blocks) when the finding is in a changed file. Advisory when it comes from the spot sweep. If it's a genuine false positive, annotate with `// nosec: <reason>` or `# nosec B###`; 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.
 
+Findings carry `scope: "deep" | "spot"` in JSON output, and `--json` `summary` reports `spot_total` and `blocking_total` alongside the severity counts.
+
 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.