@tea-agent/loop-agent 0.42.0-next.2 → 0.42.0-next.4

package/dist/application/task-lifecycle/advance.js

@@ -260,6 +260,10 @@ async function monitorRun(input) {
         failureCategory: "monitor-timeout",
     });
 }
+function isStartupGateEligible(snapshot) {
+    const status = snapshot.source?.sourceFidelityStartup?.status;
+    return status === undefined || status === "complete" || status === "not-applicable";
+}
 function nextMutationAction(actions) {
     for (const action of actions) {
         if (action.type !== "stop")
@@ -379,7 +383,10 @@ export async function advanceTaskLifecycle(input) {
             };
         }
         const token = parseGateToken(input.rejectGateToken);
-        const currentGate = snapshot.gate ?? (await buildCurrentGate(input.repoRoot, input.taskId));
+        const currentGate = snapshot.gate ??
+            (isStartupGateEligible(snapshot)
+                ? await buildCurrentGate(input.repoRoot, input.taskId)
+                : null);
         if (!currentGate || !gateMatches(currentGate, token)) {
             return {
                 taskId: input.taskId,
@@ -443,11 +450,12 @@ export async function advanceTaskLifecycle(input) {
         dryRun,
         skipFinalize: Boolean(input.skipFinalize),
         forcePrepareContract: Boolean(input.fromDraftPath) && !preparedContractThisCall,
+        startupRepairAttempted: preparedContractThisCall,
     });
     if (dryRun) {
         const plan = planOnce(snapshot);
         const plannedGate = snapshot.gate ??
-            (snapshot.dagDraft?.exists
+            (isStartupGateEligible(snapshot) && snapshot.dagDraft?.exists
                 ? await buildCurrentGate(input.repoRoot, input.taskId)
                 : null);
         return {
@@ -499,7 +507,10 @@ export async function advanceTaskLifecycle(input) {
         }
         if (action.type === "create-task") {
             if (!snapshot.exists) {
-                await createTask(input.repoRoot, input.taskId, input.title);
+                await createTask(input.repoRoot, input.taskId, input.title, {
+                    taskKind: input.taskKind,
+                    taskKindExplicit: input.taskKindExplicit,
+                });
                 record = appendTransition(record, "task-created");
                 completed.push("task-created");
                 await saveLifecycleRecord(input.repoRoot, record);
@@ -586,6 +597,10 @@ export async function advanceTaskLifecycle(input) {
             continue;
         }
         if (action.type === "prepare-contract") {
+            const startupStatus = snapshot.source?.sourceFidelityStartup?.status;
+            const startupRepairAction = startupStatus === "missing" ||
+                startupStatus === "invalid" ||
+                startupStatus === "coverage-incomplete";
             // 生产 source fidelity Pi 接线（AC-PROD-001/005）：仅 frontend-implementation
             // 任务注入 reconcile executor + 独立 reviewer；ineligible 返回 undefined 不接线。
             // 主路径与 semantic-intake retry 路径共用同一接线，保证任意一条生产路径都实际
@@ -731,7 +746,9 @@ export async function advanceTaskLifecycle(input) {
                                     message: "structured requirement draft via semantic intake; projected managed source",
                                 });
                                 preparedContractThisCall = true;
-                                if (refreshManagedContractThisCall || input.fromDraftPath) {
+                                if (startupRepairAction ||
+                                    refreshManagedContractThisCall ||
+                                    input.fromDraftPath) {
                                     refreshManagedContractThisCall = false;
                                     regenerateDagThisCall = true;
                                 }
@@ -825,7 +842,9 @@ export async function advanceTaskLifecycle(input) {
                 break;
             }
             preparedContractThisCall = true;
-            if (refreshManagedContractThisCall || input.fromDraftPath) {
+            if (startupRepairAction ||
+                refreshManagedContractThisCall ||
+                input.fromDraftPath) {
                 // The old DAG and gate were bound to the pre-mutation contract.
                 refreshManagedContractThisCall = false;
                 regenerateDagThisCall = true;

package/dist/application/task-lifecycle/observe.js

@@ -1,9 +1,11 @@
-import { access, readFile } from "node:fs/promises";
+import { access, readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { getTaskDir, getTaskPaths, getTaskStatus, loadTaskConfig, } from "../../task/runtime.js";
 import { logicalRevisionForState, observeTaskContractState, } from "../../task/contract/index.js";
 import { assessDagRunLiveness, listAllDagRunEntries, readDagRunSpec, readDagRunState, } from "../../workflows/dag/lifecycle.js";
 import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
+import { parseLedgerJson, validateRequirementLedger, } from "../../task/source-prepare/ledger.js";
+import { REQUIREMENT_LEDGER_FILE_NAME } from "../../task/source-prepare/types.js";
 import { loadLifecycleRecord } from "./record.js";
 import { buildGateBinding, buildWriteSetGate, buildWriteSetGateDelta, controllerIdentityAnchor, hashCanonicalPayload, normalizeWriteSet, sha256Hex, } from "./gates.js";
 async function exists(filePath) {
@@ -47,6 +49,140 @@ async function taskExists(repoRoot, taskId) {
     const paths = getTaskPaths(repoRoot, taskId);
     return exists(paths.taskConfigPath);
 }
+async function assessReferenceEvidence(referencesDir) {
+    try {
+        const entries = await readdir(referencesDir);
+        const importedPrdCount = entries.filter((name) => name.endsWith(".md")).length;
+        return importedPrdCount > 0
+            ? { status: "present", importedPrdCount }
+            : { status: "absent-or-empty", importedPrdCount: 0 };
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return { status: "absent-or-empty", importedPrdCount: 0 };
+        }
+        return {
+            status: "unknown",
+            importedPrdCount: 0,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function hasLedgerStructure(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const ledger = value;
+    return (typeof ledger.taskId === "string" &&
+        typeof ledger.inputDigest === "string" &&
+        typeof ledger.requirementSha256 === "string" &&
+        Array.isArray(ledger.sourcePaths) &&
+        Array.isArray(ledger.fragments) &&
+        Array.isArray(ledger.canonicalRequirements) &&
+        Boolean(ledger.stats && typeof ledger.stats === "object") &&
+        Array.isArray(ledger.unresolved) &&
+        Array.isArray(ledger.conflicts) &&
+        Array.isArray(ledger.sourceResolutions) &&
+        typeof ledger.schemaReconcilerVersion === "string" &&
+        typeof ledger.builtAt === "string");
+}
+async function assessSourceFidelityStartup(input) {
+    if (!input.applicable) {
+        return {
+            status: "not-applicable",
+            ledgerPath: input.ledgerPath,
+            diagnostics: [],
+        };
+    }
+    if (input.referenceEvidenceError) {
+        return {
+            status: "invalid",
+            ledgerPath: input.ledgerPath,
+            diagnostics: [
+                {
+                    code: "SOURCE_FIDELITY_LEDGER_STALE",
+                    message: `imported PRD reference evidence is unreadable: ${input.referenceEvidenceError}`,
+                },
+            ],
+        };
+    }
+    let raw;
+    try {
+        raw = await readFile(input.ledgerPath, "utf-8");
+    }
+    catch (error) {
+        const missing = !(await exists(input.ledgerPath));
+        return {
+            status: missing ? "missing" : "invalid",
+            ledgerPath: input.ledgerPath,
+            diagnostics: [
+                {
+                    code: missing
+                        ? "SOURCE_FIDELITY_LEDGER_MISSING"
+                        : "SOURCE_FIDELITY_LEDGER_STALE",
+                    message: missing
+                        ? "managed frontend task has no requirement-ledger.json"
+                        : `requirement ledger is unreadable: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+        };
+    }
+    try {
+        const ledger = parseLedgerJson(raw);
+        if (!hasLedgerStructure(ledger)) {
+            return {
+                status: "invalid",
+                ledgerPath: input.ledgerPath,
+                diagnostics: [
+                    {
+                        code: "SOURCE_FIDELITY_LEDGER_STALE",
+                        message: "requirement ledger is missing required structural fields",
+                    },
+                ],
+            };
+        }
+        const nonDecisionErrors = validateRequirementLedger(ledger, {
+            allowedUnresolved: true,
+            allowedConflicts: true,
+        });
+        if (nonDecisionErrors.length > 0) {
+            const coverageCodes = new Set([
+                "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+                "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED",
+            ]);
+            return {
+                status: nonDecisionErrors.every((error) => coverageCodes.has(error.code))
+                    ? "coverage-incomplete"
+                    : "invalid",
+                ledgerPath: input.ledgerPath,
+                diagnostics: nonDecisionErrors,
+            };
+        }
+        const decisionErrors = validateRequirementLedger(ledger);
+        if (decisionErrors.length > 0) {
+            return {
+                status: "human-decision-blocked",
+                ledgerPath: input.ledgerPath,
+                diagnostics: decisionErrors,
+            };
+        }
+        return { status: "complete", ledgerPath: input.ledgerPath, diagnostics: [] };
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            ledgerPath: input.ledgerPath,
+            diagnostics: [
+                {
+                    code: "SOURCE_FIDELITY_LEDGER_STALE",
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            ],
+        };
+    }
+}
 /**
  * Explicit Task↔DAG association only:
  * - lifecycle.json recorded runAssociations
@@ -182,10 +318,12 @@ export async function observeTaskLifecycle(repoRoot, taskId) {
     const record = await loadLifecycleRecord(repoRoot, taskId);
     const contractState = await observeTaskContractState(repoRoot, taskId);
     let title;
+    let taskKind;
     let taskConfigAllowed = [];
     try {
         const config = await loadTaskConfig(repoRoot, taskId);
         title = config.title;
+        taskKind = config.taskKind;
         taskConfigAllowed = config.allowedPaths ?? [];
     }
     catch {
@@ -199,19 +337,22 @@ export async function observeTaskLifecycle(repoRoot, taskId) {
         ...(requirementReady ? [] : [requirementPath]),
         ...(constraintsReady ? [] : [constraintsPath]),
     ];
-    let importedPrdCount = 0;
+    const contractManaged = contractState.effectiveStatus === "managed" || Boolean(contractState.ref);
     const referencesDir = path.join(paths.sourceDir, "references");
-    if (await exists(referencesDir)) {
-        // Count is best-effort; absence is fine.
-        try {
-            const { readdir } = await import("node:fs/promises");
-            const entries = await readdir(referencesDir);
-            importedPrdCount = entries.filter((name) => name.endsWith(".md")).length;
-        }
-        catch {
-            importedPrdCount = 0;
-        }
-    }
+    const referenceEvidence = await assessReferenceEvidence(referencesDir);
+    const importedPrdCount = referenceEvidence.importedPrdCount;
+    const ledgerPath = path.join(paths.sourceDir, REQUIREMENT_LEDGER_FILE_NAME);
+    const sourceFidelityStartup = await assessSourceFidelityStartup({
+        ledgerPath,
+        applicable: contractManaged &&
+            taskKind === "frontend-implementation" &&
+            referenceEvidence.status !== "absent-or-empty",
+        referenceEvidenceError: referenceEvidence.status === "unknown"
+            ? referenceEvidence.error
+            : undefined,
+    });
+    const sourceFidelityReady = sourceFidelityStartup.status === "complete" ||
+        sourceFidelityStartup.status === "not-applicable";
     const dagDraftPath = paths.dagDraftPath;
     const dagDraftExists = await exists(dagDraftPath);
     let specHash = null;
@@ -285,7 +426,11 @@ export async function observeTaskLifecycle(repoRoot, taskId) {
     // Open gate only when draft is strict-validated and the current binding is
     // not already approved/rejected. Rejected same-digest gates stay closed
     // until contract/source/DAG/writeSet/controller binding changes.
-    const gate = gateBound && strictValidated && !approvedCurrent && !rejectedCurrent
+    const gate = gateBound &&
+        strictValidated &&
+        sourceFidelityReady &&
+        !approvedCurrent &&
+        !rejectedCurrent
         ? buildWriteSetGate({ taskId, bound: gateBound, delta: gateDelta })
         : null;
     const gateOpen = Boolean(gate);
@@ -310,11 +455,10 @@ export async function observeTaskLifecycle(repoRoot, taskId) {
                 activeRun.failureCategory === "needs-attention" ||
                 activeRun.failureCategory === "suspected-stall" ||
                 activeRun.failureCategory === "monitor-timeout"));
-    const contractManaged = contractState.effectiveStatus === "managed" || Boolean(contractState.ref);
     const lifecycleState = deriveLifecycleState({
         exists: true,
         contractManaged,
-        sourceReady: requirementReady,
+        sourceReady: requirementReady && sourceFidelityReady,
         dagValidated: strictValidated,
         gateOpen: Boolean(gate),
         activeRun,
@@ -352,6 +496,7 @@ export async function observeTaskLifecycle(repoRoot, taskId) {
             constraintsReady,
             importedPrdCount,
             missing,
+            sourceFidelityStartup,
         },
         dagDraft: {
             path: dagDraftPath,
@@ -375,7 +520,16 @@ export async function observeTaskLifecycle(repoRoot, taskId) {
             exists: closeoutExists || Boolean(record?.closeout),
         },
         completedTransitions: record?.completedTransitions ?? [],
-        blockers: [],
+        blockers: sourceFidelityReady
+            ? []
+            : sourceFidelityStartup.diagnostics.map((diagnostic) => ({
+                code: diagnostic.code,
+                message: diagnostic.message,
+                details: {
+                    startupStatus: sourceFidelityStartup.status,
+                    ledgerPath: sourceFidelityStartup.ledgerPath,
+                },
+            })),
         warnings: [],
         next,
     };

package/dist/application/task-lifecycle/plan-transitions.js

@@ -46,6 +46,37 @@ export function planTransitions(input) {
         actions.push({ type: "recover-contract" });
         expectedTransitions.push("contract-recovered");
     }
+    const startupStatus = snapshot.source?.sourceFidelityStartup?.status;
+    const startupRepairDetected = startupStatus === "missing" ||
+        startupStatus === "invalid" ||
+        startupStatus === "coverage-incomplete";
+    if (startupRepairDetected && input.startupRepairAttempted) {
+        actions.push({ type: "stop", reason: "blocker" });
+        return {
+            actions,
+            gate: null,
+            blockers,
+            next: {
+                kind: "advance",
+                command: `loop-agent task advance ${snapshot.taskId} --json`,
+            },
+            expectedTransitions,
+        };
+    }
+    const startupRepairRequired = startupRepairDetected;
+    if (startupStatus === "human-decision-blocked") {
+        actions.push({ type: "stop", reason: "blocker" });
+        return {
+            actions,
+            gate: null,
+            blockers,
+            next: {
+                kind: "external-action",
+                description: "Requirement ledger requires an existing human source decision; preserve sourceResolutions, resolve the blocker, then advance again.",
+            },
+            expectedTransitions,
+        };
+    }
     const sourceReady = snapshot.source?.requirementReady === true;
     const contractManaged = snapshot.contract?.effectiveStatus === "managed" ||
         Boolean(snapshot.contract?.revision && snapshot.contract.revision > 0);
@@ -53,7 +84,9 @@ export function planTransitions(input) {
     // Prefer prepare once PRDs are on disk; re-import only when caller still
     // signals hasPrdInput (advance.ts latches this after one import per call).
     const shouldImportPrd = input.hasPrdInput;
-    if (input.forcePrepareContract || input.refreshManagedContract) {
+    if (input.forcePrepareContract ||
+        input.refreshManagedContract ||
+        startupRepairRequired) {
         if (shouldImportPrd) {
             actions.push({ type: "import-prd" });
             expectedTransitions.push("prd-imported");
@@ -124,7 +157,8 @@ export function planTransitions(input) {
     const strictValidated = snapshot.dagDraft?.strictValidated === true;
     const dagRefreshRequired = Boolean(input.forceDagRefresh ||
         input.refreshManagedContract ||
-        input.forcePrepareContract);
+        input.forcePrepareContract ||
+        startupRepairRequired);
     if (!dagExists || dagRefreshRequired) {
         actions.push({ type: "generate-dag" });
         expectedTransitions.push("dag-generated");
@@ -145,10 +179,11 @@ export function planTransitions(input) {
         snapshot.lifecycleState === "evidence-closed" ||
         snapshot.lifecycleState === "needs-attention" ||
         snapshot.lifecycleState === "awaiting-decision";
-    const approvedForCurrent = postRunState || (input.approveGate && gate !== null);
+    const approveCurrentGate = input.approveGate && !dagRefreshRequired;
+    const approvedForCurrent = postRunState || (approveCurrentGate && gate !== null);
     if (!approvedForCurrent && (strictValidated || !dagExists || dagRefreshRequired)) {
         // Gate opens after generate+validate in the advance loop; plan includes open.
-        if (!input.approveGate) {
+        if (!approveCurrentGate) {
             actions.push({ type: "open-write-set-gate" });
             expectedTransitions.push("write-set-gate-opened");
             if (input.dryRun) {
@@ -177,14 +212,14 @@ export function planTransitions(input) {
         (snapshot.lifecycleState === "run-failed" && !failedRecoverable) ||
         snapshot.lifecycleState === "evidence-closed";
     if (!alreadyTerminalRun) {
-        if (input.approveGate && !postRunState) {
+        if (approveCurrentGate && !postRunState) {
             expectedTransitions.push("write-set-approved");
             actions.push({ type: "start-or-monitor-run" });
             expectedTransitions.push("dag-run-started", "dag-run-monitored");
         }
         else if (snapshot.lifecycleState === "running" ||
             snapshot.activeRun ||
-            (input.approveGate && Boolean(snapshot.activeRun))) {
+            (approveCurrentGate && Boolean(snapshot.activeRun))) {
             actions.push({ type: "start-or-monitor-run" });
             expectedTransitions.push("dag-run-monitored");
         }
@@ -218,7 +253,7 @@ export function planTransitions(input) {
         actions,
         gate,
         blockers,
-        next: deriveNext(snapshot, gate, input.approveGate),
+        next: deriveNext(snapshot, gate, approveCurrentGate),
         expectedTransitions,
     };
 }

package/dist/application/task-lifecycle/recommendations.js

@@ -42,6 +42,7 @@ export async function buildTaskLifecycleRecommendations(input) {
     const allowedPaths = [];
     const verifyCommands = [];
     // 1) managed task config
+    let hasDeclaredManagedVerify = false;
     try {
         const config = await loadTaskConfig(input.repoRoot, input.taskId);
         for (const glob of config.allowedPaths ?? []) {
@@ -53,7 +54,9 @@ export async function buildTaskLifecycleRecommendations(input) {
                 source: "managed-task-config",
             });
         }
-        for (const cmd of config.verifyCommands ?? []) {
+        const managedVerify = (config.verifyCommands ?? []).filter((cmd) => Boolean(cmd.command?.trim()));
+        hasDeclaredManagedVerify = managedVerify.length > 0;
+        for (const cmd of managedVerify) {
             const label = cmd.label?.trim() || "verify";
             const command = cmd.command?.trim();
             if (!command)
@@ -70,14 +73,22 @@ export async function buildTaskLifecycleRecommendations(input) {
         // task may not exist yet
     }
     // 2) package.json scripts (only if not already covered by managed config)
+    // The full-suite `test` script is recommended only when the task declares
+    // NO managed verifyCommands at all. Once a task configures a targeted
+    // verify set (e.g. per-change typecheck + a scoped vitest run), the full
+    // `npm run test` must never be auto-added: it validates the whole repo,
+    // costs far more than the change under review, and can fail on unrelated
+    // pre-existing breakage, turning a targeted verify green into a hard fail.
     const scripts = await readPackageScripts(input.repoRoot);
     const hasVerifyLabel = (label) => verifyCommands.some((entry) => entry.label === label);
     const scriptCandidates = [
         { label: "typecheck", script: "typecheck" },
-        { label: "test", script: "test" },
         { label: "check-repo", script: "check:repo" },
         { label: "check-repo", script: "check-repo" },
     ];
+    if (!hasDeclaredManagedVerify) {
+        scriptCandidates.push({ label: "test", script: "test" });
+    }
     for (const candidate of scriptCandidates) {
         const scriptBody = scripts[candidate.script];
         if (!scriptBody)

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.42.0-next.2",
-  "gitSha": "464c462ece3604d8b6c7b44a7a915e5465bbc84f",
-  "builtAt": "2026-08-31T12:53:12.759Z"
+  "version": "0.42.0-next.4",
+  "gitSha": "67e59744bed3b112db83511b2d330b46a9caeb4e",
+  "builtAt": "2026-09-01T05:04:11.489Z"
 }

package/dist/cli/command-definitions.js

@@ -37,6 +37,7 @@ import { runDagReconcileTasks } from "../commands/dag-reconcile-tasks.js";
 import { runDagReconcileRun } from "../commands/dag-reconcile-run.js";
 import { runDagRequestInterrupt } from "../commands/dag-request-interrupt.js";
 import { runDagRerunTask } from "../commands/dag-rerun-task.js";
+import { runDagFollowUp } from "../commands/dag-follow-up.js";
 import { runDagRerun } from "../commands/dag-rerun.js";
 import { runDagResume } from "../commands/dag-resume.js";
 import { runDagDecisionInspect, runDagDecisionValidate, } from "../workflows/dag/decision-envelope.js";
@@ -137,6 +138,7 @@ const DAG_SUBCOMMANDS = [
     "request-interrupt",
     "rerun",
     "rerun-task",
+    "follow-up",
     "reconcile-tasks",
     "final-verification",
     "context",
@@ -585,6 +587,11 @@ export const COMMAND_DEFINITIONS = [
                 await runDagRerunTask(repoRoot, rerunTaskArgs);
                 return;
             }
+            if (subcommand === "follow-up") {
+                const followUpArgs = rest.filter((arg) => Boolean(arg));
+                await runDagFollowUp(repoRoot, followUpArgs);
+                return;
+            }
             if (subcommand === "reconcile-tasks") {
                 const reconcileArgs = rest.filter((arg) => Boolean(arg));
                 await runDagReconcileTasks(repoRoot, reconcileArgs);

package/dist/cli/program.js

@@ -15,6 +15,7 @@ import { runDagReconcileTasks } from "../commands/dag-reconcile-tasks.js";
 import { runDagReconcileRun } from "../commands/dag-reconcile-run.js";
 import { runDagRequestInterrupt } from "../commands/dag-request-interrupt.js";
 import { runDagRerunTask } from "../commands/dag-rerun-task.js";
+import { runDagFollowUp } from "../commands/dag-follow-up.js";
 import { runDagRerun } from "../commands/dag-rerun.js";
 import { runDagReject } from "../commands/dag-reject.js";
 import { runDagCloseoutDraft, runDagReport } from "../commands/dag-report.js";
@@ -359,6 +360,9 @@ async function runDagAction(repoRoot, subcommand, rest) {
         case "rerun-task":
             await runDagRerunTask(repoRoot, args);
             return;
+        case "follow-up":
+            await runDagFollowUp(repoRoot, args);
+            return;
         case "reconcile-tasks":
             await runDagReconcileTasks(repoRoot, args);
             return;
@@ -553,6 +557,7 @@ function addDagCommand(program, defaultRepoRoot) {
         "request-interrupt",
         "rerun",
         "rerun-task",
+        "follow-up",
         "reconcile-tasks",
         "final-verification",
         "context",

package/dist/commands/client-recovery.js

@@ -1328,12 +1328,15 @@ export async function runClientRecovery(input) {
     }
     const plugin = await installProjectOpenCodePlugin({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const overflowPlugin = await installProjectOpenCodeOverflowCompactPlugin({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const piExtension = await installProjectPiContextOverflowExtension({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const pi = await applyProjectPiSettingsMerge({ repoRoot: input.repoRoot });
     if (mode !== "user") {