@tea-agent/loop-agent 0.1.0-fe-test.0

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

@@ -0,0 +1,251 @@
+/**
+ * Pure reducer: given a lifecycle snapshot + intent flags, decide the next
+ * safe automatic transitions until a stop condition.
+ */
+export function planTransitions(input) {
+    const { snapshot } = input;
+    const actions = [];
+    const expectedTransitions = [];
+    const blockers = [...snapshot.blockers];
+    if (input.rejectGate) {
+        return {
+            actions: [{ type: "stop", reason: "terminal" }],
+            gate: snapshot.gate ?? null,
+            blockers,
+            next: {
+                kind: "advance",
+                command: `loop-agent task advance ${snapshot.taskId} --json`,
+            },
+            expectedTransitions: ["write-set-rejected"],
+        };
+    }
+    if (!snapshot.exists) {
+        // Create is always allowed when advance is invoked for a missing task.
+        // Further intake (PRD/boundaries) is required before contract/DAG steps.
+        actions.push({ type: "create-task" });
+        expectedTransitions.push("task-created");
+        if (!input.hasPrdInput && !input.hasEngineeringBoundary) {
+            actions.push({ type: "stop", reason: "blocker" });
+            blockers.push({
+                code: "INTAKE_REQUIRED",
+                message: "task created or creatable; provide --prd and engineering boundary flags (or --from-text) to continue",
+            });
+            return {
+                actions,
+                gate: null,
+                blockers,
+                next: {
+                    kind: "advance",
+                    command: `loop-agent task advance ${snapshot.taskId} --prd <path> --allowed-path <glob> --json`,
+                },
+                expectedTransitions,
+            };
+        }
+    }
+    if (snapshot.contract?.transactionIncomplete) {
+        actions.push({ type: "recover-contract" });
+        expectedTransitions.push("contract-recovered");
+    }
+    const sourceReady = snapshot.source?.requirementReady === true;
+    const contractManaged = snapshot.contract?.effectiveStatus === "managed" ||
+        Boolean(snapshot.contract?.revision && snapshot.contract.revision > 0);
+    const alreadyImportedPrd = (snapshot.source?.importedPrdCount ?? 0) > 0;
+    // 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 (shouldImportPrd) {
+            actions.push({ type: "import-prd" });
+            expectedTransitions.push("prd-imported");
+        }
+        actions.push({ type: "prepare-contract" });
+        expectedTransitions.push("contract-managed");
+    }
+    else if (!sourceReady || !contractManaged) {
+        // Console PRD Intake Bridge (2026-08-11), two-phase:
+        // 1) hasPrdInput without engineering boundary → import only (archive
+        //    references). Do NOT prepare yet so multi-file bootstrap can finish
+        //    all imports before the one-shot Semantic Intake burns.
+        // 2) alreadyImportedPrd without new --prd (and/or with boundary) →
+        //    prepare-contract so deterministic parse + Semantic Intake run.
+        // prepare soft-stops on EMPTY_ALLOWED_PATHS etc. and never opens the
+        // writeSet gate without a complete managed contract.
+        if (shouldImportPrd && !input.hasEngineeringBoundary) {
+            actions.push({ type: "import-prd" });
+            expectedTransitions.push("prd-imported");
+            actions.push({ type: "stop", reason: "blocker" });
+            blockers.push({
+                code: "BOUNDARY_REQUIRED",
+                message: "PRD imported; re-run task advance (optionally with --allowed-path / --verify) to prepare contract / semantic intake",
+            });
+            return {
+                actions,
+                gate: null,
+                blockers,
+                next: {
+                    kind: "advance",
+                    command: `loop-agent task advance ${snapshot.taskId} --json`,
+                },
+                expectedTransitions,
+            };
+        }
+        if (shouldImportPrd ||
+            input.hasEngineeringBoundary ||
+            alreadyImportedPrd) {
+            if (shouldImportPrd) {
+                actions.push({ type: "import-prd" });
+                expectedTransitions.push("prd-imported");
+            }
+            actions.push({ type: "prepare-contract" });
+            expectedTransitions.push("contract-managed");
+        }
+        else {
+            // Task exists (e.g. just created in this advance loop) but intake is
+            // still incomplete. Soft-stop with INTAKE_REQUIRED so create-only /
+            // Console bootstrap does not attempt prepare-contract on empty facts.
+            actions.push({ type: "stop", reason: "blocker" });
+            blockers.push({
+                code: "INTAKE_REQUIRED",
+                message: "task created or creatable; provide --prd and engineering boundary flags (or --from-text) to continue",
+            });
+            return {
+                actions,
+                gate: null,
+                blockers,
+                next: {
+                    kind: "advance",
+                    command: `loop-agent task advance ${snapshot.taskId} --prd <path> --allowed-path <glob> --json`,
+                },
+                expectedTransitions,
+            };
+        }
+    }
+    const dagExists = snapshot.dagDraft?.exists === true;
+    const strictValidated = snapshot.dagDraft?.strictValidated === true;
+    const dagRefreshRequired = Boolean(input.forceDagRefresh ||
+        input.refreshManagedContract ||
+        input.forcePrepareContract);
+    if (!dagExists || dagRefreshRequired) {
+        actions.push({ type: "generate-dag" });
+        expectedTransitions.push("dag-generated");
+    }
+    if (!strictValidated || dagRefreshRequired) {
+        actions.push({ type: "strict-validate-dag" });
+        expectedTransitions.push("dag-strict-validated");
+    }
+    // After validate, open write-set gate unless already approved/rejected for current digest.
+    const gate = snapshot.gate ?? null;
+    // run-failed is terminal only when there is no current open gate. An open
+    // current writeSet gate supersedes an older failed run so recovery approve
+    // can start the next DAG run (observe may already report awaiting).
+    const failedRecoverable = snapshot.lifecycleState === "run-failed" && gate !== null;
+    const postRunState = snapshot.lifecycleState === "running" ||
+        snapshot.lifecycleState === "run-succeeded" ||
+        (snapshot.lifecycleState === "run-failed" && !failedRecoverable) ||
+        snapshot.lifecycleState === "evidence-closed" ||
+        snapshot.lifecycleState === "needs-attention" ||
+        snapshot.lifecycleState === "awaiting-decision";
+    const approvedForCurrent = postRunState || (input.approveGate && gate !== null);
+    if (!approvedForCurrent && (strictValidated || !dagExists || dagRefreshRequired)) {
+        // Gate opens after generate+validate in the advance loop; plan includes open.
+        if (!input.approveGate) {
+            actions.push({ type: "open-write-set-gate" });
+            expectedTransitions.push("write-set-gate-opened");
+            if (input.dryRun) {
+                actions.push({ type: "stop", reason: "dry-run" });
+            }
+            else {
+                actions.push({ type: "stop", reason: "gate" });
+            }
+            return {
+                actions,
+                gate,
+                blockers,
+                next: gate
+                    ? { kind: "approve-gate", command: gate.approveCommand }
+                    : {
+                        kind: "advance",
+                        command: `loop-agent task advance ${snapshot.taskId} --json`,
+                    },
+                expectedTransitions,
+            };
+        }
+    }
+    // Only start/monitor when not already in a terminal post-run state.
+    // Keep run-succeeded / evidence-closed terminal; allow run-failed + open gate.
+    const alreadyTerminalRun = snapshot.lifecycleState === "run-succeeded" ||
+        (snapshot.lifecycleState === "run-failed" && !failedRecoverable) ||
+        snapshot.lifecycleState === "evidence-closed";
+    if (!alreadyTerminalRun) {
+        if (input.approveGate && !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))) {
+            actions.push({ type: "start-or-monitor-run" });
+            expectedTransitions.push("dag-run-monitored");
+        }
+    }
+    if (!input.skipFinalize &&
+        (snapshot.lifecycleState === "run-succeeded" ||
+            (snapshot.latestRun?.lifecycle === "completed" &&
+                snapshot.latestRun.status === "finished"))) {
+        if (!snapshot.promotion?.ready) {
+            actions.push({ type: "promote" });
+            expectedTransitions.push("promotion-completed");
+        }
+        if (!snapshot.closeout?.exists) {
+            actions.push({ type: "closeout" });
+            expectedTransitions.push("closeout-completed");
+        }
+    }
+    if (snapshot.lifecycleState === "evidence-closed") {
+        return {
+            actions: [{ type: "stop", reason: "terminal" }],
+            gate: null,
+            blockers,
+            next: { kind: "none" },
+            expectedTransitions: [],
+        };
+    }
+    if (input.dryRun) {
+        actions.push({ type: "stop", reason: "dry-run" });
+    }
+    return {
+        actions,
+        gate,
+        blockers,
+        next: deriveNext(snapshot, gate, input.approveGate),
+        expectedTransitions,
+    };
+}
+function deriveNext(snapshot, gate, approveGate) {
+    if (gate && !approveGate) {
+        return { kind: "approve-gate", command: gate.approveCommand };
+    }
+    if (snapshot.lifecycleState === "evidence-closed") {
+        return { kind: "none" };
+    }
+    // Keep planner semantics aligned with observe (AC-001): a terminal failed
+    // run without an open gate must not recommend task advance — advance cannot
+    // progress a terminal run state.
+    if (snapshot.lifecycleState === "run-failed" && !gate) {
+        return {
+            kind: "external-action",
+            description: "The latest DAG run failed and is terminal; task advance cannot progress it. Read the run report (loop-agent dag report --run-id <runId> --json), then follow the recovery guidance (eligible node rerun / same-task recovery) or fix the root cause before advancing.",
+        };
+    }
+    if (snapshot.lifecycleState === "run-succeeded" && !gate) {
+        return {
+            kind: "external-action",
+            description: "The latest DAG run succeeded; task advance cannot progress it. Run promotion/closeout via the lifecycle closeout path or archive the task.",
+        };
+    }
+    return {
+        kind: "advance",
+        command: `loop-agent task advance ${snapshot.taskId} --json`,
+    };
+}

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

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { loadTaskConfig } from "../../task/runtime.js";
+function sha256Canonical(value) {
+    const json = JSON.stringify(value);
+    return `sha256:${createHash("sha256").update(json, "utf8").digest("hex")}`;
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readPackageScripts(repoRoot) {
+    const packageJsonPath = path.join(repoRoot, "package.json");
+    if (!(await pathExists(packageJsonPath)))
+        return {};
+    try {
+        const raw = await readFile(packageJsonPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed.scripts ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Deterministic engineering-boundary recommendations (P1).
+ *
+ * Priority:
+ * 1. managed task config (highest)
+ * 2. package.json scripts (typecheck/test/check-repo)
+ * 3. PRD path-like tokens as weak candidates only (never auto-elevated)
+ *
+ * Recommendations never enter contract draft unless acceptDigest matches.
+ */
+export async function buildTaskLifecycleRecommendations(input) {
+    const allowedPaths = [];
+    const verifyCommands = [];
+    // 1) managed task config
+    try {
+        const config = await loadTaskConfig(input.repoRoot, input.taskId);
+        for (const glob of config.allowedPaths ?? []) {
+            if (!glob.trim())
+                continue;
+            allowedPaths.push({
+                glob: glob.trim(),
+                reason: "existing managed task.json.allowedPaths",
+                source: "managed-task-config",
+            });
+        }
+        for (const cmd of config.verifyCommands ?? []) {
+            const label = cmd.label?.trim() || "verify";
+            const command = cmd.command?.trim();
+            if (!command)
+                continue;
+            verifyCommands.push({
+                label,
+                command,
+                reason: "existing managed task.json.verifyCommands",
+                source: "managed-task-config",
+            });
+        }
+    }
+    catch {
+        // task may not exist yet
+    }
+    // 2) package.json scripts (only if not already covered by managed config)
+    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" },
+    ];
+    for (const candidate of scriptCandidates) {
+        const scriptBody = scripts[candidate.script];
+        if (!scriptBody)
+            continue;
+        if (hasVerifyLabel(candidate.label))
+            continue;
+        verifyCommands.push({
+            label: candidate.label,
+            command: `npm run ${candidate.script}`,
+            reason: `package.json scripts.${candidate.script}`,
+            source: "package-scripts",
+        });
+    }
+    // 3) weak PRD path candidates (never auto-accepted alone)
+    const prdTexts = input.prdTexts ?? [];
+    const seenGlobs = new Set(allowedPaths.map((entry) => entry.glob));
+    const pathLike = /(?:^|[\s`"'(])((?:src|test|tests|docs|website|scripts|skills)\/[A-Za-z0-9_./ conf-]+(?:\/\*\*)?)/gm;
+    for (const text of prdTexts) {
+        for (const match of text.matchAll(pathLike)) {
+            const raw = match[1]?.trim();
+            if (!raw)
+                continue;
+            const glob = raw.endsWith("/**")
+                ? raw
+                : raw.endsWith("/")
+                    ? `${raw}**`
+                    : raw.includes("*")
+                        ? raw
+                        : `${raw.replace(/\/$/, "")}/**`;
+            if (seenGlobs.has(glob))
+                continue;
+            // Skip overly broad roots
+            if (glob === "src/**" || glob === "docs/**" || glob === "test/**") {
+                // still allow as weak candidate with explicit reason
+            }
+            seenGlobs.add(glob);
+            allowedPaths.push({
+                glob,
+                reason: "path-like token in PRD (weak candidate; not auto-elevated)",
+                source: "prd-weak-candidate",
+            });
+        }
+    }
+    // Stable sort for digest
+    allowedPaths.sort((a, b) => a.glob.localeCompare(b.glob));
+    verifyCommands.sort((a, b) => a.label.localeCompare(b.label));
+    const digestPayload = {
+        schemaVersion: 1,
+        taskId: input.taskId,
+        allowedPaths: allowedPaths.map((entry) => ({
+            glob: entry.glob,
+            source: entry.source,
+        })),
+        verifyCommands: verifyCommands.map((entry) => ({
+            label: entry.label,
+            command: entry.command,
+            source: entry.source,
+        })),
+    };
+    const digest = sha256Canonical(digestPayload);
+    return {
+        allowedPaths,
+        verifyCommands,
+        digest,
+        requiresAccept: true,
+    };
+}
+export function applyAcceptedRecommendations(input) {
+    const explicitAllowed = input.explicitAllowedPaths ?? [];
+    const explicitVerify = input.explicitVerifyCommands ?? [];
+    if (explicitAllowed.length > 0 || explicitVerify.length > 0) {
+        return {
+            allowedPaths: explicitAllowed.length > 0 ? explicitAllowed : undefined,
+            verifyCommands: explicitVerify.length > 0 ? explicitVerify : undefined,
+            accepted: false,
+            staleAccept: false,
+        };
+    }
+    const accept = input.acceptDigest?.trim();
+    if (!accept) {
+        return { accepted: false, staleAccept: false };
+    }
+    if (accept !== input.recommendations.digest) {
+        return { accepted: false, staleAccept: true };
+    }
+    // Only elevate non-weak sources automatically when accepted.
+    const allowedPaths = input.recommendations.allowedPaths
+        .filter((entry) => entry.source !== "prd-weak-candidate")
+        .map((entry) => entry.glob);
+    const verifyCommands = input.recommendations.verifyCommands.map((entry) => ({
+        label: entry.label,
+        command: entry.command,
+    }));
+    return {
+        allowedPaths: allowedPaths.length > 0 ? allowedPaths : undefined,
+        verifyCommands: verifyCommands.length > 0 ? verifyCommands : undefined,
+        accepted: true,
+        staleAccept: false,
+    };
+}

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

@@ -0,0 +1,73 @@
+import { access, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { getTaskDir } from "../../task/runtime.js";
+export function getLifecycleRecordPath(repoRoot, taskId) {
+    return path.join(getTaskDir(repoRoot, taskId), "lifecycle.json");
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function loadLifecycleRecord(repoRoot, taskId) {
+    const filePath = getLifecycleRecordPath(repoRoot, taskId);
+    if (!(await exists(filePath)))
+        return null;
+    try {
+        const raw = JSON.parse(await readFile(filePath, "utf-8"));
+        if (raw.schemaVersion !== 1 || raw.taskId !== taskId)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function emptyLifecycleRecord(taskId) {
+    return {
+        schemaVersion: 1,
+        taskId,
+        updatedAt: new Date().toISOString(),
+        completedTransitions: [],
+        runAssociations: [],
+    };
+}
+export async function saveLifecycleRecord(repoRoot, record) {
+    const filePath = getLifecycleRecordPath(repoRoot, record.taskId);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const next = {
+        ...record,
+        updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(filePath, next);
+}
+export function appendTransition(record, transition) {
+    if (record.completedTransitions.includes(transition)) {
+        return record;
+    }
+    return {
+        ...record,
+        completedTransitions: [...record.completedTransitions, transition],
+    };
+}
+export function recordRunAssociation(record, run) {
+    if (record.runAssociations.some((entry) => entry.runId === run.runId)) {
+        return record;
+    }
+    return {
+        ...record,
+        runAssociations: [
+            ...record.runAssociations,
+            {
+                runId: run.runId,
+                recordedAt: new Date().toISOString(),
+                source: run.source,
+            },
+        ],
+    };
+}

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

@@ -0,0 +1 @@
+export const TASK_LIFECYCLE_SCHEMA_VERSION = 1;

package/dist/build-stamp.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "version": "0.1.0-fe-test.0",
+  "gitSha": "ba5bae8692aa3c2ec0ceeeefc3bb45e2adaa6569",
+  "builtAt": "2026-08-20T08:23:07.508Z"
+}

package/dist/cli/catalog.js

@@ -0,0 +1,24 @@
+import { COMMAND_DEFINITIONS, toCommandManifestEntry, } from "./command-definitions.js";
+/** Order remains stable for compatibility; tiers provide the selection signal. */
+export const CODE_AGENT_COMMAND_MANIFEST = COMMAND_DEFINITIONS.map(toCommandManifestEntry);
+export const CODE_AGENT_TOP_LEVEL_COMMANDS = CODE_AGENT_COMMAND_MANIFEST.map((entry) => entry.name);
+export function listCommandsByTier(tier, manifest = CODE_AGENT_COMMAND_MANIFEST) {
+    return manifest.filter((entry) => entry.tier === tier);
+}
+export function listCompatibilityOnlyCommands(manifest = CODE_AGENT_COMMAND_MANIFEST) {
+    return manifest.filter((entry) => entry.compatibilityStatus === "compatibility-only" ||
+        entry.compatibilityStatus === "deprecated-candidate");
+}
+export function isRegisteredTopLevelCommand(command, manifest = CODE_AGENT_COMMAND_MANIFEST) {
+    if (!command)
+        return false;
+    return manifest.some((entry) => entry.name === command);
+}
+export function findCommandManifestEntry(name, manifest = CODE_AGENT_COMMAND_MANIFEST) {
+    return manifest.find((entry) => entry.name === name);
+}
+export function listCommandsRequiringAdapter(manifest = CODE_AGENT_COMMAND_MANIFEST) {
+    return manifest
+        .filter((entry) => entry.adapter === "required")
+        .map((entry) => entry.name);
+}