feat: classify finding severity with custom rubrics

[kmbroai]

Summary

Let CLI and SDK users classify existing findings under a custom severity rubric and resume interrupted classification without repeating successful model calls. Each successful finding is checkpointed in SQLite before the next finding starts. Omitting a rubric inherits the original severity without a model call.

Changes

• Add codex-security classify-severity with exactly one of --scan ID (including unique prefixes and latest) or --scan-dir PATH, optional --rubric PATH, repeatable --knowledge-base PATH and --finding-id ID, and existing model/effort controls.
• Add --reprocess (default false) and SDK reprocess: true to bypass matching checkpoints for the selected findings. Normal runs reuse assessments only when evidence, rubric, and context hashes match. Exclusions are reusable assessments with null severity.
• Export the in-memory classifySeverity primitive and the database-backed classifyScanSeverity and classifyScanDirectorySeverity wrappers. Each rubric evaluation uses the supplied report/context in a separate read-only Codex turn without tools or source inspection.
• Add migration 41: finding_severity_assessments stores the latest assessment per finding ID, and scan_severity_classifications stores each scan's requested selection and policy/context hashes. Save each successful row independently; a failed reassessment retains that finding's previous row. Preserve original findings and sealed artifacts.
• Make SQLite authoritative for scan assessment reuse and Linear publication. Export the complete selected result to severity-classification.json after a successful run. Publication rejects incomplete or stale selections, omits exclusions, and uses assessed severity for ticket priority/title. SDK callers can still supply an assessment explicitly.
• Add repeatable publish scan --to linear --finding-id ID for direct selection while retaining full sealed-scan membership checks. Update help, SDK types, documentation, package fixtures, and bundled-file contracts.

Testing

• Focused classification, CLI, publication, and real SQLite integration tests: 86 passed, 0 failed. Coverage includes interruption/resume, cached exclusions, selected reassessment, input invalidation, immutable evidence, JSON export behavior, and migration/read-only compatibility.
• Full SDK suites: 2,324 passed, 41 skipped, 0 failed in each run (seed 12345 and randomized seed 1812793090).
• pnpm run types and pnpm run format: passed.
• pnpm pack and pnpm run check:package -- <tarball>: passed. Validated 411 archive entries, installed exports and strict NodeNext consumer types, CLI/SDK lifecycle, credential locking, plugin/MCP startup, and nested worker startup.
• Full Python source contract suite: 1,094 passed, 9 skipped, 103 subtests passed. Ran with the inherited Python safe-path override unset and temporary fixtures outside an existing parent Git marker.
• Plugin source Ruff lint, Ruff formatting, and portable source compatibility checks: passed.
• Installed CLI with a synthetic 12-finding scan: live classification persisted incremental rows; a cached rerun succeeded with a deliberately unavailable model and left all assessment rows unchanged; reprocessing one selected finding changed only that row. The full selection was restored from cached results.
• Built classify-severity --help and git diff --check: passed.

Risk and rollout

This adds public CLI/SDK surface and an additive local database migration. Classification of external scan directories also uses the configured local state database. Existing JSON-only assessments require one classification run to populate checkpoints; the JSON export is no longer read as an authoritative assessment. Classification and publication must use the same state directory.

Reprocessing replaces successful rows individually and retains rows outside the selected set. There is no assessment history or whole-scan rollback. Changing only the model or effort requires --reprocess. Standalone classifySeverity remains an in-memory operation. Original scan severity and existing Linear tickets are unchanged; --skip-existing retains its current behavior.

Public disclosure review

• No customer, partner, prospect, or user identities, data, or identifying details are included.
• No credentials, personal data, private source, scan findings, or nonpublic links or tickets are included.
• I reviewed the branch name, title, description, commits, changes, comments, logs, screenshots, attachments, and links for public disclosure.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-09-03T03:35:12.665565Z	5b09508	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[sylvesterkaczmarek]

finding_severity_assessments is keyed only by stable finding_id, but findings are intentionally global across scans and finding_occurrences carries the scan-specific occurrence. If the same finding appears in scans A and B, classifying B overwrites A's row (including occurrence_id/input_sha256). Publishing A then sees B's assessment and fails validation; reclassifying A in turn breaks B. Could the checkpoint key be scan/occurrence-scoped (for example (scan_id, finding_id) or occurrence_id) and add a two-scan same-finding regression?