计划检查器（Gate 1 规划验证器）

该技能拥有单一且严格限定的职责：在开发开始前，对 tasks/ 下的预定任务合约和任务包执行 Gate 1 确定性静态验证。

Gate 1：此技能中的确定性脚本：快速、离线、仅依赖标准库。
Gate 2：仅提示的语义审查（review 技能，以 references/gate-2-review.md 作为备选）。
非目标：计划检查器不执行代码、不构建或运行 CI 流水线、不执行 AST/代码复杂度分析，也不审计测试或 03-qa-verification.md 中记录的 QA 复杂度/变异证据（仅执行占位符扫描和存在性检查）。所有 CI 流水线和验证关卡由 quality-engineering 负责；本地测试由 qa 负责。

Gate 1：确定性检查

检查项	默认	可覆盖
01-contract.md 存在且包含有效元数据	必需	否
task_id 等于目录名	必需	否
task_id 在整个任务包中唯一	必需	否
touch_files 数量	1..3	max_touch_files
estimated_lines	50..250	min_diff_lines, max_diff_lines
origin_spec_anchor 匹配 #sec-[a-z0-9-]+	必需	require_anchor
adherence_adrs 至少列出一个 ADR	必需	require_adrs
dod.type_check, dod.lint, dod.test_file	必需	否
dod.edge_cases 数量	至少 2	min_edge_cases
02-dev-workspace.md, 03-qa-verification.md, 04-process.md 存在	必需	require_docs
禁止的 touch 前缀	tests/acceptance/	forbidden_touch_prefixes
01/02/03 中未解决的占位符	阻止	scan_placeholders
03-qa-verification.md 内容级别的 QA 证据	不审计（Gate 3）	否
逆向拓扑：修改路径存在，创建路径不存在	警告	check_topology, strict_topology, --repo-root
size_class micro：存在 change_id，1 个 touch 文件，更小的预算	当为 micro 时必需	micro_min_diff_lines, micro_max_touch_files
change_id 在 change 目录下存在开放的提案	当给定 --changes-dir 时必需	--changes-dir
规范锚点覆盖率矩阵（未覆盖的章节）	报告；若使用 --require-full-coverage 则报错	--spec, --coverage-out
合约锚点在规范中不存在	警告；若使用 --strict-anchor 则报错	--spec
依赖图	无环、无缺失任务	否

所有检查项均被执行；输出中顺序稳定。

快速开始

# 标准报告或机器可读 JSON
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --json

# 自定义配置或旧版格式
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --config plan-linter.json
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --legacy

# Gate 2 启发式检查及 CI 阻断模式
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks \
  --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes --json
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks \
  --spec .specs/02-tech-spec.md --strict-topology --strict-anchor --require-full-coverage

该脚本是可选的。如果 Python 不可用，请使用 references/gate-2-review.md 作为手动检查清单，并手动审查相同字段。

Gate 2 是单独的 review 技能。 在 Gate 1 退出码为 0 后，若安装了 review 技能，则使用它（计划审查模式）执行独立的语义审计。此技能保留了 references/gate-2-review.md 作为自包含的备选方案，以防 review 技能未安装；它从不替代 Gate 1。

退出码

退出码	含义
0	所有任务包的 Gate 1 均通过
1	发现违规（或合约前置元数据无法解析）
2	使用或配置错误
3	意外的内部错误

合约格式

01-contract.md 的 YAML 前置元数据具有权威性。其下的表格仅为可读性辅助。

---
task_id: task-001-auth
title: "用户认证"
module: auth
dependencies: [task-000-bootstrap]
estimated_lines: 120
touch_files:
  - action: create
    path: src/auth/service.py
  - action: modify
    path: src/auth/routes.py
origin_spec_anchor: "#sec-auth"
adherence_adrs: [ADR-001]
dod:
  type_check: "npm run type-check"
  lint: "npm run lint"
  test_file: "tests/acceptance/test_auth.ts"
  edge_cases:
    - "空凭据返回 400"
    - "过期令牌返回 401"
---

规则：

task_id 必须等于任务目录名；路径相对于仓库并使用正斜杠。
touch_files 不能指向禁止的前缀（默认为 tests/acceptance/）。
不要在 01/02/03 中留下占位符（{{...}}、[TBD]、TODO）。

旧版备选格式

没有 YAML 前置元数据的合约使用针对 pre-v2 布局的表格备选方案，并打印 LEGACY_FORMAT 警告。添加 --legacy 以强制使用备选方案。

配置

{
  "max_touch_files": 3,
  "min_diff_lines": 50,
  "max_diff_lines": 250,
  "require_anchor": true,
  "require_adrs": true,
  "min_edge_cases": 2,
  "require_docs": ["02-dev-workspace.md", "03-qa-verification.md", "04-process.md"],
  "forbidden_touch_prefixes": ["tests/acceptance/"],
  "scan_placeholders": true,
  "micro_min_diff_lines": 10,
  "micro_max_touch_files": 1,
  "check_topology": true,
  "strict_topology": false,
  "ignore_task_dirs": ["archive"]
}

阈值是仓库约定，并非通用法则。可针对项目进行覆盖；未知键会产生警告，类型错误的值会导致退出码 2。

JSON 输出

{
  "gate": "1",
  "passed": true,
  "tasks_scanned": 3,
  "errors": [],
  "warnings": [],
  "coverage": {
    "spec": ".specs/02-tech-spec.md",
    "spec_anchors": 3,
    "covered": ["#sec-alpha", "#sec-beta"],
    "uncovered": ["#sec-gamma"],
    "contract_anchors_missing_from_spec": [],
    "coverage_ratio": 0.6667
  }
}

仅当传递了 --spec 时，coverage 才会出现；--coverage-out 会将其写入文件。

每个错误对象包含键 task、code、message、file 和 line。错误代码是稳定的英文标识符（例如 MISSING_DOC、TASK_ID_MISMATCH、DAG_CYCLE、PLACEHOLDER、TOUCH_FILE_MISSING、FORBIDDEN_TOUCH_FILE、BDD_MISSING_PRECONDITION、BDD_MISSING_ACTION、BDD_MISSING_OUTCOME、BDD_INVALID_SCENARIO、SPEC_SECTION_UNCOVERED）。归档的提案会产生 CHANGE_ALREADY_ARCHIVED 而非错误，并且 ignore_task_dirs（tasks/archive）永远不会作为待处理任务包被扫描。完整错误参考：references/gate-2-review.md。

Gate 2：语义审查（仅提示）

Gate 1 通过后，以独立审查者的身份遵循 references/gate-2-review.md。总结为以下任一种格式：

Gate 2 Plan Review Passed: 0 omissions, 0 hallucinations；或
查找列表：任务目录、受污染的字段以及违反的 ADR ID。

Gate 2 是手动的：脚本无法判断语义真实性。未经审查不要通过。

可移植性、边界和非目标

该脚本仅依赖标准库，相对于自身目录解析路径，且从不写入文件。

严格边界和非目标：

不执行代码：绝不运行 DoD 命令、应用程序代码或测试套件。
不编排 CI：不构建、管理或运行 CI 流水线（由 quality-engineering 负责）。
不进行 AST 或复杂度分析：不计算圈复杂度 $V(G)$（由 quality-engineering 负责）。
不审计测试或验证：不审计 03 QA 证据。仅四个文档的存在性检查和未解决占位符扫描会触及 03-qa-verification.md；复杂度、基础路径覆盖率和变异 MSI 由 Gate 3（quality-engineering/verification_linter.py）审计。
不进行语义判断：不判断语义真实性（Gate 2 为提示审查）。
不执行 RBAC：不替代基于 git 的 RBAC 审计。

formal-you/agent-skills-suite

agent-skills-suite 是什么？

在你喜欢的 AI 中提问

文档