@guanlin4924/devflow-pi 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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/SKILL.md

@@ -115,14 +115,14 @@ After each step completes, verify the step's gate before advancing:
 | requirement-wayfinder | 决策地图.meta.json `status=ready_for_baseline` AND `ready_for_baseline=true` | Reject advance to domain-modeling |
 | domain-modeling | 领域模型记录及 meta 存在且标识当前功能 | Reject advance to requirement-feasibility-review |
 | requirement-feasibility-review | 可实现性审查.meta.json `status=ready_for_baseline`、`baseline_gate=pass`、`gap_count=0` 且无 critical finding | Reject advance to requirement-baseline |
-| requirement-baseline | baseline.md review conclusion is "通过" AND baseline.meta.json `review_status` is `passed` AND blocking counters are all 0 | Reject advance to api-contract |
-| api-contract | api-contract.meta.json `review_status` is `passed` AND `pending_contract_count` is 0 | Reject advance to dual tracks |
+| requirement-baseline | baseline.md review conclusion is "通过" AND baseline.meta.json `review_status` / `traceability_status` are `passed` AND blocking counters are all 0 | Reject advance to api-contract |
+| api-contract | api-contract.meta.json `review_status` / `traceability_status` are `passed` AND `pending_contract_count` is 0 | Reject advance to dual tracks |
 | ui-spec | UI-SPEC.md review conclusion is "通过" | Reject advance to feature-breakdown |
 | feature-breakdown | 功能点梳理.md review conclusion is "通过" | Reject advance to tech-specs |
 | api-call-guide | api-call-guide.meta.json `frontend_consumable` and `mock_ready` are true, pending_items is empty | Reject merge gate |
 | frontend-tech-spec + backend-tech-spec | Both review conclusions are "通过" | Reject integration-verify |
-| integration-verify | integration-report.meta.json `merge_gate_status` is `passed` and all mismatch/blocking counters are 0 | Reject advance to change-plan |
-| change-plan | 变更清单.md review conclusion is "通过" | Reject advance to execute |
+| integration-verify | integration-report.meta.json `merge_gate_status` / `traceability_status` are `passed` and all mismatch/blocking counters are 0 | Reject advance to change-plan |
+| change-plan | 变更清单.md review conclusion is "通过" AND 变更清单.meta.json traceability_status is `passed` with zero uncovered/orphan counts | Reject advance to execute |
 
 If a gate fails, the current step must be re-executed. Do not skip failing gates.
 

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