@nazty_labs/common-ground 0.5.1

package/dist/discovery.js

@@ -0,0 +1,417 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parse } from 'jsonc-parser';
+import { relativePath } from './model.js';
+const ENTRY_LIMIT = 1500, FILE_BYTES = 256 * 1024, TOTAL_BYTES = 2 * 1024 * 1024, PROJECT_LIMIT = 50;
+const excluded = new Set(['.git', 'node_modules', '.common-ground', 'dist', 'build', 'target', '.nx', '.vite', '.next', '.nuxt', '.svelte-kit', '.angular', '.turbo', '.yarn', '.pnpm-store', '.output', 'coverage',
+    '.vscode', '.idea', '.codex', '.claude', '.cursor', 'dep', 'bundled', 'vendored', 'vendor', 'third_party', 'third-party', 'thirdparty', 'external', 'extern', 'deps', 'dependencies', '.venv', 'venv', '__pycache__', 'pods', 'carthage', '.build', 'deriveddata', '.gradle', '.dart_tool', '.pub-cache', 'bin', 'obj']);
+const inside = (file, root) => root === '.' || file === root || file.startsWith(`${root}/`);
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const markers = /^(CMakeLists\.txt|Makefile|meson\.build|package\.json|angular\.json|project\.json|nx\.json|turbo\.json|lerna\.json|pnpm-workspace\.ya?ml|Package\.swift|project\.pbxproj|pom\.xml|(?:build|settings)\.gradle(?:\.kts)?|AndroidManifest\.xml|go\.(?:mod|work)|pyproject\.toml|requirements(?:[-.][\w-]+)?\.txt|Pipfile|setup\.py|Cargo\.toml|Gemfile|composer\.json|pubspec\.yaml|app\.json|app\.config\.json|.*\.(?:csproj|fsproj|vbproj|sln|slnx))$/;
+const source = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|java|kt|swift|c|cc|cpp|cxx|h|hh|hpp|hxx|m|py|go|rs|cs|fs|vb|rb|php|dart|xml|json|toml|ya?ml|gradle|kts)$/;
+const ci = (file) => /^(?:.*\/)?(?:azure-pipelines[^/]*\.ya?ml|\.gitlab-ci\.ya?ml|Jenkinsfile)$/.test(file) || /(?:^|\/)(?:\.github\/workflows|\.circleci)\/[^/]+\.ya?ml$/.test(file) || /(?:^|\/)pipelines\/.*\.ya?ml$/.test(file);
+const roles = {
+    'ci-cd': ['CI/CD Pipelines', 'Pipeline definitions, templates and execution contracts.'],
+    'workspace-tooling': ['Workspace Tooling', 'Shared workspace configuration and build orchestration.'],
+    'web-components': ['Shared Libraries and Components', 'Reusable library and component contracts shared across applications.'],
+    'web-applications': ['Web Applications', 'Web application structure, routing and runtime contracts.'],
+    'mobile-applications': ['Mobile Applications', 'Mobile application structure and cross-platform runtime contracts.'],
+    'native-applications': ['Native Applications and Packages', 'Native application and package structure and public contracts.'],
+    'cpp-projects': ['C / C++ Projects', 'C and C++ application and library structure, build and runtime contracts.'],
+    'jvm-applications': ['JVM Applications', 'Java and Kotlin project structure, build and runtime contracts.'],
+    'javascript-projects': ['JavaScript / TypeScript Projects', 'JavaScript and TypeScript project structure and runtime contracts.'],
+    'python-projects': ['Python Projects', 'Python application and package structure and runtime contracts.'],
+    'go-projects': ['Go Projects', 'Go module structure and public application or package contracts.'],
+    'rust-projects': ['Rust Projects', 'Rust crate structure and public application or library contracts.'],
+    'dotnet-projects': ['.NET Projects', '.NET project structure, build and runtime contracts.'],
+    'ruby-projects': ['Ruby Projects', 'Ruby application and library structure and runtime contracts.'],
+    'php-projects': ['PHP Projects', 'PHP application and package structure and runtime contracts.'],
+    'dart-projects': ['Dart Projects', 'Dart package structure and runtime contracts.'],
+};
+const npmSignals = { '@angular/core': 'Angular', react: 'React', 'react-native': 'React Native', expo: 'Expo', next: 'Next.js', vue: 'Vue', nuxt: 'Nuxt', svelte: 'Svelte', '@sveltejs/kit': 'SvelteKit', astro: 'Astro', express: 'Express', fastify: 'Fastify', '@nestjs/core': 'NestJS', typescript: 'TypeScript', nx: 'Nx', turbo: 'Turborepo', lerna: 'Lerna' };
+/** Bounded breadth-first discovery keeps deep application trees from starving sibling manifests. */
+async function scanFiles(store, exclude) {
+    const files = [], queue = ['.'], skipped = [], skippedPaths = [];
+    let inspectedEntries = 0, truncated = false;
+    for (let offset = 0; offset < queue.length && !truncated; offset++) {
+        const directory = queue[offset];
+        if (directory !== '.')
+            await store.safe(directory);
+        const children = [];
+        for await (const entry of await fs.opendir(path.join(store.root, directory))) {
+            if (inspectedEntries === ENTRY_LIMIT) {
+                truncated = true;
+                break;
+            }
+            inspectedEntries++;
+            const file = path.posix.join(directory, entry.name);
+            const reason = entry.isSymbolicLink() ? 'symlink' : excluded.has(entry.name.toLowerCase()) || entry.name.startsWith('.env') ? 'dependency, generated output or tool configuration' : exclude.some(p => inside(file, p)) ? 'explicit exclusion' : undefined;
+            if (reason) {
+                skippedPaths.push(file);
+                skipped.push({ path: entry.name.startsWith('.env') ? '[environment file]' : file, reason });
+                continue;
+            }
+            if (entry.isDirectory())
+                children.push(file);
+            else if (entry.isFile())
+                files.push(file);
+        }
+        queue.push(...children.sort((a, b) => {
+            const priority = (p) => /^(src|include|apps|packages|libs|services)(\/|$)/.test(p) ? 0 : 1;
+            return priority(a) - priority(b) || a.localeCompare(b);
+        }));
+    }
+    return { files: files.sort(), inspectedEntries, truncated, skipped: skipped.slice(0, 30), skippedPaths, skippedCount: skipped.length };
+}
+/** Collapse only homogeneous, fully scanned subtrees. Never infer whole-repository ownership. */
+function ownershipHints(files, scan) {
+    const owned = new Set(files), directories = new Set();
+    for (const file of files) {
+        let dir = path.posix.dirname(file);
+        while (dir !== '.') {
+            directories.add(dir);
+            dir = path.posix.dirname(dir);
+        }
+    }
+    const chosen = [];
+    if (!scan.truncated)
+        for (const dir of [...directories].sort((a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b))) {
+            if (dir === '.github' || chosen.some(parent => inside(dir, parent)) || scan.skippedPaths.some(file => inside(file, dir)))
+                continue;
+            const contents = scan.files.filter(file => inside(file, dir));
+            if (contents.some(file => /(^|\/)(tests?|examples?|samples?|bindings|python)\//.test(file.slice(dir.length + 1))))
+                continue;
+            // Mixed source types (for example bindings and a native library) need separate responsibility review.
+            const families = new Set(contents.map(file => /\.(?:c|cc|cpp|cxx|h|hh|hpp|hxx)$/.test(file) ? 'native' : /\.py$/.test(file) ? 'python' : /\.[cm]?[jt]sx?$/.test(file) ? 'javascript' : 'other'));
+            families.delete('other');
+            if (contents.length > 1 && families.size <= 1 && contents.every(file => owned.has(file)))
+                chosen.push(dir);
+        }
+    const paths = [...chosen, ...files.filter(file => !chosen.some(dir => inside(file, dir)))];
+    return { paths: paths.slice(0, 30), directoryHints: chosen.slice(0, 30), truncated: paths.length > 30 };
+}
+/** Require independent implementation signals and a narrowly named specification before raising a review question. */
+function formatArchitecturePrompts(files) {
+    const filenameWords = (file) => path.posix.basename(file, path.posix.extname(file))
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z])([A-Z][a-z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join(' ');
+    const implementations = files.filter(file => /\.(?:[cm]?[jt]sx?|java|kt|swift|c|cc|cpp|cxx|h|hh|hpp|hxx|m|py|go|rs|cs|fs|vb|rb|php|dart)$/i.test(file));
+    const roles = [/\b(?:headers?|validate|validation)\b/, /\b(?:nodes?|chunks?|writer|writing)\b/, /\b(?:hierarchy|hierarchies|serialize|serialization|serializer)\b/]
+        .map(pattern => implementations.filter(file => pattern.test(filenameWords(file))));
+    const specifications = files.filter(file => {
+        if (!/\.(?:md|mdx|rst|txt|adoc|pdf)$/i.test(file))
+            return false;
+        const name = filenameWords(file);
+        return /^(?:(?:file|binary|serialization) )?format(?: spec(?:ification)?)?$/.test(name)
+            || /^(?:spec|specification)$/.test(name) && /^(?:file[-_]?)?format$/i.test(path.posix.basename(path.posix.dirname(file)));
+    });
+    if (!specifications.length || roles.some(paths => !paths.length))
+        return [];
+    // A file with several suggestive words cannot stand in for independent source locations.
+    const distinct = (index, chosen) => {
+        if (index === roles.length)
+            return chosen;
+        for (const file of roles[index])
+            if (!chosen.includes(file)) {
+                const result = distinct(index + 1, [...chosen, file]);
+                if (result)
+                    return result;
+            }
+        return undefined;
+    };
+    const representatives = distinct(0, []);
+    if (!representatives)
+        return [];
+    const paths = [...new Set([...representatives, ...specifications, ...roles.flat()])];
+    return [{ responsibility: 'Format architecture', paths: paths.slice(0, 10), pathCount: paths.length, pathsTruncated: paths.length > 10,
+            questions: ['Do these sources and the specification describe one coherent format contract: header/version validation, node/chunk writing and hierarchy serialization?',
+                'Has navigation to this format repeatedly been needed beyond a single query, and would a small source entry help?',
+                'Can the verified entry fit an existing approved chapter and its ownership boundaries?',
+                'Has the developer directed adding the entry or any required ownership expansion after reviewing the source relationships?'],
+            basis: 'Heuristic review prompt from filenames only; relationships and topic coverage are unverified. No navigation entry, ownership boundary or fact is created.' }];
+}
+export async function discover(store, exclude = []) {
+    exclude = exclude.map(p => relativePath.parse(p));
+    const scan = await scanFiles(store, exclude), projects = new Map(), warnings = [];
+    let manifestBytesRead = 0;
+    const add = (root, technology, evidence, library = false) => {
+        const p = projects.get(root) ?? { root, technologies: new Set(), evidence: new Set(), library: false };
+        p.technologies.add(technology);
+        p.evidence.add(evidence);
+        p.library ||= library;
+        projects.set(root, p);
+        return p;
+    };
+    const warn = (file, reason) => warnings.push({ path: file, reason });
+    const read = async (file) => {
+        const safe = await store.safe(file), stat = await fs.stat(safe);
+        if (stat.size > FILE_BYTES) {
+            warn(file, 'manifest exceeds 256 KiB; content skipped');
+            return undefined;
+        }
+        if (manifestBytesRead + stat.size > TOTAL_BYTES) {
+            warn(file, '2 MiB manifest read budget exhausted');
+            return undefined;
+        }
+        // A bounded buffer also protects against a file growing between stat and read.
+        const handle = await fs.open(safe, 'r');
+        try {
+            const buffer = Buffer.alloc(FILE_BYTES + 1), { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if (bytesRead > FILE_BYTES || manifestBytesRead + bytesRead > TOTAL_BYTES) {
+                warn(file, 'manifest grew beyond read budget; content skipped');
+                return undefined;
+            }
+            manifestBytesRead += bytesRead;
+            return buffer.subarray(0, bytesRead).toString('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    const json = (file, text) => {
+        const errors = [];
+        const data = parse(text, errors, { allowTrailingComma: true });
+        if (errors.length || !object(data)) {
+            warn(file, 'invalid JSON object; content signals skipped');
+            return undefined;
+        }
+        return data;
+    };
+    const manifestFiles = scan.files.filter(f => markers.test(path.posix.basename(f))).sort((a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b));
+    for (const file of manifestFiles) {
+        const name = path.posix.basename(file), root = path.posix.dirname(file), text = await read(file);
+        // Filename signals remain useful even when content is too large or malformed.
+        if (name === 'CMakeLists.txt')
+            add(root, 'CMake', file);
+        if (name === 'meson.build')
+            add(root, 'Meson', file);
+        if (name === 'Package.swift')
+            add(root, 'Swift Package Manager', file);
+        if (name === 'project.pbxproj')
+            add(path.posix.dirname(root), 'Xcode', file);
+        if (name === 'pom.xml')
+            add(root, 'Maven', file);
+        if (/^build\.gradle/.test(name))
+            add(root, 'Gradle', file);
+        if (/^settings\.gradle/.test(name))
+            add(root, 'Gradle Workspace', file);
+        if (name === 'AndroidManifest.xml') {
+            const parts = file.split('/');
+            const src = parts.indexOf('src');
+            add(src >= 0 ? parts.slice(0, src).join('/') || '.' : root, 'Android', file);
+        }
+        if (name === 'go.mod')
+            add(root, 'Go', file);
+        if (name === 'go.work')
+            add(root, 'Go Workspace', file);
+        if (/^(pyproject\.toml|requirements.*\.txt|Pipfile|setup\.py)$/.test(name))
+            add(root, 'Python', file);
+        if (name === 'Cargo.toml')
+            add(root, 'Rust', file);
+        if (/\.(csproj|fsproj|vbproj|sln|slnx)$/.test(name))
+            add(root, '.NET', file);
+        if (name === 'Gemfile')
+            add(root, 'Ruby', file);
+        if (name === 'composer.json')
+            add(root, 'PHP', file);
+        if (name === 'pubspec.yaml')
+            add(root, 'Dart', file);
+        const workspace = { 'nx.json': 'Nx', 'turbo.json': 'Turborepo', 'lerna.json': 'Lerna', 'pnpm-workspace.yaml': 'pnpm Workspaces', 'pnpm-workspace.yml': 'pnpm Workspaces' };
+        if (workspace[name])
+            add(root, workspace[name], file);
+        if (name === 'angular.json')
+            add(root, 'Angular Workspace', file);
+        if (text === undefined)
+            continue;
+        if (name.endsWith('.json')) {
+            const data = json(file, text);
+            if (!data)
+                continue;
+            if (name === 'package.json') {
+                add(root, 'Node.js', file);
+                const deps = new Set(['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'].flatMap(k => object(data[k]) ? Object.keys(data[k]) : []));
+                for (const [dependency, technology] of Object.entries(npmSignals))
+                    if (deps.has(dependency))
+                        add(root, technology, file);
+                if (Array.isArray(data.workspaces) || (object(data.workspaces) && Array.isArray(data.workspaces.packages)))
+                    add(root, 'npm/Yarn Workspaces', file);
+            }
+            if (name === 'angular.json' && object(data.projects))
+                for (const value of Object.values(data.projects)) {
+                    if (!object(value) || typeof value.root !== 'string')
+                        continue;
+                    if (value.root !== '' && value.root !== '.' && !relativePath.safeParse(value.root).success) {
+                        warn(file, 'unsafe Angular project root ignored');
+                        continue;
+                    }
+                    const child = path.posix.join(root, value.root);
+                    if (!scan.files.some(f => inside(f, child))) {
+                        warn(file, 'Angular project root outside scanned files; inspect manually');
+                        continue;
+                    }
+                    add(child, 'Angular', file, value.projectType === 'library');
+                }
+            if (name === 'project.json' && (data.projectType === 'library' || data.projectType === 'application' || object(data.targets))) {
+                add(root, 'Nx Project', file, data.projectType === 'library');
+                const executors = object(data.targets) ? Object.values(data.targets).filter(object).map(t => t.executor ?? t.builder).filter((v) => typeof v === 'string') : [];
+                for (const executor of executors)
+                    for (const [pattern, technology] of [[/^@(?:nx|nrwl)\/angular:|^@angular-devkit\/build-angular:/, 'Angular'], [/^@(?:nx|nrwl)\/next:/, 'Next.js'], [/^@(?:nx|nrwl)\/react-native:/, 'React Native'], [/^@(?:nx|nrwl)\/expo:/, 'Expo'], [/^@(?:nx|nrwl)\/react:/, 'React'], [/^@(?:nx|nrwl)\/vue:/, 'Vue']])
+                        if (pattern.test(executor))
+                            add(root, technology, file);
+            }
+            if ((name === 'app.json' || name === 'app.config.json') && object(data.expo)) {
+                add(root, 'Expo', file);
+                add(root, 'React Native', file);
+            }
+            if (name === 'composer.json' && object(data.require) && Object.hasOwn(data.require, 'laravel/framework'))
+                add(root, 'Laravel', file);
+        }
+        else {
+            // Configs are inspected as text, never evaluated, imported, or passed to package managers.
+            const content = text.replace(/^\s*#.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+            if (/^(?:pom\.xml|(?:build|settings)\.gradle(?:\.kts)?)$/.test(name)) {
+                if (/org\.springframework\.boot/.test(content))
+                    add(root, 'Spring Boot', file);
+                if (/com\.android\.(?:application|library)/.test(content))
+                    add(root, 'Android', file);
+            }
+            if (/^(pyproject\.toml|requirements.*\.txt|Pipfile)$/.test(name))
+                for (const [pattern, label] of [[/\bdjango\b/i, 'Django'], [/\bfastapi\b/i, 'FastAPI'], [/\bflask\b/i, 'Flask']])
+                    if (pattern.test(content))
+                        add(root, label, file);
+            if (name === 'Gemfile' && /\bgem\s*\(?\s*['"]rails['"]/.test(content))
+                add(root, 'Rails', file);
+            if (name === 'pubspec.yaml' && /^\s*flutter\s*:/m.test(content))
+                add(root, 'Flutter', file);
+            if (name === 'Cargo.toml' && /^\s*\[workspace\]\s*$/m.test(content))
+                add(root, 'Cargo Workspace', file);
+        }
+    }
+    const nearest = (file) => [...projects.values()].filter(p => inside(file, p.root)).sort((a, b) => b.root.length - a.root.length)[0];
+    const conventional = (file) => file.match(/^(?:apps|packages|libs|services|projects)\/[^/]+/)?.[0] ?? '.';
+    const language = { '.c': 'C', '.cc': 'C++', '.cpp': 'C++', '.cxx': 'C++', '.hpp': 'C++', '.hxx': 'C++', '.java': 'Java', '.kt': 'Kotlin', '.swift': 'Swift', '.py': 'Python', '.go': 'Go', '.rs': 'Rust', '.cs': '.NET', '.fs': '.NET', '.rb': 'Ruby', '.php': 'PHP', '.dart': 'Dart', '.vue': 'Vue', '.svelte': 'Svelte', '.astro': 'Astro',
+        '.js': 'JavaScript', '.jsx': 'JavaScript', '.mjs': 'JavaScript', '.cjs': 'JavaScript', '.ts': 'TypeScript', '.tsx': 'TypeScript', '.mts': 'TypeScript', '.cts': 'TypeScript' };
+    for (const file of scan.files) {
+        const technology = language[path.posix.extname(file)];
+        if (!technology)
+            continue;
+        const owner = nearest(file);
+        const fallback = conventional(file);
+        // A root workspace manifest must not swallow independent conventional application roots.
+        const root = owner && owner.root !== '.' ? owner.root : fallback;
+        add(root, technology, file);
+    }
+    // Shared UI/library paths are responsibility hints, not proof of React or any other framework.
+    for (const file of scan.files)
+        if (/^(?:packages\/(?:ui|components|shared)|libs\/[^/]+)\/.*\.[cm]?[jt]sx?$/.test(file)) {
+            const root = conventional(file), p = nearest(file);
+            if (!p || p.root === '.' || p.root === root)
+                add(root, 'JavaScript/TypeScript Library', file, true);
+        }
+    // Keep native platform subtrees of React Native/Flutter apps with their owning application.
+    const mobile = [...projects.values()].filter(p => p.technologies.has('React Native') || p.technologies.has('Expo') || p.technologies.has('Flutter')).sort((a, b) => a.root.length - b.root.length);
+    for (const p of [...projects.values()])
+        for (const parent of mobile) {
+            const relative = parent.root === '.' ? p.root : p.root.slice(parent.root.length + 1);
+            if (p !== parent && inside(p.root, parent.root) && /^(ios|android)(\/|$)/.test(relative)) {
+                for (const tech of p.technologies)
+                    parent.technologies.add(tech);
+                for (const evidence of p.evidence)
+                    parent.evidence.add(evidence);
+                projects.delete(p.root);
+                break;
+            }
+        }
+    const role = (p) => {
+        const has = (...names) => names.some(n => p.technologies.has(n));
+        if (has('React Native', 'Expo', 'Flutter'))
+            return 'mobile-applications';
+        if (p.library)
+            return 'web-components';
+        const workspace = has('Nx', 'Turborepo', 'Lerna', 'npm/Yarn Workspaces', 'pnpm Workspaces', 'Angular Workspace', 'Go Workspace', 'Cargo Workspace', 'Gradle Workspace');
+        const children = [...projects.keys()].some(root => root !== p.root && inside(root, p.root));
+        const ownSource = [...p.evidence].some(file => {
+            const relative = p.root === '.' ? file : file.slice(p.root.length + 1);
+            return source.test(file) && (/^(src|app|pages)\//.test(relative) || /^(App|index)\.[jt]sx?$/.test(relative));
+        });
+        if (workspace && children && !ownSource)
+            return 'workspace-tooling';
+        if (has('Angular', 'React', 'Next.js', 'Vue', 'Nuxt', 'Svelte', 'SvelteKit', 'Astro'))
+            return 'web-applications';
+        if (has('Android'))
+            return 'mobile-applications';
+        if (has('Swift', 'Swift Package Manager', 'Xcode'))
+            return 'native-applications';
+        if (has('Java', 'Kotlin', 'Maven', 'Gradle', 'Spring Boot'))
+            return 'jvm-applications';
+        if (has('C', 'C++', 'CMake', 'Meson'))
+            return 'cpp-projects';
+        for (const [tech, key] of [['Python', 'python'], ['Go', 'go'], ['.NET', 'dotnet'], ['Rust', 'rust'], ['Ruby', 'ruby'], ['PHP', 'php'], ['Dart', 'dart']])
+            if (has(tech))
+                return `${key}-projects`;
+        if (workspace)
+            return 'workspace-tooling';
+        return 'javascript-projects';
+    };
+    const groups = new Map();
+    const ordered = [...projects.values()].sort((a, b) => b.root.length - a.root.length || a.root.localeCompare(b.root));
+    for (const file of scan.files) {
+        if (ci(file)) {
+            const key = 'ci-cd', g = groups.get(key) ?? { project: { root: '.', technologies: new Set(['CI/CD']), evidence: new Set(), library: false }, files: [] };
+            g.files.push(file);
+            g.project.evidence.add(file);
+            groups.set(key, g);
+            continue;
+        }
+        if (!source.test(file) && !markers.test(path.posix.basename(file)))
+            continue;
+        const p = ordered.find(p => inside(file, p.root));
+        if (!p)
+            continue;
+        const key = `${role(p)}:${p.root}`, g = groups.get(key) ?? { project: p, files: [] };
+        g.files.push(file);
+        groups.set(key, g);
+    }
+    const definitions = [], detections = [], selected = new Set();
+    const candidates = [...groups].sort(([a], [b]) => a.localeCompare(b));
+    for (const [group, { project: p, files }] of candidates.slice(0, PROJECT_LIMIT)) {
+        const id = group === 'ci-cd' ? group : role(p), [title, scope] = roles[id];
+        let pillar = definitions.find(d => d.id === id);
+        if (!pillar) {
+            pillar = { id, title, scope, excludes: 'Responsibilities owned by other approved pillars.', chapters: [] };
+            definitions.push(pillar);
+        }
+        const chapterId = p.root === '.' ? 'overview' : `${p.root.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'project'}-${createHash('sha256').update(p.root).digest('hex').slice(0, 8)}`;
+        const hints = ownershipHints([...files].sort((a, b) => Number(p.evidence.has(b)) - Number(p.evidence.has(a)) || a.localeCompare(b)), scan), paths = hints.paths;
+        for (const file of scan.files)
+            if (paths.some(scope => inside(file, scope)))
+                selected.add(file);
+        pillar.chapters.push({ id: chapterId, title: p.root === '.' ? 'Overview' : `Project ${p.root}`.slice(0, 100), scope, excludes: 'Unrelated projects and other pillar responsibilities.', paths });
+        detections.push({ root: p.root, technologies: [...p.technologies].sort(), evidence: [...p.evidence].sort().slice(0, 6), evidenceCount: p.evidence.size,
+            chapterId: `${id}/${chapterId}`, pathHintCount: paths.length, pathsTruncated: hints.truncated, matchedFileCount: files.length,
+            ownershipCoverage: scan.truncated || hints.truncated ? 'incomplete' : 'scanned-files', directoryHints: hints.directoryHints,
+            rationale: `${title} is a coarse candidate from ${[...p.technologies].sort().join(', ')} signals at ${p.root}. Inspect source to separate runtime, interfaces, tests, examples and delivery responsibilities; technology labels do not establish ownership.` });
+    }
+    const responsibilityHints = [
+        { responsibility: 'Native library or application', pattern: /(^|\/)(cpp|include|native)(\/|$)/ },
+        { responsibility: 'Python interface or application', pattern: /(^|\/)(python|bindings)(\/|$)/ },
+        { responsibility: 'Test validation and fixtures', pattern: /(^|\/)(tests?|testing)(\/|$)/ },
+        { responsibility: 'Usage examples', pattern: /(^|\/)(examples?|samples?)(\/|$)/ },
+        { responsibility: 'Build and delivery', pattern: /(^|\/)(CMakeLists\.txt|pyproject\.toml|package\.json|\.release-it\.[^/]+)$|(^|\/)\.github\/workflows\// },
+    ].flatMap(({ responsibility, pattern }) => {
+        const paths = scan.files.filter(file => pattern.test(file));
+        return paths.length ? [{ responsibility, paths: paths.slice(0, 6), pathCount: paths.length, pathsTruncated: paths.length > 6,
+                rationale: 'Path conventions suggest a responsibility to review, not an approved boundary or a factual claim.' }] : [];
+    });
+    const deliveryFiles = scan.files.filter(file => ci(file) || /(^|\/)(package\.json|pyproject\.toml|setup\.py|CMakeLists\.txt|\.release-it\.[^/]+)$/.test(file));
+    const ownershipIncomplete = scan.truncated || candidates.length > PROJECT_LIMIT || detections.some(d => d.pathsTruncated);
+    return { schemaVersion: 2, requiresDeveloperApproval: true, scan: { inspectedFiles: scan.files.length, inspectedEntries: scan.inspectedEntries, truncated: scan.truncated, limit: ENTRY_LIMIT, excludedPaths: exclude, skipped: scan.skipped, skippedCount: scan.skippedCount, manifestBytesRead, manifestByteLimit: TOTAL_BYTES },
+        pillars: definitions, detections, detectedProjectCount: candidates.length, projectsTruncated: candidates.length > PROJECT_LIMIT,
+        responsibilityHints, ownershipIncomplete,
+        next: ownershipIncomplete ? 'Ownership hints are incomplete. Inspect omitted files and truncated trees, then expand or split boundaries before bootstrap. Do not publish the sampled map as complete.' : 'Review suggested responsibilities and directory boundaries against source, including unclassified and excluded areas, before bootstrap.',
+        coveragePrompts: [...(deliveryFiles.length ? [{ responsibility: 'Build and delivery', paths: deliveryFiles.slice(0, 10), pathCount: deliveryFiles.length, pathsTruncated: deliveryFiles.length > 10,
+                    questions: ['How are versions chosen and releases triggered?', 'Which jobs build and test each artifact?', 'Where are artifacts published, and what gates publication?', 'Which distribution steps are external or not established by inspected source?'],
+                    basis: 'Review prompts from detected filenames; validation does not establish completeness.' }] : []), ...formatArchitecturePrompts(scan.files)],
+        warnings: warnings.slice(0, 10), warningCount: warnings.length, unclassifiedSample: scan.files.filter(f => !selected.has(f)).slice(0, 30),
+        note: 'Heuristic candidates only. Frameworks are navigation signals, not facts or automatic pillar boundaries. Review and merge responsibility boundaries, expand sampled paths, and inspect unclassified or truncated areas. No facts or dependencies have been inferred.' };
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+/** Stable CLI error envelope. Unclassified domain failures use OPERATION_FAILED. */
+export declare class GroundError extends Error {
+    code: string;
+    fields: string[];
+    recovery: string;
+    details?: unknown | undefined;
+    constructor(code: string, message: string, fields?: string[], recovery?: string, details?: unknown | undefined);
+}
+export declare function errorPayload(error: unknown): {
+    details?: {} | undefined;
+    code: string;
+    message: string;
+    fields: string[];
+    recovery: string;
+};

package/dist/errors.js

@@ -0,0 +1,22 @@
+/** Stable CLI error envelope. Unclassified domain failures use OPERATION_FAILED. */
+export class GroundError extends Error {
+    code;
+    fields;
+    recovery;
+    details;
+    constructor(code, message, fields = [], recovery = 'Inspect the command help and correct the request.', details) {
+        super(message);
+        this.code = code;
+        this.fields = fields;
+        this.recovery = recovery;
+        this.details = details;
+    }
+}
+export function errorPayload(error) {
+    const value = error;
+    if (error instanceof GroundError)
+        return { code: error.code, message: error.message, fields: error.fields, recovery: error.recovery, ...(error.details ? { details: error.details } : {}) };
+    if (Array.isArray(value.issues))
+        return { code: 'INVALID_INPUT', message: value.issues.map(i => `${i.path.join('.') || 'input'}: ${i.message}`).join('; '), fields: [...new Set(value.issues.map(i => i.path.join('.') || 'input'))], recovery: 'Inspect cground schema <operation> and correct the affected fields.' };
+    return { code: value.code ?? 'OPERATION_FAILED', message: value.message ?? String(error), fields: value.fields ?? (value.path ? [value.path] : []), recovery: value.recovery ?? 'Inspect cground <command> --help and correct the request.' };
+}

package/dist/export.d.ts

@@ -0,0 +1,14 @@
+import type { Store } from './store.js';
+import type { RegistryRecord } from './model.js';
+export declare const markdownPath = ".common-ground/local/knowledge.md";
+/** Complete, deterministic view of shared knowledge; no timestamps or local drafts. */
+export declare function renderKnowledge(registry: RegistryRecord | null): string;
+/** Caller holds the store writer lock when publishing shared records. */
+export declare function writeKnowledgeExport(store: Store, registry: RegistryRecord | null): Promise<{
+    path: string;
+    changed: boolean;
+}>;
+export declare function refreshKnowledgeExport(store: Store): Promise<{
+    path: string;
+    changed: boolean;
+}>;

package/dist/export.js

@@ -0,0 +1,86 @@
+import { promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+export const markdownPath = '.common-ground/local/knowledge.md';
+const localName = 'local/knowledge.md';
+const text = (value) => value.replace(/[\\`*_[\]<>#|]/g, '\\$&');
+const paragraph = (value) => text(value).replace(/\r?\n/g, '\n\n');
+const sourceLink = (file) => `[${text(file)}](../../${file.split('/').map(part => encodeURIComponent(part).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)).join('/')})`;
+const factLink = (key) => `[${text(key)}](#fact-${key})`;
+function quote(value) {
+    const fence = '`'.repeat(Math.max(3, ...[...value.matchAll(/`+/g)].map(m => m[0].length + 1)));
+    return `${fence}text\n${value}\n${fence}`;
+}
+/** Complete, deterministic view of shared knowledge; no timestamps or local drafts. */
+export function renderKnowledge(registry) {
+    const lines = ['# Common Ground knowledge', '',
+        'Generated from [knowledge.json](../knowledge.json). This local file is disposable; edit the shared registry through the reviewed knowledge workflow.', '',
+        'This is a snapshot of stored knowledge, not proof that every assertion is currently true. Verify current source and run `cground validate` before relying on it.', ''];
+    if (!registry)
+        return [...lines, '## No approved knowledge yet', '',
+            'Review the [proposed responsibility map](bootstrap.json) with your developer. After approval and fact population, this file will contain the complete shared knowledge.', ''].join('\n');
+    const chapters = registry.pillars.flatMap(p => p.chapters);
+    lines.push(`Schema version: ${registry.schemaVersion}. Pillars: ${registry.pillars.length}. Chapters: ${chapters.length}. Facts: ${chapters.reduce((n, c) => n + c.facts.length, 0)}.`, '', `Registry fingerprint (SHA-256): ${createHash('sha256').update(JSON.stringify(registry)).digest('hex')}`, '', '## Contents', '');
+    if (!registry.pillars.length)
+        lines.push('No pillars have been recorded.', '');
+    for (const p of registry.pillars) {
+        lines.push(`- [${text(p.title)}](#pillar-${p.id})`);
+        for (const c of p.chapters)
+            lines.push(`  - [${text(c.title)}](#chapter-${p.id}/${c.id}) — ${c.facts.length} facts`);
+    }
+    lines.push('');
+    for (const p of registry.pillars) {
+        lines.push(`<a id="pillar-${p.id}"></a>`, '', `## ${text(p.title)}`, '', `**Pillar ID:** ${p.id}`, '', `**Scope:** ${paragraph(p.scope)}`, '', `**Excludes:** ${paragraph(p.excludes)}`, '');
+        for (const c of p.chapters) {
+            const key = `${p.id}/${c.id}`;
+            lines.push(`<a id="chapter-${key}"></a>`, '', `### ${text(c.title)}`, '', `**Chapter ID:** ${key} · **Revision:** ${c.revision}`, '', `**Scope:** ${paragraph(c.scope)}`, '', `**Excludes:** ${paragraph(c.excludes)}`, '', '**Owned paths**', '', ...c.paths.map(file => `- ${sourceLink(file)}`), '');
+            if (!c.facts.length)
+                lines.push('No facts recorded in this chapter.', '');
+            for (const f of c.facts) {
+                const factKey = `${key}/${f.id}`;
+                lines.push(`<a id="fact-${factKey}"></a>`, '', `#### ${f.id}`, '', paragraph(f.statement), '', `**Fact ID:** ${factKey}`, '', '**Source scope**', '', ...f.sourceScope.map(file => `- ${sourceLink(file)}`), '', '**Depends on**', '', ...(f.dependsOn.length ? f.dependsOn.map(dep => `- ${factLink(dep)}`) : ['None.']), '', '**Evidence**', '');
+                for (const e of f.evidence)
+                    lines.push(sourceLink(e.path), '', quote(e.quote), '');
+            }
+            // Preserve every stored baseline without burying the prose in machine metadata.
+            lines.push('<details>', '<summary>Stored source hashes and dependency fingerprints</summary>', '', '**Source hashes**', '', '| Source | SHA-256 |', '| --- | --- |', ...Object.entries(c.sources).sort(([a], [b]) => a.localeCompare(b)).map(([file, hash]) => `| ${sourceLink(file)} | ${text(hash)} |`), '', '**Dependency fingerprints**', '', '| Fact | Fingerprint |', '| --- | --- |', ...Object.entries(c.dependencyFingerprints).sort(([a], [b]) => a.localeCompare(b)).map(([dep, hash]) => `| ${factLink(dep)} | ${text(hash)} |`), '', '</details>', '');
+        }
+    }
+    return lines.join('\n');
+}
+/** Caller holds the store writer lock when publishing shared records. */
+export async function writeKnowledgeExport(store, registry) {
+    const content = renderKnowledge(registry);
+    await store.safe(markdownPath, true);
+    try {
+        if (await fs.readFile(store.file(localName), 'utf8') === content)
+            return { path: markdownPath, changed: false };
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    await fs.mkdir(store.file('local'), { recursive: true });
+    const temporary = store.file(`${localName}.${randomUUID()}.tmp`);
+    try {
+        await fs.writeFile(temporary, content, { flag: 'wx' });
+        await fs.rename(temporary, store.file(localName));
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+    return { path: markdownPath, changed: true };
+}
+export async function refreshKnowledgeExport(store) {
+    return store.lock(async () => {
+        let registry;
+        try {
+            registry = await store.read();
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+            registry = null;
+        }
+        return writeKnowledgeExport(store, registry);
+    });
+}

package/dist/guidance.d.ts

@@ -0,0 +1,11 @@
+export declare const bootstrapNext: {
+    action: string;
+    approvalRequired: boolean;
+    command: string;
+    schema: string;
+    guide: string;
+    authorization: string;
+};
+export declare const rules = "## Common Ground\n\nCode is the source of truth; these notes only help navigation.\n\nFor repository questions, use cground lookup with a path or short query for facts and source locations. Lookup is stateless; default freshness is not checked. Open source and directory READMEs before relying on claims. Use --verify when live freshness matters. Derive temporary state live.\n\nKeep the developer task primary. After edits, cground assess --touched checks only this task's actual paths, including additions/deletions. No matching source change means no fact review or task bookkeeping; still review relevant local documentation. Source drift means check the affected claims, not automatic revision. Follow additional semantic connections found in source.\n\nIf corrections are needed, request assess --review. Before editing, read [.common-ground/POLICY.md](.common-ground/POLICY.md), every required chapter page and the listed sources/docs. prepare-patch works without taskId; complete review and conflict checks remain mandatory. Summarize actual corrections as before \u2192 after, why, source links and recommendation.\n\nTask contexts are optional for aggregated reporting and deferred additions. Start one when needed; propose_facts queues drafts, finish after the main task, then ask \"Ready to make the following facts available to the team?\" New facts, chapters, pillars and ownership expansion need developer direction. If started, finish the task once; reuse cached responses only within it and refresh:true after context loss.\n\nDefault to no write. Keep durable patterns, not debugging history; library-local detail belongs in its README. Resolve disputed behavior with the developer. No change means no Common Ground report. Setup: [.common-ground/START_HERE.md](.common-ground/START_HERE.md).\n";
+export declare const policy = "## Common Ground\n\nCode is the source of truth. Notes cache durable repository knowledge; matching quotes and hashes establish mechanical consistency, not semantic truth.\n\n### Reading and writing invariants\n\n- Open relevant source and directory, ancestor, sibling, child and referenced documentation this session. Derive temporary state live. Do not record bugs, debugging history, activity logs, secrets or guesses.\n- Default to no write. Unrelated work and unchanged facts produce no shared knowledge changes. Library-local detail belongs in its README. Each fact holds one coherent, source-backed claim of at most 2,000 characters.\n- Review every existing fact in each required logical chapter before revision. Follow dependency and dependent links, request the review checklist, and verify all required source and documentation. A verification declaration does not prove an agent read or understood a file.\n- Correct verified contradictions in the affected scope quietly, preserving IDs. Merge duplicates and remove superseded claims with explicit reasons and repaired references. Never clean up unrelated responsibilities. Ask if uncertainty blocks the task; otherwise collect it for completion.\n- New facts, chapters, pillars and ownership expansion require developer direction. A new pillar also needs an uncovered standalone responsibility. Approval flags declare developer direction; they never grant autonomous permission or prove human review. Boundary approval does not approve facts. For initial setup, explicit delegation to save/publish may cover verified boundaries and facts within the requested scope; see START_HERE.md. Routine additions still follow the deferred approval workflow below.\n- Chapter paths define non-overlapping ownership. Fact source scopes stay inside ownership; supporting evidence may cite other repository files and is tracked for freshness. Exact evidence, safe paths and valid dependencies remain mandatory.\n- Publish a complete reviewed transaction. Source or registry conflicts reject publication. Unchanged reviews use ignored local receipts; only changed chapters are rewritten. Never bypass required tests based on notes.\n\n### Quiet task workflow\n\nUse stateless lookup for relevant facts and source paths; default freshness is not checked. After edits, assess actual task-touched paths (including additions and deletions). A matching unchanged source requires no fact review; changed source requires checking affected claims, not automatic revision. Review local/ancestor documentation relevant to the edit and follow semantic connections found in source. Empty touched paths require no review. Use assess --review when a correction needs complete chapters and verification paths. Neither command creates task state or requires finish.\n\nBefore correcting notes, read this policy and every page of all required chapters. prepare_patch attests reviewedAllFacts:true and the expected revision, then retains unchanged facts. Use prepare_patch without taskId and commit_update for verified corrections. Task contexts remain optional for aggregate reporting and deferred additions. Source or revision conflicts require fresh review. Citation-only repairs may use empty touchedPaths without a tidyId: only evidence may change; the fact ID, statement, sourceScope and dependsOn must remain unchanged. Supply a verified reason, read every required chapter, attest source/documentation verification and the expected revisions. Publication rechecks source and registry conflicts. Use review-plan and review-checklist for the selected chapter; do not invent touched paths.\n\nFor new facts, start a task when needed and queue them with propose_facts; pending drafts are never authoritative. Finish the developer task and checks, then finish any task context you started. Reuse cached task responses only within that task; refresh:true after context loss. Summarize actual corrections as before \u2192 after, why, source links and keep/reverify recommendation. Present additions together and ask \"Ready to make the following facts available to the team?\" Wait for explicit approval, read proposal-review and required chapters/source, then accept-facts with complete reviews and verification. Drop rejected entries first. Changed drafts need fresh verification and approval. Never require developer JSON review. With no changes or pending questions, give no Common Ground report.\n\nUse tidy only for developer-requested cleanup. It returns a local tidyId; the calling agent reads source and submits verified corrections. Common Ground runs no model or autonomous watcher. If unavailable, continue safe task work and report unresolved maintenance; never claim a failed write succeeded. Host tool approval settings remain authoritative.\n\nSee START_HERE.md for commands and state-specific setup. Keep knowledge.json and managed guidance tracked; local/ is disposable and ignored. Never remove another active task's files.\n";
+export declare const startGuide = "# Start Here \u2014 Common Ground\n\nCommon Ground is a framework for shared, Git-backed repository knowledge. Its interfaces are the CLI and local MCP server. Code is the source of truth.\n\n## Initial setup: draft, verify, publish\n\n1. Run cground init. It creates guidance, MCP configuration and a local candidate map without creating knowledge.json. Use --skip-hook if Git metadata is protected; hook permission failures are advisory and setup continues. The setup report lists completed, skipped, failed and pending steps. Retry safely after fixing a failure; existing registries and bootstrap drafts are preserved. Install the reminder later with cground hook install.\n2. Read source and directory READMEs. Refine .common-ground/local/bootstrap.json into responsibility boundaries and verified facts. detections are raw technology/path signals; responsibilityHints and directory paths are suggestions. Inspect ownershipIncomplete, pathsTruncated, scan.truncated and unclassified samples. Expand or split incomplete boundaries. Follow coveragePrompts for release triggers, versioning, artifacts and publication where detected. Validity and unchanged evidence do not establish complete coverage.\n3. Use cground schema bootstrap and cground bootstrap --help --example. Prepare pillars plus batches of chapterId/facts, then run cground bootstrap PLAN.json --dry-run. This validates the whole transaction without writes and returns source-file counts and a preflight token. JSON commands also accept --stdin.\n4. Establish publication direction from the developer's request. \u201CInitialize\u201D or \u201Cgenerate a map\u201D means draft by default. \u201CInitialize and save/publish the map autonomously\u201D explicitly delegates publication of verified initial boundaries and facts within that scope. Honor an existing delegation without asking again. Otherwise present the exact boundaries and facts in plain language and ask \u201CReady to make the following facts available to the team?\u201D Wait for approval before publication. A draft-only request never authorizes publication; boundary-only approval never approves facts.\n5. With publication direction, apply the same payload using --approve --preflight TOKEN, run cground check, and summarize what was saved with source links and remaining coverage gaps. Source or payload changes require a fresh dry run and verification; confirm they remain within any delegated scope, or obtain new content approval. Flags declare direction and tokens detect changes; neither proves human review, identity, semantic truth or completeness. Host tool approval settings still apply.\n\nThe bootstrap path above is self-contained for an empty registry. Before revising existing knowledge, read [POLICY.md](POLICY.md) and every required chapter/source page. For separate setup stages, cground approve creates boundaries only; seed-batch --dry-run and seed-batch --approve --preflight TOKEN populate approved empty chapters with authorized facts. Use command help for exact inputs.\n\nA bootstrap-required or not-initialized response has no taskId. Continue the developer task from source. Never fabricate an empty registry or call task assess/propose/finish without a returned taskId. After setup, use lookup; task contexts are optional for deferred additions or aggregate reporting.\n\n## My build failed. Where do I go?\n\nFollow AGENTS.md for lookup and task-touched assessment. Lookup navigation contains separately labeled ownership/source hints, not facts; freshness is not checked by default. Read source when matches only partly cover a question. --verify checks selected facts and dependencies, not topic completeness or navigation hints.\n\nFor corrections, assess --review supplies complete chapters and verification paths. Read POLICY.md and every required page before prepare-patch and commit. For deferred additions and task reporting, POLICY.md describes the task_context workflow.\n\n## Setup and review commands\n\n- cground doctor checks setup; cground refresh-guidance updates managed instructions while preserving surrounding text. A healthy check returns next: null.\n- cground check [TARGET] validates structure, exact evidence and freshness. --all-results includes passing rows; follow nextCursor. --cleanup y creates a developer-requested cleanup plan, not a completed repair.\n- cground review [TARGET] summarizes changes against HEAD. --staged selects the index; --evidence includes changed quotations. Explain before \u2192 after, why, sources and a keep/approve/reverify recommendation.\n- cground export refreshes [local/knowledge.md](local/knowledge.md), the ignored reference excluding drafts. Successful knowledge writes refresh it too.\n- cground hook mute/unmute controls advisory reminders. Existing hook managers can call cground hook check.\n\nEvery command has --help. cground schema OPERATION gives CLI payloads; --both adds MCP arguments. Both MCP profiles expose these workflows through cground. Keep knowledge.json and managed guidance tracked; local/ is ignored. See POLICY.md for maintenance invariants and the framework's docs/pillar-contract.md and docs/quiet-workflow.md for full contracts.\n";