♻️ refactor(cook-it-through): move workflow engine into skill
This commit is contained in:
@@ -0,0 +1,26 @@
|
||||
# Feature 集成
|
||||
|
||||
stdout 出现 `INTEGRATION_REQUIRED=<feature>@integrated` 后，先读 `main_loop.py integrate --help`。
|
||||
只在全局锁下处理严格 integration frontier；后序 feature 即使完成也不得越序。
|
||||
|
||||
feature 必须先显式吸收最新 main，再完成 feature verification、main candidate verification 和
|
||||
最终双轴 review。收到 `RETRY: feature needs main sync` 时同步后全部重跑；不得自行 merge 或
|
||||
绕过 frontier。
|
||||
|
||||
merge 冲突令该 feature integration blocked，但不阻止后续 ticket 开发；必要时用
|
||||
`main_loop.py block-feature` 记录边界，解决后用 `main_loop.py release-feature`。
|
||||
|
||||
## 三道证据门禁
|
||||
|
||||
三个独立门禁，不能互相替代：feature、main candidate 和 review 都必须是 fresh UTF-8 JSON
|
||||
artifact，精确字段以 `integrate --help` 为准。调用 `main_loop.py integrate` 时只提交 frontier
|
||||
feature、已验证的 `FEATURE_HEAD`、feature verification、main verification 和 review；
|
||||
`skipped` ticket 还必须显式授权 partial integration。收到 `NOOP`/`RETRY` 仍按 stdout 处理。
|
||||
|
||||
## 持久化最终状态
|
||||
|
||||
集成成功后，先完成 merge commit，再只暂存 `.scratch/<feature>/` 及确被改写的
|
||||
`.scratch/queue.md`，提交 final workflow state；不要运行 `git add .scratch`，不得 amend/squash。
|
||||
|
||||
保持 `.main-loop.json` 的 `integration_commit` 指向 `MAIN_INTEGRATION_COMMIT`，解析并报告全部
|
||||
`WARNING` 与残留 worktree。已集成 feature 的重试必须幂等。
|
||||
@@ -0,0 +1,55 @@
|
||||
# 入口 4：feature 规划与入队
|
||||
|
||||
## 选择与建立上下文
|
||||
|
||||
巨大而模糊的工作先用 `wayfinder`；需要外部事实时用 `research`。先进入 `grill-with-docs`，
|
||||
研究报告不能替代 grilling。进入 `grill-with-docs` 前，重读
|
||||
`memory-bank/project-brief.md`、`memory-bank/tech-context.md`、
|
||||
`memory-bank/system-patterns.md` 以及会改变设计的项目规则、领域文档和 ADR。
|
||||
首次运行 `setup-matt-pocock-skills` 时选择 local Markdown tracker。
|
||||
|
||||
让 `grilling` 清空 design frontier 并取得用户确认；seam confirmation 在 `to-spec` 与 `tdd`，
|
||||
`tdd` 不得在未经确认的 seam 上开始。按顺序推进：
|
||||
|
||||
`setup-matt-pocock-skills -> grill-with-docs -> to-spec -> to-tickets`
|
||||
`-> main_loop.py enqueue -> 提交 planning baseline -> main_loop.py claim`
|
||||
|
||||
关键规划链是 `to-spec -> to-tickets`。
|
||||
|
||||
## Ticket 身份与依赖格式
|
||||
|
||||
- `FeatureId`：小写字母或数字开头，只含小写字母、数字和连字符。
|
||||
- `TicketId`：qualified `feature-slug/NN`；feature slug 与至少两位数字共同构成身份。
|
||||
- `FeatureIntegrationId`：`feature-slug@integrated`。
|
||||
- Dependency 只能是后两类身份；标题和文件名中的可读 slug 不是身份。
|
||||
|
||||
每个 ticket 必须恰有一行 `**Blocked by:** None`，或
|
||||
`**Blocked by:** feature-a/01; feature-b@integrated`。执行 hard cut：`None` 只能单独出现；
|
||||
同 feature 也写完整身份；只用分号；拒绝裸数字、标题描述、逗号、隐式当前 feature、
|
||||
非法/重复/缺失目标、自依赖和跨 feature cycle。旧格式必须在 enqueue 前人工迁移；
|
||||
禁止增加 fallback、双解析器或自动重写。
|
||||
|
||||
## 全局图与两个 Frontier
|
||||
|
||||
- 锁内加载全部 queued features：每个 ticket 是节点，每个 feature 增加 integration node。
|
||||
- ticket 使用 `Blocked by` 边；integration node 依赖本 feature 全部 tickets；queue 顺序只连接
|
||||
integration nodes，不形成 ticket claim 门槛。
|
||||
- ticket frontier 是依赖已满足且 `ready-for-agent` 的 tickets，按 queue feature、ticket number、
|
||||
稳定 slug 排序；integration frontier 是首个尚未集成的 feature，两者独立。
|
||||
- ticket 在 `resolved` 或 `skipped` 时满足；integration dependency 只在持久状态含有效
|
||||
`integration_commit` 时满足。`skipped` 令 feature partial，集成时必须显式授权。
|
||||
- 枚举顺序不得改变 frontier、claim 或错误顺序。
|
||||
|
||||
## 入队与 planning baseline
|
||||
|
||||
第三方 `to-tickets` 只定义通用 tracker 行为；主循环格式以本文件和执行引擎为准。
|
||||
跨 feature 前向依赖必须把相关 feature 放在同一批次；同批重复 `--feature` 与现有 queue 一起校验。
|
||||
任一解析、目标或 DAG 校验失败，都不得写 queue、ticket metadata/status 或 feature state；
|
||||
`enqueue` 是最终机器校验边界。参数与结果只查相应 `--help`，不维护命令职责表。
|
||||
|
||||
生成和入队不隐式提交。任何 claim 前，提交 `.scratch/<feature>/spec.md`、
|
||||
`.scratch/<feature>/issues/*.md` 和 `.scratch/queue.md` 作为 planning baseline；随后读
|
||||
`workflows/ticket-execution.md`，由 `main_loop.py status` / `main_loop.py claim` 取得正式 assignment。
|
||||
|
||||
尚未 claim ticket 时，加载 `to-questionnaire`，把问题写入 control checkout 的
|
||||
`.scratch/questions/<slug>.md`，并从 `grill-with-docs` 恢复；不得把问题写入稳定知识。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 入口 2/3：单 session 工作
|
||||
|
||||
## 入口 2：单切片改动
|
||||
|
||||
修改前记录当前 `HEAD` 为 review fixed point。确认工作仍局限于单模块或既有接口、
|
||||
既有测试 seam，且没有新公开接口、配置、数据格式、依赖、迁移、兼容或并发边界。
|
||||
|
||||
按 `tdd` 实现并验证，提交全部实现；再以 `<fixed-point>` 作为 `code-review` 的 fixed point，
|
||||
仅运行 Standards axis。修复硬 finding 后重新提交、验证和 review。
|
||||
这里不生成 spec/tickets，也不提前创建 ticket branch。
|
||||
|
||||
## 入口 3：已明确预期行为的 bug
|
||||
|
||||
让 `diagnosing-bugs` 完整执行 Phase 1-6；它的 Phase 5 已包含 test-first，
|
||||
不重复 `tdd` 或 grilling。先建立可重复的失败反馈；若环境、artifact 或许可不足，
|
||||
记录缺口并请求补充。
|
||||
|
||||
缺少 seam 时可记录后完成修复，落地后再用 `improve-codebase-architecture`。
|
||||
不要因为 bug 已经明确而跳过根因验证，也不要把未证实的猜测当修复依据。
|
||||
|
||||
## 完成与升级
|
||||
|
||||
完成后运行 fresh verification，并保留 fixed point、验证命令和结果。
|
||||
若出现新 seam、兼容/架构取舍、跨模块或跨 session 影响，先完成当前入口可验证的收尾，
|
||||
再转 `workflows/feature-planning.md`；不要把已有修改当作已批准设计。
|
||||
|
||||
入口 3 的 bug 段不进入 `grill-with-docs`；只有暴露新的产品或架构取舍时才升级入口 4。
|
||||
@@ -0,0 +1,78 @@
|
||||
# 入队后的 ticket 执行
|
||||
|
||||
## 建立机器上下文
|
||||
|
||||
先读 `main_loop.py status --help`，再按 stdout 分开读取 qualified `TICKET_FRONTIER` 与
|
||||
`INTEGRATION_FRONTIER`，并处理 `CLAIM`、`STALE`、`BLOCKED`、`TICKET_ERROR`、
|
||||
`BLOCKED_DEPENDENCY`、`WAITING_ON`、`FEATURE_BLOCKED` 和 `MAIN_INTEGRATION_COMMIT`；
|
||||
单 feature 空 frontier 不是全局 BUSY。
|
||||
|
||||
claim 前使用 `--state-root "<PROJECT_ROOT>/.scratch"`；claim 必须显式传绝对
|
||||
`--repo-root "<PROJECT_ROOT>"`、全局唯一 `--owner` 和 `--isolation`。只从
|
||||
`main_loop.py claim --help` 取得参数。成功 assignment 的键是 `FEATURE`、`TICKET`、
|
||||
`CONTROL_ROOT`、`STATE_ROOT`、`WORKSPACE`、`BRANCH`、`BASE`、`ISOLATION`。
|
||||
|
||||
领取后立即从返回的绝对 `STATE_ROOT` 读取 feature spec/ticket。领取后实现前重读三个
|
||||
memory-bank 文件；不要预猜 ticket，也不要使用 worktree 中的 `.scratch` 副本。
|
||||
`NO FEATURES`、`NOOP`、`BUSY`、`RETRY` 和 `INTEGRATION_REQUIRED=<feature>@integrated`
|
||||
是 stdout/0 的机器结果，`ERROR` 是 stderr/2；始终解析 stdout。只有全局无可领取 ticket 且
|
||||
integration frontier 可推进时，才把 `INTEGRATION_REQUIRED` 交给 feature integration 路由。
|
||||
|
||||
## 🔴 Integration visibility RETRY
|
||||
|
||||
stdout 出现 `RETRY: dependency integration is not visible` 时，立即停止 claim 和实现。
|
||||
必须原样取得 `TICKET`、`DEPENDENCY`、`INTEGRATION_COMMIT`、`WORKSPACE`、`BRANCH`、
|
||||
`BRANCH_HEAD`、`TICKET_BRANCH`、`TICKET_BRANCH_HEAD`、`SYNC_BRANCH`、`MAIN_BRANCH`、
|
||||
`MAIN_HEAD`、`SYNC_COMMAND`。
|
||||
|
||||
任一字段缺失就报告原始 stdout 并停止，不自行推导 fetch、merge、rebase 或 cherry-pick。
|
||||
从任一现有目录执行返回的 `SYNC_COMMAND`；它负责创建或使用 `WORKSPACE`，不要预先切换到
|
||||
可能不存在的目录。成功后重新运行 status/claim；取得正式 assignment 前不得继续。
|
||||
|
||||
## 隔离、租约与恢复
|
||||
|
||||
- 请求 in-place 时，任意活动 claim 都令其 BUSY；活动 in-place claim 也阻止新 claim 和
|
||||
pending integration。
|
||||
- worktree ticket 可跨 feature 并发；活动 worktree 不阻止更早 feature integration。
|
||||
- `auto` 在全局无 claim 时选 in-place，否则选 worktree；同 owner 只恢复自己的 ticket。
|
||||
- in-place 要求 control checkout 除 `.scratch` 外干净；不要 stash、reset 或覆盖其他 session 改动。
|
||||
|
||||
claim 租约固定为 30 分钟，至少每 10 分钟运行 `main_loop.py heartbeat`，并在长验证/review
|
||||
前后续租。`reclaim` 只接管 stale 的 `claimed` ticket，保留 branch、workspace、未提交改动和
|
||||
原 `BASE`；接管后原 owner 不得 heartbeat/finish。
|
||||
|
||||
blocked ticket 用原 owner 的 `main_loop.py finish --result released` 释放；原 session 丢失时才用
|
||||
`main_loop.py release-ticket`，不要用 reclaim。claim 环境准备失败会占住该 ticket，也按此恢复；
|
||||
blocked/skipped 必须给 reason，released 回到 ready 并保留 workspace。禁止猜 ticket、复用通用
|
||||
owner 或自动转移 stale claim。
|
||||
|
||||
## 实现、Review 与 Finish
|
||||
|
||||
按顺序执行：读取已领取 ticket 的 spec → 按 `tdd` 实现与验证 → 提交全部实现 →
|
||||
运行 `code-review` 的 Standards/Spec 双轴 → 修复硬 finding 后重新提交、验证、完整 review →
|
||||
结构化证据调用 main_loop.py finish。
|
||||
|
||||
ticket review 的 fixed point 是 claim 返回的 `BASE`，或 RETRY 返回的 `FEATURE_HEAD`；
|
||||
Spec sources 是 `<STATE_ROOT>/<feature>/spec.md` 与
|
||||
`<STATE_ROOT>/<feature>/issues/<NN>-*.md`。只有对应 axis 零个未解决的硬 finding 才能映射为 pass；
|
||||
`code-review` 不给 pass/fail 判定，来源缺失、axis 跳过或仍有 finding 时不得填写 pass。
|
||||
|
||||
收到 `RETRY: feature advanced` 时，把该 `FEATURE_HEAD` 合入 ticket branch，重新验证并以它为新
|
||||
review base；只有成功合入 feature branch 后 ticket 才能 resolved。调用前读取
|
||||
`main_loop.py finish --help`，不得复用旧 artifact。
|
||||
|
||||
无人值守或当前 session 无法继续时，按 `main_loop.py finish --result blocked` 记录具体 reason。
|
||||
按各自 `--help` 调用 `main_loop.py status`、`main_loop.py heartbeat`、`main_loop.py finish`、
|
||||
`main_loop.py reclaim`、`main_loop.py release-ticket`、`main_loop.py block-feature`、
|
||||
`main_loop.py release-feature`；不维护命令职责表。
|
||||
|
||||
## 证据门禁
|
||||
|
||||
ticket、feature、main candidate 验证是三个独立门禁，不能互相替代。只接受 fresh UTF-8 JSON artifact；
|
||||
精确 verification/review schema 以 `finish --help` 和 `integrate --help` 为准。
|
||||
主循环校验摘要、Git object、branch tip、review base 与 workspace，并快照到
|
||||
`.scratch/<feature>/evidence/`。
|
||||
|
||||
artifact 无法证明命令真的执行过或报告来自真实 review；无法证明命令真的执行过时不得伪造 pass。
|
||||
完成前做 fresh verification，并按帮助输出构造结构化参数。禁止手工修改 ticket `Status`，
|
||||
禁止为旧 Blocked by 格式增加 fallback，禁止伪造或复用证据 artifact。
|
||||
Reference in New Issue
Block a user