@hupan56/wlkj 3.1.3 → 3.1.5

package/templates/qoder/contracts/isolation.md

@@ -0,0 +1,119 @@
+# 隔离与并发安全契约（ISOLATION）
+
+> 回答团队最关心的三个问题：**我能不能改到别人的任务？同步会不会覆盖别人的工作？禅道同步会不会拉错/推错？**
+> 本文件是这些保证的**单一事实源**。实现见 `task_utils.py` / `team_sync.py` / `syncgate.py`。
+
+---
+
+## TL;DR（给 PM 的 3 句话）
+
+1. **本地任务**：你只能改自己创建/被指派的任务，别人的任务 ACL 直接拒绝（返回 4）——改不到。
+2. **team_sync 同步**：push 只暂存白名单路径（workspace/data/docs/data/index）+ 安全扩展名，pull 用 autostash 保护你的本地改动——正常不丢不覆盖。
+3. **禅道同步**：禅道是**团队共享账号**，server 层不区分谁在操作 → **必须靠 assignedTo 归属过滤**，否则会拉到/覆盖队友任务。见下文「禅道同步」红线。
+
+---
+
+## 一、本地任务隔离（已实现，强保证）
+
+### 1.1 任务存储：团队共享 + 字段隔离
+
+- 任务文件 `workspace/tasks/{MM-DD-slug}/task.json` 是**团队共享目录**，push 后全队可见。
+- 隔离**不靠物理分目录**，靠 task.json 里的 `creator` / `assignee` 字段 + ACL 校验。
+- 真正「个人隔离」的只有：个人草稿产出（`workspace/members/{dev}/`）、活跃任务指针（`.runtime/current-task.{dev}` 按开发者命名）、私有凭证（`.private/`）。
+
+### 1.2 ACL：谁能改一个任务
+
+| 操作 | 谁能做 |
+|------|--------|
+| create（新建） | 任何人（新任务归属创建者，assignee 默认=创建者） |
+| start / finish / archive / reassign / set-due / block / 子任务 | **仅** `creator ∪ assignee ∪ admin` |
+| list / 查看所有人任务 | 任何人（产品要看全局排期）；`--mine` 才过滤只看自己 |
+
+- 实现：`task_utils.py` `assert_can_modify_task`。非归属人操作一律返回退出码 **4（权限拒绝）**。
+- 所有变更命令都过此校验：`task_lifecycle.py`（create 除外）/ `task_relations.py` 全部写操作。
+
+### 1.3 并发读改写：每任务一把锁
+
+- `modify_task_json` 在文件锁 `task_dir/.task.lock` 内完成 load→改→write，**原子**。
+- 锁竞争超时**不降级为无锁写**——宁可失败也不丢更新。
+- 写入是原子操作（temp 文件 + `os.replace`），最坏情况是「半写」，不会产生损坏的 JSON。
+- **结论**：两个 PM 同时改同一个任务的不同字段（一个改 status、一个改 due）→ 不丢更新。
+
+### 1.4 已知边界（低风险，记录在案）
+
+- `archive`（整目录移动）与并发写同一任务：ACL 先挡非归属人；归属人之间的极端时序靠 OS 文件系统兜底，最坏是「改完的内容随目录进了 archive」，不损坏但可能「以为没生效」。
+- `list`（无 `--mine`）能看到所有人的任务——这是**有意设计**（产品看全局），不是隔离漏洞。
+
+---
+
+## 二、team_sync 同步（已实现，强保证）
+
+### 2.1 push：只推白名单 + 安全扩展名 + 串行锁
+
+- **路径白名单**（`SYNC_SCOPES`）：只 `workspace` / `data/docs` / `data/index` 三个 scope。
+- **扩展名白名单**（`SAFE_EXTENSIONS`）：仅 `.md .html .json .jsonl .yaml .yml .toml .txt .csv .svg`。`.env .zip .docx` 等一律拒绝并打印跳过警告。
+- **绝不** `git add -A`；改为逐 scope + 扩展名过滤的批量 add（每批 400 个）。
+- **全局串行锁** `team-sync.lock`（push 与 pull 共用），同一时刻只有一个同步在跑。
+- **零信任门禁**（commit 前）：身份强制 + git 作者与注册身份一致 + 秘密扫描 + REQ-ID 撞号校验 + 平台标注 + EVA 质量门禁（≥80%）。任一失败 `git reset HEAD` 撤销暂存。
+
+> 各人产出在 `members/{自己}/` 物理隔离：A push 会把 `members/B/` 也推上去，但路径不冲突，不会覆盖 B 的内容。
+
+### 2.2 pull：autostash 保护本地改动 + 冲突安全回退
+
+- `git pull --rebase --autostash`：本地未提交改动先 stash，rebase 完再 pop——**正常不丢**。
+- 冲突时（`SYNC_CONFLICT` 标记 + 退出码 3）：自动 `git rebase --abort` + 尝试恢复 stash + 输出 6 步 AI 指南。**绝不要求用户自己跑 git**（CRITICAL RULE #3）。
+- `kg.duckdb` 二进制冲突有专门自动解决（取 `built_at` 更新的版本）。
+
+### 2.3 已知边界
+
+- `--autostash` 的 stash pop 本身也可能冲突（典型：两个 PM 同日改同一份共享索引）。此情况**数据不丢**（还在 stash 里），但需 AI/人工介入 `git stash pop`。
+- 没有「本地有未提交改动就先警告再 pull」的预检——直接 autostash，靠 git 兜底。
+
+---
+
+## 三、禅道同步（共享账号 — 红线区，需重点遵守）
+
+> ⚠️ 禅道 MCP 是**团队共享账号**（`.qoder/config.yaml` 的 `zentao.user`），server 层无法区分「这次操作是哪个本地开发者发起的」。
+> 这是拉错/推错风险的**唯一来源**。
+
+### 3.1 红线（违反 = 可能污染/覆盖队友）
+
+| 方向 | 红线 | 正确做法 |
+|------|------|---------|
+| 拉取（禅道→本地） | ❌ 直接 `list_execution_tasks` 不过滤 → 拉到全队任务写进本地 | ✅ **强制** `assignedTo == 当前开发者禅道账号` 过滤 |
+| 推送（本地→禅道） | ❌ 批量盲推 create/update → 覆盖同名队友任务 | ✅ **默认 `--dry-run`** + 仅推 `creator==我` 的 + 禅道同名任务 assignedTo 须一致才更新 |
+| create | ❌ 用共享账号把任务派给别人 | ✅ 强制 `assignedTo = 当前开发者` |
+| 幂等 | ❌ 重复 create 同一任务 | ✅ task.json 的 `zentao_id` 字段做主键，已有则跳过 |
+
+### 3.2 归属字段对照（实现 zentao_sync 的依据）
+
+| 字段 | 用途 | 能否区分「我的 vs 别人的」 |
+|------|------|------------------------|
+| `assignedTo`（指派人） | 禅道任务核心归属字段 | ✅ **最可靠，拉取主过滤以此为准** |
+| `openedBy`（创建人） | 谁建的（改派后不变） | ⚠️ 辅助，语义不同 |
+| `account` | 工时记录字段（list_effort） | ❌ 不是任务归属，别用 |
+
+### 3.3 本地 developer ↔ 禅道 account 映射
+
+- 本地 developer 名（如 `hupan56`）与禅道 account（如 `hupan`）**不一致**，需映射表。
+- 映射存于 member 注册信息（`zentao_account` 字段）。同步前先解析当前 developer → 禅道 account，再用 account 做过滤。
+- **无映射 = 拒绝同步**（宁可不同步也不猜，避免拉错）。
+
+---
+
+## 四、违反契约的症状与自检
+
+| 症状 | 含义 | 自检/恢复 |
+|------|------|----------|
+| 退出码 **4** | ACL 权限拒绝 | 你不是该任务的 creator/assignee/admin，确认是否选错任务 |
+| 退出码 **3（SYNC_CONFLICT）** | 同步冲突 | AI 接 `team_sync.py` 输出的 6 步指南解决，无需用户碰 git |
+| 退出码 **2（SYNC_BUSY）** | 同步锁竞争 | 等 5 分钟（stale_seconds=300）或确认无其它同步在跑 |
+| `task.json.corrupt.<ts>` 出现 | task.json 曾损坏 | 已自动备份，原文件清空等重建；查 stderr 告警定位原因 |
+
+---
+
+## 五、修改本契约的规则
+
+- 本文件描述的保证**靠代码实现**（`task_utils.py` ACL/锁、`team_sync.py` 同步、`syncgate.py` 门禁、`zentao_sync.py` 归属过滤）。
+- 若改了相关代码的行为，**必须同步更新本文件**，否则契约与实现脱节。
+- 新增任何「多人共享数据」的操作（新命令、新脚本），都必须在本文件登记其隔离机制。

package/templates/qoder/contracts/prd.md

@@ -0,0 +1,118 @@
+# 模块契约：prd（需求）
+
+> 产品模块。从「一句话」到「可发布的 PRD + 原型」。
+> 这是**最上游的契约源**，下游 design/spec/task/test 都靠它。
+
+---
+
+## Input（吃什么）
+
+| 优先级 | 输入 | 怎么用 |
+|--------|------|--------|
+| **完整** | 业务需求描述 + 平台 | `context_pack.py <词> --platform <web\|app>` 取上下文 |
+| 降级 1 | 只有业务描述，没指定平台 | **必须先问平台**（见铁律），不许跳过 |
+| 降级 2 ★ | 用户一句话口语需求 | 跑 context_pack + search_index --prd 自补上下文 |
+| 参考 | 现有页面 / 字段 / API | 来自 context_pack 的 7 段输出，不强依赖 |
+
+**平台是硬约束**：Web=fywl-ui / APP=Carmg-H5 / both。没定平台不许开干。
+
+---
+
+## Output（吐什么）
+
+### 主产物：PRD 草稿
+
+```
+路径：workspace/members/{developer}/drafts/REQ-{YYYY}-{NNN}-{标题}.md
+命名：REQ-ID 由 common/reqid.py 的 allocate_req_id() 原子分配
+```
+
+**第一行必须是契约头**（软契约，缺了只警告）：
+
+```markdown
+<!-- @contract prd v1
+platform: web|app|both
+req-id: REQ-2025-0042
+title: 保单批改功能
+mode: full|quick|reference|brainstorm|planning
+# brainstorm/planning 已随探索能力迁至 /wl-insight，PRD 不再主动产出这两个模式。
+# 保留枚举是为了向后兼容旧 PRD（eval_prd 仍能识别）。新 PRD 只用 quick/reference。
+acceptance: [验收点1, 验收点2]
+source: context_pack:保单批改,web
+-->
+```
+
+### 副产物：原型
+
+```
+单端：workspace/members/{developer}/drafts/prototype-{feature}.html
+两端：...prototype-{feature}-web.html + ...prototype-{feature}-app.html
+```
+
+### 归档（自动）
+
+```
+归档副本：workspace/members/{dev}/archive/{YYYY-MM-DD}/REQ-*.md（只复制不移动）
+```
+
+### 发布
+
+```
+发布后：git_sync.py 的 collect_prds() 把草稿拷到 data/docs/prd/REQ-*.md（立刻可搜）
+```
+
+---
+
+## 必含字段骨架
+
+### full 模式（完整需求）— 13 章
+
+版本信息 / 变更日志 / 名词解释 / 需求背景 / 需求来源 / 产品现状 /
+需求范围 / 功能清单 / 字段规格 / 操作与校验 / 非功能性需求 / 埋点 / 版本计划
+
+> **"版本计划"章节边界**：只写**本期排期**（本需求何时上线）。
+> 长期 roadmap / 多版本路线图已归 `/wl-insight plan`，不在 PRD 内展开。
+> PRD 聚焦"本次做什么"，不背"未来规划"的职责。
+
+### quick 模式（零星需求）— 6 章
+
+功能入口 / 需求背景 / 需求说明 / 影响范围 / 验收标准 / 不在本次范围
+
+> quick 模式整体跳过 EVA 门禁（用于快速出稿，不背完整质量责任）。
+
+---
+
+## 校验（唯一硬门禁）
+
+```bash
+python .qoder/scripts/orchestration/wlkj.py eval <prd.md> [原型.html]
+```
+
+| 维度 | 权重 | 检查内容 |
+|------|------|----------|
+| A1 现实锚定 | 40 分 | PRD 表格内 camelCase 字段、API 路径在索引命中比例 |
+| A2 风格保真 | 30 分 | 原型颜色来自真源（无原型则跳过，满分降为 70） |
+| A3 模板完整 | 30 分 | 章节齐全比例 |
+
+**阈值：≥ 80% 才 PASS**（`PASS_THRESHOLD = 80.0`）。结果追加到 `data/learning/eval-history.jsonl`。
+
+> full 模式无原型时满分 70，实际过线需 `A1+A3 ≥ 56`。
+> **这是整个工作流唯一的硬门禁**——因为 prd 是契约源头，源头不靠谱全链路歪。
+
+---
+
+## 与下游的接口
+
+| 下游模块 | 消费 prd 的什么 |
+|----------|----------------|
+| design | 验收标准里的界面相关点 + 平台 |
+| task | 功能清单 → 拆任务 |
+| spec | 全文，尤其是字段规格 + 操作校验 |
+| test | `acceptance` 列表 → 测试用例 |
+
+---
+
+## 现状提醒
+
+- ✅ eval_prd.py 已存在，校验可跑。
+- ⚠️ quick 模式跳过 EVA，可能产出质量较低的契约。下游拿到 quick PRD 时应留意。

package/templates/qoder/contracts/schemas/design-spec.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "qoder://contract/design-spec",
+  "title": "Design Spec 契约 (设计师规格)",
+  "description": "设计师从 Figma/Axure 录入的规格。优先级 > 代码风格 > PDF 规范。最适合 schema 化的契约 (纯 JSON 产物)。",
+  "type": "object",
+  "required": ["_contract", "design_tokens", "layout", "components"],
+  "properties": {
+    "_contract": {
+      "type": "object",
+      "required": ["type", "version", "platform", "requirement"],
+      "properties": {
+        "type": { "const": "design-spec" },
+        "version": { "type": "integer", "minimum": 1 },
+        "platform": { "type": "string", "enum": ["web", "app", "both"] },
+        "requirement": { "type": "string", "description": "关联的需求名/REQ-ID" },
+        "source": { "type": "string", "description": "figma:截图 / lanhu:链接" }
+      }
+    },
+    "design_tokens": {
+      "type": "object",
+      "description": "配色/尺寸/字体/圆角等设计令牌",
+      "properties": {
+        "colors": { "type": "object" },
+        "spacing": { "type": "object" },
+        "fonts": { "type": "object" },
+        "radius": { "type": "object" }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "description": "页面布局结构 (栅格/区块/导航)"
+    },
+    "components": {
+      "type": "array",
+      "description": "组件清单 (类型/props/状态)",
+      "items": { "type": "object" }
+    },
+    "icons": {
+      "type": "array",
+      "description": "图标清单 (禁止 emoji, web=AntDesign SVG / app=Vant)",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/qoder/contracts/schemas/prd.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "qoder://contract/prd",
+  "title": "PRD 契约 (产品需求文档)",
+  "description": "PRD 是最上游的契约源。下游 design/spec/task/test 都靠它。机器可校验版。",
+  "type": "object",
+  "required": ["type", "version", "req-id", "platform", "title", "acceptance"],
+  "properties": {
+    "type": { "const": "prd", "description": "契约类型标识" },
+    "version": { "type": "integer", "minimum": 1, "description": "契约版本, 未来演进用 (当前 v1)" },
+    "req-id": {
+      "type": "string",
+      "pattern": "^REQ-\\d{4}-\\d{3,}$",
+      "description": "需求编号, 贯穿全链路唯一 key, 由 reqid.py 原子分配"
+    },
+    "platform": {
+      "type": "string",
+      "enum": ["web", "app", "both"],
+      "description": "目标平台: web=fywl-ui / app=Carmg-H5 / both=两端"
+    },
+    "title": { "type": "string", "minLength": 2, "description": "需求标题" },
+    "acceptance": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "验收标准列表, 下游 test 据此生成用例"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["quick", "reference", "brainstorm", "planning"],
+      "description": "生成模式 (quick 零星需求, reference 完整档)"
+    },
+    "source": { "type": "string", "description": "来源: context_pack:词,平台 / manual" }
+  },
+  "additionalProperties": true
+}

package/templates/qoder/contracts/schemas/test-cases.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "qoder://contract/test-cases",
+  "title": "Test Cases 契约 (测试用例集)",
+  "description": "从 PRD acceptance 或手动生成的测试用例。autotest 强依赖其结构。",
+  "type": "object",
+  "required": ["_contract", "cases"],
+  "properties": {
+    "_contract": {
+      "type": "object",
+      "required": ["type", "version"],
+      "properties": {
+        "type": { "const": "test-cases" },
+        "version": { "type": "integer", "minimum": 1 },
+        "platform": { "type": "string", "enum": ["web", "app", "both"] },
+        "req-id": {
+          "type": "string",
+          "pattern": "^REQ-\\d{4}-\\d{3,}$",
+          "description": "关联需求 (可空, 测试用例可能跨需求)"
+        }
+      }
+    },
+    "cases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "intent"],
+        "properties": {
+          "name": { "type": "string", "description": "用例名" },
+          "intent": { "type": "string", "description": "测试意图/验收点" },
+          "anchor": { "type": "string", "description": "页面锚点 (定位用)" },
+          "steps": { "type": "array", "items": { "type": "string" } },
+          "expected": { "type": "string" }
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/qoder/contracts/spec.md

@@ -0,0 +1,81 @@
+# 模块契约：spec（技术规格）
+
+> 规格模块。把 PRD 翻译成开发能照着写的**技术契约**。
+> 是 code 模块的最佳输入。
+
+---
+
+## Input（吃什么）
+
+| 优先级 | 输入 | 怎么用 |
+|--------|------|--------|
+| **完整** | 一份已确认的 PRD（`data/docs/prd/REQ-*.md`） | 字段规格 + 操作校验 → 接口/数据结构 |
+| 降级 1 | PRD 草稿（`drafts/REQ-*.md`） | 也能写 spec，标 `source: draft` |
+| 参考 | 历史 Spec | `workspace/specs/` 看同类写法 |
+| 参考 | 字段命名 | `search_index.py --field <字段名>` |
+| 参考 | 数据字典 | `.qoder/context/data-dictionary.md`（不存在则跳过） |
+
+**团队技术约定（写进 spec 的默认约束）**：
+- 后端 Java：MyBatis Plus + RESTful + `BigDecimal` 金额 + JSR-303 校验 + `Result<T>`
+- 表名 `t_{module}_{entity}`，全栈 Entity→Mapper→Service→Controller
+- 不写 PRD 未定义的功能
+
+---
+
+## Output（吐什么）
+
+### 主产物：Spec 文件
+
+```
+路径：workspace/specs/REQ-{ID}-{module}.spec.md
+     （或任务目录 workspace/tasks/{task-id}/spec.md）
+命名：★ 统一为 REQ-{ID}-{module}.spec.md
+```
+
+**契约头**：
+
+```markdown
+<!-- @contract spec v1
+source-req: REQ-2025-0042
+platform: web
+module: policy
+endpoints: [POST /api/policy/amend, GET /api/policy/amend/{id}]
+-->
+```
+
+### 骨架
+
+每条 PRD 验收标准 → 映射一个 Spec 测试用例。必须包含：
+
+- 接口定义（路径 / 方法 / 入参 / 出参 / 错误码）
+- 数据结构（表 / 字段 / 类型 / 约束）
+- 边界与异常处理
+- 与 PRD 验收标准的映射表
+
+---
+
+## 校验
+
+- ❌ **无独立校验脚本**（待建）。
+- 软契约：缺 `source-req` 只警告。
+- review 模式（带 `review` 参数）只给改进建议，不重生成。
+
+---
+
+## 与上下游的接口
+
+| 方向 | 接口 |
+|------|------|
+| 上游 prd | 读 PRD 验收标准 + 字段规格 |
+| 下游 code | spec 是 code 的最佳输入 |
+| 下游 test | spec 的测试用例映射 → 单元测试 |
+
+---
+
+## ⚠️ 现状提醒（KNOWN GAP）
+
+- **文件命名两处 skill 不一致**：
+  - `spec-generator/SKILL.md` 写 `REQ-{ID}-{module}.spec.md`
+  - `wl-spec/SKILL.md` 写 `spec-{REQ-ID}-{desc}.md`
+- **契约统一为 `REQ-{ID}-{module}.spec.md`**（与 prd 的 REQ-ID 命名一致，便于贯穿检索）。
+- 待修正 `wl-spec/SKILL.md` 的输出路径声明。

package/templates/qoder/contracts/task.md

@@ -0,0 +1,125 @@
+# 模块契约：task（任务）
+
+> 任务模块。把 PRD 拆成可执行任务 + RICE 排优先级。
+> task.json 是本模块的**唯一事实源**。
+
+---
+
+## Input（吃什么）
+
+| 优先级 | 输入 | 怎么用 |
+|--------|------|--------|
+| **完整** | 一份 PRD（`REQ-*.md`） | 功能清单 → 拆任务 |
+| 降级 1 | PRD 草稿（drafts 里的） | 也能拆，只是还没发布 |
+| 降级 2 | 一句话任务描述 | 直接 `task.py create "XXX"` |
+| 参考 | 已有任务 | `task.py list` 看排期，避免重复 |
+
+不强依赖 prd 模块执行——可以直接手动建任务。
+
+---
+
+## Output（吐什么）
+
+### 任务目录
+
+```
+路径：workspace/tasks/{MM-DD-slug}/
+内含：
+  task.json         ← 任务元数据 + 状态 + RICE
+  prd.md            ← 任务级需求（可空）
+  implement.jsonl   ← 实现记录
+  check.jsonl       ← 检查记录
+```
+
+### task.json 骨架（对齐 task.py 真实输出）
+
+```json
+{
+  "title": "...",
+  "slug": "baodan-piGai",
+  "status": "planning",           // planning → in_progress → completed（归档时再补 archived_at）
+  "priority": "P0|P1|P2|P3",
+  "assignee": "{developer}",       // ← 注意是 assignee 不是 owner
+  "creator": "{developer}",
+  "created_at": "...", "updated_at": "...",
+  "branch": null, "base_branch": null,
+  "scope": null,
+  "parent": null, "children": [],  // 父子任务
+  "tags": ["REQ-2026-0042"],       // ← PRD 的 REQ-ID 记这里（双向追溯）
+  "rice": 24,                      // ← RICE 排序时 AI 算好后写入（数值，不是对象）
+  // 能力增强字段（可选，旧 task.json 不含时取默认值）
+  "due_date": "2026-07-01",        // YYYY-MM-DD（set-due 写）
+  "start_date": null,
+  "estimate_hours": null,
+  "blocked_by": [],                // 被哪些任务阻塞（block 写，自动维护反向 blocks）
+  "blocks": [],                    // 被哪些任务依赖（自动维护）
+  "stage_ts": { "created": "...", "started": null, "completed": null },
+  "zentao_id": null                // 对应禅道任务 ID（zentao_sync 写）。幂等主键: 已有则跳过 create。
+                                   //   隔离契约见 contracts/isolation.md「禅道同步」。
+}
+```
+
+> ⚠️ 字段名以 **task.py 实际输出**为准（`assignee`/`planning`/`completed`/`rice` 为数值）。
+> 上面是权威骨架，与 task.py 的 `cmd_create` 逐字段对齐。
+
+### 状态流转
+
+```
+create(planning) → start → in_progress → finish → completed → archive
+```
+
+**关键动作都会自动 stage workspace/tasks/ 到 team_sync**（push 后团队可见）。
+
+---
+
+## 操作命令
+
+```bash
+# 基础生命周期
+python .qoder/scripts/task.py create "XXX" [--slug ...] [--assignee ...] [--priority P0|P1|P2|P3]
+python .qoder/scripts/task.py list [--mine] [--status in_progress] [--ready] [--blocked]
+python .qoder/scripts/task.py show <task-dir>
+python .qoder/scripts/task.py start <task-dir>      # planning → in_progress，设为活跃任务
+python .qoder/scripts/task.py current [--source]    # 看当前活跃任务
+python .qoder/scripts/task.py finish                 # 活跃任务 → completed，清活跃指针
+python .qoder/scripts/task.py archive <task-dir>     # 移到 .qoder/archive/{YYYY-MM}/，自动清孤儿依赖
+
+# 子任务
+python .qoder/scripts/task.py add-subtask <parent> <child>
+python .qoder/scripts/task.py remove-subtask <parent> <child>
+
+# 排期与依赖（B2 能力）
+python .qoder/scripts/task.py set-due <task> <YYYY-MM-DD>
+python .qoder/scripts/task.py block <task> <blocker>     # 循环依赖自动检测，反向 blocks 自动维护
+python .qoder/scripts/task.py unblock <task> <blocker>
+python .qoder/scripts/task.py gantt [--weeks 4]          # 只排有日期的任务，自动标逾期
+```
+
+**退出码**：`0`=成功 / `1`=任务不存在/JSON 缺失/循环依赖 / `4`=权限不足（零信任 ACL，仅 creator/assignee/admin 可改）。
+
+**RICE** = Reach × Impact × Confidence ÷ Effort（AI 层评估，算好后写入 task.json 的 `rice` 数值字段）
+
+---
+
+## 校验
+
+- ❌ **无独立校验脚本**。当前靠 task.py 自身的状态机约束。
+- 软契约：task.json 缺 `_contract` / `acceptance` 只警告不拦。
+
+---
+
+## 与上下游的接口
+
+| 方向 | 接口 |
+|------|------|
+| 上游 prd | 读 PRD 的功能清单 → 拆任务 |
+| 下游 spec/code | 任务目录可放 `spec.md`（spec 模块写到任务目录时） |
+
+---
+
+## 现状提醒
+
+- ✅ task.py 功能完整：CRUD + 依赖图（block/unblock + 循环检测）+ 排期（set-due/gantt）+ 子任务 + 零信任 ACL + 归档孤儿依赖清理。
+- ✅ PRD→task 衔接：create 时把 REQ-ID 记进 `tags`，PRD 验收点贴进 task 的 `prd.md`（命令层引导）。
+- ✅ RICE 排序在 AI 层（task.py 只存数值，不替 AI 算分）。
+- 🧩 QoderWork 增强（可选）：待办双向同步。无连接器则回退，task.json 仍为准。