C05

The requested correction belongs in check_flag_doc_coverage; it should share the existing flag-identity rule with the truth checker while retaining whole-manpage coverage.

Current behavior, from source inspection:

  • src/gzkit/doc_coverage/flag_scanner.py:220 reads each existing command manpage and uses if flag in content. Consequently, a document containing only --output-format satisfies --output. This is a code-derived conclusion, not an executed reproduction.
  • The same module already defines _FLAG_END = r"(?![\w-])" and _mentions at lines 286–291. The truth checker uses that escaped regex to avoid treating --attestor-present as --attestor. Reusing it addresses the requested suffix collision without introducing a second matching policy.
  • Presence accepts mentions anywhere: prose, examples, tables, headings or usage. Truth separately reads fenced Usage/Synopsis blocks and checks requiredness/value-taking. It skips flags not mentioned there. Neither check should acquire the other's scope.
  • Missing files are skipped by per-flag coverage; command-level auditing reports missing required manpages. Explicit waivers suppress individual command/flag findings; the committed presence and truth waiver maps are empty.

Necessary coupled obligations:

  1. Replace substring presence with the shared matcher and update its usage-specific parameter/docstring plus the coverage docstring's obsolete string-presence explanation. Update the presence description in docs/user/manpages/cli-audit.md to make the longer-sibling exclusion explicit. No heading mandate or Markdown parser is needed.
  2. Preserve matching syntax: exact flags followed by whitespace, punctuation, closing backticks/brackets, end-of-file, or = should remain recognized. The existing negative lookahead excludes letters, digits, underscores, Unicode word characters and hyphens immediately after the name. A plain word boundary would incorrectly accept the hyphen in --output-format.
  3. Preserve AST discovery, name/spec projections, per-function parser scope, long-alias handling, space-to-hyphen manpage paths, waiver keys/defaulting and issue ordering/schema. Coverage changes should not rewrite parser registrations or introduce dependencies.
  4. Verify the immediate CLI consumer: cli_audit_cmd appends both checks' findings, sets valid from the combined issues and exits 1 on failure. JSON keys valid, issues, cross_coverage and existing human diagnostics remain compatible. Command-level cross-coverage may still pass when flag coverage fails; its counters are not flag counters.
  5. Audit newly exposed real-document gaps and repair genuine missing mentions rather than silently adding waivers. TestPerFlagDocCoverage.test_per_flag_doc_waivers_match_real_project_drift already demands no unwaived drift and checks stale waivers. The quality wrapper delegates to CLI audit, so stricter findings can affect the normal quality path.

Proposed verification, not performed:

  • First add a regression with both registered flags and a manpage mentioning only --output-format; assert exactly one finding for --output, including its canonical path. Add the exact shorter flag and assert both pass.
  • Parameterize suffix collisions (--output-format, --output2, --output_extra) and valid delimiters (--output=FILE, backticks, brackets, punctuation, EOF). Include prose-only coverage to catch accidental restriction to usage blocks.
  • Verify explicit waiver suppression, empty-waiver behavior, missing-page delegation and nested command slugs. Retain discovery tests and truth tests, especially sibling-prefix and claims-outside-usage regressions.
  • Exercise a controlled CLI fixture with valid command-level surfaces and the deliberate flag gap; assert JSON failure, exit 1 and human finding, then successful repair. Inspect existing audit fixtures that synthesize whitespace-separated exact flag mentions.
  • Subsequently run the relevant unittest modules, real-manpage coverage/truth census, CLI audit and appropriate quality/docs verification, recording actual output at that time.

Compatibility limits and uncertainty:

The existing matcher has no left boundary: embedded x--output still matches. Defining a stricter token grammar would be an additional behavior decision, not necessary for the requested longer-sibling fix. runner.py's separate documentation-coverage report only consumes command-level scanning; this change should not silently expand it into a flag report. No repository-wide gap count, passing-test claim or governance ownership determination is established here.

Read inventory: all repository paths below are relative to /tmp/gzkit-current-snapshot. Full or partial content reads: src/gzkit/doc_coverage/{flag_scanner,manifest,scanner,runner}.py; src/gzkit/commands/cli_audit.py; src/gzkit/quality.py; src/gzkit/cli/parser_artifacts.py; tests/commands/{test_cli_audit,test_audit}.py; docs/user/manpages/{cli-audit,justify}.md; .gzkit/skills/gz-cli-audit/SKILL.md. Initial combined output was truncated; the missing CLI and opening test portions were subsequently read. Searches inspected matching lines under src, tests, docs/user, and .gzkit/skills; search-only hits were discovery leads, not whole-file evidence. Attempts to read src/gzkit/commands/check.py and docs/user/manpages/adr-eval-record.md failed because those paths did not exist. Also read /tmp/gzkit-current-inputs/C05.md. Eight shell/read calls total, including this response-file write. No tests, workflows, source edits, history, network or evaluation material were accessed.