@guanlin4924/devflow-pi 0.1.0 → 0.1.4

package/README.md

@@ -27,6 +27,7 @@ devflow-pi
 /devflow doctor
 /devflow project-init
 /devflow explain-state
+/devflow recover
 /devflow start <feature>|<phase>
 /devflow continue
 /devflow advance
@@ -114,7 +115,7 @@ bash .skills/install.sh --apply --force-config
 
 首次使用时，在 OMP 的模型角色界面中分别为 `smol`、`task`、`slow` 选择具体模型；`modelRoleStorage: project` 会把选择保存在项目作用域。建议分别使用快速探索模型、代码实现模型和独立推理/审查模型。配置完成后以 `/devflow doctor` 的 `models:` 行为准。
 
-`/devflow start` 只创建 Feature 状态，不会自动启动整条流程。`/devflow continue` 只运行当前一个工作流步骤并停止；产物审查后由用户显式执行 `/devflow advance`，checkpoint 也必须由用户通过 `/devflow checkpoint` 确认。恢复已有流程使用 `/devflow resume`，它同样只恢复状态而不自动执行。普通中文输入“初始化项目”“查看状态”“需求：……”会进入相应的受控只读分诊，不会偷偷启动实现或状态迁移。
+`/devflow start` 只创建 Feature 状态，不会自动启动整条流程。`/devflow continue` 只运行当前一个工作流步骤并停止；产物审查后由用户显式执行 `/devflow advance`，checkpoint 也必须由用户通过 `/devflow checkpoint` 确认。`/devflow explain-state` 发现控制面和制品 registry 漂移时会给出只读恢复计划；用户审查后可用 `/devflow recover` 确认仅修复可由文件系统证明的 registry 字段，它绝不推进步骤或自动通过 checkpoint。恢复已有流程使用 `/devflow resume`，它同样只恢复状态而不自动执行。普通中文输入“初始化项目”“查看状态”“需求：……”会进入相应的受控只读分诊，不会偷偷启动实现或状态迁移。
 
 ## Marketplace 能力包
 

package/bin/devflow-pi

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+
+import "../src/cli.ts";

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",
   "bin": {
-    "devflow-pi": "./src/cli.ts"
+    "devflow-pi": "bin/devflow-pi"
   },
   "scripts": {
     "dev": "bun run src/cli.ts",
@@ -25,6 +25,7 @@
     "typescript": "^5.9.3"
   },
   "files": [
+    "bin",
     "src",
     "plugins",
     "!plugins/**/__pycache__",

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

@@ -46,6 +46,7 @@ const STATE_MUTATION_TOOLS = new Set([
   "devflow_bootstrap",
   "devflow_transition",
   "devflow_artifact",
+  "devflow_recovery",
   "devflow_context_sync",
   "devflow_evidence",
 ]);
@@ -163,6 +164,7 @@ const REQUIRED_EXTENSION_TOOLS = [
   "devflow_bootstrap",
   "devflow_transition",
   "devflow_artifact",
+  "devflow_recovery",
   "devflow_skill_script",
   "devflow_context_sync",
   "devflow_code_index",
@@ -593,11 +595,8 @@ export default function devflowCore(pi: ExtensionAPI) {
   let sessionId = randomUUID();
   let controlState: SessionControlState = initialControlState();
   let activeContract: ActiveExecutionContract | undefined;
-  let toolCalls = 0;
-  const toolCallBudget = 40;
 
   function setControlState(ctx: { ui: { setStatus(key: string, text: string | undefined): void } }, state: SessionControlState) {
-    if (state.phase === "executing" && controlState.phase !== "executing") toolCalls = 0;
     controlState = state;
     ctx.ui.setStatus("devflow-control", statusText(state));
   }
@@ -925,13 +924,6 @@ export default function devflowCore(pi: ExtensionAPI) {
   });
 
   pi.on("tool_call", async (event, ctx) => {
-    toolCalls += 1;
-    if (toolCalls > toolCallBudget && controlState.phase === "executing") {
-      return {
-        block: true,
-        reason: `本步骤已达到工具调用上限（${toolCallBudget}）。已自动停止，请检查证据后使用 /devflow advance 或重新 /devflow continue。`,
-      };
-    }
     const toolName = String(event.toolName).toLowerCase();
     if (toolName === "task") {
       const requested = requestedTaskAgents(event.input);
@@ -1347,6 +1339,26 @@ export default function devflowCore(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "devflow_recovery",
+    label: "Devflow Recovery",
+    description: "Apply a previewed, registry-only control-plane repair. Requires explicit confirmation and the inspected state revision; never advances a workflow.",
+    parameters: z.object({
+      expectedRevision: z.number().int().min(0),
+      confirm: z.literal(true),
+      state: z.string().optional(),
+    }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const args = ["--write", "--confirm", "--expected-revision", String(params.expectedRevision), "--json"];
+      if (params.state) args.push("--state", params.state);
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/repair_control_plane.rb", args),
+        { action: "repair-control-plane" },
+      );
+    },
+  });
+
   pi.registerTool({
     name: "devflow_skill_script",
     label: "Devflow Skill Script",
@@ -1415,6 +1427,36 @@ export default function devflowCore(pi: ExtensionAPI) {
         setControlState(ctx, initialControlState());
         return;
       }
+      if (trimmed === "recover") {
+        const inspected = await inspectWorkflow(ctx.cwd);
+        const plan = inspected.snapshot?.recovery_plan as Record<string, unknown> | undefined;
+        const revision = plan?.expected_revision;
+        if (!inspected.result.ok || !plan || plan.classification !== "safe_repairable" || typeof revision !== "number") {
+          ctx.ui.notify("当前状态没有可安全执行的恢复计划；请先运行 /devflow explain-state，并按其中的阻塞证据处理。", "error");
+          return;
+        }
+        const confirmed = await ctx.ui.confirm(
+          "确认修复 Devflow 控制面",
+          "将只根据已存在的文件同步 artifact registry；不会推进步骤、确认 checkpoint 或修改需求产物。继续吗？",
+        );
+        if (!confirmed) {
+          ctx.ui.notify("恢复未确认；状态保持不变。", "info");
+          return;
+        }
+        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/repair_control_plane.rb", [
+          "--write",
+          "--confirm",
+          "--expected-revision",
+          String(revision),
+          "--json",
+        ]);
+        if (!result.ok) {
+          ctx.ui.notify(`控制面恢复失败：${result.stderr || result.stdout}`, "error");
+          return;
+        }
+        ctx.ui.notify("控制面 registry 已修复；未推进工作流。请审查当前步骤产物后使用 /devflow advance。", "info");
+        return;
+      }
       if (trimmed === "project-init") {
         const summary = await collectProjectInitialization(ctx);
         if (!summary) return;
@@ -1634,7 +1676,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         return;
       }
       ctx.ui.notify(
-        "Usage: /devflow doctor | status | explain-state | project-init | start <feature>|<phase> | resume | continue | advance | checkpoint",
+        "Usage: /devflow doctor | status | explain-state | recover | project-init | start <feature>|<phase> | resume | continue | advance | checkpoint",
         "warning",
       );
     },

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

@@ -37,6 +37,7 @@ Use the JSON result to choose one of these actions:
 | `run_project_context` | Load and execute `workflow-project-context`, then run the state inspector again. |
 | `run_next_step` | Load and execute the indicated `next_step.skill`. |
 | `run_current_step` | Re-run or finish the indicated `current_step.skill`. |
+| `recover_artifact_registry` | Review `recovery_plan`; if it is `safe_repairable`, call `devflow_recovery(expectedRevision=<plan revision>, confirm=true)`, re-inspect, then explicitly complete the current step when its output is ready. |
 | `workflow_complete` | Report completion and do not call another workflow skill. |
 | `blocked` | Report the blocking reason and ask for the minimum missing input. |
 
@@ -188,6 +189,16 @@ revision is rejected without changing state, registry, or next-intent files.
 
 Checkpoint confirmation also writes the configured `.planning/.next-intent`.
 
+## Control-plane recovery
+
+`devflow_state(action="inspect")` reports `recovery_plan` for output/registry drift. Only a plan classified `safe_repairable` may be applied, and it must be explicitly confirmed with the exact inspected revision:
+
+```text
+devflow_recovery(expectedRevision=<recovery_plan.expected_revision>, confirm=true)
+```
+
+This is registry-only: it derives file existence/content metadata from the filesystem and never changes `completed_steps`, `pending_steps`, `current_step`, checkpoint state, or workflow status. Plans classified `unsafe` (for example missing required output or conflicting state tracking) must be corrected manually; recovery refuses them.
+
 When `devflow_transition` succeeds, it automatically regenerates the Markdown body of STATE.md from the YAML state + artifact registry. The body is marked `<!-- GENERATED — DO NOT EDIT -->` and must not be manually edited.
 
 ## Lessons Rules

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

@@ -96,9 +96,9 @@ def content_validity(root, path, checks)
   { "valid" => issues.empty?, "issues" => issues }
 end
 
-def sync_artifact_registry(root, workflow, state)
+def build_artifact_registry(root, workflow, state)
   registry_path = workflow.dig("artifact_registry", "source")
-  return nil unless registry_path
+  return [nil, nil] unless registry_path
 
   abs = File.join(root, registry_path)
   existing_by_path = if File.exist?(abs)
@@ -159,6 +159,15 @@ def sync_artifact_registry(root, workflow, state)
     "artifacts" => artifacts
   }
 
+  [registry_path, registry]
+end
+
+def sync_artifact_registry(root, workflow, state, registry: nil)
+  registry_path = workflow.dig("artifact_registry", "source")
+  return nil unless registry_path
+
+  registry ||= build_artifact_registry(root, workflow, state).last
+  abs = File.join(root, registry_path)
   DevflowControlIO.atomic_write(abs, registry.to_yaml)
   registry_path
 end
@@ -479,10 +488,16 @@ result =
           state["state_updated_at"] = Date.today.to_s
           state["revision"] = current_revision + 1
         end
+        # Build the registry from the candidate state before validating it. A
+        # step's output is normally written before this transition, so the
+        # persisted registry may still describe the previous state revision.
+        # Validating against it would make complete-step self-blocking.
+        _candidate_registry_path, candidate_registry = changed ? build_artifact_registry(root, workflow, state) : [nil, nil]
         validation = WorkflowStateValidator.validate(
           root: root,
           state_path: state_path,
           state_override: state,
+          artifact_registry_override: candidate_registry,
           strict_artifact_status: false,
           strict_registry_revision: false
         )
@@ -490,7 +505,7 @@ result =
         if changed && !validation["ok"]
           result = fail_result("state_validation_failed", "validation" => validation)
         elsif changed && options[:write]
-          sync_artifact_registry(root, workflow, state)
+          sync_artifact_registry(root, workflow, state, registry: candidate_registry)
           artifact_by_path = load_artifact_registry(root, workflow)
           write_state_file(root, state_path, state, workflow, artifact_by_path, action_description)
           next_intent_written = write_next_intent(root, workflow) if next_intent_requested

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

@@ -382,8 +382,49 @@ result =
               action: "blocked",
               reason: "state_validation_failed",
               state_validation: validation,
+              recovery_plan: {
+                classification: "unsafe",
+                state_transition: "none",
+                registry_write: false,
+                reasons: validation["errors"].map { |issue| issue["code"] }
+              },
               recovery: "Fix missing/invalid artifacts or call devflow_artifact with action=sync and preserve=false, then call devflow_state with action=inspect."
             }
+          elsif (drift = validation["warnings"].find { |issue| issue["code"] == "current_output_registry_drift" })
+            {
+              current_flow: state["current_flow"],
+              current_feature: state["current_feature"],
+              current_phase: state["current_phase"],
+              status: state["status"],
+              completed_steps: completed_ids,
+              pending_steps: pending_ids,
+              current_step: current_step && {
+                id: current_step["id"],
+                label: current_step["label"],
+                skill: current_step["skill"],
+                action: current_step["action"]
+              },
+              next_step: nil,
+              workflow_config: workflow_path,
+              artifact_registry: artifact_registry_summary(root, artifact_by_path).merge(
+                "path" => artifact_registry_path,
+                "error" => artifact_registry_error,
+                "current_outputs_registered" => 0
+              ),
+              action: "recover_artifact_registry",
+              reason: "current_output_registry_drift",
+              drift: drift,
+              recovery_plan: {
+                classification: "safe_repairable",
+                state_transition: "none",
+                registry_write: true,
+                confirmation_required: true,
+                expected_revision: state.fetch("revision", 0),
+                diff: [{ path: drift["path"], registry_exists: drift["registry_exists"], filesystem_exists: true,
+                         registry_content_valid: drift["registry_content_valid"], filesystem_content_valid: true }]
+              },
+              recovery: "After reviewing this diff, call devflow_recovery(expectedRevision=#{state.fetch("revision", 0)}, confirm=true). It only reconciles registry metadata; explicitly complete the step separately when ready."
+            }
           elsif current_step.nil?
             fallback_next_id = next_pending_step_id(state, pending_ids, step_by_id, completed_ids)
             fallback_next_step = fallback_next_id && step_by_id[fallback_next_id]

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "optparse"
+require "yaml"
+require_relative "control_io"
+require_relative "validate_state"
+
+options = { state: ".planning/STATE.md", expected_revision: nil, confirm: false, write: false, json: false }
+OptionParser.new do |opts|
+  opts.banner = "Usage: repair_control_plane.rb --expected-revision N --confirm --write"
+  opts.on("--state PATH") { |value| options[:state] = value }
+  opts.on("--expected-revision N", Integer) { |value| options[:expected_revision] = value }
+  opts.on("--confirm", "Required acknowledgement of the proposed registry-only repair") { options[:confirm] = true }
+  opts.on("--write", "Persist the repair") { options[:write] = true }
+  opts.on("--json") { options[:json] = true }
+end.parse!
+
+def front_matter(markdown)
+  markdown.match(/\A---\n(.*?)\n---\n/m)&.[](1)
+end
+
+def interpolate_path(path, state)
+  path.gsub("{feature}", state.fetch("current_feature", "").to_s).gsub("{phase}", state.fetch("current_phase", "").to_s)
+end
+
+def build_registry(root, workflow, state)
+  checks = workflow.dig("artifact_registry", "content_checks") || {}
+  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)
+      exists = File.exist?(abs)
+      issues = []
+      issues << "file_missing" unless exists
+      issues << "below_min_bytes(#{File.size(abs)} < #{checks["min_bytes"]})" if exists && checks["min_bytes"] && File.size(abs) < checks["min_bytes"]
+      if exists && checks["required_header"]
+        head = File.read(abs, [checks["required_header"].length + 50, 200].min)
+        issues << "missing_required_header(#{checks["required_header"].inspect})" unless head.include?(checks["required_header"])
+      end
+      completed = Array(state["completed_steps"]).include?(step.fetch("id"))
+      status = completed ? (step["checkpoint"] ? "approved" : "completed") : "planned"
+      entry = { "path" => path, "type" => output["type"], "workflow_step" => step.fetch("id"), "produced_by" => step["skill"] || step["action"], "status" => status, "exists" => exists, "content_valid" => issues.empty? }
+      entry["checkpoint"] = step["checkpoint"] if step["checkpoint"]
+      entry["content_issues"] = issues unless issues.empty?
+      entry
+    end
+  end
+  { "schema_version" => 1, "state_revision" => state.fetch("revision", 0), "updated_at" => Date.today.to_s,
+    "registry_scope" => { "flow" => state["current_flow"], "feature" => state["current_feature"], "phase" => state["current_phase"] }, "artifacts" => artifacts }
+end
+
+root = Dir.pwd
+state_path = File.expand_path(options[:state], root)
+result = nil
+lock = options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
+begin
+  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)
+    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) }
+    else
+      registry_path = File.join(root, workflow.dig("artifact_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 } }
+    end
+  end
+ensure
+  DevflowControlIO.release_lock(lock)
+end
+puts JSON.pretty_generate(result)

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

@@ -21,7 +21,7 @@ module WorkflowStateValidator
 
   module_function
 
-  def validate(root:, state_path:, state_override: nil, workflow_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)
     root = File.expand_path(root)
     state_path = File.expand_path(state_path, root)
     issues = []
@@ -45,7 +45,8 @@ module WorkflowStateValidator
       registry_path,
       issues,
       state_revision: state.fetch("revision", 0),
-      strict_registry_revision: strict_registry_revision
+      strict_registry_revision: strict_registry_revision,
+      registry_override: artifact_registry_override
     )
 
     steps = Array(workflow["steps"])
@@ -60,6 +61,7 @@ module WorkflowStateValidator
     validate_dependencies(issues, step_by_id, completed_ids)
     validate_completed_outputs(issues, root, state, step_by_id, completed_ids, artifact_by_path, strict_artifact_status)
     validate_waiting_checkpoint(issues, root, state, step_by_id, artifact_by_path, strict_artifact_status)
+    validate_current_in_progress_output_drift(issues, root, state, step_by_id, artifact_by_path)
 
     ok = issues.none? { |entry| entry["severity"] == "error" }
     result(ok, state_path, workflow_path, registry_path, issues)
@@ -96,16 +98,19 @@ module WorkflowStateValidator
     nil
   end
 
-  def load_artifacts(root, registry_path, issues, state_revision:, strict_registry_revision:)
+  def load_artifacts(root, registry_path, issues, state_revision:, strict_registry_revision:, registry_override: nil)
     return {} unless registry_path
 
-    abs_registry_path = File.expand_path(registry_path, root)
-    unless File.exist?(abs_registry_path)
-      issues << issue("error", "missing_artifact_registry", "Artifact registry does not exist", path: registry_path)
-      return {}
-    end
+    registry = registry_override
+    unless registry
+      abs_registry_path = File.expand_path(registry_path, root)
+      unless File.exist?(abs_registry_path)
+        issues << issue("error", "missing_artifact_registry", "Artifact registry does not exist", path: registry_path)
+        return {}
+      end
 
-    registry = YAML.safe_load(File.read(abs_registry_path), permitted_classes: [], aliases: false)
+      registry = YAML.safe_load(File.read(abs_registry_path), permitted_classes: [], aliases: false)
+    end
     if strict_registry_revision && registry.key?("state_revision") && Integer(registry["state_revision"]) != Integer(state_revision)
       issues << issue(
         "error",
@@ -207,6 +212,37 @@ module WorkflowStateValidator
     validate_step_outputs(issues, root, state, step, artifact_by_path, strict_artifact_status, true)
   end
 
+  # An in-progress step may have written its output before its complete-step
+  # transition. Treat a stale registry observation as recoverable drift, not as
+  # proof that the output is absent. Completion will reconcile it atomically.
+  def validate_current_in_progress_output_drift(issues, root, state, step_by_id, artifact_by_path)
+    return unless state["status"] == "in_progress"
+
+    step = step_by_id[state["current_step"]]
+    return unless step
+
+    Array(step["outputs"]).each do |output|
+      next unless output["required"]
+
+      path = interpolate_path(output.fetch("path"), state)
+      next unless File.exist?(File.expand_path(path, root))
+
+      artifact = artifact_by_path[path]
+      next if artifact && artifact["exists"] != false && artifact["content_valid"] != false
+
+      issues << issue(
+        "warning",
+        "current_output_registry_drift",
+        "Current in-progress step output exists but artifact registry is missing or marks it invalid",
+        step: step["id"],
+        path: path,
+        registry_exists: artifact && artifact["exists"],
+        registry_content_valid: artifact && artifact["content_valid"],
+        recovery: "Call devflow_artifact with action=sync and preserve=false, then retry the complete-step transition."
+      )
+    end
+  end
+
   def validate_step_outputs(issues, root, state, step, artifact_by_path, strict_artifact_status, waiting_checkpoint)
     Array(step["outputs"]).each do |output|
       next unless output["required"]