necropsy 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc6a4c3ecf1f46c6950e6cb91e522d6162e41b1bc1b8e8b2aaa96a75b1ccb575
-  data.tar.gz: b77ffd85970bf4445c287cce8e3727c3e8ba675314ecfc5b9ce5cc8df73cbdf9
+  metadata.gz: c6859ea7acfe1f2357759a87f5f2f2f2b1b487447d34f61d6778164c8362dc6e
+  data.tar.gz: 39f91eb66de04a292f749ba37fc2a9b4ba333ec799c1671716068f9d315f6d96
 SHA512:
-  metadata.gz: 6c86a65179785984b75bf39de3843ae5a2759b1e6c327ec7d9f6cbb88f961b0dfaa4944af69bd4aa602e0d27ac23accc69f62d344b55bd258779271047fd72fb
-  data.tar.gz: a91136e79e7056cc81c816be84b28b77598efc525e28304b530484282b045a5a8c463b0276dbfc487f5db0ee7fdf3c14aa137ed8c542cd94781e90794bb9e18e
+  metadata.gz: d7a3f31943091c4e9288d4705e65779f5165ad251fe8f440f3361f1ec1f675035b4d83f6425fbdb6b5b0e88ab1240800bf621d3bc78ad6e624f6c3e6e7eaca96
+  data.tar.gz: f1fa13456a999bb6897f938776dc3884197f01ffafdcab19ba416a6d41727980cb03906a5280cb48a60d245f50f714c61e12adb950134ee06ca71c202e417a55

data/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to Necropsy are documented in this file.
 
 ## Unreleased
 
+No unreleased changes.
+
+## 0.3.0 - 2026-08-13
+
+- Preserve repeated and reopened Ruby definitions as distinct physical graph nodes while retaining logical method names for compatibility; ambiguous runtime references no longer silently select one definition.
+- Record structured call-site resolution, scoped blockers, evidence grades, and analyzer provenance, with conservative adaptation for existing custom static analyzers.
+- Store graph evidence once and expose exact, conservative, and scope-filtered observed views while preserving conservative reachability and the existing nested edge JSON.
+- Separate runtime, test, and external roots; library mode now protects public and protected APIs from dead-code findings, with optional conservative roots for every production file.
+- Separate analysis, repository reference, and report scopes so output filters cannot remove callers from the graph; reference-only Ruby definitions are not reported, and narrowed scans expose entry-point and symlink diagnostics.
+- Block candidates that still appear in unparsed templates or configuration, with bounded file/line/snippet diagnostics and safe limits for common names, generated content, binary files, and oversized inputs.
+- Add `why-not` human and versioned JSON diagnostics covering physical definitions, examined calls and resolutions, blockers, world policy, external text matches, analysis failures, enabled rules, and suggested evidence.
+- Write physical-definition baseline schema v2 while continuing to read logical v1 baselines; CI now stops for an explicit review when a legacy entry maps to multiple definitions.
+- Expose legacy and physical fingerprints additively in JSON and SARIF, and show both logical-symbol and physical-definition candidate views in benchmark output.
+- Fail closed on analyzer, parser, source-revision, reference-scan, and unsafe RTA failures; expose explicit health status, strict-health policy, machine-readable failure reports, and graph self-checks.
+- Harden Ruby semantic traversal and finite value flow for modifier definitions, default arguments, dynamic sends, short-circuit paths, unsupported control flow, reflective hooks, and receiver-aware core protocol calls.
+- Add conservative Rails and framework conventions for generated methods, associations, enums, scopes, callbacks, ActionCable, ActiveJob, Sidekiq, GraphQL, serializers, ViewComponent, routes, ERB, inflections, and structural dependency detection.
+- Add bounded and deterministic external-reference scanning with qualified-owner matching, streaming limits, byte/match/time budgets, unsafe-skip blockers, and safe repository discovery.
+- Add deterministic NDJSON graph export, content-addressed cache metadata, reproducible runtime artifacts, performance distributions, macro-averaged evaluation, AST fuzzing, runtime target oracles, mutation safety harnesses, and a generated semantics matrix.
+
+## 0.2.1 - 2026-08-04
+
+- Prevent unsafe dead-code recommendations when runtime dispatch, source parsing, or an analyzer is incomplete; affected methods are now reported as low-confidence `blocked` findings with the reason and source location.
+- Make the default analysis conservative: RTA no longer deletes broader static edges, runtime observations only prove liveness, and quarantine expiry requests review without increasing deadness confidence.
+- Harden remote Coverband/Redis evidence loading with verified TLS, bounded DNS/connect/read/write/total deadlines, strict payload and RESP limits, safe deserialization, and credential-redacted errors.
+- Add reproducible five-corpus release auditing with reviewed candidate transitions, safety-invariant and adversarial suites, provenance-bound artifacts, and fail-closed wall-time/RSS budgets.
+
 ## 0.2.0 - 2026-08-03
 
 - **Breaking:** Reports now omit `low` confidence findings by default, substantially reducing noisy output. Pass `--min-confidence low` to retain the previous output.

data/MEASUREMENTS.md

@@ -2,6 +2,33 @@
 
 Measurements are local wall-clock results. Compare runs made on the same machine and Ruby version; absolute timings are not portable.
 
+The reproducible seed under `bench/corpora/v1` supersedes ad hoc commands for new comparisons.
+`bundle exec ruby bench/run.rb` regenerates normalized findings, candidate-union results, corpus
+summaries, wall time, and RSS measurements in one pass. RuboCop remains pinned to 1.75.0 and is
+enabled by setting `NECROPSY_RUBOCOP_CORPUS`; an unavailable checkout is reported as a skip.
+
+## 0.2.1 safety release audit
+
+The versioned audit compares commit `51d490188ae9ad846b4c023f14e252ec624a2d5e`, the first
+integrity-bound five-corpus snapshot, with `3831ce651ed331426413a767824955414529001d` on the same
+Ruby 4.0.0/macOS arm64 environment. RSS is the benchmark process's current resident size after each
+corpus, not a per-corpus isolated peak. Full provenance and candidate-level changes are stored in
+`bench/audits/0.2.1/audit.json`.
+
+| corpus | findings baseline/current | state changes | newly high | wall s baseline/current | RSS KiB baseline/current |
+|---|---:|---:|---:|---:|---:|
+| dynamic evidence | 4 / 4 | 0 | 0 | 0.001 / 0.003 | 52,720 / 51,200 |
+| plain Ruby | 3 / 3 | 0 | 0 | 0.002 / 0.002 | 53,088 / 51,488 |
+| Rails fixture | 4 / 4 | 0 | 0 | 0.004 / 0.004 | 54,272 / 52,656 |
+| RuboCop 1.75.0 | 5,797 / 5,797 | 119 | 0 | 5.196 / 5.281 | 576,256 / 584,432 |
+| self | 78 / 50 | 2 | 0 | 0.217 / 0.423 | 608,448 / 580,480 |
+
+All seven release gates passed. Rails had no candidate changes. RuboCop retained the same candidate
+count; its 119 state changes were conservative transitions to `blocked`, with all nine deterministic
+stratified review samples accepted. The dynamic, parse, ambiguity, and remote-input adversarial
+suites passed 69 examples in total. No new high-confidence candidate or confirmed reviewed false
+positive was introduced.
+
 | date | commit | target | nodes | findings | ratio | seconds |
 |---|---|---|---:|---:|---:|---:|
 | 2026-08-01 | baseline | necropsy | 678 | 246 | 36.3% | 4.33 |

data/README.md

@@ -5,12 +5,15 @@ collects method definitions with Prism, adds call-edge evidence from static and
 optional dynamic analyzers, then runs reachability from framework and configured
 entry points.
 
+Machine-readable JSON reports use schema v2. The published contract is
+[`schema/necropsy-report-v2.schema.json`](schema/necropsy-report-v2.schema.json).
+
 Necropsy includes:
 
 - Prism-based method collection for ordinary, singleton, delegated, aliased, forwarded, and dynamically defined methods
-- static name resolution, CHA, and RTA-style filtering over instantiated classes
+- static name resolution and CHA, with rank-only RTA hints from classes instantiated in the scanned program
 - Prism-backed Rails route parsing plus callback, view, component, migration, plain Ruby, and test-suite entry points
-- `unreachable`, `unused`, and `test_only_reachable` classifications
+- `unreachable`, `unused`, `blocked`, and `test_only_reachable` classifications
 - confidence levels, compact JSON/YAML reports, SARIF/GitHub output, CI guardrails, dynamic collectors, and benchmarking
 
 ## Installation
@@ -29,6 +32,11 @@ Create a baseline:
 bundle exec necropsy baseline --root .
 ```
 
+New baselines use schema v2 and identify each physical method definition. Existing
+schema v1 baselines remain readable, but `necropsy check` accepts only exact physical
+matches. Run `necropsy baseline migrate` to use body/symbol/path hints and produce a
+review report; ambiguous or legacy matches never pass an ordinary check silently.
+
 Run a report:
 
 ```bash
@@ -46,11 +54,35 @@ nearby alive node, and unresolved dispatch notes:
 ```bash
 bundle exec necropsy why 'MyService#call' --root .
 bundle exec necropsy why 'MyService#call' --root . --format json
+bundle exec necropsy why-not 'LegacyService#unused' --root .
+bundle exec necropsy why-not 'LegacyService#unused' --root . --format json
 bundle exec necropsy explain 'LegacyService#unused' --root .
 ```
 
 `explain` shows every confidence score component and the final confidence
-level. Missing symbol IDs return partial-match suggestions.
+level. `why-not` emits a refutable `necropsy.why-not.v1` artifact for candidates,
+blocked findings, and test-only definitions. It includes examined call sites and
+resolution statuses, rejected targets, blockers, world/root policy, non-Ruby
+matches, parse/analyzer failures, enabled analyzers and type providers, artifact
+digests, assumptions, risk flags, the recommended review action, and the next
+evidence to collect. Every diagnostic collection reports total, returned, and
+truncated counts, and nested metadata is bounded as well. Missing IDs return
+partial-match suggestions. When a logical symbol ID matches multiple physical
+definitions, all three diagnostic commands list every source location and an
+executable command using its full definition ID.
+
+For compatibility, the existing logical `id` and `fingerprint` remain stable.
+Reports add `logical_fingerprint` and `physical_fingerprint`, while SARIF retains
+the `necropsy` partial fingerprint and adds `necropsyPhysicalDefinition`. Reports
+also include `symbol_id` and `definition_id`; human, GitHub, and SARIF findings
+display or expose the full physical definition ID so reopened or duplicate methods
+can be distinguished.
+
+Runtime artifacts remain backward compatible: collectors keep the legacy
+`nodes` and `edges` fields while adding structured `node_references` and edge
+endpoint references with `definition_id`, `symbol_id`, `file`, and `line` when
+available. Importers prefer structured references and continue to accept v1
+logical-ID artifacts.
 
 Fail CI only for new high-confidence findings:
 
@@ -58,6 +90,12 @@ Fail CI only for new high-confidence findings:
 bundle exec necropsy check --root . --fail-on high
 ```
 
+`check`, baseline writes, quarantine writes, and release benchmarks fail with status
+3 when analysis health is incomplete. Use `--strict-health` to apply the same policy
+to informational analysis/diagnostic commands. A known degraded reason can be
+temporarily admitted by exact code, for example
+`--allow-degraded=reference_scan_incomplete`; invalid health is never admitted.
+
 Record dynamic evidence from a Ruby script:
 
 ```bash
@@ -80,12 +118,42 @@ Evaluate against a gold standard:
 bundle exec necropsy bench --root . --gold-standard gold.yml --ablation
 ```
 
+Benchmark JSON keeps the existing logical-ID metrics and adds `identity_views`.
+The legacy view groups by `symbol_id`; the physical view lists every
+`definition_id` and both fingerprints, so duplicate definitions cannot disappear
+from review totals.
+
+Benchmark precision is measured from actionable `unreachable`/`unused` findings only.
+`blocked` and `test_only_reachable` remain visible diagnostics but are not removal candidates.
+The additive `quality` and `by_category` objects report candidate precision/count/LOC,
+known-positive recall, blocked and unknown rates, and rule/risk counts. A run with zero
+candidates fails the evaluator's `candidate_yield` release check instead of receiving perfect
+precision. The legacy `Report#dead_methods` API is unchanged; integrations that need the stricter
+set can use `Report#actionable_candidates`.
+
+Non-analyzer features can be compared with the same evaluator by supplying already analyzed
+on/off reports. This keeps feature configuration outside the metric engine while producing a
+physical-definition candidate diff and metric deltas:
+
+```ruby
+Necropsy::Bench::Evaluator.new(
+  report: feature_on_report,
+  gold_standard_path: 'gold.yml',
+  feature_ablation: {
+    'receiver_flow' => { on: feature_on_report, off: feature_off_report }
+  }
+).call
+```
+
 JSON and YAML omit the full call graph by default. Add `--include-graph` when
 nodes, edges, evidence, and entry points are needed in machine-readable output.
 
 Example configuration:
 
 ```yaml
+analysis:
+  world: application # application | library
+  load_roots: known # known | all
 analyzers:
   static: [name_resolution, cha, rta]
   dynamic:
@@ -93,12 +161,24 @@ analyzers:
       source: tmp/necropsy_coverage.yml
       min_observation_days: 30
     coverband:
-      source: redis://prod-redis:6379/2?key=coverband
+      source: rediss://prod-redis:6379/2?key=coverband
+      connect_timeout: 5
+      read_timeout: 5
+      total_timeout: 15
+      max_response_bytes: 16777216
+      max_bulk_bytes: 8388608
+      max_array_elements: 100000
+      max_resp_depth: 16
+      max_keys: 1000
+      max_payload_depth: 64
     trace_point:
       source: tmp/necropsy_trace_point.yml
   custom:
     - class: "MyCompany::GraphqlEntryAnalyzer"
       require: "config/necropsy/graphql_entry_analyzer"
+      trusted: true # executes Ruby in the Necropsy process
+rta:
+  pruning: rank_only # legacy pruning marks analysis invalid and cannot pass check
 cache:
   enabled: true
   path: .necropsy_cache/scan.json
@@ -109,6 +189,8 @@ implicit_callers:
     owner_ancestors: ["RuboCop::Cop::Base"]
     reason: "RuboCop Commissioner callback"
 paths:
+  analyze: ["**/*.rb", "Rakefile", "**/*.rake", "bin/*", "exe/*", "*.gemspec"]
+  reference: ["**/*"]
   exclude: ["app/legacy/**/*.rb"]
 report:
   include: ["app/**", "lib/**"]
@@ -121,44 +203,127 @@ ci:
   baseline: .necropsy_baseline.yml
 quarantine:
   days: 30
+  expiry: warn # warn | fail | ignore
 bench:
   precision_threshold: 0.85
 logging:
   verbose: false
 ```
 
-The scan cache is invalidated when scanned Ruby files or configuration values
-change.
+The scan cache is invalidated when analyzed Ruby files, reference files, or
+configuration values change.
+
+`analysis.world: application` uses executable, framework, and configured roots.
+Use `library` when callers may live outside the repository: every non-test
+public or protected method becomes an `external` root, while private methods
+remain eligible for review. `analysis.load_roots: all` is an opt-in conservative
+mode that treats every non-test Ruby file top level as a runtime root when load
+status cannot be established. Root domain, reason, and provenance are included
+in graph JSON and `why` paths.
 
 When a call receiver cannot be resolved exactly, Necropsy conservatively keeps
 up to `resolution.ambiguity_limit` same-name candidates alive. The default of
-four is based on the RuboCop 1.75.0 measurements in `MEASUREMENTS.md`.
+four is based on the RuboCop 1.75.0 measurements in `MEASUREMENTS.md`. If a
+runtime call has more candidates, Necropsy records a message- and owner-scoped
+blocker instead of treating the empty target set as proof of deadness. Matching
+definitions are reported as `blocked` with the call site, scope, and reason;
+they never receive `high` or `certain` confidence. Unresolved calls found only
+in test files remain diagnostic evidence and do not block production candidates.
 
 Ruby VM hooks and common protocol methods receive lower confidence because
 their callers may not appear in source. Add `implicit_callers` rules for
 framework or application callbacks; `owner_ancestors` is optional.
 
-`paths.include` narrows the source files used to construct the call graph and
-can remove executables, tests, routes, and other entry points. Use
-`report.include` and `report.exclude` when the full project should be analyzed
-but only selected application paths should be reported. Necropsy warns when a
-configured `paths.include` excludes detected entry-point files.
+Source discovery has three independent scopes. `paths.analyze` selects Ruby
+definitions eligible for findings. `paths.reference` defaults to the whole
+repository and keeps Ruby callers outside the analysis scope in the graph;
+definitions found only there are never reported as dead-code findings. It also
+inventories non-Ruby files for conservative reference checks. `report.include`
+and `report.exclude` only filter output and never remove graph nodes or edges.
+When `paths.analyze` is omitted, the existing conventional Ruby source set
+(`*.rb`, `*.rake`, the root `Rakefile` and gem specifications, and Ruby
+executables directly under `bin/` or `exe/`) remains the analysis scope.
+
+`paths.exclude` continues to remove files from the analysis scope, while the
+legacy `paths.include` key remains an alias for `paths.analyze`. Narrowing the
+analysis scope can hide entry points, so reports include scope diagnostics and
+Necropsy warns when detected executables, tests, routes, or task files are left
+outside it. Repository discovery rejects symlinks and paths that resolve outside
+the project root. If `paths.reference` excludes non-test Ruby files that may
+contain callers, findings are conservatively `blocked` and the report lists the
+excluded count and sample until the reference scope is expanded.
+
+For otherwise actionable candidates, Necropsy also scans reference-scope files
+that are not Ruby. Unexplained method names in templates, YAML, GraphQL SDL, and
+scheduler configuration become `unparsed_external_reference` blockers with the
+matching file, line, and snippet. Common names such as `call` or `run` require a
+review more often because safety takes precedence over yield; benchmark results
+identify formats that merit a dedicated parser. The scanner is a portable Ruby
+fallback with no `rg` dependency. It ignores comments, generated/tool metadata,
+and binary formats. Files from 1–16 MiB are streamed. Generated, unreadable,
+larger, or budget-truncated runtime inputs are never treated as negative evidence:
+they add a global blocker, degraded health, and bounded provenance diagnostics.
 
 Dynamic inputs may provide `executed` or `nodes` entries with method IDs,
 `edges` with `caller_id`/`callee_id`, and an `observation` hash. SARIF and
 GitHub Actions annotations are available via `--format sarif` and
 `--format github`.
 
+Reports retain logical method names while the graph distinguishes repeated or
+reopened definitions with physical `definition_id` values. Graph consumers and
+custom analyzer authors upgrading to the structured resolution model should
+follow the [0.3.0 migration guide](docs/migrations/0.3.0.md).
+
+The adversarial disposition of every item in the implementation review is recorded
+in the [148-item implementation matrix](docs/impv_implementation_matrix.md). Explicit
+no-go decisions include measurable reconsideration gates rather than hidden backlog.
+
+The graph keeps one interned evidence store and derives `exact`, `conservative`,
+and scope-filtered `observed` edge views on demand. Normal analysis and the
+serialized `edges` view use the conservative projection, preserving legacy
+reachability. Serialized edges retain nested `evidences` and additionally
+reference the top-level `evidence_records` through stable `evidence_ids`.
+
+Runtime evidence is positive-only: executed methods and the endpoints of
+observed edges are kept alive, while an unobserved method never becomes a new
+finding and never receives higher confidence. Observation duration and
+environment remain informational metadata. `min_observation_days` is a
+read-compatibility no-op and cannot change candidates, classifications, or
+confidence. The `unused` state remains only for reading and aggregating legacy
+schemas; positive-only analysis does not produce new `unused` findings. Reports
+include attempted, matched, and unmatched evidence counts plus a bounded
+unmatched sample.
+
+Schema v1 payloads may omit the analyzed source revision. Their positive
+evidence is accepted for liveness for compatibility, but an omitted revision is
+marked `source_revision_status: unknown` and is never treated as proof that
+unobserved code is dead. When `source_revision` is supplied, it is retained in
+the evidence scope so an exact projection can require a matching revision. Use
+evidence recorded from the same checkout.
+
 Coverband file, Redis string, and Redis hash exports are supported. Redis URLs
-may include an ACL username and password; `connect_timeout` and `read_timeout`
-can be set in the Coverband analyzer configuration. Rails route
+may include an ACL username and password. `rediss://` uses the system CA store,
+TLS peer verification, SNI, and post-connect hostname verification; URI
+credentials are redacted from loader errors. Connect, read, and total timeouts,
+response and bulk bytes, RESP array size/depth, key count, and payload depth all
+have the bounded defaults shown above and can be set in the Coverband analyzer
+configuration. Rails route
 entry point detection covers common `resources`, `resource`, `namespace`,
 `scope`, `controller`, `concerns`, `draw`, `mount`, `root`, and verb route
 forms.
 
-`necropsy quarantine --write` adds `# necropsy:quarantine since=YYYY-MM-DD`.
-When the configured quarantine window expires and no alive evidence appears,
-the finding is raised to `certain`.
+`necropsy quarantine --write` adds
+`# necropsy:quarantine since=YYYY-MM-DD fingerprint=PHYSICAL_FINGERPRINT`.
+The annotation applies only to the immediately following physical definition
+when its fingerprint matches. Legacy annotations without a fingerprint require
+review and can be upgraded in place with `quarantine --write`.
+Use `--as-of YYYY-MM-DD` or `SOURCE_DATE_EPOCH` to make quarantine expiry,
+annotation dates, and baseline timestamps reproducible.
+Expiry never changes a finding's classification, score, or confidence. Instead,
+the finding receives a `quarantine_review_required` diagnostic. The `check`
+command warns by default; set `quarantine.expiry` to `fail` to make an expired
+annotation fail CI, or to `ignore` to suppress the operational check. An invalid
+`since` date is reported as `quarantine_invalid_date` without changing deadness.
 
 ## Development
 

data/bench/README.md

@@ -0,0 +1,92 @@
+# Reproducible benchmark seed
+
+Run the version 1 corpus from the repository root:
+
+```shell
+bundle exec ruby bench/run.rb
+```
+
+The command writes normalized reports, the candidate union, and a performance summary to
+`tmp/necropsy-benchmark/v1`. The normalized reports omit machine-specific roots and timing data;
+the separate summary records wall time, phase allocations, resolution-cache counts, and peak RSS
+(or current RSS when the platform does not expose a process high-water mark). Its `golden.status` is `match`, `drift`, or `missing`, with every
+changed deterministic artifact listed under `golden.differences`.
+
+The manifest pins five corpus roles: this repository, RuboCop 1.75.0, a plain Ruby fixture, a Rails
+fixture, and a positive dynamic-evidence fixture. The small fixtures are in `spec/fixtures`; set
+`NECROPSY_RUBOCOP_CORPUS` to an existing RuboCop 1.75.0 checkout to enable that external corpus.
+RuboCop is fixed to tag `v1.75.0` and commit `9c2bc8eb11e269f1cf47113041a1be3ff615f68b`;
+a checkout at another commit fails before analysis. Missing external corpora are recorded as
+explicit skips rather than downloaded automatically, but omission causes golden drift and a
+nonzero exit once the pinned RuboCop result is present in the golden set. All five manifest entries
+are required for golden updates; an incomplete run raises an error before touching existing golden
+files. Pinned Git corpora must also have no tracked working-tree changes.
+
+The comparison-tool YAML files are versioned review seeds, not claims from a fresh tool execution.
+They exercise the candidate-union schema for Necropsy, Debride, Spoom, and a type-aware analyzer
+without requiring those tools to be installed. Replace them with pinned output snapshots when a
+comparison is rerun. A missing snapshot and executable produces an explicit skipped tool result.
+
+Deterministic golden files live in `bench/golden/v1`. Drift is printed and exits nonzero. Updating
+them requires an audit reason; `metadata.json` binds that reason to every artifact digest:
+
+```shell
+bundle exec ruby bench/run.rb --update-golden 'explain the intentional finding drift'
+```
+
+Review `candidate_union.json` before accepting drift. Labels use `dead`, `alive`, `external`, or
+`unknown`, and every reviewed label includes a rationale. A label that does not match an actual
+candidate from a generated Necropsy report or a versioned comparison snapshot is rejected.
+
+Normalized report schema version 1 remains compatible and now has additive measurement fields.
+Each finding declares `candidate` versus `diagnostic`, physical `definition_id`, LOC, category,
+unknown status, rule hits, risks, and blockers. The `quality` object provides the corresponding
+counts and rates. Report include/exclude scope is applied before these fields are aggregated.
+Blocked and test-only findings never become Necropsy candidates in `candidate_union.json`, though
+they remain available under `summary.necropsy_diagnostics`.
+
+`summary.tool_metrics` separates candidate-union precision from known-positive recall and reports
+candidate count and measured LOC overall and by category. Add an optional `category` to reviewed
+labels to define stable error strata. A separate top-level `known_positives` list in the labels
+file may include methods missed by every tool; when omitted, reviewed `dead` labels are the
+backward-compatible recall set. Each known positive requires its own rationale. `unknown` labels
+are not treated as either true or false
+positives. When a tool produces no candidates, precision is `null` with
+`precision_status: no_candidates`; yield remains zero, so an empty result cannot claim 100%
+precision. External snapshots without LOC remain valid and expose `candidate_loc_measured_count`
+instead of inventing a method size.
+
+## 0.2.1 safety release audit
+
+The release audit compares all five current corpus reports with the first integrity-bound
+five-corpus snapshot, reviews deterministic Rails/RuboCop differences, runs the dynamic, parse,
+ambiguity, and remote-input adversarial suites, and enforces wall-time and RSS budgets:
+
+```shell
+NECROPSY_RUBOCOP_CORPUS=/path/to/rubocop-1.75.0 \
+  bundle exec ruby bench/audit.rb
+```
+
+Run it from a clean worktree. The command binds generated reports to the exact Git revision and to
+the benchmark manifest and audit-config digests. It also records Ruby, OS, command, and RSS
+measurement provenance, and fails closed when those values are incompatible with the saved
+baseline. `--skip-benchmark` is intended only for an immediate rerun: it verifies the saved report
+digests and all source provenance before accepting existing output. `--skip-adversarial` records
+the suites as not run and cannot pass the release gate.
+
+The reviewed input policy and baseline performance measurement live under
+`bench/audits/0.2.1`. A passing run writes `audit.json` and `audit.md` there; neither an empty policy
+nor an unknown review outcome is accepted.
+
+The 1.0 public accuracy claim remains fail-closed until the independent review target is met. Generate
+the deterministic, explicitly pending queue with:
+
+```shell
+bundle exec ruby bench/review_queue.rb
+```
+
+The committed `bench/audits/0.2.1/review_queue.yml` contains 300 actionable rows from all five
+corpora, but it contains no labels, outcomes, or reviewer identities. Its `claim_gate_passed` value is
+therefore `false`; editing the queue alone cannot satisfy the gate. Add independently reviewed labels
+to the benchmark review input, rerun the audit, and publish precision and known-positive recall
+separately.

data/bench/audit.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'optparse'
+require 'yaml'
+require_relative '../lib/necropsy'
+require_relative '../lib/necropsy/bench/seed_runner'
+require_relative '../lib/necropsy/bench/release_audit'
+require_relative '../lib/necropsy/bench/release_audit/adversarial_runner'
+require_relative '../lib/necropsy/bench/release_audit/artifact_writer'
+require_relative '../lib/necropsy/bench/release_audit/config_validator'
+require_relative '../lib/necropsy/bench/release_audit/git_snapshot'
+require_relative '../lib/necropsy/bench/release_audit/run_provenance'
+
+root = File.expand_path('..', __dir__)
+options = {
+  config: File.join(__dir__, 'audits/0.2.1/config.yml'),
+  benchmark_output: File.join(root, 'tmp/necropsy-benchmark/v1'),
+  audit_output: File.join(__dir__, 'audits/0.2.1'),
+  run_benchmark: true,
+  run_adversarial: true
+}
+
+OptionParser.new do |parser|
+  parser.banner = 'Usage: bundle exec ruby bench/audit.rb [options]'
+  parser.on('--config PATH', 'Audit configuration') { |path| options[:config] = path }
+  parser.on('--benchmark-output DIR', 'Current benchmark output') { |path| options[:benchmark_output] = path }
+  parser.on('--output DIR', 'Audit artifact output') { |path| options[:audit_output] = path }
+  parser.on('--skip-benchmark', 'Use an existing current benchmark run') { options[:run_benchmark] = false }
+  parser.on('--skip-adversarial', 'Do not execute adversarial suites') { options[:run_adversarial] = false }
+end.parse!
+
+config_path = File.expand_path(options.fetch(:config), root)
+config = YAML.safe_load_file(config_path, aliases: false)
+Necropsy::Bench::ReleaseAudit::ConfigValidator.new(config).validate!
+
+manifest_path = File.join(root, 'bench/corpora/v1/manifest.yml')
+benchmark_output = File.expand_path(options.fetch(:benchmark_output), root)
+provenance_path = File.join(benchmark_output, 'run_metadata.json')
+rubocop_corpus = ENV.fetch('NECROPSY_RUBOCOP_CORPUS', '<unset>')
+measurement_command = "NECROPSY_RUBOCOP_CORPUS=#{rubocop_corpus} bundle exec ruby bench/run.rb"
+provenance = Necropsy::Bench::ReleaseAudit::RunProvenance.new(
+  root: root,
+  manifest_path: manifest_path,
+  config_path: config_path,
+  output_dir: benchmark_output,
+  command: measurement_command
+)
+
+current_provenance = if options[:run_benchmark]
+                       source = provenance.capture_source!
+                       summary = Necropsy::Bench::SeedRunner.new(
+                         manifest_path: manifest_path,
+                         output_dir: benchmark_output
+                       ).call
+                       provenance.complete(source, summary).tap do |payload|
+                         provenance.write(provenance_path, payload)
+                       end
+                     else
+                       provenance.load_and_validate!(provenance_path)
+                     end
+
+corpora = config.fetch('corpora')
+current_reports = corpora.to_h do |corpus|
+  path = File.join(benchmark_output, 'reports', "#{corpus}.json")
+  [corpus, JSON.parse(File.read(path))]
+end
+current_summary = JSON.parse(File.read(File.join(benchmark_output, 'summary.json')))
+baseline = config.fetch('baseline')
+baseline_reports = Necropsy::Bench::ReleaseAudit::GitSnapshot.new(
+  root: root,
+  git_ref: baseline.fetch('git_ref'),
+  reports_path: baseline.fetch('reports_path')
+).reports(corpora)
+
+load_yaml = lambda do |relative|
+  YAML.safe_load_file(File.expand_path(relative, root), aliases: false) || {}
+end
+label_entries = Array(load_yaml.call(config.fetch('labels_path'))['labels'])
+labels = label_entries.to_h { |entry| [[entry.fetch('corpus'), entry.fetch('id')], entry] }
+reviews = Array(load_yaml.call(config.dig('review', 'path'))['reviews'])
+baseline_performance = load_yaml.call(config.dig('performance', 'baseline_path'))
+adversarial_results = if options[:run_adversarial]
+                        Necropsy::Bench::ReleaseAudit::AdversarialRunner.new(
+                          root: root,
+                          suites: config.fetch('adversarial_suites')
+                        ).call
+                      else
+                        config.fetch('adversarial_suites').sort.map do |name, definition|
+                          { 'name' => name, 'command' => definition.fetch('command'), 'passed' => false,
+                            'exit_status' => nil, 'duration_seconds' => 0.0, 'summary' => 'not run' }
+                        end
+                      end
+
+audit = Necropsy::Bench::ReleaseAudit.new(
+  config: config,
+  baseline_reports: baseline_reports,
+  current_reports: current_reports,
+  current_summary: current_summary,
+  labels: labels,
+  reviews: reviews,
+  baseline_performance: baseline_performance,
+  adversarial_results: adversarial_results,
+  current_provenance: current_provenance
+).call
+paths = Necropsy::Bench::ReleaseAudit::ArtifactWriter.new(
+  audit: audit,
+  output_dir: File.expand_path(options.fetch(:audit_output), root)
+).call
+puts "release audit: #{audit.fetch('status')}"
+puts "machine artifact: #{paths.fetch(:json)}"
+puts "human artifact: #{paths.fetch(:markdown)}"
+exit(audit.fetch('status') == 'pass' ? 0 : 1)