forge-orkes 0.11.0 → 0.13.0

package/package.json

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

@@ -0,0 +1,85 @@
+---
+name: deferred
+description: Read-only aggregator. Show all deferred work in this project grouped by surface (milestones, refactor backlog, phases/tasks inside active milestones). Trigger:`/forge deferred`, "show deferred", "deferred items", "what's deferred".
+model: haiku
+---
+
+# Deferred
+
+Read-only. Surface all deferred work across three storage surfaces so user need not remember where each kind lives. Never mutates state. No agents, no Skill invocations, no Write/Edit.
+
+Three surfaces:
+
+1. **Milestones** — `.forge/state/index.yml` entries with `status: deferred`. Strategic punts (whole milestone frozen).
+2. **Refactor backlog** — `.forge/refactor-backlog.yml` items with `status: deferred`. Code-quality punts.
+3. **Inside active milestones** — phase/task entries with `status: deferred` or `deferred: true` inside `.forge/state/milestone-*.yml`. Tactical punts within in-flight work.
+
+## Step 1: Read three surfaces
+
+**Surface 1 — Deferred milestones.** Read `.forge/state/index.yml`. Collect every entry under `milestones:` where `status: deferred`. Pull `id`, `name`, `lifecycle.deferred_at` (if present at top level fall back to `last_updated`), `lifecycle.deferred_reason` (may live in the milestone state file — read `.forge/state/milestone-{id}.yml → lifecycle.deferred_at / deferred_reason` for accuracy).
+
+**Surface 2 — Deferred refactor items.** Read `.forge/refactor-backlog.yml`. Collect every item with `status: deferred`. Pull `id` (e.g. R-007), `description` (first line, truncate ≤80 chars), `deferred_at`, `deferred_reason`.
+
+**Surface 3 — Deferred phases/tasks inside active milestones.** Glob `.forge/state/milestone-*.yml`. For each file:
+
+- Look up that milestone's status in `index.yml`.
+- **Only process if `status: active`.** Skip `complete` and `deferred` milestones.
+- *Why:* a deferred milestone's own `lifecycle.deferred_at` block is already counted by Surface 1. Including it here double-counts. Skipping `complete` avoids historical noise.
+- Within the file, find phase or task entries with `status: deferred` or `deferred: true`. Pull milestone id, phase/task name, `deferred_at`, `deferred_reason`.
+
+Missing source files → that section renders `(none)`. Never error.
+
+## Step 2: Normalize
+
+Each entry → tuple `{ surface, id, name, deferred_at, deferred_reason }`. Missing `deferred_at` → null. Missing `deferred_reason` → null.
+
+## Step 3: Sort
+
+Within each section, sort by `deferred_at` ascending (oldest first). Null dates sort last.
+
+## Step 4: Render
+
+Exact format:
+
+```
+Deferred work in this project:
+
+## Milestones ({count})
+- M{id} — {name} (deferred {deferred_at | "date unknown"})
+  Reason: {deferred_reason | "—"}
+
+## Refactor Backlog ({count})
+- {R-id} — {description} (deferred {deferred_at | "unknown"})
+  Reason: {deferred_reason | "—"}
+
+## Inside Active Milestones ({count})
+- M{milestone_id} → {phase or task name} (deferred {deferred_at | "unknown"})
+  Reason: {deferred_reason | "—"}
+```
+
+Section with count 0 → render header + `(none)` line beneath.
+
+## Empty state
+
+All three counts zero → print exactly:
+
+```
+No deferred work in this project.
+```
+
+Then exit.
+
+## Graceful degradation
+
+- Missing `.forge/state/index.yml` → cannot proceed. Print `No forge state found in this project.` exit.
+- Missing `.forge/refactor-backlog.yml` → Surface 2 renders `(none)`. Continue.
+- No `milestone-*.yml` matches → Surface 3 renders `(none)`. Continue.
+- Malformed YAML in any source → skip that source, render `(unreadable)` beneath header, continue others.
+
+## Boundaries
+
+- Read-only. No Write, no Edit, no Bash mutations.
+- No agent dispatch. Mechanical aggregation only.
+- No filter subcommands. Grouped-only view (locked decision).
+- No auto-close, no rot detection, no promotion. Deferred to v2.
+- Do not invoke other skills.

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/executing/SKILL.md

@@ -212,6 +212,8 @@ Do NOT list test failures here — pre-existing failures belong in deferred-issu
 3. Update `.forge/state/index.yml` — set `last_updated` timestamp
 4. All plans in phase complete → transition to `verifying`
 
+**When deferring an individual phase or task** (writing `status: deferred` or `deferred: true` to a phase/task entry inside the milestone state file — as opposed to milestone-wide defer which goes through the forge skill's lifecycle flow): write `deferred_at` (ISO date today) and `deferred_reason` (one-line) siblings. Old entries without these fields parse fine — lazy migration. These feed the `deferred` aggregator skill.
+
 ## Desire Path Signals
 
 Log to `.forge/state/index.yml → desire_paths` (global, not per-milestone):

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]?"*
@@ -59,9 +92,15 @@ 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)
+- "deferred" / "show deferred" / "deferred items" / "what's deferred" / "deferred work" → **Show Deferred**
 
 No match → fall through to Step 2B (tier detection).
 
+### Show Deferred
+
+1. Invoke `Skill(deferred)` directly.
+2. Do not enter tier detection. Do not prompt for milestone. The deferred skill is read-only and self-contained.
+
 ### Defer Operation
 
 1. Validate: milestone in `index.yml`, status not `deferred`
@@ -185,6 +224,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | quick-tasking | haiku | Speed |
 | discussing | sonnet | Conversation |
 | testing | sonnet | Code gen (author) + audit judgment (analyst) — matches executing/reviewing |
+| deferred | haiku | Read + format only |
 
 | `current.status` | Route To |
 |-------------------|----------|
@@ -199,6 +239,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | `complete` | Done. Ask what's next. |
 | `deferred` | Milestone frozen. *"Resume milestone {id}" to reactivate.* |
 | `quick-tasking` | `Skill(quick-tasking)` |
+| (keyword: `deferred` / "show deferred") | `Skill(deferred)` — read-only aggregator |
 
 ### Status Advancement Check
 

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

@@ -285,6 +285,8 @@ items:
 
 Missing? Create from `.forge/templates/refactor-backlog.yml`.
 
+**When deferring an individual refactor item** (status flipped to `deferred`, as opposed to milestone-wide defer which goes through the forge skill): write `deferred_at` (ISO date today) and `deferred_reason` (one-line) siblings to `status: deferred`. Pre-existing items without these fields parse fine — lazy migration. These feed the `deferred` aggregator skill.
+
 ### Route
 
 **HEALTHY/WARNINGS (accepted):** `current.status: complete` in milestone + index. *"Milestone [{name}] complete. {N} backlog items."* Beads: `bd complete`.
@@ -304,16 +306,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 -> 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:
 
-`forge` surfaces -> user selects -> route by effort -> `status: done` + date.
+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/templates/refactor-backlog.yml

@@ -1,6 +1,12 @@
 # Forge Refactor Backlog
 # Auto-managed by the refactoring skill. Items added after milestone audits.
 # Work items via quick-tasking (effort: quick) or Standard tier (effort: standard).
+#
+# Status vocab: pending | in_progress | done | dismissed | deferred
+# Optional fields (lazy migration — only required on entries set to status: deferred going forward):
+#   deferred_at: ISO date when status flipped to deferred
+#   deferred_reason: one-line why; revisited when status changes
+# Pre-existing items without these fields parse fine.
 
 items:
   - id: R001                             # Sequential ID: R001, R002, ...
@@ -11,6 +17,21 @@ items:
     description: "Brief description of the refactoring opportunity"
     effort: quick                        # quick (< 30 min, < 50 lines) | standard (needs planning)
     suggested_approach: "Concrete suggestion for how to address it"
-    status: pending                      # pending | in_progress | done | dismissed
+    status: pending                      # pending | in_progress | done | dismissed | deferred
     added: "2026-01-01"                  # ISO 8601 date when added
     completed: null                      # ISO 8601 date when done, null otherwise
+
+  # Example of a deferred item — note the two optional sibling fields:
+  - id: R002
+    milestone: 1
+    category: abstraction
+    file: "src/legacy.ts"
+    lines: "1-200"
+    description: "Extract module — blocked on upstream API change"
+    effort: standard
+    suggested_approach: "Wait for v2 API, then extract"
+    status: deferred
+    deferred_at: "2026-05-29"            # ISO date when status flipped to deferred
+    deferred_reason: "Blocked on upstream v2 API; revisit Q3"
+    added: "2026-01-15"
+    completed: null

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
@@ -49,8 +50,23 @@ deviations:                            # Tracked deviations during execution
 
 # Lifecycle — events separate from workflow position (current:).
 # current.status stays frozen when deferred — it IS the resume point.
+# This block handles MILESTONE-LEVEL deferral (whole milestone frozen).
 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
+
+# Phase/task-level deferral (separate scope from milestone-level lifecycle above):
+# When marking an individual phase or task deferred INSIDE an active milestone,
+# add deferred_at + deferred_reason adjacent to that entry's status field.
+# Fields are OPTIONAL (lazy migration — old entries lacking them parse fine).
+# These feed the `deferred` aggregator skill.
+#
+# Example (this template doesn't model concrete phases, but when a skill
+# writes such an entry, follow this shape):
+#   phases:
+#     - id: 3
+#       status: deferred
+#       deferred_at: "2026-05-29"
+#       deferred_reason: "Blocked on upstream API; revisit when X ships"