@aipper/aiws-spec 0.0.24 → 0.0.25

package/docs/workflow-governance-rules.json

@@ -0,0 +1,294 @@
+{
+  "version": 1,
+  "description": "Machine-readable governance inference rules for aiws change status/next/dashboard.",
+  "governanceRules": [
+    {
+      "id": "strict_blockers",
+      "when": { "signal": "blockers_strict_count", "gt": 0 },
+      "currentStage": "ws-plan-verify",
+      "recommendedStage": "ws-plan-verify",
+      "rationale": "strict blockers remain unresolved"
+    },
+    {
+      "id": "unchecked_tasks",
+      "when": { "signal": "tasks_unchecked", "gt": 0 },
+      "currentStage": "ws-dev",
+      "recommendedStage": "ws-dev",
+      "rationale": "{tasks_unchecked} unchecked task(s) remain"
+    },
+    {
+      "id": "finish_completed",
+      "when": { "signal": "finish_state", "eq": "done" },
+      "currentStage": "ws-finish",
+      "recommendedStage": "ws-handoff",
+      "rationale": "finish completed; archive/handoff remains"
+    },
+    {
+      "id": "finish_failed",
+      "when": { "signal": "finish_state", "eq": "failed" },
+      "currentStage": "ws-finish",
+      "recommendedStage": "ws-finish",
+      "rationale": "finish started locally but push/cleanup failed; resolve and rerun finish"
+    },
+    {
+      "id": "finish_cleanup_pending",
+      "when": { "signal": "finish_state", "eq": "cleanup_pending" },
+      "currentStage": "ws-finish",
+      "recommendedStage": "ws-finish",
+      "rationale": "push completed but cleanup is still pending ({finish_state_reason}); resolve and rerun finish"
+    },
+    {
+      "id": "finish_local",
+      "when": { "signal": "finish_state", "eq": "local" },
+      "currentStage": "ws-finish",
+      "recommendedStage": "ws-finish",
+      "rationale": "finish started locally but is not fully completed yet"
+    },
+    {
+      "id": "review_missing",
+      "when": { "signal": "review_effective_count", "eq": 0 },
+      "currentStage": "ws-review",
+      "recommendedStage": "ws-review",
+      "rationale": "deliver-ready state has no review artifact yet"
+    },
+    {
+      "id": "dual_review_incomplete",
+      "when": { "signal": "dual_review_missing_count", "gt": 0 },
+      "currentStage": "ws-review",
+      "recommendedStage": "ws-review",
+      "rationale": "dual review gate incomplete (spec={spec_review_status}, quality={quality_review_status})"
+    },
+    {
+      "id": "review_conflicted",
+      "when": { "signal": "git_conflicted", "gt": 0 },
+      "currentStage": "ws-commit",
+      "recommendedStage": "ws-commit",
+      "rationale": "review exists but the change worktree still has merge conflicts"
+    },
+    {
+      "id": "review_dirty",
+      "when": { "signal": "git_total", "gt": 0 },
+      "currentStage": "ws-commit",
+      "recommendedStage": "ws-commit",
+      "rationale": "review exists but the change worktree is still dirty"
+    },
+    {
+      "id": "deliver_finish_gate_pending_submodules",
+      "when": {
+        "all": [
+          { "signal": "repo_submodules", "gt": 0 },
+          {
+            "any": [
+              { "signal": "evidence_persistent_count", "gt": 0 },
+              { "signal": "lifecycle_evidence_runs", "gt": 0 }
+            ]
+          },
+          { "signal": "finish_gate_missing_count", "gt": 0 }
+        ]
+      },
+      "currentStage": "ws-deliver",
+      "recommendedStage": "ws-deliver",
+      "rationale": "delivery evidence exists but finish gate is incomplete (missing={finish_gate_missing_count})"
+    },
+    {
+      "id": "deliver_finish_gate_pending",
+      "when": {
+        "all": [
+          {
+            "any": [
+              { "signal": "evidence_persistent_count", "gt": 0 },
+              { "signal": "lifecycle_evidence_runs", "gt": 0 }
+            ]
+          },
+          { "signal": "finish_gate_missing_count", "gt": 0 }
+        ]
+      },
+      "currentStage": "ws-deliver",
+      "recommendedStage": "ws-deliver",
+      "rationale": "delivery evidence exists but finish gate is incomplete (missing={finish_gate_missing_count})"
+    },
+    {
+      "id": "deliver_evidence_converged_submodules",
+      "when": {
+        "all": [
+          { "signal": "repo_submodules", "gt": 0 },
+          {
+            "any": [
+              { "signal": "evidence_persistent_count", "gt": 0 },
+              { "signal": "lifecycle_evidence_runs", "gt": 0 }
+            ]
+          },
+          { "signal": "finish_gate_missing_count", "eq": 0 }
+        ]
+      },
+      "currentStage": "ws-deliver",
+      "recommendedStage": "ws-finish",
+      "rationale": "delivery evidence and finish gate are converged; next step is submodule-aware finish"
+    },
+    {
+      "id": "deliver_evidence_converged",
+      "when": {
+        "all": [
+          {
+            "any": [
+              { "signal": "evidence_persistent_count", "gt": 0 },
+              { "signal": "lifecycle_evidence_runs", "gt": 0 }
+            ]
+          },
+          { "signal": "finish_gate_missing_count", "eq": 0 }
+        ]
+      },
+      "currentStage": "ws-deliver",
+      "recommendedStage": "ws-finish",
+      "rationale": "delivery evidence and finish gate are converged; next step is safe finish"
+    },
+    {
+      "id": "deliver_evidence_pending_submodules",
+      "when": { "signal": "repo_submodules", "gt": 0 },
+      "currentStage": "ws-deliver",
+      "recommendedStage": "ws-deliver",
+      "rationale": "submodule-aware delivery/evidence convergence is still required"
+    },
+    {
+      "id": "deliver_evidence_pending",
+      "when": {},
+      "currentStage": "ws-deliver",
+      "recommendedStage": "ws-deliver",
+      "rationale": "delivery evidence is still required before finish"
+    }
+  ],
+  "guidanceRules": [
+    {
+      "id": "guidance_plan_verify",
+      "when": { "signal": "governance_current_stage", "eq": "ws-plan-verify" },
+      "lines": [
+        "先修复 strict blockers，再复跑 `aiws change validate <id> --strict`"
+      ]
+    },
+    {
+      "id": "guidance_dev",
+      "when": { "signal": "governance_current_stage", "eq": "ws-dev" },
+      "lines": [
+        "继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）"
+      ]
+    },
+    {
+      "id": "guidance_review",
+      "when": { "signal": "governance_current_stage", "eq": "ws-review" },
+      "lines": [
+        "进入审计：在 AI 工具中运行 `$ws-review`（形成 review 结论后再进入提交/交付）"
+      ]
+    },
+    {
+      "id": "guidance_review_spec_missing",
+      "when": { "signal": "spec_review_ready", "falsy": true },
+      "lines": [
+        "补齐流程审查：运行 `$ws-spec-review`，并落盘 `changes/<change-id>/review/spec-review.md`"
+      ]
+    },
+    {
+      "id": "guidance_review_quality_missing",
+      "when": { "signal": "quality_review_ready", "falsy": true },
+      "lines": [
+        "补齐质量审查：运行 `$ws-quality-review`，并落盘 `changes/<change-id>/review/quality-review.md`"
+      ]
+    },
+    {
+      "id": "guidance_commit",
+      "when": { "signal": "governance_current_stage", "eq": "ws-commit" },
+      "lines": [
+        "进入提交门：在 AI 工具中运行 `$ws-commit`（review + validate stamp + commit message 确认）"
+      ]
+    },
+    {
+      "id": "guidance_commit_stage_scope",
+      "when": {
+        "all": [
+          { "signal": "governance_current_stage", "eq": "ws-commit" },
+          { "signal": "git_staged", "eq": 0 }
+        ]
+      },
+      "lines": [
+        "进入 `$ws-commit` 前，先明确 staging 范围（例如 `git add <path>` 或 `git add -p`）"
+      ]
+    },
+    {
+      "id": "guidance_deliver",
+      "when": { "signal": "governance_current_stage", "eq": "ws-deliver" },
+      "lines": [
+        "进入交付收敛：在 AI 工具中运行 `$ws-deliver`（证据收敛 + submodule 感知提交）"
+      ]
+    },
+    {
+      "id": "guidance_deliver_validate_missing",
+      "when": {
+        "all": [
+          { "signal": "governance_current_stage", "eq": "ws-deliver" },
+          { "signal": "validate_stamp_ready", "falsy": true }
+        ]
+      },
+      "lines": [
+        "补齐 validate stamp：运行 `aiws validate . --stamp`"
+      ]
+    },
+    {
+      "id": "guidance_deliver_verify_before_complete_missing",
+      "when": {
+        "all": [
+          { "signal": "governance_current_stage", "eq": "ws-deliver" },
+          { "signal": "verify_before_complete_ready", "falsy": true }
+        ]
+      },
+      "lines": [
+        "补齐完成前 gate：运行 `$ws-verify-before-complete`，并落盘 `changes/<change-id>/evidence/verify-before-complete.md`"
+      ]
+    },
+    {
+      "id": "guidance_deliver_finish",
+      "when": {
+        "all": [
+          { "signal": "governance_current_stage", "eq": "ws-deliver" },
+          { "signal": "governance_recommended_stage", "eq": "ws-finish" }
+        ]
+      },
+      "lines": [
+        "交付工件齐全后，进入 `$ws-finish`（安全合并 + push + cleanup）"
+      ]
+    },
+    {
+      "id": "guidance_finish_cleanup_pending",
+      "when": { "signal": "governance_rule_id", "eq": "finish_cleanup_pending" },
+      "lines": [
+        "push 已完成，但 cleanup 仍未完成（{finish_state_reason}）；清理对应 worktree 后重跑 `$ws-finish`"
+      ]
+    },
+    {
+      "id": "guidance_finish_handoff",
+      "when": { "signal": "governance_rule_id", "eq": "finish_completed" },
+      "lines": [
+        "收尾已完成：下一步运行 `$ws-handoff`，并归档 change"
+      ]
+    },
+    {
+      "id": "guidance_finish_retry",
+      "when": { "signal": "governance_rule_id", "in": ["finish_failed", "finish_local"] },
+      "lines": [
+        "收尾未完整完成：检查 push / cleanup / submodule 状态后重跑 `$ws-finish`"
+      ]
+    },
+    {
+      "id": "guidance_handoff",
+      "when": { "signal": "governance_current_stage", "eq": "ws-handoff" },
+      "lines": [
+        "进入交接：在 AI 工具中运行 `$ws-handoff`，并生成/检查归档 handoff"
+      ]
+    },
+    {
+      "id": "guidance_default",
+      "when": { "signal": "governance_current_stage", "eq": "" },
+      "lines": [
+        "按阶段契约继续推进当前 change"
+      ]
+    }
+  ]
+}

package/docs/workflow-governance-rules.md

@@ -0,0 +1,63 @@
+# workflow-governance-rules
+
+<!-- Generated from packages/spec/docs/workflow-governance-rules.json by scripts/sync-workflow-governance-rules.mjs. Do not hand edit. -->
+
+## 目的
+
+这份文档描述 `aiws change status` / `change next` / dashboard 共用的阶段推断规则真值。
+运行时应读取 `workflow-governance-rules.json`；本文件保留为人类可读说明。
+
+## 概览
+
+- version: `1`
+- description: Machine-readable governance inference rules for aiws change status/next/dashboard.
+- governance rules: 16
+- guidance rules: 16
+
+## 阶段推断规则
+
+| Rule ID | Match | Current | Next | Rationale |
+| --- | --- | --- | --- | --- |
+| `strict_blockers` | `blockers_strict_count` > 0 | `ws-plan-verify` | `ws-plan-verify` | strict blockers remain unresolved |
+| `unchecked_tasks` | `tasks_unchecked` > 0 | `ws-dev` | `ws-dev` | {tasks_unchecked} unchecked task(s) remain |
+| `finish_completed` | `finish_state` == `done` | `ws-finish` | `ws-handoff` | finish completed; archive/handoff remains |
+| `finish_failed` | `finish_state` == `failed` | `ws-finish` | `ws-finish` | finish started locally but push/cleanup failed; resolve and rerun finish |
+| `finish_cleanup_pending` | `finish_state` == `cleanup_pending` | `ws-finish` | `ws-finish` | push completed but cleanup is still pending ({finish_state_reason}); resolve and rerun finish |
+| `finish_local` | `finish_state` == `local` | `ws-finish` | `ws-finish` | finish started locally but is not fully completed yet |
+| `review_missing` | `review_effective_count` == `0` | `ws-review` | `ws-review` | deliver-ready state has no review artifact yet |
+| `dual_review_incomplete` | `dual_review_missing_count` > 0 | `ws-review` | `ws-review` | dual review gate incomplete (spec={spec_review_status}, quality={quality_review_status}) |
+| `review_conflicted` | `git_conflicted` > 0 | `ws-commit` | `ws-commit` | review exists but the change worktree still has merge conflicts |
+| `review_dirty` | `git_total` > 0 | `ws-commit` | `ws-commit` | review exists but the change worktree is still dirty |
+| `deliver_finish_gate_pending_submodules` | (`repo_submodules` > 0) AND ((`evidence_persistent_count` > 0) OR (`lifecycle_evidence_runs` > 0)) AND (`finish_gate_missing_count` > 0) | `ws-deliver` | `ws-deliver` | delivery evidence exists but finish gate is incomplete (missing={finish_gate_missing_count}) |
+| `deliver_finish_gate_pending` | ((`evidence_persistent_count` > 0) OR (`lifecycle_evidence_runs` > 0)) AND (`finish_gate_missing_count` > 0) | `ws-deliver` | `ws-deliver` | delivery evidence exists but finish gate is incomplete (missing={finish_gate_missing_count}) |
+| `deliver_evidence_converged_submodules` | (`repo_submodules` > 0) AND ((`evidence_persistent_count` > 0) OR (`lifecycle_evidence_runs` > 0)) AND (`finish_gate_missing_count` == `0`) | `ws-deliver` | `ws-finish` | delivery evidence and finish gate are converged; next step is submodule-aware finish |
+| `deliver_evidence_converged` | ((`evidence_persistent_count` > 0) OR (`lifecycle_evidence_runs` > 0)) AND (`finish_gate_missing_count` == `0`) | `ws-deliver` | `ws-finish` | delivery evidence and finish gate are converged; next step is safe finish |
+| `deliver_evidence_pending_submodules` | `repo_submodules` > 0 | `ws-deliver` | `ws-deliver` | submodule-aware delivery/evidence convergence is still required |
+| `deliver_evidence_pending` | (default) | `ws-deliver` | `ws-deliver` | delivery evidence is still required before finish |
+
+## Guidance 规则
+
+| Rule ID | Match | Guidance |
+| --- | --- | --- |
+| `guidance_plan_verify` | `governance_current_stage` == `ws-plan-verify` | 先修复 strict blockers，再复跑 `aiws change validate <id> --strict` |
+| `guidance_dev` | `governance_current_stage` == `ws-dev` | 继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证） |
+| `guidance_review` | `governance_current_stage` == `ws-review` | 进入审计：在 AI 工具中运行 `$ws-review`（形成 review 结论后再进入提交/交付） |
+| `guidance_review_spec_missing` | `spec_review_ready` is falsy | 补齐流程审查：运行 `$ws-spec-review`，并落盘 `changes/<change-id>/review/spec-review.md` |
+| `guidance_review_quality_missing` | `quality_review_ready` is falsy | 补齐质量审查：运行 `$ws-quality-review`，并落盘 `changes/<change-id>/review/quality-review.md` |
+| `guidance_commit` | `governance_current_stage` == `ws-commit` | 进入提交门：在 AI 工具中运行 `$ws-commit`（review + validate stamp + commit message 确认） |
+| `guidance_commit_stage_scope` | (`governance_current_stage` == `ws-commit`) AND (`git_staged` == `0`) | 进入 `$ws-commit` 前，先明确 staging 范围（例如 `git add <path>` 或 `git add -p`） |
+| `guidance_deliver` | `governance_current_stage` == `ws-deliver` | 进入交付收敛：在 AI 工具中运行 `$ws-deliver`（证据收敛 + submodule 感知提交） |
+| `guidance_deliver_validate_missing` | (`governance_current_stage` == `ws-deliver`) AND (`validate_stamp_ready` is falsy) | 补齐 validate stamp：运行 `aiws validate . --stamp` |
+| `guidance_deliver_verify_before_complete_missing` | (`governance_current_stage` == `ws-deliver`) AND (`verify_before_complete_ready` is falsy) | 补齐完成前 gate：运行 `$ws-verify-before-complete`，并落盘 `changes/<change-id>/evidence/verify-before-complete.md` |
+| `guidance_deliver_finish` | (`governance_current_stage` == `ws-deliver`) AND (`governance_recommended_stage` == `ws-finish`) | 交付工件齐全后，进入 `$ws-finish`（安全合并 + push + cleanup） |
+| `guidance_finish_cleanup_pending` | `governance_rule_id` == `finish_cleanup_pending` | push 已完成，但 cleanup 仍未完成（{finish_state_reason}）；清理对应 worktree 后重跑 `$ws-finish` |
+| `guidance_finish_handoff` | `governance_rule_id` == `finish_completed` | 收尾已完成：下一步运行 `$ws-handoff`，并归档 change |
+| `guidance_finish_retry` | `governance_rule_id` in [`finish_failed`, `finish_local`] | 收尾未完整完成：检查 push / cleanup / submodule 状态后重跑 `$ws-finish` |
+| `guidance_handoff` | `governance_current_stage` == `ws-handoff` | 进入交接：在 AI 工具中运行 `$ws-handoff`，并生成/检查归档 handoff |
+| `guidance_default` | `governance_current_stage` == `` | 按阶段契约继续推进当前 change |
+
+## 说明
+
+- 规则按数组顺序匹配，先命中者优先。
+- `governance.ruleId` 应对应上表中的 `Rule ID`，便于状态诊断。
+- 若需要补充背景说明，请编辑 JSON 真值，再重新生成本文件。

package/docs/workflow-governance-rules.schema.json

@@ -0,0 +1,182 @@
+{
+  "type": "object",
+  "required": ["version", "description", "governanceRules", "guidanceRules"],
+  "properties": {
+    "version": { "type": "integer" },
+    "description": { "type": "string", "minLength": 1 },
+    "governanceRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "when", "currentStage", "recommendedStage", "rationale"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "when": { "$ref": "#/$defs/condition" },
+          "currentStage": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" },
+          "recommendedStage": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" },
+          "rationale": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "guidanceRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "when", "lines"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "when": { "$ref": "#/$defs/condition" },
+          "lines": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "condition": {
+      "anyOf": [
+        {
+          "type": "object",
+          "maxProperties": 0,
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["all"],
+          "properties": {
+            "all": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/condition" }
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["any"],
+          "properties": {
+            "any": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/condition" }
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["not"],
+          "properties": {
+            "not": { "$ref": "#/$defs/condition" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "eq"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "eq": {}
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "ne"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "ne": {}
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "gt"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "gt": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "gte"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "gte": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "lt"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "lt": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "lte"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "lte": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "in"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "in": {
+              "type": "array",
+              "minItems": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "notIn"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "notIn": {
+              "type": "array",
+              "minItems": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "truthy"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "truthy": { "type": "boolean", "const": true }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["signal", "falsy"],
+          "properties": {
+            "signal": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+            "falsy": { "type": "boolean", "const": true }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

package/docs/workflow-review-gates.json

@@ -0,0 +1,72 @@
+{
+  "version": 1,
+  "title": "workflow-review-gates",
+  "description": "Machine-readable dual-review and pre-complete verification gates for aiws.",
+  "purpose": [
+    "这份文档把 `ws-review` 进一步拆成可复用的 review gate：一类检查 workflow/spec/gate 是否完整，一类检查实现质量与回归风险。",
+    "同时增加完成前验证 gate，避免只有 review 文件存在，却没有 validate stamp、交付证据或 finish 前检查的伪完成状态。"
+  ],
+  "gates": [
+    {
+      "id": "spec_review",
+      "name": "ws-spec-review",
+      "stage": "review",
+      "focus": "requirements 归因、plan/change 绑定、证据路径、流程 gate 与危险操作边界",
+      "mustRead": "AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md；plan/...；changes/<change-id>/...",
+      "mustWrite": "changes/<change-id>/review/spec-review.md（无法识别 change 时回退 .agentdocs/tmp/review/spec-review.md）",
+      "blockers": "无法定位真值文件；无法确认变更归因；无法写 review 证据",
+      "exitCriteria": "已给出流程/真值层 blockers、scope/gate 问题与最小修复建议",
+      "next": "ws-quality-review 或修复后重审"
+    },
+    {
+      "id": "quality_review",
+      "name": "ws-quality-review",
+      "stage": "review",
+      "focus": "行为回归、边界条件、测试覆盖、实现质量、可维护性",
+      "mustRead": "git diff；验证结果；相关代码/配置；已有 review/analysis/patches 工件",
+      "mustWrite": "changes/<change-id>/review/quality-review.md（无法识别 change 时回退 .agentdocs/tmp/review/quality-review.md）",
+      "blockers": "没有可审改动；没有验证上下文；无法写 review 证据",
+      "exitCriteria": "已给出高优先级缺陷/风险、测试缺口和最小验证建议",
+      "next": "ws-verify-before-complete 或修复后重审"
+    },
+    {
+      "id": "verify_before_complete",
+      "name": "ws-verify-before-complete",
+      "stage": "finish_gate",
+      "focus": "finish / handoff 前检查 review、validate、evidence 与 completion gate 是否齐全",
+      "mustRead": "changes/<change-id>/review/...；.agentdocs/tmp/aiws-validate/*.json；changes/<change-id>/evidence/...；git status",
+      "mustWrite": "changes/<change-id>/evidence/verify-before-complete.md（无法识别 change 时回退 .agentdocs/tmp/review/verify-before-complete.md）",
+      "blockers": "缺少 spec review；缺少 quality review；缺少 validate stamp；存在未关闭 blocker",
+      "exitCriteria": "已明确 pass/fail、缺失项与是否可进入 ws-finish / ws-handoff",
+      "next": "ws-finish / ws-handoff 或回退前置 gate"
+    }
+  ],
+  "unifiedRules": [
+    "spec review 与 quality review 关注点不同；不能用单一 review 文件同时替代两者而不明确区分。",
+    "双审查的最小要求是留下两份可审计 review 证据，而不是口头说“已经 review 过”。",
+    "verify-before-complete 不负责替代 finish；它只负责判断是否已经具备进入 finish / handoff 的前置条件。",
+    "若 review 结论里仍有 blocker，则不得把状态表述为 ready-to-finish。"
+  ],
+  "evidence": [
+    {
+      "label": "spec review",
+      "value": "changes/<change-id>/review/spec-review.md"
+    },
+    {
+      "label": "quality review",
+      "value": "changes/<change-id>/review/quality-review.md"
+    },
+    {
+      "label": "validate stamp",
+      "value": ".agentdocs/tmp/aiws-validate/*.json"
+    },
+    {
+      "label": "pre-complete summary",
+      "value": "changes/<change-id>/evidence/verify-before-complete.md"
+    }
+  ],
+  "notes": [
+    "`ws-review` 仍保留为通用评审入口；在高风险或准备 finish 的任务里，应进一步细化到 `ws-spec-review` + `ws-quality-review`。",
+    "这份真值当前主要服务 skill/command 文案和人工 gate；后续若需要，再由 dashboard 或 validate 消费。"
+  ]
+}

package/docs/workflow-review-gates.md

@@ -0,0 +1,36 @@
+# workflow-review-gates
+
+<!-- Generated from packages/spec/docs/workflow-review-gates.json by scripts/sync-workflow-review-gates.mjs. Do not hand edit. -->
+
+## 目的
+
+这份文档把 `ws-review` 进一步拆成可复用的 review gate：一类检查 workflow/spec/gate 是否完整，一类检查实现质量与回归风险。
+
+同时增加完成前验证 gate，避免只有 review 文件存在，却没有 validate stamp、交付证据或 finish 前检查的伪完成状态。
+
+## Gate 表
+
+| Gate | Stage | Focus | Must Read | Must Write | Blockers | Exit | Next |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `ws-spec-review` | review | requirements 归因、plan/change 绑定、证据路径、流程 gate 与危险操作边界 | AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md；plan/...；changes/<change-id>/... | changes/<change-id>/review/spec-review.md（无法识别 change 时回退 .agentdocs/tmp/review/spec-review.md） | 无法定位真值文件；无法确认变更归因；无法写 review 证据 | 已给出流程/真值层 blockers、scope/gate 问题与最小修复建议 | ws-quality-review 或修复后重审 |
+| `ws-quality-review` | review | 行为回归、边界条件、测试覆盖、实现质量、可维护性 | git diff；验证结果；相关代码/配置；已有 review/analysis/patches 工件 | changes/<change-id>/review/quality-review.md（无法识别 change 时回退 .agentdocs/tmp/review/quality-review.md） | 没有可审改动；没有验证上下文；无法写 review 证据 | 已给出高优先级缺陷/风险、测试缺口和最小验证建议 | ws-verify-before-complete 或修复后重审 |
+| `ws-verify-before-complete` | finish_gate | finish / handoff 前检查 review、validate、evidence 与 completion gate 是否齐全 | changes/<change-id>/review/...；.agentdocs/tmp/aiws-validate/*.json；changes/<change-id>/evidence/...；git status | changes/<change-id>/evidence/verify-before-complete.md（无法识别 change 时回退 .agentdocs/tmp/review/verify-before-complete.md） | 缺少 spec review；缺少 quality review；缺少 validate stamp；存在未关闭 blocker | 已明确 pass/fail、缺失项与是否可进入 ws-finish / ws-handoff | ws-finish / ws-handoff 或回退前置 gate |
+
+## 统一规则
+
+- spec review 与 quality review 关注点不同；不能用单一 review 文件同时替代两者而不明确区分。
+- 双审查的最小要求是留下两份可审计 review 证据，而不是口头说“已经 review 过”。
+- verify-before-complete 不负责替代 finish；它只负责判断是否已经具备进入 finish / handoff 的前置条件。
+- 若 review 结论里仍有 blocker，则不得把状态表述为 ready-to-finish。
+
+## 证据约定
+
+- spec review：changes/<change-id>/review/spec-review.md
+- quality review：changes/<change-id>/review/quality-review.md
+- validate stamp：.agentdocs/tmp/aiws-validate/*.json
+- pre-complete summary：changes/<change-id>/evidence/verify-before-complete.md
+
+## 说明
+
+- `ws-review` 仍保留为通用评审入口；在高风险或准备 finish 的任务里，应进一步细化到 `ws-spec-review` + `ws-quality-review`。
+- 这份真值当前主要服务 skill/command 文案和人工 gate；后续若需要，再由 dashboard 或 validate 消费。