Coverage records why a selected file failed, but not why a file was never selected

[NicolasRocchia]

Context

I was studying how review tools represent a check that was planned and did not run, and read the run manifest and the session compare logic. The design is unusually careful: terminal_state derived from the coverage sets and run_failure only, never from comment count or warnings; FailureClass a fixed set with a mandatory catch-all; ItemID content-independent so a resume chain keeps a stable identity; rule_config_sha256 and runtime_config_sha256 pinned in execution. The not_reviewed bucket in CompareResult, and its comment — "They are not resolved: nobody re-checked them" — is the sharpest statement of this problem I have found in a review tool.

This is about a gap I could not close by reading, so I may have missed where it is handled.

The gap

Coverage has selected, completed, reused, failed and waived. A file that never became a candidate — removed by user_exclude, default_path, unsupported_ext, provider_directory, too_large — is in none of them.

model.ExcludeReason is already a closed vocabulary of nine values, and Preview carries will_review, exclude_reason and excluded_count. But ExcludeReason appears only under cmd/, internal/model, internal/agent and internal/scan. Grepping internal/session/ for ExcludeReason or Excluded returns nothing: the exclusion reason reaches the terminal output and ocr delegate preview, and stops there. It is not in the manifest and not in the session JSONL.

Two consequences follow:

1. A run where 2 of 40 changed files were excluded finalizes as terminal_state: complete with 38 selected items. The denominator shrinks instead of the gap becoming visible. From the manifest alone, "there was nothing else to review" and "those two were deliberately not looked at" are the same record.

2. execution pins rule_config_sha256, so a consumer can prove which rules ran, but not which files those rules removed. Given how much of the rest of the manifest exists to make coverage auditable after the fact, that asymmetry reads as unintended rather than as a decision.

Proposed change (small)

Add an excluded []CoverageItem set to Coverage, populated at selection time, with classification carrying the existing ExcludeReason value and reason left empty. Then either count a non-empty excluded in the terminal_state derivation, or state explicitly in the schema docs that complete means complete over the selected set.

No new vocabulary is needed — the values already exist and are already closed. The change is where they are written down.

Alternatives I considered

Keeping it in the preview only, and asking users to save ocr delegate preview next to the run: it works, but it is a second artifact that has to be kept in sync by hand, and the preview is taken before the run rather than recorded by it. Reconstructing exclusions later from rule_config_sha256 plus the repo state: possible in principle, not reproducible once the rules or the working tree change.

Why I think this earns a field

I maintain a corpus of 44 adversarial-review records under a schema that requires declaring what a review round could not close. 37 of its 46 residue items are checks that were planned and did not run. Once the not-run case is recordable at all, it is not a rare edge — it is most of what the record ends up containing. A manifest that can only describe selected work under-reports by construction, and the under-report is the part nobody can see.

I can send a PR if the direction is welcome, or open a formal Feature Request if you prefer that path.

—
Nicolás Rocchia · https://disensor.dev

[Qiyuanqiii]

I don’t really check the discussion module, so... does it still need to be resolved?

[NicolasRocchia]

It is in Discussions rather than in an issue because that is where your own config sends it. .github/ISSUE_TEMPLATE/config.yml has blank_issues_enabled: false, and the Ideas contact link reads "Discuss feature ideas before opening a formal request", with feature_request.yml as the step after. So this was the documented first door. If Ideas is not actually watched, that routing is probably worth knowing about on its own, separately from whether you want this change.

Tell me which door you prefer and I will use it. I can open the Feature Request, or send the PR directly. The change is one excluded set on Coverage, populated at selection time, carrying the existing model.ExcludeReason value. No new vocabulary, and nothing moves except where it gets written down.