Repository navigation
context-forge: content-anchor code citations (CF-N13) for large multi-tenant repos - #20
Merged
Merged
Conversation
…-tenant repos Raw `path:line` citations were the identity of every citation the toolkit emits (constitution rules, both findings logs) and the key both staleness engines checked (refresh re-check, scrubber's "stale citation" category). In large, churning, multi-tenant repos this backfired: any edit above a cited line drifted the number, so citations went "stale" without the referenced knowledge changing, and the same relative path shape recurring under many tenants made a bare path+line ambiguous. The result was constant re-flagging and rework — the exact churn the plugin exists to prevent. Re-key every emitted citation on a stable content anchor: - New governing norm CF-N13 (shared principles.md, both copies): citations are `path#anchor` — a grep-resolvable symbol/heading (or short unique snippet), repo-root-relative and module-qualified so tenants aren't ambiguous — with a line number only ever an optional, approximate `(~Lnn)` hint, never the identity. Amends CF-N1 and CF-N9 to reference it. - Staleness redefined across both engines: a citation is stale only when its anchor no longer resolves; a merely drifted `~L` hint is current and is re-stamped in place as metadata, never flagged (refresh-protocol, audit-protocol, both SKILLs, both agents). - Multi-site ambiguity is disambiguated by module-qualified path or deduped up the tree (CF-N3), never guessed. - Legacy `path:line` citations stay valid input and are re-grounded to `path#anchor` the next time refresh/re-audit touches the row — backward compatible. - Threaded the `path#anchor (~Lnn)` form through every placeholder and example in the agents, protocols, and all three templates; README gains a "Content-anchored citations" design note. - Version 0.8.0 -> 0.9.0 across all three tool manifests. Validators (plugin + marketplace, self-tests and live) pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VzYYP7rcbdLLLKapxfvfvR
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The context-forge skills bake a
path:linecitation contract into everything they emit — constitution rules, both findings logs — and both staleness engines (therefreshre-check and the scrubber's stale citation category) resolve citations by line number. In large, churning, multi-tenant repos this is exactly backwards:refresh/scrub then re-flags real citations → constant rework, the churn the toolkit exists to prevent.services/<tenant>/handler.go), so a bare path + line is both fragile and ambiguous.The repo already stated the correct principle in one place —
apply-protocol.md: "located by content … line numbers drift … content-anchored edits stay correct." This change generalizes that established principle to the entire citation contract.Change
Re-key every emitted citation on a stable content anchor, with the line demoted to an optional hint.
CF-N13(sharedprinciples.md, both byte-identical copies): a citation ispath#anchor— a grep-resolvable symbol / migration id / doc heading (or a short unique quoted snippet when no symbol fits), repo-root-relative and module-qualified so tenants aren't ambiguous — and a line number is only ever an approximate, regenerable(~Lnn)hint, never the identity.CF-N1andCF-N9amended to reference it.~Lhint is current and is re-stamped in place as metadata (like the header provenance line) — never arefresh"stale" flag, never a scrubber finding. This is the single change that stops the false-positive churn.CF-N3).path:linecitations stay valid input and are re-grounded topath#anchorthe next time arefresh/re-audit touches the row — a legacy line-only citation whose file exists but whose line drifted is re-grounded, never retired.path#anchor (~Lnn)form through every placeholder and example across both agents, all protocols, and all three templates; README gains a Content-anchored citations design section.0.8.0→0.9.0across all three tool manifests (Claude Code, Cursor, Codex), kept identical.Validation
Shared
principles.mdcopies confirmed byte-identical (validator's DRIFT check). No behavioral change to the marketplace catalogs; membership/semver parity intact.🤖 Generated with Claude Code
https://claude.ai/code/session_01VzYYP7rcbdLLLKapxfvfvR
Generated by Claude Code