@guanlin4924/devflow-pi 0.1.39 → 0.1.40

package/package.json

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

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

@@ -4,6 +4,10 @@ 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));
 }
@@ -872,7 +898,10 @@ export default function devflowCore(pi: ExtensionAPI) {
     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 destination = path.join(directory, `${step}.engine-events.jsonl`);
+    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,
@@ -881,6 +910,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       feature,
       step,
       event,
+      ...(attempt === undefined ? {} : { attempt, branch_id: extra.branch_id }),
       collector: "devflow-runtime/harness",
       ...extra,
     })}\n`, "utf8");
@@ -1323,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;
 
@@ -1351,11 +1385,83 @@ 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) => {
@@ -1485,6 +1591,15 @@ export default function devflowCore(pi: ExtensionAPI) {
   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");
@@ -1645,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}` };
@@ -1806,10 +1925,13 @@ 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,

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

@@ -26,7 +26,12 @@ options = {
   cancel_reason: nil,
   expected_revision: nil,
   json: false,
-  runtime_confirmed: false
+  runtime_confirmed: false,
+  parallel_action: nil,
+  parallel_branch_id: nil,
+  parallel_attempt: nil,
+  parallel_branch_revision: nil,
+  parallel_evidence: {}
 }
 
 OptionParser.new do |opts|
@@ -43,6 +48,12 @@ OptionParser.new do |opts|
   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
@@ -409,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
@@ -457,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
@@ -565,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))
 
@@ -576,13 +679,40 @@ 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])
-        target_step_id = if options[:complete_step]
+         (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"]
@@ -595,20 +725,72 @@ result =
         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[:confirm_checkpoint]
+          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 = transition_gate_preflight(workflow, state, target_step, current_revision, options[:runtime_confirmed], transition_kind)
+          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
@@ -675,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"
@@ -917,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.

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

@@ -7,6 +7,7 @@ module CheckerRegistry
     api-test-schema-check contract-coverage-check api-test-matrix-check
     test-coverage-check test-obligation-check acceptance-test-results-check
     change-impact-check tdd-evidence-check test-task-binding-check
+    cross-track-consistency-check
   ].freeze
   EMBEDDED = %w[requirement-coverage-check source-authority-check traceability-check].freeze
 

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

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "yaml"
+
+options = { feature: nil, json: false }
+OptionParser.new do |opts|
+  opts.on("--feature FEATURE") { |value| options[:feature] = value }
+  opts.on("--json") { options[:json] = true }
+end.parse!
+
+raise ArgumentError, "--feature is required" if options[:feature].to_s.empty?
+feature = options[:feature].to_s
+raise ArgumentError, "feature contains path separators" if feature.include?("/") || feature.include?("\\")
+
+root = Dir.pwd
+base = File.join(root, ".planning", "features", feature)
+files = {
+  "api_contract" => File.join(base, "api-contract.md"),
+  "api_call_guide" => File.join(base, "api-call-guide.md"),
+  "frontend_spec" => File.join(base, "前端技术方案.md"),
+  "backend_spec" => File.join(base, "后端技术方案.md"),
+  "api_supplement" => File.join(base, "api-supplement-requests.md"),
+}
+errors = []
+missing = files.select { |_, path| !File.file?(path) }.keys
+errors << { "code" => "CROSS_TRACK_ARTIFACT_MISSING", "files" => missing } unless missing.empty?
+
+read = lambda do |key|
+  path = files.fetch(key)
+  File.file?(path) ? File.read(path) : ""
+end
+contract = read.call("api_contract")
+guide = read.call("api_call_guide")
+frontend = read.call("frontend_spec")
+
+# Endpoint references are deliberately extracted from the authoritative API
+# contract and checked for textual closure in both consumers. This is a
+# deterministic reference-closure check; an AI integration summary is not used.
+endpoint_pattern = %r{\b(?:GET|POST|PUT|PATCH|DELETE)\s+(/[A-Za-z0-9_./:-]+(?:\{[A-Za-z0-9_]+\})*)}
+endpoints = contract.scan(endpoint_pattern).flatten.uniq
+unreferenced = endpoints.reject { |endpoint| guide.include?(endpoint) && frontend.include?(endpoint) }
+unless unreferenced.empty?
+  errors << { "code" => "CROSS_TRACK_ENDPOINT_REFERENCE_MISSING", "endpoints" => unreferenced }
+end
+
+contract_set = endpoints.to_h { |endpoint| [endpoint, true] }
+{
+  "api_call_guide" => guide.scan(endpoint_pattern).flatten.uniq,
+  "frontend_spec" => frontend.scan(endpoint_pattern).flatten.uniq,
+}.each do |consumer, references|
+  ghosts = references.reject { |endpoint| contract_set[endpoint] }
+  errors << { "code" => "CROSS_TRACK_ENDPOINT_NOT_IN_CONTRACT", "consumer" => consumer, "endpoints" => ghosts } unless ghosts.empty?
+end
+
+supplement = read.call("api_supplement")
+supplement_endpoints = supplement.scan(endpoint_pattern).flatten.uniq
+supplement_ghosts = supplement_endpoints.reject { |endpoint| contract_set[endpoint] }
+errors << { "code" => "CROSS_TRACK_SUPPLEMENT_ENDPOINT_NOT_IN_CONTRACT", "endpoints" => supplement_ghosts } unless supplement_ghosts.empty?
+supplement_unconsumed = supplement_endpoints.reject { |endpoint| guide.include?(endpoint) }
+errors << { "code" => "CROSS_TRACK_SUPPLEMENT_GUIDE_MISMATCH", "endpoints" => supplement_unconsumed } unless supplement_unconsumed.empty?
+
+meta_path = File.join(base, "api-call-guide.meta.json")
+if File.file?(meta_path)
+  begin
+    meta = JSON.parse(File.read(meta_path))
+    errors << { "code" => "CROSS_TRACK_API_GUIDE_NOT_CONSUMABLE" } unless meta["frontend_consumable"] == true && meta["mock_ready"] == true
+    pending = meta["pending_items"]
+    errors << { "code" => "CROSS_TRACK_API_GUIDE_PENDING_ITEMS", "pending_items" => pending } unless pending.is_a?(Array) && pending.empty?
+  rescue JSON::ParserError => error
+    errors << { "code" => "CROSS_TRACK_META_INVALID", "detail" => error.message }
+  end
+end
+
+supplement_meta = File.join(base, "api-supplement-requests.meta.json")
+if File.file?(supplement_meta)
+  begin
+    meta = JSON.parse(File.read(supplement_meta))
+    unresolved = meta["unresolved_supplement_count"]
+    errors << { "code" => "CROSS_TRACK_SUPPLEMENT_UNRESOLVED", "count" => unresolved } unless unresolved == 0
+  rescue JSON::ParserError => error
+    errors << { "code" => "CROSS_TRACK_META_INVALID", "detail" => error.message }
+  end
+end
+
+result = {
+  "ok" => errors.empty?,
+  "checker_id" => "cross-track-consistency-check",
+  "errors" => errors,
+  "evidence" => { "endpoint_count" => endpoints.length, "checked_files" => files.values.map { |path| path.sub("#{root}/", "") } },
+}
+puts(options[:json] ? JSON.generate(result) : result.to_yaml)

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

@@ -14,7 +14,7 @@ POLICY = {
   "requirement-baseline" => { "checkers" => %w[requirement-graph-check slice-independence-check acceptance-coverage-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[requirement rule boundary slice acceptance] },
   "api-contract" => { "checkers" => %w[requirement-graph-check contract-coverage-check api-test-schema-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[api] },
   "architecture-feasibility" => { "checkers" => %w[requirement-graph-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[workload_shape workload_constraint decision risk metric read_model] },
-  "integration-verify" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[requirement risk decision] },
+  "integration-verify" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check cross-track-consistency-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[requirement risk decision] },
   "acceptance-test-design" => { "checkers" => %w[requirement-graph-check contract-coverage-check acceptance-coverage-check api-test-matrix-check test-coverage-check test-obligation-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[test_case] },
   "change-plan" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check api-test-matrix-check test-coverage-check test-obligation-check test-task-binding-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[acceptance] },
   "execute" => { "checkers" => %w[tdd-evidence-check change-impact-check], "agents" => ["implementation-worker"], "budget" => 1, "allowed_graph_delta" => %w[requirement rule boundary behavior] },