okf-kit 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,297 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-06
+
+### Added
+
+- A new rule, `sources-fresh-future`, complements `sources-fresh`: it flags
+  a doc's frontmatter `timestamp` that is later than the doc file's own
+  last commit by more than a clock-skew allowance (default 10 minutes,
+  `--future-skew-minutes <n>`), catching a local wall-clock time
+  mistakenly written with a `Z`/UTC suffix it doesn't actually have.
+  Unlike `sources-fresh`, it never looks at `sources` commit times, only
+  at the doc file's own git history, and it is assessed over the same doc
+  population (a validly-shaped `sources` list and a repo root available).
+  An uncommitted doc (no own commit yet) is "unknown, not flagged", the
+  same posture `sources-fresh` already takes for an untracked source path.
+  `FUTURE-DATED` findings are `warning` severity, same as `STALE`; run
+  with the existing `--strict` flag to fail the build on either, rather
+  than a second, rule-specific strictness switch. Extends
+  `src/rules/sources-fresh.ts` (shares its `getLastCommitEpoch` git
+  helper and its doc-population filter) instead of adding a parallel
+  mechanism; see the README's "Staleness (sources-fresh)" section,
+  "Future-dated timestamps (`sources-fresh-future`)" subsection, for the
+  full rule contract and how the two rules relate. Together with the
+  `sources-fresh` narrowing below, catches: a source path committed
+  after the doc's `timestamp`; a source and the doc co-committed
+  together where that commit did not re-stamp the doc; and a local
+  wall-clock time hand-written with a `Z`/UTC suffix it doesn't
+  actually have. Does NOT catch a doc-only prose edit that leaves
+  `sources` untouched and the `timestamp` stale -- neither rule has a
+  source-side signal to compare against in that case, so it stays a
+  reviewer judgment call.
+- `sources-fresh-future` skips (severity `notice`) a `timestamp` string
+  with no `Z`/UTC designator or numeric offset (e.g.
+  `2026-01-01T00:00:00`): such a string parses in the machine's own
+  local timezone under `Date.parse`, which would swing the check's
+  verdict by hours between a UTC+2 laptop and a UTC CI runner against a
+  default 10-minute allowance. A numeric offset (`+02:00`, `-0500`) is
+  unambiguous and is still assessed normally. `sources-fresh`'s own
+  thresholds are days wide, so this ambiguity does not practically
+  matter there; the gate applies only to `sources-fresh-future`.
+- CI: the agent-dx `okf-anchor-guard` job (`.github/workflows/ci.yml`)
+  gained a strict freshness step that fails the build on any
+  `sources-fresh`/`sources-fresh-future` warning for
+  `packages/orchestrator-workflow/docs/okf`. **Release dependency:**
+  `sources-fresh-future` did not exist in the okf-kit version this job
+  installed before this release (a pinned release from npm, kept in sync
+  with `package.json`'s own version by
+  `orchestrator-workflow/test/docs-consistency.test.ts`), so the step's
+  filter matched only `sources-fresh` findings until this release; the
+  job's pin moves to 0.10.0 in the same commit as every other
+  `okf-kit@<version>` pin (per this file's "Changed" entry below), so it
+  now matches both rule ids and no other change to the step is needed,
+  since it already filters by rule id rather than a fixed list.
+
+### Fixed
+
+- `sources-fresh`'s co-commit staleness exception (a source committed
+  at/before the doc file's own last commit is treated as fresh) is
+  narrowed to a commit that actually re-stamped the doc. A commit that
+  co-commits a source change with the doc (a prose edit, a typo fix)
+  WITHOUT touching the stamp no longer suppresses staleness --
+  previously this unconditional exception let exactly that case (a
+  source and the doc's prose committed together with the timestamp left
+  stale) pass silently, which was the review class this rule pair
+  exists to close. "Re-stamped" is decided by VALUE: the doc's parsed
+  frontmatter `timestamp` at that commit is compared against its value
+  in the commit's FIRST PARENT, and they must differ (a doc created
+  there, having no parent revision at all, counts as re-stamped). The
+  lookup follows a rename, so a `git mv` is not read as a creation, and
+  it reads trees rather than a patch, so a merge commit -- including the
+  `refs/pull/N/merge` ref CI checks out -- is assessed like any other
+  commit. Consequently a `timestamp:` line inside a fenced YAML example
+  in the doc's BODY is not mistaken for a re-stamp. The check answers
+  "did the value change", never "is the new value right": a hand-typed
+  or backdated stamp still counts (`sources-fresh-future` is the rule
+  that catches an implausible value), and a doc-only prose edit with
+  unchanged sources remains outside both rules' reach. When git cannot
+  answer the question at all, the doc gets one `staleness not
+  assessable` notice rather than a STALE warning or a silent pass. See
+  the README's "Staleness (sources-fresh)" section for the full contract
+  and its remaining known limitations.
+- `sources-fresh`'s re-stamp lookup no longer misjudges two more shapes
+  the value comparison above did not yet cover. (1) In a SHALLOW clone
+  (`git clone --depth`, including `actions/checkout`'s default), the
+  grafted history boundary commit reports an EMPTY parent list for every
+  path touched at or before it -- indistinguishable from a real root
+  commit by the parent-list check alone, which previously trusted it and
+  assumed "created" (re-stamped) unconditionally. The lookup now checks
+  `git rev-parse --is-shallow-repository` (once per `check` run, not per
+  doc: only spent at all when some doc's re-stamp lookup actually
+  reaches a commit with no parents) and, when the repository is shallow,
+  answers `not assessable` there instead -- see the README's "CI usage"
+  section for the `fetch-depth: 0` remedy. (2) A NON-ASCII doc path was
+  C-quoted by `git diff-tree`'s default `--name-status` output
+  (`core.quotePath` defaults to true, e.g. `"bundle/\303\266lt.md"` for
+  `bundle/ölt.md`), so the rename/created lookup's plain string match
+  against the doc's real (unquoted) path never matched, silently fell
+  through to the wrong path, and turned a normal rename or creation into
+  a `not assessable` notice instead of the real verdict. The lookup now
+  runs with `-z` (NUL-delimited, never quoted regardless of
+  `core.quotePath`) instead of the default form. New fixtures also pin:
+  an octopus merge (three parents) as a doc's last commit without a
+  re-stamp still reports STALE (only the FIRST parent is ever consulted,
+  however many there are); and a cosmetic rewrite of the stamp to the
+  same instant in another string representation (`...00Z` to
+  `...00.000Z`) still counts as a re-stamp, since the comparison is by
+  raw parsed VALUE, not by resolved instant -- while adding or removing
+  quotes around an otherwise-unchanged value does NOT count, since YAML
+  parsing already normalizes those away before the comparison ever sees
+  them.
+- `--future-skew-minutes ''` (empty or whitespace-only) is now rejected
+  as the same usage error (exit 2) a negative value already gets,
+  instead of silently accepting it as `0`.
+- The internal git runner now sets an explicit 16 MiB output cap.
+  Node's default for a synchronous child process is 1 MiB, and
+  `sources-fresh` reads whole doc blobs to compare frontmatter
+  timestamps, so a doc larger than 1 MiB previously resolved to "git
+  failed" -- and therefore to a permanent not-assessable notice -- on a
+  perfectly healthy repository.
+- CI: the `okf-anchor-guard` job's freshness step (`.github/workflows/ci.yml`)
+  now rejects any `error`-severity freshness finding too (was: only
+  `warning`), gained a self-test mirroring the neighbouring
+  Anchor-citation guard's shape (its `assert_numeric` guard included),
+  guards explicitly against a missing or malformed report before its
+  first `jq`, and runs with `if: success() || failure()` so its findings
+  surface in the same CI round as the Anchor-citation guard's rather
+  than being skipped after an anchor failure -- while, unlike
+  `always()`, staying out of the way of a cancelled run or an earlier
+  setup failure that never produced a report. The self-test step now
+  carries the same `if: success() || failure()` (it previously ran
+  unconditionally), and both it and the real step now read the SAME
+  `FRESHNESS_FILTER` jq expression from the job's `env:` rather than the
+  self-test guarding its own hand-kept copy: an edit to the real filter
+  is now exercised by the self-test, not silently bypassed by it.
+
+### Changed
+
+- The release procedure now bumps orchestrator-workflow's okf-kit pins
+  (every `npm install -g okf-kit@<version>` or `npx okf-kit@<version>`
+  occurrence under `.github/workflows/`) in the same commit as the
+  okf-kit version cut, via `scripts/bump-okf-kit-pin.mjs` (repo root,
+  supports `--dry-run`). The reason: a release PR that only cuts
+  okf-kit's own version leaves OW's docs-consistency parity guard red on
+  master, and since `publish-npm.yml` runs the tests at the tag tree, the
+  OW tag then cannot publish either. See CONTRIBUTING.md's "Releasing
+  okf-kit" section for the full order.
+
+## [0.9.0] - 2026-09-01
+
+### Added
+
+- A new opt-in rule, `prose-line-references` (`--prose-line-references`,
+  strict sub-flag `--prose-line-references-strict`), closes a gap
+  `citations-resolve` leaves open: a prose-embedded line reference written
+  outside its backtick grammar ("lines 496-498",
+  "generate-codex-config.ts lines 129-132") is structurally invisible to
+  `citations-resolve`'s `CITATION_RE`, which requires a literal `:` between
+  the path and the digits. A doc can be re-verified, re-stamped, and pass
+  `check` with 0 findings while its prose line numbers are drifted, because
+  nothing ever looked at them -- exactly what happened in harness task
+  ad66c43f (2026-08-30/31): review round 1 of that OKF sweep found 9 wrong
+  prose references behind a fresh `citations-resolve`-clean stamp, the fix
+  round's own sweep found more (including one citing the wrong file
+  entirely), and the verification round a third residue; both reviewers
+  named the missing mechanical guard as the structural cause. Extracts
+  `line N`/`lines N-M`/`lines N to M` (deliberately not `L N`, a
+  comma-separated list of several numbers, or a second unlabelled range
+  chained by "vs"; see the README for the full, deliberately conservative
+  grammar), binds each to the nearest named file (same sentence first,
+  then same paragraph, reusing `citations-resolve`'s own path-resolution
+  rules verbatim rather than a second, drift-prone copy), and reports
+  `out-of-bounds`, `blank-start-line`, `unresolvable`, or `ambiguous`.
+  `--prose-line-references-strict` additionally flags EVERY extracted
+  reference (resolved or not) with the remedy: lift it into a backtick
+  anchored citation, or de-precise it to a symbol name. Off by default;
+  see "Prose line references (opt-in, `--prose-line-references`)" in the
+  README for the full grammar, binding rule, and finding table.
+
+- `prose-line-references` review-round fixes, found by a reviewer pass on
+  the rule above before it shipped: a start line of `0` no longer indexes
+  `lines[-1]` and is now its own `out-of-bounds` finding rather than a
+  misclassified `blank-start-line`; `LINE_REF_RE`'s leading `\b` no longer
+  matches right after a hyphen, so "in-line 999", "multi-line 999", and
+  "command-line 999" are no longer mis-extracted as citations to line 999;
+  a reference inside an HTML comment (`` <!-- see line 5 above --> ``) or
+  on a line that is itself a Markdown ATX heading (`## Line 3 semantics`)
+  is now excluded from extraction, the same way a fenced code block's
+  example already was; and a finding now quotes the doc's own matched text
+  verbatim (an en-dash range stays an en-dash range) instead of a
+  re-rendered, always-hyphenated approximation, with the normalised
+  hyphen-ranged form folded into the message body only when it actually
+  differs from what the doc wrote. Also closes a coverage gap the
+  reviewer found: the binding rule's paragraph-level fallback
+  (`nearestPrecedingMentionInParagraph`) and its same-sentence
+  "following mention" branch had no test that could tell them apart from
+  a hypothetical "always bind to the first mention in the paragraph"
+  mutant; see "Verification" below for the fixture and the mutation
+  check.
+
+- `citations-resolve`: a fifth `--require-anchors` check,
+  `anchor-required-continuation` (warning), closes a gap the four checks
+  added in 0.8.0 left open: they all fire only for a "full" citation, so a
+  continuation (`` `:N` ``/`` `:N-M` ``, `` -`M` ``/`` –`M` ``, `` (`N`) ``)
+  or a bound paragraph-bound short-form `:N-M` chained off an
+  ALREADY-anchored full citation was invisible to `--require-anchors`
+  entirely: it carries no path of its own to hang an anchor on (see
+  "Anchored citations" in the README), so it was never itself an in-repo
+  full citation `anchor-required` could reach, and the anchor on its
+  governing citation does not (and structurally cannot) extend to a later
+  continuation of it. A line-shift that lands the continuation on still
+  non-blank, in-bounds, unrelated content -- exactly the drift class this
+  rule exists to catch -- was previously silent for a continuation the
+  same way it was for an unanchored full citation before 0.8.0. Fires once
+  the continuation's governing citation resolves in-repo, mirroring
+  `anchor-required`'s own exemptions (a reserved citing doc; a
+  `requireAnchors.allow` pattern, matched against the GOVERNING citation's
+  raw citedPath, since a continuation has no path of its own to match).
+  The paragraph-bound short form is included under the identical
+  reasoning. See "Anchor strictness (opt-in, `--require-anchors`)" in the
+  README for the full rationale.
+
+### Verification
+
+- `prose-line-references`: default mode (no `--prose-line-references`) is
+  byte-identical before and after this change: verified by building the
+  CLI at both the pre-change commit and this change, then running `check
+  --json` in default mode against the same three real bundles as below
+  (each repo's full real tree as `--repo-root`, not a narrow `docs/okf`-
+  only extraction, since this rule's own file-mention resolution needs the
+  rest of the repo present) and diffing the JSON output byte for byte --
+  0 bytes of diff on all three.
+- `prose-line-references` migration backlog, run with
+  `--prose-line-references` after this change against the same three
+  bundles, full real repo tree as `--repo-root`: agent-dx's own
+  orchestrator-workflow bundle 3 findings (2 `out-of-bounds`, 1
+  `blank-start-line`), harness 5 (2 `ambiguous`, 1 `blank-start-line`, 2
+  `unresolvable`), agent-grounding 0. Spot-checked, not exhaustively
+  audited: the harness `ambiguous` pair is a real collision (`intercept.ts`
+  resolves to both `src/cli/policy/intercept.ts` and
+  `src/runtime/intercept.ts`); the agent-dx `out-of-bounds`/
+  `blank-start-line` trio is a real false positive of the binding rule's
+  own stated limitation (a "test lines N-M" phrase bound to a file named
+  elsewhere in the same sentence for an unrelated reason, not the file the
+  line numbers actually belong to -- once before the reference, once
+  after) -- see the README's closing paragraph on "Prose line references"
+  for that known category. No
+  consumer CI currently selects on `[prose-line-references]` findings by
+  rule id, so no consumer pin bump is required before this rule starts
+  reporting; enabling `--prose-line-references` anywhere is itself the
+  opt-in.
+- `prose-line-references` review-round fixes above: default mode is still
+  byte-identical, re-verified the same way as above (build both commits,
+  `check --json` on the same three real bundles, diff byte for byte -- 0
+  bytes of diff on all three). The migration backlog counts are unchanged
+  by these fixes: agent-dx 3, harness 5, agent-grounding 0, identical
+  reasons to the counts above -- none of the three real bundles contained
+  a `line 0`, a hyphen-joined "-line N" word, an ATX heading naming a
+  line, or an HTML comment naming one. Four mutation probes verified
+  by hand against the new tests: replacing nearest-in-sentence binding
+  with first-in-paragraph binding, deleting the en-dash/em-dash/"to"
+  alternation from `LINE_REF_RE`, deleting the inverted-range branch in
+  `checkTarget`, and disabling the reserved-doc skip each fail a
+  dedicated new test, and pass again once reverted.
+- Regression test added for a latent `FILE_MENTION_RE` extension-matching
+  bug found while measuring the migration backlog above: the extension
+  alternation lists `js` before `json`, and `js` is a strict prefix of
+  `json`; without forcing the regex to reject a truncated match, a real
+  `config.json` mention resolved (or failed to resolve) as `config.js`
+  instead. Fixed with a trailing `(?!\w)` on the match; `citations-resolve`'s
+  own `CITATION_RE` does not have this problem, since its mandatory
+  trailing `:` already forces the same backtracking.
+- Default mode (no `--require-anchors`) is byte-identical before and
+  after this change: verified by building the CLI at both the pre-change
+  commit and this change, then running `check --json` in default mode
+  against three real bundles (this repo's own
+  `packages/orchestrator-workflow/docs/okf`, harness's `docs/okf`, and
+  agent-grounding's `docs/okf`, each extracted read-only at a pinned
+  commit) and diffing the sorted finding lists -- 0 lines of diff on all
+  three, both against a narrow `docs/okf`-only extraction and against the
+  full real repo tree as `--repo-root`.
+- Migration backlog, run with `--require-anchors` after this change
+  against the same three bundles with their full real repo tree as
+  `--repo-root` (a narrow `docs/okf`-only extraction under-counts this,
+  since most citations fail to resolve without the rest of the repo
+  present): agent-dx's own orchestrator-workflow bundle 70
+  `anchor-required-continuation` findings, harness 24, agent-grounding
+  24. Consumer CI pins (agent-dx's and agent-grounding's own
+  `okf-anchor-guard` jobs, which select findings by the trailing
+  `[rule-id]` bracket) must be bumped to this version before
+  `anchor-required-continuation` starts gating; that bump is out of scope
+  here.
+
 ## [0.8.0] - 2026-08-27
 
 ### Added

package/README.md

@@ -29,8 +29,11 @@ okf-kit check path/to/bundle --repo-root /path/to/repo
 # JSON output for tooling
 okf-kit check path/to/bundle --json
 
-# fail on warnings too, not just errors (STALE findings are warnings)
+# fail on warnings too, not just errors (STALE and FUTURE-DATED findings are warnings)
 okf-kit check path/to/bundle --strict
+
+# narrow sources-fresh-future's default 10-minute clock-skew allowance
+okf-kit check path/to/bundle --future-skew-minutes 2
 ```
 
 ## Scaffold a bundle (`init`)
@@ -55,7 +58,7 @@ Every template doc except `benchmark-template.md` ships with `sources: [path/to/
 
 ### Authoring guidance
 
-- **`timestamp` means "last verified against sources," not "created on."** Bump it, and add a line to `log.md`, every time you re-verify a doc against its sources. Always use the real instant of verification (`new Date().toISOString()` or equivalent); never hand-write an artificial midnight datetime, `sources-fresh` staleness comparisons depend on it being real.
+- **`timestamp` means "last verified against sources," not "created on."** Bump it, and add a line to `log.md`, every time you re-verify a doc against its sources. Always use the real instant of verification (`new Date().toISOString()` or equivalent); never hand-write an artificial midnight datetime, or a local wall-clock time with a `Z` suffix it doesn't actually have -- `sources-fresh` and `sources-fresh-future` staleness comparisons both depend on it being real. See "Future-dated timestamps (`sources-fresh-future`)" below for the measure-after-commit discipline this enforces.
 - **Never list the bundle's own directory in `sources`.** A bundle directory changes on every doc edit inside it, so a self-referential `sources` entry goes permanently stale. This happened to the OKF pilot's own `BENCHMARK.md` (`agent-tasks` `docs/okf/BENCHMARK.md`, `sources: [docs/okf/]`); `benchmark-template.md` here omits `sources` entirely for the same reason, since a benchmark record measures the bundle rather than describing a piece of the codebase.
 - **Keep all links same-directory relative.** Use `name.md`, not `/name.md`; see `no-absolute-links` above for why a leading slash breaks once the bundle is viewed outside its own repository.
 - **Write a sibling short-form citation as a connective-led `:N-M`, not `(N-M)`.** When a paragraph cites several sub-ranges of a source already named by a full `path:N-M` citation earlier in the same paragraph, write each later one as a `:N-M` led by one of the serial connectives the gate accepts -- `,`, `;`, `(`, or a trailing `and`/`or` -- right after the phrase it points at (e.g. `review finding L1 (:1170-1227, ...)`). `citations-resolve` only recognises the colon form; a parenthesized `(N-M)` is never checked, so it can drift silently. This convention is not demonstrated by any scaffolded template; it is a `citations-resolve` authoring rule. See "Citation resolution (citations-resolve)" below.
@@ -69,8 +72,10 @@ Every template doc except `benchmark-template.md` ships with `sources: [path/to/
 | `links-resolve` | error | Markdown links to other `.md` files in the bundle must resolve to a real file. Relative targets resolve against the containing file's directory; targets starting with `/` resolve against the bundle root. A relative target that climbs out of the bundle directory (`../outside.md`) and still resolves on disk is accepted; the rule checks resolution, not containment. |
 | `no-absolute-links` | warning | Link targets should not start with `/`. GitHub resolves a leading slash against the repository root, not the bundle root, so an absolute link 404s once the bundle is viewed outside its own repository. Use a same-directory relative link instead. |
 | `sources-shape` | error | Frontmatter `sources`, when present, must be a non-empty array of non-empty strings. With a repo root (explicit or auto-detected), each listed path (file or directory) must also exist under it. |
-| `sources-fresh` | warning / notice | For docs with a `sources` list and a repo root, flags a source path whose last git commit is newer than both the doc's `timestamp` and the doc file's own last commit. See "Staleness (sources-fresh)" below. |
-| `citations-resolve` | warning / notice | For docs with a repo root, flags a `` `path:N`/`path:N-M` `` citation (and its `` `:N` ``/`` -`M` ``/`` (`N`) `` continuations, and bare paragraph-bound short forms `:N-M`/`(N-M)`) whose target file is missing, whose range is inverted or exceeds the file, or whose start line is blank or (for a non-markdown target) only a closing brace. A full citation may also carry an optional `#anchor` (e.g. `` `CHANGELOG.md:50-144#0.24.0` ``), checked against the target's own structure/content instead of just its line numbers. A backtick-delimited `` `path:#heading` `` citation (`.md` targets only) resolves to a whole Markdown section instead of a line range, immune to every line-number shift above it; see "Heading-section citations" below. A short-form citation's range into a test file is also checked for a describe/it block boundary. `--require-anchors` opts into four additional checks; see "Anchor strictness (opt-in, `--require-anchors`)" below. See "Citation resolution (citations-resolve)" below. |
+| `sources-fresh` | warning / notice | For docs with a `sources` list and a repo root, flags a source path whose last git commit is newer than both the doc's `timestamp` and the doc file's own last re-stamping commit (re-stamp decided by comparing frontmatter `timestamp` values across that commit's first-parent boundary). See "Staleness (sources-fresh)" below. |
+| `sources-fresh-future` | warning | For the same docs as `sources-fresh`, flags a `timestamp` later than the doc file's own last commit by more than a clock-skew allowance (default 10 minutes, `--future-skew-minutes`). Catches a local wall-clock time mistakenly written with a `Z`/UTC suffix. See "Staleness (sources-fresh)" below. |
+| `citations-resolve` | warning / notice | For docs with a repo root, flags a `` `path:N`/`path:N-M` `` citation (and its `` `:N` ``/`` -`M` ``/`` (`N`) `` continuations, and bare paragraph-bound short forms `:N-M`/`(N-M)`) whose target file is missing, whose range is inverted or exceeds the file, or whose start line is blank or (for a non-markdown target) only a closing brace. A full citation may also carry an optional `#anchor` (e.g. `` `CHANGELOG.md:50-144#0.24.0` ``), checked against the target's own structure/content instead of just its line numbers. A backtick-delimited `` `path:#heading` `` citation (`.md` targets only) resolves to a whole Markdown section instead of a line range, immune to every line-number shift above it; see "Heading-section citations" below. A short-form citation's range into a test file is also checked for a describe/it block boundary. `--require-anchors` opts into five additional checks; see "Anchor strictness (opt-in, `--require-anchors`)" below. See "Citation resolution (citations-resolve)" below. |
+| `prose-line-references` | (opt-in, `--prose-line-references`) warning / notice | Off by default. Flags a prose-embedded line reference outside `citations-resolve`'s own backtick grammar (`line N`, `lines N-M`, `lines N to M`) that is drifted, unresolvable, or ambiguous once bound to the nearest named file. `--prose-line-references-strict` additionally flags every such reference as a formatting policy violation. See "Prose line references (opt-in, `--prose-line-references`)" below. |
 
 ## repo-root auto-detection
 
@@ -82,12 +87,15 @@ Pass `--repo-root` explicitly to pin a specific root (useful in CI when the bund
 
 ## Staleness (sources-fresh)
 
-`sources-fresh` compares each frontmatter `sources` entry's last git commit time against the doc's `timestamp`, and additionally against the doc file's own last commit time: a source committed at or before the doc file's last commit is treated as fresh even when the frontmatter `timestamp` is older. That keeps squash-merge PRs honest: when a doc re-stamp lands in the same commit as its changed sources, the merge gives every source a commit time later than any pre-merge `timestamp`, which used to make such docs stale-on-arrival. The rule never blocks a doc that has no `sources`, and it never invents an error where git can't give a real answer:
+`sources-fresh` compares each frontmatter `sources` entry's last git commit time against the doc's `timestamp`, and additionally against the doc file's own last commit time: a source committed at or before the doc file's last commit is treated as fresh even when the frontmatter `timestamp` is older, PROVIDED that same commit actually re-stamped the doc. "Re-stamped" is decided by VALUE, not by diff text: okf-kit reads the doc's frontmatter at that commit and in the commit's first parent, parses both, and compares the `timestamp` values -- they differ, or the doc did not exist in the parent at all (it was created there), and it counts as re-stamped. The lookup follows a rename, so `git mv`ing a doc is not a creation, and it reads trees rather than a patch, so a merge commit (including the `refs/pull/N/merge` ref CI checks out) is assessed like any other commit. That keeps squash-merge PRs honest: when a doc re-stamp lands in the same commit as its changed sources, the merge gives every source a commit time later than any pre-merge `timestamp`, which used to make such docs stale-on-arrival. It does NOT extend to a commit that merely happens to also touch the doc file -- a typo fix, a co-committed prose edit, a repo-wide formatter run -- without rewriting the stamp: that commit carries no verification claim, so staleness stands. "Created" is trusted only in a genuinely unshallow repository: in a shallow clone (`git clone --depth`), a commit with an empty parent list can simply be the boundary history was grafted onto, not the doc's real first commit, so this case gets the same not-assessable notice as any other unanswerable re-stamp question rather than an assumed pass (see "CI usage" below for the `fetch-depth: 0` remedy). The rule never blocks a doc that has no `sources`, and it never invents an error where git can't give a real answer:
 
 | Situation | Severity | Message |
 |-----------|----------|---------|
 | A source path's last commit is newer than the doc's `timestamp` and the doc file's last commit | warning | `STALE: <path> changed <iso> after doc timestamp <iso>` |
-| A source path's last commit is newer than the doc's `timestamp` but at/before the doc file's last commit | (nothing) | fresh: doc and source landed together (or the doc was committed later) |
+| A source path's last commit is newer than the doc's `timestamp`, at/before the doc file's last commit, AND that commit re-stamped the doc | (nothing) | fresh: doc and source landed together with a real re-stamp (or the doc was committed later, or created there) |
+| A source path's last commit is newer than the doc's `timestamp`, at/before the doc file's last commit, but that commit did NOT re-stamp the doc | warning | `STALE: <path> changed <iso> after doc timestamp <iso>` (co-commit with no re-stamp is not an exception) |
+| A source path's last commit is newer than the doc's `timestamp`, at/before the doc file's last commit, and git could not be asked whether that commit re-stamped the doc | notice | `staleness not assessable: git could not read the doc's own last commit to decide whether it re-stamped the doc` (once per doc, never a STALE warning and never a silent pass) |
+| Same, but the repository is a shallow clone and the doc's last commit is the grafted history boundary (an empty parent list that is not really a root commit) | notice | `staleness not assessable: this is a shallow clone ... use fetch-depth: 0 ... to assess it` (once per doc) |
 | A source path exists but has no git history (untracked) | notice | `untracked by git, staleness unknown: <path>` |
 | The doc's `timestamp` is missing or not a parseable date, while `sources` is present | notice | `staleness not assessable: no valid timestamp` |
 | No repo root available (see auto-detection above) | notice | `staleness skipped: not inside a git work tree` |
@@ -97,10 +105,31 @@ STALE findings are warnings, so they are advisory by default; run with `--strict
 
 Known limitation: a `git log` call that fails for a reason other than "no history for this path" (for example a corrupt object or a transient git error) is reported the same way as a genuinely untracked path, the `untracked by git, staleness unknown` notice; okf-kit does not currently distinguish a real git failure from "no commits touch this path".
 
-Known limitation: the doc-commit comparison suppresses staleness for every source older than the doc file's last commit, not only for sources from the same commit. For a multi-source doc that means any commit touching the doc (a typo fix, a repo-wide formatter run, a rename, which resets the doc's last-commit time because `git log` runs without `--follow`) silences drift on all sources changed before it, even ones nobody re-verified. The frontmatter `timestamp` still governs sources changed after the doc's last commit.
+Known limitation: the doc-commit comparison suppresses staleness for every source older than the doc file's last re-stamping commit, not only for sources from the same commit -- provided that commit is the one that rewrote the stamp. For a multi-source doc that means a re-stamp silences drift on every source changed before it, even ones that specific re-stamp did not itself verify. The frontmatter `timestamp` still governs sources changed after the doc's last commit. Also note: the check only looks at WHETHER the `timestamp` value changed, never at whether the new value is itself correct -- a hand-typed or deliberately backdated stamp still counts as a re-stamp (`sources-fresh-future` is the rule that catches an implausible value). "Changed" means the parsed frontmatter VALUE changed: a rewrite to the same instant in another representation (`...00Z` to `...00.000Z`) still counts as a re-stamp, since the raw string differs even though it names the same instant, while adding or removing quotes around an otherwise-unchanged value does NOT count, since YAML parsing already normalizes those away before the comparison ever sees them. And the comparison is against the FIRST parent only: a merge that takes the doc wholesale from its second parent is judged against the first-parent baseline, which is the baseline the pull request under review is measured against anyway.
 
 **Authoring guidance:** when you re-verify a doc against its sources, bump its frontmatter `timestamp` (and add a line to the bundle's `log.md`) so `sources-fresh` reflects that the doc is current again.
 
+### Future-dated timestamps (`sources-fresh-future`)
+
+`sources-fresh` catches a `timestamp` that is too OLD relative to a source's last commit. `sources-fresh-future` catches the opposite mistake: a `timestamp` that is too NEW relative to the doc file's OWN last commit -- in practice, almost always a local wall-clock time hand-written with a trailing `Z` (or another UTC marker) it does not actually have, rather than a genuine future date. It never looks at `sources` commit times at all, only at the doc file's own git history, so it has nothing to say about whether any source is stale; the two rules are complementary, not overlapping, and are assessed over the same population of docs (a validly-shaped `sources` list and a repo root available, exactly like `sources-fresh` above).
+
+| Situation | Severity | Message |
+|-----------|----------|---------|
+| The doc's `timestamp` is later than the doc file's own last commit by more than the skew allowance | warning | `FUTURE-DATED: doc timestamp <iso> is after the doc's own last commit <iso> (skew allowance <n>s)` |
+| The doc's `timestamp` is at or within the skew allowance of the doc file's own last commit | (nothing) | fresh: an ordinary write-then-commit gap, not a mistake |
+| The doc's `timestamp` string has no `Z`/UTC designator or numeric offset (e.g. `2026-01-01T00:00:00`, no offset) | notice | future-dated check skipped: timestamp has no UTC designator (`Z`) or numeric offset, can't be compared reliably across timezones |
+| The doc has no git history yet (uncommitted) | (nothing) | unknown, not flagged: there is no real commit time to compare against |
+| The doc's `timestamp` is missing or not a parseable date | (nothing) | left to `sources-fresh`'s own notice, not duplicated here |
+| No repo root available (see auto-detection above) | (nothing) | left to `sources-fresh`'s single bundle-level notice, not duplicated here |
+
+The skew allowance defaults to 10 minutes (600 seconds), absorbing the ordinary gap between writing a timestamp and the commit that carries it landing; override it with `--future-skew-minutes <n>`. Like `STALE` findings, `FUTURE-DATED` findings are warnings, advisory by default; run with `--strict` to fail the build on either.
+
+**The measure-after-commit discipline both rules enforce:** re-verify the doc against its sources, THEN bump `timestamp` to the real instant of that verification (`new Date().toISOString()` or equivalent, never a hand-written value), THEN commit -- committing without re-stamping is what `sources-fresh` catches, and hand-writing a local time with a `Z` suffix it doesn't have is what `sources-fresh-future` catches.
+
+**Why the UTC-designator gate exists:** a bare local datetime string (no `Z`, no numeric offset) parses under `Date.parse` in the machine's OWN timezone, so the same frontmatter value would compare differently on a UTC+2 laptop than on a UTC CI runner -- unusable against a default allowance measured in minutes. A numeric offset (`+02:00`, `-0500`) is unambiguous and IS assessed normally (`Date.parse` already normalizes it to a real UTC instant); only a fully bare datetime is skipped. `sources-fresh`'s own thresholds are days wide, so this ambiguity doesn't practically matter there and the gate applies only to `sources-fresh-future`.
+
+**What these two rules catch, precisely, and what they don't:** a source path committed after the doc's `timestamp` (`sources-fresh`'s base case); a source and the doc co-committed together where that commit did NOT re-stamp the doc (`sources-fresh`'s narrowed co-commit exception, see "Staleness (sources-fresh)" above); and a local wall-clock time hand-written with a `Z`/UTC suffix it doesn't actually have (`sources-fresh-future`). What they do NOT catch: a doc-only prose edit that leaves `sources` untouched and the `timestamp` stale -- neither rule has a source-side signal to compare against in that case, so it is not mechanically assessable and stays a reviewer judgment call, the same as before this pair of rules existed.
+
 ## Citation resolution (citations-resolve)
 
 `sources-fresh` catches a source file changing after a doc's `timestamp`, but it is structurally blind to an edit that shifts *line numbers* inside a still-fresh file: a doc citing `path:42` keeps citing line 42 even after an edit moves the referenced content to line 50. `citations-resolve` finds every `` `path:N` ``/`` `path:N-M` `` citation in a doc, resolves `path` to a real file, and flags a citation that clearly cannot be pointing at real content any more. It is mechanical only (no symbol/AST resolution): it does not verify the cited line is *semantically* the right one, only that the target exists, the range is sound, and the start line is not blank or (for a non-markdown target) a lone closing brace/bracket.
@@ -134,13 +163,14 @@ Known limitation: the doc-commit comparison suppresses staleness for every sourc
 | `anchor-not-on-last-line` | (opt-in, `--require-anchors`) A string-anchored citation's anchor text was found in the cited range, but not on the range's own last CONTENT line (see below). **Warning**. |
 | `anchor-not-unique-in-range` | (opt-in, `--require-anchors`) A string-anchored citation's anchor text occurs on more than one line of the cited range. **Warning**. |
 | `test-range-straddles-block` | (opt-in, `--require-anchors`) A full citation's own range into a `.test.`/`.spec.` target (`.ts`, `.js`, `.mjs`) contains a `describe`/`it`/`test` block-head line, at the same or a shallower indent than the range's own first line, on any line other than that first line. **Warning**. |
+| `anchor-required-continuation` | (opt-in, `--require-anchors`) A continuation (any of `` `:N` ``/`` -`M` ``/`` (`N`) ``) or a bound paragraph-bound short-form `:N-M` citation whose governing citation resolves in-repo -- it cannot carry a `#anchor` of its own. **Warning**. |
 
 **Anchored citations.** A full citation may carry an anchor directly after its range: `` `path:N-M#anchor` ``, e.g. `` `CHANGELOG.md:50-144#0.24.0` ``. This closes a gap the checks above cannot: a CHANGELOG.md that grows by inserting each new release at the top shifts every later entry's absolute line numbers, so a citation that lands 15 lines off in the *wrong* release section is exactly as green as before the shift -- none of `missing-file`/`inverted-range`/`range-exceeds-file`/`blank-start-line`/`closing-brace-start-line` can tell the difference. An anchor pins the citation to a piece of the target's own structure or content that a pure line-shift does not preserve. Two forms, told apart by the anchor text itself:
 
 - **Heading form** (bare/unquoted, e.g. `#0.24.0` or `#[0.24.0]`): the citation's nearest *enclosing* Markdown heading (level 1 or 2 only -- see below) must contain the anchor text, and the range must not run past that heading's own section (no heading of the same or shallower level may start before the range's end line). Capped at heading level 2 deliberately: a Keep-a-Changelog `CHANGELOG.md` nests `## [x.y.z]` release headings around identically-named `### Added`/`### Changed`/`### Fixed` subsections repeated in every release, so matching "the nearest heading of any level" would make this check nearly useless there (it would match the wrong release's own `### Changed` just as readily as the right one's); deeper subsection headings are transparent to the search instead. The anchor text itself may contain word characters, `.`, and `-`, but never starts or ends on a `.` or `-`, so a trailing sentence period or a following `,`/`)` never becomes part of it (e.g. `` `path:7-8#0.24.0.` `` at the end of a sentence captures `0.24.0`, not `0.24.0.`); a hyphenated token like `0.24.0-rc1` is captured whole. A fenced code block inside the *target* (e.g. a `` ```bash `` example containing a `#`-led comment) is excluded from the heading search the same way a citing doc's own fences are already excluded from short-form matching (see below): a comment line inside an example is never mistaken for a real heading, on either end of the enclosure check.
 - **String form** (double-quoted, e.g. `#"reproduction requirement"`): the anchor text must occur, verbatim, on at least one line of the cited range itself -- "occurs inside it" rather than "encloses it", so this form also works against a non-Markdown target (`.ts`/`.js`/...) where "enclosing heading" has no meaning. The quoted text cannot cross a line break or a backtick: an unterminated opening quote (a typo) fails to parse as an anchor at all (the citation is then checked as if no anchor had been written, with no diagnostic) rather than greedily consuming the rest of the document up to some unrelated later quote character, which would otherwise silently hide every citation in between from this rule entirely.
 
-Anchors are checked only once the base checks above (blank-start-line, closing-brace-start-line, inverted-range, range-exceeds-file) already came back clean for that citation. Anchors are full-citation-only: a continuation or a short-form citation never carries its own path, so there is nowhere natural to hang one on. The `#anchor` suffix is entirely optional and strictly additive: an existing anchorless citation matches and is checked exactly as it was before this feature existed.
+Anchors are checked only once the base checks above (blank-start-line, closing-brace-start-line, inverted-range, range-exceeds-file) already came back clean for that citation. Anchors are full-citation-only: a continuation or a short-form citation never carries its own path, so there is nowhere natural to hang one on -- under `--require-anchors`, such a continuation or bound short-form is instead flagged `anchor-required-continuation` (see below) rather than silently exempted. The `#anchor` suffix is entirely optional and strictly additive: an existing anchorless citation matches and is checked exactly as it was before this feature existed.
 
 **Anchor syntax note.** Any `#` immediately following a citation's range is read as the start of an anchor, with no other signal required -- there is no way to write a bare range immediately followed by an unrelated `#` and have it ignored. This means a Markdown link like `` [note](path:1-2#x) `` or an editor-style fragment such as `path:1-2#L7` is interpreted as an anchored citation (`x` and `L7` respectively), whether that was intended or not. The recommended, unambiguous form is the one used throughout this doc: the whole citation, range and anchor together, inside a single pair of backticks, e.g. `` `path:1-2#L7` ``.
 
@@ -170,15 +200,51 @@ Like `sources-fresh`, this rule requires a repo root (explicit `--repo-root` or
 
 ### Anchor strictness (opt-in, `--require-anchors`)
 
-Everything above is on by default. `--require-anchors` opts into four additional, stricter checks against `citations-resolve`, all `warning`-severity, off unless the flag is passed -- an existing bundle's findings under a plain `check` are byte-for-byte unaffected by this section existing. `--require-anchors` (and its sibling `--require-anchors-allow`) is a CLI flag only; okf-kit has no bundle-level config file today (no `.okf.yml`, no `okf-kit.config`, no frontmatter field), so there is no other way to turn this on. All four checks are also exempt for a citing doc that is a reserved file (`index.md`, `log.md`), the same carve-out `citations-resolve` already gives reserved docs for short-form matching elsewhere in this doc -- a reserved doc's citations still get the unconditional base checks (`missing-file`, `inverted-range`, `anchor-not-found-in-range`, and so on), just none of the four opt-in ones:
+Everything above is on by default. `--require-anchors` opts into five additional, stricter checks against `citations-resolve`, all `warning`-severity, off unless the flag is passed -- an existing bundle's findings under a plain `check` are byte-for-byte unaffected by this section existing. `--require-anchors` (and its sibling `--require-anchors-allow`) is a CLI flag only; okf-kit has no bundle-level config file today (no `.okf.yml`, no `okf-kit.config`, no frontmatter field), so there is no other way to turn this on. All five checks are also exempt for a citing doc that is a reserved file (`index.md`, `log.md`), the same carve-out `citations-resolve` already gives reserved docs for short-form matching elsewhere in this doc -- a reserved doc's citations still get the unconditional base checks (`missing-file`, `inverted-range`, `anchor-not-found-in-range`, and so on), just none of the five opt-in ones:
 
 - **`anchor-required`.** An in-repo full citation (resolved to a real target -- an unresolved one already gets its own `missing-file`/`unresolved-ambiguous` finding, not this one) carrying no `#anchor` at all is flagged. Also exempt (beyond the reserved-doc carve-out above): a citedPath matching one of `--require-anchors-allow`'s patterns (repeatable/space-separated, exact string or a `*`/`?` glob against the citation's raw, as-written path text), for a doc category not meant to be anchor-checked, e.g. `--require-anchors-allow README.md INSTALL-AGENT.md`. A target cited under several different spellings in the same bundle (`init.ts` in one paragraph, `src/init.ts` in another) needs one allow pattern per spelling, or a `*basename` glob that covers all of them -- the match is against the citation's own raw text, not the path it resolves to. `--require-anchors-allow` is commander-variadic: its list stops at the next `-`-prefixed token, so flags placed after it parse normally, but it swallows the positional bundle path if placed before it (`check --require-anchors-allow README.md <bundleDir>` fails with a missing-argument error); pass it after the bundle path.
 - **`anchor-not-on-last-line`.** A string-anchored citation (`` `path:N-M#"text"` ``) whose anchor text was found in the cited range, but not on the range's own last CONTENT line. A content line is any line whose trimmed text is not empty and not composed only of closing brackets/braces/parens plus an optional trailing `,`/`;` (`}`, `});`, `]);`, `}),`, and similar); a range ending on one or more such boilerplate lines (the common shape of a `});` that closes a whole cited block) resolves to the real content line before them instead. An anchor sitting on the range's first line survives a small insertion above the range (the shifted window still contains the anchor's original content, just at a different offset); anchoring on the last content line closes that, since the original last content line falls out of the shifted window on any insertion at all.
 - **`anchor-not-unique-in-range`.** A string-anchored citation whose anchor text occurs on more than one line of the cited range -- ambiguous evidence for which occurrence is the one actually pinning the citation. A count of zero is unaffected (already `anchor-not-found-in-range`, unconditionally).
 - **`test-range-straddles-block`.** A FULL citation's own range into a `.test.`/`.spec.` target (`.ts`, `.js`, `.mjs`) must not run into a sibling or outer `describe`/`it`/`test` block (including `.only`/`.skip`/`.each` variants): a block-head line at the same or a shallower indent than the range's own start line, found on any line of the range OTHER than that start line, means the citation straddled out into a sibling or outer block. A block-head line indented STRICTLY DEEPER than the start line is a nested block (e.g. every `it(` inside a `describe(` the range cites in full) and is not a straddle -- citing a whole block is expected to contain every head line nested inside it. The start line itself is never checked here -- it is either a legitimate block head (the range correctly starts a block) or legitimately inside a block's body (a deliberate partial citation), and both are fine. A range that leaves its block without a later block-head line inside it (ending on an outer block's closing line) is not detected by this line-based check. Deliberately scoped to test-file targets only, and to this same opt-in: a full citation into a Markdown target legitimately cites a couple of arbitrary lines all the time (the same reasoning that keeps the Markdown half of `test-range-start-not-head`/`test-range-end-not-closing` scoped to short-form citations only, see above), and turning this on unconditionally for every existing full citation would silently regress an already-green bundle for every consumer, not just one that opted in.
+- **`anchor-required-continuation`.** A continuation (`` `:N` ``/`` `:N-M` ``, `` -`M` ``/`` –`M` ``, `` (`N`) ``) or a bound paragraph-bound short-form `:N-M` citation whose governing citation (the full citation it is chained to, or the paragraph's last-named full range for a short form) resolves in-repo is flagged: it structurally cannot carry a `#anchor` of its own (see "Anchored citations" above), so it is invisible to every other check in this section, including when its governing full citation is itself already anchored -- an anchor on the full citation does not cover a later continuation of it. Same exemptions as `anchor-required`: a reserved citing doc, and `requireAnchors.allow`, matched against the GOVERNING citation's raw citedPath (a continuation carries no path of its own to match). The remedy is always the same: lift the continuation into its own full `path:N-M#anchor` citation. This closes a gap the other four checks leave open: they all fire only for a "full" citation, so a continuation chained off an ALREADY-anchored full citation was previously invisible to `--require-anchors` -- a line-shift landing it on still non-blank, in-bounds content is exactly the drift class `anchor-required` exists to catch for a full citation, just unreachable through it for a continuation.
 
 `--require-anchors` is off by default and, once on, surfaces a real backlog the first time it is run against an existing, unaudited bundle -- the same posture `blank-start-line` already documents for `citations-resolve` itself. `anchor-required` in particular is only useful once a bundle's citations have actually been anchored; running it against a bundle that predates anchoring will flag most of that bundle's full citations.
 
+## Prose line references (opt-in, `--prose-line-references`)
+
+`citations-resolve` only sees a citation written in its own backtick grammar (`` `path:N` ``). Prose habitually names a line number a different way instead -- "lines 496-498", "generate-codex-config.ts lines 129-132" -- and those shapes are structurally invisible to `citations-resolve`'s `CITATION_RE`, which requires a literal `:` between the path and the digits. A doc can be re-verified, re-stamped, and pass `check` with 0 findings while its prose line numbers are drifted, because nothing ever looked at them. `--prose-line-references` closes that gap. Off by default; every finding below is `prose-line-references`, off unless the flag is passed, so an existing bundle's `check` output is byte-for-byte unaffected by this section existing.
+
+**Extraction grammar** (conservative -- deliberately narrower than everything actually seen in the wild): `line N`, `lines N-M` (hyphen, en-dash, or em-dash), and `lines N to M`. Deliberately NOT matched:
+
+- `L N` / `L1` -- not observed in the corpus this rule was measured against, and more ambiguous than `line N` (`L1` already means "review finding 1" in this package's own short-form-citation authoring convention, see "Authoring guidance" above).
+- `<file>:N` outside backticks -- already matched by `citations-resolve`'s own `CITATION_RE`, which has no backtick requirement (only its heading-section form does). Matching it again here would double-report the same drift under two rule ids.
+- a comma-separated list of several numbers/ranges after one `lines` keyword (e.g. "lines 178, 234, 265-268"), or a second, unlabelled range chained by "vs"/"and" onto an already-extracted one (e.g. "lines 676-698 vs 564-591" only extracts `676-698`) -- only the first number/range is extracted; the rest are silently under-extracted, never mis-parsed. Under-extraction, never mis-binding, matches this rule's "never guess" posture throughout.
+
+A reference inside a fenced code block, an indented code block, an inline code span, or a Markdown table row is excluded from extraction, same as `citations-resolve`'s own short-form matching. So is a reference falling inside a real `citations-resolve` full citation's own span (mostly relevant to a citation's quoted string anchor, e.g. `` `path.md:10-20#"see line 5 above"` ``), a reference inside an HTML comment (e.g. `` <!-- see line 5 above for the earlier draft --> ``, which narrates a past state rather than citing current content), and a reference on a line that is itself a Markdown ATX heading (e.g. `## Line 3 semantics`, which names a section about a line rather than citing it). A URL with a port (`host:8080`), an ISO timestamp, and a version string (`1.2.3`) need no special-casing at all: the grammar above requires the literal word `line`/`lines` immediately before the digits, which none of those three shapes contain. A hyphen-joined compound word ("in-line 999", "multi-line 999", "command-line 999") is also excluded: the leading boundary check rejects a match starting right after a `-`.
+
+**Binding rule** (conservative -- never guessed across a paragraph boundary): a reference is bound to the nearest "file mention" -- a path-like token with one of `citations-resolve`'s own recognised extensions (`.ts`, `.js`, `.mjs`, `.md`, `.yml`, `.yaml`, `.json`) that resolves to a real file under the bundle's repo root, using `citations-resolve`'s own path-resolution rules verbatim (frontmatter `sources` match, ancestor climb for a bare filename, repo-root-relative, doc-relative, "last full path mentioned", repo-wide basename search):
+
+1. the nearest file mention in the same sentence, preceding first, then following (a rough sentence-boundary heuristic: a `.`/`!`/`?` followed by whitespace and then a capital letter, digit, backtick, quote, or open bracket, or the end of the paragraph);
+2. otherwise the nearest PRECEDING file mention in the same paragraph;
+3. otherwise `unresolvable` -- never guessed, never silently bound to the wrong file.
+
+A candidate file-mention token that itself fails to resolve, or resolves to more than one real file (two files sharing a basename), is not skipped in favor of a farther candidate: "nearest wins" is taken literally, so the outcome is `unresolvable`/`ambiguous` rather than quietly falling through to a second-nearest mention the prose did not actually name. `ambiguous` covers only that one case, a single mention whose own basename collides across files; two DISTINCT mentions that each resolve cleanly (e.g. "`` `src/a.ts` `` sets it up; `` `src/b.ts` `` line 5 reads it") are resolved by nearest-wins as usual and are deliberately never reported as `ambiguous` -- the binding rule picked one of them on purpose, it did not fail to pick. A bare backtick-wrapped filename (`` `src/cli.ts` ``) counts as a file mention exactly the way a bare filename in running prose does -- unlike the base extraction grammar above, mention detection deliberately does NOT exclude inline code, since a backtick-wrapped filename is this package's own normal, encouraged way to name a file in prose (see "Authoring guidance" above). `index.md`/`log.md` (reserved citing docs) are skipped entirely, the same carve-out `citations-resolve` already gives them: an append-only narrative journal routinely narrates historical line-number deltas as prose about the past, not live citations against current content.
+
+**Findings:**
+
+| Reason | Meaning | Severity |
+|--------|---------|----------|
+| `out-of-bounds` | The bound reference's range is inverted, or its start (or end) line exceeds the bound file's line count. | Warning |
+| `blank-start-line` | The bound reference's start line is blank. | Warning |
+| `unresolvable` | No file mention could be bound (no candidate in the sentence or paragraph, the nearest candidate does not resolve to a real file, or the resolved target could not be read). | Notice |
+| `ambiguous` | The nearest file mention's basename resolves to more than one real file; not evaluated. The finding names both (or all) candidates. | Notice |
+
+`unresolvable` and `ambiguous` are notice-severity rather than warning: "line" occurs constantly in ordinary English with no adjacent file nearby ("in line with", "product line"), so "no file mention nearby" is weaker evidence of actual drift than a reference that resolved cleanly and then turned out wrong. `out-of-bounds` and `blank-start-line` are warning-severity, mirroring `citations-resolve`'s own "a wrong start/target is strong drift evidence" posture once a reference DOES resolve to a single real file.
+
+**Strict mode (`--prose-line-references-strict`, ignored unless `--prose-line-references` is also passed):** flags EVERY extracted reference, resolved or not, with its own warning-severity `prose-line-reference-not-anchored` finding and a fixed remedy: lift it into a backtick `path:N-M` citation (so `citations-resolve` can verify it going forward), or de-precise it to a symbol name instead of a line number. This is additive, not a replacement for the base checks above -- a drifted reference under strict mode gets both its `out-of-bounds`/etc. finding AND the policy finding, since both facts are independently true of it.
+
+`--prose-line-references` is off by default and, once on, surfaces a real backlog the first time it is run against an existing, unaudited bundle -- the same posture `--require-anchors` already documents above. Known false-positive category: the binding rule conflates "the file this sentence is about" with "the file these line numbers belong to" when they differ, e.g. "`06-handoff.md`'s `## Accepted Waivers` heading ... (test lines 132-135)" binds `test lines 132-135` to `06-handoff.md` even though the line numbers actually belong to an unnamed test file discussed elsewhere in the same sentence -- a real limitation of a conservative, non-semantic heuristic, not a bug; expect some of this class of noise on a first run against an existing corpus.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -189,15 +255,23 @@ Everything above is on by default. `--require-anchors` opts into four additional
 
 ## CI usage
 
-This is advisory: don't fail the build on warnings unless you pass `--strict`. Use a normal (non-shallow) checkout of the repo that owns the bundle: repo-root detection runs `git rev-parse --show-toplevel` from the `path/to/bundle` argument itself, not from the shell's working directory, and `sources-fresh` reads `git log`, so a shallow clone reports paths as untracked.
+This is advisory: don't fail the build on warnings unless you pass `--strict`. Use a normal (non-shallow) checkout of the repo that owns the bundle: repo-root detection runs `git rev-parse --show-toplevel` from the `path/to/bundle` argument itself, not from the shell's working directory, and `sources-fresh` reads `git log`. A shallow clone (`actions/checkout`'s default `fetch-depth: 1`, or any `git clone --depth`) does NOT report paths as untracked -- every path is still tracked at the boundary commit's own commit time. What it DOES cost: `sources-fresh`'s re-stamp check (see "Staleness (sources-fresh)" above) can no longer tell a doc's real root commit from the grafted boundary commit history was cut off at, so a doc whose own last commit lands there gets a `staleness not assessable` notice instead of a real STALE/pass verdict. Pass `fetch-depth: 0` (a full checkout) to get a real verdict there too.
 
 ```yaml
+- uses: actions/checkout@v5
+  with:
+    fetch-depth: 0
 - name: OKF bundle check
-  run: npx okf-kit@0.8.0 check path/to/bundle
+  run: npx okf-kit@0.10.0 check path/to/bundle
 ```
 
 Pin the version: an unpinned `npx okf-kit` picks up new rules on their release day, which turns an unrelated PR red.
 
+Releasing a new okf-kit version to npm must also bump the `npm install -g
+okf-kit@<version>` pins this repo's own `orchestrator-workflow` package
+carries in `.github/workflows/`, in the same release commit; see
+`CONTRIBUTING.md`'s "Releasing okf-kit" section for the order.
+
 ## Where this fits
 
 okf-kit is the producer-side check: it validates a bundle you are authoring or maintaining. Consuming an OKF bundle at query time (loading, indexing, ranking passages for an agent) lives in [codebase-oracle](https://github.com/LanNguyenSi/codebase-oracle), a separate tool.

package/dist/bundle.d.ts

@@ -1,2 +1,19 @@
-import type { BundleContext, RunGit } from "./types.js";
+import type { BundleContext, FrontmatterInfo, RunGit } from "./types.js";
 export declare function loadBundle(bundleDir: string, repoRoot?: string, runGit?: RunGit): BundleContext;
+/**
+ * A frontmatter block is the first line being exactly `---` up to the next
+ * line that is exactly `---`. Anything else (no opening delimiter, or an
+ * opening delimiter with no matching close) counts as no frontmatter block
+ * at all, per the OKF v0.1 shape rule.
+ *
+ * Exported so `sources-fresh` can apply the IDENTICAL parse to a historical
+ * blob (`git show <sha>:<path>`) that `loadBundle` applies to the working-tree
+ * file: the rule's re-stamp test compares the parsed frontmatter `timestamp`
+ * VALUE across a commit boundary, and a second, subtly different parser there
+ * would decide freshness by a different notion of "frontmatter" than the rest
+ * of the tool.
+ */
+export declare function parseFrontmatter(raw: string): {
+    frontmatter: FrontmatterInfo;
+    body: string;
+};

package/dist/bundle.js

@@ -39,8 +39,15 @@ function walkMarkdownFiles(dir) {
  * line that is exactly `---`. Anything else (no opening delimiter, or an
  * opening delimiter with no matching close) counts as no frontmatter block
  * at all, per the OKF v0.1 shape rule.
+ *
+ * Exported so `sources-fresh` can apply the IDENTICAL parse to a historical
+ * blob (`git show <sha>:<path>`) that `loadBundle` applies to the working-tree
+ * file: the rule's re-stamp test compares the parsed frontmatter `timestamp`
+ * VALUE across a commit boundary, and a second, subtly different parser there
+ * would decide freshness by a different notion of "frontmatter" than the rest
+ * of the tool.
  */
-function parseFrontmatter(raw) {
+export function parseFrontmatter(raw) {
     const lines = raw.split(/\r?\n/);
     if (lines[0] !== "---") {
         return { frontmatter: { present: false }, body: raw };

package/dist/bundle.js.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -19,6 +19,27 @@ export interface CheckOptions {
      * Ignored when `requireAnchors` is not set.
      */
     requireAnchorsAllow?: string[];
+    /**
+     * Opt-in for `prose-line-references`: flag a prose-embedded line
+     * reference outside `citations-resolve`'s own backtick grammar (e.g.
+     * "lines 129-132") that is drifted, unresolvable, or ambiguous. See the
+     * doc block in `src/rules/prose-line-references.ts`.
+     */
+    proseLineReferences?: boolean;
+    /**
+     * Also flag EVERY prose line reference `prose-line-references` extracts,
+     * not only a drifted one, with the remedy to lift it into a backtick
+     * citation or a symbol name. Ignored when `proseLineReferences` is not
+     * set.
+     */
+    proseLineReferencesStrict?: boolean;
+    /**
+     * `sources-fresh-future`'s clock-skew allowance, in minutes (default 10
+     * when omitted; see `DEFAULT_FUTURE_SKEW_SECONDS` in
+     * `src/rules/sources-fresh.ts`). Converted to seconds and stored on
+     * `ctx.freshnessFutureSkewSeconds`.
+     */
+    futureSkewMinutes?: number;
     /** Test-only override for git access; production code shells out to the real `git` binary. */
     runGit?: RunGit;
 }