Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)
This commit is contained in:
octopus
@@ -0,0 +1,211 @@
|
||||
> Core 中立版（Increment 6a 改写，原 deferHard verbatim）。编号与条目结构严格不变（C-2 不变量）；实例术语按 `core/adapters/TERMINOLOGY.md` 绑定。
|
||||
# 流程审计检查清单（Process Audit Checklist）
|
||||
|
||||
> 用于审计 `<instance-root>/` 流程基础设施本身的完整性、一致性与合规性。
|
||||
> 审计对象是这套 SDLC「工厂」本身（skills / checklists / templates / schemas），
|
||||
> 而非某个具体项目对流程的遵循情况（后者归 `retrospective`）。
|
||||
>
|
||||
> 依据：内部一致性规则、ISO 19011:2018（审核指南）、IEEE 1028-2008（软件评审与审计）、
|
||||
> 以及本仓库 `AGENTS.md` 工程约定。
|
||||
|
||||
> **维度命名空间（dimension namespace）**: 本清单中的维度代码（如 TRC）是**清单局部（checklist-local）**标识符，仅在本文档内唯一；其他清单可能对相同字母串绑定不同概念（如 code-review.md 的 TRC=Traceability vs 本清单的 TRC=Traceability 审计维度）。跨清单引用时必须带清单限定（如 audit-process.md TRC 10.3），不得使用裸代码。
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. 审计对象是 `<instance-root>/` 目录下的 `skills/`、`checklists/`、`templates/`、`schemas/`；
|
||||
2. 每个审计维度由一名独立审计员（Explorer，只读）负责，逐项判定 PASS / FAIL / NA（NA＝逐项"不适用"判定标记，不属于 findings JSON 的维度 verdict 枚举 PASS/WARN/FAIL/UNRESOLVED——UNRESOLVED 专指审计员崩溃/超时状态，勿混用）；
|
||||
3. 对 FAIL 项必须给出：具体文件位置、引用证据、可执行的修复建议；
|
||||
4. 审计员必须保持**独立性**（ISO 19011:2018）：仅依据文件事实判定，不臆测意图；
|
||||
5. 任一维度存在 FAIL 项须修订后重新审计，直至收敛。
|
||||
|
||||
**Known exceptions to INV 1.3** (inline self-check checklists — skills whose
|
||||
checklist obligations are embedded in the SKILL.md body by design):
|
||||
- `core/skills/writing-skills/SKILL.md` §"Authoring checklist" — methodology
|
||||
skill, inline RED/GREEN/REFACTOR self-check is its normative form.
|
||||
- `core/skills/codegraph-setup/SKILL.md` §"Verification checklist" —
|
||||
setup/installation skill, inline verification checklist is its normative form.
|
||||
- `core/skills/project-kickoff/SKILL.md` §"4. Workflow" step 4 (**Post-kickoff verification**) —
|
||||
setup/lifecycle skill; its self-check is the `octopus kickoff --check-only`
|
||||
tool's 5 readiness items, which is the tool-based equivalent of an inline
|
||||
checklist (analogous to codegraph-setup's CLI verification), not a
|
||||
`core/checklists/` artifact checklist.
|
||||
- `core/skills/analyze-dag/SKILL.md` — pipeline Producer (DAG route entry
|
||||
skill). Its producer-side self-check obligations are folded inline into the
|
||||
SKILL.md body (Topology Constraints §, Page-Size Budget, Requirement
|
||||
Registry, Exec-Resource Configuration) as the mechanically-checkable
|
||||
destination of the folded plan-checklist rows; the **gate-side** coverage is
|
||||
`core/checklists/dag-single-gate.md` (TOPO/REQMAP/RELEASE), not a
|
||||
producer self-check checklist. A thin `analyze-dag.md` wrapper would add no
|
||||
value over the in-skill rows + the single-gate checklist.
|
||||
- `core/skills/land-batch/SKILL.md` — merge-pr stage skill (batch PR
|
||||
landing). Its self-check obligations are inline by design: the fail-closed
|
||||
`## Preconditions (all mandatory, fail-closed)` block and the
|
||||
"Pre-validate locally (never enter CI red)" rung are the normative gates,
|
||||
backstopped by CI merge-gate mechanical checks — same doctrine as
|
||||
project-kickoff's tool-based self-check; a thin wrapper checklist would
|
||||
add no value.
|
||||
- Tool/utility & integration skills — `browser-debug`,
|
||||
`gitea-rest`, `image-interpret`, `headless-session-ops` — are
|
||||
non-artifact-producing (they drive tools / sessions / MCP servers, not SDLC
|
||||
pipeline artifacts), so INV 1.3's "产物型 skill" clause does not apply to
|
||||
them; their operational obligations are inline normative statements (e.g.
|
||||
`browser-debug`'s session-cleanup / screenshot-naming iron rules) by the same
|
||||
doctrine as the listed exemptions above.
|
||||
These are exempted per `audit/2026-08-11/round1/revision-summary` (writing-skills,
|
||||
codegraph-setup), `audit/2026-08-13/round1/revision-summary` (project-kickoff),
|
||||
`audit/2026-08-17/round1/revision-summary` (analyze-dag), and
|
||||
`audit/2026-09-01/round1/revision-summary` (land-batch);
|
||||
creating thin wrapper checklist files would add no value.
|
||||
|
||||
---
|
||||
|
||||
## 1. 清单完整性（INV — Inventory Completeness）
|
||||
|
||||
> 流水线阶段齐全、无孤儿文件。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 1.1 | SDLC 流水线各阶段均有对应 skill（analyze-dag→review-dag 单门→implement→review-code→verify→release→retrospective；legacy roadmap/requirements/design/plan 已归档 [org-internal #3072] phase 3，见 `<instance-root>/archive/`） | ☐ | ☐ | |
|
||||
| 1.2 | 每个 `skills/<name>/` 目录恰好包含一个 `SKILL.md`（例外：`_shared/` 目录不含 `SKILL.md`，为共享引用文档目录） | ☐ | ☐ | |
|
||||
| 1.3 | 每个产物型 skill 都有配套 `checklists/<name>.md`（无清单的自检要求即为缺口） | ☐ | ☐ | |
|
||||
| 1.4 | `checklists/` 中无孤儿清单（存在清单但无任何 skill 引用） | ☐ | ☐ | |
|
||||
| 1.5 | `templates/` 中无孤儿模板（存在模板但无任何 skill 引用） | ☐ | ☐ | |
|
||||
| 1.6 | `schemas/` 中无孤儿 schema（存在 schema 但无任何 skill 引用） | ☐ | ☐ | |
|
||||
| 1.7 | 每个 review-* skill 的维度数量与其引用清单的章节数量一致，或存在文档化的合并说明（每节恰好被一个维度覆盖） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 2. 交叉引用完整性（XREF — Cross-Reference Integrity）
|
||||
|
||||
> skill ↔ checklist ↔ template ↔ schema 的引用路径不得断裂。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 2.1 | skill 中引用的每个 `core/checklists/*.md` 路径真实存在 | ☐ | ☐ | |
|
||||
| 2.2 | skill 中引用的每个 `core/templates/*.md` 路径真实存在 | ☐ | ☐ | |
|
||||
| 2.3 | skill 中引用的每个 `core/schemas/*.json` 路径真实存在 | ☐ | ☐ | |
|
||||
| 2.4 | skill 中引用的 wiki `{slug}/...` 路径结构与其它 skill 一致；引用模式见 `_shared/gitea-read-patterns.md` / `_shared/gitea-write-patterns.md` | ☐ | ☐ | |
|
||||
| 2.5 | 清单中引用的标准编号（IEEE/ISO）在 skill References 中亦有呼应 | ☐ | ☐ | |
|
||||
| 2.6 | skill 之间相互引用的前序/后继阶段名称真实存在（无断链） | ☐ | ☐ | |
|
||||
| 2.7 | 引用的检查项编号（如 `ARCH 1.1–1.7`）在目标清单中确实存在 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 3. 元数据合规性（FM — Frontmatter Conformance）
|
||||
|
||||
> 每个 SKILL.md 的 frontmatter 必须符合 octopus skill 规范。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 3.1 | `name` 存在、小写连字符、≤64 字符，且与所在目录名一致 | ☐ | ☐ | |
|
||||
| 3.2 | `description` 存在且非空（缺失会被加载器过滤、永不触发） | ☐ | ☐ | |
|
||||
| 3.3 | `description` 同时说明「做什么」与「何时触发」 | ☐ | ☐ | |
|
||||
| 3.4 | `description` 使用第三人称（"Use when..."，而非 "I help..."） | ☐ | ☐ | |
|
||||
| 3.5 | 需要静默于相邻话题的 skill 使用了 "Use ONLY when..." 或 "Use ONLY after..." 限定 | ☐ | ☐ | |
|
||||
| 3.6 | `triggers`（如有）为关键词/文件名，前置了用户可能说出的字面词 | ☐ | ☐ | |
|
||||
| 3.7 | frontmatter 无未知顶层字段，YAML 可解析 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 4. 命名约定一致性（NAM — Naming Convention）
|
||||
|
||||
> 跨流程基础设施的命名必须统一。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 4.1 | 清单文件名使用产物名词形式（如 `implementation.md`、`code-review.md`），skill 名使用动词形式或标准 SDLC 产物名（如 `implement`、`review-code`；`frontend`、`writing-skills` 等按产物/领域命名的 skill，以及按工具命名的集成类 skill（`gitea-rest`、`codegraph-setup`）除外），共享清单以产物名命名（如 `verification.md`、`port.md`；已归档的 legacy 清单见 `<instance-root>/archive/checklists/`） | ☐ | ☐ | |
|
||||
| 4.2 | 维度代码（如 ARCH / SEC / TRC）在 skill 与清单间拼写一致 | ☐ | ☐ | |
|
||||
| 4.3 | 角色名称与 core/skills/_shared/roles/*.yaml 的 name 字段一致（Producer/Reviewer/Verifier/Tool/Coordinator）。旧角色名（Developer/Analyst/Architect 等）由 role.ts 中的 ROLE_ALIASES 安全映射，不再需要独立 YAML。不得使用已废弃的角色名（如 'Organizer'）。`escalation` 字段除可指向上述注册角色外，亦可指向有效的 subagent_type（如 'Builder'，其作为运行时可加载的构建型子代理类型） | ☐ | ☐ | |
|
||||
| 4.4 | 产物路径片段（wiki `{slug}/...`）命名跨 skill 统一；引用模式见 `_shared/gitea-read-patterns.md` / `_shared/gitea-write-patterns.md`。审计类产物使用日期 slug（如 wiki `audit/{date}/`）属允许例外 | ☐ | ☐ | |
|
||||
| 4.5 | 严重度等级（BLOCKER/MAJOR/MINOR/INFO）跨 skill 与 schema 一致 | ☐ | ☐ | 允许例外：`port-analysis.schema.json` 使用三值契约（BLOCKER/MAJOR/MINOR，永不产出 INFO），已在 schema description 中自证为对四值集的文档化例外 |
|
||||
| 4.6 | 裁决值（PASS/WARN/FAIL）跨 skill 与 schema 一致 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 流水线衔接（FLOW — Pipeline Cohesion）
|
||||
|
||||
> 阶段之间的前置条件与产物链必须闭合，无断裂。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 5.1 | 每个 skill 的 Preconditions 引用的前序产物，确由某个上游 skill 产出 | ☐ | ☐ | |
|
||||
| 5.2 | 每个 skill 的产物，确被某个下游 skill 作为输入消费（终点除外：verify、release、retrospective，以及发布/副作用类 skill 如 `review-artifact` (target: process)，其产出由人类或外部系统消费） | ☐ | ☐ | |
|
||||
| 5.3 | review-* skill 的输入路径与其对应生产 skill 的输出路径精确匹配（代码评审输入为项目源码树中 git diff 标识的文件；其余评审输入为 wiki `{slug}/` 下的文档，读取模式见 `_shared/gitea-read-patterns.md`；process 审计目标为第三输入类——本地 `<instance-root>/` 语料，无上游生产 skill，自产自审） | ☐ | ☐ | |
|
||||
| 5.4 | 收敛/审批关卡（如「Do NOT advance without approval」）在阶段切换处存在 | ☐ | ☐ | |
|
||||
| 5.5 | 阶段顺序无环（不存在 A 依赖 B 同时 B 依赖 A） | ☐ | ☐ | |
|
||||
| 5.6 | 每个 skill 声明的角色与模型分配在同类 skill 间一致 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 6. Schema 契约（SCH — Schema Contract）
|
||||
|
||||
> schema 被正确引用，且 skill 描述的字段与 schema 定义对齐。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 6.1 | skill 中要求写入的 JSON 产物均指明了对应的 `core/schemas/*.json` | ☐ | ☐ | 允许例外：(a) `precondition-gate.jsonl`（review-code/verify）为自版本化、机器可再生的 JSONL 记录，有意无 backing schema；(b) browser-debug 证据包（`browser/{session-id}/manifest.json` 等）由冻结共享契约 `browser-evidence-4486/shared/pack-manifest-v1` 等校验（写入方 `<harness-package>/src/browser/evidence-pack.ts`），不在 `core/schemas/` 下 |
|
||||
| 6.2 | skill 文中描述的字段名与 schema 的 `required`/`properties` 一致 | ☐ | ☐ | |
|
||||
| 6.3 | skill 描述的枚举值（verdict/severity）与 schema `enum` 一致 | ☐ | ☐ | |
|
||||
| 6.4 | 每个 schema 自身合法（`$schema`、`$id`、`type` 齐备） | ☐ | ☐ | |
|
||||
| 6.5 | 多个 skill 共用同一 schema 时语义一致（无相互冲突的字段约定） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 7. 重复与漂移（DUP — Duplication & Drift）
|
||||
|
||||
> 单一事实来源；术语不漂移。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 7.1 | 同一概念在不同 skill 中术语一致（无同义词漂移） | ☐ | ☐ | |
|
||||
| 7.2 | 检查项/规则无跨文件的实质性重复（应集中于清单而非散落于 skill） | ☐ | ☐ | |
|
||||
| 7.3 | 收敛准则（max_rounds、停止条件）在各 review-* skill 间一致或有理由不一致 | ☐ | ☐ | |
|
||||
| 7.4 | 标准编号引用一致（同一标准不出现多种写法） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 8. 审计原则合规（STD — Audit Standards / ISO 19011:2018 · IEEE 1028-2008）
|
||||
|
||||
> 体现独立性、客观证据、分级判定、可重复。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 8.1 | 审计员独立性：review-* skill 明确审计员只读、不得越权（ISO 19011:2018 §4） | ☐ | ☐ | |
|
||||
| 8.2 | 客观证据：findings 要求 location + evidence（IEEE 1028-2008 证据留痕） | ☐ | ☐ | |
|
||||
| 8.3 | 分级判定：严重度与裁决规则量化（pass_rate 阈值明确，非主观） | ☐ | ☐ | |
|
||||
| 8.4 | 可重复：审计员 prompt 标准化、温度低（确定性输出） | ☐ | ☐ | |
|
||||
| 8.5 | 防范范围收窄：明令禁止「只看重点/从简」类弱化措辞（IEEE 1028-2008 完整性） | ☐ | ☐ | |
|
||||
| 8.6 | 留痕：审计产物落盘到结构化文件，而非仅存于对话 | ☐ | ☐ | |
|
||||
| 8.7 | 闭环：存在重审循环与收敛/审批终止条件（ISO 19011:2018 跟踪与关闭） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 9. 工程约定符合度（AGT — AGENTS.md Conformance）
|
||||
|
||||
> 流程基础设施所描述/示例的工程做法须符合本仓库 `AGENTS.md` 及其**委托的约定源**：
|
||||
> `AGENTS.md` 将工程约定委托给 L1 `core/rules/*`（注入主会话）与 L2 wiki `rules/*`
|
||||
> （按需读取），故本维各项的「基线」是 `AGENTS.md` 委托到的实际约定文档（下各条注明）。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 9.1 | skill 示例命令与测试约定一致（基线：`core/rules/testing.md` — `bun run test:parallel`、从 package 目录运行、勿从 repo 根运行） | ☐ | ☐ | |
|
||||
| 9.2 | skill 示例的类型检查命令与 `core/rules/type-checking.md` 一致（package 目录 `bun typecheck`，非直接 `tsc`；repo 根整仓为 `bun turbo typecheck`） | ☐ | ☐ | |
|
||||
| 9.3 | skill 引用的 DB/迁移流程与 L2 wiki `rules/database`（Drizzle、`bun run db generate`）一致 | ☐ | ☐ | |
|
||||
| 9.4 | skill 描述的模块形态与 L2 wiki `rules/style-guide`（无 `export namespace`、自再导出）一致 | ☐ | ☐ | |
|
||||
| 9.5 | skill 描述的 Effect 用法与 L2 wiki `rules/effect-rules` 一致（如适用） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 10. 可追溯性（TRC — Traceability）
|
||||
|
||||
> 从需求到验证全链路可追溯；审计自身亦可追溯。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 10.1 | 存在贯穿全流水线的追溯机制（需求 ID → 设计 → 实现 → 验证） | ☐ | ☐ | |
|
||||
| 10.2 | 每个 review-* skill 都包含 Traceability 维度或等价检查 | ☐ | ☐ | |
|
||||
| 10.3 | 审计 finding 的 ID 规则唯一且可定位到具体检查项 | ☐ | ☐ | |
|
||||
| 10.4 | 审计历史（轮次、裁决、blocker/major 数）被记录于 status 产物 | ☐ | ☐ | |
|
||||
| 10.5 | 模型/角色分配变更可在 skill 中追溯（同类 skill 横向可比） | ☐ | ☐ | |
|
||||
@@ -0,0 +1,85 @@
|
||||
> Core 中立版（Increment 6a 改写，原 deferHard verbatim）。编号与条目结构严格不变（C-2 不变量）；实例术语按 `core/adapters/TERMINOLOGY.md` 绑定。
|
||||
# Bugfix 检查清单
|
||||
|
||||
> 开发者在修复 Bug 时自检使用。确保修复的是根因而非症状，且不引入新问题。
|
||||
|
||||
> **维度命名空间（dimension namespace）**: 本清单中的维度代码（如 TST/BEH/GATE/REG）是**清单局部（checklist-local）**标识符，仅在本文档内唯一；其他清单可能对相同字母串绑定不同概念（如 code-review.md 的 TST=Test Quality、verification.md 的 TST=Test Suite Completeness、port.md 的 TST=Test Porting）。跨清单引用时必须带清单限定（如 code-review.md TST 5.8），不得使用裸代码。
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. Phase 1-4 每阶段结束时检查对应项；
|
||||
2. Phase 5 完成后检查全部项；
|
||||
3. 所有项通过后方可提交。
|
||||
|
||||
---
|
||||
|
||||
## 1. 复现确认（REPRO — Reproduction）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------------- | ---- | ------ | ---- |
|
||||
| 1.1 | Bug 可以稳定复现（有明确的复现步骤） | ☐ | ☐ | |
|
||||
| 1.2 | 实际行为与 Bug 报告一致 | ☐ | ☐ | |
|
||||
| 1.3 | 如果无法复现，已向用户反馈原因并等待补充信息 | ☐ | ☐ | |
|
||||
| 1.4 | 已捕获环境快照（`ps aux`、`lsof -p PID`、日志文件大小、进程树 — pipeline 模式强制，standalone 建议） | ☐ | ☐ | |
|
||||
| 1.5 | 复现置信度评级 1–5（≥3 方可进入 pipeline 设计阶段；<3 → abort） | ☐ | ☐ | |
|
||||
| 1.6 | 已检索 Gitea wiki `{slug}/repro-notes` / `{slug}/bugfix-report` 中是否存在同类症状的先前调查报告，复用已知根因而非重新推导（via `wiki 读写 API（见 TERMINOLOGY）`） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因分析（ROOT — Root Cause）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------ | ---- | ------ | ---- |
|
||||
| 2.1 | 根因已定位到具体代码行（非模块级别） | ☐ | ☐ | |
|
||||
| 2.2 | 根因是底层逻辑缺陷，非表面症状 | ☐ | ☐ | |
|
||||
| 2.3 | 如果根因来自数据/环境/配置，已注明具体差异 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 3. 回归测试（TEST — Regression Test）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 3.1 | 已编写针对性的回归测试 | ☐ | ☐ | |
|
||||
| 3.2 | 回归测试在修复前 FAIL（确认覆盖了 Bug） | ☐ | ☐ | |
|
||||
| 3.3 | 回归测试在修复后 PASS | ☐ | ☐ | |
|
||||
| 3.4 | 如果无法编写自动化测试，已标注 `[flaky]` 并说明原因 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 4. 修复质量（FIX — Fix Quality）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------------- | ---- | ------ | ---- |
|
||||
| 4.1 | 修复是最小变更——只改了必须改的部分 | ☐ | ☐ | |
|
||||
| 4.2 | 未混入重构、风格调整或不相关的"顺手改" | ☐ | ☐ | |
|
||||
| 4.3 | 修复的是根因而非症状 | ☐ | ☐ | |
|
||||
| 4.4 | 同一模块的已有测试全部通过（修复未引入退化） | ☐ | ☐ | |
|
||||
| 4.5 | Commit 消息使用常规提交前缀（`fix:` / `refactor:` / `docs:`）并位于 `[{chunk-id}][{iteration}]` 之后 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 全面回归（REG — Full Regression）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------------------- | ---- | ------ | ---- |
|
||||
| 5.1 | `bun run test:parallel` 全部通过（零失败） | ☐ | ☐ | |
|
||||
| 5.2 | `bun typecheck` 无错误 | ☐ | ☐ | |
|
||||
| 5.3 | `bun lint` 无错误 | ☐ | ☐ | |
|
||||
| 5.4 | 如果有集成/端到端测试，已运行并全部通过 | ☐ | ☐ | |
|
||||
| 5.5 | 移交评审前已按 `core/checklists/code-review.md` 的 A11Y（§8）与 PERF（§4）节自检本次变更，并对全部改动文件跑 `bunx prettier --check`（pre-commit 钩子只扫提交时的 staged 文件，CR-COMMIT 把提交推迟到评审收敛后，移交前的工作区漂移没有任何钩子拦截——出处：sticky-diff-error 复盘 action item 2） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 6. 闭环（CLOSURE — Fix Linked to Commit）
|
||||
|
||||
> 防止"幽灵 artifact"：bugfix 报告已写出但代码修复从未提交/合并，导致 bug
|
||||
> 复发并重复调查。参见 `core/skills/retrospective/SKILL.md` 了解该规则的
|
||||
> 复盘出处。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------------- | ---- | ------ | ---- |
|
||||
| 6.1 | standalone bugfix 的 `{slug}/bugfix-report` 必须在同一周期内有**已合并提交**背书；若仅调查未应用修复，必须显式标注 "investigation only — no fix applied" | ☐ | ☐ | |
|
||||
| 6.2 | 若本次修复取代了先前的同类 `{slug}/bugfix-report`，已在该先前报告顶部标注 SUPERSEDED 并指向新 PR | ☐ | ☐ | |
|
||||
@@ -0,0 +1,198 @@
|
||||
# 代码评审检查清单
|
||||
|
||||
> 用于评审代码的正确性、设计一致性、安全性和可维护性。
|
||||
> 依据 IEEE 1028-2008 和行业最佳实践。
|
||||
|
||||
> **维度命名空间（dimension namespace）**: 本清单中的维度代码（如 TST/BEH/GATE/REG）是**清单局部（checklist-local）**标识符，仅在本文档内唯一；其他清单可能对相同字母串绑定不同概念（如 code-review.md 的 TST=Test Quality、verification.md 的 TST=Test Suite Completeness、port.md 的 TST=Test Porting）。跨清单引用时必须带清单限定（如 code-review.md TST 5.8），不得使用裸代码。
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. 阅读待评审的全部代码文件；
|
||||
2. 同时阅读设计文档中的相关章节作为参考基线；
|
||||
3. 逐项检查，判定为"通过"或"不通过"；
|
||||
4. 对"不通过"项注明具体文件名、行号和问题描述；
|
||||
5. 任一检查维度中若存在"不通过"项，须修订后重新评审；
|
||||
6. 所有维度均通过后方可合并或发布。
|
||||
7. 第 2 轮及以后的评审中，任何仅属外观性的 MINOR 发现（命名、注释、死代码、导入顺序、风格等不影响正确性或可读性的问题）必须满足其一：已修复并关闭，或在 synthesis 中以 `WAIVED-{id}` 条目显式豁免并注明原因。`WAIVED-{id}` 约定的规范定义见 `.octopus/skills/_shared/review-revision-prompt.md`（本清单的豁免标记形如 `WAIVED-COR-R2-001`）。
|
||||
8. **CR-COMMIT 门禁**：代码评审收敛（所有维度 PASS）后，必须将所有评审修订提交到工作分支，再进入 verify 阶段。未提交的评审修订不得通过 verify 放行。验证阶段（verify）启动前必须确认 `git status` 无未提交修改。
|
||||
9. **standalone-bugfix 模式的预先存在模式豁免**：在 standalone-bugfix 模式下，修复的范围应以最小化外科手术为原则。若 COR/STY/DOC 维度的发现指向的是**修复前已存在的模式**（并非本次变更引入），且该模式与文件中已有代码保持一致，则 `WAIVED` 或 `ACCEPTED_RISK` 是有效的处理方式。具体适用场景：
|
||||
- COR 1.9/1.10/1.13：错误处理策略在变更前已采用同等模式（如 `console.warn` 而非面向用户的错误提示、无超时策略等），本次变更未使其劣化
|
||||
- STY 6.8：文件/模块长度超过 200 行属于变更前已有的结构，拆分为独立重构任务（非本次 bugfix 范畴）
|
||||
- DOC 9.5：注释中的默认值初始化（如 `lastTriggerScrollTop = -1`）为防御性编程，在观察者建立前即被覆盖，无行为影响
|
||||
每次豁免必须在 synthesis 中以带编号的 `WAIVED-{id}` 或 `ACCEPTED_RISK` 条目记录原因。此豁免不影响其他维度的评审标准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 正确性、错误处理与兼容性检查（COR — Correctness, Error Handling & Compatibility）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| ---- | ------------------------------------------------------------ | ---- | ------ | ---- |
|
||||
| 1.1 | 逻辑分支完整，无遗漏的 if/else、switch case 或漏处理的枚举值 | ☐ | ☐ | |
|
||||
| 1.2 | 边界条件正确处理（空值、空集合、零值、负值、最大值/最小值） | ☐ | ☐ | |
|
||||
| 1.3 | null/undefined 在使用前已检查，无空引用风险 | ☐ | ☐ | |
|
||||
| 1.4 | 异步操作正确使用 await 或 Promise 链，无竞态条件 | ☐ | ☐ | |
|
||||
| 1.5 | 循环有正确的终止条件，无无限循环风险 | ☐ | ☐ | |
|
||||
| 1.6 | 类型转换安全（如字符串转数字、JSON 解析），有失败处理 | ☐ | ☐ | |
|
||||
| 1.7 | 无逻辑死区（unreachable code）或死代码（dead code） | ☐ | ☐ | |
|
||||
| 1.8 | 所有可能失败的操作（I/O、网络、解析、数据库）有错误处理 | ☐ | ☐ | |
|
||||
| 1.9 | 错误信息对用户友好（不暴露内部堆栈、路径或 SQL） | ☐ | ☐ | |
|
||||
| 1.10 | 外部服务调用有超时、重试和熔断策略（与设计文档一致） | ☐ | ☐ | |
|
||||
| 1.11 | 事务边界明确，异常时回滚，无部分提交 | ☐ | ☐ | |
|
||||
| 1.12 | 错误码和 HTTP 状态码语义正确（不把 500 当 400 用） | ☐ | ☐ | |
|
||||
| 1.13 | 异常被捕获且传播到合适的层级，无被吞掉的异常 | ☐ | ☐ | |
|
||||
| 1.14 | 异步错误（Promise rejection、EventEmitter error）有处理器 | ☐ | ☐ | |
|
||||
| 1.15 | 公共 API 的签名、参数和返回值未做不兼容变更（或已标注 breaking） | ☐ | ☐ | |
|
||||
| 1.16 | 配置项的新增/删除/改名有迁移路径或向后兼容处理 | ☐ | ☐ | |
|
||||
| 1.17 | 客户端（前端/移动端/SDK）与后端接口版本兼容 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计一致性与依赖检查（DGN — Design Compliance & Dependencies）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| ---- | ------------------------------------------------------ | ---- | ------ | ---- |
|
||||
| 2.1 | 代码实现了设计文档中该组件的全部指定接口和方法签名 | ☐ | ☐ | |
|
||||
| 2.2 | 组件职责与设计文档中声明的职责一致，无越界逻辑 | ☐ | ☐ | |
|
||||
| 2.3 | 组件依赖关系与设计文档的依赖图一致，无反向依赖 | ☐ | ☐ | |
|
||||
| 2.4 | 数据模型（字段、类型、关系）与设计文档的数据设计一致 | ☐ | ☐ | |
|
||||
| 2.5 | 接口输入输出的 Schema 与设计文档的接口设计一致 | ☐ | ☐ | |
|
||||
| 2.6 | 代码未引入设计文档中未提及的新依赖或新服务 | ☐ | ☐ | |
|
||||
| 2.7 | 架构模式（工厂、策略、仓储等）的使用方式与设计决策一致 | ☐ | ☐ | |
|
||||
| 2.8 | 若代码偏离设计，有明确的 ADR 或注释说明理由 | ☐ | ☐ | |
|
||||
| 2.9 | 已用 `graph usages`/`impact` 核验改动符号的所有调用方与传递影响均已处理，无遗漏的破坏性变更（评审时用代码图核对，而非 grep 逐文件追踪） | ☐ | ☐ | |
|
||||
| 2.10 | 实现文件结构与迭代计划中的架构描述一致（文件数、模块划分、依赖方向）。若偏离（如单文件合并替代多文件架构），迭代计划已更新或偏离理由于设计文档中标明 | ☐ | ☐ | |
|
||||
| 2.11 | 新增依赖有明确的技术理由（不在审查时追问"为什么需要它"） | ☐ | ☐ | |
|
||||
| 2.12 | 依赖版本已锁定（package-lock.json / bun.lock / 等同文件已更新） | ☐ | ☐ | |
|
||||
| 2.13 | 无已知漏洞的依赖版本（依据 CVE 数据库或 `npm audit` 等同检查） | ☐ | ☐ | |
|
||||
| 2.14 | 无引入未使用的依赖 | ☐ | ☐ | |
|
||||
| 2.15 | 许可证兼容，无 GPL/AGPL 等强传染性许可证引入到非 GPL 项目 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 3. 安全性检查（SEC — Security）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| ---- | ----------------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 3.1 | 用户输入在执行 SQL/命令/HTML 前已参数化或转义 | ☐ | ☐ | |
|
||||
| 3.2 | 身份认证逻辑无绕过路径，会话令牌安全生成和验证 | ☐ | ☐ | |
|
||||
| 3.3 | 授权检查在关键操作前执行，无 IDOR（越权访问）风险 | ☐ | ☐ | |
|
||||
| 3.4 | 敏感数据（密码、令牌、密钥、PII）不在日志、错误消息或响应中泄露 | ☐ | ☐ | |
|
||||
| 3.5 | 加密算法为业界推荐标准（无 MD5/SHA1/DES 用于安全目的），密钥管理合规 | ☐ | ☐ | |
|
||||
| 3.6 | 输入校验在服务端执行（不依赖客户端校验） | ☐ | ☐ | |
|
||||
| 3.7 | 无硬编码的凭据、密钥、内网地址或环境特定值 | ☐ | ☐ | |
|
||||
| 3.7.1 | 暂存区/提交无符号链接，无机器本地绝对路径引用（`git diff --cached --diff-filter=T` 为空）| ☐ | ☐ | |
|
||||
| 3.8 | 安全相关配置项（CORS、CSP、速率限制）符合设计文档安全章节 | ☐ | ☐ | |
|
||||
| 3.9 | SAST 结论已核对：PR 存在时引用同 SHA 的 CI SAST 结果（`sast.yml`，无新增 HIGH/CRITICAL 发现）；无 PR 或同 SHA 无扫描结果时标注 `UNVERIFIABLE-LOCAL`，留待 verify Phase 2.5 处理。评审员为只读权限，不自行运行扫描工具 | ☐ | ☐ | |
|
||||
| 3.10 | 针对 CI SAST 报告的 HIGH 发现：True Positive 已修复或路由 Developer；False Positive 已标注排除理由（引用 `sast.yml` 产物，不重复推导） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 4. 性能检查（PERF — Performance）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| ---- | ------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 4.1 | 循环内无同步 I/O 或数据库查询（N+1 问题） | ☐ | ☐ | |
|
||||
| 4.2 | 算法复杂度合理（无 O(n²) 或更高在主路径中，除非设计明确接受） | ☐ | ☐ | |
|
||||
| 4.3 | 资源（连接、文件句柄、缓冲区）在使用后释放，无泄漏风险 | ☐ | ☐ | |
|
||||
| 4.4 | 查询使用了索引，EXPLAIN 计划与设计文档索引设计一致 | ☐ | ☐ | |
|
||||
| 4.5 | 适度使用缓存和批处理，无过早优化但也无非受控的重复计算 | ☐ | ☐ | |
|
||||
| 4.6 | 异步操作非阻塞，长耗时操作用队列或后台任务处理 | ☐ | ☐ | |
|
||||
| 4.7 | 前端：列表子项有稳定 key，事件处理器引用稳定，无不必要的重渲染 | ☐ | ☐ | |
|
||||
| 4.8 | 前端：大列表使用虚拟滚动或分页，非首屏组件使用代码分割（lazy） | ☐ | ☐ | |
|
||||
| 4.9 | 前端：图片有懒加载（`loading="lazy"`）和尺寸占位，无布局偏移 | ☐ | ☐ | |
|
||||
| 4.10 | 前端：`useMemo`/`useCallback`/`computed`/`derived` 使用合理，无不必要的计算 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试质量检查（TST — Test Quality）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------ | ---- | ------ | ---- |
|
||||
| 5.1 | 新增代码有对应的测试（单元或集成），覆盖主要路径和分支 | ☐ | ☐ | |
|
||||
| 5.2 | 测试覆盖了边界条件（空值、极值、异常路径） | ☐ | ☐ | |
|
||||
| 5.3 | 测试断言验证了具体行为，非仅"不抛异常"或"返回非空" | ☐ | ☐ | |
|
||||
| 5.4 | 测试相互独立，可任意顺序运行，无共享可变状态 | ☐ | ☐ | |
|
||||
| 5.5 | Mock/Stub 的使用合理，模拟的外部行为与真实行为一致 | ☐ | ☐ | |
|
||||
| 5.6 | 测试命名清晰表达了测试场景和预期结果 | ☐ | ☐ | |
|
||||
| 5.7 | 本次变更涉及的测试已通过（`test:changed`，由 mechanical-green gate 机器判定，评审员引用 gate 结果即可）。全量套件（`test:parallel`）归 verify，不是代码评审门禁（[org-internal #2598] 检查分层） | ☐ | ☐ | |
|
||||
| 5.8 | 评审发现的"dummy fixture / harness 默认值漂移"类问题，不能仅凭 `WAIVED` 处置：若漂移值是 harness 对**生产 CLI/配置默认值**的镜像（如 harness 旧 owner 默认 vs CLI 新 owner 默认这类 token 漂移），WAIVED 会把真实漂移放行到 post-merge（[org-internal #3169] TST-F002 → 后续 [org-internal #3172] 才修）。处置前确认该值是否被生产路径读取；被读取则必须 FIX 或显式登记 TD | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 6. 风格与约定检查（STY — Style & Convention）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------ | ---- | ------ | ---- |
|
||||
| 6.1 | 命名遵循项目约定（函数名、变量名、文件名、目录结构） | ☐ | ☐ | |
|
||||
| 6.2 | 缩进、空格、引号、分号、行长度与项目格式化配置一致 | ☐ | ☐ | |
|
||||
| 6.3 | 函数/方法长度合理（通常 ≤ 50 行），单一职责 | ☐ | ☐ | |
|
||||
| 6.4 | 导入语句有序分组（第三方、内部、相对），无未使用的导入 | ☐ | ☐ | |
|
||||
| 6.5 | 无注释掉的代码块（应删除或用版本控制追溯） | ☐ | ☐ | |
|
||||
| 6.6 | 类型声明充分，无不必要的 `any` 或隐式类型 | ☐ | ☐ | |
|
||||
| 6.7 | Lint 零错误已由机器判定（mechanical-green gate 与 CI 的 `bun oxlint --deny-warnings`）；评审员引用 gate/CI 结果即可，只复核 lint 覆盖不到的约定项（6.1–6.6、6.8），不重复人工推导 | ☐ | ☐ | |
|
||||
| 6.8 | 文件/模块长度 ≤ 200 行（超出需拆分）。模块过长降低可维护性和 review 效率 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 7. 数据库与数据检查（DBT — Database & Data）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 7.1 | 数据库迁移可安全回滚（down migration 正确且与 up 对称） | ☐ | ☐ | |
|
||||
| 7.2 | 查询使用参数化，无拼接 SQL 字符串 | ☐ | ☐ | |
|
||||
| 7.3 | 索引使用与设计文档的索引设计对应，EXPLAIN 计划合理 | ☐ | ☐ | |
|
||||
| 7.4 | 事务范围最小化（不在事务内执行外部调用或长计算） | ☐ | ☐ | |
|
||||
| 7.5 | 数据库连接生命周期正确，连接池配置合理 | ☐ | ☐ | |
|
||||
| 7.6 | 无大规模数据迁移导致锁表风险，大表变更方案已说明 | ☐ | ☐ | |
|
||||
| 7.7 | 数据库 Schema 变更对已有数据向后兼容（新字段允许 NULL 或有默认值） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 8. 可访问性与浏览器兼容性检查（A11Y — Accessibility & Browser Compatibility）
|
||||
|
||||
> 适用于所有面向用户的前端代码。确保 UI 可被各类用户（包括使用辅助技术者）正常使用。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| ---- | ----------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 8.1 | 交互元素使用原生语义 HTML（`<button>`/`<a>`/`<input>` 而非 `<div>` 模拟） | ☐ | ☐ | |
|
||||
| 8.2 | 图片有有意义的 `alt` 文本；纯装饰性图片使用 `alt=""` 或 CSS background | ☐ | ☐ | |
|
||||
| 8.3 | 表单控件有关联的 `<label>` 元素（非仅 placeholder） | ☐ | ☐ | |
|
||||
| 8.4 | 所有交互元素可通过键盘访问和操作（Tab 聚焦，Enter/Space 激活，方向键导航） | ☐ | ☐ | |
|
||||
| 8.5 | 模态框/弹窗：打开时焦点移入首元素，关闭时焦点回退触发按钮，ESC 可关闭 | ☐ | ☐ | |
|
||||
| 8.6 | 动态内容更新有 `aria-live` 通知（如搜索结果显示数、表单错误提示） | ☐ | ☐ | |
|
||||
| 8.7 | 颜色对比度合规：正文 ≥ 4.5:1，大文本 ≥ 3:1，非仅靠颜色传达信息 | ☐ | ☐ | |
|
||||
| 8.8 | 页面标题层级（`h1`→`h2`→`h3`）有逻辑层次，无跳级 | ☐ | ☐ | |
|
||||
| 8.9 | `aria-label`/`aria-labelledby` 为仅图标按钮、导航区提供了屏幕阅读器标签 | ☐ | ☐ | |
|
||||
| 8.10 | 焦点指示器可见（`:focus-visible`），无 `outline: none` 但未提供替代样式 | ☐ | ☐ | |
|
||||
| 8.11 | a11y 自动化扫描（`a11y.yml` / axe-core）结果已引用：PR 命中触发路径时以同 SHA CI 结论为准（无新增违规项），评审员不重复运行；语义性条目（8.1–8.10）仍由评审判断 | ☐ | ☐ | |
|
||||
| 8.12 | 前端：目标浏览器（Chrome/Firefox/Safari/Edge 最近 2 个主版本）下功能正常 | ☐ | ☐ | |
|
||||
| 8.13 | 前端：CSS 特性（Grid/Flexbox/Custom Properties）在目标浏览器均有支持或降级方案 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 9. 文档检查（DOC — Documentation）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ---------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 9.1 | 复杂算法、非常规优化或非直觉的逻辑有解释性注释 | ☐ | ☐ | |
|
||||
| 9.2 | 对外 API 的接口文档已同步更新（参数、返回值、错误码） | ☐ | ☐ | |
|
||||
| 9.3 | 面向用户的错误消息清晰、可操作（不应是"系统错误，请重试"） | ☐ | ☐ | |
|
||||
| 9.4 | README / runbook / 运维文档如有必要已更新（如新增配置项） | ☐ | ☐ | |
|
||||
| 9.5 | 注释与代码一致（代码已改但注释未改视为文档错误） | ☐ | ☐ | |
|
||||
| 9.6 | 废弃的 API/配置有 `@deprecated` 标记和替代方案说明 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 10. 可追溯性完整性检查（TRC — Traceability Completeness）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| ---- | ------------------------------------------------------------------ | ---- | ------ | ---- |
|
||||
| 10.1 | 每次代码修改的 commit/PR 描述包含对应的工作项 ID | ☐ | ☐ | |
|
||||
| 10.2 | 每个验收标准的实现均有对应的自动化测试用例 | ☐ | ☐ | |
|
||||
| 10.3 | 无验收标准遗漏测试或手动验证路径（全部覆盖） | ☐ | ☐ | |
|
||||
| 10.4 | 代码修改范围未超出工作项定义（无"顺便修"的无关变更） | ☐ | ☐ | |
|
||||
| 10.5 | 新增的需求引用（REQ-F-{NNN} / REQ-NF-{NNN}）在代码中有对应实现 | ☐ | ☐ | |
|
||||
| 10.6 | 已删除/弃用的代码有明确的移除原因和替代方案说明 | ☐ | ☐ | |
|
||||
| 10.7 | 测试报告能按工作项 ID 筛选（测试与工作项可交叉引用） | ☐ | ☐ | |
|
||||
@@ -0,0 +1,59 @@
|
||||
# 单门三维审查 checklist（review-dag）
|
||||
|
||||
> 单门 `review-dag` 替代 `review-design-space` + `review-iteration-plan` 双门（spec-02 §1 D-02）。
|
||||
> 门内分层三维：**TOPO**（拓扑）、**REQMAP**（需求映射）、**RELEASE**（滚动放行）。
|
||||
> 省的是编排开销，不省修订循环——三维各审独立风险面。
|
||||
>
|
||||
> **权威源**：本文件判据逐行复制 `dag-pipeline/spec-04` §1 三张表
|
||||
> （含 `NFR:` 前缀 / 里程碑边 / 里程碑节点豁免与 `estimated_sessions` 判据）。
|
||||
> 若本文件与 spec-04 §1 不一致，以 spec-04 §1 为唯一权威源。
|
||||
> （`spec-0N` 前身为 `dag-pipeline/03-design-0N-*`，2026-08-21 [org-internal #3072] phase 3
|
||||
> 升格迁移，旧名仅保留墓碑占位以维持旧 URL 可达。）
|
||||
|
||||
## TOPO — 拓扑维
|
||||
|
||||
| 检查项 | 判据 |
|
||||
|---|---|
|
||||
| 环检测 | 边方向图无环；有环 = BLOCKER |
|
||||
| 依赖正确性 | 每条边 `from→to` 方向正确（契约生产方先于消费方）；缺边/错边 = MAJOR |
|
||||
| 大小均匀性 | 节点工作量分布均匀，无"巨型节点"；巨型节点 = 单个 task 节点 `size_attrs.estimated_sessions ≥ 2` → MAJOR（需拆分；INFO 豁免不适用） |
|
||||
| **粒度下限** | 每个 task 节点预估实现时长由 `size_attrs.estimated_hours`/`estimated_sessions` 承载（冻结字段，见 spec-02 §2.1）；判据一律以 `estimated_sessions` 为准（两字段一致性不变量见 spec-02 §2.1，完整分档见 spec-03 §3 规则 3）：字段不一致（`|estimated_hours − 8 × estimated_sessions| > 2`）= MAJOR（需 `analyze-dag` 重填）；`estimated_sessions < 0.25`（对应约 `estimated_hours < 2`）= 低于下限（MAJOR，≥3 处 = BLOCKER）；`1 < estimated_sessions < 2` = 超出上限（MINOR，提示拆分；连续集成性工作不可拆分则 INFO）；`estimated_sessions ≥ 2` = 巨型节点 → MAJOR（需拆分，见「大小均匀性」行，INFO 豁免不适用）（防工单元数据成本爆炸） |
|
||||
| 里程碑位置 | 每个 `cross_session_in ≥ 2` 汇聚点已焊入里程碑（spec-03 规则 2）；缺失 = BLOCKER |
|
||||
| 可执行性 | 每个 task 节点可被单个 session 独立实现（EXE 折叠项；里程碑节点无实现工作、由 verify 承担，不参与本判据） |
|
||||
| 页尺寸自检信号 | 读 `{epic-slug}/dag` 页首 `> 页尺寸自检: 超限` 标志（spec-02 §2.6）→ 以 **INFO** finding 记录于 synthesis（`summary` = 页尺寸超限、子页已下沉 `{subpages}`），供 retrospective 统计与试点负责人核查；**不改变任何门判据、不触发重派生**（非 PASS/FAIL 判据） |
|
||||
|
||||
## REQMAP — 需求映射维
|
||||
|
||||
| 检查项 | 判据 |
|
||||
|---|---|
|
||||
| 需求覆盖 | **每需求至少一节点**：需求登记表每条 `REQ-F-{NNN}` 被 ≥1 节点的 `req_refs` 引用（无"有需求无节点"遗漏） |
|
||||
| 节点溯源 | **每 task 节点至少一需求**：每 task 节点 `req_refs` 非空且引用有效编号（无"有节点无需求"过度分解） |
|
||||
| 验收标准可证伪 | 每 task 节点 `acceptance_criteria` 可证伪且映射 `test_id`（CLR 折叠项：无"视情况而定"；`NFR:` 前缀条目不参与本判据——其验证由 per-task review-code + 里程碑 verify 承担，见 spec-02 §2.9） |
|
||||
| **AC 路径覆盖** | 每 task 节点验收标准覆盖正常路径、错误路径、边界场景三类（`.octopus/archive/checklists/requirements-analysis.md` TST 8.3/8.7 等价）；缺错误/边界路径 = MAJOR（`NFR:` 前缀条目不参与本判据——其验证由 per-task review-code + 里程碑 verify 承担，见 spec-02 §2.9） |
|
||||
| 契约↔节点一致性 | 每条 task 间跨 session 边的 `contract_ref` 与两端节点验收标准一致（里程碑边无 `contract_ref`、不参与本判据，见 spec-02 §2.1 / spec-03 §2） |
|
||||
|
||||
> **REQMAP 维仅审 task 节点**：milestone 节点无 `req_refs`/`acceptance_criteria`（只有 DoD，spec-03 §3 规则 2(b)），由 spec-05 里程碑 DoD 承担，非评审对象（spec-08 §2 里程碑行 `评审深度` 列 `—`）——故「每 task 节点」均不含里程碑行，含里程碑的 DAG 不会在 REQMAP 维产生误报。
|
||||
|
||||
> **AC 下沉子页的读取路径**：当节点 AC 细目因 `{epic-slug}/dag` 页尺寸预算超限下沉到 `{epic-slug}/dag-nodes/{node-id}` 子页时（spec-02 §2.6），reviewer 按 `{epic-slug}/dag` 页内 `{node-id} → {epic-slug}/dag-nodes/{node-id}` 指针读取子页核对「验收标准可证伪」「AC 路径覆盖」判据（子页 AC 与页内指针同源，均为冻结副本 `{epic-slug}/dag` 的一部分）。
|
||||
|
||||
## RELEASE — 滚动放行维
|
||||
|
||||
| 检查项 | 判据 |
|
||||
|---|---|
|
||||
| 就绪规则 | 节点 `ready` 当且仅当其所有跨 session 入边源节点均处于各自类型的终结态（task 源节点 `done`、里程碑源节点 `green`；同 session 边不阻塞就绪） |
|
||||
| 依赖批放行 | 按依赖层分批放行：一层内互不依赖的节点同批 `ready`（最大化并行，见 spec-05 里程碑） |
|
||||
| 契约冻结范围 | 仅 task 间的跨 session 边进入 `frozen`；同 session 边与里程碑边不冻结（spec-02 §1 D-05；里程碑边 `contract_state` 不适用，见 spec-02 §2.1 / spec-03 §2） |
|
||||
| 放行风险前移 | 高风险节点（breaking 契约 / 大 fan-out）前移至早期批次（RISK 折叠项）。**操作化锚点**：breaking 契约节点不得晚于其所在依赖层内其它非 breaking 节点的最早可用批次（同层内先于或等于）；**大 fan-out** = 单节点跨 session 出边数 ≥ 3（取 `cross_session_edge_count` 阈值表 D3 档起点，spec-06 §2），此类节点同样适用「不晚于同层最早批次」规则——reviewer 按拓扑层序对批次划分做机械核对 |
|
||||
| 估算合理性 | 各 **task** 节点 `size_attrs.estimated_hours`/`estimated_sessions`（冻结字段）已填写、取值在 TOPO「粒度下限」「大小均匀性」界内（两字段一致性不变量见 spec-02 §2.1），并支撑批次划分——同批并行节点由跨 session 边拓扑可达性决定（「依赖批放行」行）；容量/并发上限属 Orchestrator 执行期资源配置、单门不审（§2.1 PAR 4.4 丢弃行，EST 折叠项）——reviewer 对照冻结 node schema 逐 **task** 节点核验该字段存在且取值合理（里程碑节点无实现工作、不填，见 spec-02 §2.1 / spec-03 §3） |
|
||||
|
||||
## 门收敛规则
|
||||
|
||||
| 项 | 规则 |
|
||||
|---|---|
|
||||
| 轮次上限 | 由评审深度派生（spec-06）：D1≤2，D2≤3，D3≤3，D4≤4 |
|
||||
| PASS | 三维均 0 BLOCKER 且 0 MAJOR |
|
||||
| WARN | 0 BLOCKER；MAJOR 在修订轮内关闭；MINOR/INFO 允许（收敛为 PASS） |
|
||||
| FAIL | 任一维存在 BLOCKER |
|
||||
| INFO 处理 | INFO 不阻塞，记录供 retrospective 统计与试点负责人核查（review-dag 因 `never_trim: true` 结构性不可裁剪——gate-trim 元进程已退役，该字段自足于 `dag:` 块，见 spec-07 §5） |
|
||||
| 部分重审 | **round 3 起**（round 2 仍全维重审——三维共享 DAG 形状/字段副作用面，先以一轮全维重审建立干净基线，再于 round 3 起缩窄；与共享 review-artifact skill「round 2 起部分重审」的差异是有意的，因本门仅 3 维且互为副作用面）轮间只重审上一轮的 FAIL / WARN（含未关闭 BLOCKER 或 MAJOR 的维）/ UNRESOLVED 维（不省修订循环）；维度需重审 = 该维 verdict 为 FAIL / WARN（含未关闭 BLOCKER 或 MAJOR）/ UNRESOLVED，MINOR/INFO 维视为通过不复跑。任一维修订改变**共享 DAG 形状（节点/边集合）或共享字段（`size_attrs`、AC 文本、契约内容）**时，以该字段为判据输入的相关维随轮重验（三维互为副作用面） |
|
||||
| 输出 | 单门 synthesis（复用 `synthesis.schema.json`，`dimensions` 键为 TOPO/REQMAP/RELEASE）+ commit status `pipeline/review-dag` |
|
||||
@@ -0,0 +1,115 @@
|
||||
# 前端实现自检清单
|
||||
|
||||
> 开发者在编写前端代码前后自检使用。确保组件结构合理、样式一致、状态完整、
|
||||
> 可访问且可测试。分为"实现前"（PRE）和"实现后"（POST）两部分。
|
||||
> 全部通过后方可提交代码评审。
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **PRE** 项在开始写组件前检查；
|
||||
2. **POST** 项在完成编码和所有验证命令后检查；
|
||||
3. 对"不通过"项必须在代码评审前修复；
|
||||
4. 无法满足的项标记 `[N/A: <原因>]`。
|
||||
|
||||
---
|
||||
|
||||
## 实现前（PRE — Pre-Implementation）
|
||||
|
||||
### 1. 上下文完备性
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ----- | ------------------------------------------------------------------ | ---- | ------ | --- | ---- |
|
||||
| PRE-1 | 已确定项目框架（React / Vue / Svelte / SolidJS / Angular） | ☐ | ☐ | ☐ | |
|
||||
| PRE-2 | 已确定样式方案（Tailwind / CSS Modules / styled-components / ...） | ☐ | ☐ | ☐ | |
|
||||
| PRE-3 | 已读取至少 3 个同模块的现有文件（UI 工作同类组件），理解命名、结构和样式模式（共享 brownfield 规则，规范出处：`.octopus/skills/review-code/SKILL.md` §"Greenfield vs. Brownfield"） | ☐ | ☐ | ☐ | |
|
||||
| PRE-4 | 已确认路由模式（file-based / config-based）和新组件路由位置 | ☐ | ☐ | ☐ | |
|
||||
| PRE-5 | 已确认项目使用的 UI 基础库（Kobalte / Radix / Headless UI / ...） | ☐ | ☐ | ☐ | |
|
||||
| PRE-6 | 若项目有设计系统（token / theme / spacing），已确认取值方式 | ☐ | ☐ | ☐ | |
|
||||
| PRE-7 | Pipeline 模式：已读取设计文档的组件设计、接口设计、NFR 章节（DAG 路由：设计输入解析自冻结 DAG 副本 `{epic-slug}/dag` 节点规格 + 跨 session 边契约，见 `implementation.md` 使用说明第 5 条） | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 2. 组件边界
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ----- | --------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-8 | 组件职责单一——一个组件只做一件事 | ☐ | ☐ | ☐ | |
|
||||
| PRE-9 | Props 类型已列出（TypeScript 接口 / PropTypes / defineProps） | ☐ | ☐ | ☐ | |
|
||||
| PRE-10| 所有需要的 UI 状态已识别：loading / empty / error / success / edge | ☐ | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 实现后（POST — Post-Implementation）
|
||||
|
||||
### 3. 组件结构
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ----------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-1 | 组件命名清晰、遵循项目约定（PascalCase / kebab-case） | ☐ | ☐ | ☐ | |
|
||||
| POST-2 | 所有 Props 有完整类型，无 `any` 类型 | ☐ | ☐ | ☐ | |
|
||||
| POST-3 | 组件文件结构符合项目约定（单文件 / 目录+index / co-located） | ☐ | ☐ | ☐ | |
|
||||
| POST-4 | 无巨型组件（> 200 行）——必要时已拆分为子组件 | ☐ | ☐ | ☐ | |
|
||||
| POST-5 | 事件处理器和回调遵循项目命名规范（`on*` / `handle*`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 4. 样式与设计系统
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | -------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-6 | 使用项目统一的样式方案，未引入新的样式库 | ☐ | ☐ | ☐ | |
|
||||
| POST-7 | 若使用 Tailwind：无冗余类名堆积，复杂样式已提取为 `@apply` 或组件 | ☐ | ☐ | ☐ | |
|
||||
| POST-8 | 响应式断点已处理（移动端/平板/桌面），无横向溢出 | ☐ | ☐ | ☐ | |
|
||||
| POST-9 | 若项目有暗色模式：组件在亮/暗主题下均可正常显示 | ☐ | ☐ | ☐ | |
|
||||
| POST-10| 使用项目设计 token（颜色/间距/字体），无硬编码魔法数值 | ☐ | ☐ | ☐ | |
|
||||
| POST-11| 动画/过渡遵循项目约定（`motion` / CSS transition / ...），无突兀跳动 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 5. 状态覆盖
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ----------------------------------------------------------------| ---- | ------ | --- | ---- |
|
||||
| POST-12| **Loading 状态**：数据加载时有骨架屏/加载指示器，布局不跳动 | ☐ | ☐ | ☐ | |
|
||||
| POST-13| **Empty 状态**：无数据时有友好提示和操作引导（非空白页） | ☐ | ☐ | ☐ | |
|
||||
| POST-14| **Error 状态**：请求失败时显示错误信息和重试/恢复操作 | ☐ | ☐ | ☐ | |
|
||||
| POST-15| **Edge cases**：超长文本截断、特殊字符、空数组、`null`/`undefined` 值均已处理 | ☐ | ☐ | ☐ | |
|
||||
| POST-16| 数据更新后 UI 正确反映最新状态（无过期数据残留） | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 6. 可访问性（a11y）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ------------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-17| 使用语义化 HTML 元素（`<button>` 而非 `<div onclick>`） | ☐ | ☐ | ☐ | |
|
||||
| POST-18| 图片/图标有有意义的 `alt` 文本（纯装饰性图片使用 `alt=""`） | ☐ | ☐ | ☐ | |
|
||||
| POST-19| 表单控件有关联的 `<label>`（非仅 placeholder） | ☐ | ☐ | ☐ | |
|
||||
| POST-20| 所有交互元素可通过键盘访问（Tab 导航，Enter/Space 激活） | ☐ | ☐ | ☐ | |
|
||||
| POST-21| 弹窗/模态框：打开时焦点移入，关闭时焦点回退，ESC 可关闭 | ☐ | ☐ | ☐ | |
|
||||
| POST-22| 动态内容更新（加载完成/错误提示/列表变化）有适当的 `aria-live` 通知 | ☐ | ☐ | ☐ | |
|
||||
| POST-23| 色彩对比度：正文 ≥ 4.5:1，大文本 ≥ 3:1，非仅靠颜色传达信息 | ☐ | ☐ | ☐ | |
|
||||
| POST-24| 页面有逻辑的标题层级（`h1` → `h2` → `h3`），无跳级 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 7. 性能
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | -------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-25| 无不必要的重渲染——列表子项 key 稳定、事件处理器引用稳定 | ☐ | ☐ | ☐ | |
|
||||
| POST-26| 大列表使用虚拟滚动或分页（非一次性渲染全部） | ☐ | ☐ | ☐ | |
|
||||
| POST-27| 图片使用懒加载（`loading="lazy"`），有合适的 `width`/`height` 防止布局偏移 | ☐ | ☐ | ☐ | |
|
||||
| POST-28| 非首屏组件考虑代码分割（`lazy()` / `defineAsyncComponent`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 8. 代码质量
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ----------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-29| `bun typecheck`（或项目等效命令）通过，无类型错误 | ☐ | ☐ | ☐ | |
|
||||
| POST-30| `bun lint`（或项目等效命令）通过，无错误或警告 | ☐ | ☐ | ☐ | |
|
||||
| POST-31| 无注释掉的代码块或 `console.log` 调试语句 | ☐ | ☐ | ☐ | |
|
||||
| POST-32| 无硬编码的 API 地址、密钥或环境特定值——使用环境变量或配置 | ☐ | ☐ | ☐ | |
|
||||
| POST-33| 没有因 UI 改动导致的不相关组件样式错乱 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 9. 前端测试
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ------------------------------------------------------------------ | ---- | ------ | --- | ---- |
|
||||
| POST-34| 新组件有基础渲染测试（"does it render without crashing"） | ☐ | ☐ | ☐ | |
|
||||
| POST-35| 关键交互有行为测试（点击/输入/提交触发预期回调或状态变化） | ☐ | ☐ | ☐ | |
|
||||
| POST-36| 至少覆盖 loading / error / empty 其中一种边界状态的测试 | ☐ | ☐ | ☐ | |
|
||||
| POST-37| 若项目使用 Storybook：新组件有至少一个 story | ☐ | ☐ | ☐ | |
|
||||
| POST-38| `bun run test:parallel`（或项目等效命令）全部通过 | ☐ | ☐ | ☐ | |
|
||||
@@ -0,0 +1,153 @@
|
||||
# 实现自检清单
|
||||
|
||||
> 开发者在编写代码前后自检使用。确保代码忠实实现设计、可测试且符合项目规范。
|
||||
> 分为"实现前"（PRE）和"实现后"（POST）两部分。全部通过后方可提交代码评审。
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **PRE** 项在开始写代码前检查；
|
||||
2. **POST** 项在完成编码和所有验证命令后检查；
|
||||
3. 对"不通过"项必须在代码评审前修复；
|
||||
4. 无法满足的项标记 `[N/A: <原因>]`；
|
||||
5. **DAG 路由产物解析（[org-internal #3072] phase 3 后唯一管线模式）**：DAG 运行不存在
|
||||
legacy `{slug}/04-plan-*` / `{slug}/03-design-*` 页面，PRE-1～PRE-7、
|
||||
PRE-11、PRE-12、PRE-19、POST-15.1 引用的产物按 `implement`/`verify`
|
||||
SKILL 的 DAG-route read map 解析：工作项定义 → 冻结 DAG 副本
|
||||
`{epic-slug}/dag` 节点规格 + 节点工单正文；验收条件与声明的 `test_id`
|
||||
→ 节点 `acceptance_criteria`（含 `{epic-slug}/dag-nodes/{node-id}`
|
||||
下沉子页）；组件/接口/数据设计、REQ→组件追溯 → 节点规格 + 跨 session
|
||||
边契约（`{epic-slug}/shared/{file}`）；「在 plan 中标注」（PRE-19）与
|
||||
迭代计划页标注（POST-15.1）→ 节点 `acceptance_criteria` 或节点工单
|
||||
正文显式标注。standalone 模式（bugfix/refactor/port）以请求本身为规格，
|
||||
上述项标记 `[N/A: standalone 无 legacy 产物]`。
|
||||
|
||||
---
|
||||
|
||||
## 实现前（PRE — Pre-Implementation）
|
||||
|
||||
### 1. 上下文完备性
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ----- | -------------------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-1 | 已读取工作项定义（wiki page `{slug}/04-plan-04-iteration-assignment`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
| PRE-2 | 已读取本迭代验收条件（wiki page `{slug}/04-plan-05-acceptance-criteria`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
| PRE-2.1 | 已从 plan/05 验收条件表提取本工作项每条声明的 test_id（测试用例 ID 列），作为 Phase 3 Red→Green 测试优先顺序的依据；MANUAL/BENCH 类型已识别 | ☐ | ☐ | ☐ | |
|
||||
|
||||
| PRE-3 | 已读取可追溯矩阵中的 REQ→组件映射（wiki page `{slug}/03-design-08-traceability`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
| PRE-4 | 已读取涉及组件的设计文档（wiki page `{slug}/03-design-03-component-design`） | ☐ | ☐ | ☐ | |
|
||||
| PRE-5 | 若涉及 API，已读取接口设计（wiki page `{slug}/03-design-04-interface-design`） | ☐ | ☐ | ☐ | |
|
||||
| PRE-6 | 若涉及数据模型，已读取数据设计（wiki page `{slug}/03-design-05-data-design`） | ☐ | ☐ | ☐ | |
|
||||
| PRE-7 | 若涉及非功能需求，已读取对应设计章节（wiki page `{slug}/03-design-06-non-functional-design`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 2. 代码图调研（Code Graph）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ------------------------------------------------------------------------------------------ | ---- | ------ | --- | ---- |
|
||||
| PRE-CG1 | 会话已确认代码图就绪（`codegraph_status` 非空，否则 `codegraph init -i`） | ☐ | ☐ | ☐ | |
|
||||
| PRE-CG2 | 已用 `codegraph_explore`/`codegraph_search` 定位待改符号的定义与依赖，而非 grep+read 全文拼凑 | ☐ | ☐ | ☐ | |
|
||||
| PRE-CG3 | 已用 `codegraph_callers` 查清待改符号的所有调用方，确认改动不遗漏调用点 | ☐ | ☐ | ☐ | |
|
||||
| PRE-CG4 | 已用 `codegraph_explore`/`codegraph_callers` 评估改动的传递影响范围，回归风险已知 | ☐ | ☐ | ☐ | |
|
||||
| PRE-CG5 | 精读实现时使用 `read(filePath, symbol: ...)` 只取目标符号，未整文件读取大文件 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 3. 工作项边界
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ---------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-8 | 工作项范围清晰，不超过 3 个文件变更（单次 Worker 会话上下文窗口限制） | ☐ | ☐ | ☐ | |
|
||||
| PRE-9 | 所有需要创建/修改的文件在设计文档中有对应组件或接口 | ☐ | ☐ | ☐ | |
|
||||
| PRE-10 | 没有设计文档未提及的新组件、新表或新外部依赖需要引入 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 4. 设计与计划门控（Design & Plan Gate）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | -------------------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-11 | 设计文档（wiki pages `{slug}/03-design-**`）已存在且包含本工作项涉及的全部组件设计 | ☐ | ☐ | ☐ | |
|
||||
| PRE-12 | 迭代计划（plan/）已存在且本工作项有明确的工作项 ID 和验收条件 | ☐ | ☐ | ☐ | |
|
||||
| PRE-13 | 评审门已收敛：DAG 路由下为 review-dag 单门收敛（`octopus review status --stage review-dag` 的 state 为 `success`，与 `pipeline-gate.md` DAG 路由变体一致）；standalone 模式（bugfix/refactor/port）无上游评审门，标记 `[N/A: standalone 无上游评审]`（legacy design-space / iteration-plan 双门已随 [org-internal #3072] phase 3 归档） | ☐ | ☐ | ☐ | |
|
||||
| PRE-14 | 合并前基准刷新：当前分支已 rebase 到目标分支（`git fetch origin && git rebase origin/main`），无合并冲突。若 rebase 引入新变更，重新运行 `bun typecheck && bun run test:parallel` 后再提交 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 5. UI 组件设计完整性（仅前端/UI 工作项）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | -------------------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-15 | 设计文档覆盖了组件的全部四种状态（Loading / Empty / Error / Success），每种状态有明确的渲染内容和触发条件（参见 `.octopus/archive/templates/design.md` §11.1，legacy 设计模板 [org-internal #3072] phase 3） | ☐ | ☐ | ☐ | |
|
||||
| PRE-16 | 设计文档覆盖了组件所需的全部交互行为：列表导航、焦点管理、键盘快捷键、展开/折叠、实时过滤（参见 `.octopus/archive/templates/design.md` §11.2，legacy 设计模板 [org-internal #3072] phase 3） | ☐ | ☐ | ☐ | |
|
||||
| PRE-17 | 设计文档覆盖了组件的全部可访问性要求：ARIA role/label、键盘可达、焦点环、对比度、色彩独立性（参见 `.octopus/archive/templates/design.md` §11.3，legacy 设计模板 [org-internal #3072] phase 3） | ☐ | ☐ | ☐ | |
|
||||
| PRE-18 | 设计文档已逐组件声明测试策略类型（render / source-verification / E2E / manual）。已知测试基础设施限制（Kobalte portal + happydom、路由上下文缺失等）已有对应替代方案标记（参见 `.octopus/archive/templates/design.md` §11.4，legacy 设计模板 [org-internal #3072] phase 3） | ☐ | ☐ | ☐ | |
|
||||
| PRE-19 | 超过 3 个 MANUAL 类型的 AC 已标记为设计风险，并在 plan 中标注更高级测试基础设施依赖 | ☐ | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 实现后（POST — Post-Implementation）
|
||||
|
||||
### 4. 设计一致性
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ------------------------------------------------------ | ---- | ------ | --- | ---- |
|
||||
| POST-1 | 组件接口签名（方法名、参数、返回值）与设计文档一致 | ☐ | ☐ | ☐ | |
|
||||
| POST-2 | 数据模型字段名、类型、约束与数据设计一致 | ☐ | ☐ | ☐ | |
|
||||
| POST-3 | API 端点、方法、请求/响应格式、状态码与接口设计一致 | ☐ | ☐ | ☐ | |
|
||||
| POST-4 | 组件依赖关系与设计的依赖图一致，无反向依赖或新增依赖 | ☐ | ☐ | ☐ | |
|
||||
| POST-5 | 未引入设计文档未提及的新依赖（npm 包、外部服务） | ☐ | ☐ | ☐ | |
|
||||
| POST-6 | 若不得已偏离设计，有明确的注释标注原因和设计修正建议（含 ADR/amend 引用 — 不可仅写"偏离设计"） | ☐ | ☐ | ☐ | |
|
||||
| POST-6.1 | 已用设计文档中的决策树/状态机/真值表，代入至少 2 组具体输入手工 trace 每条分支，确认代码输出与设计预期一致（尤其条件取反、`===` vs `!==`、状态翻转等易错点） | ☐ | ☐ | ☐ | |
|
||||
| POST-6.2 | 因 API 不兼容、上游限制或测试基础设施不足而延迟的项，已在代码中用 `[OPEN: <short-id>]` 标注（含延迟原因、影响范围、建议解决时机）。verify Phase 5.5 会为每个 `[OPEN]` 项在源票 `## TD 登记` 评论登记一行（registry-first，`ticket-lifecycle.md`；排期后才升格独立票）。禁止仅标注 `[OPEN]` 而不登记 | ☐ | ☐ | ☐ | |
|
||||
| POST-6.3 | 邻近配额（[org-internal #3002] G3）：本迭代触碰的区域（包/模块）若在源票 `## TD 登记` 中有适用行，已带走 ≥1 项一并处置（修复或带理由显式再延迟）；无适用行时在报告记录 `0 applicable` | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 5. 代码质量
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------- | ----------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-7 | `bun typecheck` 通过，无类型错误 | ☐ | ☐ | ☐ | |
|
||||
| POST-8 | `bun lint` 通过，无 lint 错误或警告 | ☐ | ☐ | ☐ | |
|
||||
| POST-8.1 | 删除代码后（清理死代码、测试文件、重构移除），重新运行 `bun lint` 并确认无 unused-import / unused-variable 警告（常见遗留：删除测试代码后遗漏的 import） | ☐ | ☐ | ☐ | |
|
||||
| POST-8.2 | 删除 `.ts`/`.tsx` 文件后，验证 `bun typecheck` 无"找不到模块"或孤立类型引用错误 | ☐ | ☐ | ☐ | |
|
||||
| POST-9 | 函数/方法长度合理（≤ 50 行），单一职责 | ☐ | ☐ | ☐ | |
|
||||
| POST-10 | 错误处理路径完备（I/O、网络、解析、数据库操作） | ☐ | ☐ | ☐ | |
|
||||
| POST-10.1 | I/O 操作有超时守卫（如 `Effect.timeout`），避免无限挂起 | ☐ | ☐ | ☐ | |
|
||||
| POST-10.2 | 子进程调用有显式退出码检查（`exitCode !== 0` 显式 fail） | ☐ | ☐ | ☐ | |
|
||||
| POST-10.3 | `Effect.orDie`/`orDieWith` 仅用于 unrecoverable 场景；recoverable 错误用 `catchAll`/`recoverWith` | ☐ | ☐ | ☐ | |
|
||||
| POST-10.4 | 多写操作（INSERT + UPDATE）用 `Database.transaction` 包裹保证原子性 | ☐ | ☐ | ☐ | |
|
||||
| POST-11 | 无硬编码凭据、密钥、内网地址或环境特定值 | ☐ | ☐ | ☐ | |
|
||||
| POST-11.1 | 提交前无法跟踪链接检查（单一事实来源：`code-review.md` SEC 3.7.1——`git diff --cached --diff-filter=T` 为空；判据以该条为准）| ☐ | ☐ | ☐ | |
|
||||
| POST-11.2 | 提交前已确认无进程/流程副产品混入暂存区（如 `.claim` 空文件、claim carrier、临时 pid/日志）——`git status` 逐条核对，`git add -A` 前先看 untracked 清单（[org-internal #3169] 教训：`.claim` 空文件随 iter-0 混入，round-1 九维评审要求 `git rm`） | ☐ | ☐ | ☐ | |
|
||||
| POST-12 | 无注释掉的代码块或 `console.log` 调试语句 | ☐ | ☐ | ☐ | |
|
||||
| POST-13 | 无 `as any` 类型断言绕过类型检查（生产代码必须保有完整类型安全） | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 6. 测试
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------- | ---------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-14 | `bun run test:parallel` 全部通过，无失败用例 | ☐ | ☐ | ☐ | |
|
||||
| POST-15 | 新增代码有测试覆盖，覆盖主要路径和关键分支 | ☐ | ☐ | ☐ | |
|
||||
| POST-15.1 | 测试与实现位于同一迭代；若分拆到下一迭代，必须在迭代计划（wiki page `{slug}/04-plan-04-iteration-assignment`）中显式标注并给出理由。实现提交时不得处于"零测试覆盖"状态 | ☐ | ☐ | ☐ | |
|
||||
| POST-15.2 | 新增组件源文件（`.tsx`/组件 `.ts`）提交时，同一 commit 必须附带至少一个冒烟测试（render 测试，或 Kobalte portal 类组件的源码验证测试——见 AGENTS.md「Testing Kobalte components with happydom」）。禁止整批源文件无任何测试落地、将全部测试统一延后到未来 chunk | ☐ | ☐ | ☐ | |
|
||||
| POST-15.3 | plan/05 中声明的每个 test_id 已落地为真实测试（文件路径::测试名与声明一致） | ☐ | ☐ | ☐ | |
|
||||
| POST-16 | 测试验证了验收条件中的具体行为 | ☐ | ☐ | ☐ | |
|
||||
| POST-17 | 测试覆盖了边界条件（空值、异常输入、权限边界） | ☐ | ☐ | ☐ | |
|
||||
| POST-18 | 测试相互独立，可任意顺序运行 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 7. 文档与日志
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------- | ---------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-19 | 复杂逻辑有简洁解释（若真正非直觉） | ☐ | ☐ | ☐ | |
|
||||
| POST-20 | 对外 API 的错误消息用户可读且可操作 | ☐ | ☐ | ☐ | |
|
||||
| POST-21 | 关键操作有结构化日志（含上下文如 userId、requestId） | ☐ | ☐ | ☐ | |
|
||||
| POST-22 | JSDoc 与实际函数签名一致，参数（含新增参数）已完整文档化 | ☐ | ☐ | ☐ | |
|
||||
| POST-23 | 带副作用的新代码路径（日志、事件发布）已守卫所有控制流（恢复、空值、错误路径），防止幽灵触发 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 8. 过程与规范一致性
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------- | -------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-24 | AI artifact header 使用 `@ai-artifact:` 多行格式（示例见 AGENTS.md）。不得使用其他格式如 `// AI-GENERATED ARTIFACT` | ☐ | ☐ | ☐ | |
|
||||
| POST-25 | 评审修订后，若修改了被测试覆盖的代码，已同步更新对应的测试断言（source-verification 或 render 测试） | ☐ | ☐ | ☐ | |
|
||||
| POST-26 | 测试断言中不得包含 `@opencode-ai` 字符串字面量（namespace gate 扫描字符串字面量，会将其误判为命名空间残留）；安全写法见 `.octopus/rules/testing.md` § "Namespace gate and test assertions" | ☐ | ☐ | ☐ | |
|
||||
| POST-31 | commit 消息使用了正确的 conventional 类型：性能优化用 `perf`（非 `feat`），内部重构用 `refactor`，新功能用 `feat`，bug 修复用 `fix`。类型选择直接影响 auto-changelog 和 release notes 准确性 | ☐ | ☐ | ☐ | |
|
||||
| POST-32 | 若工作项依赖关键 upstream 库（如 `marked`、`effect`、`@kobalte/core`），已在本地运行基础 smoke test 确认 API 签名未变（upstream 可能在 minor 版本变更返回类型或参数） | ☐ | ☐ | ☐ | |
|
||||
@@ -0,0 +1,129 @@
|
||||
> Core 中立版（Increment 6a 改写，原 deferHard verbatim）。编号与条目结构严格不变（C-2 不变量）；实例术语按 `core/adapters/TERMINOLOGY.md` 绑定。
|
||||
# Pipeline Gate Checklist
|
||||
|
||||
跨阶段门控清单。implement、review-code、verify 的 precondition 应引用本清单。
|
||||
每个阶段启动前必须逐项确认。
|
||||
|
||||
## DAG 路由变体（DAG-routed Epic/Feature 及其 Kind/Task 子工单）
|
||||
|
||||
DAG 路由（`dag.route` / `dag.task_route`）**不适用**下方 legacy 的
|
||||
Upstream Artifact Existence 与 Upstream Review Convergence 检查
|
||||
（各 skill 的 DAG 分支——implement §"DAG-mode input path"、review-code
|
||||
§"DAG Task Mode"、verify §"DAG branch"——以下列判据替代）：
|
||||
|
||||
- [ ] 冻结 DAG 副本存在：wiki page `{epic-slug}/dag` 存在且首行为
|
||||
`> DAG 工件状态: frozen`（节点 spec、跨 session 边契约、
|
||||
`size_attrs` 均自该副本解析）
|
||||
- [ ] 单门收敛：`octopus review status --stage review-dag` state 为
|
||||
`success`（替代 design-space + iteration-plan 双门；任务工单
|
||||
不重跑单门，只核对其已收敛）
|
||||
- [ ] （仅任务工单）票 body `## 父级 / Parent` 指向 DAG 父级
|
||||
（`Kind/Epic` 或 `Kind/Feature`，[org-internal #3061] 阶段 2），
|
||||
Step 0 解析到 `dag.task_route`（entry `implement`），不继承
|
||||
`dag.route`
|
||||
- [ ] 跨节点依赖由 DAG 拓扑承担：节点 ready 以其全部跨 session 上游
|
||||
处于终态为准（同 session 边不阻塞）；fan-in ≥ 2 里程碑节点由
|
||||
verify 里程碑承担 DoD，不建工单、不走本清单
|
||||
|
||||
abort 恢复：单门未收敛 → 聚合 agent 重跑 review-artifact skill（target:
|
||||
review-dag）直至收敛；DAG 副本缺失或未冻结 → 回到 `analyze-dag`
|
||||
（分解 → 单门 → 冻结）后再重试。
|
||||
|
||||
## Upstream Artifact Existence（live — standalone modes）
|
||||
|
||||
- [ ] standalone bugfix：repro notes wiki page `{slug}/repro-notes` 存在且含环境快照（via `wiki 读写 API（见 TERMINOLOGY）`）
|
||||
- [ ] 验收条件可解析：来自请求/工单 body 或节点 AC（等价的验收条件文档，via `wiki 读写 API（见 TERMINOLOGY）` / `工单 API（见 TERMINOLOGY）get`）
|
||||
|
||||
> Legacy（[org-internal #3072] phase 3，2026-08-21 归档）：requirements/design/plan baseline
|
||||
> 页（`{slug}/02-requirements-index` / `{slug}/03-design-index` /
|
||||
> `{slug}/04-plan-index` / `{slug}/04-plan-05-acceptance-criteria`）与
|
||||
> design-space / iteration-plan 双门收敛检查随 legacy 管线归档
|
||||
> （`<instance-root>/archive/`）；历史页面仍可读，DAG 路由由上方 DAG 变体接管。
|
||||
|
||||
## Upstream Review Convergence
|
||||
|
||||
- [ ] （代码评审阶段）code review 已收敛 — run `octopus review status --stage code` and verify state is `success`
|
||||
|
||||
## Upstream Dependency Check
|
||||
|
||||
- [ ] 当前节点的所有跨 session 上游依赖节点处于终态（task `done` / milestone `green`，以冻结 DAG 副本 / `## DAG 状态` 表为准）
|
||||
- [ ] 如果有依赖节点未到终态 → abort，列出阻塞的节点
|
||||
|
||||
## Deferred Items Closure
|
||||
|
||||
- [ ] 上一迭代的 Carried Items 全部有明确的 Target Iteration 且已在当前迭代处理或重新延期
|
||||
- [ ] 上一迭代的 Carried Risks 状态已更新（open/closed）
|
||||
- [ ] verify 阶段：所有 UNVERIFIABLE 项有明确的 reactivation plan 或被标记为 accepted tech debt（有记录）
|
||||
|
||||
## Tech Debt Review
|
||||
|
||||
- [ ] tech debt 可经 Gitea issue 查询（`工单 API（见 TERMINOLOGY）list(labels="tech-debt")`，如果项目有任何已完成的 chunk/迭代）
|
||||
- [ ] 回读 open `tech-debt` issues，检查每项的 Reactivation Trigger 是否已满足
|
||||
- [ ] 到期项（trigger 已满足）已纳入当前迭代工作项或显式延期（更新 trigger）
|
||||
- [ ] 如果有到期项未处理 → warn 并列出，建议纳入当前迭代
|
||||
- [ ] 本迭代全部 tech-debt 项均已创建为 `tech-debt` labeled issue；遗漏的项已在 verify 阶段补建或在报告中 flag
|
||||
|
||||
## PR 准入（pr-admission）
|
||||
|
||||
> 纪律：`core/rules/ticket-lifecycle.md` PR 准入节（TD-678 / [org-internal #3881] / [org-internal #4425]）。
|
||||
|
||||
- [ ] PR 标题符合 `[slug][iter-N] type(scope): 描述` 格式
|
||||
- [ ] PR 正文含变更清单 + 自测结果 + 关联合规（关联 issue 引用，如 `Closes #N`；数字后须接 ASCII 标点或行尾——紧跟全角标点会破坏 Gitea 自动关闭，PR [org-internal #3882] 实例）
|
||||
- [ ] 交付推送前本地验证已绿：`<harness-package>` 下 `bun run test:changed` 全绿 + `bun typecheck` 0 error（WIP 备份推送不受此门约束——分支裸推零 CI，交付信号是完成回报而非推送）
|
||||
- [ ] 分支已推送 origin；PR **未**由本会话自行创建（由编排按容量串行开启，一次一张、双绿并入再开下一张）
|
||||
- [ ] 交付报告已发（branch= 分支名 / 改动文件清单 / 自测结果 / verify 与 risk 回执）
|
||||
- [ ] 若编排不可达（fail-open）自开了 PR：PR 正文已标注 `uncoordinated`
|
||||
|
||||
## Issue Checklist Sync
|
||||
|
||||
> 跨阶段门控。source issue 的 checklist 与 `## 当前状态` live-status 表
|
||||
> 必须在每次对外可见的状态跃迁后就地同步（PR 创建 / 评审收敛 / CI
|
||||
> 状态跃迁），不得等到技能退出边界。规则：`core/rules/issue-checklist-sync.md`。
|
||||
|
||||
- [ ] 若存在 source issue：其 checklist 已按同步点表渐进勾选（DAG 冻结、iteration commit、PR 创建、review PASS、CI 跃迁、verify 终扫），无陈旧 `- [ ]` 项
|
||||
- [ ] 若为 incident / standalone-bugfix 流程：issue 含 `## 当前状态` live-status 小节，且 PR / review / CI 行已随跃迁更新（[org-internal #1689]）
|
||||
- [ ] 过程性 AC（如"连续 N 次绿"）的进度注记已更新（带 run 编号）
|
||||
- [ ] 遗留项（未勾选）均有 `(Deferred: ...)` 或 `(Pending: ...)` 注记
|
||||
- [ ] verify PASS 时 `## 当前状态` 小节已折叠进 checklist 注记并移除
|
||||
|
||||
## Bugfix Pipeline Pre-Design Falsification Gate
|
||||
|
||||
> Bugfix 流程特有。必须在进入修复实现前逐项确认。
|
||||
> 单一事实来源：`core/checklists/bugfix.md` §1 REPRO（条目 1.4-1.6）——
|
||||
> 环境快照、复现置信度 ≥3/5、根因假设未被证伪、不满足即 abort 的判据
|
||||
> 以该清单为准，此处不重复列举；逐项核对 bugfix.md §1 后方可进入修复实现。
|
||||
|
||||
## Failure Protocol
|
||||
|
||||
如果任何检查项不满足：
|
||||
1. **abort** 当前阶段，不继续执行
|
||||
2. 列出所有不满足的检查项
|
||||
3. 指出需要完成的上游工作
|
||||
4. 告知用户在 upstream 工作完成前无法继续
|
||||
|
||||
## Recovery Protocol
|
||||
|
||||
abort 后，根据缺失项运行对应的 skill 修复上游工作，然后再重试当前阶段：
|
||||
|
||||
| abort 原因 | 恢复动作（运行的 skill） | 修复后重试 |
|
||||
|-----------|--------------------------|-----------|
|
||||
| 冻结 DAG 副本缺失或未冻结 | `analyze-dag` — 分解 → `review-artifact` (target: review-dag) 单门 → 冻结 | implement / review-code / verify |
|
||||
| review-dag 单门未收敛（`octopus review status --stage review-dag` non-`success`） | `review-artifact` (target: review-dag) — 重新运行单门评审直到收敛（聚合 agent） | implement / review-code / verify |
|
||||
| 上游依赖节点未到终态（task 非 `done` / milestone 非 `green`） | 切换到该依赖节点的工作流，从其当前阶段继续推进，直到其 verify 通过 | implement / verify |
|
||||
| carried items 未闭环（上一迭代 Carried Items 未处理或无延期记录） | 在当前迭代处理该 carried item，或正式延期到下一迭代并更新其 Target Iteration | verify |
|
||||
| 验收条件不可解析（节点 AC 缺失或工单 body 无验收条件） | 在 DAG 副本上补齐节点 AC（修订走 oversize 信号流程），或在工单 body 补验收条件 | verify |
|
||||
| tech debt 到期项未处理（open `tech-debt` issue） | 将到期项纳入当前迭代工作项，或在该 tech-debt issue 中更新 Reactivation Trigger 并说明延期理由 | implement / verify |
|
||||
|
||||
### 恢复流程
|
||||
|
||||
1. abort 时，列出所有不满足的检查项
|
||||
2. 对照上表，确定每个缺失项对应的恢复 skill
|
||||
3. 如果有多个缺失项，按流水线顺序修复（DAG 冻结 → review-dag 单门 → 实现 → code review → verify）
|
||||
4. 每个恢复 skill 完成后，重新检查对应的 precondition
|
||||
5. 所有 precondition 满足后，重试原本 abort 的阶段
|
||||
|
||||
### 注意
|
||||
|
||||
- 恢复上游工作时，不要丢弃已完成的下游工作（如已有代码实现），而是将其作为修复后的验证输入
|
||||
- 如果上游修复导致下游已完成的工件失效，需要重新运行受影响阶段
|
||||
- 上游依赖 chunk 未完成时，优先推进依赖 chunk 而非绕过
|
||||
@@ -0,0 +1,159 @@
|
||||
> Core 中立版（Increment 6a 改写，原 deferHard verbatim）。编号与条目结构严格不变（C-2 不变量）；实例术语按 `core/adapters/TERMINOLOGY.md` 绑定。
|
||||
# Port 检查清单
|
||||
|
||||
> 跨项目端口移植自检。Developer 在 Phase A1.7/A1.8（目标分析+能力边界）、
|
||||
> Phase 5（实现）、Phase 6（测试）、Phase 7（报告）各过一遍。
|
||||
|
||||
> **维度命名空间（dimension namespace）**: 本清单中的维度代码（如 TST/BEH/GATE/REG）是**清单局部（checklist-local）**标识符，仅在本文档内唯一；其他清单可能对相同字母串绑定不同概念（如 code-review.md 的 TST=Test Quality、verification.md 的 TST=Test Suite Completeness、port.md 的 TST=Test Porting）。跨清单引用时必须带清单限定（如 code-review.md TST 5.8），不得使用裸代码。
|
||||
|
||||
---
|
||||
|
||||
## 0. 自检门控（GATE — Self-Check Gate）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ---------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 0.1 | 全部 12 个章节均已逐项检查并标记 ☑ 或 ☐ | ☐ | ☐ | |
|
||||
| 0.2 | 所有 ☐ 项均有修复计划或推迟路径（含 reactivation path） | ☐ | ☐ | |
|
||||
| 0.3 | 已完成清单已输出为 wiki `port-{name}/self-check`（via `wiki 读写 API（见 TERMINOLOGY）`） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 0.5 源分析评审（SRV — Source Analysis Review）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------------------ | ---- | ------ | ---- |
|
||||
| 0.5.1 | 源函数清单与源文件交叉验证：无遗漏函数/符号（**须用自动化符号 diff，非主观判断**） | ☐ | ☐ | |
|
||||
| 0.5.2 | 公共 API 表与源路由/方法定义一致（输入/输出/错误码准确） | ☐ | ☐ | |
|
||||
| 0.5.3 | FID 清单覆盖所有源测试用例，file:line 引用正确 | ☐ | ☐ | |
|
||||
| 0.5.4 | 依赖列表与源项目包管理文件一致 | ☐ | ☐ | |
|
||||
| 0.5.5 | Pipeline 模式：10 维度评审全部收敛（0 BLOCKER, 0 MAJOR） | ☐ | ☐ | |
|
||||
| 0.5.6 | SRC-CMP 符号差集已记录：codegraph/grep 导出源符号集 vs 清单，差集为空或差集项均有 BLOCKER/DEFER 记录 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 0.7 目标接收面分析（TGT — Target Surface Analysis）
|
||||
|
||||
> 在 Phase A2（概念映射）之前完成。回答"目标项目准备好了吗？"。
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ---------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 0.7.1 | 目标项目包结构已映射（每个包的角色已记录） | ☐ | ☐ | |
|
||||
| 0.7.2 | 目标已有能力已识别（与源功能重叠的模块/路由/Provider/Schema） | ☐ | ☐ | |
|
||||
| 0.7.3 | 自动化结构差异已完成（文件/依赖/导出符号/路由/Provider/Schema/CLI/主题/配置/Env/构建） | ☐ | ☐ | |
|
||||
| 0.7.4 | 集成点已识别（每个集成点标注变更类型和受影响的目标文件） | ☐ | ☐ | |
|
||||
| 0.7.5 | 目标就绪评估已完成（是否需要重构/新包/Migration/配置变更，阻塞项已标注） | ☐ | ☐ | |
|
||||
| 0.7.6 | `port-{name}/source-analysis/11-target-surface`（wiki）已输出 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 0.8 能力边界定义（CAP — Capability Boundary）
|
||||
|
||||
> 在 Phase A2（概念映射）之前完成。回答"这个能力的完整边界是什么？"。
|
||||
> **GATE：13 个维度必须全部填写，否则不得进入 Phase A2。**
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ---------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 0.8.1 | 维度 1 — 源代码文件：每个文件已列出（含目标位置和状态） | ☐ | ☐ | |
|
||||
| 0.8.2 | 维度 2 — 类型定义/接口：所有共享类型/品牌类型/Schema 已列出 | ☐ | ☐ | |
|
||||
| 0.8.3 | 维度 3 — 数据库 Schema/Migration：表/列/Migration 已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.4 | 维度 4 — 配置条目：Config Key/Setting/默认值已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.5 | 维度 5 — 环境变量：Env Var/VITE_* 已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.6 | 维度 6 — CLI 标志/命令：CLI 命令/标志/选项已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.7 | 维度 7 — 主题/样式文件：CSS/Theme JSON/Tailwind/Token 已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.8 | 维度 8 — 路由定义：新路由/修改重定向/路由守卫已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.9 | 维度 9 — Provider/Context 层级：新 Provider/插入点/Context Key 已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.10 | 维度 10 — 构建配置变更：vite/tsconfig/webpack/tailwind 已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.11 | 维度 11 — Package.json 依赖：新依赖/版本变更/Workspace 依赖已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.12 | 维度 12 — 测试文件：单元测试/集成测试/测试夹具/测试助手已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.13 | 维度 13 — 共享包变更：SDK/UI/Core 等跨包依赖变更已列出或 N/A | ☐ | ☐ | |
|
||||
| 0.8.14 | 交叉验证：源函数清单中每个函数/符号出现在维度 1 或维度 2 中 | ☐ | ☐ | |
|
||||
| 0.8.15 | 交叉验证：结构差异中每个 Gap 在能力边界中有对应条目 | ☐ | ☐ | |
|
||||
| 0.8.16 | 所有 N/A 维度含一行理由 | ☐ | ☐ | |
|
||||
| 0.8.17 | 所有 ☐ 项含推迟路径和 reactivation trigger | ☐ | ☐ | |
|
||||
| 0.8.18 | `port-{name}/source-analysis/12-capability-boundary`（wiki）已输出 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 1. 源项目理解（SRC — Source Understanding）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------ | ---- | ------ | ---- |
|
||||
| 1.1 | 源功能代码已逐文件阅读 | ☐ | ☐ | |
|
||||
| 1.2 | 源测试已全部阅读（测试是权威行为规范） | ☐ | ☐ | |
|
||||
| 1.3 | 源项目依赖已全部列清（库、服务、基础设施） | ☐ | ☐ | |
|
||||
| 1.4 | 源项目的公共 API 已文档化 | ☐ | ☐ | |
|
||||
| 1.5 | 源函数清单已生成（每个公开/私有函数/符号均有记录，含 Ported? 列） | ☐ | ☐ | |
|
||||
| 1.6 | 源测试用例已全部提取为 FID 清单（`port-{name}/source-analysis/fid-raw`，wiki） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 2. 概念映射（MAP — Concept Mapping）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 2.1 | 每个源概念在目标项目中都有对应（或标记 [GAP]） | ☐ | ☐ | |
|
||||
| 2.2 | 映射优先使用目标项目的现有模式和库（不引入新依赖） | ☐ | ☐ | |
|
||||
| 2.3 | 模式冲突时（如回调 vs async/await）以目标项目模式为准 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 3. 差距分析（GAP — Gap Analysis）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------ | ---- | ------ | ---- |
|
||||
| 3.1 | 所有 [GAP] 都有替代方案和决策记录；推迟项含 reactivation path | ☐ | ☐ | |
|
||||
| 3.2 | 差距不应通过引入新基础设施解决（除非无替代方案） | ☐ | ☐ | |
|
||||
| 3.3 | 导致行为变更的差距标记为 FIDELITY DEVIATION 并已获批准 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 4. 适配设计（ADAPT — Adaptation Design）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------ | ---- | ------ | ---- |
|
||||
| 4.1 | 文件在目标项目中的位置已规划 | ☐ | ☐ | |
|
||||
| 4.2 | 接口适配已记录（命名、类型、错误处理风格） | ☐ | ☐ | |
|
||||
| 4.3 | 依赖替代方案已内联到 Phase 3 的 Gap 决策 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 实现忠实度（FID — Fidelity）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------------- | ---- | ------ | ---- |
|
||||
| 5.1 | 移植代码遵循目标项目约定（命名、模式、风格） | ☐ | ☐ | |
|
||||
| 5.2 | 未"改进"源逻辑（行为一致优先） | ☐ | ☐ | |
|
||||
| 5.3 | 未引入新的第三方依赖 | ☐ | ☐ | |
|
||||
| 5.4 | 源项目注释已同步移植 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 6. 测试移植（TST — Test Porting）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------ | ---- | ------ | ---- |
|
||||
| 6.1 | 源项目的所有测试（含边界/异常/错误路径）均已移植 | ☐ | ☐ | |
|
||||
| 6.2 | 移植的测试全部通过 | ☐ | ☐ | |
|
||||
| 6.3 | 目标项目已有测试无回归 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 7. 行为忠实度验证（BEH — Behavioral Fidelity）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------- | ---- | ------ | ---- |
|
||||
| 7.1 | 源项目的每个公共行为在目标项目中可复现 | ☐ | ☐ | |
|
||||
| 7.2 | 忠实度偏差已有文档记录和批准 | ☐ | ☐ | |
|
||||
| 7.3 | 推迟的功能（不能移植的部分）有后续计划 | ☐ | ☐ | |
|
||||
| 7.4 | 反向覆盖：源函数清单 Ported? 列无残留 ☐（残留项须有 DEFER + reactivation trigger） | ☐ | ☐ | |
|
||||
| 7.5 | 符号级完整性：源/目标导出符号 diff 的 hard gap 均有 DEFER 记录（B5 SRC-CMP） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 8. 最终验证（FINAL — Final Validation）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------ | ---- | ------ | ---- |
|
||||
| 8.1 | `bun run test:parallel` 全部通过（移植测试 + 已有测试） | ☐ | ☐ | |
|
||||
| 8.2 | `bun typecheck` 无错误 | ☐ | ☐ | |
|
||||
| 8.3 | `bun lint` 无错误 | ☐ | ☐ | |
|
||||
@@ -0,0 +1,59 @@
|
||||
> Core 中立版（Increment 6a 改写，原 deferHard verbatim）。编号与条目结构严格不变（C-2 不变量）；实例术语按 `core/adapters/TERMINOLOGY.md` 绑定。
|
||||
# Prototype / Spike 自检清单
|
||||
|
||||
> 开发者在执行 prototype skill 时自检使用。确保 disposition 决策明确、契约完整、
|
||||
> 产出物可审计。分为 THROWAWAY 与 EVOLUTIONARY 两轨。
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **Phase 0** 项在写任何代码前检查；
|
||||
2. **THROWAWAY** 或 **EVOLUTIONARY** 项根据 disposition 选择执行；
|
||||
3. 全部通过后方可声明完成；无法满足的项标记 `[N/A: <原因>]`。
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Disposition 决策（强制）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
|---|--------|------|--------|-----|------|
|
||||
| P0-1 | 已用一句话明确回答"这段代码会被提升为生产代码（EVOLUTIONARY）还是学习后丢弃（THROWAWAY）？" | ☐ | ☐ | ☐ | |
|
||||
| P0-2 | 已从用户原话中引用证据（`@evidence`）支持 disposition 决策 | ☐ | ☐ | ☐ | |
|
||||
| P0-3 | 若用户措辞为条件式（"if it works..."）或模糊，已向用户提问澄清而非猜测 | ☐ | ☐ | ☐ | |
|
||||
| P0-4 | disposition 与 evidence 已记录在产出物头部或对应 artifact 中 | ☐ | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## THROWAWAY 轨（Spike）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
|---|--------|------|--------|-----|------|
|
||||
| T-1 | 已声明 time-box（小时/天），并在到期时停止 | ☐ | ☐ | ☐ | |
|
||||
| T-2 | 产出物包含 spike 代码 + learning report（wiki `{slug}/spike-report`，via `wiki 读写 API（见 TERMINOLOGY）`）；写入模式见 `_shared/gitea-write-patterns.md` | ☐ | ☐ | ☐ | |
|
||||
| T-3 | spike 代码已标记 `@ai-artifact: spike`，且位于 `spike/` 或 scratch worktree | ☐ | ☐ | ☐ | |
|
||||
| T-4 | learning report 包含：验证了什么、什么失败、go/pivot/stop 决策 | ☐ | ☐ | ☐ | |
|
||||
| T-5 | spike 代码不可被生产代码 import；report 接受后已删除或隔离 | ☐ | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## EVOLUTIONARY 轨（高保真原型）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
|---|--------|------|--------|-----|------|
|
||||
| E-1 | 已创建 debt register（wiki `{slug}/prototype-debt`，via `wiki 读写 API（见 TERMINOLOGY）`），每项 shortcut 有 owner + promotion criterion | ☐ | ☐ | ☐ | |
|
||||
| E-2 | 第 1 天质量底线：typecheck 通过、无未授权的 `any`、committed code 无 `console.log` | ☐ | ☐ | ☐ | |
|
||||
| E-3 | 明确延迟的质量项（测试覆盖、错误状态、可观测性、性能预算）已列入 debt register | ☐ | ☐ | ☐ | |
|
||||
| E-4 | promotion 前已通过 `review-code`（`mode: "prototype-promotion"`），debt register 作为必需输入 | ☐ | ☐ | ☐ | |
|
||||
| E-5 | debt register 为空 OR 每项剩余条目有 reviewer 书面 waiver | ☐ | ☐ | ☐ | |
|
||||
| E-6 | waived 条目已由 `verify` Phase 5.5 创建为 `tech-debt` labeled issue（无平行 tracker） | ☐ | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 反模式（不得出现）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
|---|--------|------|--------|-----|------|
|
||||
| A-1 | 未以"prototype 最终总要重写"为由，在 EVOLUTIONARY 场景下 freeze + delete 原型 | ☐ | ☐ | ☐ | |
|
||||
| A-2 | 未以"spike 只是玩玩"为由，跳过 learning report | ☐ | ☐ | ☐ | |
|
||||
| A-3 | 未以"先跑起来再说"为由，让 EVOLUTIONARY 原型在无 debt register 的情况下进入 review | ☐ | ☐ | ☐ | |
|
||||
@@ -0,0 +1,64 @@
|
||||
# Refactor 检查清单
|
||||
|
||||
> 重构自检。Developer 在 Phase 4（每步）和 Phase 5（最终验证）各过一遍。
|
||||
|
||||
> **维度命名空间（dimension namespace）**: 本清单中的维度代码（如 TST/BEH/GATE/REG）是**清单局部（checklist-local）**标识符，仅在本文档内唯一；其他清单可能对相同字母串绑定不同概念（如 code-review.md 的 TST=Test Quality、verification.md 的 TST=Test Suite Completeness、port.md 的 TST=Test Porting）。跨清单引用时必须带清单限定（如 code-review.md TST 5.8），不得使用裸代码。
|
||||
|
||||
---
|
||||
|
||||
## 1. 基线检查（BASE — Baseline）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------- | ---- | ------ | ---- |
|
||||
| 1.1 | 重构范围内的代码有测试覆盖 | ☐ | ☐ | |
|
||||
| 1.2 | 全量测试在重构前全部通过 | ☐ | ☐ | |
|
||||
| 1.3 | 测试覆盖率已捕获（行/分支） | ☐ | ☐ | |
|
||||
| 1.4 | 工作区干净（无未提交变更） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 2. 范围控制（SCOPE — Scope）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 2.1 | 重构目标明确（哪种变换，为什么） | ☐ | ☐ | |
|
||||
| 2.2 | 步骤分解 ≤ 10 步 | ☐ | ☐ | |
|
||||
| 2.3 | 不存在范围蔓延（未在同一重构中混入新功能或 Bug 修复） | ☐ | ☐ | |
|
||||
| 2.4 | 若重构涉及身份/owner token 改名（org、账号、邮箱、域名前缀）：已先产出"不改清单"——OS 账号、个人邮箱、历史记录归属、dummy fixture 等非组织身份引用逐类明确保留，再执行机械替换（[org-internal #3169] 教训：D1 缺此边界 → round-1 15 MAJOR） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 3. 步骤执行（STEP — Per-step Verification）
|
||||
|
||||
> 每一步重构后检查：
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 3.1 | 每步为单一概念变换（非 rename + extract 一步完成） | ☐ | ☐ | |
|
||||
| 3.2 | 每步后 `bun run test:parallel` 全部通过 | ☐ | ☐ | |
|
||||
| 3.3 | 若测试失败，已立即回退而非原地修复 | ☐ | ☐ | |
|
||||
| 3.4 | 每步有独立 commit（便于 revert 或 cherry-pick） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 4. 最终验证（FINAL — Final Validation）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 4.1 | `bun run test:parallel` 全部通过（与重构前相同数量或更多） | ☐ | ☐ | |
|
||||
| 4.2 | `bun typecheck` 无错误 | ☐ | ☐ | |
|
||||
| 4.3 | `bun lint` 无错误 | ☐ | ☐ | |
|
||||
| 4.4 | 测试覆盖率未下降（±1%） | ☐ | ☐ | |
|
||||
| 4.5 | 无新增或修改的测试（重构不应改变测试中的断言逻辑） | ☐ | ☐ | |
|
||||
| 4.6 | 若重构改变了对外可见字符串（stage 名称、tool description、错误消息等），对应的 snapshot 已通过 `bun test --update-snapshots` 更新 | ☐ | ☐ | |
|
||||
| 4.7 | 若重构变更了身份/owner token：残留扫描守卫（如 `script/verify-urls.ts`）已做**语义正反验证**——搜索模式指向**旧** token（旧 owner 前缀的 URL 形态），且已知新 token（新 owner 前缀的 URL 形态）与真实旧残留各跑一次，确认守卫对"合规新 URL"不误报、对"真实残留"不漏报（[org-internal #3169] 教训：D5 模式被翻转 → 守卫对新 URL 误报、对旧残留失明） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 无行为变更（BEH — No Behavior Change）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------------------------- | ---- | ------ | ---- |
|
||||
| 5.1 | 对外接口签名未变化（或已有 @deprecated 说明） | ☐ | ☐ | |
|
||||
| 5.2 | 公共 API 行为一致（相同输入 → 相同输出） | ☐ | ☐ | |
|
||||
| 5.3 | 未引入新的运行时错误/异常路径 | ☐ | ☐ | |
|
||||
@@ -0,0 +1,76 @@
|
||||
# Release 检查清单
|
||||
|
||||
> 发版前自检。Release Manager 在 Phase 1 和 Phase 6 完整过一遍。
|
||||
|
||||
> **维度命名空间（dimension namespace）**: 本清单中的维度代码（如 TST/BEH/GATE/REG）是**清单局部（checklist-local）**标识符，仅在本文档内唯一；其他清单可能对相同字母串绑定不同概念（如 code-review.md 的 TST=Test Quality、verification.md 的 TST=Test Suite Completeness、port.md 的 TST=Test Porting）。跨清单引用时必须带清单限定（如 code-review.md TST 5.8），不得使用裸代码。
|
||||
|
||||
---
|
||||
|
||||
## 1. 前置闸门（GATE — Pre-release Gates）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ---------------------------------------- | ---- | ------ | ---- |
|
||||
| 1.1 | 工作区干净（`git status` 无未提交变更） | ☐ | ☐ | |
|
||||
| 1.2 | 在正确的发布分支上 | ☐ | ☐ | |
|
||||
| 1.3 | 构建通过 | ☐ | ☐ | |
|
||||
| 1.4 | Typecheck + Lint 通过 | ☐ | ☐ | |
|
||||
| 1.5 | 测试全部通过 | ☐ | ☐ | |
|
||||
| 1.6 | 依赖审计已运行，无新增 HIGH/CRITICAL CVE | ☐ | ☐ | |
|
||||
| 1.7 | 无未跟踪的敏感文件（.npmrc 含 token、.env、credentials、私钥等） | ☐ | ☐ | |
|
||||
|
||||
> **注意 1.6**：若使用了无法访问公有 registry 的私有仓库（如自建 Gitea），`bun audit` / `npm audit` 可能报 404。此时无法获取 CVE 数据属于已知盲区，须在 release report 中明确标注「dependency audit: N/A (custom registry)」。
|
||||
|
||||
---
|
||||
|
||||
## 2. 版本号（VER — Version）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------- | ---- | ------ | ---- |
|
||||
| 2.1 | 已找到上一个 tag（或确认这是首个 tag） | ☐ | ☐ | |
|
||||
| 2.2 | 所有 commit 已按类型分类（BREAKING/feat/fix/other） | ☐ | ☐ | |
|
||||
| 2.3 | 版本号遵循 semver（MAJOR.MINOR.PATCH） | ☐ | ☐ | |
|
||||
| 2.4 | 变更类型与 commit 内容一致 | ☐ | ☐ | |
|
||||
| 2.5 | 版本号大于上一个 tag | ☐ | ☐ | |
|
||||
| 2.6 | 版本号已写入所有版本文件 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 3. 变更日志（LOG — Changelog）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------------- | ---- | ------ | ---- |
|
||||
| 3.1 | 自上一个 tag 以来的所有非 chore 提交均已收录 | ☐ | ☐ | |
|
||||
| 3.2 | 条目分组正确（Added/Changed/Fixed/Breaking） | ☐ | ☐ | |
|
||||
| 3.3 | Breaking change 有迁移说明 | ☐ | ☐ | |
|
||||
| 3.4 | 每个条目标注了对应的 commit hash | ☐ | ☐ | |
|
||||
| 3.5 | CHANGELOG.md 已更新（prepend 新版本段） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 4. 标签（TAG — Git Tag）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------------------- | ---- | ------ | ---- |
|
||||
| 4.1 | commit message 含版本号 | ☐ | ☐ | |
|
||||
| 4.2 | tag 已创建且指向正确 commit | ☐ | ☐ | |
|
||||
| 4.3 | tag 命名遵循项目约定（默认 v{version}） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 回滚计划（ROLL — Rollback Plan）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------- | ---- | ------ | ---- |
|
||||
| 5.1 | Git 回退步骤已文档化 | ☐ | ☐ | |
|
||||
| 5.2 | 若有数据库迁移，down migration 存在且已测试 | ☐ | ☐ | |
|
||||
| 5.3 | 回滚触发条件已明确（延迟/错误率/严重 Bug） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 6. 冒烟测试（SMOKE — Post-release Smoke）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------- | ---- | ------ | ---- |
|
||||
| 6.1 | Tagged commit 可构建 | ☐ | ☐ | |
|
||||
| 6.2 | 测试全部通过 | ☐ | ☐ | |
|
||||
| 6.3 | 回到了原始分支 | ☐ | ☐ | |
|
||||
@@ -0,0 +1,64 @@
|
||||
# Retrospective 检查清单
|
||||
|
||||
> 迭代复盘自检。Retrospective Lead 在 Phase 7 报告前检查。
|
||||
|
||||
---
|
||||
|
||||
## 1. 数据收集（DATA — Data Quality）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ---------------------------------------------- | ---- | ------ | ---- |
|
||||
| 1.1 | 分析范围已明确（tag range / time range） | ☐ | ☐ | |
|
||||
| 1.2 | Commit 按类型统计已运行（BREAKING/feat/fix/...） | ☐ | ☐ | |
|
||||
| 1.3 | Revert 数和无前缀 commit 数已统计 | ☐ | ☐ | |
|
||||
| 1.4 | 文件改动 Top 10 已列出（按 +/− 排序） | ☐ | ☐ | |
|
||||
| 1.5 | 测试结果已获取（通过/失败/跳过数） | ☐ | ☐ | |
|
||||
| 1.6 | 测试文件改动情况已检查（无测试改动的源码改动） | ☐ | ☐ | |
|
||||
| 1.7 | Typecheck + Lint 当前状态已检查 | ☐ | ☐ | |
|
||||
| 1.8 | 依赖审计已运行，变更已记录 | ☐ | ☐ | |
|
||||
| 1.9 | 流程基础设施已检查（pre-commit/CI/PR/review/doc/artifact） | ☐ | ☐ | |
|
||||
| 1.10 | 已检查是否存在被删除的未合并 workflow/* 分支（废弃工作/资源浪费） | ☐ | ☐ | |
|
||||
| 1.11 | 已检查 merged workflow/* 分支与关联 worktree 在合并后已清理（本地分支删除 + worktree 移除） | ☐ | ☐ | |
|
||||
| 1.12 | 周期时长和团队规模已记录（压缩周期 = 质量风险，单点故障） | ☐ | ☐ | |
|
||||
| 1.13 | 范围估算验证：triage/scope 声明前已统计各标签下的 issue 数量（如 `Status/Blocked`、`Kind/*`、`Priority/*`），并与之前声明对比，偏差 >20% 标注为估算偏差 | ☐ | ☐ | |
|
||||
| 1.14 | 门缺陷逃逸分析已运行（§2.8 escape-rate 单指标，[org-internal #3061]）：各 gate 的 clean runs / escapes / escape_rate 已统计，UNDER-POWERED（≥0.3）门已标注并回馈 §2.9 pre-flight（gate-trim 元进程已退役，[org-internal #3072] phase 3） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 2. 分析质量（ANAL — Analysis Quality）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 2.1 | "What went wrong" 每一项都有数据证据支撑 | ☐ | ☐ | |
|
||||
| 2.2 | 根因追溯到具体环节（测试缺失/模块过于庞大/提交不规范）| ☐ | ☐ | |
|
||||
| 2.3 | "What went well" 有可复用的模式描述 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 3. 行动项（ACT — Action Items）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 3.1 | 行动项数 ≤ 5 | ☐ | ☐ | |
|
||||
| 3.2 | 每个行动项有具体文件路径（修改哪个 template/checklist/SKILL/config） | ☐ | ☐ | |
|
||||
| 3.3 | 每个行动项有 Owner 角色 | ☐ | ☐ | |
|
||||
| 3.4 | 行动项可度量（如何判断已执行） | ☐ | ☐ | |
|
||||
| 3.5 | 行动项不是"更努力"、"更仔细"等空泛措辞 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 4. 闭环（LOOP — Feedback Loop）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 4.1 | 所有素材文件已更新（行动项中引用的文件） | ☐ | ☐ | |
|
||||
| 4.2 | 更新的素材变更已在 report 中记录 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 无指责原则（SAFE — Blameless）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | -------------------------------------------- | ---- | ------ | ---- |
|
||||
| 5.1 | 报告不含任何个人指责 | ☐ | ☐ | |
|
||||
| 5.2 | 所有问题归因于流程/工具/信息不足，非个人能力 | ☐ | ☐ | |
|
||||
@@ -0,0 +1,146 @@
|
||||
> Core 中立版（Increment 6a 改写，原 deferHard verbatim）。编号与条目结构严格不变（C-2 不变量）；实例术语按 `core/adapters/TERMINOLOGY.md` 绑定。
|
||||
# 迭代验证检查清单
|
||||
|
||||
> 迭代级质量门禁。在所有工作项通过代码评审后执行。
|
||||
> 确保集成正确、非功能达标、无回归。
|
||||
|
||||
> **维度命名空间（dimension namespace）**: 本清单中的维度代码（如 TST/BEH/GATE/REG）是**清单局部（checklist-local）**标识符，仅在本文档内唯一；其他清单可能对相同字母串绑定不同概念（如 code-review.md 的 TST=Test Quality、verification.md 的 TST=Test Suite Completeness、port.md 的 TST=Test Porting）。跨清单引用时必须带清单限定（如 code-review.md TST 5.8），不得使用裸代码。
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. 在当前迭代所有工作项通过代码评审后执行；
|
||||
2. 逐项检查，判定为"通过"或"不通过"；
|
||||
3. "不通过"项注明具体指标和差距；
|
||||
4. 全部通过后迭代正式 Done；
|
||||
5. DoD 行判定词汇 PASS/FAIL/UNVERIFIABLE 为 verify 阶段专用：UNVERIFIABLE＝
|
||||
"无自动化验证手段（缺测试/缺工具/缺基线）"，与评审维度的 verdict 枚举
|
||||
PASS/WARN/FAIL/UNRESOLVED 有意区分（WARN＝评审软通过，UNRESOLVED＝评审员
|
||||
崩溃/超时），勿混用。
|
||||
6. **DAG 路由产物解析**：DAG 运行不存在 legacy `{slug}/04-plan-*` /
|
||||
`{slug}/03-design-*` 页面，条目 1.5 引用的验收条件页
|
||||
`{slug}/04-plan-05-acceptance-criteria` 按 DAG-route read map 解析：
|
||||
→ 节点 `acceptance_criteria`（`{epic-slug}/dag`，含
|
||||
`{epic-slug}/dag-nodes/{node-id}` 下沉子页）或节点工单正文显式标注；
|
||||
standalone 模式以请求本身为规格。
|
||||
|
||||
---
|
||||
|
||||
## 1. DoD 矩阵完整性检查（DOD — Definition of Done Matrix）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ---------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 1.1 | DoD 矩阵中每一条验收条件有明确判定（PASS/FAIL/UNVERIFIABLE） | ☐ | ☐ | |
|
||||
| 1.2 | 每个 PASS 判定有可验证的证据（测试名称、命令输出、测量值） | ☐ | ☐ | |
|
||||
| 1.3 | 每个 FAIL 判定注明了具体差距（期望值 vs 实测值） | ☐ | ☐ | |
|
||||
| 1.4 | UNVERIFIABLE 项标记了原因（缺测试/缺工具/缺基线）并标注了重新激活路径（目标 chunk+iteration）。不可仅标注"未来处理"（wishlist） | ☐ | ☐ | |
|
||||
| 1.5 | DoD 矩阵覆盖本迭代的全部需求（与 wiki page `{slug}/04-plan-05-acceptance-criteria` 对照） | ☐ | ☐ | |
|
||||
| 1.6 | DoD 表中声明的每个测试用例 ID 在代码库中存在、本轮已运行且通过；缺失或未通过项记为 FAIL 并注明差距（期望断言 vs 实际）。`MANUAL`/`BENCH` 条目须附人工记录或基准输出 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 2. 测试完备性检查（TST — Test Suite Completeness）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------- | ---- | ------ | ---- |
|
||||
| 2.1 | `bun run test:parallel` 全部通过（或项目等同命令）。单次执行：同一棵树只跑一次，结果同时用于 DoD 判定与回归分类（5.1），仅当代码在验证中途变更时重跑 | ☐ | ☐ | |
|
||||
| 2.2 | 单元测试 + 集成测试均已运行（若项目有分离命令） | ☐ | ☐ | |
|
||||
| 2.3 | 所有测试输出已捕获，失败用例有详细记录 | ☐ | ☐ | |
|
||||
| 2.4 | 对于使用 `git worktree add/remove` 的模块，`test:parallel` 可能因 git 内部文件锁定而挂起。接受隔离/串行测试结果（`bun test <file> --timeout 120000`）并通过，并注明 TST-GIT-CONTENTION | ☐ | ☐ | |
|
||||
| 2.5 | 已统计本轮 flaky test（间歇性失败/跳过）数量并与基线对比；新增 flaky test 需追溯根因并路由回 Developer；本轮未修复的 flaky test 已在 Phase 5.56 登记为 `flaky-test` labeled issue（FT-NNN） | ☐ | ☐ | |
|
||||
| 2.6 | E2E 浏览器可用性已检查（`npx playwright install --dry-run` 或等效命令）。若浏览器未安装，E2E 相关 DoD 条目预标记为 `⚠️ UNVERIFIABLE — Playwright browsers not installed`，并在 reactivation trigger 中注明安装命令。禁止在无浏览器环境中对 E2E 条目标记 PASS | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 3. 构建与类型检查（BLD — Build & Typecheck）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------- | ---- | ------ | ---- |
|
||||
| 3.1 | `bun typecheck` 无错误（或项目等同命令） | ☐ | ☐ | |
|
||||
| 3.2 | `bun lint` 无错误（警告可记录但非阻断） | ☐ | ☐ | |
|
||||
| 3.3 | 构建产物可正常生成（如项目有 build 步骤） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 4. 非功能需求验证（NFR — Non-Functional Requirements）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ----------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 4.1 | 本迭代覆盖的每个性能指标已测量（P50/P95/P99、吞吐量） | ☐ | ☐ | |
|
||||
| 4.2 | 性能指标与设计阈值和基线（前次迭代）双重对比 | ☐ | ☐ | |
|
||||
| 4.3 | 性能超出阈值的指标有差距分析和 profiling 热点 | ☐ | ☐ | |
|
||||
| 4.4 | 安全扫描已执行，无新高危漏洞引入 | ☐ | ☐ | |
|
||||
| 4.5 | 如无自动性能/安全测试，已标注为 UNVERIFIABLE 并建议具体工具 | ☐ | ☐ | |
|
||||
| 4.6 | 前端：Lighthouse / Core Web Vitals 性能评分未下降（FCP/LCP/TBT/CLS 均在阈值内） | ☐ | ☐ | |
|
||||
| 4.7 | 前端：bundle 体积分析已运行，无预期外增长（新增 chunk > 50KB 需说明理由） | ☐ | ☐ | |
|
||||
| 4.8 | 前端：axe-core / Lighthouse a11y 扫描无新增违规项 | ☐ | ☐ | |
|
||||
| 4.9 | 前端：可访问性（键盘导航、屏幕阅读器、对比度）已验证通过 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 回归检查（REG — Regression）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | ---------------------------------------------- | ---- | ------ | ---- |
|
||||
| 5.1 | 之前迭代通过的测试全部继续通过（零回归）——复用 2.1 同一次全量运行的结果判定，不重复执行 | ☐ | ☐ | |
|
||||
| 5.2 | 任何回归有失败单元测试名和可能原因分析 | ☐ | ☐ | |
|
||||
| 5.3 | 如无之前迭代的测试基线，首次迭代此项标记为 N/A | ☐ | ☐ | |
|
||||
| 5.4 | 用引用缺失/空 `{file:...}` 令牌的可选配置启动 TUI/CLI，确认启动不崩溃。回归测试位于 `<harness-package>/test/config/config-content-substitution.test.ts` | ☐ | ☐ | |
|
||||
| 5.5 | 每个失败用例已在 base 分支/最近绿色 commit 上单独复跑并分类：base 上也失败 → 预先存在（BF，Phase 5.55 登记）；base 通过本分支失败 → 回归（阻塞并路由 Developer）。禁止把预先存在失败当作"别人的问题"丢弃 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 6. 报告完整性检查（RPT — Report Completeness）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 6.1 | 验证报告写入 wiki `{slug}/05-verify-iteration-{N}`（via `wiki 读写 API（见 TERMINOLOGY）`） | ☐ | ☐ | |
|
||||
| 6.2 | 报告包含 DoD 矩阵汇总（PASS/FAIL/UNVERIFIABLE 计数） | ☐ | ☐ | |
|
||||
| 6.3 | 报告包含 NFR 验证结果 | ☐ | ☐ | |
|
||||
| 6.4 | 报告包含回归检查状态 | ☐ | ☐ | |
|
||||
| 6.5 | 报告包含 FAIL 项的处理路径（路由回 Developer 或标记为已知） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 7. 上下文卫生验证（CTX — Context Hygiene）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| ---- | ----------------------------------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 7.1 | 迭代执行中每个 stage 边界执行了压缩，或确认上下文未超限无需压缩 | ☐ | ☐ | |
|
||||
| 7.2 | 每次压缩后重读了 wiki `{slug}/` 页面恢复当前 slug/stage（非仅依赖压缩摘要）；读取模式见 `_shared/gitea-read-patterns.md`（deprecated: `.artifacts/{slug}/`） | ☐ | ☐ | |
|
||||
| 7.3 | 多轮 review 的 round 边界压缩遵循（round ≥ 2 时 compact + 重读 synthesis comment 与 commit status（`octopus review status --stage ...`）） | ☐ | ☐ | |
|
||||
| 7.4 | 未在 stage 中途（tool-call 循环 / sub-agent 派发过程中）执行压缩 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 8. 技术债务登记检查（TD-LOCAL — Tech Debt Local Registration）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 8.1 | 本迭代全部 UNVERIFIABLE / ACCEPTED_RISK / `[OPEN]` 项均已登记为源票 `## TD 登记` 评论中的行（registry-first，`ticket-lifecycle.md`；`filing.sprint-mode: true` 期间禁止升格独立票） | ☐ | ☐ | |
|
||||
| 8.2 | 每行含 `TD-NNN`、type、Severity、origin、一句话摘要与可客观验证的 Reactivation Trigger；TD-NNN 为注册期分配——经 `script/td-alloc.sh` 从号段台账（TD allocation ledger，常设 tracker）取号，任何分配必须先落台账 td-alloc 评论（[org-internal #3322] 互斥） | ☐ | ☐ | |
|
||||
| 8.3 | 两处登记的 `TD-NNN` 标识一致，且每项都有可客观验证的 Reactivation Trigger | ☐ | ☐ | |
|
||||
| 8.4 | 邻近配额复核（[org-internal #3002] G3）：报告含本迭代触碰区域的登记册带走情况（consumed/applicable，或 `0 applicable`）；与本 run 的债务配额记录一致（legacy roadmap 状态追踪表已归档，[org-internal #3072] phase 3） | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 9. 基线失败登记检查（BF-LOCAL — Baseline-Failure Registration）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| --- | --------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 9.1 | 本迭代全部预先存在失败（Phase 2.6 分类为 pre-existing）均已创建为 Gitea issue（label `baseline-failure`，via `工单 API（见 TERMINOLOGY）list(labels="baseline-failure")` 可查） | ☐ | ☐ | |
|
||||
| 9.2 | 每个 baseline-failure issue 含 `BF-NNN`（标题）、Test 标识、Severity（Priority label）、`## Parent` 交叉链接、可在 base commit 复现的 Reproduction 步骤 | ☐ | ☐ | |
|
||||
| 9.3 | 已对存量 `baseline-failure` issue 去重（按 failure signature 匹配——错误/断言形状 + 受影响表面，同一根因家族可跨多个测试，与 verify Phase 5.55 及 `core/rules/ticket-lifecycle.md` BF 家族伞口径一致），未重复登记已知失败；若本迭代修复了既有 BF，已关闭对应 issue 并引用修复 commit（编号/去重规则见 `core/rules/testing.md`） | ☐ | ☐ | |
|
||||
| 9.4 | 验证报告 "Baseline Failures (Pre-existing)" 段落记录了 `BF-NNN → #NNNN` 映射（无则记 "0 baseline failures"）；未登记任何失败时本节为空方为通过 | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 10. Flaky Test 登记检查（FT-LOCAL — Flaky-Test Registration）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | 备注 |
|
||||
| ---- | --------------------------------------------------------------------- | ---- | ------ | ---- |
|
||||
| 10.1 | 本迭代全部未修复 flaky test 均已创建为 Gitea issue（label `flaky-test`，via `工单 API（见 TERMINOLOGY）list(labels="flaky-test")` 可查） | ☐ | ☐ | |
|
||||
| 10.2 | 每个 flaky-test issue 含 `FT-NNN`（标题）、Test 标识、Severity（Priority label）、Failure rate、`## Parent` 交叉链接、复现步骤（多次重跑） | ☐ | ☐ | |
|
||||
| 10.3 | 已对存量 `flaky-test` issue 去重（按 failure signature 匹配——错误/断言形状 + 受影响表面，与 verify Phase 5.56 及 `core/rules/ticket-lifecycle.md` FT 家族伞口径一致）；未重复登记已知 flaky；已稳定的 flaky 已关闭并引用修复 commit（编号/去重规则见 `core/rules/testing.md`） | ☐ | ☐ | |
|
||||
| 10.4 | 验证报告 "Flaky Tests (Intermittent)" 段落记录了 `FT-NNN → #NNNN` 映射（无则记 "0 flaky tests"） | ☐ | ☐ | |
|
||||
Reference in New Issue
Block a user