forge-orkes 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/skills/planning/SKILL.md

@@ -57,15 +57,41 @@ If missing, create from `.forge/templates/requirements.yml`:
 
 Never write to top-level `.forge/requirements.yml` -- that path is deprecated.
 
-## Step 5: Create Roadmap
+## Step 5: Create or Update Roadmap
 
-If `.forge/roadmap.yml` missing (Full only):
+`.forge/roadmap.yml` is **multi-milestone by design** -- see `.forge/templates/roadmap.yml`. Top-level `milestones:` lists each milestone with its phase numbers; top-level `phases:` lists every phase. Phase IDs are scoped per-milestone via the dir naming `m{milestone_id}-{phase_num}-{name}/`, so phase `id: 1` can exist in m50 and m51 without collision.
+
+**Never overwrite existing roadmap content.** Read first, then route on three cases:
+
+### Case A: `roadmap.yml` missing (Full only)
+
+Create from `.forge/templates/roadmap.yml`:
 1. Group by delivery boundaries
 2. Inter-group dependencies
 3. Phases (coherent, verifiable)
 4. Every FR -> one phase, no orphans
 5. Waves: independent=1, dependent=2+
 
+### Case B: `roadmap.yml` exists, current milestone already in it
+
+Verify the milestone entry under `milestones:` and its phases under `phases:` are present and consistent with `requirements/m{N}.yml`. Update phase entries in place if requirements changed. Do not touch other milestones.
+
+### Case C: `roadmap.yml` exists, current milestone NOT in it (append)
+
+This is the common case when starting a new milestone alongside an existing one. Do not fork the file, do not create per-milestone roadmap files, do not overwrite.
+
+1. Append a new entry under `roadmap.milestones:`:
+   ```yaml
+   - id: {N}
+     name: "{milestone name from state/milestone-{N}.yml}"
+     phases: [{list of phase ids you are about to add}]
+   ```
+2. Append each new phase under `roadmap.phases:` with IDs scoped to this milestone (start at `1`, ignore IDs used by other milestones -- dir naming prevents collision).
+3. Recompute `coverage_verified` against the union of all active milestones' `requirements/m{N}.yml` files. Every FR-ID in the active milestone must map to exactly one phase in that milestone.
+4. Update `waves:` only with the new milestone's phase wave assignments. Leave other milestones' wave entries alone.
+
+If a sibling milestone (e.g. m50) has state + requirements but is missing from `roadmap.yml`, that's a pre-existing gap -- flag to user, don't silently backfill.
+
 ## Step 6: Decompose Tasks
 
 Per phase (or feature, Standard tier):

package/template/.forge/migrations/0.10.0-per-milestone-requirements.md

@@ -89,6 +89,8 @@ grep -h "^\s*- id: NFR-" .forge/requirements/*.yml | sort | uniq -d
 
 If duplicates appear: keep the older milestone's ID, renumber the newer one to the next free integer across all files. Update any references in `.forge/phases/m{N}-*/plan-*.md` that cite the renumbered IDs.
 
+**Pragmatic out for projects mid-stream.** If you are migrating a project where multiple milestones were authored under the old pre-0.10.0 assumption that IDs were file-scoped, retroactively renumbering can be hours of mechanical edits across already-shipped plan files. Acceptable alternative: grandfather the existing duplicates as-is, enforce global uniqueness only for new milestones from this point forward, and record the carve-out in `.forge/context.md` under Locked Decisions. The framework's downstream tooling (refactor backlog, plan-file cross-references) will tolerate the grandfathered duplicates as long as no new collisions are introduced.
+
 ### 6. Update references in state files
 
 State files may cite the old paths in `decisions`, `blockers`, or `quick_tasks_history`:

package/template/CLAUDE.md

@@ -125,7 +125,7 @@ State lives in `.forge/`:
 - `project.yml` — Vision, stack, design system, verification, constraints (<5KB)
 - `constitution.md` — Active architectural gates
 - `design-system.md` — Component mapping table
-- `requirements/m{N}.yml` — Per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. FR-IDs are globally unique across milestones (`FR-001` in `m1.yml` and `FR-042` in `m2.yml` don't collide). Concurrent milestones each own their file — no cross-stream contention.
+- `requirements/m{N}.yml` — Per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR-IDs, DEF-IDs, and NFR-IDs are globally unique across all milestone files** — `FR-001` may exist in exactly one `m{N}.yml`. Before adding a new ID, scan `.forge/requirements/*.yml` for the highest in-use number and continue the sequence. On collision (e.g. during a migration), keep the older milestone's ID and renumber the newer. Concurrent milestones each own their file — no cross-stream contention on file writes, but ID space is shared.
 - `roadmap.yml` — Phases, milestones, dependencies
 - `state/index.yml` — Global: active milestones, desire_paths, metrics
 - `state/milestone-{id}.yml` — Per-milestone cursor: position, progress, decisions, blockers