@piagent/platform 1.5.5 → 1.6.0

package/packages/piagent-core/runtime/registration/task-completion-tools.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { durableContextEvidenceEntries, isRuntimeOwnedContextEvidenceEntry } from "../../extensions/context-evidence.js";
+import { mergeObservedTaskContext } from "../../extensions/task-contract-view.js";
 import { buildHandoffProjection, writeHandoffProjection } from "../recovery/handoff-projection.ts";
 import { buildCompletionReceiptView } from "../product/operator-projections.ts";
 import { semanticRepairProvenance } from "../recovery/semantic-repair-handshake.ts";
@@ -41,13 +43,50 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
       if (task.trace.outcome !== "pending") {
         return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; context evidence was not changed.` }], details: task, isError: true };
       }
-      if (runtime.contextBudget !== "off" && task.contextManifest.length + params.files.length > budget.maxManifestFiles) {
+      const activeIdentity = runtimeState.taskIdentity(ctx);
+      if (!activeIdentity || activeIdentity.taskId !== task.taskId || activeIdentity.taskRunId !== task.taskRunId) {
         return {
-          content: [{ type: "text", text: `Context manifest budget exceeded: ${task.contextManifest.length + params.files.length} files > ${budget.maxManifestFiles}` }],
+          content: [{ type: "text", text: `Context evidence rejected for ${task.taskId}: the active runtime task identity does not match this session task.` }],
+          details: { reasonCode: "context-evidence-task-identity-mismatch" },
           isError: true
         };
       }
-      const fileBudget = params.files.map((file) => candidateFileBudget(ctx.cwd, file.path, budget));
+      const observedPaths = new Set(runtimeState.observedContext(ctx)
+        .map((entry: { path: string }) => normalizeRelative(ctx.cwd, entry.path))
+        .filter((filePath: string | undefined): filePath is string => Boolean(filePath)));
+      const qualifiedByPath = new Map<string, { path: string; reason: string }>();
+      for (const entry of runtimeState.qualifiedContextEvidence(ctx, task.taskRunId)) {
+        const filePath = normalizeRelative(ctx.cwd, entry.path);
+        if (filePath && isRuntimeOwnedContextEvidenceEntry(entry)) qualifiedByPath.set(filePath, entry);
+      }
+      const qualifiedFiles = new Map<string, { path: string; reason: string }>();
+      const unprovenPaths: string[] = [];
+      for (const file of params.files) {
+        const filePath = normalizeRelative(ctx.cwd, file.path);
+        const evidence = filePath ? qualifiedByPath.get(filePath) : undefined;
+        if (!filePath || !observedPaths.has(filePath) || !evidence) {
+          unprovenPaths.push(redactText(file.path));
+          continue;
+        }
+        qualifiedFiles.set(filePath, { path: filePath, reason: evidence.reason });
+      }
+      if (unprovenPaths.length > 0) {
+        return {
+          content: [{ type: "text", text: `Context evidence rejected for ${task.taskId}: no runtime-observed read or host-confirmed delivery exists in this task/session for ${unprovenPaths.join(", ")}. Read the exact file successfully in this task or rely on automatic delivery confirmation.` }],
+          details: { reasonCode: "context-evidence-unproven", paths: unprovenPaths },
+          isError: true
+        };
+      }
+      const safeFiles = [...qualifiedFiles.values()];
+      const evidencePaths = new Set(durableContextEvidenceEntries(task).map((item) => item.path));
+      const projectedManifestFiles = evidencePaths.size + new Set(safeFiles.map((item) => item.path).filter((filePath) => !evidencePaths.has(filePath))).size;
+      if (runtime.contextBudget !== "off" && projectedManifestFiles > budget.maxManifestFiles) {
+        return {
+          content: [{ type: "text", text: `Context manifest budget exceeded: ${projectedManifestFiles} files > ${budget.maxManifestFiles}` }],
+          isError: true
+        };
+      }
+      const fileBudget = safeFiles.map((file) => candidateFileBudget(ctx.cwd, file.path, budget));
       const overLimit = fileBudget.filter((item) => item.overLimit);
       if (runtime.contextBudget === "enforce" && overLimit.length > 0) {
         return {
@@ -56,17 +95,8 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
           isError: true
         };
       }
-
-      const safeFiles = params.files.map((file) => ({
-        path: file.path,
-        reason: redactText(file.reason)
-      }));
-      const seen = new Set(task.contextManifest.map((item) => `${item.path}\u0000${item.reason}`));
-      for (const file of safeFiles) {
-        const key = `${file.path}\u0000${file.reason}`;
-        if (!seen.has(key)) task.contextManifest.push(file);
-      }
-      const lifecycle = task.changeMode === "read-only"
+      mergeObservedTaskContext(task, safeFiles, budget.maxManifestFiles, (value) => value);
+      const lifecycle = task.changeMode === "read-only" || task.mutationPolicy === "forbidden"
         ? applyRuntimeLifecycleObservation(task, "context-complete", nowIso())
         : { changed: false, mode: runtimeLifecycleMode(task) };
       const written = writeTask(ctx.cwd, task);
@@ -74,7 +104,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
       appendSessionTrace(pi, { taskId: task.taskId, taskRunId: task.taskRunId, sessionId: task.sessionId, event: "context_record", files: safeFiles, lifecycleMode: lifecycle.mode, lifecycleAdvanced: lifecycle.changed });
 
       return {
-        content: [{ type: "text", text: `Context recorded for ${task.taskId}: ${params.files.length} file(s)` }],
+        content: [{ type: "text", text: `Context recorded for ${task.taskId}: ${safeFiles.length} runtime-qualified file(s)` }],
         details: compactTaskDetails(written)
       };
     }
@@ -296,7 +326,10 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         currentDigests: finalFileDigests,
         currentWorkingTreeDigest: workingTreeEvidenceDigest(finalFileDigests)
       });
-      const semanticBlock = taskAuthorityDecision(nextTask, "CAP-13", "block").allowed ? semanticRepairCompletionBlock?.(ctx.cwd, nextTask.taskRunId) : undefined;
+      const semanticBlock = (taskAuthorityDecision(nextTask, "CAP-13", "block").allowed
+        || taskAuthorityDecision(nextTask, "CAP-12", "mutate").allowed)
+        ? semanticRepairCompletionBlock?.(ctx.cwd, nextTask.taskRunId)
+        : undefined;
       if (semanticBlock) gate = { ...gate, decision: "fail", missing: [...new Set([...gate.missing, semanticBlock])] };
       if (params.outcome === "completed" && (semanticBlock || (runtime.finalGate === "enforce" && gate.decision === "fail"))) {
         const blockedTrace = {

package/packages/piagent-core/runtime/registration/task-start-guidance.ts

@@ -0,0 +1,163 @@
+type CriterionNode = {
+  id?: string;
+  obligation?: string;
+  kind?: string;
+  proofKinds?: string[];
+  targetHints?: string[];
+};
+
+type CriterionGraph = { mode?: string; nodes?: CriterionNode[] } | undefined;
+
+export type FocusedTestCandidate = {
+  criterionId: string;
+  path: string;
+};
+
+export type CriterionProofGuidance = {
+  criterionId: string;
+  guidance: string[];
+};
+
+type ProofTask = {
+  changeMode?: string;
+  mutationPolicy?: string;
+  criterionGraph?: CriterionGraph;
+};
+
+export const RUNTIME_SOURCE_REUSE_GUIDANCE = "Use runtime-delivered source; do not reread it. On edit drift/oldText mismatch, use attached recovery; otherwise reread the affected region once. Never retry guessed anchors. Otherwise read only missing source or a named criterion-focused test. Globs/directories grant scope, not file targets.";
+
+export const EXACT_VERIFIER_EXECUTION_GUIDANCE = "Keep each exact verifier command separate and unmodified. Run the set once on the final tree; rerun only after a later mutation or a runtime-authorized same-tree infrastructure retry.";
+
+function normalizedPath(value: string): string {
+  return value.trim().replaceAll("\\", "/");
+}
+
+function exactNameMentioned(obligation: string, file: string): boolean {
+  const text = obligation.toLowerCase().replaceAll("\\", "/");
+  const normalized = normalizedPath(file).toLowerCase();
+  const basename = normalized.split("/").pop() ?? "";
+  return [normalized, basename].filter(Boolean).some((candidate) => {
+    let offset = text.indexOf(candidate);
+    while (offset >= 0) {
+      const before = text[offset - 1] ?? "";
+      const after = text[offset + candidate.length] ?? "";
+      const afterNext = text[offset + candidate.length + 1] ?? "";
+      const nameContinuesAfter = /[a-z0-9_/-]/i.test(after) || (after === "." && /[a-z0-9_-]/i.test(afterNext));
+      if (!/[a-z0-9_./-]/i.test(before) && !nameContinuesAfter) return true;
+      offset = text.indexOf(candidate, offset + candidate.length);
+    }
+    return false;
+  });
+}
+
+function behavioralNodes(criterionGraph: CriterionGraph): CriterionNode[] {
+  return (criterionGraph?.nodes ?? []).filter((node) => (
+    typeof node?.id === "string"
+    && typeof node?.obligation === "string"
+    && Array.isArray(node?.proofKinds)
+    && node.proofKinds.includes("behavioral-check")
+  ));
+}
+
+export function concretePlannedAcceptanceTests(
+  plannedContext: Array<{ path: string; reason: string }>,
+  repositoryFiles: string[],
+  criterionGraph: CriterionGraph,
+  isAcceptanceTestPath: (file: string) => boolean,
+  acceptanceLanguageAdapterForPath: (file: string) => { disposition?: string }
+): FocusedTestCandidate[] {
+  const concreteFiles = new Set(repositoryFiles.map(normalizedPath));
+  const nodes = behavioralNodes(criterionGraph);
+  const candidates: FocusedTestCandidate[] = [];
+  for (const entry of plannedContext) {
+    const file = normalizedPath(entry.path);
+    if (!file || /[?*[\]{}]/.test(file) || !concreteFiles.has(file)) continue;
+    if (!isAcceptanceTestPath(file) || acceptanceLanguageAdapterForPath(file)?.disposition !== "supported") continue;
+    if (/\.d\.[cm]?ts$/i.test(file)) continue;
+    for (const node of nodes) {
+      if (exactNameMentioned(node.obligation!, file)) candidates.push({ criterionId: node.id!, path: file });
+    }
+  }
+  const seen = new Set<string>();
+  return candidates.filter((candidate) => {
+    const identity = `${candidate.criterionId}\0${candidate.path}`;
+    if (seen.has(identity)) return false;
+    seen.add(identity);
+    return true;
+  });
+}
+
+export function behavioralCriterionProofGuidance(
+  criterionGraph: CriterionGraph,
+  acceptanceProofGuidance: (text: string) => string[]
+): CriterionProofGuidance[] {
+  return behavioralNodes(criterionGraph).map((node) => ({
+    criterionId: node.id!,
+    guidance: acceptanceProofGuidance(node.obligation!)
+  }));
+}
+
+export function criticalProofSection(
+  proofGuidance: string[],
+  acceptanceTests: FocusedTestCandidate[],
+  criterionProofs: CriterionProofGuidance[]
+): string[] {
+  if (proofGuidance.length === 0) return [];
+  const candidateMap = new Map<string, string[]>();
+  for (const candidate of acceptanceTests) {
+    candidateMap.set(candidate.criterionId, [...new Set([...(candidateMap.get(candidate.criterionId) ?? []), candidate.path])]);
+  }
+  let mappedCandidate = false;
+  const proofLines = proofGuidance.flatMap((proof) => {
+    const criterionIds = [...new Set(criterionProofs
+      .filter((entry) => entry.guidance.includes(proof))
+      .map((entry) => entry.criterionId))];
+    if (criterionIds.length === 0) {
+      return [`- [fallback] ${proof}`];
+    }
+    const tags = criterionIds.map((criterionId) => {
+      const candidates = candidateMap.get(criterionId) ?? [];
+      if (candidates.length === 0) {
+        return `[${criterionId}:fallback]`;
+      }
+      mappedCandidate = true;
+      return `[${criterionId}:candidate=${candidates.join("|")}]`;
+    });
+    return [`- ${tags.join("")} ${proof}`];
+  });
+  return [[
+    "Critical behavioral proof:",
+    ...(!mappedCandidate ? ["No concrete criterion-linked focused test was selected."] : []),
+    ...proofLines,
+    "Candidate tags are locations, not proof; add/update durable scoped tests with live assertions and changed-test evidence. Each fallback tag requires adding/updating a durable scoped focused test with live assertions. If test scope is unavailable, report missing durable proof and do not claim completion. Run proof after the criterion's final intended mutation and before exact verifiers; rerun after later target mutation or a runtime-authorized same-tree infrastructure retry. Transient/print-only probes and prose are insufficient."
+  ].join("\n")];
+}
+
+export function automaticTaskExecutionGuidance(task: ProofTask): string {
+  if (task.changeMode === "read-only" || task.mutationPolicy === "forbidden") {
+    return task.changeMode === "source-change"
+      ? "Stay mutation-free. Runtime permits bounded inspection and the exact configured verifier, records completion evidence, and requires a zero task delta."
+      : "Stay read-only. Runtime records targeted reads and completion evidence; do not call task-management tools.";
+  }
+  return task.criterionGraph?.mode === "criterion-graph"
+    ? "Follow the execution map and implement dependency-ready criteria. The map plans work but never overrides the operator request or exact verifiers. Runtime records evidence and completion; do not call task-management tools."
+    : "Privately map every operator criterion to implementation and durable focused-test coverage before mutating. Finish intended edits and a criterion-by-criterion self-review. Runtime records evidence and completion; do not call task-management tools.";
+}
+
+export function taskCriticalProofSection(
+  task: ProofTask,
+  plannedContext: Array<{ path: string; reason: string }>,
+  repositoryFiles: string[],
+  acceptanceProofGuidance: (taskOrText: unknown) => string[],
+  isAcceptanceTestPath: (file: string) => boolean,
+  acceptanceLanguageAdapterForPath: (file: string) => { disposition?: string }
+): string[] {
+  const proofGuidance = task.changeMode === "source-change" && task.mutationPolicy !== "forbidden"
+    ? acceptanceProofGuidance(task)
+    : [];
+  const acceptanceTests = concretePlannedAcceptanceTests(
+    plannedContext, repositoryFiles, task.criterionGraph, isAcceptanceTestPath, acceptanceLanguageAdapterForPath
+  );
+  const criterionProofs = behavioralCriterionProofGuidance(task.criterionGraph, acceptanceProofGuidance);
+  return criticalProofSection(proofGuidance, acceptanceTests, criterionProofs);
+}

package/packages/piagent-core/runtime/registration/task-start-retry-helpers.ts

@@ -0,0 +1,37 @@
+type AuthoritySnapshot = {
+  profile: string;
+  capabilities: Array<{ id: string; authority: string }>;
+};
+
+type AuthorityReplacementTask = {
+  authoritySnapshot?: AuthoritySnapshot;
+};
+
+type AuthorityReplacementState = {
+  reason?: string;
+  killedCapabilities: string[];
+};
+
+export function sameStringRecord(left: Record<string, string>, right: Record<string, string>): boolean {
+  const leftEntries = Object.entries(left).sort(([a], [b]) => a.localeCompare(b));
+  const rightEntries = Object.entries(right).sort(([a], [b]) => a.localeCompare(b));
+  return leftEntries.length === rightEntries.length
+    && leftEntries.every(([key, value], index) => rightEntries[index]?.[0] === key && rightEntries[index]?.[1] === value);
+}
+
+export function satisfiesAuthorityReplacement(
+  task: AuthorityReplacementTask,
+  state: AuthorityReplacementState
+): boolean {
+  if (!task.authoritySnapshot) return false;
+  const authoritySnapshot = task.authoritySnapshot;
+  if (state.reason === "mechanical-rollback-requested") {
+    return authoritySnapshot.profile === "mechanical-only";
+  }
+  if (state.reason === "capability-kill-switch-requested") {
+    return state.killedCapabilities.length > 0 && state.killedCapabilities.every((capabilityId) => (
+      authoritySnapshot.capabilities.some((entry) => entry.id === capabilityId && entry.authority === "off")
+    ));
+  }
+  return true;
+}

package/packages/piagent-core/runtime/registration/task-start-tool.ts

@@ -5,40 +5,25 @@ import { automaticTaskSummary, boundedRuntimeIntakeMessage } from "../workflows/
 import { WORKING_TREE_DIGEST_ALGORITHM } from "../../extensions/working-tree-digest.js";
 import { createEnvironmentBoundTaskAuthority } from "../policy/task-authority-runtime.ts";
 import { authorityReplacementState } from "../policy/authority-resume-policy.ts";
-import { compileCriterionGraph, criterionGraphContextSelection, criterionGraphGuidance, criterionGraphMode } from "../../extensions/criterion-graph.js";
+import { compileCriterionGraph, criterionGraphContextSelection, criterionGraphContextSelectionDetails, criterionGraphGuidance, criterionGraphMode } from "../../extensions/criterion-graph.js";
 import { captureTaskStartBaseline } from "../inspection/task-baseline-start-capture.ts";
-type ExtensionContext = any;
-type TaskContract = any;
-type TaskStartParameters = any;
-function sameStringRecord(left: Record<string, string>, right: Record<string, string>): boolean {
-  const leftEntries = Object.entries(left).sort(([a], [b]) => a.localeCompare(b));
-  const rightEntries = Object.entries(right).sort(([a], [b]) => a.localeCompare(b));
-  return leftEntries.length === rightEntries.length
-    && leftEntries.every(([key, value], index) => rightEntries[index]?.[0] === key && rightEntries[index]?.[1] === value);
-}
-function satisfiesAuthorityReplacement(task: TaskContract, state: ReturnType<typeof authorityReplacementState>): boolean {
-  if (!task.authoritySnapshot) return false;
-  if (state.reason === "mechanical-rollback-requested") {
-    return task.authoritySnapshot.profile === "mechanical-only";
-  }
-  if (state.reason === "capability-kill-switch-requested") {
-    return state.killedCapabilities.length > 0 && state.killedCapabilities.every((capabilityId) => (
-      task.authoritySnapshot.capabilities.some((entry: any) => entry.id === capabilityId && entry.authority === "off")
-    ));
-  }
-  return true;
-}
+import { sameStringRecord, satisfiesAuthorityReplacement } from "./task-start-retry-helpers.ts";
+import {
+  automaticTaskExecutionGuidance, EXACT_VERIFIER_EXECUTION_GUIDANCE, RUNTIME_SOURCE_REUSE_GUIDANCE,
+  taskCriticalProofSection
+} from "./task-start-guidance.ts";
+type ExtensionContext = any; type TaskContract = any; type TaskStartParameters = any;
 export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
     DEFAULT_MAX_TASK_ATTEMPTS, ORCHESTRATION_ROLES, REVIEW_LENSES, StringEnum, Type,
     activateToolGroups, activeSessionTask, activeTaskToolGroups, appendSessionTrace, appendTrace,
-    applyRuntimeLifecycleObservation, automaticAcceptanceCriteria, automaticReadOnlyTaskScope, automaticReviewLenses, automaticTaskIntakeMode, automaticTaskRiskLane, automaticTaskScope,
-    acceptanceBaselineGuidance, acceptanceProofGuidance, bindSessionTask, buildAcceptanceReceipt, compactTaskDetails, contextBudgetConfig, createTaskRunId,
+    applyRuntimeLifecycleObservation, automaticAcceptanceCriteria, automaticReadOnlyTaskScope, automaticReviewLenses, automaticTaskIntakeMode, automaticTaskMutationPolicy, automaticTaskRiskLane, automaticTaskScope,
+    acceptanceBaselineGuidance, acceptanceLanguageAdapterForPath, acceptanceProofGuidance, bindSessionTask, buildAcceptanceReceipt, compactTaskDetails, contextBudgetConfig, createTaskRunId,
     currentSessionName, defaultWorkPlan, effectiveProtectedPaths, hasGitEvidenceRoot, hasOperatorSessionName,
-    loadProfileFromContext, matchesProtectedPath, normalizeReviewLenses, normalizeWorkPlanSteps, nowIso, policy,
+    isAcceptanceTestPath, loadProfileFromContext, matchesProtectedPath, normalizeReviewLenses, normalizeWorkPlanSteps, nowIso, policy,
     priorTaskAttempts, recordTaskStartCheckpoint, redactText, redactTextArray, registerRuntimeTool,
-    repositoryFileManifest, resolveOrchestrationPolicy, resolveTaskScopePatterns, runtimeLifecycleMode, runtimeState, safeTaskId, selectVerificationPlan,
-    summarizeAttempt, validTaskScopePattern, validateNewWorkPlan, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence,
+    repositoryFileManifest, repositoryFileManifestDetails, resolveOrchestrationPolicy, resolveTaskScopePatterns, runtimeLifecycleMode, runtimeState, safeTaskId, selectVerificationPlan,
+    summarizeAttempt, telemetry, validTaskScopePattern, validateNewWorkPlan, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence,
     writeTask
   } = deps;
   const taskStartTool = {
@@ -48,7 +33,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     promptSnippet: "Start a governed project task and persist the task contract.",
     promptGuidelines: [
       "Call this exactly once before source edits in a project managed by Pi Agent Platform.",
-      "Use source-change for project command execution, including tests, builds, lint, typecheck, verification, and package dry-runs, even when the operator requires source files to remain unchanged. Read-only intentionally blocks shell execution.",
+      "Use source-change for project verifier execution or edits. For an assessment, report, or plan with no source changes, set mutationPolicy=forbidden; use read-only when no project verifier needs to execute.",
       "Do not call context, status, policy, evidence-recording, trace, or gate tools first; runtime hooks provide those checks automatically.",
       "Use tiny for a bounded low-risk change, normal for ordinary multi-file work, and high-risk for security, data, release, migration, or external-impact work.",
       "Every scope entry must be a project-relative path or glob such as src/file.ts, src/**, or test/**; never put prose in scope.",
@@ -60,15 +45,16 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       summary: Type.String({ minLength: 10 }),
       riskLane: StringEnum(["tiny", "normal", "high-risk"] as const),
       changeMode: Type.Optional(StringEnum(["source-change", "read-only"] as const, {
-        description: "Use source-change for project command execution as well as edits; use read-only only for inspection that needs no shell execution."
+        description: "Use source-change for project verifier execution or edits; use read-only for bounded inspection."
       })),
+      mutationPolicy: Type.Optional(StringEnum(["required", "forbidden"] as const, { description: "Required demands a final diff; forbidden allows exact verification, rejects source mutation, and requires a zero task delta." })),
       maxAttempts: Type.Optional(Type.Number({ minimum: 1, maximum: 10 })),
       expectedOutput: Type.String({ minLength: 10 }),
       acceptanceCriteria: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 12 }),
       scope: Type.Array(Type.String({
         minLength: 1,
         description: "Project-relative path or glob only (for example src/file.ts, src/**, or test/**); do not use prose."
-      }), { minItems: 1 }),
+      }), { minItems: 1, maxItems: 2000 }),
       outOfScope: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
       reviewLenses: Type.Optional(Type.Array(StringEnum(REVIEW_LENSES))),
       workPlan: Type.Optional(Type.Array(Type.Object({
@@ -95,6 +81,12 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       const sessionId = ctx.sessionManager.getSessionId();
       const sessionName = currentSessionName(ctx);
       const active = activeSessionTask(ctx.cwd, sessionId) as TaskContract | undefined;
+      if (active && active.trace.outcome !== "pending" && runtimeState.taskIdentity(ctx)?.taskRunId === active.taskRunId) {
+        runtimeState.clearTaskBoundary(ctx, active.taskRunId);
+      } else if (!active) {
+        const cachedTask = runtimeState.taskIdentity(ctx);
+        if (cachedTask) runtimeState.clearTaskBoundary(ctx, cachedTask.taskRunId);
+      }
       const activeAuthorityReplacement = active ? authorityReplacementState(ctx.cwd, active) : undefined;
       if (activeAuthorityReplacement && !activeAuthorityReplacement.enforcementSafe) {
         return {
@@ -246,6 +238,8 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       }
       const orchestration = resolveOrchestrationPolicy(profile, policy);
       const changeMode = params.changeMode === "read-only" ? "read-only" : "source-change";
+      const mutationPolicy = changeMode === "read-only" || params.mutationPolicy === "forbidden" ? "forbidden" : "required";
+      if (changeMode === "read-only" && params.mutationPolicy === "required") return { content: [{ type: "text", text: "Task start refused: read-only tasks cannot require source mutation." }], isError: true };
       if (changeMode === "source-change" && !hasGitEvidenceRoot(ctx.cwd)) {
         return {
           content: [{ type: "text", text: "Task start refused: source-change tasks require a Git working tree, or a workspace parent with direct child Git repositories, so changed-file evidence cannot silently disappear. Initialize Git, open the parent that contains the repos, or use read-only mode." }],
@@ -263,7 +257,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       const reviewLenses = normalizeReviewLenses(params.reviewLenses, orchestration.defaultReviewLenses);
       const providedWorkPlan = normalizeWorkPlanSteps(params.workPlan);
       const defaultPlanLane = params.intakeMode === "runtime" && params.riskLane === "normal" ? "tiny" : params.riskLane;
-      const workPlan = providedWorkPlan.length ? providedWorkPlan : defaultWorkPlan(safeSummary, defaultPlanLane, changeMode);
+      const workPlan = providedWorkPlan.length ? providedWorkPlan : defaultWorkPlan(safeSummary, defaultPlanLane, changeMode, mutationPolicy);
       const workPlanError = validateNewWorkPlan(workPlan);
       if (workPlanError) {
         return { content: [{ type: "text", text: `Task start refused: ${workPlanError}.` }], details: workPlan, isError: true };
@@ -298,7 +292,11 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       });
       const criterionGraph = compileCriterionGraph({ acceptanceCriteria: acceptance.acceptanceCriteria, scope: resolvedScope,
         verifyCommands: verifyPlan.commands, changeMode, mode: criterionGraphMode(), createdAt });
-      const seededContext = criterionGraphContextSelection(criterionGraph, repositoryFileManifest(ctx.cwd), runtimeState.observedContext(ctx), contextBudgetConfig(policy).maxManifestFiles);
+      const projectManifest = repositoryFileManifestDetails(ctx.cwd), projectFiles = projectManifest.files;
+      const maxManifestFiles = contextBudgetConfig(policy).maxManifestFiles;
+      const plannedSelection = criterionGraphContextSelectionDetails(criterionGraph, projectFiles, [], maxManifestFiles, projectManifest.complete, resolvedScope);
+      const plannedContext = plannedSelection.entries;
+      const observedContext = criterionGraphContextSelection(undefined, [], runtimeState.preTaskContext(ctx), maxManifestFiles);
       const task: TaskContract = {
         schemaVersion: 2,
         taskRunId,
@@ -306,6 +304,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         sessionId,
         sessionName,
         changeMode,
+        mutationPolicy,
         attempt,
         maxAttempts,
         previousAttempts: priorAttempts.filter((task) => task.trace.outcome !== "pending").slice(0, 10).reverse().map(summarizeAttempt),
@@ -319,7 +318,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         outOfScope: redactTextArray(params.outOfScope),
         protectedPaths: profile.protectedPaths ?? [],
         requiredContext: profile.requiredContext ?? [],
-        contextManifest: seededContext,
+        contextManifest: observedContext,
         memoryCitations: [],
         mcpCapabilities: profile.mcpCapabilities ?? [],
         verifyGroup: verifyPlan.group,
@@ -347,16 +346,20 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         createdAt,
         updatedAt: createdAt
       };
-      if (changeMode === "read-only" && seededContext.length > 0) {
+      if (mutationPolicy === "forbidden" && observedContext.length > 0) {
         applyRuntimeLifecycleObservation(task, "context-complete", createdAt);
       }
       const written = writeTask(ctx.cwd, task);
-      const baselineGuidance = changeMode === "source-change"
+      runtimeState.promotePreTaskContext(ctx, written.taskRunId, observedContext);
+      const baselineGuidance = changeMode === "source-change" && mutationPolicy === "required"
         ? acceptanceBaselineGuidance(written, { cwd: ctx.cwd })
         : [];
-      const exactOutputGuidance = changeMode === "read-only"
+      const exactOutputGuidance = mutationPolicy === "forbidden"
         ? exactFinalOutputGuidance(written.summary)
         : [];
+      const criticalProof = taskCriticalProofSection(
+        written, plannedContext, projectFiles, acceptanceProofGuidance, isAcceptanceTestPath, acceptanceLanguageAdapterForPath
+      );
       bindSessionTask(ctx.cwd, sessionId, sessionName, written);
       runtimeState.cacheTaskIdentity(ctx, written);
       if (written.intakeMode !== "runtime") {
@@ -367,8 +370,9 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       }
       const lifecycleMode = runtimeLifecycleMode(written);
       const scopeMappings = scopeResolution.mappings.map((item) => `${item.from} -> ${item.to}`);
-      appendTrace(ctx.cwd, { taskId, taskRunId, sessionId, sessionName, attempt, event: "task_start", summary: task.summary, riskLane: params.riskLane, intakeMode: task.intakeMode, changeMode: task.changeMode, lifecycleMode, criterionGraphMode: written.criterionGraph.mode, criterionGraphDigest: written.criterionGraph.graphDigest, authorityProfile: written.authoritySnapshot.profile, authoritySnapshotDigest: written.authoritySnapshot.snapshotDigest, scopeMappings, seededContext: seededContext.map((item) => item.path) });
-      appendSessionTrace(pi, { taskId, taskRunId, sessionId, sessionName, attempt, event: "task_start", summary: task.summary, riskLane: params.riskLane, intakeMode: task.intakeMode, changeMode: task.changeMode, lifecycleMode, criterionGraphMode: written.criterionGraph.mode, criterionGraphDigest: written.criterionGraph.graphDigest, authorityProfile: written.authoritySnapshot.profile, authoritySnapshotDigest: written.authoritySnapshot.snapshotDigest, scopeMappings, seededContext: seededContext.map((item) => item.path) });
+      appendTrace(ctx.cwd, { taskId, taskRunId, sessionId, sessionName, attempt, event: "task_start", turnId: runtimeState.currentTurn(ctx)?.turnId, summary: task.summary, riskLane: params.riskLane, intakeMode: task.intakeMode, changeMode: task.changeMode, mutationPolicy: task.mutationPolicy, lifecycleMode, criterionGraphMode: written.criterionGraph.mode, criterionGraphDigest: written.criterionGraph.graphDigest, authorityProfile: written.authoritySnapshot.profile, authoritySnapshotDigest: written.authoritySnapshot.snapshotDigest, scopeMappings, plannedContext: plannedContext.map((item) => item.path), plannedContextComplete: plannedSelection.complete, plannedContextCandidateCount: plannedSelection.candidateCount, observedContext: observedContext.map((item) => item.path) });
+      appendSessionTrace(pi, { taskId, taskRunId, sessionId, sessionName, attempt, event: "task_start", turnId: runtimeState.currentTurn(ctx)?.turnId, summary: task.summary, riskLane: params.riskLane, intakeMode: task.intakeMode, changeMode: task.changeMode, mutationPolicy: task.mutationPolicy, lifecycleMode, criterionGraphMode: written.criterionGraph.mode, criterionGraphDigest: written.criterionGraph.graphDigest, authorityProfile: written.authoritySnapshot.profile, authoritySnapshotDigest: written.authoritySnapshot.snapshotDigest, scopeMappings, plannedContext: plannedContext.map((item) => item.path), plannedContextComplete: plannedSelection.complete, plannedContextCandidateCount: plannedSelection.candidateCount, observedContext: observedContext.map((item) => item.path) });
+      telemetry(ctx, { event: "turn_task_bound", turnId: runtimeState.currentTurn(ctx)?.turnId, taskRunId });
       recordTaskStartCheckpoint(ctx, written, firstReady.id, lifecycleMode);
       return {
         content: [{
@@ -379,6 +383,9 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
             written.verifyCommands.length > 0
               ? ["Exact verifier commands:", ...verifierCommandInstructions(written.verifyCommands)].join("\n")
               : "Verify: none (read-only).",
+            ...(written.verifyCommands.length > 0
+              ? [EXACT_VERIFIER_EXECUTION_GUIDANCE]
+              : []),
             written.acceptanceCriteria.length > 0
               ? ["Acceptance focus:", ...written.acceptanceCriteria.map((criterion, index) => `${index + 1}. ${criterion}`)].join("\n")
               : "Acceptance focus: not recorded.",
@@ -386,9 +393,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
               ? [["Execution map (planning only; verifier remains authoritative):", ...criterionGraphGuidance(written.criterionGraph).map((line: string) => `- ${line}`)].join("\n")]
               : []),
             ...exactOutputGuidance,
-            ...(changeMode === "source-change" && acceptanceProofGuidance(written).length > 0
-              ? [["Critical behavioral proof:", ...acceptanceProofGuidance(written).map((item: string) => `- ${item}`), "Map every proof item above to a live focused assertion or explicit test matrix before the verifier; happy-path coverage and prose claims are insufficient."].join("\n")]
-              : []),
+            ...criticalProof,
             ...(baselineGuidance.length > 0
               ? [["Existing public contract:", ...baselineGuidance.map((item: string) => `- ${item}`)].join("\n")]
               : []),
@@ -396,6 +401,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
               ? "Runtime records targeted reads and final completion automatically. Stay read-only and report cited evidence."
               : lifecycleMode === "assisted-readonly"
                 ? "Runtime records read-only evidence automatically; complete only the explicit evidence-review step before handoff."
+                : mutationPolicy === "forbidden" ? "Runtime permits bounded inspection and exact configured verifier commands only. Source mutation is blocked, and completion requires a zero task delta."
                 : lifecycleMode === "automatic"
               ? "Runtime will record reads, changes, exact verifier results, and final completion automatically. Continue with ordinary read/edit/bash work."
                   : lifecycleMode === "assisted"
@@ -408,19 +414,19 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     }
   };
   registerRuntimeTool(pi, taskStartTool);
-  async function maybeStartAutomaticTask(prompt: string, ctx: ExtensionContext): Promise<{ started: boolean; text: string; task?: TaskContract } | undefined> {
+  async function maybeStartAutomaticTask(prompt: string, ctx: ExtensionContext): Promise<{ started: boolean; text: string; task?: TaskContract; plannedContext?: Array<{ path: string; reason: string }>; plannedContextComplete?: boolean } | undefined> {
     const profile = loadProfileFromContext(ctx);
     const readProtectedPaths = effectiveProtectedPaths(policy, profile).readProtectedPaths;
     const intakeMode = automaticTaskIntakeMode(prompt, readProtectedPaths);
     if (!intakeMode) return undefined;
-    const active = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+    const mutationPolicy = automaticTaskMutationPolicy(prompt, intakeMode), active = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
     if (active?.trace.outcome === "pending") return undefined;
     const summary = redactText(automaticTaskSummary(prompt));
     const sessionName = currentSessionName(ctx);
-    const projectFiles = repositoryFileManifest(ctx.cwd);
+    const projectManifest = repositoryFileManifestDetails(ctx.cwd), projectFiles = projectManifest.files;
     const scope = intakeMode === "read-only"
-      ? automaticReadOnlyTaskScope(prompt, runtimeState.observedContext(ctx))
-      : automaticTaskScope(prompt, runtimeState.observedContext(ctx), projectFiles);
+      ? automaticReadOnlyTaskScope(prompt, runtimeState.preTaskContext(ctx))
+      : automaticTaskScope(prompt, runtimeState.preTaskContext(ctx), projectFiles);
     const started = await taskStartTool.execute(
       `runtime-intake-${ctx.sessionManager.getSessionId()}`,
       {
@@ -429,10 +435,10 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         riskLane: automaticTaskRiskLane(prompt),
         intakeMode: "runtime",
         changeMode: intakeMode,
-        expectedOutput: intakeMode === "read-only"
-          ? "The requested read-only investigation is answered from observed project evidence without mutating files."
+        mutationPolicy,
+        expectedOutput: mutationPolicy === "forbidden" ? "The requested read-only investigation is answered from observed project evidence without mutating files."
           : "The requested bounded change is implemented and passes the configured verification.",
-        acceptanceCriteria: automaticAcceptanceCriteria(prompt, intakeMode),
+        acceptanceCriteria: automaticAcceptanceCriteria(prompt, mutationPolicy === "forbidden" ? "read-only" : intakeMode),
         scope,
         outOfScope: ["Unrelated files and behavior outside the operator request."],
         reviewLenses: automaticReviewLenses(prompt)
@@ -458,22 +464,25 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       };
     }
     const assurance = taskPerformanceAssurance(task);
-    const baselineGuidance = task.changeMode === "source-change"
+    const plannedSelection = criterionGraphContextSelectionDetails(task.criterionGraph, projectFiles, [], contextBudgetConfig(policy).maxManifestFiles, projectManifest.complete, task.scope);
+    const plannedContext = plannedSelection.entries;
+    const baselineGuidance = task.changeMode === "source-change" && task.mutationPolicy !== "forbidden"
       ? acceptanceBaselineGuidance(task, { cwd: ctx.cwd })
       : [];
-    const exactOutputGuidance = task.changeMode === "read-only"
-      ? exactFinalOutputGuidance(task.summary)
-      : [];
+    const exactOutputGuidance = task.changeMode === "read-only" || task.mutationPolicy === "forbidden" ? exactFinalOutputGuidance(task.summary) : [];
+    const criticalProof = taskCriticalProofSection(
+      task, plannedContext, projectFiles, acceptanceProofGuidance, isAcceptanceTestPath, acceptanceLanguageAdapterForPath
+    );
     return {
       started: true,
       task,
+      plannedContext,
+      plannedContextComplete: plannedSelection.complete,
       text: boundedRuntimeIntakeMessage([
         `Piagent runtime task: ${task.taskId}; scope: ${task.scope.join(", ")}.`,
         "The complete operator request above is the authoritative acceptance contract; runtime keeps its full criteria, so do not restate or re-scout it.",
         `Assurance: ${assurance.tier} (${assurance.reasonCodes.join(", ") || "bounded-runtime"}).`,
-        ...(task.changeMode === "source-change" && acceptanceProofGuidance(task).length > 0
-          ? [["Critical behavioral proof:", ...acceptanceProofGuidance(task).map((item: string) => `- ${item}`), "Map every proof item above to a live focused assertion or explicit test matrix before the verifier; happy-path coverage is insufficient."].join("\n")]
-          : []),
+        ...criticalProof,
         ...(baselineGuidance.length > 0
           ? [["Existing public contract:", ...baselineGuidance.map((item: string) => `- ${item}`)].join("\n")]
           : []),
@@ -481,15 +490,11 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         "Exact verifier commands:",
         ...(task.verifyCommands.length > 0 ? verifierCommandInstructions(task.verifyCommands) : ["none"]),
         ...(criterionGraphGuidance(task.criterionGraph).length > 0 ? [["Execution map (planning only):", ...criterionGraphGuidance(task.criterionGraph).map((line: string) => `- ${line}`)].join("\n")] : []),
+        RUNTIME_SOURCE_REUSE_GUIDANCE,
         "Root project instructions are loaded. Do not re-read root AGENTS.md or inspect Piagent/platform files; work directly in relevant source/tests with ordinary tools.",
-        task.changeMode === "read-only"
-          ? "Stay read-only. Runtime records targeted reads and completion evidence; do not call task-management tools."
-          : task.criterionGraph?.mode === "criterion-graph"
-            ? "Follow the execution map: batch context reads by target, implement dependency-ready criteria, then run the exact verifier once; rerun only after a later mutation. The map plans work but never overrides the operator request or verifier."
-            : "Before mutating, privately map every operator criterion to implementation and focused-test coverage; batch independent reads or writes. Finish intended edits and one criterion-by-criterion self-review, then run the exact verifier once; rerun only after a later mutation. Runtime records evidence and completion; do not call task-management tools."
+        automaticTaskExecutionGuidance(task)
       ].join("\n"))
     };
   }
-
   return maybeStartAutomaticTask;
 }