@guanlin4924/devflow-pi 0.1.99 → 0.1.101

package/README.md

@@ -11,7 +11,7 @@ Devflow Pi 是一个面向项目研发交付的独立 OMP 产品入口，内置
 安装与启动：
 
 ```bash
-npm install -g @guanlin4924/devflow-pi@0.1.99
+npm install -g @guanlin4924/devflow-pi@0.1.101
 cd /path/to/your-project
 devflow-pi init
 devflow-pi doctor

package/package.json

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

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

@@ -1075,8 +1075,10 @@ function isCoreOwnedGovernancePath(filePath: string): boolean {
     || /^\.devflow\/planning\/phases\/[^/\\\x00-\x1F\x7F]+\/REVIEW\.md$/u.test(filePath);
 }
 
-function planningFeatureFromPath(filePath: string): string | null {
-  const match = filePath.match(/^\.devflow\/planning\/(?:requirements|features)\/([^/\\\x00-\x1F\x7F]+)(?:\/|$)/u);
+// Only `requirements/<feature>/...` is feature-scoped; files directly under
+// requirements/ (baseline.md, baseline.meta.json) are global artifacts.
+export function planningFeatureFromPath(filePath: string): string | null {
+  const match = filePath.match(/^\.devflow\/planning\/(?:requirements|features)\/([^/\\\x00-\x1F\x7F]+)\//u);
   return match?.[1] ?? null;
 }
 
@@ -2672,7 +2674,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       const details = issues.length > 0
         ? issues.map(issue => `- ${describeStartupIssue(issue && typeof issue === "object" ? issue as Record<string, unknown> : {})}`).join("\n")
         : "- 开工预检输出无法解析";
-      ctx.ui.notify(`开工预检未通过：\n${details}`, "error");
+      ctx.ui.notify(`开工预检未通过：\n${details}\n可以说「下一步」，由 Devflow 诊断并给出处理办法。`, "error");
       return { ok: false };
     }
     const facts = payload.facts && typeof payload.facts === "object" ? payload.facts as Record<string, unknown> : {};
@@ -2982,7 +2984,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     return true;
   }
 
-  async function diagnoseCurrentWorkflow(cwd: string): Promise<{
+  async function diagnoseCurrentWorkflow(cwd: string, options: { skipWorkflowUpgrade?: boolean } = {}): Promise<{
     snapshot: Record<string, unknown> | null;
     inspectError?: string;
     rolloverState: Record<string, unknown> | null;
@@ -2996,6 +2998,40 @@ export default function devflowCore(pi: ExtensionAPI) {
       ? parseJsonResult(await runRuby(cwd, "workflow-orchestrator/scripts/session_rollover.rb", ["inspect", "--json"]))
       : null;
     const rollover = rolloverState?.rollover as Record<string, unknown> | undefined;
+    let workflowUpgrade = { outdated: false, blocked: false, paths: [] as string[] };
+    if (typeof snapshot?.current_feature === "string" && !options.skipWorkflowUpgrade) {
+      try {
+        const upgradeRun = await runRuby(
+          cwd,
+          "workflow-orchestrator/scripts/init_workflow.rb",
+          ["--force", "--json"],
+        );
+        if (!upgradeRun.ok) throw new Error("workflow upgrade dry-run failed");
+        const upgradeResult = parseJsonResult(upgradeRun);
+        if (!upgradeResult) throw new Error("workflow upgrade dry-run returned invalid JSON");
+        // init_workflow.rb returns { changes: [{ path, exists,
+        // same_as_template, action, ... }] }; a dry-run drift has action
+        // "would_skip_existing", so drift is derived from the boolean fields.
+        const changes = Array.isArray(upgradeResult?.changes) ? upgradeResult.changes : [];
+        const records = changes.filter((change): change is Record<string, unknown> =>
+          Boolean(change && typeof change === "object" && !Array.isArray(change))
+        );
+        const paths = records.flatMap(change =>
+          change.exists === true && change.same_as_template !== true && typeof change.path === "string"
+            ? [change.path]
+            : []
+        );
+        workflowUpgrade = {
+          outdated: paths.length > 0,
+          blocked: records.some(change =>
+            change.action === "blocked_state_mismatch" || change.action === "would_overwrite_blocked"
+          ),
+          paths,
+        };
+      } catch {
+        workflowUpgrade = { outdated: false, blocked: false, paths: [] };
+      }
+    }
     const diagnosis = diagnoseWorkflow({
       inspect: { ok: Boolean(snapshot), error: inspectError },
       snapshot,
@@ -3003,6 +3039,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       outputsReady: snapshot ? isReviewableWorkflowSnapshot(snapshot) : false,
       rolloverPrepared: Boolean(rolloverState && typeof rolloverState.revision === "number"
         && rollover?.status === "prepared" && typeof rollover.id === "string"),
+      workflowUpgrade,
     });
     return { snapshot, inspectError, rolloverState, diagnosis };
   }
@@ -3063,8 +3100,10 @@ export default function devflowCore(pi: ExtensionAPI) {
         return;
       }
     }
+    // Declining the template upgrade must not strand the step behind it.
+    let skipWorkflowUpgrade = false;
     for (let attempt = 0; attempt < 4; attempt += 1) {
-      const current = await diagnoseCurrentWorkflow(ctx.cwd);
+      const current = await diagnoseCurrentWorkflow(ctx.cwd, { skipWorkflowUpgrade });
       const { diagnosis, snapshot } = current;
       const summary = renderDiagnosis(diagnosis);
       if (diagnosis.kind === "execute" && snapshot) {
@@ -3086,6 +3125,12 @@ export default function devflowCore(pi: ExtensionAPI) {
         { label: skip, description: "保持现状，不做任何修改" },
       ]);
       const fix = fixes.find(item => FIX_LABELS[item].label === choice);
+      const upgradeOffered = diagnosis.diagnoses.some(item => item.code === "WORKFLOW_TEMPLATE_OUTDATED");
+      if (!fix && upgradeOffered) {
+        skipWorkflowUpgrade = true;
+        ctx.ui.notify("本次不升级工作流定义，继续按现有定义诊断。", "info");
+        continue;
+      }
       if (!fix) {
         ctx.ui.notify("已保持现状，未做任何修改。", "info");
         return;
@@ -3145,6 +3190,37 @@ export default function devflowCore(pi: ExtensionAPI) {
         ctx.ui.notify("登记表已修复，未推进工作流。正在重新诊断……", "info");
         continue;
       }
+      if (fix === "upgrade-workflow") {
+        const paths = diagnosis.diagnoses
+          .find(item => item.code === "WORKFLOW_TEMPLATE_OUTDATED")?.evidence ?? [];
+        const confirmed = await ctx.ui.confirm(
+          "升级工作流定义",
+          `将用当前版本内置模板替换以下工作流文件：\n${paths.map(item => `- ${item}`).join("\n")}\n\n这些文件中的手工修改会被替换；需求产物和 STATE 不会改变，也不会推进任何步骤。继续吗？`,
+        );
+        if (!confirmed) {
+          skipWorkflowUpgrade = true;
+          ctx.ui.notify("本次不升级工作流定义，继续按现有定义诊断。", "info");
+          continue;
+        }
+        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_workflow.rb", [
+          "--write", "--force", "--json",
+        ]);
+        if (!controlPlaneSucceeded(result)) {
+          ctx.ui.notify(`工作流升级失败：${describeControlFailure(result)}`, "error");
+          return;
+        }
+        const synced = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
+          "--write", "--no-preserve", "--json",
+        ]);
+        if (!controlPlaneSucceeded(synced)) {
+          ctx.ui.notify(`工作流升级后的产物同步失败：${describeControlFailure(synced)}`, "error");
+          return;
+        }
+        activeContract = undefined;
+        contractAgentCalls = 0;
+        ctx.ui.notify("工作流定义已升级。正在重新诊断……", "info");
+        continue;
+      }
       if (fix === "help-bundle") {
         const bundlePath = await writeHelpBundle(ctx, current);
         ctx.ui.notify(`已生成求助包：${bundlePath}\n只包含诊断信息（状态摘要、校验错误、最近的工具报错），不含源码。可以把这个文件发给维护者。`, "info");

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

@@ -63,7 +63,9 @@ targets = {
   "workflows-README.md" => ".devflow/planning/workflows/README.md"
 }
 
-blocked_target_paths = if options[:force] && options[:write] && !options[:allow_state_mismatch]
+# Evaluated for dry runs too, so callers can tell before writing whether a
+# forced upgrade would be refused for the active STATE step set.
+blocked_target_paths = if options[:force] && !options[:allow_state_mismatch]
                          targets.select do |template_name, target_path|
                            source = File.join(template_dir, template_name)
                            target = File.join(root, target_path)

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

@@ -158,7 +158,14 @@ def preflight(root: Path, feature: str, step: str, contract_path: str,
                 issues.append({"code": "INVALID_OBLIGATION_PATH", "index": index, "detail": str(error)})
                 continue
             producer = obligation.get("producer")
-            if producer == "existing":
+            if producer == "existing" and relative.endswith("/"):
+                # Collection inputs (trailing "/") are directories, not files. As in
+                # gate_runtime.rb, a missing collection is allowed at entry.
+                if path.is_dir():
+                    evidence.append({"kind": "input_collection", "path": relative})
+                elif path.exists() or stage != "entry":
+                    issues.append({"code": "MISSING_INPUT_FACT", "index": index, "path": relative})
+            elif producer == "existing":
                 if not path.is_file():
                     issues.append({"code": "MISSING_INPUT_FACT", "index": index, "path": relative})
                 elif obligation.get("sha256") is not None and obligation.get("sha256") != sha256(path):

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

@@ -120,10 +120,15 @@ def startup_preflight(root: Path, feature: str, step: str,
                 else:
                     continue
                 rendered = render_path(relative, feature, phase)
+                collection = relative.endswith("/")
                 try:
-                    exists = review_preflight.within(root, rendered).is_file()
+                    target = review_preflight.within(root, rendered)
+                    exists = target.is_dir() if collection else target.is_file()
                 except ValueError:
                     exists = False
+                # Same rule as gate_runtime.rb: a collection input may be absent at entry.
+                if collection and not exists:
+                    required = False
                 input_facts.append({"path": rendered, "required": required, "exists": exists})
                 # Input readiness is independent of whether the caller supplied
                 # a frozen contract. Keep the derived contract view exempt, as

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

@@ -438,7 +438,9 @@ steps:
     inputs:
       - ".devflow/planning/requirements/{feature}/决策地图.md"
       - ".devflow/planning/requirements/{feature}/wayfinder/"
-      - ".devflow/planning/CONTEXT.md"
+      # Glossary created by domain-modeling on the first feature of a project.
+      - path: ".devflow/planning/CONTEXT.md"
+        required_at_entry: false
     outputs:
       - path: ".devflow/planning/requirements/{feature}/领域模型记录.md"
         type: domain-modeling
@@ -464,7 +466,9 @@ steps:
     inputs:
       - ".devflow/planning/requirements/{feature}/决策地图.md"
       - ".devflow/planning/requirements/{feature}/领域模型记录.md"
-      - ".devflow/planning/CONTEXT.md"
+      # Glossary created by domain-modeling on the first feature of a project.
+      - path: ".devflow/planning/CONTEXT.md"
+        required_at_entry: false
     outputs:
       - path: ".devflow/planning/requirements/{feature}/可实现性审查.md"
         type: requirement-feasibility-review
@@ -1033,7 +1037,7 @@ steps:
     outputs:
       - path: ".devflow/planning/test-runs/{feature}/human-acceptance-results.json"
         type: human-acceptance-results
-        required: true
+        required: false
       - path: ".devflow/planning/test-runs/{feature}/developer-handoff.md"
         type: developer-acceptance-handoff
         required: true
@@ -1050,7 +1054,9 @@ steps:
       - ".devflow/planning/code-index/index.sqlite"
       - ".devflow/planning/code-index/relations.jsonl"
       - ".devflow/planning/phases/{phase}/REVIEW.md"
-      - ".devflow/planning/test-runs/{feature}/human-acceptance-results.json"
+      - path: ".devflow/planning/test-runs/{feature}/human-acceptance-results.json"
+        required: false
+        required_at_entry: false
       - ".devflow/planning/test-runs/{feature}/developer-handoff.md"
     outputs:
       - path: ".devflow/planning/features/{feature}/acceptance-test-bindings.json"

package/plugins/devflow-design/skills/workflow-ui-spec/SKILL.md

@@ -73,7 +73,7 @@ UI-SPEC 不写代码细节（那是前端技术方案的事），但必须把 UI
    - **A. 用户直接提供的截图/图片** → 直接读取分析
    - **B. Figma/蓝湖链接** → 要求用户导出截图后提供，不直接访问
    - **C. 需求基线中的 UI 描述** → 从 baseline.md 提取文字描述
-   - **D. 无设计稿** → 标记为待确认，UI-SPEC.md 不生成，下游功能点梳理和前端方案直接使用基线描述
+   - **D. 无设计稿** → 仍按本文既定结构生成 UI-SPEC.md，使用需求基线中的 UI 描述填充，并在文档顶部声明“未提供设计来源，需求基线中的 UI 描述是本规范的来源”；所有缺少已确认来源的视觉值都写入“待确认事项”，下游步骤继续读取该文件
 
 3. 如果设计稿路径为图片（.png/.jpg/.webp），使用 Read 工具读取图片内容进行视觉分析。
 

package/plugins/devflow-requirements/skills/workflow-requirement-triage/SKILL.md

@@ -26,7 +26,7 @@ Always create or update:
   "duplicate_count": 0,
   "prior_rejection_count": 0,
   "blocking_question": "",
-  "next_skill": "workflow-requirement-baseline | workflow-demand-clarify | workflow-wayfinder | none",
+  "next_skill": "workflow-demand-clarify | workflow-wayfinder | none",
   "searched_sources": [],
   "related_code_paths": [],
   "related_history_paths": []
@@ -118,8 +118,8 @@ Result categories:
 |----------|---------|-------|
 | 已实现且一致 | Current behavior already satisfies the request | `already_done` |
 | 已实现但用户可能不知道 | Capability exists but may be hidden, permission-limited, or named differently | `ready_for_human` |
-| 部分重叠 | Existing behavior covers part of request | `ready_for_baseline` with reuse note |
-| 冲突 | Existing behavior contradicts requested behavior | `ready_for_baseline` with conflict note |
+| 部分重叠 | Existing behavior covers part of request | `ready_for_wayfinder` with reuse note |
+| 冲突 | Existing behavior contradicts requested behavior | `ready_for_wayfinder` with conflict note |
 | 未发现 | No reliable overlap after searched sources | Continue triage |
 
 ## Phase 3 — Prior Rejection / Out-Of-Scope Check
@@ -149,7 +149,7 @@ If found, route:
 
 - `wontfix` when the current request exactly repeats a still-valid rejection.
 - `ready_for_human` when the user may intentionally be reversing a prior decision.
-- `ready_for_baseline` when the prior decision is related but not blocking; record it as context.
+- `ready_for_wayfinder` when the prior decision is related but not blocking; record the prior decision as context.
 
 ## Phase 4 — Scale And Fog Routing
 

package/src/constants.ts

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

package/src/workflow-diagnosis.ts

@@ -12,6 +12,7 @@ export type FixAction =
   | "review-and-advance"
   | "rerun-step"
   | "revise-outputs"
+  | "upgrade-workflow"
   | "repair-registry"
   | "resume-rollover"
   | "help-bundle"
@@ -22,6 +23,7 @@ export type DiagnosisCode =
   | "NO_ACTIVE_FEATURE"
   | "WORKFLOW_COMPLETE"
   | "ROLLOVER_PENDING"
+  | "WORKFLOW_TEMPLATE_OUTDATED"
   | "REGISTRY_DRIFT"
   | "CHECKPOINT_WAITING"
   | "STEP_OUTPUTS_READY"
@@ -56,6 +58,7 @@ export type DiagnosisInput = {
   /** Every required output of the current step exists and is not marked invalid; `planned` allowed. */
   outputsReady: boolean;
   rolloverPrepared: boolean;
+  workflowUpgrade?: { outdated: boolean; blocked: boolean; paths: string[] };
 };
 
 export const FIX_LABELS: Record<FixAction, { label: string; description: string }> = {
@@ -63,9 +66,10 @@ export const FIX_LABELS: Record<FixAction, { label: string; description: string
   "review-and-advance": { label: "审查后推进", description: "弹出推进确认；确认后由 Core 校验产物并推进到下一步" },
   "rerun-step": { label: "重新执行这一步", description: "按当前步骤重新启动 AI（会先激活执行合同）" },
   "revise-outputs": { label: "按意见修改产物", description: "回到审查状态；你直接说明要改什么，AI 修改后再推进" },
+  "upgrade-workflow": { label: "升级工作流定义", description: "用当前版本内置的模板替换项目里的工作流文件（.devflow/planning/workflows/）；不改需求产物，不推进步骤" },
   "repair-registry": { label: "修复登记表", description: "由 Core 按当前状态重建产物登记表；不推进工作流" },
   "resume-rollover": { label: "继续会话交接", description: "完成未走完的会话切换，然后在新会话中继续" },
-  "help-bundle": { label: "生成求助包", description: "把诊断信息写到 .devflow/diagnostics/，不含源码内容" },
+  "help-bundle": { label: "生成求助包", description: "把诊断信息写到 .devflow/runs/diagnostics/，不含源码内容" },
   "cancel-feature": { label: "弃用当前需求", description: "结束当前需求并保留现有产物；之后可以创建新需求" },
 };
 
@@ -160,6 +164,18 @@ export function diagnoseWorkflow(input: DiagnosisInput): WorkflowDiagnosis {
       diagnoses: [{ code: "WORKFLOW_COMPLETE", title: `需求「${feature}」已经结束`, evidence: [], fixes: ["create-feature"] }],
     };
   }
+  if (input.workflowUpgrade?.outdated && !input.workflowUpgrade.blocked) {
+    return {
+      ...base,
+      kind: "repair",
+      diagnoses: [{
+        code: "WORKFLOW_TEMPLATE_OUTDATED",
+        title: "项目里的工作流定义比当前版本旧",
+        evidence: input.workflowUpgrade.paths,
+        fixes: ["upgrade-workflow"],
+      }],
+    };
+  }
   const plan = record(snapshot.recovery_plan);
   if (plan?.classification === "safe_repairable") {
     return {