ns-living-spec

Living Spec Consolidator

docs/specs/ を製品の最新の機能仕様として維持します。

セッションの開始

../../ns-harness/references/session-boot.md と ../../ns-harness/references/artifact-layout.md を参照してください。

モード

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

呼び出し元がモード appearance（または同等のもの：ガイド／プロトタイプのパス + 動作上の差分、レビュー判定なし）を渡した場合は Appearance です。モードが ad-hoc（または同等のもの：{version_san} なし、タスクの説明 + 承認済みの差分）の場合は Ad-hoc です。それ以外は Version です。

書き込み先

モードとは独立しています（モードは 何を 文書化するか、および適用するゲートを決定します）。どこに 書き込むかを決めてください。

書き込み先	使用するタイミング	書き込み内容
Direct	統合ブランチ、ブランチの役割が不明、または（レガシーリポジトリで）docs/specs/_pending/ がない場合	Workflow に従って docs/specs/{domain}.md + INDEX.md に書き込みます。_pending/ に断片がある場合は、先に Consolidate を実行します
Fragment	機能ブランチ（../../ns-harness/references/artifact-layout.md → Branch role）で、docs/specs/_pending/ がある場合	ドメインごとに新しいファイルを1つだけ作成します。references/pending-fragment.template.md から docs/specs/_pending/{label}-{slug}.md を作成してください。docs/specs/ 配下のほかの場所には何も書き込みません
Consolidate	統合ブランチで明示的に依頼された場合、または Direct に書き込む前	すべての断片を適用してから削除します（Consolidate を参照）

理由：同じドメインファイルを並行するMRで編集すると競合しますが、個別の新しいファイルであれば競合しません。配置については、../../ns-harness/references/artifact-layout.md → Living spec fragments を参照してください。

Fragment では、現在のモードのすべてのゲート、スキップ規則、ドメイン対応付けの手順を維持します。変更するのはステップ2のみです（ドメインファイルを編集せず、差分を断片に書き込みます）。ステップ3はスキップします（INDEX.md に触れるのは統合時のみです）。{slug} はタスクまたは課題の短いケバブケース表記です。{label} はモードの変更履歴ラベルです。Living specs staged を使って、ドメインと断片のパスを報告してください。

Consolidate

各断片の作成時にゲートはすでに適用されています。レビュー判定を再度求めないでください。

1. docs/specs/_pending/*.md を一覧表示し、ファイル名順（決定的な順序）に処理します。
2. 断片ごとに、対象の {domain}.md 全体を読み、要件／データモデル／エンドポイントの差分を適用し、断片の変更履歴エントリーをその label とともに追加します。ドメインファイルがない場合は、references/domain-spec.template.md から作成します。
3. 最後に一度だけ INDEX.md を更新します（更新日 + 変更対象の各ドメインのバージョン）。
4. 各断片は、正常に適用できた場合にのみ削除します。
5. 競合（断片が更新または削除しようとする要件が、すでに存在しない、または先行する断片によって名称変更されている場合）：推測で対応しないでください。その断片は残し、理由とともに報告に記載します。
6. ## Living specs consolidated として報告します。処理した断片、残した断片（理由を含む）、更新したドメインを記載してください。

統合ブランチ（または役割が不明な場合）でのみ実行してください。機能ブランチでは実行しないでください。

呼び出し時

• バージョン完了後、Code Review: Approved かつ Delivery Review: Approved の場合 — Version
• アドホックなコーディングで、両方のレビューが Approved になっており、docs/specs/ がある場合 — Ad-hoc
• プロトタイプの作成／改良、または動作を伴うUXを文書化する規範的なビジュアルガイドの場合 — Appearance
• 両方が Approved になる前は、Version／Ad-hoc を実行しないでください

前提条件

バージョンモード

• 解決済みの requirements.md — まず sdd/ を確認し、なければレガシーのバージョンルートを使用（artifact-layout.md Legacy path resolution）
• 呼び出し元が Code Review: Approved と Delivery Review: Approved を報告 — code-review-report.md は不要
• 解決済みの execution-handoff.md — まず sdd/ を確認し、なければレガシーのバージョンルートを使用（タスク完了）

アドホックモード

• docs/specs/ がすでに存在する（ツリーを新規作成しない）
• 呼び出し元が Code Review: Approved と Delivery Review: Approved を報告
• {task_description} ＋承認済みの作業ツリー差分（動作の変更）
• 差分が動作に影響しない場合はスキップ（書き込みなし）：見た目のみの変更、名前変更のみ、API／スキーマ／UX／ドメインの動作を変更しない純粋なリファクタリング — スキップしたことを報告

外観モード

• 入力：外観ガイドのパス、および／または prototype/ の画面と、簡潔な動作上の差分（ユーザーができること／変更または記録された表示内容）
• docs/specs/ ＋ INDEX.md が存在しない場合は作成してもよい
• プロダクト上でユーザーに見える動作に限る（フロー、フィールド、状態、権限を示す手がかり）
• ドメイン仕様に Element | How it should appear の表を貼り付けない — 代わりにガイドへのリンクを記載する
• 見た目のみの調整（間隔、色の変更、フォントの差し替えなどで動作に変更がないもの）はスキップ — 理由を報告する
• Code Review / Approved の要件なし

ワークフロー

全モードで共通するステップ 1〜4。変更履歴のラベルはモードによって異なります。

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

機能を標準ドメインに対応付けます（例）：

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

docs/specs/agent-architecture.md は継続的に更新する ADR（ns-agent-architecture）です。ドメイン仕様ではありません。{domain}.md として扱わないでください。

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

アドホック： {task_description} と差分のみをもとに対応付けます — 無関係なドメインを追加しないでください。

外観： 動作上の差分とガイド／プロトタイプの範囲のみをもとに対応付けます。必要に応じて、「関連／参照」の下に外観ドキュメントへのドメインリンクを追加します。

2. ドメインごとの処理

docs/specs/{domain}.md が存在しない場合：references/domain-spec.template.md をもとに作成します

存在する場合：全体を読み、追記または更新します — 内容を確認せずに上書きしないでください

関連する機能ごとに：

• ### Requirement: ブロック（SHALL ＋シナリオ）を追加または更新します
• スキーマ／API が変更された場合は ## Data model ＋ ## Endpoints を更新します（バージョン／アドホック）
• 外観：UX／動作の要件を優先します。根拠のない API／スキーマを作成しないでください
• ## Changelog エントリーを追記します：
  • バージョン： **{version_san}** — {ISO date}: {summary}
  • アドホック： **adhoc-YYYY-MM-DD** — {ISO date}: {summary}（要約はタスクと差分をもとに作成）
  • 外観： **appearance-YYYY-MM-DD** — {ISO date}: {summary}

3. INDEX.md を更新する

docs/specs/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

フラグメントの対象：見出しを ## Living specs staged に置き換え、ドメインファイルの代わりに docs/specs/_pending/ のパスを列挙します。

スキップした場合（動作の変更なし、見た目のみの調整、またはアドホックモードで docs/specs/ が存在しない場合）：

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

重要なルール

• 仕様の内容は英語にします
• 要件には検証可能な SHALL 形式の表現を使用します
• 既存の仕様を変更する前に読みます
• 計画オーケストレーターは、新しいバージョンの要件を作成する前に INDEX.md を読みます
• アドホックでは、docs/versions/ 配下にバージョン成果物を作成してはいけません
• アドホックでは、{version_san} をでっち上げてはいけません
• Appearance では、仕様に規範的な Element|How テーブルを貼り付けてはいけません
• Appearance では、Code Review Approved を必須にしてはいけません
• Fragment の対象は docs/specs/{domain}.md または INDEX.md を編集してはいけません。Consolidate は、完全に適用していないフラグメントを削除してはいけません
• docs/specs/agent-architecture.md（ns-agent-architecture の継続的な ADR）を上書きしてはいけません。agent.md は動作のみを記述します

関連スキル

• ns-spec-driven — 計画時に継続的な仕様を読み込みます（references/requirements-generator.md）
• ns-reviewer — Version/Ad-hoc の前提条件として Code Review: Approved が必要です
• ns-judge — Version/Ad-hoc の前提条件として Delivery Review: Approved が必要です
• ns-coder — 両方の Approved の後、アドホックを呼び出す場合があります
• ns-proto-creator / ns-proto-visual-guide — appearance モードを呼び出す場合があります