@cleocode/core 2026.10.12 → 2026.10.13-rc.ci.682

package/dist/docs/section-write-path.js

@@ -0,0 +1,423 @@
+/**
+ * Docs update write path through the section CRDT merge layer (T13355 ·
+ * spec `cleodocs-rearch-design` §2 option b · D11165).
+ *
+ * Every `cleo docs update` carrying new inline text is projected through
+ * this module after the legacy whole-row write lands (`docs-update.ts`):
+ *
+ *   1. Resolve the doc's immutable uid, adopting a legacy doc into the
+ *      conduit family on first sight ({@link ensureConduitDoc}).
+ *   2. Split the new text into sections and resolve the previous head's
+ *      section texts from its version blob — the single-writer vs.
+ *      concurrent discriminator (T13589).
+ *   3. Apply each section's edit to its local Loro state
+ *      (`section-merge.ts`): while the stored state equals the head's text
+ *      the input projects EXACTLY (re-seed; replaces and deletions apply
+ *      verbatim — the primitives can only append, so re-seeding is the
+ *      honest encoding); a concurrent edit that is a pure append composes
+ *      onto the stored state so both survive (T13585); a concurrent
+ *      NON-append edit is never fabricated into a merge — it is landed as
+ *      its own version row and recorded as a head conflict (T13595).
+ *   4. Read the MERGED text back out of the merged Loro states — never out
+ *      of the input — and write its content-addressed blob so the version
+ *      row's `storage_key` resolves.
+ *   5. Append the merged text as a DAG version row
+ *      (`appendConduitAttachmentVersion`, parent = the previous head's
+ *      version) — history is append-only.
+ *   6. Project the merged text into the current-version row via
+ *      {@link upsertConduitDocHead}: the max-HLC head wins and a losing
+ *      concurrent head is recorded as a conflict, never silently shadowed
+ *      (typed rule `docs.head.max-hlc`).
+ *   7. Rebase the local section states onto the landed version and rebuild
+ *      the derived contributors rollup.
+ *
+ * Steps 1–7 run inside ONE `BEGIN IMMEDIATE` transaction
+ * ({@link withConduitDocWriteTransaction}, T13583): a failure after the
+ * version append rolls everything back, so the next update cannot fork
+ * onto a half-landed projection. The body uses only sync-driver accessors
+ * and sync `node:fs` calls, so no real I/O yield can admit another writer
+ * on the connection mid-transaction (the documented constraint).
+ *
+ * Loro owns LOCAL-ONLY section state; the syncing rows are owned by the
+ * Stage C journal merge engine — one merge authority per table (§2).
+ *
+ * @module
+ * @task T13355
+ * @epic T13340
+ * @saga T13339
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getCleoDirAbsolute } from '../paths.js';
+import { appendConduitAttachmentVersion, ensureConduitDoc, getConduitAttachmentVersion, getConduitDocHead, readSectionCrdtState, rebaseSectionCrdtStates, rebuildConduitAttachmentContributors, resolveConduitDocUid, upsertConduitDocHead, withConduitDocWriteTransaction, writeSectionCrdtState, } from '../store/conduit-doc-history.js';
+import { resolveBoundSession } from '../store/session-store.js';
+import { compareHlc, encodeHlc, genesisHlc, parseHlc, tick } from '../store/sync/hlc.js';
+import { listSectionLeases, SectionLeaseManager, } from './section-leases.js';
+import { applySectionTextEdit, joinSections, sectionId, sectionStateText, splitDocIntoSections, } from './section-merge.js';
+/**
+ * TTL granted by the write path's lease acquisitions (seconds). Inside
+ * llmtxt's 1–300 s range; long enough to cover an edit burst, short enough
+ * that a dead session's lease dies quickly (AC4: lease state never outlives
+ * its session without renew).
+ */
+export const SECTION_LEASE_TTL_SECONDS = 60;
+/**
+ * This device's docs-writer HLC state. Module-level (not the journal's
+ * persisted `_sync_clock`): the docs projection's HLC orders the
+ * current-version row only, is seeded from the stored head on open, and a
+ * reset across processes is safe because the head comparison is (phys, ctr,
+ * replica) — a fresher wall clock always wins.
+ */
+let writerReplica = null;
+let lastIssued = null;
+/** The local writer's replica id (one random UUID per process). */
+function localWriterReplica() {
+    writerReplica ??= randomUUID();
+    return writerReplica;
+}
+/**
+ * Mint the next local head HLC, strictly above the stored head when one
+ * exists (so a local write always advances the max-HLC projection).
+ *
+ * @param headHlc - The stored head's HLC, or `null` when no projection yet.
+ * @param wallMs - The physical candidate (defaults to `Date.now()`).
+ * @returns The encoded HLC.
+ */
+function mintHeadHlc(headHlc, wallMs = Date.now()) {
+    let base = lastIssued ?? genesisHlc(localWriterReplica());
+    if (headHlc !== null) {
+        try {
+            const head = parseHlc(headHlc);
+            if (compareHlc(head, base) > 0)
+                base = { ...head, replica: localWriterReplica() };
+        }
+        catch {
+            // A stored head this process cannot parse is ignored: the mint below
+            // still lands at the wall clock, ahead of any plausible stored head.
+        }
+    }
+    lastIssued = tick(base, wallMs);
+    return encodeHlc(lastIssued);
+}
+/**
+ * Rough token count for the version row (whitespace split; display only).
+ *
+ * @param text - The text to count.
+ * @returns The token count.
+ */
+function countTokens(text) {
+    return text.split(/\s+/).filter((w) => w.length > 0).length;
+}
+/**
+ * Resolve the on-disk path of a version row's content-addressed blob.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param storageKey - The version's `storage_key` (`<2>/<rest>.md`).
+ * @returns The absolute blob path.
+ */
+function versionBlobPath(projectRoot, storageKey) {
+    return join(getCleoDirAbsolute(projectRoot), 'attachments', 'sha256', storageKey);
+}
+/**
+ * Read the previous head version's merged text and split it into sections.
+ *
+ * This is the single-writer vs. concurrent discriminator (T13589): a
+ * section whose stored state text equals the head's section text holds no
+ * unlanded concurrent edit. Sync `node:fs` only — the caller runs inside
+ * the write transaction, which must not yield to real I/O.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param head - The current head row.
+ * @returns The head's sections in document order, or `null` when the head's
+ *   version or its blob is not resolvable locally (callers then take the
+ *   single-writer path — see {@link applySectionTextEdit}).
+ */
+async function readHeadSectionTexts(projectRoot, head) {
+    const version = await getConduitAttachmentVersion(projectRoot, head.headVersionUid);
+    if (!version?.storageKey)
+        return null;
+    try {
+        const text = readFileSync(versionBlobPath(projectRoot, version.storageKey), 'utf-8');
+        return splitDocIntoSections(text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the merged text's content-addressed blob so the version row's
+ * `storage_key` resolves. Sync `node:fs` only (transaction constraint, see
+ * {@link withConduitDocWriteTransaction}); content-addressed, so an existing
+ * file is reused and an orphan from a rolled-back transaction is harmless.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param storageKey - The version's `storage_key`.
+ * @param text - The merged text the key addresses.
+ */
+function writeMergedBlob(projectRoot, storageKey, text) {
+    const path = versionBlobPath(projectRoot, storageKey);
+    if (existsSync(path))
+        return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, 'utf-8');
+}
+/**
+ * Project one docs update through the section CRDT merge layer.
+ *
+ * The whole projection — adopt, section-state writes, version append, head
+ * upsert, rebase, contributors rebuild — is one transaction
+ * ({@link withConduitDocWriteTransaction}); the merged text is read back
+ * from the merged Loro states, so concurrent same-base section edits both
+ * survive into the version row and the head projection.
+ *
+ * Lease coordination (T13356, ADVISORY): before the transaction, the
+ * projection resolves the caller's session (input, else the bound session,
+ * gate 16) and acquires/renews a lease for every section the edit touches.
+ * A section leased by another live session yields a {@link SectionLeaseNotice}
+ * — the 409 equivalent as data. The edit PROCEEDS regardless: "409 is a
+ * social signal, not a hard lock" (llmtxt T285); the CRDT layer guarantees
+ * nothing is lost when coordination fails. Leases acquired for a projection
+ * that then rolls back are released, so a failed edit leaves no stale claim.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param input - The update facts.
+ * @returns The merge outcome.
+ */
+export async function projectDocUpdateThroughSections(projectRoot, input) {
+    const existingUid = await resolveConduitDocUid(projectRoot, input.slug);
+    const contentBuffer = Buffer.from(input.content, 'utf-8');
+    // T13356 — advisory lease coordination, before the transaction. Unbound
+    // callers (no input session, no bound session) edit uncoordinated: leases
+    // are per-session state and there is nothing to acquire under.
+    const boundSessionId = input.sessionId ?? (await resolveBoundSession(projectRoot))?.session.id ?? null;
+    const leaseNotices = [];
+    const acquiredThisRun = [];
+    if (boundSessionId !== null) {
+        const leaseManager = new SectionLeaseManager(projectRoot, {
+            sessionId: boundSessionId,
+            holder: input.authorAgentId,
+        });
+        const docUidForLeases = existingUid ?? input.slug;
+        for (const [index, text] of splitDocIntoSections(input.content).entries()) {
+            const id = sectionId(index);
+            const stored = existingUid !== null ? await readSectionCrdtState(projectRoot, docUidForLeases, id) : null;
+            // Only sections the edit actually touches are coordinated: unchanged
+            // sections carry no edit, so claiming them would only block others.
+            const touches = stored === null || sectionStateText(stored.snapshot) !== text;
+            if (!touches)
+                continue;
+            const acquired = await leaseManager.acquire(input.slug, id, SECTION_LEASE_TTL_SECONDS, input.changeSummary ?? 'section edit');
+            if (acquired.ok) {
+                acquiredThisRun.push(id);
+                continue;
+            }
+            if (acquired.conflict.sessionId === boundSessionId) {
+                // Our own lease: continued edits renew it (T13356 AC2).
+                const renewed = await leaseManager.renew(input.slug, id, SECTION_LEASE_TTL_SECONDS);
+                if (!renewed.ok) {
+                    // Expired between the probes: re-acquire (takeover of our own
+                    // stale lease). A foreign live lease here is reported below.
+                    const retry = await leaseManager.acquire(input.slug, id, SECTION_LEASE_TTL_SECONDS, input.changeSummary ?? 'section edit');
+                    if (retry.ok) {
+                        acquiredThisRun.push(id);
+                        continue;
+                    }
+                    leaseNotices.push(noticeOf(id, retry.conflict));
+                }
+                continue;
+            }
+            leaseNotices.push(noticeOf(id, acquired.conflict));
+        }
+    }
+    try {
+        return await withConduitDocWriteTransaction(projectRoot, async () => {
+            const { uid: docUid, adopted } = existingUid !== null
+                ? { uid: existingUid, adopted: false }
+                : await ensureConduitDoc(projectRoot, {
+                    slug: input.slug,
+                    authorAgentId: input.authorAgentId,
+                    content: contentBuffer,
+                });
+            // Resolve the previous head's section texts FIRST — the default
+            // single-writer vs. concurrent discriminator for every section below
+            // (T13589). A caller-declared base (T13674) REPLACES it: the incoming
+            // edit is then judged against the base it was authored from, so a
+            // stale base composes (append) or conflicts (non-append) instead of
+            // re-seeding over a concurrent writer's landed edit.
+            const previousHead = await getConduitDocHead(projectRoot, docUid);
+            const headSections = previousHead !== null ? await readHeadSectionTexts(projectRoot, previousHead) : null;
+            const referenceSections = input.baseSections !== undefined && input.baseSections !== null
+                ? input.baseSections
+                : headSections;
+            // Apply each section's edit onto its stored Loro state and read the
+            // MERGED text back out of the state — never out of the input (T13585).
+            const sections = splitDocIntoSections(input.content);
+            const mergedSections = [];
+            const sectionsModified = [];
+            const conflictedSections = [];
+            for (const [index, text] of sections.entries()) {
+                const id = sectionId(index);
+                const stored = await readSectionCrdtState(projectRoot, docUid, id);
+                const { snapshot, changed, conflicted } = applySectionTextEdit(stored?.snapshot ?? null, text, referenceSections?.[index] ?? null);
+                if (changed || stored === null) {
+                    await writeSectionCrdtState(projectRoot, {
+                        attachmentUid: docUid,
+                        sectionId: id,
+                        snapshot,
+                        baseVersionUid: stored?.baseVersionUid ?? null,
+                    });
+                }
+                if (changed)
+                    sectionsModified.push(id);
+                if (conflicted)
+                    conflictedSections.push(id);
+                mergedSections.push(sectionStateText(snapshot));
+            }
+            const mergedText = joinSections(mergedSections);
+            // Append the DAG version row (parent = the previous head's version).
+            const contentHash = createHash('sha256').update(mergedText, 'utf-8').digest('hex');
+            const size = Buffer.byteLength(mergedText, 'utf-8');
+            const storageKey = `${contentHash.slice(0, 2)}/${contentHash.slice(2)}.md`;
+            // Write the blob BEFORE the insert so a committed row never references
+            // missing bytes; a rollback only leaves a harmless content-addressed
+            // orphan (reused by a later identical projection).
+            writeMergedBlob(projectRoot, storageKey, mergedText);
+            const parentVersionUid = input.parentVersionUid !== undefined
+                ? input.parentVersionUid
+                : (previousHead?.headVersionUid ?? null);
+            const version = await appendConduitAttachmentVersion(projectRoot, {
+                attachmentUid: docUid,
+                parentVersionUid,
+                authorAgentId: input.authorAgentId,
+                storageKey,
+                contentHash,
+                originalSize: size,
+                compressedSize: size,
+                tokens: countTokens(mergedText),
+                changeType: 'patch',
+                ...(input.changeSummary !== undefined ? { changeSummary: input.changeSummary } : {}),
+                sectionsModified,
+                tokensAdded: countTokens(input.content),
+            });
+            // Project into the current-version row under the max-HLC rule. The
+            // version row survives even when a concurrent head wins, so nothing
+            // written above is lost.
+            const headHlc = input.hlc ?? mintHeadHlc(previousHead?.headHlc ?? null);
+            const head = await upsertConduitDocHead(projectRoot, {
+                attachmentUid: docUid,
+                headVersionUid: version.uid ?? '',
+                headHlc,
+            });
+            // T13595: a non-append concurrent section edit cannot be merged without
+            // fabricating text (the primitives are append-only), so land the incoming
+            // edit as its OWN version row — append-only history already preserves
+            // both — keep the stored projection as the head, and record the conflict
+            // on the head, mirroring the docs.head.max-hlc semantics. The conflict
+            // upsert uses the previous head's HLC, which is strictly below the
+            // projection HLC in the local-mint path, so the incoming version always
+            // loses honestly. (With an explicit `hlc` at or below the previous
+            // head's, the projection itself loses first and the incoming version
+            // records a second conflict — both stay visible, nothing is invented.)
+            const conflicts = [];
+            if (conflictedSections.length > 0) {
+                const incomingHash = createHash('sha256').update(input.content, 'utf-8').digest('hex');
+                const incomingKey = `${incomingHash.slice(0, 2)}/${incomingHash.slice(2)}.md`;
+                writeMergedBlob(projectRoot, incomingKey, input.content);
+                const incoming = await appendConduitAttachmentVersion(projectRoot, {
+                    attachmentUid: docUid,
+                    parentVersionUid,
+                    authorAgentId: input.authorAgentId,
+                    storageKey: incomingKey,
+                    contentHash: incomingHash,
+                    originalSize: Buffer.byteLength(input.content, 'utf-8'),
+                    compressedSize: Buffer.byteLength(input.content, 'utf-8'),
+                    tokens: countTokens(input.content),
+                    changeType: 'patch',
+                    changeSummary: `concurrent non-append edit on ${conflictedSections.join(', ')} — conflict recorded, not merged`,
+                    sectionsModified: conflictedSections,
+                    tokensAdded: countTokens(input.content),
+                });
+                if (previousHead !== null && incoming.uid) {
+                    await upsertConduitDocHead(projectRoot, {
+                        attachmentUid: docUid,
+                        headVersionUid: incoming.uid,
+                        headHlc: previousHead.headHlc,
+                    });
+                    for (const sectionId of conflictedSections) {
+                        conflicts.push({
+                            sectionId,
+                            incomingVersionUid: incoming.uid,
+                            projectionVersionUid: version.uid ?? '',
+                        });
+                    }
+                }
+            }
+            // A landed version rebases the local section states; the derived
+            // contributors rollup is rebuilt from the versions table.
+            if (version.uid) {
+                await rebaseSectionCrdtStates(projectRoot, docUid, version.uid);
+            }
+            await rebuildConduitAttachmentContributors(projectRoot, docUid);
+            return {
+                docUid,
+                adopted,
+                mergedText,
+                sectionsModified,
+                version,
+                head,
+                previousHeadVersionUid: previousHead?.headVersionUid ?? null,
+                conflicts,
+                leaseNotices,
+            };
+        });
+    }
+    catch (err) {
+        // The projection rolled back: release the leases acquired for it, so a
+        // failed edit leaves no stale claim. (Renewed pre-existing leases stay —
+        // the session still holds them.)
+        if (boundSessionId !== null && acquiredThisRun.length > 0) {
+            const leaseManager = new SectionLeaseManager(projectRoot, {
+                sessionId: boundSessionId,
+                holder: input.authorAgentId,
+            });
+            for (const section of acquiredThisRun) {
+                await leaseManager.release(input.slug, section);
+            }
+        }
+        throw err;
+    }
+}
+/** Conflict view of a lease for a {@link SectionLeaseNotice}. */
+function noticeOf(sectionIdValue, conflict) {
+    return {
+        sectionId: sectionIdValue,
+        holder: conflict.holder,
+        sessionId: conflict.sessionId,
+        expiresAt: conflict.expiresAt,
+    };
+}
+/**
+ * Release every section lease this session holds for a doc — the "release
+ * on completion" path of T13356 AC2: a session calls this when it finishes
+ * editing the doc, so the sections are free for the next editor before the
+ * TTL would have expired them.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param slug - The doc's live slug (leases are keyed by it).
+ * @param sessionId - The finishing session (only its own leases are released).
+ * @returns The section ids released.
+ */
+export async function releaseSectionLeases(projectRoot, slug, sessionId) {
+    const leaseManager = new SectionLeaseManager(projectRoot, { sessionId });
+    const released = [];
+    for (const lease of await listSectionLeases(projectRoot, slug)) {
+        if (lease.sessionId !== sessionId)
+            continue;
+        if (await leaseManager.release(lease.slug, lease.sectionId)) {
+            released.push(lease.sectionId);
+        }
+    }
+    return released;
+}
+//# sourceMappingURL=section-write-path.js.map

package/dist/docs/section-write-path.js.map

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

package/dist/docs/stats.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `docs.stats` — per-project CleoDocs adoption metrics (T13363, spec §7/§9).
+ *
+ * Emitted so the CleoDocs re-architecture is judged by behaviour, not by
+ * file counts in the store:
+ *
+ *   - **add:update ratio** — `docs.add` vs `docs.update` entries in the docs
+ *     audit log (`.cleo/audit/docs-audit.jsonl`, via {@link readAuditLog}).
+ *     The pilot's starting point is ~10:1.
+ *   - **loose-markdown count** — `*.md` files TRACKED BY GIT outside the
+ *     CleoDocs store (`git ls-files '*.md'` minus the store). Using the index
+ *     makes the scan gitignore-aware by construction: dependency trees,
+ *     VCS internals, `.cleo/council-runs`, and nested git worktrees never
+ *     appear because real projects ignore them. The Council baseline counts
+ *     (~751 axiom-app + 1,265 admin-operations) were of tracked/counted
+ *     loose files, so this is the comparable shape. UNTracked loose `.md`
+ *     files are intentionally out of scope — they are invisible to the
+ *     adoption signal. Outside a git work tree the metric is 0 (there is no
+ *     tracked-files notion to measure).
+ *   - **wikilinks edges** — row count of the `docs_wikilinks` graph table
+ *     (T11826), through the chokepoint drizzle handle.
+ *   - **decisions linked** — live `decision_adr_links` rows (status
+ *     `linked`, T13359). The legacy ledger `adrPath` field has no read
+ *     accessor, so only the link table contributes.
+ *
+ * Read-only: never writes to the store, the filesystem, or the audit log.
+ *
+ * @module
+ * @task T13363
+ * @task T13629 — loose-markdown scan is git ls-files-based (gitignore-aware)
+ * @epic T13340
+ * @saga T13339
+ */
+import type { DocsStatsResult, LooseMarkdownMetrics } from '@cleocode/contracts/operations/docs.js';
+/**
+ * Count loose `*.md` files — git-tracked markdown outside the CleoDocs
+ * store. `git ls-files '*.md'` from the project root returns the tracked
+ * markdown paths (gitignore-aware); the store and dependency trees are then
+ * filtered defensively. Untracked files are intentionally NOT counted.
+ *
+ * @param projectRoot - Absolute project root (must be a git work tree).
+ * @returns The count plus what was scanned and excluded; `count` is 0 with
+ *   empty `scannedDirs` when the root is not a git work tree.
+ */
+export declare function countLooseMarkdown(projectRoot: string): LooseMarkdownMetrics;
+/**
+ * Compute the per-project adoption metrics for `docs.stats` (T13363).
+ *
+ * @param opts.projectRoot - Absolute path to the CLEO project root.
+ * @returns The metrics envelope (read-only; nothing is written).
+ * @task T13363
+ */
+export declare function computeDocsStats(opts: {
+    projectRoot: string;
+}): Promise<DocsStatsResult>;
+//# sourceMappingURL=stats.d.ts.map

package/dist/docs/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/docs/stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAEV,eAAe,EACf,oBAAoB,EACrB,MAAM,wCAAwC,CAAC;AAgBhD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,CAkB5E;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAsC9F"}

package/dist/docs/stats.js

@@ -0,0 +1,119 @@
+/**
+ * `docs.stats` — per-project CleoDocs adoption metrics (T13363, spec §7/§9).
+ *
+ * Emitted so the CleoDocs re-architecture is judged by behaviour, not by
+ * file counts in the store:
+ *
+ *   - **add:update ratio** — `docs.add` vs `docs.update` entries in the docs
+ *     audit log (`.cleo/audit/docs-audit.jsonl`, via {@link readAuditLog}).
+ *     The pilot's starting point is ~10:1.
+ *   - **loose-markdown count** — `*.md` files TRACKED BY GIT outside the
+ *     CleoDocs store (`git ls-files '*.md'` minus the store). Using the index
+ *     makes the scan gitignore-aware by construction: dependency trees,
+ *     VCS internals, `.cleo/council-runs`, and nested git worktrees never
+ *     appear because real projects ignore them. The Council baseline counts
+ *     (~751 axiom-app + 1,265 admin-operations) were of tracked/counted
+ *     loose files, so this is the comparable shape. UNTracked loose `.md`
+ *     files are intentionally out of scope — they are invisible to the
+ *     adoption signal. Outside a git work tree the metric is 0 (there is no
+ *     tracked-files notion to measure).
+ *   - **wikilinks edges** — row count of the `docs_wikilinks` graph table
+ *     (T11826), through the chokepoint drizzle handle.
+ *   - **decisions linked** — live `decision_adr_links` rows (status
+ *     `linked`, T13359). The legacy ledger `adrPath` field has no read
+ *     accessor, so only the link table contributes.
+ *
+ * Read-only: never writes to the store, the filesystem, or the audit log.
+ *
+ * @module
+ * @task T13363
+ * @task T13629 — loose-markdown scan is git ls-files-based (gitignore-aware)
+ * @epic T13340
+ * @saga T13339
+ */
+import { spawnSync } from 'node:child_process';
+import { count } from 'drizzle-orm';
+import { countLinkedDecisionAdrs } from '../store/decision-adr-links.js';
+import { docsWikilinks } from '../store/schema/attachments.js';
+import { getDb } from '../store/sqlite.js';
+import { readAuditLog } from './docs-audit.js';
+/**
+ * Directory names excluded from the loose-markdown count. The gitignore-aware
+ * `git ls-files` scan already keeps these out of the index in real projects;
+ * the filter below is defense-in-depth for a project that force-adds one.
+ * `.cleo` covers the CleoDocs storage surfaces (attachments, blobs) and
+ * `.cleo/council-runs` (the Council workload store).
+ */
+const EXCLUDED_DIR_NAMES = ['node_modules', '.git', '.cleo'];
+/**
+ * Count loose `*.md` files — git-tracked markdown outside the CleoDocs
+ * store. `git ls-files '*.md'` from the project root returns the tracked
+ * markdown paths (gitignore-aware); the store and dependency trees are then
+ * filtered defensively. Untracked files are intentionally NOT counted.
+ *
+ * @param projectRoot - Absolute project root (must be a git work tree).
+ * @returns The count plus what was scanned and excluded; `count` is 0 with
+ *   empty `scannedDirs` when the root is not a git work tree.
+ */
+export function countLooseMarkdown(projectRoot) {
+    const excludedDirs = [...EXCLUDED_DIR_NAMES];
+    const result = spawnSync('git', ['ls-files', '--', '*.md'], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+    });
+    if (result.status !== 0) {
+        // Not a git work tree (or git unavailable): the metric counts tracked
+        // loose markdown only, so there is nothing to measure.
+        return { count: 0, scannedDirs: [], excludedDirs };
+    }
+    const tracked = result.stdout.split('\n').filter((line) => line.length > 0);
+    const counted = tracked.filter((p) => !p.startsWith('.cleo/') && !p.startsWith('node_modules/'));
+    const scanned = new Set();
+    for (const path of counted) {
+        scanned.add(path.includes('/') ? path.slice(0, path.indexOf('/')) : '(root)');
+    }
+    return { count: counted.length, scannedDirs: [...scanned].sort(), excludedDirs };
+}
+/**
+ * Compute the per-project adoption metrics for `docs.stats` (T13363).
+ *
+ * @param opts.projectRoot - Absolute path to the CLEO project root.
+ * @returns The metrics envelope (read-only; nothing is written).
+ * @task T13363
+ */
+export async function computeDocsStats(opts) {
+    const { projectRoot } = opts;
+    // Add vs update activity — the audit log is the canonical mutation record.
+    const audit = readAuditLog(projectRoot);
+    let adds = 0;
+    let updates = 0;
+    for (const entry of audit.entries) {
+        if (entry.op === 'docs.add')
+            adds += 1;
+        else if (entry.op === 'docs.update')
+            updates += 1;
+    }
+    const addUpdate = {
+        adds,
+        updates,
+        ratio: updates > 0 ? adds / updates : null,
+    };
+    const looseMarkdown = countLooseMarkdown(projectRoot);
+    // Graph edge count, through the chokepoint drizzle handle (reads only).
+    const db = await getDb(projectRoot);
+    const edgeRows = await db.select({ n: count() }).from(docsWikilinks).all();
+    const wikilinksEdges = edgeRows[0]?.n ?? 0;
+    const decisionsLinked = await countLinkedDecisionAdrs(projectRoot);
+    const ratioText = addUpdate.ratio === null ? 'n/a' : addUpdate.ratio.toFixed(2);
+    return {
+        addUpdate,
+        looseMarkdown,
+        wikilinksEdges,
+        decisionsLinked,
+        generatedAt: new Date().toISOString(),
+        summary: `adds ${adds} / updates ${updates} (ratio ${ratioText}); ` +
+            `${looseMarkdown.count} loose markdown files; ` +
+            `${wikilinksEdges} wikilinks edges; ${decisionsLinked} decisions linked`,
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/docs/stats.js.map

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

package/dist/gc/cleanup.d.ts

@@ -160,7 +160,7 @@ export interface OrphanEntry {
  * @task T9043
  * @task T11996
  */
-export declare function pruneOrphanWorktrees(options: PruneOrphanWorktreesOptions): CleanupResult;
+export declare function pruneOrphanWorktrees(options: PruneOrphanWorktreesOptions): Promise<CleanupResult>;
 /**
  * Prune orphaned CLEO-generated temp directories.
  *

package/dist/gc/cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/gc/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAoBH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAqCtC,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,QAAqB,CAAC;AAM1D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,kCAAkC;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAoND;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,aAAa,CAwKxF;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAsE3F;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,GAAE,MAAgC,EAC1C,OAAO,GAAE,MAAiB,GACzB,WAAW,EAAE,CA4Bf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,WAAW,CAAC,EAAE,MAAM,GACnB,WAAW,EAAE,CAkDf"}
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/gc/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAoBH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAqCtC,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,QAAqB,CAAC;AAM1D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,kCAAkC;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAoND;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,aAAa,CAAC,CAkLxB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAsE3F;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,GAAE,MAAgC,EAC1C,OAAO,GAAE,MAAiB,GACzB,WAAW,EAAE,CA4Bf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,WAAW,CAAC,EAAE,MAAM,GACnB,WAAW,EAAE,CAkDf"}