C01

The change belongs in the per-flag presence predicate, with coupled tests and documentation. Static evidence supports reusing the existing flag-ending rule; it does not establish whether current manpages would acquire new findings.

Current behavior

src/gzkit/doc_coverage/flag_scanner.py:220–258 checks if flag in content. Thus a manpage containing only --output-format satisfies --output by construction. Presence searches the entire UTF-8 manpage, including examples and prose, without requiring a particular heading. Commands map to filenames by replacing spaces with hyphens. Missing files are skipped here; other audit checks own missing-page reporting. Waivers suppress exact command/flag pairs; the committed default waiver map is empty.

The same module already defines _FLAG_END = r"(?![\w-])" and _mentions, using re.escape(flag) followed by that ending rule. The usage truth check uses this matcher and related expressions to avoid confusing --attestor with --attestor-present. It checks requiredness and value-taking only in fenced Usage/Synopsis blocks. Presence and truth deliberately answer different questions.

src/gzkit/commands/cli_audit.py:242–275 discovers specs once, projects names, appends both checks’ issues, emits valid, issues, and cross_coverage, and exits 1 for findings. src/gzkit/quality.py:687–737,798–805 incorporates this command into overall quality success. A newly detected presence gap therefore affects the command and quality outcome, even though the command-level cross-coverage report can remain green.

Necessary coupled obligations and boundaries

  • Use one flag-ending definition for presence and truth; generalize _mentions’ usage-specific naming/docstring if reused on whole documents. Preserve literal escaping. Do not substitute a plain word boundary: hyphens extend sibling flags but are not word characters.
  • Update the coverage docstring’s explicit substring promise and clarify the presence assertion in docs/user/manpages/cli-audit.md. Retain acceptance of mentions anywhere, including inline code, prose, examples, and tables. This request does not establish a heading requirement or semantic prose grader.
  • Preserve return shape, diagnostic path/message, command ordering, waiver behavior, missing-document handling, and absent-source fallback. No parser-discovery or manifest-schema change is needed for the stated example.
  • Preserve truth-check behavior if the helper is shared. The existing rule is a right boundary only: it blocks following word characters/underscores/digits/hyphens but accepts punctuation and =. Rejecting embedded occurrences on the left, or defining arbitrary argparse punctuation as flag-name characters, would broaden semantics and needs an explicit decision rather than silently changing the shared helper.
  • Inspect and repair genuine manpage omissions exposed by tighter matching. Do not automatically populate the empty waiver map or alter existing tests to bless newly discovered gaps.

Proposed verification, not executed

  1. Add a focused fixture with registered --output and --output-format, documenting only the latter. Assert exactly one issue, naming the shorter flag and its canonical manpage path. Then independently add a real shorter mention and assert success. Include a multiword command to exercise slugging.
  2. Table-test sibling suffixes (-format, letters, digits, underscore) versus valid delimiters (EOF, whitespace/newline, backticks, brackets, punctuation, and --output=VALUE). Include a regex-metacharacter flag fixture to protect literal matching.
  3. Verify explicit/default waivers, unrelated waived flags, missing pages, and multiple commands. Keep presence outside Usage accepted. Retain existing truth collision, optionality, value-taking, and outside-Usage tests.
  4. Add a CLI-level collision fixture proving JSON valid: false, the expected issue, nonzero exit, and human reporting; retain cross-coverage structure. Existing clean-output tests do not prove this failure path. The generated fixture in tests/commands/test_audit.py documents literal flags separated by spaces and should remain compatible.
  5. Subsequently run focused tests and the real-manpage audit, inspect every new finding, then relevant quality verification. No tests, census, or workflows ran in this assessment; repository-wide cleanliness and live ownership remain unverified.

Read inventory and limit

8 shell/read calls total, including task read and this output write. All repository paths below are relative to /tmp/gzkit-current-snapshot.

Content reads: /tmp/gzkit-current-inputs/C01.md; .gzkit/personas/main-session.md; src/gzkit/doc_coverage/{flag_scanner,manifest}.py; src/gzkit/commands/cli_audit.py; tests/commands/{test_cli_audit,test_audit}.py; docs/user/manpages/cli-audit.md. Excerpts: src/gzkit/doc_coverage/scanner.py, src/gzkit/quality.py.

Additional searches returned matching lines in src, tests, docs/user, and docs/design/adr; those were navigation evidence only, not full-file reads or an ownership determination. One combined output was truncated; the missing opening test section was reread. Two guessed search paths did not exist. No history, network, evaluation contents, other responses, or current checkout were inspected. Only the permitted response file was written.