@tea-agent/loop-agent 0.16.25 → 0.17.0

package/dist/workflows/dag/prompt.js

@@ -98,8 +98,49 @@ function buildReadOnlyBoundary(writePolicy) {
         "Return findings in the assistant response/stdout only; the DAG runner persists node artifacts under .harness/dag-runs/<state>/<run-id>/<node-id>/.",
     ];
 }
+function formatProjectGovernanceContext(ctx) {
+    if (!ctx || !ctx.applicable)
+        return undefined;
+    const lines = [];
+    lines.push("Deterministic project governance manifest for the actual writer changeset of this run. Interpret it for compliance review; do not invent rules beyond the files and hashes listed here.");
+    lines.push("Before issuing a verdict, use read-only tools to read every applicable AGENTS.md and every mandatory referenced standard listed below from the repository; hashes bind the exact inputs for audit.");
+    lines.push("Your first non-empty output line must be exactly VERDICT: pass or VERDICT: request-revision. Request revision while any applicable mandatory instruction is violated.");
+    lines.push("");
+    lines.push("Change manifest (writer nodes and their changed files):");
+    for (const entry of ctx.changeManifest) {
+        if (entry.changedFiles.length === 0)
+            continue;
+        lines.push(`- ${entry.writerNodeId}: ${entry.changedFiles.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("Applicable AGENTS.md chain (root -> nearest):");
+    for (const entry of ctx.agentsMdChain) {
+        lines.push(`- ${entry.path} (enforcement=mandatory, directory=${entry.directory || "/"}, sha256=${entry.sha256}, bytes=${entry.bytes}) applies to: ${entry.appliesTo.join(", ") || "(none)"}`);
+    }
+    if (ctx.referencedStandards.length > 0) {
+        lines.push("");
+        lines.push("Referenced repository-local code standards:");
+        for (const std of ctx.referencedStandards) {
+            lines.push(`- ${std.path} (enforcement=${std.enforcement}, from ${ctx.agentsMdChain[std.fromAgentsMd]?.path ?? "AGENTS.md"}, sha256=${std.sha256}, bytes=${std.bytes}, scope=${std.scope})`);
+        }
+    }
+    if (ctx.unresolvedReferences.length > 0) {
+        lines.push("");
+        lines.push("Unresolved reference diagnostics (structured, not read): for awareness only.");
+        for (const ref of ctx.unresolvedReferences) {
+            lines.push(`- ${ref.declaredPath}: ${ref.reason} (from ${ctx.agentsMdChain[ref.fromAgentsMd]?.path ?? "AGENTS.md"})`);
+        }
+    }
+    if (ctx.diagnostics.length > 0) {
+        lines.push("");
+        lines.push("Resolver diagnostics:");
+        for (const diag of ctx.diagnostics)
+            lines.push(`- ${diag}`);
+    }
+    return lines.join("\n");
+}
 export function buildDagNodePromptEnvelope(input) {
-    const { spec, task, upstream, resolvedSkills = [], resolvedSkillInstructions = [], maxUpstreamChars = MAX_UPSTREAM_CHARS, } = input;
+    const { spec, task, upstream, resolvedSkills = [], resolvedSkillInstructions = [], maxUpstreamChars = MAX_UPSTREAM_CHARS, projectGovernanceContext, } = input;
     const objective = spec.objective ?? spec.title;
     const successCriteria = formatBulletList(spec.successCriteria, "(none specified)");
     const globalConstraints = formatBulletList(spec.globalConstraints, "(none specified)");
@@ -150,6 +191,10 @@ export function buildDagNodePromptEnvelope(input) {
     else {
         sections.push("<upstream_context>\n(none)\n</upstream_context>");
     }
+    const governanceSection = formatProjectGovernanceContext(projectGovernanceContext);
+    if (governanceSection) {
+        sections.push(`<project_governance_context>\n${governanceSection}\n</project_governance_context>`);
+    }
     sections.push(`<task>\n${task.subtask_prompt}\n</task>`);
     return sections.join("\n\n");
 }

package/dist/workflows/dag/retry-policy.js

@@ -16,6 +16,11 @@ export const DEFAULT_DAG_RETRY_CATEGORIES = [
     "rate-limit",
     "unavailable",
 ];
+export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
+export const STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES = [
+    ...DEFAULT_DAG_RETRY_CATEGORIES,
+    STRUCTURED_OUTPUT_RETRY_CATEGORY,
+];
 const RETRY_SAFE_PI_ROLES = new Set([
     "planner",
     "scout",
@@ -23,7 +28,7 @@ const RETRY_SAFE_PI_ROLES = new Set([
     "verifier",
     "closeout",
 ]);
-export const dagRetryCategorySchema = z.enum(DEFAULT_DAG_RETRY_CATEGORIES);
+export const dagRetryCategorySchema = z.enum(STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES);
 export const dagRetryBackoffSchema = z.enum(["exponential"]);
 /**
  * Opt-in retry policy for a DagTask. Generated only for safe read-only Pi
@@ -71,6 +76,16 @@ export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
     maxDelayMs: 30000,
     retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES],
 };
+/**
+ * Structured planner nodes may retry with a compact-output instruction
+ * when the model produced an oversized assistant response. This category is
+ * not part of the default read-only retry set because report/review nodes
+ * should not silently learn new output semantics.
+ */
+export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES],
+};
 /**
  * Deterministic helper: is this raw failure category eligible for retry under
  * the given policy? Pure function; executor never decides retry eligibility.

package/dist/workflows/dag/runner.js

@@ -117,6 +117,7 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
             status: "PENDING",
             executor: task.executor,
             complexity: task.complexity,
+            ...(task.outputMode ? { outputMode: task.outputMode } : {}),
             ...(resolveModelForTask(task, spec.executorModels)
                 ? { model: resolveModelForTask(task, spec.executorModels) }
                 : {}),
@@ -178,6 +179,10 @@ export async function runDag(spec, opts) {
     assertValidDagSpec(spec);
     // Candidate identity is validated before run-id allocation or directory creation.
     await assertEvaluationBindingPreflight(opts.cwd, spec.evaluation);
+    // Phase 0.5: new writer execution requires DagSpec v4 + live taskContractBinding match.
+    const { assertDagSpecAllowsNewWriterExecution, assertTaskContractBindingConsistent } = await import("./task-contract-binding.js");
+    assertDagSpecAllowsNewWriterExecution(spec);
+    await assertTaskContractBindingConsistent({ repoRoot: opts.cwd, spec });
     const runningIdentity = resolveRunningControllerIdentity();
     if (!runningIdentity) {
         throw new Error("running controller identity could not be resolved; refuse to create an unpinned DAG run");
@@ -273,6 +278,10 @@ export async function resumeDagRun(opts) {
     }
     assertFrozenEvaluationBinding(spec, state);
     assertFrozenBudget(spec.budget, state.budget, state.runId);
+    // Phase 0.5: refuse resume of pre-v4 writer DAGs; revalidate live binding.
+    const { assertDagSpecAllowsNewWriterExecution, assertTaskContractBindingConsistent } = await import("./task-contract-binding.js");
+    assertDagSpecAllowsNewWriterExecution(spec);
+    await assertTaskContractBindingConsistent({ repoRoot: opts.cwd, spec });
     // Runtime contract + controller identity must be re-verified before executing
     // any remaining node on resume; drift fails closed.
     const runningIdentity = resolveRunningControllerIdentity();

package/dist/workflows/dag/skill-snapshot.js

@@ -524,6 +524,7 @@ export function buildNodePromptFromSnapshot(input) {
             resolvedSkills: skillNames,
             resolvedSkillInstructions,
             maxUpstreamChars: policy.resolveMaxUpstreamChars(input.task),
+            projectGovernanceContext: input.projectGovernanceContext,
         }),
         resolvedSkills: resolvedSkillInstructions.map(stripPromptText),
     };

package/dist/workflows/dag/task-contract-binding.js

@@ -0,0 +1,138 @@
+import { observeTaskContract } from "../../task/contract/observe.js";
+export async function readCurrentTaskContractBinding(input) {
+    const state = await observeTaskContract({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+    });
+    if (state.effectiveStatus !== "managed" || !state.ref) {
+        return {
+            ok: false,
+            code: "BINDING_DRIFT",
+            message: `task ${input.taskId} is not managed (effectiveStatus=${state.effectiveStatus}); adopt/apply before DAG generate/run`,
+        };
+    }
+    const ref = state.ref;
+    return {
+        ok: true,
+        current: {
+            schemaVersion: 1,
+            taskId: ref.taskId,
+            revision: ref.revision,
+            projectionVersion: ref.projectionVersion,
+            canonicalizerVersion: ref.canonicalizerVersion,
+            taskConfigSchemaVersion: ref.taskConfigSchemaVersion,
+            canonicalHash: ref.canonicalHash,
+            taskConfigSha256: ref.taskConfigSha256,
+        },
+    };
+}
+export function compareTaskContractBinding(declared, current) {
+    if (declared.taskId !== current.taskId ||
+        declared.revision !== current.revision ||
+        declared.canonicalHash !== current.canonicalHash ||
+        declared.taskConfigSha256 !== current.taskConfigSha256 ||
+        declared.projectionVersion !== current.projectionVersion ||
+        declared.canonicalizerVersion !== current.canonicalizerVersion ||
+        declared.taskConfigSchemaVersion !== current.taskConfigSchemaVersion) {
+        return {
+            ok: false,
+            code: "BINDING_DRIFT",
+            message: `taskContractBinding drift for ${declared.taskId}: declared revision=${declared.revision} hash=${declared.canonicalHash}, current revision=${current.revision} hash=${current.canonicalHash}`,
+            declared,
+            current,
+        };
+    }
+    return { ok: true, declared, current };
+}
+/**
+ * Fail closed when a v4 DAG's frozen binding does not match current managed ref.
+ * Historical v3 specs without binding are left to migration matrix callers.
+ */
+export async function assertTaskContractBindingConsistent(input) {
+    if (input.spec.version !== 4) {
+        return;
+    }
+    const declared = input.spec.taskContractBinding;
+    if (!declared) {
+        const err = new Error("DagSpec version 4 missing taskContractBinding");
+        err.code = "BINDING_DRIFT";
+        throw err;
+    }
+    const current = await readCurrentTaskContractBinding({
+        repoRoot: input.repoRoot,
+        taskId: declared.taskId,
+    });
+    if (!current.ok || !current.current) {
+        const err = new Error(current.message ?? "task contract binding unavailable");
+        err.code = current.code ?? "BINDING_DRIFT";
+        throw err;
+    }
+    const cmp = compareTaskContractBinding(declared, current.current);
+    if (!cmp.ok) {
+        const err = new Error(cmp.message ?? "taskContractBinding drift");
+        err.code = "BINDING_DRIFT";
+        throw err;
+    }
+}
+/**
+ * v3 migration matrix: historical DAGs may remain readable/executable only
+ * when they contain no exclusive writer. Terminal report/doctor never call
+ * this helper.
+ */
+export function dagHasWriterExecution(spec) {
+    return spec.tasks.some((task) => (task.writePolicy ?? spec.defaults?.writePolicy) === "exclusive");
+}
+export function assertDagSpecAllowsNewWriterExecution(spec) {
+    if (!dagHasWriterExecution(spec))
+        return;
+    // Migration matrix (design §5.3.10):
+    // - New writer start/approve/resume requires DagSpec v4 + taskContractBinding.
+    // - Historical read-only/static/shell DAGs remain executable; they cannot
+    //   introduce repository writer execution and remain useful for diagnostics,
+    //   saved workflows, and deterministic verification.
+    // - v3 DAGs containing an exclusive writer must regenerate before execution.
+    if (spec.version !== 4) {
+        const err = new Error(`DagSpec version ${spec.version} cannot start/approve/resume new writer execution; regenerate as version 4 with taskContractBinding`);
+        err.code = "BINDING_DRIFT";
+        throw err;
+    }
+}
+/** Result-form API used by some callers; wraps assertTaskContractBindingConsistent. */
+export async function assertTaskContractBindingFresh(input) {
+    const action = input.action ?? "dag-action";
+    if (input.rejectHistoricalV3ForWriter && input.spec.version === 3) {
+        return {
+            ok: false,
+            code: "BINDING_DRIFT",
+            message: `${action}: DagSpec version 3 cannot start/approve/resume new writers; regenerate as v4`,
+        };
+    }
+    if (input.spec.version !== 4) {
+        return {
+            ok: true,
+            binding: input.spec.taskContractBinding,
+            current: input.spec.taskContractBinding,
+        };
+    }
+    try {
+        await assertTaskContractBindingConsistent({
+            repoRoot: input.repoRoot,
+            spec: input.spec,
+        });
+        return {
+            ok: true,
+            binding: input.spec.taskContractBinding,
+            current: input.spec.taskContractBinding,
+        };
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "BINDING_DRIFT";
+        return {
+            ok: false,
+            code,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/workflows/dag/types.js

@@ -7,6 +7,7 @@ export const dagNodeExecutorSchema = z.enum(["pi", "shell", "static"]);
 export const CURSOR_DAG_EXECUTOR_REMOVED_ERROR = 'executor "cursor" is no longer supported; regenerate the DAG with Pi-only writers (implement-pi / repair-pi)';
 export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = "executorModels.cursor is no longer supported; use executorModels.pi only";
 export const dagToolProfileSchema = z.enum(["read-only", "write"]);
+export const dagOutputModeSchema = z.enum(["default", "structured-required"]);
 export const dagShellPresetSchema = z.enum(["loop-agent-standard-verify"]);
 export const dagVerifyQuotaSchema = z.enum(["1", "3", "full"]);
 export const dagVerifyStrategySchema = z
@@ -75,6 +76,12 @@ export const dagRequirementCoverageGateSchema = z.object({
     fromNodeIds: z
         .array(z.string().regex(/^[a-z][a-z0-9-]*$/, "fromNodeIds must be kebab-case"))
         .min(1),
+    fallbackFromNodeIds: z
+        .array(z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "fallbackFromNodeIds must be kebab-case"))
+        .min(1)
+        .optional(),
     requiredIds: z
         .array(z
         .string()
@@ -95,6 +102,12 @@ export const dagJsonArtifactSchemaIdSchema = z.enum([
 ]);
 export const dagJsonArtifactGateSchema = z.object({
     fromNodeId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    fallbackFromNodeIds: z
+        .array(z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "fallbackFromNodeIds must be kebab-case"))
+        .min(1)
+        .optional(),
     schemaId: dagJsonArtifactSchemaIdSchema,
     artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
@@ -102,8 +115,25 @@ export const dagJsonArtifactGateSchema = z.object({
 });
 export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export const dagVersionSchema = z
-    .union([z.literal(1), z.literal(2), z.literal(3)])
+    .union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)])
     .default(1);
+/** DagSpec v4 binding to managed TaskContractRefV1 (design §5.3.10). */
+export const dagTaskContractBindingSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    taskId: z.string().min(1),
+    revision: z.number().int().nonnegative(),
+    projectionVersion: z.literal(1),
+    canonicalizerVersion: z.literal(1),
+    taskConfigSchemaVersion: z.literal(1),
+    canonicalHash: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/, "canonicalHash must be lowercase hex"),
+    taskConfigSha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/, "taskConfigSha256 must be lowercase hex"),
+})
+    .strict();
 export const dagRoleSchema = z.enum([
     "planner",
     "scout",
@@ -152,6 +182,9 @@ export const dagShellConfigSchema = z.object({
     commands: z.array(z.string()).default([]),
     preset: dagShellPresetSchema.optional(),
     verdictGate: dagVerdictGateSchema.optional(),
+    projectGovernanceGate: z.object({
+        contextPath: z.literal(".runtime/project-governance-context.json"),
+    }).strict().optional(),
     requirementCoverageGate: dagRequirementCoverageGateSchema.optional(),
     jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
@@ -310,7 +343,15 @@ export const dagTaskSchema = z.object({
     shell: dagShellConfigSchema.optional(),
     static: dagStaticConfigSchema.optional(),
     outputContract: z.string().optional(),
+    outputMode: dagOutputModeSchema.optional(),
     firstProtocolLine: z.string().min(1).optional(),
+    /**
+     * Explicit opt-in for the deterministic project governance context resolver
+     * (AGENTS.md chain + referenced code standards). Only tasks that set this
+     * to `true` receive a `<project_governance_context>` prompt section and
+     * closeout-blocking gate behavior. Never inferred from role/name.
+     */
+    governanceStandardReview: z.boolean().optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     decisionGate: dagDecisionGateSchema.optional(),
@@ -366,9 +407,11 @@ export const dagSpecSchema = z
     title: z.string().min(1),
     runtimeContract: dagRuntimeContractSchema.optional(),
     evaluation: dagEvaluationBindingSchema.optional(),
-    /** Optional hard/record-only budget; requires version 3. */
+    /** Optional hard/record-only budget; requires version 3 or 4. */
     budget: dagBudgetSchema.optional(),
     sourceBinding: dagSourceBindingSchema.optional(),
+    /** v4 managed Task Contract binding; only valid on version 4. */
+    taskContractBinding: dagTaskContractBindingSchema.optional(),
     outputLanguage: dagOutputLanguageSchema.optional(),
     objective: z.string().optional(),
     successCriteria: z.array(z.string()).optional(),
@@ -381,34 +424,65 @@ export const dagSpecSchema = z
     tasks: z.array(dagTaskSchema).min(1),
 })
     .superRefine((spec, ctx) => {
-    if (spec.evaluation && spec.version !== 3) {
+    const supportsV3Fields = spec.version === 3 || spec.version === 4;
+    if (spec.evaluation && !supportsV3Fields) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "evaluation requires DagSpec version 3",
+            message: "evaluation requires DagSpec version 3 or 4",
             path: ["evaluation"],
         });
     }
-    if (spec.budget && spec.version !== 3) {
+    if (spec.budget && !supportsV3Fields) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "budget requires DagSpec version 3",
+            message: "budget requires DagSpec version 3 or 4",
             path: ["budget"],
         });
     }
-    if (spec.runtimeContract && spec.version !== 3) {
+    if (spec.runtimeContract && !supportsV3Fields) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "runtimeContract requires DagSpec version 3",
+            message: "runtimeContract requires DagSpec version 3 or 4",
             path: ["version"],
         });
     }
-    if (spec.version === 3 && !spec.runtimeContract) {
+    if (supportsV3Fields && !spec.runtimeContract) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "DagSpec version 3 requires runtimeContract",
+            message: `DagSpec version ${spec.version} requires runtimeContract`,
             path: ["runtimeContract"],
         });
     }
+    if (spec.taskContractBinding && spec.version !== 4) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "taskContractBinding requires DagSpec version 4",
+            path: ["taskContractBinding"],
+        });
+    }
+    if (spec.version === 4) {
+        if (!spec.sourceBinding) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "DagSpec version 4 requires sourceBinding",
+                path: ["sourceBinding"],
+            });
+        }
+        if (!spec.taskContractBinding) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "DagSpec version 4 requires taskContractBinding",
+                path: ["taskContractBinding"],
+            });
+        }
+        if (!spec.runtimeContract) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "DagSpec version 4 requires runtimeContract",
+                path: ["runtimeContract"],
+            });
+        }
+    }
     // Catch raw cursor keys that Zod .strict() on nested objects already rejects when parsed
     // via parseDagSpec; this refine covers typed object construction paths.
     const models = spec.executorModels;

package/dist/workflows/dag/validate.js

@@ -256,10 +256,20 @@ function validateRequirementCoverageGateConfig(task, spec, issues) {
         issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate requires executor=shell` });
         return;
     }
+    if (gate.fallbackFromNodeIds?.length && gate.fromNodeIds.length !== 1) {
+        issues.push({
+            type: "invalid-requirement-coverage-gate-config",
+            message: `task ${task.id} shell.requirementCoverageGate with fallbackFromNodeIds requires exactly one fromNodeIds entry`,
+        });
+    }
     const dependencyIds = new Set(task.depends_on);
-    for (const fromNodeId of gate.fromNodeIds) {
+    const sourceNodeIds = [
+        ...gate.fromNodeIds,
+        ...(gate.fallbackFromNodeIds ?? []),
+    ];
+    for (const fromNodeId of new Set(sourceNodeIds)) {
         if (!dependencyIds.has(fromNodeId)) {
-            issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate.fromNodeIds entry "${fromNodeId}" must appear in depends_on` });
+            issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate source "${fromNodeId}" must appear in depends_on` });
         }
         const upstream = spec.tasks.find((candidate) => candidate.id === fromNodeId);
         if (upstream?.executor === "shell") {
@@ -493,11 +503,19 @@ function validateShellTaskConfig(task, spec, issues) {
     }
     validateVerdictGateConfig(task, spec, issues);
     validateRequirementCoverageGateConfig(task, spec, issues);
-    if (shell.jsonArtifactGate && !task.depends_on.includes(shell.jsonArtifactGate.fromNodeId)) {
-        issues.push({
-            type: "missing-dependency",
-            message: `shell task ${task.id} jsonArtifactGate source ${shell.jsonArtifactGate.fromNodeId} must be a direct dependency`,
-        });
+    if (shell.jsonArtifactGate) {
+        const sourceNodeIds = [
+            shell.jsonArtifactGate.fromNodeId,
+            ...(shell.jsonArtifactGate.fallbackFromNodeIds ?? []),
+        ];
+        for (const sourceNodeId of new Set(sourceNodeIds)) {
+            if (!task.depends_on.includes(sourceNodeId)) {
+                issues.push({
+                    type: "missing-dependency",
+                    message: `shell task ${task.id} jsonArtifactGate source ${sourceNodeId} must be a direct dependency`,
+                });
+            }
+        }
     }
     validateRepairArtifactGateConfig(task, spec, issues);
     validateShellVerdictGateGovernance(task, commands, issues);
@@ -653,12 +671,40 @@ export function validateDagSpec(spec) {
         validateStaticTaskConfig(task, issues);
         validateDecisionGateTaskConfig(task, issues);
         validateRetryPolicyTaskConfig(task, issues);
+        validateProjectGovernanceTaskConfig(task, spec, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);
     validateWriterSourceBinding(spec, issues);
     return issues;
 }
+function validateProjectGovernanceTaskConfig(task, spec, issues) {
+    if (task.governanceStandardReview) {
+        if (task.executor !== "pi" ||
+            task.toolProfile === "write" ||
+            !["read-only", "none"].includes((task.writePolicy ?? "read-only"))) {
+            issues.push({
+                type: "invalid-project-governance-config",
+                message: `task ${task.id} governanceStandardReview requires a read-only Pi node`,
+            });
+        }
+    }
+    if (!task.shell?.projectGovernanceGate)
+        return;
+    const verdictGate = task.shell.verdictGate;
+    const source = verdictGate
+        ? spec.tasks.find((candidate) => candidate.id === verdictGate.fromNodeId)
+        : undefined;
+    if (task.executor !== "shell" ||
+        !verdictGate ||
+        !task.depends_on.includes(verdictGate.fromNodeId) ||
+        !source?.governanceStandardReview) {
+        issues.push({
+            type: "invalid-project-governance-config",
+            message: `task ${task.id} projectGovernanceGate requires verdictGate over a directly-dependent governanceStandardReview node`,
+        });
+    }
+}
 export function assertValidDagSpec(spec, options = {}) {
     const issues = collectBlockingIssues(options.issues ?? validateDagSpec(spec), options);
     if (issues.length > 0) {

package/docs/README.md

@@ -31,6 +31,8 @@
 - `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
 - `design/backend-test-workflow.md` — 已实现的 backend-test 15 节点单次执行全流程、pass-only 评审门禁、run-owned artifacts 与最终 outcome
 - `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
+- `design/agent-worker-fullstack-workflow-integration.md` — 已实现的 workflow routing、Task Outcome、artifact-aware Ready、`fullstack-v1` 与 Verification Bundle，以及后续 failure routing / execute-existing 领域设计
+- `design/fullstack-end-to-end-delivery-optimization-roadmap.md` — 当前全栈端到端优化的收敛路线图：先完成 release train / Delivery，再冻结 Final Verification 权威、Environment Contract、分类恢复与 Observe 指标
 - `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
 - `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
 

package/docs/architecture/evolution.md

@@ -40,6 +40,8 @@
 | Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
 
 > 本地 Loop Operator Console 已在 `docs/design/local-operator-console-from-pi-web.md` 作为独立设计输入：单仓库、loopback、随 `@tea-agent/loop-agent` 同包发布、canonical mutation 只经 sibling CLI；它不是本表中的远端 Web Console，也不能把远端多租户/云编排需求偷渡进本地 MVP。
+>
+> **Phase 3 落地（Unreleased）**：versioned Observe `/api/health`、Console `observeLink` fail-closed、recovery CTA 矩阵；Console 与 Observe 仍分进程。Phase 4 General Operator Chat 与合服仍属后续，未实现。
 
 > 注意：`ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md` 是 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
 

package/docs/architecture/system-overview.md

@@ -59,6 +59,12 @@ workflow runtime（调度 Pi / shell / static 节点）
 
 `agent-worker` 位于核心 runtime 的**上游调用侧**，不是 DAG 执行完成后的必经下游。Observe 可以在任一路径后读取现有事实，但不会改变执行结果。
 
+### 本地 Operator Console（Official，与 Observe 协作）
+
+- `agent-worker console serve` 提供 loopback Operator Console；canonical mutation 只经 sibling 已发布 `loop-agent`（`LoopAgentClient`），不 in-process 跑 DAG kernel。
+- Observe 保持**独立**只读进程；Console 通过 versioned Observe `/api/health`（`schemaVersion`、`repoFingerprint`、route capabilities）做深链 fail-closed，**不** mount / proxy。
+- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/local-operator-console-from-pi-web.md`。
+
 ## 外部边界
 
 - npm 发布包：`@tea-agent/loop-agent`，包含两个 bin 与静态能力资料。

package/docs/architecture/worker-and-feature.md

@@ -73,6 +73,13 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 - 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
 - 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
 - Observe 是本地只读暖白控制台；snapshot 投影失败返回安全错误摘要而非全零健康状态（见 `CHANGELOG.md [0.9.0]`）。
+- Phase 3：`GET /api/health` 为 versioned DTO（`schemaVersion: 1`、`repoFingerprint` 复用 Console `repoFingerprintV1`、package 元数据、由 ROUTES 派生的 `routeCapabilities`）。Console 深链 fail-closed 依赖该合同；Observe 仍独立进程、不经 Console proxy。
+
+### Loop Operator Console（Official 控制面骨架）
+
+- 模块：`src/worker/console/`（loopback serve、doctor、operator API、Vite SPA）。
+- 与 Observe 协作：`observeLink` + recovery CTA 矩阵；无 Cancel / 无主 CTA「直接改代码」。
+- 写入路径仍只经 `LoopAgentClient` → 已发布 `loop-agent`；不与 Observe 合服。
 
 ## 版本化自举的 deterministic canary