@nazty_labs/common-ground 0.5.1

package/dist/retrieval.d.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { Store } from './store.js';
+import { type RegistryRecord } from './model.js';
+export declare function listPillars(store: Store, cursor?: string, limit?: number): Promise<{
+    items: {
+        id: string;
+        title: string;
+        scope: string;
+        excludes: string;
+        chapterCount: number;
+    }[];
+    total: number;
+    nextCursor: string | null;
+}>;
+export declare function listChapters(store: Store, pillarId: string, cursor?: string, limit?: number): Promise<{
+    items: {
+        chapterId: string;
+        title: string;
+        scope: string;
+        excludes: string;
+        revision: number;
+        factCount: number;
+    }[];
+    total: number;
+    nextCursor: string | null;
+    pillarId: string;
+}>;
+export declare function readChapter(store: Store, key: string, cursor?: string, limit?: number): Promise<{
+    chapterId: string;
+    title: string;
+    scope: string;
+    excludes: string;
+    paths: string[];
+    revision: number;
+    freshness: {
+        chapterId: string;
+        revision: number;
+        status: string;
+        locallyReviewed: boolean;
+        changedPaths: string[];
+        dependencyDrift: boolean;
+        error?: undefined;
+    } | {
+        chapterId: string;
+        revision: number;
+        status: string;
+        error: any;
+        locallyReviewed?: undefined;
+        changedPaths?: undefined;
+        dependencyDrift?: undefined;
+    };
+    facts: {
+        items: {
+            id: string;
+            statement: string;
+            evidencePaths: string[];
+        }[];
+        total: number;
+        nextCursor: string | null;
+    };
+}>;
+export declare function readFact(store: Store, key: string, id: string): Promise<{
+    chapterId: string;
+    revision: number;
+    fact: {
+        id: string;
+        statement: string;
+        evidence: {
+            path: string;
+            quote: string;
+        }[];
+        sourceScope: string[];
+        dependsOn: string[];
+    };
+    freshness: {
+        chapterId: string;
+        revision: number;
+        status: string;
+        locallyReviewed: boolean;
+        changedPaths: string[];
+        dependencyDrift: boolean;
+        error?: undefined;
+    } | {
+        chapterId: string;
+        revision: number;
+        status: string;
+        error: any;
+        locallyReviewed?: undefined;
+        changedPaths?: undefined;
+        dependencyDrift?: undefined;
+    };
+}>;
+export declare function search(store: Store, query: string, limit?: number, chapterId?: string, registry?: RegistryRecord, cache?: Map<string, Promise<string>>): Promise<{
+    freshness: any;
+    chapterId: string;
+    fact: {
+        id: string;
+        statement: string;
+        evidencePaths: string[];
+    };
+    matchedTerms: string[];
+    score: number;
+    directPath: boolean;
+}[]>;
+export declare const ReadKnowledge: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodEnum<["pillars", "chapters", "chapter", "fact", "search", "owners", "graph", "review", "checklist", "tidy", "proposals", "proposal-review"]>;
+    target: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodString, string, string>>, "many">>;
+    taskId: z.ZodOptional<z.ZodString>;
+    refresh: z.ZodOptional<z.ZodBoolean>;
+    evidence: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    kind: "chapters" | "pillars" | "search" | "chapter" | "fact" | "review" | "tidy" | "owners" | "graph" | "checklist" | "proposals" | "proposal-review";
+    evidence?: boolean | undefined;
+    paths?: string[] | undefined;
+    target?: string | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+    taskId?: string | undefined;
+    refresh?: boolean | undefined;
+}, {
+    kind: "chapters" | "pillars" | "search" | "chapter" | "fact" | "review" | "tidy" | "owners" | "graph" | "checklist" | "proposals" | "proposal-review";
+    evidence?: boolean | undefined;
+    paths?: string[] | undefined;
+    target?: string | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+    taskId?: string | undefined;
+    refresh?: boolean | undefined;
+}>;
+export declare function readKnowledge(store: Store, input: unknown): Promise<unknown>;
+export declare function reviewChecklist(store: Store, chapterIds: string[], touchedPaths: string[], cursor?: string, limit?: number): Promise<{
+    items: {
+        state: string;
+        kind: string;
+        path: string;
+    }[];
+    total: number;
+    nextCursor: string | null;
+    policy: string;
+}>;

package/dist/retrieval.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { relativePath } from './model.js';
+import { Workflow } from './workflow.js';
+import { page } from './paging.js';
+import { ownershipMap, pillarGraph, tidyPlan } from './navigation.js';
+import { queryTerms, termWeights, queryPath, matchFields } from './matching.js';
+export async function listPillars(store, cursor, limit) { return page((await store.read()).pillars.map(({ id, title, scope, excludes, chapters }) => ({ id, title, scope, excludes, chapterCount: chapters.length })), cursor, limit); }
+export async function listChapters(store, pillarId, cursor, limit) {
+    const reg = await store.read();
+    const p = reg.pillars.find(p => p.id === pillarId);
+    if (!p)
+        throw new Error('Unknown pillar');
+    return { pillarId, ...page(p.chapters.map(c => ({ chapterId: `${p.id}/${c.id}`, title: c.title, scope: c.scope, excludes: c.excludes, revision: c.revision, factCount: c.facts.length })), cursor, limit) };
+}
+export async function readChapter(store, key, cursor, limit) {
+    const reg = await store.read();
+    const c = store.chapter(reg, key);
+    return { chapterId: key, title: c.title, scope: c.scope, excludes: c.excludes, paths: c.paths, revision: c.revision, freshness: await store.status(key, reg), facts: page(c.facts.map(({ id, statement, evidence }) => ({ id, statement, evidencePaths: [...new Set(evidence.map(e => e.path))] })), cursor, limit, String(c.revision)) };
+}
+export async function readFact(store, key, id) { const reg = await store.read(); const c = store.chapter(reg, key); const fact = c.facts.find(f => f.id === id); if (!fact)
+    throw new Error('Unknown fact'); return { chapterId: key, revision: c.revision, fact, freshness: await store.status(key, reg) }; }
+export async function search(store, query, limit = 8, chapterId, registry, cache) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 20)
+        throw new Error('Search limit must be between 1 and 20');
+    const terms = queryTerms(query);
+    const reg = registry ?? await store.read();
+    if (chapterId)
+        store.chapter(reg, chapterId);
+    const entries = store.facts(reg).filter(entry => !chapterId || entry.chapterId === chapterId);
+    const { weights } = termWeights(terms, entries.map(({ key, fact }) => `${key} ${fact.statement} ${fact.evidence.map(e => e.path).join(' ')}`));
+    const path = queryPath(query);
+    const matches = entries.map(({ key, chapterId, fact }) => {
+        const match = matchFields(terms, `${key} ${fact.evidence.map(e => e.path).join(' ')}`, fact.statement, weights);
+        const directPath = !!path && fact.evidence.some(e => e.path === path || e.path.startsWith(`${path}/`));
+        return { chapterId, fact: { id: fact.id, statement: fact.statement, evidencePaths: [...new Set(fact.evidence.map(e => e.path))] }, matchedTerms: match.matchedTerms, score: match.weight, directPath };
+    }).filter(m => m.directPath || m.matchedTerms.length > 0).sort((a, b) => Number(b.directPath) - Number(a.directPath) || b.score - a.score || b.matchedTerms.length - a.matchedTerms.length || `${a.chapterId}/${a.fact.id}`.localeCompare(`${b.chapterId}/${b.fact.id}`)).slice(0, limit);
+    const states = new Map();
+    for (const m of matches)
+        if (!states.has(m.chapterId))
+            states.set(m.chapterId, await store.status(m.chapterId, reg, cache));
+    return matches.map(m => ({ ...m, freshness: states.get(m.chapterId) }));
+}
+const paging = { cursor: z.string().optional(), limit: z.number().int().min(1).max(20).optional() };
+export const ReadKnowledge = z.object({
+    kind: z.enum(['pillars', 'chapters', 'chapter', 'fact', 'search', 'owners', 'graph', 'review', 'checklist', 'tidy', 'proposals', 'proposal-review']),
+    target: z.string().optional(), query: z.string().optional(), paths: z.array(relativePath).optional(),
+    taskId: z.string().uuid().optional(), refresh: z.boolean().optional(), evidence: z.boolean().optional(), ...paging,
+}).strict();
+const shortStatus = (status) => ({ status: status.status, ...(status.error ? { error: status.error } : {}) });
+export async function readKnowledge(store, input) {
+    const args = ReadKnowledge.parse(input), { kind, target, query, paths = [], taskId, refresh, cursor, limit } = args;
+    const workflow = new Workflow(store), registry = await store.read(), cache = new Map();
+    let value;
+    let keys = [];
+    const required = () => { if (!target)
+        throw new Error('target is required for this read kind.'); return target; };
+    switch (kind) {
+        case 'pillars':
+            value = await listPillars(store, cursor, limit);
+            break;
+        case 'chapters':
+            value = await listChapters(store, required(), cursor, limit);
+            break;
+        case 'chapter': {
+            const key = required(), c = store.chapter(registry, key);
+            keys = [key];
+            value = { chapterId: key, revision: c.revision, scope: c.scope, excludes: c.excludes, paths: c.paths, freshness: shortStatus(await store.status(key, registry, cache)),
+                facts: page(args.evidence ? c.facts : c.facts.map(({ id, statement }) => ({ id, statement })), cursor, limit, String(c.revision), 12000) };
+            break;
+        }
+        case 'fact': {
+            const f = store.fact(registry, required());
+            keys = [f.chapterId];
+            value = { chapterId: f.chapterId, revision: f.chapter.revision, fact: f.fact, freshness: shortStatus(await store.status(f.chapterId, registry, cache)) };
+            break;
+        }
+        case 'search': {
+            if (!query)
+                throw new Error('query is required.');
+            const matches = await search(store, query, limit, target, registry, cache);
+            keys = [...new Set(matches.map(m => m.chapterId))];
+            value = { items: matches.map(m => ({ ...m, freshness: shortStatus(m.freshness) })) };
+            break;
+        }
+        case 'owners': {
+            const { basis, ...routes } = await ownershipMap(store, { path: paths[0], signal: query, cursor, limit }, registry, cache);
+            keys = routes.items.map(r => r.chapterId);
+            value = { ...routes, items: routes.items.map(({ matchedTerms, paths, score, ...r }) => ({ ...r, freshness: shortStatus(r.freshness) })) };
+            break;
+        }
+        case 'graph': {
+            const { basis, ...graph } = await pillarGraph(store, target, cursor, limit);
+            value = graph;
+            break;
+        }
+        case 'review': {
+            const key = required();
+            let chapterId = key, factIds;
+            if (key.split('/').length === 3) {
+                const f = store.fact(registry, key);
+                chapterId = f.chapterId;
+                factIds = [f.fact.id];
+            }
+            keys = store.related(registry, chapterId, factIds);
+            value = page(keys.map(chapterId => ({ chapterId, revision: store.chapter(registry, chapterId).revision, factCount: store.chapter(registry, chapterId).facts.length })), cursor, limit, JSON.stringify(registry));
+            break;
+        }
+        case 'checklist': {
+            const key = required();
+            keys = key.split('/').length === 3 ? store.related(registry, store.fact(registry, key).chapterId, [store.fact(registry, key).fact.id]) : store.resolveTarget(registry, key).flatMap(k => store.related(registry, k));
+            const { policy, ...checklist } = await reviewChecklist(store, [...new Set(keys)], paths, cursor, limit);
+            value = checklist;
+            break;
+        }
+        case 'tidy': {
+            const { policy, next, ...plan } = await tidyPlan(store, required(), cursor, limit);
+            value = plan;
+            break;
+        }
+        case 'proposals':
+            if (!taskId)
+                throw new Error('taskId required.');
+            return workflow.proposals(taskId, cursor, limit);
+        case 'proposal-review':
+            if (!taskId)
+                throw new Error('taskId required.');
+            return workflow.proposalReview(taskId, cursor, limit);
+    }
+    if (!taskId)
+        return value;
+    let context = registry;
+    if (keys.length) {
+        try {
+            context = await store.context(registry, [...new Set(keys.flatMap(k => store.related(registry, k)))], cache);
+        }
+        catch {
+            return value;
+        }
+    }
+    if (kind === 'checklist')
+        context = { context, documents: await store.fileSnapshots((await store.reviewFiles(registry, [...new Set(keys)], paths)).documentFiles) };
+    return workflow.reuse(taskId, { kind, target, query, paths, cursor, limit, evidence: args.evidence }, value, context, refresh);
+}
+export async function reviewChecklist(store, chapterIds, touchedPaths, cursor, limit) {
+    const files = await store.reviewFiles(await store.read(), chapterIds, touchedPaths);
+    const entries = [...files.sourceFiles.map(path => ({ kind: 'sourceFiles', path })), ...files.documentFiles.map(path => ({ kind: 'documentFiles', path }))];
+    const selected = page(entries, cursor, limit);
+    const snapshots = await store.fileSnapshots(selected.items.map(item => item.path));
+    return { policy: 'Open each current file in this session. If it is missing, verify deletion live. Skim whole chapters and relevant sibling, child, and reference documentation; follow additional code references manually. This checklist is bounded discovery, not proof of reading.', ...selected, items: selected.items.map(item => ({ ...item, state: snapshots[item.path] === 'missing' ? 'missing' : 'present' })) };
+}

package/dist/review-files.d.ts

@@ -0,0 +1,3 @@
+import type { Store } from './store.js';
+/** Bounded discovery of local documentation; never follows symlinks or remote links. */
+export declare function reviewDocuments(store: Store, paths: string[], mode?: 'full' | 'focused'): Promise<string[]>;

package/dist/review-files.js

@@ -0,0 +1,106 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const document = (name) => /\.(md|mdx|rst|adoc)$/i.test(name) || /^readme(?:\.[^/]+)?$/i.test(name);
+const excluded = (file) => file.split('/').some(p => ['.git', 'node_modules', '.common-ground', 'dist', 'build', 'target', '.nx', '.next', 'coverage'].includes(p) || p.startsWith('.env'));
+/** Bounded discovery of local documentation; never follows symlinks or remote links. */
+export async function reviewDocuments(store, paths, mode = 'full') {
+    if (!paths.length)
+        return [];
+    const directories = new Set();
+    const files = new Set();
+    for (const file of paths) {
+        await store.safe(file, true);
+        if (excluded(file))
+            continue;
+        let directory = path.posix.dirname(file);
+        try {
+            if ((await fs.stat(path.join(store.root, file))).isDirectory())
+                directory = file;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (directory !== '.')
+            directories.add(directory);
+        if (document(file))
+            files.add(file);
+    }
+    // A root-level source change does not force a recursive scan of the whole monorepo.
+    const direct = new Set(['.']);
+    for (const directory of directories) {
+        let current = directory;
+        while (current !== '.') {
+            direct.add(current);
+            current = path.posix.dirname(current);
+        }
+    }
+    for (const directory of direct) {
+        let entries;
+        try {
+            entries = await fs.readdir(path.join(store.root, directory), { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        for (const entry of entries) {
+            const file = path.posix.join(directory, entry.name);
+            if (excluded(file) || entry.isSymbolicLink())
+                continue;
+            if (entry.isFile() && document(entry.name) && (mode === 'full' || /^(readme(?:\.[^/]+)?|AGENTS\.md)$/i.test(entry.name)))
+                files.add(file);
+            // Include sibling directory READMEs without crawling every sibling subsystem.
+            if (mode === 'full' && entry.isDirectory())
+                for (const child of await fs.readdir(path.join(store.root, file), { withFileTypes: true })) {
+                    if (child.isFile() && /^readme(?:\.[^/]+)?$/i.test(child.name))
+                        files.add(`${file}/${child.name}`);
+                }
+        }
+    }
+    if (mode === 'full' && directories.size) {
+        const scan = await store.walk([...directories], 10000);
+        if (scan.truncated)
+            throw new Error('Documentation discovery exceeds the beta scan limit; narrow chapter evidence scopes before review.');
+        for (const file of scan.files)
+            if (document(file))
+                files.add(file);
+    }
+    if (mode === 'focused')
+        return [...files].sort();
+    // Follow relative documentation references transitively, with cycles deduplicated.
+    for (const file of files) {
+        if (files.size > 1000)
+            throw new Error('Documentation review exceeds the beta limit of 1,000 files.');
+        let content;
+        try {
+            const safe = await store.safe(file);
+            if ((await fs.stat(safe)).size > 2_000_000)
+                throw new Error(`Documentation file too large: ${file}`);
+            content = await fs.readFile(safe, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        for (const match of content.matchAll(/\[[^\]]*\]\((<[^>]+>|[^\s)]+)[^)]*\)/g)) {
+            let target = match[1].replace(/^<|>$/g, '').split('#')[0];
+            try {
+                target = decodeURIComponent(target);
+            }
+            catch {
+                continue;
+            }
+            if (!target || /^(?:[a-z][a-z0-9+.-]*:|\/)/i.test(target) || target.includes('\\'))
+                continue;
+            const relative = path.posix.normalize(path.posix.join(path.posix.dirname(file), target));
+            if (relative.startsWith('../') || excluded(relative) || !document(relative))
+                continue;
+            await store.safe(relative, true);
+            files.add(relative);
+        }
+    }
+    return [...files].sort();
+}

package/dist/review.d.ts

@@ -0,0 +1,86 @@
+import type { Store } from './store.js';
+import type { Fact, RegistryRecord } from './model.js';
+import type { z } from 'zod';
+type FactRecord = z.infer<typeof Fact>;
+export type FactChange = {
+    before: FactRecord | null;
+    after: FactRecord | null;
+    reason: string;
+};
+export declare function factReview(before: FactRecord | null, after: FactRecord | null, evidence?: boolean): {
+    evidenceDetails?: string | undefined;
+    change: string;
+    fields: {
+        [k: string]: {
+            before: {} | null;
+            after: {} | null;
+        };
+    };
+    evidencePaths: string[];
+} | null;
+export declare function knowledgeChanges(before: RegistryRecord, after: RegistryRecord, target?: string, evidence?: boolean): ({
+    evidenceDetails?: string | undefined;
+    change: string;
+    fields: {
+        [k: string]: {
+            before: {} | null;
+            after: {} | null;
+        };
+    };
+    evidencePaths: string[];
+    kind: "chapter" | "fact" | "pillar";
+    id: string;
+    label: string;
+} | {
+    change: string;
+    fields: {
+        [k: string]: {
+            before: {} | null;
+            after: {} | null;
+        };
+    };
+    kind: "chapter" | "fact" | "pillar";
+    id: string;
+    label: string;
+})[];
+/** A derived diff, not an approval, semantic validator, or another tracked knowledge file. */
+export declare function reviewKnowledge(store: Store, target?: string, staged?: boolean, evidence?: boolean, cursor?: string, limit?: number): Promise<{
+    items: ({
+        evidenceDetails?: string | undefined;
+        change: string;
+        fields: {
+            [k: string]: {
+                before: {} | null;
+                after: {} | null;
+            };
+        };
+        evidencePaths: string[];
+        kind: "chapter" | "fact" | "pillar";
+        id: string;
+        label: string;
+    } | {
+        change: string;
+        fields: {
+            [k: string]: {
+                before: {} | null;
+                after: {} | null;
+            };
+        };
+        kind: "chapter" | "fact" | "pillar";
+        id: string;
+        label: string;
+    })[];
+    total: number;
+    nextCursor: string | null;
+    target: string;
+    comparison: string;
+    writesKnowledge: boolean;
+    summary: {
+        pillars: number;
+        chapters: number;
+        facts: number;
+    };
+    guidance: string;
+}>;
+export declare function reviewText(result: Awaited<ReturnType<typeof reviewKnowledge>>): string;
+export {};

package/dist/review.js

@@ -0,0 +1,124 @@
+import { execFile } from 'node:child_process';
+import { promisify, isDeepStrictEqual as equal } from 'node:util';
+import { page } from './paging.js';
+const evidencePaths = (fact) => [...new Set(fact?.evidence.map(e => e.path) ?? [])].sort();
+const factFields = (fact) => ({ statement: fact.statement, evidence: [...fact.evidence].sort((a, b) => a.path.localeCompare(b.path) || a.quote.localeCompare(b.quote)), sourceScope: [...fact.sourceScope].sort(), dependsOn: [...fact.dependsOn].sort() });
+function changedFields(before, after) {
+    return Object.fromEntries([...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})])]
+        .filter(field => !equal(before?.[field], after?.[field]))
+        .map(field => [field, { before: before?.[field] ?? null, after: after?.[field] ?? null }]));
+}
+export function factReview(before, after, evidence = false) {
+    const fields = changedFields(before ? factFields(before) : undefined, after ? factFields(after) : undefined);
+    if (!Object.keys(fields).length)
+        return null;
+    // Exact changed quotes are available on demand; never silently omit that evidence changed.
+    if (fields.evidence && !evidence)
+        fields.evidence = { before: evidencePaths(before), after: evidencePaths(after) };
+    return { change: !before ? 'added' : !after ? 'removed' : 'updated', fields,
+        evidencePaths: evidencePaths(after ?? before), ...(fields.evidence && !evidence ? { evidenceDetails: 'changed; use evidence:true or --evidence for exact quotes' } : {}) };
+}
+function records(registry) {
+    const entries = new Map();
+    for (const pillar of registry.pillars) {
+        const { id, title, scope, excludes } = pillar;
+        entries.set(id, { kind: 'pillar', label: title, fields: { title, scope, excludes } });
+        for (const chapter of pillar.chapters) {
+            const key = `${id}/${chapter.id}`;
+            entries.set(key, { kind: 'chapter', label: `${title} / ${chapter.title}`, fields: { title: chapter.title, scope: chapter.scope, excludes: chapter.excludes, paths: [...chapter.paths].sort() } });
+            for (const fact of chapter.facts)
+                entries.set(`${key}/${fact.id}`, { kind: 'fact', label: `${title} / ${chapter.title}`, fields: factFields(fact), fact });
+        }
+    }
+    return entries;
+}
+export function knowledgeChanges(before, after, target = 'all', evidence = false) {
+    const old = records(before), current = records(after), ids = [...new Set([...old.keys(), ...current.keys()])];
+    if (target !== 'all') {
+        const matches = ids.filter(id => id === target || (id.split('/').length === 3 && id.endsWith(`/${target}`)));
+        if (matches.length !== 1)
+            throw new Error(matches.length ? 'Ambiguous target; use a qualified ID.' : 'Unknown target; use a pillar, chapter, fact, or all.');
+        target = matches[0];
+    }
+    return ids.filter(id => target === 'all' || id === target || id.startsWith(`${target}/`)).sort().flatMap(id => {
+        const previous = old.get(id), next = current.get(id), entry = next ?? previous;
+        const change = entry.kind === 'fact' ? factReview(previous?.fact ?? null, next?.fact ?? null, evidence) : {
+            change: !previous ? 'added' : !next ? 'removed' : 'updated', fields: changedFields(previous?.fields, next?.fields)
+        };
+        return change && Object.keys(change.fields).length ? [{ kind: entry.kind, id, label: entry.label, ...change }] : [];
+    });
+}
+const exec = promisify(execFile);
+const empty = () => ({ schemaVersion: 2, pillars: [] });
+/** A derived diff, not an approval, semantic validator, or another tracked knowledge file. */
+export async function reviewKnowledge(store, target = 'all', staged = false, evidence = false, cursor, limit) {
+    let gitRoot = store.root;
+    const git = async (args) => (await exec('git', ['--literal-pathspecs', '-C', gitRoot, ...args], { maxBuffer: 16 * 1024 * 1024 })).stdout;
+    let prefix;
+    try {
+        prefix = (await git(['rev-parse', '--show-prefix'])).replace(/\r?\n$/, '');
+        gitRoot = (await git(['rev-parse', '--show-toplevel'])).replace(/\r?\n$/, '');
+    }
+    catch {
+        throw new Error('cground review requires a Git checkout. Task completion summaries work without Git.');
+    }
+    const file = `${prefix}.common-ground/knowledge.json`;
+    let head;
+    try {
+        head = (await git(['rev-parse', '--verify', '--quiet', 'HEAD'])).trim();
+    }
+    catch (error) {
+        if (error.code !== 1)
+            throw error;
+    }
+    let before = empty(), after;
+    if (head) {
+        const entry = await git(['ls-tree', '-z', head, '--', file]);
+        if (entry) {
+            if (!entry.startsWith('100644 ') && !entry.startsWith('100755 '))
+                throw new Error('Knowledge in HEAD must be a regular file.');
+            before = store.validateRegistry(JSON.parse(await git(['show', `${head}:${file}`])));
+        }
+    }
+    if (staged) {
+        const entries = (await git(['ls-files', '--stage', '-z', '--', file])).split('\0').filter(Boolean);
+        if (entries.some(entry => !/^100(?:644|755) [a-f0-9]+ 0\t/.test(entry)))
+            throw new Error('Resolve staged knowledge conflicts or unsupported file types before review.');
+        after = entries.length ? store.validateRegistry(JSON.parse(await git(['show', `:${file}`]))) : empty();
+    }
+    else {
+        try {
+            after = await store.read();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            after = empty();
+        }
+    }
+    const items = knowledgeChanges(before, after, target, evidence);
+    return { target, comparison: staged ? 'HEAD to staged knowledge' : 'HEAD to working knowledge', writesKnowledge: false,
+        summary: { pillars: items.filter(i => i.kind === 'pillar').length, chapters: items.filter(i => i.kind === 'chapter').length, facts: items.filter(i => i.kind === 'fact').length },
+        guidance: 'Present only these changes in plain language with source links, the reason you verified, a recommendation and any uncertainty. This diff does not validate truth or establish approval. Do not ask the developer to read or edit JSON; fetch exact evidence only when needed.',
+        ...page(items, cursor, limit, JSON.stringify({ head, before, after, target, staged, evidence }), 12000) };
+}
+function valueText(value) { return value === null ? '(none)' : Array.isArray(value) ? value.map(v => typeof v === 'string' ? v : JSON.stringify(v)).join(', ') : String(value); }
+export function reviewText(result) {
+    if (!result.total)
+        return 'No knowledge content changes. Revision and fingerprint-only changes are omitted.';
+    const lines = [`Knowledge review — ${result.comparison}`, `${result.summary.pillars} pillar, ${result.summary.chapters} chapter, ${result.summary.facts} fact changes.`, ''];
+    for (const item of result.items) {
+        lines.push(`${item.change.toUpperCase()} ${item.kind}: ${item.id} (${item.label})`);
+        for (const [field, change] of Object.entries(item.fields))
+            lines.push(`  ${field}: ${valueText(change.before)} → ${valueText(change.after)}`);
+        if ('evidencePaths' in item)
+            lines.push(`  Source: ${item.evidencePaths.join(', ')}`);
+        if ('evidenceDetails' in item && item.evidenceDetails)
+            lines.push(`  Evidence: ${item.evidenceDetails}`);
+        lines.push('');
+    }
+    if (result.nextCursor)
+        lines.push(`More changes: rerun with --cursor ${result.nextCursor}`);
+    lines.push('Recommended: run this review through your coding agent to verify source, explain changes, and recommend what to keep or approve. No JSON editing is needed.');
+    return lines.join('\n');
+}

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+export { ReadKnowledge, readKnowledge, listPillars, listChapters, readChapter, readFact, search, reviewChecklist } from './retrieval.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Store } from './store.js';
+export { page } from './paging.js';
+export declare function createFullServer(store: Store): McpServer;
+export declare function serve(store: Store, profile?: string): Promise<void>;
+export declare function createServer(store: Store, profile?: string): McpServer;
+export declare function registerOperations(server: McpServer, store: Store): void;