@tea-agent/loop-agent 0.1.0

package/dist/governance/skill-safety.js

@@ -0,0 +1,135 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+const NEGATION_PATTERN = /\b(?:do not|don't|must not|never|cannot|should not|not|no|without|禁止|不得|不要|不能|不可)\b|不\s*(?:mutate|修改|重写|删除|覆盖|绕过|跳过)/i;
+const CREDENTIAL_PATTERN = /(?:api[\s_-]?key|token|password|credential|secret|密钥|令牌|凭据|密码)/i;
+const SKILL_SAFETY_RULES = [
+    {
+        id: "learned-shell-command",
+        message: "learned guidance must not add shell or runtime commands",
+        profiles: ["learned"],
+        patterns: [
+            /^```/,
+            /^\s*\$\s*\S+/,
+            /^\s*(?:bash|sh|zsh|npm|pnpm|yarn|node|python|python3|curl|chmod|sudo|git)\b/i,
+        ],
+    },
+    {
+        id: "credential-handling",
+        message: "skill guidance must not request credential handling or disclosure",
+        profiles: ["policy", "learned"],
+        patterns: [
+            new RegExp(`\\b(?:read|print|echo|export|send|upload|store|ask\\s+for|prompt\\s+for|collect|handle|rotate|change)\\b.{0,48}${CREDENTIAL_PATTERN.source}`, "i"),
+            new RegExp(`${CREDENTIAL_PATTERN.source}.{0,48}\\b(?:read|print|echo|export|send|upload|store|ask\\s+for|prompt\\s+for|collect|handle|rotate|change)\\b`, "i"),
+        ],
+    },
+    {
+        id: "permission-expansion",
+        message: "skill guidance must not expand tools, permissions, or path allowlists",
+        profiles: ["policy", "learned"],
+        patterns: [
+            /\b(?:grant|expand|enable|add|relax|broaden)\b.{0,40}\b(?:tools?|permissions?|allowlists?|allowedPaths|forbiddenPaths|writeSet|权限|工具|白名单)\b/i,
+            /\b--tools\b.{0,40}\b(?:write|shell|exec|all)\b/i,
+        ],
+    },
+    {
+        id: "completion-authority-bypass",
+        message: "skill guidance must not bypass verification, gates, or completion authority",
+        profiles: ["policy", "learned"],
+        patterns: [
+            /\b(?:skip|bypass|disable|ignore)\b.{0,40}\b(?:verification|tests?|guards?|gates?|human gate|decision gate|write guard|shell verification|验证|测试|门禁)\b/i,
+            /\bcomplete(?:d|ion)?\b.{0,40}\bwithout\b.{0,40}\b(?:verification|tests?|evidence|gate)\b/i,
+            /\b(?:always|auto(?:matically)?)\b.{0,40}\b(?:accept|approve|complete|mark complete)\b/i,
+        ],
+    },
+    {
+        id: "completed-facts-mutation",
+        message: "skill guidance must not mutate completed DAG or one-shot run facts",
+        profiles: ["policy", "learned"],
+        patterns: [
+            /\b(?:modify|rewrite|edit|delete|overwrite|mutate)\b.{0,60}\b(?:completed DAG|completed run|one-shot run|run facts|dag-runs\/completed|runs\/completed)\b/i,
+        ],
+    },
+];
+function toRepoRelative(repoRoot, filePath) {
+    return path.relative(repoRoot, filePath).split(path.sep).join("/");
+}
+function isMarkdownFile(filePath) {
+    return filePath.endsWith(".md");
+}
+async function listMarkdownFiles(root) {
+    const files = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            if (entry.isFile() && isMarkdownFile(full)) {
+                files.push(full);
+            }
+        }
+    }
+    await walk(root);
+    return files.sort();
+}
+function profileForFile(filePath) {
+    if (path.basename(filePath) === "prompt-delta.md")
+        return "learned";
+    return filePath.split(path.sep).includes("learned") ? "learned" : "policy";
+}
+function shouldIgnoreLine(line) {
+    return NEGATION_PATTERN.test(line);
+}
+export function auditSkillMarkdownContent(input) {
+    const profile = input.profile ?? profileForFile(input.filePath);
+    const relative = toRepoRelative(input.repoRoot, input.filePath);
+    const findings = [];
+    input.content.split(/\r?\n/).forEach((line, index) => {
+        if (shouldIgnoreLine(line))
+            return;
+        for (const rule of SKILL_SAFETY_RULES) {
+            if (!rule.profiles.includes(profile))
+                continue;
+            if (!rule.patterns.some((pattern) => pattern.test(line)))
+                continue;
+            findings.push({
+                ruleId: rule.id,
+                severity: "error",
+                file: relative,
+                line: index + 1,
+                snippet: line.trim().slice(0, 160),
+                message: rule.message,
+            });
+        }
+    });
+    return findings;
+}
+export async function auditLoopAgentSkillSafety(repoRoot) {
+    const skillRoot = path.join(repoRoot, "skills", "loop-agent");
+    const harnessTasksRoot = path.join(repoRoot, ".harness", "tasks");
+    const skillFiles = await listMarkdownFiles(skillRoot);
+    const promptDeltaFiles = (await listMarkdownFiles(harnessTasksRoot)).filter((filePath) => path.basename(filePath) === "prompt-delta.md" &&
+        filePath.split(path.sep).includes("source"));
+    const files = [...skillFiles, ...promptDeltaFiles].sort();
+    const findings = [];
+    for (const filePath of files) {
+        const content = await readFile(filePath, "utf-8");
+        findings.push(...auditSkillMarkdownContent({ repoRoot, filePath, content }));
+    }
+    return {
+        root: `${toRepoRelative(repoRoot, skillRoot)} + .harness/tasks/*/source/prompt-delta.md`,
+        filesChecked: files.length,
+        findings,
+        summary: {
+            errorCount: findings.length,
+        },
+    };
+}

package/dist/governance/spine-audit.js

@@ -0,0 +1,152 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { resolveAdapter } from "../adapters/index.js";
+import { resolveVerifyPreset } from "../executors/shell-verification.js";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+import { getTaskPaths, loadTaskConfig } from "../task/runtime.js";
+import { formatRequirementCoverageMarkdown, requirementCoverageFailureReasons, runRequirementCoverageAudit, } from "./requirement-coverage.js";
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toRepoRelative(repoRoot, filePath) {
+    return path.relative(repoRoot, filePath).split(path.sep).join("/");
+}
+function probeForPattern(pattern) {
+    return pattern
+        .replace(/\\/g, "/")
+        .replace(/\/\*\*$/, "/_probe_")
+        .replace(/\*\*$/, "_probe_")
+        .replace(/\*/g, "_")
+        .replace(/^\.\//, "");
+}
+function patternsOverlap(left, right) {
+    const leftProbe = probeForPattern(left);
+    const rightProbe = probeForPattern(right);
+    return (pathMatchesPattern(leftProbe, right) ||
+        pathMatchesPattern(rightProbe, left) ||
+        leftProbe === rightProbe);
+}
+function isBroadAllowedPath(pattern) {
+    const normalized = pattern.replace(/\\/g, "/").replace(/^\.\//, "");
+    return normalized === "**" || normalized === "./**" || normalized === ".";
+}
+export async function runSpineAudit(repoRoot, taskId) {
+    const taskPaths = getTaskPaths(repoRoot, taskId);
+    const config = await loadTaskConfig(repoRoot, taskId);
+    const requirementPath = path.join(taskPaths.sourceDir, "需求.md");
+    const constraintsPath = path.join(taskPaths.sourceDir, "执行约束.md");
+    const findings = [];
+    if (!(await exists(requirementPath))) {
+        findings.push({
+            severity: "error",
+            type: "missing-source",
+            message: "missing source/需求.md",
+            evidence: [toRepoRelative(repoRoot, requirementPath)],
+        });
+    }
+    if (!(await exists(constraintsPath))) {
+        findings.push({
+            severity: "error",
+            type: "missing-source",
+            message: "missing source/执行约束.md",
+            evidence: [toRepoRelative(repoRoot, constraintsPath)],
+        });
+    }
+    if ((config.complexity === "medium" || config.complexity === "large") && config.allowedPaths.length === 0) {
+        findings.push({
+            severity: "error",
+            type: "empty-allowed-paths",
+            message: `${config.complexity} task requires non-empty allowedPaths`,
+        });
+    }
+    for (const allowed of config.allowedPaths) {
+        if (isBroadAllowedPath(allowed)) {
+            findings.push({
+                severity: config.complexity === "small" ? "warning" : "error",
+                type: "broad-allowed-paths",
+                message: `allowedPaths entry "${allowed}" is too broad for a spine-owned task`,
+            });
+        }
+        for (const forbidden of config.forbiddenPaths) {
+            if (patternsOverlap(allowed, forbidden)) {
+                findings.push({
+                    severity: "error",
+                    type: "allowed-forbidden-overlap",
+                    message: `allowedPaths entry "${allowed}" overlaps forbiddenPaths entry "${forbidden}"`,
+                });
+            }
+        }
+    }
+    const requirementCoverage = await runRequirementCoverageAudit(repoRoot, taskId);
+    for (const reason of requirementCoverageFailureReasons(requirementCoverage)) {
+        findings.push({
+            severity: "error",
+            type: "uncovered-requirement",
+            message: reason,
+        });
+    }
+    const adapter = await resolveAdapter(repoRoot);
+    const preset = resolveVerifyPreset(config.verifyPreset, config);
+    const verifyCommands = adapter.getVerifyCommands(repoRoot, {
+        preset,
+        quota: "full",
+        phase: "final",
+        taskConfig: config,
+    });
+    if (verifyCommands.length === 0) {
+        findings.push({
+            severity: "error",
+            type: "missing-verification",
+            message: "adapter returned no final verification commands",
+        });
+    }
+    return {
+        ok: findings.every((finding) => finding.severity !== "error"),
+        taskId,
+        extractedAt: new Date().toISOString(),
+        objectiveSource: toRepoRelative(repoRoot, requirementPath),
+        constraintsSource: toRepoRelative(repoRoot, constraintsPath),
+        allowedPaths: config.allowedPaths,
+        forbiddenPaths: config.forbiddenPaths,
+        verifyCommandLabels: verifyCommands.map((command) => command.label),
+        requirementCoverage,
+        findings,
+    };
+}
+export function formatSpineAuditMarkdown(audit) {
+    const lines = [
+        "# Minimal Spec Spine Audit",
+        "",
+        `- task: \`${audit.taskId}\``,
+        `- extractedAt: ${audit.extractedAt}`,
+        `- ok: ${audit.ok ? "yes" : "no"}`,
+        `- objective source: \`${audit.objectiveSource}\``,
+        `- constraints source: \`${audit.constraintsSource}\``,
+        `- allowedPaths: ${audit.allowedPaths.length > 0 ? audit.allowedPaths.join(", ") : "(empty)"}`,
+        `- forbiddenPaths: ${audit.forbiddenPaths.length > 0 ? audit.forbiddenPaths.join(", ") : "(empty)"}`,
+        `- final verification: ${audit.verifyCommandLabels.length > 0 ? audit.verifyCommandLabels.join(", ") : "(empty)"}`,
+        "",
+        "## Findings",
+        "",
+    ];
+    if (audit.findings.length === 0) {
+        lines.push("- none", "");
+    }
+    else {
+        for (const finding of audit.findings) {
+            lines.push(`- ${finding.severity}: ${finding.type}: ${finding.message}`);
+        }
+        lines.push("");
+    }
+    lines.push(formatRequirementCoverageMarkdown(audit.requirementCoverage).trimEnd());
+    return `${lines.join("\n")}\n`;
+}
+export function formatSpineAuditJson(audit) {
+    return `${JSON.stringify(audit, null, 2)}\n`;
+}

package/dist/records/closeout.js

@@ -0,0 +1,2 @@
+export * from "./promotion.js";
+export * from "../commands/closeout.js";

package/dist/records/harvest.js

@@ -0,0 +1,236 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { loadHarnessManifest } from '../governance/harness.js';
+import { resolveWorktreePath } from '../task/worktree.js';
+import { getTaskPaths, getTaskStatus, loadTaskConfig } from '../task/runtime.js';
+import { validateDiffPathGuard, listDiffPaths } from '../governance/path-guard.js';
+import { validateCursorArtifacts } from '../executors/cursor-artifacts.js';
+import { checkTaskHandoff } from '../governance/checks.js';
+import { archiveTaskDirFromWorktree } from '../task/worktree-cleanup.js';
+export { copyDir } from '../shared/copy-dir.js';
+/**
+ * Harvest a completed task: validate state → preview diff → merge → archive → cleanup.
+ *
+ * Refuses to harvest unless task status is "completed". Failed/active tasks must
+ * be inspected manually; their worktree is preserved.
+ */
+export async function harvestTask(repoRoot, manifest, taskId, opts = {}) {
+    const archive = opts.archive !== false;
+    const keepWorktree = opts.keepWorktree === true;
+    const squash = opts.squash === true;
+    // Step 1: Locate worktree
+    let effectiveManifest = manifest;
+    if (!effectiveManifest) {
+        try {
+            effectiveManifest = await loadHarnessManifest(repoRoot);
+        }
+        catch {
+            effectiveManifest = undefined;
+        }
+    }
+    const worktreePath = resolveWorktreePath(repoRoot, effectiveManifest, taskId);
+    const taskRoot = await resolveHarvestTaskRoot(repoRoot, worktreePath, taskId);
+    const worktreePresent = (await pathExists(worktreePath)) && (await pathExists(path.join(worktreePath, '.git')));
+    // Step 2: Preflight — task must be completed (prefer archived main-repo state after cleanup)
+    let state;
+    try {
+        state = await getTaskStatus(taskRoot, taskId);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`harvest preflight failed: cannot load task state for "${taskId}": ${msg}`);
+    }
+    if (state.status !== 'completed') {
+        throw new Error(`harvest refused: task "${taskId}" status is "${state.status}", expected "completed". ` +
+            'Failed/active tasks must be inspected manually; their worktree is preserved.');
+    }
+    // Step 3: Determine task branch (worktree cwd or default task/<id> after cleanup)
+    let branch = `task/${taskId}`;
+    if (worktreePresent) {
+        branch = (await tryRunGit(repoRoot, ['-C', worktreePath, 'branch', '--show-current']))?.trim() ?? branch;
+    }
+    const baseBranch = (await tryRunGit(repoRoot, ['branch', '--show-current']))?.trim() || 'main';
+    // Step 4: Generate diff preview (commits + diffstat)
+    const commitsRaw = (await tryRunGit(repoRoot, ['log', `${baseBranch}..${branch}`, '--oneline'])) ?? '';
+    const diffstat = (await tryRunGit(repoRoot, ['diff', '--stat', `${baseBranch}..${branch}`])) ?? '';
+    const commits = commitsRaw.split('\n').map((line) => line.trim()).filter(Boolean);
+    if (commits.length === 0) {
+        throw new Error(`harvest aborted: branch "${branch}" has no new commits relative to "${baseBranch}". ` +
+            'Either the task did nothing, or the base branch already includes its work.');
+    }
+    // Step 4b: Path / artifact / handoff gates
+    await runHarvestGates(repoRoot, taskId, taskRoot, baseBranch, branch);
+    // Step 5: Merge into base branch
+    let commitHash;
+    let merged = false;
+    try {
+        if (squash) {
+            await runGit(repoRoot, ['merge', '--squash', branch]);
+            await runGit(repoRoot, ['commit', '-m', `feat(task): merge ${taskId} (squashed)`]);
+        }
+        else {
+            await runGit(repoRoot, ['merge', '--no-ff', branch, '-m', `feat(task): merge ${taskId}`]);
+        }
+        merged = true;
+        commitHash = (await tryRunGit(repoRoot, ['rev-parse', 'HEAD']))?.trim();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Try to detect conflict and surface helpful info
+        const conflictFiles = await detectConflictFiles(repoRoot);
+        throw new Error(`harvest merge failed: ${msg}` +
+            (conflictFiles.length > 0
+                ? `\nConflicting files:\n  - ${conflictFiles.join('\n  - ')}\nResolve manually then re-run harvest.`
+                : ''));
+    }
+    // Step 6: Archive — copy artifacts/logs/state from worktree back to main repo
+    let archived = false;
+    if (archive) {
+        try {
+            if (await pathExists(worktreePath)) {
+                await archiveTaskDirFromWorktree(repoRoot, worktreePath, taskId);
+            }
+            archived = true;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`harvest archive failed: ${msg}. Merge already completed; worktree preserved.`);
+        }
+    }
+    // Step 7: Cleanup — remove worktree + branch
+    let worktreeRemoved = false;
+    let branchDeleted = false;
+    if (!keepWorktree) {
+        try {
+            await runGit(repoRoot, ['worktree', 'remove', worktreePath]);
+            worktreeRemoved = true;
+        }
+        catch {
+            // Best-effort. If remove fails, instruct user; do not abort harvest.
+        }
+        try {
+            await runGit(repoRoot, ['branch', '-d', branch]);
+            branchDeleted = true;
+        }
+        catch {
+            // Branch may already be deleted by merge or hold unmerged commits; ignore.
+        }
+    }
+    return {
+        taskId,
+        branch,
+        baseBranch,
+        worktreePath,
+        merged,
+        squash,
+        commitHash,
+        archived,
+        worktreeRemoved,
+        branchDeleted,
+        diff: {
+            commits,
+            diffstat,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Harvest gates (path guard, artifacts, handoff)
+// ---------------------------------------------------------------------------
+async function resolveHarvestTaskRoot(repoRoot, worktreePath, taskId) {
+    if (await pathExists(getTaskPaths(worktreePath, taskId).statePath)) {
+        return worktreePath;
+    }
+    if (await pathExists(getTaskPaths(repoRoot, taskId).statePath)) {
+        return repoRoot;
+    }
+    return worktreePath;
+}
+async function runHarvestGates(repoRoot, taskId, taskRoot, baseBranch, branch) {
+    let taskConfig;
+    try {
+        taskConfig = await loadTaskConfig(taskRoot, taskId);
+    }
+    catch {
+        return;
+    }
+    const shouldRunPathGuard = taskConfig.executor === 'cursor'
+        || (taskConfig.allowedPaths ?? []).length > 0
+        || (taskConfig.forbiddenPaths ?? []).length > 0;
+    if (shouldRunPathGuard) {
+        const changedPaths = await listDiffPaths(repoRoot, baseBranch, branch);
+        const pathGuard = validateDiffPathGuard(changedPaths, taskConfig);
+        if (!pathGuard.ok) {
+            throw new Error(`harvest path guard failed for task "${taskId}": ${pathGuard.violations.join(', ')}. ` +
+                'Worktree preserved for manual review.');
+        }
+    }
+    if (taskConfig.executor !== 'cursor') {
+        return;
+    }
+    const paths = getTaskPaths(taskRoot, taskId);
+    const modifyLog = await readFile(path.join(paths.taskDir, 'artifacts', '修改记录.md'), 'utf-8');
+    const verifyResult = await readFile(path.join(paths.taskDir, 'artifacts', '验证结果.md'), 'utf-8');
+    const artifactIssues = validateCursorArtifacts(modifyLog, verifyResult);
+    if (artifactIssues.length > 0) {
+        throw new Error(`harvest artifact validation failed for cursor task "${taskId}": ${artifactIssues.join('; ')}. ` +
+            'Worktree preserved for manual review.');
+    }
+    const handoff = await checkTaskHandoff(taskRoot, taskId);
+    const taskHandoff = handoff.tasks.find((task) => task.taskId === taskId);
+    const blockingIssues = (taskHandoff?.issues ?? []).filter((issue) => issue.severity === 'error');
+    if (blockingIssues.length > 0) {
+        throw new Error(`harvest handoff check failed for task "${taskId}": ${blockingIssues.map((issue) => issue.message).join('; ')}. ` +
+            'Worktree preserved for manual review.');
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function pathExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function detectConflictFiles(repoRoot) {
+    const out = await tryRunGit(repoRoot, ['diff', '--name-only', '--diff-filter=U']);
+    if (!out)
+        return [];
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+async function tryRunGit(repoRoot, args) {
+    try {
+        return await runGit(repoRoot, args);
+    }
+    catch {
+        return null;
+    }
+}
+function runGit(repoRoot, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, {
+            cwd: repoRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on('data', (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
+        child.on('error', (err) => {
+            reject(new Error(`git ${args.join(' ')} spawn error: ${err.message}`));
+        });
+        child.on('close', (code) => {
+            const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf-8');
+            if (code !== 0) {
+                reject(new Error(`git ${args.join(' ')} failed (exit ${code}): ${stderr.trim() || stdout.trim()}`));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}

package/dist/records/index.js

@@ -0,0 +1,3 @@
+export * from "./promotion.js";
+export * from "./closeout.js";
+export * from "./one-shot-runs.js";