pi-dev-team 0.2.0

package/knowledge/security-primitives-contract.md

@@ -0,0 +1,301 @@
+---
+name: security-primitives-contract
+description: Versioned cross-plugin contract defining the data envelopes passed between dev-team and security-assessment. Agent IDs, skill IDs, three JSON schemas (RECON, unified finding, disposition register), and presentational severity mapping. Consumers declare `required-primitives-contract: ^1.0.0`.
+version: 1.3.1
+semver-policy: |
+  PATCH (1.0.x) — clarifications, typo fixes, documentation improvements; no
+                  schema changes.
+  MINOR (1.x.0) — additive schema changes (new OPTIONAL fields, new enum
+                  values, new agent IDs, new skill IDs, new guidance/
+                  invariants enforced downstream). Consumers on prior
+                  1.x.0 continue to work; new features ignored.
+  MAJOR (x.0.0) — breaking changes (renamed or removed fields, changed
+                  semantics, new REQUIRED fields, removed enum values).
+                  Consumers on prior major MUST be updated.
+---
+
+# Security Primitives Contract v1.3.1
+
+This file is the single source of truth for the data envelopes exchanged between `plugins/dev-team/` (producer of primitives) and `plugins/security-assessment/` (consumer). Downstream plugins declare compatibility via `required-primitives-contract: ^1.0.0` in their `plugin.json`.
+
+**Canonical schema registry**: this file is the single registry for every JSON/JSONL artifact shape shared or emitted in the security-assessment pipeline. Producer plugins (including the companion `security-assessment`) PR into this file rather than forking per-plugin contracts, so reviewers can trace any artifact back to one authoritative schema. New envelopes arrive as MINOR releases with `## Envelope N` sections plus changelog entries; per-tool raw outputs remain out of contract (see below).
+
+The contract covers three data envelopes, two registries, and a presentational severity mapping. Per-tool raw outputs are **explicitly not in the contract** — they are normalized into the unified finding envelope by SARIF-first adapters in `skills/static-analysis-integration/SKILL.md`. That normalization layer is an implementation detail behind the contract, free to evolve under PATCH releases.
+
+## Bypass path
+
+Edits to this file are guarded by `hooks/contract_version_guard.py`. A body change without a `version` field bump is blocked. Bypass is auto-granted only for release-please commits (matched by author `release-please[bot]` or commit-message prefix `chore(main): release`).
+
+## Registries
+
+### Agent IDs
+
+Agents that produce or consume contract envelopes. Each ID is stable across the major version. Renames trigger a MAJOR bump.
+
+| Agent ID | Produces | Consumes | Defined in |
+|---|---|---|---|
+| `codebase-recon` | RECON envelope | — | `plugins/dev-team/agents/codebase-recon.md` |
+| `security-review` | unified findings | — | `plugins/dev-team/agents/security-review.md` |
+| `fp-reduction` | disposition register | unified findings, RECON | `plugins/security-assessment/agents/fp-reduction.md` (companion plugin) |
+| `tool-finding-narrative-annotator` | — | unified findings, RECON | `plugins/security-assessment/agents/tool-finding-narrative-annotator.md` (companion plugin) |
+| `business-logic-domain-review` | unified findings (domain-level) | — | `plugins/security-assessment/agents/business-logic-domain-review.md` (companion plugin) |
+| `cross-repo-synthesizer` | — | RECON, unified findings | `plugins/security-assessment/agents/cross-repo-synthesizer.md` (companion plugin) |
+| `exec-report-generator` | — | all three envelopes | `plugins/security-assessment/agents/exec-report-generator.md` (companion plugin) |
+
+Adding an agent ID is a MINOR bump. Removing one is a MAJOR bump.
+
+### Skill IDs
+
+Skills that participate in the contract (operate on envelopes or define adapter behavior).
+
+| Skill ID | Role | Defined in |
+|---|---|---|
+| `static-analysis-integration` | SARIF-first adapters; produces unified findings from per-tool outputs | `plugins/dev-team/skills/static-analysis-integration/SKILL.md` |
+| `false-positive-reduction` | Consumes unified findings, produces disposition register | `plugins/security-assessment/skills/false-positive-reduction/SKILL.md` (companion plugin) |
+| `compliance-mapping` | Consumes unified findings, emits compliance annotations (not in contract — downstream-only) | `plugins/security-assessment/skills/compliance-mapping/SKILL.md` (companion plugin) |
+| `security-assessment-pipeline` | Orchestrates full envelope flow end-to-end | `plugins/security-assessment/skills/security-assessment-pipeline/SKILL.md` (companion plugin) |
+
+## Envelope 1 — RECON
+
+Normalized reconnaissance output from `codebase-recon`. Schema: `knowledge/schemas/recon-envelope-v1.json`.
+
+Key design notes:
+- Superset of the `codebase-recon` v0.1 placeholder; `schema_version` bumps to `"1.0"`.
+- Added under 1.0: `repo.vcs` object (distinguishes git from non-git repos), `architecture.notable_anti_patterns` (open-ended notes from the recon pass), `security_surface.csp_headers` (referenced in security contexts).
+- All v0.1 field names remain stable.
+
+### `file_inventory` (added in 1.2.0)
+
+An authoritative enumeration of every file the recon considered in-scope at recon time. Gap 6's manifest-membership hook depends on this field — without it, consumers cannot answer "did a scan agent read a file outside the recon surface?" without their own tree walk.
+
+The list itself ships as a **sibling file** (not embedded JSON) because mid-size repos produce 10k+ paths that bloat envelope diffs and validation cost. The main envelope carries a pointer and a count; the list lives at `.claude/memory/recon-<slug>.inventory.txt`.
+
+**Shape** (main envelope, optional at schema level):
+
+```json
+"file_inventory": {
+  "source": "git-ls-files" | "filesystem-walk",
+  "count": <integer>,
+  "sibling_ref": "recon-<slug>.inventory.txt"
+}
+```
+
+All three sub-fields are required when the object is present. Object itself is optional so pre-1.2.0 envelopes stay schema-valid; `codebase-recon` always emits it from 1.2.0 forward.
+
+**Sibling file contract** (`.claude/memory/recon-<slug>.inventory.txt`):
+
+- UTF-8, LF line terminators, no BOM.
+- One repo-relative path per line; path separator `/` on every platform; no leading `./`.
+- Sorted lexicographically under `LC_ALL=C`; deduplicated.
+- No blank lines. Final line is LF-terminated.
+- No symlink entries — symlinks resolve to real-path targets; broken symlinks are skipped and recorded in the envelope's `notes` array.
+- Plain text; not JSON; not validated by schema tooling.
+
+**Enumeration pipeline** — canonical shippable implementation at `plugins/dev-team/scripts/recon_inventory.py` (the single source of truth per the 1.2.0 plan's decision #1). Both the `codebase-recon` agent and the test harnesses invoke this script. Excluded prefixes and filenames for the non-git branch live in `plugins/dev-team/knowledge/recon-inventory-excludes.txt`.
+
+### Consumer error contract
+
+Consumers that depend on `file_inventory` (e.g., Gap 6's PreToolUse hook, or any audit that wants to prove a reviewer didn't silently read outside the recon surface) **must fail-open** when any of the three branches below fires. Fail-open = emit a one-time informational notice to stderr in the exact format below, then proceed without the membership check. Never block the consumer's normal work; the inventory is a nice-to-have quality signal, not a correctness gate.
+
+| Branch | Trigger | Stderr notice template |
+|---|---|---|
+| a | `file_inventory` field is absent on the envelope | `[recon-inventory] notice: file_inventory field absent on envelope; proceeding without membership check` |
+| b | `file_inventory.sibling_ref` resolves to a file that is missing or unreadable at `.claude/memory/<sibling_ref>` | `[recon-inventory] notice: sibling file <path> missing; proceeding without membership check` |
+| c | `file_inventory.count != wc -l <sibling>` (envelope declares N, sibling contains M, M != N) | `[recon-inventory] notice: file_inventory.count (<declared>) != wc -l <sibling> (<actual>); proceeding without membership check` |
+
+Reference implementation: `evals/primitives-contract/fixtures/consumer-stub-fail-open.sh`. Conformance test: `evals/primitives-contract/tests/backward-compat-1.2.0.sh`.
+
+## Envelope 2 — Unified finding
+
+Narrow normalization over SARIF `result` objects. Schema: `knowledge/schemas/unified-finding-v1.json`.
+
+Required fields only. Per-tool raw output is NOT part of the contract (it is accessible via the `metadata.source_ref` field for debugging but consumers must not depend on its shape).
+
+Required fields:
+- `rule_id` — string, format `<source>.<language?>.<rule>` (e.g. `semgrep.python.hardcoded-password`, `gitleaks.generic.aws-access-key`)
+- `file` — repo-relative path
+- `line` — 1-indexed integer
+- `severity` — enum: `error | warning | suggestion | info`
+- `message` — one-line human-readable summary
+- `metadata` — object with `source` (string: tool name), `confidence` (enum: `high | medium | low | none`)
+
+Optional (at schema level):
+- `column` — 1-indexed integer
+- `end_line`, `end_column`
+- `cwe`, `cve`, `owasp` — string arrays
+- `metadata.source_ref` — opaque pointer to the raw tool output (debugging aid only; not stable)
+- `metadata.exploitability` — enum: `demonstrated | plausible | theoretical | unknown`
+
+**Strongly recommended at schema; enforced downstream (added in v1.1.0):**
+
+- `cwe` is **strongly recommended** for every finding with `severity: error` or `severity: warning`. The schema keeps `cwe` optional for backward compatibility with adapters that do not emit it (hadolint, actionlint, some trivy config rules). The `exec-report-generator` (Phase B Step 14) **rejects** findings without CWE from CRITICAL / HIGH sections of the exec report with a named error, and lists them in an appendix for follow-up.
+- CRITICAL / HIGH presentational findings (see § Severity mapping below) **must** carry a reachability trace. The trace lives on the finding's disposition entry, not on the finding itself. The exec-report-generator enforces this too.
+
+## Envelope 3 — Disposition register
+
+Output of `fp-reduction` over unified findings. Schema: `knowledge/schemas/disposition-register-v1.json`.
+
+One disposition entry per unified finding processed. Each entry:
+- `finding` — the unified finding being dispositioned (embedded verbatim, not a reference)
+- `verdict` — enum: `true_positive | likely_true_positive | uncertain | likely_false_positive | false_positive`
+- `reachability` — object: `{ reachable: bool, rationale: string }`
+- `reachability_source` — enum: `joern-cpg | llm-fallback` (drives exec report's fallback banner per P2 Phase B)
+- `exploitability` — object: `{ score: 0-10, rationale: string }`
+- `dispositioner` — string: agent ID that produced this disposition (typically `fp-reduction`)
+- `dispositioned_at` — ISO-8601 timestamp
+
+## Envelope 4 — Accepted-risks log (added in v1.3.0)
+
+Per-target suppression log emitted by `scripts/apply-accepted-risks.sh` in the companion plugin. Written to `<memory-dir>/accepted-risks-<slug>.jsonl`. Source-of-truth input is `<target-dir>/ACCEPTED-RISKS.md` — see `plugins/security-assessment/docs/accepted-risks-format.md` for the input format.
+
+Two record shapes, discriminated by the `status` field:
+
+**Suppression record** — an active accepted-risks entry matched a finding and that finding was removed from `findings-<slug>.jsonl`:
+
+```json
+{
+  "status": "suppressed",
+  "rule_id": "semgrep.csharp.sqli.raw-sql-concat",
+  "source_ref": "src/Legacy/Query/Foo.cs",
+  "source_ref_glob": "src/Legacy/**/*.cs",
+  "reason": "Legacy reporting module scheduled for deletion Q3 2026 (TICKET-1234).",
+  "expires": "2026-09-30",
+  "iso": "2026-04-24T17:30:39Z"
+}
+```
+
+**Expired-entry record** — an ACCEPTED-RISKS.md entry's `expires` date has passed; the script logs the lapse but does NOT suppress any finding:
+
+```json
+{
+  "status": "expired",
+  "rule_id": "hadolint.DL3003",
+  "source_ref_glob": "docker/base/Dockerfile",
+  "reason": "Base image built in a controlled CI step; cd is intentional.",
+  "expires": "2020-01-01",
+  "iso": "2026-04-24T17:30:39Z"
+}
+```
+
+Field invariants:
+- `status` ∈ `{"suppressed", "expired"}`.
+- `rule_id`, `source_ref_glob`, `reason`, `expires`, `iso` are required on both shapes.
+- `source_ref` is required only on `status:"suppressed"` (it records the specific finding that matched).
+- `expires` is `YYYY-MM-DD` UTC.
+- `iso` is ISO-8601 UTC (second precision suffices; the log is for audit, not tracing).
+
+Idempotency: the script rewrites (does not append to) the log file on each run, so a re-run against unchanged inputs produces a byte-identical file.
+
+## Envelope 5 — Severity-floors log (added in v1.3.0)
+
+Per-target floor-application log emitted by `scripts/apply-severity-floors.sh` in the companion plugin. Written to `<memory-dir>/severity-floors-log-<slug>.jsonl`. The script raises `exploitability.score` on matched disposition entries (Envelope 3) and emits one JSONL record per match.
+
+```json
+{
+  "id": "sec-appsettings.json-511",
+  "floor_class": "hardcoded-creds",
+  "floor": 9,
+  "original_score": 9,
+  "final_score": 9
+}
+```
+
+Field invariants:
+- `id` matches an entry `id` in the disposition register.
+- `floor_class` comes from the `<class> floor=<n>` pattern embedded in the entry's `exploitability.rationale` (fp-reduction agent convention) AND must appear in `plugins/security-assessment/knowledge/severity-floors.json`'s `recognized_classes`.
+- `floor`, `original_score`, `final_score` are integers in 0..10.
+- `final_score >= original_score` (floors only raise).
+- `final_score >= floor` (the floor was respected).
+- Records are emitted for every matched entry on first run, even when `original_score == final_score` (log-every-match semantics, matching the 2026-04-24 extranetapi reference).
+
+Idempotency: the script sets `exploitability.floor_applied: true` on each mutated entry; subsequent runs skip marked entries, so the log file is append-safe across re-runs against an already-floored register.
+
+Suppression phrase: entries whose rationale contains `floor=<n> suppressed to <m>` are skipped entirely (the fp-reduction agent signaled the default floor does not apply in context) — no log record is emitted.
+
+## Severity mapping (added in v1.1.0)
+
+The unified finding envelope uses a lint-grade severity scale optimized for tool output (`error | warning | suggestion | info`). The `exec-report-generator` maps these into a **presentational** CRITICAL / HIGH / MEDIUM / LOW scale for executive-audience reports. The presentational scale matches the `opus_repo_scan_test` reference and is familiar to CISO / CTO readers.
+
+The mapping combines the finding's `severity` with its disposition-register `exploitability.score` (0–10) and `metadata.exploitability` enum. The scale is presentational only — findings remain stored at the narrower schema-level severity.
+
+| Presentational | Definition | Driven by |
+|---|---|---|
+| **CRITICAL** | Immediate exploitation, data breach, or fraud bypass. Demands same-day remediation. | `severity: error` AND (`exploitability.score >= 7` OR `metadata.exploitability: demonstrated`) |
+| **HIGH** | Exploitable with moderate effort, significant impact. Demands same-week remediation. | `severity: error` AND `exploitability.score` in `[4, 6]`; OR `severity: warning` AND `exploitability.score >= 7` |
+| **MEDIUM** | Requires specific conditions or insider access. Addressed in normal release cycle. | `severity: warning` AND `exploitability.score` in `[3, 6]`; OR `severity: error` AND `exploitability.score < 4` |
+| **LOW** | Informational or defence-in-depth. No immediate action. | `severity: suggestion`, or `severity: warning`/`error` with `exploitability.score < 3`, or `severity: info` |
+
+Tie-breaks:
+- A finding with `verdict: false_positive` never reaches the presentational scale; suppressed from the report.
+- `verdict: likely_false_positive` downgrades one presentational level (CRITICAL → HIGH → MEDIUM → LOW).
+- A finding without a disposition entry (happens when FP-reduction is bypassed) is presented at one level lower than the mechanical mapping would give, with a footnote noting FP-reduction was skipped.
+
+### Downstream invariants
+
+The `exec-report-generator` enforces these invariants and rejects (with named errors) any finding that violates them from CRITICAL / HIGH sections. LOW findings can bypass all three:
+
+1. **CWE required** on CRITICAL and HIGH. Findings without CWE appear in an appendix labelled "Findings missing CWE — investigate" for the audit trail.
+2. **Reachability trace required** on CRITICAL and HIGH. The trace comes from the disposition entry's `reachability.rationale` (min 20 chars per schema). Missing → same appendix.
+3. **Dedup applied**. One credential appearing in N config variants is one finding with N locations, not N findings.
+
+## Out of contract
+
+Explicitly NOT part of this contract:
+
+- Per-tool raw outputs (SARIF documents, JSON outputs from bespoke adapters). These flow through the adapter layer and are normalized into unified findings. Consumers treat adapters as opaque — the unified finding envelope is the contract boundary.
+- Internal adapter configuration (`skills/static-analysis-integration/references/tool-configs.md` layouts, matcher regexes). These are implementation details of `skills/static-analysis-integration`.
+- Compliance mapping outputs. These are a downstream product of the companion plugin, not shared cross-plugin primitives.
+- Report templates (executive report sections, Mermaid diagrams). These are presentation concerns.
+- Red-team harness artifacts. The harness ships its own schemas under `plugins/security-assessment/harness/redteam/schemas/` — separate lifecycle, separate versioning.
+
+## Conformance
+
+Schemas live at `plugins/dev-team/knowledge/schemas/{recon-envelope,unified-finding,disposition-register}-v1.json` and must validate using any Draft 2020-12 JSON Schema validator.
+
+Conformance fixtures at `evals/primitives-contract/fixtures/` exercise each envelope against positive and negative cases. The `/agent-audit` command validates references to this file (agent IDs cited elsewhere in the plugin must match the registry above).
+
+A mutation test alters a field in a conformance fixture; CI must fail. A version-mismatch mock (producer 2.0.0 vs. consumer `^1.0.0`) exercises the `install.sh` refusal path.
+
+## Versioning lifecycle
+
+- Clarifications and typos → open a PR with `version: 1.0.X` (PATCH).
+- New optional fields, new enum values, new agent or skill IDs, new guidance or invariants enforced downstream → `version: 1.X.0` (MINOR). Update the relevant schema file; add a fixture; document the addition under `## Changelog`.
+- Removing a field, renaming a field, changing a field's semantics, or adding a REQUIRED field → `version: X.0.0` (MAJOR). Publish a migration note; downstream plugins' `required-primitives-contract` constraints force them to update before installing.
+
+## Changelog
+
+### 1.3.1 (2026-07-25)
+
+Clarification only — no schema or field changes. Consumers on `^1.0.0` are unaffected.
+
+- **Path clarification.** Envelope 1's `file_inventory` sibling-file location updated from bare `memory/recon-<slug>.inventory.txt` to `.claude/memory/recon-<slug>.inventory.txt`, matching the `.claude/`-scoped runtime-artifact convention adopted repo-wide (#1405/#1406). The `sibling_ref` field itself remains a bare filename (`"recon-<slug>.inventory.txt"`); only the directory it resolves under changed. Historical entries below are left as originally written for the version they describe.
+
+### 1.3.0 (2026-04-24)
+
+Additive schema release. Consumers on `^1.0.0` continue to install unmodified.
+
+- **New Envelope 4 — Accepted-risks log.** Registers the `<memory-dir>/accepted-risks-<slug>.jsonl` artifact emitted by the companion plugin's new `scripts/apply-accepted-risks.sh` (Phase 1c). Two record shapes: `status:"suppressed"` and `status:"expired"`. Input format reference lives at `plugins/security-assessment/docs/accepted-risks-format.md`.
+- **New Envelope 5 — Severity-floors log.** Registers the `<memory-dir>/severity-floors-log-<slug>.jsonl` artifact emitted by the companion plugin's new `scripts/apply-severity-floors.sh` (Phase 2b). Schema matches the 2026-04-24 extranetapi reference byte-for-byte.
+- **New canonical-registry paragraph** in the preamble making explicit that this file is the single registry for artifacts shared between the two plugins. Addresses an architecture-review observation during the helper-scripts PR that producers should PR into this file rather than fork per-plugin contracts.
+- **Backward compatibility:** pre-1.3.0 plugin installations continue to work — the new envelopes have no producers outside the new helper scripts, and the existing envelopes are unchanged.
+
+### 1.2.0 (2026-04-24)
+
+Additive schema release. Consumers on `^1.0.0` continue to install unmodified.
+
+- **New field:** Envelope 1 now carries an optional `file_inventory` object (`source` enum, `count` integer, `sibling_ref` string). The actual path list ships as a sibling file `memory/recon-<slug>.inventory.txt` to keep JSON diffs small on large repos.
+- **New subsection:** `### Consumer error contract` under Envelope 1 documents the three fail-open branches (field absent, sibling absent, count mismatch) with exact stderr notice templates. Reference implementation at `evals/primitives-contract/fixtures/consumer-stub-fail-open.sh`.
+- **New canonical enumeration pipeline:** `plugins/dev-team/scripts/recon_inventory.py` is the single source of truth for both the git-ls-files branch and the filesystem-walk branch; excludes for the non-git branch live in `plugins/dev-team/knowledge/recon-inventory-excludes.txt`.
+- **Backward compatibility:** pre-1.2.0 envelopes continue to validate. Consumers that need the field (Gap 6's manifest-membership hook) follow the fail-open contract documented above.
+
+### 1.1.0 (2026-04-21)
+
+Additive guidance release. Schema files unchanged; consumers on `^1.0.0` work unmodified.
+
+- **New section:** Severity mapping from unified `severity` + disposition `exploitability` into presentational CRITICAL / HIGH / MEDIUM / LOW. Matches the `opus_repo_scan_test` reference's severity framework so executive-audience reports are comparable.
+- **New invariants (enforced by `exec-report-generator`, not by schema):** CWE required on CRITICAL / HIGH; reachability trace required on CRITICAL / HIGH; dedup applied before reporting. Findings violating these are reported in a dedicated appendix rather than silently dropped.
+- **Backward compatibility:** adapters that do not emit CWE (hadolint, actionlint, some trivy config rules) continue to work; their findings land at MEDIUM or LOW unless FP-reduction's exploitability scoring elevates them — in which case the CWE-missing appendix notifies reviewers.
+
+### 1.0.0 (2026-04-21)
+
+Initial contract. Finalizes the RECON envelope v0.1 placeholder from `codebase-recon`. Defines unified finding envelope as a narrow SARIF `result` normalization. Defines disposition register as the FP-reduction output envelope. Registers initial agent and skill IDs.

package/knowledge/security-review-rule-map.yaml

@@ -0,0 +1,107 @@
+# security-review category -> unified-finding rule_id mapping
+#
+# Single source of truth for agent-emitted rule_ids. The adapter at
+# plugins/dev-team/skills/static-analysis-integration/adapters/security-review-adapter.py
+# reads this file. See skills/static-analysis-integration/references/security-review-adapter.md for the contract.
+#
+# Versioning is independent of the primitives-contract. Bump on any semantic change:
+#   - patch: renumber / rename a rule_id that aliases an upstream rename
+#   - minor: add a new mapping
+#   - major: remove or move a mapping
+version: 1.1.0
+mappings:
+  # Pattern-visible classes — adopt upstream rule_ids (rules-vs-prompts policy Q4).
+  A02.weak-hashing-md5: semgrep.generic.weak-hash-md5
+  A03.sql-injection: semgrep.generic.sql-injection
+  A03.xss-innerhtml: semgrep.javascript.xss-innerhtml
+  A03.command-injection: semgrep.generic.command-injection
+  A08.binary-formatter: semgrep.csharp.binary-formatter
+  A08.object-input-stream: semgrep.java.deserialization-object-input-stream
+  A08.js-eval: semgrep.javascript.eval-injection
+  A05.cors-wildcard: semgrep.generic.cors-wildcard
+  A07.jwt-alg-none: semgrep.generic.jwt-alg-none
+  A02.insecure-random-js: semgrep.javascript.weak-random
+  A05.default-credentials: semgrep.generic.default-credentials
+
+  # Judgment-only classes — security-review namespace.
+  A01.idor: security-review.a01.idor
+  A01.missing-auth-middleware: security-review.a01.missing-auth-middleware
+  A01.missing-authorize-csharp: security-review.a01.missing-authorize-csharp
+  A04.no-rate-limiting: security-review.a04.no-rate-limiting
+  A04.no-brute-force-protection: security-review.a04.no-brute-force-protection
+  A07.jwt-no-exp: security-review.a07.jwt-no-exp
+  A07.session-fixation: security-review.a07.session-fixation
+  A09.pii-in-logs: security-review.a09.pii-in-logs
+  A05.verbose-errors-prod: security-review.a05.verbose-errors-prod
+  A09.no-auth-event-logging: security-review.a09.no-auth-event-logging
+
+# Policy-as-data: the rules-vs-prompts boundary, made structural (issue #118).
+# This replaces the prose "classes that move to rules / stay in prompt / both"
+# lists from the removed rules-vs-prompts-policy.md. The boundary is now
+# queryable here and enforced by scripts/audit-rules-vs-prompts.sh.
+#
+#   surface: rule   — pattern-stable, detected by a semgrep rule; the agent does
+#                     NOT re-detect (only assesses exploitability on tool findings)
+#   surface: prompt — judgment class; detection needs cross-file/architectural
+#                     reasoning, lives in the agent prompt + owasp-detection.md
+#   surface: both   — a rule detects the pattern AND the agent assesses impact
+#
+# rule/both classes MUST carry a measured `fp_rate` (≤ 0.10 policy threshold)
+# and a `fixtures` dir with ≥1 positive and ≥1 negative fixture.
+classes:
+  # --- rule-surface (pattern-visible; adopt upstream semgrep rule_ids) ---------
+  A02.weak-hashing-md5:
+    surface: rule
+    fp_rate: 0.0
+    fixtures: knowledge/rule-fixtures/A02.weak-hashing-md5
+  A02.insecure-random-js:
+    surface: rule
+    fp_rate: 0.0
+    fixtures: knowledge/rule-fixtures/A02.insecure-random-js
+  A03.sql-injection:
+    surface: rule
+    fp_rate: 0.05
+    fixtures: knowledge/rule-fixtures/A03.sql-injection
+  A03.xss-innerhtml:
+    surface: rule
+    fp_rate: 0.0
+    fixtures: knowledge/rule-fixtures/A03.xss-innerhtml
+  A03.command-injection:
+    surface: rule
+    fp_rate: 0.05
+    fixtures: knowledge/rule-fixtures/A03.command-injection
+  A08.binary-formatter:
+    surface: rule
+    fp_rate: 0.0
+    fixtures: knowledge/rule-fixtures/A08.binary-formatter
+  A08.object-input-stream:
+    surface: rule
+    fp_rate: 0.0
+    fixtures: knowledge/rule-fixtures/A08.object-input-stream
+  A08.js-eval:
+    surface: rule
+    fp_rate: 0.05
+    fixtures: knowledge/rule-fixtures/A08.js-eval
+  A05.cors-wildcard:
+    surface: rule
+    fp_rate: 0.0
+    fixtures: knowledge/rule-fixtures/A05.cors-wildcard
+  A07.jwt-alg-none:
+    surface: rule
+    fp_rate: 0.0
+    fixtures: knowledge/rule-fixtures/A07.jwt-alg-none
+  A05.default-credentials:
+    surface: rule
+    fp_rate: 0.1
+    fixtures: knowledge/rule-fixtures/A05.default-credentials
+  # --- prompt-surface (judgment classes; no fixtures/fp_rate required) ---------
+  A01.idor: { surface: prompt }
+  A01.missing-auth-middleware: { surface: prompt }
+  A01.missing-authorize-csharp: { surface: prompt }
+  A04.no-rate-limiting: { surface: prompt }
+  A04.no-brute-force-protection: { surface: prompt }
+  A07.jwt-no-exp: { surface: prompt }
+  A07.session-fixation: { surface: prompt }
+  A09.pii-in-logs: { surface: prompt }
+  A05.verbose-errors-prod: { surface: prompt }
+  A09.no-auth-event-logging: { surface: prompt }

package/knowledge/skills-registry.md

@@ -0,0 +1,72 @@
+<!-- Extracted from CLAUDE.md ## Skills Registry — do not duplicate here, edit the source -->
+
+# Skills Registry
+
+> This file is extracted from `plugins/dev-team/CLAUDE.md` → Skills Registry. Edit the source table there; this file is a standalone reference copy for agents that need to load only the skills catalog.
+
+User-invocable workflows in `.claude/skills/`. All review skills are executed under orchestrator direction. Every agent declares its own `model:`/`effort:` frontmatter — the native Claude Code sub-agent contract the harness resolves directly (see **Model/Effort Resolution** in `agents/orchestrator.md`).
+
+> **Moved to the `marketplace-dev` plugin.** The plugin-authoring skills `agent-create`, `agent-skill-authoring`, `agent-add`, `agent-remove`, and `add-plugin` are no longer part of dev-team. They — plus a generalized `/plugin-audit` — now live in the companion `marketplace-dev` plugin, which builds and audits Claude Code plugins for any marketplace. Install it from the `bfinster` marketplace.
+
+## Command Table
+
+| Command | File | Role | What It Does |
+| --------- | ------ | ------ | -------------- |
+| `/agent-audit` | `skills/agent-audit/SKILL.md` | orchestrator | Audit agents/skills/hooks for structural compliance (self-audits this plugin's own agents/skills — largely repo-checkout-relative, see ADR 0032) |
+| `/agent-eval` | `skills/agent-eval/SKILL.md` | orchestrator | Run eval fixtures, grade accuracy, detect regressions (operates on this repo's own `evals/` corpus — monorepo-checkout-only, see ADR 0032) |
+| `/agent-readiness` | `skills/agent-readiness/SKILL.md` | worker | Score how agent-ready the current project repo is against the Agent-Readiness Scorecard; emits a tiered JSON/Markdown report (scores your project, not the plugin — use `/harness-audit` for that) |
+| `/apply-fixes` | `skills/apply-fixes/SKILL.md` | implementation | Apply correction prompts from `/code-review` output |
+| `/apply-test-doubles` | `skills/apply-test-doubles/SKILL.md` | worker | Apply `/cd-test-architecture`'s Step 4b build-vs-document decision logic against an existing, saved assessment report — or, when no valid report path is given, against a target to assess first — without re-running the full Steps 0-6 assessment each time |
+| `/autoship` | `skills/autoship/SKILL.md` | orchestrator | Bounded automated issue-dispatch round: reclaim orphaned in-progress issues, discover `autoship:ready` issues, invoke `/ship --no-auto-merge` sequentially for each, detect stakeholder-input blockers, classify outcomes, and log a round summary to `.claude/metrics/autoship-log.jsonl`. Requires `--max-issues` and `--max-cost-usd` |
+| `/benchmark` | `skills/benchmark/SKILL.md` | worker | Capture runtime performance metrics (Core Web Vitals, resource sizes) and compare against baselines |
+| `/browse` | `skills/browse/SKILL.md` | worker | Browser-based QA: navigate, screenshot, click, fill forms via Playwright |
+| `/build` | `skills/build/SKILL.md` | orchestrator | Execute an approved plan in small per-behavior batches (Code-First Small Batches) with inline reviews and verification evidence; ends with a Farley Score for the branch's tests before prompting for `/pr` |
+| `/careful` | `skills/careful/SKILL.md` | worker | Toggle destructive command blocking (rm -rf, force-push, DROP TABLE, etc.) |
+| `/co-evolution-audit` | `skills/co-evolution-audit/SKILL.md` | worker | Flag production files that churn repeatedly while their paired test files do not — the "Red Queen" co-evolution gap. Uses git log --stat, language-aware pairing heuristics (Python, JS/TS, Go, Java, C#), and produces a ranked table of stale-coverage pairs as prioritization input for /test-improve and /mutation-testing |
+| `/code-review` | `skills/code-review/SKILL.md` | orchestrator | Run review agents, auto-fix actionable issues, re-run until clean (up to 5 iterations). Short-circuits documentation-only changesets (skips review; `--force` overrides) |
+| `/continue` | `skills/continue/SKILL.md` | orchestrator | Resume work from a prior session using phase progress files |
+| `/cost-report` | `skills/cost-report/SKILL.md` | worker | Report actual token spend and dollar cost of dispatched work — per agent and total — and flag cost regressions |
+| `/coverage-baseline` | `skills/coverage-baseline/SKILL.md` | worker | Phase-2 of `/test-improve` — detect the repo's coverage tool, capture line+branch percentages as the pre-improvement baseline, post to the parent issue or local FEATURE.md |
+| `/coverage-delta` | `skills/coverage-delta/SKILL.md` | worker | Phase-5 of `/test-improve` — re-run coverage and post Δ vs. baseline after each Story closes; when `--story-files` is supplied, also runs scoped mutation testing on those files and emits a structured status (`ok | net_new_survivors | first_measurement | tool_unavailable | skipped_empty_scope`) for the orchestrator to act on; never halts and never overwrites history (atomic temp-file-then-rename writes to`mutation-history.json`) |
+| `/explore` | `skills/explore/SKILL.md` | worker | Charter-driven exploratory testing of a running target (Chaos Specialist mode): structured heuristics + adversarial expansion, auto-triages critical defects, writes an incremental report |
+| `/fix` | `skills/fix/SKILL.md` | orchestrator | Investigate a bug via `/triage` (or reuse an existing triage record), prove the defect reproduces, implement the record's TDD Fix Plan one RED/GREEN cycle at a time with a regression check after each cycle, close the record, and delegate to `/pr` for a reviewed pull request |
+| `/freeze` | `skills/freeze/SKILL.md` | worker | Scope-lock editing to a glob pattern; blocks edits outside the pattern |
+| `/frontend-architecture` | `skills/frontend-architecture/SKILL.md` | orchestrator | Dispatch `component-architecture-review` over the frontend component files to catch reusable components that should be extracted, duplicated UI patterns, prop drilling, granularity problems, and inconsistent component APIs (advisory) |
+| `/gherkin-derive` | `skills/gherkin-derive/SKILL.md` | worker | Standalone Gherkin derivation from code — discovers the public surface (OpenAPI → routes → tests → signatures), recommends a BDD binding mode via the value rubric, writes `.feature` files and (bdd-runner) pending step stubs; no tracker Stories. Phase 3 of `/test-improve` |
+| `/gherkin-public` | `skills/gherkin-public/SKILL.md` | worker | Standalone worker — author Gherkin scenarios for the entire public interface (API endpoints, UI flows, batch-job entry points, library exports, event types) at the observable boundary. Standalone; not part of the current `/test-improve` orchestrator flow |
+| `/guard` | `skills/guard/SKILL.md` | worker | Combined `/careful` + `/freeze` for production-critical sessions |
+| `/harness-audit` | `skills/harness-audit/SKILL.md` | orchestrator | Analyze harness effectiveness and flag stale components (audits this plugin's own agents/skills/hooks — not your project, see ADR 0032; contrast `/agent-readiness`, which scores your project) |
+| `/harness-e2e-check` | `skills/harness-e2e-check/SKILL.md` | worker | On-demand end-to-end integration check of the harness's own mechanisms (failure-class routing, dead-end detection, evidence bundles, invariants/rollback, refactor-freeze guard family, lesson-validation weighting, handoff rename) — originated as issue #907's post-merge test plan, kept repeatable via `skills/harness-e2e-check/references/watchlist.md`'s regression tracking |
+| `/headless-run` | `skills/headless-run/SKILL.md` | worker | Run a Claude Code skill/command headlessly in an isolated subprocess (fresh `--session-id`, clean HOME/config, scrubbed env, JSON result, timeout) so a benchmark harness (e.g. #821 running `/code-review` per case) doesn't inherit the parent Remote session identity/tool surface — the reusable #842 workaround |
+| `/help` | `skills/help/SKILL.md` | worker | List the main dev-team workflows, with `--all` to show every user command |
+| `/issues-from-assessment` | `skills/issues-from-assessment/SKILL.md` | worker | Convert a `/cd-test-architecture` assessment into a parent + Phase-tagged child issues via the tracker CLI resolved from the parent URL host (gh / az / glab / acli). Falls back to local plan files when no URL is given or the CLI is missing |
+| `/issues-from-plan` | `skills/issues-from-plan/SKILL.md` | orchestrator | Break a plan into independently-grabbable GitHub issues |
+| `/orchestration-benchmark` | `skills/orchestration-benchmark/SKILL.md` | orchestrator | Pre-registered 3-arm solo-vs-orchestration A/B benchmark at matched verification rigor; reports per-class medians + spread, the mandatory mechanism check, and the delegation crossover threshold |
+| `/plan` | `skills/plan/SKILL.md` | orchestrator | Decompose a feature into vertical slices — each with its Gherkin scenarios and TDD steps; persists slice Gherkin to `.feature` files when the project has a BDD convention |
+| `/pr` | `skills/pr/SKILL.md` | orchestrator | Run quality gates and create a pull request (enables auto-merge by default) |
+| `/project-init` | `skills/project-init/SKILL.md` | worker | Get a repo ready for the dev-team toolchain: detect the stack (JS/TS, Python, C#, Java), inventory existing tools, confirm a three-column plan, install only what's missing repo-level; full JS scaffold for greenfield JS; also offers detection-gated capability tools (semgrep, Playwright, adr, gh, docker scanners) and the opt-in all-or-none code-lookup group (CodeGraph — user-level only, never committed; Repowise — local keyless index + MCP server; graphify — repo-level native integration with a CLAUDE.md corruption guard) |
+| `/property-based-testing` | `skills/property-based-testing/SKILL.md` | worker | Generate a runnable property-based test for a target function — a round-trip test for an encode/decode pair, or an invariant test for a documented postcondition ("returns sorted", "is idempotent"); Hypothesis for Python, fast-check for JS/TS |
+| `/quality-targets-converge` | `skills/quality-targets-converge/SKILL.md` | worker | Phase-8 of `/test-improve` — loop that picks the largest gap to the four quality targets (coverage / mutants / determinism / speed) and dispatches the smallest action to close it |
+| `/report-pdf` | `skills/report-pdf/SKILL.md` | worker | Render a dev-team Markdown report (any `.dev-team-reports/*.md` or `reports/*.md`) to a styled, shareable PDF via the shared `report_pdf.py` module; graceful engine fallback (pandoc + headless Chrome → weasyprint → wkhtmltopdf → md-to-pdf), skips with an install hint when no engine is present |
+| `/repo-review` | `skills/repo-review/SKILL.md` | orchestrator | Whole-repository drift review for `token-efficiency-review`, `ai-provenance-review`, `claude-setup-review`, and `component-architecture-review` — agents whose findings are properties of accumulated drift or the full codebase, not any single diff, so they were removed from `/code-review`'s per-diff panel (#1733) and run here instead, on demand. Report-only — never gates a commit |
+| `/review` | `skills/review/SKILL.md` | orchestrator | Alias for `/code-review` — same arguments, same behavior |
+| `/review-agent` | `skills/review-agent/SKILL.md` | worker | Run a single review agent (used for inline checkpoints) |
+| `/review-summary` | `skills/review-summary/SKILL.md` | orchestrator | Generate compact session summary for context continuity |
+| `/run-report` | `skills/run-report/SKILL.md` | worker | Report one orchestrated run's timeline joined from `boundary-events.jsonl`, `cost-metering.jsonl`, and `workflow-states.jsonl` for a given `session_id` (default: most recent) — per-state dwell time, rejection count, hook denials/bypasses by cause, and best-effort cost |
+| `/semantic-scan` | `skills/semantic-scan/SKILL.md` | worker | Build computation register and detect semantic duplicates across architectural layers |
+| `/semgrep-analyze` | `skills/semgrep-analyze/SKILL.md` | worker | Run Semgrep SAST and return structured findings |
+| `/session-review` | `skills/session-review/SKILL.md` | orchestrator | Mine real session transcripts (via the deterministic `session_report.py --profile maintainer`) and dispatch `session-analysis` to suggest token/rework/accuracy improvements; suggests, never auto-applies |
+| `/setup` | `skills/setup/SKILL.md` | orchestrator | Provision a repo for the dev-team plugin end to end: install plugin prerequisites (jq, python3, per-language mutation tooling — Stryker, pitest, Stryker.NET), then generate dev-team-specific project config (CLAUDE.md, PostToolUse formatting hook, agent template activation, generated `/pr` command) from the stack signal `/project-init` establishes; invokes `/project-init` for all stack detection/toolchain install |
+| `/ship` | `skills/ship/SKILL.md` | orchestrator | Run the full spec→plan→build (Code-First Small Batches)→code-review→PR(auto-merge) pipeline as one command, pausing at the existing human gates |
+| `/source-verification` | `skills/source-verification/SKILL.md` | worker | Extract and verify factual claims in generated content against this repo's own code and, where needed, external sources — flags each claim verified/contradicted/unverifiable, never silently drops or defaults one to "verified" |
+| `/telemetry` | `skills/telemetry/SKILL.md` | worker | Manage and report the opt-in, privacy-clean usage telemetry beacon (on/off/status/report) |
+| `/test-audit-disable` | `skills/test-audit-disable/SKILL.md` | worker | Standalone worker — detect tests that cannot fail (no assertions, tautologies, self-equality, swallowed exceptions) and disable each by skip-and-tag with the reason; never deletes. Not part of the current `/test-improve` orchestrator flow |
+| `/test-design` | `skills/test-design/SKILL.md` | orchestrator | Deep test-design review: dispatch test-review + test-smell-review, score all existing tests (Farley Score), then run test-design-advisor for testability/refactor recommendations (advisory) |
+| `/test-health` | `skills/test-health/SKILL.md` | orchestrator | Project-wide test-strategy audit: shape vs. architecture fit, quadrant coverage, flaky/automation maturity, ordered plan. Runs `/test-design` (Farley Score + smell themes) and `mutation-testing` and folds their results in; delegates pipeline assessment to cd-test-architecture (advisory) |
+| `/test-improve` | `skills/test-improve/SKILL.md` | orchestrator | Consolidated analyze-then-improve test orchestrator — 10 phases (0-9): Phase-0 approach contract → coverage + mutation baseline → optional `/gherkin-derive` → `/test-health` analyze → `/issues-from-assessment` plan fixes → `/build` + `/coverage-delta --workflow test-improve` + `mutation-kill` per Story (no-refactor) → refactor decision → optional refactor-for-testability → `/quality-targets-converge` → 10-section executive-summary report. Defaults to lightweight ceremony; opts into heavier capabilities only when the operator asks; Go-aware (mutation advisory); local-first with `--parent <url>` opt-in for tracker sinks |
+| `/triage` | `skills/triage/SKILL.md` | worker | Investigate a bug and write a triage record to `.dev-team-reports/triage/<slug>.md` with a TDD fix plan |
+| `/unfreeze` | `skills/unfreeze/SKILL.md` | worker | Lift the scope lock set by `/freeze` |
+| `/upgrade` | `skills/upgrade/SKILL.md` | worker | Check for and apply plugin updates from within a session |
+| `/version` | `skills/version/SKILL.md` | worker | Report the installed plugin version |
+
+Referenced from: `plugins/dev-team/CLAUDE.md` → Skills Registry

package/knowledge/task-size-classifier.md

@@ -0,0 +1,103 @@
+# Task Size Classifier
+
+Objective task-size signal that feeds the `trivial | standard | complex` vocabulary
+used by `/plan` (step 5a tier), `/build` (per-step review depth), and the
+orchestrator's no-plan fast path. **Never re-classify using a fresh LLM judgement** —
+derive the tier from the objective signals below.
+
+Calibrated from `docs/experiments/agentic-workflow-evidence/data/3sizes-3arms-summary.json`.
+Routing rationale: Rec 2 of `docs/experiments/RECOMMENDATIONS.md` — the full
+pipeline's cost premium shrinks as tasks grow (4.74× small, 2.57× medium,
+1.33× large), so small, well-specified work routes to direct single-agent
+dispatch and the pipeline is reserved for large, multi-file work.
+
+## Inputs
+
+Collect these signals before classifying. When a signal is unavailable (e.g. no
+plan yet exists), omit it and classify conservatively.
+
+| Signal | How to obtain |
+|--------|---------------|
+| `files_changed` | `git diff --name-only HEAD` or the plan's slice file lists (deduplicated) |
+| `loc_delta` | `git diff --stat HEAD \| awk '/files? changed/ {print $4+$6}'` — net insertions + deletions |
+| `slice_count` | `plan-waves.sh` JSON `.slices \| length` — or 1 when no plan exists |
+| `wave_count` | `plan-waves.sh` JSON `.waves \| length` — or 1 when no plan exists |
+| `has_complex_step` | Any step in the plan with `**Complexity**: complex` |
+| `decision_axis_triggered` | Any high-reversal-cost axis in `knowledge/decision-defaults.md` raised by this task (checked during discovery) |
+| `single_module` | True when every changed file (from the plan's slice file lists, or `git diff --name-only HEAD`) lives in one module — a single top-level source directory/package plus its test mirror. False when files span modules or the file set is unknown. |
+
+## Classification Rules
+
+Apply in order; the first match wins.
+
+### Trivial (no-plan fast path eligible)
+
+**ALL** of the following must hold:
+
+- `files_changed` ≤ 1
+- `loc_delta` ≤ 50
+- `slice_count` ≤ 1
+- `wave_count` ≤ 1
+- `has_complex_step` = false
+- `decision_axis_triggered` = false  ← decision-axis guardrail: never skips plan for high-reversal-cost work
+
+Expected saving vs full pipeline: ~65% fewer turns, ~45% lower cost (small-kata data; see calibration file).
+
+### Complex
+
+**ANY** of the following:
+
+- `files_changed` ≥ 6
+- `loc_delta` ≥ 300
+- `wave_count` ≥ 2
+- `has_complex_step` = true
+- `decision_axis_triggered` = true
+- Security-sensitive or cross-cutting concern (cross-module invariant, auth, data schema)
+
+### Standard
+
+Everything between trivial and complex.
+
+## Route (1:1 with classification — this file is the single source of truth)
+
+| Classification | Route |
+|---|---|
+| `trivial` | No-plan fast path |
+| `standard`, **fast-path eligible** (below) | No-plan fast path |
+| `standard`, otherwise | Full three-phase workflow |
+| `complex` | Full three-phase workflow |
+
+**Fast-path eligibility for `standard`** (Rec 2): a well-specified
+single-module `standard` task routes to the no-plan fast path when **ALL** of
+the following hold:
+
+- `single_module` = true
+- `slice_count` ≤ 1
+- `has_complex_step` = false
+- `decision_axis_triggered` = false  ← decision-axis guardrail: a triggered axis always excludes the fast path
+
+Any exclusion failing — files spanning modules, more than one slice, any
+`complex` step, or any triggered decision axis — sends the task to the full
+three-phase workflow. When `single_module` cannot be determined, treat it as
+false (bias rule below).
+
+## Bias rule
+
+When signals are ambiguous or a signal is missing, **classify up** (standard rather
+than trivial, complex rather than standard). The fast path is an optimisation — the
+cost of a false-trivial (wrong route, rework) is higher than the cost of a false-standard
+(unnecessary planning).
+
+## Decision log entry
+
+After classifying, append to `.claude/memory/decisions.md`:
+
+```
+**ID**: DEC-<date>-SIZE
+**Date**: <date>
+**Agent**: orchestrator
+**Task**: <task slug>
+**Decision**: Classified as <trivial|standard|complex> → route <fast path|full workflow>
+**Inputs**: files_changed=<N>, loc_delta=<N>, slice_count=<N>, wave_count=<N>, has_complex_step=<bool>, decision_axis_triggered=<bool>, single_module=<bool>
+**Rationale**: <which rule fired>
+```