compliance_summary (EN+TR) and the ISO/SOC2 alignment design misstate the verifier exit codes: verify-audit is said to exit 1 on HMAC mismatch or manifest divergence, and exit 6 i… (CR-A09-008) #447

Wave 1 · theme D1-8: Docs describing features that do not exist (doc side of code findings) · highest severity High · 1 finding(s) · effort small

Summary

An auditor or CI author follows compliance_summary.md and writes case $? in 1) page-security;; *) retry;; esac around verify-audit. A tampered log exits 6, so it is retried or ignored rather than paged.

Primary finding

CR-A09-008 — compliance_summary (EN+TR) and the ISO/SOC2 alignment design misstate the verifier exit codes: verify-audit is said to exit 1 on HMAC mismatch or manifest divergence, and exit 6 is missing

severity High · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN C31-EXIT-CODE-PROSE — docs/roadmap/phase-16-trust-surface-hardening.md:196-197 (OPS-24 compliance_summary prose; S15 open)

What happens. docs/reference/compliance_summary.md:240-245 (TR mirror: compliance_summary-tr.md:242-247), in the Article 12 section aimed at compliance officers and auditors, says forgelm verify-audit [--require-hmac] "exits 0 (valid) or 1 (any failure — parse error, HMAC mismatch, manifest divergence, file not found, option error). The richer 0/1/2/3 exit-code surface applies to the trainer entry-point, not to verify-audit." The code maps chain, HMAC, genesis-manifest and non-UTF-8 failures to EXIT_INTEGRITY_FAILURE (6) and an unreadable log to EXIT_TRAINING_ERROR (2) (forgelm/cli/subcommands/_verify_audit.py:126-150, 200-215). The trainer's surface is 0-4, not 0/1/2/3. docs/design/iso27001_soc2_alignment.md:105, a self-described 'living spec' deployer evidence map, lists verify-audit as "exit 0/1/2/3". verify-audit never emits 3 and does emit 6. Line 126 lists verify-integrity as "exit 0/1/2", but _verify_integrity.py:157 emits 6. This is the same pre-Step-3 rot that check_cli_exit_code_prose.py was built to stop in --help (its docstring, lines 7-17), and it survives here in the auditor-facing reference. A CI branch or an alarm runbook written from this page keys 'tampering' on 1. A real tamper then exits 6 and falls through to a default branch. Exit 6 is the very signal that error-handling.md:28 and CLAUDE.md tell operators to alarm on.

Where.

• docs/reference/compliance_summary.md:240-245
• docs/reference/compliance_summary.md:243
• docs/reference/compliance_summary-tr.md:242-247
• docs/reference/compliance_summary-tr.md:245
• docs/design/iso27001_soc2_alignment.md:105
• docs/design/iso27001_soc2_alignment.md:126
• forgelm/cli/subcommands/_verify_audit.py:143-148
• forgelm/cli/subcommands/_verify_integrity.py:157
• forgelm/cli/_dispatch.py:84
• forgelm/cli/_dispatch.py:116-117

Evidence.

• I built a 2-entry log with AuditLogger (no HMAC), tampered with the first entry's field and ran python -m forgelm verify-audit va/audit_log.jsonl. Output: 'FAIL at line 2: chain broken at line 2 ...' with EXIT=6. A missing path gives EXIT=1 and a clean log EXIT=0. compliance_summary says the chain-break case is 1.

Recommended fix. Rewrite both compliance_summary paragraphs to the 0/1/2/6 split and link the exit-codes table. Fix the two iso27001_soc2_alignment rows to 0/1/2/6. Pin these with the guard extension in the guard-gap finding.

Acceptance criteria

• A regression test reproduces the failure scenario and asserts the corrected behaviour.
• Documentation listed above is corrected in English and in its Turkish mirror in the same PR.
• Every finding in this issue is resolved or explicitly closed with a reason.

_{Found by the October 2026 ForgeLM code and documentation review against commit cab2947. Code links point at that commit; line numbers may have moved since. Finding IDs (CR-…, DOC-…, TECH-…) are stable references for this backlog.}