shift-ax 0.3.0

package/dist/core/context/context-bundle.js

@@ -0,0 +1,300 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { searchDecisionMemory } from '../memory/decision-register.js';
+import { searchPastTopics } from '../memory/topic-recall.js';
+import { getRootDirFromTopicDir } from '../topics/topic-artifacts.js';
+import { parseIndexDocument, resolveContextFromIndex, } from './index-resolver.js';
+import { getGlobalContextHome } from '../settings/global-context-home.js';
+export function classifyContextBundle(bundle) {
+    if (bundle.issues.length > 0) {
+        return {
+            status: 'critical',
+            recommendation: 'Base-context issues are present. Repair the shared docs or index before trusting this context bundle.',
+        };
+    }
+    const ratio = bundle.total_source_chars / Math.max(bundle.max_chars, 1);
+    if (bundle.truncated && ratio >= 1.5) {
+        return {
+            status: 'critical',
+            recommendation: 'The current context is far above the bundle budget. Split the work, pause safely, or build a smaller bundle.',
+        };
+    }
+    if (bundle.truncated || ratio >= 1.0) {
+        return {
+            status: 'warn',
+            recommendation: 'The current context is approaching the bundle budget. Narrow the query or checkpoint the work soon.',
+        };
+    }
+    return {
+        status: 'ok',
+        recommendation: 'The current context fits safely inside the bundle budget. Continue working.',
+    };
+}
+function tokenize(value) {
+    return String(value || '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3);
+}
+function slugify(value) {
+    return String(value || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '') || 'context';
+}
+async function readMaybe(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+async function loadBaseContextItems(rootDir, query) {
+    const home = getGlobalContextHome();
+    const localIndexPath = join(rootDir, 'docs', 'base-context', 'index.md');
+    const candidates = [
+        { indexPath: localIndexPath, indexRootDir: rootDir, kind: 'local' },
+        { indexPath: home.indexPath, indexRootDir: home.root, kind: 'global' },
+    ];
+    const candidateResults = [];
+    for (const candidate of candidates) {
+        const issues = [];
+        const rawIndex = await readMaybe(candidate.indexPath);
+        if (!rawIndex.trim()) {
+            candidateResults.push({
+                items: [],
+                issues: candidate.kind === 'global' ? [] : [`Base-context index is missing or unreadable: ${candidate.indexPath}`],
+            });
+            continue;
+        }
+        const resolved = await resolveContextFromIndex({
+            rootDir,
+            indexPath: candidate.indexPath,
+            indexRootDir: candidate.indexRootDir,
+            query,
+            maxMatches: 5,
+        }).catch(() => ({
+            matches: [],
+            unresolved_paths: [],
+        }));
+        const directMatches = (resolved.matches ?? []).map((match) => ({
+            label: match.label,
+            path: match.path,
+            score: match.score,
+            content: match.content.trim(),
+        }));
+        if ((resolved.unresolved_paths ?? []).length > 0) {
+            for (const path of resolved.unresolved_paths ?? []) {
+                issues.push(`Base-context path could not be resolved: ${path}`);
+            }
+        }
+        if (directMatches.length > 0) {
+            candidateResults.push({ items: directMatches, issues });
+            continue;
+        }
+        const queryTokens = tokenize(query);
+        const entries = parseIndexDocument(rawIndex);
+        const ranked = [];
+        for (const entry of entries) {
+            const content = await readMaybe(join(candidate.indexRootDir, entry.path));
+            if (!content.trim())
+                continue;
+            const haystack = new Set(tokenize(content));
+            const score = queryTokens.reduce((sum, token) => sum + (haystack.has(token) ? 1 : 0), 0);
+            if (score <= 0)
+                continue;
+            ranked.push({
+                label: entry.label,
+                path: entry.path,
+                score,
+                content: content.trim(),
+            });
+        }
+        if (ranked.length === 0 && candidate.kind === 'local') {
+            issues.push('No matching base-context documents were found for the current query.');
+        }
+        candidateResults.push({
+            items: ranked.sort((left, right) => (right.score ?? 0) - (left.score ?? 0)).slice(0, 5),
+            issues,
+        });
+    }
+    const firstUseful = candidateResults.find((result) => result.items.length > 0);
+    if (firstUseful)
+        return firstUseful;
+    return candidateResults[candidateResults.length - 1] ?? { items: [], issues: [] };
+}
+async function loadReviewedArtifactItems(topicDir) {
+    if (!topicDir)
+        return [];
+    const requestSummary = await readMaybe(join(topicDir, 'request-summary.md'));
+    const spec = await readMaybe(join(topicDir, 'spec.md'));
+    const plan = await readMaybe(join(topicDir, 'implementation-plan.md'));
+    const brainstorm = await readMaybe(join(topicDir, 'brainstorm.md'));
+    const items = [];
+    if (requestSummary.trim()) {
+        items.push({
+            label: 'Request Summary',
+            path: 'request-summary.md',
+            content: requestSummary.trim(),
+        });
+    }
+    if (spec.trim()) {
+        items.push({
+            label: 'Reviewed Spec',
+            path: 'spec.md',
+            content: spec.trim(),
+        });
+    }
+    if (plan.trim()) {
+        items.push({
+            label: 'Implementation Plan',
+            path: 'implementation-plan.md',
+            content: plan.trim(),
+        });
+    }
+    if (brainstorm.trim()) {
+        items.push({
+            label: 'Brainstorm',
+            path: 'brainstorm.md',
+            content: brainstorm.trim(),
+        });
+    }
+    return items;
+}
+function mapDecisionItems(matches) {
+    return matches.map((match) => ({
+        label: match.title,
+        path: match.source_doc,
+        score: match.score,
+        content: [
+            match.summary.trim(),
+            match.source_topic_summary?.trim() ? `Source topic summary: ${match.source_topic_summary.trim()}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n'),
+    }));
+}
+function mapTopicRecallItems(matches) {
+    return matches.map((match) => ({
+        label: match.topic_slug,
+        score: match.score,
+        content: [match.summary.trim(), match.request.trim()].filter(Boolean).join('\n'),
+    }));
+}
+function trimToBudget(text, budget) {
+    if (budget <= 0)
+        return '';
+    if (text.length <= budget)
+        return text;
+    if (budget <= 3)
+        return text.slice(0, budget);
+    return `${text.slice(0, budget - 3).trimEnd()}...`;
+}
+function renderSectionHeader(title) {
+    return `## ${title}\n\n`;
+}
+function renderItem(item) {
+    const header = item.path ? `### ${item.label} (${item.path})\n\n` : `### ${item.label}\n\n`;
+    return `${header}${item.content.trim()}\n\n`;
+}
+export async function buildContextBundle({ rootDir, topicDir, query, maxChars = 6000, }) {
+    const effectiveRoot = rootDir || (topicDir ? getRootDirFromTopicDir(topicDir) : '');
+    if (!effectiveRoot) {
+        throw new Error('rootDir or topicDir is required');
+    }
+    const [baseContext, reviewedItems, decisionItems, topicRecallItems] = await Promise.all([
+        loadBaseContextItems(effectiveRoot, query),
+        loadReviewedArtifactItems(topicDir),
+        searchDecisionMemory({
+            rootDir: effectiveRoot,
+            query,
+            limit: 3,
+        }).then(mapDecisionItems),
+        searchPastTopics({
+            rootDir: effectiveRoot,
+            query,
+            limit: 3,
+        }).then(mapTopicRecallItems),
+    ]);
+    const plannedSections = [
+        { kind: 'reviewed_artifacts', title: 'Reviewed Artifacts', items: reviewedItems },
+        { kind: 'base_context', title: 'Base Context', items: baseContext.items },
+        { kind: 'decision_memory', title: 'Decision Memory', items: decisionItems },
+        { kind: 'topic_recall', title: 'Past Topic Recall', items: topicRecallItems },
+    ];
+    let remaining = maxChars;
+    const sections = [];
+    let rendered = '';
+    const totalSourceChars = plannedSections
+        .flatMap((section) => section.items)
+        .reduce((sum, item) => sum + item.content.length, 0);
+    const issues = [...baseContext.issues];
+    if (issues.length > 0) {
+        const issuesBlock = ['## Context Issues', '', ...issues.map((issue) => `- ${issue}`), '', ''].join('\n');
+        rendered += trimToBudget(issuesBlock, remaining);
+        remaining = maxChars - rendered.length;
+    }
+    for (const section of plannedSections) {
+        if (remaining <= 0)
+            break;
+        const header = renderSectionHeader(section.title);
+        if (header.length > remaining)
+            break;
+        let sectionRendered = header;
+        let sectionRemaining = remaining - header.length;
+        const keptItems = [];
+        for (const item of section.items) {
+            if (sectionRemaining <= 0)
+                break;
+            const renderedItem = renderItem(item);
+            const trimmed = trimToBudget(renderedItem, sectionRemaining);
+            if (!trimmed.trim())
+                break;
+            sectionRendered += trimmed;
+            keptItems.push({
+                ...item,
+                content: trimToBudget(item.content, Math.max(0, trimmed.length)),
+            });
+            sectionRemaining = maxChars - (rendered.length + sectionRendered).length;
+        }
+        if (keptItems.length === 0 && section.kind !== 'base_context') {
+            continue;
+        }
+        rendered += sectionRendered;
+        remaining = maxChars - rendered.length;
+        sections.push({
+            ...section,
+            items: keptItems,
+        });
+    }
+    return {
+        query,
+        max_chars: maxChars,
+        total_source_chars: totalSourceChars,
+        truncated: totalSourceChars > rendered.length,
+        issues,
+        sections,
+        rendered: rendered.slice(0, maxChars),
+    };
+}
+export async function writeContextBundle({ rootDir, topicDir, query, maxChars = 6000, outputPath, workflowStep = 'general', }) {
+    const bundle = await buildContextBundle({
+        rootDir,
+        topicDir,
+        query,
+        maxChars,
+    });
+    const effectiveRoot = rootDir || (topicDir ? getRootDirFromTopicDir(topicDir) : '');
+    const targetPath = outputPath || join(effectiveRoot, '.ax', 'context-bundles', `${slugify(query)}--${slugify(workflowStep)}.md`);
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, `# Shift AX Context Bundle\n\n- workflow_step: ${workflowStep}\n- query: ${query}\n- max_chars: ${bundle.max_chars}\n\n${bundle.rendered.trim()}\n`, 'utf8');
+    return {
+        bundle,
+        output_path: targetPath,
+        status: classifyContextBundle(bundle).status,
+    };
+}

package/dist/core/context/discovery.js

@@ -0,0 +1,82 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const EXCLUDED_SEGMENTS = new Set(['base-context', 'verification', 'roadmap', '.ax']);
+const INCLUDED_KEYWORDS = [
+    'architecture',
+    'policy',
+    'policies',
+    'domain',
+    'glossary',
+    'context',
+    'overview',
+    'service',
+    'reference',
+    'decision',
+    'adr',
+];
+async function walkMarkdownFiles(dir, rootDir, results) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        const relPath = relative(rootDir, fullPath).replace(/\\/g, '/');
+        if (entry.isDirectory()) {
+            if ([...EXCLUDED_SEGMENTS].some((segment) => relPath.split('/').includes(segment))) {
+                continue;
+            }
+            await walkMarkdownFiles(fullPath, rootDir, results);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.toLowerCase().endsWith('.md'))
+            continue;
+        if (entry.name.toLowerCase() === 'index.md' && relPath.includes('docs/base-context'))
+            continue;
+        results.push(relPath);
+    }
+}
+function humanizeSlug(slug) {
+    return slug
+        .replace(/[-_]+/g, ' ')
+        .replace(/\b\w/g, (ch) => ch.toUpperCase())
+        .trim();
+}
+async function readHeading(rootDir, relPath) {
+    try {
+        const content = await readFile(join(rootDir, relPath), 'utf8');
+        const match = content.match(/^#\s+(.+)$/m);
+        return match ? match[1].trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function looksRelevant(path) {
+    const normalized = path.toLowerCase();
+    return INCLUDED_KEYWORDS.some((keyword) => normalized.includes(keyword));
+}
+export async function discoverBaseContextEntries({ rootDir, }) {
+    const docsRoot = join(rootDir, 'docs');
+    const files = [];
+    await walkMarkdownFiles(docsRoot, rootDir, files).catch(() => undefined);
+    const relevantFiles = files.filter(looksRelevant);
+    const discovered = [];
+    for (const relPath of relevantFiles) {
+        const label = (await readHeading(rootDir, relPath)) ??
+            humanizeSlug(relPath.split('/').pop()?.replace(/\.md$/i, '') ?? relPath);
+        const topLevel = relPath.split('/')[1] ?? 'docs';
+        discovered.push({
+            label,
+            path: relPath,
+            reason: `Detected from docs/${topLevel}/ markdown structure.`,
+        });
+    }
+    const seen = new Set();
+    return discovered.filter((entry) => {
+        const key = `${entry.label}::${entry.path}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/core/context/global-index-authoring.js

@@ -0,0 +1,199 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { getGlobalContextHome } from '../settings/global-context-home.js';
+function slugify(value) {
+    return String(value || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '') || 'context';
+}
+async function writeMarkdown(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${content.trimEnd()}\n`, 'utf8');
+}
+function renderProcedurePage({ workType, repository, }) {
+    const repoTitle = repository.repository;
+    const lines = [
+        `# ${workType} — ${repoTitle}`,
+        '',
+        '## Repository',
+        '',
+        `- Name: ${repoTitle}`,
+        ...(repository.repositoryPath ? [`- Path: ${repository.repositoryPath}`] : []),
+        ...(repository.purpose ? [`- Purpose: ${repository.purpose}`] : []),
+        '',
+        '## Working Directories',
+        '',
+        ...(repository.directories.length > 0
+            ? repository.directories.map((directory) => `- ${directory}`)
+            : ['- No directories were recorded yet.']),
+        '',
+        '## Working Method',
+        '',
+        repository.workflow.trim(),
+        '',
+    ];
+    if ((repository.inferredNotes ?? []).length > 0) {
+        lines.push('## Inferred Workflow Notes', '');
+        lines.push(...(repository.inferredNotes ?? []).map((note) => `- ${note}`));
+        lines.push('');
+    }
+    if (repository.confirmationNotes?.trim()) {
+        lines.push('## Confirmation Notes', '', repository.confirmationNotes.trim(), '');
+    }
+    lines.push('## Volatility', '', repository.volatility === 'stable'
+        ? 'This workflow is treated as stable cross-repo guidance.'
+        : 'This workflow is treated as volatile inspect-and-confirm guidance.', '');
+    return lines.join('\n');
+}
+function renderRepositoryPage({ repository, workTypes, }) {
+    const lines = [
+        `# ${repository.repository}`,
+        '',
+        '## Work Types',
+        '',
+        ...workTypes.map((workType) => `- ${workType}`),
+        '',
+    ];
+    if (repository.repositoryPath) {
+        lines.push('## Repository Path', '', repository.repositoryPath, '');
+    }
+    if (repository.purpose?.trim()) {
+        lines.push('## Purpose', '', repository.purpose.trim(), '');
+    }
+    lines.push('## Notes', '', 'This page is a repository index. Detailed working methods live in linked procedure pages.', '');
+    return lines.join('\n');
+}
+function renderWorkTypePage({ workType, procedureLinks, }) {
+    return [
+        `# ${workType.name}`,
+        '',
+        '## Summary',
+        '',
+        workType.summary?.trim() || 'No summary recorded yet.',
+        '',
+        '## Related Repositories',
+        '',
+        ...procedureLinks.map((item) => `- ${item.repository} -> ${item.path}`),
+        '',
+    ].join('\n');
+}
+function renderDomainLanguagePage(entry) {
+    return [
+        `# ${entry.term}`,
+        '',
+        entry.definition.trim(),
+        '',
+    ].join('\n');
+}
+function renderIndex({ primaryRoleSummary, workTypeEntries, domainEntries, }) {
+    return [
+        '# Shift AX Global Index',
+        '',
+        '## Primary Role',
+        '',
+        primaryRoleSummary.trim(),
+        '',
+        '## Work Types',
+        '',
+        ...(workTypeEntries.length > 0
+            ? workTypeEntries.map((entry) => `- ${entry.label} -> ${entry.path}`)
+            : ['- None yet.']),
+        '',
+        '## Domain Language',
+        '',
+        ...(domainEntries.length > 0
+            ? domainEntries.map((entry) => `- ${entry.label} -> ${entry.path}`)
+            : ['- None yet.']),
+        '',
+        'Notes:',
+        '',
+        '- The index stays intentionally lightweight.',
+        '- Detailed procedures and repository notes live in linked markdown pages.',
+        '- Reviewed topic artifacts override repository evidence, which override global knowledge, when they conflict.',
+        '',
+    ].join('\n');
+}
+export async function authorGlobalKnowledgeBase({ primaryRoleSummary, workTypes, domainLanguage, }) {
+    const home = getGlobalContextHome();
+    const contextDocs = [];
+    const workTypeEntries = [];
+    const domainEntries = [];
+    const repoWorkTypeMap = new Map();
+    for (const workType of workTypes) {
+        const workTypeSlug = slugify(workType.name);
+        const procedureLinks = [];
+        for (const repository of workType.repositories) {
+            const repoSlug = slugify(repository.repository || basename(repository.repositoryPath || 'repo'));
+            const procedureFileName = `${workTypeSlug}--${repoSlug}.md`;
+            const procedureAbsolutePath = join(home.proceduresDir, procedureFileName);
+            const procedureRelativePath = `procedures/${procedureFileName}`;
+            await writeMarkdown(procedureAbsolutePath, renderProcedurePage({
+                workType: workType.name,
+                repository,
+            }));
+            procedureLinks.push({
+                repository: repository.repository,
+                path: procedureRelativePath,
+            });
+            contextDocs.push({
+                label: `${workType.name} — ${repository.repository}`,
+                path: procedureRelativePath,
+            });
+            const repoKey = repoSlug;
+            if (!repoWorkTypeMap.has(repoKey)) {
+                repoWorkTypeMap.set(repoKey, new Set());
+            }
+            repoWorkTypeMap.get(repoKey).add(workType.name);
+            const repoAbsolutePath = join(home.reposDir, `${repoSlug}.md`);
+            const repoRelativePath = `repos/${repoSlug}.md`;
+            await writeMarkdown(repoAbsolutePath, renderRepositoryPage({
+                repository,
+                workTypes: [...repoWorkTypeMap.get(repoKey)],
+            }));
+            if (!contextDocs.some((entry) => entry.path === repoRelativePath)) {
+                contextDocs.push({
+                    label: repository.repository,
+                    path: repoRelativePath,
+                });
+            }
+        }
+        const workTypeRelativePath = `work-types/${workTypeSlug}.md`;
+        await writeMarkdown(join(home.workTypesDir, `${workTypeSlug}.md`), renderWorkTypePage({
+            workType,
+            procedureLinks,
+        }));
+        workTypeEntries.push({
+            label: workType.name,
+            path: workTypeRelativePath,
+        });
+        contextDocs.push({
+            label: workType.name,
+            path: workTypeRelativePath,
+        });
+    }
+    for (const entry of domainLanguage) {
+        const slug = slugify(entry.term);
+        const relativePath = `domain-language/${slug}.md`;
+        await writeMarkdown(join(home.domainLanguageDir, `${slug}.md`), renderDomainLanguagePage(entry));
+        domainEntries.push({
+            label: entry.term,
+            path: relativePath,
+        });
+        contextDocs.push({
+            label: entry.term,
+            path: relativePath,
+        });
+    }
+    await writeMarkdown(home.indexPath, renderIndex({
+        primaryRoleSummary,
+        workTypeEntries,
+        domainEntries,
+    }));
+    return {
+        indexPath: home.indexPath,
+        contextDocs,
+    };
+}

package/dist/core/context/global-knowledge-updates.js

@@ -0,0 +1,116 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { parseIndexDocument } from './index-resolver.js';
+import { getGlobalContextHome } from '../settings/global-context-home.js';
+const ELIGIBLE_GLOBAL_UPDATE_KINDS = new Set([
+    'work-type',
+    'domain-language',
+]);
+function slugify(value) {
+    return String(value || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '') || 'context';
+}
+function timestampPrefix(now = new Date()) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
+async function backupIfPresent(path) {
+    const home = getGlobalContextHome();
+    const current = await readFile(path, 'utf8').catch(() => '');
+    if (!current)
+        return;
+    await mkdir(home.backupsDir, { recursive: true });
+    await writeFile(join(home.backupsDir, `${timestampPrefix()}-${basename(path)}`), current, 'utf8');
+}
+async function upsertIndexEntry(entry) {
+    const home = getGlobalContextHome();
+    const raw = await readFile(home.indexPath, 'utf8').catch(() => '# Shift AX Global Index\n\n## Work Types\n\n- None yet.\n\n## Domain Language\n\n- None yet.\n');
+    const entries = parseIndexDocument(raw).filter((current) => current.label !== entry.label);
+    entries.push(entry);
+    const workTypeEntries = entries.filter((current) => current.path.startsWith('work-types/'));
+    const domainEntries = entries.filter((current) => current.path.startsWith('domain-language/'));
+    const rendered = [
+        '# Shift AX Global Index',
+        '',
+        '## Work Types',
+        '',
+        ...(workTypeEntries.length > 0 ? workTypeEntries.map((item) => `- ${item.label} -> ${item.path}`) : ['- None yet.']),
+        '',
+        '## Domain Language',
+        '',
+        ...(domainEntries.length > 0 ? domainEntries.map((item) => `- ${item.label} -> ${item.path}`) : ['- None yet.']),
+        '',
+    ].join('\n');
+    await backupIfPresent(home.indexPath);
+    await mkdir(home.root, { recursive: true });
+    await writeFile(home.indexPath, `${rendered.trimEnd()}\n`, 'utf8');
+}
+function parseGlobalKnowledgeUpdates(markdown, source) {
+    const lines = String(markdown || '').split(/\r?\n/);
+    const updates = [];
+    let inSection = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (/^##\s+Global Knowledge Updates$/i.test(trimmed)) {
+            inSection = true;
+            continue;
+        }
+        if (inSection && /^##\s+/.test(trimmed)) {
+            break;
+        }
+        if (!inSection || !trimmed.startsWith('-'))
+            continue;
+        const body = trimmed.slice(1).trim();
+        if (/^none/i.test(body))
+            continue;
+        const match = body.match(/^(work-type|domain-language):\s*(.+?)\s*->\s*(.+)$/i);
+        if (!match)
+            continue;
+        updates.push({
+            kind: match[1].toLowerCase(),
+            label: match[2].trim(),
+            content: match[3].trim(),
+            source,
+        });
+    }
+    return updates;
+}
+export async function applyGlobalKnowledgeUpdatesFromArtifacts({ brainstormContent, specContent, implementationPlanContent, }) {
+    const updates = [
+        ...parseGlobalKnowledgeUpdates(brainstormContent ?? '', 'brainstorm.md'),
+        ...parseGlobalKnowledgeUpdates(specContent ?? '', 'spec.md'),
+        ...parseGlobalKnowledgeUpdates(implementationPlanContent ?? '', 'implementation-plan.md'),
+    ];
+    const unique = new Map();
+    for (const update of updates) {
+        unique.set(`${update.kind}:${update.label}`, update);
+    }
+    const home = getGlobalContextHome();
+    const applied = [...unique.values()];
+    for (const update of applied) {
+        if (!ELIGIBLE_GLOBAL_UPDATE_KINDS.has(update.kind)) {
+            continue;
+        }
+        const slug = slugify(update.label);
+        const relativePath = update.kind === 'work-type' ? `work-types/${slug}.md` : `domain-language/${slug}.md`;
+        const absolutePath = update.kind === 'work-type'
+            ? join(home.workTypesDir, `${slug}.md`)
+            : join(home.domainLanguageDir, `${slug}.md`);
+        const markdown = update.kind === 'work-type'
+            ? `# ${update.label}\n\n## Stable Guidance\n\n${update.content}\n\n## Source\n\n- ${update.source}\n`
+            : `# ${update.label}\n\n${update.content}\n\n## Source\n\n- ${update.source}\n`;
+        await backupIfPresent(absolutePath);
+        await mkdir(update.kind === 'work-type' ? home.workTypesDir : home.domainLanguageDir, {
+            recursive: true,
+        });
+        await writeFile(absolutePath, markdown, 'utf8');
+        await upsertIndexEntry({
+            label: update.label,
+            path: relativePath,
+        });
+    }
+    return applied;
+}