@guanlin4924/devflow-pi 0.1.93 → 0.1.95

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

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Read-only access to Core approval records in control.db (变更清单 §1.8).
+
+Approvals are written only by the Runtime extension's UI confirmation path.
+This module never writes: it opens control.db with mode=ro and re-derives
+validity by recomputing the current pins with approval_pins.compute (the single
+pin implementation shared with the proposal/confirm side) and comparing them
+with the stored pins_json.  The
+file-compatibility authority has no approval channel, so every lookup there
+fails with approval_requires_database_authority.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from tc_hash import canonicalize
+
+
+APPROVAL_KINDS = frozenset({"execution_plan", "environment_profile", "mode_override", "human_result"})
+REQUIRES_DATABASE = "approval_requires_database_authority"
+
+
+def _project_id(root: Path) -> str | None:
+    try:
+        value = json.loads((root / ".devflow" / "project.json").read_text(encoding="utf-8"))["projectId"]
+        return value if isinstance(value, str) and value else None
+    except (OSError, KeyError, TypeError, ValueError):
+        return None
+
+
+def devflow_home() -> Path:
+    """DEVFLOW_HOME rule shared with the TS writer (src/paths.ts normalizeDevflowHome) and hook_common.
+
+    Unset, empty or whitespace-only means unset -> ~/.devflow-pi. Otherwise only a leading '~' or '~/'
+    is expanded (never '~user'), then the path is made absolute with os.path.abspath (existence is not required).
+    """
+    value = os.environ.get("DEVFLOW_HOME")
+    value = "~/.devflow-pi" if value is None or not value.strip() else value.strip()
+    if value == "~" or value.startswith("~/"):
+        value = str(Path.home()) + value[1:]
+    return Path(os.path.abspath(value))
+
+
+def _connect(root: Path) -> tuple[sqlite3.Connection | None, str | None]:
+    project_id = _project_id(root)
+    if project_id is None:
+        return None, None
+    database = devflow_home() / "projects" / project_id / "control.db"
+    if not database.is_file():
+        return None, project_id
+    # Path.as_uri() percent-quotes '?', '#', '%' etc., so they cannot be read as URI syntax.
+    connection = sqlite3.connect(f"{database.as_uri()}?mode=ro", uri=True)
+    connection.row_factory = sqlite3.Row
+    return connection, project_id
+
+
+def _same(left: Any, right: Any) -> bool:
+    try:
+        return canonicalize(left) == canonicalize(right)
+    except ValueError:
+        return False
+
+
+def latest_approval(root: Path, feature: str, kind: str, subject_key: str) -> dict[str, Any]:
+    """The newest non-superseded approval for (feature, kind, subject_key), without validity checks."""
+    if kind not in APPROVAL_KINDS:
+        return {"ok": False, "reason": "approval_invalid", "message": f"unknown approval kind: {kind}"}
+    try:
+        connection, project_id = _connect(root)
+        if connection is None:
+            return {"ok": False, "reason": REQUIRES_DATABASE, "message": "approvals require the database control-plane authority"}
+        try:
+            authority = connection.execute("SELECT authority FROM authority_state WHERE project_id=?", (project_id,)).fetchone()
+            if not authority or authority["authority"] != "database":
+                return {"ok": False, "reason": REQUIRES_DATABASE, "message": "approvals require the database control-plane authority"}
+            row = connection.execute(
+                """SELECT a.id, a.proposal_id, a.pins_json, a.decision_json, a.approved_via, a.approved_at, p.status AS proposal_status, p.payload_json,
+                          p.kind AS proposal_kind, p.subject_key AS proposal_subject, p.feature AS proposal_feature, p.project_id AS proposal_project
+                   FROM approvals a JOIN approval_proposals p ON p.id=a.proposal_id
+                   WHERE a.project_id=? AND a.feature=? AND a.kind=? AND a.subject_key=? AND a.superseded_at IS NULL
+                   ORDER BY a.approved_at DESC, a.rowid DESC LIMIT 1""",
+                (project_id, feature, kind, subject_key),
+            ).fetchone()
+        finally:
+            connection.close()
+    except sqlite3.Error as error:
+        return {"ok": False, "reason": "approval_invalid", "message": f"approval store is unreadable: {error}"}
+    if row is None:
+        return {"ok": False, "reason": "approval_missing", "message": f"no {kind} approval for {subject_key}"}
+    if (row["approved_via"] != "runtime_ui_confirm" or row["proposal_status"] != "consumed" or row["proposal_kind"] != kind
+            or row["proposal_subject"] != subject_key or row["proposal_feature"] != feature or row["proposal_project"] != project_id):
+        return {"ok": False, "reason": "approval_invalid", "message": "approval record is not bound to a consumed UI-confirmed proposal"}
+    try:
+        pins = json.loads(row["pins_json"])
+        decision = json.loads(row["decision_json"])
+        payload = json.loads(row["payload_json"] or "{}")
+    except (TypeError, json.JSONDecodeError):
+        return {"ok": False, "reason": "approval_invalid", "message": "approval record JSON is malformed"}
+    if not isinstance(pins, dict) or not isinstance(decision, dict) or not isinstance(payload, dict):
+        return {"ok": False, "reason": "approval_invalid", "message": "approval pins, decision and payload must be objects"}
+    request = payload.get("request", {})
+    return {"ok": True, "reason": None, "approval": {"id": row["id"], "proposal_id": row["proposal_id"], "kind": kind, "subject_key": subject_key,
+                                                      "pins": pins, "decision": decision, "request": request if isinstance(request, dict) else {},
+                                                      "approved_at": row["approved_at"]}}
+
+
+def valid_approval(root: Path, feature: str, kind: str, subject_key: str, current_pins: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Return {"ok", "reason", "message", "approval"}.
+
+    Valid only when the newest non-superseded approval's pins equal the pins
+    approval_pins.compute derives now from the proposal request; any key given
+    in ``current_pins`` (e.g. the hash of the DSL the binding actually names)
+    must additionally equal the stored pin.
+    """
+    found = latest_approval(root, feature, kind, subject_key)
+    if not found["ok"]:
+        return {**found, "approval": None}
+    approval = found["approval"]
+    try:
+        from approval_pins import compute
+    except ImportError as error:
+        return {"ok": False, "reason": "approval_invalid", "message": f"approval_pins is unavailable: {error}", "approval": None}
+    computed = compute(root, feature, kind, subject_key, approval["request"])
+    if not computed.get("ok"):
+        return {"ok": False, "reason": "approval_stale", "message": "current pins cannot be computed: " + "; ".join(map(str, computed.get("errors", []))), "approval": None}
+    expected = dict(computed["pins"])
+    for key, value in (current_pins or {}).items():
+        if not _same(expected.get(key), value):
+            return {"ok": False, "reason": "approval_stale", "message": f"approval does not cover the current {key}", "approval": None}
+    if not _same(approval["pins"], expected):
+        changed = sorted(key for key in set(approval["pins"]) | set(expected) if not _same(approval["pins"].get(key), expected.get(key)))
+        return {"ok": False, "reason": "approval_stale", "message": f"approval pins no longer match: {', '.join(changed)}", "approval": None}
+    return {"ok": True, "reason": None, "message": None, "approval": approval}

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Structural coverage of a frozen TC by its v1 DSL (方案 §6.1, first layer).
+
+Every frozen precondition and step must be covered by at least one DSL step;
+the oracle must be covered by at least one non-weak assertion.  This only
+detects omissions and obviously weak assertions; semantic adequacy remains the
+job of the human-approved execution plan.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from dsl_v1 import UI_ASSERTIONS, UI_INTERACTIONS, all_steps
+
+
+def is_assertion(step: dict[str, Any]) -> bool:
+    if step.get("driver") == "ui":
+        return step.get("action") in UI_ASSERTIONS
+    return step.get("driver") == "api" and (bool(step.get("assertions")) or "expect_status" in step)
+
+
+def weak_reason(step: dict[str, Any], preceding: list[dict[str, Any]]) -> str | None:
+    """MVP weak assertions: assert_visible of a static entry element; 2xx-only API checks."""
+    if step.get("driver") == "api":
+        status = step.get("expect_status")
+        if not step.get("assertions") and (status is None or 200 <= status <= 299):
+            return "API assertion only checks a 2xx status without response body assertions"
+        return None
+    if step.get("action") != "assert_visible":
+        return None
+    interactions = [item for item in preceding if (item.get("driver") == "ui" and item.get("action") in UI_INTERACTIONS)
+                    or (item.get("driver") == "api" and item.get("method") != "GET")]
+    if not interactions:
+        return "assert_visible before any interaction only proves a static entry element is present"
+    if any(item.get("target") == step.get("target") for item in interactions):
+        return "assert_visible on an element the flow itself interacted with does not verify an outcome"
+    return None
+
+
+def _count(data: dict[str, Any], key: str) -> int:
+    value = data.get(key)
+    if isinstance(value, list):
+        return len(value)
+    return 1 if isinstance(value, str) and value.strip() else 0
+
+
+def check(tc_data: dict[str, Any], dsl: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    counts = {"preconditions": _count(tc_data, "preconditions"), "steps": _count(tc_data, "steps")}
+    covered: dict[str, set[int]] = {"preconditions": set(), "steps": set()}
+    oracle = tc_data.get("oracle")
+    has_oracle = (isinstance(oracle, str) and bool(oracle.strip())) or (isinstance(oracle, list) and bool(oracle))
+    oracle_assertions: list[tuple[str, dict[str, Any], str | None]] = []
+    main: list[dict[str, Any]] = []
+    for phase, path, step in all_steps(dsl):
+        covers = step.get("covers") if isinstance(step.get("covers"), dict) else {}
+        if phase == "cleanup" and covers:
+            errors.append(f"{path}.covers is not allowed on cleanup steps")
+            continue
+        for key in ("preconditions", "steps"):
+            for index in covers.get(key, []):
+                if not isinstance(index, int) or isinstance(index, bool) or not 1 <= index <= counts[key]:
+                    errors.append(f"{path}.covers.{key} index {index} is outside the frozen TC {key} (1..{counts[key]})")
+                else:
+                    covered[key].add(index)
+        if covers.get("oracle") is True:
+            if not is_assertion(step):
+                errors.append(f"{path} covers the oracle but {step.get('action')} is not an assertion")
+            elif phase != "main":
+                errors.append(f"{path} covers the oracle outside the main steps")
+            else:
+                oracle_assertions.append((path, step, weak_reason(step, main)))
+        if phase == "main":
+            main.append(step)
+    for key in ("preconditions", "steps"):
+        missing = sorted(set(range(1, counts[key] + 1)) - covered[key])
+        if missing:
+            errors.append(f"frozen TC {key} not covered by any DSL step: {', '.join(map(str, missing))}")
+    if has_oracle and not oracle_assertions:
+        errors.append("frozen TC oracle is not covered by any assertion step")
+    elif oracle_assertions and all(reason for _path, _step, reason in oracle_assertions):
+        errors.extend(f"{path}: weak oracle assertion ({reason})" for path, _step, reason in oracle_assertions)
+        errors.append("frozen TC oracle is covered only by weak assertions")
+    if tc_data.get("execution_surface") == "ui" or (tc_data.get("execution_surface") is None and tc_data.get("test_type") == "page"):
+        if oracle_assertions and not any(step.get("driver") == "ui" and not reason for _path, step, reason in oracle_assertions):
+            errors.append("UI TC oracle must be covered by a non-weak page assertion; API checks cannot replace it")
+    return errors