@tea-agent/loop-agent 0.1.0

package/dist/executors/shell-write-guard.js

@@ -0,0 +1,126 @@
+import { spawn } from "node:child_process";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+export function snapshotGitStatusPorcelain(porcelain) {
+    const snapshot = new Map();
+    for (const line of porcelain.split("\n")) {
+        const trimmed = line.trimEnd();
+        if (!trimmed)
+            continue;
+        const x = trimmed[0] ?? " ";
+        const y = trimmed[1] ?? " ";
+        const rawPath = trimmed.slice(3);
+        const path = normalizeGitPath(rawPath);
+        snapshot.set(path, `${x}${y}`);
+    }
+    return snapshot;
+}
+export function pathsChangedDuringRun(before, after) {
+    const changed = new Set();
+    for (const [filePath, afterCode] of after) {
+        const beforeCode = before.get(filePath);
+        if (beforeCode === undefined || beforeCode !== afterCode) {
+            changed.add(filePath);
+        }
+    }
+    for (const filePath of before.keys()) {
+        if (!after.has(filePath)) {
+            changed.add(filePath);
+        }
+    }
+    return Array.from(changed).sort();
+}
+const DAG_RUNS_PREFIX = ".harness/dag-runs/";
+/** MVP post-run guard: only paths that changed during the shell node are checked. */
+export function validateShellWriteGuard(input) {
+    const violations = [];
+    const writePolicy = input.writePolicy ?? "read-only";
+    const writeSet = input.writeSet ?? [];
+    const allowedPaths = input.allowedPaths ?? [];
+    const forbiddenPaths = input.forbiddenPaths ?? [];
+    for (const rawPath of input.changedPaths) {
+        const filePath = normalizePath(rawPath);
+        if (filePath.startsWith(DAG_RUNS_PREFIX)) {
+            continue;
+        }
+        if (matchesAnyPattern(filePath, forbiddenPaths)) {
+            violations.push(filePath);
+            continue;
+        }
+        if (writePolicy === "read-only" || writePolicy === "none") {
+            violations.push(filePath);
+            continue;
+        }
+        if (writePolicy === "exclusive") {
+            if (writeSet.length > 0 && matchesAnyPattern(filePath, writeSet)) {
+                continue;
+            }
+            if (input.allowSiblingWriteSetAttribution === true &&
+                matchesAnySiblingWriteSet(filePath, input.concurrentSiblingWriteSets ?? [])) {
+                continue;
+            }
+            violations.push(filePath);
+            continue;
+        }
+        if (allowedPaths.length > 0 && !matchesAnyPattern(filePath, allowedPaths)) {
+            violations.push(filePath);
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}
+export async function readGitStatusPorcelain(cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["status", "--porcelain=v1", "--untracked-files=all"], {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf-8");
+        child.stderr.setEncoding("utf-8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve(stdout);
+                return;
+            }
+            reject(new Error(`git status failed: ${stderr.trim() || stdout.trim()}`));
+        });
+    });
+}
+export async function runPostRunWriteGuard(input) {
+    const afterStatus = await readGitStatusPorcelain(input.rootCwd);
+    const beforeSnapshot = snapshotGitStatusPorcelain(input.beforeStatus);
+    const afterSnapshot = snapshotGitStatusPorcelain(afterStatus);
+    const changedPaths = pathsChangedDuringRun(beforeSnapshot, afterSnapshot);
+    return validateShellWriteGuard({
+        changedPaths,
+        writePolicy: input.writePolicy,
+        writeSet: input.writeSet,
+        allowedPaths: input.allowedPaths,
+        forbiddenPaths: input.forbiddenPaths,
+        concurrentSiblingWriteSets: input.concurrentSiblingWriteSets,
+        allowSiblingWriteSetAttribution: input.writePolicy === "exclusive" &&
+            (input.concurrentSiblingWriteSets?.length ?? 0) > 0,
+    });
+}
+function matchesAnyPattern(filePath, patterns) {
+    return patterns.some((pattern) => pathMatchesPattern(filePath, pattern));
+}
+function matchesAnySiblingWriteSet(filePath, siblingWriteSets) {
+    return siblingWriteSets.some((writeSet) => writeSet.length > 0 && matchesAnyPattern(filePath, writeSet));
+}
+function normalizeGitPath(value) {
+    const target = value.includes(" -> ")
+        ? (value.split(" -> ").at(-1) ?? value)
+        : value;
+    return normalizePath(target);
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}

package/dist/executors/shell.js

@@ -0,0 +1,3 @@
+export * from "./shell-executor.js";
+export * from "./shell-presets.js";
+export * from "./shell-write-guard.js";

package/dist/executors/static.js

@@ -0,0 +1 @@
+export * from "./dag-static-executor.js";

package/dist/governance/checks.js

@@ -0,0 +1,434 @@
+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, shouldRunRetrospective } 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，但验证工件未标记完成',
+                });
+            }
+            if (state.status === 'completed' && shouldRunRetrospective(taskConfig) && !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/harness.js

@@ -0,0 +1,9 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { harnessManifestSchema } from '../shared/types.js';
+export async function loadHarnessManifest(repoRoot) {
+    const manifestPath = path.join(repoRoot, 'harness.json');
+    const raw = await readFile(manifestPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return harnessManifestSchema.parse(parsed);
+}

package/dist/governance/index.js

@@ -0,0 +1,3 @@
+export * from "./manifest.js";
+export * from "./profiles.js";
+export * from "./path-guards.js";