@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/governance/checks.js

@@ -0,0 +1,437 @@
+import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { repoRelativePath } from '../shared/path-refs.js';
+import { loadHarnessManifest } from './harness.js';
+import { auditLoopAgentSkillSafety } from './skill-safety.js';
+import { getTaskPaths, getTaskStatus, loadTaskConfig } from '../task/runtime.js';
+import { buildTaskReadModel } from '../task/read-model.js';
+const SKIP_DIRS = new Set([
+    '.git',
+    '.harness',
+    'node_modules',
+    'dist',
+    'coverage',
+]);
+export async function resolveGovernancePaths(repoRoot) {
+    const manifest = await loadHarnessManifest(repoRoot);
+    const governanceRoot = path.join(repoRoot, manifest.governanceRoot);
+    const execPlansDir = path.join(repoRoot, manifest.artifacts.execPlansDir ?? path.join(manifest.governanceRoot, 'exec-plans'));
+    return {
+        readmePath: path.join(repoRoot, manifest.entrypoints.readme ?? 'README.md'),
+        governanceRoot,
+        governanceIndexPath: manifest.entrypoints.governanceIndex
+            ? path.join(repoRoot, manifest.entrypoints.governanceIndex)
+            : null,
+        execPlansDir,
+        activePlansDir: path.join(execPlansDir, 'active'),
+        completedPlansDir: path.join(execPlansDir, 'completed'),
+    };
+}
+export async function listActivePlans(repoRoot) {
+    const paths = await resolveGovernancePaths(repoRoot);
+    const entries = await safeReadDir(paths.activePlansDir);
+    const plans = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md') || entry.name === 'README.md')
+            continue;
+        const absolutePath = path.join(paths.activePlansDir, entry.name);
+        const content = await readFile(absolutePath, 'utf-8');
+        plans.push({
+            file: entry.name,
+            relativePath: toRepoRelative(repoRoot, absolutePath),
+            title: extractTitle(content) ?? entry.name,
+            statusLine: extractStatusLine(content),
+            normalizedStatus: normalizeStatus(extractStatusLine(content)),
+        });
+    }
+    return plans.sort((a, b) => a.file.localeCompare(b.file));
+}
+export async function auditDocs(repoRoot) {
+    const paths = await resolveGovernancePaths(repoRoot);
+    const manifest = await loadHarnessManifest(repoRoot);
+    const issues = [];
+    const plans = await listActivePlans(repoRoot);
+    for (const plan of plans) {
+        if (plan.normalizedStatus !== 'active') {
+            issues.push({
+                type: 'active-status-mismatch',
+                severity: 'warning',
+                file: plan.relativePath,
+                message: `active 目录中的计划状态为 ${plan.statusLine ?? 'unknown'}，建议迁入 completed/ 或修正文档状态`,
+            });
+        }
+    }
+    for (const [name, entry] of Object.entries(manifest.entrypoints ?? {})) {
+        if (!entry || !entry.endsWith('.md'))
+            continue;
+        const target = path.join(repoRoot, entry);
+        if (!await exists(target)) {
+            issues.push({
+                type: 'missing-harness-entrypoint',
+                severity: 'error',
+                file: 'harness.json',
+                message: `entrypoints.${name} 指向缺失文档：${entry}`,
+            });
+        }
+    }
+    const markdownFiles = await listMarkdownFiles(repoRoot);
+    for (const markdownFile of markdownFiles) {
+        const content = await readFile(markdownFile, 'utf-8');
+        for (const link of extractMarkdownLinks(content)) {
+            if (!isLocalMarkdownLink(link))
+                continue;
+            const resolved = path.resolve(path.dirname(markdownFile), stripAnchor(link));
+            if (!await exists(resolved)) {
+                issues.push({
+                    type: 'missing-link-target',
+                    severity: 'error',
+                    file: toRepoRelative(repoRoot, markdownFile),
+                    message: `存在失效文档链接：${link}`,
+                });
+            }
+        }
+        const relative = toRepoRelative(repoRoot, markdownFile);
+        if (path.basename(markdownFile).startsWith('aimax-memory-plugin-host-gap-')
+            && /Closeout/i.test(content)
+            && /(已不再是宿主阻塞项|已完成能力|closeout)/i.test(content)) {
+            issues.push({
+                type: 'host-gap-closeout',
+                severity: 'warning',
+                file: relative,
+                message: '该 host-gap 文档内容已 closeout，建议重命名或降级为历史记录入口',
+            });
+        }
+    }
+    const skillSafety = await auditLoopAgentSkillSafety(repoRoot);
+    for (const finding of skillSafety.findings) {
+        issues.push({
+            type: `skill-safety:${finding.ruleId}`,
+            severity: finding.severity,
+            file: `${finding.file}:${finding.line}`,
+            message: `${finding.message}: ${finding.snippet}`,
+        });
+    }
+    return {
+        governanceRoot: toRepoRelative(repoRoot, paths.governanceRoot),
+        issues,
+        plans,
+        summary: {
+            activePlanCount: plans.length,
+            issueCount: issues.length,
+            errorCount: issues.filter((issue) => issue.severity === 'error').length,
+            warningCount: issues.filter((issue) => issue.severity === 'warning').length,
+        },
+    };
+}
+export async function archivePlan(repoRoot, inputPath) {
+    const paths = await resolveGovernancePaths(repoRoot);
+    const sourcePath = await resolveArchiveSourcePath(repoRoot, paths.activePlansDir, inputPath);
+    const destinationPath = path.join(paths.completedPlansDir, path.basename(sourcePath));
+    await mkdir(paths.completedPlansDir, { recursive: true });
+    const sourceContent = await readFile(sourcePath, 'utf-8');
+    const archivedContent = ensureArchiveMetadata(normalizeArchivedStatus(sourceContent), path.basename(sourcePath));
+    await writeFile(destinationPath, archivedContent, 'utf-8');
+    await rm(sourcePath, { force: true });
+    const oldRelativePath = toRepoRelative(repoRoot, sourcePath);
+    const newRelativePath = toRepoRelative(repoRoot, destinationPath);
+    const updatedFiles = await rewriteMarkdownReferences(repoRoot, oldRelativePath, newRelativePath);
+    const activeIndexPath = path.join(paths.activePlansDir, 'README.md');
+    if (await exists(activeIndexPath)) {
+        const activeIndex = await readFile(activeIndexPath, 'utf-8');
+        const rewritten = activeIndex
+            .split(/\r?\n/)
+            .filter((line) => !line.includes(`(${path.basename(sourcePath)})`) && !line.includes(path.basename(sourcePath)))
+            .join('\n')
+            .replace(/\n{3,}/g, '\n\n');
+        if (rewritten !== activeIndex) {
+            await writeFile(activeIndexPath, rewritten.trimEnd() + '\n', 'utf-8');
+            updatedFiles.push(toRepoRelative(repoRoot, activeIndexPath));
+        }
+    }
+    const completedIndexPath = path.join(paths.completedPlansDir, 'README.md');
+    if (await exists(completedIndexPath)) {
+        const completedIndex = await readFile(completedIndexPath, 'utf-8');
+        const marker = `- [${path.basename(destinationPath)}](${path.basename(destinationPath)})`;
+        if (!completedIndex.includes(marker)) {
+            const next = appendArchivedMarker(completedIndex, marker);
+            await writeFile(completedIndexPath, next, 'utf-8');
+            updatedFiles.push(toRepoRelative(repoRoot, completedIndexPath));
+        }
+    }
+    return {
+        from: oldRelativePath,
+        to: newRelativePath,
+        updatedFiles: Array.from(new Set(updatedFiles)).sort(),
+    };
+}
+export async function checkTaskHandoff(repoRoot, taskId) {
+    const tasksDir = path.join(repoRoot, '.harness', 'tasks');
+    const taskIds = taskId ? [taskId] : await listTaskIds(tasksDir);
+    const tasks = [];
+    for (const currentTaskId of taskIds) {
+        const issues = [];
+        try {
+            const state = await getTaskStatus(repoRoot, currentTaskId);
+            const taskConfig = await loadTaskConfig(repoRoot, currentTaskId);
+            const taskPaths = getTaskPaths(repoRoot, currentTaskId);
+            const readModel = await buildTaskReadModel(repoRoot, currentTaskId);
+            const requirementPath = path.join(taskPaths.sourceDir, '需求.md');
+            const constraintPath = path.join(taskPaths.sourceDir, '执行约束.md');
+            if (!await exists(requirementPath)) {
+                issues.push({
+                    type: 'missing-requirement',
+                    severity: 'error',
+                    file: toRepoRelative(repoRoot, requirementPath),
+                    message: '缺少 source/需求.md',
+                });
+            }
+            if (!await exists(constraintPath)) {
+                issues.push({
+                    type: 'missing-constraint',
+                    severity: 'error',
+                    file: toRepoRelative(repoRoot, constraintPath),
+                    message: '缺少 source/执行约束.md',
+                });
+            }
+            if (taskConfig.autoCommitAfterVerify && taskConfig.allowedPaths.length === 0) {
+                issues.push({
+                    type: 'unsafe-auto-commit-scope',
+                    severity: 'warning',
+                    file: toRepoRelative(repoRoot, taskPaths.taskConfigPath),
+                    message: 'autoCommitAfterVerify=true 但 allowedPaths 为空，后续自动提交范围可能过宽',
+                });
+            }
+            const executorLogPath = path.join(taskPaths.logsDir, 'executor.jsonl');
+            const decisionLogPath = path.join(taskPaths.logsDir, 'decisions.jsonl');
+            const modifyLogPath = path.join(taskPaths.taskDir, 'artifacts', '修改记录.md');
+            if (state.decisionLog.length === 0) {
+                issues.push({
+                    type: 'missing-decision-log',
+                    severity: 'warning',
+                    file: toRepoRelative(repoRoot, decisionLogPath),
+                    message: '任务尚未记录结构化 decision log',
+                });
+            }
+            if (!await exists(executorLogPath)) {
+                issues.push({
+                    type: 'missing-executor-log',
+                    severity: 'warning',
+                    file: toRepoRelative(repoRoot, executorLogPath),
+                    message: '缺少 logs/executor.jsonl',
+                });
+            }
+            if (!await exists(decisionLogPath)) {
+                issues.push({
+                    type: 'missing-decision-log-file',
+                    severity: 'warning',
+                    file: toRepoRelative(repoRoot, decisionLogPath),
+                    message: '缺少 logs/decisions.jsonl',
+                });
+            }
+            if (state.sourceState.stalePlan) {
+                issues.push({
+                    type: 'stale-plan',
+                    severity: state.currentStep === 'implement' || state.status === 'active' ? 'error' : 'warning',
+                    file: toRepoRelative(repoRoot, taskPaths.statePath),
+                    message: 'source materials 已变更，但最近一次 plan/spec baseline 未更新',
+                });
+            }
+            if (state.status === 'completed' && !state.artifacts.verifyResult) {
+                issues.push({
+                    type: 'missing-verify-artifact',
+                    severity: 'error',
+                    file: toRepoRelative(repoRoot, path.join(taskPaths.taskDir, 'artifacts', '验证结果.md')),
+                    message: '任务已 completed，但验证工件未标记完成',
+                });
+            }
+            // Standard DAG tasks do not require a retrospective artifact. Preserve an
+            // explicit legacy task contract, however, so historical tasks that opted
+            // into requireRetrospective do not silently lose their handoff warning.
+            if (state.status === 'completed' && taskConfig.requireRetrospective && !state.artifacts.retrospective) {
+                issues.push({
+                    type: 'missing-retrospective-artifact',
+                    severity: 'warning',
+                    file: toRepoRelative(repoRoot, path.join(taskPaths.taskDir, 'artifacts', '复盘报告.md')),
+                    message: '任务显式要求 retrospective，但复盘工件未完成',
+                });
+            }
+            if (readModel.promotion.required && !readModel.promotion.ready) {
+                issues.push({
+                    type: 'missing-promotion-artifacts',
+                    severity: 'error',
+                    file: toRepoRelative(repoRoot, path.join(taskPaths.taskDir, 'artifacts')),
+                    message: '已存在 completed DAG/one-shot run evidence，但任务工件尚未完成 promotion',
+                });
+            }
+            if (readModel.promotion.ready && !readModel.closeout.exists) {
+                issues.push({
+                    type: 'missing-closeout-record',
+                    severity: 'warning',
+                    file: toRepoRelative(repoRoot, readModel.closeout.path),
+                    message: '任务工件已 promotion，但缺少 docs/progress closeout 记录',
+                });
+            }
+            if (state.artifacts.modifyLog && await exists(modifyLogPath)) {
+                const modifyLog = (await readFile(modifyLogPath, 'utf-8')).trim();
+                if (modifyLog === '# 修改记录\n\n## 1. 修改文件清单\n\n## 2. 关键改动说明') {
+                    issues.push({
+                        type: 'empty-modify-log',
+                        severity: 'warning',
+                        file: toRepoRelative(repoRoot, modifyLogPath),
+                        message: '修改记录仍是模板内容，尚未写入实际改动说明',
+                    });
+                }
+            }
+            tasks.push({
+                taskId: currentTaskId,
+                status: state.status,
+                issues,
+            });
+        }
+        catch (error) {
+            issues.push({
+                type: 'task-load-failed',
+                severity: 'error',
+                file: path.join('.harness', 'tasks', currentTaskId),
+                message: error instanceof Error ? error.message : String(error),
+            });
+            tasks.push({
+                taskId: currentTaskId,
+                status: 'unknown',
+                issues,
+            });
+        }
+    }
+    const flatIssues = tasks.flatMap((task) => task.issues);
+    return {
+        tasks,
+        summary: {
+            taskCount: tasks.length,
+            issueCount: flatIssues.length,
+            errorCount: flatIssues.filter((issue) => issue.severity === 'error').length,
+            warningCount: flatIssues.filter((issue) => issue.severity === 'warning').length,
+        },
+    };
+}
+function extractTitle(content) {
+    const match = content.match(/^#\s+(.+)$/m);
+    return match?.[1]?.trim() ?? null;
+}
+function extractStatusLine(content) {
+    const match = content.match(/^## 状态\s*\n\s*\n([^\n]+)$/m);
+    return match?.[1]?.trim() ?? null;
+}
+function normalizeStatus(statusLine) {
+    if (!statusLine)
+        return 'unknown';
+    const value = statusLine.replace(/^- /, '').trim();
+    if (value.startsWith('active'))
+        return 'active';
+    if (value.startsWith('completed'))
+        return 'completed';
+    if (value.startsWith('blocked'))
+        return 'blocked';
+    if (value.startsWith('draft'))
+        return 'draft';
+    return 'unknown';
+}
+function normalizeArchivedStatus(content) {
+    return content.replace(/^## 状态\s*\n\s*\n([^\n]+)$/m, (_whole, line) => `## 状态\n\n${line.replace(/^-\s*active\b/, '- completed').replace(/^active\b/, 'completed')}`);
+}
+function ensureArchiveMetadata(content, fileName) {
+    if (content.includes('## 归档说明'))
+        return content;
+    const replacement = `## 状态\n\n- completed\n\n## 归档说明\n\n- 由 \`loop-agent docs archive\` 自动归档\n- 归档文件：\`${fileName}\`\n`;
+    if (/^## 状态\s*\n\s*\n[^\n]+$/m.test(content)) {
+        return content.replace(/^## 状态\s*\n\s*\n[^\n]+$/m, replacement);
+    }
+    return `${content.trimEnd()}\n\n## 归档说明\n\n- 由 \`loop-agent docs archive\` 自动归档\n- 归档文件：\`${fileName}\`\n`;
+}
+async function rewriteMarkdownReferences(repoRoot, oldRelativePath, newRelativePath) {
+    const markdownFiles = await listMarkdownFiles(repoRoot);
+    const updatedFiles = [];
+    for (const markdownFile of markdownFiles) {
+        const original = await readFile(markdownFile, 'utf-8');
+        const rewritten = original.replaceAll(oldRelativePath, newRelativePath);
+        if (rewritten !== original) {
+            await writeFile(markdownFile, rewritten, 'utf-8');
+            updatedFiles.push(toRepoRelative(repoRoot, markdownFile));
+        }
+    }
+    return updatedFiles;
+}
+function appendArchivedMarker(content, marker) {
+    const header = '## Recently Archived';
+    if (content.includes(header)) {
+        return content.replace(header, `${header}\n\n${marker}`);
+    }
+    return `${content.trimEnd()}\n\n${header}\n\n${marker}\n`;
+}
+async function resolveArchiveSourcePath(repoRoot, activePlansDir, inputPath) {
+    if (path.isAbsolute(inputPath))
+        return inputPath;
+    if (inputPath.includes('/'))
+        return path.resolve(repoRoot, inputPath);
+    return path.join(activePlansDir, inputPath);
+}
+async function listTaskIds(tasksDir) {
+    const entries = await safeReadDir(tasksDir);
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+async function listMarkdownFiles(root) {
+    const files = [];
+    await walk(root, files);
+    return files.sort();
+}
+async function walk(targetDir, files) {
+    const entries = await safeReadDir(targetDir);
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            await walk(path.join(targetDir, entry.name), files);
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+            files.push(path.join(targetDir, entry.name));
+        }
+    }
+}
+function extractMarkdownLinks(content) {
+    const links = [];
+    const pattern = /\[[^\]]+\]\(([^)]+)\)/g;
+    for (const match of content.matchAll(pattern)) {
+        if (match[1])
+            links.push(match[1]);
+    }
+    return links;
+}
+function isLocalMarkdownLink(link) {
+    if (link.startsWith('http://') || link.startsWith('https://') || link.startsWith('mailto:') || link.startsWith('#')) {
+        return false;
+    }
+    return stripAnchor(link).endsWith('.md');
+}
+function stripAnchor(link) {
+    return link.split('#')[0] ?? link;
+}
+async function exists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeReadDir(targetPath) {
+    try {
+        return await readdir(targetPath, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function toRepoRelative(repoRoot, absolutePath) {
+    return repoRelativePath(repoRoot, absolutePath);
+}

package/dist/governance/document-index-closure.js

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+function normalizePath(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function isConcreteRepoRelativePath(value) {
+    const normalized = normalizePath(value);
+    if (!normalized)
+        return false;
+    if (normalized === "." ||
+        normalized === "**" ||
+        normalized === "*" ||
+        normalized === "/*") {
+        return false;
+    }
+    if (normalized.includes("**") || normalized.includes("*"))
+        return false;
+    if (path.isAbsolute(normalized) || /^[A-Za-z]:\//.test(normalized))
+        return false;
+    if (normalized.split("/").some((segment) => segment === ".."))
+        return false;
+    return true;
+}
+function assertValidDirectoryIndexRule(rule, indexLabel) {
+    if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+        throw new Error(`document-index-closure: invalid completeDirectoryIndexes entry at ${indexLabel}`);
+    }
+    const record = rule;
+    if (typeof record.directory !== "string" ||
+        record.directory.trim().length === 0) {
+        throw new Error(`document-index-closure: completeDirectoryIndexes[${indexLabel}].directory must be a non-empty string`);
+    }
+    if (typeof record.index !== "string" || record.index.trim().length === 0) {
+        throw new Error(`document-index-closure: completeDirectoryIndexes[${indexLabel}].index must be a non-empty string`);
+    }
+    const directory = normalizePath(record.directory);
+    const index = normalizePath(record.index);
+    if (!isConcreteRepoRelativePath(directory)) {
+        throw new Error(`document-index-closure: completeDirectoryIndexes[${indexLabel}].directory must be a concrete repo-relative path (got "${record.directory}")`);
+    }
+    if (!isConcreteRepoRelativePath(index)) {
+        throw new Error(`document-index-closure: completeDirectoryIndexes[${indexLabel}].index must be a concrete repo-relative path without globs (got "${record.index}")`);
+    }
+    return { directory, index };
+}
+/**
+ * Load completeDirectoryIndexes from docs/document-catalog.json only.
+ * Does not hard-code a second directory table.
+ */
+export function loadCompleteDirectoryIndexes(repoRoot) {
+    const catalogPath = path.join(repoRoot, "docs", "document-catalog.json");
+    // The catalog is an opt-in governance surface. Projects that have not
+    // initialized it must still be able to generate DAGs for docs paths.
+    if (!existsSync(catalogPath))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(catalogPath, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`document-index-closure: failed to read docs/document-catalog.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`document-index-closure: docs/document-catalog.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("document-index-closure: docs/document-catalog.json root must be an object");
+    }
+    const rulesRaw = parsed
+        .completeDirectoryIndexes;
+    if (rulesRaw === undefined) {
+        return [];
+    }
+    if (!Array.isArray(rulesRaw)) {
+        throw new Error("document-index-closure: completeDirectoryIndexes must be an array when present");
+    }
+    return rulesRaw.map((rule, index) => assertValidDirectoryIndexRule(rule, String(index)));
+}
+function candidateDirectoryPrefixes(candidatePath) {
+    const normalized = normalizePath(candidatePath);
+    if (!normalized)
+        return [];
+    // Treat trailing /** globs as directory roots for prefix matching.
+    const withoutGlob = normalized
+        .replace(/\/\*\*$/, "")
+        .replace(/\/\*$/, "")
+        .replace(/\*\*$/, "")
+        .replace(/\*$/, "");
+    const base = normalizePath(withoutGlob);
+    if (!base || base === "." || base === "**")
+        return [];
+    const segments = base.split("/").filter(Boolean);
+    const prefixes = [];
+    for (let i = segments.length; i >= 1; i -= 1) {
+        prefixes.push(segments.slice(0, i).join("/"));
+    }
+    return prefixes;
+}
+function longestMatchingRule(candidatePath, rules) {
+    const prefixes = new Set(candidateDirectoryPrefixes(candidatePath));
+    if (prefixes.size === 0)
+        return undefined;
+    let best;
+    for (const rule of rules) {
+        if (!prefixes.has(rule.directory) &&
+            !candidateUnderDirectory(candidatePath, rule.directory)) {
+            continue;
+        }
+        if (!best || rule.directory.length > best.directory.length) {
+            best = rule;
+        }
+    }
+    return best;
+}
+function candidateUnderDirectory(candidatePath, directory) {
+    const normalized = normalizePath(candidatePath)
+        .replace(/\/\*\*$/, "")
+        .replace(/\/\*$/, "");
+    const dir = normalizePath(directory);
+    return normalized === dir || normalized.startsWith(`${dir}/`);
+}
+/**
+ * Derive concrete companion index paths for candidate docs paths using catalog rules.
+ * Longest directory prefix wins. Throws fail-closed on forbidden conflicts.
+ */
+export function resolveDocumentIndexCompanions(input) {
+    const forbidden = input.forbiddenPaths ?? [];
+    const companions = new Set();
+    for (const candidate of input.candidatePaths) {
+        const rule = longestMatchingRule(candidate, input.rules);
+        if (!rule)
+            continue;
+        const indexPath = rule.index;
+        if (forbidden.some((pattern) => pathMatchesPattern(indexPath, pattern))) {
+            throw new Error(`document-index-closure: companion index "${indexPath}" for "${candidate}" conflicts with forbiddenPaths`);
+        }
+        companions.add(indexPath);
+    }
+    return [...companions].sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Convenience: load catalog and merge companion indexes into path lists.
+ */
+export function mergeDocumentIndexCompanions(input) {
+    const rules = loadCompleteDirectoryIndexes(input.repoRoot);
+    const companions = resolveDocumentIndexCompanions({
+        candidatePaths: input.paths,
+        rules,
+        forbiddenPaths: input.forbiddenPaths,
+    });
+    const merged = new Set(input.paths.map(normalizePath));
+    for (const companion of companions) {
+        merged.add(companion);
+    }
+    return {
+        paths: [...merged],
+        companions,
+    };
+}