forge-orkes 0.10.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.10.0",
+  "version": "0.12.1",
   "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/discussing/SKILL.md

@@ -27,6 +27,8 @@ Structured conversation: approach, trade-offs, decisions. Clarity, not artifacts
 > Write to `.forge/context.md` after EVERY confirmed decision, before asking the next question.
 > If you reach convergence without having written each decision individually — you already violated this rule.
 
+> **Advisory mode (no milestone yet):** Storage still exists. Use `### M? — {topic} (drafting)` heading. Do NOT wait for milestone creation in Step A to start writing. First decision → create heading → append. Same protocol as milestone-bound discussions.
+
 After each user response that confirms a decision:
 
 1. **STOP** — do not continue the discussion
@@ -96,12 +98,14 @@ options:
 If fresh (after `/clear`):
 
 ```
-Read: .forge/state/milestone-{id}.yml → current position, progress
+Read: .forge/state/milestone-{id}.yml → current position, progress (skip if no milestone — advisory mode)
 Read: .forge/project.yml → tech stack, project description
 Read: .forge/context.md → existing locked decisions (if exists)
 Read: .forge/constitution.md → active gates (if exists)
 ```
 
+**Advisory mode (no milestone):** Skip milestone state load. Progressive persistence still applies — writes go to `.forge/context.md` under `### M? — {topic} (drafting)` heading from the first decision. Milestone gets created in Step A only if scope warrants it.
+
 Check `.forge/phases/` for research. If inline-only: *"Summarize findings, or re-scan?"*
 
 ### Step 1: Present Decisions with AskUserQuestion
@@ -306,6 +310,12 @@ If milestone exists → skip to Step B.
 
 ### Step B: Standard Handoff
 
+> **HARD GATE — VERIFY BEFORE HANDOFF.**
+> Read `.forge/context.md` now. Count decisions under the active milestone heading. Compare against decisions confirmed in this conversation.
+> - **If counts match** → proceed to handoff steps below.
+> - **If file is missing, heading absent, or decisions undercount** → progressive persistence failed. STOP. Do NOT recommend `/clear`. Write the missing decisions now from conversation memory, then re-verify. Only then proceed.
+> - **Never claim "state written" without having just read the file.** The recommendation `/clear` is destructive to working memory — earn it.
+
 1. **Promote decisions in `context.md`** -- Rename milestone heading from `(drafting)` → `(locked {date})`. Decisions already written progressively — just finalize:
    - Verify all confirmed decisions present under `## Locked Decisions`
    - Verify deferred items under `## Deferred Ideas`
@@ -313,4 +323,4 @@ If milestone exists → skip to Step B.
    - Add any unresolved items to `## Needs Resolution`
    - If `context.md` already exists (post-planning discussion), update relevant sections + log amendments
 2. **Update state** -- `current.status` = `planning` (`architecting` for Full) in milestone yml
-3. **Recommend clear:** *"State written. `/clear` then `/forge` for {planning/architecting}."*
+3. **Recommend clear:** *"State written and verified ({N} decisions in context.md). `/clear` then `/forge` for {planning/architecting}."*

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

@@ -37,7 +37,40 @@ Read `.forge/context.md`. **Needs Resolution** unchecked → warn: *"{N} unresol
 
 Check `.forge/refactor-backlog.yml`:
 - *"{N} refactors ({Q} quick, {S} standard). Tackle first?"*
-- Pick → `quick-tasking`/Standard, set `in_progress`. Decline → proceed.
+- Pick item → branch on `effort`:
+  - `effort: quick` → `quick-tasking`, set `status: in_progress`. Unchanged.
+  - `effort: standard` → **Promote to milestone** (procedure below), then fall through to Step 3 Standard routing.
+- Decline → proceed.
+
+**Promotion procedure (effort: standard only):**
+
+1. Read backlog item `id` (e.g. `R61-002`). Synthesize milestone id `m-{R-id}` (e.g. `m-R61-002`).
+2. Copy `.forge/templates/state/milestone.yml` → `.forge/state/milestone-{m-R-id}.yml`. Populate:
+   - `milestone.id: m-{R-id}`
+   - `milestone.name: "Promoted from {R-id}: {backlog item title}"`
+   - `milestone.origin: {R-id}`
+   - `current.tier: standard`, `current.status: researching`
+   - `progress.last_update: {ISO date}`
+3. Append to `.forge/state/index.yml` `milestones:`:
+   ```yaml
+   - id: m-{R-id}
+     name: "Promoted from {R-id}: {title}"
+     status: active
+     last_updated: "{ISO date}"
+   ```
+4. Append to `.forge/roadmap.yml` — one milestone entry + one phase (`refactor-{R-id}`, `requirements_source: refactor-backlog.yml#{R-id}`, `dependencies: []`).
+5. Update `.forge/refactor-backlog.yml` item: `status: in_progress`, add `promoted_to: m-{R-id}`.
+6. Confirm: *"Promoted {R-id} → milestone m-{R-id}. State + roadmap created. Routing to researching."*
+
+```text
+backlog pickup → effort: standard
+  ├─ write milestone-{m-R-id}.yml (origin: {R-id})
+  ├─ append index.yml + roadmap.yml
+  ├─ flip backlog item (in_progress + promoted_to)
+  └─ fall through → Standard tier routing
+```
+
+Downstream skills (researching, discussing, planning, executing, verifying, reviewing) see a normal milestone — no special branching.
 
 Check `desire_paths` 3+ occurrences:
 - *"Recurring: [{description}] ({N}x). Fix via [suggestion]?"*

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/.claude/skills/reviewing/SKILL.md

@@ -304,16 +304,28 @@ Report = audit trail.
 ## Backlog Lifecycle
 
 ```
-pending → in_progress → done
-pending → dismissed (during triage or later)
+pending → in_progress → resolved
+pending → wontfix (during triage or later)
 ```
 
-`quick` -> `quick-tasking`. `standard` -> Standard tier.
+`quick` -> `quick-tasking`. `standard` -> promoted to milestone via `forge` Step 1.2.
 
-`forge` surfaces -> user selects -> route by effort -> `status: done` + date.
+`forge` surfaces -> user selects -> route by effort -> on completion, `status: resolved` + date.
+
+Legacy items may use `done`/`dismissed` — both still readable; new transitions use `resolved`/`wontfix`.
+
+## Promoted Milestone Completion Hook
+
+If the milestone being completed has `milestone.origin: {R-id}` set (promoted from refactor-backlog), flip the originating item before exit:
+
+1. Read `milestone.origin` from `milestone-{id}.yml`. If null → skip (fresh milestone, no hook).
+2. Open `.forge/refactor-backlog.yml`. Find item with matching `id`.
+3. Update item: `status: resolved`, set `completed: "<ISO 8601 date>"`. Keep `promoted_to: {milestone-id}` intact for audit trail.
+4. Log in summary: *"Backlog item {R-id} → resolved (promoted milestone {id} complete)."*
 
 ## Phase Handoff
 
 1. Confirm report + backlog
-2. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"`
-3. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*
+2. **Run promoted-milestone completion hook** (above) if `milestone.origin` set
+3. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"`
+4. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*

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/.forge/templates/state/milestone.yml

@@ -6,6 +6,7 @@
 milestone:
   id: null                             # Milestone ID from roadmap
   name: ""                             # Human-readable milestone name
+  origin: null                         # Backlog item ID if this milestone was promoted from refactor-backlog.yml. null for fresh milestones.
 
 current:
   tier: null                           # quick | standard | full

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