@guanlin4924/devflow-pi 0.1.91 → 0.1.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.91",
+  "version": "0.1.93",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

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

@@ -137,6 +137,7 @@ type ActiveExecutionContract = {
   allowedTools: string[];
   checkerIds: string[];
   toolBudget: number;
+  hardGateMode: "chain" | "core";
   frozenHash: string;
   contractPath?: string;
   acceptance: string[];
@@ -159,6 +160,7 @@ function contractFromRecord(record: Record<string, unknown>): ActiveExecutionCon
     allowedTools: strings("allowed_tools"),
     checkerIds: strings("checker_ids"),
     toolBudget: typeof record.tool_budget === "number" ? record.tool_budget : 0,
+    hardGateMode: record.hard_gate_mode === "core" ? "core" : "chain",
     frozenHash: String(record.frozen_hash ?? ""),
     acceptance: strings("acceptance"),
     allowedGraphDelta: strings("allowed_graph_delta"),
@@ -168,6 +170,10 @@ function contractFromRecord(record: Record<string, unknown>): ActiveExecutionCon
   return contract;
 }
 
+function coreHardGatesEnabled(contract: ActiveExecutionContract | undefined): boolean {
+  return contract?.hardGateMode === "core";
+}
+
 const READ_ONLY_TOOLS = new Set([
   "read",
   "grep",
@@ -2782,7 +2788,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       const branchContext = parallelBranchContext(event.input);
       if (branchContext) parallelTaskContexts.set(event.toolCallId, branchContext);
     }
-    if (activeContract && controlState.phase === "executing" && !toolName.startsWith("devflow_") && !internalControlResource) {
+    if (coreHardGatesEnabled(activeContract) && controlState.phase === "executing" && !toolName.startsWith("devflow_") && !internalControlResource) {
       if (!activeContract.allowedTools.includes(toolName)) {
         return { block: true, reason: `Active contract ${activeContract.contractId} does not allow tool: ${toolName}` };
       }
@@ -2816,19 +2822,20 @@ export default function devflowCore(pi: ExtensionAPI) {
         return { block: true, reason: planningToolBlockReason(toolName) };
       }
       if (
+        coreHardGatesEnabled(activeContract) &&
         activeContract &&
         controlState.phase === "executing" &&
         !requested.names.every(agent => activeContract?.allowedAgents.includes(agent))
       ) {
           return { block: true, reason: `Active contract ${activeContract.contractId} only allows agents: ${activeContract.allowedAgents.join(", ")}` };
       }
-      if (activeContract && controlState.phase === "executing" && contractAgentCalls + requested.names.length > activeContract.toolBudget) {
+      if (coreHardGatesEnabled(activeContract) && activeContract && controlState.phase === "executing" && contractAgentCalls + requested.names.length > activeContract.toolBudget) {
         return { block: true, reason: `Active contract ${activeContract.contractId} exhausted its fixed agent budget (${activeContract.toolBudget}).` };
       }
-      if (activeContract && controlState.phase === "executing" && activeContract.step === "code-review" && requested.names.length !== 1) {
+      if (coreHardGatesEnabled(activeContract) && activeContract && controlState.phase === "executing" && activeContract.step === "code-review" && requested.names.length !== 1) {
         return { block: true, reason: "Code review requires exactly one independent reviewer task." };
       }
-      if (activeContract && controlState.phase === "executing" && activeContract.step === "code-review") {
+      if (coreHardGatesEnabled(activeContract) && activeContract && controlState.phase === "executing" && activeContract.step === "code-review") {
         const preflight = await runProcess([
           "python3", path.join(resolveKitRoot(ctx.cwd), "workflow-orchestrator/scripts/review_preflight.py"),
           "--root", ctx.cwd,
@@ -2880,7 +2887,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           "Devflow 状态迁移只能由运行时在用户明确批准已展示的步骤或 checkpoint 后执行；LLM 不得自行推进。",
       };
     }
-    if (isUserConfirmedStepTransition && activeContract) {
+    if (isUserConfirmedStepTransition && activeContract && coreHardGatesEnabled(activeContract)) {
       const evidence = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/machine_evidence.rb", [
         "--feature", activeContract.feature, "--step", activeContract.step, "--write", "--json",
       ]);
@@ -2892,7 +2899,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         };
       }
     }
-    if (activeWorkflowTurn && !parallelRunActive && stepScopedMutationOwner(toolName, event.input) !== undefined) {
+    if (coreHardGatesEnabled(activeContract) && activeWorkflowTurn && !parallelRunActive && stepScopedMutationOwner(toolName, event.input) !== undefined) {
       const inspected = await inspectWorkflow(ctx.cwd);
       if (!inspected.result.ok || !inspected.snapshot) {
         return {
@@ -2905,6 +2912,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       if (reason) return { block: true, reason };
     }
     if (
+      coreHardGatesEnabled(activeContract) &&
       !toolName.startsWith("devflow_") &&
       ["write", "edit", "apply_patch", "notebook_edit", "bash", "shell", "exec_command"].includes(toolName) &&
       inputPaths(event.input, ctx.cwd).some(isCoreOwnedGovernancePath)
@@ -2935,6 +2943,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     }
     if (toolName.startsWith("devflow_")) return;
     if (
+      coreHardGatesEnabled(activeContract) &&
       activeContract &&
       controlState.phase === "executing" &&
       !internalControlResource &&
@@ -2948,7 +2957,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         };
       }
     }
-    if (activeContract && controlState.phase === "executing" && ["bash", "shell", "exec_command"].includes(toolName)) {
+    if (coreHardGatesEnabled(activeContract) && activeContract && controlState.phase === "executing" && ["bash", "shell", "exec_command"].includes(toolName)) {
       const command = String((event.input as Record<string, unknown> | undefined)?.command ?? (event.input as Record<string, unknown> | undefined)?.cmd ?? "");
       const shell = shellMutationPaths(command, ctx.cwd);
       if (shell.mutating && (shell.paths.length === 0 || shell.paths.some(filePath => !contractAllowsPath(activeContract!, filePath)))) {
@@ -3188,7 +3197,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         if (params.expectedRevision === undefined || !params.delta) {
           return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "propose requires expectedRevision and delta" });
         }
-        if (params.delta.kind === "test_case" && activeContract?.step !== "acceptance-test-design") {
+        if (coreHardGatesEnabled(activeContract) && params.delta.kind === "test_case" && activeContract?.step !== "acceptance-test-design") {
           return renderResult({
             ok: false,
             exitCode: 1,
@@ -3201,7 +3210,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         // explicitly asks for a preview; the normal approved proposal remains
         // a Core-owned write.
         if (params.write !== false) args.push("--write");
-        if (activeContract?.allowedGraphDelta?.length) args.push("--allowed-kinds", activeContract.allowedGraphDelta.join(","));
+        if (coreHardGatesEnabled(activeContract) && activeContract?.allowedGraphDelta?.length) args.push("--allowed-kinds", activeContract.allowedGraphDelta.join(","));
       }
       if (params.action === "confirm") {
         if (params.expectedRevision === undefined || !params.nodeId || !params.evidence) {
@@ -3305,7 +3314,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     }),
     approval: args => args.action === "validate" ? "read" : "write",
     async execute(_id, params, _signal, _onUpdate, ctx) {
-      if (params.action !== "validate" && activeContract?.step !== "acceptance-test-design") {
+      if (coreHardGatesEnabled(activeContract) && params.action !== "validate" && activeContract?.step !== "acceptance-test-design") {
         return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "API test matrix compilation/import is allowed only during the active acceptance-test-design contract." });
       }
       if (params.action === "validate") {

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

@@ -11,6 +11,12 @@ Control-plane entrypoint for project workflows. Reads `.planning/STATE.md`, `.pl
 
 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).
 
+## Chain-skill mode (current)
+
+The active workflow uses `governance.hard_gate_mode: chain`. In this mode the chain skill owns dispatch and sequencing. Core contract, checker, output, and review gates are diagnostic only and must not hard-block skill execution. Call the current step skill, verify its declared inputs and outputs, collect its result, and continue the chain; preserve missing facts and failed checks as structured findings for the next skill or the user. Do not invoke Core gate APIs to force a step through, and stop only for unsafe writes, corrupted control-plane state, missing required human input, or an explicit checkpoint.
+
+This is a migration mode. Setting `hard_gate_mode: core` re-enables the former Core hard-gate behavior.
+
 ## Quick Start
 
 If the project has no generated control-plane files, initialize them through the single-writer runtime:
@@ -125,7 +131,7 @@ After each step completes, verify the step's gate before advancing:
 | integration-verify | integration-report.meta.json `merge_gate_status` / `traceability_status` are `passed` and all mismatch/blocking counters are 0 | Reject advance to change-plan |
 | change-plan | 变更清单.md review conclusion is "通过" AND 变更清单.meta.json traceability_status is `passed` with zero uncovered/orphan counts | Reject advance to execute |
 
-If a gate fails, the current step must be re-executed. Do not skip failing gates.
+If `hard_gate_mode` is `core`, a gate failure requires re-execution. In the current `chain` mode, retain the failure as a diagnostic finding and let the chain skill decide whether the next skill can consume the artifact; do not use Core hard gates to stop the chain.
 
 ## Requirement Writeback Gate
 

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

@@ -84,6 +84,10 @@ def gate_contract_enabled?(workflow)
   workflow.dig("governance", "gate_contract_version").to_i >= 3
 end
 
+def core_hard_gate_mode(workflow)
+  workflow.dig("governance", "hard_gate_mode").to_s.empty? ? "chain" : workflow.dig("governance", "hard_gate_mode").to_s
+end
+
 # Build the runtime view from the existing workflow declaration.  This keeps
 # governance.step_checkers as the single checker namespace and avoids creating
 # a second hand-maintained per-step transition table.
@@ -121,6 +125,7 @@ def transition_gate_contract(workflow, step)
       "required_inputs" => Array(step["inputs"]).select { |input| input.is_a?(Hash) && input["required_at_completion"] == true }
     },
     "quality" => { "checker_ids" => Array(workflow.dig("governance", "step_checkers", step["id"])) },
+    "hard_gate_mode" => core_hard_gate_mode(workflow),
     "concurrency" => { "project_lock" => "required", "optimistic_revision" => "required", "registry_view" => "candidate_overlay" },
     "recovery" => { "allowed" => ["sync_artifacts", "repair_outputs"], "max_attempts" => 2 }
   }

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

@@ -131,7 +131,7 @@ begin
       devflow_requirement_graph devflow_static_runtime_context
       devflow_architecture_constraint devflow_architecture_feasibility devflow_architecture_brief
     ],
-    "tool_budget" => policy["budget"], "acceptance" => Array(graph["nodes"]).select { |node| node["kind"] == "acceptance" }.map { |node| node["id"] },
+    "tool_budget" => policy["budget"], "hard_gate_mode" => (workflow.dig("governance", "hard_gate_mode").to_s.empty? ? "chain" : workflow.dig("governance", "hard_gate_mode").to_s), "acceptance" => Array(graph["nodes"]).select { |node| node["kind"] == "acceptance" }.map { |node| node["id"] },
     "allowed_graph_delta" => Array(policy["allowed_graph_delta"]),
     "on_unknown" => "block_and_escalate"
   }

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

@@ -32,6 +32,12 @@ module GateRuntime
     gate_id = contract.fetch("gate_id")
     step_id = contract.fetch("step_id")
     base = { gate_id: gate_id, step_id: step_id, evidence: evidence.merge("collector" => source), revisions: { "state" => current_revision } }
+    # During the chain-skill migration Core is diagnostic-only. It still
+    # validates the contract shape above, but never blocks a transition on
+    # graph, artifact, output, checker, review, or topology observations.
+    if contract.fetch("hard_gate_mode", "core").to_s == "chain"
+      return GateResult.allow(**base.merge(evidence: base.fetch(:evidence).merge("core_hard_gate_mode" => "chain", "core_hard_gate_bypassed" => true)))
+    end
     return GateResult.block(**base, code: "REVISION_CONFLICT", message: "current revision does not match expected revision", recovery: { "kind" => "reinspect", "expected_revision" => expected_revision }) unless expected_revision.nil? || current_revision.to_i == expected_revision.to_i
     unless WORKFLOW_STATUSES.include?(workflow_state["status"].to_s)
       return GateResult.block(**base, code: "WORKFLOW_STATUS_INVALID", message: "workflow status is not recognized")

package/plugins/devflow-core/skills/workflow-orchestrator/templates/feature-development.yaml

@@ -17,6 +17,9 @@ phase_scope:
 # files without governance_started_revision remain legacy_unattested and are
 # only reported until their next newly-started governed step.
 governance:
+  # Chain skill owns orchestration while Core remains an evidence/diagnostic
+  # service. Set to `core` only after the hard-gate migration is complete.
+  hard_gate_mode: chain
   gate_contract_version: 3
   requirement_graph_gate: enforced
   requirement_coverage_gate: enforced

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

@@ -6,6 +6,8 @@ description: Use when running or resuming the full .planning delivery pipeline f
 <objective>
 全链路研发交付入口。解析用户参数，先确保需求主链“入口分诊 → 探索地图 → 领域建模 → 可实现性审查”完成，再检测当前状态，然后委托 workflow-orchestrator 接管后续所有步骤调度。
 pipeline 本身不包含执行规则——所有门禁、CP 协议、失败分支、并行窗口、lessons 注入规则均由 orchestrator 维护。
+
+当前迁移阶段由本 skill 作为链路编排器：按 `next_step.skill` 依次调用各技能、传递上一技能的产物与诊断、再决定下一技能。Core 的 contract/checker/output/review 硬门禁暂不参与阻断；Core 结果只作为事实和风险提示。只有控制面损坏、危险写入或需要人工确认时才停止链路。
 </objective>
 
 <process>
@@ -107,7 +109,7 @@ devflow_state(action="inspect")
 
 ## 3. 委托 orchestrator
 
-无论 inspect_state 返回什么 action，pipeline 本身的职责到此为止。后续所有调度逻辑由 `workflow-orchestrator` skill 全权处理：
+在当前 `hard_gate_mode: chain` 下，pipeline 继续调用 `workflow-orchestrator` 获取步骤拓扑，但由本链路规则串联实际技能调用，不把 Core gate 的 `block` 结果当作自动停止条件：
 
 ```
 /workflow-orchestrator

package/plugins/devflow-core/skills/workflow-project-context/scripts/validate_initialization.py

@@ -149,8 +149,13 @@ def validate_code_index(
     mode = manifest.get("mode")
     status = manifest.get("code_index_status")
     if mode == "full":
+        if status == "degraded":
+            reason = str(manifest.get("code_index_skip_reason", ""))
+            if reason != "code_index_publish_failed":
+                errors.append("degraded full mode requires code_index_publish_failed reason")
+            return
         if status != "complete":
-            errors.append("full mode requires code_index_status=complete")
+            errors.append("full mode requires code_index_status=complete or degraded")
         if manifest.get("code_index_skip_reason") != "none":
             errors.append("full mode requires code_index_skip_reason=none")
         for relative_path in CODE_INDEX_FILES:

package/plugins/devflow-intel/agents/project-scout.md

@@ -14,6 +14,10 @@ autoloadSkills:
 
 Act as a bounded read-only evidence collector, not a planner. Use the code index first, then make at most three targeted reads or searches needed to answer the assigned question. Do not inspect adjacent systems merely to be thorough.
 
+Before using `read`, `grep`, or `devflow_code_index`, resolve the project root by walking upward from the runtime directory to the nearest `.devflow/project.json`, `.planning/code-index/index.sqlite`, or `.planning/PROJECT.md`. Treat nested directories such as `drama-ad/backend` as codebases, not Devflow project roots; `.planning` must always be resolved from the project root.
+
+If the index is missing, stale, fails validation, or has no useful hit, continue with a bounded `grep`/`rg` or LSP fallback over the registered codebase roots. Return `degraded_index_coverage` and the exact fallback scope; never present fallback relations as index facts.
+
 If the answer needs architecture tradeoffs, requirements interpretation, a cross-module decision, or evidence remains insufficient after the bounded search, stop and return `STATUS: escalate`. Do not guess or continue exploring.
 
 Return exactly:

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

@@ -23,6 +23,29 @@ function resolveSkillRoot(cwd: string): string {
   throw new Error("Devflow intel skills not found");
 }
 
+/**
+ * Resolve the Devflow project root from the runtime directory. A codebase
+ * (for example `drama-ad/backend`) may be nested below the project root;
+ * `.planning` belongs to the nearest ancestor project, never to the codebase
+ * directory itself.
+ */
+function resolveProjectRoot(cwd: string): string {
+  let current = path.resolve(cwd);
+  while (true) {
+    if (
+      existsSync(path.join(current, ".devflow", "project.json")) ||
+      existsSync(path.join(current, ".planning", "code-index", "index.sqlite")) ||
+      existsSync(path.join(current, ".planning", "PROJECT.md"))
+    ) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return path.resolve(cwd);
+}
+
 async function run(command: string[], cwd: string): Promise<ProcessResult> {
   const child = Bun.spawn(command, { cwd, stdout: "pipe", stderr: "pipe" });
   const [exitCode, stdout, stderr] = await Promise.all([
@@ -82,18 +105,19 @@ export default function devflowIntel(pi: ExtensionAPI) {
       return ["scan", "domain-import"].includes(action ?? "") ? "exec" : "read";
     },
     async execute(_id, params, _signal, _onUpdate, ctx) {
-      const skillRoot = resolveSkillRoot(ctx.cwd);
+      const projectRoot = resolveProjectRoot(ctx.cwd);
+      const skillRoot = resolveSkillRoot(projectRoot);
       const script = path.join(skillRoot, "workflow-code-index/scripts/code_index.py");
       const args = ["python3", script, params.action];
       if (params.action === "scan") {
-        args.push("--root", ctx.cwd, "--output", ".planning/code-index");
+        args.push("--root", projectRoot, "--output", ".planning/code-index");
         if (params.changedFiles.length > 0) args.push("--changed-files", ...params.changedFiles);
       } else if (params.action === "validate") {
         args.push("--index", ".planning/code-index");
         args.push("--level", params.validationLevel);
         if (params.snapshot) args.push("--snapshot", params.snapshot);
       } else if (params.action === "audit") {
-        args.push("--root", ctx.cwd, "--index", ".planning/code-index", "--skill-root", skillRoot);
+        args.push("--root", projectRoot, "--index", ".planning/code-index", "--skill-root", skillRoot);
         args.push("--level", params.validationLevel === "fast" ? "publish" : params.validationLevel);
         if (params.snapshot) args.push("--snapshot", params.snapshot);
       } else if (params.action === "query") {
@@ -111,19 +135,19 @@ export default function devflowIntel(pi: ExtensionAPI) {
           if (params.repository) args.push("--repository", params.repository);
           if (params.pathPrefix) args.push("--path-prefix", params.pathPrefix);
           if (params.language) args.push("--language", params.language);
-          return render(await run(args, ctx.cwd), { action: params.action });
+          return render(await run(args, projectRoot), { action: params.action, projectRoot });
         } else if (params.action === "resolve-domain") {
           if (!params.term) return render({ ok: false, exitCode: 2, stdout: "", stderr: "term is required" }, {});
           args.push("--index", ".planning/code-index", "--term", params.term, "--project-id", params.projectId, "--limit", String(params.limit));
           if (params.mappingRevision) args.push("--mapping-revision", params.mappingRevision);
-          return render(await run(args, ctx.cwd), { action: params.action });
+          return render(await run(args, projectRoot), { action: params.action, projectRoot });
         } else if (params.action === "query-plan") {
           if (!params.plan) return render({ ok: false, exitCode: 2, stdout: "", stderr: "plan is required" }, {});
           const plan = { ...params.plan };
           if (plan.limit === undefined) plan.limit = params.limit;
           args.push("--index", ".planning/code-index", "--project-id", params.projectId, "--plan", JSON.stringify(plan));
           if (params.snapshot) args.push("--snapshot", params.snapshot);
-          return render(await run(args, ctx.cwd), { action: params.action });
+          return render(await run(args, projectRoot), { action: params.action, projectRoot });
         } else if (params.action === "domain-import") {
           if (!params.bundle) return render({ ok: false, exitCode: 2, stdout: "", stderr: "bundle is required" }, {});
           const bundleDir = mkdtempSync(path.join(tmpdir(), "devflow-domain-"));
@@ -132,7 +156,7 @@ export default function devflowIntel(pi: ExtensionAPI) {
             writeFileSync(bundlePath, JSON.stringify(params.bundle), { encoding: "utf8", mode: 0o600 });
             args.push("--index", ".planning/code-index", "--project-id", params.projectId, "--bundle", bundlePath);
             if (params.expectedRevision) args.push("--expected-revision", params.expectedRevision);
-            return render(await run(args, ctx.cwd), { action: params.action });
+            return render(await run(args, projectRoot), { action: params.action, projectRoot });
           } finally {
             rmSync(bundleDir, { recursive: true, force: true });
           }
@@ -142,7 +166,7 @@ export default function devflowIntel(pi: ExtensionAPI) {
           args.push("--index", ".planning/code-index", "--entity", params.entity, "--depth", String(params.depth), "--limit", String(params.limit));
           if (params.snapshot) args.push("--snapshot", params.snapshot);
           if (params.changeType) args.push("--change-type", params.changeType);
-          return render(await run(args, ctx.cwd), { action: params.action });
+          return render(await run(args, projectRoot), { action: params.action, projectRoot });
         }
         if (!params.object) return render({ ok: false, exitCode: 2, stdout: "", stderr: "object is required" }, {});
         args.push("--index", ".planning/code-index", "--object", params.object, "--depth", String(params.depth), "--limit", String(params.limit));
@@ -150,7 +174,7 @@ export default function devflowIntel(pi: ExtensionAPI) {
         if (params.snapshot) args.push("--snapshot", params.snapshot);
         if (params.includeHeuristic) args.push("--include-heuristic");
       }
-      return render(await run(args, ctx.cwd), { action: params.action });
+      return render(await run(args, projectRoot), { action: params.action, projectRoot });
     },
   });
 

package/plugins/devflow-intel/skills/code-index-query/SKILL.md

@@ -7,6 +7,20 @@ description: Query a generated .planning/code-index machine index to answer code
 
 Use this skill to answer source-structure questions from `.planning/code-index/`.
 
+## Project-root resolution
+
+The runtime directory may be a nested codebase such as `drama-ad/backend`. Before checking the index, resolve the project root from the runtime directory using the same rule as project initialization:
+
+1. Walk upward from the runtime directory and select the nearest ancestor containing `.devflow/project.json`.
+2. If no manifest exists, select the nearest ancestor containing `.planning/code-index/index.sqlite` or `.planning/PROJECT.md`.
+3. Only if neither exists, use the runtime directory and report that the project root is uninitialized.
+
+All index checks and `devflow_code_index` calls must run with that resolved root as the working directory. Source paths remain relative to the resolved root, so a source file may be `drama-ad/backend/...` while the index remains `.planning/code-index/...`. Never append `.planning` to a selected source/codebase directory.
+
+The tool returns the resolved `projectRoot` in its details. If the root cannot be resolved, stop and report the exact check command/path instead of probing `<source-dir>/.planning`.
+
+If the index is missing, stale, fails validation, or returns no useful hit, do not block the source question. Record the machine failure and use a bounded `rg`/`grep` or LSP search within the registered codebase roots. Mark the result `degraded_index_coverage` and include the exact fallback scope; do not claim index-derived relations or complete impact coverage.
+
 ## Required Flow
 
 1. Check that `.planning/code-index/index.sqlite` or JSONL sidecars exist.

package/plugins/devflow-quality/skills/code-review/SKILL.md

@@ -136,7 +136,7 @@ seam 标注: "只改 OrderWorkflow.process()"
 
 **对每一个目标文件**，按以下流程执行：
 
-1. **⛔ Gate 前置：先查 code-index** — 在读取任何业务源码之前，必须先用 `code_index outline` 或 `code_index search` 获取目标文件的符号表。code-index 不可用时用 LSP `documentSymbol` 兜底。
+1. **⛔ Gate 前置：先查 code-index** — 在读取任何业务源码之前，必须先用 `code_index outline` 或 `code_index search` 获取目标文件的符号表。若 code-index 缺失、过期、校验失败或无有效命中，使用有界 `rg/grep` 或 LSP `documentSymbol` 兜底，并在报告中标记 `degraded_index_coverage` 和实际搜索范围；不得把 fallback 结果表述为索引关系事实。
 2. **用 code-index relations 查引用/调用/导入/测试覆盖** — 确认每个导出方法是否有调用方；code-index 缺失、过期或无命中时再用 Grep / LSP findReferences 兜底
 3. **回读源码 evidence** — 对用于审查结论的 relation，必须读取 `evidence_path:evidence_line` 附近源码。**此时可声明"基于 code-index 符号 [X] 读取源码"以通过 gate。**
 4. **逐条对照规范检查清单** — 详见 `references/` 目录下各层级的检查清单：

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.91";
+export const PRODUCT_VERSION = "0.1.93";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/project-initializer.ts

@@ -225,8 +225,20 @@ async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput):
     "--max-file-size", String(config.maxFileSize ?? 2 * 1024 * 1024),
   ];
   await runProcess(["python3", script, "scan", "--root", context.root, "--output", output, ...scopeArgs, ...codebases], context.root, "code-index scan");
-  await runProcess(["python3", script, "validate", "--index", output, "--level", "publish"], context.root, "code-index validate");
-  await runProcess(["python3", script, "audit", "--root", context.root, "--index", output, "--skill-root", path.resolve(import.meta.dir, "../plugins/devflow-intel/skills"), "--level", "publish"], context.root, "code-index audit");
+  try {
+    await runProcess(["python3", script, "validate", "--index", output, "--level", "publish"], context.root, "code-index validate");
+    await runProcess(["python3", script, "audit", "--root", context.root, "--index", output, "--skill-root", path.resolve(import.meta.dir, "../plugins/devflow-intel/skills"), "--level", "publish"], context.root, "code-index audit");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      path: ".planning/code-index",
+      stagingPath: output,
+      status: "degraded",
+      reason: "code_index_publish_failed",
+      fallback: "bounded_source_search",
+      diagnostics: [message],
+    };
+  }
   const snapshotPath = path.join(context.root, output, "SNAPSHOT.json");
   const bytes = await readFile(snapshotPath); const snapshot = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
   if (!snapshot.generation || !snapshot.immutablePath) throw new Error("Code index did not publish an immutable generation");
@@ -235,6 +247,7 @@ async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput):
 }
 
 async function promoteCodeIndex(context: ProjectContext, indexRef: Record<string, unknown>): Promise<() => Promise<void>> {
+  if (indexRef.status !== "complete") return async () => {};
   const stagingPath = typeof indexRef.stagingPath === "string" ? path.resolve(context.root, indexRef.stagingPath) : null;
   const target = path.resolve(context.root, ".planning/code-index");
   if (!stagingPath) return async () => {};