@guanlin4924/devflow-pi 0.1.92 → 0.1.94

package/plugins/devflow-core/skills/workflow-orchestrator/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: workflow-orchestrator
-description: Use when the user asks to continue, resume, advance, inspect, or route a .planning-based workflow; when the OMP development agent must decide the next workflow skill from project state; or when a checkpoint must be handled before proceeding.
+description: Use when the user asks to continue, resume, advance, inspect, or route a .devflow/planning-based workflow; when the OMP development agent must decide the next workflow skill from project state; or when a checkpoint must be handled before proceeding.
 ---
 
 # Workflow Orchestrator
 
 ## Overview
 
-Control-plane entrypoint for project workflows. Reads `.planning/STATE.md`, `.planning/workflows/*.yaml`, and the artifact registry, decides the next action, and preserves checkpoint gates. Pipeline delegates here after parameter parsing and breakpoint detection.
+Control-plane entrypoint for project workflows. Reads `.devflow/planning/STATE.md`, `.devflow/planning/workflows/*.yaml`, and the artifact registry, decides the next action, and preserves checkpoint gates. Pipeline delegates here after parameter parsing and breakpoint detection.
 
 This skill is the **single source of truth for all execution-time rules**: gate rules, CP protocol, failure branches, parallel windows, state writeback, lessons injection, and requirement writeback. Pipeline only handles entry (args + breakpoint).
 
@@ -51,7 +51,7 @@ When `blocked` includes a `recovery` command, run or propose that command before
 
 `inspect_state.rb` runs `validate_state.rb` before dispatching normal actions. If validation fails, stop at `action: blocked` and fix the reported state/artifact inconsistency before continuing. Do not treat `status: completed` as authoritative unless `validate_state.rb --json` returns `ok: true`.
 
-When `run_project_context` is returned, do not initialize workflow state manually first. Execute `workflow-project-context` with the user's provided codebase locations and project-init arguments, verify it writes `.planning/PROJECT.md`, `.planning/navigation/INDEX.md`, `.context/spec/index.md`, and `.planning/STATE.md`, then run `inspect_state.rb --json` again and continue from the returned action.
+When `run_project_context` is returned, do not initialize workflow state manually first. Execute `workflow-project-context` with the user's provided codebase locations and project-init arguments, verify it writes `.devflow/planning/PROJECT.md`, `.devflow/planning/navigation/INDEX.md`, `.devflow/context/spec/index.md`, and `.devflow/planning/STATE.md`, then run `inspect_state.rb --json` again and continue from the returned action.
 
 ## Automatic Run Loop
 
@@ -63,7 +63,7 @@ When the invocation contains `<devflow-runtime-directive>`, run the workflow con
 4. Stop only when the inspector returns `await_user_confirmation`, `blocked`, or `workflow_complete`; also stop on an explicit user interruption or an unrecoverable tool failure.
 5. At `await_user_confirmation`, present the checkpoint and yield to the user. Resume the same loop only after an explicit confirmation and successful `devflow_transition`.
 
-Do not interpret “automatic” as permission to cross a checkpoint, weaken a gate, retry a stale revision without re-inspection, or continue after a blocked action. If context pressure requires a new turn, preserve project truth in `.planning`, finish required context synchronization, and use `/devflow resume` rather than inventing state from the conversation.
+Do not interpret “automatic” as permission to cross a checkpoint, weaken a gate, retry a stale revision without re-inspection, or continue after a blocked action. If context pressure requires a new turn, preserve project truth in `.devflow/planning`, finish required context synchronization, and use `/devflow resume` rather than inventing state from the conversation.
 
 ## Step Execution Protocol
 
@@ -105,7 +105,7 @@ When the inspector returns `await_user_confirmation`:
 5. Check artifact registry content_valid status for the listed outputs.
 6. Use `ask` to present the CP prompt, filling in the `summary_fields` from `.meta.json` data.
 7. If the user confirms, inspect the current revision and call `devflow_transition(action="confirm-checkpoint", expectedRevision=<revision>)`.
-8. If the user asks for fixes or rejects the checkpoint, keep `.planning/STATE.md` at `status: waiting_checkpoint`, inspect the current revision, call `devflow_transition(action="checkpoint-decision", decision="needs_fix", expectedRevision=<revision>)`, and route to the requested remediation.
+8. If the user asks for fixes or rejects the checkpoint, keep `.devflow/planning/STATE.md` at `status: waiting_checkpoint`, inspect the current revision, call `devflow_transition(action="checkpoint-decision", decision="needs_fix", expectedRevision=<revision>)`, and route to the requested remediation.
 
 CP skip rules:
 - CP-1, CP-API, CP-2, CP-3, CP-4: **never skip**.
@@ -137,7 +137,7 @@ If `hard_gate_mode` is `core`, a gate failure requires re-execution. In the curr
 
 When any later step discovers or introduces a change that alters external behavior, the requirement baseline must be updated first before downstream documents or code are modified.
 
-Must writeback to `.planning/requirements/baseline.md` when:
+Must writeback to `.devflow/planning/requirements/baseline.md` when:
 - New or changed user-visible behavior, notifications, failure handling, retry policy, scheduling, permissions, API contracts, or data write rules
 - Missing edge cases, compatibility requirements, historical impacts, or non-functional constraints found during execution
 - User adds/modifies requirements during tech-spec, change-plan, execution, or verification
@@ -194,7 +194,7 @@ devflow_transition(action="enter-failure-branch", expectedRevision=<revision>)
 Always obtain `<revision>` from a fresh `devflow_state(action="inspect")`. A stale
 revision is rejected without changing state, registry, or next-intent files.
 
-Checkpoint confirmation also writes the configured `.planning/.next-intent`.
+Checkpoint confirmation also writes the configured `.devflow/planning/.next-intent`.
 
 ## Control-plane recovery
 
@@ -253,19 +253,19 @@ The `.meta.json` data feeds CP prompts — e.g., CP-1 reads `baseline.meta.json`
 
 ## Initialization Rules
 
-This skill must be portable. Do not require manually-created `.planning` control files.
+This skill must be portable. Do not require manually-created `.devflow/planning` control files.
 
-If `.planning/STATE.md` is missing and project context files are also missing, route to `workflow-project-context` instead of asking for `init_state.rb`. If `.planning/STATE.md` is missing but project context files already exist, keep the existing `init_state.rb` recovery path.
+If `.devflow/planning/STATE.md` is missing and project context files are also missing, route to `workflow-project-context` instead of asking for `init_state.rb`. If `.devflow/planning/STATE.md` is missing but project context files already exist, keep the existing `init_state.rb` recovery path.
 
-If `.planning/STATE.md` contains blockers with `type: PENDING_TEMPLATE`, stop normal dispatch and report the missing depth spec template. The blocker must name the codebase, topic, matched path, missing template path, and impact.
+If `.devflow/planning/STATE.md` contains blockers with `type: PENDING_TEMPLATE`, stop normal dispatch and report the missing depth spec template. The blocker must name the codebase, topic, matched path, missing template path, and impact.
 
 Use these generators:
 
 | Script | Generates |
 |--------|-----------|
-| `init_workflow.rb` | `.planning/workflows/*.yaml` and workflow README from bundled templates. |
-| `init_state.rb` | `.planning/STATE.md` YAML front matter. |
-| `sync_artifacts.rb` | `.planning/artifacts/index.yaml` from active workflow outputs. |
+| `init_workflow.rb` | `.devflow/planning/workflows/*.yaml` and workflow README from bundled templates. |
+| `init_state.rb` | `.devflow/planning/STATE.md` YAML front matter. |
+| `sync_artifacts.rb` | `.devflow/planning/artifacts/index.yaml` from active workflow outputs. |
 
 The generated files may be project-specific instances, but their creation path must remain inside this skill.
 
@@ -273,26 +273,26 @@ The generated files may be project-specific instances, but their creation path m
 
 - Do not modify existing `workflow-*` skill behavior.
 - Auto-execute only the parallel window returned by the inspector while the runtime loop is active. Use task agents when isolation is safe; otherwise use `serial_fallback_order`.
-- Do not infer a missing workflow. If `.planning/STATE.md` has no machine-readable front matter, ask to initialize workflow state.
+- Do not infer a missing workflow. If `.devflow/planning/STATE.md` has no machine-readable front matter, ask to initialize workflow state.
 - Do not skip CP-1, CP-3, or CP-4. CP-2 can only be skipped if the active workflow config explicitly allows it.
-- Do not treat `.planning/pipeline-state.md` as the primary state source when YAML front matter exists in `.planning/STATE.md`.
+- Do not treat `.devflow/planning/pipeline-state.md` as the primary state source when YAML front matter exists in `.devflow/planning/STATE.md`.
 - Do not advance a step if its `meta_output` `.meta.json` is missing or incomplete.
 
 ## Files
 
 | File | Purpose |
 |------|---------|
-| `.planning/STATE.md` | Primary runtime state, YAML front matter + auto-generated Markdown body. |
-| `.planning/workflows/<current_flow>.yaml` | Active workflow config: step topology, CP definitions, meta_output contracts. |
+| `.devflow/planning/STATE.md` | Primary runtime state, YAML front matter + auto-generated Markdown body. |
+| `.devflow/planning/workflows/<current_flow>.yaml` | Active workflow config: step topology, CP definitions, meta_output contracts. |
 | `failure_branch.workflow_config` | Optional remediation workflow returned by the inspector. |
 | active workflow `artifact_registry.source` | Artifact status registry with content validation. |
 | `scripts/inspect_state.rb` | Deterministic state and next-action inspector. |
 | `scripts/init_workflow.rb` | Creates required workflow YAML files from bundled templates. |
-| `scripts/init_state.rb` | Creates or repairs `.planning/STATE.md` front matter. |
+| `scripts/init_state.rb` | Creates or repairs `.devflow/planning/STATE.md` front matter. |
 | `scripts/sync_artifacts.rb` | Generates artifact registry with content validation. |
 | `scripts/validate_state.rb` | Verifies STATE.md, workflow steps, dependencies, outputs, meta outputs, and artifact statuses agree before dispatch or writeback. |
 | `scripts/advance_state.rb` | State writeback + Markdown body auto-generation. |
 | `scripts/parallel_recover.rb` | Audited, CAS-guarded recovery and join for legacy lost parallel lifecycle events. |
-| `scripts/update_triage_route.rb` | Deterministically updates `.planning/requirements/{feature}/入口分诊.meta.json` route/status after clarify or wayfinder. |
+| `scripts/update_triage_route.rb` | Deterministically updates `.devflow/planning/requirements/{feature}/入口分诊.meta.json` route/status after clarify or wayfinder. |
 | `scripts/manage_lessons.rb` | Lesson candidate selector and evidence-based template writer. |
 | `templates/` | Portable workflow templates used by `init_workflow.rb`. |

package/plugins/devflow-core/skills/workflow-orchestrator/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Workflow Orchestrator"
-  short_description: "Route .planning workflows, checkpoints, remediation, and parallel windows"
-  default_prompt: "Inspect .planning/STATE.md and route the workflow safely"
+  short_description: "Route .devflow/planning workflows, checkpoints, remediation, and parallel windows"
+  default_prompt: "Inspect .devflow/planning/STATE.md and route the workflow safely"

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/acceptance_test_runner.py

@@ -134,9 +134,9 @@ def frozen_cases(suite: dict[str, Any], errors: list[str]) -> dict[str, dict[str
 
 def paths(root: Path, feature: str) -> tuple[Path, Path, Path]:
     return (
-        root / ".planning" / "requirements" / feature / "tests.json",
-        root / ".planning" / "features" / feature / "acceptance-test-bindings.json",
-        root / ".planning" / "test-runs" / feature / "acceptance-results.json",
+        root / ".devflow/planning" / "requirements" / feature / "tests.json",
+        root / ".devflow/planning" / "features" / feature / "acceptance-test-bindings.json",
+        root / ".devflow/planning" / "test-runs" / feature / "acceptance-results.json",
     )
 
 
@@ -339,8 +339,8 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
     cases = frozen_cases(suite, [])
     _, _, result_path = paths(root, feature)
     previous = read_json(result_path, [], "previous acceptance-test results")
-    task_bindings_path = root / ".planning" / "features" / feature / "test-bindings.json"
-    execution_bindings_path = root / ".planning" / "features" / feature / "acceptance-test-bindings.json"
+    task_bindings_path = root / ".devflow/planning" / "features" / feature / "test-bindings.json"
+    execution_bindings_path = root / ".devflow/planning" / "features" / feature / "acceptance-test-bindings.json"
     results: list[dict[str, Any]] = []
     for entry in bindings["cases"]:
         tc_id = entry["tc_id"]

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

@@ -59,7 +59,7 @@ OptionParser.new do |opts|
 end.parse!
 
 root = Dir.pwd
-state_path, = DevflowControlIO.resolve_control_path(root, options[:state] || ".planning/STATE.md", :state)
+state_path, = DevflowControlIO.resolve_control_path(root, options[:state] || ".devflow/planning/STATE.md", :state)
 
 def front_matter(markdown)
   match = markdown.match(/\A---\n(.*?)\n---\n/m)
@@ -71,7 +71,7 @@ def load_yaml_file(path)
 end
 
 def workflow_path_for(root, state)
-  state["workflow_config"] || File.join(".planning", "workflows", "#{state.fetch("current_flow")}.yaml")
+  state["workflow_config"] || File.join(".devflow/planning", "workflows", "#{state.fetch("current_flow")}.yaml")
 end
 
 def load_workflow(root, state)
@@ -384,7 +384,7 @@ def checkpoint_label(workflow, checkpoint_id)
 end
 
 def next_intent_path(root, workflow)
-  workflow.dig("resume_rules", "continue_keyword", "next_intent_path") || ".planning/.next-intent"
+  workflow.dig("resume_rules", "continue_keyword", "next_intent_path") || ".devflow/planning/.next-intent"
 end
 
 def write_next_intent(root, workflow)
@@ -635,16 +635,16 @@ end
 
 def business_cross_model_check(root, feature)
   script = File.join(__dir__, "business_cross_model_check.py")
-  business = ".planning/business-model/#{feature}/canonical.json"
-  wireframe = ".planning/features/#{feature}/canonical.json"
+  business = ".devflow/planning/business-model/#{feature}/canonical.json"
+  wireframe = ".devflow/planning/features/#{feature}/canonical.json"
   unless File.file?(File.join(root, business))
     return { "valid" => false, "errors" => [{ "code" => "BUSINESS_CANONICAL_MISSING", "path" => business }] }
   end
   command = ["python3", script, "--business-canonical", business]
   command += ["--wireframe", wireframe] if File.file?(File.join(root, wireframe))
-  claims = ".planning/features/#{feature}/business-claims.yaml"
+  claims = ".devflow/planning/features/#{feature}/business-claims.yaml"
   command += ["--claims", claims] if File.file?(File.join(root, claims))
-  traceability = ".planning/requirements/#{feature}/traceability.json"
+  traceability = ".devflow/planning/requirements/#{feature}/traceability.json"
   command += ["--traceability", traceability] if File.file?(File.join(root, traceability))
   stdout, stderr, status = Open3.capture3(*command, "--json", chdir: root)
   payload = JSON.parse(stdout)
@@ -675,7 +675,7 @@ rescue JSON::ParserError => error
 end
 
 def test_suite_freeze_attestation_path(root, feature)
-  DevflowControlIO.resolve_control_path(root, ".planning/features/#{feature}/test-suite-freeze.json", :artifact)
+  DevflowControlIO.resolve_control_path(root, ".devflow/planning/features/#{feature}/test-suite-freeze.json", :artifact)
 end
 
 def frozen_test_suite_pin(freeze_result)
@@ -1218,7 +1218,7 @@ result =
         prospective_owner = if changed
                               {
                                 "phase" => state["current_phase"], "feature" => state["current_feature"],
-                                "flow" => state["current_flow"], "state_path" => ".planning/STATE.md",
+                                "flow" => state["current_flow"], "state_path" => ".devflow/planning/STATE.md",
                                 "scope" => "global", "status" => "active"
                               }
                             end

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/api_test_matrix.py

@@ -72,8 +72,8 @@ def write_text(path: Path, value: str) -> None:
 
 
 def paths(root: Path, feature: str) -> tuple[Path, Path, Path, Path]:
-    requirements = root / ".planning" / "requirements" / feature
-    feature_dir = root / ".planning" / "features" / feature
+    requirements = root / ".devflow/planning" / "requirements" / feature
+    feature_dir = root / ".devflow/planning" / "features" / feature
     return (
         requirements / "governance.json",
         requirements / "api-test-matrix.json",

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

@@ -17,7 +17,7 @@ require_relative "runtime_context_collector"
 module ArchitectureAssessment
   SCHEMA_VERSION = 1
   RULE_VERSION = 1
-  ROOT_DIR = File.join(".planning", "architecture-assessment")
+  ROOT_DIR = File.join(".devflow/planning", "architecture-assessment")
 
   UNRESOLVED = {
     DELTA_SET_BINDING_FAILED: "DELTA_SET_BINDING_FAILED",

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

@@ -12,7 +12,7 @@ require_relative "architecture_feasibility"
 require_relative "control_io"
 
 module ArchitectureBrief
-  ROOT = ".planning/features"
+  ROOT = ".devflow/planning/features"
   SCHEMA_VERSION = 1
 
   module_function

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

@@ -27,7 +27,7 @@ module ArchitectureFeasibility
 
     pointer = JSON.parse(File.read(pointer_path))
     relative = pointer.fetch("path")
-    raise ArgumentError, "static runtime-context pointer path is invalid" unless relative.is_a?(String) && relative.start_with?(".context/static-runtime-context/revisions/")
+    raise ArgumentError, "static runtime-context pointer path is invalid" unless relative.is_a?(String) && relative.start_with?(".devflow/context/static-runtime-context/revisions/")
 
     absolute = File.expand_path(relative, root)
     root_real = File.realpath(root)

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

@@ -11,7 +11,7 @@ require "time"
 require "yaml"
 require_relative "control_io"
 
-options = { root: ".", feature: nil, canonical: nil, changed_source: [], registry: ".planning/artifacts/index.yaml", write: false, json: false }
+options = { root: ".", feature: nil, canonical: nil, changed_source: [], registry: ".devflow/planning/artifacts/index.yaml", write: false, json: false }
 OptionParser.new do |o|
   o.on("--root PATH") { |v| options[:root] = v }
   o.on("--feature NAME") { |v| options[:feature] = v }
@@ -42,7 +42,7 @@ lock = nil
 begin
   raise ArgumentError, "feature is required" if options[:feature].to_s.empty?
   raise ArgumentError, "at least one changed source is required" if options[:changed_source].empty?
-  canonical_path = options[:canonical] || ".planning/business-model/#{options[:feature]}/canonical.json"
+  canonical_path = options[:canonical] || ".devflow/planning/business-model/#{options[:feature]}/canonical.json"
   canonical_absolute, canonical_relative = DevflowControlIO.resolve_control_path(root, canonical_path, :artifact)
   model = read_json(canonical_absolute)
   changed = options[:changed_source].uniq
@@ -56,7 +56,7 @@ begin
     end
   end
   affected_ids = affected.map { |item| item["id"].to_s }.to_set
-  wireframe_relative = ".planning/features/#{options[:feature]}/canonical.json"
+  wireframe_relative = ".devflow/planning/features/#{options[:feature]}/canonical.json"
   wireframe_path, = DevflowControlIO.resolve_control_path(root, wireframe_relative, :artifact)
   consumers = []
   if File.file?(wireframe_path)
@@ -70,7 +70,7 @@ begin
   if options[:write]
     lock = DevflowControlIO.acquire_project_lock(root)
     timestamp = Time.now.utc.iso8601
-    approval_relative = ".planning/features/#{options[:feature]}/approval.json"
+    approval_relative = ".devflow/planning/features/#{options[:feature]}/approval.json"
     approval_path, = DevflowControlIO.resolve_control_path(root, approval_relative, :artifact)
     if !consumers.empty? && File.file?(approval_path)
       approval = read_json(approval_path)
@@ -93,7 +93,7 @@ begin
       DevflowControlIO.atomic_write(registry_path, registry.to_yaml.sub(/\A---\n/, ""))
       report["registry_path"] = registry_relative
     end
-    report_path = File.join(root, ".planning", "business-model", options[:feature], "invalidation.json")
+    report_path = File.join(root, ".devflow/planning", "business-model", options[:feature], "invalidation.json")
     DevflowControlIO.atomic_write(report_path, JSON.pretty_generate(report) + "\n")
     report["written"] = true
   else

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

@@ -43,7 +43,7 @@ module BusinessModelCommit
     raise ArgumentError, "invalid feature" unless valid_feature?(feature)
 
     root_real = File.realpath(root)
-    relative = File.join(".planning", "business-model", feature)
+    relative = File.join(".devflow/planning", "business-model", feature)
     absolute = File.expand_path(relative, root_real)
     raise ArgumentError, "business model path escapes project root" unless absolute.start_with?("#{root_real}#{File::SEPARATOR}")
 
@@ -67,7 +67,7 @@ module BusinessModelCommit
     raise ArgumentError, "proposal path contains control characters" if value.match?(/[\x00-\x1F\x7F]/)
 
     normalized = Pathname.new(value).cleanpath.to_s.tr("\\", "/")
-    prefix = File.join(".planning", "business-model", feature, "proposals").tr("\\", "/") + "/"
+    prefix = File.join(".devflow/planning", "business-model", feature, "proposals").tr("\\", "/") + "/"
     raise ArgumentError, "proposal path is outside the feature proposal directory" unless normalized.start_with?(prefix)
     absolute = File.expand_path(normalized, root_real)
     raise ArgumentError, "proposal path escapes project root" unless absolute.start_with?("#{root_real}#{File::SEPARATOR}")
@@ -255,7 +255,7 @@ module BusinessModelCommit
   def load_delta(root, feature, raw)
     raise ArgumentError, "candidate delta path is required" if raw.to_s.empty?
     path = File.expand_path(raw, root)
-    feature_root = File.expand_path(File.join(".planning", "business-model", feature, "candidates"), root)
+    feature_root = File.expand_path(File.join(".devflow/planning", "business-model", feature, "candidates"), root)
     raise ArgumentError, "candidate delta is missing" unless File.file?(path)
     path = File.realpath(path)
     feature_root = File.realpath(feature_root)
@@ -290,7 +290,7 @@ module BusinessModelCommit
   def source_registry_fingerprint(root, feature, aggregate)
     registry_ref = aggregate.dig("merged", "source_registry_ref").to_s
     return "" if registry_ref.empty?
-    path = if registry_ref.start_with?(".planning/")
+    path = if registry_ref.start_with?(".devflow/planning/")
              File.expand_path(registry_ref, root)
            else
              File.expand_path(registry_ref, feature_dir(root, feature))

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/business_model_validate.py

@@ -606,7 +606,7 @@ def load_json(path: Path) -> Any:
 
 
 def requirement_nodes(root: Path, feature: str, violations: list[dict[str, Any]]) -> set[str]:
-    requirements_root = (root / ".planning" / "requirements").resolve()
+    requirements_root = (root / ".devflow/planning" / "requirements").resolve()
     path = (requirements_root / feature / "governance.json").resolve()
     if not path.is_relative_to(requirements_root):
         add_violation(violations, "BUSINESS_REQUIREMENT_GRAPH_INVALID", feature, path=str(path), message="feature escapes requirements directory")

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

@@ -101,7 +101,7 @@ module BusinessSourceResolver
     output = command(root, "git", "status", "--porcelain=v1", "--untracked-files=all")
     lines = output.lines.map(&:rstrip).reject do |line|
       path = line.length > 3 ? line[3..].to_s.strip : ""
-      path.start_with?(".planning/", ".context/")
+      path.start_with?(".devflow/planning/", ".devflow/context/")
     end
     "sha256:#{Digest::SHA256.hexdigest(lines.join("\n"))}"
   end
@@ -237,7 +237,7 @@ module BusinessSourceResolver
     current_signature = worktree_signature(root)
     add(errors, "BUSINESS_WORKTREE_SIGNATURE_MISMATCH", "worktree signature is stale", source_id: id) unless source["worktree_signature"].to_s == current_signature
 
-    snapshot_path = File.join(root, ".planning", "code-index", "SNAPSHOT.json")
+    snapshot_path = File.join(root, ".devflow/planning", "code-index", "SNAPSHOT.json")
     unless File.file?(snapshot_path)
       add(errors, "BUSINESS_CODE_INDEX_STALE", "code index snapshot is missing", source_id: id, path: snapshot_path)
       return
@@ -258,7 +258,7 @@ module BusinessSourceResolver
     end
     return if symbol.empty?
 
-    symbols_path = File.join(root, ".planning", "code-index", "symbols.jsonl")
+    symbols_path = File.join(root, ".devflow/planning", "code-index", "symbols.jsonl")
     unless File.file?(symbols_path)
       add(errors, "BUSINESS_CODE_SYMBOL_NOT_FOUND", "symbols index is missing", source_id: id, path: symbols_path)
       return
@@ -318,7 +318,7 @@ module BusinessSourceResolver
     raise ArgumentError, "invalid feature" unless valid_feature?(feature)
     root = File.realpath(root)
     schema = load_yaml(REGISTRY_SCHEMA)
-    raw_registry = registry_path || File.join(".planning", "business-model", feature, "source-registry.yaml")
+    raw_registry = registry_path || File.join(".devflow/planning", "business-model", feature, "source-registry.yaml")
     registry_absolute, registry_relative = safe_path(root, raw_registry, "source registry")
     registry = load_yaml(registry_absolute)
     errors = []

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

@@ -60,22 +60,22 @@ module CheckerAdapter
     when "cross-track-consistency-check"
       ["ruby", File.join(scripts, "cross_track_consistency_check.rb"), "--feature", feature, "--json"]
     when "business-cross-model-check"
-      business = ".planning/business-model/#{feature}/canonical.json"
+      business = ".devflow/planning/business-model/#{feature}/canonical.json"
       return nil unless File.file?(File.join(root, business))
       command = ["python3", File.join(scripts, "business_cross_model_check.py"), "--business-canonical", business]
-      wireframe = ".planning/features/#{feature}/canonical.json"
-      claims = ".planning/features/#{feature}/business-claims.yaml"
-      traceability = ".planning/requirements/#{feature}/traceability.json"
+      wireframe = ".devflow/planning/features/#{feature}/canonical.json"
+      claims = ".devflow/planning/features/#{feature}/business-claims.yaml"
+      traceability = ".devflow/planning/requirements/#{feature}/traceability.json"
       command += ["--wireframe", wireframe] if File.file?(File.join(root, wireframe))
       command += ["--claims", claims] if File.file?(File.join(root, claims))
       command += ["--traceability", traceability] if File.file?(File.join(root, traceability))
       command + ["--json"]
     when "business-claim-reference-check"
-      claims = ".planning/features/#{feature}/business-claims.yaml"
-      business = ".planning/business-model/#{feature}/canonical.json"
+      claims = ".devflow/planning/features/#{feature}/business-claims.yaml"
+      business = ".devflow/planning/business-model/#{feature}/canonical.json"
       return nil unless File.file?(File.join(root, claims)) && File.file?(File.join(root, business))
       command = ["python3", File.join(scripts, "business_claim_validate.py"), "--claims", claims, "--business-canonical", business]
-      traceability = ".planning/requirements/#{feature}/traceability.json"
+      traceability = ".devflow/planning/requirements/#{feature}/traceability.json"
       command += ["--traceability", traceability] if File.file?(File.join(root, traceability))
       command
     end

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

@@ -5,6 +5,7 @@ require "fileutils"
 require "json"
 require "pathname"
 require "securerandom"
+require "time"
 
 # Shared durability primitives for every writer in the Devflow control plane.
 # The project lock serializes state, workflow, registry, and next-intent updates;
@@ -14,10 +15,52 @@ module DevflowControlIO
 
   module_function
 
+  def assert_layout_ready(root)
+    root_path = File.realpath(root)
+    legacy_planning = File.join(root_path, ".planning")
+    legacy_context = File.join(root_path, ".context")
+    planning_markers = %w[STATE.md PROJECT.md .devflow.lock navigation/INDEX.md code-index/INDEX.md workflows contracts evidence review-runs requirements features handoffs artifacts phase-ownership.yaml]
+    context_markers = %w[spec/index.md index.md project/index.md knowledge/index.md]
+    legacy_markers = planning_markers.map { |item| File.join(legacy_planning, item) } + context_markers.map { |item| File.join(legacy_context, item) }
+    return true unless legacy_markers.any? { |item| File.exist?(item) }
+
+    manifest = JSON.parse(File.read(File.join(root_path, ".devflow", "project.json")))
+    valid_manifest = manifest["schemaVersion"] == 1 &&
+      manifest["projectId"].to_s.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i) &&
+      !manifest["name"].to_s.strip.empty? &&
+      !Time.iso8601(manifest["createdAt"].to_s).nil? &&
+      [nil, 1, 2].include?(manifest["layoutVersion"])
+    raise InvalidControlPath, "DEVFLOW_LEGACY_LAYOUT_CONFIRMATION_REQUIRED: valid project manifest required" unless valid_manifest
+
+    marker = JSON.parse(File.read(File.join(root_path, ".devflow", "layout-migration.json"))) rescue nil
+    migration_complete = marker.is_a?(Hash) && marker["schemaVersion"] == 1 && marker["status"] == "complete" && marker["migrated"].is_a?(Array)
+    active = %w[STATE.md workflows contracts evidence review-runs requirements features handoffs artifacts phase-ownership.yaml].find do |item|
+      File.exist?(File.join(legacy_planning, item))
+    end
+    raise InvalidControlPath, "DEVFLOW_ACTIVE_LEGACY_LAYOUT: .planning/#{active} requires dedicated control-plane migration" if active && !migration_complete
+    canonical_exists = File.exist?(File.join(root_path, ".devflow", "planning")) || File.exist?(File.join(root_path, ".devflow", "context"))
+    if manifest["layoutVersion"] == 2 && !migration_complete
+      raise InvalidControlPath, "DEVFLOW_LEGACY_REINTRODUCTION: v2 project cannot import legacy layout"
+    end
+    if manifest["layoutVersion"] == 2 && migration_complete
+      planning_legacy = planning_markers.any? { |item| File.exist?(File.join(legacy_planning, item)) }
+      context_legacy = context_markers.any? { |item| File.exist?(File.join(legacy_context, item)) }
+      missing_canonical = (planning_legacy && !File.exist?(File.join(root_path, ".devflow", "planning"))) ||
+        (context_legacy && !File.exist?(File.join(root_path, ".devflow", "context")))
+      raise InvalidControlPath, "DEVFLOW_LEGACY_REINTRODUCTION: v2 project will not backfill a missing canonical directory" if missing_canonical
+    end
+    raise InvalidControlPath, "DEVFLOW_LAYOUT_CONFLICT: canonical and legacy layouts coexist without migration marker" if canonical_exists && !migration_complete
+    raise InvalidControlPath, "DEVFLOW_LAYOUT_MIGRATION_REQUIRED: run project initialization" unless canonical_exists
+    true
+  rescue Errno::ENOENT, JSON::ParserError, ArgumentError
+    raise InvalidControlPath, "DEVFLOW_LEGACY_LAYOUT_CONFIRMATION_REQUIRED: valid project manifest required"
+  end
+
   # 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)
+    assert_layout_ready(root)
     root_path = File.realpath(root)
     value = raw.to_s
     raise InvalidControlPath, "#{kind} path is required" if value.empty?
@@ -27,14 +70,14 @@ module DevflowControlIO
     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/")
+              when :state then normalized == ".devflow/planning/STATE.md"
+              when :workflow then normalized.match?(%r{\A\.devflow/planning/workflows/[A-Za-z0-9][A-Za-z0-9_-]*\.yaml\z})
+              when :registry then normalized == ".devflow/planning/artifacts/index.yaml"
+              when :artifact then normalized.start_with?(".devflow/planning/") || normalized.start_with?(".devflow/context/")
               # Feature names are user-facing and may be Unicode. `cleanpath`
               # and the parent-traversal check above own containment; this
               # matcher only fixes the handoff namespace and immutable name.
-              when :handoff then normalized.match?(%r{\A\.planning/handoffs/[^/]+/ROL-[0-9a-f-]+\.json\z})
+              when :handoff then normalized.match?(%r{\A\.devflow/planning/handoffs/[^/]+/ROL-[0-9a-f-]+\.json\z})
               else false
               end
     raise InvalidControlPath, "invalid #{kind} control path" unless allowed
@@ -58,7 +101,8 @@ module DevflowControlIO
   end
 
   def acquire_project_lock(root)
-    planning_dir = File.join(root, ".planning")
+    assert_layout_ready(root)
+    planning_dir = File.join(root, ".devflow/planning")
     FileUtils.mkdir_p(planning_dir)
     handle = File.open(File.join(planning_dir, ".devflow.lock"), File::RDWR | File::CREAT, 0o644)
     handle.flock(File::LOCK_EX)
@@ -122,7 +166,7 @@ module DevflowControlIO
   # 独立受控工件登记：与 sync_artifacts 的 workflow-outputs registry 分开，
   # 避免被 workflow 重建覆盖。按 path 去重，last-write-wins。
   def register_control_artifact(root, entry)
-    path = File.join(root, ".planning", "artifacts", "control-artifacts.json")
+    path = File.join(root, ".devflow/planning", "artifacts", "control-artifacts.json")
     existing = File.exist?(path) ? JSON.parse(File.read(path)) : { "schema_version" => 1, "artifacts" => [] }
     existing["artifacts"] ||= []
     existing["artifacts"].reject! { |item| item["path"] == entry["path"] }

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

@@ -16,7 +16,7 @@ feature = options[:feature].to_s
 raise ArgumentError, "feature contains path separators" if feature.include?("/") || feature.include?("\\")
 
 root = Dir.pwd
-base = File.join(root, ".planning", "features", feature)
+base = File.join(root, ".devflow/planning", "features", feature)
 files = {
   "api_contract" => File.join(base, "api-contract.md"),
   "api_call_guide" => File.join(base, "api-call-guide.md"),

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

@@ -43,7 +43,7 @@ OptionParser.new do |o|
 end.parse!
 
 def load_state(root)
-  document = File.read(File.join(root, ".planning/STATE.md"))
+  document = File.read(File.join(root, ".devflow/planning/STATE.md"))
   front = document.match(/\A---\n(.*?)\n---/m)&.[](1)
   raise "STATE.md has no YAML front matter" unless front
   YAML.safe_load(front, permitted_classes: [], aliases: false)
@@ -57,7 +57,7 @@ def render_execution_contract_markdown(contract)
   lines = [
     "# Execution Contract",
     "",
-    "> Core-generated derived view. The immutable contract JSON under `.planning/contracts/` is authoritative.",
+    "> Core-generated derived view. The immutable contract JSON under `.devflow/planning/contracts/` is authoritative.",
     "",
     "- Contract ID: `#{contract.fetch("contract_id")}`",
     "- Feature: `#{contract.fetch("feature")}`",
@@ -106,7 +106,7 @@ begin
   # omitting production_paths strands implementation workers in a contract
   # that can write summaries but never code.
   if options[:step] == "execute"
-    binding_path = File.join(root, ".planning/features", options[:feature], "test-bindings.json")
+    binding_path = File.join(root, ".devflow/planning/features", options[:feature], "test-bindings.json")
     if File.file?(binding_path)
       bindings = JSON.parse(File.read(binding_path))
       Array(bindings["tasks"]).each do |task|
@@ -142,10 +142,10 @@ begin
     result = { "ok" => true, "contract" => frozen }
   else
     raise ArgumentError, "--write is required" unless options[:write]
-    destination = File.join(root, ".planning/contracts", options[:feature], "#{contract_id}.json")
+    destination = File.join(root, ".devflow/planning/contracts", options[:feature], "#{contract_id}.json")
     DevflowControlIO.atomic_write(destination, JSON.pretty_generate(frozen) + "\n")
-    DevflowControlIO.atomic_write(File.join(root, ".planning/execution-contract.md"), render_execution_contract_markdown(frozen) + "\n")
-    audit = File.join(root, ".planning/contracts", options[:feature], "control-events.jsonl")
+    DevflowControlIO.atomic_write(File.join(root, ".devflow/planning/execution-contract.md"), render_execution_contract_markdown(frozen) + "\n")
+    audit = File.join(root, ".devflow/planning/contracts", options[:feature], "control-events.jsonl")
     existing = File.exist?(audit) ? File.read(audit) : ""
     DevflowControlIO.atomic_write(audit, existing + JSON.generate({ "event" => "execution_contract_frozen", "contract_id" => contract_id, "state_revision" => state["revision"], "graph_revision" => graph["revision"], "frozen_hash" => frozen["frozen_hash"] }) + "\n")
     result = { "ok" => true, "path" => destination.sub("#{root}/", ""), "contract" => frozen }

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

@@ -87,7 +87,7 @@ module GateRuntime
           invalid_outputs = validate_declared_inputs(contract.dig("outputs", "required_inputs"), root, workflow_state, purpose: :completion)
           return GateResult.block(**base, code: "REQUIRED_OUTPUT_INVALID", message: "required step input/output fact is invalid", details: { "invalid" => invalid_outputs }) unless invalid_outputs.empty?
           if step_id == "code-review"
-            contract_view = File.join(root, ".planning/execution-contract.md")
+            contract_view = File.join(root, ".devflow/planning/execution-contract.md")
             contract_id = if File.file?(contract_view) && !File.symlink?(contract_view)
                             File.read(contract_view).match(/^- Contract ID: `(EC-[0-9a-f]{16})`$/)&.[](1)
                           end
@@ -234,9 +234,9 @@ module GateRuntime
         case validation
         when "static-runtime-context"
           pointer_path = payload.fetch("path")
-          raise "invalid pointer path" unless pointer_path.start_with?(".context/static-runtime-context/revisions/")
+          raise "invalid pointer path" unless pointer_path.start_with?(".devflow/context/static-runtime-context/revisions/")
           root_real = File.realpath(root)
-          revisions_root = File.realpath(File.join(root, ".context/static-runtime-context/revisions"))
+          revisions_root = File.realpath(File.join(root, ".devflow/context/static-runtime-context/revisions"))
           snapshot_real = File.realpath(File.expand_path(pointer_path, root))
           raise "snapshot path escapes project root" unless snapshot_real.start_with?("#{root_real}#{File::SEPARATOR}")
           raise "snapshot path escapes revisions directory" unless snapshot_real.start_with?("#{revisions_root}#{File::SEPARATOR}")