forge-orkes 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.11.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/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/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