roadmap-generator

使用する場面

• システムをゼロから本番環境まで実装するための、正規の変更一覧を生成する場合。
• 構造化されたナレッジベースを、並列化を明示した運用計画に変換する場合。
• 変更ごとのクリティカルパス、ガバナンスレベル、KB との契約を特定する場合。

次の場合は使用しないでください：

• ルートに knowledge-base/ が存在しない場合（先に kb-creator を実行してください）。
• openspec/ フォルダーが存在しない場合（先に openspec init を実行してください）。
• ルートに完全な CHANGES.md がすでに存在し、ユーザーが1件だけ更新したい場合（代わりに該当箇所のみ編集するよう提案してください）。

---

重要なパターン

必須の事前チェック

CHANGES.md を生成する前に、次の3つの条件を検証してください。いずれか1つでも満たさない場合は、何も生成せず、明確なメッセージを返してください。

チェック	満たさない場合
ルートに knowledge-base/ が存在する	"KB がありません。生成するには、先に kb-creator を実行してください。"
knowledge-base/ に10個の正規ファイルがある	"KB が不完全です。不足しているファイル：[一覧]。補完するには kb-creator を実行してください。"
ルートに openspec/ が存在する	"OpenSpec が初期化されていません。先に npx @fission-ai/openspec@latest init を実行してください。"

出力 — 配置場所

CHANGES.md をプロジェクトのルートに1ファイルだけ生成してください（openspec/ 内ではありません）。

理由：CHANGES.md はプロジェクトのマスター一覧であり、リポジトリに入った人やエージェントが最初に目にするものである必要があります。配置場所はルートです。

入力 — KB から読み取る内容

オーケストレーションされている場合（.jr-orchestrator-state.json が存在し、version == 2 かつ state.kb.files が空でない場合）： ディレクトリを glob で検索する代わりに、読み取るパスの正規リストとして state.kb.files を使用してください。 変更の命名・グループ化とガバナンスの推定には、コンテキストとして state.kb.discovery を使用してください（ヒントのみ。情報源として優先されるのはファイルです）。 state.kb.files が空または存在しない場合は、ディスクを使ったフォールバック（スタンドアロンの動作）に切り替えてください。

スタンドアロンの場合（状態がない、または state.kb.files が空のためフォールバックする場合）： 通常の3つの事前チェックを実行し、knowledge-base/ からファイルを直接読み取ってください。

次の正規ファイル4つは必ず読み取ってください（最も有益なファイルです）：

1. 04_modelo_de_datos.md → エンティティとリレーション（テーブルの作成順が分かります）。
2. 06_funcionalidades.md → US とエピック（各変更の単位です）。
3. 07_flujos_principales.md → E2E フロー（どの変更がアトミックか、複合的かが分かります）。
4. 08_arquitectura_propuesta.md → パターン（事前に必要なインフラが分かります）。

次のファイルがあれば、任意で読み取ってください：

• 03_actores_y_roles.md → auth と RBAC に関する変更用。
• 05_reglas_de_negocio.md → 複数の変更にまたがるルールを検出するため。
• 10_preguntas_abiertas.md → 依存関係が不確かな変更にフラグを付けるため。

---

CHANGES.md の必須フォーマット

ファイルは常に次の構造にしてください。最上位のセクションを追加または削除しないでください — これらは契約です。

上位構造

# CHANGES — Secuencia de Implementación

> Índice canónico de todos los changes del proyecto {NombreProyecto}.
> Cada change es atómico: un agente puede implementarlo en una sesión (~4-6 horas).
> **Leer este archivo antes de ejecutar cualquier `/opsx:propose`.**

---

## Cómo usar este documento

(5 pasos numerados: identificar change → leer KB → propose → archive → marcar checkbox)

---

## Árbol de dependencias

(ASCII art jerárquico con └── y │ mostrando la cadena de dependencias)

### Paralelismo por fase

(GATES numerados desde GATE 0. Cada gate dice qué se desbloqueó y qué se puede ejecutar en paralelo, con [Agente A/B/C] marcando asignaciones sugeridas)

### Camino crítico ({N} changes — mínimo irreducible)

(la cadena más corta para llegar a producción, en flecha)

### Plan óptimo con 3 agentes

(tabla 3 columnas: Paso | Agente A | Agente B | Agente C — qué hace cada uno en cada paso)

---

## FASE {N} — {Nombre semántico de la fase}

> Nota opcional sobre paralelismo dentro de la fase

### [C-{NN}] `{kebab-case-name}`
- **Estado**: `[ ]` pendiente
- **Scope**: descripción densa con bullets (modelos, endpoints, eventos, migraciones, tests)
- **Dependencias**: ninguna | `C-NN` | `C-NN, C-MM`
- **Governance**: BAJO | MEDIO | ALTO | CRITICO
- **Leer antes**:
  - `knowledge-base/0X_archivo.md` §{sección}
  - `knowledge-base/0Y_archivo.md`

変更の命名規則

• 連番のコード C-01、C-02、...、C-NN を使います。常に2桁でゼロ埋めしてください。
• kebab-case の分かりやすい名前を付け、us-NNN- のような接頭辞は付けないでください（この形式では C-NN を ID として使用します）。
• 変更が複数の US を対象とする場合は、Scope 内に記載してください。
• 横断的な変更（インフラ）でも、通常の C-NN を割り当ててください。

依存関係を推測するルール

必須の階層：

1. まずインフラ：C-01 は常に foundation-setup（構造、依存関係、.env、初期 DB）です。何にも依存しません。
2. コアモデルを機能より先に：C-02 は通常、core-models（基本エンティティ、ミックスイン、汎用リポジトリ）です。
3. 保護されたリソースより先に認証：ログイン済みユーザーやロールが必要な change は、認証の change に依存します。
4. 参照する側より先に参照されるエンティティ：例：categorias を productos より先にします。
5. 密結合したフロントエンドより先にバックエンド：フロントエンドのビューがエンドポイントを使用する場合、その change はエンドポイントを作成した change に依存します。
6. 外部連携／決済／webhook は最後：作成済みのドメインエンティティに依存します。
7. 管理画面／ダッシュボードは最後：表示するデータに依存します。
8. ビジュアルのリファクタリング／UI のスタイル変更は最終段階：安定したプロダクトが必要です。

並列処理の GATE に関するルール

グラフ内で、ある change の完了により、互いに依存しない複数の change が開始可能になるポイントを特定します。このような各ポイントを GATE N とします。

各 GATE の形式：

GATE {N}: {change(s) que se completaron} ✓     {← anotación opcional: PRIMER FORK, etc.}
  → C-XX nombre-del-change             [Agente A]
  → C-YY nombre-del-change             [Agente B]
  → C-ZZ nombre-del-change             [Agente C — si C-NN ✓]

• 適切な場合は、ドメインに応じて [Agente A]、[Agente B]、[Agente C]（バックエンドコア、バックエンド補助、フロントエンド）を割り当てます。
• gate 内の change がさらに別の change に依存する場合は、その旨を記載します：[Agente C — si C-NN ✓]。
• 複数のブランチ（並列 change が 2 つを超える）が始まる gate に ← FORK を付けます。

クリティカルパスに関するルール

• C-01 から、本番稼働に不可欠な最後の change までの最短の直線的なチェーンです。
• ビジュアルのリファクタリング、追加のダッシュボード、オプション機能は含めません。
• 2 つの change がクリティカルパスの「最後」になり得る場合は、両方にアスタリスクを付けます。

3 エージェントでの計画に関するルール

列は次のとおりです：Paso | Agente A (Backend Core) | Agente B (Backend Aux) | Agente C (Frontend)。

• 依存関係を守って、各 change をエージェントに割り当てます。
• あるステップでエージェントが作業しない場合は、— を記載します。
• 3 人のエージェントがほぼ同時に完了することを目指します。

ガバナンスに関するルール

レベル	条件
BAJO	スキャフォールディング、シンプルな CRUD、重要なロジックを含まないフロントエンドページ、設定。
MEDIO	状態を持つフロー、セッション、ステートマシン、重要ではない WebSocket イベント。
ALTO	通知システム、ロール管理、WS ゲートウェイ、オブザーバビリティ。
CRITICO	認証、決済、セキュリティデータ（食品のアレルゲン）、監査証跡、他のすべてが参照するコアモデル。

「事前に読む」項目に関するルール

change ごとに、KB の標準ファイルを3〜5 件列挙し、該当する場合は具体的なセクションも記載します（§2.1、§Auth、§Round lifecycle）。

優先順位：

• 認証の場合：03_actores_y_roles.md、05_reglas_de_negocio.md §Auth、セキュリティ関連のファイルがあればそのファイル。
• エンティティの場合：04_modelo_de_datos.md §entidad。
• エンドポイントの場合：07_flujos_principales.md、API 関連のファイルがあればそのファイル。
• フロントエンドの場合：08_arquitectura_propuesta.md §frontend、規約のファイル。
• 決済／連携の場合：05_reglas_de_negocio.md §Pagos、抽象化レイヤーのファイル。

Scope に関するルール

説明的ではなく、作業内容を示す箇条書きにします。各箇条書きには、エージェントが生成するものを記載します。

• ✅ 良い例：POST /api/auth/login — JWT access + refresh、IP+email ごとに 5/60s のレート制限

• ❌ 悪い例：トークンを使った完全な認証システム

• ✅ 良い例：Migración 003: allergen、product_allergen、allergen_cross_reaction テーブル

• ❌ 悪い例：アレルゲンのテーブルを作成する

以下を明示します：

• 新しいモデル／エンティティ（Modelos: Category, Subcategory, Product）
• 主要なエンドポイント（/api/admin/categories、/api/public/menu/{slug}）
• KB で規約が定義されている場合は、番号付きマイグレーション（Migración 002: ...）
• WS イベントがある場合は、そのイベント（ROUND_PENDING, ROUND_CONFIRMED, ...）
• 想定されるテスト（Tests: CRUD、マルチテナント分離、キャッシュ無効化）

---

ワークフロー

1. 事前チェックを実行します（KB が存在すること、正規ファイルが 10 個あること、openspec/ が存在すること）。
2. 必須の正規ファイル 4 個と、存在する場合は任意の正規ファイル 3 個を読みます。
3. システムのアトミックな機能を特定します（それぞれが C-NN になります）。
4. 意味的なフェーズごとにグループ化し、C-NN を連番で割り当てます。
5. 8 つのルールを適用して依存関係を推定します。
6. 並列処理の GATE を計算します。
7. クリティカルパスを特定します。
8. 3 エージェントで計画を設計します。
9. 各 change について、状態、スコープ、依存関係、ガバナンス、事前に読むファイルを記述します。
10. ルートに CHANGES.md を作成します。
11. 最後に概要表と、最初に取り組む change の提案を添えます。
12. オーケストレーション実行時：状態フックを実行し、state.roadmap を更新します。created_by: "roadmap-generator"、source: "CHANGES.md"、生成した ID C-NN の一覧を設定します。step は記述しないでください（オーケストレーターが step を進めます）。条件付き処理の全アルゴリズムについては、assets/state-contract.md を参照してください。

完了時にユーザーに出力

## CHANGES.md generado

✅ `CHANGES.md` creado en la raíz con **{N} changes** organizados en **{M} fases**.

**Camino crítico**: {K} changes
**Gates de paralelismo**: {G}
**Primer change recomendado**: `C-01` ({nombre})

Para arrancar: `/opsx:propose C-01-{nombre}`

---

状態統合（オーケストレーション実行時）

このフックは条件付きで、単独実行にも安全です。プロジェクトのルートに .jr-orchestrator-state.json がすでに存在する場合（jr-orchestrator によるオーケストレーション実行時）にのみ実行されます。ファイルが存在しない場合、現在と同じ動作となり、状態ファイルは作成されません。

実行タイミング：CHANGES.md の書き込み直後（ワークフローの最終ステップで、ユーザーに応答する前）。

書き込む内容：state.roadmap のみです。step、owner、kb、skills、agents には一切触れません。

登録する slice：

フィールド	値
created_by	"roadmap-generator"
source	"CHANGES.md"
changes	生成した ID C-NN の一覧（順序どおり）

この slice は薄いインデックスです。各 change のスコープ、ガバナンス、依存関係の詳細は CHANGES.md（唯一の信頼できる情報源）に記載します。状態ファイルに重複して記録することはありません。

アルゴリズム全体、オーケストレーション入力ルール、ディスクへのフォールバックについては、assets/state-contract.md を参照してください。

---

リソース

• テンプレート：assets/changes-template.md を参照してください。例を含む CHANGES.md の完全なテンプレートです。
• 状態コントラクト：assets/state-contract.md を参照してください。state.roadmap の schema slice、条件付き書き込みアルゴリズム、オーケストレーション入力ルール（state.kb.files / state.kb.discovery）、ディスクへのフォールバックについて説明しています。