forge-orkes 0.28.0 → 0.29.0

package/package.json

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

@@ -42,13 +42,23 @@ Never accumulate decisions in working memory. Never batch writes to convergence.
 
 ### Write Protocol
 
+`context.md` is **shared mutable** state per FORGE.md State Ownership — writes follow two structural rules:
+- **Scope to your milestone's block.** Different milestone blocks → git merges cleanly across worktrees.
+- **Append-only within a block.** When superseding an older decision, *strike through* (`~~old decision~~`) and append the new line below — never rewrite in place. Same-line concurrent edits become impossible by construction; reading the history of a decision becomes possible by inspection.
+
 **On first decision of the session:**
 - Check if `.forge/context.md` exists. If not → create it from `.forge/templates/context.md`
 - Add a milestone heading inside `## Locked Decisions`: `### M{id} — {name} (drafting)` (use "M?" if no milestone yet)
+- **Cross-tree liveness check (informational).** If editing an existing block for milestone `{id}`, run `git worktree list --porcelain | awk '/^branch / && $2 ~ /refs\/heads\/forge\/m-'"$id"'(-|$)/ {print}'`. Any hit means m{id} is **live in another worktree** — surface one line: *"m{id} is live in worktree at `{path}`. Edits land cleanly on main but won't be visible to that worktree until it rebases or pulls."* Proceed with the write — main is often the canonical author of `context.md`, this is a heads-up, not a block.
 
 **On each confirmed decision:**
 - Append under the milestone heading: `- **[Topic]**: [Decision]. Reason: [Why]`
 
+**On superseding a prior decision (in your own milestone's block):**
+- Find the original line. Wrap it in `~~ ~~` (markdown strikethrough). DO NOT delete it.
+- Append the new decision on a new line below it: `- **[Topic]**: [Decision]. Reason: [Why]. Supersedes ~~prior on {date}~~.`
+- Why: shared-mutable append-only rule (FORGE.md State Ownership). Decisions stay readable as history; concurrent writes from another worktree on a different bullet can't conflict with this one.
+
 **On deferred ideas** (user says "not now" / "later" / "skip"):
 - Append to `## Deferred Ideas` immediately: `- [Idea] — Deferred because: [reason]`
 

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

@@ -9,6 +9,33 @@ Entry point. Detect tier, route skills, manage transitions. New projects → ini
 
 ## Step 1: Read State
 
+**Preflight (multi-tree visibility) — run before everything in this section.**
+
+The presence of live Forge worktrees changes the meaning of "which milestone am I editing" — the operator needs to see the picture before any state edit. Cheap to compute, free if there's nothing to show.
+
+```bash
+# This session's checkout — main or a worktree? --git-dir == --git-common-dir → main; differ → linked worktree.
+this_dir=$(git rev-parse --git-dir 2>/dev/null) || exit 0
+common_dir=$(git rev-parse --git-common-dir)
+in_main_checkout=$([ "$this_dir" = "$common_dir" ] && echo true || echo false)
+
+# Forge worktrees = branch matches forge/m-*
+git worktree list --porcelain 2>/dev/null \
+  | awk '
+      /^worktree /  { path=$2 }
+      /^branch /    { br=$2; if (br ~ /refs\/heads\/forge\/m-/) print path " " br }
+    '
+```
+
+**If `in_main_checkout: true`** AND any Forge worktrees are reported:
+- Surface them at the top of the boot output, one line each: *"m{id} is live in worktree `{path}` on branch `{branch}`. Edits to its milestone state belong there; shared-doc edits here (`context.md`, `refactor-backlog.yml`) won't be visible to it until it rebases or pulls."*
+- This is informational — `forge` continues to Rollup + selection. The operator now knows. (See FORGE.md State Ownership for the full taxonomy.)
+
+**If `in_main_checkout: false`** (this session is itself a worktree) AND `forge.worktree_rebase_check: true` in `.forge/project.yml` (default `false` — opt-in):
+- Diff `.forge/` between this worktree's `HEAD` and `origin/main` (or `main` if no remote), restricted to the **shared-mutable** + **stable-shared** files per the FORGE.md taxonomy (`context.md`, `refactor-backlog.yml`, `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `requirements/m{N}.yml`).
+- Any differ → surface: *"`{file}` has changed on main since this worktree branched. Pull just this file (`git restore --source main -- {file}`), rebase, or skip?"* — operator decides.
+- Setting absent or `false` → no-op.
+
 ### 1.0 State Rollup (index.yml is derived)
 
 `index.yml` is a **derived registry** — regenerate it from the milestone files before reading, and after any milestone CRUD (promote/defer/resume/delete). **Never hand-edit `index.yml`.**

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

@@ -312,6 +312,12 @@ Deferred issues triage: If `.forge/deferred-issues.md` has `status: pending` ite
 
 ### Backlog
 
+`refactor-backlog.yml` is **shared mutable** state per FORGE.md State Ownership — many milestones append over time. Two rules apply:
+- **Items carry `milestone:` scoping** (already enforced by the schema below) — concurrent appends from different milestones touch different items, so git merges cleanly.
+- **Existing items are append-only** in spirit: change `status:` and add `completed:`/`deferred_at:` rather than rewriting the item's body. Compaction-on-write (below) handles physical relocation of terminal items.
+
+**Cross-tree liveness check (informational).** Before writing, run `git worktree list --porcelain | awk '/^branch / && $2 ~ /refs\/heads\/forge\/m-/ {print}'`. Any non-empty output means another milestone is live in a worktree — surface one line: *"{N} other Forge milestone(s) live in worktrees ({list}). Backlog appends here land cleanly on main but won't be visible to those worktrees until they rebase."* Proceed with the write — reviewing on main is the canonical author. (Two reviewing sessions writing in parallel from different worktrees rely on the milestone-scoped append rule above, not on this check.)
+
 Read `.forge/refactor-backlog.yml`. Next ID = max + 1. Append:
 
 ```yaml

package/template/.forge/FORGE.md

@@ -162,9 +162,38 @@ State-sync commits are separate from per-task code commits (which stay atomic du
 
 ### State Ownership (multi-worktree safety)
 
-- `state/milestone-{id}.yml` is the **single source of truth**; exactly one agent owns it at a time.
+`.forge/` is **code-like**: it branches with the repo, syncs via git, atomic-commits with the work it describes. Worktrees get their own `.forge/` checkout by construction — that's not configuration, that's git. The framework's job is to specify how each *kind* of `.forge/` file behaves under that model.
+
+**Every `.forge/` artifact falls into one of five sharing classes.** The class determines the write rule across worktrees:
+
+| Class | Files | Write rule |
+|---|---|---|
+| **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md` | Exactly one writer at a time — the worktree (or main session) currently driving that milestone. **Other worktrees never touch it**, not even to read-then-write — they pull from main if they need it. |
+| **Derived** | `state/index.yml` | Never hand-edited. Regenerated by Rollup 1.0 from `milestone-*.yml`. Only the main/orchestrator session runs rollup. |
+| **Append-only shared** | `releases.yml` (version reservations), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` uses the Version Reservation Protocol (append + commit + push before depending on the slot); desire-paths use distinct filenames so two writers never touch the same file. |
+| **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` (ID space `FR-`/`DEF-`/`NFR-` is globally shared even though each milestone owns its file) | Two rules: **(a) Write only to YOUR milestone's block.** Different milestone blocks → git merges cleanly. **(b) Within a block, append-only.** Locked decisions get *struck through* (`~~old~~`) rather than rewritten in place; new sub-bullets appended below existing ones. Same-line concurrent edits become impossible by construction. |
+| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md` | Rarely changes after init. Canonical on main. Worktrees lag and pull on rebase. No special protocol — git handles it because the conflict surface is tiny. |
+
+**Cross-tree write awareness.** When a session edits a shared-mutable file's block whose milestone is **live in a different worktree** (e.g. main writes to `context.md`'s `## M9` block while m9 is running in a worktree), the edit lands cleanly on main but is **invisible to the worktree until it pulls/rebases**. This is identical to how `src/foo.ts` works under branches — there's nothing pathological about it; it's branch divergence. The framework surfaces the situation so the operator can decide:
+
+- **`forge` Step 1** in main checks `git worktree list` and surfaces live Forge worktrees at boot — *"m9 is live in worktree X at e94b6bb. Edits to m9 state belong there; shared docs edited here need a sync."*
+- **`discussing`** (before writing to `context.md`'s milestone block) and **`reviewing`** (before writing to `refactor-backlog.yml`) emit a one-line warning when the target block's milestone is live elsewhere. The warning informs, never blocks — main is often the canonical author of these files.
+- **Worktree-side rebase check** (opt-in via `forge.worktree_rebase_check: true` in `project.yml`) — when `forge` boots inside a worktree, it diffs `.forge/` between the worktree's HEAD and `main`; if shared-mutable files have changed on main, it offers `git restore --source main -- <files>` or a rebase.
+
+**Why not global `.forge/`?** A common instinct is "make `.forge/` shared so context propagates automatically." It breaks four load-bearing invariants:
+1. **Decisions are contracts** — they're versioned with the code they govern; severing them from branches breaks the contract.
+2. **State survives machine loss** — the multi-laptop pull-from-any-clone story depends on `.forge/` being in git.
+3. **History time-travel** — `git checkout` an old commit and you see the plan/decisions as they were; global state makes that impossible.
+4. **Git is the concurrency detector** — without it, two sessions writing the same field becomes silent last-write-wins.
+
+Per-worktree `.forge/` with a sharing taxonomy is the model. See [ADR-011](../docs/decisions/ADR-011-shared-state-taxonomy.md) for the longer version.
+
+### State Ownership rules (quick reference)
+
+- `state/milestone-{id}.yml` is the **single source of truth**; exactly one agent owns it at a time. **Other worktrees never write it** — promoted from advice to explicit rule, because catching yourself before the first wrong edit is the part the framework can help with.
 - Worktree / parallel agents write **only** their own milestone file and **append** desire-path files. They **never** write `index.yml`.
 - `index.yml` is **regenerated by rollup** (read every `milestone-*.yml` → rewrite the registry) by the main/orchestrator session — on `forge` resume and at `orchestrating` teardown. The rollup is deterministic + idempotent, so it **is** the reconcile step — never a hand-merge.
+- For shared-mutable files: write only your milestone's block; within a block, append-only (strike through, don't rewrite).
 - Same-milestone parallel work is out of scope, guarded by the M10 claim layer.
 
 ### Version Reservation Protocol

package/template/.forge/migrations/0.29.0-shared-state-taxonomy.md

@@ -0,0 +1,68 @@
+# Migration Guide: Shared-state taxonomy (Forge 0.29.0)
+
+Applies to any Forge project that uses git worktrees (M10 or hand-rolled). This is a **documentation + skill-behavior** change, not a state-file change — there is nothing in `.forge/` to migrate. Read this once, then the new skill behavior catches the situations.
+
+## What changed and why
+
+Forge's `State Ownership (multi-worktree safety)` section in `FORGE.md` previously documented two file classes — `state/milestone-{id}.yml` (single-owner) and `state/index.yml` (derived) — and was silent on every other file in `.forge/`. In practice three more classes exist, and the riskiest one (shared mutable — `context.md`, `refactor-backlog.yml`) had no rule.
+
+A worked example from canvaz on 2026-06-15: a main-session edit to `context.md`'s `## M9` block was invisible to the live m9 worktree, because the worktree was branched off main earlier and reads `.forge/` from its own checkout. The operator had to deduce the sync gap from first principles, and nearly committed `milestone-9.yml` edits from main on the first attempt before catching themselves.
+
+0.29.0 closes the gap with **taxonomy + visibility + structural rules**, not with a state migration. See [ADR-011](../decisions/ADR-011-shared-state-taxonomy.md) for the longer version (including why a "global `.forge/`" approach is wrong).
+
+## The 5-class taxonomy (read this once)
+
+| Class | Examples | Write rule |
+|---|---|---|
+| **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md` | One writer at a time; other worktrees **never** touch it. Explicit rule. |
+| **Derived** | `state/index.yml` | Never hand-edited; regenerated by Rollup 1.0. Only main/orchestrator runs rollup. |
+| **Append-only shared** | `releases.yml`, `state/desire-paths/*` | Many writers OK; structure prevents collision. Append + commit + push before depending on the slot. |
+| **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` | (a) Write only to YOUR milestone's block. (b) Within a block, append-only — strike through (`~~old~~`) superseded decisions instead of rewriting in place. |
+| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md` | Rarely changes after init; canonical on main; worktrees lag and pull on rebase. No protocol — git handles it. |
+
+The full canonical version lives in `FORGE.md` → `State Ownership`.
+
+## What the framework now does automatically
+
+After upgrading to 0.29.0:
+
+- **`forge` Step 1 preflight (main checkout):** before Rollup, surfaces any live Forge worktrees and their owning milestones — *"m9 is live in worktree X at e94b6bb. Edits to its milestone state belong there; shared docs edited here need a sync."* No prescription, just visibility.
+- **`discussing`** emits a one-line warning before writing to `context.md`'s milestone block if that milestone is live in another worktree.
+- **`reviewing`** emits the same warning before appending to `refactor-backlog.yml` if any milestone is live in a worktree.
+- **`discussing`** also documents the supersede protocol (strike-through old decisions, append new ones below) so concurrent edits across worktrees stay mergeable.
+
+## Optional: enable the worktree-side rebase check
+
+Opt-in; default off. When enabled, `forge` boot **inside a worktree** diffs `.forge/` against `main` and offers to pull individual shared-mutable / stable-shared files when they've moved.
+
+Add to `.forge/project.yml`:
+
+```yaml
+forge:
+  worktree_rebase_check: true
+```
+
+Trade-off: adds one git diff per `forge` boot inside worktrees. Worth it for projects that frequently update `context.md` / `constitution.md` on main while worktrees are mid-flight; overkill for projects where the main checkout is mostly read-only.
+
+## Existing decisions in context.md — do nothing
+
+The taxonomy is descriptive: every existing decision in `context.md` already fits the new rules (it lives under a milestone heading, was append-only in practice). No rewrite needed. **New** writes follow the protocol (use strike-through to supersede).
+
+If a past edit broke the rule (decision rewritten in place), don't go back and reconstruct strike-throughs — the history is in git. Just follow the rule going forward.
+
+## Detection (none needed)
+
+There's nothing to detect on disk. The framework changes are in skills and `FORGE.md`. Upgrade and you have them.
+
+## Validation
+
+After `npx forge-orkes upgrade`:
+
+- `grep "5-class\|sharing classes" .forge/FORGE.md` returns hits in the `State Ownership` section.
+- `grep "cross-tree liveness\|append-only" .claude/skills/discussing/SKILL.md` returns the Write Protocol additions.
+- `grep "worktree-liveness\|worktree_rebase_check" .claude/skills/forge/SKILL.md` returns the Step 1 preflight.
+
+Then, if you have a worktree active:
+
+- `forge` in the main checkout surfaces the live worktree at the top of its boot output.
+- Begin a discussion in main that touches a worktree-live milestone → `discussing` emits the cross-tree warning before its first write.