bug(prover): prove() doc comment incorrectly references severity grades #2394

Agent Diagnostic

• No relevant skills loaded (pure code investigation)
• OpenShell version tested: v0.0.88 (latest release, 2026-07-21)
• Latest release checked: yes — bug present in v0.0.88
• Possible duplicates searched: no existing issues found for "severity", "prover", "exit code", or "doc comment"
• Findings: lib.rs:31-32 uses severity language ("critical/high") that contradicts four other locations in the same crate and the actual exit code logic in report.rs
• Agent could not self-resolve: the doc comment is wrong and needs correcting in source

Description

The prove() function in crates/openshell-prover/src/lib.rs has an incorrect doc comment at lines
31–32:

/// - `0` — pass (no critical/high findings, or all accepted)
/// - `1` — fail (critical or high findings present)

The prover has no severity grades — findings are categorical (yes/no per formal query). Exit code 1
fires on any unaccepted finding regardless of category. The correct semantics are:

  /// - `0` — pass (no findings, or all accepted)
  /// - `1` — fail (one or more unaccepted findings present)

Four other locations in the same crate all explicitly state the prover is not severity-graded
(src/finding.rs:8, src/report.rs:6, src/queries.rs:9, README.md:19). The exit code logic in
src/report.rs:111–124 confirms no severity check is performed — it branches solely on path_count > 0
where path_count counts all unaccepted finding paths.

Expected behavior: Doc comment accurately reflects that exit code 1 fires on any unaccepted finding,
not only high/critical ones.

Reproduction Steps

1. Read crates/openshell-prover/src/lib.rs:31-32.
2. Compare against src/report.rs:111-124 (exit code logic) and the four references above.

Environment

• OpenShell: v0.0.88
• Introduced: commit e98ea3e (feat(policy): add agentic approval loop)
• Affected file: crates/openshell-prover/src/lib.rs:31-32

Logs

Agent-First Checklist

• I pointed my agent at the repo and had it investigate this issue
• I loaded relevant skills (e.g., debug-openshell-cluster, debug-inference, openshell-cli)
• I checked the latest OpenShell release and either reproduced the issue there or explained why I cannot upgrade/test it
• I searched existing issues for possible duplicates or explained why I could not
• My agent could not resolve this — the diagnostic above explains why