@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/smiths/context-pipeline/workspace-context.js

@@ -0,0 +1,988 @@
+/**
+ * Canonical cross-provider workspace context graph (#1811).
+ *
+ * WORKSPACE.md owns provider-neutral project/operator context. Provider startup
+ * files are compiled adapters that load or explicitly direct the harness to
+ * WORKSPACE.md first and AIWG.md second. Existing layouts remain readable until
+ * an operator runs the explicit migration workflow.
+ */
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { buildAiwgMdContent } from './aiwg-md.js';
+import { buildNormalizedAiwgMd } from './finalization.js';
+import { getProviderDefinition, listProviderDefinitions, } from '../../providers/provider-definitions.js';
+import { projectAiwgPath, resolveProjectAiwgDir } from '../../config/project-artifacts.js';
+export const WORKSPACE_MANAGED_START = '<!-- AIWG:workspace-context:start -->';
+export const WORKSPACE_MANAGED_END = '<!-- AIWG:workspace-context:end -->';
+export const WORKSPACE_OPERATOR_START = '<!-- AIWG:workspace-operator:start -->';
+export const WORKSPACE_OPERATOR_END = '<!-- AIWG:workspace-operator:end -->';
+export const PROJECT_EXTRACTION_START = '<!-- AIWG:project-extraction:start -->';
+export const PROJECT_EXTRACTION_END = '<!-- AIWG:project-extraction:end -->';
+export const PROVIDER_BOOTSTRAP_START = '<!-- AIWG:provider-bootstrap:start -->';
+export const PROVIDER_BOOTSTRAP_END = '<!-- AIWG:provider-bootstrap:end -->';
+export const WORKSPACE_SIGNATURE = '<!-- aiwg-managed -->';
+const LEGACY_ROOT_FILES = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    'AGENTS.override.md',
+    'WARP.md',
+    '.hermes.md',
+    '.github/copilot-instructions.md',
+    'AIWG.md',
+];
+const GENERATED_BLOCKS = [
+    [PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END],
+    ['<!-- AIWG:context-hook:start -->', '<!-- AIWG:context-hook:end -->'],
+    ['<!-- AIWG:claude-md-hook:start -->', '<!-- AIWG:claude-md-hook:end -->'],
+    ['<!-- BEGIN AIWG -->', '<!-- END AIWG -->'],
+    [WORKSPACE_MANAGED_START, WORKSPACE_MANAGED_END],
+    ['<!-- spillover-from-AGENTS.md:START -->', '<!-- spillover-from-AGENTS.md:END -->'],
+];
+const PROJECT_CONTEXT_PLACEHOLDER = [
+    '## Project Context',
+    '',
+    'Add project conventions, local hook/context pointers, and links to deeper project documents here.',
+].join('\n');
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+async function readOptional(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function atomicWrite(filePath, content) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp.${process.pid}`);
+    await fs.writeFile(temporary, content, 'utf8');
+    try {
+        await fs.rename(temporary, filePath);
+    }
+    catch (error) {
+        await fs.rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function resolveProjectRelative(projectPath, relativePath) {
+    if (path.isAbsolute(relativePath))
+        throw new Error(`Unsafe absolute migration path: ${relativePath}`);
+    const root = path.resolve(projectPath);
+    const resolved = path.resolve(root, relativePath);
+    const artifactRoot = path.resolve(resolveProjectAiwgDir(projectPath));
+    const insideProject = resolved === root || resolved.startsWith(`${root}${path.sep}`);
+    const insideArtifactRoot = resolved === artifactRoot || resolved.startsWith(`${artifactRoot}${path.sep}`);
+    if (!insideProject && !insideArtifactRoot) {
+        throw new Error(`Unsafe migration path outside project: ${relativePath}`);
+    }
+    return resolved;
+}
+function replaceBlock(content, start, end, block) {
+    const startIndex = content.indexOf(start);
+    const endIndex = content.indexOf(end);
+    if (startIndex < 0 && endIndex < 0)
+        return null;
+    if (startIndex < 0 || endIndex < startIndex)
+        throw new Error(`Malformed managed block: ${start} / ${end}`);
+    return content.slice(0, startIndex) + block + content.slice(endIndex + end.length);
+}
+function stripGeneratedBlocks(content) {
+    let stripped = content;
+    for (const [start, end] of GENERATED_BLOCKS) {
+        while (stripped.includes(start) || stripped.includes(end)) {
+            const replaced = replaceBlock(stripped, start, end, '');
+            if (replaced === null)
+                break;
+            stripped = replaced;
+        }
+    }
+    return stripped
+        .replace(/^<!-- aiwg-managed -->\s*$/gm, '')
+        .replace(/^<!-- Generated by AIWG[^\n]*-->\s*$/gm, '')
+        .trim();
+}
+function isGeneratedRootContext(relativePath, content) {
+    if (content.includes(WORKSPACE_SIGNATURE))
+        return true;
+    const head = content.split('\n').slice(0, 12).join('\n');
+    if (/<!--\s*Generated by\s+(?:AIWG|aiwg)(?:\s+use)?\b[^>]*-->/i.test(head))
+        return true;
+    return relativePath === 'AIWG.md' && /^# AIWG Framework Context\b/m.test(head);
+}
+function cleanInlineMarkdown(value) {
+    return value
+        .replace(/<!--.*?-->/g, ' ')
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+        .replace(/[`*_~#|]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function truncateAtWord(value, limit) {
+    if (value.length <= limit)
+        return value;
+    const candidate = value.slice(0, limit + 1);
+    const boundary = candidate.lastIndexOf(' ');
+    return `${candidate.slice(0, boundary > Math.floor(limit * 0.7) ? boundary : limit).trimEnd()}…`;
+}
+function projectLink(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/');
+    return `[\`${normalized}\`](./${normalized})`;
+}
+async function firstReadmePurpose(projectPath) {
+    for (const source of ['README.md', 'README.mdx', 'README.rst', 'README.txt']) {
+        const content = await readOptional(path.join(projectPath, source));
+        if (!content || isGeneratedRootContext(source, content))
+            continue;
+        const blocks = content.replace(/\r\n/g, '\n').split(/\n\s*\n/);
+        for (const block of blocks) {
+            const lines = block.split('\n').filter((line) => {
+                const trimmed = line.trim();
+                return trimmed
+                    && !trimmed.startsWith('#')
+                    && !trimmed.startsWith('![')
+                    && !trimmed.startsWith('[![')
+                    && !trimmed.startsWith('<')
+                    && !/^[-*+]\s/.test(trimmed)
+                    && !/^```/.test(trimmed);
+            });
+            const purpose = cleanInlineMarkdown(lines.join(' ')).slice(0, 360).trim();
+            if (purpose.length >= 24)
+                return { source, purpose };
+        }
+    }
+    return null;
+}
+async function existingPaths(projectPath, candidates) {
+    const found = [];
+    for (const candidate of candidates) {
+        try {
+            await fs.access(path.join(projectPath, candidate));
+            found.push(candidate);
+        }
+        catch {
+            // Optional project evidence.
+        }
+    }
+    return found;
+}
+async function workflowFiles(projectPath) {
+    const files = [];
+    for (const directory of ['.gitea/workflows', '.github/workflows']) {
+        let entries;
+        try {
+            entries = await fs.readdir(path.join(projectPath, directory), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isFile() && /^[A-Za-z0-9._-]+\.ya?ml$/i.test(entry.name))
+                files.push(`${directory}/${entry.name}`);
+        }
+    }
+    return files.sort((left, right) => left.localeCompare(right));
+}
+export async function extractExistingProjectContext(projectPath) {
+    const lines = [
+        PROJECT_EXTRACTION_START,
+        '',
+        '## Existing Project Snapshot',
+        '',
+        '<!-- Generated from stable project metadata. Edit the linked sources, not this block. -->',
+    ];
+    const sources = new Set();
+    let sensitiveFindings = [];
+    const packageContent = await readOptional(path.join(projectPath, 'package.json'));
+    if (packageContent) {
+        try {
+            const manifest = JSON.parse(packageContent);
+            const facts = [];
+            if (typeof manifest.name === 'string' && manifest.name.trim())
+                facts.push(`- Name: \`${cleanInlineMarkdown(manifest.name).slice(0, 120)}\``);
+            if (typeof manifest.description === 'string' && manifest.description.trim()) {
+                facts.push(`- Description: ${truncateAtWord(cleanInlineMarkdown(manifest.description), 360)}`);
+            }
+            if (typeof manifest.packageManager === 'string' && manifest.packageManager.trim()) {
+                facts.push(`- Package manager: \`${cleanInlineMarkdown(manifest.packageManager).slice(0, 120)}\``);
+            }
+            if (manifest.engines && typeof manifest.engines === 'object' && !Array.isArray(manifest.engines)) {
+                const engines = Object.entries(manifest.engines)
+                    .filter((entry) => typeof entry[1] === 'string')
+                    .sort(([left], [right]) => left.localeCompare(right))
+                    .map(([name, constraint]) => `${name} ${cleanInlineMarkdown(constraint).slice(0, 80)}`);
+                if (engines.length)
+                    facts.push(`- Runtime: ${engines.map((engine) => `\`${engine}\``).join(', ')}`);
+            }
+            if (facts.length) {
+                lines.push('', `### Package (source: ${projectLink('package.json')})`, '', ...facts);
+                sources.add('package.json');
+            }
+            if (manifest.scripts && typeof manifest.scripts === 'object' && !Array.isArray(manifest.scripts)) {
+                const preferred = ['build', 'test', 'lint', 'typecheck', 'check', 'start', 'dev'];
+                const available = preferred.filter((name) => typeof manifest.scripts[name] === 'string');
+                if (available.length) {
+                    lines.push('', `### Common Commands (source: ${projectLink('package.json')})`, '', ...available.map((name) => `- \`npm run ${name}\``));
+                    sources.add('package.json');
+                }
+            }
+        }
+        catch {
+            // Invalid package metadata remains the owning tool's concern; extraction skips it.
+        }
+    }
+    const readme = await firstReadmePurpose(projectPath);
+    if (readme) {
+        lines.push('', `### Purpose (source: ${projectLink(readme.source)})`, '', readme.purpose);
+        sources.add(readme.source);
+    }
+    const stackSignals = await existingPaths(projectPath, [
+        'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb',
+        'tsconfig.json', 'deno.json', 'deno.jsonc', 'pyproject.toml', 'requirements.txt',
+        'Pipfile', 'poetry.lock', 'Cargo.toml', 'Cargo.lock', 'go.mod', 'Gemfile',
+        'composer.json', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'Makefile',
+    ]);
+    if (stackSignals.length) {
+        lines.push('', '### Stack and Tooling', '', ...stackSignals.map((source) => `- ${projectLink(source)}`));
+        for (const source of stackSignals)
+            sources.add(source);
+    }
+    const architecture = await existingPaths(projectPath, [
+        'ARCHITECTURE.md', 'docs/architecture.md', 'docs/architecture', 'docs/adr', 'docs/adrs',
+        'src', 'app', 'apps', 'packages', 'services', 'crates',
+    ]);
+    const tests = await existingPaths(projectPath, [
+        'test', 'tests', '__tests__', 'vitest.config.ts', 'vitest.config.js', 'vitest.config.mts',
+        'jest.config.js', 'jest.config.ts', 'pytest.ini', 'tox.ini', 'playwright.config.ts',
+    ]);
+    const workflows = await workflowFiles(projectPath);
+    if (architecture.length) {
+        lines.push('', '### Architecture and Topology', '', ...architecture.map((source) => `- ${projectLink(source)}`));
+    }
+    if (tests.length) {
+        lines.push('', '### Testing', '', ...tests.map((source) => `- ${projectLink(source)}`));
+    }
+    if (workflows.length) {
+        lines.push('', '### Continuous Integration', '', ...workflows.map((source) => `- ${projectLink(source)}`));
+    }
+    for (const source of [...architecture, ...tests, ...workflows])
+        sources.add(source);
+    const orderedSources = [...sources].sort((left, right) => left.localeCompare(right));
+    if (orderedSources.length === 0)
+        return { content: '', sources: [], sensitiveFindings };
+    lines.push('', PROJECT_EXTRACTION_END);
+    const content = lines.join('\n');
+    sensitiveFindings = sensitiveEvidence(content).map((evidence) => ({ path: 'project extraction', evidence }));
+    return { content, sources: orderedSources, sensitiveFindings };
+}
+function mergeProjectExtraction(operatorContent, extraction) {
+    const existingStart = operatorContent.indexOf(PROJECT_EXTRACTION_START);
+    const existingEnd = operatorContent.indexOf(PROJECT_EXTRACTION_END);
+    let preserved = operatorContent.trim();
+    if (existingStart >= 0 || existingEnd >= 0) {
+        const replaced = replaceBlock(preserved, PROJECT_EXTRACTION_START, PROJECT_EXTRACTION_END, '');
+        preserved = (replaced ?? preserved).trim();
+    }
+    if (preserved === PROJECT_CONTEXT_PLACEHOLDER || preserved === [
+        '## Project Context',
+        '',
+        'Add provider-neutral project conventions and links here.',
+    ].join('\n'))
+        preserved = '';
+    if (!extraction)
+        return preserved || PROJECT_CONTEXT_PLACEHOLDER;
+    return [preserved, extraction].filter(Boolean).join('\n\n');
+}
+function providerForPath(relativePath) {
+    for (const definition of listProviderDefinitions()) {
+        if (definition.context.startupFiles.includes(relativePath) || definition.context.bootstrapTargets.includes(relativePath)) {
+            return definition.id;
+        }
+    }
+    return null;
+}
+function projectArtifactMarkdownPath(projectPath, ...segments) {
+    const rel = path.relative(projectPath, projectAiwgPath(projectPath, ...segments)).replace(/\\/g, '/');
+    if (rel === '')
+        return '.';
+    return rel.startsWith('.') ? rel : `./${rel}`;
+}
+function workspaceLinks(projectPath, providerFiles = []) {
+    const links = new Set([
+        '[AIWG framework context](./AIWG.md)',
+        `[AIWG project configuration](${projectArtifactMarkdownPath(projectPath, 'aiwg.config')})`,
+    ]);
+    if (providerFiles.length > 0) {
+        for (const file of providerFiles)
+            links.add(`[Provider-specific context](./${file.replace(/\\/g, '/')})`);
+    }
+    // The quickref source is linked, not copied into each provider directory.
+    links.add(`[Project-local quickref](${projectArtifactMarkdownPath(projectPath, 'quickref.json')}) (when configured)`);
+    return [...links];
+}
+export function buildWorkspaceManagedBlock(projectPath, providerFiles = []) {
+    const links = workspaceLinks(projectPath, providerFiles);
+    return [
+        WORKSPACE_MANAGED_START,
+        '',
+        '## AIWG Context Graph',
+        '',
+        'This file is the canonical provider-neutral home for project and operator context.',
+        'Provider startup files are generated adapters: they direct the harness here first,',
+        'then to AIWG.md for framework discovery and routing.',
+        '',
+        '### Precedence',
+        '',
+        '1. Provider, system, and organization instructions retain their native authority.',
+        '2. Root WORKSPACE.md supplies shared project/operator context.',
+        '3. AIWG.md supplies generated framework/discovery context.',
+        '4. Narrower linked files and provider-native subtree instructions govern their declared scope.',
+        '',
+        '### Ownership',
+        '',
+        '- Edit project-neutral notes only inside the protected Project Context section below.',
+        '- Keep detailed policies, runbooks, hooks, and quickrefs in linked files.',
+        '- Keep provider-only directives in `.aiwg/context/providers/`.',
+        '- Never store secrets, tokens, credentials, or machine-local sensitive values here.',
+        '',
+        '### Linked Context',
+        '',
+        ...links.map((link) => `- ${link}`),
+        '',
+        WORKSPACE_MANAGED_END,
+    ].join('\n');
+}
+export function buildWorkspaceDocument(projectPath, operatorContent = '', providerFiles = []) {
+    const content = operatorContent.trim() || PROJECT_CONTEXT_PLACEHOLDER;
+    return [
+        '# WORKSPACE.md',
+        WORKSPACE_SIGNATURE,
+        '<!-- Generated structure by AIWG; operator content is protected by markers. -->',
+        '',
+        buildWorkspaceManagedBlock(projectPath, providerFiles),
+        '',
+        WORKSPACE_OPERATOR_START,
+        '',
+        content,
+        '',
+        WORKSPACE_OPERATOR_END,
+        '',
+    ].join('\n');
+}
+export async function ensureWorkspaceContext(projectPath, options = {}) {
+    const workspacePath = path.join(projectPath, 'WORKSPACE.md');
+    const warnings = [];
+    const existing = await readOptional(workspacePath);
+    if (existing === null) {
+        await atomicWrite(workspacePath, buildWorkspaceDocument(projectPath, '', options.providerFiles));
+        return { path: workspacePath, action: 'created', warnings };
+    }
+    const block = buildWorkspaceManagedBlock(projectPath, options.providerFiles);
+    if (existing.includes(WORKSPACE_MANAGED_START) || existing.includes(WORKSPACE_MANAGED_END)) {
+        const updated = replaceBlock(existing, WORKSPACE_MANAGED_START, WORKSPACE_MANAGED_END, block);
+        if (updated === existing)
+            return { path: workspacePath, action: 'unchanged', warnings };
+        await atomicWrite(workspacePath, updated);
+        return { path: workspacePath, action: 'updated', warnings };
+    }
+    if (!options.force) {
+        warnings.push('WORKSPACE.md is operator-owned and has no AIWG markers; left untouched. Use workspace-context migrate to adopt it safely.');
+        return { path: workspacePath, action: 'preserved', warnings };
+    }
+    const backupPath = `${workspacePath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    await fs.writeFile(backupPath, existing, 'utf8');
+    await atomicWrite(workspacePath, buildWorkspaceDocument(projectPath, existing, options.providerFiles));
+    return { path: workspacePath, action: 'updated', backupPath, warnings };
+}
+export function buildProviderBootstrapBlock(provider) {
+    const definition = getProviderDefinition(provider);
+    const contract = definition?.context;
+    if (!definition || !contract || contract.loadMode === 'unsupported') {
+        return [
+            PROVIDER_BOOTSTRAP_START,
+            '',
+            '# Provider workspace bootstrap',
+            '',
+            'This provider has no verified project-local automatic context loader.',
+            'If the harness exposes file-reading tools, read WORKSPACE.md first and AIWG.md second.',
+            '',
+            PROVIDER_BOOTSTRAP_END,
+        ].join('\n');
+    }
+    const loading = contract.loadMode === 'native-include'
+        ? [
+            'Load the canonical project context first, then the generated AIWG framework context:',
+            '',
+            '@WORKSPACE.md',
+            '@AIWG.md',
+        ]
+        : contract.loadMode === 'config-registration'
+            ? [
+                'WORKSPACE.md and AIWG.md are registered through the provider configuration.',
+                'Read and follow WORKSPACE.md first; use AIWG.md second for AIWG discovery and routing.',
+            ]
+            : [
+                'Read and follow [WORKSPACE.md](./WORKSPACE.md) first.',
+                'Then read [AIWG.md](./AIWG.md) for AIWG discovery, quickrefs, and framework routing.',
+                '',
+                'These are explicit reading instructions. Plain Markdown links are not claimed to auto-load.',
+            ];
+    return [
+        PROVIDER_BOOTSTRAP_START,
+        '',
+        '# Provider workspace bootstrap',
+        '',
+        ...loading,
+        '',
+        PROVIDER_BOOTSTRAP_END,
+    ].join('\n');
+}
+export function buildProviderBootstrapFile(provider) {
+    return [
+        '# Provider workspace bootstrap',
+        WORKSPACE_SIGNATURE,
+        '<!-- Generated by AIWG. Project/operator context belongs in WORKSPACE.md. -->',
+        '',
+        buildProviderBootstrapBlock(provider),
+        '',
+    ].join('\n');
+}
+export async function registerProviderContext(provider, projectPath) {
+    const contract = getProviderDefinition(provider)?.context;
+    if (!contract?.configRegistration)
+        return null;
+    const configPath = path.join(projectPath, contract.configRegistration.file);
+    const existing = await readOptional(configPath);
+    let config = {};
+    if (existing !== null) {
+        try {
+            config = JSON.parse(existing);
+        }
+        catch {
+            return { path: configPath, changed: false, warning: `${contract.configRegistration.file} is not valid JSON; context registration was not changed.` };
+        }
+    }
+    const key = contract.configRegistration.key;
+    const current = Array.isArray(config[key]) ? config[key].filter((item) => typeof item === 'string') : [];
+    const next = [...new Set([...current, 'WORKSPACE.md', 'AIWG.md'])];
+    if (JSON.stringify(current) === JSON.stringify(next))
+        return { path: configPath, changed: false };
+    config[key] = next;
+    if (!('$schema' in config) && path.basename(configPath) === 'opencode.json') {
+        config = { $schema: 'https://opencode.ai/config.json', ...config };
+    }
+    await atomicWrite(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    return { path: configPath, changed: true };
+}
+function directives(content) {
+    return [...new Set(content
+            .split('\n')
+            .map((line) => line.replace(/^\s*[-*+]\s+/, '').replace(/^#+\s+/, '').trim())
+            .filter((line) => line.length >= 8 && !line.startsWith('<!--') && !/^https?:\/\//i.test(line)))];
+}
+function directiveKey(directive) {
+    if (!/^(always|never|must|do not|don't|required|prefer|use|avoid|keep|preserve)\b/i.test(directive))
+        return null;
+    return directive.toLowerCase()
+        .replace(/[^a-z0-9\s]/g, '')
+        .replace(/^(?:always|never|must|required|prefer|avoid|keep|preserve|do not|dont)\s+/, '')
+        .replace(/^use\s+/, '')
+        .split(/\s+/).slice(0, 5).join(' ');
+}
+function directivePolarity(directive) {
+    return /^(?:never|do not|don't|avoid)\b/i.test(directive) ? 'negative' : 'positive';
+}
+function sensitiveEvidence(content) {
+    const findings = [];
+    for (const line of content.split('\n')) {
+        if (/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/.test(line)) {
+            findings.push(`private-key material (${sha256(line).slice(0, 12)})`);
+        }
+        if (/\b(?:api[_-]?key|token|secret|password)\s*[:=]\s*(?!<|\$\{|\*{3}|example|placeholder)["']?[A-Za-z0-9_\-/.+=]{12,}/i.test(line)) {
+            findings.push(`credential-like assignment (${sha256(line).slice(0, 12)})`);
+        }
+    }
+    return findings;
+}
+async function nestedInstructionFiles(projectPath) {
+    const found = [];
+    const ignored = new Set(['.git', 'node_modules', 'dist', 'build', 'coverage', '.aiwg']);
+    async function walk(directory) {
+        let entries;
+        try {
+            entries = await fs.readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!ignored.has(entry.name) && !entry.name.startsWith('.context-migration-'))
+                    await walk(path.join(directory, entry.name));
+            }
+            else if (['AGENTS.md', 'CLAUDE.md', 'WARP.md'].includes(entry.name)) {
+                const relative = path.relative(projectPath, path.join(directory, entry.name)).replace(/\\/g, '/');
+                const segments = relative.split('/');
+                const generatedArtifactPath = segments.includes('templates') || segments.includes('fixtures');
+                if (!generatedArtifactPath && !LEGACY_ROOT_FILES.includes(relative))
+                    found.push(relative);
+            }
+        }
+    }
+    await walk(projectPath);
+    return found.sort((a, b) => a.localeCompare(b));
+}
+async function migratedProviderFiles(projectPath) {
+    const directory = projectAiwgPath(projectPath, 'context', 'providers');
+    try {
+        return (await fs.readdir(directory, { withFileTypes: true }))
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+            .map((entry) => projectOutputPath(projectPath, path.join(directory, entry.name)))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function auditWorkspaceContext(projectPath) {
+    const extractedProject = await extractExistingProjectContext(projectPath);
+    const candidates = new Set([
+        'WORKSPACE.md',
+        ...LEGACY_ROOT_FILES,
+        ...await nestedInstructionFiles(projectPath),
+        ...await migratedProviderFiles(projectPath),
+    ]);
+    const sources = [];
+    const sensitiveFindings = [...extractedProject.sensitiveFindings];
+    for (const relativePath of [...candidates].sort((a, b) => a.localeCompare(b))) {
+        const content = await readOptional(path.join(projectPath, relativePath));
+        if (content === null)
+            continue;
+        const operatorContent = relativePath === 'WORKSPACE.md'
+            ? (() => {
+                const start = content.indexOf(WORKSPACE_OPERATOR_START);
+                const end = content.indexOf(WORKSPACE_OPERATOR_END);
+                return start >= 0 && end > start
+                    ? content.slice(start + WORKSPACE_OPERATOR_START.length, end).trim()
+                    : stripGeneratedBlocks(content);
+            })()
+            : isGeneratedRootContext(relativePath, content)
+                ? ''
+                : stripGeneratedBlocks(content);
+        for (const evidence of sensitiveEvidence(operatorContent))
+            sensitiveFindings.push({ path: relativePath, evidence });
+        sources.push({
+            path: relativePath,
+            provider: providerForPath(relativePath),
+            scope: LEGACY_ROOT_FILES.includes(relativePath) || relativePath === 'WORKSPACE.md' ? 'root' : 'nested',
+            managed: content.includes(WORKSPACE_SIGNATURE) || content.includes('AIWG:context-hook:start') || content.includes('AIWG:claude-md-hook:start'),
+            operatorContent,
+            checksum: sha256(content),
+        });
+    }
+    const byDirective = new Map();
+    for (const source of sources) {
+        for (const directive of directives(source.operatorContent)) {
+            const paths = byDirective.get(directive) ?? [];
+            paths.push(source.path);
+            byDirective.set(directive, paths);
+        }
+    }
+    const identical = [...byDirective]
+        .filter(([, paths]) => paths.length > 1)
+        .map(([directive, paths]) => ({ sources: [...paths].sort(), directives: [directive] }));
+    const overlaps = [];
+    for (let index = 0; index < sources.length; index += 1) {
+        const left = new Set(directives(sources[index].operatorContent));
+        for (let rightIndex = index + 1; rightIndex < sources.length; rightIndex += 1) {
+            const common = directives(sources[rightIndex].operatorContent).filter((item) => left.has(item));
+            if (common.length > 0)
+                overlaps.push({ sources: [sources[index].path, sources[rightIndex].path], directives: common.sort() });
+        }
+    }
+    const conflictMap = new Map();
+    for (const source of sources) {
+        for (const directive of directives(source.operatorContent)) {
+            const key = directiveKey(directive);
+            if (!key)
+                continue;
+            const values = conflictMap.get(key) ?? [];
+            values.push({ path: source.path, directive, polarity: directivePolarity(directive) });
+            conflictMap.set(key, values);
+        }
+    }
+    const conflicts = [...conflictMap]
+        .filter(([, values]) => new Set(values.map((value) => value.polarity)).size > 1)
+        .map(([key, values]) => ({ key, sources: values.map(({ path: sourcePath, directive }) => ({ path: sourcePath, directive })).sort((a, b) => a.path.localeCompare(b.path)) }));
+    const rootOperator = sources.filter((source) => source.scope === 'root' && source.operatorContent.trim());
+    // Provider startup roots remain attributed provider context even when one
+    // directive is duplicated elsewhere. Promoting an entire root file because
+    // of one matching line can copy large provider/framework bodies into the
+    // provider-neutral WORKSPACE.md operator region.
+    const neutralSources = rootOperator.filter((source) => source.path === 'WORKSPACE.md').map((source) => source.path);
+    const providerSources = rootOperator.filter((source) => source.path !== 'WORKSPACE.md' && !neutralSources.includes(source.path)).map((source) => source.path);
+    const providerOutputs = providerSources.map((source) => providerContextOutput(projectPath, source));
+    const workspaceExists = sources.some((source) => source.path === 'WORKSPACE.md');
+    return {
+        version: 1,
+        projectPath,
+        workspaceExists,
+        legacyCompatible: !workspaceExists && sources.some((source) => LEGACY_ROOT_FILES.includes(source.path)),
+        sources,
+        identical,
+        overlaps,
+        conflicts,
+        sensitiveFindings,
+        plan: {
+            neutralSources,
+            providerSources,
+            nestedSources: sources.filter((source) => source.scope === 'nested').map((source) => source.path),
+            projectSources: extractedProject.sources,
+            outputs: ['WORKSPACE.md', ...providerOutputs, ...listProviderDefinitions().flatMap((definition) => definition.context.bootstrapTargets)].filter((value, index, all) => all.indexOf(value) === index).sort(),
+        },
+    };
+}
+function projectOutputPath(projectPath, absPath) {
+    return path.relative(projectPath, absPath).replace(/\\/g, '/');
+}
+function providerContextOutput(projectPath, sourcePath) {
+    return projectOutputPath(projectPath, projectAiwgPath(projectPath, 'context', 'providers', sourcePath.replace(/[^A-Za-z0-9.-]+/g, '-').replace(/^-+/, '')));
+}
+function neutralMigrationContent(audit) {
+    const selected = audit.sources.filter((source) => audit.plan.neutralSources.includes(source.path));
+    const seen = new Set();
+    const lines = ['## Project Context', ''];
+    for (const source of selected) {
+        const unique = directives(source.operatorContent).filter((directive) => !seen.has(directive));
+        for (const directive of unique)
+            seen.add(directive);
+        if (unique.length === 0)
+            continue;
+        lines.push(`### From ${source.path}`, '', ...unique.map((directive) => `- ${directive}`), '');
+    }
+    if (lines.length === 2)
+        lines.push('Add project conventions, local hook/context pointers, and links to deeper project documents here.');
+    return lines.join('\n').trim();
+}
+function providerMigrationContent(source) {
+    return [
+        `# Provider-specific context from ${source.path}`,
+        '',
+        `Source attribution: migrated from \`${source.path}\`; checksum \`${source.checksum}\`.`,
+        '',
+        source.operatorContent.trim() || '(No operator-authored content remained after managed blocks were removed.)',
+        '',
+    ].join('\n');
+}
+async function configuredProviders(projectPath) {
+    const config = await readOptional(projectAiwgPath(projectPath, 'aiwg.config'));
+    if (config) {
+        try {
+            const parsed = JSON.parse(config);
+            if (Array.isArray(parsed.providers))
+                return parsed.providers.filter((provider) => typeof provider === 'string');
+        }
+        catch {
+            // Audit/migration reports malformed provider config through the normal CLI path.
+        }
+    }
+    return ['claude'];
+}
+async function stageMigrationWrites(projectPath, audit, options = {}) {
+    const writes = new Map();
+    for (const source of audit.sources.filter((item) => audit.plan.providerSources.includes(item.path))) {
+        writes.set(providerContextOutput(projectPath, source.path), providerMigrationContent(source));
+    }
+    const providerFiles = [...new Set([
+            ...audit.sources.filter((source) => source.path.replace(/\\/g, '/').includes('/context/providers/')).map((source) => source.path),
+            ...writes.keys(),
+        ])].sort();
+    const existingWorkspace = audit.sources.find((source) => source.path === 'WORKSPACE.md');
+    let workspaceOperatorContent = existingWorkspace?.managed
+        ? existingWorkspace.operatorContent
+        : neutralMigrationContent(audit);
+    if (options.extractProject) {
+        const extracted = await extractExistingProjectContext(projectPath);
+        workspaceOperatorContent = mergeProjectExtraction(workspaceOperatorContent, extracted.content);
+    }
+    writes.set('WORKSPACE.md', buildWorkspaceDocument(projectPath, workspaceOperatorContent, providerFiles));
+    const providers = await configuredProviders(projectPath);
+    const targetProviders = new Map();
+    for (const provider of providers) {
+        const definition = getProviderDefinition(provider);
+        if (!definition)
+            continue;
+        for (const target of definition.context.bootstrapTargets) {
+            const values = targetProviders.get(target) ?? [];
+            values.push(provider);
+            targetProviders.set(target, values);
+        }
+    }
+    for (const [target, targetProviderIds] of targetProviders) {
+        // Shared AGENTS.md is deliberately provider-neutral prose so sequential
+        // multi-provider deployment cannot make the last provider win.
+        const provider = targetProviderIds.length === 1 ? targetProviderIds[0] : 'generic';
+        const content = provider === 'generic'
+            ? [
+                '# Provider workspace bootstrap', WORKSPACE_SIGNATURE,
+                '<!-- Generated by AIWG. Project/operator context belongs in WORKSPACE.md. -->', '',
+                PROVIDER_BOOTSTRAP_START, '',
+                'Read and follow [WORKSPACE.md](./WORKSPACE.md) first.',
+                'Then read [AIWG.md](./AIWG.md) for AIWG discovery and framework routing.',
+                'These are explicit reading instructions; a plain Markdown link is not claimed to auto-load.', '',
+                PROVIDER_BOOTSTRAP_END, '',
+            ].join('\n')
+            : buildProviderBootstrapFile(provider);
+        writes.set(target, content);
+    }
+    // Any detected operator-owned root startup file participates in the explicit
+    // adoption even when that provider is not currently enabled. Its authored
+    // content is already staged in an attributed provider file above; replacing
+    // the active root with a bootstrap completes the move and prevents two
+    // divergent sources of truth.
+    for (const source of audit.sources.filter((item) => audit.plan.providerSources.includes(item.path))) {
+        if (source.scope === 'root' && source.provider && source.path !== 'AIWG.md' && !targetProviders.has(source.path)) {
+            writes.set(source.path, buildProviderBootstrapFile(source.provider));
+        }
+    }
+    const activeCodexOverride = audit.sources.find((source) => source.path === 'AGENTS.override.md' && source.operatorContent.trim());
+    if (providers.includes('codex') && activeCodexOverride) {
+        writes.set('AGENTS.override.md', buildProviderBootstrapFile('codex'));
+    }
+    for (const provider of providers) {
+        const contract = getProviderDefinition(provider)?.context;
+        if (!contract?.configRegistration)
+            continue;
+        const configPath = contract.configRegistration.file;
+        const existing = await readOptional(path.join(projectPath, configPath));
+        let config = {};
+        if (existing !== null)
+            config = JSON.parse(existing);
+        const key = contract.configRegistration.key;
+        const current = Array.isArray(config[key]) ? config[key].filter((item) => typeof item === 'string') : [];
+        config[key] = [...new Set([...current, 'WORKSPACE.md', 'AIWG.md'])];
+        if (!('$schema' in config) && path.basename(configPath) === 'opencode.json')
+            config = { $schema: 'https://opencode.ai/config.json', ...config };
+        writes.set(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    }
+    if (options.includeGeneratedContext) {
+        const normalizedPath = projectOutputPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+        const existingNormalized = await readOptional(path.join(projectPath, normalizedPath)) ?? '';
+        writes.set(normalizedPath, await buildNormalizedAiwgMd(projectPath, existingNormalized));
+        const stagedClaude = writes.has('CLAUDE.md')
+            ? writes.get('CLAUDE.md')
+            : await readOptional(path.join(projectPath, 'CLAUDE.md'));
+        writes.set('AIWG.md', await buildAiwgMdContent(projectPath, stagedClaude));
+    }
+    return writes;
+}
+function safePreimageName(relativePath) {
+    return `${sha256(relativePath).slice(0, 16)}-${path.basename(relativePath)}`;
+}
+export async function migrateWorkspaceContext(projectPath, options = {}) {
+    const audit = await auditWorkspaceContext(projectPath);
+    const sensitiveFindingCount = audit.sensitiveFindings.length;
+    if (sensitiveFindingCount > 0) {
+        throw new Error(`Migration refused: ${sensitiveFindingCount} possible secret/credential value(s) found. Remove them before migration.`);
+    }
+    if (audit.conflicts.length > 0 && !options.allowConflicts) {
+        throw new Error(`Migration refused: ${audit.conflicts.length} ambiguous directive conflict(s). Review the deterministic audit or pass --allow-conflicts to preserve each source separately.`);
+    }
+    const writes = await stageMigrationWrites(projectPath, audit, {
+        extractProject: options.extractProject,
+        includeGeneratedContext: options.includeGeneratedContext,
+    });
+    const changedEntries = [];
+    for (const [relativePath, content] of writes) {
+        if (await readOptional(path.join(projectPath, relativePath)) !== content)
+            changedEntries.push([relativePath, content]);
+    }
+    if (options.dryRun || !options.apply) {
+        return { audit, dryRun: true, changed: changedEntries.length > 0, written: changedEntries.map(([relative]) => relative), backups: [] };
+    }
+    if (changedEntries.length === 0)
+        return { audit, dryRun: false, changed: false, written: [], backups: [] };
+    const createdAt = new Date().toISOString();
+    const id = `${createdAt.replace(/[:.]/g, '-')}-${sha256(JSON.stringify(audit.plan)).slice(0, 8)}`;
+    const transactionDir = projectAiwgPath(projectPath, 'context-migrations', id);
+    const preimageDir = path.join(transactionDir, 'preimages');
+    await fs.mkdir(preimageDir, { recursive: true });
+    const manifest = { version: 1, id, createdAt, projectPath, status: 'prepared', files: [] };
+    const backups = [];
+    for (const [relativePath, content] of changedEntries) {
+        const target = path.join(projectPath, relativePath);
+        const existing = await readOptional(target);
+        let preimage = null;
+        if (existing !== null) {
+            preimage = path.relative(projectPath, path.join(preimageDir, safePreimageName(relativePath))).replace(/\\/g, '/');
+            await fs.writeFile(path.join(projectPath, preimage), existing, 'utf8');
+            backups.push(preimage);
+        }
+        manifest.files.push({ path: relativePath, existed: existing !== null, preimage, outputChecksum: sha256(content) });
+    }
+    const manifestPath = path.join(transactionDir, 'manifest.json');
+    await atomicWrite(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    try {
+        for (const [relativePath, content] of changedEntries.sort(([left], [right]) => left.localeCompare(right))) {
+            await atomicWrite(path.join(projectPath, relativePath), content);
+        }
+        manifest.status = 'applied';
+        await atomicWrite(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    }
+    catch (error) {
+        await restoreMigrationManifest(projectPath, manifest);
+        throw error;
+    }
+    return { audit, dryRun: false, changed: true, transactionId: id, written: changedEntries.map(([relative]) => relative).sort(), backups };
+}
+async function restoreMigrationManifest(projectPath, manifest) {
+    for (const file of [...manifest.files].reverse()) {
+        const target = resolveProjectRelative(projectPath, file.path);
+        if (file.existed && file.preimage) {
+            const preimage = await fs.readFile(resolveProjectRelative(projectPath, file.preimage), 'utf8');
+            await atomicWrite(target, preimage);
+        }
+        else {
+            await fs.rm(target, { force: true });
+        }
+    }
+}
+export async function rollbackWorkspaceContext(projectPath, requestedId) {
+    const root = projectAiwgPath(projectPath, 'context-migrations');
+    let ids;
+    try {
+        ids = (await fs.readdir(root)).sort().reverse();
+    }
+    catch {
+        throw new Error('No workspace-context migration transactions found.');
+    }
+    const id = requestedId ?? ids[0];
+    if (!id || id.includes('/') || id.includes('\\'))
+        throw new Error('Invalid workspace-context migration id.');
+    const manifestPath = path.join(root, id, 'manifest.json');
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    if (manifest.status === 'rolled-back')
+        return { id, restored: [] };
+    for (const file of manifest.files) {
+        const current = await readOptional(resolveProjectRelative(projectPath, file.path));
+        if (current === null || sha256(current) !== file.outputChecksum) {
+            throw new Error(`Rollback refused: ${file.path} changed after migration. Preserve or reconcile that work before restoring transaction ${id}.`);
+        }
+    }
+    await restoreMigrationManifest(projectPath, manifest);
+    manifest.status = 'rolled-back';
+    await atomicWrite(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return { id, restored: manifest.files.map((file) => file.path) };
+}
+function markdownLinks(content) {
+    return [...content.matchAll(/\[[^\]]+\]\((\.\/?[^)#]+)(?:#[^)]+)?\)/g)].map((match) => match[1]);
+}
+export async function workspaceLinkedFiles(projectPath) {
+    const content = await readOptional(path.join(projectPath, 'WORKSPACE.md'));
+    if (!content)
+        return [];
+    const files = [];
+    for (const link of markdownLinks(content)) {
+        const normalized = link.replace(/^\.\//, '');
+        const resolved = path.resolve(projectPath, normalized);
+        if (resolved !== projectPath && !resolved.startsWith(`${path.resolve(projectPath)}${path.sep}`))
+            continue;
+        try {
+            const stat = await fs.stat(resolved);
+            if (stat.isFile())
+                files.push(resolved);
+        }
+        catch {
+            // Missing optional linked files are reported by doctor, not index builds.
+        }
+    }
+    return [...new Set(files)].sort();
+}
+export async function diagnoseWorkspaceContext(projectPath) {
+    const diagnostics = [];
+    const audit = await auditWorkspaceContext(projectPath);
+    const workspacePath = path.join(projectPath, 'WORKSPACE.md');
+    const workspace = await readOptional(workspacePath);
+    if (!workspace) {
+        diagnostics.push({ severity: 'info', code: 'legacy-layout', message: 'Legacy provider context layout is supported; run `aiwg workspace-context migrate --dry-run` for opt-in conversion.' });
+        return diagnostics;
+    }
+    if (!workspace.includes(WORKSPACE_MANAGED_START) || !workspace.includes(WORKSPACE_OPERATOR_START)) {
+        diagnostics.push({ severity: 'warning', code: 'workspace-unmanaged', message: 'WORKSPACE.md lacks complete AIWG ownership markers.', path: 'WORKSPACE.md' });
+    }
+    if (workspace.includes(PROVIDER_BOOTSTRAP_START)) {
+        diagnostics.push({ severity: 'error', code: 'include-loop', message: 'WORKSPACE.md contains a provider bootstrap marker and could create a self-referential context loop.', path: 'WORKSPACE.md' });
+    }
+    for (const link of markdownLinks(workspace)) {
+        const normalized = link.replace(/^\.\//, '');
+        if (normalized.includes('WORKSPACE.md'))
+            continue;
+        let linkedPath;
+        try {
+            linkedPath = resolveProjectRelative(projectPath, normalized);
+        }
+        catch {
+            diagnostics.push({ severity: 'error', code: 'unsafe-link', message: `Linked context path escapes the project: ${normalized}`, path: 'WORKSPACE.md' });
+            continue;
+        }
+        let exists = false;
+        try {
+            await fs.stat(linkedPath);
+            exists = true;
+        }
+        catch {
+            exists = false;
+        }
+        if (!exists && !normalized.endsWith('quickref.json')) {
+            diagnostics.push({ severity: 'warning', code: 'missing-link', message: `Linked context file is missing: ${normalized}`, path: 'WORKSPACE.md' });
+        }
+    }
+    for (const conflict of audit.conflicts) {
+        diagnostics.push({ severity: 'error', code: 'directive-conflict', message: `Conflicting duplicate directive group '${conflict.key}' appears in ${conflict.sources.map((source) => source.path).join(', ')}.` });
+    }
+    for (const overlap of audit.identical) {
+        diagnostics.push({ severity: 'warning', code: 'duplicate-directive', message: `Identical directive is duplicated across ${overlap.sources.join(', ')}.` });
+    }
+    for (const finding of audit.sensitiveFindings) {
+        diagnostics.push({ severity: 'error', code: 'possible-secret', message: 'Possible credential value found in context; remove it.', path: finding.path });
+    }
+    const providers = await configuredProviders(projectPath);
+    for (const provider of providers) {
+        const definition = getProviderDefinition(provider);
+        if (!definition)
+            continue;
+        for (const target of definition.context.bootstrapTargets) {
+            const targetContent = await readOptional(path.join(projectPath, target));
+            if (targetContent?.includes(WORKSPACE_SIGNATURE) && !targetContent.includes('WORKSPACE.md')) {
+                diagnostics.push({ severity: 'error', code: 'bootstrap-drift', message: `${target} is AIWG-managed but no longer points to WORKSPACE.md first.`, path: target });
+            }
+        }
+        if (definition.context.configRegistration) {
+            const registration = definition.context.configRegistration;
+            const config = await readOptional(path.join(projectPath, registration.file));
+            if (config) {
+                try {
+                    const parsed = JSON.parse(config);
+                    const values = Array.isArray(parsed[registration.key]) ? parsed[registration.key] : [];
+                    if (!values.includes('WORKSPACE.md'))
+                        diagnostics.push({ severity: 'error', code: 'registration-drift', message: `${registration.file} does not register WORKSPACE.md.`, path: registration.file });
+                }
+                catch {
+                    diagnostics.push({ severity: 'error', code: 'registration-invalid', message: `${registration.file} is invalid JSON.`, path: registration.file });
+                }
+            }
+        }
+    }
+    if (diagnostics.length === 0)
+        diagnostics.push({ severity: 'info', code: 'healthy', message: 'Workspace context graph is healthy.' });
+    return diagnostics;
+}
+export function providerContextContract(provider) {
+    return getProviderDefinition(provider)?.context;
+}
+//# sourceMappingURL=workspace-context.js.map