roadmap-generator

适用场景

• 生成从零到生产环境实施系统所需的 规范 changes 索引。
• 将结构化知识库转换为包含明确并行安排的操作计划。
• 识别每个 change 的 关键路径、治理级别和 KB 合约。

不适用场景：

• 根目录中不存在 knowledge-base/（请先运行 kb-creator）。
• 不存在 openspec/ 文件夹（请先运行 openspec init）。
• 根目录中已存在完整的 CHANGES.md，且用户只想更新其中一项（建议改为针对性编辑）。

---

关键模式

必须执行的预检查

生成 CHANGES.md 前，验证以下三个条件。如果任何一项不满足，不要生成任何内容，并返回明确的消息：

检查	不满足时
根目录中存在 knowledge-base/	"缺少 KB。请先运行 kb-creator 以生成它。"
knowledge-base/ 包含全部 10 个规范文件	"KB 不完整。缺少：[列表]。请运行 kb-creator 以补全。"
根目录中存在 openspec/	"OpenSpec 尚未初始化。请先运行 npx @fission-ai/openspec@latest init。"

输出 — 位置

生成一个文件：项目根目录中的 CHANGES.md（不要放在 openspec/ 中）。

理由：CHANGES.md 是项目的 主索引，应当是任何人或 Agent 进入仓库时首先看到的内容。它应放在根目录。

输入 — 要读取的 KB 内容

如果由编排器编排（存在 .jr-orchestrator-state.json，version == 2 且 state.kb.files 非空）： 使用 state.kb.files 作为要读取的路径的权威列表，而不是对目录进行 glob 匹配。 将 state.kb.discovery 用作 change 命名、分组和推断治理级别的上下文（仅作提示——文件才是事实来源）。 如果 state.kb.files 为空或缺失，则回退到读取磁盘（独立运行行为）。

如果独立运行（无状态，或因 state.kb.files 为空而回退）： 执行常规的三项预检查，并直接读取 knowledge-base/ 中的文件。

始终读取以下 4 个规范文件（信息量最大）：

1. 04_modelo_de_datos.md → 实体和关系（揭示表的创建顺序）。
2. 06_funcionalidades.md → US 和史诗（每个 change 的单位）。
3. 07_flujos_principales.md → E2E 流程（揭示哪些 change 是原子性的，哪些是复合的）。
4. 08_arquitectura_propuesta.md → 模式（揭示所需的前置基础设施）。

如果存在，也可选读以下文件：

• 03_actores_y_roles.md → 用于 auth + RBAC 相关的 change。
• 05_reglas_de_negocio.md → 用于检测跨 change 的规则。
• 10_preguntas_abiertas.md → 用于标记依赖关系不确定的 change。

---

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`

change 命名规则

• 使用连续编号 C-01、C-02、...、C-NN。始终补齐为 2 位数字。
• 名称使用 kebab-case，清晰描述内容，不要使用 us-NNN- 前缀（此格式使用 C-NN 作为 ID）。
• 如果一个 change 涵盖多个 US，请在 Scope 中列出。
• 如果是横向 change（基础设施），也照常分配一个 C-NN。

推断依赖关系的规则

必须遵循的层级：

1. 先处理基础设施：C-01 始终是 foundation-setup（结构、依赖项、.env、初始 DB）。它不依赖任何内容。
2. 核心模型先于功能：C-02 通常是 core-models（基础实体、mixins、通用仓库）。
3. 先处理 Auth，再处理受保护资源：如果某个 change 需要已登录用户或角色，则依赖 Auth change。
4. 先处理被引用的实体，再处理引用它的实体：例如，categorias 先于 productos。
5. 后端先于与之耦合的前端：如果某个前端视图使用一个 endpoint，则其 change 依赖创建该 endpoint 的 change。
6. 外部集成／支付／webhook 放在最后：它们依赖已创建的领域实体。
7. 管理后台／仪表盘放在最后：它们依赖所展示的数据。
8. 视觉重构／UI restyle 放在最末尾：需要产品稳定后才能进行。

并行 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 ✓]。
• 对开启多个分支（超过 2 个并行 change）的 gate，标记 ← FORK。

关键路径规则

• 从 C-01 到生产环境所必需的最后一个 change 的最短线性链。
• 不包括视觉重构、额外仪表盘或可选功能。
• 如果有两个 change 都可能是关键路径的“最后一个”，则两者都加星号。

3 个 Agent 的计划规则

表格列：Paso | Agente A (Backend Core) | Agente B (Backend Aux) | Agente C (Frontend)。

• 在遵循依赖关系的前提下，将每个 change 分配给一个 Agent。
• 如果某个步骤中有 Agent 空闲，请标记 —。
• 尽量让 3 个 Agent 大致同时完成工作。

Governance 规则

等级	适用情况
BAJO	脚手架、简单 CRUD、无关键逻辑的前端页面、配置。
MEDIO	有状态的流程、会话、状态机、非关键 WebSocket 事件。
ALTO	通知系统、角色管理、WS gateway、可观测性。
CRITICO	Auth、支付、安全数据（food 中的过敏原）、审计轨迹、其他所有内容都会引用的核心模型。

“Leer antes”规则

每个 change 列出 KB 中 3 到 5 个规范文件，适用时注明具体章节（§2.1、§Auth、§Round lifecycle）。

优先参考：

• 对于 Auth：03_actores_y_roles.md、05_reglas_de_negocio.md §Auth，以及安全文件（如果存在）。
• 对于实体：04_modelo_de_datos.md §entidad。
• 对于 endpoint：07_flujos_principales.md，以及 API 文件（如果存在）。
• 对于前端：08_arquitectura_propuesta.md §frontend，以及约定文件。
• 对于支付／集成：05_reglas_de_negocio.md §Pagos，以及抽象层文件。

Scope 规则

使用操作性项目符号，而非描述性内容。每个项目都必须说明 Agent 将生成什么：

• ✅ 好：POST /api/auth/login — JWT access + refresh，按 IP+email 实施 5/60s 速率限制

• ❌ 不好：完整的身份验证系统和令牌

• ✅ 好：迁移 003：表 allergen、product_allergen、allergen_cross_reaction

• ❌ 不好：创建过敏原表

明确提及：

• 新模型／实体（模型：Category、Subcategory、Product）
• 关键 endpoint（/api/admin/categories、/api/public/menu/{slug}）
• 如果 KB 定义了约定，则注明迁移编号（迁移 002：...）
• 如果存在 WS 事件，则注明（ROUND_PENDING、ROUND_CONFIRMED、...）
• 预期测试（测试：CRUD、多租户隔离、缓存失效）

工作流

1. 执行预检查（KB 存在、10 个规范文件、openspec/ 存在）。
2. 阅读 4 个必需的规范文件 + 3 个可选文件（如果存在）。
3. 识别系统的原子能力（每项能力对应一个 C-NN）。
4. 按语义阶段分组，依次分配 C-NN。
5. 应用 8 条规则推断依赖关系。
6. 计算并行 GATES。
7. 识别关键路径。
8. 使用 3 个 Agent 设计计划。
9. 为每项 change 编写：状态、范围、依赖关系、治理、阅读前置内容。
10. 在根目录编写 CHANGES.md。
11. 以汇总表 + 第一项 change 建议收尾。
12. 如果由编排器编排：执行状态钩子——使用 created_by: "roadmap-generator"、source: "CHANGES.md" 和生成的 C-NN ID 列表更新 state.roadmap。不要写入 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。

记录的切片：

字段	值
created_by	"roadmap-generator"
source	"CHANGES.md"
changes	按顺序排列的生成的 C-NN ID 列表

该切片是一个精简索引：每项 change 的范围、治理和依赖关系详情都保存在 CHANGES.md 中（唯一事实来源）。状态中不会重复任何内容。

完整算法、编排模式下的输入规则以及磁盘回退机制：请参阅 assets/state-contract.md。

---

资源

• 模板：请参阅 assets/changes-template.md——包含示例的完整 CHANGES.md 模板。
• 状态约定：请参阅 assets/state-contract.md——state.roadmap 切片的 schema、有条件写入算法、编排模式下的输入规则（state.kb.files / state.kb.discovery）以及磁盘回退机制。