forge-orkes 0.49.0 → 0.50.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.49.0",
+  "version": "0.50.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/chief-of-staff/SKILL.md

@@ -200,7 +200,11 @@ Resume:
 1. Run the Stream Rollup, then load the stream file and brief.
 2. Surface status, blockers, owned surfaces, shared surfaces, and next action.
 3. Set the **stream file's** `status` to `active`, then regenerate `active.yml`.
-4. Run conflict detection before continuing.
+4. **Relocate into the stream worktree (Native Worktree Entry).** When the resumed stream's file records a `runtime.worktree`, apply the canonical Native Worktree Entry contract (identical to the forge ownership-gate option 1):
+   - **If the `EnterWorktree` tool is available**, call `EnterWorktree({path: {runtime.worktree}})` to relocate this session into the stream worktree **in place**, then log `Relocated into worktree {runtime.worktree} ({runtime.branch})` (independent of any prompt, so the cwd move is visible) and continue the resume from inside the worktree.
+   - **If `EnterWorktree` is unavailable** (older Claude Code CLI, or a non-Claude-Code adapter), fall back to printing the `cd {path}` instruction (here `cd {runtime.worktree}`) — today's implicit behavior made explicit.
+   - Streams with no `runtime.worktree` resume unchanged — no relocation attempted. Exit is always `ExitWorktree({action: "keep"})`; the Chief never lets the native tool remove a worktree (teardown/merge stays the Chief's existing flow).
+5. Run conflict detection before continuing.
 
 ## Delegate Flow
 

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

@@ -152,7 +152,10 @@ The gate (below) and this finalize path are mutually exclusive on `current.statu
 
 Present the four resolutions and wait for an explicit choice:
 
-1. **Enter the worktree** *(recommended)* — print the exact command (`cd {worktree_path}` then `/forge`); re-running there anchors to this milestone and writes land in the owner. This session does nothing further to the milestone.
+1. **Enter the worktree** *(recommended)* — relocate this session into the worktree **in place** (the operator no longer has to `cd` + re-run). This is the canonical **Native Worktree Entry** contract, reused verbatim at the `chief-of-staff` resume and `orchestrating` hand-back touch points:
+   - **If the `EnterWorktree` tool is available**, call `EnterWorktree({path: {worktree_path}})` — always `{path}` into the recorded `lifecycle.worktree_path`, never `{name}` (Forge owns worktree creation; `{name}` would spawn a new one on the wrong branch convention). Then log one line — `Relocated into worktree {worktree_path} ({branch})` — **independent of any confirmation prompt**, so the cwd move is always visible in the transcript. Continue routing to the requested skill from inside the worktree: writes now land in the owner, and the ownership gate is satisfied because this session **is** the owner.
+   - **If `EnterWorktree` is unavailable** (older Claude Code CLI, or a non-Claude-Code adapter), fall back to today's behavior: print the exact command (`cd {worktree_path}` then `/forge`); re-running there anchors to this milestone and writes land in the owner. This session does nothing further to the milestone.
+   - Exit is always `ExitWorktree({action: "keep"})` — Forge never lets the native tool **remove** a worktree; teardown stays option 3 / `git worktree remove`.
 2. **Sync, then continue in the worktree** — bring main's commits in (`git -C {worktree_path} rebase main`, or merge), then work from the worktree. Use when main has changes the worktree needs first.
 3. **Retire the worktree** — only if it is dead/superseded. Close the stream, `git worktree remove {worktree_path}`, and clear `lifecycle.worktree_*` on the milestone — which ends its ownership so main may write. **Confirm before removing; never auto-remove a worktree.**
 4. **Recorded override** — deliberately write from main anyway. Write `lifecycle.ownership_override: {at: {ISO}, from: main, reason: "{operator's reason}"}` into `milestone-{id}.yml`, echo it in the boot line, and carry it into the next `reviewing` report. This is the **only** way past the block and it is **never silent**. (An override is scoped to this milestone; clear it once the worktree is retired or synced.)

package/template/.forge/migrations/0.50.1-template-releases-scrub.md

@@ -0,0 +1,91 @@
+# Migration Guide: Template-Seeded Release Registry Scrub (Forge 0.50.1)
+
+Applies to projects whose fresh install ran with forge-orkes 0.32.0–0.50.0. Those
+package versions shipped `template/.forge/releases.yml` containing the forge dev
+repo's own release history (13–19 entries, versions 0.20.0–0.37.0) instead of an
+empty scaffold, so `npx forge-orkes` seeded every new project's Version
+Reservation Registry with foreign entries. The registry's `max()` rule then
+resolves against forge's history — a fresh 0.1.0 project reserving its first
+version gets 0.38.0. From 0.50.1 the template ships an empty scaffold
+(`releases: []`) and the release script refuses to ship a template with live
+registry entries; this guide cleans installs that were already seeded.
+
+`reservations.yml` (the ID-reservation sibling) was audited for the same
+pattern: its template copy has been an empty scaffold since it was introduced —
+no migration needed there.
+
+## Prerequisites
+
+1. On the new version's framework files (run `npx forge-orkes upgrade` first).
+2. Working tree clean or changes committed — the migration rewrites
+   `.forge/releases.yml`.
+
+## Detection
+
+Prints `MIGRATE` when `.forge/releases.yml` carries the template-seeded foreign
+entries; silent + exit 0 otherwise.
+
+```bash
+# Fingerprint two forge-dev entries every seeded variant (0.32.0–0.50.0)
+# contains; either match → the registry was template-seeded at install.
+# The forge dev repo itself legitimately holds these entries — skip it.
+F=.forge/releases.yml
+[ -f "$F" ] || exit 0
+[ -d packages/create-forge/template ] && exit 0
+if grep -qF 'CLAUDE.md @import extraction (framework prose' "$F" \
+   || grep -qF 'Nested phase layout (phases/milestone-{id}/{phase}-{name}/)' "$F"; then
+  echo "MIGRATE — .forge/releases.yml was seeded with the forge dev repo's release history at install; scrub the foreign entries"
+fi
+```
+
+## Migration steps
+
+The migration is NEVER auto-applied. In Claude Code it runs via the
+`quick-tasking` skill, which the `upgrading` Step-7 prompt hands this guide to
+on "yes". Step 3 is potentially lossy — confirm with the user before renumbering
+anything.
+
+### 1. Separate foreign entries from the project's own
+
+An entry belongs to THIS project iff its `milestone:` matches a milestone that
+exists here — in `.forge/state/milestone-*.yml`, `.forge/roadmap.yml`, or
+`.forge/archive/milestone-*/`. Everything else is foreign: the seeded block is
+contiguous, sits at the top of the `releases:` list, spans versions
+0.20.0–0.37.0, and its summaries describe forge framework features (streams,
+worktree gates, CLAUDE.md @import extraction, …) rather than anything this
+project built. Entries the project itself appended (if any) follow the seeded
+block.
+
+### 2. Rebuild the registry
+
+Keep the header comment block. Delete the foreign entries. Keep the project's
+own entries in their original order. If no own entries remain, end the file
+with `releases: []`.
+
+### 3. Check the project's own entries for version skew (confirm with user)
+
+Any entry the project reserved while the foreign block was present took
+`max()` off forge's history — e.g. a project actually at 0.3.0 reserving
+"0.38.0". For each such entry, ask the operator:
+
+- **Not yet published or tagged anywhere** → renumber the entry (and the
+  project's `package.json` or equivalent version file) to continue the
+  project's true version line.
+- **Already published/tagged** → keep the inflated number for continuity and
+  note the skew in a comment beside the entry.
+
+Never renumber without explicit confirmation.
+
+### 4. Commit
+
+One scoped commit, e.g.
+`fix(forge): scrub template-seeded entries from releases.yml (0.50.1 migration)`.
+
+## Validation
+
+- `grep -F 'CLAUDE.md @import extraction' .forge/releases.yml` → no matches.
+- Every remaining `milestone:` in `.forge/releases.yml` names a milestone that
+  exists in this project's state, roadmap, or archive.
+- The highest `version:` left in the registry (if any) is consistent with the
+  project's actual version in `package.json` (or equivalent).
+- Re-running the Detection block prints nothing and exits 0.

package/template/.forge/releases.yml

@@ -20,110 +20,17 @@
 # editing package.json. If two sessions reserve near-simultaneously, the second
 # push rebases onto the first (append-only → no conflict) and must re-read max()
 # and take the next number.
+#
+# LAZY MIGRATION: this file starts empty. The first milestone that bumps this
+# project's version appends the first entry; while empty, max() falls back to
+# the version already recorded in the project itself (package.json or
+# equivalent). Entries belong to THIS project's milestones only.
+#
+#   releases:
+#     - milestone: 3
+#       version: "0.4.0"
+#       bump: minor
+#       reserved_at: "2026-07-01"
+#       summary: "User-facing summary of what this release ships"
 
-releases:
-  - milestone: 12
-    version: "0.21.0"
-    bump: minor
-    reserved_at: "2026-06-12"
-    summary: "CLAUDE.md @import extraction (framework prose → .forge/FORGE.md)"
-  - milestone: 13
-    version: "0.20.0"
-    bump: minor
-    reserved_at: "2026-06-12"
-    summary: "Nested phase layout (phases/milestone-{id}/{phase}-{name}/)"
-  - milestone: 14
-    version: "0.22.0"
-    bump: minor
-    reserved_at: "2026-06-13"
-    summary: "Refactor-backlog compaction migration + lifecycle (archive terminal items, size gate, status-vocab enforcement)"
-  - milestone: 10
-    version: "0.23.0"
-    bump: minor
-    reserved_at: "2026-06-14"
-    summary: "M10 auto-routing — forge routes Standard/Full through orchestrating when installed (install = consent); orchestration.auto opt-out"
-  - milestone: 15
-    version: "0.24.0"
-    bump: minor
-    reserved_at: "2026-06-14"
-    summary: "Disconfirm-before-commit rigor: debugging Confirmation Gate (blind-spot check), architecting Platform & Goal Validation + option-space framing, discussing widen-before-narrowing, CLAUDE.md principle 8"
-  - milestone: 16
-    version: "0.25.0"
-    bump: minor
-    reserved_at: "2026-06-14"
-    summary: "Worktree branch anchor in forge milestone selection — git branch deterministically selects the milestone (exact lifecycle.worktree_branch match, or milestone-id token in branch name) before the timestamp default; deferred/complete matches surface instead of auto-resuming"
-  - milestone: 16
-    version: "0.26.0"
-    bump: minor
-    reserved_at: "2026-06-14"
-    summary: "Milestone-anchored worktree naming in orchestrating — worktree dir + branch become forge/m-{id}-{session_id} (was forge/{uuid}), adds lifecycle.worktree_anchor. Makes the 0.25.0 branch-anchor id-token fallback work for orch worktrees so a moved/stale-state worktree still resolves to its milestone off the branch name alone; uuid suffix keeps collision-resistance, forge/ prefix keeps GC sweep"
-  - milestone: 17
-    version: "0.27.0"
-    bump: minor
-    reserved_at: "2026-06-15"
-    summary: "Human Verification Gate — hard block on milestone close + orchestration teardown until an explicit human sign-off is recorded as current.human_verified in milestone state. Code-level PASS is necessary but never sufficient to close. Captured by verifying (post-verdict prompt), enforced at reviewing-complete + orchestrating Step 5.0; recorded-override (method: override) is the only bypass and is surfaced. New current.human_verified state field — lazy migration: absent = prompt on next close, already-complete milestones never re-gated."
-  - milestone: 18
-    version: "0.28.0"
-    bump: minor
-    reserved_at: "2026-06-15"
-    summary: "Configurable repo-scoped worktree root — orchestration.worktree_root defaults to ../<repo-name>-worktrees/ (was shared ../forge-worktrees/). Fixes cross-repo worktree mixing when multiple repos share a parent dir, fixes cwd-sensitive resolution (relative roots now resolve against repo root, not shell cwd), and folds a gitignore-guard for repos with fully-ignored .claude/ trees (initializing writes correct carve-out for greenfield; upgrading detects + warns for brownfield)"
-  - milestone: 19
-    version: "0.29.0"
-    bump: minor
-    reserved_at: "2026-06-15"
-    summary: "Shared-state taxonomy for multi-worktree Forge — FORGE.md State Ownership expanded to enumerate all 5 file-sharing classes (single-owner mutable, derived, append-only shared, shared mutable, stable shared) with the rule each follows. Promotes 'do not touch another worktree's state files' to explicit rule. Adds structural rule for context.md + refactor-backlog.yml (write only to your milestone block, within-block append-only). New `forge` boot worktree-liveness view (lists live Forge worktrees + their owning milestones in main). Cross-tree write warnings in discussing (context.md) + reviewing (refactor-backlog.yml). Opt-in worktree-side rebase check at boot (gated by forge.worktree_rebase_check). Triggered by the canvaz 2026-06-15 case: main-session edits to m9's context block were invisible to the m9 worktree."
-  - milestone: 20
-    version: "0.30.0"
-    bump: minor
-    reserved_at: "2026-06-16"
-    summary: "Upstream desire-path feedback channel (ADR-012) — closes the capture→act loop in Principle 7. (1) Plan-anchor re-derivation guard already landed (commit 5ddf3a1): executing re-derives plan literals against HEAD before the first task; planning makes anchors drift-resistant. (2) `scope: project|framework` field added to the desire-path schema, set at capture by verifying/executing/planning (lazy migration: absent⇒project). (3) Single review owner = forge boot — retires verifying's duplicate 'Surface Recommendations', co-locates the type→evolution suggestion table, adds a decline-ledger (declined/) so declines stop re-nagging, adds a Quick-tier review trigger in quick-tasking. (4) Tiered upstream transport for scope:framework signals: always write a portable block to state/desire-paths/upstream/; offer `gh issue create` against forge.upstream_repo (default github.com/zayneupton/forge) when gh present; upgrading harvests upstream/ into {source}/docs/desire-paths-inbox/. Optional forge.upstream_repo added to project.yml. Triggered by the canvaz plan-anchor-drift signal that could only reach the framework via manual chat copy-paste."
-  - milestone: 15
-    version: "0.31.0"
-    bump: minor
-    reserved_at: "2026-06-17"
-    summary: "Data-driven migration detection — replaces hardcoded per-version detection blocks (SKILL Step 7 + bin detectLegacyLayouts) with a single loop over synced .forge/migrations/{v}-*.md guides, ranged (installed, source]. New uniform Detection-block contract: echo `MIGRATE` on stdout when the migration applies, silent/exit-0 for no-op. All 7 guides normalized to it (0.28.0 consolidated to one `## Detection`; 0.29.0 stays an explicit in-range no-op). Removes the staleness class entirely — a new guide is auto-covered the moment it ships in the template, zero per-version code, and the install-run blind spot is fixed (detection keys off freshly-synced guides + pre-bump installed version). Triggered by ptnrkit 0.19.2→0.30.0 upgrade where bin was 4 versions behind and 2 real on-disk migrations (0.20.0, 0.22.0) reported 'needs manual review: 0'."
-  - milestone: 16
-    version: "0.32.0"
-    bump: minor
-    reserved_at: "2026-06-18"
-    summary: "Project Chief / Streams orchestration — adds Project/Stream/Work Package runtime layers, Chief of Staff routing, stream/work-package templates, active context compaction, framework-wide size audit, and an idempotent migration guide. M10 is repositioned as an optional backend for worktree isolation, merge queue support, and experimental file claims."
-  - milestone: 16
-    version: "0.32.1"
-    bump: patch
-    reserved_at: "2026-06-20"
-    summary: "Chief front-door follow-up — detects projects that adopted worktree-backed streams but left legacy orchestration.auto enabled or unset, then prompts to set orchestration.auto: false so Chief/Streams is the default entry point while M10 remains explicit."
-  - milestone: 16
-    version: "0.33.0"
-    bump: minor
-    reserved_at: "2026-06-21"
-    summary: "Worktree convention promoted to base + experimental-skill drift fix + Chief registry drift check (issues #4/#5/#6). (1) FORGE.md gains a base 'Worktree Convention' (path/anchor/branch + orchestration.worktree_root resolution + lifecycle.worktree_path authority) so Chief/Streams has a fallback when a worktree was created outside orchestrating, and the convention stays upgrade-synced regardless of the experimental skill. (2) upgrading no longer blanket-skips installed experimental skills — it diffs them against experimental/*/source and offers a preview/confirm re-sync (warn at minimum), closing the silent-freeze where base migrations (e.g. 0.28.0 worktree-root) became no-ops against a frozen orchestrating skill. (3) migration-guide template gains an authoring guard: guides whose behavior lives in an experimental skill must detect the skill's content, not just the version stamp. (4) chief-of-staff gains an advisory Registry Drift Check (Show + Sync) reconciling state/index.yml active milestones against streams/active.yml."
-  - milestone: 16
-    version: "0.34.0"
-    bump: minor
-    reserved_at: "2026-06-21"
-    summary: "Live-Worktree Ownership Gate (issue #7). forge boot's worktree surfacing was advisory, so a session on main could write single-owner-mutable milestone state (milestone-{id}.yml, phases/, research/) while a live worktree owned the milestone — forking the cursor (main 'reviewing' vs worktree 'planning'). forge SKILL gains an enforced gate (1.1a): when invoked from main and the selected milestone has a live worktree, milestone-owned writes are blocked and routing stops until the operator enters the worktree, syncs it, retires it, or records an explicit lifecycle.ownership_override (the only, never-silent bypass). Shared project docs stay writable from main with a not-visible-until-sync warning. FORGE.md State Ownership promoted from advice to enforcement. Also folds in dev/template skill drift cleanup: forge/discussing/planning dev .claude/skills copies were behind the template (chief-streams + context-archive content) — brought to parity."
-  - milestone: 16
-    version: "0.35.0"
-    bump: minor
-    reserved_at: "2026-06-21"
-    summary: "Merge often and early (issue #8). Stream integration was pull-based and deferred — ready work sat on its branch until milestone end, drifting from main and staling shared surfaces. Adds the stated principle to FORGE.md Project Streams (continuous integration posture; surfacing only, never auto-merge/auto-rebase). chief-of-staff gains an advisory Merge Cadence Check (Show + Sync): ready-to-merge surfacing from active.yml status:ready + merge_queue, idle-ready nudge, sibling-rebase nudge when main advanced on a shared surface, and merge-order recommendation. forge boot gains a light ready-to-merge nudge pointing to chief-of-staff. All advisory — never blocks, never merges, never rebases."
-  - milestone: 16
-    version: "0.36.0"
-    bump: minor
-    reserved_at: "2026-06-21"
-    summary: "Stream Integration Checkpoints — event-driven continuous integration, the producer/flag/consumer follow-up to #8's polling-based cadence check. (1) planning marks integration_checkpoint phases in plan frontmatter (advisory; default = last phase + depended-on phases; the mark is the opt-in so unmarked/existing work is unaffected). (2) Producer: verifying, on a PASSED + human-verified checkpoint phase in a worktree, fast-forward-only publishes to main (git push origin HEAD:main — git rejects non-ff, which is the safety; diverged main is surfaced, never forced) and sets an integration flag in .git/forge/integration-pending (git common dir, shared across a machine's worktrees). (3) Consumer: forge boot in a worktree reads the flag cheaply — set + no divergence → auto git merge --ff-only main (conflict-free); diverged → surface a rebase prompt; not set → skip (no fetch, no scan). Supersedes the 0.35.0 forge-boot polling pointer with event-driven detection. Cross-machine falls back to opt-in worktree_rebase_check. Never force-pushes, auto-resolves a conflict, or auto-rebases."
-  - milestone: 16
-    version: "0.37.0"
-    bump: minor
-    reserved_at: "2026-06-22"
-    summary: "Derived stream registry / Stream Rollup (ADR-015) — the durable structural fix for issue #4's registry drift, superseding the 0.33.0 advisory Registry Drift Check. streams/active.yml becomes a DERIVED projection (like state/index.yml), never hand-edited, regenerated by a deterministic join-rollup over two single-sourced inputs: per-stream files streams/{stream}.yml (coordination lifecycle + ownership/runtime/merge/blockers) and active milestone files (workflow phase). Resolves the not-1:1 milestone↔stream relationship by keeping workflow phase and coordination status as orthogonal dimensions side by side in each derived row (phase from milestone, coordination from stream file) rather than collapsing one into the other; coverage is computed (active milestone with no stream file → derived 'implicit' row) so #4's exact symptom is structurally impossible. Adds stream.milestone link field (lazy; absent ⇒ standalone). forge boot + chief-of-staff Show/Sync run the Stream Rollup; chief Start/Pause/Resume/Close/Adopt write per-stream files then regenerate. Registry Drift Check removed. active.yml put in the derived state-ownership class (ADR-011); worktrees never write it. Migration: materialize per-stream files from a hand-maintained active.yml, then regenerate."
-
-# Note on the 15 / 0.24.0 ordering: reserved as max(0.23.0)+minor. origin/main was
-# already at 0.23.0 when this shipped (M10/M12/M13/M14 all merged), so 0.24.0 is a
-# clean increment — no publish-order coordination needed. (Earlier draft of this
-# release was built on a stale 0.19.2 base before a fetch corrected it.)
-
-# Note on the 12/13 ordering: both reserved 2026-06-12. M13 holds the lower number
-# (0.20.0) and M12 the higher (0.21.0) by explicit user decision — they ship in the
-# same package release, M12 topping the version. max() here is 0.21.0, so the next
-# milestone reserves 0.22.0 (minor) regardless of which milestone id is higher.
+releases: []