forge-orkes 0.5.1 → 0.8.0

package/package.json

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

@@ -40,6 +40,33 @@ Sessions `/clear` or die mid-discussion. Previous behavior: decisions lived only
 
 Now: any `/clear` preserves everything decided so far. Worst case on interruption = last answer lost, not all answers.
 
+## Functionality Distillation
+
+Per feature, force behavioral clarity. Surface assumptions + edge cases.
+
+**L1 (Happy Path):** *"See first?" / "Sequence?" / "Confirms success?"*
+**L2 (Rules):** *"Who can?" / "Limits?" / "Trigger type?"*
+**L3 (Failures):** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
+**L4 (Side Effects):** *"Else updates?" / "Notify?" / "Undo?"*
+**L5 (Evolution):** *"v1 or final?" / "Essential vs nice-to-have?"*
+
+**Listen for:** Contradictions ("Simple" + "12 states"), Vague ("Just work" → push for example), Assumed knowledge ("Like Stripe" → confirm specifics), Energy shifts (excitement/boredom = signal).
+
+Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
+
+Example -- L3:
+```
+question: "When the enrichment API is down, what should the system do?"
+header: "Failure mode"
+options:
+  - label: "Retry with backoff (Recommended)"
+    description: "Queue retries at 1m/5m/30m. Adds complexity but self-heals."
+  - label: "Fail and alert"
+    description: "Mark failed, send alert. Simple but requires manual re-trigger."
+  - label: "Skip and continue"
+    description: "Process remaining items, revisit failures in next sweep."
+```
+
 ## Pre-Planning Discussion
 
 ### Step 0: Load Context
@@ -114,33 +141,10 @@ Open-ended via prose: *"Tried before?" / "Must-haves or must-nots?"* 1-2 at a ti
 
 ### Step 4: Functionality Distillation
 
-Per feature, force behavioral clarity. Surface assumptions + edge cases.
-
-**L1 (Happy Path):** *"See first?" / "Sequence?" / "Confirms success?"*
-**L2 (Rules):** *"Who can?" / "Limits?" / "Trigger type?"*
-**L3 (Failures):** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
-**L4 (Side Effects):** *"Else updates?" / "Notify?" / "Undo?"*
-**L5 (Evolution):** *"v1 or final?" / "Essential vs nice-to-have?"*
-
-**Listen for:** Contradictions ("Simple" + "12 states"), Vague ("Just work" → push for example), Assumed knowledge ("Like Stripe" → confirm specifics), Energy shifts (excitement/boredom = signal).
-
-Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
+Apply Functionality Distillation (above), grounded in research findings.
 
 **After each user response:** write confirmed behavioral decisions to `context.md` immediately.
 
-Example -- L3:
-```
-question: "When the enrichment API is down, what should the system do?"
-header: "Failure mode"
-options:
-  - label: "Retry with backoff (Recommended)"
-    description: "Queue retries at 1m/5m/30m. Adds complexity but self-heals."
-  - label: "Fail and alert"
-    description: "Mark failed, send alert. Simple but requires manual re-trigger."
-  - label: "Skip and continue"
-    description: "Process remaining items, revisit failures in next sweep."
-```
-
 ### Step 5: Converge
 
 Summarize decided items, then confirm:
@@ -157,8 +161,6 @@ options:
     description: "Topics we haven't covered yet."
 ```
 
-Decisions written to `.forge/context.md` at Phase Handoff (below).
-
 ## Post-Planning Discussion
 
 ### Step 1: Load Context
@@ -184,7 +186,7 @@ Translate into meaning, don't recite. Example: *"Phase 2: 3 plans, 8 tasks. Plan
 
 ### Step 4: Drill Functionality
 
-Apply **Functionality Distillation** (Step 4 above), grounded in tasks:
+Apply Functionality Distillation (above), grounded in plan tasks:
 
 - *"Notification service send failure -- retry or log?"*
 - *"Dashboard-to-API -- poll or push?"*
@@ -248,6 +250,34 @@ Re-plan? Route to `planning` with summary.
 
 After convergence:
 
+### Step A: Milestone Gate (Advisory → Tier Escalation)
+
+If no milestone exists (advisory discussion — forge routed here without tier/milestone):
+
+1. **Assess decisions.** Do locked decisions require code changes?
+   - Schema changes, field renames, new files, API changes, multi-file edits, refactoring → **yes, changes needed**
+   - Documentation only, config tweaks, "no changes needed" → **no** → end. *"No code changes needed. Discussion complete."*
+2. **Detect tier from decisions scope.**
+   - Single file, <50 lines, trivial → **Quick**
+   - Multi-file, refactor, feature, service changes → **Standard**
+   - Major architectural, multi-subsystem, multi-phase → **Full**
+3. **Create milestone.**
+   - Read `.forge/state/index.yml` (create from `.forge/templates/state/index.yml` if missing)
+   - Next ID = max existing ID + 1 (or 1 if none)
+   - Create `milestone-{id}.yml` from `.forge/templates/state/milestone.yml`:
+     - `milestone.id` = {id}, `milestone.name` = brief summary of discussion topic
+     - `current.tier` = detected tier
+     - `current.status` = `planning` (Standard) / `architecting` (Full) / `not_started` (Quick)
+     - `decisions[]` = locked decisions from `context.md`
+   - Add entry to `index.yml`: `id`, `name`, `status: active`, `last_updated: now`
+4. **Update `context.md`** — scope decisions under `### M{id} — {name} (locked {date})`
+5. **Quick tier?** → *"Scope is Quick. `/clear` then `/forge {id}` for quick-tasking."* End.
+6. Proceed to Step B with new milestone.
+
+If milestone exists → skip to Step B.
+
+### Step B: Standard Handoff
+
 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`
@@ -255,6 +285,4 @@ After convergence:
    - 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:**
-
-*"Decisions written to `.forge/context.md`. State updated. `/clear` then `/forge` to continue with {planning/architecting}."*
+3. **Recommend clear:** *"State written. `/clear` then `/forge` for {planning/architecting}."*

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

@@ -22,9 +22,9 @@ Check state files:
    - Match IDs (exact) or names (case-insensitive substring)
    - Found → auto-select: *"Resuming {id}: [{name}] -- {current.status}, {overall_percent}%"*
    - No match → *"No match for '{arg}'. Active:"*
-3. **Multiple (no arg):** Show all + status + `last_updated`. Default recent. *"{N} active. Most recent: [{name}] ({current.status}, {date}). This one, or switch?"*
+3. **Multiple (no arg):** Show active + not_started milestones with status + `last_updated`. Default most recent. After main list, show **Deferred:** section (id, name, frozen status `was: {current.status}`, defer date, reason). *"{N} active. Most recent: [{name}] ({current.status}, {date}). This one, or switch?"*
 4. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {overall_percent}%"*
-5. **None:** Init or create.
+5. **None active:** If deferred exist, mention them: *"No active milestones. {N} deferred — 'resume milestone {id}' to reactivate."* Else → init or create.
 6. Load `milestone-{id}.yml`
 7. **Route on `current.status`, NOT `overall_percent`.** Complete only at `complete`. 100% tasks ≠ done -- verifying + reviewing must run.
 8. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `overall_percent`. **No menus.** Position → action → invoke.
@@ -43,6 +43,60 @@ Check `desire_paths` 3+ occurrences:
 
 No `project.yml` + Standard/Full → **Step 2A**. State exists → **Step 2B**.
 
+## Step 1.5: Lifecycle Operations
+
+Before tier detection, check if user request matches lifecycle patterns:
+- "defer milestone {id}" / "defer {id}" / "pause milestone {id}" → **Defer**
+- "resume milestone {id}" / "undefer {id}" / "reactivate milestone {id}" → **Resume**
+- "delete milestone {id}" / "archive milestone {id}" / "remove milestone {id}" → **Delete** (see below)
+
+No match → fall through to Step 2B (tier detection).
+
+### Defer Operation
+
+1. Validate: milestone in `index.yml`, status not `deferred`
+2. Extract reason (text after "—"/"-" or second sentence). None → ask: *"Reason for deferring?"*
+3. Update `index.yml`: `status: deferred`, `last_updated`
+4. Update `milestone-{id}.yml`:
+   - `lifecycle.deferred_at` = ISO 8601 now
+   - `lifecycle.deferred_reason` = reason
+   - `lifecycle.status_before_defer` = copy of `current.status`
+5. Update `roadmap.yml`: all phases belonging to this milestone → `status: deferred`
+6. Confirm: *"Deferred milestone {id}: {name}. Was {status}, frozen at {current.status}. Reason: {reason}."*
+
+### Resume Operation
+
+1. Validate: milestone in `index.yml`, status is `deferred`
+2. Update `index.yml`: `status: active`, `last_updated`
+3. Update `milestone-{id}.yml`: `lifecycle.resumed_at` = ISO 8601 now
+4. Confirm + route: *"Resumed milestone {id}: {name}. Picking up at {current.status}."*
+5. Fall through to normal routing (Step 3) — `current.status` already frozen at correct position
+
+### Delete (Archive) Operation
+
+1. Validate: milestone in `index.yml` (any status — active, deferred, complete, not_started)
+2. Build manifest — scan for associated files:
+   - `.forge/state/milestone-{id}.yml`
+   - `.forge/phases/m{id}-*/` (glob all phase dirs)
+   - `.forge/research/milestone-{id}.md` (if exists)
+   - `.forge/audits/milestone-{id}-*` (if exists)
+   - Note: `.forge/context.md` is shared — do NOT archive or modify. M{id} decisions stay as history.
+3. Show manifest + confirm:
+   *"Archiving milestone {id}: {name}\n  - {list files}\n  → .forge/archive/milestone-{id}/\n\nProceed?"*
+4. On confirm:
+   a. Create `.forge/archive/milestone-{id}/`
+   b. Copy `milestone-{id}.yml` → archive as `state.yml`
+   c. Copy phase dirs → archive `phases/`
+   d. Copy research file → archive `research.md` (if exists)
+   e. Copy audit files → archive `audits/` (if exists)
+   f. Remove originals after successful copy
+   g. Remove milestone entry from `index.yml`
+   h. Remove milestone + its phases from `roadmap.yml`
+   i. Update `index.yml` `last_updated`
+5. Confirm: *"Archived milestone {id}: {name} → .forge/archive/milestone-{id}/. Removed from active state."*
+
+**Safety:** Copy-then-delete, not move. If copy fails, originals intact.
+
 ### Parent Session Model Advisory
 
 Check `models.parent_session` from `project.yml`. **Always display:** *"Session model: {current}. Project recommends: {parent_session}."*
@@ -71,6 +125,12 @@ ANY: new project, major arch change, multi-phase, multi-subsystem, days of work,
 ### Direct Utility
 "upgrade"/"update forge"/"sync forge" → `upgrading` (bypasses tiers)
 
+### Advisory (Tier Deferred)
+ANY: "review"/"advise"/"assess"/"evaluate" + specific system/component/feature, scope unclear, "what do you think about"
+→ No `project.yml` → init first. Then `discussing` (no milestone — tier detected post-discussion).
+
+Can't know upfront if "review X" → "it's fine" or "restructure 6 files." Discussion determines scope. Discussing skill detects tier at convergence, creates milestone if code changes needed.
+
 ### User Override
 "Use Quick/Standard/Full tier" → honor.
 
@@ -119,6 +179,8 @@ Subagents via `Agent` tool → same precedence, enforced via `model` param.
 | discussing | sonnet | Conversation |
 | testing | sonnet | Code gen (author) + audit judgment (analyst) — matches executing/reviewing |
 
+*Model enforced only for Agent-dispatched skills (verifying, quick-tasking). Skill-routed phases are advisory — use `/model` to switch.*
+
 | `current.status` | Route To | Method |
 |-------------------|----------|--------|
 | `not_started` | Detect tier, start | — |
@@ -130,51 +192,83 @@ Subagents via `Agent` tool → same precedence, enforced via `model` param.
 | `verifying` | Agent-dispatched → reviewing | **Agent** |
 | `reviewing` | `Skill(reviewing)` → complete | Skill |
 | `complete` | Done. Ask what's next. | — |
+| `deferred` | Milestone frozen. *"Resume milestone {id}" to reactivate.* | — |
+| `quick-tasking` | Agent-dispatched (Quick tier / refactor-backlog) | **Agent** |
+
+**Phases marked Agent MUST use `Agent()` with `model` param. Never `Skill()` — model enforcement only works through `Agent()`.**
 
 ### Agent-Dispatched Phases
 
-Some phases run as spawned agents instead of in-session skills. This **enforces model routing** — the `Agent` tool's `model` param guarantees the correct model runs.
+Phases marked **Agent** run as spawned agents to enforce model routing. `Agent` tool's `model` param = only enforcement point.
 
-#### Verifying (Agent-Dispatched)
+**Skill contract:** Each dispatched skill carries a guard header — if parent loads via Skill(), guard says STOP.
 
-When `current.status == verifying`, do NOT call `Skill(verifying)`. Instead:
+**Parent protocol:**
+1. Resolve model: `models.skills.{skill}` → `models.default` → parent
+2. On return: read updated state, display *"Result: {outcome}. Model: {model} (enforced)."*, route next
 
-1. Read milestone state: `.forge/state/milestone-{id}.yml`
-2. Identify the plan path from state: `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`
-3. Resolve model: `models.skills.verifying` → `models.default` → parent
-4. Spawn agent:
+**Agent prompt requirements:** `touch .forge/.active-skill` (pre-commit guard) + "Report resolved model in summary."
+
+#### Verifying
+
+When `current.status == verifying`:
+
+1. Read milestone state → identify plan path
+2. Spawn:
 
 ```
 Agent(
-  model: "{resolved_model}",
+  model: "{model}",
   description: "Verify milestone {id}: {name}",
-  prompt: "You are a verifier agent. Your job: prove completed work delivers what was promised.
+  prompt: "You are a verifier agent. Prove completed work delivers what was promised.
 
-FIRST: Run `touch .forge/.active-skill` to satisfy the pre-commit hook guard. Without this, all Write/Edit operations will be blocked.
+FIRST: Run `touch .forge/.active-skill`
 
-Read these files for context:
-- .claude/skills/verifying/SKILL.md — your full process instructions
-- .claude/agents/verifier.md — your role, tools, output format
+Read:
+- .claude/skills/verifying/SKILL.md — process instructions
+- .claude/agents/verifier.md — role, tools, output format
 - .forge/state/milestone-{id}.yml — current state
-- .forge/phases/{phase_path}/plan-{NN}.md — must_haves to verify
-- .forge/project.yml — tech stack, verification commands
+- .forge/phases/{phase_path}/plan-{NN}.md — must_haves
+- .forge/project.yml — stack, verification commands
 - .forge/context.md — locked decisions
-- .forge/requirements.yml — requirement IDs for coverage
+- .forge/requirements.yml — requirement coverage
 
-Follow the 3-level verification process in verifying/SKILL.md exactly.
-Write verification results to the plan directory.
-Update milestone state: set current.status to 'reviewing' if PASSED, keep 'verifying' if GAPS FOUND.
-End with a verification summary for the parent session."
+Follow verifying/SKILL.md 3-level process exactly.
+Write results to plan directory.
+Update state: 'reviewing' if PASSED, keep 'verifying' if GAPS.
+Report resolved model in summary."
 )
 ```
 
-5. On agent return:
-   - Read updated `milestone-{id}.yml`
-   - Display result: *"Verification {PASSED|GAPS FOUND}. Model: {model} (enforced)."*
-   - PASSED → route to reviewing
-   - GAPS FOUND → route back to planning (gap-closure mode)
+3. On return: PASSED → reviewing. GAPS → planning (gap-closure).
+
+#### Quick-Tasking
+
+Quick-tasking runs as Agent from Quick tier or refactor-backlog. Parent constructs prompt based on milestone context:
+
+```
+Agent(
+  model: "{model}",
+  description: "Quick fix: {description}",
+  prompt: "You are a quick-tasking agent. Small, scoped fix.
+
+FIRST: Run `touch .forge/.active-skill`
+
+Read:
+- .claude/skills/quick-tasking/SKILL.md — workflow
+- .forge/project.yml — stack, verification commands
+[with milestone: + .forge/state/milestone-{id}.yml, .forge/context.md]
+
+Task: {description}
+
+Follow quick-tasking/SKILL.md workflow.
+[with milestone: After commit, update milestone-{id}.yml (increment progress, log deviations).]
+[without milestone: No state management.]
+Report resolved model in summary."
+)
+```
 
-- Skip before `current.status`; resume current.
+On return: display result + model. With milestone → read updated state.
 
 ### Status Advancement Check
 
@@ -233,8 +327,9 @@ After clear, skills load from disk via "Read Context"/"Pre-Execution Checklist".
 ## State Transitions
 
 ```
-Standard: not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
-Full:     not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
+Standard:  not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
+Full:      not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
+Advisory:  [init?] → discussing → [tier gate] → planning → executing → verifying → reviewing → complete
 
 Branches (any tier, on-demand): debugging (stuck) · designing (UI) · securing (auth/data/API) · testing (e2e/integration/flake)
 Phase boundaries: `[clear]` recommended between phases to reset context.

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

@@ -312,7 +312,7 @@ User selects per stack.
      milestones:
        - id: 1
          name: "{project name}"
-         status: active
+         status: active                # not_started | active | deferred | complete
          last_updated: "{date}"
      ```
    - `.forge/state/milestone-1.yml`:

package/template/.claude/skills/quick-tasking/SKILL.md

@@ -3,6 +3,8 @@ name: quick-tasking
 description: "Small, scoped changes: typo fixes, config updates, minor bugs, dependency bumps, doc tweaks. Under 50 lines, 1-2 files, no architectural decisions. Quick tier — skip ceremony."
 ---
 
+> **AGENT-DISPATCHED:** If reading in parent session, STOP — use Agent() via forge/SKILL.md § Agent-Dispatched Phases.
+
 # Quick-Tasking
 
 Small change? Skip ceremony. Do it right, do it fast.
@@ -60,6 +62,27 @@ Example: `fix(docs): correct typo in API reference`
 ### 6. Done
 No verification ceremony. Move on.
 
+## Milestone Context
+
+Quick-tasking handles two contexts. Existing workflow steps (Identify → Validate → Execute → Test → Commit → Done) apply in both — this section adds state management around them.
+
+### With Milestone
+
+Invoked via forge routing (mid-workflow or refactor-backlog item with milestone context):
+
+1. Read `.forge/state/milestone-{id}.yml` for current position
+2. Follow standard workflow (above)
+3. After commit: update milestone state — increment `progress.overall_percent`, log deviations if any Rule 1-3 applied
+4. Report: fix description, files changed, milestone progress update
+
+### Without Milestone
+
+Standalone quick fix (no forge state exists or no milestone context provided):
+
+1. Follow standard workflow (above)
+2. No state reads or writes
+3. Report: fix description, files changed
+
 ## Scope Creep Detection
 
 During execution, if you discover:

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

@@ -3,6 +3,8 @@ name: verifying
 description: "Prove completed work delivers what was promised. Goal-backward verification with 3 levels: Observable Truths, Artifacts, and Key Links. Task completion ≠ goal achievement."
 ---
 
+> **AGENT-DISPATCHED:** If reading in parent session, STOP — use Agent() via forge/SKILL.md § Agent-Dispatched Phases.
+
 # Verifying
 
 Prove completed work delivers what was promised. Task completion ≠ goal achievement.
@@ -194,8 +196,6 @@ After PASSED verdict:
 
 1. **Persist** — Confirm verification results documented, desire paths logged to `.forge/state/index.yml`
 2. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
-3. **Recommend context clear:**
-
-*"Verification passed. State written. `/clear` then `/forge` to continue with reviewing."*
+3. **Recommend clear:** *"State written. `/clear` then `/forge` for reviewing."*
 
 If GAPS found, route back to planning in gap-closure mode. Context clear applies after re-verified PASSED verdict.

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

@@ -4,13 +4,16 @@
 
 roadmap:
   # Milestones group phases into concurrent work streams.
-  # Phases keep global IDs. Milestones reference them.
+  # Each milestone contains its own phases numbered sequentially (1, 2, 3...).
   # Different milestones can be worked on in parallel across sessions.
   milestones:
     - id: 1
       name: ""                         # e.g., "MVP", "Admin Dashboard"
-      phases: []                       # List of phase IDs belonging to this milestone
+      phases: []                       # List of phase numbers belonging to this milestone
 
+  # Phases are scoped within milestones. Each phase has a local number (1, 2, 3...)
+  # within its milestone. Directory naming: .forge/phases/m{milestone_id}-{phase_num}-{name}/
+  # Example: m1-1-foundation/, m1-2-auth/, m2-1-dashboard/
   phases:
     - id: 1
       name: ""                       # e.g., "Foundation & Architecture"
@@ -21,7 +24,7 @@ roadmap:
         - ""                         # e.g., "User can see the landing page"
         - ""                         # e.g., "API returns valid JSON for /users"
       estimated_hours: null
-      status: pending                # pending | researching | planning | executing | verifying | complete
+      status: pending                # pending | researching | planning | executing | verifying | deferred | complete
 
     - id: 2
       name: ""

package/template/.forge/templates/state/index.yml

@@ -5,7 +5,7 @@
 milestones:                            # Active milestones and their high-level status
   - id: 1
     name: ""                           # Human-readable milestone name from roadmap
-    status: not_started                # not_started | active | complete
+    status: not_started                # not_started | active | deferred | complete
     last_updated: null                 # ISO 8601 timestamp — used for resume default selection
 
 metrics:

package/template/.forge/templates/state/milestone.yml

@@ -46,3 +46,11 @@ deviations:                            # Tracked deviations during execution
     plan: null
     task: null
     resolution: ""
+
+# Lifecycle — events separate from workflow position (current:).
+# current.status stays frozen when deferred — it IS the resume point.
+lifecycle:
+  deferred_at: null                    # ISO 8601 — when milestone was deferred
+  deferred_reason: ""                  # User-provided reason for deferring
+  status_before_defer: null            # Workflow status when deferred (mirrors frozen current.status)
+  resumed_at: null                     # ISO 8601 — when milestone was resumed

package/template/CLAUDE.md

@@ -36,6 +36,10 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 **Flow:** `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `reviewing` → done
 **Optional:** `designing` (UI), `securing` (auth/data/API), `debugging` (stuck), `testing` (e2e/integration/flake)
 
+### Advisory (tier deferred)
+**Triggers:** "review"/"advise"/"assess"/"evaluate" + specific system/component, scope unclear upfront
+**Flow:** `discussing` → [tier gate detects scope] → `planning` → `executing` → `verifying` → `reviewing` → done
+
 ## Skill Routing
 
 | Need to... | Skill | Tier |
@@ -130,8 +134,10 @@ State lives in `.forge/`:
 - `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
 - `phases/m{M}-{N}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter
 - `refactor-backlog.yml` — Refactoring catalog, worked via quick-tasking
+- `archive/milestone-{id}/` — Archived milestone artifacts (archive-delete)
 
-**Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions.
+**Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
+`index.yml status` gates routing: `not_started | active | deferred | complete`.
 **Format**: YAML for machine state, Markdown for human content.
 **`current.status` is authoritative.** Complete only at `current.status == complete`. 100% tasks ≠ done — still needs verifying + reviewing.