forge-orkes 0.49.0 → 0.53.0

package/template/.forge/migrations/0.52.0-id-reservation-milestone-refactor.md

@@ -0,0 +1,45 @@
+# Migration Guide: forge-reserve covers milestone + refactor ids; DI-NNN → counter-free files (Forge 0.52.0)
+
+Forge 0.52.0 closes the last scan-and-increment ID collisions across concurrent worktrees ([ADR-023](../../docs/decisions/ADR-023-extend-id-reservation-to-milestone-refactor-ids.md), extends [ADR-021](../../docs/decisions/ADR-021-id-reservation-ledger-git-common-dir.md)):
+
+- **`forge-reserve` gains two kinds** — `milestone` (emits `M-NN`, unpadded) and `refactor` (emits `R0NN`, no hyphen). Both scan live **and archived** locations as the cold-ledger floor, so a compacted or archived id is never reallocated. The milestone-id sites (`forge` Rollup, `discussing`, `prototyping`) and the refactor-backlog site (`reviewing`) now call the helper instead of hand-scanning `max + 1`.
+- **DI-NNN deferred-issue ids are eliminated.** Deferred issues become **counter-free per-issue files** under `.forge/deferred-issues/` named `{YYYY-MM-DD}-{milestone}-{slug}.md` — the same anti-collision pattern as `.forge/state/desire-paths/`. No shared counter means concurrent worktrees never collide.
+
+**The `forge-reserve` change is zero-touch** — it takes effect the moment the framework files sync; the next milestone/refactor allocation just works. **The deferred-issues change is backward-compatible** — the reader skills still read a legacy single-file `.forge/deferred-issues.md` when the new directory is absent, so nothing breaks before you migrate.
+
+## What changed (no action needed for the helper)
+
+- `forge-reserve <milestone|refactor> --milestone <id>` allocates through the same machine-local ledger + `reservations.yml` audit trail as the existing kinds. Id formats: `milestone` → `M-26` (hyphen, unpadded — ids are used bare); `refactor` → `R067` (no hyphen, zero-padded — matches the backlog).
+- The in-tree scan for these kinds reads archives too: `milestone` = live `state/milestone-*.yml` ∪ `.forge/archive/milestone-*/`; `refactor` = `refactor-backlog.yml` ∪ `refactor-backlog-archive.yml`.
+- `executing`/`quick-tasking` (writers) log a new per-issue file; `verifying`/`reviewing` (readers) glob `.forge/deferred-issues/*.md`, with the legacy single file as fallback.
+
+## Detection
+
+Prints `MIGRATE` only if a legacy single-file `.forge/deferred-issues.md` is present (the DI-NNN layout the new skills supersede). Silent + exit 0 otherwise — including projects that never had deferred issues.
+
+```bash
+[ -d .forge ] || exit 0                                   # not a Forge project
+[ -f .forge/deferred-issues.md ] || exit 0                # no legacy file → nothing to migrate, silent
+echo "MIGRATE — legacy .forge/deferred-issues.md present; split each issue into a counter-free file under .forge/deferred-issues/ ({date}-{milestone}-{slug}.md) and remove the old file (ADR-023). Safe to defer — the skills still read the legacy file until you do."
+exit 0
+```
+
+## Migration steps (deferred issues only)
+
+The `forge-reserve` kinds need no migration. For deferred issues, if Detection prints `MIGRATE`:
+
+1. For each entry in `.forge/deferred-issues.md` `issues:`, create `.forge/deferred-issues/{first_seen}-{milestone}-{slug}.md` by copying `.forge/templates/deferred-issue.md` and filling the frontmatter (`type`, `command`, `summary`, `first_seen`, `milestone`, `status`). `{slug}` is a short kebab of the summary. **Drop the `id: DI-NNN` field** — the filename is the id now.
+2. Delete `.forge/deferred-issues.md` once every entry has a file.
+3. Commit the split with your next state-sync.
+
+This is **safe to defer**: until you split the file, the reader skills (`verifying`, `reviewing`) still load the legacy `deferred-issues.md`, so no deferred failure is lost or silently un-tracked.
+
+## Validation
+
+```bash
+[ -x .claude/hooks/forge-reserve.sh ] && echo "OK: forge-reserve present" || echo "FAIL: helper missing"
+m=$(.claude/hooks/forge-reserve.sh milestone --milestone m-smoke) && echo "OK: milestone $m" || echo "FAIL: milestone kind"
+r=$(.claude/hooks/forge-reserve.sh refactor --milestone m-smoke) && echo "OK: refactor $r" || echo "FAIL: refactor kind"
+# revert the smoke reservations: drop the last two reservations.yml blocks + their ledger lines
+echo "validation complete"
+```

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: []

package/template/.forge/templates/deferred-issue.md

@@ -0,0 +1,22 @@
+<!--
+Deferred-issue file template (ADR-023). Copy to:
+  .forge/deferred-issues/{YYYY-MM-DD}-{milestone}-{slug}.md
+ONE file per issue — the filename slug replaces the old DI-NNN counter. Because
+each writer picks a distinct {date}-{milestone}-{slug} name, concurrent worktrees
+never touch the same file, so there is no shared counter to collide on at merge
+(the same anti-collision property as .forge/state/desire-paths/).
+
+Legacy .forge/deferred-issues.md (single file, DI-NNN entries) is still READ by the
+reader skills when this directory is absent — lazy migration, no data loss.
+
+Frontmatter below is the per-issue record. Keep it terse; this is state, not a doc.
+-->
+type: test_failure          # test_failure | lint_failure | build_failure
+command: ""                 # the command that surfaced it, e.g. "npm test"
+summary: ""                 # one line — what fails and why (feeds the verify report)
+first_seen: ""              # YYYY-MM-DD — also the filename date
+milestone: ""               # milestone id that logged it, e.g. m26
+status: pending             # pending | triaged | dismissed
+# --- set by reviewing triage (optional; omit until triaged) ---
+# triaged_at: ""            # YYYY-MM-DD when accepted into the refactor backlog
+# dismissed_reason: ""      # why it was dismissed instead of tracked