@cleocode/core 2026.10.27 → 2026.11.1-canary.10

package/dist/docs/derive-links.js

@@ -57,6 +57,24 @@ export function extractTaskMentions(contentText) {
     }
     return [...ids].sort((a, b) => Number(a.slice(1)) - Number(b.slice(1)));
 }
+/** `[[slug]]`, `[[slug#heading]]` or `[[slug|label]]` wikilinks; group 1 is the slug. */
+export const WIKILINK_PATTERN = /\[\[([^\]|#\n]+)(?:#[^\]|\n]*)?(?:\|[^\]\n]*)?\]\]/g;
+/**
+ * Extract the sorted, de-duplicated slugs a body links to with `[[wikilinks]]`.
+ *
+ * @param contentText - Decoded UTF-8 body.
+ * @returns Linked slugs (e.g. `['adr-078-docs-provenance']`).
+ * @task T14113
+ */
+export function extractWikilinkTargets(contentText) {
+    const out = new Set();
+    for (const match of contentText.matchAll(WIKILINK_PATTERN)) {
+        const target = match[1]?.trim();
+        if (target)
+            out.add(target);
+    }
+    return [...out].sort();
+}
 /**
  * Derive provenance links for a doc write.
  *
@@ -69,6 +87,7 @@ export function deriveDocLinks(contentText, labels) {
     return {
         relatedTasks: extractTaskMentions(contentText),
         topics: labels ? [...new Set(labels)].sort() : [],
+        wikilinks: extractWikilinkTargets(contentText),
     };
 }
 /**

package/dist/docs/derive-links.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive-links.js","sourceRoot":"","sources":["../../src/docs/derive-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4EAA4E;AAC5E,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAwB;IAC1D,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAC5D,IAAI,IAAI,KAAK,0BAA0B;QAAE,OAAO,KAAK,CAAC;IACtD,OAAO,CACL,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QACxB,IAAI,KAAK,kBAAkB;QAC3B,IAAI,KAAK,iBAAiB;QAC1B,IAAI,KAAK,kBAAkB;QAC3B,IAAI,KAAK,oBAAoB,CAC9B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC;AAaD;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB,EAAE,MAA0B;IAC5E,OAAO;QACL,YAAY,EAAE,mBAAmB,CAAC,WAAW,CAAC;QAC9C,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE;KAClD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB;IACvD,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"derive-links.js","sourceRoot":"","sources":["../../src/docs/derive-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4EAA4E;AAC5E,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAwB;IAC1D,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAC5D,IAAI,IAAI,KAAK,0BAA0B;QAAE,OAAO,KAAK,CAAC;IACtD,OAAO,CACL,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QACxB,IAAI,KAAK,kBAAkB;QAC3B,IAAI,KAAK,iBAAiB;QAC1B,IAAI,KAAK,kBAAkB;QAC3B,IAAI,KAAK,oBAAoB,CAC9B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,MAAM,gBAAgB,GAAG,qDAAqD,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC3D,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAChC,IAAI,MAAM;YAAE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAeD;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB,EAAE,MAA0B;IAC5E,OAAO;QACL,YAAY,EAAE,mBAAmB,CAAC,WAAW,CAAC;QAC9C,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE;QACjD,SAAS,EAAE,sBAAsB,CAAC,WAAW,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB;IACvD,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC7D,CAAC"}

package/dist/docs/display-alias.d.ts

@@ -94,4 +94,3 @@ export interface SetDisplayAliasResult {
  * @throws {CleoError} `E_ALIAS_TAKEN` when an ADR already owns the number.
  */
 export declare function setDisplayAlias(projectRoot: string, params: SetDisplayAliasParams): Promise<SetDisplayAliasResult>;
-//# sourceMappingURL=display-alias.d.ts.map

package/dist/docs/display-alias.js

@@ -116,6 +116,9 @@ export async function setDisplayAlias(projectRoot, params) {
             }
         }
         db.prepare('UPDATE docs_attachments SET display_alias = ? WHERE id = ?').run(displayAlias, row.id);
+        // T14288: the doc's identity row carries its display number too.
+        const { mirrorConduitDocMeta } = await import('../store/conduit-doc-history.js');
+        await mirrorConduitDocMeta(projectRoot, { rowId: row.id });
         db.exec('COMMIT');
     }
     catch (txErr) {

package/dist/docs/display-alias.js.map

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

package/dist/docs/doc-name-rule.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The doc naming rule (T14107, owner decision D11210 "docs never rot"): a
+ * published doc's name says what it is about, never when or for which task or
+ * session it was written. Task and decision links and dates live in the doc's
+ * metadata, so a doc can be updated in place for as long as it is true.
+ *
+ * A name is lowercase kebab-case, at most 64 characters, and carries no task
+ * id (`t1234` as a token), no session id (`ses_…`) and no date (`2026-10-28`,
+ * `2026-10`, `20261028`). An ADR keeps its number (`adr-0123-…`) and a release
+ * note its version (`v2026.10.27`): those are the doc's identity.
+ *
+ * @task T14107
+ */
+/** Longest allowed doc name, in characters. */
+export declare const DOC_NAME_MAX_LENGTH = 64;
+/** Doc kinds the rule does not govern: per-task working state and release plumbing. */
+export declare const DOC_NAME_EXEMPT_KINDS: readonly string[];
+/**
+ * Tracked docs that broke the rule before it existed: a shrink-only list the
+ * docs census (T14108) empties as it renames them.
+ */
+export declare const DOC_NAME_BASELINE_PATH = "scripts/.docs-name-baseline.json";
+/** Why a doc name breaks the rule. */
+export type DocNameReason = 'format' | 'length' | 'task-id' | 'session-id' | 'date';
+/** A doc name that breaks the rule, why, and a name that would not. */
+export interface DocNameViolation {
+    /** Every rule the name breaks. */
+    reasons: DocNameReason[];
+    /** The name with the forbidden tokens removed, in kebab-case. */
+    suggestion: string;
+}
+/**
+ * A rule-abiding name built from `name`: lowercase kebab-case without task
+ * ids, session ids or dates, cut to {@link DOC_NAME_MAX_LENGTH}.
+ *
+ * @param name - The offending name.
+ * @returns The suggested name, or `doc` when nothing is left.
+ * @task T14107
+ */
+export declare function suggestDocName(name: string): string;
+/**
+ * The rule-abiding slug CLEO mints from a title or file name: its subject
+ * words in kebab-case, without task ids, session ids or dates, at most
+ * `maxLength` characters. Internal writers (ADR allocation, spawn topic slugs,
+ * imports) use it so their slugs pass {@link docNameViolation}; the task stays
+ * a link on the doc, not part of its name.
+ *
+ * @param source - The title or file base name.
+ * @param maxLength - Longest result, for callers that add a prefix.
+ * @returns The slug, or `doc` when the source has no subject words.
+ * @task T14129
+ */
+export declare function subjectSlug(source: string, maxLength?: number): string;
+/**
+ * Check a doc name (a slug, or a published file name without `.md`) against
+ * the rule. An ADR's leading number and a release note's version are allowed.
+ *
+ * @param name - The slug or file base name.
+ * @param kind - The doc kind, when known; exempt kinds always pass.
+ * @returns The violation, or null when the name is fine.
+ * @task T14107
+ */
+export declare function docNameViolation(name: string, kind?: string): DocNameViolation | null;
+/** Readable explanation of a violation, for refusals and gate output. */
+export declare function describeDocNameViolation(name: string, violation: DocNameViolation): string;
+/**
+ * Whether a repository path is a published doc the rule governs: a `*.md`
+ * under `docs/`, except generated output and `README.md` files.
+ *
+ * @param path - Repository-relative path, `/`-separated.
+ * @returns True when the rule applies.
+ */
+export declare function isGovernedDocPath(path: string): boolean;
+/** One governed doc path and how it breaks the rule. */
+export interface DocPathViolation extends DocNameViolation {
+    /** Repository-relative path. */
+    file: string;
+}
+/** Result of {@link checkDocNames}. */
+export interface DocNameCheck {
+    /** Governed paths that break the rule and are not baselined. */
+    violations: DocPathViolation[];
+    /** Baselined paths that no longer exist or no longer break the rule. */
+    stale: string[];
+}
+/**
+ * Check every governed doc path against the rule. A path in the shrink-only
+ * baseline is tolerated while it still breaks the rule; a baseline entry that
+ * is gone or fixed is stale and must be removed, so the list only shrinks.
+ *
+ * @param paths - Tracked repository paths.
+ * @param baseline - Baselined paths ({@link readDocNameBaseline}).
+ * @returns New violations and stale baseline entries.
+ * @task T14107
+ */
+export declare function checkDocNames(paths: readonly string[], baseline: readonly string[]): DocNameCheck;
+/**
+ * The baselined doc paths of a repository ({@link DOC_NAME_BASELINE_PATH}).
+ *
+ * @param root - Repository root.
+ * @returns The baselined paths; empty when the file is absent.
+ * @throws When the file exists but is not `{ "files": string[] }`.
+ */
+export declare function readDocNameBaseline(root: string): string[];

package/dist/docs/doc-name-rule.js

@@ -0,0 +1,212 @@
+/**
+ * The doc naming rule (T14107, owner decision D11210 "docs never rot"): a
+ * published doc's name says what it is about, never when or for which task or
+ * session it was written. Task and decision links and dates live in the doc's
+ * metadata, so a doc can be updated in place for as long as it is true.
+ *
+ * A name is lowercase kebab-case, at most 64 characters, and carries no task
+ * id (`t1234` as a token), no session id (`ses_…`) and no date (`2026-10-28`,
+ * `2026-10`, `20261028`). An ADR keeps its number (`adr-0123-…`) and a release
+ * note its version (`v2026.10.27`): those are the doc's identity.
+ *
+ * @task T14107
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/** Longest allowed doc name, in characters. */
+export const DOC_NAME_MAX_LENGTH = 64;
+/** Doc kinds the rule does not govern: per-task working state and release plumbing. */
+export const DOC_NAME_EXEMPT_KINDS = ['rcasd', 'changeset'];
+/**
+ * Tracked docs that broke the rule before it existed: a shrink-only list the
+ * docs census (T14108) empties as it renames them.
+ */
+export const DOC_NAME_BASELINE_PATH = 'scripts/.docs-name-baseline.json';
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const ADR_PREFIX = /^adr-\d{3,4}-/;
+const RELEASE_NAME = /^v\d{4}\.\d+\.\d+(-[a-z0-9-]+)?$/;
+/** Hyphen/underscore/dot-separated lowercase tokens of a name. */
+function tokens(name) {
+    return name
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+const isTaskToken = (token) => /^t\d{3,}$/.test(token);
+const isDateToken = (token) => /^(19|20)\d{6}$|^(19|20)\d{12}$/.test(token);
+/** Whether the name holds a session id: `ses_…`, or `ses` then a numeric token. */
+function hasSessionId(name) {
+    const parts = tokens(name);
+    return (/(^|[^a-z])ses_/i.test(name) ||
+        parts.some((token, i) => token === 'ses' && /^\d+$/.test(parts[i + 1] ?? '')));
+}
+/** Whether the name holds a calendar date: `YYYY-MM(-DD)`, or `YYYYMMDD`. */
+function hasDate(name) {
+    return (/(^|[^0-9])(19|20)\d{2}-(0[1-9]|1[0-2])(-\d{2})?([^0-9]|$)/.test(name) ||
+        tokens(name).some(isDateToken));
+}
+/**
+ * A rule-abiding name built from `name`: lowercase kebab-case without task
+ * ids, session ids or dates, cut to {@link DOC_NAME_MAX_LENGTH}.
+ *
+ * @param name - The offending name.
+ * @returns The suggested name, or `doc` when nothing is left.
+ * @task T14107
+ */
+export function suggestDocName(name) {
+    // A dated or calver token goes whole, `v` prefix included (`ship-v2026-10-27`).
+    const parts = tokens(name.replace(/(^|[^a-z0-9])v?(19|20)\d{2}-\d{2}(-\d{2})?/gi, '$1 '));
+    const kept = [];
+    // A session id is `ses` and the numeric tokens after it (`ses_<time>_<n>`).
+    let inSession = false;
+    for (let i = 0; i < parts.length; i++) {
+        const token = parts[i] ?? '';
+        if (token === 'ses') {
+            inSession = true;
+            continue;
+        }
+        if (inSession && /^\d+$/.test(token))
+            continue;
+        inSession = false;
+        // A year then a month (`2026 10`, a calver `v2026.10.28`) joins into a
+        // date: drop the year token (with any `v` prefix) and the numbers after it.
+        if (/^v?(19|20)\d{2}$/.test(token) && /^\d{1,2}$/.test(parts[i + 1] ?? '')) {
+            i += /^\d{1,2}$/.test(parts[i + 2] ?? '') ? 2 : 1;
+            continue;
+        }
+        if (!isTaskToken(token) && !isDateToken(token))
+            kept.push(token);
+    }
+    const joined = kept.join('-').replace(/^[^a-z]+/, '');
+    return joined.slice(0, DOC_NAME_MAX_LENGTH).replace(/-+$/, '') || 'doc';
+}
+/**
+ * The rule-abiding slug CLEO mints from a title or file name: its subject
+ * words in kebab-case, without task ids, session ids or dates, at most
+ * `maxLength` characters. Internal writers (ADR allocation, spawn topic slugs,
+ * imports) use it so their slugs pass {@link docNameViolation}; the task stays
+ * a link on the doc, not part of its name.
+ *
+ * @param source - The title or file base name.
+ * @param maxLength - Longest result, for callers that add a prefix.
+ * @returns The slug, or `doc` when the source has no subject words.
+ * @task T14129
+ */
+export function subjectSlug(source, maxLength = DOC_NAME_MAX_LENGTH) {
+    const clean = (text) => suggestDocName(text).slice(0, maxLength).replace(/-+$/, '') || 'doc';
+    const slug = clean(source);
+    if (docNameViolation(slug) === null)
+        return slug;
+    // Cutting can leave a new violation at the end: clean once more, and fall
+    // back to `doc` rather than return a slug the rule refuses.
+    const again = clean(slug);
+    return docNameViolation(again) === null ? again : 'doc';
+}
+/**
+ * Check a doc name (a slug, or a published file name without `.md`) against
+ * the rule. An ADR's leading number and a release note's version are allowed.
+ *
+ * @param name - The slug or file base name.
+ * @param kind - The doc kind, when known; exempt kinds always pass.
+ * @returns The violation, or null when the name is fine.
+ * @task T14107
+ */
+export function docNameViolation(name, kind) {
+    if (kind !== undefined && DOC_NAME_EXEMPT_KINDS.includes(kind))
+        return null;
+    if (kind === 'release-note' && RELEASE_NAME.test(name))
+        return null;
+    const subject = ADR_PREFIX.test(name) ? name.replace(ADR_PREFIX, '') : name;
+    const reasons = [];
+    if (!KEBAB.test(name))
+        reasons.push('format');
+    if (name.length > DOC_NAME_MAX_LENGTH)
+        reasons.push('length');
+    if (tokens(subject).some(isTaskToken))
+        reasons.push('task-id');
+    if (hasSessionId(subject))
+        reasons.push('session-id');
+    if (hasDate(subject))
+        reasons.push('date');
+    if (reasons.length === 0)
+        return null;
+    const prefix = ADR_PREFIX.exec(name)?.[0] ?? '';
+    return { reasons, suggestion: `${prefix}${suggestDocName(subject)}` };
+}
+/** Readable explanation of a violation, for refusals and gate output. */
+export function describeDocNameViolation(name, violation) {
+    const why = {
+        format: 'is not lowercase kebab-case',
+        length: `is longer than ${DOC_NAME_MAX_LENGTH} characters`,
+        'task-id': 'carries a task id',
+        'session-id': 'carries a session id',
+        date: 'carries a date',
+    };
+    return (`doc name "${name}" ${violation.reasons.map((r) => why[r]).join(', ')}; ` +
+        `name docs by subject (e.g. "${violation.suggestion}") and record task, decision and date links in the doc's metadata`);
+}
+/**
+ * Whether a repository path is a published doc the rule governs: a `*.md`
+ * under `docs/`, except generated output and `README.md` files.
+ *
+ * @param path - Repository-relative path, `/`-separated.
+ * @returns True when the rule applies.
+ */
+export function isGovernedDocPath(path) {
+    return (path.startsWith('docs/') &&
+        path.endsWith('.md') &&
+        !path.startsWith('docs/generated/') &&
+        basename(path) !== 'README.md');
+}
+/** The doc kind a governed path's directory implies, for the kind-specific allowances. */
+function kindOfPath(path) {
+    return path.startsWith('docs/release/') ? 'release-note' : undefined;
+}
+/**
+ * Check every governed doc path against the rule. A path in the shrink-only
+ * baseline is tolerated while it still breaks the rule; a baseline entry that
+ * is gone or fixed is stale and must be removed, so the list only shrinks.
+ *
+ * @param paths - Tracked repository paths.
+ * @param baseline - Baselined paths ({@link readDocNameBaseline}).
+ * @returns New violations and stale baseline entries.
+ * @task T14107
+ */
+export function checkDocNames(paths, baseline) {
+    const tolerated = new Set(baseline);
+    const breaking = new Map();
+    for (const file of paths) {
+        if (!isGovernedDocPath(file))
+            continue;
+        const violation = docNameViolation(basename(file, '.md'), kindOfPath(file));
+        if (violation)
+            breaking.set(file, violation);
+    }
+    return {
+        violations: [...breaking]
+            .filter(([file]) => !tolerated.has(file))
+            .map(([file, violation]) => ({ file, ...violation })),
+        stale: baseline.filter((file) => !breaking.has(file)),
+    };
+}
+/**
+ * The baselined doc paths of a repository ({@link DOC_NAME_BASELINE_PATH}).
+ *
+ * @param root - Repository root.
+ * @returns The baselined paths; empty when the file is absent.
+ * @throws When the file exists but is not `{ "files": string[] }`.
+ */
+export function readDocNameBaseline(root) {
+    const path = join(root, DOC_NAME_BASELINE_PATH);
+    if (!existsSync(path))
+        return [];
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    const files = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed.files
+        : undefined;
+    if (!Array.isArray(files) || files.some((f) => typeof f !== 'string'))
+        // @sync-invariant none:input-shape a malformed baseline file is refused before any check runs; nothing is written
+        throw new Error(`${DOC_NAME_BASELINE_PATH} must be { "files": string[] }`);
+    return files.filter((f) => typeof f === 'string');
+}
+//# sourceMappingURL=doc-name-rule.js.map

package/dist/docs/doc-name-rule.js.map

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

package/dist/docs/docs-audit.d.ts

@@ -127,4 +127,3 @@ export declare function verifyAuditTrail(projectRoot: string): AuditVerifyResult
  * @returns Number of audit entries referencing this slug.
  */
 export declare function countAuditEntriesForSlug(projectRoot: string, slug: string): number;
-//# sourceMappingURL=docs-audit.d.ts.map

package/dist/docs/docs-fts.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Full-text index over the docs store (T14197).
+ *
+ * `memory find --docs` ranked every doc body per query with n-gram
+ * similarity (`searchAllProjectDocs`): about 3.5 s on a 3,312-doc store, so
+ * docs stayed an opt-in source. This index lives in the project `cleo.db`:
+ * one row per slugged text doc (the slug's current body, superseded docs
+ * included, so a match on one can surface its current doc), ranked by BM25.
+ *
+ * Two tables, rowid for rowid: `docs_fts`, a contentless FTS5 table (title
+ * and body are tokenized, not stored a second time), and `docs_fts_rows`,
+ * which names the slug and sha256 each rowid holds. FTS5's
+ * `contentless_unindexed` would keep those in one table, but dropping such a
+ * table leaves its `_content` shadow behind (SQLite 3.51 to 3.54), which can
+ * neither be dropped nor let the table be created again: a lost index could
+ * never be rebuilt.
+ *
+ * The index is derived: it holds nothing the store cannot rebuild, and both
+ * tables are classified `derived` (Gate A, never synced). {@link syncDocsFts} keeps it in
+ * step by diffing the slug → sha256 map of `attachments` against the index
+ * and re-reading only the bodies that changed. The docs mutations (add,
+ * update, supersede, remove, merge, import) call it after they succeed, and
+ * every search calls it first, so rows another writer or device added are
+ * picked up too. A missing table is created and filled from the store by the
+ * same diff.
+ *
+ * @task T14197
+ * @epic T14106
+ */
+/** The FTS5 table (project `cleo.db`, class `derived`). */
+export declare const DOCS_FTS_TABLE = "docs_fts";
+/** The slug and sha256 each `docs_fts` rowid holds (class `derived`). */
+export declare const DOCS_FTS_ROWS_TABLE = "docs_fts_rows";
+/** Bytes of a doc body indexed (the n-gram search read the same window). */
+export declare const DOCS_FTS_MAX_BYTES: number;
+/**
+ * How long a search waits for the write lock before it gives up syncing and
+ * reads the index as it is: a read never blocks behind another writer.
+ */
+export declare const DOCS_FTS_READ_BUSY_TIMEOUT_MS = 250;
+/** What one {@link syncDocsFts} did. */
+export interface DocsFtsSync {
+    /** False when this SQLite build has no FTS5 (the caller falls back). */
+    readonly available: boolean;
+    /** Docs (re)indexed. */
+    readonly indexed: number;
+    /** Index rows removed (doc gone, renamed or re-versioned). */
+    readonly removed: number;
+    /** Docs in the index afterwards. */
+    readonly total: number;
+}
+/**
+ * Bring the docs index in step with the store: index every slugged text doc
+ * whose body the index lacks or holds at another sha256, and drop rows whose
+ * slug is gone. Creates (and so rebuilds) the table when it is missing. A
+ * doc whose bytes cannot be read stays out until a later sync can read them.
+ * Throws when the store cannot be written (another writer past
+ * `busyTimeoutMs`, a read-only store); the index is then left as it was.
+ *
+ * @param projectRoot - Project root.
+ * @param opts - `busyTimeoutMs`: how long to wait for the write lock (default:
+ *   the connection's own busy timeout).
+ * @returns What changed.
+ * @example
+ * ```ts
+ * const { indexed, total } = await syncDocsFts(projectRoot);
+ * ```
+ */
+export declare function syncDocsFts(projectRoot: string, opts?: {
+    busyTimeoutMs?: number;
+}): Promise<DocsFtsSync>;
+/**
+ * An FTS5 MATCH expression for free text: each word quoted (so FTS5 syntax in
+ * the query is inert), OR-joined so BM25 ranks docs matching more words higher.
+ *
+ * @param query - The search text.
+ * @returns The expression, or null when the text has no searchable word.
+ */
+export declare function docsFtsMatch(query: string): string | null;
+/**
+ * Slugs of the docs matching `query`, best BM25 rank first. Superseded docs
+ * are included: the caller resolves each to its current doc.
+ *
+ * A read never fails or blocks on the index write: the search first tries a
+ * {@link syncDocsFts} that waits at most {@link DOCS_FTS_READ_BUSY_TIMEOUT_MS}
+ * for the write lock. When that sync cannot write (another writer, a
+ * read-only store), the index is searched as it stands; when there is no
+ * index to search, or anything else fails, the result is null and the caller
+ * falls back. Never throws.
+ *
+ * @param projectRoot - Project root.
+ * @param query - The search text.
+ * @param limit - Maximum slugs.
+ * @returns The slugs, or null when there is no usable index (no FTS5, not
+ *   yet built and not buildable now, or unreadable).
+ * @example
+ * ```ts
+ * const slugs = await searchDocsFts(projectRoot, 'backup retention', 10);
+ * ```
+ */
+export declare function searchDocsFts(projectRoot: string, query: string, limit: number): Promise<string[] | null>;