[bline]

A prose-only documentation edit can leave detect_changes with no behavioral seed even when the paragraph explicitly names implementation code. This proposes detect_changes(scope: "doc_references") for #2614: changed prose selects its indexed document owner and reports one outbound MENTIONS hop as targets for review. These references are separate from behavioral impact and never become traversal seeds. Existing scopes and defaults retain their behavior.

This draft makes the issue's three design choices concrete for maintainer review: query-time section ownership, a separate outbound reference scope, and File ownership before the first heading. Maintainer direction on this contract remains pending.

Prose belongs to the nearest preceding heading until the next heading; text before the first heading uses the File node. These intervals are derived at query time, including repeated headings. Resolved code targets and reason-coded unresolved references share stable pagination. Recognized resolved documentation/Section targets are omitted; unresolved references retain raw text and their reason because their target type is unknown. Recognized document extensions and documents with indexed Sections are described in the README.

The mode uses one comparison-base-to-current diff, including staged changes. It verifies source content and recorded coverage before attributing hunks, pins its index reads, and binds cursors to the generation and changed-file fingerprint. Invalid continuations and unavailable input/reference layers fail visibly. A failed scope restoration detaches the unsafe server binding and closes the handle only when owned. Missing, stale, deleted or partially covered recognized documents remain unavailable. Output-budget exhaustion and the 5,000-row materialization cap are explicit. Top-of-file deletions anchor to the first surviving line. File-boundary and hunk-body handling prevent hunks from leaking into other documents. Cursor offsets equal to or beyond the materialized count fail visibly.

This discovers references present in the current index. It does not reconstruct deleted historical references, prove complete extraction, establish behavioral impact or maintain/publish claims. Filesystem fingerprinting is a before/after consistency check, not an atomic filesystem snapshot. Documentation diffs force raw, uncolored output with fixed prefixes. Quoted and overlong paths use an explicit whole-file fallback because the shared hunk parser cannot represent them precisely.

The real Git/Markdown regression covers prose-only edits under repeated headings, preamble references, unresolved members, paging, stale cursors, content drift, tight output budgets, mixed top deletion/later edits, a deleted file sorted after the changed document, quoted Unicode paths, configured Git prefixes/color, header-like prose, and cursor offsets at and beyond the result boundary.

Validation on Linux x86_64:

• scripts/test.sh CC=clang CXX=clang++: exit 0; ASan+UBSan, 10,326 passed, 0 failed, 11 skipped across 192 suites, followed by all production-binary guards. MCP phase: 425 passed, 4 skipped.
• scripts/lint.sh --ci CLANG_FORMAT=clang-format-20 CPPCHECK_JOBS=4 LINT_SRCS=src/mcp/mcp.c LINT_HDRS=src/mcp/mcp_internal.h: exit 0 using the project lint toolchain container.
• scripts/security-audit.sh, source/test syntax checks and git diff --check: exit 0. The two proposed patches also apply together and their combined source/test syntax and tool-metadata ceiling checks pass; runtime suites were run separately for each PR.

Full scripts/lint.sh remains non-green: clang-tidy reports existing handler complexity, and the project's existing safe_free macro triggers C pointer-cast diagnostics. Canonical safe_free is retained for legacy-owned strings; the allocation ratchet passes at 765 raw sites against the existing 769 baseline. No check suppression, threshold or allocation-baseline changes were made.

AI disclosure: implemented with Codex; retained read-only Claude and Astra xhigh reviews were used for correctness feedback. Model review is separate from the executed checks above.

Fixes #2614

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.