@tea-agent/loop-agent 0.1.0

package/dist/workflows/dag/governance-profile.js

@@ -0,0 +1,405 @@
+import { resolveShellCommands } from "../../executors/shell-executor.js";
+import { BASELINE_FORBIDDEN_PATHS } from "./governance-constants.js";
+import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { topoSortToRanks } from "./topo.js";
+/** Delivery signals that require supervised-implementation under --profile auto. */
+export const SUPERVISED_QUALITY_GATE_DELIVERY_SIGNALS = [
+    "loop-agent-runtime-paths",
+    "scripts-ci-harness-paths",
+    "public-contract-paths",
+];
+const PLACEHOLDER_WRITESET_MARKER = "REPLACE/WITH";
+const DELIVERY_PATH_RULES = [
+    {
+        id: "public-contract-paths",
+        patterns: [
+            "docs/templates/**",
+            "**/*.schema.json",
+            "docs/**/prompt*.md",
+            "**/*prompt-template*",
+        ],
+        message: "writeSet touches public contract/schema/prompt-template paths",
+    },
+    {
+        id: "loop-agent-runtime-paths",
+        patterns: [
+            "./src/workflows/dag/**",
+            "./src/task/**",
+            "./src/executors/**",
+            "./src/records/**",
+            "./src/governance/**",
+            "./src/shared/**",
+            "./src/adapters/**",
+            "./src/commands/**",
+        ],
+        message: "writeSet touches loop-agent runtime/workflow/executor paths",
+    },
+    {
+        id: "scripts-ci-harness-paths",
+        patterns: ["scripts/**", "**/ci*.sh", ".github/**"],
+        message: "writeSet touches scripts/CI/harness governance paths",
+    },
+    {
+        id: "high-failure-cost-paths",
+        patterns: [
+            "**/agents/memory/**",
+            "**/agents/skills/**",
+            "~/.agents/**",
+            "~/GoogleDrive/agents/**",
+        ],
+        message: "writeSet touches high failure-cost memory/agent-extension paths",
+    },
+];
+const CLI_CONTRACT_PATHS = [
+    "./src/cli.ts",
+    "./src/cli/index.ts",
+];
+function normalizePath(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function resolveWritePolicy(task, spec) {
+    return task.writePolicy ?? spec.defaults?.writePolicy;
+}
+function isExclusiveWriter(task, spec) {
+    return resolveWritePolicy(task, spec) === "exclusive";
+}
+function isImplementer(task) {
+    return task.role === "implementer";
+}
+function isRepairNode(task) {
+    return /repair/i.test(task.id);
+}
+function forbiddenPathsBeyondBaseline(forbiddenPaths) {
+    return forbiddenPaths.filter((entry) => !BASELINE_FORBIDDEN_PATHS.some((baseline) => pathMatchesPattern(entry, baseline)) &&
+        !BASELINE_FORBIDDEN_PATHS.some((baseline) => pathMatchesPattern(baseline, entry)));
+}
+function isBroadWriteSetEntry(entry) {
+    const normalized = normalizePath(entry.trim());
+    if (!normalized || normalized === "." || normalized === "./")
+        return true;
+    if (normalized === "**")
+        return true;
+    return normalized.includes(PLACEHOLDER_WRITESET_MARKER);
+}
+function topLevelModules(writeSet) {
+    const modules = new Set();
+    for (const entry of writeSet) {
+        const normalized = normalizePath(entry);
+        const first = normalized.split("/")[0];
+        if (first && first !== "**") {
+            modules.add(first);
+        }
+    }
+    return modules;
+}
+function writeSetMatchesAnyPattern(writeSet, patterns) {
+    for (const entry of writeSet) {
+        const normalized = normalizePath(entry);
+        for (const pattern of patterns) {
+            if (pathMatchesPattern(normalized, pattern)) {
+                return entry;
+            }
+        }
+    }
+    return undefined;
+}
+function shellCommandLooksDeterministic(command) {
+    return (/\bnpx vitest run\b/.test(command) ||
+        /\bnpm run (lint|typecheck|test)\b/.test(command) ||
+        /check-repo\.sh/.test(command) ||
+        /\bshell\.preset\b/.test(command) ||
+        /loop-agent-standard-verify/.test(command));
+}
+function taskHasDeterministicShellVerification(task) {
+    if (task.executor !== "shell")
+        return false;
+    const commands = resolveShellCommands(task.shell ?? { commands: [] });
+    return commands.some(shellCommandLooksDeterministic);
+}
+function collectExclusiveWriters(spec) {
+    return spec.tasks.filter((task) => isExclusiveWriter(task, spec) && (task.writeSet?.length ?? 0) > 0);
+}
+function collectImplementerWriters(spec) {
+    return collectExclusiveWriters(spec).filter(isImplementer);
+}
+function findLastImplementerRankIndex(spec, ranks) {
+    const implementerIds = new Set(collectImplementerWriters(spec).map((task) => task.id));
+    let lastRank = -1;
+    for (let index = 0; index < ranks.length; index += 1) {
+        if (ranks[index].some((id) => implementerIds.has(id))) {
+            lastRank = index;
+        }
+    }
+    return lastRank;
+}
+function hasPostImplementationShellVerification(spec, ranks) {
+    const lastImplementerRank = findLastImplementerRankIndex(spec, ranks);
+    if (lastImplementerRank < 0)
+        return false;
+    const taskById = new Map(spec.tasks.map((task) => [task.id, task]));
+    for (let index = lastImplementerRank + 1; index < ranks.length; index += 1) {
+        for (const taskId of ranks[index] ?? []) {
+            const task = taskById.get(taskId);
+            if (task && taskHasDeterministicShellVerification(task)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function hasSupervisedTopology(spec) {
+    const hasSupervisor = spec.tasks.some((task) => task.role === "supervisor");
+    const hasRepairWriter = spec.tasks.some((task) => isRepairNode(task) && isExclusiveWriter(task, spec));
+    const verdictGates = spec.tasks.filter((task) => task.shell?.verdictGate);
+    const hasWriteSetGate = spec.tasks.some((task) => /write-set-gate|write-set-audit/i.test(task.id));
+    const hasProcessGate = spec.tasks.some((task) => /process-gate|process-supervisor/i.test(task.id));
+    const hasReviewGate = spec.tasks.some((task) => /review-gate/i.test(task.id));
+    return (hasSupervisor &&
+        hasRepairWriter &&
+        verdictGates.length >= 2 &&
+        hasWriteSetGate &&
+        hasProcessGate &&
+        hasReviewGate);
+}
+function hasReviewGateTopology(spec) {
+    return spec.tasks.some((task) => task.executor === "shell" &&
+        (/review-gate/i.test(task.id) || task.shell?.verdictGate !== undefined) &&
+        task.depends_on.some((dep) => /review/i.test(dep)));
+}
+function collectProcessSignals(spec, ranks) {
+    const signals = [];
+    const writers = collectExclusiveWriters(spec);
+    if (writers.length > 1) {
+        signals.push({
+            id: "multiple-exclusive-writers",
+            category: "process",
+            message: `DAG has ${writers.length} exclusive writer nodes (${writers.map((task) => task.id).join(", ")})`,
+        });
+    }
+    const repairNodes = spec.tasks.filter((task) => isRepairNode(task) && isExclusiveWriter(task, spec));
+    if (repairNodes.length > 0) {
+        signals.push({
+            id: "repair-node-present",
+            category: "process",
+            message: `repair exclusive writer present: ${repairNodes.map((task) => task.id).join(", ")}`,
+        });
+    }
+    for (const writer of writers) {
+        const extraForbidden = forbiddenPathsBeyondBaseline(writer.forbiddenPaths ?? []);
+        if (extraForbidden.length > 0) {
+            signals.push({
+                id: "non-baseline-forbidden-on-writer",
+                category: "process",
+                message: `writer ${writer.id} declares non-baseline forbiddenPaths: ${extraForbidden.join(", ")}`,
+            });
+            break;
+        }
+    }
+    for (const writer of writers) {
+        for (const entry of writer.writeSet ?? []) {
+            if (isBroadWriteSetEntry(entry)) {
+                signals.push({
+                    id: "broad-write-set",
+                    category: "process",
+                    message: `writer ${writer.id} has broad/placeholder/root writeSet entry "${entry}"`,
+                });
+                break;
+            }
+        }
+        if (signals.some((signal) => signal.id === "broad-write-set"))
+            break;
+    }
+    for (const writer of collectImplementerWriters(spec)) {
+        if (writer.complexity === "HIGH") {
+            signals.push({
+                id: "high-complexity-implementer",
+                category: "process",
+                message: `HIGH complexity implementer ${writer.id} increases attribution/repair risk`,
+            });
+            break;
+        }
+    }
+    const mergedWriteSet = writers.flatMap((task) => task.writeSet ?? []);
+    if (topLevelModules(mergedWriteSet).size > 1) {
+        signals.push({
+            id: "cross-module-write-set",
+            category: "process",
+            message: `exclusive writeSet spans multiple top-level modules: ${[...topLevelModules(mergedWriteSet)].join(", ")}`,
+        });
+    }
+    if (collectImplementerWriters(spec).length > 0 &&
+        !hasPostImplementationShellVerification(spec, ranks)) {
+        signals.push({
+            id: "weak-post-implementation-verification",
+            category: "process",
+            message: "no deterministic shell verification node after the last implementer (preset/vitest/check-repo)",
+        });
+    }
+    return signals;
+}
+function collectDeliverySignals(spec) {
+    const signals = [];
+    const writers = collectExclusiveWriters(spec);
+    const mergedWriteSet = writers.flatMap((task) => task.writeSet ?? []);
+    for (const rule of DELIVERY_PATH_RULES) {
+        const hit = writeSetMatchesAnyPattern(mergedWriteSet, rule.patterns);
+        if (hit) {
+            signals.push({
+                id: rule.id,
+                category: "delivery",
+                message: `${rule.message} (matched "${hit}")`,
+            });
+        }
+    }
+    const cliHit = writeSetMatchesAnyPattern(mergedWriteSet, CLI_CONTRACT_PATHS);
+    if (cliHit) {
+        signals.push({
+            id: "cli-contract-paths",
+            category: "delivery",
+            message: `writeSet touches CLI contract paths (matched "${cliHit}")`,
+        });
+    }
+    const srcEntries = mergedWriteSet.filter((entry) => {
+        const normalized = normalizePath(entry);
+        return (/\/src\//.test(normalized) &&
+            !/\/test\//.test(normalized) &&
+            !normalized.endsWith(".test.ts"));
+    });
+    const testEntries = mergedWriteSet.filter((entry) => {
+        const normalized = normalizePath(entry);
+        return /\/test\//.test(normalized) || normalized.endsWith(".test.ts");
+    });
+    if (srcEntries.length > 0 && testEntries.length === 0) {
+        signals.push({
+            id: "missing-focused-test-evidence",
+            category: "delivery",
+            message: "writeSet changes source paths without paired focused regression test paths",
+        });
+    }
+    return signals;
+}
+function collectCodeChangeSignals(spec) {
+    const signals = [];
+    for (const writer of collectExclusiveWriters(spec)) {
+        for (const entry of writer.writeSet ?? []) {
+            const normalized = normalizePath(entry);
+            if (/\/src\//.test(normalized) &&
+                !/\/test\//.test(normalized) &&
+                !normalized.endsWith(".test.ts")) {
+                signals.push({
+                    id: "behavior-changing-writer",
+                    category: "codeChange",
+                    message: `exclusive writer ${writer.id} may change runtime behavior via "${entry}"`,
+                });
+            }
+        }
+    }
+    return signals;
+}
+function buildProfileReasons(profile, process, delivery, codeChange, supervisedTopology) {
+    const reasons = [];
+    if (profile === "supervised") {
+        reasons.push("supervised topology detected (supervisor + repair + write-set/process/review gates)");
+        return reasons;
+    }
+    if (supervisedTopology) {
+        reasons.push("partial supervised markers present but topology incomplete; profile downgraded");
+    }
+    const signalIds = [
+        ...process.map((signal) => signal.id),
+        ...delivery.map((signal) => signal.id),
+        ...codeChange.map((signal) => signal.id),
+    ];
+    if (profile === "minimal") {
+        reasons.push("single narrow writer with deterministic post-implementation shell verification and no elevated process/delivery/code-change signals");
+        return reasons;
+    }
+    if (profile === "reviewed") {
+        if (process.some((signal) => signal.id === "repair-node-present")) {
+            reasons.push("repair writer requires reviewed-or-higher governance");
+        }
+        if (process.some((signal) => signal.id === "multiple-exclusive-writers")) {
+            reasons.push("multiple exclusive writers require coordination/review gates");
+        }
+        if (delivery.some((signal) => signal.id === "loop-agent-runtime-paths")) {
+            reasons.push("loop-agent core path writes require reviewed governance");
+        }
+        if (process.some((signal) => signal.id === "weak-post-implementation-verification")) {
+            reasons.push("weak post-implementation verification elevates governance to reviewed");
+        }
+        if (signalIds.length === 0) {
+            reasons.push("explicit review-gate topology detected");
+        }
+    }
+    if (profile === "standard") {
+        reasons.push(`standard hybrid implementation profile (${signalIds.length} governance signal(s): ${signalIds.join(", ") || "implementer present"})`);
+    }
+    return reasons;
+}
+function inferProfileName(spec, process, delivery, codeChange, ranks) {
+    if (hasSupervisedTopology(spec)) {
+        return "supervised";
+    }
+    const processIds = new Set(process.map((signal) => signal.id));
+    const deliveryIds = new Set(delivery.map((signal) => signal.id));
+    const hasImplementer = collectImplementerWriters(spec).length > 0;
+    if (processIds.has("repair-node-present") ||
+        processIds.has("multiple-exclusive-writers") ||
+        hasReviewGateTopology(spec) ||
+        deliveryIds.has("loop-agent-runtime-paths") ||
+        deliveryIds.has("scripts-ci-harness-paths") ||
+        (processIds.has("weak-post-implementation-verification") && hasImplementer) ||
+        (processIds.has("high-complexity-implementer") &&
+            (delivery.length > 0 || codeChange.length > 0))) {
+        return "reviewed";
+    }
+    const totalSignals = process.length + delivery.length + codeChange.length;
+    if (hasImplementer && totalSignals > 0) {
+        return "standard";
+    }
+    if (hasImplementer &&
+        totalSignals === 0 &&
+        hasPostImplementationShellVerification(spec, ranks) &&
+        collectExclusiveWriters(spec).length === 1) {
+        return "minimal";
+    }
+    return totalSignals > 1 ? "reviewed" : "standard";
+}
+export function requiresSupervisedQualityGate(result) {
+    const deliveryIds = new Set(result.delivery.map((signal) => signal.id));
+    const signalIds = SUPERVISED_QUALITY_GATE_DELIVERY_SIGNALS.filter((id) => deliveryIds.has(id));
+    if (signalIds.length === 0) {
+        return { required: false, signalIds: [], reasons: [] };
+    }
+    const reasons = [];
+    if (signalIds.includes("loop-agent-runtime-paths")) {
+        reasons.push("supervised-quality-gate-required: loop-agent runtime/core path writes need process supervisor, repair, and hard verification gates");
+    }
+    if (signalIds.includes("scripts-ci-harness-paths")) {
+        reasons.push("supervised-quality-gate-required: scripts/CI/harness governance path writes need supervised repair and verification gates");
+    }
+    if (signalIds.includes("public-contract-paths")) {
+        reasons.push("supervised-quality-gate-required: public contract/schema/prompt-template path writes need write-set audit and review gates before closeout");
+    }
+    return { required: true, signalIds: [...signalIds], reasons };
+}
+export function resolveAutoRoutingProfile(candidateProfile) {
+    const gate = requiresSupervisedQualityGate(candidateProfile);
+    return gate.required ? "supervised" : candidateProfile.profile;
+}
+export function inferGovernanceProfile(spec) {
+    const { ranks } = topoSortToRanks(spec);
+    const process = collectProcessSignals(spec, ranks);
+    const delivery = collectDeliverySignals(spec);
+    const codeChange = collectCodeChangeSignals(spec);
+    const supervisedTopology = hasSupervisedTopology(spec);
+    const profile = inferProfileName(spec, process, delivery, codeChange, ranks);
+    const reasons = buildProfileReasons(profile, process, delivery, codeChange, supervisedTopology);
+    return {
+        profile,
+        process,
+        delivery,
+        codeChange,
+        reasons,
+    };
+}

package/dist/workflows/dag/index.js

@@ -0,0 +1,6 @@
+export * from "./spec.js";
+export * from "./authoring.js";
+export * from "./runtime.js";
+export * from "./facts.js";
+export * from "./report.js";
+export * from "./decision-gates.js";