@guanlin4924/devflow-pi 0.1.16 → 0.1.17

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

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Workload constraint validator (P1 NFR). Source-status driven: measured /
+# contracted require evidence; approved_assumption requires owner +
+# observability + review date + escalation trigger; unknown carries no
+# evidence requirement but is only advisory.
+require "json"
+require "optparse"
+
+module WorkloadConstraint
+  SOURCE_STATUSES = %w[measured contracted approved_assumption unknown].freeze
+  METRICS = %w[peak_qps data_growth rpo rto p95_latency].freeze
+  APPROVED_ASSUMPTION_FIELDS = %w[owner observability_metric review_date escalation_trigger].freeze
+
+  module_function
+
+  def validate(constraint)
+    errors = []
+    errors << "workload_ref is required" if constraint["workload_ref"].to_s.empty?
+    unless constraint["workload_ref"].to_s.match?(/\A(BEH|SL|API)-\d+\z/)
+      errors << "workload_ref must reference BEH/SL/API"
+    end
+    errors << "metric is required" if constraint["metric"].to_s.empty?
+    errors << "invalid metric" if !constraint["metric"].to_s.empty? && !METRICS.include?(constraint["metric"])
+    errors << "source_status is required" if constraint["source_status"].to_s.empty?
+    errors << "invalid source_status" if !constraint["source_status"].to_s.empty? && !SOURCE_STATUSES.include?(constraint["source_status"])
+    target = constraint["target"]
+    errors << "target.value is required" unless target.is_a?(Hash) && !target["value"].to_s.empty?
+    case constraint["source_status"]
+    when "measured", "contracted"
+      errors << "evidence_ref is required for #{constraint["source_status"]}" if constraint["evidence_ref"].to_s.empty?
+    when "approved_assumption"
+      APPROVED_ASSUMPTION_FIELDS.each do |key|
+        errors << "approved_assumption requires #{key}" if constraint[key].to_s.empty?
+      end
+    end
+    errors.uniq
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { constraint_json: nil }
+  command = ARGV.shift
+  OptionParser.new do |o|
+    o.on("--constraint-json JSON") { |v| options[:constraint_json] = v }
+    o.on("--json") { options[:json] = true }
+  end.parse!
+  begin
+    raise ArgumentError, "command must be validate" unless command == "validate"
+    constraint = JSON.parse(options[:constraint_json].to_s)
+    errors = WorkloadConstraint.validate(constraint)
+    { "ok" => errors.empty?, "errors" => errors }
+  rescue StandardError => error
+    { "ok" => false, "reason" => "workload_constraint_failed", "message" => error.message }
+  end.tap { |r| puts JSON.pretty_generate(r) }
+end

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

@@ -33,6 +33,9 @@ governance:
       - requirement-graph-check
       - contract-coverage-check
       - change-impact-check
+    architecture-feasibility:
+      - requirement-graph-check
+      - change-impact-check
     integration-verify:
       - requirement-graph-check
       - slice-independence-check
@@ -78,7 +81,7 @@ lessons_policy:
 parallel_windows:
   - id: dual-track-design
     label: API contract based frontend/backend design parallel window
-    after_step: api-contract
+    after_step: architecture-feasibility
     branch_steps:
       - backend-tech-spec
       - ui-spec
@@ -218,7 +221,7 @@ checkpoints:
       - approve
       - needs_fix
     skip_policy: never
-    resume_behavior: "user confirms, then enter Track A/Track B design"
+    resume_behavior: "user confirms, then run architecture feasibility review before Track A/Track B design"
   CP-2:
     name: Merge Gate confirmation
     gate_after: integration-verify
@@ -472,12 +475,44 @@ steps:
         traceability_status: { type: string, required: true }
     checkpoint: CP-API
 
+  - id: architecture-feasibility
+    order: 18
+    label: Architecture feasibility
+    skill: workflow-architecture-feasibility
+    depends_on:
+      - api-contract
+    inputs:
+      - ".planning/requirements/baseline.md"
+      - ".planning/features/{feature}/api-contract.md"
+      - ".planning/requirements/{feature}/governance.json"
+      - ".context/static-runtime-context.json"
+      - ".planning/navigation/INDEX.md"
+    outputs:
+      - path: ".planning/features/{feature}/architecture-brief.md"
+        type: architecture-brief
+        required: true
+    meta_output:
+      path: ".planning/features/{feature}/architecture-brief.meta.json"
+      fields:
+        assessment_status: { type: string, required: true }
+        assessment_level: { type: string, required: true }
+        graph_revision: { type: integer, required: true }
+        static_context_snapshot_revision: { type: integer, required: false }
+        comparison_status: { type: string, required: true }
+        trigger_codes: { type: array, required: true }
+        unresolved_codes: { type: array, required: true }
+        decision_ids: { type: array, required: true }
+        confirmed_decision_ids: { type: array, required: true }
+        risk_ids: { type: array, required: true }
+        confirmed_risk_ids: { type: array, required: true }
+
   - id: ui-spec
     order: 20
     label: UI spec
     skill: workflow-ui-spec
     depends_on:
       - api-contract
+      - architecture-feasibility
     inputs:
       - ".planning/requirements/baseline.md"
       - ".planning/features/{feature}/api-contract.md"
@@ -508,8 +543,11 @@ steps:
     depends_on:
       - feature-breakdown
       - api-contract
+      - architecture-feasibility
     inputs:
       - ".planning/features/{feature}/api-contract.md"
+      - ".planning/features/{feature}/architecture-brief.md"
+      - ".planning/features/{feature}/architecture-brief.meta.json"
       - ".planning/features/{feature}/功能点梳理.md"
       - ".planning/features/{feature}/UI-SPEC.md"
       - ".planning/navigation/INDEX.md"
@@ -526,6 +564,10 @@ steps:
         component_count: { type: integer, required: true }
         api_count: { type: integer, required: true }
         api_gaps_count: { type: integer, required: true }
+        architecture_brief_revision: { type: integer, required: true }
+        architecture_graph_revision: { type: integer, required: true }
+        architecture_static_context_snapshot_revision: { type: integer, required: false }
+        architecture_comparison_status: { type: string, required: true }
 
   - id: backend-tech-spec
     order: 50
@@ -533,8 +575,11 @@ steps:
     skill: workflow-backend-tech-spec
     depends_on:
       - api-contract
+      - architecture-feasibility
     inputs:
       - ".planning/features/{feature}/api-contract.md"
+      - ".planning/features/{feature}/architecture-brief.md"
+      - ".planning/features/{feature}/architecture-brief.meta.json"
       - ".planning/requirements/baseline.md"
       - ".planning/navigation/INDEX.md"
       - ".planning/execution-contract.md"
@@ -543,6 +588,13 @@ steps:
       - path: ".planning/features/{feature}/后端技术方案.md"
         type: backend-tech-spec
         required: true
+    meta_output:
+      path: ".planning/features/{feature}/后端技术方案.meta.json"
+      fields:
+        architecture_brief_revision: { type: integer, required: true }
+        architecture_graph_revision: { type: integer, required: true }
+        architecture_static_context_snapshot_revision: { type: integer, required: false }
+        architecture_comparison_status: { type: string, required: true }
 
   - id: api-call-guide
     order: 55

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

@@ -29,6 +29,7 @@ pipeline 本身不包含执行规则——所有门禁、CP 协议、失败分
 | 8 | requirement-feasibility-review | 可实现性审查 |
 | 10 | requirement-baseline | 需求基线 |
 | 15 | api-contract | API 契约（分叉前共同事实） |
+| 18 | architecture-feasibility | 架构可行性与方案比较（分叉前共同事实） |
 | 20 | ui-spec | Track B：UI 设计规范 |
 | 30 | feature-breakdown | Track B：功能点梳理 |
 | 40 | backend-tech-spec | Track A：后端方案 |
@@ -46,8 +47,8 @@ pipeline 本身不包含执行规则——所有门禁、CP 协议、失败分
 | 110 | update-navigation | 更新导航 |
 | 120 | archive | 里程碑归档 |
 
-- **`--track A`**：后端/API 轨道产物模式。可跑 `requirement-triage → requirement-wayfinder → domain-modeling → requirement-feasibility-review → requirement-baseline → api-contract → backend-tech-spec → api-call-guide`，但不能自动进入 `integration-verify / change-plan / execute`。
-- **`--track B`**：前端/UI 轨道产物模式。要求 `api-contract` 已存在且 approved；新需求从需求主链开始，已有契约可跑 `ui-spec → feature-breakdown → frontend-tech-spec`，但不能自动进入 `change-plan / execute`。
+- **`--track A`**：后端/API 轨道产物模式。可跑 `requirement-triage → requirement-wayfinder → domain-modeling → requirement-feasibility-review → requirement-baseline → api-contract → architecture-feasibility → backend-tech-spec → api-call-guide`，但不能自动进入 `integration-verify / change-plan / execute`。
+- **`--track B`**：前端/UI 轨道产物模式。要求 `api-contract` 与 `architecture-feasibility` 已完成；新需求从需求主链开始，已有共同事实可跑 `ui-spec → feature-breakdown → frontend-tech-spec`，但不能自动进入 `change-plan / execute`。
 - **未设置 track**：完整交付模式。必须完成双轨并通过 `integration-verify` 后才能进入 `change-plan`。
 - **`--no-review`**：保留参数位，但当前双轨 workflow 不自动跳过 CP-2。Merge Gate 不能跳过。
 

package/plugins/devflow-core/skills/workflow-project-context/SKILL.md

@@ -35,6 +35,7 @@ Always create or update:
 - `.planning/navigation/INDEX.md` — codebase registry: maps each codebase to its navigation file, plus rule package index and downstream read contract
 - `.planning/navigation/{name}.md` — one file per codebase: framework, entries, conventions, commands (name comes from user-provided codebase name)
 - `.planning/code-index/` — machine code intelligence index location; generated by `workflow-code-index` by default unless fast mode skips it
+- `.context/static-runtime-context/` + `.context/static-runtime-context.json` — Core-owned, Git-bound static declarations snapshot; never a production-health or capacity assertion
 - `.context/spec/design/` — conditional frontend design rule package; installed after code-index for projects with frontend codebases
 - `.planning/project-context-run.json` — current-run evidence: run identity, code-index status, dynamically discovered depth specs, source paths, and source fingerprints
 - `.context/spec/index.md` — generated technical specification registry: maps stack profiles and codebase specs
@@ -114,7 +115,7 @@ If `.planning/` already exists:
 
 1. Read existing `.planning/PROJECT.md`, `.planning/STATE.md`, and `.planning/navigation/*.md` before writing.
 2. Preserve user-authored business context, constraints, key decisions, and missing information unless the user explicitly asks to replace them.
-3. Refresh only machine-derived fields. This includes: detected paths, frameworks, entries, commands, scan status, navigation index, rule package files (execution-contract.md, toolchain.md, rules/INDEX.md), **all currently discovered depth spec files (Step 7.4)**, and **code index (Step 6.5)**. The presence of existing output files does NOT exempt a step from re-execution — machine-derived fields must be regenerated to reflect current codebase state.
+3. Refresh only machine-derived fields. This includes: detected paths, frameworks, entries, commands, scan status, navigation index, rule package files (execution-contract.md, toolchain.md, rules/INDEX.md), **all currently discovered depth spec files (Step 7.4)**, **code index (Step 6.5)**, and **static runtime-context (Step 6.5a)**. The presence of existing output files does NOT exempt a step from re-execution — machine-derived fields must be regenerated to reflect current codebase state.
 4. If provided codebase locations differ from existing records, record the change in `STATE.md` under `Change Log`.
 5. Never delete existing planning files during initialization. Preserve user-authored content in execution-contract.md and toolchain.md when refreshing machine-derived fields.
 
@@ -478,6 +479,21 @@ After full-mode commands succeed, set `code_index_status` to `complete`, use ski
 
 Do not require users to manually run Python when they invoked this skill.
 
+## Step 6.5a — Static Runtime Context Snapshot (REQUIRED)
+
+After Step 6.5, collect the separate P1 static-context snapshot:
+
+```text
+devflow_static_runtime_context(action="collect")
+devflow_static_runtime_context(action="inspect")
+```
+
+Run this in both full and fast modes. It reads the committed Git tree and may therefore collect manifest declarations even when code-index was intentionally skipped. Verify that the returned pointer exists and record the snapshot revision in the initialization summary.
+
+Do not describe this snapshot as production topology, resource health, capacity, or a list of deployed services. Its P1 scope is repository declarations and explicitly supported platform manifests only; unsupported resource bindings, integrations, and jobs remain `unknown` until a later collector can prove them.
+
+If the repository has no readable Git commit, retain the generated snapshot with incomplete coverage and record the limitation. Do not invent a working-tree baseline or silently skip the collection.
+
 ## Step 6.6 — Design Rule Package (Conditional Required)
 
 This step belongs to project initialization, not feature design. It runs **after the code index is available** and before the context-spec package is finalized.

package/plugins/devflow-design/skills/workflow-architecture-feasibility/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: workflow-architecture-feasibility
+description: "Use after API contract and before frontend/backend technical specifications to compare implementation paths against confirmed workload facts and repository-static context. Use for async or scheduled work, batch operations, external calls, fanout, migrations, workload/SLA constraints, or when a feature may not fit the current framework and integrations."
+---
+
+# 架构可行性与方案比较
+
+生成一份由 Core 派生的架构简报；不把自由 Markdown 当作架构真相，也不把仓库声明当成生产容量。
+
+## 固定流程
+
+1. 读取 `devflow_requirement_graph(action="inspect")`、`devflow_static_runtime_context(action="inspect")`、API 契约和需求基线。
+2. 调用 `devflow_architecture_feasibility(feature=...)`。保留返回的 graph revision、static snapshot revision、触发码和未决码；不得自行改写等级。
+3. 对命中的工作负载补充 candidate：先用 `devflow_architecture_constraint` 校验，再用 `devflow_requirement_graph(action="propose")` 写入。
+   - WSH 使用 `workload_shape`，并连接 `REQ/BEH/API → WSH`，relation 为 `shapes_workload`。
+   - WLC 使用 `workload_constraint`，并连接 `BEH/SL/API → WLC`，relation 为 `constrains_workload`。
+   - `unknown` 只能写缺口、责任人、截止 checkpoint；不能填 target、evidence 或 assumption。
+4. 对 `lightweight` 或 `full` 且存在实质取舍的结果，提交 `decision_type: architecture_option_comparison` 的 `DECISION` candidate：
+   - `subject_refs` 只引用 WSH/WLC；WSH 用 `informs_decision` 连到 DECISION，WLC 用 `constrains_decision` 连到 DECISION。
+   - 每个 option 使用 `option_key`，并包含 `mechanism`、非空 `fact_refs`、非空 `tradeoffs`。
+   - `multiple_options` 至少两个机制不同的选项；没有实质替代时使用 `single_path`，不要凑 A/B/C。
+   - `recommendation_option_id` 是建议，不是自动决策。
+5. 对 `full` 评估，提交 `risk_type: architecture_option_risk` 的 `RISK` candidate，连接 `DECISION/WSH/WLC → RISK`，relation 为 `has_architecture_risk`。必须写失败模式、影响、处理、处理方式、负责人和复核条件。
+6. 只用 `devflow_requirement_graph(action="confirm")` 确认 WSH/WLC、架构 DECISION 和架构 RISK。Core 必须展示确认对话；确认方案比较时，用户确认的是显示的 `recommendation_option_id`，确认风险时只确认处理责任，不宣称生产风险已消失。
+7. 调用 `devflow_architecture_brief(action="render")` 生成 `.planning/features/{feature}/architecture-brief.md` 及 meta。不得手写或补写简报正文。
+
+## 不变量
+
+- 静态上下文只说明提交到仓库的声明/引用；不说明生产资源、健康度、容量或监控余量。
+- 数字没有 measured/contracted 证据时，保持 unknown；不得为通过检查编 QPS、DAU、数据量或阈值。
+- `assessment_status: incomplete`、`comparison_status: missing` 或 `awaiting_*` 必须原样交给下游技术方案，不能写成“评估通过”。
+- 已确认 WSH/WLC/架构 DECISION/RISK 不可原地更新；新建 candidate、重新连边，并让 stale 传播要求消费者复核。
+- 不替用户选择方案、接受残余风险或伪造 CP 记录。
+
+## 下游交接
+
+前端和后端技术方案都必须读取 `architecture-brief.md` 和 `.meta.json`，并记录消费的 `graph_revision`、`static_context_snapshot_revision`、`brief_revision`。若 brief 不是 `comparison_status: confirmed`，只可把其未决项作为前提/风险写入方案，不能把推荐项变成已决定实现。

package/plugins/devflow-design/skills/workflow-architecture-feasibility/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Architecture Feasibility"
+  short_description: "Compare architecture options from confirmed constraints."
+  default_prompt: "Use $workflow-architecture-feasibility to compare evidence-bound implementation options before technical specs."

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

@@ -13,6 +13,8 @@ user-invocable: true
 pattern: generator+tool-wrapper
 inputs:
 - .planning/features/{功能名}/api-contract.md
+- .planning/features/{功能名}/architecture-brief.md
+- .planning/features/{功能名}/architecture-brief.meta.json
 - .planning/requirements/baseline.md
 - .planning/features/{功能名}/功能点梳理.md (optional, Track B context when already available)
 - .planning/PROJECT.md
@@ -73,8 +75,9 @@ allowed-tools:
    - 影响 scope、语义、归属、兼容性或实现成本的未确认项，不得被当成已确认需求
    - 若未确认项阻塞后端方案，询问用户；`--auto` 或无法询问时写入待确认事项和风险
 7. 读取 `.planning/features/{功能名}/api-contract.md`。在双轨模式下，后端方案必须以 API 契约和需求基线作为权威输入，不得等待 Track B 的 `功能点梳理.md` 才开始。
-8. 若 `功能点梳理.md` 已存在，可作为测试可读上下文补充读取；若不存在，不阻塞 Track A。
-9. 若 baseline、api-contract 或 `功能点梳理.md` 包含 `SL-*` 切片计划，读取 `skill://workflow-pipeline/references/slice-safety-guide.md`，只为当前执行切片生成后端方案。后置切片只可作为依赖上下文或后续范围，不得生成库表、接口、任务或运行时设计。
+8. 读取 `.planning/features/{功能名}/architecture-brief.md` 和 `.meta.json`，在文档开头记录消费的 `brief_revision`、`graph_revision` 和 `static_context_snapshot_revision`。`comparison_status=confirmed` 的选择可作为实现依据；其他状态只能作为风险或待确认前提，不得把 recommendation 写成已决定实现。若 `assessment_level=full` 但未 confirmed，停止并回到架构评估。
+9. 若 `功能点梳理.md` 已存在，可作为测试可读上下文补充读取；若不存在，不阻塞 Track A。
+10. 若 baseline、api-contract 或 `功能点梳理.md` 包含 `SL-*` 切片计划，读取 `skill://workflow-pipeline/references/slice-safety-guide.md`，只为当前执行切片生成后端方案。后置切片只可作为依赖上下文或后续范围，不得生成库表、接口、任务或运行时设计。
 
 ### 第二阶段：探索现有代码
 
@@ -208,6 +211,8 @@ If an older baseline still points to root `features/{功能名}/`, treat that as
 
 ### 第五阶段：结构化元数据
 
+完成后写入 `.planning/features/{功能名}/后端技术方案.meta.json`。必须从 `architecture-brief.meta.json` 原样复制：`brief_revision → architecture_brief_revision`、`graph_revision → architecture_graph_revision`、`static_context_snapshot_revision → architecture_static_context_snapshot_revision`、`comparison_status → architecture_comparison_status`。不得凭记忆填写或改写这些值。
+
 完成后写入 `.planning/features/{功能名}/后端技术方案.meta.json`，字段定义见 `feature-development.yaml` 中 `steps[backend-tech-spec].meta_output.fields`：`api_count`, `table_count`, `migration_count`。
 
 ## 注意事项

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

@@ -14,6 +14,8 @@ pattern: generator+tool-wrapper
 inputs:
 - .planning/features/{功能名}/功能点梳理.md
 - .planning/features/{功能名}/UI-SPEC.md
+- .planning/features/{功能名}/architecture-brief.md
+- .planning/features/{功能名}/architecture-brief.meta.json
 - .planning/requirements/baseline.md
 - .planning/PROJECT.md
 - .planning/navigation/INDEX.md
@@ -72,7 +74,8 @@ allowed-tools:
    - 已确认的页面/交互/复用/替代方案决策必须进入前端方案
    - 影响 scope、交互语义、组件归属、兼容性或实现成本的未确认项，不得被当成已确认需求
    - 若未确认项阻塞前端方案，询问用户；`--auto` 或无法询问时写入待确认事项和风险
-9. 若 baseline 或 `功能点梳理.md` 包含 `SL-*` 切片计划，读取 `skill://workflow-pipeline/references/slice-safety-guide.md`，只为当前执行切片生成前端方案。后置切片只可作为依赖上下文或后续范围，不得生成路由、组件或 API 调用实现设计。
+9. 读取 `.planning/features/{功能名}/architecture-brief.md` 和 `.meta.json`，在文档开头记录消费的 `brief_revision`、`graph_revision` 和 `static_context_snapshot_revision`。只有 `comparison_status=confirmed` 的架构选择可改变请求编排、缓存、轮询或异步交互；未确认/未决项必须保留为风险或待确认事项。
+10. 若 baseline 或 `功能点梳理.md` 包含 `SL-*` 切片计划，读取 `skill://workflow-pipeline/references/slice-safety-guide.md`，只为当前执行切片生成前端方案。后置切片只可作为依赖上下文或后续范围，不得生成路由、组件或 API 调用实现设计。
 
 ### 第二阶段：探索现有前端代码
 
@@ -170,6 +173,8 @@ If an older baseline still points to root `features/{功能名}/`, treat that as
 
 完成后写入 `.planning/features/{功能名}/前端技术方案.meta.json`，字段定义见 `feature-development.yaml` 中 `steps[frontend-tech-spec].meta_output.fields`：`route_count`, `component_count`, `api_count`, `api_gaps_count`。
 
+同时必须从 `architecture-brief.meta.json` 原样复制：`brief_revision → architecture_brief_revision`、`graph_revision → architecture_graph_revision`、`static_context_snapshot_revision → architecture_static_context_snapshot_revision`、`comparison_status → architecture_comparison_status`。不得凭记忆填写或改写这些值。
+
 `api_gaps_count` 表示前端方案发现但 `api-contract.md` 未覆盖的接口缺口数量。若大于 0，必须由 `workflow-api-supplement` 处理并回写 API 契约后，才能进入 `integration-verify`。
 
 ## 注意事项