proteum 2.5.10 → 2.5.12

package/agents/project/CODING_STYLE.md

@@ -68,6 +68,33 @@ retries++;
 // See docs/fixes/2026-06-02-stripe-replay.md.
 ```
 
+## Doc anchors
+
+A why-comment explains one decision. A doc anchor connects the file to the durable documentation that governs it, so an agent that opens the file finds the feature pack, the decision record and the invariant without searching the corpus first.
+
+Write anchors in a leading block comment:
+
+```typescript
+/**
+ * @docs docs/features/search
+ * @adr  ADR-0004
+ * @fix  docs/fixes/2026-06-09-keyword-search-semantic-order.md
+ * @rule Composite ordering stays alias-aware. Never rewrite ORDER BY with regex.
+ */
+```
+
+- `@docs` points at the feature pack that owns the file. Required on every file that default-exports `definePageRoute`, `defineController`, `defineServerRoute`, or `defineServerRoutes`, and on every exported class extending a service base such as `Service` or `UsersManagementService`. Error routes are exempt: they render a status message and carry no feature-specific rule, so requiring a pack for one would manufacture documentation. Add an anchor to an error route only when it really does carry a rule.
+- Components are not covered automatically. A presentational primitive such as `Icon.tsx` or `Card.tsx` owns no feature, so a blanket rule would manufacture documentation for hundreds of files. Cover the component directories that do own a feature by listing them in `includeDocAnchors` when building the ESLint config, for example `['client/components/paywall/**']`.
+- `@adr` and `@fix` point at the decision record and fix note that constrain the file. Add them where the decision or the bug actually lives, not on every file in the area.
+- `@rule` states the invariant inline, in full. It is the one anchor that carries content rather than a pointer, because the rule is what an agent needs at the moment of editing. A `@rule` that only says `todo` or repeats the linked title is a defect.
+- Anchors are not a substitute for the documents. Narrative, alternatives, benchmarks and acceptance stay under `docs/**`; the anchor carries the pointer and the single-sentence rule.
+
+Two ESLint rules enforce this. `proteum/require-doc-anchor` reports definition files with no `@docs`, and warns by default so an adopting project sees its backlog without a failing build; pass `docAnchors: 'error'` to `createProteumEslintConfig` once the backfill is done. `proteum/valid-doc-anchor` always errors, because an anchor pointing at a deleted document is worse than no anchor.
+
+The read-only MCP owner payloads return these anchors alongside `explain_summary`, `orient`, `route_candidates`, `diagnose`, and `workflow_start`, so the documentation reaches the agent in the same response that identifies the owner.
+
+`proteum docs check` verifies the whole corpus in both directions: it fails on an anchor that no longer resolves, and reports as a backlog every fix note carrying an `Agent warning` that no code anchors, plus every feature pack nothing points at. `proteum verify changed` selects it automatically whenever `docs/**` or a source file changes, so a renamed document cannot silently orphan an anchor.
+
 ## Self-check before finishing
 
 Re-scan every touched file against this list before declaring the work done:
@@ -75,5 +102,6 @@ Re-scan every touched file against this list before declaring the work done:
 - No `any`, `unknown`, or casts introduced; contracts fixed at the boundary.
 - New code sits under the right banner section, and section names still match their content.
 - Every non-obvious decision, workaround, magic value, and bug fix has a why-comment at the site.
+- Every touched definition file carries a `@docs` anchor, and any fix or decision applied in this pass left a `@rule` anchor at the code site it constrains.
 - No comments that restate code; no leftover debug logs or commented-out code.
 - Repeated logic extracted; one class or component per file; catalogs stay canonical.

package/agents/project/DOCUMENTATION.md

@@ -37,6 +37,8 @@ Do not code from assumptions when a source-of-truth document exists.
 
 Do not duplicate rules across documents. Link to the source of truth when needed.
 
+Documentation must be reachable from the code it governs. Every document written under these rules names the code it affects; the code must point back with a doc anchor, so the next agent finds the governing document by opening the file rather than by searching the corpus. Anchors carry pointers plus the single-sentence invariant, never the narrative. The format and the lint rules that enforce it are in `CODING_STYLE.md`.
+
 ---
 
 # 2. Always read these first
@@ -86,6 +88,7 @@ docs/features/<feature>/acceptance.md
 docs/testing/regression-tests.md              if a regression test was added
 docs/decisions/                               if a major decision changed
 docs/fixes/                                   if a bug or regression was fixed
+@docs anchor on each definition file the feature owns
 ```
 
 ---
@@ -108,6 +111,7 @@ After fixing the bug, update:
 docs/fixes/YYYY-MM-DD-short-bug-name.md
 docs/testing/regression-tests.md
 affected feature edge-cases.md if a new edge case was discovered
+@rule and @fix anchors at the code site that regressed
 ```
 
 A bug fix is incomplete if:
@@ -117,6 +121,7 @@ the root cause is not documented
 the implemented solution is not documented
 the regression test is not linked
 future agents cannot tell what pattern must not return
+the invariant lives only in the fix note and not at the code site that regressed
 ```
 
 ---
@@ -847,12 +852,18 @@ tests/regression/<area>/<bug-name>.test.ts
 
 ## New rule added
 
-What should future agents follow?
+What should future agents follow? Both sections below are mandatory, and each one must also be mirrored to a `@rule` doc anchor at the code site it constrains. A rule that lives only in this note reaches no agent editing that file.
 
 ## Agent warning
 
 What pattern must not be reintroduced?
 
+## Code anchor
+
+```txt
+path/to/file        the @rule and @fix anchors added there
+```
+
 ## Related docs
 
 - docs/features/<feature>/
@@ -1004,11 +1015,17 @@ tests/performance/<benchmark>.test.ts
 
 ## New rule added
 
-What should future agents follow?
+What should future agents follow? Both sections below are mandatory, and each one must also be mirrored to a `@rule` doc anchor at the code site it constrains. A rule that lives only in this note reaches no agent editing that file.
 
 ## Agent warning
 
 What pattern must not be reintroduced?
+
+## Code anchor
+
+```txt
+path/to/file        the @rule and @fix anchors added there
+```
 ````
 
 ---

package/cli/commands/docs.ts

@@ -0,0 +1,223 @@
+import { UsageError } from 'clipanion';
+import fs from 'fs-extra';
+import path from 'path';
+
+import cli from '..';
+import { renderRows } from '../presentation/layout';
+import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
+
+const { collectDocAnchors } = require('../../docAnchors.js') as {
+    collectDocAnchors: (sourceText: string) => {
+        docs: string[];
+        fix: string[];
+        entries: { line: number; tag: string; value: string }[];
+    };
+};
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+type TDocsCheckFinding = {
+    detail: string;
+    kind: 'unresolved-anchor' | 'unanchored-fix-note' | 'orphan-feature-pack';
+    subject: string;
+};
+
+type TDocsCheckReport = {
+    anchoredFiles: number;
+    findings: TDocsCheckFinding[];
+    scannedFiles: number;
+};
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const skippedDirectories = new Set([
+    '.generated',
+    '.git',
+    '.proteum',
+    'bin',
+    'bin-dev',
+    'dist',
+    'node_modules',
+    'var',
+]);
+
+const isSourceFile = (name: string) => /\.(ts|tsx|mts|cts)$/.test(name);
+
+const walkSourceFiles = (directory: string, collected: string[] = []) => {
+    let entries: { isDirectory: () => boolean; name: string }[] = [];
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch (error) {
+        // An unreadable directory is not a documentation failure; skip it and
+        // keep scanning so one permission problem cannot mask real findings.
+        if (cli.verbose) console.warn(`docs check: skipping ${directory} (${(error as Error).message})`);
+        return collected;
+    }
+
+    entries.forEach((entry) => {
+        if (entry.name.startsWith('.') && entry.name !== '.') return;
+        const full = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (skippedDirectories.has(entry.name)) return;
+            walkSourceFiles(full, collected);
+            return;
+        }
+        if (isSourceFile(entry.name)) collected.push(full);
+    });
+
+    return collected;
+};
+
+/**
+ * Resolve an anchor value the same way the `proteum/valid-doc-anchor` lint rule
+ * does: against every ancestor of the file that holds a `docs/` directory, so a
+ * monorepo app can point at the repository-level corpus.
+ */
+const resolveAnchorValue = (value: string, fromDirectory: string, root: string) => {
+    if (path.isAbsolute(value)) return fs.existsSync(value);
+
+    const roots: string[] = [];
+    let current = fromDirectory;
+    // The walk deliberately continues past `root`: running this from an app root
+    // inside a monorepo must still resolve anchors aimed at the repository-level
+    // corpus, exactly as the `proteum/valid-doc-anchor` lint rule does.
+    while (current) {
+        if (fs.existsSync(path.join(current, 'docs'))) roots.push(current);
+        const parent = path.dirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+    if (!roots.includes(root)) roots.push(root);
+
+    return roots.some((candidate) => fs.existsSync(path.resolve(candidate, value)));
+};
+
+const listFeaturePacks = (root: string) => {
+    const featuresDir = path.join(root, 'docs', 'features');
+    if (!fs.existsSync(featuresDir)) return [];
+
+    return fs
+        .readdirSync(featuresDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+};
+
+const listFixNotesRequiringAnchor = (root: string) => {
+    const fixesDir = path.join(root, 'docs', 'fixes');
+    if (!fs.existsSync(fixesDir)) return [];
+
+    return fs
+        .readdirSync(fixesDir)
+        .filter((name) => name.endsWith('.md'))
+        .filter((name) => /^## Agent warning\s*$/m.test(fs.readFileSync(path.join(fixesDir, name), 'utf8')));
+};
+
+export const buildDocsCheckReport = (root: string): TDocsCheckReport => {
+    const files = walkSourceFiles(root);
+    const findings: TDocsCheckFinding[] = [];
+    const referencedPacks = new Set<string>();
+    const referencedFixNotes = new Set<string>();
+    let anchoredFiles = 0;
+
+    files.forEach((filepath) => {
+        const anchors = collectDocAnchors(fs.readFileSync(filepath, 'utf8'));
+        if (anchors.entries.length === 0) return;
+
+        anchoredFiles += 1;
+        const relative = path.relative(root, filepath);
+
+        anchors.docs.forEach((value) => {
+            referencedPacks.add(path.basename(value.replace(/\/+$/, '')));
+            if (!resolveAnchorValue(value, path.dirname(filepath), root)) {
+                findings.push({ detail: `@docs ${value}`, kind: 'unresolved-anchor', subject: relative });
+            }
+        });
+
+        anchors.fix.forEach((value) => {
+            referencedFixNotes.add(path.basename(value));
+            if (!resolveAnchorValue(value, path.dirname(filepath), root)) {
+                findings.push({ detail: `@fix ${value}`, kind: 'unresolved-anchor', subject: relative });
+            }
+        });
+    });
+
+    listFixNotesRequiringAnchor(root).forEach((note) => {
+        if (referencedFixNotes.has(note)) return;
+        findings.push({
+            detail: 'carries an Agent warning that no source file anchors',
+            kind: 'unanchored-fix-note',
+            subject: `docs/fixes/${note}`,
+        });
+    });
+
+    listFeaturePacks(root).forEach((pack) => {
+        if (referencedPacks.has(pack)) return;
+        findings.push({
+            detail: 'no source file points at this pack with @docs',
+            kind: 'orphan-feature-pack',
+            subject: `docs/features/${pack}`,
+        });
+    });
+
+    return { anchoredFiles, findings, scannedFiles: files.length };
+};
+
+/*----------------------------------
+- COMMAND
+----------------------------------*/
+
+const renderFindings = (findings: TDocsCheckFinding[], kind: TDocsCheckFinding['kind'], label: string) => {
+    const matching = findings.filter((finding) => finding.kind === kind);
+    if (matching.length === 0) return `${label}: none`;
+
+    return [`${label}: ${matching.length}`, ...matching.map((finding) => `  ${finding.subject} | ${finding.detail}`)].join(
+        '\n',
+    );
+};
+
+export const run = async (): Promise<void> => {
+    if (cli.args.action !== 'check') throw new UsageError('Usage: `proteum docs check`');
+
+    const root = cli.paths.appRoot;
+
+    console.info(
+        [
+            await renderTitle('PROTEUM DOCS CHECK', 'Checking that code and documentation still point at each other.'),
+            renderRows([{ label: 'root', value: root === process.cwd() ? '.' : root }]),
+            await renderStep('[1/1]', 'Resolving doc anchors.'),
+        ].join('\n\n'),
+    );
+
+    const report = buildDocsCheckReport(root);
+    const unresolved = report.findings.filter((finding) => finding.kind === 'unresolved-anchor');
+
+    console.info(
+        [
+            renderRows([
+                { label: 'files scanned', value: String(report.scannedFiles) },
+                { label: 'files anchored', value: String(report.anchoredFiles) },
+            ]),
+            renderFindings(report.findings, 'unresolved-anchor', 'Unresolved anchors'),
+            renderFindings(report.findings, 'unanchored-fix-note', 'Fix notes with no code anchor'),
+            renderFindings(report.findings, 'orphan-feature-pack', 'Feature packs with no inbound anchor'),
+        ].join('\n\n'),
+    );
+
+    // Only a broken pointer fails the command. Missing coverage is reported as a
+    // backlog so a project can adopt anchors without a red build on day one.
+    if (unresolved.length > 0)
+        throw new Error(
+            `Proteum docs check failed: ${unresolved.length} doc anchor(s) do not resolve. Update or remove them.`,
+        );
+
+    const backlog = report.findings.length;
+    console.info(
+        backlog > 0
+            ? await renderWarning(`Anchors resolve. ${backlog} coverage gap(s) reported above.`)
+            : await renderSuccess('All doc anchors resolve, and coverage is complete.'),
+    );
+};

package/cli/presentation/commands.ts

@@ -14,6 +14,7 @@ export const proteumCommandNames = [
     'typecheck',
     'lint',
     'check',
+    'docs',
     'e2e',
     'connect',
     'doctor',
@@ -301,6 +302,19 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: ['This command executes refresh, typecheck, then lint in that order.', 'From a monorepo wrapper root, check runs once per discovered Proteum app.'],
         status: 'stable',
     },
+    docs: {
+        name: 'docs',
+        category: 'Quality gates',
+        summary: 'Check that code and documentation still point at each other.',
+        usage: 'proteum docs check',
+        bestFor: 'Confirming doc anchors resolve and that fix notes and feature packs are reachable from code.',
+        examples: [{ description: 'Check every doc anchor in the repository', command: 'proteum docs check' }],
+        notes: [
+            'Only an anchor that no longer resolves fails the command; missing coverage is reported as a backlog.',
+            'Anchors are the `@docs`, `@adr`, `@fix`, and `@rule` tags described in `CODING_STYLE.md`.',
+        ],
+        status: 'stable',
+    },
     e2e: {
         name: 'e2e',
         category: 'Quality gates',

package/cli/runtime/commands.ts

@@ -352,6 +352,22 @@ class CheckCommand extends ProteumCommand {
     }
 }
 
+class DocsCommand extends ProteumCommand {
+    public static paths = [['docs']];
+
+    public static usage = buildUsage('docs');
+
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = '', ...restArgs] = this.args;
+
+        assertNoLegacyArgs('docs', restArgs);
+        this.setCliArgs({ action });
+        await runCommandModule(() => import('../commands/docs'));
+    }
+}
+
 class E2eCommand extends ProteumCommand {
     public static paths = [['e2e']];
 
@@ -919,6 +935,7 @@ export const registeredCommands = {
     typecheck: TypecheckCommand,
     lint: LintCommand,
     check: CheckCommand,
+    docs: DocsCommand,
     e2e: E2eCommand,
     connect: ConnectCommand,
     doctor: DoctorCommand,
@@ -955,6 +972,7 @@ export const createCli = (version: string) => {
     clipanion.register(TypecheckCommand);
     clipanion.register(LintCommand);
     clipanion.register(CheckCommand);
+    clipanion.register(DocsCommand);
     clipanion.register(E2eCommand);
     clipanion.register(ConnectCommand);
     clipanion.register(DoctorCommand);

package/cli/verification/changed.ts

@@ -144,6 +144,13 @@ const isDocsOnlyFile = (filepath: string) =>
     filepath.startsWith('agents/') ||
     docsOnlyExtensions.has(path.extname(filepath));
 
+/**
+ * A change that can break the code-to-documentation link: either the corpus
+ * moved under the anchors, or a source file that may carry anchors changed.
+ */
+const isDocAnchorRelevantFile = (filepath: string) =>
+    filepath.startsWith('docs/') || isRelatedSourceFile(filepath);
+
 const normalizeGlob = (glob: string) => normalizePath(glob.trim());
 
 const escapeRegExp = (value: string) => value.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
@@ -350,6 +357,20 @@ export const buildChangedVerificationPlan = ({
         if (check) addCheck({ check, selectedChecks });
     }
 
+    const docAnchorFiles = files.filter(isDocAnchorRelevantFile);
+    if (docAnchorFiles.length > 0) {
+        const check = createSuiteCheck({
+            configRoot: gitRoot,
+            files: docAnchorFiles,
+            id: 'builtin:doc-anchors',
+            reason: 'Changed docs or source files should keep doc anchors resolvable.',
+            scope: 'static',
+            source: 'builtin',
+            suite: 'npx proteum docs check',
+        });
+        if (check) addCheck({ check, selectedChecks });
+    }
+
     for (const rule of config.rules || []) {
         const matchedFiles = matchFiles(files, rule.match);
         if (matchedFiles.length === 0) continue;

package/common/dev/mcpPayloads.ts

@@ -45,8 +45,34 @@ type TNodePath = {
     resolve: (...segments: string[]) => string;
 };
 
+type TDocAnchorEntry = {
+    line: number;
+    tag: string;
+    value: string;
+};
+
+type TDocAnchorGroups = {
+    adr: string[];
+    docs: string[];
+    entries: TDocAnchorEntry[];
+    fix: string[];
+    rules: string[];
+};
+
+type TDocAnchorsModule = {
+    collectDocAnchors: (sourceText: string, options?: { maxLength?: number }) => TDocAnchorGroups;
+};
+
+export type TOwnerDocAnchors = {
+    adr?: string[];
+    docs?: string[];
+    fix?: string[];
+    rules?: string[];
+};
+
 const maxInstructionPreviewLength = 360;
 const maxTextLength = 220;
+const maxOwnerDocAnchorRules = 3;
 const nodeRequire = (() => {
     try {
         return eval('require') as NodeRequire;
@@ -56,6 +82,23 @@ const nodeRequire = (() => {
 })();
 const fs = nodeRequire ? (nodeRequire('fs') as TNodeFs) : undefined;
 const path = nodeRequire ? (nodeRequire('path') as TNodePath) : undefined;
+const docAnchors = (() => {
+    if (!nodeRequire) return undefined;
+
+    // Relative resolution covers the linked framework checkout; the package
+    // specifier covers an installed copy whose transpiled layout may differ.
+    // Owner payloads stay valid without anchors, so a resolution failure
+    // degrades to the previous behaviour instead of breaking the tool.
+    for (const specifier of ['../../docAnchors.js', 'proteum/docAnchors.js']) {
+        try {
+            return nodeRequire(specifier) as TDocAnchorsModule;
+        } catch (_error) {
+            continue;
+        }
+    }
+
+    return undefined;
+})();
 
 const hasNodeFs = () => fs !== undefined;
 const hasNodePath = () => path !== undefined;
@@ -217,14 +260,49 @@ export const summarizeManifest = (manifest: TProteumManifest | undefined) => {
     };
 };
 
-const compactOwnerMatch = (match: TExplainOwnerResponse['matches'][number]) => ({
-    kind: match.kind,
-    label: match.label,
-    score: match.score,
-    scope: match.scopeLabel,
-    origin: match.originHint,
-    source: match.source,
-});
+/**
+ * Resolve the doc anchors declared in an owner's source file.
+ *
+ * This is what makes the documentation corpus discoverable at the point an
+ * agent asks who owns a route: the governing feature pack, decision record and
+ * fix note arrive with the owner instead of costing a separate search.
+ */
+export const readOwnerDocAnchors = (filepath?: string): TOwnerDocAnchors | undefined => {
+    if (!filepath || !docAnchors || fs === undefined || !fileExists(filepath)) return undefined;
+
+    let groups: TDocAnchorGroups;
+    try {
+        groups = docAnchors.collectDocAnchors(fs.readFileSync(filepath, 'utf8'));
+    } catch (_error) {
+        return undefined;
+    }
+
+    if (groups.entries.length === 0) return undefined;
+
+    return {
+        docs: groups.docs.length > 0 ? groups.docs : undefined,
+        adr: groups.adr.length > 0 ? groups.adr : undefined,
+        fix: groups.fix.length > 0 ? groups.fix : undefined,
+        rules:
+            groups.rules.length > 0
+                ? compactList(groups.rules, maxOwnerDocAnchorRules).map((rule) => truncateForMcp(rule))
+                : undefined,
+    };
+};
+
+const compactOwnerMatch = (match: TExplainOwnerResponse['matches'][number]) => {
+    const docs = readOwnerDocAnchors(match.source.filepath);
+
+    return {
+        kind: match.kind,
+        label: match.label,
+        score: match.score,
+        scope: match.scopeLabel,
+        origin: match.originHint,
+        source: match.source,
+        ...(docs ? { docs } : {}),
+    };
+};
 
 const compactDiagnostic = (diagnostic: TDoctorResponse['diagnostics'][number]) => ({
     level: diagnostic.level,

package/docAnchors.js

@@ -0,0 +1,135 @@
+/*
+ * Shared doc-anchor contract.
+ *
+ * A doc anchor ties a source file to the durable documentation that governs it,
+ * so an agent editing the file sees the governing rule without first reading the
+ * whole documentation corpus.
+ *
+ * Supported tags, written in any leading block comment:
+ *
+ *   @docs docs/features/search
+ *   @adr  ADR-0004
+ *   @fix  docs/fixes/2026-06-09-keyword-search-semantic-order.md
+ *   @rule Composite ordering stays alias-aware. Never rewrite ORDER BY with regex.
+ *
+ * `@docs`, `@adr` and `@fix` are pointers resolved by the MCP owner payloads.
+ * `@rule` carries the one-line invariant inline, where an agent cannot miss it.
+ *
+ * This module is plain CommonJS with no dependencies because both the ESLint
+ * rules and the TypeScript MCP payload builder load it. Keep it that way so the
+ * lint surface and the agent-facing surface can never disagree on the format.
+ */
+
+const docAnchorTags = ['docs', 'adr', 'fix', 'rule'];
+const pathDocAnchorTags = ['docs', 'fix'];
+const maxDocAnchorScanLength = 64 * 1024;
+const minDocAnchorRuleLength = 8;
+
+const blockCommentPattern = /\/\*[\s\S]*?\*\//g;
+const commentGutterPattern = /^\s*\*+[ \t]?/;
+const tagPattern = /^@([a-zA-Z][\w-]*)[ \t]*(.*)$/;
+
+const countLinesBefore = (text, index) => {
+    let line = 1;
+    for (let cursor = 0; cursor < index; cursor += 1) {
+        if (text[cursor] === '\n') line += 1;
+    }
+
+    return line;
+};
+
+const stripCommentGutter = (line) => line.replace(commentGutterPattern, '').trim();
+
+const isDocAnchorTag = (tag) => docAnchorTags.includes(tag);
+const isPathDocAnchorTag = (tag) => pathDocAnchorTags.includes(tag);
+
+/**
+ * Parse the inner text of a single block comment.
+ *
+ * `startLine` is the 1-based line the comment opens on, so reported entries
+ * point at the exact anchor line rather than the top of the file.
+ */
+const parseDocAnchorComment = (commentValue, startLine = 1) => {
+    const entries = [];
+    const lines = String(commentValue === undefined || commentValue === null ? '' : commentValue).split('\n');
+    let current;
+
+    lines.forEach((rawLine, index) => {
+        const line = stripCommentGutter(rawLine);
+        if (line === '') {
+            current = undefined;
+            return;
+        }
+
+        const tagMatch = line.match(tagPattern);
+        if (tagMatch) {
+            const tag = tagMatch[1].toLowerCase();
+            if (!isDocAnchorTag(tag)) {
+                current = undefined;
+                return;
+            }
+
+            current = { tag, value: tagMatch[2].trim(), line: startLine + index };
+            entries.push(current);
+            return;
+        }
+
+        // A non-empty line that opens no new tag continues the previous value,
+        // which keeps multi-line `@rule` invariants readable in source.
+        if (current) current.value = `${current.value} ${line}`.trim();
+    });
+
+    return entries.filter((entry) => entry.value !== '');
+};
+
+const uniqueValues = (entries, tag) => {
+    const values = [];
+    entries.forEach((entry) => {
+        if (entry.tag !== tag || values.includes(entry.value)) return;
+        values.push(entry.value);
+    });
+
+    return values;
+};
+
+const buildDocAnchorGroups = (entries) => ({
+    entries,
+    docs: uniqueValues(entries, 'docs'),
+    adr: uniqueValues(entries, 'adr'),
+    fix: uniqueValues(entries, 'fix'),
+    rules: uniqueValues(entries, 'rule'),
+});
+
+const hasDocAnchorTag = (groups, tag) => groups.entries.some((entry) => entry.tag === tag);
+
+/**
+ * Collect every doc anchor in raw source text.
+ *
+ * Used by the MCP owner payloads, which read a file from disk and have no AST.
+ * The scan is capped so enriching an owner match stays cheap on large files.
+ */
+const collectDocAnchors = (sourceText, options) => {
+    const maxLength = options && options.maxLength ? options.maxLength : maxDocAnchorScanLength;
+    const text = String(sourceText === undefined || sourceText === null ? '' : sourceText).slice(0, maxLength);
+    const entries = [];
+
+    blockCommentPattern.lastIndex = 0;
+    let match = blockCommentPattern.exec(text);
+    while (match !== null) {
+        const body = match[0].slice(2, -2);
+        entries.push(...parseDocAnchorComment(body, countLinesBefore(text, match.index)));
+        match = blockCommentPattern.exec(text);
+    }
+
+    return buildDocAnchorGroups(entries);
+};
+
+module.exports = {
+    buildDocAnchorGroups,
+    collectDocAnchors,
+    docAnchorTags,
+    hasDocAnchorTag,
+    isPathDocAnchorTag,
+    minDocAnchorRuleLength,
+    parseDocAnchorComment,
+};