212 lines
17 KiB
Markdown
212 lines
17 KiB
Markdown
|
> 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 横向可比） | ☐ | ☐ | |
|