@aipper/aiws-spec 0.0.23 → 0.0.25

package/docs/workflow-review-gates.schema.json

@@ -0,0 +1,67 @@
+{
+  "type": "object",
+  "required": [
+    "version",
+    "title",
+    "description",
+    "purpose",
+    "gates",
+    "unifiedRules",
+    "evidence",
+    "notes"
+  ],
+  "properties": {
+    "version": { "type": "integer" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "purpose": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "gates": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "stage", "focus", "mustRead", "mustWrite", "blockers", "exitCriteria", "next"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "name": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" },
+          "stage": { "type": "string", "minLength": 1 },
+          "focus": { "type": "string", "minLength": 1 },
+          "mustRead": { "type": "string", "minLength": 1 },
+          "mustWrite": { "type": "string", "minLength": 1 },
+          "blockers": { "type": "string", "minLength": 1 },
+          "exitCriteria": { "type": "string", "minLength": 1 },
+          "next": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "unifiedRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["label", "value"],
+        "properties": {
+          "label": { "type": "string", "minLength": 1 },
+          "value": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "notes": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "additionalProperties": false
+}

package/docs/workflow-router-rules.json

@@ -0,0 +1,196 @@
+{
+  "version": 1,
+  "title": "workflow-router-rules",
+  "description": "Machine-readable bootstrap/router rules for the aiws default workflow entry.",
+  "purpose": [
+    "这份文档把 `using-aiws` / `ws-router` 的路由规则收口为机器可读真值，避免不同工具各自发明“先做什么”的入口逻辑。",
+    "重点不是自动执行控制器，而是强制任何 coding task 先读真值文件、先判定 workflow，再进入具体 `ws-*` skill。"
+  ],
+  "truthFiles": [
+    "AI_PROJECT.md",
+    "REQUIREMENTS.md",
+    "AI_WORKSPACE.md"
+  ],
+  "bootstrapEntry": {
+    "name": "using-aiws",
+    "kind": "skill",
+    "summary": "默认 workflow bootstrap/router：先读真值，再把任务路由到正确的 `ws-*` 入口。",
+    "outputContract": [
+      "Root / Found / Missing",
+      "Task intent / Binding status / Route",
+      "Why / Next"
+    ]
+  },
+  "universalSequence": [
+    {
+      "step": "read_truths",
+      "action": "先定位项目根，并读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。",
+      "why": "router 不能绕过真值文件，否则会把 workflow 判断建立在会话猜测上。"
+    },
+    {
+      "step": "classify_intent",
+      "action": "判断当前任务是在做需求变更、实现、评审、收尾还是交接。",
+      "why": "先判 workflow，再决定进入哪个 skill；不能一开始就跳进实现。"
+    },
+    {
+      "step": "check_binding",
+      "action": "检查任务是否具备 `Req_ID` / `Problem_ID` / change 上下文 / Verify 入口等最小绑定。",
+      "why": "缺失绑定时必须阻断或回退到 `ws-plan`，避免无归因实现。"
+    },
+    {
+      "step": "route_or_clarify",
+      "action": "给出单一路由结果；若意图不明确，则先问关键澄清问题并停止。",
+      "why": "default-routed workflow 的关键不是自动执行，而是避免模糊任务直接进入实现。"
+    }
+  ],
+  "routingRules": [
+    {
+      "id": "missing_truths",
+      "intent": "仓库未初始化或真值缺失",
+      "match": "缺失任一真值文件，或无法确定项目根目录。",
+      "routeTo": "ws-preflight",
+      "gate": "先补齐真值或确认项目根，不进入实现。",
+      "rationale": "所有后续 skill 都依赖真值文件；缺失时 router 只能回退到 preflight/init 路径。"
+    },
+    {
+      "id": "unclear_intent",
+      "intent": "用户目标、归因或验收不清晰",
+      "match": "无法明确当前是需求变更、实现、评审、finish 还是 handoff；或无法明确 `Req_ID` / `Problem_ID` / Verify。",
+      "routeTo": "clarify",
+      "gate": "必须先问 1-3 个关键澄清问题，然后停止。",
+      "rationale": "router 的职责是阻断模糊任务，而不是用猜测替代路由。"
+    },
+    {
+      "id": "requirements_change",
+      "intent": "需求/验收/合同变更",
+      "match": "任务涉及 `REQUIREMENTS.md`、requirements CSV、spec contract、验收标准或 workflow 真值变更。",
+      "routeTo": "ws-req-review",
+      "gate": "先做需求评审，再决定是否进入 `ws-plan` / `ws-dev`。",
+      "rationale": "需求真值变更必须先过 review，不能直接编码。"
+    },
+    {
+      "id": "review_request",
+      "intent": "审计/评审/找风险",
+      "match": "用户明确要求 review、audit、评审、找 bug、识别风险或检查回归。",
+      "routeTo": "ws-review",
+      "gate": "先给 findings；除非用户另行要求，不先改代码。",
+      "rationale": "评审任务与实现任务的输出契约不同，必须优先走 review。"
+    },
+    {
+      "id": "finish_request",
+      "intent": "收尾/合并/推送/cleanup",
+      "match": "用户要求 finish、merge、push、收尾、交付完成、清理 worktree 或 branch。",
+      "routeTo": "ws-finish",
+      "gate": "必须满足 finish gate，不能跳过 validate / push / cleanup。",
+      "rationale": "finish 是独立治理阶段，不能与普通实现混用。"
+    },
+    {
+      "id": "handoff_request",
+      "intent": "交接/归档总结",
+      "match": "用户要求 handoff、交接说明、archive summary、会话总结或接力说明。",
+      "routeTo": "ws-handoff",
+      "gate": "先确认 change 已 finish 或 archive 上下文存在。",
+      "rationale": "handoff 依赖已有证据与归档上下文，不应在实现前触发。"
+    },
+    {
+      "id": "plan_first",
+      "intent": "中大型实现或需要建立 change 上下文",
+      "match": "任务是多步实现、跨文件、跨模块、需要方案、需要新建 change/worktree，或当前还没有计划工件。",
+      "routeTo": "ws-plan",
+      "gate": "plan 过 gate 前不进入 `ws-dev`。",
+      "rationale": "medium/complex 任务必须先生成可落盘计划，避免 router 直接跳进实现。"
+    },
+    {
+      "id": "direct_implementation",
+      "intent": "小步实现/修复/配置调整",
+      "match": "目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。",
+      "routeTo": "ws-dev",
+      "gate": "若执行中发现复杂度升高，必须回退到 `ws-plan`。",
+      "rationale": "router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门。"
+    }
+  ],
+  "routeCases": [
+    {
+      "id": "case_missing_truths",
+      "scenario": "仓库未初始化或真值缺失时，不能直接开始实现。",
+      "request": "在一个还没执行 aiws init 的仓库里继续开发这个功能。",
+      "expectedRuleId": "missing_truths",
+      "expectedRoute": "ws-preflight",
+      "why": "缺失真值文件时只能先补齐 preflight/init 路径。"
+    },
+    {
+      "id": "case_unclear_continue",
+      "scenario": "用户只说继续，但没有明确当前 change、归因或验证入口。",
+      "request": "继续。",
+      "expectedRuleId": "unclear_intent",
+      "expectedRoute": "clarify",
+      "why": "这种场景必须先澄清意图和绑定，不能猜测实现。"
+    },
+    {
+      "id": "case_requirements_change",
+      "scenario": "任务要修改 REQUIREMENTS、requirements CSV 或 workflow 真值。",
+      "request": "更新 REQUIREMENTS.md 和 requirements/requirements-issues.csv，补充验收标准。",
+      "expectedRuleId": "requirements_change",
+      "expectedRoute": "ws-req-review",
+      "why": "需求真值变更必须先做需求评审。"
+    },
+    {
+      "id": "case_review_request",
+      "scenario": "用户明确要求 review、审计、找风险或检查回归。",
+      "request": "review 这批改动，先给我风险和回归点，不要先改代码。",
+      "expectedRuleId": "review_request",
+      "expectedRoute": "ws-review",
+      "why": "评审任务的输出契约是 findings，不应直接进入实现。"
+    },
+    {
+      "id": "case_finish_request",
+      "scenario": "用户要求合并、push、cleanup 或 finish 当前 change。",
+      "request": "把 demo-change finish 掉并 push，顺便 cleanup worktree。",
+      "expectedRuleId": "finish_request",
+      "expectedRoute": "ws-finish",
+      "why": "finish 是独立治理阶段，必须先走 finish gate。"
+    },
+    {
+      "id": "case_handoff_request",
+      "scenario": "用户要求 handoff、交接说明、archive summary 或接力文档。",
+      "request": "给这个 change 写 handoff，并补 archive summary。",
+      "expectedRuleId": "handoff_request",
+      "expectedRoute": "ws-handoff",
+      "why": "handoff 依赖已有 finish/archive 上下文，不能当成普通实现。"
+    },
+    {
+      "id": "case_plan_first",
+      "scenario": "任务是跨文件、多步实现，且需要先建立 change/worktree 或方案。",
+      "request": "实现 dashboard 的阶段治理视图并补测试，需要新建 change 和计划。",
+      "expectedRuleId": "plan_first",
+      "expectedRoute": "ws-plan",
+      "why": "中大型实现应先落盘计划，再进入 dev。"
+    },
+    {
+      "id": "case_direct_implementation",
+      "scenario": "任务是小步明确修复，归因和验证入口都已清楚。",
+      "request": "修复 codex install-skills 的默认路径，并补一条可复现回归。",
+      "expectedRuleId": "direct_implementation",
+      "expectedRoute": "ws-dev",
+      "why": "小步明确实现允许直接进入 dev，但仍保留回退到 plan 的门。"
+    }
+  ],
+  "clarificationTriggers": [
+    "用户只说“继续”“优化一下”“看一下”，但没有明确目标对象或当前阶段。",
+    "无法把任务绑定到 `Req_ID` / `Problem_ID` / change 上下文。",
+    "没有可复现验证入口，且无法从 `AI_WORKSPACE.md` 推断。",
+    "当前描述同时包含需求变更、实现和收尾，但没有明确优先级。"
+  ],
+  "universalRules": [
+    "router 自己不是实现阶段；先判定 workflow，再进入具体 `ws-*` skill。",
+    "除缺失真值场景外，router 至少要给出一个明确的 `Route:` 结果或明确的澄清问题。",
+    "当 `routeTo=clarify` 时，必须停止，不直接写代码。",
+    "当 `routeTo=ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` 时，后续行为必须遵循对应 skill 契约。",
+    "任何 route 都不能绕过 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。"
+  ],
+  "notes": [
+    "default-routed workflow 不等于 daemon / pane / runtime orchestration；这一版只固定真值和入口。",
+    "`using-aiws` 可以作为默认入口；若未来需要更短命名，可再引入 `ws-router` 作为等价别名。",
+    "Claude/OpenCode/Codex 的 native 目录不同，但 router 语义必须共用同一份 JSON 真值。"
+  ]
+}

package/docs/workflow-router-rules.md

@@ -0,0 +1,83 @@
+# workflow-router-rules
+
+<!-- Generated from packages/spec/docs/workflow-router-rules.json by scripts/sync-workflow-router-rules.mjs. Do not hand edit. -->
+
+## 目的
+
+这份文档把 `using-aiws` / `ws-router` 的路由规则收口为机器可读真值，避免不同工具各自发明“先做什么”的入口逻辑。
+
+重点不是自动执行控制器，而是强制任何 coding task 先读真值文件、先判定 workflow，再进入具体 `ws-*` skill。
+
+## 真值入口
+
+router 在做任何 workflow 判断前，必须先读取：
+
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+
+## Bootstrap Entry
+
+- name: `using-aiws`
+- kind: `skill`
+- summary: 默认 workflow bootstrap/router：先读真值，再把任务路由到正确的 `ws-*` 入口。
+- output contract:
+  - Root / Found / Missing
+  - Task intent / Binding status / Route
+  - Why / Next
+
+## 通用顺序
+
+| Step | Action | Why |
+| --- | --- | --- |
+| `read_truths` | 先定位项目根，并读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。 | router 不能绕过真值文件，否则会把 workflow 判断建立在会话猜测上。 |
+| `classify_intent` | 判断当前任务是在做需求变更、实现、评审、收尾还是交接。 | 先判 workflow，再决定进入哪个 skill；不能一开始就跳进实现。 |
+| `check_binding` | 检查任务是否具备 `Req_ID` / `Problem_ID` / change 上下文 / Verify 入口等最小绑定。 | 缺失绑定时必须阻断或回退到 `ws-plan`，避免无归因实现。 |
+| `route_or_clarify` | 给出单一路由结果；若意图不明确，则先问关键澄清问题并停止。 | default-routed workflow 的关键不是自动执行，而是避免模糊任务直接进入实现。 |
+
+## 路由规则
+
+| Rule ID | Intent | Match | Route | Gate | Rationale |
+| --- | --- | --- | --- | --- | --- |
+| `missing_truths` | 仓库未初始化或真值缺失 | 缺失任一真值文件，或无法确定项目根目录。 | `ws-preflight` | 先补齐真值或确认项目根，不进入实现。 | 所有后续 skill 都依赖真值文件；缺失时 router 只能回退到 preflight/init 路径。 |
+| `unclear_intent` | 用户目标、归因或验收不清晰 | 无法明确当前是需求变更、实现、评审、finish 还是 handoff；或无法明确 `Req_ID` / `Problem_ID` / Verify。 | `clarify` | 必须先问 1-3 个关键澄清问题，然后停止。 | router 的职责是阻断模糊任务，而不是用猜测替代路由。 |
+| `requirements_change` | 需求/验收/合同变更 | 任务涉及 `REQUIREMENTS.md`、requirements CSV、spec contract、验收标准或 workflow 真值变更。 | `ws-req-review` | 先做需求评审，再决定是否进入 `ws-plan` / `ws-dev`。 | 需求真值变更必须先过 review，不能直接编码。 |
+| `review_request` | 审计/评审/找风险 | 用户明确要求 review、audit、评审、找 bug、识别风险或检查回归。 | `ws-review` | 先给 findings；除非用户另行要求，不先改代码。 | 评审任务与实现任务的输出契约不同，必须优先走 review。 |
+| `finish_request` | 收尾/合并/推送/cleanup | 用户要求 finish、merge、push、收尾、交付完成、清理 worktree 或 branch。 | `ws-finish` | 必须满足 finish gate，不能跳过 validate / push / cleanup。 | finish 是独立治理阶段，不能与普通实现混用。 |
+| `handoff_request` | 交接/归档总结 | 用户要求 handoff、交接说明、archive summary、会话总结或接力说明。 | `ws-handoff` | 先确认 change 已 finish 或 archive 上下文存在。 | handoff 依赖已有证据与归档上下文，不应在实现前触发。 |
+| `plan_first` | 中大型实现或需要建立 change 上下文 | 任务是多步实现、跨文件、跨模块、需要方案、需要新建 change/worktree，或当前还没有计划工件。 | `ws-plan` | plan 过 gate 前不进入 `ws-dev`。 | medium/complex 任务必须先生成可落盘计划，避免 router 直接跳进实现。 |
+| `direct_implementation` | 小步实现/修复/配置调整 | 目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。 | `ws-dev` | 若执行中发现复杂度升高，必须回退到 `ws-plan`。 | router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门。 |
+
+## Route Cases
+
+| Case ID | Scenario | Request | Expected Rule | Expected Route | Why |
+| --- | --- | --- | --- | --- | --- |
+| `case_missing_truths` | 仓库未初始化或真值缺失时，不能直接开始实现。 | 在一个还没执行 aiws init 的仓库里继续开发这个功能。 | `missing_truths` | `ws-preflight` | 缺失真值文件时只能先补齐 preflight/init 路径。 |
+| `case_unclear_continue` | 用户只说继续，但没有明确当前 change、归因或验证入口。 | 继续。 | `unclear_intent` | `clarify` | 这种场景必须先澄清意图和绑定，不能猜测实现。 |
+| `case_requirements_change` | 任务要修改 REQUIREMENTS、requirements CSV 或 workflow 真值。 | 更新 REQUIREMENTS.md 和 requirements/requirements-issues.csv，补充验收标准。 | `requirements_change` | `ws-req-review` | 需求真值变更必须先做需求评审。 |
+| `case_review_request` | 用户明确要求 review、审计、找风险或检查回归。 | review 这批改动，先给我风险和回归点，不要先改代码。 | `review_request` | `ws-review` | 评审任务的输出契约是 findings，不应直接进入实现。 |
+| `case_finish_request` | 用户要求合并、push、cleanup 或 finish 当前 change。 | 把 demo-change finish 掉并 push，顺便 cleanup worktree。 | `finish_request` | `ws-finish` | finish 是独立治理阶段，必须先走 finish gate。 |
+| `case_handoff_request` | 用户要求 handoff、交接说明、archive summary 或接力文档。 | 给这个 change 写 handoff，并补 archive summary。 | `handoff_request` | `ws-handoff` | handoff 依赖已有 finish/archive 上下文，不能当成普通实现。 |
+| `case_plan_first` | 任务是跨文件、多步实现，且需要先建立 change/worktree 或方案。 | 实现 dashboard 的阶段治理视图并补测试，需要新建 change 和计划。 | `plan_first` | `ws-plan` | 中大型实现应先落盘计划，再进入 dev。 |
+| `case_direct_implementation` | 任务是小步明确修复，归因和验证入口都已清楚。 | 修复 codex install-skills 的默认路径，并补一条可复现回归。 | `direct_implementation` | `ws-dev` | 小步明确实现允许直接进入 dev，但仍保留回退到 plan 的门。 |
+
+## 必须先澄清的情形
+
+- 用户只说“继续”“优化一下”“看一下”，但没有明确目标对象或当前阶段。
+- 无法把任务绑定到 `Req_ID` / `Problem_ID` / change 上下文。
+- 没有可复现验证入口，且无法从 `AI_WORKSPACE.md` 推断。
+- 当前描述同时包含需求变更、实现和收尾，但没有明确优先级。
+
+## 统一规则
+
+- router 自己不是实现阶段；先判定 workflow，再进入具体 `ws-*` skill。
+- 除缺失真值场景外，router 至少要给出一个明确的 `Route:` 结果或明确的澄清问题。
+- 当 `routeTo=clarify` 时，必须停止，不直接写代码。
+- 当 `routeTo=ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` 时，后续行为必须遵循对应 skill 契约。
+- 任何 route 都不能绕过 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
+
+## 说明
+
+- default-routed workflow 不等于 daemon / pane / runtime orchestration；这一版只固定真值和入口。
+- `using-aiws` 可以作为默认入口；若未来需要更短命名，可再引入 `ws-router` 作为等价别名。
+- Claude/OpenCode/Codex 的 native 目录不同，但 router 语义必须共用同一份 JSON 真值。

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

@@ -0,0 +1,119 @@
+{
+  "type": "object",
+  "required": [
+    "version",
+    "title",
+    "description",
+    "purpose",
+    "truthFiles",
+    "bootstrapEntry",
+    "universalSequence",
+    "routingRules",
+    "routeCases",
+    "clarificationTriggers",
+    "universalRules",
+    "notes"
+  ],
+  "properties": {
+    "version": { "type": "integer" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "purpose": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "truthFiles": {
+      "type": "array",
+      "minItems": 3,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "bootstrapEntry": {
+      "type": "object",
+      "required": ["name", "kind", "summary", "outputContract"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9-]+$" },
+        "kind": { "type": "string", "minLength": 1, "enum": ["skill", "command"] },
+        "summary": { "type": "string", "minLength": 1 },
+        "outputContract": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "universalSequence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["step", "action", "why"],
+        "properties": {
+          "step": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "action": { "type": "string", "minLength": 1 },
+          "why": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "routingRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "intent", "match", "routeTo", "gate", "rationale"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "intent": { "type": "string", "minLength": 1 },
+          "match": { "type": "string", "minLength": 1 },
+          "routeTo": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(clarify|ws-[a-z0-9-]+)$"
+          },
+          "gate": { "type": "string", "minLength": 1 },
+          "rationale": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "routeCases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "scenario", "request", "expectedRuleId", "expectedRoute", "why"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "pattern": "^case_[a-z0-9_]+$" },
+          "scenario": { "type": "string", "minLength": 1 },
+          "request": { "type": "string", "minLength": 1 },
+          "expectedRuleId": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "expectedRoute": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(clarify|ws-[a-z0-9-]+)$"
+          },
+          "why": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "clarificationTriggers": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "universalRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "notes": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "additionalProperties": false
+}

package/docs/workflow-stage-contracts.json

@@ -0,0 +1,148 @@
+{
+  "version": 1,
+  "title": "workflow-stage-contracts",
+  "description": "Machine-readable workflow stage contracts for aiws ws-* stages.",
+  "purpose": [
+    "这份文档把 `aiws` 核心 `ws-*` workflow 的阶段契约写成统一真值，避免不同工具、不同协作者把同一个入口用成不同语义。",
+    "重点不是“命令名长什么样”，而是每个阶段必须收什么输入、产出什么结果、在什么情况下必须停止。"
+  ],
+  "standardChain": [
+    "ws-preflight",
+    "ws-plan",
+    "ws-plan-verify",
+    "ws-dev",
+    "ws-review",
+    "ws-commit",
+    "ws-deliver",
+    "ws-finish",
+    "ws-handoff"
+  ],
+  "notes": [
+    "ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。",
+    "ws-finish 用于 fast-forward 合并、push 和 worktree cleanup。",
+    "ws-handoff 通常在 archive 后使用，为下一次会话留下交接说明。",
+    "若存在独立 change worktree，治理信号应优先读取该 worktree；若 worktree metadata 已 stale，则降级为 warning 并回退到当前 worktree。"
+  ],
+  "stages": [
+    {
+      "stage": "ws-preflight",
+      "goal": "对齐真值文件与协作约束",
+      "requiredInputs": "项目根；AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md",
+      "requiredOutputs": "Root / Found / Missing / Key rules / Next",
+      "blockers": "无法确定项目根；真值缺失",
+      "next": "ws-plan 或 ws-dev"
+    },
+    {
+      "stage": "ws-plan",
+      "goal": "建立 change 绑定并落盘计划",
+      "requiredInputs": "任务描述；真值文件；proposal.md（若存在）",
+      "requiredOutputs": "plan/...；Bindings；Verify；Risks；Evidence；Next",
+      "blockers": "绑定不清；dirty 工作区无法安全建 context；无法写盘",
+      "next": "ws-plan-verify"
+    },
+    {
+      "stage": "ws-plan-verify",
+      "goal": "检查计划是否满足严格契约",
+      "requiredInputs": "plan/...；proposal.md；当前 change",
+      "requiredOutputs": "Quality gate；Fix list；可执行最小计划摘要",
+      "blockers": "strict 校验失败；无法定位 change",
+      "next": "修计划后重跑或进入 ws-dev"
+    },
+    {
+      "stage": "ws-dev",
+      "goal": "实施最小改动并验证",
+      "requiredInputs": "真值文件；归因目标；计划（medium/complex）",
+      "requiredOutputs": "Changed；Verify；Evidence；Next",
+      "blockers": "无法归因；没有验证入口；change 上下文不安全",
+      "next": "ws-review / ws-commit"
+    },
+    {
+      "stage": "ws-review",
+      "goal": "审计规范、风险与验证完整性",
+      "requiredInputs": "当前 diff；验证结果；真值文件",
+      "requiredOutputs": "review 文件；Top risks；Next",
+      "blockers": "无改动可审；无法写审计证据",
+      "next": "ws-commit 或修复后重审"
+    },
+    {
+      "stage": "ws-commit",
+      "goal": "串联 review、validate、commit 确认",
+      "requiredInputs": "staged diff；review 证据；validate stamp；用户确认的 message",
+      "requiredOutputs": "Evidence；Context；Commit",
+      "blockers": "无 staged changes；submodule dirty；validate 失败；message 未确认",
+      "next": "ws-deliver / ws-finish"
+    },
+    {
+      "stage": "ws-deliver",
+      "goal": "在 submodule 场景下完成顺序提交与证据收敛",
+      "requiredInputs": "change 上下文；.gitmodules；submodules.targets；各 repo 状态",
+      "requiredOutputs": "submodule 提交摘要；superproject 提交摘要；Evidence",
+      "blockers": "submodule 真值不完整；不在正确 change；commit 未确认",
+      "next": "ws-finish"
+    },
+    {
+      "stage": "ws-finish",
+      "goal": "安全合并、push、cleanup",
+      "requiredInputs": "干净工作区；已提交的 change；push 目标；submodule 真值（若有）",
+      "requiredOutputs": "Merge；Push；Worktree cleanup；Evidence",
+      "blockers": "dirty 工作区；ff 失败；submodule 无法安全 push",
+      "next": "ws-handoff 或 archive"
+    },
+    {
+      "stage": "ws-handoff",
+      "goal": "生成可接力的归档交接说明",
+      "requiredInputs": "已归档或待归档的 change",
+      "requiredOutputs": "changes/archive/.../handoff.md；Next",
+      "blockers": "无法定位 change；archive 失败；handoff 无法生成",
+      "next": "新 change 通过 Depends_On 接力"
+    }
+  ],
+  "unifiedRules": [
+    "每个阶段都必须回指真值文件或 change 工件，不能只依赖会话上下文。",
+    "每个阶段都必须有明确输出，不能只给“建议继续”而不留下工件或证据。",
+    "遇到阻断条件时必须停止，不能为了推进速度跳过门禁。",
+    "如果一个阶段没有留下可审计路径，它就不算真正完成。",
+    "`ws-finish` 只有在 merge、push、cleanup 都完成后才算完成；仅本地 merge 成功不等于可进入 `ws-handoff`。"
+  ],
+  "evidence": {
+    "intro": "最少证据集合：",
+    "minimum": [
+      {
+        "label": "planning",
+        "value": "`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`"
+      },
+      {
+        "label": "review",
+        "value": "`changes/<change-id>/review/...` 或 `.agentdocs/tmp/review/...`"
+      },
+      {
+        "label": "validate",
+        "value": "`.agentdocs/tmp/aiws-validate/*.json`"
+      },
+      {
+        "label": "deliver / finish",
+        "value": "`changes/<change-id>/evidence/...`、`state`、merge / push 结果"
+      },
+      {
+        "label": "handoff",
+        "value": "`changes/archive/.../handoff.md`"
+      }
+    ],
+    "notes": [
+      "tmp review 证据可以作为“进入 commit gate”的临时治理信号，但在交付前应通过 `aiws change evidence` 收敛为持久 review 证据。",
+      "finish 生命周期建议区分“本地开始”和“完整完成”两类信号，避免仅凭本地 merge 就误导到 handoff。"
+    ]
+  },
+  "positioning": {
+    "intro": "这份阶段契约文档是 `aiws` “治理内核”定位的直接落点：",
+    "layers": [
+      "`packages/spec/` 继续作为规则真值层",
+      "`ws-*` 阶段契约是工作流治理层",
+      "`docs/workflow-stage-contracts.json` 是运行时阶段契约的机器可读真值",
+      "`docs/workflow-governance-rules.json` 是运行时阶段推断的机器可读真值",
+      "CLI / tool-native files 是执行与分发层",
+      "review / validate / handoff 等工件属于证据与审计层"
+    ],
+    "closing": "如果未来要吸收新的 skill、协同角色或外部 workflow，优先判断它能否被映射到这张阶段表；不能稳定映射的能力，不应直接成为核心真值。"
+  }
+}