@tea-agent/loop-agent 0.1.0

package/dist/governance/manifest-types.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+export const stepModelConfigSchema = z.object({
+    provider: z.string().optional(),
+    model: z.string().optional(),
+    thinking: z.string().optional(),
+    timeoutMs: z.number().int().positive().optional(),
+});
+export const modelProfileSchema = stepModelConfigSchema.extend({
+    fallback: stepModelConfigSchema.optional(),
+});
+export const complexityRouteSchema = z.object({
+    small: z.string().optional(),
+    medium: z.string().optional(),
+    large: z.string().optional(),
+});
+export const worktreeManifestConfigSchema = z.object({
+    rootRelativePath: z.string().optional().default(".worktrees"),
+});
+export const taskExecutorSchema = z.enum(["pi", "cursor"]);
+export const executorManifestSchema = z.object({
+    description: z.string().optional(),
+    enabled: z.boolean().optional(),
+    defaultModel: z.string().optional().default("default"),
+    requiresApiKey: z.string().optional().default("CURSOR_API_KEY"),
+});
+export const workflowPolicyProfileNameSchema = z.enum([
+    "minimal",
+    "standard",
+    "reviewed",
+    "supervised",
+]);
+export const workflowPolicyDagTemplateSchema = z.enum([
+    "standard-dag",
+    "review-gated-dag",
+    "supervised-implementation",
+]);
+export const workflowPolicySchema = z
+    .object({
+    /** Preferred implementation workflow for recoverable loop-agent work. Declarative policy; callers may still require explicit CLI flags. */
+    defaultImplementationWorkflow: z
+        .enum(["agent-dag", "level-1"])
+        .optional()
+        .default("agent-dag"),
+    dag: z
+        .object({
+        defaultEntry: z
+            .enum(["dag run-task", "run-dag"])
+            .optional()
+            .default("dag run-task"),
+        profileRouting: z
+            .object({
+            minimal: workflowPolicyDagTemplateSchema
+                .optional()
+                .default("standard-dag"),
+            standard: workflowPolicyDagTemplateSchema
+                .optional()
+                .default("standard-dag"),
+            reviewed: workflowPolicyDagTemplateSchema
+                .optional()
+                .default("review-gated-dag"),
+            supervised: workflowPolicyDagTemplateSchema
+                .optional()
+                .default("supervised-implementation"),
+        })
+            .optional()
+            .default({}),
+    })
+        .optional()
+        .default({}),
+    humanGatePolicy: z
+        .object({
+        defaultMode: z
+            .enum(["record-only", "pause-on-human"])
+            .optional()
+            .default("record-only"),
+        pauseOn: z.array(z.string()).optional().default([]),
+    })
+        .optional()
+        .default({}),
+})
+    .optional()
+    .default({});
+export const harnessManifestSchema = z.object({
+    version: z.number(),
+    project: z.string(),
+    governanceRoot: z.string(),
+    features: z
+        .object({
+        goals: z.boolean().optional().default(true),
+    })
+        .optional()
+        .default({
+        goals: true,
+    }),
+    entrypoints: z.record(z.string(), z.string().nullable()),
+    artifacts: z.record(z.string(), z.string().nullable()),
+    scripts: z.record(z.string(), z.string().nullable()),
+    models: z
+        .object({
+        analyze: stepModelConfigSchema.optional(),
+        plan: stepModelConfigSchema.optional(),
+        implement: stepModelConfigSchema.optional(),
+        verify: stepModelConfigSchema.optional(),
+        retrospective: stepModelConfigSchema.optional(),
+    })
+        .optional()
+        .default({}),
+    modelProfiles: z
+        .record(z.string(), modelProfileSchema)
+        .optional()
+        .default({}),
+    modelRouting: z
+        .object({
+        analyze: complexityRouteSchema.optional(),
+        plan: complexityRouteSchema.optional(),
+        implement: complexityRouteSchema.optional(),
+        retrospective: complexityRouteSchema.optional(),
+        implementRetry: z.string().optional(),
+    })
+        .optional()
+        .default({}),
+    workflowPolicy: workflowPolicySchema,
+    worktree: worktreeManifestConfigSchema.optional(),
+    executors: z
+        .record(z.string(), executorManifestSchema)
+        .optional()
+        .default({}),
+});

package/dist/governance/manifest.js

@@ -0,0 +1,2 @@
+export * from "./harness.js";
+export * from "./manifest-types.js";

package/dist/governance/path-guard.js

@@ -0,0 +1,69 @@
+import { pathMatchesPattern } from '../shared/git-progress.js';
+function normalizePath(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function isTaskHarnessPath(filePath, taskId) {
+    const normalized = normalizePath(filePath);
+    if (!normalized.startsWith('.harness/tasks/'))
+        return false;
+    if (!taskId)
+        return true;
+    return normalized.startsWith(`.harness/tasks/${taskId}/`);
+}
+/**
+ * Validate git diff paths against task allowed/forbidden boundaries.
+ * Task harness paths are always allowed so artifacts/logs can be updated.
+ */
+export function validateDiffPathGuard(changedPaths, taskConfig) {
+    const forbiddenHits = [];
+    const outOfScopeHits = [];
+    for (const rawPath of changedPaths) {
+        const filePath = normalizePath(rawPath);
+        if (isTaskHarnessPath(filePath, taskConfig.taskId))
+            continue;
+        if (matchesForbidden(filePath, taskConfig.forbiddenPaths ?? [])) {
+            forbiddenHits.push(filePath);
+            continue;
+        }
+        const allowed = taskConfig.allowedPaths ?? [];
+        if (allowed.length === 0) {
+            outOfScopeHits.push(filePath);
+            continue;
+        }
+        const allowedMatch = allowed.some((pattern) => pathMatchesPattern(filePath, pattern));
+        if (!allowedMatch) {
+            outOfScopeHits.push(filePath);
+        }
+    }
+    const violations = [...forbiddenHits, ...outOfScopeHits];
+    return {
+        ok: violations.length === 0,
+        violations,
+        forbiddenHits,
+        outOfScopeHits,
+    };
+}
+function matchesForbidden(filePath, forbiddenPaths) {
+    return forbiddenPaths.some((pattern) => pathMatchesPattern(filePath, pattern));
+}
+export async function listDiffPaths(repoRoot, baseRef, headRef) {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['diff', '--name-only', '-z', `${baseRef}..${headRef}`], {
+            cwd: repoRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const out = [];
+        child.stdout?.on('data', (chunk) => out.push(chunk));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code !== 0) {
+                resolve([]);
+                return;
+            }
+            const raw = Buffer.concat(out).toString('utf-8');
+            const paths = raw.split('\0').map((line) => line.trim()).filter(Boolean);
+            resolve(Array.from(new Set(paths)));
+        });
+    });
+}

package/dist/governance/path-guards.js

@@ -0,0 +1,2 @@
+export * from "./path-guard.js";
+export * from "../executors/shell-write-guard.js";

package/dist/governance/profiles.js

@@ -0,0 +1,3 @@
+export * from "../workflows/dag/governance-constants.js";
+export * from "../workflows/dag/governance-profile.js";
+export * from "./checks.js";

package/dist/governance/requirement-coverage.js

@@ -0,0 +1,425 @@
+import { access, readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { extractGoalAuditScope } from '../task/goal-audit.js';
+import { getTaskPaths, loadTaskConfig } from '../task/runtime.js';
+export const COVERAGE_STATUSES = [
+    'covered_by_code',
+    'covered_by_test',
+    'covered_by_static_gate',
+    'covered_by_artifact',
+    'explicitly_out_of_scope',
+];
+const GOAL_SCOPE_START = /<!--\s*goal-scope\s*-->/i;
+const GOAL_SCOPE_END = /<!--\s*\/goal-scope\s*-->/i;
+const SECTION_HEADING = /^##\s+(.+?)\s*$/;
+const CHECKLIST_LINE = /^-\s*\[( |x|X)\]\s+(.+)$/;
+const NUMBERED_LINE = /^(\d+)\.\s+(.+)$/;
+const REQ_ID = /\b(REQ-[A-Z0-9]+(?:-[A-Z0-9]+)*)\b/i;
+const OUT_OF_SCOPE_SECTION = /非目标|out[- ]of[- ]scope/i;
+const OUT_OF_SCOPE_INLINE = /\[(?:out-of-scope|explicitly_out_of_scope)\]|explicitly_out_of_scope\s*:/i;
+const STATIC_GATE_KEYWORDS = [
+    { pattern: /lint|typecheck|静态/i, tokens: ['lint', 'typecheck', 'tsc'] },
+    { pattern: /test|单元测试|vitest/i, tokens: ['test', 'vitest', 'npm test'] },
+    { pattern: /check-repo|仓库检查/i, tokens: ['check-repo', 'scripts/check-repo'] },
+];
+const TEXT_FILE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.md',
+    '.json',
+    '.sh',
+]);
+function extractReqId(text) {
+    const match = text.match(REQ_ID);
+    return match?.[1]?.toUpperCase();
+}
+function isOutOfScopeSectionHeading(heading) {
+    return OUT_OF_SCOPE_SECTION.test(heading.trim());
+}
+function isOutOfScopeLine(text) {
+    return OUT_OF_SCOPE_INLINE.test(text);
+}
+export function splitMarkdownSections(text) {
+    const lines = text.split('\n');
+    const sections = [];
+    let currentHeading = null;
+    let currentLines = [];
+    const flush = () => {
+        sections.push({
+            heading: currentHeading,
+            body: currentLines.join('\n'),
+        });
+        currentLines = [];
+    };
+    for (const line of lines) {
+        const headingMatch = line.match(SECTION_HEADING);
+        if (headingMatch) {
+            flush();
+            currentHeading = headingMatch[1]?.trim() ?? null;
+            continue;
+        }
+        currentLines.push(line);
+    }
+    flush();
+    return sections;
+}
+export function extractRequirementsFromMarkdown(text) {
+    const scoped = extractGoalAuditScope(text);
+    const hasScopeMarkers = GOAL_SCOPE_START.test(text) && GOAL_SCOPE_END.test(text);
+    const sourceText = hasScopeMarkers ? scoped : text;
+    const sections = splitMarkdownSections(sourceText);
+    const requirements = [];
+    const outOfScope = [];
+    const seenIds = new Set();
+    let checklistCounter = 0;
+    let numberedCounter = 0;
+    const pushRequirement = (item, bucket) => {
+        const explicitId = extractReqId(item.label);
+        const id = explicitId ?? item.id ?? `${item.source}-${bucket.length + 1}`;
+        if (seenIds.has(id))
+            return;
+        seenIds.add(id);
+        bucket.push({
+            ...item,
+            id,
+            label: item.label.trim(),
+        });
+    };
+    for (const section of sections) {
+        const inOutOfScopeSection = section.heading ? isOutOfScopeSectionHeading(section.heading) : false;
+        const lines = section.body.split('\n');
+        for (let index = 0; index < lines.length; index += 1) {
+            const lineNumber = index + 1;
+            const line = lines[index] ?? '';
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const checklistMatch = trimmed.match(CHECKLIST_LINE);
+            if (checklistMatch) {
+                const checked = (checklistMatch[1] ?? '').toLowerCase() === 'x';
+                const label = checklistMatch[2]?.trim() ?? '';
+                if (!label)
+                    continue;
+                checklistCounter += 1;
+                const bucket = inOutOfScopeSection || isOutOfScopeLine(label) ? outOfScope : requirements;
+                pushRequirement({
+                    label,
+                    source: 'checklist',
+                    line: lineNumber,
+                    section: section.heading ?? undefined,
+                    checked,
+                    id: extractReqId(label) ?? `checklist-${checklistCounter}`,
+                }, bucket);
+                continue;
+            }
+            const numberedMatch = trimmed.match(NUMBERED_LINE);
+            if (numberedMatch) {
+                const label = numberedMatch[2]?.trim() ?? '';
+                if (!label)
+                    continue;
+                numberedCounter += 1;
+                const bucket = inOutOfScopeSection || isOutOfScopeLine(label) ? outOfScope : requirements;
+                pushRequirement({
+                    label,
+                    source: 'numbered',
+                    line: lineNumber,
+                    section: section.heading ?? undefined,
+                    id: extractReqId(label) ?? `numbered-${numberedCounter}`,
+                }, bucket);
+                continue;
+            }
+            const explicitId = extractReqId(trimmed);
+            if (explicitId) {
+                const label = trimmed.replace(REQ_ID, '').replace(/^[-*:\s]+/, '').trim() || explicitId;
+                const bucket = inOutOfScopeSection || isOutOfScopeLine(trimmed) ? outOfScope : requirements;
+                pushRequirement({
+                    id: explicitId,
+                    label,
+                    source: 'explicit-id',
+                    line: lineNumber,
+                    section: section.heading ?? undefined,
+                }, bucket);
+            }
+        }
+    }
+    return { requirements, outOfScope };
+}
+function entryIsOutOfScope(entry) {
+    return entry.statuses.includes('explicitly_out_of_scope');
+}
+function entryIsCovered(entry) {
+    return entry.statuses.some((status) => status !== 'explicitly_out_of_scope');
+}
+export function buildRequirementCoverageAudit(taskId, requirements, outOfScope, evidenceByRequirementId) {
+    const outOfScopeIds = new Set(outOfScope.map((item) => item.id));
+    const entries = [];
+    for (const requirement of requirements) {
+        if (outOfScopeIds.has(requirement.id)) {
+            entries.push({
+                requirement,
+                statuses: ['explicitly_out_of_scope'],
+                evidence: ['source/需求.md'],
+            });
+            continue;
+        }
+        const mapped = evidenceByRequirementId.get(requirement.id);
+        const statuses = new Set(mapped?.statuses ?? []);
+        const evidence = [...(mapped?.evidence ?? [])];
+        entries.push({
+            requirement,
+            statuses: Array.from(statuses),
+            evidence: Array.from(new Set(evidence)),
+        });
+    }
+    for (const requirement of outOfScope) {
+        if (entries.some((entry) => entry.requirement.id === requirement.id))
+            continue;
+        entries.push({
+            requirement,
+            statuses: ['explicitly_out_of_scope'],
+            evidence: ['source/需求.md'],
+        });
+    }
+    const uncovered = entries.filter((entry) => !entryIsOutOfScope(entry) && !entryIsCovered(entry));
+    const covered = entries.filter((entry) => entryIsCovered(entry));
+    const outOfScopeCount = entries.filter((entry) => entryIsOutOfScope(entry)).length;
+    return {
+        ok: uncovered.length === 0,
+        taskId,
+        extractedAt: new Date().toISOString(),
+        entries,
+        uncovered,
+        summary: {
+            total: entries.length,
+            covered: covered.length,
+            outOfScope: outOfScopeCount,
+            uncovered: uncovered.length,
+        },
+    };
+}
+async function exists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function walkTextFiles(rootDir, files) {
+    let entries;
+    try {
+        entries = await readdir(rootDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const absolutePath = path.join(rootDir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist')
+                continue;
+            await walkTextFiles(absolutePath, files);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const ext = path.extname(entry.name);
+        if (!TEXT_FILE_EXTENSIONS.has(ext))
+            continue;
+        files.push(absolutePath);
+    }
+}
+function classifyEvidencePath(relativePath) {
+    if (/(^|\/)test\//.test(relativePath) || relativePath.includes('.test.')) {
+        return 'covered_by_test';
+    }
+    if (relativePath.includes('artifacts/')) {
+        return 'covered_by_artifact';
+    }
+    return 'covered_by_code';
+}
+function detectStaticGateCoverage(label, verifyContent) {
+    const haystack = verifyContent.toLowerCase();
+    for (const rule of STATIC_GATE_KEYWORDS) {
+        if (!rule.pattern.test(label))
+            continue;
+        if (rule.tokens.some((token) => haystack.includes(token.toLowerCase()))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function loadCoverageMapping(mappingPath) {
+    if (!await exists(mappingPath))
+        return null;
+    try {
+        const raw = JSON.parse(await readFile(mappingPath, 'utf-8'));
+        if (raw.version !== 1 || !Array.isArray(raw.entries))
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+async function collectSearchRoots(repoRoot, allowedPaths) {
+    if (allowedPaths.length === 0) {
+        return [repoRoot];
+    }
+    return allowedPaths.map((entry) => path.resolve(repoRoot, entry.replace(/\/+$/, '')));
+}
+function pathMatchesAllowed(relativePath, allowedPaths) {
+    if (allowedPaths.length === 0)
+        return true;
+    const normalized = relativePath.replace(/\\/g, '/');
+    return allowedPaths.some((allowed) => {
+        const prefix = allowed.replace(/\\/g, '/').replace(/\/+$/, '');
+        return normalized === prefix || normalized.startsWith(`${prefix}/`);
+    });
+}
+async function scanRepoEvidence(repoRoot, requirements, allowedPaths, verifyContent, artifactContents) {
+    const evidenceById = new Map();
+    const addEvidence = (requirementId, status, evidencePath) => {
+        const current = evidenceById.get(requirementId) ?? { statuses: [], evidence: [] };
+        if (!current.statuses.includes(status))
+            current.statuses.push(status);
+        if (!current.evidence.includes(evidencePath))
+            current.evidence.push(evidencePath);
+        evidenceById.set(requirementId, current);
+    };
+    for (const requirement of requirements) {
+        if (detectStaticGateCoverage(requirement.label, verifyContent)) {
+            addEvidence(requirement.id, 'covered_by_static_gate', 'artifacts/验证结果.md');
+        }
+        for (const artifact of artifactContents) {
+            if (artifact.content.includes(requirement.id)
+                || artifact.content.toLowerCase().includes(requirement.label.toLowerCase())) {
+                addEvidence(requirement.id, 'covered_by_artifact', artifact.relativePath);
+            }
+        }
+    }
+    const searchRoots = await collectSearchRoots(repoRoot, allowedPaths);
+    const files = [];
+    for (const root of searchRoots) {
+        if (!await exists(root))
+            continue;
+        const rootStat = await stat(root);
+        if (rootStat.isFile()) {
+            files.push(root);
+            continue;
+        }
+        if (rootStat.isDirectory()) {
+            await walkTextFiles(root, files);
+        }
+    }
+    for (const absolutePath of files) {
+        const relativePath = path.relative(repoRoot, absolutePath).replace(/\\/g, '/');
+        if (!pathMatchesAllowed(relativePath, allowedPaths))
+            continue;
+        let content = '';
+        try {
+            content = await readFile(absolutePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        for (const requirement of requirements) {
+            if (!content.includes(requirement.id) && !content.toLowerCase().includes(requirement.label.toLowerCase())) {
+                continue;
+            }
+            addEvidence(requirement.id, classifyEvidencePath(relativePath), relativePath);
+        }
+    }
+    return evidenceById;
+}
+export async function runRequirementCoverageAudit(repoRoot, taskId) {
+    const taskPaths = getTaskPaths(repoRoot, taskId);
+    const requirementPath = path.join(taskPaths.sourceDir, '需求.md');
+    const taskConfig = await loadTaskConfig(repoRoot, taskId);
+    let requirementMarkdown = '';
+    try {
+        requirementMarkdown = await readFile(requirementPath, 'utf-8');
+    }
+    catch {
+        return buildRequirementCoverageAudit(taskId, [], [], new Map());
+    }
+    const { requirements, outOfScope } = extractRequirementsFromMarkdown(requirementMarkdown);
+    const artifactDir = path.join(taskPaths.taskDir, 'artifacts');
+    const artifactContents = [];
+    let verifyContent = '';
+    if (await exists(artifactDir)) {
+        const artifactEntries = await readdir(artifactDir, { withFileTypes: true });
+        for (const entry of artifactEntries) {
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            const absolutePath = path.join(artifactDir, entry.name);
+            const content = await readFile(absolutePath, 'utf-8');
+            const relativePath = path.relative(repoRoot, absolutePath).replace(/\\/g, '/');
+            artifactContents.push({ relativePath, content });
+            if (entry.name === '验证结果.md') {
+                verifyContent = content;
+            }
+        }
+    }
+    const mappingPath = path.join(artifactDir, 'requirement-coverage.json');
+    const mapping = await loadCoverageMapping(mappingPath);
+    const evidenceById = await scanRepoEvidence(repoRoot, requirements, taskConfig.allowedPaths, verifyContent, artifactContents);
+    if (mapping) {
+        for (const entry of mapping.entries) {
+            const current = evidenceById.get(entry.requirementId) ?? { statuses: [], evidence: [] };
+            for (const status of entry.statuses) {
+                if (!current.statuses.includes(status))
+                    current.statuses.push(status);
+            }
+            for (const evidencePath of entry.evidence ?? []) {
+                if (!current.evidence.includes(evidencePath))
+                    current.evidence.push(evidencePath);
+            }
+            evidenceById.set(entry.requirementId, current);
+        }
+    }
+    return buildRequirementCoverageAudit(taskId, requirements, outOfScope, evidenceById);
+}
+export function formatRequirementCoverageMarkdown(audit) {
+    const lines = [
+        '# Requirement Coverage Audit',
+        '',
+        `- task: \`${audit.taskId}\``,
+        `- extractedAt: ${audit.extractedAt}`,
+        `- ok: ${audit.ok ? 'yes' : 'no'}`,
+        `- total: ${audit.summary.total}`,
+        `- covered: ${audit.summary.covered}`,
+        `- outOfScope: ${audit.summary.outOfScope}`,
+        `- uncovered: ${audit.summary.uncovered}`,
+        '',
+        '## Requirements',
+        '',
+        '| ID | Label | Statuses | Evidence |',
+        '| --- | --- | --- | --- |',
+    ];
+    for (const entry of audit.entries) {
+        const statuses = entry.statuses.length > 0 ? entry.statuses.join(', ') : 'uncovered';
+        const evidence = entry.evidence.length > 0 ? entry.evidence.join('; ') : '-';
+        lines.push(`| ${entry.requirement.id} | ${entry.requirement.label.replace(/\|/g, '\\|')} | ${statuses} | ${evidence} |`);
+    }
+    if (audit.uncovered.length > 0) {
+        lines.push('', '## Uncovered', '');
+        for (const entry of audit.uncovered) {
+            lines.push(`- ${entry.requirement.id}: ${entry.requirement.label}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function formatRequirementCoverageJson(audit) {
+    return `${JSON.stringify(audit, null, 2)}\n`;
+}
+export function requirementCoverageFailureReasons(audit) {
+    if (audit.ok)
+        return [];
+    return audit.uncovered.map((entry) => `uncovered requirement ${entry.requirement.id}: ${entry.requirement.label}`);
+}