pi-dev-team 0.2.0

package/skills/static-analysis-integration/adapters/security-review-adapter.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""security-review agent output -> unified-finding envelope adapter.
+
+Reads the security-review agent's JSON output (see
+plugins/dev-team/agents/security-review.md for the agent-output
+schema) and emits one unified-finding envelope v1 (JSONL) per issue.
+
+Rule_id lookup is driven by the canonical mapping at
+plugins/dev-team/knowledge/security-review-rule-map.yaml. This
+adapter contains NO inline rule_id literals beyond the
+``security-review.`` namespace prefix constant used for the
+fallback path; the single-source-of-truth invariant is enforced by an
+AST-level test in evals/security-review-adapter/tests/.
+
+Contract, error semantics, and failure modes are documented in
+plugins/dev-team/skills/static-analysis-integration/references/security-review-adapter.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from typing import Any
+
+# Resolved at startup; exposed via module-level for test inspection.
+_SCHEMA_PATH = os.path.abspath(
+    os.path.join(
+        os.path.dirname(os.path.abspath(__file__)),
+        "..",
+        "..",
+        "..",
+        "knowledge",
+        "schemas",
+        "unified-finding-v1.json",
+    )
+)
+
+# Namespace prefix used when a well-formed category is not in the mapping YAML.
+# This is the ONLY rule_id-shaped literal permitted in this source file;
+# every other rule_id travels in from security-review-rule-map.yaml.
+_FALLBACK_NAMESPACE = "security-review."
+
+_CATEGORY_RE = re.compile(r"^A[0-9]{2}\.[a-z0-9-]+$")
+
+# Default mapping path resolved relative to this file, so the adapter works
+# from any cwd. The repo-relative path is also named in --help for operators.
+_THIS_FILE = os.path.abspath(__file__)
+_ADAPTER_DIR = os.path.dirname(_THIS_FILE)
+# /plugins/dev-team/skills/static-analysis-integration/adapters -> /plugins/dev-team
+_PLUGIN_ROOT = os.path.abspath(os.path.join(_ADAPTER_DIR, "..", "..", ".."))
+_DEFAULT_MAPPING_ABS = os.path.join(
+    _PLUGIN_ROOT, "knowledge", "security-review-rule-map.yaml"
+)
+_DEFAULT_MAPPING_REL = "plugins/dev-team/knowledge/security-review-rule-map.yaml"
+
+# Stdlib-only YAML subset parser (ADR 0014/0015 — no third-party imports in
+# shipped plugins/dev-team/ code); lives at plugins/dev-team/hooks/lib/.
+sys.path.insert(0, os.path.join(_PLUGIN_ROOT, "hooks", "lib"))
+
+
+def _fail_mapping(path: str) -> None:
+    print(f"ERROR: mapping file at {path} is invalid", file=sys.stderr)
+    sys.exit(1)
+
+
+def _load_mapping(path: str) -> dict[str, str]:
+    """Load the YAML mapping. Hard-fails with a specific ERROR on any issue."""
+    from minimal_yaml import YamlError, parse_yaml  # local import; cheap, stdlib-only
+
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            data = parse_yaml(fh.read())
+    except FileNotFoundError:
+        _fail_mapping(path)
+    except YamlError:
+        _fail_mapping(path)
+    if (
+        not isinstance(data, dict)
+        or "mappings" not in data
+        or not isinstance(data.get("mappings"), dict)
+    ):
+        _fail_mapping(path)
+    return {str(k): str(v) for k, v in data["mappings"].items()}
+
+
+def resolve_rule_id(
+    category: str, mapping: dict[str, str], mapping_path: str
+) -> tuple[str, str | None]:
+    """Resolve a category to a rule_id.
+
+    Returns (rule_id, warning_or_none). The caller prints the warning to stderr
+    when it is not None.
+
+    - Malformed category (regex-violating): exits 1.
+    - Well-formed + mapped: upstream rule_id, no warning.
+    - Well-formed + unmapped: security-review.<lowercase> rule_id + WARN.
+    """
+    if not _CATEGORY_RE.fullmatch(category):
+        print(
+            f"ERROR: category {category!r} does not match required format A<NN>.<slug>",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    if category in mapping:
+        return mapping[category], None
+    minted = _FALLBACK_NAMESPACE + category.lower()
+    warning = (
+        f"WARN: category {category} not in mapping at {mapping_path}; minted {minted}"
+    )
+    return minted, warning
+
+
+def _build_finding(issue: dict[str, Any], rule_id: str) -> dict[str, Any]:
+    """Map an agent issue to a unified-finding envelope."""
+    return {
+        "rule_id": rule_id,
+        "file": issue["file"],
+        "line": issue["line"],
+        "severity": issue["severity"],
+        "message": issue["message"],
+        "metadata": {
+            "source": "security-review",
+            "confidence": issue.get("confidence", "none"),
+            "source_ref": issue,
+        },
+    }
+
+
+def _parse_args(argv):
+    parser = argparse.ArgumentParser(
+        prog="security-review-adapter.py",
+        description=(
+            "Normalize security-review agent JSON into unified-finding-v1 JSONL. "
+            f"Default mapping: {_DEFAULT_MAPPING_REL}."
+        ),
+    )
+    parser.add_argument("--input", required=True, help="Agent-output JSON file.")
+    parser.add_argument(
+        "--output",
+        required=True,
+        help="Destination JSONL path (one unified finding per line).",
+    )
+    parser.add_argument(
+        "--mapping",
+        default=_DEFAULT_MAPPING_ABS,
+        help=f"Mapping YAML path. Default: {_DEFAULT_MAPPING_REL}",
+    )
+    return parser.parse_args(argv)
+
+
+def _load_validator():
+    """Load the unified-finding validator once at startup."""
+    try:
+        from jsonschema import Draft202012Validator
+    except ImportError as exc:  # pragma: no cover
+        print(
+            f"ERROR: jsonschema not installed; install with 'pip install jsonschema' ({exc})",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    with open(_SCHEMA_PATH, "r", encoding="utf-8") as fh:
+        schema = json.load(fh)
+    return Draft202012Validator(schema)
+
+
+def main(argv=None) -> int:
+    args = _parse_args(argv)
+    try:
+        with open(args.input, "r", encoding="utf-8") as fh:
+            agent = json.load(fh)
+    except (FileNotFoundError, json.JSONDecodeError) as exc:
+        print(f"ERROR: cannot read agent input {args.input!r}: {exc}", file=sys.stderr)
+        return 1
+
+    mapping = _load_mapping(args.mapping)
+    validator = _load_validator()
+    issues = agent.get("issues", []) or []
+
+    with open(args.output, "w", encoding="utf-8") as out:
+        for issue in issues:
+            if "category" not in issue:
+                print(
+                    "ERROR: agent issue missing required 'category' field; "
+                    "upgrade the agent output",
+                    file=sys.stderr,
+                )
+                return 1
+            rule_id, warning = resolve_rule_id(issue["category"], mapping, args.mapping)
+            if warning:
+                print(warning, file=sys.stderr)
+            finding = _build_finding(issue, rule_id)
+            errors = list(validator.iter_errors(finding))
+            if errors:
+                detail = "; ".join(
+                    f"{'.'.join(str(p) for p in e.path) or '<root>'}: {e.message}"
+                    for e in errors
+                )
+                print(
+                    "ERROR: emitted finding violates unified-finding-v1 schema "
+                    f"({detail})",
+                    file=sys.stderr,
+                )
+                return 1
+            out.write(json.dumps(finding, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/static-analysis-integration/maintenance.md

@@ -0,0 +1,23 @@
+# Static Analysis Integration — Maintenance Policies
+
+These policies cover the lifecycle of adapters and rulesets shipped with this skill. They are read by maintainers, not by agents at runtime — the runtime skill is in `SKILL.md`.
+
+## Adapter Maintenance Policy
+
+Adapters (SARIF wrappers, bespoke JSON adapters) have a lifecycle independent of the tools they wrap.
+
+- **Owners**: the skill's `maintainers:` frontmatter list. Minimum 2 names.
+- **Update trigger**: a tier-2 CI job (nightly) runs each adapter against the installed tool binary. Schema drift that breaks the adapter fails CI and opens an auto-issue tagged `adapter-drift`.
+- **Escalation**: a tier-2 failure unassigned for > 14 days escalates to CODEOWNERS.
+- **Deprecation**: an adapter failing CI for three consecutive releases AND upstream unmaintained for > 6 months is demoted to "deprecated" — still shipped, emits a warning on invocation, removed in the next MAJOR contract version.
+- **Adding a tool**: requires (a) a fixture pair under `evals/static-analysis-tools/tier1-mocks/<tool>/` (mock output + expected unified finding), and (b) a SARIF adapter first; bespoke-JSON only if upstream genuinely has no SARIF plan.
+
+## Ruleset Maintenance Policy
+
+Separate lifecycle from adapters — rulesets track evolving attack patterns, not tool schema drift.
+
+- **Owners**: each custom ruleset (`knowledge/semgrep-rules/*.yaml`) has a `maintainers:` frontmatter block with ≥ 2 names.
+- **Review cadence**: quarterly. Reviewers confirm patterns are still relevant, add new attack signatures, retire deprecated ones.
+- **FP drift threshold**: if eval fixtures show > 20% false-positive noise on the tier-2 suite, the ruleset is paused and triaged within one release.
+- **Community-PR intake**: PRs adding patterns require a positive fixture plus a negative fixture. Rejections must cite the policy.
+- **Deprecation**: a ruleset with no review or change in two consecutive review cycles is demoted to "archived" unless a maintainer re-ups.

package/skills/static-analysis-integration/references/language-setup.md

@@ -0,0 +1,228 @@
+# Per-language static-analysis setup
+
+User-facing configuration guide for the static-analysis integration: the
+build-time self-heal pass that runs at `/build`'s review checkpoints and the
+`/code-review` static pre-pass. One section per registered lane, below. This
+guide is the single source of truth for the manual setup commands; the
+registry of what runs (and how) lives in [`tool-configs.md`](tool-configs.md)
+§ Build-time lanes.
+
+## Opting out
+
+Set `DEV_TEAM_STATIC_SELF_HEAL=off` to skip the entire build-time static
+self-heal pass — no tool probe or invocation occurs, one info line notes the
+skip, and review checkpoints proceed straight to semantic review. Any other
+value (or unset) leaves the pass enabled. This mirrors the
+`DEV_TEAM_REVIEW_VALUE=off` convention and does not affect `/code-review`'s
+full-repo static pre-pass.
+
+## Per-lane section contract
+
+Each language section below is added by the issue that registers its lane
+and covers, in order:
+
+1. **Tools and roles** — which tools the lane uses and what each does
+   (autofix-capable vs diagnostic-only).
+2. **Repo-level install** — how to install them as project-local,
+   versioned-with-the-repo dependencies, never user-level/global, so the
+   toolchain is reproducible for every contributor and CI.
+3. **Configuration** — which config files the tools honor.
+4. **Verification** — the lane's detection probe commands, to confirm the
+   setup is detected.
+5. **Opt-out** — the `DEV_TEAM_STATIC_SELF_HEAL=off` toggle above.
+6. **Recognized equivalent providers** — the slot's ordered provider list
+   and each provider's qualification status.
+
+Each section also carries a one-line pointer to `/project-init` as the
+one-command path to the same repo-level install; this guide remains the
+source of truth for the manual commands.
+
+## Python
+
+1. **Tools and roles** — **Ruff** (autofix-capable): lint plus mechanical
+   fixes; runs the lane's pre-fix (`ruff check --fix`) and verify
+   (`ruff check`). **mypy** (diagnostic-only): type checking; it has no
+   autofix — its findings are handed to the coding agent.
+2. **Repo-level install** — add both to the project's own dev-dependency
+   mechanism so the toolchain is versioned with the repo and reproducible
+   for every contributor and CI: `requirements-dev.txt`, a `pyproject.toml`
+   dev dependency group, or `python3 -m pip install ruff mypy` inside the
+   project venv. Never `pip install --user` or a global pipx install.
+3. **Configuration** — Ruff honors the project's `ruff.toml`/`pyproject.toml`
+   when present (Ruff's default config discovery — no override flags) and
+   falls back to Ruff's defaults; the plugin pins no curated rule set — the
+   project owns its quality bar. mypy honors `mypy.ini`/`pyproject.toml`
+   (`[tool.mypy]`). A plain `src/`-layout project (modules with no
+   `__init__.py`, no mypy package-base config) needs no manual setup
+   either — both mypy invocations auto-detect the layout and add
+   `--explicit-package-bases` for you; see the mypy Tier 3 entry in
+   `tool-configs.md`.
+4. **Verification** — the lane's detection probes are `command -v ruff` and
+   `command -v mypy`; run them (with the project venv active) to confirm
+   the setup will be detected.
+5. **Opt-out** — `DEV_TEAM_STATIC_SELF_HEAL=off` skips the build-time
+   static self-heal pass entirely (see [Opting out](#opting-out)).
+6. **Recognized equivalent providers** — autofix slot: ruff (default,
+   last-resort) → black + flake8, qualified only as a combined pair (black
+   is the format-autofix half, flake8 the lint-diagnostic half — a partial
+   mapping, not 1:1 with ruff's rule surface). Diagnostic slot: mypy
+   (default, last-resort) → pyright, gated: recognition requires a ≤ 40 LOC
+   Tier 3 adapter in `static-analysis-integration`, which does not exist
+   yet. A project arriving with black + flake8 (or pyright) present and
+   configured gets them bound; ruff/mypy are installed only into slots that
+   bind no recognized provider.
+
+Run `/project-init` for the one-command path to the same repo-level
+install; the commands above remain the source of truth for manual setup.
+
+## JS/TS
+
+1. **Tools and roles** — **oxlint** (pin >= 1.0.0; Rust-based,
+   ESLint-compatible) is the lane's autofix-capable tool: the mechanical
+   pre-fix (`npx oxlint --fix`) covers a subset of its rules — partial
+   autofix; findings it cannot fix are reported fast and handed to the coding
+   agent — and the verify pass runs oxlint in check mode. **ESLint** is the
+   optional deep pass for framework-plugin rules oxlint lacks; it is not part
+   of the fast per-step loop (see the provider list below for how an
+   ESLint-configured project binds).
+2. **Repo-level install**:
+
+   ```bash
+   npm install --save-dev oxlint
+   ```
+
+   A devDependency pins the oxlint version in `package.json`/the lockfile —
+   versioned with the repo and reproducible for every contributor and CI.
+   Never `npm install -g oxlint`. One-command alternative: run
+   `/project-init` — for a new project its greenfield scaffold installs
+   oxlint and wires it as the default linter; for an existing repo it
+   installs oxlint only when the slot binds no provider.
+3. **Configuration** — oxlint honors `.oxlintrc.json` (ESLint-v8-compatible
+   shape; oxlint runs with sensible defaults when no config exists). When
+   ESLint coexists as the deep pass, add
+   [`eslint-plugin-oxlint`](https://github.com/oxc-project/eslint-plugin-oxlint)
+   to the ESLint config to turn off rules oxlint already covers, so the
+   ESLint pass only pays for the plugin-only remainder.
+4. **Verification**:
+
+   ```bash
+   npx --no-install oxlint --version
+   ```
+
+   Prints the pinned version when the lane's probe will detect oxlint (the
+   probe resolves the project-local `node_modules/.bin` first). Projects
+   bound to another provider verify the same way:
+   `npx --no-install biome --version` / `npx --no-install eslint --version`.
+5. **Opt-out** — `DEV_TEAM_STATIC_SELF_HEAL=off` skips the build-time pass
+   (see [Opting out](#opting-out)).
+6. **Recognized equivalent providers** (autofix slot; provider semantics live
+   in the build skill's `static-self-heal.md`):
+   - **oxlint** — default and last-resort provider; full-speed.
+   - **biome** — full-speed provider (fast, machine-readable).
+   - **eslint** — bound with demotion to slice-boundary granularity only
+     (fails the per-step latency budget), with one info line telling the
+     user the fast default (oxlint) exists.
+
+## C#
+
+The C# lane rides the .NET SDK — there is no separate linter binary to
+install or configure.
+
+1. **Tools and roles**
+   - `dotnet format` — autofix-capable: Roslyn-analyzer-driven whitespace,
+     style, and analyzer code-fixes. The build-time lane's mechanical
+     pre-fix (`whitespace` + `style` at every checkpoint; `analyzers` at the
+     slice boundary).
+   - Roslyn **ErrorLog SARIF** — diagnostic-only: native SARIF exported by
+     the `dotnet build` the TDD loop already runs when passed
+     `/p:ErrorLog=results.sarif,version=2.1`. Also the lane's Tier 1
+     `/code-review` source.
+2. **Repo-level install** — nothing to install: both pieces ship with the
+   .NET SDK the project already requires (SDK ≥ 6 for built-in
+   `dotnet format`; .NET 5 SDK / Roslyn 3.8+ for the SARIF v2.1 export).
+   Where the SDK version matters, pin it repo-level with `global.json`
+   (`dotnet new globaljson --sdk-version <version>`) — never a
+   user-level/global toolchain assumption. `/project-init` is the
+   one-command path: it verifies SDK presence and honors an existing
+   `global.json` pin.
+3. **Configuration** — the tools honor the project's `.editorconfig`;
+   `dotnet format` runs against it at its default `--severity warn`.
+   Third-party Roslyn analyzers (StyleCop.Analyzers, SonarAnalyzer.CSharp,
+   …) are added as `PackageReference`s in the `.csproj` and automatically
+   ride the same ErrorLog SARIF.
+4. **Verification** — the lane's detection probe is `command -v dotnet`
+   (one SDK probe covers both tools). Confirm the pieces work:
+
+   ```bash
+   command -v dotnet
+   dotnet format --version
+   dotnet build /p:ErrorLog=results.sarif,version=2.1   # writes results.sarif
+   ```
+
+5. **Opt-out** — set `DEV_TEAM_STATIC_SELF_HEAL=off` to skip the build-time
+   self-heal pass entirely (see [Opting out](#opting-out) above).
+6. **Recognized equivalent providers** — none. `dotnet format` is
+   SDK-builtin, and analyzer alternatives join via the `.csproj`, not via
+   lane providers.
+
+## Java
+
+Registered by #810.
+
+### Tools and roles
+
+- **PMD** — **diagnostic-only** (no autofix tool exists for a tight
+  per-step loop in Java). Syntax-tree based, so it needs no compile step:
+  fast enough for build-time checkpoints, and its native SARIF renderer
+  makes it a zero-adapter `/code-review` source. Findings go to the coding
+  agent to fix; PMD re-runs to confirm convergence.
+
+### Repo-level install
+
+From your project root (requires a JDK/JRE — `java` on PATH):
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/install-java-static-analysis.py"
+```
+
+Installs a pinned PMD distribution into the repo-local **`.pmd/`**
+directory (`PMD_INSTALL_DIR` overrides the target). Add `.pmd/` to your
+project's `.gitignore` — the distribution is large and must never be
+committed; the installer prints a reminder when the entry is missing. No
+PATH change is needed, and never install user-level/global. Re-running is
+idempotent: an existing install is detected and nothing is re-downloaded.
+
+Or run `/project-init` — the one-command path to the same repo-level
+install.
+
+### Configuration
+
+- **Repo-root `pmd-ruleset.xml`**, when present, is used by both the
+  build-time lane and the `/code-review` pass. Carry your own
+  `<exclude-pattern>` entries in it (generated-output dirs like `target/`).
+- Otherwise the plugin's quickstart-wrapping default ruleset applies —
+  PMD's quickstart rules plus excludes for `target/`, `build/`, `out/`,
+  and `.gradle/`. Test sources run the same rules as production code.
+
+### Verification
+
+Confirm the setup is detected (repo-local probe first, then PATH):
+
+```bash
+ls .pmd/pmd-bin-*/bin/pmd     # repo-local launcher (checked first)
+command -v pmd                # PATH fallback
+.pmd/pmd-bin-*/bin/pmd --version
+```
+
+### Opt-out
+
+Set `DEV_TEAM_STATIC_SELF_HEAL=off` to skip the build-time pass entirely —
+see [Opting out](#opting-out).
+
+### Recognized equivalent providers
+
+Diagnostic slot, in order: **PMD** (default, last-resort) → **checkstyle**.
+checkstyle qualifies as Tier 1 via native SARIF output (Checkstyle ≥ 10.3,
+no adapter); a project arriving with a repo-root `checkstyle.xml` binds it
+and PMD is not installed. SpotBugs is not a provider candidate — it needs
+compiled bytecode and belongs at the end-of-build `/code-review` pass only.

package/skills/static-analysis-integration/references/sarif-parser.md

@@ -0,0 +1,124 @@
+# SARIF → Unified Finding Parser
+
+Shared normalization layer for every SARIF-emitting tool in the static-analysis pre-pass. Reads a SARIF document, walks `runs[*].results[*]`, and emits unified-finding-v1 objects that validate against `plugins/dev-team/knowledge/schemas/unified-finding-v1.json`.
+
+## Field mapping
+
+### Required fields
+
+| Unified finding field | SARIF source | Transform |
+|---|---|---|
+| `rule_id` | `runs[r].tool.driver.name` + `results[i].ruleId` | Format: `<driver_name_kebab>.<middle>.<ruleId_kebab>` — see **Rule id prefix conventions** below for what fills the middle segment |
+| `file` | `results[i].locations[0].physicalLocation.artifactLocation.uri` | Strip `file://` prefix; resolve `uriBaseId` if present; ensure repo-relative POSIX path |
+| `line` | `results[i].locations[0].physicalLocation.region.startLine` | Integer, 1-indexed |
+| `severity` | `results[i].level` | Map: `error`→`error`, `warning`→`warning`, `note`→`suggestion`, `none` or absent→`info` |
+| `message` | `results[i].message.text` | Truncate at 500 chars |
+| `metadata.source` | `runs[r].tool.driver.name` | Lowercase; e.g. `"Semgrep"`→`"semgrep"` |
+| `metadata.confidence` | `results[i].properties.confidence` | Default: `medium` |
+
+### Optional fields
+
+| Unified finding field | SARIF source | Notes |
+|---|---|---|
+| `column` | `results[i].locations[0].physicalLocation.region.startColumn` | Omit if absent |
+| `end_line` | `results[i].locations[0].physicalLocation.region.endLine` | Omit if absent |
+| `end_column` | `results[i].locations[0].physicalLocation.region.endColumn` | Omit if absent |
+| `cwe[]` | `runs[r].tool.driver.rules[ruleIndex].properties.cwe` | Wrap as `["CWE-N"]`; accept int or string |
+| `cve[]` | `results[i].properties.cve` or rule `properties.cve` | Validate `CVE-YYYY-N` shape |
+| `owasp[]` | `runs[r].tool.driver.rules[ruleIndex].properties.owasp` | Passthrough |
+| `metadata.source_ref` | `results[i]` (the raw object) | Opaque pointer for debugging only; shape is NOT contract-stable |
+| `metadata.exploitability` | `results[i].properties.exploitability` | Map to `demonstrated|plausible|theoretical|unknown`; default `unknown` if absent |
+
+## Rule id prefix conventions
+
+Every unified rule_id follows the schema pattern `^[a-z0-9_-]+(\.[a-z0-9_-]+)+$` — at least two dot-separated segments. The parser applies the rules below depending on the shape of the raw SARIF ruleId.
+
+The middle segment comes from the raw ruleId's own structure, its plugin, or the tool → tier map — **never** from `results[i].properties.language`. An earlier version of the field table above named that property as the source; no implementation ever read it, and the tier map is what every fixture and both consumers actually exercise.
+
+**Raw ruleId contains dots (semgrep-style):** preserve the structure. Each segment is kebab-cased independently.
+
+```
+raw: python.django.audit.sql-injection
+out: semgrep.python.django.audit.sql-injection
+```
+
+**Raw ruleId is `plugin(rule)`-shaped (oxlint):** the plugin becomes the tier segment, so the namespace survives.
+
+```
+raw: jsx-a11y(alt-text)        out: oxlint.jsx-a11y.alt-text
+raw: eslint(no-magic-numbers)  out: oxlint.eslint.no-magic-numbers
+raw: react-perf(jsx-no-new-object-as-prop)
+                               out: oxlint.react-perf.jsx-no-new-object-as-prop
+```
+
+This branch is checked **before** the dotted and flat cases. Without it the
+parentheses are hyphen-flattened by `kebab()` into a single segment
+(`oxlint.js.jsx-a11y-alt-text`) — schema-valid, but it erases the boundary
+that lets a consumer tell an accessibility finding from a performance one,
+which is exactly what #1979's two oxlint concerns need. A malformed shape
+(empty half, nested parentheses) falls through to the rules below rather than
+producing a partial id.
+
+**Raw ruleId is flat:** the parser inserts a capability-tier segment from its tool → tier map.
+
+| Tool driver | Tier segment |
+|---|---|
+| semgrep | `sast` (rarely used — semgrep rules usually have dots) |
+| gitleaks | `secrets` |
+| trivy | `iac` for config findings; `cve` for CVE findings; `supply-chain` for vuln findings |
+| hadolint | `dockerfile` |
+| actionlint | `workflows` |
+| ruff | `python` |
+| oxlint | `js` (fallback only — a `plugin(rule)` id uses its plugin instead) |
+| entropy-check | `secrets` (custom script — passphrase entropy + cross-env reuse) |
+| model-hash-verify | `ml` (custom script — ML model integrity + provenance) |
+
+`ruff` and `oxlint` were absent from this map until #1979, so every finding
+from the two language linters was emitted under the `generic` fallback,
+contradicting the ids their own entries in `tool-configs.md` advertise.
+
+**Degenerate inputs still produce a valid id.** Two rules keep the output
+inside the schema pattern no matter what a driver reports, because a rule id
+that fails validation costs the whole finding — file, line, and message
+included — even when those are perfectly usable:
+
+- The **driver name is kebab-cased** into the first segment, so a tool
+  identifying itself as `Semgrep OSS` yields `semgrep-oss.…` rather than
+  embedding a space. A no-op for every tool wired up today.
+- A **rule id that kebabs to nothing** (empty string, punctuation only, a
+  non-Latin script) becomes the literal segment `unknown` rather than an
+  empty trailing segment: `oxlint.js.unknown`, never `oxlint.js.`.
+
+```
+raw: aws-access-key        out: gitleaks.secrets.aws-access-key
+raw: DS002                 out: trivy.iac.ds002
+raw: CVE-2024-1234         out: trivy.cve.cve-2024-1234
+raw: DL3008                out: hadolint.dockerfile.dl3008
+raw: shellcheck            out: actionlint.workflows.shellcheck
+```
+
+**Kebab-casing rule:** `[^a-z0-9]+` is replaced with a single hyphen, the string is lowercased, and leading/trailing hyphens are stripped.
+
+## Error handling
+
+- A SARIF document missing `runs` or `runs[*].tool.driver.name` is an adapter bug; the parser fails the run with a named-tool error.
+- A `result` missing `ruleId` OR `locations` OR `message.text` is discarded with a one-line log entry (`DROPPED: <tool> result missing required SARIF field(s)`). The rest of the run continues.
+- A mapped finding that fails unified-finding-v1 schema validation fails the whole run (not silently discarded) — adapter bug.
+
+## Non-goals
+
+- Does not convert SARIF fingerprint / taint-flow data into finding fields. Those remain in `metadata.source_ref` for tools that care.
+- Does not enrich findings with exploitability, reachability, or CWE mappings beyond what SARIF carries. Those are downstream concerns (FP-reduction, compliance-mapping).
+- Does not canonicalize file paths beyond stripping `file://` and applying `uriBaseId`. Path normalization (symlink resolution, case-folding) is the caller's responsibility.
+
+## Tests
+
+Fixtures under `evals/static-analysis-tools/tier1-mocks/<tool>/` contain a pair of files per tool:
+
+```
+<tool>/
+  mock.sarif           # raw SARIF output from the tool (captured or synthesized)
+  expected-findings.json  # array of unified findings the parser should emit
+```
+
+The validator script at `evals/static-analysis-tools/validate.py` iterates every fixture pair, parses `mock.sarif` through the shared parser, and asserts the output equals `expected-findings.json` and validates against the unified-finding-v1 schema.