@guanlin4924/devflow-pi 0.1.38 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -1,9 +1,13 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { mkdir, rename, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import {
+  TASK_SUBAGENT_LIFECYCLE_CHANNEL,
+  type SubagentLifecyclePayload,
+} from "@oh-my-pi/pi-coding-agent/task";
 
 
 export type DevflowIntent = "idle" | "explain-state" | "project-init" | "requirement-draft" | "workflow-execute";
@@ -448,6 +452,7 @@ const REQUIRED_SCRIPTS = [
   "workflow-orchestrator/scripts/tdd_evidence.py",
   "workflow-orchestrator/scripts/acceptance_test_runner.py",
   "workflow-orchestrator/scripts/machine_evidence.rb",
+  "workflow-orchestrator/scripts/cross_track_consistency_check.rb",
   "workflow-orchestrator/scripts/execution_contract.rb",
   "workflow-code-index/scripts/code_index.py",
   "workflow-context-sync/scripts/context_sync_cursor.py",
@@ -760,12 +765,24 @@ function workflowDirective(snapshot: Record<string, unknown>, source: "start" |
     recovery: snapshot.recovery,
     requirement_draft: requirementDraft,
   };
+  const parallelInstructions = snapshot.action === "run_parallel_window"
+    ? [
+      "这是并行窗口：先按 parallel_run 中的 branch 记录逐个调用 task；一个 task 只能负责一个 workflow_step，不得把多个 step 合并到一个子 Agent。",
+      "本窗口的 branch step（backend-tech-spec、api-call-guide、ui-spec、feature-breakdown、frontend-tech-spec、api-supplement）统一使用白名单 agent implementation-worker；不要把 workflow step 名称当作 agent 名称。",
+      "只有执行验证类步骤才使用 verification-runner；project-scout、requirements-auditor、contract-auditor、devflow-code-reviewer 不属于本并行窗口的默认执行 agent。",
+      "每个 task 的提示必须原样包含 DEVFLOW_BRANCH_ID、DEVFLOW_WORKFLOW_STEP、DEVFLOW_TRACK、DEVFLOW_ATTEMPT 和 DEVFLOW_BRANCH_REVISION，并只写该分支的白名单产物。",
+      "子 Agent 完成后只返回产物和验证证据；不得调用 devflow_transition，不得自行声明 checkpoint 或 join。主 Agent 负责根据生命周期结果继续调度，Core 负责最终门禁。",
+      "如果生命周期 status=aborted，按 failed 处理：先调用 Core 的 branch fail，再根据恢复信息调用 retry；不得把 aborted 当作成功或忽略，否则 join 会永久等待。",
+    ]
+    : [];
   return [
     "<devflow-runtime-directive>",
     "Devflow 已通过启动预检。读取 skill://workflow-pipeline，并只执行当前项目的一个工作流步骤。",
     "先调用 devflow_state(action=\"inspect\") 重新确认 revision，再由 workflow-orchestrator 路由当前步骤。",
     "只按 inspector 返回的当前 step 加载所需 Skill；不得调用 devflow_transition、不得推进下一步骤、不得替用户通过人工 checkpoint。",
-    "完成本步骤的真实产物后，报告证据、未决项和验证结果并停止。请用户审查后明确回复“批准执行”才可推进；回复修改意见或“拒绝执行”则不得推进。",
+    ...(parallelInstructions.length > 0 ? parallelInstructions : [
+      "完成本步骤的真实产物后，报告证据、未决项和验证结果并停止。请用户审查后明确回复“批准执行”才可推进；回复修改意见或“拒绝执行”则不得推进。",
+    ]),
     "当前步骤信封：",
     JSON.stringify(envelope, null, 2),
     "</devflow-runtime-directive>",
@@ -820,6 +837,15 @@ function inputPaths(input: unknown, cwd: string): string[] {
     .filter((value): value is string => value !== null);
 }
 
+function parallelBranchContext(input: unknown): { branch_id: string; attempt: number; branch_revision: number } | null {
+  const text = typeof input === "string" ? input : JSON.stringify(input ?? {});
+  const branch = text.match(/DEVFLOW_BRANCH_ID\s*[:=]\s*([^\s,}"']+)/)?.[1];
+  const attempt = text.match(/DEVFLOW_ATTEMPT\s*[:=]\s*(\d+)/)?.[1];
+  const revision = text.match(/DEVFLOW_BRANCH_REVISION\s*[:=]\s*(\d+)/)?.[1];
+  if (!branch || attempt === undefined || revision === undefined) return null;
+  return { branch_id: branch, attempt: Number(attempt), branch_revision: Number(revision) };
+}
+
 function isControlPath(filePath: string): boolean {
   return CONTROL_PATHS.includes(filePath) || CONTROL_PREFIXES.some(prefix => filePath.startsWith(prefix));
 }
@@ -864,6 +890,31 @@ export default function devflowCore(pi: ExtensionAPI) {
   let controlState: SessionControlState = initialControlState();
   let activeContract: ActiveExecutionContract | undefined;
   let contractAgentCalls = 0;
+  let projectRoot: string | undefined;
+
+  async function appendEngineEvidence(cwd: string | undefined, event: string, extra: Record<string, unknown> = {}) {
+    if (!cwd || !activeContract) return;
+    const feature = activeContract.feature;
+    const step = activeContract.step;
+    if (!/^[\p{L}\p{N}._-]{1,160}$/u.test(feature) || !/^[\p{L}\p{N}._-]{1,160}$/u.test(step)) return;
+    const directory = path.join(cwd, ".planning", "evidence", feature);
+    const attempt = typeof extra.attempt === "number" && Number.isInteger(extra.attempt) && extra.attempt >= 0
+      ? extra.attempt
+      : undefined;
+    const destination = path.join(directory, `${step}${attempt === undefined ? "" : `.attempt-${attempt}`}.engine-events.jsonl`);
+    await mkdir(directory, { recursive: true });
+    await appendFile(destination, `${JSON.stringify({
+      schema_version: 1,
+      timestamp: new Date().toISOString(),
+      session_id: sessionId,
+      feature,
+      step,
+      event,
+      ...(attempt === undefined ? {} : { attempt, branch_id: extra.branch_id }),
+      collector: "devflow-runtime/harness",
+      ...extra,
+    })}\n`, "utf8");
+  }
 
   function controlGuide(state: SessionControlState): string[] {
     const title = "Devflow 操作指引";
@@ -1302,6 +1353,10 @@ export default function devflowCore(pi: ExtensionAPI) {
   }
 
   let activeWorkflowTurn = false;
+  let parallelRunActive = false;
+  let parallelContinuationQueued = false;
+  const pendingParallelLifecycle = new Map<string, string>();
+  const parallelTaskContexts = new Map<string, { branch_id: string; attempt: number; branch_revision: number }>();
   let pendingProjectInitialization: ProjectInitializationRequest | undefined;
   let pendingRollover: { snapshot: Record<string, unknown>; preparedRevision: number; rolloverId: string } | undefined;
 
@@ -1330,14 +1385,87 @@ export default function devflowCore(pi: ExtensionAPI) {
     pendingRollover = { snapshot, preparedRevision: payload.revision, rolloverId };
   }
 
+  function parallelBranches(snapshot: Record<string, unknown>): Array<{ workflow_step: string; track: string }> {
+    const window = snapshot.parallel_window;
+    if (!window || typeof window !== "object") return [];
+    const branches = (window as Record<string, unknown>).branches;
+    if (!branches || typeof branches !== "object") return [];
+    return Object.entries(branches as Record<string, unknown>).flatMap(([track, steps]) => {
+      if (!Array.isArray(steps)) return [];
+      return steps.flatMap(step => {
+        const workflowStep = typeof step === "string"
+          ? step
+          : step && typeof step === "object" ? String((step as Record<string, unknown>).id ?? "") : "";
+        return workflowStep ? [{ workflow_step: workflowStep, track }] : [];
+      });
+    });
+  }
+
+  async function prepareParallelRun(cwd: string, snapshot: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (snapshot.action !== "run_parallel_window") return snapshot;
+    const feature = String(snapshot.current_feature ?? "");
+    const window = snapshot.parallel_window as Record<string, unknown> | undefined;
+    const workflowWindow = String(window?.id ?? "");
+    const existing = parseJsonResult(await runRuby(cwd, "workflow-orchestrator/scripts/parallel_run.rb", [
+      "--action", "inspect", "--feature", feature, "--json",
+    ]));
+    if (existing?.ok === true && existing.run) {
+      parallelRunActive = true;
+      return { ...snapshot, parallel_run: existing.run };
+    }
+    const revision = typeof snapshot.revision === "number" ? snapshot.revision : undefined;
+    if (!feature || !workflowWindow || revision === undefined) throw new Error("parallel window snapshot is incomplete");
+    const branches = parallelBranches(snapshot);
+    if (branches.length === 0) throw new Error("parallel window contains no branch steps");
+    const prepared = await runRuby(cwd, "workflow-orchestrator/scripts/parallel_run.rb", [
+      "--action", "prepare", "--feature", feature, "--workflow-window", workflowWindow,
+      "--state-revision", String(revision), "--json",
+      ...branches.flatMap(branch => ["--branch", `${branch.workflow_step}:${branch.track}`]),
+    ]);
+    const payload = parseJsonResult(prepared);
+    if (!controlPlaneSucceeded(prepared) || !payload?.run) {
+      throw new Error(prepared.stderr || prepared.stdout || "parallel run prepare failed");
+    }
+    parallelRunActive = true;
+    return { ...snapshot, parallel_run: payload.run };
+  }
+
   async function triggerWorkflow(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string) {
+    if (snapshot.action !== "run_parallel_window") {
+      parallelRunActive = false;
+      parallelContinuationQueued = false;
+    }
+    const preparedSnapshot = await prepareParallelRun(projectRoot ?? process.cwd(), snapshot);
     activeWorkflowTurn = true;
-    await pi.sendUserMessage(workflowDirective(snapshot, source, requirementDraft));
+    await pi.sendUserMessage(workflowDirective(preparedSnapshot, source, requirementDraft));
   }
 
+  function scheduleParallelContinuation() {
+    if (parallelContinuationQueued || pendingParallelLifecycle.size === 0) return;
+    parallelContinuationQueued = true;
+    const events = [...pendingParallelLifecycle.entries()].map(([id, status]) => `${id}:${status}`);
+    pendingParallelLifecycle.clear();
+    pi.sendMessage({
+      customType: "devflow-parallel-lifecycle",
+      content: `并行子 Agent 生命周期事件已到达（${events.join(", ")}）。请重新 inspect 整个 parallel run，逐一处理所有已完成/失败分支，必要时调用 Core 的 branch complete/fail/retry 动作，然后继续派发仍满足前置依赖的分支；不得直接 join。`,
+      display: false,
+      details: { events },
+    }, { triggerTurn: true, deliverAs: "nextTurn" });
+  }
+
+  pi.events.on(TASK_SUBAGENT_LIFECYCLE_CHANNEL, data => {
+    if (!parallelRunActive || !data || typeof data !== "object") return;
+    const event = data as Partial<SubagentLifecyclePayload>;
+    if (typeof event.id !== "string" || !["started", "completed", "failed", "aborted"].includes(String(event.status))) return;
+    if (event.status === "started") return;
+    pendingParallelLifecycle.set(event.id, String(event.status));
+    scheduleParallelContinuation();
+  });
+
   pi.setLabel("Devflow Project Runtime");
 
   pi.on("session_start", async (_event, ctx) => {
+    projectRoot = ctx.cwd;
     sessionId = randomUUID();
     const result = await runHook(ctx.cwd, "start.py", {
       session_id: sessionId,
@@ -1452,13 +1580,26 @@ export default function devflowCore(pi: ExtensionAPI) {
     await triggerWorkflow(next.snapshot, "approval");
   });
 
-  pi.on("before_agent_start", async event => ({
-    systemPrompt: [...event.systemPrompt, DEVFLOW_CHINESE_LANGUAGE_POLICY],
-  }));
+  pi.on("before_agent_start", async event => {
+    if (activeWorkflowTurn && activeContract) {
+      await appendEngineEvidence(projectRoot, "ai_runtime_initialized", { source: "runtime_before_agent_start" });
+      await appendEngineEvidence(projectRoot, "ai_invocation", { source: "runtime_before_agent_start" });
+    }
+    return { systemPrompt: [...event.systemPrompt, DEVFLOW_CHINESE_LANGUAGE_POLICY] };
+  });
 
   pi.on("agent_end", async (event, ctx) => {
     if (!activeWorkflowTurn || event.willContinue) return;
     activeWorkflowTurn = false;
+    if (parallelRunActive) {
+      parallelContinuationQueued = false;
+      setControlState(ctx, executingState("并行窗口运行中，等待子 Agent 生命周期事件"));
+      // A second detached task may finish while the continuation is running.
+      // Its event is retained and gets a follow-up continuation instead of
+      // being dropped behind the current queue marker.
+      scheduleParallelContinuation();
+      return;
+    }
     if (controlState.phase === "executing") {
       setControlState(ctx, waitingUserState("等待用户审查步骤产物并明确决定"));
       ctx.ui.notify("当前步骤已结束。请审查输出：明确回复“批准执行”推进，或回复修改意见/“拒绝执行”保持当前步骤。", "info");
@@ -1543,7 +1684,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           "--json",
           "--expected-revision",
           String(revision),
-          ...(checkpoint ? ["--confirm-checkpoint"] : ["--complete-step", stepId!]),
+          ...(checkpoint ? ["--confirm-checkpoint", "--runtime-confirmed"] : ["--complete-step", stepId!]),
         ]);
         if (!result.ok) {
           setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "推进校验失败" });
@@ -1619,6 +1760,10 @@ export default function devflowCore(pi: ExtensionAPI) {
 
   pi.on("tool_call", async (event, ctx) => {
     const toolName = String(event.toolName).toLowerCase();
+    if (parallelRunActive && toolName === "task") {
+      const branchContext = parallelBranchContext(event.input);
+      if (branchContext) parallelTaskContexts.set(event.toolCallId, branchContext);
+    }
     if (activeContract && controlState.phase === "executing" && !toolName.startsWith("devflow_")) {
       if (!activeContract.allowedTools.includes(toolName)) {
         return { block: true, reason: `Active contract ${activeContract.contractId} does not allow tool: ${toolName}` };
@@ -1691,6 +1836,18 @@ export default function devflowCore(pi: ExtensionAPI) {
           "Devflow 状态迁移只能由运行时在用户明确批准已展示的步骤或 checkpoint 后执行；LLM 不得自行推进。",
       };
     }
+    if (isUserConfirmedStepTransition && activeContract) {
+      const evidence = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/machine_evidence.rb", [
+        "--feature", activeContract.feature, "--step", activeContract.step, "--write", "--json",
+      ]);
+      const evidencePayload = parseJsonResult(evidence);
+      if (!evidence.ok || !evidencePayload || evidencePayload.complete !== true) {
+        return {
+          block: true,
+          reason: `Devflow machine evidence is incomplete; collect independent runtime evidence before completing ${activeContract.step}.`,
+        };
+      }
+    }
     if (
       !toolName.startsWith("devflow_") &&
       ["write", "edit", "apply_patch", "notebook_edit", "bash", "shell", "exec_command"].includes(toolName) &&
@@ -1767,6 +1924,15 @@ export default function devflowCore(pi: ExtensionAPI) {
 
   pi.on("tool_result", async (event, ctx) => {
     if (event.isError) return;
+    if (activeWorkflowTurn && activeContract) {
+      const taskContext = parallelTaskContexts.get(event.toolCallId);
+      await appendEngineEvidence(ctx.cwd, "engine_dispatched", {
+        engine: event.toolName,
+        ai_capable: event.toolName === "task" || event.toolName.toLowerCase().includes("ai") || event.toolName.toLowerCase().includes("midscene"),
+        ...(taskContext ?? {}),
+      });
+      if (taskContext) parallelTaskContexts.delete(event.toolCallId);
+    }
     await runHook(ctx.cwd, "post_tool.py", {
       session_id: sessionId,
       cwd: ctx.cwd,
@@ -1867,7 +2033,11 @@ export default function devflowCore(pi: ExtensionAPI) {
             stderr: "TC candidates are accepted only during the active acceptance-test-design contract.",
           });
         }
-        args.push("--write", "--expected-revision", String(params.expectedRevision), "--delta-json", JSON.stringify(params.delta));
+        args.push("--expected-revision", String(params.expectedRevision), "--delta-json", JSON.stringify(params.delta));
+        // `write` is an explicit dry-run switch. Omit it only when the caller
+        // explicitly asks for a preview; the normal approved proposal remains
+        // a Core-owned write.
+        if (params.write !== false) args.push("--write");
         if (activeContract?.allowedGraphDelta?.length) args.push("--allowed-kinds", activeContract.allowedGraphDelta.join(","));
       }
       if (params.action === "confirm") {

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/advance_state.rb

@@ -12,6 +12,7 @@ require_relative "control_io"
 require_relative "validate_state"
 require_relative "phase_ownership"
 require_relative "requirement_graph"
+require_relative "gate_runtime"
 
 options = {
   state: nil,
@@ -24,7 +25,13 @@ options = {
   cancel: false,
   cancel_reason: nil,
   expected_revision: nil,
-  json: false
+  json: false,
+  runtime_confirmed: false,
+  parallel_action: nil,
+  parallel_branch_id: nil,
+  parallel_attempt: nil,
+  parallel_branch_revision: nil,
+  parallel_evidence: {}
 }
 
 OptionParser.new do |opts|
@@ -40,6 +47,13 @@ OptionParser.new do |opts|
   opts.on("--cancel-reason REASON", "Record why the active feature was cancelled") { |reason| options[:cancel_reason] = reason }
   opts.on("--expected-revision REVISION", Integer, "Reject a stale write unless STATE.md has this revision") { |value| options[:expected_revision] = value }
   opts.on("--json", "Print JSON output") { options[:json] = true }
+  opts.on("--runtime-confirmed", "Internal runtime authorization for checkpoint confirmation") { options[:runtime_confirmed] = true }
+  opts.on("--parallel-action ACTION", %w[start complete fail retry join]) { |value| options[:parallel_action] = value }
+  opts.on("--parallel-branch-id ID", "Branch id for a parallel transition") { |value| options[:parallel_branch_id] = value }
+  opts.on("--parallel-task-id ID", "OMP task id to bind to a branch") { |value| options[:parallel_task_id] = value }
+  opts.on("--parallel-attempt N", Integer) { |value| options[:parallel_attempt] = value }
+  opts.on("--parallel-branch-revision N", Integer) { |value| options[:parallel_branch_revision] = value }
+  opts.on("--parallel-evidence JSON") { |value| options[:parallel_evidence] = JSON.parse(value) }
 end.parse!
 
 root = Dir.pwd
@@ -64,6 +78,63 @@ def load_workflow(root, state)
   [relative, load_yaml_file(path)]
 end
 
+def gate_contract_enabled?(workflow)
+  workflow.dig("governance", "gate_contract_version").to_i >= 3
+end
+
+# Build the runtime view from the existing workflow declaration.  This keeps
+# governance.step_checkers as the single checker namespace and avoids creating
+# a second hand-maintained per-step transition table.
+def transition_gate_contract(workflow, step)
+  checkpoints = workflow["checkpoints"] || {}
+  checkpoint_id = step["checkpoint"]
+  checkpoint = checkpoint_id && checkpoints[checkpoint_id]
+  track_names = Array(workflow["parallel_windows"]).flat_map do |window|
+    next [] unless window.is_a?(Hash) && window["branches"].is_a?(Hash)
+    window["branches"].keys.map { |name| name.to_s.sub(/\Atrack_/, "").upcase }
+  end
+  allowed_tracks = track_names.empty? ? ["main"] : ["main", *track_names]
+  reentries = (workflow["failure_branches"] || {}).each_with_object([]) do |(source_step, branch), entries|
+    next unless branch.is_a?(Hash) && branch["resume_after_success"].is_a?(Hash)
+    entries << { "source" => { "flow" => branch["workflow"], "step" => source_step }, "target" => branch["resume_after_success"], "requires_checkpoint_reconfirm" => true }
+  end
+  {
+    "gate_id" => "#{step.fetch("id")}-gate-v1",
+    "step_id" => step.fetch("id"),
+    "topology" => {
+      "allowed_tracks" => allowed_tracks,
+      "allowed_predecessors" => Array(step["depends_on"]),
+      "allowed_reentry" => reentries,
+      "checkpoint" => checkpoint && checkpoint.merge("id" => checkpoint_id)
+    },
+    "entry" => { "required_inputs" => Array(step["inputs"]) },
+    "outputs" => { "required" => Array(step["outputs"]).select { |output| output["required"] } },
+    "quality" => { "checker_ids" => Array(workflow.dig("governance", "step_checkers", step["id"])) },
+    "concurrency" => { "project_lock" => "required", "optimistic_revision" => "required", "registry_view" => "candidate_overlay" },
+    "recovery" => { "allowed" => ["sync_artifacts", "repair_outputs"], "max_attempts" => 2 }
+  }
+end
+
+def transition_gate_preflight(workflow, state, step, current_revision, checkpoint_authorized = false, transition_kind = nil)
+  return nil unless gate_contract_enabled?(workflow)
+
+  contract = transition_gate_contract(workflow, step)
+  track = state["active_track"].to_s
+  track = "main" unless %w[A B].include?(track)
+  GateRuntime.evaluate(
+    contract: contract,
+    workflow_state: state,
+    current_revision: current_revision,
+    expected_revision: current_revision,
+    track: track,
+    source: "advance_state",
+    root: Dir.pwd,
+    check_outputs: step["id"].to_s == state["current_step"].to_s,
+    transition_kind: transition_kind,
+    checkpoint_authorized: checkpoint_authorized
+  )
+end
+
 def interpolate_path(path, state)
   path
     .gsub("{feature}", state.fetch("current_feature", "").to_s)
@@ -349,6 +420,63 @@ def track_boundary?(state, pending_ids)
   (pending_ids & track_allowed_steps(track)).empty? && pending_ids.any?
 end
 
+def parallel_window_for(workflow, completed_step_id)
+  Array(workflow["parallel_windows"]).find do |window|
+    window.is_a?(Hash) && window["after_step"].to_s == completed_step_id.to_s
+  end
+end
+
+def parallel_branch_for(root, state, branch_id)
+  record = ParallelRun.load(root, state.fetch("current_feature"))
+  branch = Array(record && record["branches"]).find { |item| item["branch_id"].to_s == branch_id.to_s }
+  [record, branch]
+end
+
+def advance_parallel_branch(root, state, options, lock = nil)
+  branch_id = options[:parallel_branch_id]
+  raise ArgumentError, "parallel branch id is required" if branch_id.to_s.empty?
+  record, branch = parallel_branch_for(root, state, branch_id)
+  raise ArgumentError, "parallel run not found" unless record
+  raise ArgumentError, "parallel branch not found: #{branch_id}" unless branch
+  expected = Integer(record.fetch("run_revision", 0))
+  case options[:parallel_action]
+  when "start"
+    ParallelRun.update_branch(root: root, feature: state.fetch("current_feature"), branch_id: branch_id, expected_revision: expected, status: "running", task_id: options[:parallel_task_id], lock: lock)
+  when "complete"
+    ParallelRun.update_branch(root: root, feature: state.fetch("current_feature"), branch_id: branch_id, expected_revision: expected, status: "succeeded", evidence_path: options[:parallel_evidence]["evidence_path"], output_fingerprint: options[:parallel_evidence]["output_fingerprint"], lock: lock)
+  when "fail"
+    # The error is diagnostic metadata only; it is never used as evidence or
+    # as an authorization for branch completion.
+    ParallelRun.update_branch(root: root, feature: state.fetch("current_feature"), branch_id: branch_id, expected_revision: expected, status: "failed", error: options[:parallel_evidence]["error"], lock: lock)
+  when "retry"
+    ParallelRun.retry_branch(root: root, feature: state.fetch("current_feature"), branch_id: branch_id, expected_revision: expected, lock: lock)
+  else
+    raise ArgumentError, "unsupported parallel branch action"
+  end
+end
+
+def join_parallel_window(root, state, workflow, current_revision)
+  record = ParallelRun.load(root, state.fetch("current_feature"))
+  raise ArgumentError, "parallel run not found" unless record
+  branches = Array(record["branches"])
+  incomplete = branches.reject { |branch| branch["status"].to_s == "succeeded" }
+  raise ArgumentError, "parallel join requires every branch to succeed" unless branches.any? && incomplete.empty?
+
+  branch_steps = branches.map { |branch| branch.fetch("workflow_step").to_s }
+  state["completed_steps"] = (Array(state["completed_steps"]) + branch_steps).uniq
+  state["pending_steps"] = Array(state["pending_steps"]) - branch_steps
+  state["last_completed_step"] = state["current_step"]
+  state.delete("parallel_run_ref")
+  record["status"] = "completed"
+  record["run_revision"] = Integer(record.fetch("run_revision", 0)) + 1
+  record["updated_at"] = Time.now.utc.iso8601
+  state["current_step"] = workflow.fetch("parallel_windows").find { |window| window["id"].to_s == record["workflow_window"].to_s }.fetch("join_step")
+  state["status"] = "in_progress"
+  state["state_updated_at"] = Date.today.to_s
+  state["revision"] = current_revision + 1
+  [state, record, "Parallel window joined; branch steps merged and parallel_run_ref cleared."]
+end
+
 def fail_result(reason, details = {})
   { "ok" => false, "reason" => reason, "details" => details }
 end
@@ -397,6 +525,40 @@ rescue JSON::ParserError => error
   { "ok" => false, "errors" => ["API test schema checker returned invalid JSON: #{error.message}"] }
 end
 
+def cross_track_checker_enabled?(workflow, step_id)
+  Array(workflow.dig("governance", "step_checkers", step_id)).map(&:to_s).include?("cross-track-consistency-check")
+end
+
+def cross_track_consistency_check(root, feature)
+  script = File.join(__dir__, "cross_track_consistency_check.rb")
+  stdout, stderr, status = Open3.capture3("ruby", script, "--feature", feature, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash)
+
+  { "ok" => false, "errors" => [stderr.strip.empty? ? "cross-track checker returned invalid output" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "errors" => ["cross-track checker returned invalid JSON: #{error.message}"] }
+end
+
+def branch_machine_evidence(root, state, branch)
+  script = File.join(__dir__, "machine_evidence.rb")
+  step = branch.fetch("workflow_step").to_s
+  attempt = Integer(branch.fetch("attempt", 0))
+  revision = Integer(branch.fetch("branch_revision", 0))
+  stdout, stderr, status = Open3.capture3(
+    "ruby", script, "--feature", state.fetch("current_feature"), "--step", step,
+    "--parallel-branch-id", branch.fetch("branch_id").to_s,
+    "--parallel-attempt", attempt.to_s, "--parallel-branch-revision", revision.to_s,
+    "--lock-held", "--write", "--json", chdir: root
+  )
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash) && payload["ok"] == true
+
+  { "ok" => false, "errors" => [stderr.strip.empty? ? "machine evidence returned invalid output" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "errors" => ["machine evidence returned invalid JSON: #{error.message}"] }
+end
+
 def test_suite_freeze_attestation_path(root, feature)
   DevflowControlIO.resolve_control_path(root, ".planning/features/#{feature}/test-suite-freeze.json", :artifact)
 end
@@ -505,6 +667,7 @@ result =
       next_intent_written = nil
       actions = []
       action_description = nil
+      parallel_run_to_write = nil
       next_intent_requested = false
       current_revision = Integer(state.fetch("revision", 0))
 
@@ -516,6 +679,118 @@ result =
         )
       end
 
+      # Branch completion evidence is always generated by Core from the
+      # persisted branch record and current artifacts. Ignore any caller-built
+      # binding so an agent cannot self-attest a different attempt/revision.
+      if result.nil? && options[:parallel_action] == "complete" && options[:write]
+        _run, branch = parallel_branch_for(root, state, options[:parallel_branch_id])
+        if branch.nil?
+          result = fail_result("parallel_branch_not_found")
+        else
+          generated = branch_machine_evidence(root, state, branch)
+          if generated["ok"] == true
+            binding = generated.fetch("parallel_binding")
+            options[:parallel_evidence] = {
+              "evidence_path" => generated.fetch("path"),
+              "branch_id" => binding.fetch("branch_id"),
+              "attempt" => binding.fetch("attempt"),
+              "branch_revision" => binding.fetch("branch_revision"),
+              "state_revision" => binding.fetch("state_revision")
+            }
+          else
+            result = fail_result("parallel_machine_evidence_failed", "evidence" => generated)
+          end
+        end
+      end
+
+      # GateRuntime is a read-only boundary check.  It runs while the project
+      # lock is held and before any candidate state mutation; the existing
+      # validator and advance_state CAS remain the final write guard.
+      if result.nil? && gate_contract_enabled?(workflow) &&
+         !%w[prepared claimed].include?(state.dig("rollover", "status")) &&
+         (options[:complete_step] || options[:confirm_checkpoint] || options[:enter_failure_branch] || options[:exit_failure_branch] || options[:parallel_action])
+        target_step_id = if options[:parallel_action] && options[:parallel_action] != "join"
+                           _record, branch = parallel_branch_for(root, state, options[:parallel_branch_id])
+                           branch && branch["workflow_step"]
+                         elsif options[:complete_step]
+                           options[:complete_step]
+                         elsif options[:confirm_checkpoint]
+                           state["current_step"]
+                         else
+                           state["current_step"]
+                         end
+        target_step = step_by_id[target_step_id]
+        if target_step.nil?
+          result = fail_result("gate_target_step_unknown", "step" => target_step_id)
+        elsif options[:complete_step] && state["current_step"].to_s != target_step_id.to_s
+          result = fail_result("gate_current_step_mismatch", "current_step" => state["current_step"], "requested_step" => target_step_id)
+        else
+          transition_kind = if options[:parallel_action]
+                              { "start" => "parallel_branch_start", "complete" => "parallel_branch_complete", "fail" => "parallel_branch_fail", "retry" => "parallel_branch_retry", "join" => "parallel_join" }.fetch(options[:parallel_action])
+                            elsif options[:confirm_checkpoint]
+                              "confirm_checkpoint"
+                            elsif options[:enter_failure_branch]
+                              "enter_failure_branch"
+                            elsif options[:exit_failure_branch]
+                              "exit_failure_branch"
+                            end
+          gate_result = GateRuntime.evaluate(
+            contract: transition_gate_contract(workflow, target_step),
+            workflow_state: state,
+            current_revision: current_revision,
+            expected_revision: current_revision,
+            track: if options[:parallel_action] && options[:parallel_action] != "join"
+                     _record, branch = parallel_branch_for(root, state, options[:parallel_branch_id])
+                     branch ? branch["track"].to_s.sub(/\Atrack_/, "").upcase : (active_track(state) || "main")
+                   else
+                     active_track(state) || "main"
+                   end,
+            branch_id: options[:parallel_branch_id],
+            attempt: options[:parallel_attempt],
+            branch_revision: options[:parallel_branch_revision],
+            evidence: options[:parallel_evidence],
+            source: "advance_state",
+            root: root,
+            check_outputs: target_step["id"].to_s == state["current_step"].to_s,
+            transition_kind: transition_kind,
+            checkpoint_authorized: options[:runtime_confirmed]
+          )
+          if gate_result && gate_result["verdict"] != "allow"
+            result = fail_result("gate_boundary_rejected", "gate" => gate_result)
+          end
+        end
+      end
+
+      if result.nil? && options[:parallel_action]
+        if !options[:write]
+          result = fail_result("parallel_transition_requires_write")
+        elsif options[:parallel_action] == "join"
+          begin
+            if cross_track_checker_enabled?(workflow, "integration-verify")
+              checker = cross_track_consistency_check(root, state.fetch("current_feature"))
+              unless checker["ok"] == true
+                result = fail_result("cross_track_consistency_failed", "checker" => checker)
+              end
+            end
+            if result.nil?
+              state, parallel_run_to_write, action_description = join_parallel_window(root, state, workflow, current_revision)
+              changed = true
+              actions << "parallel_window_joined"
+            end
+          rescue ArgumentError, KeyError, TypeError => error
+            result = fail_result("parallel_join_failed", "message" => error.message)
+          end
+        else
+          begin
+            advance_parallel_branch(root, state, options, project_lock)
+            actions << "parallel_branch_#{options[:parallel_action]}"
+            action_description = "Parallel branch #{options[:parallel_action]}: #{options[:parallel_branch_id]}"
+          rescue ArgumentError, KeyError, TypeError => error
+            result = fail_result("parallel_branch_transition_failed", "message" => error.message)
+          end
+        end
+      end
+
       if result.nil? && options[:checkpoint_decision]
         state["checkpoint_decision"] = options[:checkpoint_decision]
         changed = true
@@ -582,6 +857,12 @@ result =
             state["checkpoint"] = step["checkpoint"]
             state["checkpoint_label"] = checkpoint_label(workflow, step["checkpoint"])
             action_description = "Step completed: #{step["label"]} (#{step_id}). Now waiting at #{step["checkpoint"]}."
+          elsif (parallel_window = parallel_window_for(workflow, step_id))
+            state["current_step"] = parallel_window.fetch("join_step")
+            state["status"] = "in_progress"
+            state.delete("checkpoint")
+            state.delete("checkpoint_label")
+            action_description = "Step completed: #{step["label"]} (#{step_id}). Entered parallel window #{parallel_window["id"]}; awaiting Core prepare."
           elsif track_boundary?(state, pending)
             state["current_step"] = step_id
             state["status"] = "blocked"
@@ -824,6 +1105,7 @@ result =
             sync_artifact_registry(root, workflow, state, registry: candidate_registry)
             artifact_by_path = load_artifact_registry(root, workflow)
             write_state_file(root, state_path, state, workflow, artifact_by_path, action_description)
+            ParallelRun.write(root, state.fetch("current_feature"), parallel_run_to_write) if parallel_run_to_write
             # STATE.md is project-global. Once its top-level workflow is
             # terminal, retain the historical owner but release its active
             # reservation so the next feature can claim a distinct phase.