okf-kit 0.7.0 → 0.9.0

package/dist/rules/citations-resolve.js

@@ -101,8 +101,8 @@ const RULE_ID = "citations-resolve";
  * citation, prose habitually repeats just the line (or range) for a later
  * reference in the same sentence rather than retyping the path, in three
  * forms:
- *   - `` `:N` `` or `` `:N-M` `` -- a bare colon-prefixed line/range
- *   - `` -`M` `` / `` –`M` `` -- a hyphen- or en-dash-led bare line, the
+ *   - `` `:N` ``/`` `:N-M` `` -- a bare colon-prefixed line/range
+ *   - `` -`M` ``/`` –`M` `` -- a hyphen- or en-dash-led bare line, the
  *     tail half of a `` `path:N`-`M` `` split range
  *   - `` (`N`) `` -- a parenthesized bare line
  * Each of these resolves against `governing`: the nearest *preceding*
@@ -198,6 +198,11 @@ const RULE_ID = "citations-resolve";
  * nowhere natural to hang an anchor on one without inventing a second,
  * detached syntax; the migration this rule was built for (CHANGELOG.md
  * citations) is written as full citations throughout the corpus it targets.
+ * Under `--require-anchors`, this remains true (no second anchor syntax is
+ * added), but a continuation or short-form that chains off an in-repo full
+ * citation is instead flagged, `anchor-required-continuation`, so it does
+ * not drift silently -- see the "Anchor strictness (opt-in)" doc block
+ * below for that check.
  *
  * Rejected alternatives (see the PR/CHANGELOG for the fuller writeup):
  *   - Embedding the literal heading markup itself, e.g.
@@ -216,6 +221,123 @@ const RULE_ID = "citations-resolve";
  *     plus prose) to stay in sync, the exact class of drift this rule
  *     exists to catch.
  */
+/**
+ * Anchor strictness (opt-in, `--require-anchors`, see `src/cli.ts`).
+ * Backward compatible by construction: every check in this section is
+ * gated on `ctx.requireAnchors` being present (`RequireAnchorsOptions`, see
+ * `src/types.ts`), so a consumer that never passes `--require-anchors`
+ * sees byte-identical findings to before this section existed. Three new
+ * rule ids, all `warning`-severity, mirroring this rule's own "a wrong
+ * start/target is strong drift evidence" posture rather than the `notice`
+ * posture reserved for the mechanical prose checks with a real
+ * false-positive risk (`markdown-range-boundary-bracket-or-fence` and
+ * friends):
+ *
+ *   - `anchor-required`: an in-repo full citation (`path:N`/`path:N-M`,
+ *     resolved to a real target -- an unresolved citation already gets its
+ *     own `missing-file`/`unresolved-ambiguous` finding, not this one)
+ *     carrying no `#anchor` at all. Exempted the same way this rule already
+ *     exempts short-form matching for a reserved citing doc
+ *     (`doc.isReserved`, e.g. `log.md`'s append-only line-number narration),
+ *     and additionally by `requireAnchors.allow`: a citedPath matching one
+ *     of its glob/exact patterns (matched against the citation's raw,
+ *     as-written `citedPath` text -- see `matchesAllowPattern`) is exempt,
+ *     for a doc category this check is not (yet) meant to cover, e.g. a
+ *     README or install guide whose prose is not line-anchored the way a
+ *     CHANGELOG or source citation is.
+ *   - `anchor-not-on-last-line`: layered on `checkAnchor`'s existing string
+ *     branch. An anchor sitting on the FIRST line of a wide range survives a
+ *     k-line insertion above the range whenever k is smaller than the range
+ *     itself, because the shifted window (the citation's own line numbers,
+ *     re-read after the insertion) still contains the original first
+ *     line's content, just at a different offset inside the window.
+ *     Anchoring on the LAST line instead closes that: the original last
+ *     line falls out of the shifted window on any insertion size >= 1, not
+ *     only large ones.
+ *   - `anchor-not-unique-in-range`: also layered on the string branch. An
+ *     anchor text occurring more than once inside its own cited range is
+ *     ambiguous evidence -- which occurrence is the one actually pinning
+ *     the citation? A count of zero is unaffected (already
+ *     `anchor-not-found-in-range`, unconditionally, not double-reported
+ *     here).
+ *
+ * Both of the last two are checked only once a match exists at all (count
+ * >= 1); uniqueness is checked before last-line placement, since a
+ * non-unique anchor is the more fundamental problem (which of the several
+ * matching lines "is" the anchor is undefined before asking whether the
+ * one occurrence is on the right line).
+ *
+ * A fourth check, `test-range-straddles-block` (warning), applies to a FULL
+ * citation's own range into a `.test.`/`.spec.` target (`.ts`, `.js`,
+ * `.mjs`) under this same opt-in (see `checkTestRangeStraddle`, called
+ * from `checkFullTarget`): a
+ * full citation's range is expected to stay inside a single `describe`/
+ * `it`/`test` block once it starts, so any block-head line
+ * (`describe(`/`describe.only(`/`describe.skip(`/`describe.each(`/`it(`/
+ * `it.only(`/`it.skip(`/`it.each(`/`test(`/`test.only(`/`test.skip(`/
+ * `test.each(`, see `TEST_BLOCK_HEAD_RE`) found on any line of the range
+ * OTHER than its own first line means the citation ran into a sibling or
+ * outer block (or never really started on one). A range that leaves its
+ * block without a later head line inside it (ending on an outer block's
+ * closing line) is not detected by this line-based check. The range's start
+ * line is never itself checked here: it is either a legitimate block head
+ * (the range correctly starts a block) or legitimately inside a block's
+ * body (a partial citation into the middle of a block), and both are fine
+ * -- only a head line reappearing *after* the start is evidence of drift.
+ * Deliberately its own rule id rather than reusing `checkRangeBoundary`'s
+ * `test-range-start-not-head`/`test-range-end-not-closing` (which stay
+ * short-form-only, see `checkShortFormTarget`): those two require the range
+ * to start exactly on a head line and end exactly on the matching closing
+ * `});`, which is far stricter than a full citation's legitimate use
+ * (citing an arbitrary sub-range once a paragraph has already named the
+ * file) needs -- the straddle check only cares whether the range crossed a
+ * block boundary, not whether it captured a whole block precisely.
+ * Deliberately scoped to test-file targets only, same reasoning
+ * `checkShortFormTarget`'s own doc comment already gives for the Markdown
+ * half of the block-boundary check: a full citation into a Markdown target
+ * legitimately cites a couple of arbitrary lines all the time.
+ *
+ * A fifth check, `anchor-required-continuation` (warning), closes a gap the
+ * four checks above leave open: every one of them is gated on reaching a
+ * "full" atom, so a continuation (` :N`/`:N-M` `, `` -`M` ``/`` –`M` ``,
+ * `` (`N`) ``) or a paragraph-bound short-form `:N-M` chained off an
+ * ALREADY-ANCHORED full citation was previously invisible to
+ * `--require-anchors` entirely -- it carries no path of its own
+ * (see the "Continuation citations" / "Short-form citations" doc blocks),
+ * so it was never itself an in-repo full citation `anchor-required` could
+ * reach, and the anchor on the governing citation it chains off does not
+ * (and structurally cannot) cover it: a line-shift that only affects the
+ * continuation's own start/end line is exactly the drift this rule's base
+ * checks (blank-start-line and friends) already catch when it lands on
+ * unusable content, but a shift that lands the continuation on still
+ * non-blank, in-bounds, unrelated content is invisible to any of them --
+ * see `pushAnchorRequiredContinuation` for where this is pushed, from all
+ * three places a continuation or short-form atom is processed in `scanDoc`.
+ * Unlike `anchor-required`, there is no "already carries one" escape here:
+ * a continuation is structurally anchor-less regardless of whether its
+ * governing full citation has an anchor, so this fires unconditionally
+ * once the same exemptions (reserved citing doc, `requireAnchors.allow`
+ * matched against the GOVERNING citation's citedPath) clear. The remedy is
+ * always the same: lift the continuation into its own full,
+ * `path:N-M#anchor` citation.
+ */
+/**
+ * True when `citedPath` (the citation's raw, as-written path text) matches
+ * one of `patterns`: an exact string match, or a glob with `*` (any run of
+ * characters) and `?` (any single character) as the only wildcards -- the
+ * minimal shape needed for `requireAnchors.allow`'s own documented example
+ * (`["README.md", "INSTALL-AGENT.md"]`), not a general-purpose glob engine.
+ */
+function matchesAllowPattern(citedPath, patterns) {
+    return patterns.some((pattern) => {
+        if (!pattern.includes("*") && !pattern.includes("?")) {
+            return pattern === citedPath;
+        }
+        const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        const reSource = "^" + escaped.replace(/\*/g, ".*").replace(/\?/g, ".") + "$";
+        return new RegExp(reSource).test(citedPath);
+    });
+}
 const ANCHOR_HEADING_MAX_LEVEL = 2;
 const MD_HEADING_RE = /^(#{1,6})\s+(.*)$/;
 /**
@@ -335,22 +457,73 @@ function findEnclosingHeading(lines, startLine, fencedLines) {
     }
     return null;
 }
+// A trimmed line composed of nothing but closing brackets/braces/parens
+// plus an optional trailing `,`/`;` -- bare closing boilerplate like `}`,
+// `});`, `]);`, `}),`. Used only by `lastContentLineInRange` (opt-in
+// `anchor-not-on-last-line`, see there): a range that ends on such a line
+// (the common shape of a `});` that closes a whole cited `describe`/`it`
+// block) should not force the anchor onto that boilerplate line itself --
+// the last CONTENT line before it is the meaningful place for an anchor
+// to live.
+const CLOSING_BOILERPLATE_RE = /^[\]\)\};,]*$/;
+function isContentLine(text) {
+    const trimmed = text.trim();
+    return trimmed !== "" && !CLOSING_BOILERPLATE_RE.test(trimmed);
+}
+/**
+ * The last line number (1-based, within `[startLine, endLine]`) whose text
+ * is a "content" line -- see `isContentLine`. Walks backward from `endLine`
+ * so a range ending on one or more bare closing-boilerplate lines (`});`,
+ * `]);`, `}),`, a lone `}`) resolves to the real content line before them
+ * instead of the boilerplate itself. Falls back to `endLine` unchanged when
+ * every line in the range is boilerplate or blank (nothing better to
+ * anchor against).
+ */
+function lastContentLineInRange(lines, startLine, endLine) {
+    for (let ln = endLine; ln >= startLine; ln--) {
+        if (isContentLine(lines[ln - 1] ?? ""))
+            return ln;
+    }
+    return endLine;
+}
 /**
  * Checks an anchored full citation's anchor against its already-resolved,
  * already-range-checked target -- see the "Anchored citations" doc block
  * above for the two forms' semantics. `endLine` is the citation's end line,
  * or its start line for a single-line citation (a size-1 range).
  */
-function checkAnchor(anchor, startLine, endLine, lines) {
+function checkAnchor(anchor, startLine, endLine, lines, requireAnchors) {
     if (anchor.kind === "string") {
+        let count = 0;
+        let lastMatchLine = -1;
         for (let i = startLine - 1; i <= endLine - 1 && i < lines.length; i++) {
-            if ((lines[i] ?? "").includes(anchor.text))
-                return null;
+            if ((lines[i] ?? "").includes(anchor.text)) {
+                count++;
+                lastMatchLine = i + 1;
+            }
         }
-        return {
-            rule: "anchor-not-found-in-range",
-            message: `anchor "${anchor.text}" does not occur in the cited range (${startLine}-${endLine})`,
-        };
+        if (count === 0) {
+            return {
+                rule: "anchor-not-found-in-range",
+                message: `anchor "${anchor.text}" does not occur in the cited range (${startLine}-${endLine})`,
+            };
+        }
+        if (requireAnchors) {
+            if (count > 1) {
+                return {
+                    rule: "anchor-not-unique-in-range",
+                    message: `anchor "${anchor.text}" occurs on ${count} lines of the cited range (${startLine}-${endLine}); expected exactly one`,
+                };
+            }
+            const lastContentLine = lastContentLineInRange(lines, startLine, endLine);
+            if (lastMatchLine !== lastContentLine) {
+                return {
+                    rule: "anchor-not-on-last-line",
+                    message: `anchor "${anchor.text}" occurs on line ${lastMatchLine}, not the cited range's last content line (${lastContentLine})`,
+                };
+            }
+        }
+        return null;
     }
     const fencedLines = computeFencedLineIndices(lines);
     const heading = findEnclosingHeading(lines, startLine, fencedLines);
@@ -379,7 +552,90 @@ function checkAnchor(anchor, startLine, endLine, lines) {
     }
     return null;
 }
-const CITATION_RE = /([\w./-]+\.(?:ts|js|mjs|md|yml|yaml|json)):(\d+)(?:-(\d+))?(?:#(\[?\w(?:[\w.-]*\w)?\]?|"[^"\n`]*"))?/g;
+// Exported so `prose-line-references` (see src/rules/prose-line-references.ts)
+// can exclude a real citations-resolve citation span from its own
+// extraction, rather than re-deriving this grammar itself.
+export const CITATION_RE = /([\w./-]+\.(?:ts|js|mjs|md|yml|yaml|json)):(\d+)(?:-(\d+))?(?:#(\[?\w(?:[\w.-]*\w)?\]?|"[^"\n`]*"))?/g;
+/**
+ * Heading-section citations. A CHANGELOG.md that grows by insertion at the
+ * top forces every later `path:N-M#anchor` citation to be re-pointed on
+ * every release, even with the heading anchor above closing the "wrong
+ * section" gap -- the line RANGE itself still drifts on every insertion,
+ * so the citation still needs editing, just not silently mis-validated.
+ * `path:#heading` sidesteps line numbers entirely: it names a heading
+ * (matched the same way the line-range anchor above already matches one,
+ * `heading.text.includes(...)`, reused rather than re-invented -- see
+ * `parseAnchor`/`findHeadingSection`) and resolves to that heading's own
+ * section (from the line after the heading up to, but not including, the
+ * next heading of the same or shallower level, or EOF) -- see
+ * `findHeadingSection`. The section must exist (`heading-section-not-found`
+ * when no such heading is found), must be unambiguous (more than one
+ * matching heading is `heading-section-ambiguous`, never silently the
+ * first hit -- the same posture `unresolved-ambiguous` already takes for
+ * path resolution), and must not be empty (`heading-section-empty`).
+ *
+ * Deliberately reuses `ANCHOR_HEADING_MAX_LEVEL` (2), not a second cap: the
+ * same Keep-a-Changelog nesting that motivates the line-range anchor's cap
+ * (`## [x.y.z]` release headings around identically-named, per-release
+ * `### Added`/`### Changed`/`### Fixed` subsections) means a level-3+
+ * heading name is *never* unique across a real CHANGELOG anyway --
+ * matching it would just turn every such citation into a guaranteed
+ * `heading-section-ambiguous`. Capping the search at level 2 keeps this
+ * form usable for exactly the case it exists for (a release section) and
+ * behaves identically to the line-range anchor for the same reason.
+ *
+ * Optional content anchor: `path:#heading#"text"`, always the quoted form
+ * (a section's body is prose/content, not a second heading to look up) --
+ * the text must occur on EXACTLY one line inside the resolved section
+ * (`heading-section-content-anchor-not-found` / `-ambiguous`), stricter
+ * than the line-range string anchor's "at least one line" (`checkAnchor`'s
+ * string branch): a whole section is a much larger haystack than a
+ * caller-chosen line range, so "present somewhere" is far weaker evidence
+ * the anchor still points at the intended spot, and "found on exactly one
+ * line" is what the task this form was built for (pinning a citation to
+ * one prose sentence inside a growing section) actually needs. The heading
+ * position itself keeps only the bare/bracketed form (`#heading`/
+ * `#[heading]`); the quoted alternative is reserved for the content anchor
+ * position so the two can never be confused by shape alone.
+ *
+ * Backtick-delimited, unlike the line-range form above (which does not
+ * require backticks -- see the "Anchor syntax note" in the README). This
+ * is a deliberate, narrower grammar for this form specifically: a bare
+ * `path#heading` (the grammar this form used in an earlier round) is
+ * indistinguishable from an ordinary Markdown link's target, which
+ * commonly has exactly that shape (`[install](docs/README.md#install)`)
+ * -- unlike the line-range form (gated by a `:N` no ordinary link ever
+ * contains), there was no character available to tell a real citation
+ * apart from a relative link's href written in prose, and measuring
+ * against real bundles (see the CHANGELOG entry that introduced the
+ * `:#` form) showed the collision is not hypothetical: existing docs write
+ * `` `path#heading` `` as inline prose pointing at an unrelated anchor,
+ * each producing a spurious `heading-section-not-found`. The colon
+ * (`path:#heading`) reuses this rule's existing citation signature (a
+ * literal `:` no Markdown link fragment ever contains) instead of relying
+ * on backticks alone to do that job, and is additionally restricted to a
+ * `.md` target: a link fragment's target is always the Markdown doc it
+ * points into, never a source or config file, so a non-`.md` path with
+ * this shape is never a live citation. Requiring the whole citation
+ * inside one pair of backticks stays in place as well, matching this
+ * rule's own general recommendation for the line-range form.
+ */
+const HEADING_SECTION_CITATION_RE = /`([\w./-]+\.md):#(\[?\w(?:[\w.-]*\w)?\]?)(?:#("[^"\n`]+"))?`/g;
+/**
+ * Companion to `HEADING_SECTION_CITATION_RE`: matches the same
+ * backtick + path + `:#` opener but accepts anything up to the closing
+ * backtick, so a heading-section citation that fails to parse (an
+ * unterminated or empty content-anchor quote, an unquoted third segment,
+ * or a non-`.md` target, which includes a non-lowercase `.MD` extension) is
+ * still recognised as an *attempt* rather than
+ * silently vanishing -- mirrors `anchor-malformed`'s
+ * "still-visible-as-a-notice" posture for the line-range anchor form (see
+ * `extractMalformedAnchorRaw`). Only used for a match whose span does not
+ * already overlap a successful `HEADING_SECTION_CITATION_RE` match (see
+ * `collectHeadingSectionMatches`); a well-formed citation never also
+ * produces a malformed notice.
+ */
+const HEADING_SECTION_MALFORMED_RE = /`([\w./-]+):#([^`\n]*)`/g;
 // Continuation citation forms (see the "Continuation citations" doc block
 // above). Each requires the backtick delimiter as part of the match so it
 // can never overlap a CITATION_RE match: a full citation's regex match
@@ -404,6 +660,14 @@ const SHORT_FORM_COLON_RE = /:(\d+)-(\d+)/g;
 const TEST_FILE_RE = /\.(test|spec)\.(ts|js|mjs)$/i;
 const TEST_HEAD_LINE_RE = /^\s*(?:describe|it)\s*\(/;
 const TEST_CLOSING_LINE_RE = /^\s*\}\)\s*;\s*$/;
+// Block-head detection for test-range-straddles-block (see the doc block
+// above and checkTestRangeStraddle below): a wider set of head shapes than
+// TEST_HEAD_LINE_RE (which stays short-form-only, unchanged, via
+// checkRangeBoundary/checkShortFormTarget) -- describe/it/test, each with
+// an optional .only/.skip/.each modifier. A leading `export `/`async ` is
+// deliberately not handled: not needed for any bundle this rule has been
+// measured against.
+const TEST_BLOCK_HEAD_RE = /^\s*(?:describe|it|test)(?:\.(?:only|skip|each))?\s*\(/;
 // Markdown block-boundary check (see checkRangeBoundary): a range boundary
 // line that is nothing but a bracket (open or close), optionally with a
 // trailing `,`/`;`, is always a drift signal. A bare code-fence delimiter is
@@ -434,8 +698,13 @@ function isFile(p) {
         return false;
     }
 }
-/** True when citedPath has a literal `..` path segment. */
-function hasParentSegment(citedPath) {
+/**
+ * True when citedPath has a literal `..` path segment. Exported so
+ * `prose-line-references` rejects the same shape before ever calling
+ * `resolveCitation` on a file-mention token, matching this rule's own
+ * `path-traversal-rejected` posture.
+ */
+export function hasParentSegment(citedPath) {
     return citedPath.split("/").includes("..");
 }
 /**
@@ -538,8 +807,14 @@ function resolveViaAncestorClimb(root, docAbsPath, citedPath) {
  * plausible target exists, or `null` when nothing matches. Callers must
  * reject a citedPath with a `..` segment (see hasParentSegment) before
  * calling this; it is not re-checked here.
+ *
+ * Exported so `prose-line-references` (see
+ * src/rules/prose-line-references.ts) reuses this exact resolution order
+ * for binding a bare prose line reference to the file mention nearest it,
+ * rather than re-implementing (and risking drifting from) this rule's own
+ * path-resolution rules.
  */
-function resolveCitation(cache, root, docAbsPath, docContent, docSources, citedPath, matchIndex) {
+export function resolveCitation(cache, root, docAbsPath, docContent, docSources, citedPath, matchIndex) {
     if (citedPath.startsWith("/")) {
         return { skip: true };
     }
@@ -679,17 +954,215 @@ function checkTarget(citedPath, startLine, endLine, resolvedPath) {
  * are full-citation-only (see that doc block for why), so `checkTarget`
  * itself is untouched and still used as-is for a cont-fresh atom.
  */
-function checkFullTarget(citedPath, startLine, endLine, resolvedPath, anchor) {
+function checkFullTarget(citedPath, startLine, endLine, resolvedPath, anchor, requireAnchors) {
     const read = readTarget(resolvedPath);
     if ("rule" in read)
-        return read;
+        return [read];
     const lines = splitLines(read.content);
     const base = checkTargetLines(citedPath, startLine, endLine, lines);
     if (base)
-        return base;
-    if (!anchor)
-        return null;
-    return checkAnchor(anchor, startLine, endLine ?? startLine, lines);
+        return [base];
+    const problems = [];
+    // test-range-straddles-block, opt-in only (see "Anchor strictness
+    // (opt-in)" above and checkTestRangeStraddle): a full citation's own
+    // range into a .test./.spec. target (.ts, .js, .mjs) must not cross
+    // into another block's head after its own first line. Deliberately
+    // scoped to test-file targets only (isTestFile), not also a markdown
+    // branch: a
+    // full citation into a markdown target legitimately cites a couple of
+    // arbitrary lines all the time (e.g. two lines of a code fence example),
+    // the exact reasoning checkShortFormTarget's own doc comment already
+    // gives for why the sibling block-boundary check was scoped to
+    // short-form in the first place. Only meaningful for an actual range
+    // (endLine !== null); a single-line citation trivially starts and ends
+    // on the same line and has nothing to straddle.
+    if (requireAnchors && endLine !== null && isTestFile(citedPath)) {
+        const straddle = checkTestRangeStraddle(startLine, endLine, lines);
+        if (straddle)
+            problems.push(straddle);
+    }
+    // The anchor check is run independently of the straddle check above
+    // (not gated on it having come back clean): a straddling range and a
+    // missing/misplaced anchor are two independent problems with the same
+    // citation, and reporting only the first one found would silently drop
+    // the other from the output every time both happen to co-occur.
+    if (anchor) {
+        const anchorProblem = checkAnchor(anchor, startLine, endLine ?? startLine, lines, requireAnchors);
+        if (anchorProblem)
+            problems.push(anchorProblem);
+    }
+    return problems;
+}
+/**
+ * Every Markdown heading in `lines` up to `ANCHOR_HEADING_MAX_LEVEL`, in
+ * document order -- the whole-document counterpart of `findEnclosingHeading`
+ * (which stops at the nearest heading at or before a given line): a
+ * heading-section citation has no start line to search backward from, it
+ * needs every candidate to test for a unique match. `fencedLines` (see
+ * `computeFencedLineIndices`) excludes a `#`-led line inside a fenced
+ * example, same as `findEnclosingHeading`.
+ */
+function collectHeadingsUpToLevel(lines, fencedLines) {
+    const headings = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (fencedLines.has(i))
+            continue;
+        const m = (lines[i] ?? "").match(MD_HEADING_RE);
+        if (m && m[1].length <= ANCHOR_HEADING_MAX_LEVEL) {
+            headings.push({ level: m[1].length, text: m[2].trim(), lineNo: i + 1 });
+        }
+    }
+    return headings;
+}
+/**
+ * Resolves a heading-section citation's heading text to a single section:
+ * every level <= `ANCHOR_HEADING_MAX_LEVEL` heading whose text contains
+ * `headingText` (same containment check `checkAnchor`'s heading branch
+ * already uses -- reused, not reinvented) is a candidate; zero is
+ * `not-found`, more than one is `ambiguous` (never silently the first
+ * match), exactly one resolves to the section running from the line right
+ * after the heading up to (not including) the next heading at or above the
+ * same level, or EOF -- the same enclosure boundary `checkAnchor`'s heading
+ * branch walks forward to check, just producing a body range here instead
+ * of a pass/fail against an already-known end line.
+ */
+function findHeadingSection(lines, fencedLines, headingText) {
+    const headings = collectHeadingsUpToLevel(lines, fencedLines);
+    const matches = headings.filter((h) => h.text.includes(headingText));
+    if (matches.length === 0)
+        return { kind: "not-found" };
+    if (matches.length > 1)
+        return { kind: "ambiguous", matches };
+    const heading = matches[0];
+    let bodyEnd = lines.length;
+    for (let i = heading.lineNo; i < lines.length; i++) {
+        if (fencedLines.has(i))
+            continue;
+        const m = (lines[i] ?? "").match(MD_HEADING_RE);
+        if (m && m[1].length <= heading.level) {
+            bodyEnd = i;
+            break;
+        }
+    }
+    return { kind: "found", heading, bodyStart: heading.lineNo, bodyEnd };
+}
+/** True when every line in `[bodyStart, bodyEnd)` is empty or whitespace-only. */
+function isSectionEmpty(lines, bodyStart, bodyEnd) {
+    for (let i = bodyStart; i < bodyEnd; i++) {
+        if ((lines[i] ?? "").trim() !== "")
+            return false;
+    }
+    return true;
+}
+/**
+ * Count of lines in `[bodyStart, bodyEnd)` containing `text` -- a heading
+ * section's content anchor must occur on exactly one such line (see the
+ * "Heading-section citations" doc block above for why this is stricter
+ * than the line-range string anchor's "at least one line").
+ */
+function countAnchorOccurrences(lines, bodyStart, bodyEnd, text) {
+    let count = 0;
+    for (let i = bodyStart; i < bodyEnd; i++) {
+        if ((lines[i] ?? "").includes(text))
+            count++;
+    }
+    return count;
+}
+/**
+ * A heading-section citation's complete target check (see the
+ * "Heading-section citations" doc block above): the named heading must
+ * exist exactly once, its section must be non-empty, and, when a content
+ * anchor was given, it must occur on exactly one line inside that section.
+ * One problem per citation, checked in that order, matching every other
+ * check in this file's "base checks first" pattern.
+ */
+function checkHeadingSectionTarget(headingAnchor, contentAnchor, resolvedPath) {
+    const read = readTarget(resolvedPath);
+    if ("rule" in read)
+        return read;
+    const lines = splitLines(read.content);
+    const fencedLines = computeFencedLineIndices(lines);
+    const section = findHeadingSection(lines, fencedLines, headingAnchor.text);
+    if (section.kind === "not-found") {
+        return {
+            rule: "heading-section-not-found",
+            message: `no heading (level <= ${ANCHOR_HEADING_MAX_LEVEL}) contains "${headingAnchor.text}"`,
+        };
+    }
+    if (section.kind === "ambiguous") {
+        return {
+            rule: "heading-section-ambiguous",
+            message: `${section.matches.length} headings contain "${headingAnchor.text}" (lines ${section.matches
+                .map((m) => m.lineNo)
+                .join(", ")}); not evaluated`,
+        };
+    }
+    if (isSectionEmpty(lines, section.bodyStart, section.bodyEnd)) {
+        return {
+            rule: "heading-section-empty",
+            message: `section under heading "${section.heading.text}" (line ${section.heading.lineNo}) has no non-blank content before the next heading`,
+        };
+    }
+    if (contentAnchor) {
+        const count = countAnchorOccurrences(lines, section.bodyStart, section.bodyEnd, contentAnchor.text);
+        if (count === 0) {
+            return {
+                rule: "heading-section-content-anchor-not-found",
+                message: `content anchor "${contentAnchor.text}" does not occur in the section under heading "${section.heading.text}"`,
+            };
+        }
+        if (count > 1) {
+            return {
+                rule: "heading-section-content-anchor-ambiguous",
+                message: `content anchor "${contentAnchor.text}" occurs on ${count} lines in the section under heading "${section.heading.text}"; expected exactly one`,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Every well-formed heading-section citation in `content`, in document
+ * order. Collected once, up front (before `CITATION_RE`'s own scan in
+ * `scanDoc`), so its match spans can gate both `CITATION_RE` (a full
+ * citation never fires inside a heading-section citation's own quoted
+ * content anchor, see the "Heading-section citations" doc block above) and
+ * the malformed companion scan (see `collectHeadingSectionMalformedMatches`)
+ * without re-deriving the same spans twice.
+ */
+function collectHeadingSectionMatches(content) {
+    const out = [];
+    const re = new RegExp(HEADING_SECTION_CITATION_RE.source, HEADING_SECTION_CITATION_RE.flags);
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        out.push({
+            index: m.index,
+            end: m.index + m[0].length,
+            citedPath: m[1],
+            headingAnchor: parseAnchor(m[2]), // group 2 is mandatory
+            contentAnchor: parseAnchor(m[3]),
+        });
+    }
+    return out;
+}
+/**
+ * Every backtick + path + `:#` opener in `content` that did NOT parse as a
+ * well-formed heading-section citation (see `HEADING_SECTION_MALFORMED_RE`'s
+ * doc comment) -- an unterminated content-anchor quote, an unquoted third
+ * segment, or a non-`.md` target. `wellFormedSpans` (from
+ * `collectHeadingSectionMatches`) gates out any match that is really just
+ * the successful citation seen from the outside; a well-formed citation
+ * never also produces a malformed notice.
+ */
+function collectHeadingSectionMalformedMatches(content, wellFormedSpans) {
+    const out = [];
+    const re = new RegExp(HEADING_SECTION_MALFORMED_RE.source, "g");
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        if (isWithinAnySpan(m.index, wellFormedSpans))
+            continue;
+        out.push({ index: m.index, end: m.index + m[0].length, raw: m[0] });
+    }
+    return out;
 }
 // A cont-ext atom only ever extends the *end* of a range whose start line
 // was already fully checked (blank / closing-brace) when it was cited as
@@ -839,6 +1312,53 @@ function checkRangeBoundary(citedPath, startLine, endLine, lines) {
     }
     return null;
 }
+/**
+ * Width (in characters) of `text`'s leading run of spaces/tabs -- used by
+ * `checkTestRangeStraddle` to tell a NESTED block head (indented deeper
+ * than the range's own start line) apart from a SIBLING or OUTER one
+ * (indented the same or shallower): citing a whole `describe` block
+ * necessarily contains every `it(`/nested-`describe(` head inside its own
+ * body, and those are not straddling anywhere, they are exactly what the
+ * citation is about.
+ */
+function leadingWhitespaceWidth(text) {
+    return (text.match(/^[ \t]*/) ?? [""])[0].length;
+}
+/**
+ * `test-range-straddles-block` (opt-in, warning): a FULL citation's own
+ * range into a `.test.`/`.spec.` target (`.ts`, `.js`, `.mjs`), see the
+ * "Anchor strictness (opt-in)" doc block above for the full rule text.
+ * Checks every line of `[startLine, endLine]` EXCEPT the range's own
+ * first line (`startLine`
+ * itself is never checked -- see that doc block for why) against
+ * `TEST_BLOCK_HEAD_RE`; the first hit (in document order) is reported,
+ * matching this file's "one problem per citation" pattern. A block-head
+ * line indented STRICTLY DEEPER than the range's own start line is a
+ * NESTED block (e.g. the `it(`s inside a `describe(` the range cites in
+ * full) and is skipped, not reported: a citation covering a whole block is
+ * expected to contain every head line nested inside it. A block-head line
+ * at the same or a shallower indent is a SIBLING or OUTER block and is
+ * still reported -- this is an approximation of "which block scope is
+ * this line lexically in" using indentation instead of a real AST, chosen
+ * because it reproduces the AST-based reference verdict on every straddle
+ * finding this rule has been measured against; a file that mixes tabs and
+ * spaces, or that does not indent nested blocks at all, can defeat it.
+ */
+function checkTestRangeStraddle(startLine, endLine, lines) {
+    const startIndent = leadingWhitespaceWidth(lines[startLine - 1] ?? "");
+    for (let i = startLine; i <= endLine - 1 && i < lines.length; i++) {
+        const text = lines[i] ?? "";
+        if (!TEST_BLOCK_HEAD_RE.test(text))
+            continue;
+        if (leadingWhitespaceWidth(text) > startIndent)
+            continue; // nested block
+        return {
+            rule: "test-range-straddles-block",
+            message: `range straddles into another block's head at line ${i + 1} ("${text.trim()}")`,
+        };
+    }
+    return null;
+}
 /**
  * A short-form citation's full check: checkTarget's existing checks
  * (unreadable-target, inverted-range, range-exceeds-file, blank-start-line,
@@ -891,6 +1411,7 @@ function collectContinuationAtoms(content) {
                 kind: "cont-ext",
                 index: m.index,
                 value: m[2] ? Number(m[2]) : Number(m[1]),
+                raw: m[0],
             });
         }
         else {
@@ -899,12 +1420,18 @@ function collectContinuationAtoms(content) {
                 index: m.index,
                 startLine: Number(m[1]),
                 endLine: m[2] ? Number(m[2]) : null,
+                raw: m[0],
             });
         }
     }
     const dashRe = new RegExp(CONT_DASH_RE.source, "g");
     while ((m = dashRe.exec(content)) !== null) {
-        atoms.push({ kind: "cont-ext", index: m.index, value: Number(m[1]) });
+        atoms.push({
+            kind: "cont-ext",
+            index: m.index,
+            value: Number(m[1]),
+            raw: m[0],
+        });
     }
     const parenRe = new RegExp(CONT_PAREN_RE.source, "g");
     while ((m = parenRe.exec(content)) !== null) {
@@ -913,6 +1440,7 @@ function collectContinuationAtoms(content) {
             index: m.index,
             startLine: Number(m[1]),
             endLine: null,
+            raw: m[0],
         });
     }
     return atoms;
@@ -966,8 +1494,16 @@ function collectShortFormMatches(content, excludedSpans) {
  * `scanFenceLines` (see there): per-line fenced/opens/closes state is
  * converted to char-offset spans by tracking each line's `[start, end)`
  * offset in `content` alongside it.
+ *
+ * Exported (with computeIndentedCodeSpans and computeTableRowSpans below)
+ * so `prose-line-references` can build its OWN excluded-span set for file
+ * mentions that leaves out computeInlineCodeSpans -- a bare backtick-
+ * wrapped filename (`` `src/cli.ts` ``) is the normal, encouraged way to
+ * write a file mention in prose, unlike a short-form bare number, so it
+ * must NOT be excluded from mention detection the way it is excluded from
+ * short-form citation matching here.
  */
-function computeFencedSpans(content) {
+export function computeFencedSpans(content) {
     const spans = [];
     const lines = content.split("\n");
     const states = scanFenceLines(lines);
@@ -998,7 +1534,7 @@ function computeFencedSpans(content) {
  * spec (no list-item-context awareness); adequate for this mechanical,
  * warn-only rule.
  */
-function computeIndentedCodeSpans(content) {
+export function computeIndentedCodeSpans(content) {
     const spans = [];
     const lines = content.split("\n");
     let offset = 0;
@@ -1069,7 +1605,7 @@ function computeInlineCodeSpans(content) {
  * and can otherwise carry a range shape the gate would not reject (e.g.
  * `| col (5-9) |`).
  */
-function computeTableRowSpans(content) {
+export function computeTableRowSpans(content) {
     const spans = [];
     const lines = content.split("\n");
     let offset = 0;
@@ -1090,8 +1626,13 @@ function computeTableRowSpans(content) {
  * per doc and combined with fullSpans (see scanDoc) via the existing
  * isWithinAnySpan helper -- the same mechanism a full citation's own span
  * already uses, not a second one.
+ *
+ * Exported so `prose-line-references` excludes the identical set of spans
+ * from its own extraction (a code-fenced or inline-code "line N" is a code
+ * example, not a live prose reference), rather than maintaining a second,
+ * possibly-drifting copy of "what counts as excluded prose".
  */
-function computeExcludedSpans(content) {
+export function computeExcludedSpans(content) {
     return [
         ...computeFencedSpans(content),
         ...computeIndentedCodeSpans(content),
@@ -1102,8 +1643,13 @@ function computeExcludedSpans(content) {
 /**
  * Paragraph-start offsets in `content`, ascending, always including 0. A
  * paragraph boundary is a blank (empty or whitespace-only) line.
+ *
+ * Exported (with paragraphStartFor below) so `prose-line-references` binds
+ * against the same notion of "paragraph" this rule already uses for
+ * short-form citation binding, instead of a second, possibly-inconsistent
+ * definition.
  */
-function computeParagraphStarts(content) {
+export function computeParagraphStarts(content) {
     const starts = [0];
     const re = /\n[ \t]*\n+/g;
     let m;
@@ -1113,7 +1659,7 @@ function computeParagraphStarts(content) {
     return starts;
 }
 /** The start offset of the paragraph containing `index` (see computeParagraphStarts). */
-function paragraphStartFor(starts, index) {
+export function paragraphStartFor(starts, index) {
     let result = starts[0];
     for (const s of starts) {
         if (s > index)
@@ -1164,6 +1710,40 @@ function pushUnreadable(findings, file, citation, resolvedTo, code) {
         detail: `resolvedTo: ${resolvedTo}, errorCode: ${code}`,
     });
 }
+/**
+ * `anchor-required-continuation` (opt-in, `--require-anchors`, warning):
+ * see the "Anchor strictness (opt-in)" doc block above. A continuation
+ * atom (cont-fresh or cont-ext, any of the three backtick forms, or a
+ * paragraph-bound short-form `:N-M`) is structurally anchor-less by
+ * construction -- see the "Continuation citations" doc block -- so
+ * unlike `anchor-required` there is no "already carries one" escape: this
+ * fires once its governing citation resolved in-repo, REGARDLESS of
+ * whether that governing full citation itself carries an anchor (an
+ * anchor on the full citation does not extend to a later continuation of
+ * it). Exemptions mirror `anchor-required`'s exactly: the caller already
+ * folds the reserved-citing-doc carve-out into `requireAnchorsForDoc`
+ * (undefined for a reserved doc), and `requireAnchors.allow` is matched
+ * here against `governing.citedPath` -- the path the continuation is
+ * chained to, since a continuation carries no path of its own to match
+ * against.
+ */
+function pushAnchorRequiredContinuation(findings, file, citation, raw, governing, requireAnchorsForDoc, root) {
+    if (!requireAnchorsForDoc ||
+        matchesAllowPattern(governing.citedPath, requireAnchorsForDoc.allow)) {
+        return;
+    }
+    const governingRange = `${governing.citedPath}:${governing.startLine}${governing.endLine ? "-" + governing.endLine : ""}`;
+    // "chained to" rather than "extends": for a cont-ext that itself chains
+    // off an earlier cont-fresh (not the original full citation), the range
+    // it literally extends is the cont-fresh's own range, not `governing`'s
+    // -- `governing` (see the loop above) always carries the ORIGINAL full
+    // citation's own startLine/endLine, unchanged across intervening
+    // cont-fresh atoms. Naming it "the governing citation" is honest for
+    // every caller (cont-ext, cont-fresh, and the short-form call site
+    // below) without having to thread the true immediate antecedent range
+    // through here.
+    pushDrift(findings, file, citation, "anchor-required-continuation", `continuation ${raw} is chained to the governing citation \`${governingRange}\`; a continuation cannot carry its own #anchor, lift it into a full \`path:N-M#anchor\` citation (--require-anchors is on)`, path.relative(root, governing.resolvedPath));
+}
 /**
  * True when a `CITATION_RE` match at `matchIndex` is the phantom tail of a
  * filename hard-wrapped across a line break (see the "Hard-wrapped prose"
@@ -1223,11 +1803,36 @@ function extractMalformedAnchorRaw(content, hashIndex) {
     }
     return content.slice(from, end);
 }
-function scanDoc(cache, root, bundleDir, doc) {
+function scanDoc(cache, root, bundleDir, doc, requireAnchors) {
     const findings = [];
     const content = doc.raw;
     const sources = getValidSources(doc.frontmatter.parsed) ?? [];
     const docAbsPath = path.join(bundleDir, doc.relPath);
+    // The four `--require-anchors` opt-in checks (anchor-required,
+    // anchor-not-on-last-line, anchor-not-unique-in-range,
+    // test-range-straddles-block) are all exempt for a reserved citing doc
+    // (index.md/log.md, see doc.isReserved), the same carve-out this rule
+    // already gives reserved docs for short-form matching: an append-only
+    // narrative journal routinely narrates historical line-number deltas as
+    // prose about the past, not live citations against current content.
+    // Threaded as `undefined` here (rather than a second boolean everywhere
+    // `requireAnchors` is read) so every opt-in check downstream stays gated
+    // on the exact same "is this option object present" test it already
+    // uses for the non-reserved case.
+    const requireAnchorsForDoc = doc.isReserved ? undefined : requireAnchors;
+    // Heading-section citations (well-formed and malformed) are collected up
+    // front so their char spans can gate the `CITATION_RE` scan below: a
+    // `CITATION_RE` match landing inside a heading-section citation's own
+    // quoted content anchor (e.g. `` `x.md:#2.0.0#"see other.md:12 now"` ``)
+    // is not a second, independent citation -- it is text the heading-section
+    // citation already owns. Reused again lower down for the heading-section
+    // findings themselves, rather than re-scanning by regex a second time.
+    const headingSectionMatches = collectHeadingSectionMatches(content);
+    const headingSectionSpans = headingSectionMatches.map((hs) => [hs.index, hs.end]);
+    const headingSectionMalformedMatches = collectHeadingSectionMalformedMatches(content, headingSectionSpans);
+    for (const hm of headingSectionMalformedMatches) {
+        headingSectionSpans.push([hm.index, hm.end]);
+    }
     const fullAtoms = [];
     // Char spans of every matched full citation, used to keep short-form
     // matching (see collectShortFormMatches) from re-matching the tail of a
@@ -1238,6 +1843,8 @@ function scanDoc(cache, root, bundleDir, doc) {
     while ((m = re.exec(content)) !== null) {
         if (isWrappedPathContinuation(content, m.index))
             continue;
+        if (isWithinAnySpan(m.index, headingSectionSpans))
+            continue;
         const matchEnd = m.index + m[0].length;
         // anchor-malformed detection (see the atom-processing loop below for
         // where the finding is actually pushed): a `#` immediately follows the
@@ -1267,9 +1874,13 @@ function scanDoc(cache, root, bundleDir, doc) {
     const atoms = [...fullAtoms, ...collectContinuationAtoms(content)].sort((a, b) => a.index - b.index);
     // `governing`: nearest preceding citation (full or continuation) that
     // resolved to a real file; see the "Continuation citations" doc block
-    // above for the reset rules. `lastStartLine`: the start line a "cont-ext"
-    // atom extends into a range; tracks the most recent full or cont-fresh
-    // atom's own startLine, scoped together with `governing`.
+    // above for the reset rules. Carries the ORIGINAL full citation's own
+    // startLine/endLine (not the extended range a later cont-ext might grow
+    // into) so `anchor-required-continuation` (see `pushAnchorRequiredContinuation`
+    // above) can name "the governing citation" the same way it was actually
+    // written. `lastStartLine`: the start line a "cont-ext" atom extends into
+    // a range; tracks the most recent full or cont-fresh atom's own
+    // startLine, scoped together with `governing`.
     let governing = null;
     let lastStartLine = null;
     for (const atom of atoms) {
@@ -1277,6 +1888,7 @@ function scanDoc(cache, root, bundleDir, doc) {
             if (!governing || lastStartLine === null)
                 continue; // nothing to extend
             const citation = `${governing.citedPath}:${lastStartLine}-${atom.value} (continuation)`;
+            pushAnchorRequiredContinuation(findings, doc.relPath, citation, atom.raw, governing, requireAnchorsForDoc, root);
             const problem = checkRangeBoundOnly(lastStartLine, atom.value, governing.resolvedPath);
             if (problem?.rule === "unreadable-target") {
                 pushUnreadable(findings, doc.relPath, citation, path.relative(root, governing.resolvedPath), problem.code ?? "UNKNOWN");
@@ -1291,6 +1903,7 @@ function scanDoc(cache, root, bundleDir, doc) {
                 continue; // nothing to validate a bare continuation against
             const { startLine, endLine } = atom;
             const citation = `${governing.citedPath}:${startLine}${endLine ? "-" + endLine : ""} (continuation)`;
+            pushAnchorRequiredContinuation(findings, doc.relPath, citation, atom.raw, governing, requireAnchorsForDoc, root);
             const problem = checkTarget(governing.citedPath, startLine, endLine, governing.resolvedPath);
             if (problem?.rule === "unreadable-target") {
                 pushUnreadable(findings, doc.relPath, citation, path.relative(root, governing.resolvedPath), problem.code ?? "UNKNOWN");
@@ -1345,15 +1958,80 @@ function scanDoc(cache, root, bundleDir, doc) {
         if (atom.malformedAnchorRaw !== null) {
             pushDrift(findings, doc.relPath, citation, "anchor-malformed", `a "#" follows the citation's range but does not parse as a heading or string anchor (raw: "${atom.malformedAnchorRaw}")`, undefined, "notice");
         }
-        const problem = checkFullTarget(citedPath, startLine, endLine, resolution.path, anchor);
+        // anchor-required (opt-in, warning): see the "Anchor strictness
+        // (opt-in)" doc block above. Gated on the same posture every other
+        // per-atom check already uses (only reached once the citation resolved
+        // to a real, unambiguous, non-skipped target), plus a reserved citing
+        // doc (e.g. log.md, folded into requireAnchorsForDoc above) and an
+        // allowlisted citedPath being exempt.
+        if (requireAnchorsForDoc &&
+            !anchor &&
+            !matchesAllowPattern(citedPath, requireAnchorsForDoc.allow)) {
+            pushDrift(findings, doc.relPath, citation, "anchor-required", `full citation into an in-repo file carries no #anchor (--require-anchors is on)`, path.relative(root, resolution.path));
+        }
+        const problems = checkFullTarget(citedPath, startLine, endLine, resolution.path, anchor, requireAnchorsForDoc);
+        for (const problem of problems) {
+            if (problem.rule === "unreadable-target") {
+                pushUnreadable(findings, doc.relPath, citation, path.relative(root, resolution.path), problem.code ?? "UNKNOWN");
+            }
+            else {
+                pushDrift(findings, doc.relPath, citation, problem.rule, problem.message, path.relative(root, resolution.path));
+            }
+        }
+        governing = {
+            citedPath,
+            resolvedPath: resolution.path,
+            startLine,
+            endLine,
+        };
+        lastStartLine = startLine;
+    }
+    // Heading-section citations -- see the "Heading-section citations" doc
+    // block above. Independent of `governing`/`lastStartLine`/`fullAtoms`:
+    // this form carries its own path on every citation (never a continuation
+    // or short form), so there is nothing to chain off. Iterates over
+    // `headingSectionMatches`, collected up front (see above), rather than
+    // re-scanning `content` with the regex a second time.
+    for (const hs of headingSectionMatches) {
+        const citedPath = hs.citedPath;
+        const headingAnchor = hs.headingAnchor;
+        const contentAnchor = hs.contentAnchor;
+        const citation = `${citedPath}:${formatAnchorForLabel(headingAnchor)}${contentAnchor ? formatAnchorForLabel(contentAnchor) : ""}`;
+        if (hasParentSegment(citedPath)) {
+            pushDrift(findings, doc.relPath, citation, "path-traversal-rejected", `citedPath contains a ".." segment and was rejected without resolving: ${citedPath}`);
+            continue;
+        }
+        const resolution = resolveCitation(cache, root, docAbsPath, content, sources, citedPath, hs.index);
+        if (!resolution) {
+            pushDrift(findings, doc.relPath, citation, "missing-file", `could not resolve ${citedPath}: tried doc sources, ancestor climb (bare filenames only), repo-root, doc-relative, nearest prior qualified mention, repo-wide search; no candidate file exists`);
+            continue;
+        }
+        if ("skip" in resolution)
+            continue;
+        if ("ambiguous" in resolution) {
+            pushAmbiguous(findings, doc.relPath, citation, resolution.candidates);
+            continue;
+        }
+        const problem = checkHeadingSectionTarget(headingAnchor, contentAnchor, resolution.path);
         if (problem?.rule === "unreadable-target") {
             pushUnreadable(findings, doc.relPath, citation, path.relative(root, resolution.path), problem.code ?? "UNKNOWN");
         }
         else if (problem) {
             pushDrift(findings, doc.relPath, citation, problem.rule, problem.message, path.relative(root, resolution.path));
         }
-        governing = { citedPath, resolvedPath: resolution.path };
-        lastStartLine = startLine;
+    }
+    // heading-section-malformed (notice): a backtick + path + `:#` opener
+    // that did not parse as a well-formed heading-section citation above --
+    // mirrors `anchor-malformed`'s posture for the line-range anchor form
+    // (see `extractMalformedAnchorRaw`'s doc comment): a typo should not
+    // silently vanish from the very check it was written to exercise.
+    for (const hm of headingSectionMalformedMatches) {
+        // `hm.raw` includes the delimiting backticks (the regex match itself);
+        // the citation label, like every other citation label in this file,
+        // does not repeat them -- pushDrift's message template already wraps
+        // the label in its own pair.
+        const inner = hm.raw.slice(1, -1);
+        pushDrift(findings, doc.relPath, inner, "heading-section-malformed", `a backtick-delimited "path:#" heading-section citation opener does not parse as a well-formed citation (raw: "${inner}")`, undefined, "notice");
     }
     // Short-form (paragraph-bound) citations -- see that doc block above.
     // Deliberately independent of `governing`/`lastStartLine`: short-form
@@ -1381,6 +2059,8 @@ function scanDoc(cache, root, bundleDir, doc) {
                 namedFullAtoms.push({
                     index: a.index,
                     citedPath: a.citedPath,
+                    startLine: a.startLine,
+                    endLine: a.endLine,
                 });
             }
         }
@@ -1410,6 +2090,27 @@ function scanDoc(cache, root, bundleDir, doc) {
                 pushAmbiguous(findings, doc.relPath, citation, resolution.candidates);
                 continue;
             }
+            // anchor-required-continuation (opt-in, warning) also applies to a
+            // bound short-form citation: it is just as anchor-less as a
+            // backtick continuation (see the "Short-form citations" doc block
+            // above), for the identical reason -- a bound short form cannot
+            // carry an anchor either, so it is flagged as well, rather than
+            // left as a silent gap in `--require-anchors`.
+            //
+            // `raw` here is synthesized from the parsed startLine/endLine
+            // (`:${rangeLabel}`) rather than carried from the match itself --
+            // `ShortFormMatch` (see there) does not retain the matched text.
+            // This is exact for `SHORT_FORM_COLON_RE` (`/:(\d+)-(\d+)/`) as
+            // written today, since re-stringifying the two captured numbers
+            // reproduces the source bytes; it would stop being exact if that
+            // regex ever tolerated something re-stringifying can't round-trip
+            // (e.g. a leading zero).
+            pushAnchorRequiredContinuation(findings, doc.relPath, citation, `:${rangeLabel}`, {
+                citedPath: targetPath,
+                resolvedPath: resolution.path,
+                startLine: target.startLine,
+                endLine: target.endLine,
+            }, requireAnchorsForDoc, root);
             const problem = checkShortFormTarget(targetPath, sf.startLine, sf.endLine, resolution.path);
             if (problem?.rule === "unreadable-target") {
                 pushUnreadable(findings, doc.relPath, citation, path.relative(root, resolution.path), problem.code ?? "UNKNOWN");
@@ -1423,7 +2124,7 @@ function scanDoc(cache, root, bundleDir, doc) {
 }
 export const citationsResolveRule = {
     id: RULE_ID,
-    description: "`path:N`/`path:N-M` citations (and their `:N`, -`M`/–`M`, (`N`) continuations) must resolve to a real target file and land on real, non-blank content. Mechanical only: does not verify the cited line is semantically correct.",
+    description: "`path:N`/`path:N-M` citations (and their `:N`, -`M`/–`M`, (`N`) continuations), and backtick-delimited `` `path:#heading` `` heading-section citations (`.md` targets only), must resolve to a real target file and land on real, non-blank content. Mechanical only: does not verify the cited line is semantically correct.",
     run(ctx) {
         if (!ctx.repoRoot) {
             // Never silently skip: mirrors sources-fresh's posture so a "clean"
@@ -1442,7 +2143,7 @@ export const citationsResolveRule = {
         // Fresh per invocation: see findByBasename's doc comment for why this
         // is not held at module scope.
         const cache = new Map();
-        return ctx.docs.flatMap((doc) => scanDoc(cache, root, ctx.bundleDir, doc));
+        return ctx.docs.flatMap((doc) => scanDoc(cache, root, ctx.bundleDir, doc, ctx.requireAnchors));
     },
 };
 //# sourceMappingURL=citations-resolve.js.map