crewforth 0.0.1 → 3.0.0-rc.2

package/kit/skills/reflect/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: reflect
+description: |
+  Retrospective self-audit after nontrivial work: unverified assumptions, skipped items, is-this-the-right-
+  approach — findings, not code. The step-back counterpart to iterate's refine-to-done loop.
+---
+
+# Reflect — step back and audit the work, not just the code
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "reflect", "retro", "retrospective", "what did we miss", "step back", "introspect"
+
+## When
+A nontrivial chunk of work just finished (a feature, a plan, a debugging session) and it's worth a deliberate
+step back **before** committing or moving on. This is the meta-cognitive counterpart to [[iterate]]: iterate
+drives a change *to* its exit test; reflect asks whether the exit test — and the approach behind it — was even
+the right one. Skip it for a one-line, unambiguous change; there's nothing to reflect on.
+
+## Measure first, then remember
+Run **`bash .claude/hooks/session-stats.sh`** before answering anything below, and open the pass with what it
+reports. A retro built only on recall is an interview with the least reliable witness in the room: the model
+reconstructs a tidy story from a context that has already been summarised, and the stretches where it span on a
+failing approach are exactly the ones it remembers least. The script counts what actually happened — prompts,
+tool calls, failing loops, near-duplicate prompts, interrupts, auto-compactions.
+
+Treat each ⚠️ as a **question to answer in the pass**, not a verdict: a runaway loop asks *what assumption kept
+failing*; a repeated prompt asks *what context never landed*; an interrupt asks *where intent diverged*; an auto
+compaction asks *what state was silently dropped*. If the numbers and your recollection disagree, the numbers are
+the record. If the script is missing (a plugin install has no `.claude/hooks/`), say the retro is recall-based —
+do not present recall as measurement.
+
+## The pass
+Ask each question honestly and write the answer, not a reassurance:
+1. **Unverified assumptions** — what did I take for granted that I never checked? Name each one and whether it
+   was actually confirmed (read the code / ran the flow) or just assumed.
+2. **What got skipped** — an edge case, an error path, a test, a doc update, a security/privacy angle. What was
+   silently dropped, and was that a conscious trade-off or an oversight?
+3. **Right approach?** — with hindsight, is this the direction we'd still pick? Did scope creep in? Is there a
+   simpler path we walked past ([[code-review]] altitude: could 200 lines be 50)?
+4. **Evidence gap** — which claims of "done" / "works" rest on having *observed* behavior vs. on inference?
+   An unobserved "it works" is a finding (see [[iterate]] / verify: drive the real flow).
+5. **What I'd tell the next session** — the one thing a fresh context most needs to know (feeds [[handoff]]).
+
+## Guardrails
+- **Findings, not code.** Reflect surfaces gaps; the relevant specialist fixes them (a found gap re-enters
+  [[iterate]] or the author agent). It changes nothing itself.
+- **Honest, not performative.** A retro that only confirms good work is a failed retro. If nothing is found,
+  say specifically *why* you're confident (what was verified), don't just assert it.
+- **Bounded.** One pass, concrete findings, then act or close — not an open rumination loop.
+- **Token discipline** ([[token-budget]]): a short ranked findings list to the main thread; detail to a file.
+
+## DoD (this skill's contribution)
+- `session-stats.sh` was run and every ⚠️ it raised is answered — or its absence is stated.
+- Assumptions are labeled verified vs. assumed; unverified ones are flagged, not buried.
+- Skipped items and any scope creep are named explicitly.
+- Every "done/works" claim is traced to observed evidence or marked as inference.
+- Findings are actionable (each maps to a fix, a follow-up, or an accepted trade-off).

package/kit/skills/release/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: release
+description: |
+  Versioning and CHANGELOG: SemVer mapped from Conventional Commits, Keep a Changelog format, tagging,
+  pre-release gates.
+  Use when cutting a version: bumping, writing the CHANGELOG entry, or tagging.
+---
+
+# Release & CHANGELOG
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "release", "cut a release", "changelog", "version bump", "bump the version", "new version", "tag", "semver"
+
+## SemVer mapping (derive from Conventional Commits)
+- `fix:` → **PATCH** (x.y.Z)
+- `feat:` → **MINOR** (x.Y.0)
+- `BREAKING CHANGE:` / `feat!:` → **MAJOR** (X.0.0)
+
+## CHANGELOG (Keep a Changelog)
+Headings: **Added · Changed · Fixed · Removed · Security · Deprecated**.
+Every version is dated; the `Unreleased` section can be auto-populated from commits.
+
+## Pre-release gates (all must pass)
+- [ ] Tests green + `sonarqube-check` PASSED
+- [ ] `dependency-audit` clean (0 HIGH/CRITICAL)
+- [ ] CHANGELOG up to date
+- [ ] Version number conforms to SemVer
+- [ ] **The release commit is a diff too (§4.6).** A `chore(release)` bump, a CHANGELOG-only edit and a docs-site
+      version touch each stage a diff, and §4.6 exempts nothing by size — `crew-review-agent` runs over them like
+      any other. A version that disagrees with the tag, a CHANGELOG entry naming the wrong one, a generated
+      manifest edited by hand: that is what this review is for, and all three have shipped before.
+- [ ] **Every distribution channel has a documented way to GET this version.** Publishing and reaching users are
+      different events. A channel whose consumers pin at install time — an editor extension, a plugin, a vendored
+      copy — leaves them on the version they installed until they ask for a new one, so a security fix ships and
+      does not arrive. For each channel name the upgrade command in the README, and say plainly where it is not
+      automatic.
+
+## Tagging
+```bash
+git tag -a vX.Y.Z -m "vX.Y.Z"    # asks for approval (§4.4); push on explicit request (§4.5)
+```
+
+## DoD
+- Correct SemVer bump; complete CHANGELOG; tag + rollback plan ready.

package/kit/skills/security-scan/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: security-scan
+description: |
+  Stack-agnostic security audit: map the attack surface, trace untrusted input to dangerous calls, surface
+  dependency and configuration flaws. Severity-ranked report with fixes.
+  Use when auth, input handling, secrets or dependencies change, and before a release.
+---
+
+# Security Scan
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "security scan", "run a security scan", "OWASP check", "scan for vulnerabilities", "find security vulnerabilities", "security audit", "api key", "secret key", "leaked credential", "credentials leaked", "hardcoded secret", "hardcoded password", "sql injection", "can an attacker"
+
+The core of a security vulnerability fits in a single sentence: **an untrusted input reaches a
+dangerous operation without being adequately checked.** This skill chases exactly that sentence — it first
+looks for where the input comes from, then where it flows, and what gate should sit in between.
+It is stack-agnostic: whatever the language/framework, the same logic applies; when current tooling and
+patterns are needed, it runs a web search.
+
+> **Crewforth adaptation (local, .claude/):** `crew-security-expert` applies this; findings are carried to
+> **crew-review-agent** in severity order, whatever the stack. Automatic
+> fixes only with explicit approval (§4.4); `.claude` does not go to the repo (§4.3). §4 Prohibitions apply.
+
+## What it does, what it doesn't
+- **Does:** surfaces common vulnerability classes, known vulnerable dependencies, and risky configuration; ties each finding to a concrete fix.
+- **Doesn't:** does not replace a professional pentest / SAST / DAST. The report **guides**, it does not give full assurance — state this at the end of the report.
+- **Boundary:** analysis is local; code/data is not sent to an external service, and the project directory is not left.
+
+## A question is not a scan
+Loading this skill does not mean running all of it. "Is this query injectable?", "should this key be in the
+repo?", "how do I hash these passwords?" are **questions**: answer them from the relevant part of this skill and
+stop — no discovery pass, no fan-out of verifiers, no coverage ledger, no report file. The full workflow below runs
+when the user asks for a scan, an audit or a security review of a codebase or a change, or asks for the report
+itself. When a request could be either, ask one question before starting the full workflow; do not guess upward.
+
+## Mental model — source → gate → sink
+Reduce every check to three questions:
+1. **Source** — where does the input enter? (route, API endpoint, form, CLI argument, file upload, WebSocket, queue message, external API response)
+2. **Sink** — which dangerous operation does this input reach? (SQL execution, shell, file path, HTML render, deserialization, template)
+3. **Gate** — is there validation / parameterization / escaping / authorization in between? If not, that's the finding.
+
+The scan applies this model on four fronts: **dependency · code · configuration · authorization**. The result is ranked by severity, and the fix is presented for the user to choose.
+
+## Scope
+Prefer **`docs/THREAT_MODEL.md`** if present (from the `threat-model` skill): its entry points and attack classes
+are the focus areas, and its impact/likelihood bias which findings count as high severity — the biggest lever on
+false positives. No threat model → map the surface yourself first (Front 0 · Discovery).
+
+## Checklist
+- [ ] Stack and package ecosystem(s) detected, attack surface mapped
+- [ ] Dependency audit run for each ecosystem
+- [ ] Source→sink paths traced across the four vulnerability classes
+- [ ] Configuration and secret leakage scanned
+- [ ] Authorization matrix produced, unprotected sensitive endpoints searched for
+- [ ] Code builds on a model (prompts, retrieval, memory, tools, sub-agents, MCP) → Front 5 run (`references/ai-agents.md`)
+- [ ] Each candidate adversarially **verified** (N-verifier disprove pass); FALSE_POSITIVE / CANNOT_VERIFY separated out
+- [ ] Severity **derived from preconditions × access** (not the scanner's category); verification ≠ severity
+- [ ] Findings reported in severity order, no secret disclosed; ruled-out findings recorded too
+- [ ] Fix options presented to the user
+
+---
+
+## Fronts
+
+Five review fronts — Discovery · Dependencies · Code (source→sink) · Configuration · Authorization: **`references/fronts.md`** (read the fronts you're scanning). A sixth, for code built on a model — prompts, retrieval, memory, tools, sub-agents, MCP — lives in **`references/ai-agents.md`**: read it only when that code is present.
+
+When you fan out a sub-agent per front, how you prompt it decides recall — describe vulnerability **shapes** not a
+checklist, scope each agent, and state that vulnerabilities exist: **`references/prompting.md`**.
+
+---
+
+## Verify before you report
+
+Discovery is deliberately noisy (recall-biased); a **separate adversarial pass** disproves each candidate before it
+reaches the report — the biggest lever on false positives. Run **N independent verifiers** per finding (each starts
+from the code, not the summary; each hunts for why it's *wrong*), classify **TRUE_POSITIVE / FALSE_POSITIVE /
+CANNOT_VERIFY**, then derive **severity from preconditions × access** (independently — "real" is not "critical").
+The verifier procedure, the false-positive exclusion rules, the parseable verdict block, and the severity matrix
+live in **`references/verify.md`**. Ruled-out findings are recorded, not silently dropped.
+
+## Report
+
+The severity scale, finding format, summary line, and the fix-presentation format live in **`references/reporting.md`**.
+
+## Invariant rules
+1. **Guides, does not assure** — it does not replace a professional audit; say so in the report.
+2. **State coverage, not just findings** — every report ends with a `complete / partial / unknown` ledger over the
+   threat model's surfaces, each non-complete row carrying its reason. Without it, "no findings" and "never
+   looked" read identically to whoever acts on the report (`references/reporting.md`).
+3. **Mask secrets** — only the first 4 + last 4 characters (`sk-p…i789`); never write the full secret.
+4. **No automatic fix without approval** — even if "Fix everything" is chosen, first show what will change.
+5. **Do not install tools without asking.**
+6. **Preserve behavior** — a fix must not change functionality beyond closing the vulnerability.
+7. **Stay local** — do not send code/data to an external service, do not cross the project boundary.
+8. **Do not run the code under review to prove a finding** — no build, test, install or fixture run of it unless it
+   is isolated: no network, an empty environment, writes confined to a scratch directory, and hard limits on time
+   and resources. An install runs the target's own scripts; a test run executes whatever the target chose. If that
+   isolation is not available, the finding stays **CANNOT_VERIFY** with the exact local check that would settle
+   it. Reading source never needs any of this; executing it always does.

package/kit/skills/security-scan/references/ai-agents.md

@@ -0,0 +1,107 @@
+# Front 5 — AI, agent and MCP code
+
+Read this front when the code under review builds on a model: it assembles prompts, retrieves context, stores
+memory, exposes or calls tools, delegates to sub-agents, or speaks MCP. It is about the CODE around the model. For
+testing whether a deployed agent's defences hold under attack, that is `red-team`.
+
+## The rule that decides what counts
+
+**Persuasive text is not a vulnerability. A missing deterministic control is.** A model can always be talked into
+something; that alone proves nothing about the system. A finding here needs a boundary that code failed to hold:
+content reached another principal's context, an action ran with authority the requester did not have, data was
+disclosed to someone who could not read it, or a sink was driven that the attacker could not reach directly.
+
+Three consequences follow, and they rule out most false positives in this front:
+
+- **Instructions in a prompt guard nothing.** "The system prompt forbids it" is not a control. Count only what
+  a deterministic path enforces: authorization scoped to the resource, isolation, binding, constrained
+  credentials.
+- **Everything the model reads or writes is untrusted input** — its own output, retrieved documents, memory, tool
+  descriptions, MCP responses. Point to the line of code that trusts it.
+- **Using your own authority on purpose is not a defect.** A user who asks the agent to do something they are
+  allowed to do has not been attacked because a model carried it out.
+
+Name, for every candidate: the attacker, the affected principal, the identity the action actually ran as, the
+resource, the exact action, the authority used, and the result someone can observe.
+
+## Where it breaks
+
+### Context, retrieval and memory
+- **Injected content reaching someone else's context.** Who can write each retrieved source — a document, page,
+  ticket, email, tool result — and whose session ends up reading it? Check that retrieval is scoped to the reader,
+  not just that the content looks benign.
+- **Context bleeding across sessions or tenants.** History, embeddings, retrieval results and prompt caches keyed
+  too broadly. A tenant field on the record is not enforcement if one query path or one cache key leaves it out.
+- **Memory that turns low-trust observations into durable instructions.** Content an attacker influenced, or a
+  model's own summary of it, written into memory that later steers another user or a privileged task. Who may
+  create, merge and delete memory, and does retrieval tell a user's preference apart from policy? A note a user
+  keeps for themself, read back only by that user, crosses no boundary.
+- **Forged provenance.** Prompt assembly that lets untrusted text pass as a system message, an earlier turn, a tool
+  result or a memory record — string concatenation, untyped history, a caller-supplied role field. It matters when
+  the forged label changes a trust decision or unlocks a capability.
+
+### Tools and actions
+- **Model-written arguments reaching a sink unchecked.** A tool schema shapes input; it does not authorize a path,
+  a URL, a query or a resource id. Follow each argument from the decoded call to the SQL, shell, file or network
+  call, and look for the handler's own validation.
+- **Confused deputy.** The agent acts with a broad service credential and the handler never re-checks whether the
+  requesting principal may touch that resource. Ask what that user could already do without the agent. One service
+  credential is fine when every call made with it is still scoped to the requester.
+- **Approval that does not bind the action.** The user approves one described action, and execution can use
+  different arguments, a different target, a later turn, a retry or a resumed session. Or attacker content triggers
+  a side effect under the victim's valid authority that the victim never asked for — generic permission does not
+  make that intentional. The approval has to bind the normalized tool name, the complete argument object, the
+  requester and the target.
+- **Schema and handler disagreeing.** Validation and the handler read one input two ways: an alias, a repeated or
+  unexpected key, a type that gets coerced, a free-form nested object, a value out of range. Validate again where a value
+  becomes a resource selector or a security option.
+- **Delegated loops with no ceiling.** A bounded request that can enqueue unbounded spend, sends, mutations or
+  external calls — no per-request budget, no per-action check, no cancellation, no idempotency. Establish it from
+  the code and a locally bounded loop, never by exhausting a real service.
+
+### MCP and sub-agents
+- **Delegation that hands over everything.** A sub-agent or MCP call receives the whole session, its credentials,
+  its memory, rather than the least authority the task needs; or its result is trusted on return.
+- **Identity by name instead of by connection.** Calls or results routed by a server name, tool name, request id,
+  resource URI or a model-chosen alias that an attacker can influence, instead of the authenticated connection and
+  the pending request. Can two servers claim one tool? Does a reconnect change the binding? Can one server's
+  response satisfy another's pending call?
+- **Metadata treated as policy.** Whatever an MCP peer says about itself — tool text, resource details, suggested
+  prompts, schemas, completions — can steer the model and can never grant it anything. Find the allowlist, the server
+  identity check and the handler authorization that stay authoritative when the metadata says otherwise.
+
+### Output and disclosure
+- **Model output rendered unencoded.** Output reaching HTML, Markdown, a template, a URL or a command without that
+  sink's encoding. Whether a renderer outside the repository sanitizes it is a fact you do not have — that makes
+  the candidate CANNOT_VERIFY, not confirmed.
+- **Secrets extractable from the assembled context.** Credentials, another user's data or access-granting policy
+  values placed in context that user-influenced output can reveal. Leaking generic instructions crosses no
+  boundary and is not a finding.
+
+## How to hunt it
+
+Before opening single files, make four inventories: the identities code runs under, the capabilities it holds, the
+context and memory stores something can write into, and the destinations output reaches. Then trace each request
+from the one who made it to the power finally used on its behalf. From each tool with side effects, walk back
+through dispatch, schema, confirmation, context, retrieval and ingestion; from each memory read, walk back to
+everyone who writes there. One action can arrive directly, from a queue, as a retry, a resumed run, a batch or
+through a delegate — the deciding check belongs after the arguments are fixed and before anything happens, on every
+one of those routes.
+
+## Before a finding here leaves the verifier
+
+Apply `verify.md` as usual, plus:
+
+1. It says which boundary was crossed and what anyone can see afterwards: who attacks, who (or which shared
+   resource) is harmed, the identity the action ran as, the target, and the action or disclosure nobody authorized
+   or asked for.
+2. A confused-deputy claim shows two things: the handler never checks the requester against the resource, AND the
+   attacker has no way to do the same through the product itself. An action-binding claim shows instead that
+   content the attacker controlled set off an action, carried out with the victim's authority, that the victim did
+   not mean to request or approve.
+3. A memory or retrieval claim shows both halves: where the attacker writes, and where another principal or a
+   privileged decision later reads. A shared record that nothing reads across a boundary does not qualify.
+4. An MCP identity claim looks at four things: which connection is authenticated, how a response is matched to its
+   request, how tool names are namespaced, and which credential is actually used. When the answer depends on
+   routing done by an outside server or the deployment, the verdict is CANNOT_VERIFY, naming the one fact that
+   would decide it.

package/kit/skills/security-scan/references/fronts.md

@@ -0,0 +1,99 @@
+# Review fronts
+
+The scan applies the **source → gate → sink** model on these fronts. Read the fronts you're scanning.
+
+## Front 0 — Discovery (map the surface)
+
+The rest of the audit rests on the map produced here.
+
+1. Scan for manifest/build files at the root and in subdirectories: `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `pom.xml`, `build.gradle`, `composer.json`, `*.csproj`, `*.sln`, `mix.exs`. In a monorepo, note each ecosystem separately.
+2. Derive the framework and runtime from the manifest.
+3. **List the attack surface:** all the points where user input enters the system (the "Source" list above). These are the starting points for the following fronts.
+4. Run a **web search** for the detected framework — tooling and patterns change often: `"[framework] security best practices"`, `"[framework] common vulnerabilities"`, the current `"OWASP Top 10"` list.
+
+---
+
+## Front 1 — Dependencies
+
+Known vulnerabilities in third-party packages are the cheapest path to most breaches.
+
+1. Run the audit command that suits the ecosystem (if it is not installed, suggest installing it, do not install it yourself):
+
+   | Ecosystem | Command |
+   |---|---|
+   | Node | `npm audit` · `pnpm audit` · `yarn npm audit` |
+   | Python | `pip-audit` |
+   | .NET | `dotnet list package --vulnerable --include-transitive` |
+   | Rust | `cargo audit` |
+   | Go | `govulncheck ./...` |
+   | Ruby | `bundle audit` |
+   | Java | OWASP Dependency-Check |
+
+2. If you are unsure of the correct/current command, verify it on the web; where possible, get machine-readable output with `--json`.
+3. Extract from each finding: package · installed version · vulnerability id (CVE/GHSA) · severity · fixed version.
+4. In a monorepo, audit each sub-project separately. The results go into the report (below).
+
+---
+
+## Front 2 — Code (source→sink tracing)
+
+Start from every entry point on the attack surface, trace the input to where it is used, and check whether there is a gate in between. The table below is the **minimum** coverage — if you see another sink during the scan, add it.
+
+| Sink class | Vulnerability | What the "gate" should be |
+|---|---|---|
+| **Query** | SQL / NoSQL / LDAP / ORM raw query injection | Parameterized query; no string concatenation |
+| **Command** | Shell/OS command injection | Argument array; no passing a string to the shell |
+| **Render** | XSS (input in HTML without escaping), SSTI (input as template code) | Context-appropriate escaping; input as data, not code |
+| **Path** | Path traversal, unrestricted file upload | Path allowlist/normalization; type-size-content validation |
+| **Object** | Insecure deserialization, mass assignment | Safe format; field allowlist |
+| **Expression** | Expression/eval injection, `eval`/`exec` | Never evaluate input as code |
+
+**On state-changing + browser-originating endpoints, additionally:**
+- **CSRF** — does the state-changing endpoint have token protection?
+- **CORS** — is there a wildcard origin with credentials, or an origin reflected without validation?
+
+**Secret leakage — hardcoded credentials in the source:** search for these patterns, excluding `.env.example` and test fixtures:
+```
+(password|api[_-]?key|secret|token)\s*[:=]\s*["'][^"']+["']
+-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----
+```
+Also: unmasked password/token/PII in logs; a stack trace or internal path leaked to the user.
+
+**Tracing method:** read the route/controller files (input enters here) → grep for dangerous calls (`eval`, `exec`, string-SQL) → check whether the middleware/interceptor has auth·CSRF·rate-limit → check whether the data model has mass-assignment protection. Run a web search for language-specific dangerous functions.
+
+**Record for each finding:** file:line · vulnerability · what an attacker could do (impact) · fix specific to this code.
+
+---
+
+## Front 3 — Configuration
+
+**Is a secret in the repo:**
+```bash
+git ls-files --error-unmatch .env 2>/dev/null && echo "WARNING: .env is tracked"
+```
+If it's a finding, CRITICAL: `git rm --cached .env` → add to `.gitignore` → **rotate the exposed secrets**.
+
+**Debug on in prod:** search for the framework-specific flag with `"[framework] debug mode production"`. Signs: an open debug flag, an error page showing a stack trace, a published source map, accessible development endpoints.
+
+**Insecure transport:** hardcoded `http://` addresses (API, webhook, OAuth redirect, CDN) that should be `https`, and cookies without `Secure`. Exclude `localhost`/`127.0.0.1`/`0.0.0.0`.
+
+**Missing security headers:** CSP, HSTS, X-Frame-Options, X-Content-Type-Options.
+
+---
+
+## Front 4 — Authorization (auth-z)
+
+Access-control flaws are the class most often missed in a scan, because the code appears to "work." Mandatory if the project includes admin/dashboard or role-based access:
+
+1. Enumerate all roles/levels (admin, moderator, user, guest…).
+2. Write all routes/endpoints and the **required** permission level into a matrix.
+3. Verify that each protected route actually checks — "being logged in" is not authorization.
+4. Look for endpoints that should be protected but aren't; try whether there is an admin endpoint reachable by guessing the URL.
+5. Verify that authorization is enforced both at the controller **and** at the data-access layer (IDOR: object reference without ownership validation).
+6. Privilege escalation: can a user change their own role/permission? Does a sensitive admin action require extra protection (re-auth/2FA)?
+7. **JWT:** `alg: none` / algorithm confusion, secret embedded in code, missing expiration.
+
+## Front 5 — AI, agent and MCP code
+
+Only when the code under review builds on a model. The classes, the rule that decides what counts, and the extra
+checks a finding must pass before it leaves the verifier are in **`ai-agents.md`**.

package/kit/skills/security-scan/references/prompting.md

@@ -0,0 +1,23 @@
+# Prompting the review sub-agents (defensive security)
+
+When the scan fans out a sub-agent per front, *how* you prompt it decides recall. Field-tested rules — these also
+apply to `red-team` and any agent you point at a codebase to find bugs:
+
+1. **Give the model room.** A high-level task beats prescriptive scaffolding. Long instructions, staged checklists,
+   and piles of reference material tend to backfire — the model pattern-matches your scaffold instead of reasoning
+   about the code.
+2. **Describe vulnerability *shapes*, not a checklist.** Enumerating bug types ("find SQLi, XSS, and CSRF")
+   **worsens** recall — the model stops at your list. Describe the structural property instead: *"attacker input
+   that alters the syntactic structure of an interpreted string — SQL, shell, HTML, a template — or crosses a trust
+   boundary without a gate."*
+3. **Scope each agent.** Tell it precisely which slice of the surface to search **and which classes you don't care
+   about**, so parallel agents don't all converge on the same easy findings. (A `threat-model` gives you this scope.)
+4. **Frame verification adversarially.** "Actively look for reasons this finding is *wrong*" beats "check for
+   protections" — the whole disprove pass lives in `references/verify.md`.
+5. **State that vulnerabilities exist.** "Act like a pentester" is weak. Strong: *"Produce a findings report with a
+   PoC for each Critical/High; assume there ARE vulnerabilities here; keep going until you've covered the surface."*
+6. **Share mitigations the code doesn't show** (a WAF rule, a gateway auth check, a platform default) up front — it
+   saves the reviewer from re-finding a path that is already closed one layer up (a common false positive).
+7. **Prompt-level guardrails are defense-in-depth only.** Real safety is human approval + the tool-level gates
+   (§4.4/§4.5), never a sentence in a prompt. Don't rely on "please don't exploit this" — rely on the gate.
+8. **The sub-agent's final report is all the caller reads** — put every finding and its coverage in it.

package/kit/skills/security-scan/references/reporting.md

@@ -0,0 +1,75 @@
+# Reporting & fix presentation
+
+## Report
+
+**Severity scale:**
+
+| Level | Meaning |
+|---|---|
+| CRITICAL | Directly exploitable — urgent (SQL injection, hardcoded secret in prod) |
+| HIGH | Serious — close before deploy (XSS, command injection, known CVE) |
+| MEDIUM | Defense gap — soon (missing CSRF, loose CORS) |
+| LOW | Best-practice violation — when convenient (debug mode, missing header) |
+| INFO | Observation — no immediate risk |
+
+**Finding format** (ranked by severity):
+```
+[CRITICAL] SQL Injection — src/api/users.ts:42
+  Vuln  : Input concatenated directly into the SQL query
+  Impact: DB can be read / modified / deleted
+  Fix   : Use a parameterized query
+```
+
+**Summary line:**
+```
+=== Security Scan Summary ===
+  CRITICAL: X · HIGH: X · MEDIUM: X · LOW: X · INFO: X · Total: X
+```
+
+## Coverage — say what you did NOT look at
+
+A report with no findings is read as "nothing is wrong". It can equally mean "that surface was never opened",
+and the two are indistinguishable to the person acting on it — who then ships believing an audit happened. The
+`CANNOT_VERIFY` verdict already handles this for an individual finding; coverage handles it for the audit.
+
+Every report ends with a coverage ledger, one row per surface from the threat model ([[threat-model]]):
+
+```
+=== Coverage ===
+  complete  auth/session handling        — read every route + middleware
+  complete  SQL data access              — grepped all query construction sites
+  partial   file upload                  — read the handler; storage backend config not available
+  unknown   payment webhook              — third-party signature logic, no source access
+  unknown   admin client (Blazor)        — out of scope this pass, agreed with the user
+```
+
+Rules:
+- **`complete` is a claim, not a hope.** Use it only where you can name what you read or ran. If you sampled,
+  it is `partial`.
+- Every `partial` and `unknown` carries **why** — no access, out of scope, no time, third-party. A bare
+  `unknown` is the same silence the ledger exists to remove.
+- `unknown` on a surface the threat model calls high-risk is itself a finding: report it at the severity that
+  surface would carry, not as a footnote.
+- The ledger is written **before** the fixes are proposed. Written afterwards, it gets trimmed to match the
+  work that happened to be done.
+- "Zero findings, coverage complete" is a strong claim and rare. "Zero findings, half the surface unknown" is
+  an honest and much more common one.
+
+### When a previous report exists
+Read it before planning, and let it shape priority — never coverage.
+- A previous **TRUE_POSITIVE** carries into this report only if the code on its path is unchanged; the verifier
+  re-checks it like any other candidate. Changed code makes it a fresh candidate, not an inherited one.
+- A previous **FALSE_POSITIVE** rules out that exact claim on that exact unchanged code — nothing more. The surface
+  it sat on is still reviewed.
+- A previous **CANNOT_VERIFY** is current work, unless the fact it waited on is still unavailable; then it carries
+  with that same named blocker.
+- A previous `partial` or `unknown` row is never inherited as `complete`, and a previous narrow or quick pass is
+  never read as "the rest was fine". Say in this report which rows came from the earlier one and why they still hold.
+
+## Fix presentation
+```
+How shall we proceed?
+  1. Fix everything        2. CRITICAL+HIGH only
+  3. Approve one by one    4. Manual (no changes)
+```
+For each fix: preview the diff → wait for approval → (if a dependency) upgrade command + breaking-change note → re-run the relevant check.

package/kit/skills/security-scan/references/verify.md

@@ -0,0 +1,131 @@
+# Verify before you report — the adversarial pass
+
+Discovery and verification want opposite things. **Discovery is recall-biased** — when unsure whether something is
+real, surface it (a low-confidence finding beats a missed bug). **Verification is precision-biased** — a separate,
+adversarial pass that tries to *disprove* each finding. Keeping them separate is the single biggest lever on false
+positives. (This is the same two-stage-verdict discipline `crew-code-review` uses — reused here for security findings.)
+
+Run this pass on every candidate before it reaches the report.
+
+## The verifier stance
+For each finding, run **N independent verifiers** (default **3**; 1 for a quick scan, 5 for a release/high-stakes
+audit). Each verifier:
+- **Starts from the code at the cited `file:line`, not the finding's summary.** If you start from the summary you
+  inherit its misreading.
+- Is stanced **"find any reason this finding is wrong."** Actively hunt for why it is *not* exploitable.
+- Is **blind to the other verifiers' reasoning** — shared context propagates the same blind spot.
+
+### "Independent" means a separate context, or it means nothing
+Three passes inside one context window are not three verifiers. The second pass has already read the first one's
+reasoning; the blindness above is then a wish, not a property, and the agreement it produces is one argument
+counted three times. So:
+- **Each verifier is its own subagent** (`Agent`, one call per verifier, run in parallel). A subagent has its own
+  context window: it cannot see what the others concluded, which is the whole point. Read-only work, so no
+  `worktree` is needed — nothing is being written.
+- **Give it the finding and the file:line, never your reasoning.** Not "I think X is exploitable because Y" —
+  just "claim: X at file:line. Try to refute it."
+- **If you did not isolate, say so.** Write `verifiers: 1 (single pass, not isolated)` in the verdict block. A
+  single honest pass is useful; three passes labelled as independent when they were not is worse than one,
+  because it launders confidence.
+
+**Cost gate, because isolation is not free** — each subagent re-pays for its own context (see `token-budget`), so
+N×findings gets expensive fast. Isolate by stake, not by default:
+- **critical / high severity, or anything heading for a release** → isolate, N=3 (N=5 for a release audit).
+- **medium** → isolate, N=1. One genuinely independent pass beats three entangled ones.
+- **low** → single inline pass, labelled as such. Do not spend a subagent proving a `low`.
+
+### The verifiers must not be three copies of one method
+Independent is still not uncorrelated. Three verifiers running the same four steps fail in the same place, and
+their agreement then reads as confirmation when it is only repetition. Assign each a **different attack**:
+- **Reachability** — can untrusted input actually arrive here? Quote the first call-site as evidence.
+- **Protection** — does something on every path already stop it? Try to break each guard.
+- **Reproduction** — what input, in what state, actually triggers it? If you cannot name one, that is
+  `CANNOT_VERIFY`, not agreement with the others.
+
+At N=5 add **exclusion rules** (does this match a known FALSE_POSITIVE class below?) and **blast radius** (if it
+is real, what does it actually reach?). Record which lens produced which verdict — a verdict whose lens is
+unnamed cannot be weighed.
+
+### Unanimity is a signal to check, not a verdict to trust
+If every verifier returns the same verdict **for the same reason**, that is one argument counted N times. Before
+accepting it, run one counterfactual pass: *"assume this verdict is wrong — what would have to be true, and what
+evidence would show it?"* Record the answer beside the verdict. Unanimity with N distinct reasons is strong;
+unanimity with one reason is a monoculture, and it is exactly how a whole panel misses the same guard.
+
+## The 4-step verify procedure (each step kills a specific false-positive class)
+1. **Read the cited code yourself** — do not trust the description.
+2. **Trace reachability backward from the sink.** Can untrusted input actually reach it? **Quote the first
+   call-site `file:line`** as evidence. *Unreachable code is the single largest source of false positives* — a
+   plausible-sounding chain is not enough.
+3. **Hunt for protections** on every path: validation, parameterization, auto-escaping, type/length bounds, an
+   auth/scope gate, or the code being dead/test-only.
+4. **Stress-test each protection on every path** — a guard that holds on one route but not another is not a guard.
+
+## Verdict — three outcomes, never a forced binary
+- **TRUE_POSITIVE** — requires ALL of: reachable + protections insufficient + exploitation feasible.
+- **FALSE_POSITIVE** — fails one of the above, or matches an exclusion rule below.
+- **CANNOT_VERIFY** — static reasoning hit its limit (needs a running system / data you don't have). Report it
+  honestly as `needs_manual_test`; never inflate uncertainty into a confident verdict.
+  - It carries **no severity**. It is a specific, source-grounded hypothesis that one missing fact blocks — not a
+    low-confidence confirmed vulnerability — and a severity on it would be read as a rating it has not earned.
+  - Name the missing fact exactly, and the check that would settle it.
+  - Controls that live outside the repository — a proxy, a WAF, provider settings, identity policy, network
+    topology, how a renderer sanitizes — are real controls. When a verdict depends on one that the source does not
+    show, do not assume it is **present**, and do not assume it is **absent**: that is what CANNOT_VERIFY is for.
+
+"I couldn't write a working PoC" is **weak** evidence of non-exploitability — do not downgrade on that alone.
+
+## Exclusion rules — FALSE_POSITIVE even if technically accurate
+1. Volumetric/rate DoS with no amplification (just "many requests").
+2. Test, fixture, example, or provably dead/unreachable code.
+3. Intended, documented design (a stated, accepted risk).
+4. Memory-safety issue in a memory-safe language/runtime.
+5. Input that only a trusted operator controls (a local CLI flag, an ops-only env var).
+6. "Outdated dependency" with no reachable vulnerable call path.
+7. Weak randomness used somewhere non-security (a cache key, a test seed).
+8. XSS auto-neutralised by the framework's default escaping.
+9. Traversal blocked one layer up (a gateway/service the reasoning didn't read).
+10. A theoretical-only TOCTOU with no realistic race window.
+11. "Missing hardening" with no concrete exploit (a nice-to-have header).
+12. Low-impact nuisance with no security consequence.
+
+Add project-specific rules as you confirm them.
+
+## Structured verdict block (one per finding, parseable)
+```
+VERDICT: TRUE_POSITIVE | FALSE_POSITIVE | CANNOT_VERIFY
+CONFIDENCE: 0-10
+VERIFIERS: <N, isolated | N, single pass not isolated>
+LENSES: <reachability, protection, reproduction — which ones actually ran>
+AGREEMENT: <unanimous-same-reason | unanimous-distinct-reasons | split N-M>
+REACHABILITY: <first untrusted call-site file:line, or "unreachable">
+EXCLUSION_RULE: <number, or none>
+RATIONALE: <cites concrete file:line, not prose>
+```
+`VERIFIERS` and `AGREEMENT` exist so the reader can discount the verdict without re-doing the work. "3, single
+pass not isolated" and "unanimous-same-reason" together mean one argument wearing three hats — still worth
+reporting, not worth treating as three. Leaving these fields out is how a weak verdict passes for a strong one.
+
+## Tally
+Verdict = majority of the N verifiers; confidence = mean of the agreeing votes. **Tie → the operator's noise
+tolerance:** precision → drop; recall → keep as `needs_manual_test`; ask → one batched question. Never silently
+drop a finding — a dropped finding is recorded (with its verdict) in the report's "Ruled out" section.
+
+## Severity is a SEPARATE judgment from verification
+"This is real" must not inflate into "this is critical." Derive severity from **preconditions × access level**, not
+from the vulnerability category:
+
+| access ↓ / preconditions → | 0 preconditions | 1–2 | 3+ |
+|---|---|---|---|
+| **unauthenticated / remote** | CRITICAL–HIGH | MEDIUM | LOW |
+| **authenticated** | MEDIUM | MEDIUM | LOW |
+| **local / operator** | LOW | LOW | INFO |
+
+- Take the **lower** of the two axes. If the precondition list has **3+ items, HIGH is almost certainly wrong.**
+- **HIGH or MEDIUM? Ask one question:** does the demonstrated result fully **defeat** an explicit control for an
+  action with real consequences, or only **weaken** it? Defeat is HIGH territory; weaken is MEDIUM at most. If you
+  cannot state the concrete damage in a sentence, the severity is lower than it feels.
+- Severity never exceeds the impact actually demonstrated.
+- A `threat-model` match may raise severity by **at most one step** — never two (a stated threat can't re-inflate a LOW to HIGH).
+- Record `severity_alignment` (**-5..+5**): judged from the stance of a reviewer who has seen two hundred inflated
+  scanner findings this week — how over- or under-stated is the raw claim? Negative = deflate it.