@guanlin4924/devflow-pi 0.1.13 → 0.1.14

package/package.json

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

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

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { mkdir, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -42,6 +42,10 @@ const READ_ONLY_TOOLS = new Set([
 ]);
 
 const REQUIREMENT_DRAFT_TOOLS = new Set([...READ_ONLY_TOOLS, "ask"]);
+// A Todo update changes only the client-visible task list, never the project
+// or Devflow state. Permit it during planning so a harmless checklist cannot
+// produce a misleading "blocked" warning during initialization.
+const PLANNING_INTERNAL_TOOLS = new Set(["todo"]);
 
 const PLANNING_AGENTS = new Set(["project-scout", "requirements-auditor", "contract-auditor"]);
 
@@ -93,6 +97,7 @@ export function statusText(state: SessionControlState): string {
 
 export function isPlanningToolAllowed(toolName: string, taskAgents: string[] = []): boolean {
   const normalized = toolName.toLowerCase();
+  if (PLANNING_INTERNAL_TOOLS.has(normalized)) return true;
   if (READ_ONLY_TOOLS.has(normalized)) return true;
   if (normalized !== "task") return false;
   return taskAgents.length > 0 && taskAgents.every(agent => PLANNING_AGENTS.has(agent));
@@ -105,6 +110,7 @@ export function isReadOnlyShellCommand(command: string): boolean {
 
 export function isRequirementDraftToolAllowed(toolName: string, input: unknown, taskAgents: string[] = []): boolean {
   const normalized = toolName.toLowerCase();
+  if (PLANNING_INTERNAL_TOOLS.has(normalized)) return true;
   if (["bash", "shell", "exec_command"].includes(normalized)) {
     const record = input && typeof input === "object" ? input as Record<string, unknown> : {};
     return isReadOnlyShellCommand(String(record.command ?? record.cmd ?? ""));
@@ -113,11 +119,21 @@ export function isRequirementDraftToolAllowed(toolName: string, input: unknown,
   return normalized === "task" && taskAgents.length > 0 && taskAgents.every(agent => PLANNING_AGENTS.has(agent));
 }
 
+/** `xd://devflow_contract` is an in-memory OMP control resource, not a
+ * project file. The planner must be able to read and activate it while the
+ * filesystem remains read-only; otherwise initialization deadlocks before it
+ * can create a bounded execution contract. */
+export function isInternalDevflowContractResource(toolName: string, input: unknown): boolean {
+  if (!["read", "write"].includes(toolName.toLowerCase()) || !input || typeof input !== "object") return false;
+  const record = input as Record<string, unknown>;
+  return [record.path, record.uri, record.resource].some(value => value === "xd://devflow_contract");
+}
+
 export type NaturalControlAction = "approve" | "reject";
 
 export function classifyNaturalControlAction(input: string): NaturalControlAction | null {
   const text = input.trim();
-  if (/^(?:批准|确认|同意|通过)(?:执行|继续|推进|当前(?:方案|步骤|计划))?[。！!]?$/.test(text)) return "approve";
+  if (/^(?:批准|确认|同意|通过)(?:\s*(?:(?:full|完整|全量)?\s*初始化|执行|继续|推进|当前(?:方案|步骤|计划)))?[。！!]?$/i.test(text)) return "approve";
   if (/^(?:拒绝|不同意|暂不|需要修改|退回)(?:执行|继续|推进|当前(?:方案|步骤|计划))?[。！!]?$/.test(text)) return "reject";
   return null;
 }
@@ -256,6 +272,7 @@ const REQUIRED_AGENT_NAMES = new Set(Object.keys(REQUIRED_AGENTS));
 const REQUIRED_SCRIPTS = [
   "workflow-orchestrator/scripts/init_workflow.rb",
   "workflow-orchestrator/scripts/init_state.rb",
+  "workflow-orchestrator/scripts/phase_ownership.rb",
   "workflow-orchestrator/scripts/inspect_state.rb",
   "workflow-orchestrator/scripts/advance_state.rb",
   "workflow-orchestrator/scripts/sync_artifacts.rb",
@@ -263,6 +280,17 @@ const REQUIRED_SCRIPTS = [
   "workflow-context-sync/scripts/context_sync_cursor.py",
 ];
 
+function defaultPhaseId(feature: string): string {
+  // STATE.md is project-global, so a generic name such as "delivery" is not
+  // a safe default. Keep the generated id filesystem-safe and deterministic
+  // without requiring a user to learn a phase-naming command.
+  return `feature-${createHash("sha256").update(feature, "utf8").digest("hex").slice(0, 12)}`;
+}
+
+function validPhaseId(phase: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(phase);
+}
+
 function resolvePluginRoot(): string {
   const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
   return path.resolve(process.env.DEVFLOW_PLUGIN_ROOT || path.resolve(moduleDirectory, "../.."));
@@ -490,6 +518,13 @@ function parseJsonResult(result: ProcessResult): Record<string, unknown> | null
   }
 }
 
+/** Ruby control-plane scripts report expected validation failures as JSON with
+ * `ok: false` and intentionally keep a zero process exit code. Never mistake
+ * that structured failure for a successful state mutation. */
+function controlPlaneSucceeded(result: ProcessResult): boolean {
+  return result.ok && parseJsonResult(result)?.ok === true;
+}
+
 function compactStep(value: unknown): Record<string, unknown> | null {
   if (!value || typeof value !== "object") return null;
   const step = value as Record<string, unknown>;
@@ -542,6 +577,17 @@ function workflowDirective(snapshot: Record<string, unknown>, source: "start" |
   ].join("\n");
 }
 
+function projectInitializationDirective(summary: string): string {
+  return [
+    "<devflow-project-initialization-directive>",
+    "用户已批准完整项目初始化。现在处于执行模式；不要再创建 Todo、不要读取或写入 xd://devflow_contract。",
+    "执行 skill://workflow-project-context，按已确认的项目边界建立 .planning/PROJECT.md、.planning/navigation/INDEX.md、.context/spec/index.md，并按用户选择建立 full 代码索引。",
+    "只写项目初始化所需的 .planning/ 与 .context/ 控制产物；不得改动业务源码、依赖或配置。完成后运行项目初始化校验，报告生成文件和验证结果并停止，等待用户审查。",
+    summary,
+    "</devflow-project-initialization-directive>",
+  ].join("\n");
+}
+
 function explainWorkflowSnapshot(snapshot: Record<string, unknown> | null): string {
   if (!snapshot) return "Devflow 当前没有可解释的工作流状态。可使用 /devflow start <feature> 创建新 Feature。";
   const step = compactStep(snapshot.next_step) ?? compactStep(snapshot.current_step);
@@ -881,6 +927,7 @@ export default function devflowCore(pi: ExtensionAPI) {
   }
 
   let activeWorkflowTurn = false;
+  let pendingProjectInitialization: string | undefined;
 
   async function triggerWorkflow(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string) {
     activeWorkflowTurn = true;
@@ -933,6 +980,21 @@ export default function devflowCore(pi: ExtensionAPI) {
       await triggerWorkflow(inspected.snapshot, "start", requirementDraft);
       return { handled: true };
     }
+    if (controlState.intent === "project-init" && controlState.phase === "planning") {
+      if (controlAction === "approve") {
+        if (!pendingProjectInitialization) {
+          ctx.ui.notify("项目初始化缺少已确认的边界信息，请重新发起初始化。", "error");
+          return { handled: true };
+        }
+        setControlState(ctx, executingState("执行已批准的项目初始化"));
+        activeWorkflowTurn = true;
+        return { text: projectInitializationDirective(pendingProjectInitialization), handled: false };
+      }
+      if (controlAction === "reject") {
+        ctx.ui.notify("已保留初始化规划，未创建任何项目控制文件。请直接说明需要调整的初始化范围。", "info");
+        return { handled: true };
+      }
+    }
     if (controlState.phase === "awaiting-approval" || controlState.phase === "waiting-user") {
       if (controlAction === "reject") {
         ctx.ui.notify("已保留当前步骤和产物。请直接说明需要修改的内容；未执行任何推进。", "info");
@@ -985,6 +1047,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     if (intent === "project-init") {
       const summary = await collectProjectInitialization(ctx);
       if (!summary) return { handled: true };
+      pendingProjectInitialization = summary;
       const state = planningState("project-init");
       setControlState(ctx, state);
       return {
@@ -1051,6 +1114,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     } else if (
       controlState.phase === "planning" &&
       toolName !== "devflow_contract" &&
+      !isInternalDevflowContractResource(toolName, event.input) &&
       !(toolName === "devflow_evidence" && String((event.input as Record<string, unknown> | undefined)?.action) !== "create") &&
       !(controlState.intent === "requirement-draft"
         ? isRequirementDraftToolAllowed(toolName, event.input)
@@ -1342,35 +1406,54 @@ export default function devflowCore(pi: ExtensionAPI) {
     description: "Initialize workflow definitions, STATE.md, and the artifact registry for a project feature.",
     parameters: z.object({
       feature: z.string().min(1),
-      phase: z.string().min(1).default("delivery"),
+      phase: z.string().min(1).optional(),
       flow: z.string().min(1).default("feature-development"),
       force: z.boolean().default(false),
     }),
     approval: "write",
     async execute(_id, params, _signal, _onUpdate, ctx) {
+      const phase = params.phase?.trim() || defaultPhaseId(params.feature);
+      if (!validPhaseId(phase)) {
+        return {
+          content: [{ type: "text" as const, text: "Phase ID 必须是 1-64 位字母、数字、下划线或连字符，且不得包含路径分隔符。" }],
+          isError: true,
+        };
+      }
       const force = params.force ? ["--force"] : [];
+      const ownership = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/phase_ownership.rb", [
+        "claim",
+        "--feature",
+        params.feature,
+        "--phase",
+        phase,
+        "--flow",
+        params.flow,
+        "--json",
+      ]);
+      if (!controlPlaneSucceeded(ownership)) return renderResult(ownership, { stage: "phase-ownership" });
       const workflow = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_workflow.rb", [
         "--write",
         "--json",
         ...force,
       ]);
-      if (!workflow.ok) return renderResult(workflow, { stage: "workflow" });
+      if (!controlPlaneSucceeded(workflow)) return renderResult(workflow, { stage: "workflow" });
       const state = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_state.rb", [
         "--feature",
         params.feature,
         "--phase",
-        params.phase,
+        phase,
         "--flow",
         params.flow,
         "--write",
         "--json",
         ...force,
       ]);
-      if (!state.ok) return renderResult(state, { stage: "state" });
+      if (!controlPlaneSucceeded(state)) return renderResult(state, { stage: "state" });
       const artifacts = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
         "--write",
         "--json",
       ]);
+      if (!controlPlaneSucceeded(artifacts)) return renderResult(artifacts, { stage: "artifacts" });
       return renderResult(artifacts, {
         stage: "complete",
         workflow: workflow.stdout,
@@ -1455,7 +1538,8 @@ export default function devflowCore(pi: ExtensionAPI) {
     approval: "write",
     async execute(_id, params, _signal, _onUpdate, ctx) {
       const args = ["--write", "--confirm", "--expected-revision", String(params.expectedRevision), "--json"];
-      if (params.state) args.push("--state", params.state);
+      const state = safeControlPath(ctx.cwd, params.state, "state");
+      if (state) args.push("--state", state);
       return renderResult(
         await runRuby(ctx.cwd, "workflow-orchestrator/scripts/repair_control_plane.rb", args),
         { action: "repair-control-plane" },
@@ -1573,6 +1657,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       if (trimmed === "project-init") {
         const summary = await collectProjectInitialization(ctx);
         if (!summary) return;
+        pendingProjectInitialization = summary;
         setControlState(ctx, planningState("project-init"));
         await pi.sendUserMessage(
           [
@@ -1617,11 +1702,16 @@ export default function devflowCore(pi: ExtensionAPI) {
         return;
       }
       if (trimmed.startsWith("start ")) {
-        const [feature, phase = "delivery"] = trimmed.slice(6).split("|", 2).map(value => value.trim());
+        const [feature, requestedPhase] = trimmed.slice(6).split("|", 2).map(value => value.trim());
         if (!feature) {
           ctx.ui.notify("Usage: /devflow start <feature>|<phase>", "error");
           return;
         }
+        const phase = requestedPhase || defaultPhaseId(feature);
+        if (!validPhaseId(phase)) {
+          ctx.ui.notify("Phase ID 必须是 1-64 位字母、数字、下划线或连字符，且不得包含路径分隔符。", "error");
+          return;
+        }
         const report = await runDoctor(ctx);
         if (!report.ok) {
           ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
@@ -1636,16 +1726,33 @@ export default function devflowCore(pi: ExtensionAPI) {
           existingFeature !== feature
         ) {
           ctx.ui.notify(
-            `An unfinished Devflow state belongs to feature ${existingFeature}. Use /devflow resume and complete that workflow before starting ${feature}.`,
+            `当前仍有未完成需求：${existingFeature}。请在对话中继续处理当前步骤，完成后再创建新需求：${feature}。`,
             "error",
           );
           return;
         }
+        // This dry-run happens before init_workflow.rb, so a rejected feature
+        // can never overwrite generated workflow files belonging to an active
+        // owner or a legacy phase directory that has no trustworthy owner.
+        const ownership = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/phase_ownership.rb", [
+          "claim",
+          "--feature",
+          feature,
+          "--phase",
+          phase,
+          "--flow",
+          "feature-development",
+          "--json",
+        ]);
+        if (!controlPlaneSucceeded(ownership)) {
+          ctx.ui.notify((ownership.stderr || ownership.stdout).slice(0, 6000), "error");
+          return;
+        }
         const workflow = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_workflow.rb", [
           "--write",
           "--json",
         ]);
-        if (!workflow.ok) {
+        if (!controlPlaneSucceeded(workflow)) {
           ctx.ui.notify(workflow.stderr || workflow.stdout, "error");
           return;
         }
@@ -1660,7 +1767,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           "--json",
           ...(previousWorkflowComplete ? ["--force"] : []),
         ]);
-        if (!state.ok) {
+        if (!controlPlaneSucceeded(state)) {
           ctx.ui.notify((state.stderr || state.stdout).slice(0, 6000), "error");
           return;
         }
@@ -1668,7 +1775,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           "--write",
           "--json",
         ]);
-        if (!artifacts.ok) {
+        if (!controlPlaneSucceeded(artifacts)) {
           ctx.ui.notify((artifacts.stderr || artifacts.stdout).slice(0, 6000), "error");
           return;
         }

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

@@ -8,6 +8,7 @@ require "optparse"
 require "yaml"
 require_relative "control_io"
 require_relative "validate_state"
+require_relative "phase_ownership"
 
 options = {
   state: nil,
@@ -35,7 +36,7 @@ OptionParser.new do |opts|
 end.parse!
 
 root = Dir.pwd
-state_path = options[:state] ? File.expand_path(options[:state], root) : File.join(root, ".planning", "STATE.md")
+state_path, = DevflowControlIO.resolve_control_path(root, options[:state] || ".planning/STATE.md", :state)
 
 def front_matter(markdown)
   match = markdown.match(/\A---\n(.*?)\n---\n/m)
@@ -51,8 +52,9 @@ def workflow_path_for(root, state)
 end
 
 def load_workflow(root, state)
-  path = workflow_path_for(root, state)
-  [path, load_yaml_file(File.join(root, path))]
+  source = workflow_path_for(root, state)
+  path, relative = DevflowControlIO.resolve_control_path(root, source, :workflow)
+  [relative, load_yaml_file(path)]
 end
 
 def interpolate_path(path, state)
@@ -65,7 +67,7 @@ def load_artifact_registry(root, workflow)
   registry_path = workflow.dig("artifact_registry", "source")
   return {} unless registry_path
 
-  abs = File.join(root, registry_path)
+  abs, = DevflowControlIO.resolve_control_path(root, registry_path, :registry)
   return {} unless File.exist?(abs)
 
   registry = load_yaml_file(abs)
@@ -79,7 +81,7 @@ def collect_outputs(workflow)
 end
 
 def content_validity(root, path, checks)
-  abs = File.join(root, path)
+  abs, = DevflowControlIO.resolve_control_path(root, path, :artifact)
   return { "valid" => false, "issues" => ["file_missing"] } unless File.exist?(abs)
 
   issues = []
@@ -102,7 +104,7 @@ def build_artifact_registry(root, workflow, state)
   registry_path = workflow.dig("artifact_registry", "source")
   return [nil, nil] unless registry_path
 
-  abs = File.join(root, registry_path)
+  abs, = DevflowControlIO.resolve_control_path(root, registry_path, :registry)
   existing_by_path = if File.exist?(abs)
                        Array(load_yaml_file(abs)["artifacts"]).to_h { |artifact| [artifact.fetch("path"), artifact] }
                      else
@@ -127,7 +129,8 @@ def build_artifact_registry(root, workflow, state)
       end
 
     validity = content_validity(root, path, content_checks)
-    file_exists = File.exist?(File.join(root, path))
+    artifact_path, = DevflowControlIO.resolve_control_path(root, path, :artifact)
+    file_exists = File.exist?(artifact_path)
     status = if preservable_statuses.include?(existing["status"])
                existing["status"]
              else
@@ -169,7 +172,7 @@ def sync_artifact_registry(root, workflow, state, registry: nil)
   return nil unless registry_path
 
   registry ||= build_artifact_registry(root, workflow, state).last
-  abs = File.join(root, registry_path)
+  abs, = DevflowControlIO.resolve_control_path(root, registry_path, :registry)
   DevflowControlIO.atomic_write(abs, registry.to_yaml)
   registry_path
 end
@@ -348,7 +351,7 @@ def apply_return_to!(root, state, branch_workflow)
   source_workflow_config = state["source_workflow_config"]
   return nil unless return_to && source_flow && source_workflow_config
 
-  main_workflow_path = File.join(root, source_workflow_config)
+  main_workflow_path, = DevflowControlIO.resolve_control_path(root, source_workflow_config, :workflow)
   return nil unless File.exist?(main_workflow_path)
 
   main_workflow = load_yaml_file(main_workflow_path)
@@ -512,7 +515,8 @@ result =
           result = fail_result("missing_failure_branch", "current_step" => state["current_step"])
         else
           branch_path = branch.fetch("workflow_config")
-          branch_workflow = load_yaml_file(File.join(root, branch_path))
+          branch_workflow_path, branch_path = DevflowControlIO.resolve_control_path(root, branch_path, :workflow)
+          branch_workflow = load_yaml_file(branch_workflow_path)
           transition = branch_workflow.dig("state_contract", "suggested_transition") || {}
           state["source_flow"] = state["current_flow"]
           state["source_workflow_config"] = workflow_path
@@ -553,6 +557,13 @@ result =
           state["revision"] = current_revision + 1
           workflow_path, workflow = load_workflow(root, state)
         end
+        prospective_owner = if changed
+                              {
+                                "phase" => state["current_phase"], "feature" => state["current_feature"],
+                                "flow" => state["current_flow"], "state_path" => ".planning/STATE.md",
+                                "scope" => "global", "status" => "active"
+                              }
+                            end
         # Build the registry from the candidate state before validating it. A
         # step's output is normally written before this transition, so the
         # persisted registry may still describe the previous state revision.
@@ -564,16 +575,37 @@ result =
           state_override: state,
           artifact_registry_override: candidate_registry,
           strict_artifact_status: false,
-          strict_registry_revision: false
+          strict_registry_revision: false,
+          phase_owner_override: prospective_owner
         )
 
         if changed && !validation["ok"]
           result = fail_result("state_validation_failed", "validation" => validation)
         elsif changed && options[:write]
-          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)
-          next_intent_written = write_next_intent(root, workflow) if next_intent_requested
+          ownership = PhaseOwnership.claim(
+            root: root, feature: state["current_feature"], phase: state["current_phase"],
+            flow: state["current_flow"], write: true
+          )
+          if !ownership["ok"]
+            result = fail_result("phase_ownership_claim_failed", "ownership" => ownership)
+          else
+            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)
+            # 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.
+            if %w[completed failed cancelled].include?(state["status"]) && Array(state["pending_steps"]).empty? && state["source_flow"].nil?
+              completed_owner = PhaseOwnership.complete(
+                root: root, feature: state["current_feature"], phase: state["current_phase"],
+                flow: state["current_flow"], write: true
+              )
+              unless completed_owner["ok"]
+                result = fail_result("phase_ownership_completion_failed", "ownership" => completed_owner)
+              end
+            end
+            next_intent_written = write_next_intent(root, workflow) if next_intent_requested
+          end
         end
 
         result ||= {

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

@@ -2,14 +2,56 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "pathname"
 require "securerandom"
 
 # Shared durability primitives for every writer in the Devflow control plane.
 # The project lock serializes state, workflow, registry, and next-intent updates;
 # atomic rename prevents readers from observing partially written documents.
 module DevflowControlIO
+  class InvalidControlPath < StandardError; end
+
   module_function
 
+  # Control-plane files are not general-purpose CLI file arguments. Keeping
+  # their location fixed prevents a crafted STATE/workflow/registry reference
+  # from turning recovery or synchronization into an out-of-project writer.
+  def resolve_control_path(root, raw, kind)
+    root_path = File.realpath(root)
+    value = raw.to_s
+    raise InvalidControlPath, "#{kind} path is required" if value.empty?
+    raise InvalidControlPath, "#{kind} path must be project-relative" if Pathname.new(value).absolute?
+    raise InvalidControlPath, "#{kind} path contains control characters" if value.match?(/[\x00-\x1F\x7F]/)
+
+    normalized = Pathname.new(value).cleanpath.to_s.tr("\\", "/")
+    raise InvalidControlPath, "#{kind} path cannot traverse parent directories" if normalized == ".." || normalized.start_with?("../")
+    allowed = case kind
+              when :state then normalized == ".planning/STATE.md"
+              when :workflow then normalized.match?(%r{\A\.planning/workflows/[A-Za-z0-9][A-Za-z0-9_-]*\.yaml\z})
+              when :registry then normalized == ".planning/artifacts/index.yaml"
+              when :artifact then normalized.start_with?(".planning/") || normalized.start_with?(".context/")
+              else false
+              end
+    raise InvalidControlPath, "invalid #{kind} control path" unless allowed
+
+    absolute = File.expand_path(normalized, root_path)
+    raise InvalidControlPath, "#{kind} path escapes project root" unless absolute.start_with?("#{root_path}#{File::SEPARATOR}")
+    # Existing symlinks in any parent component are equally unsafe: a write
+    # through one could escape after lexical normalization.
+    cursor = root_path
+    normalized.split("/").each do |segment|
+      cursor = File.join(cursor, segment)
+      next unless File.exist?(cursor) || File.symlink?(cursor)
+      next unless File.symlink?(cursor)
+
+      resolved = File.realpath(cursor)
+      unless resolved == root_path || resolved.start_with?("#{root_path}#{File::SEPARATOR}")
+        raise InvalidControlPath, "#{kind} path escapes project through a symlink"
+      end
+    end
+    [absolute, normalized]
+  end
+
   def acquire_project_lock(root)
     planning_dir = File.join(root, ".planning")
     FileUtils.mkdir_p(planning_dir)

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

@@ -2,11 +2,13 @@
 # frozen_string_literal: true
 
 require "date"
+require "digest"
 require "fileutils"
 require "json"
 require "optparse"
 require "yaml"
 require_relative "control_io"
+require_relative "phase_ownership"
 
 options = {
   feature: nil,
@@ -36,7 +38,12 @@ OptionParser.new do |opts|
 end.parse!
 
 root = Dir.pwd
-state_path = File.expand_path(options[:state], root)
+begin
+  state_path, = DevflowControlIO.resolve_control_path(root, options[:state], :state)
+rescue DevflowControlIO::InvalidControlPath => error
+  puts JSON.pretty_generate({ "ok" => false, "reason" => "invalid_control_path", "message" => error.message })
+  exit 0
+end
 
 def front_matter(markdown)
   match = markdown.match(/\A---\n(.*?)\n---\n/m)
@@ -44,7 +51,13 @@ def front_matter(markdown)
 end
 
 feature = options[:feature] || File.basename(root)
-phase = options[:phase] || "01-#{feature}"
+# CLI callers get the same safe invariant as the extension entrypoint: phase
+# identifiers never derive from a user-facing feature label or a shared name.
+phase = options[:phase] || "feature-#{Digest::SHA256.hexdigest(feature)[0, 12]}"
+unless PhaseOwnership.valid_slug?(phase)
+  puts JSON.pretty_generate({ "ok" => false, "reason" => "invalid_phase", "message" => "phase must be a safe non-empty slug" })
+  exit 0
+end
 workflow_config = ".planning/workflows/#{options[:flow]}.yaml"
 workflow_path = File.expand_path(workflow_config, root)
 fallback_pending_steps = [
@@ -104,6 +117,11 @@ state["active_track"] = options[:track] if %w[A B].include?(options[:track].to_s
 project_lock = DevflowControlIO.acquire_project_lock(root) if options[:write]
 
 begin
+ownership = PhaseOwnership.claim(root: root, feature: feature, phase: phase, flow: options[:flow], write: options[:write])
+unless ownership["ok"]
+  puts JSON.pretty_generate(ownership)
+  exit 0
+end
 existing = File.exist?(state_path) ? File.read(state_path) : nil
 existing_front = existing && front_matter(existing)
 action =
@@ -129,6 +147,7 @@ result = {
   "written" => options[:write] && action != "skip_existing_front_matter",
   "path" => options[:state],
   "action" => action,
+  "phase_ownership" => ownership,
   "state" => state
 }
 ensure

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

@@ -0,0 +1,154 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The control plane has one STATE.md, so phases must be claimed serially.  This
+# registry deliberately lives beside STATE.md instead of inside a phase folder:
+# it remains visible even when a caller has selected the wrong phase directory.
+require "date"
+require "json"
+require "optparse"
+require "yaml"
+require_relative "control_io"
+
+module PhaseOwnership
+  REGISTRY_PATH = ".planning/phase-ownership.yaml"
+  PHASE_SLUG = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
+  module_function
+
+  def valid_slug?(value)
+    value.is_a?(String) && value.match?(PHASE_SLUG)
+  end
+
+  # Feature labels are user-facing names and may be Unicode.  They are never
+  # used as a registry filename here, but reject separators/control characters
+  # so a later caller cannot reinterpret them as a path.
+  def valid_feature?(value)
+    value.is_a?(String) && !value.strip.empty? && !value.match?(/[\\\/\x00-\x1F\x7F]/)
+  end
+
+  def registry_path(root)
+    File.join(root, REGISTRY_PATH)
+  end
+
+  def load_registry(root)
+    path = registry_path(root)
+    return [nil, nil] unless File.exist?(path)
+
+    registry = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+    return [nil, "invalid_phase_ownership_registry"] unless registry.is_a?(Hash) && registry["schema_version"] == 1 && registry["owners"].is_a?(Hash)
+
+    [registry, nil]
+  rescue Psych::Exception
+    [nil, "invalid_phase_ownership_registry"]
+  end
+
+  def valid_owner?(owner, phase: nil)
+    owner.is_a?(Hash) && valid_slug?(owner["phase"]) && (phase.nil? || owner["phase"] == phase) &&
+      valid_feature?(owner["feature"]) && owner["flow"].is_a?(String) && !owner["flow"].empty? &&
+      owner["state_path"] == ".planning/STATE.md" && %w[active completed].include?(owner["status"])
+  end
+
+  def nonempty_phase_dirs(root)
+    Dir.glob(File.join(root, ".planning", "phases", "*")).select do |path|
+      File.directory?(path) && !Dir.children(path).empty?
+    end.map { |path| File.basename(path) }
+  end
+
+  def claim(root:, feature:, phase:, flow:, write:)
+    return failure("invalid_phase", "phase must be a safe non-empty slug") unless valid_slug?(phase)
+    return failure("invalid_feature", "feature must be non-empty and cannot contain path separators or control characters") unless valid_feature?(feature)
+    return failure("invalid_flow", "flow is required") unless flow.is_a?(String) && !flow.empty?
+
+    registry, error = load_registry(root)
+    return failure(error, "phase ownership registry is malformed") if error
+    registry ||= { "schema_version" => 1, "owners" => {} }
+    owners = registry["owners"]
+
+    nonempty_phase_dirs(root).each do |phase_dir|
+      owner = owners[phase_dir]
+      next if valid_owner?(owner, phase: phase_dir)
+
+      return failure("legacy_phase_directory_without_owner", "non-empty phase directory has no valid ownership record", phase: phase_dir)
+    end
+
+    owners.each do |owner_phase, owner|
+      return failure("invalid_phase_owner", "phase ownership record is invalid", phase: owner_phase) unless valid_owner?(owner, phase: owner_phase)
+      next unless owner["status"] == "active"
+      next if owner["phase"] == phase && owner["feature"] == feature
+
+      return failure("active_phase_owned_by_another_feature", "an active phase already owns the global state", owner: owner)
+    end
+
+    current = owners[phase]
+    if current && current["feature"] != feature
+      return failure("phase_owned_by_another_feature", "requested phase is already owned by another feature", owner: current)
+    end
+
+    owner = current || { "phase" => phase, "feature" => feature, "flow" => flow, "state_path" => ".planning/STATE.md", "scope" => "global", "status" => "active" }
+    owner = owner.merge("phase" => phase, "feature" => feature, "flow" => flow, "state_path" => ".planning/STATE.md", "scope" => "global", "status" => "active")
+    registry["owners"][phase] = owner
+    registry["updated_at"] = Date.today.to_s
+    DevflowControlIO.atomic_write(registry_path(root), registry.to_yaml) if write
+    { "ok" => true, "written" => write, "action" => current ? "idempotent_claim" : "claim", "owner" => owner, "path" => REGISTRY_PATH }
+  end
+
+  def complete(root:, feature:, phase:, flow:, write:)
+    registry, error = load_registry(root)
+    return failure(error || "missing_phase_owner", "phase ownership record is required") unless registry
+    owner = registry["owners"][phase]
+    unless valid_owner?(owner, phase: phase) && owner["feature"] == feature && owner["flow"] == flow
+      return failure("phase_owner_mismatch", "cannot complete a phase owned by another feature")
+    end
+    owner["status"] = "completed"
+    registry["updated_at"] = Date.today.to_s
+    DevflowControlIO.atomic_write(registry_path(root), registry.to_yaml) if write
+    { "ok" => true, "written" => write, "action" => "complete", "owner" => owner, "path" => REGISTRY_PATH }
+  end
+
+  def validate_state(root:, state:, owner_override: nil)
+    registry, error = load_registry(root)
+    return failure(error || "missing_phase_owner", "STATE.md has no phase ownership record") unless registry
+    phase = state["current_phase"]
+    feature = state["current_feature"]
+    flow = state["current_flow"]
+    return failure("invalid_phase", "STATE.md current_phase must be a safe non-empty slug") unless valid_slug?(phase)
+    owner = owner_override || registry["owners"][phase]
+    return failure("missing_phase_owner", "STATE.md phase has no ownership record", phase: phase) unless valid_owner?(owner, phase: phase)
+    unless owner["feature"] == feature && owner["flow"] == flow && owner["state_path"] == ".planning/STATE.md"
+      return failure("phase_owner_mismatch", "STATE.md does not match phase ownership record", owner: owner)
+    end
+    conflicting = registry["owners"].values.find { |entry| valid_owner?(entry) && entry["status"] == "active" && entry["phase"] != phase }
+    return failure("active_phase_ownership_conflict", "another active phase owns the global state", owner: conflicting) if conflicting
+    { "ok" => true, "owner" => owner, "path" => REGISTRY_PATH }
+  end
+
+  def failure(reason, message, extra = {})
+    { "ok" => false, "reason" => reason, "message" => message }.merge(extra)
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { feature: nil, phase: nil, flow: "feature-development", write: false, json: false }
+  command = ARGV.shift
+  OptionParser.new do |opts|
+    opts.banner = "Usage: phase_ownership.rb claim|inspect|complete --feature NAME --phase ID --flow ID [--write] [--json]"
+    opts.on("--feature NAME") { |value| options[:feature] = value }
+    opts.on("--phase ID") { |value| options[:phase] = value }
+    opts.on("--flow ID") { |value| options[:flow] = value }
+    opts.on("--write") { options[:write] = true }
+    opts.on("--json") { options[:json] = true }
+  end.parse!
+  root = Dir.pwd
+  lock = options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
+  begin
+    result = case command
+             when "claim" then PhaseOwnership.claim(root: root, feature: options[:feature], phase: options[:phase], flow: options[:flow], write: options[:write])
+             when "complete" then PhaseOwnership.complete(root: root, feature: options[:feature], phase: options[:phase], flow: options[:flow], write: options[:write])
+             when "inspect" then PhaseOwnership.validate_state(root: root, state: { "current_feature" => options[:feature], "current_phase" => options[:phase], "current_flow" => options[:flow] })
+             else PhaseOwnership.failure("invalid_command", "command must be claim, inspect, or complete")
+             end
+  ensure
+    DevflowControlIO.release_lock(lock)
+  end
+  puts JSON.pretty_generate(result)
+end

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

@@ -7,6 +7,7 @@ require "optparse"
 require "yaml"
 require_relative "control_io"
 require_relative "validate_state"
+require_relative "phase_ownership"
 
 options = { state: ".planning/STATE.md", expected_revision: nil, confirm: false, write: false, json: false }
 OptionParser.new do |opts|
@@ -31,7 +32,7 @@ def build_registry(root, workflow, state)
   artifacts = Array(workflow["steps"]).flat_map do |step|
     Array(step["outputs"]).map do |output|
       path = interpolate_path(output.fetch("path"), state)
-      abs = File.join(root, path)
+      abs, = DevflowControlIO.resolve_control_path(root, path, :artifact)
       exists = File.exist?(abs)
       issues = []
       issues << "file_missing" unless exists
@@ -53,43 +54,51 @@ def build_registry(root, workflow, state)
 end
 
 root = Dir.pwd
-state_path = File.expand_path(options[:state], root)
 result = nil
 lock = options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
 begin
+  state_path, = DevflowControlIO.resolve_control_path(root, options[:state], :state)
   unless File.exist?(state_path)
     result = { "ok" => false, "classification" => "unsafe", "reason" => "missing_state_file" }
   else
     state = YAML.safe_load(front_matter(File.read(state_path)), permitted_classes: [], aliases: false)
-    workflow_path = File.expand_path(state.fetch("workflow_config"), root)
-    workflow = YAML.safe_load(File.read(workflow_path), permitted_classes: [], aliases: false)
-    registry_source = workflow.dig("artifact_registry", "source")
-    if !registry_source.is_a?(String) || registry_source.empty?
-      result = { "ok" => false, "classification" => "unsafe", "reason" => "missing_artifact_registry_config", "plan" => { "state_transition" => "none", "registry_write" => false } }
+    ownership = PhaseOwnership.validate_state(root: root, state: state)
+    unless ownership["ok"]
+      result = { "ok" => false, "classification" => "unsafe", "reason" => ownership["reason"], "issues" => [ownership], "plan" => { "state_transition" => "none", "registry_write" => false } }
     else
-      candidate = build_registry(root, workflow, state)
-      validation = WorkflowStateValidator.validate(root: root, state_path: state_path, state_override: state, workflow_override: workflow, artifact_registry_override: candidate, strict_artifact_status: true, strict_registry_revision: true)
-      current = Array(workflow["steps"]).find { |step| step["id"] == state["current_step"] }
-      missing_current_outputs = Array(current && current["outputs"]).map do |output|
-        next unless output["required"]
-        path = interpolate_path(output.fetch("path"), state)
-        path unless File.exist?(File.join(root, path))
-      end.compact
-      if missing_current_outputs.any?
-        result = { "ok" => false, "classification" => "unsafe", "reason" => "missing_required_output", "missing_outputs" => missing_current_outputs, "plan" => { "state_transition" => "none", "registry_write" => false } }
-      elsif !validation["ok"]
-        result = { "ok" => false, "classification" => "unsafe", "reason" => "ambiguous_or_invalid_state", "issues" => validation["errors"], "plan" => { "state_transition" => "none", "registry_write" => false } }
-      elsif !options[:confirm] || !options[:write]
-        result = { "ok" => false, "classification" => "safe_repairable", "reason" => "confirmation_required", "revision" => state.fetch("revision", 0), "plan" => { "state_transition" => "none", "registry_write" => true, "registry" => candidate } }
-      elsif options[:expected_revision] != state.fetch("revision", 0)
-        result = { "ok" => false, "classification" => "unsafe", "reason" => "stale_revision", "expected_revision" => options[:expected_revision], "actual_revision" => state.fetch("revision", 0) }
+      workflow_path, = DevflowControlIO.resolve_control_path(root, state.fetch("workflow_config"), :workflow)
+      workflow = YAML.safe_load(File.read(workflow_path), permitted_classes: [], aliases: false)
+      registry_source = workflow.dig("artifact_registry", "source")
+      if !registry_source.is_a?(String) || registry_source.empty?
+        result = { "ok" => false, "classification" => "unsafe", "reason" => "missing_artifact_registry_config", "plan" => { "state_transition" => "none", "registry_write" => false } }
       else
-        registry_path = File.join(root, registry_source)
-        DevflowControlIO.atomic_write(registry_path, candidate.to_yaml)
-        result = { "ok" => true, "classification" => "safe_repairable", "written" => true, "revision" => state.fetch("revision", 0), "plan" => { "state_transition" => "none", "registry_write" => true } }
+        candidate = build_registry(root, workflow, state)
+        validation = WorkflowStateValidator.validate(root: root, state_path: state_path, state_override: state, workflow_override: workflow, artifact_registry_override: candidate, strict_artifact_status: true, strict_registry_revision: true)
+        current = Array(workflow["steps"]).find { |step| step["id"] == state["current_step"] }
+        missing_current_outputs = Array(current && current["outputs"]).map do |output|
+          next unless output["required"]
+          path = interpolate_path(output.fetch("path"), state)
+          output_path, = DevflowControlIO.resolve_control_path(root, path, :artifact)
+          path unless File.exist?(output_path)
+        end.compact
+        if missing_current_outputs.any?
+          result = { "ok" => false, "classification" => "unsafe", "reason" => "missing_required_output", "missing_outputs" => missing_current_outputs, "plan" => { "state_transition" => "none", "registry_write" => false } }
+        elsif !validation["ok"]
+          result = { "ok" => false, "classification" => "unsafe", "reason" => "ambiguous_or_invalid_state", "issues" => validation["errors"], "plan" => { "state_transition" => "none", "registry_write" => false } }
+        elsif !options[:confirm] || !options[:write]
+          result = { "ok" => false, "classification" => "safe_repairable", "reason" => "confirmation_required", "revision" => state.fetch("revision", 0), "plan" => { "state_transition" => "none", "registry_write" => true, "registry" => candidate } }
+        elsif options[:expected_revision] != state.fetch("revision", 0)
+          result = { "ok" => false, "classification" => "unsafe", "reason" => "stale_revision", "expected_revision" => options[:expected_revision], "actual_revision" => state.fetch("revision", 0) }
+        else
+          registry_path, = DevflowControlIO.resolve_control_path(root, registry_source, :registry)
+          DevflowControlIO.atomic_write(registry_path, candidate.to_yaml)
+          result = { "ok" => true, "classification" => "safe_repairable", "written" => true, "revision" => state.fetch("revision", 0), "plan" => { "state_transition" => "none", "registry_write" => true } }
+        end
       end
     end
   end
+rescue DevflowControlIO::InvalidControlPath => error
+  result = { "ok" => false, "classification" => "unsafe", "reason" => "invalid_control_path", "message" => error.message, "plan" => { "state_transition" => "none", "registry_write" => false } }
 ensure
   DevflowControlIO.release_lock(lock)
 end

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

@@ -7,6 +7,7 @@ require "json"
 require "optparse"
 require "yaml"
 require_relative "control_io"
+require_relative "phase_ownership"
 
 options = {
   state: ".planning/STATE.md",
@@ -63,11 +64,18 @@ end
 project_lock = DevflowControlIO.acquire_project_lock(root) if options[:write]
 
 begin
-state = load_state(File.join(root, options[:state]))
-workflow_path = options[:workflow] || state["workflow_config"] || ".planning/workflows/#{state.fetch("current_flow")}.yaml"
-workflow = load_yaml_file(File.join(root, workflow_path))
-registry_path = options[:output] || workflow.dig("artifact_registry", "source") || ".planning/artifacts/index.yaml"
-existing_registry_path = File.join(root, registry_path)
+state_path, = DevflowControlIO.resolve_control_path(root, options[:state], :state)
+state = load_state(state_path)
+ownership = PhaseOwnership.validate_state(root: root, state: state)
+unless ownership["ok"]
+  puts JSON.pretty_generate(ownership.merge("written" => false))
+  exit 0
+end
+workflow_source = options[:workflow] || state["workflow_config"] || ".planning/workflows/#{state.fetch("current_flow")}.yaml"
+workflow_path, = DevflowControlIO.resolve_control_path(root, workflow_source, :workflow)
+workflow = load_yaml_file(workflow_path)
+registry_source = options[:output] || workflow.dig("artifact_registry", "source") || ".planning/artifacts/index.yaml"
+existing_registry_path, registry_path = DevflowControlIO.resolve_control_path(root, registry_source, :registry)
 existing_by_path = {}
 if options[:preserve] && File.exist?(existing_registry_path)
   existing = load_yaml_file(existing_registry_path)
@@ -80,7 +88,7 @@ content_checks = workflow.dig("artifact_registry", "content_checks") || {}
 preservable_statuses = %w[approved completed passed pending_rerun stale failed]
 
 def content_validity(root, path, checks)
-  abs = File.join(root, path)
+  abs, = DevflowControlIO.resolve_control_path(root, path, :artifact)
   return { "valid" => false, "issues" => ["file_missing"] } unless File.exist?(abs)
 
   issues = []
@@ -114,7 +122,8 @@ artifacts = collect_outputs(workflow).map do |step, output|
     end
 
   validity = content_validity(root, path, content_checks)
-  file_exists = File.exist?(File.join(root, path))
+  artifact_path, = DevflowControlIO.resolve_control_path(root, path, :artifact)
+  file_exists = File.exist?(artifact_path)
   status = if options[:preserve] && preservable_statuses.include?(existing["status"])
              existing["status"]
            else
@@ -161,6 +170,8 @@ result = {
   "missing_count" => artifacts.count { |artifact| !artifact["exists"] },
   "registry" => registry
 }
+rescue DevflowControlIO::InvalidControlPath => error
+  result = { "ok" => false, "written" => false, "reason" => "invalid_control_path", "message" => error.message }
 ensure
   DevflowControlIO.release_lock(project_lock)
 end

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

@@ -4,6 +4,8 @@
 require "json"
 require "optparse"
 require "yaml"
+require_relative "control_io"
+require_relative "phase_ownership"
 
 module WorkflowStateValidator
   REQUIRED_STATE_FIELDS = %w[
@@ -18,12 +20,18 @@ module WorkflowStateValidator
 
   TERMINAL_ARTIFACT_STATUSES = %w[approved completed passed].freeze
   NON_TERMINAL_ARTIFACT_STATUSES = %w[planned generated pending_rerun stale failed].freeze
+  TERMINAL_WORKFLOW_STATUSES = %w[completed failed cancelled].freeze
 
   module_function
 
-  def validate(root:, state_path:, state_override: nil, workflow_override: nil, artifact_registry_override: nil, strict_artifact_status: true, strict_registry_revision: true)
+  def validate(root:, state_path:, state_override: nil, workflow_override: nil, artifact_registry_override: nil, strict_artifact_status: true, strict_registry_revision: true, phase_owner_override: nil)
     root = File.expand_path(root)
-    state_path = File.expand_path(state_path, root)
+    canonical_state_path, = DevflowControlIO.resolve_control_path(root, ".planning/STATE.md", :state)
+    unless File.expand_path(state_path, root) == canonical_state_path
+      issues = [issue("error", "invalid_control_path", "STATE.md path must be .planning/STATE.md")]
+      return result(false, state_path, nil, nil, issues)
+    end
+    state_path = canonical_state_path
     issues = []
 
     state = state_override || load_state(state_path, issues)
@@ -34,8 +42,14 @@ module WorkflowStateValidator
     end
     return result(false, state_path, nil, nil, issues) if issues.any? { |entry| entry["severity"] == "error" }
 
+    ownership = PhaseOwnership.validate_state(root: root, state: state, owner_override: phase_owner_override)
+    unless ownership["ok"]
+      issues << issue("error", ownership["reason"], ownership["message"], ownership.reject { |key, _| %w[ok reason message].include?(key) })
+      return result(false, state_path, nil, nil, issues)
+    end
+
     workflow_path = state["workflow_config"] || File.join(".planning", "workflows", "#{state.fetch("current_flow")}.yaml")
-    abs_workflow_path = File.expand_path(workflow_path, root)
+    abs_workflow_path, workflow_path = DevflowControlIO.resolve_control_path(root, workflow_path, :workflow)
     workflow = workflow_override || load_yaml(abs_workflow_path, issues, "workflow_config")
     return result(false, state_path, workflow_path, nil, issues) unless workflow
 
@@ -103,7 +117,7 @@ module WorkflowStateValidator
 
     registry = registry_override
     unless registry
-      abs_registry_path = File.expand_path(registry_path, root)
+      abs_registry_path, = DevflowControlIO.resolve_control_path(root, registry_path, :registry)
       unless File.exist?(abs_registry_path)
         issues << issue("error", "missing_artifact_registry", "Artifact registry does not exist", path: registry_path)
         return {}
@@ -121,7 +135,7 @@ module WorkflowStateValidator
       )
     end
     Array(registry["artifacts"]).to_h { |artifact| [artifact.fetch("path"), artifact] }
-  rescue ArgumentError, TypeError, Psych::SyntaxError => e
+  rescue ArgumentError, TypeError, Psych::SyntaxError, DevflowControlIO::InvalidControlPath => e
     issues << issue("error", "invalid_artifact_registry", e.message, path: registry_path)
     {}
   end
@@ -145,8 +159,10 @@ module WorkflowStateValidator
     unknown.each do |step_id|
       issues << issue("error", "unknown_tracked_step", "Tracked step is not defined in the active workflow", step: step_id)
     end
-    missing.each do |step_id|
-      issues << issue("error", "missing_tracked_step", "Workflow step is missing from both completed_steps and pending_steps", step: step_id)
+    unless %w[failed cancelled].include?(state["status"])
+      missing.each do |step_id|
+        issues << issue("error", "missing_tracked_step", "Workflow step is missing from both completed_steps and pending_steps", step: step_id)
+      end
     end
 
     current_step = state["current_step"]
@@ -162,6 +178,10 @@ module WorkflowStateValidator
       missing_completed.each do |step_id|
         issues << issue("error", "completed_status_missing_step", "Workflow status is completed but a workflow step is not completed", step: step_id)
       end
+    elsif %w[failed cancelled].include?(state["status"])
+      if pending_ids.any?
+        issues << issue("error", "terminal_with_pending_steps", "Terminal workflow status must not retain pending steps", status: state["status"])
+      end
     elsif pending_ids.empty?
       issues << issue("error", "non_completed_without_pending_steps", "Workflow has no pending steps but status is not completed")
     end
@@ -589,7 +609,12 @@ if __FILE__ == $PROGRAM_NAME
   end.parse!
 
   root = Dir.pwd
-  state_path = File.expand_path(options[:state], root)
+  begin
+    state_path, = DevflowControlIO.resolve_control_path(root, options[:state], :state)
+  rescue DevflowControlIO::InvalidControlPath => error
+    puts JSON.pretty_generate({ "ok" => false, "errors" => [{ "code" => "invalid_control_path", "message" => error.message }] })
+    exit 1
+  end
   validation = WorkflowStateValidator.validate(
     root: root,
     state_path: state_path,