forge-orkes 0.9.5 → 0.10.0

package/bin/create-forge.js

@@ -19,7 +19,7 @@ const FORGE_END = '<!-- forge:end -->';
 const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
 
 // Template-only: reference templates Forge controls
-const TEMPLATE_ONLY_DIRS = ['.forge/templates'];
+const TEMPLATE_ONLY_DIRS = ['.forge/templates', '.forge/migrations'];
 
 // Settings file gets smart-merge (overwrite forge.* keys, preserve user hooks)
 const SETTINGS_FILE = '.claude/settings.json';
@@ -284,6 +284,64 @@ async function install() {
   console.log(`\n  Forge v${pkgVersion} is ready. Start with: /forge\n`);
 }
 
+/**
+ * Detect pre-0.10.0 requirements layouts (single top-level file, suffixed top-level,
+ * or per-phase files). Returns array of legacy paths found, relative to project root.
+ */
+function detectLegacyRequirementsLayout() {
+  const forgeDir = path.join(targetDir, '.forge');
+  if (!fs.existsSync(forgeDir)) return [];
+
+  const legacy = [];
+
+  for (const entry of fs.readdirSync(forgeDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (entry.name === 'requirements.yml') {
+      legacy.push(path.join('.forge', entry.name));
+    } else if (/^requirements-m\d+\.yml$/.test(entry.name)) {
+      legacy.push(path.join('.forge', entry.name));
+    }
+  }
+
+  const phasesDir = path.join(forgeDir, 'phases');
+  if (fs.existsSync(phasesDir)) {
+    for (const phase of fs.readdirSync(phasesDir, { withFileTypes: true })) {
+      if (!phase.isDirectory()) continue;
+      const reqPath = path.join(phasesDir, phase.name, 'requirements.yml');
+      if (fs.existsSync(reqPath)) {
+        legacy.push(path.join('.forge', 'phases', phase.name, 'requirements.yml'));
+      }
+    }
+  }
+
+  return legacy;
+}
+
+/**
+ * After upgrade, surface any detected legacy file layouts that the new framework
+ * version no longer writes. Non-interactive — prints a warning with a pointer to
+ * the migration guide. Add new detection blocks here as future versions change layout.
+ */
+function runPostUpgradeMigrationChecks() {
+  const legacyReqs = detectLegacyRequirementsLayout();
+  if (legacyReqs.length === 0) return;
+
+  console.log('  ⚠  Pre-0.10.0 requirements layout detected');
+  console.log('  ─────────────────────────────────────────');
+  console.log('  Found:');
+  for (const p of legacyReqs) {
+    console.log(`    ${p}`);
+  }
+  console.log();
+  console.log('  Forge 0.10.0+ uses per-milestone files at .forge/requirements/m{N}.yml.');
+  console.log('  Migration guide: .forge/migrations/0.10.0-per-milestone-requirements.md');
+  console.log();
+  console.log('  Run the migration before your next planning cycle. In Claude Code:');
+  console.log('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
+  console.log('    with the guide path as the task definition.');
+  console.log();
+}
+
 async function upgrade() {
   console.log('\n  Forge Upgrade\n');
 
@@ -384,6 +442,8 @@ async function upgrade() {
   }
 
   console.log(`  Upgraded to v${pkgVersion}\n`);
+
+  runPostUpgradeMigrationChecks();
 }
 
 // --- Entry point ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.9.5",
+  "version": "0.10.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/agents/planner.md

@@ -18,7 +18,7 @@ Research -> actionable plans. Every plan passes constitutional gates with verifi
 Research findings, `.forge/templates/project.yml`, `constitution.md`, `context.md`, `state/milestone-{id}.yml` (if resuming).
 
 ## Output
-`.forge/` files: `phases/m{M}-{N}-{name}/plan.md` (XML tasks), `specs/`, `requirements.yml`, `context.md`, `state/milestone-{id}.yml`.
+`.forge/` files: `phases/m{M}-{N}-{name}/plan.md` (XML tasks), `specs/`, `requirements/m{N}.yml`, `context.md`, `state/milestone-{id}.yml`.
 
 ## Process
 

package/template/.claude/agents/verifier.md

@@ -60,6 +60,7 @@ Run: {n} | Passed: {n} | Failed: {n} | Coverage: {if available}
 Read: .forge/phases/m{M}-{N}-{name}/plan.md → extract must_haves
 Read: .forge/state/milestone-{id}.yml → reported progress
 Read: .forge/context.md → locked decisions
+Read: .forge/deferred-issues.md → known pre-existing failures (if exists; treat as advisory)
 ```
 
 ### 2. Truths
@@ -90,6 +91,10 @@ npm run build 2>&1
 npm run lint 2>&1
 ```
 
+Cross-reference failures against `deferred-issues.md`:
+- Match on test name or summary → advisory; label "Pre-existing (deferred: DI-{N})"
+- No match → regression; include in Issues (Critical) and gaps
+
 ### 6. Anti-Pattern Scan
 
 | Pattern | Command | Severity |
@@ -101,7 +106,7 @@ npm run lint 2>&1
 | Missing error handling | `grep -rn "\.catch()" src/` | Warning |
 
 ### 7. Requirements
-Cross-ref `requirements.yml`: `must-have` implemented, criteria testable, flag gaps.
+Cross-ref `requirements/m{N}.yml` (current milestone): `must-have` implemented, criteria testable, flag gaps.
 
 ### 8. Report
 **PASS**: all truths, substantive+wired, tests pass. **PARTIAL**: some gaps. **FAIL**: unverified, stubs, failing tests.

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

@@ -23,16 +23,21 @@ Structured conversation: approach, trade-offs, decisions. Clarity, not artifacts
 
 ## Progressive Persistence
 
-**Decisions persist immediately. This is a hard gate — not a guideline.**
+> **HARD GATE — NOT A GUIDELINE. NO EXCEPTIONS.**
+> 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.
 
 After each user response that confirms a decision:
 
 1. **STOP** — do not continue the discussion
 2. **Write to disk** — append to `.forge/context.md` (create from template if missing)
+   - **Path is always `.forge/context.md`** — never `.forge/phases/*/context.md`, never inline memory
 3. **THEN** continue to the next question
 
 Never accumulate decisions in working memory. Never batch writes to convergence.
 
+**Common failure mode:** Agent says "decisions live in conversation; planning writes context.md." This is WRONG. Discussing writes context.md. Planning reads it.
+
 ### Write Protocol
 
 **On first decision of the session:**
@@ -190,7 +195,7 @@ options:
 
 ```
 Read: .forge/phases/m{M}-{N}-{name}/plan-{NN}.md → the plan
-Read: .forge/requirements.yml → source requirements
+Read: .forge/requirements/m{N}.yml → source requirements (current milestone)
 Read: .forge/context.md → locked decisions
 Read: .forge/constitution.md → active gates
 ```

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

@@ -10,6 +10,18 @@ description: "Build to plan with atomic commits, deviation rules, and context en
 - [ ] Context.md locked decisions noted
 - [ ] Constitution.md gates satisfied
 - [ ] Milestone state updated to `status: executing`
+- [ ] Baseline snapshot captured (see below)
+
+## Baseline Snapshot
+
+Run **before the first task begins**. Makes failure causality mechanical — no self-assessment.
+
+1. Run all non-advisory verification commands
+2. Record which tests/checks pass and which fail — this is the baseline
+3. After each commit: failures **not in baseline** = introduced by this task = **must fix under Rule 3**
+4. Failures **present in baseline** = pre-existing → append to `.forge/deferred-issues.md`, mark `status: pending`
+
+Skip only if re-entering an in-progress execution and `deferred-issues.md` already documents all current failures.
 
 ## Deviation Rules
 
@@ -116,9 +128,9 @@ For each command, in order:
 ```
 Attempt 1:
   1. Read error output
-  2. Caused by current task?
-     - YES → fix code, stage fixes, amend commit
-     - NO → mark advisory for this session; append to .forge/deferred-issues.md; continue
+  2. In baseline snapshot?
+     - YES (pre-existing) → mark advisory for this session; append to .forge/deferred-issues.md; continue
+     - NO (introduced by this task) → fix code, stage fixes, amend commit
   3. Re-run command
   4. Pass → next command
   5. Fail → next attempt (up to max_retries)
@@ -133,7 +145,7 @@ After max_retries exhausted:
 Verification retries count toward the task's 3-strike limit. 2 strikes used = 1 verification retry max.
 
 ### Do NOT Fix
-- **Pre-existing failures** not from current task → mark advisory; append to `.forge/deferred-issues.md`
+- **Pre-existing failures** present in baseline snapshot → mark advisory; append to `.forge/deferred-issues.md`
 - **Flaky tests** passing on re-run without changes → note in summary, no strike
 - **Unrelated warnings** (deprecation, non-blocking lint) → ignore
 
@@ -190,7 +202,8 @@ After completing all tasks in a plan:
 - src/components/Login.tsx (created)
 
 ## Notes
-[Anything the verifier should know]
+[Genuine handoff context only: environment requirements, seed data, external services needed (e.g. "Redis must be running for auth tests").
+Do NOT list test failures here — pre-existing failures belong in deferred-issues.md; task-introduced failures must be fixed before committing.]
 ```
 
 ## State Updates

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

@@ -246,7 +246,7 @@ Phase transitions = clear boundaries. **Recommend `/clear`** after writing state
 | researching | `.forge/research/milestone-{id}.md` | discussing |
 | discussing | `.forge/context.md` (locked decisions, deferrals, discretion) | planning |
 | architecting | ADRs, data models, API contracts | planning |
-| planning | `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml | executing |
+| planning | `.forge/phases/m{M}-{N}-{name}/`, `.forge/requirements/m{N}.yml`, roadmap.yml | executing |
 | executing | Committed code, execution summary, state | verifying |
 | verifying | Verification report, desire paths | reviewing |
 

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

@@ -57,7 +57,7 @@ Check: Any structured agent/workflow system
 | Source | Target |
 |--------|--------|
 | Project descriptions | `.forge/project.yml` |
-| Requirements | `.forge/requirements.yml` |
+| Requirements | `.forge/requirements/m1.yml` (first milestone; subsequent milestones get their own file) |
 | Roadmaps/plans | `.forge/roadmap.yml` |
 | Context/decisions | `.forge/context.md` |
 | State/progress | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
@@ -75,7 +75,7 @@ Check: Any structured agent/workflow system
 | GSD Source | Extract | Write to Forge |
 |-----------|---------|---------------|
 | `PROJECT.md` | Project name, description, tech stack, goals | `.forge/project.yml` |
-| `REQUIREMENTS.md` | Feature requirements, acceptance criteria → YAML with IDs | `.forge/requirements.yml` |
+| `REQUIREMENTS.md` | Feature requirements, acceptance criteria → YAML with IDs | `.forge/requirements/m1.yml` |
 | `ROADMAP.md` | Phases, milestones, dependencies → YAML with refs | `.forge/roadmap.yml` |
 | `STATE.md` | Current phase, progress, blockers | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
 | `CONTEXT.md` | NON-NEGOTIABLE decisions, DEFERRED ideas | `.forge/context.md` |
@@ -89,7 +89,7 @@ Check: Any structured agent/workflow system
 | Spec-Kit Source | Extract | Write to Forge |
 |----------------|---------|---------------|
 | `spec-driven.md` | Governance patterns | `.forge/constitution.md` |
-| `templates/spec-template.md` | Requirements format | `.forge/requirements.yml` |
+| `templates/spec-template.md` | Requirements format | `.forge/requirements/m1.yml` |
 | `templates/constitution-template.md` | Immutable gates | `.forge/constitution.md` |
 | `extensions/` | Specialized skills | `.claude/skills/` (if relevant) |
 | Project specs (if filled in) | Locked decisions | `.forge/context.md` |

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

@@ -16,7 +16,7 @@ Read `.forge/context.md` **Needs Resolution**. If unchecked `- [ ]` items:
 |--------|--------|
 | Lock | Record in Locked Decisions |
 | Defer | Move to Deferred Ideas + revisit date |
-| Fix | Add as FR-xxx in `.forge/requirements.yml` |
+| Fix | Add as FR-xxx in `.forge/requirements/m{N}.yml` (current milestone) |
 | Drop | Note in Amendment Log |
 
 Mark resolved `- [x]`. Target: 2-5 min.
@@ -43,16 +43,20 @@ Must complete BEFORE plans. Plans reference context.md.
 
 ## Step 4: Structure Requirements
 
-If `.forge/requirements.yml` missing, create from template:
+Resolve current milestone ID from `.forge/state/index.yml` (active milestone) or invocation context. Target file: `.forge/requirements/m{N}.yml`.
+
+If missing, create from `.forge/templates/requirements.yml`:
 1. Extract from user description + research
-2. IDs: FR-001, FR-002...
+2. IDs: FR-001, FR-002... **Globally unique across milestones** -- check existing `.forge/requirements/*.yml` for highest FR-ID, continue sequence
 3. Acceptance: Given/When/Then
 4. Uncertain: `[NEEDS CLARIFICATION]`
 5. P1 (must) / P2 (should) / P3 (nice)
-6. Deferred: DEF-001...
+6. Deferred: DEF-001... (also globally unique)
 
 **Blocks until all P1 `[NEEDS CLARIFICATION]` resolved.**
 
+Never write to top-level `.forge/requirements.yml` -- that path is deprecated.
+
 ## Step 5: Create Roadmap
 
 If `.forge/roadmap.yml` missing (Full only):
@@ -193,7 +197,7 @@ Step 7 intentionally skips UI — that coverage is owned by `testing` skill (e2e
 **Auto-suggest heuristic:** When requirements contain UI signals, prompt user once (pre-code) to invoke `testing`:
 
 Signals (any match):
-- `requirements.yml` description mentions: "UI", "page", "flow", "form", "dashboard", "component", "screen"
+- `requirements/m{N}.yml` description mentions: "UI", "page", "flow", "form", "dashboard", "component", "screen"
 - Tasks in Step 6 have files matching: `src/components/**`, `src/pages/**`, `src/app/**`, `*.tsx`, `*.vue`, `*.svelte`
 - `project.yml` stack includes web framework (Next.js, React, Vue, Svelte, Astro, Remix)
 
@@ -231,6 +235,6 @@ Done when approved.
 
 ## Handoff
 
-1. **Persist** -- plans `.forge/phases/`, reqs `.forge/requirements.yml`, roadmap `.forge/roadmap.yml`, context `.forge/context.md`
+1. **Persist** -- plans `.forge/phases/`, reqs `.forge/requirements/m{N}.yml`, roadmap `.forge/roadmap.yml`, context `.forge/context.md`
 2. **State** -- `current.status` = `executing` in `.forge/state/milestone-{id}.yml`
 3. *"Plan written. `/clear` then `/forge` to continue."*

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

@@ -26,7 +26,7 @@ Template directory: `{source}/packages/create-forge/template/`.
 | **Merge-owned** | `CLAUDE.md`, `.claude/settings.json` | Never auto-overwrite |
 | **Template-only** | `.forge/templates/**` | Overwrite |
 
-**Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements.yml`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
+**Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
 ## Step 3: Sync Framework-Owned Files
 
@@ -80,3 +80,46 @@ Needs manual review: {N} files
 
 Unchanged: {N} files
 ```
+
+## Step 7: Post-Upgrade Migration Checks
+
+After sync completes, detect legacy file layouts that the new framework version no longer writes but may still read in compatibility mode. For each match, surface a migration prompt — do not auto-migrate.
+
+### Pre-0.10.0 requirements layout
+
+Run from project root:
+
+```bash
+find .forge -maxdepth 2 -type f \( -name "requirements.yml" -o -name "requirements-m*.yml" \) \
+  | grep -v "^.forge/templates/" \
+  | grep -v "^.forge/requirements/"
+
+find .forge/phases -type f -name "requirements.yml" 2>/dev/null
+```
+
+If either command returns matches, surface:
+
+```
+Pre-0.10.0 requirements layout detected
+───────────────────────────────────────
+Found: {list of legacy paths}
+
+Forge 0.10.0 uses per-milestone files at .forge/requirements/m{N}.yml.
+A migration guide is available at: .forge/migrations/0.10.0-per-milestone-requirements.md
+(installed alongside Forge; canonical copy at
+ https://github.com/Attuned-Media/forge/blob/main/docs/migrations/0.10.0-per-milestone-requirements.md)
+
+Run the migration now? (yes/no/show guide)
+```
+
+- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition
+- **show guide** → read and display the file, then re-ask
+- **no** → note in upgrade report. Skills will continue reading the legacy path as deprecated; new writes still go to the new path, causing split-brain state. Recommend running migration before next planning cycle.
+
+### Future migrations
+
+Add new detection blocks here for each Forge version that changes file layout. Pattern:
+1. Detection command(s)
+2. Single-line description of the drift
+3. Pointer to `.forge/migrations/{version}-{slug}.md` (installed copy; canonical at `docs/migrations/...` in the Forge source repo)
+4. Three-way prompt (yes/no/show guide)

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

@@ -20,9 +20,34 @@ Read: .forge/state/milestone-{id}.yml → current phase, plans completed
 Read: .forge/project.yml → tech stack (for running tests)
 Read: .forge/phases/m{M}-{N}-{name}/plan-{NN}.md → must_haves (truths, artifacts, key_links)
 Read: .forge/context.md → locked decisions
-Read: .forge/requirements.yml → requirement IDs for coverage check
+Read: .forge/requirements/m{N}.yml → requirement IDs for coverage check (current milestone, resolved from state)
+Read: .forge/deferred-issues.md → known pre-existing failures (if exists; treat as advisory)
 ```
 
+## Deferred Issues
+
+If `.forge/deferred-issues.md` exists, load it before running any tests.
+
+When test results come in, cross-reference failures against known deferred issue IDs:
+
+- **Failure matches a deferred ID** → advisory only — note as "Pre-existing (deferred: DI-{N})", do NOT fail verification for this
+- **Failure not in deferred-issues.md** → regression introduced after the baseline — **FAIL** and include in gaps
+
+In the Test Results section of the report, split accordingly:
+
+```markdown
+## Test Results
+Run: {n} | Passed: {n} | Failed: {n}
+
+### Regressions (block release)
+- {test name}: {error}
+
+### Pre-existing / Deferred (advisory)
+- DI-{N}: {test name} — {summary from deferred-issues.md}
+```
+
+Verdict: FAIL only triggers for regressions. Known deferred failures do not block a PASSED verdict — they are tracked separately and must be worked off via the refactor backlog or a dedicated fix phase.
+
 ## Interface Testing Gate
 
 Read `interface` from `.forge/project.yml`. If absent, `[]`, or `[none]` → skip gate, proceed to 3-level verification.
@@ -137,7 +162,7 @@ After 3-level verification:
 
 ## Requirements Coverage
 
-Cross-reference against `.forge/requirements.yml`:
+Cross-reference against `.forge/requirements/m{N}.yml` (current milestone):
 
 ```markdown
 | Requirement | Status | Evidence |

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

@@ -0,0 +1,140 @@
+# Migration Guide: Per-Milestone Requirements (Forge 0.10.0)
+
+Forge 0.10.0 splits requirements from a single `.forge/requirements.yml` into per-milestone files under `.forge/requirements/m{N}.yml`. FR-IDs remain globally unique across all milestone files.
+
+This guide migrates pre-0.10.0 layouts to the new convention. Safe for an agent to run autonomously.
+
+## Why
+
+The pre-0.10.0 spec had a single top-level `.forge/requirements.yml` "refreshed per milestone." Projects with concurrent active milestones produced ad-hoc adaptations (per-phase `requirements.yml`, suffixed `requirements-m{N}.yml`). Per-milestone files formalize the desire path: each active milestone owns its own file, no cross-stream contention, mirroring the existing `state/milestone-{id}.yml` pattern.
+
+## Prerequisites
+
+1. Forge framework files upgraded to ≥0.10.0 (run `Skill(upgrading)` first).
+2. Working tree clean or changes committed — migration is mechanical but touches several files.
+
+## Detection
+
+Run from project root. Any match below means migration is needed:
+
+```bash
+# Off-spec layout signals
+ls .forge/requirements.yml 2>/dev/null                    # legacy single file
+ls .forge/requirements-m*.yml 2>/dev/null                 # suffixed top-level
+find .forge/phases -name "requirements.yml" 2>/dev/null   # per-phase files
+```
+
+If `.forge/requirements/` already exists as a directory and the legacy paths above are absent, migration is complete — stop here.
+
+## Migration steps
+
+### 1. Inventory existing files
+
+List every `requirements*.yml` outside the new `requirements/` subdir:
+
+```bash
+find .forge -type f \( -name "requirements.yml" -o -name "requirements-m*.yml" \) \
+  | grep -v "^.forge/requirements/" \
+  | grep -v "^.forge/templates/"
+```
+
+For each path found, determine which milestone it belongs to:
+
+| Source pattern | Milestone ID |
+|----------------|--------------|
+| `.forge/requirements.yml` | Read `state/index.yml` — usually the most recently active milestone, or the one referenced by the file's content. If ambiguous, ask the user. |
+| `.forge/requirements-m{N}.yml` | `{N}` from the filename |
+| `.forge/phases/m{N}-{name}/requirements.yml` | `{N}` from the phase directory |
+
+### 2. Create the subdirectory
+
+```bash
+mkdir -p .forge/requirements
+```
+
+### 3. Move each file
+
+For each source file, move to `.forge/requirements/m{N}.yml`:
+
+```bash
+# Example patterns — adapt to actual filenames found in step 1
+mv .forge/requirements.yml           .forge/requirements/m{N}.yml
+mv .forge/requirements-m53.yml       .forge/requirements/m53.yml
+mv .forge/phases/m51-*/requirements.yml .forge/requirements/m51.yml
+```
+
+If multiple source files map to the same milestone (e.g., multiple per-phase files for the same milestone), merge them into one target file: concatenate the `functional`, `non_functional`, and `deferred` arrays. Preserve all FR-IDs.
+
+### 4. Add the `milestone:` field
+
+Each migrated file needs a top-level `milestone:` declaration matching the milestone ID in `state/index.yml`:
+
+```yaml
+milestone: 53          # add this line at the top
+version: "v1"
+functional:
+  - id: FR-001
+    ...
+```
+
+### 5. Audit FR-ID uniqueness
+
+FR-IDs (and DEF-IDs, NFR-IDs) are globally unique across all milestone files. Check for collisions:
+
+```bash
+grep -h "^\s*- id: FR-" .forge/requirements/*.yml | sort | uniq -d
+grep -h "^\s*- id: DEF-" .forge/requirements/*.yml | sort | uniq -d
+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.
+
+### 6. Update references in state files
+
+State files may cite the old paths in `decisions`, `blockers`, or `quick_tasks_history`:
+
+```bash
+grep -rn "requirements\.yml\|requirements-m" .forge/state/
+```
+
+Replace each match with the new per-milestone path. State file content is human-readable YAML — straightforward find/replace.
+
+### 7. Verify roadmap coverage
+
+`.forge/roadmap.yml` coverage check must now cover all milestone files. Every FR-ID across `.forge/requirements/*.yml` for active milestones should appear in exactly one phase. Run a planning skill pass to refresh the `coverage_verified` flag, or check manually.
+
+## Post-migration verification
+
+After completing all steps:
+
+```bash
+# Should be empty (no legacy paths left)
+find .forge -type f \( -name "requirements.yml" -o -name "requirements-m*.yml" \) \
+  | grep -v "^.forge/requirements/" \
+  | grep -v "^.forge/templates/"
+
+# Should list one file per active milestone
+ls .forge/requirements/
+
+# Should be empty (no duplicate FR-IDs)
+grep -h "^\s*- id: FR-" .forge/requirements/*.yml | sort | uniq -d
+```
+
+Commit the migration as a single change:
+
+```
+refactor(requirements): migrate to per-milestone files (Forge 0.10.0)
+```
+
+## What changes downstream
+
+After migration, all Forge skills read/write the new paths automatically:
+
+- `planning` writes to `.forge/requirements/m{N}.yml` using the current milestone ID
+- `verifying` and `discussing` read the same path
+- `upgrading` protects the whole `.forge/requirements/` directory
+- Top-level `.forge/requirements.yml` is deprecated — delete if a stale copy is recreated by any non-upgraded tool
+
+## Rollback
+
+Migration is reversible by `git revert` of the migration commit (paths revert, content preserved). The 0.10.0 skills still understand the legacy paths only as deprecated targets — downgrading the framework alongside the revert is required if you need full pre-0.10.0 behavior.

package/template/.forge/templates/framework-absorption/generic.md

@@ -23,7 +23,7 @@ Since the framework is unknown, use the `researching` skill to understand it:
 2. **Map the structure** — List all directories and key files
 3. **Classify content** — For each file, determine if it contains:
    - Project information (→ `.forge/project.yml`)
-   - Requirements or specifications (→ `.forge/requirements.yml`)
+   - Requirements or specifications (→ `.forge/requirements/m1.yml`)
    - Plans or roadmaps (→ `.forge/roadmap.yml`)
    - State or progress tracking (→ `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml`)
    - Decisions or constraints (→ `.forge/context.md`)
@@ -45,7 +45,7 @@ Since the framework is unknown, use the `researching` skill to understand it:
 - [ ] Framework structure mapped and understood
 - [ ] All content files classified by type
 - [ ] Project info extracted to `.forge/project.yml`
-- [ ] Requirements extracted to `.forge/requirements.yml`
+- [ ] Requirements extracted to `.forge/requirements/m1.yml`
 - [ ] Governance rules mapped to `.forge/constitution.md`
 - [ ] Remaining knowledge captured in `.forge/context.md`
 - [ ] Original framework files archived in `.forge/archive/{name}/`

package/template/.forge/templates/framework-absorption/gsd.md

@@ -18,7 +18,7 @@ CONTEXT.md with "NON-NEGOTIABLE" or "DEFERRED" sections
 | GSD Source | Forge Target | Conversion Notes |
 |-----------|-------------|-----------------|
 | `PROJECT.md` | `.forge/project.yml` | Extract project name, description, tech stack, goals. Convert prose to YAML structure. |
-| `REQUIREMENTS.md` | `.forge/requirements.yml` | Assign FR-IDs to each requirement. Convert acceptance criteria to Given/When/Then. Mark unknowns as `[NEEDS CLARIFICATION]`. |
+| `REQUIREMENTS.md` | `.forge/requirements/m1.yml` | Assign FR-IDs to each requirement. Convert acceptance criteria to Given/When/Then. Mark unknowns as `[NEEDS CLARIFICATION]`. |
 | `ROADMAP.md` | `.forge/roadmap.yml` | Extract phases, milestones. Add dependency references between phases. Convert to YAML. |
 | `STATE.md` | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` | Extract current phase number, progress, active blockers, recent decisions. Split into global index and per-milestone state. |
 | `CONTEXT.md` | `.forge/context.md` | NON-NEGOTIABLE → Locked Decisions. DEFERRED → Deferred Ideas. DISCRETION → Discretion Areas. Minimal format change needed. |
@@ -159,7 +159,7 @@ Flag any discrepancies to the user. The codebase is the source of truth, not the
 - [ ] All GSD state files read and content extracted
 - [ ] **Documentation verified against actual codebase** (discrepancies flagged)
 - [ ] Project info converted to `.forge/project.yml`
-- [ ] Requirements converted to `.forge/requirements.yml` with IDs
+- [ ] Requirements converted to `.forge/requirements/m1.yml` with IDs
 - [ ] Roadmap converted to `.forge/roadmap.yml`
 - [ ] Current state captured in `.forge/state/` (index.yml + milestone files, verified against code reality)
 - [ ] Context/decisions preserved in `.forge/context.md`

package/template/.forge/templates/framework-absorption/spec-kit.md

@@ -17,9 +17,9 @@ AGENTS.md                          # Agent definitions
 | Spec-Kit Source | Forge Target | Conversion Notes |
 |----------------|-------------|-----------------|
 | `spec-driven.md` | `.forge/constitution.md` | Extract governance rules. Map to Forge's 9 articles or create project-specific ones. |
-| `templates/spec-template.md` | `.forge/requirements.yml` | Convert spec structure to YAML requirements with IDs. |
+| `templates/spec-template.md` | `.forge/requirements/m1.yml` | Convert spec structure to YAML requirements with IDs. |
 | `templates/constitution-template.md` | `.forge/constitution.md` | Merge with Forge's article template. Preserve project-specific gates. |
-| Filled-in specs (project-specific) | `.forge/project.yml` + `.forge/requirements.yml` | Extract project info and requirements separately. |
+| Filled-in specs (project-specific) | `.forge/project.yml` + `.forge/requirements/m1.yml` | Extract project info and requirements separately. |
 | `extensions/` configs | `.claude/skills/` | Evaluate each extension. Create Forge skills for valuable ones. |
 | `AGENTS.md` | `.claude/agents/` | Map agent definitions to Forge's 5 agents. |
 | `templates/checklist-template.md` | Informs verification skill | Extract checklist patterns for verifier. |
@@ -29,7 +29,7 @@ AGENTS.md                          # Agent definitions
 
 - **Constitutional governance** — Spec-Kit's core strength. Directly maps to Forge's constitution.
 - **Template-driven behavior** — Forge uses templates similarly, just in YAML where machine-readable.
-- **Structured specs** — Maps to Forge's requirements.yml with Given/When/Then.
+- **Structured specs** — Maps to Forge's `requirements/m{N}.yml` with Given/When/Then.
 - **`[NEEDS CLARIFICATION]` markers** — Identical concept in Forge.
 
 ## What's New (Not in Spec-Kit)
@@ -44,7 +44,7 @@ AGENTS.md                          # Agent definitions
 ## Absorption Checklist
 
 - [ ] Spec-driven governance rules extracted and mapped to constitution articles
-- [ ] Project specs converted to project.yml and requirements.yml
+- [ ] Project specs converted to project.yml and `requirements/m1.yml`
 - [ ] Constitutional articles merged (Spec-Kit's + Forge's template)
 - [ ] Extensions evaluated for skill conversion
 - [ ] Agent definitions mapped to Forge's 5 agents

package/template/.forge/templates/requirements.yml

@@ -1,7 +1,10 @@
 # Forge Requirements Template
-# Copy to .forge/requirements.yml and customize. Keep under 50 KB.
+# Copy to .forge/requirements/m{N}.yml (per-milestone) and customize. Keep each file under 50 KB.
+# FR-IDs are globally unique across all milestone files — check existing requirements/*.yml
+# for highest FR-ID and continue the sequence. Same applies to DEF-IDs and NFR-IDs.
 # Mark uncertain items with [NEEDS CLARIFICATION] — planning blocks until resolved.
 
+milestone: 1                         # Milestone this file belongs to (matches state/milestone-{id}.yml)
 version: "v1"                        # v1 = MVP, v2 = next iteration
 
 functional:

package/template/.forge/templates/roadmap.yml

@@ -36,8 +36,8 @@ roadmap:
       estimated_hours: null
       status: pending
 
-  # Coverage check: every FR-ID in requirements.yml must appear in exactly one phase.
-  # Orphaned requirements = planning failure.
+  # Coverage check: every FR-ID across all `.forge/requirements/m{N}.yml` files for active
+  # milestones must appear in exactly one phase. Orphaned requirements = planning failure.
   coverage_verified: false
 
   # Wave analysis: phases with no dependencies can run in parallel (Wave 1).

package/template/CLAUDE.md

@@ -67,7 +67,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Artifact | Max | Reason |
 |----------|-----|--------|
 | `project.yml` | 5 KB | Forces clarity |
-| `requirements.yml` | 50 KB | Prevents scope creep |
+| `requirements/m{N}.yml` | 50 KB/file | Prevents scope creep |
 | `plan.md` | 30 KB | Keeps executor context <50% |
 | `constitution.md` | 10 KB | Gates must be scannable |
 
@@ -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.yml` — Structured requirements with `[NEEDS CLARIFICATION]` markers
+- `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.
 - `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