@nazty_labs/common-ground 0.5.1

package/dist/workflow.js

@@ -0,0 +1,317 @@
+import { GroundError } from './errors.js';
+import { changedFacts } from './access.js';
+import { reviewDocuments } from './review-files.js';
+import { factReview } from './review.js';
+import { promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { bootstrapNext } from './guidance.js';
+import { same } from './store.js';
+import { Fact, Maintenance, Verification, Update, chapterKey, relativePath, unique } from './model.js';
+import { page } from './paging.js';
+import { ownershipMap } from './navigation.js';
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const within = (file, scope) => file === scope || file.startsWith(`${scope}/`);
+const overlaps = (a, b) => within(a, b) || within(b, a);
+const revisionReview = z.object({ chapterId: chapterKey, expectedRevision: z.number().int().positive(), reviewedAllFacts: z.literal(true) }).strict();
+export const Patch = z.object({
+    taskId: z.string().uuid().optional(), chapterId: chapterKey, factIds: Update.shape.factIds,
+    touchedPaths: z.array(relativePath), tidyId: z.string().uuid().optional(), verification: Verification,
+    reviews: z.array(revisionReview.extend({
+        replacements: z.array(Fact).default([]), removeFactIds: z.array(z.string()).default([]),
+        reason: z.string().trim().min(12).max(1000), maintenance: z.array(Maintenance).optional(),
+    }).strict()).min(1),
+}).strict();
+export const Admission = z.object({ reviews: z.array(revisionReview).min(1), verification: Verification }).strict();
+/** Ignored, task-scoped bookkeeping. No prompt history or model calls; only changed fact records and task metadata. */
+export class Workflow {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    name(id) { return `local/task-${z.string().uuid().parse(id)}.json`; }
+    async task(id) {
+        const name = this.name(id);
+        await this.store.safe(`.common-ground/${name}`);
+        return JSON.parse(await fs.readFile(this.store.file(name), 'utf8'));
+    }
+    async save(id, task) { await this.store.atomic(this.name(id), task); }
+    async reuse(id, key, value, context, refresh = false) {
+        if (!id)
+            return value;
+        return this.store.lock(async () => {
+            const task = await this.task(id), reference = digest(key).slice(0, 16), fingerprint = digest({ value, context });
+            if (!refresh && task.cache[reference] === fingerprint)
+                return { unchanged: true, reference };
+            task.cache[reference] = fingerprint;
+            await this.save(id, task);
+            return { ...value, reference };
+        });
+    }
+    async start(paths = [], signal) {
+        paths = z.array(relativePath).parse(paths);
+        // Pending setup is expected after init; never fabricate knowledge or task state.
+        let registry;
+        try {
+            registry = await this.store.read();
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+            try {
+                await this.store.safe('.common-ground/local/bootstrap.json');
+            }
+            catch (setupError) {
+                if (setupError.code !== 'ENOENT')
+                    throw setupError;
+                return { state: 'not-initialized', next: 'Run cground init from the repository root, then review its bootstrap proposal with the developer. Continue the main task from source; no task was started, so do not assess, propose facts or finish.' };
+            }
+            return { state: 'bootstrap-required', proposalPath: '.common-ground/local/bootstrap.json', next: bootstrapNext };
+        }
+        const taskId = randomUUID();
+        const owners = this.store.chapters(registry).filter(({ chapter }) => paths.some(p => chapter.paths.some(s => overlaps(p, s))));
+        const matches = paths.length ? undefined : await ownershipMap(this.store, { signal, limit: 5 });
+        const routes = matches ? { items: matches.items.map(({ chapterId, title }) => ({ chapterId, title })), total: matches.total, nextCursor: matches.nextCursor } :
+            page(owners.map(({ key, chapter }) => ({ chapterId: key, title: chapter.title })), undefined, 5);
+        await this.store.lock(() => this.save(taskId, { phase: 'active', paths: [...new Set(paths)].sort(), cache: {}, changes: {}, pending: [], drafts: [] }));
+        const emptyChapters = this.store.chapters(registry).filter(({ chapter }) => !chapter.facts.length).map(({ key }) => key);
+        return { taskId, ...(emptyChapters.length ? { setup: { state: 'facts-required', boundariesApproved: true, emptyChapters, next: { action: 'review-facts', approvalRequired: true, schema: 'cground schema seed-batch' } } } : {}), routes: { items: routes.items, total: routes.total, hasMore: routes.nextCursor !== null }, next: 'Read relevant chapters and source. Use read_knowledge owners for more routes. Finish the developer task first; batch additions at finish.' };
+    }
+    async assess(id, paths, cursor, limit, refresh = false) {
+        paths = [...new Set(z.array(relativePath).parse(paths))].sort();
+        const registry = await this.store.read();
+        const impact = await changedFacts(this.store, registry, paths);
+        const affected = impact.changed.map(item => item.entry);
+        const byChapter = new Map();
+        for (const entry of affected) {
+            const ids = byChapter.get(entry.chapterId) ?? [];
+            ids.push(entry.fact.id);
+            byChapter.set(entry.chapterId, ids);
+        }
+        const keys = [...new Set([...byChapter].flatMap(([key, ids]) => this.store.related(registry, key, ids)))].sort();
+        const files = keys.length ? await this.store.reviewFiles(registry, keys, paths) : { sourceFiles: [], documentFiles: await reviewDocuments(this.store, paths, 'focused') };
+        const entries = [...keys.map(chapterId => ({ kind: 'chapter', chapterId, revision: this.store.chapter(registry, chapterId).revision })),
+            ...files.sourceFiles.map(path => ({ kind: 'source', path })), ...files.documentFiles.map(path => ({ kind: 'document', path }))];
+        await this.store.lock(async () => { const task = await this.task(id); if (task.phase !== 'active')
+            throw new Error('Task is finished; start a new task for more code work.'); task.paths = paths; await this.save(id, task); });
+        const value = { state: keys.length ? 'review-required' : 'no-fact-review', affectedFactCount: affected.length, ...page(entries, cursor, limit, digest(registry)) };
+        // Recompute live source and documentation state; unchanged status labels are not fingerprints.
+        let context;
+        try {
+            context = { registry, chapters: await this.store.context(registry, keys), files: await this.store.fileSnapshots([...files.sourceFiles, ...files.documentFiles, ...paths]) };
+        }
+        catch {
+            return value;
+        } // Missing evidence still needs attention; do not reuse a cached result.
+        return this.reuse(id, { assess: paths, cursor, limit }, value, context, refresh);
+    }
+    async prepare(input) {
+        const patch = Patch.parse(input), task = patch.taskId ? await this.task(patch.taskId) : undefined;
+        if (task && task.phase !== 'active')
+            throw new Error('Task is finished; start a new task before maintenance.');
+        const registry = await this.store.read();
+        const reviews = patch.reviews.map(({ reviewedAllFacts, replacements, removeFactIds, ...review }) => {
+            const old = this.store.chapter(registry, review.chapterId);
+            if (old.revision !== review.expectedRevision)
+                throw new GroundError('REGISTRY_CONFLICT', 'Chapter revision conflict; reload.', ['expectedRevision'], 'Reload and review the chapter before preparing again.');
+            unique([...replacements.map(f => f.id), ...removeFactIds], 'patch fact IDs');
+            if ([...replacements.map(f => f.id), ...removeFactIds].some(id => !old.facts.some(f => f.id === id)))
+                throw new Error('Patches only edit existing facts; queue additions with propose_facts.');
+            const facts = old.facts.filter(f => !removeFactIds.includes(f.id)).map(f => replacements.find(r => r.id === f.id) ?? f);
+            return { ...review, facts, reviewedFactIds: old.facts.map(f => f.id), invalidatedFactIds: old.facts.filter(f => !same(f, facts.find(n => n.id === f.id))).map(f => f.id) };
+        });
+        const { taskId, ...rest } = patch;
+        const result = await this.store.prepare({ ...rest, reviews });
+        if (!result.noop && taskId)
+            await this.store.lock(async () => {
+                const current = await this.task(taskId);
+                if (current.phase !== 'active')
+                    throw new Error('Task finished during preparation; prepare in a new task.');
+                const file = `local/${result.proposalId}.json`;
+                await this.store.safe(`.common-ground/${file}`);
+                const proposal = JSON.parse(await fs.readFile(this.store.file(file), 'utf8'));
+                // Persist pending first. If interrupted, finish reports attention instead of false silence.
+                current.pending.push(result.proposalId);
+                await this.save(taskId, current);
+                await this.store.atomic(file, { ...proposal, taskId });
+            });
+        return result;
+    }
+    async draftFingerprint(registry, chapterId, fact) {
+        const candidate = structuredClone(registry), chapter = this.store.chapter(candidate, chapterId);
+        if (chapter.facts.some(f => f.id === fact.id))
+            throw new Error(`Fact already exists: ${chapterId}/${fact.id}`);
+        chapter.facts.push(fact);
+        this.store.validateRegistry(candidate);
+        await this.store.validateFacts({ paths: chapter.paths, facts: [fact] });
+        const dependencies = this.store.upstreamFacts(candidate, `${chapterId}/${fact.id}`);
+        const sources = await this.store.snapshot({ paths: chapter.paths, facts: [fact] });
+        const upstream = [];
+        for (const key of dependencies) {
+            const dep = this.store.fact(candidate, key);
+            upstream.push({ key, fact: dep.fact, sources: await this.store.snapshot({ paths: dep.chapter.paths, facts: [dep.fact] }) });
+        }
+        return digest({ chapter: this.store.chapter(registry, chapterId), fact, sources, upstream });
+    }
+    async propose(id, chapterId, values) {
+        const facts = z.array(Fact).min(1).parse(values);
+        unique(facts.map(f => f.id), 'proposed fact IDs');
+        return this.store.lock(async () => {
+            const task = await this.task(id);
+            if (task.phase !== 'active')
+                throw new Error('Task is finished. Start a new task to propose or reverify additions.');
+            const registry = await this.store.read(), drafts = [...task.drafts];
+            for (const fact of facts) {
+                const draft = { chapterId, fact, fingerprint: await this.draftFingerprint(registry, chapterId, fact) };
+                const index = drafts.findIndex(d => d.chapterId === chapterId && d.fact.id === fact.id);
+                if (index < 0)
+                    drafts.push(draft);
+                else
+                    drafts[index] = draft;
+            }
+            task.drafts = drafts;
+            await this.save(id, task);
+            return { queued: facts.length, total: task.drafts.length, sharedKnowledgeChanged: false };
+        });
+    }
+    async draftStates(task, registry) {
+        const states = [];
+        for (const draft of task.drafts) {
+            let stale = false;
+            try {
+                stale = draft.fingerprint !== await this.draftFingerprint(registry, draft.chapterId, draft.fact);
+            }
+            catch {
+                stale = true;
+            }
+            states.push({ kind: 'new-fact', factId: `${draft.chapterId}/${draft.fact.id}`, statement: draft.fact.statement, evidencePaths: [...new Set(draft.fact.evidence.map(e => e.path))], stale, recommendation: stale ? 'reverify' : 'present-for-approval' });
+        }
+        return states;
+    }
+    async finish(id, cursor, limit) {
+        return this.store.lock(async () => {
+            const task = await this.task(id), registry = await this.store.read();
+            const additions = await this.draftStates(task, registry);
+            task.phase = 'awaiting-approval';
+            await this.save(id, task);
+            const changes = [];
+            const states = new Map();
+            for (const [factId, statement] of Object.entries(task.changes)) {
+                let current = null;
+                try {
+                    current = this.store.fact(registry, factId).fact;
+                }
+                catch { }
+                const detail = task.changeDetails?.[factId];
+                const changedSinceUpdate = detail ? !same(current, detail.after) : (current?.statement ?? '(removed)') !== statement;
+                const delta = detail ? factReview(detail.before, detail.after) : undefined;
+                if (detail && !delta && !changedSinceUpdate)
+                    continue; // A correction reverted in this task has no net change.
+                let evidenceValid = false;
+                if (detail)
+                    try {
+                        const key = factId.slice(0, factId.lastIndexOf('/'));
+                        await this.store.validateFacts({ paths: this.store.chapter(registry, key).paths, facts: current ? [current] : [] });
+                        if (!states.has(key))
+                            states.set(key, (await this.store.status(key, registry)).status);
+                        evidenceValid = current === null && detail.after === null || states.get(key) === 'evidence-unchanged';
+                    }
+                    catch { }
+                changes.push({ kind: 'updated-fact', factId, ...(!delta || !delta.fields.statement ? { statement } : {}), ...(delta ?? {}),
+                    reason: detail?.reason ?? 'Older task receipt has no before/after detail; use cground review.',
+                    changedSinceUpdate, evidenceStatus: evidenceValid ? 'mechanically-current' : 'needs-review',
+                    recommendation: changedSinceUpdate || !evidenceValid ? 'reverify' : 'keep-verified-correction', approvalRequired: false });
+            }
+            const entries = [...changes, ...additions,
+                ...task.pending.map(proposalId => ({ kind: 'uncommitted-review', proposalId }))];
+            const attention = task.pending.length || additions.some(a => a.stale) || changes.some(c => c.recommendation === 'reverify');
+            const reviewPrompt = attention
+                ? 'Resolve pending reviews or changed evidence before sharing these facts with the team.'
+                : additions.length
+                    ? 'Ready to make the following facts available to the team? Review the proposed facts and evidence before approving admission.'
+                    : 'Summarize applied corrections: before → after, reason, source links, and your recommendation. The developer does not need to open or edit JSON.';
+            return { notification: attention ? 'attention' : additions.length ? 'approval-required' : entries.length ? 'summary' : 'none',
+                ...page(entries, cursor, limit, '', 12000), ...(entries.length ? { reviewPrompt, reviewFormat: 'Present changed items only, grouped by pillar/chapter. Include before → after, why, source links, and keep/approve/reverify recommendation. Corrections are applied; additions still await explicit approval. Mechanical checks do not prove semantic truth; state uncertainty.' } : {}) };
+        });
+    }
+    async proposals(id, cursor, limit) {
+        const task = await this.task(id);
+        return page(task.drafts.map(({ fingerprint, ...draft }) => draft), cursor, limit, '', 12000);
+    }
+    async drop(id, keys) {
+        if (!keys.length)
+            throw new Error('Supply fully qualified fact IDs to discard.');
+        return this.store.lock(async () => {
+            const task = await this.task(id);
+            if (keys.some(key => !task.drafts.some(d => `${d.chapterId}/${d.fact.id}` === key)))
+                throw new Error('Unknown queued fact.');
+            task.drafts = task.drafts.filter(d => !keys.includes(`${d.chapterId}/${d.fact.id}`));
+            await this.save(id, task);
+            return { remaining: task.drafts.length, sharedKnowledgeChanged: false };
+        });
+    }
+    async admissionPlan(id) {
+        const task = await this.task(id), registry = await this.store.read(), candidate = structuredClone(registry);
+        if (task.phase !== 'awaiting-approval')
+            throw new Error('Finish the developer task before admitting new facts.');
+        if (!task.drafts.length)
+            throw new Error('No queued facts.');
+        if ((await this.draftStates(task, registry)).some(d => d.stale))
+            throw new Error('Queued evidence or knowledge changed; reverify and propose in a new task.');
+        for (const d of task.drafts)
+            this.store.chapter(candidate, d.chapterId).facts.push(d.fact);
+        this.store.validateRegistry(candidate);
+        const keys = [...new Set(task.drafts.flatMap(d => this.store.related(candidate, d.chapterId)))].sort();
+        return { task, registry, candidate, keys };
+    }
+    async proposalReview(id, cursor, limit) {
+        const { task, registry, candidate, keys } = await this.admissionPlan(id);
+        const files = await this.store.reviewFiles(registry, keys, task.paths, candidate);
+        return page([...keys.map(chapterId => ({ kind: 'chapter', chapterId, expectedRevision: this.store.chapter(registry, chapterId).revision })),
+            ...files.sourceFiles.map(path => ({ kind: 'source', path })), ...files.documentFiles.map(path => ({ kind: 'document', path }))], cursor, limit, digest({ candidate, files }));
+    }
+    async accept(id, input) {
+        const review = Admission.parse(input);
+        return this.store.lock(async () => {
+            const { task, registry, candidate, keys } = await this.admissionPlan(id);
+            if (task.pending.length)
+                throw new Error('Resolve uncommitted maintenance before admitting new facts.');
+            unique(review.reviews.map(r => r.chapterId), 'chapter reviews');
+            if (!same(keys, review.reviews.map(r => r.chapterId).sort()))
+                throw new Error(`Review every linked chapter: ${keys.join(', ')}`);
+            for (const item of review.reviews)
+                if (this.store.chapter(registry, item.chapterId).revision !== item.expectedRevision)
+                    throw new GroundError('REGISTRY_CONFLICT', 'Chapter revision conflict; reload.', ['expectedRevision'], 'Reload and review the chapter before preparing again.');
+            const files = await this.store.reviewFiles(registry, keys, task.paths, candidate);
+            for (const kind of ['sourceFiles', 'documentFiles']) {
+                unique(review.verification[kind], 'verified files');
+                for (const file of files[kind])
+                    if (!review.verification[kind].includes(file))
+                        throw new Error(`Session verification required for ${kind}: ${file}`);
+            }
+            const snapshots = {};
+            for (const key of keys) {
+                const chapter = this.store.chapter(candidate, key);
+                await this.store.validateFacts(chapter);
+                snapshots[key] = await this.store.snapshot(chapter);
+            }
+            await this.store.fileSnapshots([...review.verification.sourceFiles, ...review.verification.documentFiles]);
+            const changed = [...new Set(task.drafts.map(d => d.chapterId))];
+            for (const key of changed) {
+                const c = this.store.chapter(candidate, key);
+                c.revision++;
+                c.sources = snapshots[key];
+                c.dependencyFingerprints = this.store.dependencyFingerprints(candidate, key);
+            }
+            if (!same(await this.store.read(), registry) || (await this.draftStates(task, registry)).some(d => d.stale))
+                throw new Error('Source or knowledge changed during admission; reverify.');
+            // Validate the entire batch before the one shared registry write.
+            await this.store.persist(candidate);
+            const admitted = task.drafts.length;
+            task.drafts = [];
+            await this.save(id, task);
+            await this.store.markReviewed(candidate, keys, snapshots);
+            return { admitted, changedChapters: changed };
+        });
+    }
+}

package/docs/architecture.md

@@ -0,0 +1,65 @@
+# Architecture and beta boundaries
+
+Common Ground is an open-source framework combining a repository knowledge model, maintenance rules, and a local implementation developers can adapt and extend. The CLI and stdio MCP server expose that framework to coding agents. Integrations can use those interfaces and the published JSON schemas; implementation changes live in the TypeScript modules below.
+
+The supported customization surface is repository definitions and supplemental guidance, plus CLI/MCP integrations. Custom discovery, validators, record fields, storage backends, and tools require source changes. There is no plugin loader, stable public SDK, lifecycle-hook API, or configurable discovery-provider interface in this beta. Internal module exports are implementation details rather than a promised extension contract.
+
+- `src/access.ts`: stateless bounded lookup with separate registry-based ownership hints, optional fact-level verification, and source-sensitive change assessment with opt-in complete review packages.
+- `src/matching.ts`: shared technical tokenization, exact version and short-acronym boundaries, corpus-based term weights and direct-path recognition.
+- `src/source-search.ts`: separate bounded live-source search with explicit paths, lexical line excerpts and no knowledge writes.
+- `src/review.ts`: read-only content deltas for pillars/chapters/facts and compact task correction presentation; no second shared knowledge store.
+- `src/operations.ts`: shared CLI/MCP execution and validation, per-operation schemas and approval declarations.
+- `src/commands.ts`: dependency-free CLI syntax/help metadata and strict built-in argument parsing.
+- `src/retrieval.ts`: transport-independent navigation and task-scoped retrieval, also re-exported by the server for compatibility.
+- `src/maintenance.ts`: shared CLI/MCP checks, stale summaries and scoped cleanup handoffs.
+- `src/export.ts`: complete deterministic Markdown rendering and atomic refresh of the ignored local reference.
+- `src/model.ts`: strict schema v2 pillar, chapter, fact, and multi-chapter review records; schema v1 migration input.
+- `src/store.ts`: safe paths, evidence and ownership checks, dependency traversal, freshness, migration, and atomic review transactions.
+- `src/workflow.ts`: task-local context reuse, compact patches, deferred fact proposals, and reviewed batch admission.
+- `src/hooks.ts`: default advisory Git hook installation, staged-source checks, and checkout-local notification preferences.
+- `src/init.ts`: managed repository instructions/MCP configuration and bootstrap orchestration.
+- `src/discovery.ts`: bounded static manifest/source-path discovery, technology signals and proposed project ownership.
+- `src/server.ts`: six default stdio MCP tools (fourteen in the compatibility profile), paginated navigation, evidence retrieval, and Unicode-aware keyword search.
+- `src/navigation.ts`: derived ownership routing, pillar graph, Start Here responses, read-only scoped validation, and tidy plans including whole-registry review.
+- `src/review-files.ts`: bounded discovery of local, sibling, child, and referenced review documentation.
+- `src/guidance.ts`: short entry instructions, invariant policy and managed Start Here guide.
+- `src/paging.ts`: shared pagination and cursor validation.
+- `src/errors.ts`: stable CLI JSON error envelopes and typed domain errors.
+- `src/cli.ts`: shell-to-operation adapter, concise terminal output, and lazy MCP entry point.
+
+`.common-ground/knowledge.json` is a Git-tracked registry. Pillars contain chapter definitions; chapters index facts and define authoring boundaries. Facts own exact evidence, source scopes, and directed fact-to-fact dependencies. One atomic file permits all affected chapter revisions to publish together. `.common-ground/local/` contains a generated `knowledge.md` view of the complete registry, ignored proposals, review snapshots, a migration backup, tidy request receipts, task receipts/context fingerprints, queued fact drafts, and a writer lock. `.common-ground/START_HERE.md` and `.common-ground/POLICY.md` are tracked guidance. Ownership maps and pillar graphs are derived from the registry rather than duplicated in a second data model.
+
+Storage has no fixed fact-count ceiling. Pillar and chapter indexes and chapter fact reads are paginated (10 by default, up to 20 per response). Stateless lookup reads only the registry unless verification is requested. Assessment hashes only touched portions of candidate source scopes before expanding review. Request-scoped hash reuse deduplicates read work; publication checks never reuse those caches. The compact profile can batch complete facts with evidence, using a 12,000-character soft page budget (a single oversized record stays intact). The full profile also supports individual fact reads. Keyword search returns at most 20 summaries. Pagination rejects changed index/fact content. A full chapter review must traverse all its fact pages.
+
+The current storage engine still parses the full registry internally, and source hashing is synchronous work per tool request. The beta has no database index, background watcher, vector search, or incremental validator. The pre-commit hook invokes an advisory check against a temporary export of the Git index; it never rewrites knowledge or blocks commits. Existing hook managers require adding cground hook check to their entry point. Response pagination limits agent context, not internal compute. Very large knowledge stores need performance evaluation and likely indexed/per-chapter storage before a production claim.
+
+Lookup preserves version tokens, downweights terms shared across the stored corpus and prioritizes direct evidence paths. Compact results contain one statement, source-path list, relevance label and freshness result per fact; `verbose:true` adds matching diagnostics. Weak lexical coverage leads with “No direct answer found,” then bounded registry navigation and a separate, unexecuted source-search suggestion. The `source-search` operation requires explicit paths and labels results `live-source-evidence`. It reads at most 2,000 entries, 200 files, 1 MiB per file and 4 MiB total, returning up to five line excerpts. It skips symlinks, binary/non-UTF-8 files, generated/dependency paths and hidden configuration except `.github`; exclusions and truncation are explicit. It neither accesses the registry nor runs project commands. See [the setup guide](../SETUP.md#search-live-source-when-knowledge-is-thin).
+
+Dependency reviews start from selected fact IDs (or all facts in a chapter), traverse fact dependencies and reverse dependents transitively, and group the result into chapter reviews. Every linked chapter must be reviewed, but only changed facts and chapters are rewritten. Explicit maintenance can correct an existing false claim, merge duplicates, remove superseded content, or tighten narrative without requiring source drift. Routine maintenance is confined to affected chapters; developer-requested tidy receipts authorize a bounded cleanup scope. A dense graph can still produce expensive reviews. Cross-pillar relationships are supported; missing undeclared dependencies cannot be inferred reliably. Shared chapter membership alone does not propagate dependency impact.
+
+Discovery examines at most 1,500 filesystem entries breadth-first, reads at most 256 KiB per manifest and 2 MiB of accepted manifest content, and returns up to 50 project candidates with 30 file/directory path hints each. It recognizes common web/mobile/native/backend frameworks, workspace markers and CI layouts. Signals are grouped by project root and broad responsibility; framework labels never become facts automatically. Native subtrees of React Native/Expo/Flutter projects are grouped with the parent. Ownership hints collapse homogeneous fully scanned subtrees into directory suggestions, while mixed, excluded, nested-owner or truncated areas retain narrower hints. Responsibility rationales and delivery coverage prompts help the agent refine the map before authorized initial publication. All sampling and malformed/skipped manifests are reported. Developers approve an agent-refined map; discovery does not prove exhaustive coverage. See [the discovery catalog](discovery.md). Fact scope scans remain separately limited to 10,000 entries. Freshness hashing streams regular files without a per-file size cap; quotation evidence retains a 2,000,000-byte limit. Supporting evidence can cross chapter ownership and remains part of freshness and task impact. Bootstrap and empty-chapter batches support no-write preflight with file counts, then one approval-directed atomic publication guarded by a content token.
+
+Semantic entailment, approval UI, automatic command capture, remote sync, scope migration, and native Windows testing remain out of scope. `doctor` checks expected file presence, registry validity and managed guidance against installed templates; it is not a complete MCP-host diagnostic.
+
+Snapshots are optimistic checks, not OS-level filesystem snapshots. Source changes can occur after the final check. Registry writes are serialized and atomically renamed on one filesystem. If a process crashes holding a lock, confirm no writer remains before deleting `.common-ground/local/write.lock`.
+
+Avoid secrets in records. .env paths are excluded; comprehensive secret scanning is not implemented. Common Ground sends nothing to a remote service, but an agent host may transmit retrieved results to its model provider.
+
+Update requests now require session verification declarations for evidence source and discovered documentation, including no-op reviews. Commit rejects subsequent source/documentation drift. These declarations are not proof of external agent reading, and semantic correction remains the agent's responsibility. Point-in-time state, unverified claims, and debugging narratives are forbidden by policy, not by a semantic classifier. Legacy seed/admit operations still enforce exact evidence and developer direction; their session-reading and cleanup rules are agent responsibilities.
+
+Documentation discovery scans at most 10,000 scoped entries and follows at most 1,000 local documents. Root-level changes do not recursively scan the entire monorepo. The checklist follows Markdown document links, not every programming-language import or documentation reference syntax; agents must follow other relevant references themselves.
+
+Compact patches declare `reviewedAllFacts: true` against a chapter revision and reconstruct unchanged records server-side before invoking the existing validator. They do not weaken whole-chapter review. Task receipts track only committed corrections from that task; pending failed transactions produce an attention result at finish. A crash after a shared write but before its local receipt is saved can require manual reconciliation. Task state remains local and disposable after review, not shared history.
+
+New fact proposals are local and excluded from authoritative retrieval. They snapshot their chapter, source scopes and admitted upstream dependencies. Finished tasks can be admitted through explicit approval CLI or MCP operations, with a complete linked-chapter review and source/documentation declarations. Stale drafts require fresh verification and a new proposal batch. The batch writes atomically across chapters. Dependencies on other pending drafts are not supported. Legacy seed/admit commands remain available for developer-directed bootstrap/operator work, so finish/approval checks are a workflow boundary, not a sandbox against filesystem access.
+
+Response reuse is task-scoped and recomputes live fingerprints; it does not cache Git branch/submodule state, prove source reading, or survive context loss semantically. The caller must refresh or start a new task after losing earlier responses. Internal full-registry parsing and source hashing remain; byte savings measure transferred context, not all CPU, latency, or billed tokens. See `npm run measure:context` and the regression fixtures in `test/workflow.test.mjs`.
+
+
+The Markdown export contains shared records only, including evidence, dependency links, revisions and stored fingerprints. Init creates a bootstrap placeholder when the registry is absent. CLI validate/tidy and successful shared writes refresh the export; pure navigation/MCP tidy previews remain read-only. Export output is deterministic and compared before atomic replacement, so unchanged content preserves file modification time. CLI refreshes use the writer lock; shared-write refreshes run within their existing transaction. Failure to refresh this disposable view after a successful knowledge write is reported on stderr without undoing or misreporting that write. No local drafts or review receipts are rendered.
+
+Task-local correction receipts retain only the before/after records for facts actually changed, plus a reason, so finish can show a net delta and detect later evidence-only edits. They are ignored local state, not a second shared history. Git review compares the registry with HEAD or the index without writing files; it never implies approval or semantic correctness.
+
+CLI JSON errors use `{error: {code, message, fields, recovery}}` on stderr with a nonzero exit status. Codes include `INPUT_NOT_FOUND`, `INPUT_UNREADABLE`, `INVALID_JSON`, `INVALID_OPTION_VALUE`, `UNKNOWN_COMMAND`, `REGISTRY_INVALID`, `REGISTRY_MIGRATION_REQUIRED`, `REGISTRY_CONFLICT`, and `SOURCE_CONFLICT`. Missing registries still return onboarding guidance where supported; corrupt registries never masquerade as missing setup. `INIT_INCOMPLETE` additionally supplies `details` with completed, skipped, failed and pending setup steps and the underlying error. MCP operation failures preserve these initialization details under `diagnostic`. Advisory hook permission failures return setup warnings without aborting initialization; `skipHook:true` omits hook installation. `fields` identifies the input filename, option, registry, or changed reviewed paths when known. Unclassified failures retain `OPERATION_FAILED`; callers should tolerate unfamiliar codes. Doctor remains a diagnostic result (`valid:false` and registry details), rather than a thrown operation error.
+
+Guidance refresh reports `changedFiles` and `unchangedFiles` without touching the registry, MCP configuration or hooks. A completed refresh and healthy doctor return `next:null`; outdated guidance still names the refresh command. Bootstrap publication recommends lookup, not mandatory task bookkeeping.

package/docs/audit-0.4.0.md

@@ -0,0 +1,42 @@
+# 0.4.0 beta audit
+
+The audit covered CLI parsing and help, CLI/MCP parity, onboarding, dependencies and startup, knowledge storage and review transactions, source and documentation discovery, pre-commit checks, Markdown export, tests, packaging, and developer documentation. The changes focus on reducing duplicated execution paths and making existing capabilities easier to use.
+
+## Findings and changes
+
+| Finding | Change |
+| --- | --- |
+| `init --help` could initialize a repository; most commands lacked contextual help | Handle help before loading or running operations. Every command gets usage, options, and examples, including nested hook/task commands. Regression tests check every command against an empty directory. |
+| Options were removed from a global argument array regardless of which command used them | Use Node's built-in `util.parseArgs`, validate options per command, and reject incorrect arity and values before execution. Support `-h`, `-V`, `--name=value`, and `--` consistently. |
+| CLI and MCP duplicated domain dispatch and validation | CLI arguments now adapt to the same structured operation handlers used by MCP. A two-way parity test checks the complete command catalog. |
+| The operations module imported the MCP server, which imported operations | Extract retrieval into a transport-independent module; only `serve` loads the MCP runtime. Server exports remain compatible. |
+| Help/version loaded Zod, the knowledge engine, and MCP | Keep early command handling independent of those modules. Test a help/version installation containing only the entry point, command metadata, and package version reader. |
+| Check/validate schemas repeated the same behavior | Make both names reference the same operation definition. |
+| Check output was verbose for terminal users | Return a concise terminal summary; preserve JSON for pipes and `--json`, with diagnostics on stderr and no prompts in pipelines. |
+| Markdown export existed through MCP but had no direct CLI command | Add `cground export`, using the existing operation. |
+| Muted pre-commit reminders still exported and hashed the index | Return after reading the notification preference when muted; there is no check result to consume or persist. |
+| Getting started required scanning implementation and operator details | Shorten the README around install → init → review → check, then link the detailed workflow and contracts. |
+
+## What stays, and why
+
+- **One shared JSON registry:** already a small, understandable persistence model. No database, watcher, queue service, cloud dependency, or plugin runtime was added.
+- **Atomic writes, writer lock, revision/source checks, whole-chapter review, and approval declarations:** these protect shared knowledge from partial writes, stale evidence, unreviewed edits, and accidental growth. Removing them would weaken the framework's core behavior.
+- **Task-local receipts, drafts, and bounded context reuse:** these support deferred approval, accurate completion reports, and smaller repeated reads. They remain Git-ignored. No new cache layer was introduced.
+- **Staged Git export:** more work than checking the working tree, but needed to catch a stale staged change even when unstaged files already contain a fix. The existing filter and symlink protections stay. This can be expensive in a large repository.
+- **Both MCP profiles and existing CLI names:** preserving integrations is more useful than deleting aliases simply to reduce command count. The everyday commands appear first in help; all advanced commands remain discoverable.
+- **MCP SDK, Zod, and JSONC parser:** each has a concrete role in protocol compatibility, shared schemas, and preserving user configuration. No new runtime dependency was added. The lockfile contains 95 production packages including transitive dependencies; three direct dependencies does not mean three installed packages.
+
+## Measurements and checks
+
+Nine local runs of each help command, immediately before upgrading the installed package, measured median startup of **188.0 ms for installed 0.3.0-beta.1** and **30.5 ms for the new CLI**. These are warm local wall-clock measurements, not cross-machine or cold-start guarantees. They measure help startup, not validation throughput.
+
+Validation covers all-command help with no repository writes, strict arguments, CLI/MCP parity, actual stdio MCP calls, approval gates, synthetic source/dependency changes, source/revision conflicts, staged versus unstaged hook behavior, deterministic export, schema generation, demo and package installation. The behavior suite contains 142 passing tests, including checks of both MCP profiles. Release packaging also runs the synthetic demo and regenerates schemas.
+
+This is a maintainability and developer-experience audit, not a claim of exhaustive security verification or production-scale performance. Native Windows and VS Code GUI acceptance remain unverified. Very large registries still require profiling; the core parses the registry and hashes source per request. Exact evidence and hashes establish mechanical consistency, not the truth of natural-language claims.
+
+## CLI conventions consulted
+
+- [npm help](https://docs.npmjs.com/cli/v11/commands/npm-help/): discover command documentation from the terminal.
+- [Commander](https://github.com/tj/commander.js#automated-help): contextual help, explicit argument syntax, and rejection of unknown options. Common Ground uses Node's parser rather than adding a CLI dependency.
+- [Prettier CLI](https://prettier.io/docs/cli#--check): concise check summaries, affected-item lists, and documented exit behavior.
+- [Node util.parseArgs](https://nodejs.org/api/util.html#utilparseargsconfig): standard strict parsing and positional argument support.

package/docs/demo.md

@@ -0,0 +1,42 @@
+# Synthetic workflow demo
+
+Build and pack the source, then install the resulting `nazty_labs-common-ground-0.5.1.tgz` using npm. Copy `examples/demo-monorepo` to a separate directory and run:
+
+```sh
+cground init
+cground approve demo-data/plan.json --approve
+cground seed workspace-tooling/overview demo-data/workspace-tooling.json --approve
+cground seed ci-cd/overview demo-data/ci-cd.json --approve
+cground seed web-components/search demo-data/web-components.json --approve
+cground seed web-components/results demo-data/web-results.json --approve
+cground seed java-application/overview demo-data/java-application.json --approve
+cground start "build failed"
+cground owners --path pipelines/build.yml
+cground graph ci-cd
+cground chapters web-components
+cground read web-components/search
+cground fact web-components/search search-minimum
+cground review-plan web-components/search --facts search-minimum
+```
+
+The supplied plan is synthetic reviewed fixture data. Real initialization requires source review and refined responsibility boundaries. Initial publication needs content approval or explicit developer delegation to save the verified map within scope.
+
+Open the directory in VS Code and start Common Ground with MCP: List Servers. Ask Copilot to route a build failure to its owner and inspect the recorded CI → workspace dependency, then select Search and explain its facts. Check that six default tools are available. The original CLI commands below remain supported. Commit source, shared registry, Start Here guide, detailed policy, instructions, and MCP configuration; local metadata remains ignored. No Java build dependency is invented: the fixture does not establish a complete Nx/Java application stack.
+
+Change `SEARCH_MIN_LENGTH = 2` to `SEARCH_MIN_LENGTH = 3` in `packages/ui/search.ts`. The Results validation fact depends on the Search threshold fact, so both chapters must be reviewed:
+
+```sh
+cground review-plan web-components/search --facts search-minimum
+cground review-checklist web-components/search web-components/results --touched packages/ui/search.ts
+cground prepare demo-data/search-update.json
+cground commit PASTE_RETURNED_PROPOSAL_ID
+cground check
+```
+
+Before preparing, open the source files, `AGENTS.md`, and `packages/ui/README.md` listed in the request's verification fields. Those fields declare actual reading, not an instruction to skip it. Confirm that the README remains valid even though it needs no edit.
+
+The request corrects the Search fact and includes an unchanged full review of Results. Publication increments Search's revision only. Results still uses the shared constant, so its existing assertion remains true. The local review record acknowledges the dependency check without rewriting valid shared knowledge.
+
+For an automated version, run `npm run demo` from the Common Ground source directory. It copies the fixture to a temporary directory and prints its location. These fixtures illustrate contracts; they are not a complete runnable Nx/Java application stack.
+
+The automated demo also uses a task-scoped compact patch, checks that an unchanged page is reused, and verifies that finish reports only the corrected search fact. For a walkthrough of deferred additions and approval, see [the quiet task workflow](quiet-workflow.md). Run `npm run measure:context` to compare serialized context sizes.

package/docs/discovery.md

@@ -0,0 +1,70 @@
+# Repository discovery
+
+`cground init` uses bounded static discovery to propose an initial responsibility map. `cground scan` returns the same kind of preview without writing knowledge. Once a repository has an approved registry, `init` refreshes managed guidance and configuration while preserving that registry and skipping discovery.
+
+Discovery never runs project commands, installs dependencies, imports configuration scripts, invokes a model, seeds facts, or records inferred dependencies. Its observations are navigation hints for the calling agent. The agent reviews code and local READMEs and refines the proposed boundaries. Initial publication needs content approval or explicit developer delegation to save/publish a verified initial map within scope; discovery itself grants no authorization.
+
+## Built-in signals
+
+| Family | Recognized signals |
+|---|---|
+| Angular | `@angular/core` dependency, `angular.json` project roots/types, Angular Nx executor/builder names |
+| React / Next.js | `react` and `next` dependencies; matching explicit Nx executor names |
+| Vue / Nuxt | `vue` and `nuxt` dependencies, `.vue` source paths; matching Nx executor names |
+| Svelte / SvelteKit / Astro | `svelte`, `@sveltejs/kit`, `astro` dependencies; `.svelte` and `.astro` paths |
+| React Native / Expo | `react-native` or `expo` dependencies, an `expo` object in `app.json`/`app.config.json`, matching Nx executor names |
+| Swift / native Apple | `Package.swift`, Xcode `project.pbxproj`, `.swift` source paths; Swift alone does not imply iOS |
+| Java / Kotlin / Android | Maven `pom.xml`, Gradle build/settings files, `.java`/`.kt` paths, `AndroidManifest.xml`, Android plugin identifiers; Gradle alone does not imply Java |
+| Spring Boot | `org.springframework.boot` in Maven/Gradle manifests |
+| Node / TypeScript backends | `package.json`, JS/TS source paths, `express`, `fastify`, `@nestjs/core`, `typescript` dependencies |
+| Python | `pyproject.toml`, requirements files, `Pipfile`, `setup.py`, `.py` paths; Django, FastAPI and Flask names in dependency manifests |
+| Go / Rust | `go.mod`, `go.work`, `Cargo.toml`, `.go`/`.rs` paths; Cargo workspace tables |
+| .NET | Project/solution filenames (`.csproj`, `.fsproj`, `.vbproj`, `.sln`, `.slnx`) and C#/F# source paths |
+| Ruby / PHP | `Gemfile`, `composer.json`, Ruby/PHP paths; Rails gem and Laravel requirement declarations |
+| Dart / Flutter | `pubspec.yaml`, `.dart` paths, a Flutter key in the manifest |
+| Workspaces / monorepos | npm/Yarn workspaces, pnpm workspace files, Nx project/workspace files, Turborepo, Lerna, Angular workspace projects, Go/Cargo/Gradle workspace markers, conventional `apps/`, `packages/`, `libs/`, `services/`, `projects/` roots |
+| Shared libraries | Explicit Angular/Nx library declarations and conventional `libs/` or `packages/ui`, `packages/components`, `packages/shared` JS/TS paths |
+| CI/CD | GitHub Actions, Azure pipeline filenames and `pipelines/` YAML, GitLab CI, CircleCI, Jenkinsfile |
+
+Package signals come from declared dependencies, development dependencies, peer dependencies, and optional dependencies. Merely mentioning React in a README or lockfile, or depending on `@types/react`, does not identify a React application. Source extensions identify language hints; JSX/TSX alone does not prove React. Text-based checks for non-JSON manifests are heuristics, not full parsers or proof of runtime use.
+
+These built-ins follow recognizable conventions such as [Angular workspace project definitions](https://angular.dev/reference/configs/workspace-config), [Nx explicit project targets](https://nx.dev/docs/reference/project-configuration), [Swift package manifests](https://docs.swift.org/package-manager/PackageDescription/PackageDescription.html), [Expo configuration](https://docs.expo.dev/versions/latest/config/app/), and [Flutter pubspec files](https://docs.flutter.dev/tools/pubspec). They do not require a particular framework version or execute its tooling.
+
+## Responsibilities, not one pillar per technology
+
+Detections contain raw signals: a project root, technology labels, supporting paths and counts. Each links to a coarse candidate chapter and explains its rationale. Separate `responsibilityHints` use path conventions to suggest native code, Python interfaces, tests, examples and delivery responsibilities for review. They are alternatives to consider, not additional approved chapters or claims about behavior. A Next.js application can list both Next.js and React in one chapter. A React Native application can include React, Swift and Java/Kotlin signals from its `ios/` and `android/` subtrees without creating independent pillars for those implementation layers.
+
+Projects are grouped under broad candidate responsibilities such as web applications, mobile applications, native packages, JVM projects, shared libraries, workspace tooling and CI/CD. Multiple projects in the same family become chapter candidates under one pillar. A repository may need different ownership boundaries, or multiple technology families may belong to one subsystem: the agent must merge or adjust those proposals with the developer. These defaults do not establish semantic independence.
+
+Nested manifests and Angular declarations establish project roots. Explicit Nx executor names can distinguish applications with dependencies shared at the workspace root. Nx inferred tasks and arbitrary build scripts are not evaluated. Manifests, source paths and conventional directory names may be insufficient; ambiguous or missing ownership remains a review question.
+
+## Limits and output
+
+- Scan at most **1,500 directory entries**, breadth-first. Root manifests and shallow sibling projects are examined before deep trees; conventional first-party directories (src, include, apps, packages, libs, services) are queued ahead of other siblings. Very wide directories can still exhaust the budget.
+- Read at most **256 KiB per manifest** and accept at most **2 MiB of manifest content**. Oversized, malformed and budget-skipped manifests generate warnings. Source files are identified by path; their contents are left for agent verification.
+- Skip symlinks, `.env*`, dependencies, common generated output (including `.vite` dependency caches), virtual environments and native build/dependency directories such as `third_party`, `third-party`, `thirdparty`, `external`, `extern`, `deps`, `dependencies`, `Pods`, `Carthage`, `DerivedData`, `.build`, `.gradle` and `.dart_tool`. This uses a built-in exclusion list, not a complete `.gitignore` implementation.
+- Return at most **50 project candidates**, **30 file/directory ownership hints per chapter**, **6 evidence paths per detection**, **10 warning details**, and **30 unclassified/sample-omitted paths**. Total counts and truncation flags accompany capped sections. A file has at most one proposed owner; incomplete hints must be expanded or reassigned during review.
+
+On a complete scan, homogeneous subdirectories containing only one candidate’s files may collapse to a directory hint. The repository root, mixed-language directories, directories with unclassified files, nested owners or skipped descendants, and truncated scans retain narrower hints. Directory ownership still requires source review: filenames cannot establish semantic independence. `directoryHints`, `matchedFileCount`, `ownershipCoverage` and `pathsTruncated` distinguish compact directory boundaries from incomplete samples.
+
+`ownershipIncomplete` and `next` prominently flag scan, project or ownership-hint truncation. They do not imply completeness when false: unclassified, excluded and semantically mixed responsibilities still need review. Files covered by directory hints no longer appear as unclassified merely because the returned path list is short.
+
+`coveragePrompts` lists detected delivery-related filenames and asks about versioning, release triggers, build/test artifacts, publication gates and external distribution steps. It never infers release behavior from a filename or creates a fact. A passing registry check remains a mechanical consistency check, not a completeness guarantee.
+
+A separate format-architecture prompt requires three distinct implementation files whose names suggest header validation, node/chunk writing and hierarchy serialization, plus a recognizable format specification document. Directory names alone do not qualify. Up to ten evidence paths retain a representative for each role and the specification. This is a conservative review prompt: the agent must verify the relationships in source, establish usefulness beyond one query, and check existing ownership before proposing an entry. The prompt never creates a navigation entry, fact, chapter or pillar; publication still needs developer direction.
+
+`scan.truncated` reports filesystem scan truncation. `scan.inspectedEntries`, `scan.inspectedFiles` and `scan.manifestBytesRead` describe the work performed. `projectsTruncated`, `detectedProjectCount`, each detection's `pathsTruncated`/`evidenceCount`, and `warningCount` describe output limits. Inspect these fields before claiming the repository has been covered. A successful scan never proves exhaustive coverage; these discovery limits do not cap stored facts or approved projects.
+
+Invalid JSON is reported without aborting the entire bootstrap. Filename/language signals can still yield a coarse candidate. Dynamic JS/TS configuration, imported dependency catalogs, custom project layouts, linked external roots and unsupported ecosystems need source review or additional built-in detection rules. New framework support currently means editing `src/discovery.ts` and adding synthetic regression fixtures; there is no plugin/provider API yet.
+
+## Extending safely
+
+Repository owners can define an approved pillar/chapter for an unsupported technology today. Automatic discovery is a convenience, not a prerequisite for using the framework. For new built-in discovery rules, preserve bounded reads, explicit uncertainty, approval requirements and non-overlapping ownership. Add positive examples alongside false-positive, mixed-monorepo and malformed-input cases. Never populate factual claims from detection labels alone.
+
+C/C++ source extensions and CMake/Meson manifests produce C/C++ responsibility candidates. Root C/C++ signals take precedence over incidental PHP utilities in the same project root; nested manifest roots remain separate candidates. These are heuristics and require boundary review.
+
+### Explicit scan boundaries
+
+Use `cground scan --exclude odd-bundle,tools/generated` (MCP scan `exclude: ["odd-bundle", "tools/generated"]`) for repository-specific literal paths. Exclusions apply before descent, accept trailing slashes, and reject absolute or traversal paths. They apply only to this scan; inspect and use its returned map for bootstrap. They do not change existing chapter ownership or source verification.
+
+Built-in exclusions also cover `dep`, `bundled`, `vendored`, `.vscode`, `.idea`, `.codex`, `.claude` and `.cursor`. Directory-name matching is case-insensitive. `lib` and `libs` remain eligible because they often contain first-party code. Unknown dependency layouts still require explicit exclusions and source review; discovery does not prove authorship. `scan.skipped` reports up to 30 exclusions with reasons and `skippedCount` reports the total. Environment filenames are redacted. Excluded subtrees consume one encountered entry but none of their descendants consume the traversal budget.