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 時は不足事項一覧が非空。

各 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"},
  "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

1. context:fork 必須: 生成側 (elicit/doc-fetch/compile) の「網羅できた」自己肯定バイアスを断つ。
2. proposer ≠ approver: 評価者は仕様書を書き換えない (read-only)。修正は elicit/doc-fetch/compile への差し戻し (Goodhart 防止)。
3. 決定論ゲート優先: マトリクス網羅性は validate-coverage-matrix.py の exit code を一次根拠にし、自然言語で PASS 判定しない。
4. 空 findings 禁止: PASS 時も info severity で「確認した観点」を 1 件以上残す。
5. 総合 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 準拠で評価レポートを出力。python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/assign-system-spec-completeness-evaluator/scripts/aggregate-completeness.py" --report <report.json> で形状 + 総合判定整合 (fail-closed 再導出との一致) を検証する。

Gotchas

1. 観点↔評価主体を取り違えない (マトリクス=C07 + C06 ヒアリング品質 sub-input / 設計知識=C05 自前評価・独立 auditor なし / 出典鮮度=C08)。C06 は system-spec/*.md を読まないため設計知識反映へ束縛しない。
2. 決定論ゲート exit0 でも、意味層 (対象外理由の具体性 / 非公式 host / 設計知識反映の形骸化) で FAIL にしうる。
3. high severity が 1 件でもあれば総合 FAIL。
4. INDETERMINATE は fail-closed で FAIL に寄せ、仕様書修正でなく監査再実行/入力補完へ差し戻す。
5. 本 skill は kind=assign のため feedback_contract.criteria は N/A (評価器自身は評価基準を携帯せず、checklist 観点 + evaluator ゲートで担保。frontmatter の skip_reason 参照)。

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