計畫檢查工具（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 在變更目錄下有一個開啟的提案	當指定 --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"
    - "過期 token 應返回 401"
---

規則：

task_id 必須等於任務目錄名稱；路徑應相對於儲存庫根目錄，並使用正斜線。
touch_files 不能指向禁用的前置詞（預設為 tests/acceptance/）。
不要在 01/02/03 檔案中留下佔位符（{{...}}、[TBD]、TODO）。

舊版備用方案

對於不包含 YAML 前置內容的合約，會使用表格作為 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 計畫審查通過：0 個遺漏，0 個幻覺；或
發現清單：任務目錄、受污染的欄位以及違反的 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 中提問

說明文件