aitable-workflow-cli 0.1.28 → 0.1.29-beta.1790736949347

package/templates/ai-native-sdlc/docs/plans/2026-09-15-ai-native-sdlc-dual-staff.md

@@ -0,0 +1,213 @@
+# AI Native SDLC 双数字员工协作台 SPEC
+
+## 背景
+
+本项目在一台机器上运行一个单实例 aitable-workflow 服务。PM 与 Dev 两个数字员工在同一条变更生命周期中接力：AI 表格保存需求、阶段状态、人工答复和人工决策；Git 保存每一阶段可被下游读取的版本化工件。
+
+本 SPEC 只覆盖本地单实例。不引入多实例分片、认领、租约、SLA、超时自动放行、领域层级或中间提案表。
+
+## 目标
+
+1. 创建 `intake` 与 `execution` 两条 workflow，并使用同一个 AI 表格 Base 的不同 tracker 表。
+2. 让 `pm` 与 `dev` role 在同一条「变更流水」记录上接力，不拆分为各自 workflow。
+3. 将阶段工件固定沉淀到 PM 仓库的 `changes/<变更编号>/`，并以 Git commit、CR 与表内链接建立审计链。
+4. 以 Agent、表内人工答复和 GitLab CR 为硬门禁；AI 问题未满足时保持 `状态=blocked`，CR 等待保持 `active` 并持续查询真实合并状态；无 SLA 或自动放行。
+5. 首轮默认保守运行：可判断、建行、生成工件和本地 commit；不自动 push、创建 CR 或推进表内业务状态。受控验收开关开启后，允许真实测试、push 与创建 CR。
+
+## 非目标
+
+- 除 Coding Toolkit 的通用 session resume 扩展外，不改动 `aitable-agent` 框架源码；该扩展独立走框架 CR，见 `aitable-agent/docs/plans/2026-09-15-coding-toolkit-session-resume.md`。
+- 不生成设计稿，不建立 `design` step，也不创建 `03-design/`。
+- 不使用 `toolkit.ai`；领域判断、工件生成和代码任务均通过 `toolkit.coding` 驱动 Agent。需求去重只使用确定性的来源幂等键。
+- 不自动合并 GitLab CR；CR 合并由具备权限的人完成，流程只检查事实。
+
+## 术语与真源
+
+| 对象 | 真源 | 约束 |
+| --- | --- | --- |
+| 需求、领域、PM负责人、Dev负责人、人工答复、流程状态 | AI 表格 | 机器人/Agent 结论只有写入表列后才能被下轮消费。 |
+| 意图、PRD、计划、构建、评审工件 | PM Git 仓库 | 仅使用 `changes/` 目录。 |
+| 代码改动、测试、各代码仓库 CR | 对应 Dev Git 仓库 | 所有引用汇总回 PM 工件与「产出物」。 |
+
+### PM 与 Dev 仓库配置
+
+仓库均为部署配置、不是 Role 属性：
+
+```yaml
+repositories:
+  pm:
+    repo_url: git@gitlab.alibaba-inc.com:xule-test/ai-staff.git
+    default_branch: master
+  dev_allowlist:
+    - git@gitlab.alibaba-inc.com:alidocs/we-notable.git
+    - git@gitlab.alibaba-inc.com:alidocs/lippi-doc-notable.git
+```
+
+Dev 只能选择白名单内仓库。Agent 认为需要其他仓库时，必须写 `状态=blocked`、填写「阻塞原因」「解除条件」，不得 clone、创建分支或 CR。
+
+## AI 表格模型
+
+setup 在同一新 Base 创建三张表，Base ID 和 table ID 随部署配置固化，不在每次运行中询问。
+
+### 「需求池」——`intake` tracker
+
+| 字段 | 类型 / 值 |
+| --- | --- |
+| 需求标题 | text，主字段 |
+| 来源类型 | singleSelect：群反馈、Aone、用户访谈、竞品、内部提议、巡检、线上事故 |
+| 来源ID | text |
+| 原始证据 | text |
+| 领域 | text；保存「领域字典表」的领域名称 |
+| 需求状态 | singleSelect：待评估、已接受、开发中、已完成、已驳回、待澄清 |
+| 产出物 | text，接受后写对应变更行链接 |
+
+### 「变更流水」——`execution` tracker
+
+| 字段 | 类型 / 值 |
+| --- | --- |
+| 变更编号 | text，主字段；`CHG-<YYYYMMDD>-<slug>`，也是目录名、分支名和 commit 前缀 |
+| 标题 | text |
+| 需求 | text，写需求标题 |
+| 领域 | text；保存「领域字典表」的领域名称 |
+| 当前阶段 | singleSelect：意图、PRD、设计稿、计划、构建、评审、已发布；本期只写意图、PRD、计划、构建、评审、已发布 |
+| 属主 | singleSelect：PM、Dev、人 |
+| 状态 | singleSelect：active、blocked、rejected、shipped、archived |
+| 待人处理 | singleSelect：无、待批PRD、待批设计、待批合并 |
+| 等待谁 | user，只存具名真人 |
+| 阻塞原因 | text |
+| 解除条件 | text |
+| AI问题 | text；当前阶段仍未解决的问题清单，以人可读的 `Q1: 问题`、`Q2: 问题` 多行文本保存 |
+| 人工答复 | text；按对应的 `Q1: 答复`、`Q2: 答复` 多行文本填写 |
+| Agent会话ID | text；按 `阶段 + role + 仓库URL → sessionId` 的结构化 JSON 文本保存；worktree 由仓库 URL、变更编号和分支名确定性重建 |
+| 当前CR链接 | text；当前待审阶段的 CR 链接或多仓库 CR Markdown 链接，供通知和人工审阅；阶段推进后允许更新 |
+| 产出物 | text，保存工件、commit 或 CR 链接 |
+| 阶段跃迁审计 | text，保存幂等键 `变更编号 + 目标阶段` |
+
+`设计稿` 是为既有字段契约保留的选项，本期不进入 execution edges，也不由 recipe 写入。
+
+### 「领域字典表」——公共只读配置表
+
+字段为「领域名称」「领域说明」「典型例子」「PM负责人」「Dev负责人」「是否兜底」。setup 预填：数据源与同步、插件与扩展、AI 能力与知识、前端与交互、协作与权限、平台与运维、其他·未分域；各行负责人留空，且仅「其他·未分域」的「是否兜底」设为是。
+
+## Workflow 拓扑
+
+```text
+需求池 / intake
+  aitable_record 轮询（来源类型 + 来源ID 过滤与机械去重）
+  → 机械去重 → Agent 领域判定 → 领域 PM负责人受理
+  → 人写「需求状态=已接受」
+  → 创建 execution tracker 行
+
+变更流水 / execution
+  意图(PM) → PRD(PM) → 计划(Dev) → 构建(Dev) → 评审(Dev) → 已发布(人)
+```
+
+`intake` 创建 execution 记录时必须通过 `{ ref: "workflow:execution.tracker" }` 引用目标 tracker；两个 workflow 绝不共享 tracker table。
+
+两条 workflow 均采用 `aitable_record` 事件源做表格轮询，并始终带筛选条件。EventSource 只采集、过滤和转为 `ExternalEvent`；机械去重、领域判断、受理、门禁和阶段推进全部在 handler 或 recipe。
+
+## Intake 行为
+
+1. handler 按「来源类型 + 来源ID」持久化机械幂等键，阻止同源重复入池。
+2. 第一业务 step 只按「来源类型 + 来源ID」执行机械去重；命中时写「需求状态=待澄清」、通知人确认，且不得创建变更行。不作内容相似度判断，也不读取历史需求供 Agent 比较。
+3. PM recipe 通过 tracker 查询读取所有领域行，调用 Agent 选定一个领域，并只写入「领域」。受理自动化按该领域查询「领域字典表」的「PM负责人」并通知真人。
+4. PM负责人点击「接受」或「驳回」后，自动化同时写入「需求状态」和「执行状态=active」；intake 从持久化步骤指针续跑，接受则创建「变更流水」记录，驳回则结束该需求。等待受理时「执行状态=blocked」不参与候选轮询。自动化在每次通知时按领域与阶段查询负责人，绝不复制到「等待谁」。
+
+## Execution 行为与工件
+
+每个阶段首先调用 `toolkit.git.ensureWorktree(repoUrl, itemId, branch)`；`branch` 固定等于「变更编号」，基础分支为 `master`。PM 仓库内工件固定为：
+
+```text
+changes/<变更编号>/
+├── 01-prd.md
+├── 04-plan.md
+├── 05-build.md
+└── 06-review.md
+```
+
+| 阶段 | Role | 产物与门禁 |
+| --- | --- | --- |
+| PRD | PM | 生成产品可直接评审的 `01-prd.md` 并创建 PM 仓库 CR。未答「待确认问题」时 blocked。 |
+| PRD 评审 | PM | 处理 PRD CR 评论并确认真实合并；等待时保持 active 并持续轮询，合并后进入计划。 |
+| 计划 | Dev | 生成 `04-plan.md`，选择并记录目标 Dev 仓库；计划需要补充信息时 blocked。 |
+| 构建 | Dev | 用 `toolkit.coding` 实施并运行真实测试，记录完整命令与输出摘要到 `05-build.md`；涉及每个 Dev 仓库均创建独立 CR。 |
+| 评审 | Dev | 用 `toolkit.codeReview` 创建/检查 CR、读取未解决评论、驱动 Agent 修复；把 CR、测试和 CI 事实写进 `06-review.md`。所有 Dev CR 合并到 master 后才能进入已发布。 |
+| 已发布 | 人 | 人工确认发布；状态写为 shipped。 |
+
+每次阶段写入完成后，Agent 用 `toolkit.git.commit` 创建本地 commit，前缀为「变更编号」。创建 PM 或 Dev CR 后，recipe 立即更新「当前CR链接」和追加式「产出物」。负责人只在自动化发送通知时按领域与阶段查询；「产出物」是永久审计索引，按阶段、仓库、commit、CR、CI 与工件链接追加，绝不因后续 PM/Dev 阶段覆盖。
+
+所有需要评审的阶段在生成工件并完成本地 commit 后，自动推送并创建远端 CR；人工评审与真正合并仍是硬门禁。
+
+## 门禁、阻塞与恢复
+
+步骤不使用 `auto: false`：`auto: true` 让引擎继续由「当前步骤」驱动。Recipe 仅在 CR 等待时返回 `needs_human`，它不会改动 tracker 状态，目的是结束本轮并保留指针以供下次轮询；AI 问题等待则使用 `blocked`。
+
+每个需要人工处理的阶段同时满足下列条件才会继续：
+
+1. 阶段工件结尾的「## 待确认问题」中每个编号在「人工答复」中有对应答复，且当前 recipe 已消费该答复；
+2. PRD 或代码 CR 的批准/合并事实已经由 `toolkit.codeReview` 或 Git 事实检查确认。
+
+仅批准、问题未答完时必须保持 `blocked`。由于框架对 `RecipeResult.status="blocked"` 不回写 `output_mapping`，每个准备返回 blocked 的 recipe 必须先通过 `ctx.toolkit.table.updateCurrentRow()` 持久化「阻塞原因」「解除条件」「AI问题」和「Agent会话ID」，再返回 blocked：
+
+- 「AI问题」是该阶段工件末尾 `## 待确认问题` 的表内镜像，以 `Q1:` 起始的连续编号展示；它是用户回答的唯一定位依据。问题与答复在消费后一起清空，因此编号可以在下一轮安全复用。
+- 「人工答复」只接受带已有问题编号的答复。recipe 逐项比对「AI问题」，确认全部答复存在且有效后才将本轮答复注入 Agent prompt。
+- 「Agent会话ID」按阶段、role 与仓库 URL 保存 sessionId。恢复前先用 `ensureWorktree(repoUrl, 变更编号, 变更编号)` 取得同一 worktree，再将对应 sessionId 传给 `toolkit.coding` 的通用 session resume 扩展，使 PM/Dev Agent 在原上下文继续，而不是重新生成一份 PRD、计划或构建结论。
+- CR 未通过或存在未解决评论但无需人回答时，「AI问题」可为空；「解除条件」明确为待 CR 批准、评论解决或合并事实。
+
+「blocked」仅表示 AI 问题等待真人答复，不进入 tracker 候选轮询；「人工答复续跑」自动化在真人更新「人工答复」后仅将「状态」写为 `active`，引擎据既有「当前步骤」恢复。CR 等待不是 `blocked`：记录保持 `active`，recipe 以 `needs_human` 结束单轮并在后续轮询中继续查询 CR 事实。这样答复等待不会产生重复通知，CR 仍能自动处理新评论和合并。
+
+CR 等待期间「属主」保持实际可继续处理评论的 PM 或 Dev；「待人处理」表达真人 CR 评审或最终发布批准，不作为问答通知的路由真源。没有 SLA、超时或自动放行。
+
+### 阶段内循环（问题与 CR）
+
+每一个会写 Git 工件的 recipe（意图、PRD、计划、构建、评审）都不是一次性动作，而是以下两个可恢复循环：
+
+1. **问题循环**：Agent 每次更新工件后从工件末尾「## 待确认问题」同步未答问题到「AI问题」。存在任何未答问题即持久化 session、写 `blocked` 并结束本轮；人工在「人工答复」按问题编号回答后，下一轮把完整答复带回同一 session。只有 Agent 输出空问题清单并将「AI问题」清空，才允许完成该阶段工件或进入 CR。
+2. **CR 循环**：已有 CR 时，每轮先读取未解决评论。发现新的评论时，将评论内容、文件和行号交给同一 session 修复；Agent 必须运行测试、提交、推送，并把修复事实写回阶段工件。已交给 Agent 的同一评论指纹记入追加式「产出物」，避免在评论未被评审者关闭前重复修改；出现新评论时再次进入修复。无未解决评论后用 `isReadyToMerge` 提醒评审者，但只用 `isMerged` 确认已实际合并到 `master`：PRD CR 合并后进入计划，所有代码 CR 合并且真人批准发布后进入发布。
+
+本项目依赖 `aitable-workflow-core@0.1.28-beta.1789525693558` 的只读 `codeReview.isMerged`；它只验证合并事实，不代表 Agent 执行合并。
+
+「当前阶段」「属主」「阶段跃迁审计」仅能由 recipe 推进。阶段跃迁前检查「阶段跃迁审计」是否已有 `变更编号 + 目标阶段`；存在则不重复创建工件、commit 或 CR。
+
+## 表内自动化
+
+表内自动化只能通知或把人的按钮操作写入审批字段，绝不改「当前阶段」「属主」「阶段跃迁审计」。自动化按 DWS `workflow-dsl/v1` 的当期 `edit-example` 生成并在目标 Base 真实校验。
+
+1. 受理门禁：当「需求状态」为「待评估」且「领域」非空时，自动化按「领域」查询「领域字典表」；若该行「PM负责人」非空，则向该负责人发：
+   `【需求受理】『{需求标题}』（领域：{领域}）待确认是否接入。`
+   按钮为「接受」（写「已接受」）与「驳回」（写「已驳回」）。
+2. 合并门禁：当「当前阶段」为「评审」且 CR 已可合并，自动化按「领域」查询并向「Dev负责人」发：
+   `【待合并】{变更编号}『{标题}』已过 CR，请确认发布。`
+   按钮为「批准发布」（把「待人处理」写为「无」）。
+3. 阻塞问答：当「状态」为 `blocked` 且「AI问题」非空，自动化按「属主」选择负责人：PM 选「PM负责人」、Dev 选「Dev负责人」，正文先展示「需求」再发送当前「AI问题」，并提供「去填写」按钮直达该记录的「表格视图」；用户在「人工答复」按问题编号填写。另有「人工答复续跑」自动化，当真人更新「人工答复」时仅写「状态=active」；recipe 仍逐项校验答复完整性，不完整即重新 blocked。两条自动化均不写「当前阶段」「属主」或「阶段跃迁审计」。
+4. CR 待审：当「当前CR链接」写入且当前阶段为 PRD 评审或评审时，PRD 评审阶段按领域通知「PM负责人」，评审阶段按领域通知「Dev负责人」：`【CR待审】{变更编号}『{标题}』` 后固定展示 `需求：{需求}` 和当前阶段 CR 链接，并提供「去评审」按钮直达该 CR。该自动化只通知，不修改任何业务状态或审批字段。
+
+机器人新建为「AI表格开发小助手」，部署进「群答疑助手测试群」。机器人凭据通过 `.env` 声明，绝不写入 profile、scene、SPEC 或代码。
+
+## Role 与权限
+
+`pm` 和 `dev` 只定义 persona、skills、memory、guardrails、trust 与 knowledge scope。仓库 URL、工具权限、表格引用、事件源、自动化和数据边界全部放在 profile 的 workflow 部署配置中。
+
+每个 requiresAgent recipe 使用对应 `meta.role`，并提供 `workspaces/pm/AGENTS.md` 与 `workspaces/dev/AGENTS.md`。Agent 的输出要求写入 Git 工件；表格仅保存摘要、审批和链接。
+
+## 验证与验收
+
+1. `aitable-workflow validate -c <project>`：验证 profile、workflow、recipe、引用和字段。
+2. setup：新建 Base、三张表、字段、领域种子数据、机器人与两条自动化；每条自动化需远端返回 `valid: true`。
+3. trigger-once：为 intake 与 execution 使用受控 `ExternalEvent`，验证筛选、机械去重和跨 workflow 建行。
+4. 真实验收：以可识别的测试需求创建 PM 工件和 PRD CR；在一个 Dev 白名单仓库运行真实测试、创建 CR；检查表内链接、Git 工件、commit、CR、CI 证据和 blocked 恢复。
+
+## 回滚策略
+
+- 暂停 workflow 服务即可停止新增 push/CR，不删除本地 worktree 或已提交工件。
+- 暂停 workflow 服务即可停止轮询；AI 表格数据、Git commit 与 CR 保留作为审计记录。
+- 自动化通过 setup 的登记状态禁用；不删除用户在 Base 中自行创建的自动化。
+- 错误领域或需求受理仅通过表中「需求状态」与人工修正处理，不删除历史行。
+
+## 已确认的假设
+
+- `设计稿` 字段选项仅为兼容保留，本期没有设计稿阶段及设计工件。
+- PRD 需要 PM 仓库 CR 审阅；代码修复可能涉及一个或多个 Dev 白名单仓库，各自创建 CR。
+- CR 批准和 CR 合并由人完成；Agent 检查事实并在满足条件后推进，不替人执行合并。
+- PM 与 Dev 不拆成多条「变更流水」记录。`Agent会话ID` 以阶段、role、仓库 URL 为 key，`当前CR链接` 服务当前待审阶段，`产出物` 保存追加式历史，避免跨 role 覆盖。
+- GitLab、DWS、钉钉机器人、Coding Agent 的凭据与权限在 setup 阶段配置。

package/templates/ai-native-sdlc/docs/plans/2026-09-16-domain-role-notification-routing.md

@@ -0,0 +1,36 @@
+# 按领域与角色路由人工通知
+
+## 背景
+
+「等待谁」是变更记录上的临时人工指派字段，Agent 产生澄清问题或 CR 后不会可靠地填写它。以该字段作为自动化收件人，会造成通知无人接收；而同一领域的 PM 与 Dev 也可能由不同真人负责。
+
+## 目标
+
+领域字典表成为人工通知收件人的唯一配置真源。每个领域维护「PM负责人」与「Dev负责人」；所有自动化在触发时以记录的「领域」查询该表，不读取「等待谁」。
+
+## 路由规则
+
+| 场景 | 查询字段 |
+| --- | --- |
+| 需求受理、意图/PRD 的 AI 澄清、PRD CR 待审 | PM负责人 |
+| 计划/构建/评审的 AI 澄清、评审 CR 待审、合并门禁 | Dev负责人 |
+
+「等待谁」保留在变更流水中供人工临时标注，但不再由 recipe 写入，也不再由自动化消费。负责人留空时，查找步骤不发送通知，不得以默认收件人或自动放行降级。
+
+## 影响与回滚
+
+setup 为既有「领域字典表」补充两个 user 字段；现有「确认人」字段不再被流程使用，待业务确认历史兼容性后再单独清理。回滚时可恢复原自动化文件和「确认人」字段引用，不涉及业务数据删除。
+
+## 实施与验证
+
+1. 更新领域字典表声明、受理 recipe 和全部通知自动化。
+2. 为 PM 与 Dev 分开声明阻塞问答、CR 待审自动化，避免同一自动化内依赖模糊的角色分支。
+3. 使用 `aitable-workflow validate` 和项目测试校验本地产物；随后 setup 补字段并以 DWS 校验/部署自动化。
+
+## 受理续跑
+
+「需求状态」是审批结论，「执行状态」是引擎调度状态。受理等待时 recipe 将记录置为 `blocked`，该状态不在候选轮询集合内；「接受」「驳回」按钮同时写审批结论和 `执行状态=active`，引擎据「当前步骤」从 `create_change` 恢复，避免等待期重复执行。
+
+## 配置边界
+
+`create-change` 是唯一跨 workflow 写入「变更流水」的 recipe，因此它在 recipe 内声明 `execution_tracker` 配置契约。部署配置以 `{ ref: "workflow:execution.tracker.base_id" }` 与 `{ ref: "workflow:execution.tracker.table_id" }` 绑定目标 tracker，避免复制或写死表标识。领域字典表也仅由 `classify-domain` recipe 使用，故其建表/读取契约同样就近声明；PM 与 Dev 阶段配置分别由多个 recipe 共享，保留在共享配置模块。

package/templates/ai-native-sdlc/docs/plans/2026-09-16-execution-resume-and-cr-loop.md

@@ -0,0 +1,29 @@
+# Execution 阶段内恢复与 CR 闭环
+
+## 背景
+
+当前 execution recipe 把 Agent 提问、人工答复和 CR 评论当作一次性 `blocked` 结果：多数步骤不会解析问题，PRD 不逐题消费答复，PRD 与 review 遇到评论也不会让 Agent 修复。因此记录可以停住，却无法可靠地在同一个会话中完成阶段内循环。
+
+## 目标
+
+- 所有写工件阶段均能“提问 → 人工答复 → session resume → 再提问或完成”。
+- PRD 与 Dev CR 均能“拉取评论 → Agent 修复/测试/提交/推送 → 等待复审 → 新评论再修复”。
+- 阶段只在所有问题清空、所有关联 CR 无未解决评论且已合并时交接；不能以 ready-to-merge 代替合并事实。
+
+## 方案与影响面
+
+1. 在 `lib/recipe-helpers.ts` 统一解析 `SDLC_QUESTIONS`、人工答复编号、未答问题、评论指纹及已处理评论审计；问题字段只保存当前未答集合，答复留在「人工答复」供下一轮 Agent 消费。
+2. 把 intent、prd、prd-review、plan、build、review 统一改为：恢复已有 session，注入已答问题；成功后先提交工件，再根据 Agent 输出的问题决定 blocked 或继续。
+3. PRD 与 review 的已有 CR 分支读取未解决评论；仅对未处理指纹调用 Agent 修复、运行测试、commit、push，并回写 session 与追加审计。没有新评论时只轮询 CR 状态。
+4. 在公开 core 升级前，把 CR “可合并但未确认合并”视为硬阻塞。升级后接入 `codeReview.isMerged`，由其判断所有 CR 的真实合并状态。
+
+## 回滚
+
+暂停服务即可停止新增远程副作用；已有问题、答复、工件、commit 与 CR 均保留，不删除数据。
+
+## 实施计划
+
+1. 补充 helper 与单元测试：问题/答复匹配、问题清空、评论指纹及已处理审计。
+2. 改造五个写工件 recipe 的问题循环与 session 持久化。
+3. 改造 PRD 与 review 的评论修复循环；在缺 `isMerged` 的当前公开版本保持安全阻塞。
+4. 运行 `npm test` 与 `aitable-workflow validate`；对含 CR 的分支仅做模拟/契约验证，不创建真实 CR。

package/templates/ai-native-sdlc/docs/plans/2026-09-16-project-handoff.md

@@ -0,0 +1,148 @@
+# AI Native SDLC 双数字员工协作台：项目交接
+
+> 更新日期：2026-09-18。本文是后续 Agent 的当前上下文，不替代配置和代码；遇到冲突时以现有代码、AI 表格和实际命令输出为准。
+
+## 目标与边界
+
+项目实现单机、单实例的 AI Native SDLC 协作台：PM 和 Dev 在同一条变更记录上接力，AI 表格保存状态、人工答复和审批，Git 保存 `changes/<变更编号>/` 下的阶段工件及提交记录。
+
+- `intake` 管理「需求池」，接受后才创建 `execution` 的「变更流水」记录并写为「开发中」。变更编号为 `CHG-<日期>-<slug>-<标题哈希>`；中文标题的 slug 回落为 `change`，唯一性由「需求标题」的确定性哈希保证，同一标题重试得到同一编号。机械去重同样只按需求标题匹配（`来源ID` 字段已移除）。所有代码 CR 真实合并后，`execution` 将关联需求写为「已完成」。
+- `execution` 管理「变更流水」，当前链路是：
+
+  ```text
+  prd → prd_review → plan → build → review
+  ```
+
+- 「当前步骤」是引擎的持久化指针；「当前阶段」是用户可见的业务阶段。两者不能互相替代。
+- 当前阶段中新增了用户可见的「PRD 评审」，用于 PRD CR 等待与评论修复；它不与 `prd` 生成步骤混用。
+- 当前没有设计稿 recipe；「设计稿」只保留为表格既有枚举值。intent 并入 `prd` 后「意图」同样只保留为既有枚举值；create-change 新建的变更流水从「当前阶段=PRD」开始。
+- 不修改 `aitable-agent` 框架源码。项目依赖公网 `aitable-workflow-core@0.1.28-beta.1789525693558`。
+
+## 关键目录
+
+| 位置 | 用途 |
+| --- | --- |
+| `profile/profile.yml` | 场景配置唯一事实源：角色、PM 仓库、Dev 候选仓库、跨 workflow tracker 引用。coding engine 不按 workflow 声明，统一用全局 `agent.engine`（qoder）。 |
+| `workflows/intake/` | 需求去重、模块判定、受理后创建变更。 |
+| `workflows/execution/workflow.yml` | 五步执行链（prd→prd_review→plan→build→review）、变更流水字段声明及状态候选集。 |
+| `workflows/execution/recipes/` | PM/Dev 的阶段实现；`prd-review.recipe.ts` 是 PRD CR 生命周期。 |
+| `workflows/*/automations/` | AI 表格自动化 DSL。 |
+| `profile/prompts/pm.md`、`profile/prompts/dev.md` | 角色规程（工作空间规则、工件规范、提问协议）的唯一事实源，作为 persona 注入每轮 prompt。 |
+| `workspaces/pm/AGENTS.md` | PM 工作区说明（cwd 语义 + 规程指针）；作为 PM 的 cwd 被 Coding CLI 自动加载。 |
+| `workspaces/dev/AGENTS.md` | Dev 工作区说明（cwd 语义 + 规程指针）；作为 Dev 的 cwd 被自动加载。 |
+| `lib/recipe-helpers.ts` | 答复解析、session 保存、CR 评论指纹、等待与失败恢复的共享逻辑。 |
+| `test/recipe-helpers.test.ts` | 关键状态语义的轻量回归测试。 |
+
+## 角色、AGENTS 与知识
+
+- recipes 调用 `coding.run` 时**不再传 `workDir`**：框架据此以 `workspaces/<role>` 作为 cwd，Coding CLI 会自动加载该目录下的 `AGENTS.md`；该文件只说明工作区语义并指向 persona。
+- 提示词分两层：**角色层**（工作空间规则、工件规范、提问协议）集中维护在 `profile/prompts/<role>.md`，由 profile 的 `persona` 在加载期读入、作为「角色设定」注入每轮 prompt；**阶段层**（本轮上下文、本轮任务、约束）留在各 recipe 的 `coding.run()` prompt 里。阶段 prompt 不再重复角色身份与协议正文。
+- persona 文件路径相对 `profile/` 解析（`prompts/pm.md` → `profile/prompts/pm.md`）。写成相对仓库根的路径时 `RoleRegistry.loadFromProfile` 只会打警告并**静默跳过整个角色**，不会让启动失败，排查时先看这里。
+- `profile.yml` 的 role 不再声明 `skills`；它只保留 persona 和 guardrails。
+- 旧的 `knowledge/dev-repository-guide.md` 已删除，`dev_repository_guide` 配置及 recipes 中的绝对路径读取也已删除。
+- cwd 是角色 workspace，**不是**每条变更的 Git worktree；worktree 只是写入目标，由 prompt 以绝对路径给出。因此不要在 prompt 里要求读取项目根 `knowledge/` 目录（不在 cwd 祖先链上）。每个仓库 worktree 根目录若有自己的 `AGENTS.md`，prompt 会要求 Agent 先读取并遵循（仓库级约定优先于角色通用规程）。
+
+## 执行语义
+
+### 问答与 session
+
+1. AI 需要人工信息时，recipe 将问题以人可读的 `Q1: ...` 多行格式写入「AI问题」、写入「阻塞原因」「解除条件」和「Agent会话ID」，并返回 `blocked`。
+2. execution tracker 的候选集仅含 `active`，所以 blocked 记录不会被反复执行或重复通知。
+3. 「人工答复续跑」自动化仅在真人更新「人工答复」后把状态恢复为 `active`；它不写「当前阶段」「属主」「阶段跃迁审计」。
+4. 下一轮 recipe 校验每一个问题编号都有答复，消费答复并将已有 session 传给 Coding Agent。消费时会同时清空「AI问题」和「人工答复」：问题编号跨轮复用（如 `Q1`），残留旧答复会让新问题被旧答案静默通过。
+5. Coding Agent 的原生 `ASK_HUMAN_DETECTED` 被转换为带编号的「AI问题」。普通 Agent 失败保持 `active`、保存 session 并返回可重试失败，不能写成无问题的永久 `blocked`。
+6. `coding.run` 不传 `workDir`，cwd 落到 `workspaces/<role>`（AGENTS.md 自动生效）；prompt 只给出各候选 worktree 的绝对路径，工件写入选中仓库 worktree 的 `changes/<变更编号>/`，计划阶段额外注入 PM worktree 路径用于读取已合并 PRD。候选 worktree 的公共父目录不是 Git 仓库，文件必须写进具体仓库 worktree 内。提问协议（`SDLC_QUESTIONS=["问题"]` 字符串形式，编号由 `agentQuestions` 按阶段自动分配）维护在 persona 文件，prompt 不再重复。
+
+### CR 循环
+
+- CR 等待保持 `active`，由 recipe 返回 `needs_human` 结束单轮；下次轮询继续读取 CR 状态。
+- 发现新的未解决评论时，Agent 使用已有 session 修复、运行测试、commit、push；评论指纹写入「产出物」，避免同一评论集合重复修复。
+- 只使用 `codeReview.isMerged()` 判断真实合并，不能把 `isReadyToMerge()` 当作已合并。
+- PRD：单个 PM 会话只产出产品可直接评审的 `01-prd.md`。有未解问题就提问阻塞，全部澄清后才 push 并创建 CR；成功后写「阶段跃迁审计」`<变更编号>+PRD 评审`（作为步骤指针未推进时的恢复守卫，避免重复建 CR）并进入 `prd_review`；`prd_review` 处理评论、等待真实合并，合并后才推进 `plan`。
+- Dev：`review` 处理代码 CR 创建、评论与真实合并；`review` 是终点步骤——所有代码 CR 真实合并后即标记变更完成（写「状态=shipped」「当前阶段=已发布」「属主=人」并清空 CR 链接），不再有人工发布批准闸门，也无独立 `shipped` 步骤。
+- CR 等待时「属主」保持 PM 或 Dev，使问答/通知可按模块负责人路由；只有 `review` 完成时写「属主=人」。
+
+### 阶段工件与登记表
+
+- 工件写入对应 worktree 的 `changes/<变更编号>/`：`01-prd.md` 在 PM 仓库，`02-plan.md`、`03-build.md`、`04-review.md` 在选中的各 Dev 仓库。
+- 同目录 `.artifacts.json` 是工件登记表：键为工件文件名，值为 `{"summary": "这是什么、给谁用"}`。Agent 按 persona 规程**只新增或更新本工件条目**，不得删除、覆盖其他条目。
+- recipe 在 commit 前调用 `ensureArtifactManifest` 兜底：工件已写出而条目缺失时补写固定概要，工件不存在（未选中仓库）不登记、不造假条目。登记先于 commit，二者在同一次提交里，push 后下游即可读到。
+- 下游按 summary 判断某仓库该阶段是否已产出，不必读工件正文。
+
+## 表格与自动化现状
+
+已有三张表：
+
+- 「需求池」：intake tracker；其调度字段是「执行状态」。
+- 「变更流水」：execution tracker。
+- 「模块配置表」：公共只读配置；含「PM负责人」和「Dev负责人」。
+
+代码中现有六条自动化：
+
+1. 需求受理门禁
+2. PM 阶段阻塞问答通知
+3. Dev 阶段阻塞问答通知
+4. 人工答复续跑
+5. PRD CR 待审通知
+6. 评审 CR 待审通知
+
+「合并门禁」自动化随发布批准闸门一并从代码中移除（`review` 现在在所有代码 CR 合并后直接标记完成）。但此前已部署到远端的「合并门禁」流程不会因删除本地文件而自动下线，需要单独用 DWS 停用/删除；其触发条件依赖已废弃的「待人处理」字段，删除该列前应先下线该流程。
+
+PRD CR 待审通知现在以「当前阶段=PRD 评审」触发，按模块查询并通知 PM负责人；代码 CR 待审通知以「当前阶段=评审」触发，通知 Dev负责人。
+
+### 单选枚举同步的框架限制
+
+`aitable-workflow setup` 会创建缺失字段，但不会修改已有 singleSelect 的选项。为了新增「PRD 评审」，已使用 DWS 的字段更新命令读取完整选项列表、保留已有 option id，并仅追加新选项。
+
+以后再改已有单选字段时必须：
+
+1. 先读取字段当前配置；
+2. 在更新时带回全部旧 option id；
+3. 只为新增选项省略 id；
+4. 重新部署依赖该选项的自动化。
+
+自动化 DSL 的 option 占位符以最后一个下划线分割字段名和选项名。选项「PRD 评审」包含空格，正确写法是 `<当前阶段_PRD 评审_optionId>`，不要写成 `<当前阶段_PRD_评审_optionId>`。
+
+## 已知问题与后续动作
+
+### 当前未完成的验证
+
+用户在最后一次 `npm test && aitable-workflow validate` 执行过程中主动中止，因此**不要**把最新的 PRD 拆分版本称为“最终验证完成”。此前的本地校验在拆分后已经证明：
+
+- workflow 可加载，步骤数为 7、边数为 8；
+- recipe 绑定、类型检查和配置契约均通过；
+- 当时 `npm test` 通过。
+
+但在新增最终回归断言、修正自动化占位符之后，应先重新运行：
+
+```text
+npm test
+aitable-workflow validate -c /Users/xule/work/code/agent-tests/ai-native-sdlc-dual-staff
+```
+
+再启动服务。不要把两条命令串成不可中断的大操作，以便用户可单独观察结果。
+
+### 服务状态
+
+为了同步表格和自动化，长驻服务已被正常停止。当前需要在验证通过后重启：
+
+```text
+aitable-workflow start -c /Users/xule/work/code/agent-tests/ai-native-sdlc-dual-staff --skip-config-if-valid
+```
+
+启动前先用 design skill 的 `inspect-run-status.mjs` 检查，避免重复启动。DWS 访问本地登录态文件时需要在允许访问本机凭据锁的环境执行。
+
+### 自动化部署观察
+
+自动化 setup 的实时输出常只显示前几条更新，但直接列出远端流程可确认部署状态，且 PRD CR 待审通知已在本次阶段改动后更新。后续如需精确核验，使用 DWS 的 `aitable workflow list` / `get` 读取流程定义，不要仅以 setup 的截断日志判断。
+
+### 尚未做真实验收
+
+尚未针对一条真实需求完整跑出 PM PRD CR 和多个 Dev CR，也未验证真实评论回流与真实合并的端到端过程。实际验证必须遵守保守模式和人工 GitLab 合并门禁（代码 CR 的真实合并仍是人工在 GitLab 完成，合并后 `review` 自动标记变更完成）。
+
+## 操作纪律
+
+- 修改业务流程前先更新本文对应的设计/实施计划，不修改 `aitable-agent` 源码。
+- 不输出或写入 Base ID、Table ID、机器人凭据、session ID 等敏感或无用户操作价值的信息。
+- 本项目根不是 Git 仓库；不要在此目录假设可以 commit。阶段工件与 CR 由 recipes 在业务仓库的 worktree 中创建。
+- 远端表格写入和自动化部署是有副作用操作；先读当前状态再做定向更新。

package/templates/ai-native-sdlc/docs/plans/2026-09-17-prd-code-context-and-readable-prompts.md

@@ -0,0 +1,37 @@
+# PRD 代码上下文与可读 Prompt 规格
+
+## 背景
+
+当前 PRD recipe 只向 PM Agent 提供变更记录和 PM 工件 worktree。它既不知道业务代码仓库，
+也没有被要求先理解现有逻辑，导致 PRD 可能脱离当前实现。同时，多个 recipe 将任务、输入、
+路径与约束拼为一行长字符串，难以阅读和维护。
+
+## 目标
+
+- PM 在撰写 PRD 前获得已配置业务代码仓库的 URL，并按自身可用的只读能力阅读其 `master` 当前逻辑。
+- PRD 阶段绝不为业务代码仓库调用 Git toolkit，也不为它们创建 worktree、分支、工件或提交。
+- PRD 工件只写入 PM 工件仓库的 `changes/<变更编号>/01-prd.md`，供产品直接评审。
+- 每个调用 Coding Agent 的 recipe 使用可读的 Markdown 分节 prompt。
+
+## 方案
+
+在 `execution.steps.prd` 增加 `business_repositories` 配置，并由 `prdStageConfig` 校验。
+PRD recipe 只把 URL 列表传给 PM Agent，要求先以只读方式检查这些仓库的 `master` 代码；
+它不调用 `ensureWorktree`、`clone` 或任何业务仓库写操作。PRD 本身不增加“现状依据”或
+“影响仓库”等固定章节，仍按既有 PRD 契约产出需求、验收标准与依赖。
+
+每个 `coding.run()` 直接使用多行模板字符串和二级标题分节，分别表达阶段上下文（工作目录、输入）、
+本轮任务、约束和已消费的人工答复，避免单行拼接，也不引入额外的 prompt 渲染抽象。
+角色身份与提问协议由 profile 的 persona 注入（见 `2026-09-16-project-handoff.md`），阶段 prompt 不再重复。
+
+## 回滚
+
+删除 PRD 的 `business_repositories` 配置与 prompt 段即可恢复原有 PRD 输入；prompt 仅影响文本格式，
+可逐 recipe 回退，不涉及 AI 表格字段或 Git 历史。
+
+## 实施计划
+
+- [x] 为 PRD 增加业务仓库 URL 配置与 schema 校验，并在 PM workspace 规程中说明只读阅读职责。
+- [x] 重写 PRD prompt：业务仓库仅作为只读上下文，PM 工件只写入 `01-prd.md`。
+- [x] 直接以多行模板字符串重写所有 `coding.run()` prompt 为分节格式，不改变各阶段工具调用或状态机行为。
+- [x] 运行项目测试与 `aitable-workflow validate`。

package/templates/ai-native-sdlc/docs/plans/2026-09-21-plan-merge-sync-and-agent-source.md

@@ -0,0 +1,19 @@
+# 计划合并同步与 Agent 工件单一来源
+
+## 背景
+
+计划 CR 合并后，需求分支的远端内容已经变化，但本地需求 worktree 仍停留在合并前提交；build
+复用该 worktree 时看不到计划改动。与此同时，`AGENTS.md` 重复维护具体工件文件名，已与集中式
+`ARTIFACT_FILES` 产生漂移。
+
+## 方案
+
+- Core Git toolkit 增加 `syncWorktree`：仅允许在 worktree 干净时拉取指定远端分支，并 reset 到
+  `origin/<branch>`；有未提交改动则拒绝覆盖。
+- `plan-review` 在全部计划 CR 确认合并后同步对应需求分支，再推进到 build。
+- build 的本地 diff 基准使用 `origin/master`；MR 目标仍保持平台分支名 `master`。
+- `AGENTS.md` 不再声明具体工件文件名或章节，统一引用工作流提供的 `ARTIFACT_FILES` 和阶段 prompt。
+
+## 回滚
+
+回滚 toolkit 方法及 `plan-review` 同步调用即可恢复旧行为；Agent 规程可独立回滚，不影响状态机。

package/templates/ai-native-sdlc/docs/plans/2026-09-21-sdlc-base-ref-and-review-notification.md

@@ -0,0 +1,18 @@
+# SDLC 基准分支与 CR 通知修正
+
+## 背景
+
+业务仓库的本地 `master` 可能因远端分支重写而与 `origin/master` 产生历史分叉。继续以本地
+`master` 创建 worktree 会把旧提交历史当成基准；同时 Dev 规程曾残留旧的 `04-plan.md` 命名，
+会让 Agent 与工作流实际产物 `02-plan.md` 不一致。CR 通知也只写“CR待审”，没有明确当前评审阶段。
+
+## 方案
+
+- PM、Dev 的所有仓库定义和 Git toolkit 默认基准统一使用 `origin/master`。
+- Dev `AGENTS.md` 以 `02-plan.md` 为当前计划工件，并声明优先遵循工作流提供的 `ARTIFACT_FILES`。
+- PRD 评审和 Dev 评审的 CR 通知在需求名称后增加“当前阶段：{当前阶段}”。
+
+## 影响与回滚
+
+只改变模板的部署配置、Agent 规程和通知文案，不改变状态机或字段契约。
+如需回滚，将仓库 `default_branch` 和 toolkit 默认值恢复为原配置，并恢复旧规程和通知内容。