ns-sdd-living-spec-consolidator

Living Spec Consolidator

{specs_root}/ を、製品の最新の機能上の正とします。

{specs_root} のデフォルト値は {product_root}/docs/specs/ です。

ハーネスの検出

../ns-harness/references/harness-discovery.md および ../ns-harness/references/artifact-layout.md を参照してください。

モード

モード	使用するタイミング	正とする情報源	コードレビューのゲート
Version（デフォルト）	デリバリー後のバージョン完了時	docs/versions/{version_san}/ の成果物	必須（Approved）
Ad-hoc	ns-code-coder（または人間）が Code Review: Approved 後に実行	{task_description} + 承認済みの git diff	必須（Approved）
Appearance	ns-proto-creator または ns-proto-visual-guide が実行	ガイド／プロトタイプのパス + 簡潔な動作上の差分	なし

呼び出し元がモード appearance を指定した場合（または、ガイド／プロトタイプのパスと動作上の差分があり、レビュー結果がない場合）は、Appearance として検出します。モードが ad-hoc の場合（または、{version_san} がなく、タスクの説明と承認済みの差分がある場合）は、Ad-hoc として検出します。それ以外は Version です。

実行するタイミング

• バージョン完了後（Code Review: Approved の後）— Version
• 既存の {specs_root}/ があり、アドホックなコーディングのレビューが Approved となった後 — Ad-hoc
• プロトタイプの作成／更新後、または動作上の UX を記録する規範的なビジュアルガイドの作成後 — Appearance
• コードレビューで Approved の判定が出る前は、Version／Ad-hoc として実行しないでください

前提条件

Version モード

• {product_root}/docs/versions/{version_san}/requirements.md
• 呼び出し元から Code Review: Approved（スコア ≥ 9）の報告があること — code-review-report.md は不要です
• {product_root}/docs/versions/{version_san}/execution-handoff.md（タスク完了済み）

Ad-hoc モード

• {specs_root}/ がすでに存在すること（アドホックでは、ツリーをゼロから作成しないでください）
• 呼び出し元から Code Review: Approved（スコア ≥ 9）の報告があること
• {task_description} + 承認済みの作業ツリー差分（動作変更）
• 差分が動作に関わらない場合はスキップします（書き込みなし）。対象は、見た目のみの変更、名前変更のみ、API／スキーマ／UX／ドメインの動作を変更しない純粋なリファクタリングです。スキップした旨を報告してください

Appearance モード

• 入力：Appearance ガイドのパス、および／または prototype/ の画面範囲 + 簡潔な動作上の差分（ユーザーが何を実行／確認できるようになったか、または何が記録されたか）
• {specs_root}/ と INDEX.md が存在しない場合は、作成してもかまいません
• SHALL 言語は、製品上でユーザーに見える動作（フロー、フィールド、状態、権限に関する表示）にのみ使用します
• Element | How it should appear テーブルをドメイン仕様に貼り付けてはいけません。代わりにガイドへのリンクを記載してください
• 動作の変更がない装飾上の調整（余白、色の微調整、フォントの変更）はスキップし、その理由を報告してください
• コードレビュー／Approved の要件はありません

ワークフロー

共通の手順 1～4 は、すべてのモードに適用されます。変更履歴のラベルはモードによって異なります。

1. 影響を受けるドメインを特定する

機能を正規のドメインに対応付けます（例）：

機能領域	ドメインファイル
認証、ログイン、RBAC	auth.md
ユーザー、プロフィール	users.md
請求	billing.md
通知	notifications.md
レポート	reports.md
インテグレーション	integrations.md
エージェント／グラフ	agent.md

命名規則：英語、ケバブケース、単数形（user-profile.md）。複数のドメインに関わる機能では、複数の仕様を更新します。

Ad-hoc： {task_description} と差分のみをもとに対応付けます。変更に関係のないドメインを作成しないでください。

Appearance： 動作上の差分とガイド／プロトタイプの範囲のみをもとに対応付けます。必要に応じて、Appearance ドキュメントの Related／参照セクションにドメインへのリンクを追加します。

2. ドメインごと

{specs_root}/{domain}.md が存在しない場合： references/domain-spec.template.md から作成します

存在する場合： 内容をすべて読み、追記または更新します。確認せずに上書きしてはいけません。

該当する機能ごとに：

• ### Requirement: ブロック（SHALL + シナリオ）を追加または更新します
• スキーマ／API が変更された場合は、## Data model と ## Endpoints を更新します（Version／Ad-hoc）
• Appearance：UX／動作に関する要件を優先し、根拠のない API／スキーマを作り出さないでください
• ## Changelog の項目を追記します：
  • Version： **{version_san}** — {ISO date}: {summary}
  • Ad-hoc： **adhoc-YYYY-MM-DD** — {ISO date}: {summary}（タスク + 差分から要約）
  • Appearance： **appearance-YYYY-MM-DD** — {ISO date}: {summary}

3. INDEX.md を更新する

{specs_root}/INDEX.md を作成または更新します：

# Domain specs — {product_name}

| Domain | File                 | Last updated | Versions      |
| ------ | -------------------- | ------------ | ------------- |
| auth   | `docs/specs/auth.md` | {date}       | {version_san or adhoc-YYYY-MM-DD or appearance-YYYY-MM-DD} |

4. 統合レポート

引き継ぎ用の短いレポートを出力します：

## Living specs updated
| Domain | Action | File |
...
Mode: {version|ad-hoc|appearance}
Requirements added: N
Requirements updated: N
New specs: N

スキップした場合（動作に関係しない、磨き込みのみ、または Ad-hoc で {specs_root}/ がない場合）：

## Living specs skipped
Reason: {missing specs_root|non-behavioral diff|chrome polish only}

重要なルール

• 仕様の内容は英語で記述します
• 要件には検証可能な SHALL 形式を使用します
• 既存の仕様は、書き込む前に読みます
• 計画オーケストレーターは、新しいバージョン要件を作成する前に INDEX.md を読みます
• Ad-hoc では docs/versions/ にバージョン成果物を作成してはいけません
• Ad-hoc で {version_san} を作り出してはいけません
• Appearance では、規範的な Element|How テーブルを仕様に貼り付けてはいけません
• Appearance では Code Review Approved を必須にしてはいけません

関連スキル

• ns-sdd-requirements-generator — 計画時に現行仕様を読み込みます
• ns-code-reviewer — Version／Ad-hoc の前提となる承認
• ns-code-coder — Approved 後に Ad-hoc モードを呼び出す場合があります
• ns-proto-creator / ns-proto-visual-guide — Appearance モードを呼び出す場合があります