crewforth 0.0.1 → 3.0.0-rc.1

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.

package/kit/skills/sonarqube-check/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: sonarqube-check
+description: |
+  SonarQube quality gate, any language, no company server needed: run SonarQube Community Build locally (Docker),
+  read the real gate + issues, fix by rule id, re-scan and diff. A linter's green build is a pre-check, never the gate.
+---
+
+# SonarQube quality gate — produce the real report, locally
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "sonarqube", "quality gate", "code smell", "sonar scan", "sonar rapor", "A rating"
+
+**Only a SonarQube analysis can say "rating A, 0 findings".** A clean `build` says the compiler was happy — a
+different claim, about a different rule set. Passing one off as the other is how a team is told the code is clean
+and then opens a report full of findings.
+
+You do **not** need a company server or someone else's token to get the real thing: **SonarQube Community Build is
+free, needs no licence key, and runs in one Docker container on this machine.** That is the default path here — the
+gate is produced locally, offline, and it is a genuine SonarQube verdict, not a proxy for one.
+
+Language-agnostic on purpose: SonarQube covers 20+ languages plus IaC (Terraform, Kubernetes, Dockerfile). Detect
+what the project actually uses; never assume a stack.
+
+## Step 1 — get a real analysis (pick the first that applies)
+
+**a) The project already has a SonarQube** → use it, and skip to step 2.
+
+**b) It does not → stand one up locally.** Docker one-liner, the Docker-free server zip, the first login and the
+token: **`references/stand-up-server.md`**. No licence, no external account, nothing leaves the machine.
+
+> **Restarting is not installing.** Bringing an already-approved service back up on this machine — the same
+> image, the same volumes — is resuming what the user already said yes to, and this skill's own advice to keep
+> a named volume assumes exactly that. A NEW image, a new volume, or a tool this machine does not have is an
+> install, and needs the answer below.
+>
+> **Nothing here is installed without the user saying so.** Docker, Java, a scanner, a linter — each is a proposal
+> with its cost stated, and the user picks. If they decline all of them, that is a valid answer: go to (c) and
+> report "unverified" rather than installing anything to make a number appear.
+
+Scan with whatever runner the project's stack uses — the scanner is the same product for every language:
+
+| Project | Scan command |
+|---|---|
+| Any stack (generic) | `sonar-scanner -Dsonar.projectKey=app -Dsonar.sources=. -Dsonar.host.url=http://localhost:9000 -Dsonar.token=$T` |
+| Maven / Gradle | `mvn sonar:sonar -Dsonar.host.url=… -Dsonar.token=$T` · `gradle sonarqube …` |
+| .NET | `dotnet sonarscanner begin /k:app /d:sonar.host.url=… /d:sonar.token=$T` → `dotnet build` → `dotnet sonarscanner end /d:sonar.token=$T` |
+| JS/TS, Python, Go, PHP, Ruby | the generic `sonar-scanner` above (add coverage report paths if the project produces them) |
+
+**c) No server is possible at all** (no Docker, no Java, no permission to run one) → run the language's Sonar-rule
+engine locally as a pre-check (**`references/local-engines.md`** — which engine per language, and how close it is
+to Sonar's own rules) and **say what that is worth**, in these words rather than a
+rating: *"the local rule engine reports N issues, none open; the SonarQube rating and the gate were not produced —
+no analysis ran."* Then list what stays unverified: taint/injection, hotspot review state, coverage, duplication,
+files outside the compiled language, and the project's own quality profile. Offer branch (b) — a local server, with
+or without Docker — as the way to close it.
+
+**Never invent the verdict.** A rating exists only where an analysis produced one; without it the honest output is
+"unverified", and that is the sentence that saves the user from promising a clean report they cannot back.
+
+## Step 2 — read the verdict, don't infer it
+
+```bash
+S=http://localhost:9000; K=app          # or the project's own host/key
+curl -sfu "$T:" "$S/api/qualitygates/project_status?projectKey=$K"     # pass / fail, and which condition failed
+curl -sfu "$T:" "$S/api/issues/search?componentKeys=$K&resolved=false&ps=500"   # rule id + file + line per finding
+curl -sfu "$T:" "$S/api/hotspots/search?projectKey=$K&status=TO_REVIEW"          # hotspots are a SEPARATE endpoint
+curl -sfu "$T:" "$S/api/measures/component?component=$K&metricKeys=alert_status,bugs,vulnerabilities,security_hotspots,code_smells,coverage,duplicated_lines_density,reliability_rating,security_rating,sqale_rating"
+```
+
+Also read the gate's definition (`/api/qualitygates/show`): most gates judge **new code**, not the whole project.
+Chasing overall counts while the gate measures new code burns days and still fails; the reverse leaves real debt.
+Know which one applies before planning the work.
+
+## Step 3 — fix by rule, never by impression
+
+Group findings by `rule` (`csharpsquid:S1481`, `typescript:S3776`, `python:S5852`, …) and take one rule at a time,
+all occurrences together. Read what the rule actually asks, fix the cause, cite the rule id in the change. The
+domain owner does the fixing — a security rule is `crew-security-expert`'s, a query/index rule is
+`crew-database-expert`'s.
+
+**Never close a finding by silencing it.** `#pragma warning disable`, `// NOSONAR`, `eslint-disable`, an exclusion in
+`sonar-project.properties` — each one changes the report without changing the code. It needs a written reason and
+the user's approval, every time.
+
+**Security Hotspots do not close by editing code.** Each is reviewed in the UI and marked *safe* (with a rationale)
+or *fixed*. Code changes alone leave it `TO_REVIEW` and the gate keeps failing.
+
+## Step 4 — re-scan and diff. The loop is the deliverable
+
+Re-run step 1's scan, re-read step 2, and report the **difference**: counts before → after, which rule ids
+disappeared, which remain, which are new. "It should be clean now" is not a result — a second analysis is.
+Repeat until the gate says `OK`, or every remaining finding has a user-approved suppression. Nothing here closes on a first pass.
+
+## What even a local SonarQube cannot see
+
+Community Build has no **taint/injection analysis** (data flow from user input to a dangerous sink — SQLi, XSS,
+command injection); that engine is in the paid editions. It also has no branch/PR analysis. So a clean local gate
+is not proof of injection safety: cover that with the **`security-scan`** and **`threat-model`** skills plus a
+`crew-security-expert` review, and say which of the two verdicts you are reporting.
+
+## DoD
+- The verdict is quoted **from an analysis**: gate status, counts by severity, ratings, analysis date, and where it
+  ran (project server or local container).
+- Every finding closed by a code change, or by a suppression the user explicitly approved with a written reason.
+- Hotspots reviewed in the UI, not merely edited around.
+- A re-scan ran after the fixes and the before → after diff by rule id is reported.
+- Injection risk stated separately (taint analysis is not in Community Build).
+- Anything not done is said plainly — never implied clean.

package/kit/skills/sonarqube-check/references/local-engines.md

@@ -0,0 +1,32 @@
+# Running Sonar rules locally with no server at all
+
+Read this only on branch (c) of step 1 — no server is possible (no Docker, no Java, no permission to run one), or
+as a pre-check before anything is scanned.
+
+This is worth more than it sounds: several languages have SonarSource's **own** rule engine as a normal dependency,
+so you can find and fix most rule violations offline, before anything is ever scanned. What no local engine can
+produce is the **verdict** — ratings (A/B/C), gate pass/fail, coverage, duplication, hotspot review state and the
+project's quality profile are computed by the server, from an analysis. Findings yes; a rating no.
+
+**The rule, for every language:** find whether SonarSource publishes its own rule engine for the project's
+language and wire *that* into the build or the editor. Where only a third-party look-alike exists, use it and say
+that the rule ids will not match the report. Ask which languages the repo actually contains — most repos have
+more than one, and each needs its own engine.
+
+| Stack (alphabetical — no language is the default) | Local engine | How close to Sonar's own rules |
+|---|---|---|
+| Go | `golangci-lint` and friends | Third-party; overlaps in intent, not in rule ids |
+| Java / Kotlin | SonarQube for IDE (SonarLint) in the editor; SpotBugs + PMD in the build | Editor-side runs Sonar analyzers; the build-side pair is a different rule set |
+| JS / TS | `eslint-plugin-sonarjs` | SonarSource's own JS/TS rules, delivered through ESLint |
+| .NET (C# · VB.NET) | `SonarAnalyzer.CSharp` / `.VisualBasic` (Roslyn, at build time) | SonarSource's own analyzer, 480+ C# rules; rule-set parity with the server is not documented either way — close, not proven identical |
+| PHP / Ruby / other | that language's linter | Varies; check whether it is SonarSource's or a look-alike |
+| Python | `ruff` / `pylint` + `bandit` | **Not Sonar rules** — an approximation |
+
+**Injection / taint rules are not in any of these** — they run only on SonarQube Server/Cloud, in the commercial
+editions. So even a spotless local run says nothing about SQLi/XSS/command injection; that gap is covered by
+`security-scan` + `threat-model` + a `crew-security-expert` review, and is reported as its own line, never folded
+into a "clean" claim.
+
+Pin versions so builds stay reproducible (with Central Package Management, declare it there). Turning warnings into
+errors is the project's call — propose it, don't impose it. And whatever the local run says, the honest wording
+stays: *findings fixed; rating and gate not produced — no analysis ran.*

package/kit/skills/sonarqube-check/references/stand-up-server.md

@@ -0,0 +1,25 @@
+# Standing up SonarQube Community Build locally
+
+Read this only on branch (b) of step 1 — the project has no SonarQube and one is being stood up. No licence, no
+external account, nothing leaves the machine.
+
+**The consent rule in SKILL.md governs every line below.** Docker, Java, a scanner — each is a proposal with its
+cost stated, and the user picks. Restarting an already-approved service is not installing; a new image, a new
+volume, or a tool this machine does not have is.
+
+```bash
+# b1 — with Docker (one command)
+docker run -d --name sonarqube -p 9000:9000 sonarqube:community    # first boot ~1-2 min
+
+# b2 — WITHOUT Docker: the plain server zip. Needs Java 17 or 21 on PATH (`java -version`), nothing else.
+#   download SonarQube Community Build, unzip (e.g. C:\sonarqube), then start it:
+#     Windows      C:\sonarqube\bin\windows-x86-64\StartSonar.bat
+#     Linux/macOS  ./bin/<platform>/sonar.sh console
+#   It runs on an embedded H2 database — no database to install for local use.
+```
+
+Either way: http://localhost:9000 · first login `admin`/`admin` · set a new password · then My Account → Security →
+generate a token. **That token is local and yours** — it is not a company credential and nothing is sent anywhere.
+
+Persist the container (`-v sonarqube_data:/opt/sonarqube/data`) so history survives, and put the key/exclusions in
+`sonar-project.properties` so every later run is identical.