ns-sdd-execution-handoff-generator

実行ハンドオフ生成ツール

計画 → 実装をつなぎます。{product_root}/docs/versions/{version_san}/execution-handoff.md を生成・維持します。これは、タスクの順序、進捗、トークン数、経過時間の唯一の信頼できる情報源です。

requirements.md は何をするかを、tasks/task-NNN-*.md はどのようにするかを、execution-handoff.md はどの順序で進めるかとどこで実行を停止したかを示します。

ハーネスの検出

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

使用するタイミング

トリガー	アクション
計画の終了時（すべての task-NNN-*.md の作成後）	初期ハンドオフを生成
タスクは存在するが、ハンドオフがない場合	実装前に生成
タスクの開始、完了、ブロック、または免除時	ステータスを更新し、時間とトークン数を再計算
すべてのタスクが完了 — レビュー／継続的な仕様／終了処理	バージョンのステータスと最終タイムスタンプを更新

実装担当者の一連の流れ（ハンドオフを読む → タスクサイクル → 終了処理）については、 references/run-implementation.md を参照してください。

前提条件（生成）

• {product_root} と {version_san} が定義されている
• {product_root}/docs/versions/{version_san}/requirements.md が存在する
• {product_root}/docs/versions/{version_san}/tasks/task-*.md が1つ以上ある
• テンプレート：references/execution-handoff.template.md
• 計画セッションのタイムスタンプ：
  • planning_started_at（ISO形式のローカル時刻 YYYY-MM-DDTHH:MM:SS）
  • planning_finished_at（ISO形式のローカル時刻 YYYY-MM-DDTHH:MM:SS）
  • planning_total_seconds（0以上の整数）

サブバージョンの場合は、 subversions/{subversion_san}/execution-handoff.md にハンドオフを作成します（スライスの範囲のみ）。

初期生成

1. タスクのメタデータを収集する

各 task-NNN-*.md について、数値順に処理します。

フィールド	ソース
タスク	短いIDのみ：task-NNN（task-NNN-*.md から取得し、スラッグを削除）
レイヤー	ファイル名またはタスク本文から推定（backend、frontend、infra、unit-tests、e2e）

ハンドオフの表には、Feature、モデルティア、自由記述のNotesを記載しないでください。それらはタスクファイルに記載します。

2. 実行ルールのブロックを作成する

requirements.md と、存在する場合は {product_root}/docs/context/stack-confirmed.md を読みます。レガシーDBの制約、マルチテナンシー、テスト環境のルールなど、重要な項目を最大10個 {execution_rules_block} に追加します。requirementsファイル全体を重複して記載しないでください。

3. ファイルを作成する

references/execution-handoff.template.md を使用して、 {product_root}/docs/versions/{version_san}/execution-handoff.md に保存します。

• すべてのタスクを Status: pending で開始し、タイムスタンプは —、Time (s): 0、Tokens: 0 とします
• ヘッダーの Tokens (total): は 0 とします
• {next_task_id} = 最初の短いID（例：task-001）
• {base_branch} / {work_branch} は、存在する場合は gitlab-sync-config.md から取得し、それ以外は —

4. オーケストレーターに報告する

ハンドオフのパス、インデックス化したタスクの合計数、最初のタスクID、および references/run-implementation.md を使って実装を開始する指示を返します。

ステータスの更新（実装中）

タスクの開始、完了、ブロック、または免除時：

1. Task status で該当するタスク行を探します
2. Status、Started at（in_progress になった時点）、Finished at（completed になった時点）、Time (s)（Finished at − Started at）、Tokens、Updated at を更新します
3. completed にする前に Tokens が必須です。 情報源（優先順）：
   1. そのタスクの coder-agent および他のサブエージェントのタスク結果／UI に表示される使用量／トークン数
   2. プラットフォームに表示される場合、そのタスクのループにおける親タスクのトークン数
   3. 何も表示されない場合：人間に一度だけ確認します。回答を断られた場合は ~N と推定し、タスクの ## Execution notes に tokens: ~N (estimated) の行を追加します 禁止事項： LLM の作業を行った completed タスクに 0 を指定すること
4. Tokens (total) を再計算します（Tokens 列の合計。整数として扱い、~N は N として数えます）
5. Progress を再計算します（Next task = 最初の pending または in_progress のタスク）
6. Time tracking (seconds) を再計算します：
   • Implementation — start = 入力済みの Started at のうち最も早い時刻
   • Implementation — end = 入力済みの Finished at がある場合、そのうち最も遅い時刻
   • Implementation — total (s) = end − start
   • Total task time (s) = Time (s) 列の合計
   • Total process time (s) = Planning — total (s) + Implementation — total (s) +（Final delivery — end − Implementation — end。両方の値がある場合）
   • Last recalculated = 現在のタイムスタンプ
7. Version status を更新します（テンプレートを参照）
8. Session history を任意で追記します（Date + ごく短い Notes のみ）
9. 重要なメモ（ブロッカー、免除）：該当するものだけをタスクファイルの ## Execution notes に追記します。ハンドオフの Notes 列には記入しないでください

バージョンのクローズ時（レビュー、リビング仕様、_done/ への移動）：Post-implementation review — end、Review — tokens（または Session history のメモ。最後のタスクの Tokens 列には記入しないでください）、該当する場合は Living specs — end、Final delivery — end を入力し、Total process time (s) を再計算します。

許可されるタスクステータス

pending | in_progress | completed | blocked | waived

• waived： タスクの Execution notes に人間による免除の記録が必要です。文書化されたリスク受容がない限り、P0 テストタスク（テナント分離、URL RBAC、認証レート制限）を免除してはいけません。
• 禁止事項： Code Review: Approved なしにバージョンを completed にすること
• 禁止事項： 人間の承認なしにタスクの順序を変更したり、ベースプロンプトを書き換えたりすること
• 禁止事項： セッション履歴を削除すること。追記のみ許可されます

生成後にタスクが追加または削除された場合は、既存のステータスをタスクの短縮 ID ごとに保持したうえで再生成します。

インテグレーション

ステージ	スキル／リファレンス
タスク生成後	このスキル（ハンドオフを生成）
従来型の実装	references/run-implementation.md + coder-agent（利用可能な場合は必須）／ns-code-coder
分割型の実装	ns-execution-orchestrator（スライスのハンドオフ + マスターのクローズ）
バージョン終了時のレビュー	reviewer-agent（利用可能な場合は必須）／ns-code-reviewer
リビング仕様	ns-sdd-living-spec-consolidator
GitLab ボードの同期	ns-gitlab-board-sync（設定がある場合）

リファレンス

ファイル	使用する場面
references/execution-handoff.template.md	ハンドオフの構造
references/run-implementation.md	従来型のバージョン実行ループ