assign-system-spec-completeness-evaluator
Runtime root contract
runtime_root_policy: host-skill-path を適用する。- Claude Codeでは
CLAUDE_PLUGIN_ROOT をplugin rootとして使用する。
- Codexではホストが提示したこの
SKILL.md のabsolute pathから、plugin manifestを持つ祖先を上方探索して論理 PLUGIN_ROOT を解決する。
cwd からplugin rootを推測せず、literal placeholderをshellへ渡さない。各shell invocation内で解決済みabsolute pathを PLUGIN_ROOT に設定する。prompts/ 配下はこのowner Skill契約を継承する。
生成された仕様書ドキュメントセットを、上位概念trace / 意思決定根拠 / マトリクス網羅性 / deep knowledge目的適合 / 最新出典 / prompt品質の観点で評価し、観点別スコア + 総合判定 (PASS/FAIL) + 不足事項一覧を返す independent evaluator。context:fork で生成者と評価者を分離する。
Purpose & Output Contract
入力: system-spec/*.md + index (C03 出力) / spec-state.json (C01) / fetched-references.json (C02)
出力: 評価レポート (schemas/completeness-findings.schema.json 準拠) — 観点別スコア + 総合判定 + 不足事項一覧
完了条件: 全観点 verdict 付与 + findings[] (info 以上を最低 1 件) + 総合判定が観点スコアからの fail-closed 再導出値と一致 + 総合 FAIL 時は不足事項一覧が非空 + aggregate-completeness.py --report <output> --spec-dir <spec_dir> が exit 0 (Step 4)。
各 skill 単独では見えない全体網羅性の欠落を、生成物から独立した context で評価し客観的合否を返す。
監査 sub-agent 対応 (全 6 観点中、評価主体の割当に注意が要る 3 観点)
本 skill は全 6 観点 (上位概念trace / 意思決定 / マトリクス網羅性 / 設計知識反映 / 最新ドキュメント出典 / prompt品質) を採点する (schema/rubric/aggregate-completeness の正本)。うち foundation_trace / decision_guidance / prompt_quality は C05 R1-score の自前評価。以下は評価主体の割当に注意が要る 3 観点 (監査 sub-agent が担う 2 観点と、独立 auditor を立てない設計知識反映) の対応表。
| 観点 (aspect id) | ラベル | 評価主体 (component) | 一次根拠 |
|---|
matrix_coverage | マトリクス網羅性 | system-spec-matrix-auditor (C07) + sub-input system-spec-hearing-auditor (C06) | validate-coverage-matrix.py --require-complete の exit0 + 意味層。C06 のヒアリング監査 (run-system-spec-elicit の R6-audit-hearing の監査 5 軸) を網羅性・トレースの補助根拠に併せる。判定への対応は references/aspect-criteria.md 1a (決定論実装 aggregate-completeness.py --hearing ... --state ...) |
design_knowledge_reflection | 設計知識反映 | C05 R1-score が自前評価 (独立 auditor なし) | 機械層=各章の設計知識ポインタ存在 (compile 注入) + 意味層=そのポインタ原則の確定セルへの具体適用 (存在確認だけで PASS にしない = Goodhart 防止) |
doc_freshness | 最新ドキュメント出典 | system-spec-doc-freshness-auditor (C08) | 二層監査 (形式=validate-source-citation.py / 内容鮮度=公式再照合) |
system-spec/*.md を読まない C06 (hearing-auditor) を設計知識反映へ束縛するのは虚偽対応のため撤去した。C06 はヒアリング品質を担い matrix_coverage の sub-input へ再配置し、設計知識反映は C05 が system-spec/*.md と resource-map から自前評価する。監査 sub-agent (C07/C08 と matrix sub-input の C06) は Task tool でそれぞれ独立 context (fork) に起動する (R2-delegate)。監査ロジックは各 agent の SSOT prompt に委ね、本 skill は結果を集約するだけで書き換えない。
知識グラフ / doctrine の追加評価次元 (C13-C16)
上位 6 観点の top-level 構造 (aggregate-completeness.py の 6 aspect fail-closed 集約) は不変。C13-C16 の知識グラフ / doctrine 要件は新 aspect を増やさず、既存 aspect の追加評価次元として折り込む (各 validate-knowledge-graph.py --profile ... の exit0 を機械層、生成物への反映を意味層で採点)。
| 追加次元 | 折込先 aspect | 機械層ゲート | 意味層で拾う失敗 |
|---|
| C13 知識カタログが typed 辺グラフ | design_knowledge_reflection | validate-knowledge-graph.py --profile knowledge exit0 (循環/dangling/孤立/root到達不能 0) | knowledge-catalog の depends_on/refines/conflicts_with 型則違反・孤立 node の設計知識への未接地 |
| C14 elicit/compile が同一 topo_order で知識消費 | design_knowledge_reflection | 上記 --profile knowledge --order の topo_order を C01 R5 / C03 R2 が同一順で消費 | 上位概念→下位概念の位相順を破って下位技術を先に確定した章 |
| C15 doctrine anchor 1正本 + 全 category 写像全射 | design_knowledge_reflection | validate-knowledge-graph.py --profile doctrine exit0 (7 concern の concern_id 一意 + 各 authority 非空・全 category→concern 写像全射。authority は 4 種で concern 間共有可・authority 一意性は非検査) | 生成章に concern authority (Apple HIG/Clean Arch/OWASP/SRE) の上流指針が具体反映されず汎用ポインタ止まり |
| C16 必須情報カタログの被覆 + block ゲート | matrix_coverage | validate-knowledge-graph.py --profile required-info exit0 (全 in-scope domain 被覆・item 最低形状・収集順序・coverage certificate) | missing_effect=block の item 未回答のまま confirmed に進んだ確定セル (C01 R5 収集ゲート素通り。機械層ゲート validate-knowledge-graph.py (component C14) は blocking_items 列挙のみで runtime 施行せず・決定論 writer 施行は follow-up) |
C15 の意味層は「存在確認だけで PASS にしない」= design_knowledge_reflection の Goodhart 防止と同一原則で、doctrine anchor が確定セル要件へ具体適用されているかを照合する。C16 は matrix_coverage の網羅性判定に「必須情報が block ゲートを通って確定に接地しているか」を加える。
評価レポート形状 (schema)
{
"evaluator": {"name": "assign-system-spec-completeness-evaluator", "version": "0.1.0", "context": "fork"},
"spec_dir": "<引数 spec_dir の値そのまま>",
"verdict": "PASS" | "FAIL",
"aspects": {
"foundation_trace": {"verdict": "...", "auditor": "assign-system-spec-completeness-evaluator", "component": "C05", "summary": "...", ...},
"decision_guidance": {"verdict": "...", "auditor": "assign-system-spec-completeness-evaluator", "component": "C05", "summary": "...", ...},
"matrix_coverage": {"verdict": "PASS|FAIL|INDETERMINATE", "auditor": "system-spec-matrix-auditor", "component": "C07", "summary": "...", "evidence": [...]},
"design_knowledge_reflection": {"verdict": "...", "auditor": "assign-system-spec-completeness-evaluator", "component": "C05", "summary": "...", ...},
"doc_freshness": {"verdict": "...", "auditor": "system-spec-doc-freshness-auditor", "component": "C08", "summary": "...", ...},
"prompt_quality": {"verdict": "...", "auditor": "assign-system-spec-completeness-evaluator", "component": "C05", "summary": "...", ...}
},
"gate_results": [ {"id": "G-matrix", "name": "validate-coverage-matrix", "exit_code": 0, ...} ],
"findings": [ {"severity": "high|medium|low|info", "bucket": "...", "observation": "...", "suggested_fix": "..."} ],
"gaps": [ "不足事項1", ... ]
}
総合判定 (fail-closed 集約)
- 全観点PASS かつ high severity finding 0 件のときだけ総合 PASS。
- 1 観点でも FAIL/INDETERMINATE、または high finding が 1 件でもあれば総合 FAIL。
- 全観点を過不足なく評価していなければ総合 FAIL (監査観点の取りこぼしを PASS にしない)。
- 総合判定は
scripts/aggregate-completeness.py の aggregate_verdict で再導出でき、レポートの verdict と一致すること (総合判定が観点スコアに接地しているかの整合検査 = Goodhart 防止)。
Key Rules
- context:fork 必須: 生成側 (elicit/doc-fetch/compile) の「網羅できた」自己肯定バイアスを断つ。
- proposer ≠ approver: 評価者は仕様書を書き換えない (read-only)。修正は elicit/doc-fetch/compile への差し戻し (Goodhart 防止)。
- 決定論ゲート優先: マトリクス網羅性は
validate-coverage-matrix.py の exit code を一次根拠にし、自然言語で PASS 判定しない。
- 空 findings 禁止: PASS 時も info severity で「確認した観点」を 1 件以上残す。
- 総合 FAIL は差し戻し材料付き: gaps (不足事項一覧) を非空にし、どの skill (elicit/doc-fetch/compile) または監査再実行へ戻すかを記す。
Steps
正本責務は prompts/R1-score.md (スコアリング) と prompts/R2-delegate.md (監査 fork 集約)。要約:
Step 1: 観点別監査を独立 context で集約 (R2-delegate)
Task tool で監査 sub-agent (system-spec-matrix-auditor (C07) / system-spec-hearing-auditor (C06) / system-spec-doc-freshness-auditor (C08)) をそれぞれ fork する。C07 は matrix_coverage、C08 は doc_freshness の一次根拠。C06 はヒアリング品質を監査し matrix_coverage の sub-input として併せる。C06 の verdict はそのまま使わず、python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/assign-system-spec-completeness-evaluator/scripts/aggregate-completeness.py" --hearing <C06 出力> --state <spec-state.json> で sub-input の判定を導く (注記と閉じた検出は findings に残し gaps に入れない)。design_knowledge_reflection は独立 auditor を立てず Step 3 で C05 自身が評価する。
Step 2: マトリクス網羅性の決定論ゲート
python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/validate-coverage-matrix.py" --matrix <spec-state.json> --require-complete
exit0 をマトリクス網羅性観点の一次根拠にする (python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/assign-system-spec-completeness-evaluator/scripts/aggregate-completeness.py" --matrix <spec-state.json> --require-complete でも回収可)。
続けて C13-C16 の機械層ゲートを python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/assign-system-spec-completeness-evaluator/scripts/aggregate-completeness.py" --knowledge-graph (出荷 3 カタログを validate-knowledge-graph.py の knowledge/doctrine/required-info/cross 4 profile で独立再実行) の全 exit0 で確認する。C13/C14/C15 は design_knowledge_reflection (Step 3)、C16 は matrix_coverage の追加評価次元として意味層採点に併せる。
Step 3: 設計知識反映の自前評価 (独立 auditor なし)
C05 R1-score が system-spec/*.md 各章を直接読み、ref-system-design-knowledge/references/resource-map.yaml 由来の設計知識ポインタの (1) 存在 (機械層) と (2) その原則が確定セル要件へ具体適用されているか (意味層) を評価する。存在確認だけで PASS にしない (compile が機械注入するポインタを自己循環で肯定しない = Goodhart 防止)。汎用ポインタ (resource-map 索引) のみで具体適用が無い章は medium 以上で拾う。C06 のヒアリング品質監査は本観点でなく matrix_coverage の sub-input として使う。
Step 4: レポート出力と整合検査
schemas/completeness-findings.schema.json 準拠で評価レポートを出力する。
- 相対の
spec_dir と output は、この skill を起動した cwd から解決する。評価の入力の読み込み、レポートの書き出し、下の --report <output> --spec-dir <spec_dir> の検証は、どれも同じ cwd を基準にする。repo 相対の値を渡す呼び出し側 (dev-graph の C19 など) は、起動の前に cwd が repo root と同じことを確かめる。
spec_dir には引数 spec_dir の値をそのまま書く (相対パスなら相対のまま)。説明や注記を足さない。- レポートは引数
output のパスに書く。そのパスは system-spec/ の外に置き、書き出しのコマンドの中に文字列のリテラルで書く (変数・sys.argv・$ を使わない。書き方は prompts/R1-score.md の 4.3)。guard-confirmed-chapter-overwrite.py は、書き先を判定できて保護領域の外ならば、本文に system-spec が出てきても通す。
python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/assign-system-spec-completeness-evaluator/scripts/aggregate-completeness.py" --report <output> --spec-dir <spec_dir> で、形状 + 総合判定整合 (fail-closed 再導出との一致) と、spec_dir が引数と同じ dir に解決することを検証する。spec_dir_mismatch の report は、呼び出し側 (dev-graph の C02 など) が確定の取込を拒む。
Gotchas
- 観点↔評価主体を取り違えない (マトリクス=C07 + C06 ヒアリング品質 sub-input / 設計知識=C05 自前評価・独立 auditor なし / 出典鮮度=C08)。C06 は system-spec/*.md を読まないため設計知識反映へ束縛しない。
- 決定論ゲート exit0 でも、意味層 (対象外理由の具体性 / 非公式 host / 設計知識反映の形骸化) で FAIL にしうる。
- high severity が 1 件でもあれば総合 FAIL。
- INDETERMINATE は fail-closed で FAIL に寄せ、仕様書修正でなく監査再実行/入力補完へ差し戻す。
- 本 skill は kind=assign のため feedback_contract.criteria は N/A (評価器自身は評価基準を携帯せず、checklist 観点 + evaluator ゲートで担保。frontmatter の skip_reason 参照)。
spec_dir に説明や注記 ((read-only で評価) など) を混ぜない。書き出しが guard に止められても、spec_dir の値を変えて回避しない。guard が止めるのは書き先を判定できないときなので、保存先を system-spec/ の外の文字列のリテラルにして書き直す (Step 4)。
Additional Resources
references/scoring-rubric.json — 全 6 観点機械判定ルールと fail-closed 集約ポリシーreferences/aspect-criteria.md — 観点別意味判定の詳細基準 + 観点↔監査 agent 対応schemas/completeness-findings.schema.json — 評価レポート出力スキーマscripts/aggregate-completeness.py — レポート形状検証 + 総合 fail-closed 集約 (決定論)prompts/R1-score.md / prompts/R2-delegate.md — R1 (スコアリング) / R2 (監査 fork 集約) 責務正本- fork 先 agent:
../../agents/system-spec-{matrix,hearing,doc-freshness}-auditor.md