@guanlin4924/devflow-pi 0.1.13 → 0.1.15

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/traceability_check.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Fail-closed requirement-to-delivery traceability validation."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+STAGES = ("baseline", "design", "change-plan", "verify")
+DIMENSIONS = ("input", "output", "behavior", "orchestration", "failure", "verification")
+
+
+def fail(errors: list[str], message: str) -> None:
+    errors.append(message)
+
+
+def references(items: object) -> set[str]:
+    if not isinstance(items, list):
+        return set()
+    result = set()
+    for item in items:
+        if isinstance(item, str):
+            result.add(item)
+        elif isinstance(item, dict) and isinstance(item.get("id"), str):
+            result.add(item["id"])
+    return result
+
+
+def check(data: dict, stage: str) -> list[str]:
+    errors: list[str] = []
+    requirements = data.get("requirements")
+    if data.get("schema_version") != 1:
+        fail(errors, "schema_version must be 1")
+    if not isinstance(data.get("feature"), str) or not data["feature"].strip():
+        fail(errors, "feature is required")
+    if not isinstance(requirements, list) or not requirements:
+        return errors + ["requirements must be a non-empty array"]
+
+    active: set[str] = set()
+    known: set[str] = set()
+    for req in requirements:
+        if not isinstance(req, dict):
+            fail(errors, "every requirement must be an object")
+            continue
+        rid = req.get("id")
+        if not isinstance(rid, str) or not rid.startswith("REQ-"):
+            fail(errors, f"invalid requirement id: {rid!r}")
+            continue
+        known.add(rid)
+        if req.get("status", "confirmed") in {"confirmed", "approved"} and req.get("scope", "in") == "in":
+            active.add(rid)
+        dimensions = req.get("dimensions")
+        if not isinstance(dimensions, dict):
+            fail(errors, f"{rid}: dimensions is required")
+        else:
+            missing = [d for d in DIMENSIONS if not isinstance(dimensions.get(d), str) or not dimensions[d].strip()]
+            if missing:
+                fail(errors, f"{rid}: missing dimensions: {', '.join(missing)}")
+
+    if stage == "baseline":
+        return errors
+
+    designs = data.get("designs")
+    if not isinstance(designs, list) or not designs:
+        fail(errors, "designs must be a non-empty array after baseline")
+    covered_by_design = set()
+    for item in designs or []:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            fail(errors, "every design needs an id")
+            continue
+        refs = references(item.get("requirements"))
+        unknown = refs - known
+        if unknown:
+            fail(errors, f"{item['id']}: references unknown requirements: {', '.join(sorted(unknown))}")
+        covered_by_design |= refs
+        if item.get("kind") == "api":
+            contract = item.get("contract")
+            if not isinstance(contract, dict) or any(not contract.get(k) for k in ("request", "response", "errors", "behavior")):
+                fail(errors, f"{item['id']}: API design must include request, response, errors and behavior")
+    missing = active - covered_by_design
+    if missing:
+        fail(errors, "requirements missing design coverage: " + ", ".join(sorted(missing)))
+    if stage == "design":
+        return errors
+
+    tasks = data.get("tasks")
+    if not isinstance(tasks, list) or not tasks:
+        fail(errors, "tasks must be a non-empty array after design")
+    covered_by_task = set()
+    for task in tasks or []:
+        if not isinstance(task, dict) or not isinstance(task.get("id"), str):
+            fail(errors, "every task needs an id")
+            continue
+        refs = task.get("requirements")
+        if not isinstance(refs, list) or not refs:
+            fail(errors, f"{task['id']}: requirements is required")
+        else:
+            covered_by_task.update(refs)
+            unknown = set(refs) - known
+            if unknown:
+                fail(errors, f"{task['id']}: references unknown requirements: {', '.join(sorted(unknown))}")
+        criteria = task.get("acceptance")
+        if not isinstance(criteria, dict):
+            fail(errors, f"{task['id']}: acceptance is required")
+        else:
+            missing = [d for d in DIMENSIONS if not isinstance(criteria.get(d), str) or not criteria[d].strip()]
+            if missing:
+                fail(errors, f"{task['id']}: missing acceptance dimensions: {', '.join(missing)}")
+    missing = active - covered_by_task
+    if missing:
+        fail(errors, "requirements missing task coverage: " + ", ".join(sorted(missing)))
+    if stage == "change-plan":
+        return errors
+
+    verification = data.get("verification")
+    if not isinstance(verification, list) or not verification:
+        fail(errors, "verification must be a non-empty array after change-plan")
+    covered_by_verification = set()
+    for item in verification or []:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            fail(errors, "every verification item needs an id")
+            continue
+        refs = item.get("requirements")
+        if not isinstance(refs, list) or not refs:
+            fail(errors, f"{item['id']}: requirements is required")
+        else:
+            covered_by_verification.update(refs)
+            unknown = set(refs) - known
+            if unknown:
+                fail(errors, f"{item['id']}: references unknown requirements: {', '.join(sorted(unknown))}")
+        if not isinstance(item.get("evidence"), str) or not item["evidence"].strip():
+            fail(errors, f"{item['id']}: evidence is required")
+    missing = active - covered_by_verification
+    if missing:
+        fail(errors, "requirements missing verification coverage: " + ", ".join(sorted(missing)))
+    return errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--file", required=True)
+    parser.add_argument("--stage", choices=STAGES, required=True)
+    args = parser.parse_args()
+    try:
+        data = json.loads(Path(args.file).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"TRACEABILITY_FAIL: cannot read manifest: {exc}", file=sys.stderr)
+        return 2
+    if not isinstance(data, dict):
+        print("TRACEABILITY_FAIL: manifest root must be an object", file=sys.stderr)
+        return 2
+    errors = check(data, args.stage)
+    result = {"status": "passed" if not errors else "failed", "stage": args.stage, "errors": errors}
+    print(json.dumps(result, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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
@@ -304,6 +324,7 @@ module WorkflowStateValidator
     validate_frontend_tech_spec_gate(issues, step, data)
     validate_api_supplement_gate(issues, step, data)
     validate_integration_merge_gate(issues, step, data)
+    validate_change_plan_gate(issues, step, data)
     validate_verification_gate(issues, step, data)
   rescue JSON::ParserError => e
     issues << issue("error", "invalid_meta_json", e.message, step: step["id"], path: path)
@@ -403,6 +424,10 @@ module WorkflowStateValidator
 
       issues << issue("error", "baseline_blocking_counter_nonzero", "Requirement baseline has a non-zero blocking counter", step: step["id"], field: field, count: data[field])
     end
+
+    if data["traceability_status"] != "passed"
+      issues << issue("error", "baseline_traceability_not_passed", "Requirement traceability must pass before technical design", step: step["id"], status: data["traceability_status"])
+    end
   end
 
   def validate_api_contract_gate(issues, step, data)
@@ -416,6 +441,10 @@ module WorkflowStateValidator
       issues << issue("error", "api_contract_pending_items", "API contract has unresolved pending contract items", step: step["id"], count: data["pending_contract_count"])
     end
 
+    if data["traceability_status"] != "passed"
+      issues << issue("error", "api_contract_traceability_not_passed", "API contract must retain complete requirement traceability", step: step["id"], status: data["traceability_status"])
+    end
+
     api_required = data["api_required"]
     endpoint_count = data["endpoint_count"].to_i
     if api_required == false && endpoint_count.positive?
@@ -495,6 +524,10 @@ module WorkflowStateValidator
       issues << issue("error", "merge_gate_not_passed", "Integration merge gate status is not passed", step: step["id"], status: data["merge_gate_status"])
     end
 
+    if data["traceability_status"] != "passed"
+      issues << issue("error", "integration_traceability_not_passed", "Integration gate requires complete requirement-to-design traceability", step: step["id"], status: data["traceability_status"])
+    end
+
     %w[
       contract_backend_mismatch_count
       contract_frontend_mismatch_count
@@ -507,6 +540,20 @@ module WorkflowStateValidator
     end
   end
 
+  def validate_change_plan_gate(issues, step, data)
+    return unless step["id"] == "change-plan"
+
+    if data["traceability_status"] != "passed"
+      issues << issue("error", "change_plan_traceability_not_passed", "Change plan requires complete requirement-to-task traceability", step: step["id"], status: data["traceability_status"])
+    end
+
+    %w[uncovered_requirement_count orphan_task_count].each do |field|
+      next if data[field].to_i.zero?
+
+      issues << issue("error", "change_plan_traceability_counter_nonzero", "Change plan has unresolved traceability coverage", step: step["id"], field: field, count: data[field])
+    end
+  end
+
   def validate_verification_gate(issues, step, data)
     return unless step["id"] == "verify"
 
@@ -589,7 +636,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,