@cleocode/core 2026.10.27 → 2026.11.1-canary.10

package/dist/docs/lineage.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A doc's supersession chain and the work it serves (T14110).
+ *
+ * Everything is read from what the docs store already records — the
+ * `supersedes` / `superseded_by` pointers that `docs supersede` writes, the
+ * task refs that own the doc, and `related_tasks` (task ids its body names) —
+ * so readers (`docs fetch`, the session briefing) can point from a replaced
+ * doc to the one to read instead, and never surface a superseded doc as
+ * current.
+ *
+ * @task T14110
+ * @epic T14106
+ */
+import type { BrainCompactHit, SearchBrainCompactResult } from '@cleocode/contracts/memory/search.js';
+import type { DocsLineage } from '@cleocode/contracts/operations/docs.js';
+/** Hops followed along `superseded_by` before giving up (a cycle guard). */
+export declare const DOC_LINEAGE_MAX_HOPS = 32;
+/**
+ * Read a doc's lineage by slug.
+ *
+ * @param projectRoot - Project root.
+ * @param slug - The doc's slug.
+ * @returns The lineage, or null when no doc has the slug.
+ */
+export declare function readDocLineage(projectRoot: string, slug: string): Promise<DocsLineage | null>;
+/**
+ * The current docs a task owns: each owner-attached doc resolved along its
+ * `superseded_by` chain, so a superseded doc is never named (T14110).
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task id (`T####`).
+ * @returns Current doc slugs, unique, in attachment order.
+ */
+export declare function currentDocsForTask(projectRoot: string, taskId: string): Promise<string[]>;
+/**
+ * The current docs linked to a decision through `decision_adr_links`, each
+ * resolved along its `superseded_by` chain (T14110).
+ *
+ * @param projectRoot - Project root.
+ * @param decisionId - The decision id (`D####`).
+ * @returns Current doc slugs, unique.
+ */
+export declare function currentDocsForDecision(projectRoot: string, decisionId: string): Promise<string[]>;
+/**
+ * Decisions a doc supersedes, derived from what exists (T14110 · D: Q1a):
+ * the doc links the decision that replaced an older one, and that decision
+ * records `supersedes` in BRAIN. No doc→decision edge is stored.
+ *
+ * @param projectRoot - Project root.
+ * @param linkedDecisions - The doc's live linked `D####` decisions.
+ * @returns The decision ids those decisions supersede, unique.
+ */
+export declare function supersededDecisionsOf(projectRoot: string, linkedDecisions: readonly string[]): Promise<string[]>;
+/**
+ * Attach current docs to a memory search result (T14110 · D: Q2a): each
+ * decision hit gets its linked docs, and every task the query names or a
+ * decision hit belongs to gets `taskDocs`. Superseded docs never appear;
+ * their current doc does. Best-effort: a store that cannot be read leaves
+ * the result as it was.
+ *
+ * @param projectRoot - Project root.
+ * @param query - The search text (task ids in it are honoured).
+ * @param result - The search result, enriched in place.
+ */
+export declare function attachCurrentDocs(projectRoot: string, query: string, result: SearchBrainCompactResult): Promise<void>;
+/**
+ * Full-text search of the project's docs as a `memory find` source (T14152).
+ * Ranks the docs against the query through the derived FTS5 index
+ * (`docs-fts.ts`, BM25, T14197; the n-gram scan of every body is the
+ * fallback when SQLite has no FTS5), then resolves each hit along its
+ * supersession chain: a superseded doc never appears, and a match on one
+ * surfaces its current doc instead (named in `replaces`). Hits are unique by
+ * current slug and carry an RRF score so they rank alongside BRAIN hits.
+ *
+ * @param projectRoot - Project root.
+ * @param query - The search text.
+ * @param limit - Maximum doc hits (default 10).
+ * @returns Doc hits, best first.
+ */
+export declare function findCurrentDocs(projectRoot: string, query: string, limit?: number): Promise<BrainCompactHit[]>;

package/dist/docs/lineage.js

@@ -0,0 +1,246 @@
+/**
+ * A doc's supersession chain and the work it serves (T14110).
+ *
+ * Everything is read from what the docs store already records — the
+ * `supersedes` / `superseded_by` pointers that `docs supersede` writes, the
+ * task refs that own the doc, and `related_tasks` (task ids its body names) —
+ * so readers (`docs fetch`, the session briefing) can point from a replaced
+ * doc to the one to read instead, and never surface a superseded doc as
+ * current.
+ *
+ * @task T14110
+ * @epic T14106
+ */
+import { eq } from 'drizzle-orm';
+import { getDb } from '../store/sqlite.js';
+import { attachmentRefs } from '../store/tasks-schema.js';
+/** Hops followed along `superseded_by` before giving up (a cycle guard). */
+export const DOC_LINEAGE_MAX_HOPS = 32;
+/** Task ids in a JSON-array column, tolerating null and malformed values. */
+function taskIdsOf(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed)
+            ? parsed.filter((v) => typeof v === 'string' && /^T\d+$/.test(v))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read a doc's lineage by slug.
+ *
+ * @param projectRoot - Project root.
+ * @param slug - The doc's slug.
+ * @returns The lineage, or null when no doc has the slug.
+ */
+export async function readDocLineage(projectRoot, slug) {
+    const db = await getDb(projectRoot);
+    // T14288: slug (live or an alias) → the doc's identity → its head and metadata.
+    const { resolveDocRef, supersessionSlugs } = await import('./slug-rename.js');
+    const ref = await resolveDocRef(projectRoot, slug);
+    if (!ref)
+        return null;
+    const row = ref.ownRow;
+    const links = await supersessionSlugs(projectRoot, ref);
+    // Walk superseded_by to the doc that is current now.
+    let currentSlug = ref.slug;
+    let next = links.supersededBy;
+    const seen = new Set([ref.slug]);
+    for (let hop = 0; next && !seen.has(next) && hop < DOC_LINEAGE_MAX_HOPS; hop += 1) {
+        seen.add(next);
+        const hit = await resolveDocRef(projectRoot, next);
+        if (!hit)
+            break;
+        currentSlug = hit.slug;
+        next = (await supersessionSlugs(projectRoot, hit)).supersededBy;
+    }
+    const owners = await db
+        .select({ ownerType: attachmentRefs.ownerType, ownerId: attachmentRefs.ownerId })
+        .from(attachmentRefs)
+        .where(eq(attachmentRefs.attachmentId, row.id))
+        .all();
+    const servesTasks = new Set();
+    for (const o of owners)
+        if (o.ownerType === 'task' && /^T\d+$/.test(o.ownerId))
+            servesTasks.add(o.ownerId);
+    for (const t of taskIdsOf(ref.meta.relatedTasks))
+        servesTasks.add(t);
+    return {
+        lifecycleStatus: ref.meta.lifecycleStatus ?? row.lifecycleStatus,
+        supersedes: links.supersedes,
+        supersededBy: links.supersededBy,
+        currentSlug,
+        servesTasks: [...servesTasks].sort((a, b) => Number(a.slice(1)) - Number(b.slice(1))),
+    };
+}
+/**
+ * The current docs a task owns: each owner-attached doc resolved along its
+ * `superseded_by` chain, so a superseded doc is never named (T14110).
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task id (`T####`).
+ * @returns Current doc slugs, unique, in attachment order.
+ */
+export async function currentDocsForTask(projectRoot, taskId) {
+    const { createAttachmentStore } = await import('../store/attachment-store.js');
+    const store = createAttachmentStore();
+    const out = [];
+    for (const meta of await store.listByOwner('task', taskId, projectRoot)) {
+        const slug = (await store.getExtras(meta.id, projectRoot))?.slug;
+        if (!slug)
+            continue;
+        const current = (await readDocLineage(projectRoot, slug))?.currentSlug ?? slug;
+        if (!out.includes(current))
+            out.push(current);
+    }
+    return out;
+}
+/**
+ * The current docs linked to a decision through `decision_adr_links`, each
+ * resolved along its `superseded_by` chain (T14110).
+ *
+ * @param projectRoot - Project root.
+ * @param decisionId - The decision id (`D####`).
+ * @returns Current doc slugs, unique.
+ */
+export async function currentDocsForDecision(projectRoot, decisionId) {
+    const { listAdrLinksForDecision } = await import('../store/decision-adr-links.js');
+    const out = [];
+    for (const link of await listAdrLinksForDecision(projectRoot, decisionId)) {
+        const current = (await readDocLineage(projectRoot, link.adrSlug))?.currentSlug ?? link.adrSlug;
+        if (!out.includes(current))
+            out.push(current);
+    }
+    return out;
+}
+/**
+ * Decisions a doc supersedes, derived from what exists (T14110 · D: Q1a):
+ * the doc links the decision that replaced an older one, and that decision
+ * records `supersedes` in BRAIN. No doc→decision edge is stored.
+ *
+ * @param projectRoot - Project root.
+ * @param linkedDecisions - The doc's live linked `D####` decisions.
+ * @returns The decision ids those decisions supersede, unique.
+ */
+export async function supersededDecisionsOf(projectRoot, linkedDecisions) {
+    if (linkedDecisions.length === 0)
+        return [];
+    const { recallDecision } = await import('../memory/decisions.js');
+    const out = new Set();
+    for (const id of linkedDecisions) {
+        const decision = await recallDecision(projectRoot, id);
+        if (decision?.supersedes)
+            out.add(decision.supersedes);
+    }
+    return [...out];
+}
+/**
+ * Attach current docs to a memory search result (T14110 · D: Q2a): each
+ * decision hit gets its linked docs, and every task the query names or a
+ * decision hit belongs to gets `taskDocs`. Superseded docs never appear;
+ * their current doc does. Best-effort: a store that cannot be read leaves
+ * the result as it was.
+ *
+ * @param projectRoot - Project root.
+ * @param query - The search text (task ids in it are honoured).
+ * @param result - The search result, enriched in place.
+ */
+export async function attachCurrentDocs(projectRoot, query, result) {
+    try {
+        const tasks = new Set(query.match(/\bT\d{2,}\b/g) ?? []);
+        const { recallDecision } = await import('../memory/decisions.js');
+        for (const hit of result.results) {
+            if (hit.type !== 'decision' || hit.scope === 'global')
+                continue;
+            const docs = await currentDocsForDecision(projectRoot, hit.id);
+            if (docs.length > 0)
+                hit.docs = docs;
+            const taskId = (await recallDecision(projectRoot, hit.id))?.contextTaskId;
+            if (taskId)
+                tasks.add(taskId);
+        }
+        const taskDocs = [];
+        for (const taskId of tasks) {
+            const docs = await currentDocsForTask(projectRoot, taskId);
+            if (docs.length > 0)
+                taskDocs.push({ taskId, docs });
+        }
+        if (taskDocs.length > 0)
+            result.taskDocs = taskDocs;
+    }
+    catch {
+        // Docs store unavailable — search results stand on their own.
+    }
+}
+/** RRF constant shared with BRAIN retrieval: a hit at rank r scores 1/(r + 60). */
+const DOC_RRF_K = 60;
+/**
+ * Full-text search of the project's docs as a `memory find` source (T14152).
+ * Ranks the docs against the query through the derived FTS5 index
+ * (`docs-fts.ts`, BM25, T14197; the n-gram scan of every body is the
+ * fallback when SQLite has no FTS5), then resolves each hit along its
+ * supersession chain: a superseded doc never appears, and a match on one
+ * surfaces its current doc instead (named in `replaces`). Hits are unique by
+ * current slug and carry an RRF score so they rank alongside BRAIN hits.
+ *
+ * @param projectRoot - Project root.
+ * @param query - The search text.
+ * @param limit - Maximum doc hits (default 10).
+ * @returns Doc hits, best first.
+ */
+export async function findCurrentDocs(projectRoot, query, limit = 10) {
+    // Over-fetch: superseded matches fold into their current doc.
+    const { searchDocsFts } = await import('./docs-fts.js');
+    let slugs = await searchDocsFts(projectRoot, query, limit * 3);
+    if (slugs === null) {
+        // No usable index (no FTS5, or none yet and the store is busy): the n-gram
+        // scan, and no doc hits when even that cannot read the store.
+        try {
+            const { searchAllProjectDocs } = await import('./docs-ops.js');
+            const { hits } = await searchAllProjectDocs(query, { projectRoot, limit: limit * 3 });
+            slugs = hits.flatMap((hit) => (hit.slug ? [hit.slug] : []));
+        }
+        catch {
+            return [];
+        }
+    }
+    const out = [];
+    for (const slug of slugs) {
+        if (out.length >= limit)
+            break;
+        const lineage = await readDocLineage(projectRoot, slug);
+        if (!lineage)
+            continue;
+        const current = lineage.currentSlug;
+        // Superseded with no successor recorded: nothing current to surface.
+        if (current === slug && lineage.lifecycleStatus === 'superseded')
+            continue;
+        const existing = out.find((h) => h.id === current);
+        if (existing) {
+            if (current !== slug && existing.replaces === undefined)
+                existing.replaces = slug;
+            continue;
+        }
+        // T14288: the current doc's metadata through its identity.
+        const { resolveDocRef } = await import('./slug-rename.js');
+        const ref = await resolveDocRef(projectRoot, current);
+        const status = ref ? (ref.meta.lifecycleStatus ?? ref.ownRow.lifecycleStatus) : null;
+        if (!ref || status === 'superseded')
+            continue;
+        out.push({
+            id: current,
+            type: 'doc',
+            title: ref.meta.summary ?? current,
+            date: ref.ownRow.createdAt,
+            rrfScore: 1 / (out.length + 1 + DOC_RRF_K),
+            ...(current !== slug ? { replaces: slug } : {}),
+            _next: { fetch: `cleo docs fetch ${current}` },
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=lineage.js.map

package/dist/docs/lineage.js.map

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

package/dist/docs/migrate-agent-outputs.d.ts

@@ -90,4 +90,3 @@ export interface MigrateAgentOutputsOptions {
  * @returns Summary of migration results.
  */
 export declare function migrateAgentOutputs(options: MigrateAgentOutputsOptions): Promise<AgentOutputMigrationResult>;
-//# sourceMappingURL=migrate-agent-outputs.d.ts.map

package/dist/docs/modernize/apply.d.ts

@@ -0,0 +1,138 @@
+/**
+ * `cleo docs modernize --apply` and `--rollback` (T14113).
+ *
+ * Apply executes a {@link DocsModernizePlan}:
+ *
+ * 0. **Blobs.** Every scanned file's bytes are hash-verified into the blob
+ *    store before anything else runs; nothing is removed without that.
+ * 1. **Bodies.** Each survivor's text gets every `merge-into` row folded in
+ *    ({@link mergeDocBodies} never drops content) and its relative `.md`
+ *    links rewritten to `[[slug]]` wikilinks.
+ * 2. **Store.** Survivors are stored under their slug (`ingest`); a slug the
+ *    store already holds is merged into, never replaced (`merge`). A merged
+ *    or deleted file is recorded where its content went (`fold`) and, when
+ *    its bytes are not already a doc, stored under its legacy name and
+ *    superseded by the survivor (`supersede`).
+ * 3. **Files.** Survivors are written to their canonical path (`write-file`)
+ *    and every other scanned path is removed (`remove-file`).
+ * 4. **Graph.** Each survivor's body links become `links-to` edges (`link`)
+ *    and the column-derived edges are rebuilt (always, in `finally`).
+ *
+ * Write-ahead: every step is appended to `.cleo/modernize/<runId>.ops.jsonl`
+ * as `pending` (with the values it will replace) before it acts and as
+ * `done` after; replaced bytes are copied under `.cleo/modernize/<runId>/`.
+ * {@link rollbackDocsModernize} walks the steps backwards, appends
+ * `reversed` per step (so a failed rollback resumes where it stopped), and
+ * refuses to overwrite a file edited since the apply.
+ *
+ * @task T14113
+ * @epic T14106
+ */
+import type { DocsModernizePlan, DocsModernizeReceipt, DocsModernizeReceiptOp } from '@cleocode/contracts';
+/** Identity recorded on every store write modernize makes. */
+export declare const MODERNIZE_ACTOR = "cleo docs modernize";
+/** Options for {@link applyDocsModernize}. */
+export interface ApplyDocsModernizeOptions {
+    /** The plan to execute (from `planDocsModernize`, possibly edited). */
+    readonly plan: DocsModernizePlan;
+    /** Project root (store, receipts). */
+    readonly projectRoot: string;
+    /** Clock override (tests). */
+    readonly now?: () => Date;
+    /** Apply even when the root is not a clean git checkout (explicit `--allow-dirty`). */
+    readonly allowDirty?: boolean;
+    /**
+     * Rewrite relative links to planned docs as `[[slug]]` wikilinks (opt-in,
+     * `--wikilinks`). By default links stay plain markdown, re-pointed at the
+     * new paths, so they still render on GitHub (T14185).
+     */
+    readonly wikilinks?: boolean;
+    /**
+     * The checkout the command was started from (a CLEO worktree, T14188); the
+     * plan root may sit in it. The store, journal and backups stay at
+     * `projectRoot`. Default: the project root.
+     */
+    readonly checkoutRoot?: string;
+}
+/** Raised when the tree moved since the plan was made. */
+export declare class DocsModernizeStaleError extends Error {
+    /** Stable code for the envelope. */
+    readonly code = "E_MODERNIZE_STALE";
+}
+/** Raised when `--apply` meets uncommitted changes, or cannot prove there are none. */
+export declare class DocsModernizeDirtyError extends Error {
+    /** Stable code for the envelope. */
+    readonly code = "E_MODERNIZE_DIRTY";
+}
+/** Raised when bytes cannot be confirmed or backed up before a step changes them. */
+export declare class DocsModernizeBlobError extends Error {
+    /** Stable code for the envelope. */
+    readonly code = "E_MODERNIZE_BLOB";
+}
+/** Raised when a receipt cannot be found, was already rolled back, or a file changed since. */
+export declare class DocsModernizeReceiptError extends Error {
+    /** Stable code for the envelope. */
+    readonly code = "E_MODERNIZE_RECEIPT";
+}
+/**
+ * Path of a run's receipt.
+ *
+ * @param projectRoot - Project root.
+ * @param runId - Run id.
+ * @returns Absolute receipt path.
+ */
+export declare function modernizeReceiptPath(projectRoot: string, runId: string): string;
+/**
+ * Path of a run's write-ahead step journal.
+ *
+ * @param projectRoot - Project root.
+ * @param runId - Run id.
+ * @returns Absolute journal path.
+ */
+export declare function journalPath(projectRoot: string, runId: string): string;
+/** Write-ahead journal of one run's steps (`<runId>.ops.jsonl`). */
+export declare class StepJournal {
+    private readonly path;
+    private readonly ops;
+    constructor(path: string);
+    /** Append a step as `pending` before it acts; returns its index. */
+    begin(op: Partial<DocsModernizeReceiptOp> & Pick<DocsModernizeReceiptOp, 'op'>): number;
+    /** Mark a step `done`, with anything learned while acting. */
+    done(i: number, patch?: Partial<DocsModernizeReceiptOp>): void;
+    /** Every step so far. */
+    list(): DocsModernizeReceiptOp[];
+}
+/**
+ * Execute a modernize plan, journaling every step ahead of it.
+ *
+ * @param options - Plan, project root and clock.
+ * @returns The finished receipt.
+ * @throws DocsModernizeStaleError when a planned file is missing or changed.
+ * @throws DocsModernizeDirtyError when a `tree` run cannot prove a clean checkout.
+ * @throws DocsModernizeBlobError when bytes cannot be confirmed or backed up.
+ */
+export declare function applyDocsModernize(options: ApplyDocsModernizeOptions): Promise<DocsModernizeReceipt>;
+/**
+ * Read a run's receipt, with its steps taken from the write-ahead journal
+ * (which records steps the receipt file may not have caught up with).
+ *
+ * @param projectRoot - Project root.
+ * @param runId - Run id.
+ * @param checkoutRoot - The invoking checkout the run's root may sit in (T14188).
+ * @returns The receipt.
+ * @throws DocsModernizeReceiptError when it does not exist.
+ */
+export declare function readDocsModernizeReceipt(projectRoot: string, runId: string, checkoutRoot?: string): DocsModernizeReceipt;
+/**
+ * Reverse an apply run from its journal, newest step first. Each reversed
+ * step is journaled, so a rollback that stops part-way resumes on retry.
+ *
+ * @param projectRoot - Project root.
+ * @param runId - Run id from the apply receipt.
+ * @param now - Clock override (tests).
+ * @param checkoutRoot - The invoking checkout the run's root may sit in (T14188).
+ * @returns The receipt, now stamped `rolledBackAt`.
+ * @throws DocsModernizeReceiptError when the receipt is missing, already
+ *   rolled back, or a file was edited after the apply.
+ */
+export declare function rollbackDocsModernize(projectRoot: string, runId: string, now?: () => Date, checkoutRoot?: string): Promise<DocsModernizeReceipt>;