@tea-agent/loop-agent 0.26.0 → 0.26.2

package/dist/task/source-prepare/build-draft.js

@@ -0,0 +1,224 @@
+import { TASK_CONTRACT_DRAFT_SCHEMA_VERSION } from "../contract/constants.js";
+import { taskKindSchema } from "../config-types.js";
+import { assessPreparePaths, mergeForbiddenPaths, normalizePreparePath, dedupeStable, } from "./path-policy.js";
+function trimNonEmpty(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function cleanStringList(values) {
+    if (values === undefined)
+        return undefined;
+    return values.map((v) => v.trim()).filter(Boolean);
+}
+function resolveTaskKind(flags, baseDraft, existing) {
+    const candidate = flags.taskKind ?? baseDraft?.taskKind ?? existing?.taskKind ?? "standard";
+    const parsed = taskKindSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : String(candidate);
+}
+function resolveTitle(taskId, flags, facts, baseDraft, existing) {
+    return (trimNonEmpty(flags.title) ??
+        trimNonEmpty(baseDraft?.title) ??
+        trimNonEmpty(facts?.title) ??
+        trimNonEmpty(existing?.title) ??
+        taskId);
+}
+function resolveObjective(flags, facts, baseDraft, title) {
+    return (trimNonEmpty(flags.objective) ??
+        trimNonEmpty(baseDraft?.requirement.objective) ??
+        trimNonEmpty(facts?.objective) ??
+        title);
+}
+function resolveStringArrayField(input) {
+    if (input.explicit !== undefined) {
+        return cleanStringList(input.explicit) ?? [];
+    }
+    if (input.base && input.base.length > 0)
+        return [...input.base];
+    if (input.facts && input.facts.length > 0)
+        return [...input.facts];
+    return [];
+}
+function resolveAcceptance(input) {
+    if (input.explicit !== undefined) {
+        return input.explicit
+            .map((item) => ({ id: item.id.trim(), text: item.text.trim() }))
+            .filter((item) => item.id && item.text);
+    }
+    if (input.base && input.base.length > 0)
+        return [...input.base];
+    if (input.facts && input.facts.length > 0)
+        return [...input.facts];
+    return [];
+}
+function resolveAllowedPaths(input) {
+    const source = input.flags.allowedPaths !== undefined
+        ? (cleanStringList(input.flags.allowedPaths) ?? [])
+        : input.baseDraft?.constraints.allowedPaths?.length
+            ? [...input.baseDraft.constraints.allowedPaths]
+            : input.existing?.allowedPaths?.length
+                ? [...input.existing.allowedPaths]
+                : [];
+    return source.map((raw) => {
+        const n = normalizePreparePath(raw);
+        return n.ok ? n.value : raw.trim();
+    });
+}
+function resolveAllowedRoots(input) {
+    const roots = input.flags.allowedRoots ?? input.baseDraft?.constraints.allowedRoots ?? input.existing?.allowedRoots;
+    return roots === undefined ? undefined : (cleanStringList(roots) ?? []).map((raw) => {
+        const normalized = normalizePreparePath(raw);
+        return normalized.ok ? normalized.value : raw.trim();
+    });
+}
+function resolveVerifyCommands(input) {
+    if (input.flags.verifyCommands !== undefined) {
+        return input.flags.verifyCommands.map((cmd) => ({
+            label: cmd.label.trim(),
+            command: cmd.command.trim(),
+            ...(cmd.timeoutMs !== undefined ? { timeoutMs: cmd.timeoutMs } : {}),
+        }));
+    }
+    if (input.baseDraft?.verification.commands?.length) {
+        return input.baseDraft.verification.commands.map((cmd) => ({
+            label: cmd.label,
+            command: cmd.command,
+            ...(cmd.timeoutMs !== undefined ? { timeoutMs: cmd.timeoutMs } : {}),
+        }));
+    }
+    if (input.existing?.verifyCommands?.length) {
+        return input.existing.verifyCommands.map((cmd) => ({
+            label: cmd.label,
+            command: cmd.command,
+            ...(cmd.timeoutMs !== undefined ? { timeoutMs: cmd.timeoutMs } : {}),
+        }));
+    }
+    return [];
+}
+/**
+ * Build a thin TaskContractDraftV1 from draft base / PRD facts / flags / task config.
+ * Engineering fields never come from PRD facts.
+ */
+export function buildPrepareDraft(input) {
+    const { taskId, existingTaskConfig, baseDraft, facts, flags, references } = input;
+    const title = resolveTitle(taskId, flags, facts, baseDraft, existingTaskConfig);
+    const taskKind = resolveTaskKind(flags, baseDraft, existingTaskConfig);
+    const featureId = trimNonEmpty(flags.featureId) ??
+        trimNonEmpty(baseDraft?.featureId) ??
+        trimNonEmpty(existingTaskConfig?.featureId) ??
+        undefined;
+    const objective = resolveObjective(flags, facts, baseDraft, title);
+    const scope = resolveStringArrayField({
+        explicit: flags.scope,
+        base: baseDraft?.requirement.scope,
+        facts: facts?.scope,
+    });
+    const nonGoals = resolveStringArrayField({
+        explicit: flags.nonGoals,
+        base: baseDraft?.requirement.nonGoals,
+        facts: facts?.nonGoals,
+    });
+    const acceptanceCriteria = resolveAcceptance({
+        explicit: flags.acceptanceCriteria,
+        base: baseDraft?.requirement.acceptanceCriteria,
+        facts: facts?.acceptanceCriteria,
+    });
+    const allowedPaths = resolveAllowedPaths({
+        flags,
+        baseDraft,
+        existing: existingTaskConfig,
+    });
+    const allowedRoots = resolveAllowedRoots({ flags, baseDraft, existing: existingTaskConfig });
+    // D12: protected defaults always merge unless explicitly disabled.
+    // Explicit --forbidden-path appends; does not replace defaults.
+    const finalForbidden = mergeForbiddenPaths({
+        existing: baseDraft?.constraints.forbiddenPaths ??
+            existingTaskConfig?.forbiddenPaths ??
+            [],
+        explicit: flags.forbiddenPaths,
+        noDefaultForbiddenPaths: flags.noDefaultForbiddenPaths,
+    });
+    const invariants = resolveStringArrayField({
+        explicit: flags.invariants,
+        base: baseDraft?.constraints.invariants,
+        facts: facts?.invariants,
+    });
+    const openQuestions = resolveStringArrayField({
+        explicit: flags.openQuestions,
+        base: baseDraft?.openQuestions,
+        facts: facts?.openQuestions,
+    });
+    const assumptions = resolveStringArrayField({
+        explicit: flags.assumptions,
+        base: baseDraft?.assumptions,
+        facts: facts?.assumptions,
+    });
+    const verifyCommands = resolveVerifyCommands({
+        flags,
+        baseDraft,
+        existing: existingTaskConfig,
+    });
+    const pathAssessment = assessPreparePaths({
+        allowedPaths,
+        forbiddenPaths: finalForbidden,
+        noDefaultForbiddenPaths: flags.noDefaultForbiddenPaths,
+    });
+    const draft = {
+        schemaVersion: TASK_CONTRACT_DRAFT_SCHEMA_VERSION,
+        taskId,
+        title,
+        taskKind: taskKind,
+        requirement: {
+            objective,
+            scope,
+            nonGoals,
+            acceptanceCriteria,
+        },
+        constraints: {
+            invariants,
+            allowedPaths: pathAssessment.allowed.length > 0
+                ? pathAssessment.allowed
+                : dedupeStable(allowedPaths),
+            forbiddenPaths: pathAssessment.forbidden.length > 0
+                ? pathAssessment.forbidden
+                : dedupeStable(finalForbidden),
+            ...(allowedRoots !== undefined ? { allowedRoots: dedupeStable(allowedRoots) } : {}),
+        },
+        verification: {
+            commands: verifyCommands
+                .filter((cmd) => cmd.label && cmd.command)
+                .map((cmd) => ({
+                label: cmd.label,
+                command: cmd.command,
+                ...(cmd.timeoutMs !== undefined ? { timeoutMs: cmd.timeoutMs } : {}),
+            })),
+        },
+    };
+    if (featureId)
+        draft.featureId = featureId;
+    if (references && references.length > 0) {
+        draft.references = references.map((ref) => ({
+            role: ref.role,
+            ref: ref.ref,
+        }));
+    }
+    else if (baseDraft?.references?.length) {
+        draft.references = [...baseDraft.references];
+    }
+    if (openQuestions.length > 0)
+        draft.openQuestions = openQuestions;
+    if (assumptions.length > 0)
+        draft.assumptions = assumptions;
+    if (baseDraft?.sourceResolutions?.length) {
+        draft.sourceResolutions = [...baseDraft.sourceResolutions];
+    }
+    if (baseDraft?.hardConstraints?.length && invariants.length === 0) {
+        draft.hardConstraints = [...baseDraft.hardConstraints];
+    }
+    return {
+        draft,
+        pathAssessment,
+        acceptanceConflicts: facts?.acceptanceConflicts ?? [],
+    };
+}

package/dist/task/source-prepare/completeness.js

@@ -0,0 +1,195 @@
+const FRESH_SOURCE_MISSING_CODES = new Set([
+    "MISSING_REQUIREMENT",
+    "MISSING_CONSTRAINTS",
+]);
+export function isFreshLegacyUnversioned(state, sourceFilesPresent) {
+    if (state.effectiveStatus !== "legacy-unversioned")
+        return false;
+    if (state.observationErrors.some((e) => e.code === "NOT_FOUND"))
+        return false;
+    // Fresh new-task: both source files missing/empty. Any non-empty source is dirty.
+    if (sourceFilesPresent &&
+        (sourceFilesPresent.requirement || sourceFilesPresent.constraints)) {
+        return false;
+    }
+    const codes = state.observationErrors.map((e) => e.code);
+    // Allow empty errors only when caller already proved both files are empty.
+    if (codes.length === 0) {
+        return Boolean(sourceFilesPresent);
+    }
+    return codes.every((code) => FRESH_SOURCE_MISSING_CODES.has(code));
+}
+export function observationBlocksPrepare(state) {
+    if (state.observationErrors.some((e) => e.code === "NOT_FOUND")) {
+        return {
+            code: "TASK_NOT_FOUND",
+            level: "blocking",
+            message: "task not found",
+        };
+    }
+    if (state.effectiveStatus === "transaction-incomplete") {
+        return {
+            code: "TRANSACTION_INCOMPLETE",
+            level: "blocking",
+            message: "unfinished contract transaction; run task contract recover before prepare",
+        };
+    }
+    const disallowed = state.observationErrors.filter((e) => !FRESH_SOURCE_MISSING_CODES.has(e.code));
+    // EXTERNALLY_MODIFIED alone is the dirty-source signal handled by C6.
+    // Any other observation code (e.g. MANIFEST_MISSING, OBSERVE_FAILED,
+    // INVALID_CONTRACT_JSON) is independently blocking; force cannot bypass it.
+    const hard = disallowed.filter((e) => e.code !== "EXTERNALLY_MODIFIED");
+    if (hard.length > 0) {
+        return {
+            code: "OBSERVATION_ERROR",
+            level: "blocking",
+            message: hard.map((e) => e.message).join("; "),
+        };
+    }
+    return null;
+}
+export function listPrepareGaps(input) {
+    const gaps = [];
+    const risks = [];
+    const { draft } = input;
+    const obs = observationBlocksPrepare(input.state);
+    if (obs)
+        gaps.push(obs);
+    if (!draft.requirement.objective?.trim()) {
+        gaps.push({
+            code: "EMPTY_OBJECTIVE",
+            level: "blocking",
+            field: "objective",
+            message: "requirement.objective is required",
+        });
+    }
+    if (draft.requirement.acceptanceCriteria.length === 0) {
+        gaps.push({
+            code: "EMPTY_ACCEPTANCE",
+            level: "blocking",
+            field: "acceptanceCriteria",
+            message: "at least one acceptance criterion is required",
+        });
+    }
+    if (input.acceptanceConflicts && input.acceptanceConflicts.length > 0) {
+        for (const conflict of input.acceptanceConflicts) {
+            gaps.push({
+                code: "ACCEPTANCE_ID_CONFLICT",
+                level: "blocking",
+                field: "acceptanceCriteria",
+                message: `acceptance criterion id ${conflict.id} has conflicting texts`,
+            });
+        }
+    }
+    if (draft.constraints.allowedPaths.length === 0 && !(draft.taskKind === "frontend-implementation" && (draft.constraints.allowedRoots?.length ?? 0) > 0)) {
+        gaps.push({
+            code: "EMPTY_ALLOWED_PATHS",
+            level: "blocking",
+            field: "allowedPaths",
+            message: "allowedPaths must be non-empty before apply",
+        });
+    }
+    if (!draft.taskKind?.trim()) {
+        gaps.push({
+            code: "EMPTY_TASK_KIND",
+            level: "blocking",
+            field: "taskKind",
+            message: "taskKind is required",
+        });
+    }
+    if (draft.taskKind === "knowledge-sync" && !draft.featureId) {
+        gaps.push({
+            code: "MISSING_FEATURE_ID",
+            level: "blocking",
+            field: "featureId",
+            message: "featureId is required when taskKind is knowledge-sync",
+        });
+    }
+    if (draft.requirement.scope.length === 0) {
+        gaps.push({
+            code: "EMPTY_SCOPE",
+            level: "warning",
+            field: "scope",
+            message: "scope is empty; projection will show (none)",
+        });
+    }
+    if (draft.requirement.nonGoals.length === 0) {
+        gaps.push({
+            code: "EMPTY_NON_GOALS",
+            level: "warning",
+            field: "nonGoals",
+            message: "nonGoals is empty; projection will show (none)",
+        });
+    }
+    if (draft.verification.commands.length === 0) {
+        gaps.push({
+            code: "EMPTY_VERIFY",
+            level: "warning",
+            field: "verifyCommands",
+            message: "verifyCommands is empty",
+        });
+    }
+    if (input.sourceIntegrity) {
+        for (const issue of input.sourceIntegrity.issues) {
+            if (issue.level === "blocking") {
+                gaps.push({
+                    code: issue.code,
+                    level: "blocking",
+                    message: issue.message,
+                    field: issue.path,
+                });
+            }
+            else {
+                gaps.push({
+                    code: issue.code,
+                    level: "warning",
+                    message: issue.message,
+                    field: issue.path,
+                });
+            }
+        }
+    }
+    if (input.pathAssessment) {
+        risks.push(...input.pathAssessment.blocking, ...input.pathAssessment.elevated, ...input.pathAssessment.warnings);
+        for (const risk of input.pathAssessment.blocking) {
+            gaps.push({
+                code: risk.code,
+                level: "blocking",
+                message: risk.message,
+                field: risk.path,
+            });
+        }
+    }
+    // Dirty source gate (C6 / D14)
+    const status = input.state.effectiveStatus;
+    const hasExistingSource = Boolean(input.sourceFilesPresent?.requirement ||
+        input.sourceFilesPresent?.constraints);
+    const hasDirtySource = status === "externally-modified" ||
+        (status === "legacy-unversioned" && hasExistingSource);
+    if (hasDirtySource && !input.forceOverwriteSource) {
+        gaps.push({
+            code: "DIRTY_SOURCE",
+            level: "blocking",
+            message: "existing non-empty or externally-modified source refuses --apply; use show/diff/adopt/recover or --force-overwrite-source",
+        });
+        risks.push({
+            code: "DIRTY_SOURCE",
+            level: "blocking",
+            message: "source is dirty/externally-modified; prepare will not overwrite without --force-overwrite-source",
+        });
+    }
+    if (!input.hasImportedPrd) {
+        gaps.push({
+            code: "NO_IMPORTED_PRD",
+            level: "warning",
+            message: "no imported PRD in use; prefer detailed PRD → import-prd → prepare (escape hatch only)",
+        });
+    }
+    return { gaps, risks };
+}
+export function hasBlockingGaps(gaps) {
+    return gaps.some((gap) => gap.level === "blocking");
+}
+export function hasBlockingRisks(risks) {
+    return risks.some((risk) => risk.level === "blocking");
+}

package/dist/task/source-prepare/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./path-policy.js";
+export * from "./parse-intent.js";
+export * from "./reference-integrity.js";
+export * from "./completeness.js";
+export * from "./build-draft.js";
+export * from "./prepare.js";