@nazty_labs/common-ground 0.5.1

package/dist/model.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export const relativePath = z.string().min(1).transform(p => p.replace(/\/+$/, '')).pipe(z.string().min(1).refine(p => !p.startsWith('/') && !p.includes('\\') && !p.split('/').some(s => s === '..' || s === '.' || s === '') && !/^[A-Za-z]:/.test(p), 'Use a repository-relative path without traversal')).describe('Repository-relative path without traversal or symlinks; trailing directory slashes normalize away.');
+const id = z.string().regex(/^[a-z0-9][a-z0-9-]*$/);
+export const chapterKey = z.string().regex(/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/);
+export const factKey = z.string().regex(/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/);
+export const Evidence = z.object({ path: relativePath.describe('Supporting source path; may be outside the owning chapter. Evidence paths are automatically tracked for freshness without adding them to sourceScope.'), quote: z.string().trim().min(1).max(1200) }).strict();
+const LegacyFact = z.object({ id, statement: z.string().trim().min(8).max(2000), evidence: z.array(Evidence).min(1).max(8) }).strict();
+export const Fact = LegacyFact.extend({ sourceScope: z.array(relativePath).min(1).describe('Owned source coverage, restricted to this chapter paths. For a chapter owning src: sourceScope [src], evidence [{path: shared/config.ts, quote: mode = 1}]. Cross-chapter citations belong in evidence, not sourceScope.'), dependsOn: z.array(factKey).default([]) }).strict();
+const Boundary = z.object({ id, title: z.string().trim().min(3).max(100), scope: z.string().trim().min(12).max(800), excludes: z.string().trim().min(3).max(800) }).strict();
+export const ChapterDefinition = Boundary.extend({ paths: z.array(relativePath).min(1).max(30) }).strict();
+export const Chapter = ChapterDefinition.extend({ revision: z.number().int().positive(), facts: z.array(Fact), sources: z.record(z.string()), dependencyFingerprints: z.record(z.string()).default({}) }).strict();
+export const PillarDefinition = Boundary.extend({ chapters: z.array(ChapterDefinition).min(1) }).strict();
+export const Pillar = Boundary.extend({ chapters: z.array(Chapter).min(1) }).strict();
+export const Registry = z.object({ schemaVersion: z.literal(2), pillars: z.array(Pillar) }).strict();
+export const Maintenance = z.object({ factId: id, action: z.enum(['correct', 'merge', 'remove', 'tighten']), reason: z.string().trim().min(12).max(1000), replacement: factKey.optional() }).strict();
+export const Review = z.object({ chapterId: chapterKey, expectedRevision: z.number().int().positive(), invalidatedFactIds: z.array(z.string()), reviewedFactIds: z.array(z.string()), facts: z.array(Fact), reason: z.string().trim().min(12).max(1000), maintenance: z.array(Maintenance).optional() }).strict();
+export const Verification = z.object({ sourceFiles: z.array(relativePath), documentFiles: z.array(relativePath) }).strict();
+export const Update = z.object({ chapterId: chapterKey, factIds: z.array(id).min(1).optional(), touchedPaths: z.array(relativePath), reviews: z.array(Review).min(1), verification: Verification, tidyId: z.string().uuid().optional() }).strict();
+export const LegacyRegistry = z.object({ schemaVersion: z.literal(1), pillars: z.array(Boundary.extend({ paths: z.array(relativePath).min(1).max(30), revision: z.number().int().positive(), facts: z.array(LegacyFact), sources: z.record(z.string()) }).strict()) }).strict();
+export function unique(values, label) { if (new Set(values).size !== values.length)
+    throw new Error(`Duplicate ${label}`); }

package/dist/navigation.d.ts

@@ -0,0 +1,164 @@
+import { type Store } from './store.js';
+import { type RegistryRecord } from './model.js';
+export interface RouteOptions {
+    path?: string;
+    signal?: string;
+    cursor?: string;
+    limit?: number;
+}
+export declare function ownershipMap(store: Store, options?: RouteOptions, suppliedRegistry?: RegistryRecord, cache?: Map<string, Promise<string>>): Promise<{
+    items: {
+        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;
+        };
+        pillarId: string;
+        chapterId: string;
+        title: string;
+        scope: string;
+        paths: string[];
+        match: string;
+        score: number;
+        matchedTerms: string[];
+        matchingFactCount: number;
+        factHints: string[];
+        revision: number;
+    }[];
+    total: number;
+    nextCursor: string | null;
+    basis: string;
+    ambiguous: boolean;
+}>;
+export declare function pillarGraph(store: Store, pillarId?: string, cursor?: string, limit?: number): Promise<{
+    items: {
+        freshness: string;
+        from: string;
+        to: string;
+        factLinkCount: number;
+        examples: {
+            from: string;
+            to: string;
+        }[];
+    }[];
+    total: number;
+    nextCursor: string | null;
+    direction: string;
+    basis: string;
+}>;
+export declare function startHere(store: Store, options?: RouteOptions): Promise<{
+    guide: string;
+    state: string;
+    principle: string;
+    next: string;
+    policy?: undefined;
+    routes?: undefined;
+} | {
+    guide: string;
+    principle: string;
+    policy: string;
+    routes: {
+        items: {
+            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;
+            };
+            pillarId: string;
+            chapterId: string;
+            title: string;
+            scope: string;
+            paths: string[];
+            match: string;
+            score: number;
+            matchedTerms: string[];
+            matchingFactCount: number;
+            factHints: string[];
+            revision: number;
+        }[];
+        total: number;
+        nextCursor: string | null;
+        basis: string;
+        ambiguous: boolean;
+    };
+    next: string;
+    state?: undefined;
+}>;
+export declare function tidyPlan(store: Store, target: string, cursor?: string, limit?: number): Promise<{
+    target: string;
+    writesKnowledge: boolean;
+    agentActionRequired: boolean;
+    policy: string;
+    next: string;
+    requiredChapterCount: number;
+    chapters: {
+        items: {
+            chapterId: string;
+            revision: number;
+            factCount: number;
+            duplicateGroupCount: number;
+            duplicateHints: string[][];
+        }[];
+        total: number;
+        nextCursor: string | null;
+    };
+}>;
+/** Read-only mechanical validation. Evidence presence never proves semantic truth. */
+export declare function validateKnowledge(store: Store, target?: string, cursor?: string, limit?: number, allResults?: boolean): Promise<{
+    items: {
+        dependencyIssues: {
+            recordChanged: boolean;
+            changedPaths: string[];
+            errors: string[];
+            factId: string;
+        }[];
+        locallyReviewed: boolean;
+        changedPaths: string[];
+        errors: string[];
+        factId: string;
+        chapterId: string;
+        status: string;
+    }[];
+    total: number;
+    nextCursor: string | null;
+    target: string;
+    writesKnowledge: boolean;
+    valid: boolean;
+    basis: string;
+    affected: {
+        pillars: string[];
+        chapters: string[];
+        facts: string[];
+    };
+    cleanupPrompt: string | null;
+    summary: {
+        selectedFacts: number;
+        checkedFacts: number;
+        needsReview: number;
+        unpopulatedChapters: string[];
+    };
+}>;

package/dist/navigation.js

@@ -0,0 +1,164 @@
+import { same } from './store.js';
+import { relativePath } from './model.js';
+import { page } from './paging.js';
+const words = (text) => [...new Set(text.toLocaleLowerCase().split(/[^\p{L}\p{N}_]+/u).filter(Boolean))];
+const contains = (scope, file) => scope === file || file.startsWith(`${scope}/`);
+export async function ownershipMap(store, options = {}, suppliedRegistry, cache) {
+    if (options.path)
+        options = { ...options, path: relativePath.parse(options.path) };
+    const registry = suppliedRegistry ?? await store.read();
+    const terms = words(options.signal ?? '').filter(t => !['a', 'an', 'the', 'is', 'my', 'this', 'what', 'do', 'failed', 'failing'].includes(t));
+    const entries = store.chapters(registry).map(({ key, pillar, chapter }) => {
+        const paths = options.path ? chapter.paths.filter(p => contains(p, options.path)) : chapter.paths;
+        const boundary = words(`${pillar.title} ${pillar.scope} ${chapter.title} ${chapter.scope} ${chapter.paths.join(' ')}`);
+        const matchingFacts = chapter.facts.map(f => {
+            const tokens = words(`${f.statement} ${f.evidence.map(e => `${e.path} ${e.quote}`).join(' ')}`);
+            return { factId: f.id, terms: terms.filter(t => tokens.includes(t)) };
+        }).filter(f => f.terms.length);
+        const boundaryTerms = terms.filter(t => boundary.includes(t));
+        const matchedTerms = [...new Set([...boundaryTerms, ...matchingFacts.flatMap(f => f.terms)])];
+        return { pillarId: pillar.id, chapterId: key, title: chapter.title, scope: chapter.scope,
+            paths, match: paths.length && options.path ? 'registered-path' : terms.length ? 'keyword-hint' : 'index',
+            score: (options.path && paths.length ? 1000 : 0) + matchedTerms.length,
+            matchedTerms, matchingFactCount: matchingFacts.length,
+            factHints: matchingFacts.slice(0, 3).map(f => `${key}/${f.factId}`), revision: chapter.revision };
+    }).filter(entry => options.path ? entry.paths.length > 0 : options.signal ? entry.matchedTerms.length > 0 : true)
+        .sort((a, b) => b.score - a.score || a.chapterId.localeCompare(b.chapterId));
+    const result = page(entries, options.cursor, options.limit, JSON.stringify(options.path ?? '') + (options.signal ?? ''));
+    return { basis: 'Registered chapter paths define ownership. Signal matches are keyword hints from boundaries, facts, and evidence; verify source before diagnosing.',
+        ambiguous: entries.length > 1, ...result,
+        items: await Promise.all(result.items.map(async (item) => ({ ...item, freshness: await store.status(item.chapterId, registry, cache) }))) };
+}
+export async function pillarGraph(store, pillarId, cursor, limit) {
+    const registry = await store.read();
+    if (pillarId && !registry.pillars.some(p => p.id === pillarId))
+        throw new Error('Unknown pillar');
+    const edges = new Map();
+    for (const entry of store.facts(registry))
+        for (const dependency of entry.fact.dependsOn) {
+            const from = entry.key.split('/')[0], to = dependency.split('/')[0];
+            if (from === to || (pillarId && from !== pillarId && to !== pillarId))
+                continue;
+            const key = `${from}/${to}`;
+            const edge = edges.get(key) ?? { from, to, factLinkCount: 0, examples: [], chapters: new Set() };
+            edge.factLinkCount++;
+            if (edge.examples.length < 3)
+                edge.examples.push({ from: entry.key, to: dependency });
+            edge.chapters.add(entry.chapterId);
+            edge.chapters.add(dependency.slice(0, dependency.lastIndexOf('/')));
+            edges.set(key, edge);
+        }
+    const selected = page([...edges.values()].sort((a, b) => `${a.from}/${a.to}`.localeCompare(`${b.from}/${b.to}`))
+        .map(({ chapters, ...edge }) => ({ ...edge, chapterIds: [...chapters].sort() })), cursor, limit);
+    const states = new Map();
+    for (const edge of selected.items)
+        for (const key of edge.chapterIds)
+            if (!states.has(key))
+                states.set(key, await store.status(key, registry));
+    return { direction: 'dependent pillar -> dependency pillar',
+        basis: 'Derived from recorded cross-pillar fact dependencies. Missing edges mean unrecorded relationships, not proven independence. Cycles are allowed.',
+        ...selected, items: selected.items.map(({ chapterIds, ...edge }) => ({ ...edge,
+            freshness: chapterIds.some(k => states.get(k).status !== 'evidence-unchanged') ? 'needs-review' : 'evidence-unchanged' })) };
+}
+export async function startHere(store, options = {}) {
+    let routes;
+    try {
+        routes = await ownershipMap(store, options);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return { guide: '.common-ground/START_HERE.md', state: 'awaiting-bootstrap',
+            principle: 'Code is the source of truth. Common Ground is a cache that supplements source reading.',
+            next: 'Run cground init if needed, read directory READMEs and source, then refine the local bootstrap proposal with the developer before approving boundaries and seeding verified facts.' };
+    }
+    return { guide: '.common-ground/START_HERE.md',
+        principle: 'Code is the source of truth. Common Ground is a cache that supplements source reading.',
+        policy: '.common-ground/POLICY.md', routes,
+        next: routes.total === 0 ? 'No recorded owner matched. Inspect directory READMEs and code; ask the developer about ownership. Do not invent a pillar or diagnosis.'
+            : routes.ambiguous ? 'Multiple candidates matched. Narrow with a repository-relative path and read their scopes before choosing.'
+                : 'Call list_chapters for the matched pillar, then read_chapter and read_fact; verify their source.' };
+}
+export async function tidyPlan(store, target, cursor, limit) {
+    const registry = await store.read();
+    const keys = store.resolveTarget(registry, target);
+    const required = [...new Set(keys.flatMap(key => store.related(registry, key)))].sort();
+    const chapters = page(required.map(key => {
+        const c = store.chapter(registry, key);
+        const groups = new Map();
+        for (const f of c.facts) {
+            const normalized = words(f.statement).sort().join(' ');
+            groups.set(normalized, [...(groups.get(normalized) ?? []), f.id]);
+        }
+        const duplicates = [...groups.values()].filter(ids => ids.length > 1);
+        return { chapterId: key, revision: c.revision, factCount: c.facts.length,
+            duplicateGroupCount: duplicates.length, duplicateHints: duplicates.slice(0, 3).map(ids => ids.slice(0, 5)) };
+    }), cursor, limit, JSON.stringify(registry));
+    return { target, writesKnowledge: false, agentActionRequired: true,
+        policy: 'Skim every fact page in each required chapter. Read source now, merge verified near duplicates, remove superseded content, tighten narrative, correct in place, and repair references atomically. Similar wording is only a hint. If verification is ambiguous, ask; do not guess.',
+        next: 'Use review_checklist for these chapter IDs and touched paths. A developer-requested cground tidy TARGET or MCP cground operation tidy issues a local tidyId for prepare_update or prepare_patch; tidy_plan itself only previews scope.',
+        requiredChapterCount: required.length, chapters };
+}
+/** Read-only mechanical validation. Evidence presence never proves semantic truth. */
+export async function validateKnowledge(store, target = 'all', cursor, limit, allResults = true) {
+    const registry = await store.read(); // Schema, ownership and dependency references are checked globally.
+    const chapters = store.resolveTarget(registry, target);
+    const allFacts = store.facts(registry), index = new Map(allFacts.map(f => [f.key, f]));
+    const factTarget = target === 'all' ? undefined : allFacts.find(f => f.key === target || f.fact.id === target);
+    const selected = factTarget ? [factTarget] : allFacts.filter(f => chapters.includes(f.chapterId));
+    const required = [...new Set(selected.flatMap(f => [f.key, ...store.upstreamFacts(registry, f.key, index)]))];
+    const checked = new Map();
+    const states = new Map();
+    const fingerprints = new Map();
+    for (const key of required) {
+        const { chapterId, chapter, fact } = index.get(key);
+        const errors = [];
+        try {
+            await store.validateFacts({ paths: chapter.paths, facts: [fact] });
+        }
+        catch (e) {
+            errors.push(e.message);
+        }
+        let changedPaths = [];
+        try {
+            const current = await store.snapshot({ paths: chapter.paths, facts: [fact] });
+            const baseline = Object.fromEntries(Object.entries(chapter.sources).filter(([file]) => fact.sourceScope.some(scope => contains(scope, file)) || fact.evidence.some(e => e.path === file)));
+            changedPaths = [...new Set([...Object.keys(current), ...Object.keys(baseline)])].filter(file => current[file] !== baseline[file]).sort();
+        }
+        catch (e) {
+            if (!errors.includes(e.message))
+                errors.push(e.message);
+        }
+        checked.set(key, { changedPaths, errors });
+        if (!states.has(chapterId)) {
+            states.set(chapterId, await store.status(chapterId, registry));
+            fingerprints.set(chapterId, store.dependencyFingerprints(registry, chapterId));
+        }
+    }
+    const items = selected.map(({ key, chapterId, chapter }) => {
+        const own = checked.get(key);
+        const dependencies = store.upstreamFacts(registry, key, index);
+        const dependencyIssues = dependencies.filter(dep => {
+            const state = checked.get(dep);
+            return state.errors.length || state.changedPaths.length || chapter.dependencyFingerprints[dep] !== fingerprints.get(chapterId)[dep];
+        }).map(factId => ({ factId, ...checked.get(factId), recordChanged: chapter.dependencyFingerprints[factId] !== fingerprints.get(chapterId)[factId] }));
+        const locallyReviewed = states.get(chapterId).locallyReviewed === true;
+        const invalidEvidence = own.errors.length > 0 || dependencyIssues.some(d => d.errors.length > 0);
+        const drift = own.changedPaths.length > 0 || dependencyIssues.length > 0;
+        return { factId: key, chapterId, status: invalidEvidence || (drift && !locallyReviewed) ? 'needs-review' : 'evidence-unchanged',
+            ...own, dependencyIssues, locallyReviewed };
+    });
+    const unpopulatedChapters = chapters.filter(key => !store.chapter(registry, key).facts.length);
+    const stale = items.filter(item => item.status === 'needs-review');
+    const affected = { pillars: [...new Set(stale.map(item => item.chapterId.split('/')[0]))].sort(), chapters: [...new Set(stale.map(item => item.chapterId))].sort(), facts: stale.map(item => item.factId).sort() };
+    const needsReview = items.filter(item => item.status === 'needs-review').length;
+    // Do not return success for a registry that changed during a potentially long scan.
+    if (!same(registry, await store.read()))
+        throw new Error('Knowledge changed during validation; rerun validate.');
+    return { target, writesKnowledge: false, valid: items.length > 0 && needsReview === 0 && unpopulatedChapters.length === 0,
+        basis: 'Checks registry structure, exact evidence, source scopes and upstream dependencies. This does not prove the assertions are true.',
+        affected,
+        cleanupPrompt: needsReview ? "Start automatic cleanup?" : null,
+        summary: { selectedFacts: items.length, checkedFacts: required.length, needsReview, unpopulatedChapters },
+        ...page(allResults ? items : stale, cursor, limit, JSON.stringify({ target, registry, allResults }), 12000) };
+}

package/dist/operations.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import { Store } from './store.js';
+type Operation = {
+    description: string;
+    schema: z.AnyZodObject;
+    run: (args: any) => Promise<unknown>;
+};
+export declare function operations(store: Store): Record<string, Operation>;
+export declare function runOperation(store: Store, operation: string, args?: unknown): Promise<unknown>;
+export {};

package/dist/operations.js

@@ -0,0 +1,130 @@
+import { Lookup, Assess, lookup, assessChanges } from './access.js';
+import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
+import { reviewKnowledge } from './review.js';
+import { ReadKnowledge, readKnowledge, listPillars, listChapters, readChapter, readFact, search, reviewChecklist } from './retrieval.js';
+import { z } from 'zod';
+import { Fact, PillarDefinition, ChapterDefinition, Update, chapterKey, relativePath } from './model.js';
+import { Workflow, Patch, Admission } from './workflow.js';
+import { initialize, discover, guidanceStatus, refreshGuidance } from './init.js';
+import { checkHook, hookNotifications, installHook } from './hooks.js';
+import { startHere, ownershipMap, pillarGraph } from './navigation.js';
+import { checkKnowledge, startTidy } from './maintenance.js';
+import { refreshKnowledgeExport } from './export.js';
+import { version } from './version.js';
+import { SourceSearch, sourceSearch } from './source-search.js';
+const paging = { cursor: z.string().optional(), limit: z.number().int().min(1).max(20).optional() };
+const target = { target: z.string().min(1) };
+const task = { taskId: z.string().uuid() };
+const approval = { approved: z.literal(true).describe('Declaration of explicit developer approval of this exact operation and content; never infer approval from this flag.') };
+const batch = { batches: z.array(z.object({ chapterId: chapterKey, facts: z.array(Fact).min(1) }).strict()).min(1), dryRun: z.boolean().default(false), approved: z.literal(true).describe('Declaration of developer direction covering the initial boundaries and facts, through content approval or explicit delegation to publish within scope. Not proof of human review.').optional(), preflight: z.string().optional() };
+const routing = { path: relativePath.optional(), signal: z.string().optional(), ...paging };
+export function operations(store) {
+    const flow = new Workflow(store);
+    const op = (description, shape, run) => ({ description, schema: z.object(shape).strict(), run });
+    const mutation = async (operation, args, write) => {
+        const result = await write();
+        if (args.verbose)
+            return result;
+        const chapterIds = operation === 'approve' ? args.pillars.flatMap((p) => p.chapters.map((c) => `${p.id}/${c.id}`)) : operation === 'approve-chapters' ? args.chapters.map((c) => `${args.pillarId}/${c.id}`) : [args.chapterId];
+        const factIds = (args.facts ?? []).map((f) => `${args.chapterId}/${f.id}`);
+        return { operation, approved: true, chapterCount: chapterIds.length, chapterIds, factCount: factIds.length, factIds, validation: 'structure and exact evidence; not semantic verification', outputPath: '.common-ground/knowledge.json', next: operation.startsWith('approve') ? 'Boundaries approved; facts still require developer review and approval.' : 'Run validate, then use lookup as needed. Task contexts are optional.' };
+    };
+    const verbose = { verbose: z.boolean().default(false) };
+    const check = op('Check all or selected knowledge for structure, exact evidence and freshness. Stale results list affected IDs and offer cleanup. cleanup:true requires developer-requested cleanup; it creates a scoped tidyId for the calling agent to verify and submit corrections.', { target: z.string().default('all'), cleanup: z.boolean().default(false), allResults: z.boolean().default(false), ...paging }, a => checkKnowledge(store, a.target, a.cleanup, a.cursor, a.limit, undefined, a.allResults));
+    return {
+        lookup: op('Find compact facts, explicit coverage and navigation without scanning source. verify:true checks fact freshness; verbose:true adds matching diagnostics. Weak matches suggest a separate source-search operation.', Lookup.shape, a => lookup(store, a)),
+        'source-search': op('Search explicitly selected files/directories for live source evidence, separate from stored facts. Bounded read-only search; no knowledge or task writes.', SourceSearch.shape, a => sourceSearch(store, a)),
+        assess: op('Read-only assessment of actual task-touched paths. No task needed. Compare candidate source changes; review:true supplies complete chapters and verification paths before corrections.', Assess.shape, a => assessChanges(store, a)),
+        schema: op('Inspect an operation input schema and CLI payload guidance.', { operation: z.string(), both: z.boolean().default(false) }, async (a) => {
+            const entry = operations(store)[a.operation];
+            if (!entry)
+                throw new Error('Unknown operation.');
+            const payload = ['seed', 'admit', 'propose-facts'].includes(a.operation) ? entry.schema.shape.facts
+                : a.operation === 'approve' ? entry.schema.pick({ pillars: true })
+                    : a.operation === 'approve-chapters' ? entry.schema.pick({ chapters: true })
+                        : a.operation === 'accept-facts' ? entry.schema.shape.review
+                            : ['bootstrap', 'seed-batch'].includes(a.operation) ? entry.schema.omit({ dryRun: true, approved: true, preflight: true }) : entry.schema;
+            return { operation: a.operation, description: entry.description, ...(a.both ? { inputSchema: toJsonSchemaCompat(entry.schema) } : {}), cliPayloadSchema: toJsonSchemaCompat(payload) };
+        }),
+        bootstrap: op('Draft an initial map and facts without writes. Publication requires developer content approval or explicit delegation to publish within scope, plus the matching preflight token.', { pillars: z.array(PillarDefinition).min(1), ...batch }, a => {
+            if (!a.dryRun && a.approved !== true)
+                throw new Error('Developer approval required for boundaries and facts.');
+            return store.bootstrap(a.pillars, a.batches, a.dryRun, a.preflight);
+        }),
+        'seed-batch': op('Preflight and populate multiple approved empty chapters atomically.', batch, a => {
+            if (!a.dryRun && a.approved !== true)
+                throw new Error('Developer approval required for facts.');
+            return store.bootstrap(undefined, a.batches, a.dryRun, a.preflight);
+        }),
+        init: op('Initialize or refresh repository setup; report completed/failed steps and continue when advisory hook permissions are unavailable.', { skipHook: z.boolean().default(false) }, a => initialize(store, a)),
+        'refresh-guidance': op('Refresh only managed guidance; preserve surrounding content and shared knowledge.', {}, () => refreshGuidance(store)),
+        scan: op('Discover a proposed responsibility map; no approval or shared knowledge write.', { exclude: z.array(relativePath).default([]) }, a => discover(store, a.exclude)),
+        approve: op('Approve the developer-reviewed responsibility map.', { pillars: z.array(PillarDefinition), standaloneReason: z.string().optional(), ...approval, ...verbose }, a => mutation('approve', a, () => store.approveDefinitions(a.pillars, a.standaloneReason))),
+        migrate: op('Migrate a legacy registry after developer approval.', approval, () => store.migrate()),
+        'approve-chapters': op('Add developer-approved chapters.', { pillarId: z.string(), chapters: z.array(ChapterDefinition), ...approval, ...verbose }, a => mutation('approve-chapters', a, () => store.addChapters(a.pillarId, a.chapters))),
+        seed: op('Populate an approved empty chapter with developer-approved source-verified facts.', { chapterId: chapterKey, facts: z.array(Fact), ...approval, ...verbose }, a => mutation('seed', a, () => store.seed(a.chapterId, a.facts))),
+        admit: op('Admit developer-approved facts after reviewing the whole chapter and source.', { chapterId: chapterKey, facts: z.array(Fact), ...approval, ...verbose }, a => mutation('admit', a, () => store.admit(a.chapterId, a.facts))),
+        'task-start': op('Optional task context for deferred additions or aggregated correction reports; lookup and assess need no task.', { paths: z.array(relativePath).optional(), signal: z.string().optional() }, a => flow.start(a.paths, a.signal)),
+        'task-assess': op('Assess actual task-touched paths.', { ...task, paths: z.array(relativePath), refresh: z.boolean().optional(), ...paging }, a => flow.assess(a.taskId, a.paths, a.cursor, a.limit, a.refresh)),
+        'task-finish': op('Finish task; present compact before/after corrections with reasons, sources and recommendations. Only pending additions need approval; never ask the developer to review JSON.', { ...task, ...paging }, a => flow.finish(a.taskId, a.cursor, a.limit)),
+        'read-knowledge': op('Read bounded knowledge; discover read kinds in the read_knowledge tool or help.', ReadKnowledge.shape, a => readKnowledge(store, a)),
+        'prepare-patch': op('Prepare verified existing-fact maintenance after whole chapter and source review. taskId is optional; omitted means no start/finish lifecycle.', Patch.shape, a => flow.prepare(a)),
+        'propose-facts': op('Queue source-verified facts locally for later approval.', { ...task, chapterId: chapterKey, facts: z.array(Fact).min(1) }, a => flow.propose(a.taskId, a.chapterId, a.facts)),
+        'drop-facts': op('Discard selected local proposal keys.', { ...task, factKeys: z.array(z.string()).min(1) }, a => flow.drop(a.taskId, a.factKeys)),
+        'accept-facts': op('Admit the explicitly approved finished-task batch after complete linked-chapter and source review.', { ...task, review: Admission, ...approval }, a => flow.accept(a.taskId, a.review)),
+        start: op('Route from a source path or symptom.', routing, a => startHere(store, a)),
+        owners: op('Read ownership routing hints.', routing, a => ownershipMap(store, a)),
+        graph: op('Read the recorded dependency graph.', { pillarId: z.string().optional(), ...paging }, a => pillarGraph(store, a.pillarId, a.cursor, a.limit)),
+        review: op('Summarize meaningful pillar/chapter/fact changes against Git HEAD, omitting unchanged records and metadata. Present the delta, verified reason, source links and recommendation in chat; no JSON editing. This is a diff, not proof of truth or approval.', { target: z.string().default('all'), staged: z.boolean().default(false), evidence: z.boolean().default(false), ...paging }, a => reviewKnowledge(store, a.target, a.staged, a.evidence, a.cursor, a.limit)),
+        check,
+        validate: check,
+        tidy: op('Start developer-requested cleanup for all, pillar, chapter or fact; returns tidyId. Calling agent must verify source and submit corrections. No internal model runs.', { ...target, ...paging }, a => startTidy(store, a.target, a.cursor, a.limit)),
+        'review-checklist': op('List source and documentation to read this session.', { chapterIds: z.array(chapterKey), touchedPaths: z.array(relativePath), ...paging }, a => reviewChecklist(store, a.chapterIds, a.touchedPaths, a.cursor, a.limit)),
+        list: op('List pillars.', paging, a => listPillars(store, a.cursor, a.limit)),
+        chapters: op('List chapters in a pillar.', { pillarId: z.string(), ...paging }, a => listChapters(store, a.pillarId, a.cursor, a.limit)),
+        read: op('Read every chapter page before editing; fact retrieves evidence.', { chapterId: chapterKey, ...paging }, a => readChapter(store, a.chapterId, a.cursor, a.limit)),
+        fact: op('Read a fact and evidence.', { chapterId: chapterKey, factId: z.string() }, a => readFact(store, a.chapterId, a.factId)),
+        search: op('Search fact summaries.', { query: z.string().min(1), chapterId: chapterKey.optional(), limit: paging.limit }, a => search(store, a.query, a.limit, a.chapterId)),
+        'review-plan': op('Find required linked chapter reviews.', { chapterId: chapterKey, factIds: Update.shape.factIds }, a => store.reviewPlan(a.chapterId, a.factIds)),
+        prepare: op('Prepare a complete verified review transaction.', Update.shape, a => store.prepare(a)),
+        commit: op('Publish a prepared transaction after source and revision conflict checks.', { proposalId: z.string().uuid() }, a => store.commit(a.proposalId)),
+        'hook-check': op('Run the advisory staged-index hook check without prompting or blocking a commit.', {}, async () => ({ message: await checkHook(store) })),
+        'hook-install': op('Install or inspect integration of the default advisory pre-commit hook.', {}, () => installHook(store)),
+        'hook-mute': op('Suppress this checkout\'s hook notifications at developer request.', {}, () => hookNotifications(store, false)),
+        'hook-unmute': op('Restore this checkout\'s hook notifications at developer request.', {}, () => hookNotifications(store, true)),
+        export: op('Refresh the complete Git-ignored local Markdown reference.', {}, () => refreshKnowledgeExport(store)),
+        doctor: op('Check expected files and registry validity; not a complete host diagnostic.', {}, async () => {
+            const checks = { node: process.version, root: store.root };
+            let valid = true;
+            for (const file of ['AGENTS.md', '.github/copilot-instructions.md', '.vscode/mcp.json', '.common-ground/knowledge.json']) {
+                try {
+                    await store.safe(file);
+                    checks[file] = 'present';
+                }
+                catch {
+                    checks[file] = 'missing';
+                    valid = false;
+                }
+            }
+            try {
+                checks.pillars = (await store.read()).pillars.length;
+            }
+            catch (e) {
+                checks.registryError = e.message;
+                valid = false;
+            }
+            const guidance = await guidanceStatus(store);
+            if (guidance.status !== 'current')
+                valid = false;
+            return { valid, ...checks, guidance, next: valid ? null : checks.registryError ? 'Review the registry error and repair it from source or Git history.' : guidance.next ?? 'Run cground init to repair missing setup.' };
+        }),
+        version: op('Read framework version.', {}, async () => ({ version })),
+    };
+}
+export async function runOperation(store, operation, args = {}) {
+    const catalog = operations(store);
+    const entry = Object.hasOwn(catalog, operation) ? catalog[operation] : undefined;
+    if (!entry)
+        throw new Error(`Unknown operation: ${operation}. Call cground help.`);
+    return entry.run(entry.schema.parse(args));
+}

package/dist/paging.d.ts

@@ -0,0 +1,5 @@
+export declare function page<T>(items: T[], cursor?: string, limit?: number, version?: string, maxChars?: number): {
+    items: T[];
+    total: number;
+    nextCursor: string | null;
+};

package/dist/paging.js

@@ -0,0 +1,32 @@
+import { createHash } from 'node:crypto';
+export function page(items, cursor, limit = 10, version = '', maxChars = Infinity) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 20)
+        throw new Error('Page size must be between 1 and 20');
+    const fingerprint = createHash('sha256').update(JSON.stringify({ version, items })).digest('hex');
+    let offset = 0;
+    if (cursor) {
+        let parsed;
+        try {
+            parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString());
+        }
+        catch {
+            throw new Error('Invalid cursor');
+        }
+        if (parsed.fingerprint !== fingerprint)
+            throw new Error('Content changed; restart pagination.');
+        offset = parsed.offset;
+        if (!Number.isInteger(offset) || offset < 0 || offset > items.length)
+            throw new Error('Invalid cursor');
+    }
+    let next = offset, size = 0;
+    while (next < items.length && next < offset + limit) {
+        const length = JSON.stringify(items[next]).length;
+        // Always return at least one complete record; never truncate evidence or dependencies.
+        if (next > offset && size + length > maxChars)
+            break;
+        size += length;
+        next++;
+    }
+    return { items: items.slice(offset, next), total: items.length,
+        nextCursor: next < items.length ? Buffer.from(JSON.stringify({ offset: next, fingerprint })).toString('base64url') : null };
+}