forge-orkes 0.74.0 → 0.75.0

package/experimental/m10/source/skills/orchestrating/SKILL.md

@@ -80,16 +80,45 @@ mkdir -p "$wt_root"
 git worktree prune
 git worktree add -b forge/${anchor} --lock --reason "forge session m-${milestone_id}" "$wt_root/${anchor}" main
 wt="$wt_root/${anchor}"
-# Submodules don't auto-populate in a new worktree — init them if present. Reuses the
+
+# --- Hydrate the worktree ---
+# A git worktree is a clean checkout of *tracked* files only. Everything required but
+# untracked — submodule working trees, gitignored config/secrets — is absent until we
+# put it there. Hydration is that ordered step; submodule init is one instance of it.
+
+# (1) Submodules don't auto-populate in a new worktree — init them if present. Reuses the
 # superproject's shared .git/modules object store (no re-clone, just a working-tree
 # checkout); ccache absorbs the subsequent rebuild cost across worktrees.
 if [ -n "$(git -C "$wt" submodule status 2>/dev/null)" ]; then
   ( cd "$wt" && git submodule update --init --recursive )
 fi
+
+# (2) Required-but-gitignored artifacts (e.g. .mcp.json — MCP config, often secret-bearing;
+# .env.local; experimental hook configs) named in orchestration.worktree_hydrate. A clean
+# checkout lacks them, and the failure is SILENT: MCP servers that never appear, an env-
+# dependent command that misbehaves. Copy each from the superproject, guarded source-exists
+# && dest-absent → never overwrites, and we NEVER `git add` a hydrated path: it stays
+# gitignored/untracked in both trees, so a secret like .mcp.json never enters git history.
+sed -n '/^orchestration:/,/^[^[:space:]#]/p' "$repo_root/.forge/project.yml" 2>/dev/null \
+  | sed -n '/^[[:space:]]*worktree_hydrate:/,/^[[:space:]]*[a-z_]*:/p' \
+  | sed -n 's/^[[:space:]]*-[[:space:]]*//p' | tr -d "\"'" \
+  | while IFS= read -r rel; do                   # line-based: a path may contain spaces; robust across sh/bash/zsh
+      [ -n "$rel" ] || continue
+      [ -e "$repo_root/$rel" ] || continue        # source-exists guard (no-op when nothing applies)
+      [ -e "$wt/$rel" ] && continue               # dest-absent guard (idempotent — never clobbers)
+      mkdir -p "$(dirname "$wt/$rel")"
+      cp -p "$repo_root/$rel" "$wt/$rel"
+    done
+
+# (3) Dependency install (node_modules etc.) is DEFERRED to the executing/verifying preflight
+# on purpose — Forge core owns no package-manager concept, and the node_modules desire path is
+# already handled there. That is where the false-green `tsc` class (a no-op tsc against a missing
+# node_modules reporting green) is closed — not here.
+
 ( cd "$wt" && git hook run pre-commit || true )
 ```
 
-Verify worktree dir exists, branch locked, and (if applicable) submodule dirs are non-empty. On failure → cleanup partial state, refuse mode.
+Verify worktree dir exists, branch locked, and (if applicable) submodule dirs are non-empty and each configured `worktree_hydrate` artifact that exists in the superproject is present in the worktree. On failure → cleanup partial state, refuse mode.
 
 `anchor` (= `m-{milestone_id}-{session_id}`) names the worktree dir **and** branch from here on; every reference below that used to be `{session_id}` is now `{anchor}`. `session_id` (the bare uuid) is retained only as the collision key + audit id in state.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.74.0",
+  "version": "0.75.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/hooks/forge-reserve.sh

@@ -249,10 +249,27 @@ compute_id() {
   # Hyphen is OPTIONAL in the token ([A-Z]+-?[0-9]+): refactor ids (R100) carry none
   # (ADR-023), so requiring a hyphen would hide them and drop the floor to 0. Split the
   # alpha prefix from the digits in awk so R does not match e.g. FR (anchor ^prefix$).
-  main_max="$(git show main:.forge/reservations.yml 2>/dev/null \
-    | grep -oE '[A-Z]+-?[0-9]+' \
-    | awk -v p="$prefix" '{ a=$0; sub(/[-0-9].*$/,"",a); d=$0; gsub(/[^0-9]/,"",d);
-                            if(a==p){ n=d+0; if(n>m)m=n } } END{print m+0}')"
+  #
+  # READ BOTH main AND origin/main (#26): in the local-main-first workflow (ADR-010 —
+  # primary checkout parked on main, all work in worktrees reaching main via PRs), local
+  # `main` routinely lags origin/main by whatever merged since the last fast-forward, so a
+  # local-only floor hands out ids origin/main already claimed — #19's collision class,
+  # relocated to the one input that still isn't machine-shared. Best-effort-fetch origin
+  # first, then take the max across whichever of {main, origin/main} resolve. Every leg
+  # degrades to nothing offline / with no remote (the same posture the rest of the script
+  # takes) — a fetch failure or a missing ref is never fatal, it just contributes 0.
+  # FORGE_RESERVE_NO_FETCH=1 skips the fetch (fixtures with a local file:// origin want the
+  # deterministic ref state they set up, not a network round-trip).
+  ref_reservations_max() {  # $1 = git ref → max reserved id for $prefix on that ref (0 if absent)
+    git show "$1:.forge/reservations.yml" 2>/dev/null \
+      | grep -oE '[A-Z]+-?[0-9]+' \
+      | awk -v p="$prefix" '{ a=$0; sub(/[-0-9].*$/,"",a); d=$0; gsub(/[^0-9]/,"",d);
+                              if(a==p){ n=d+0; if(n>m)m=n } } END{print m+0}'
+  }
+  [ "${FORGE_RESERVE_NO_FETCH:-0}" = 1 ] || git fetch --quiet origin main 2>/dev/null || true
+  main_local_max="$(ref_reservations_max main)";        [ -n "$main_local_max" ]  || main_local_max=0
+  main_origin_max="$(ref_reservations_max origin/main)"; [ -n "$main_origin_max" ] || main_origin_max=0
+  main_max="$(awk -v a="$main_local_max" -v b="$main_origin_max" 'BEGIN{print (a>b)?a:b}')"
   [ -n "$main_max" ] || main_max=0
 
   next="$(awk -v a="$ledger_max" -v b="$intree_max" -v c="$main_max" \

package/template/.claude/hooks/tests/forge-reserve.test.sh

@@ -285,6 +285,98 @@ else
   fail "case10b --days 1 dropped the kind's max row"
 fi
 
+# --- Case 11: origin/main floor beats a lagging local main (#26) -------------
+# The local-main-first collision: origin/main carries a MERGED higher claim
+# (FR-300) that local main has not fast-forwarded to (local main still at FR-200).
+# A local-main-only floor would hand out FR-201 — an id origin/main already used.
+# The fix reads across {main, origin/main}, so the floor is FR-300 → next FR-301.
+origin_repo="$(new_repo case11-origin)"
+( cd "$origin_repo"
+  mkdir -p .forge
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-300
+    milestone: m-sibling
+    reserved_at: "2026-02-01"
+    summary: "merged on origin/main, ahead of local main"
+YML
+  git add -A && git commit -qm "origin has FR-300" )
+# Clone it (clone's origin → the seed repo), then rewind the clone's LOCAL main to
+# an earlier commit carrying only FR-200 — simulating a primary checkout parked on a
+# stale main while sibling work merged FR-300 to origin.
+clone="$ROOT/repo.case11-clone"
+git clone -q "$origin_repo" "$clone"
+cd "$clone"
+git config user.email t@example.com; git config user.name tester
+# Build a divergent local main: reset to an orphan-free earlier state with FR-200.
+cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "local main lags"
+YML
+git add -A && git commit -qm "local main at FR-200 (behind origin/main FR-300)"
+# origin/main (remote-tracking) still points at FR-300; local main is now at FR-200.
+# Allow the helper to fetch the local file:// origin (deterministic, no network).
+got="$(FORGE_RESERVE_NO_FETCH=1 "$HELPER" fr --milestone m-x)"
+check "case11 origin/main floor (FR-300) beats lagging local main (FR-200) -> FR-301" "$got" "FR-301"
+# Negative control: with the origin arm blind (simulate no remote-tracking ref by
+# reading a repo that has NO origin at all), the floor falls back to local main only.
+d="$(new_repo case11-noorigin)"; cd "$d"
+mkdir -p .forge
+cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "no origin — local main is the only floor"
+YML
+git add -A && git commit -qm init
+rm .forge/reservations.yml
+got="$(FORGE_RESERVE_NO_FETCH=1 "$HELPER" fr --milestone m-x)"
+check "case11 no-origin repo still floors on local main (FR-200) -> FR-201" "$got" "FR-201"
+
+# --- Case 12: the fetch refreshes a STALE origin/main tracking ref (#26) ------
+# The end-to-end proof: a sibling merges a higher claim to origin AFTER this clone
+# was made, so the clone's origin/main remote-tracking ref is stale. Without the
+# best-effort fetch the floor would miss it; with the fetch (default, NOT skipped)
+# the helper refreshes origin/main and floors correctly. Uses a local file:// origin
+# so the "fetch" is a deterministic local operation, no network.
+seed="$(new_repo case12-seed)"
+( cd "$seed"
+  mkdir -p .forge
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "seed FR-200"
+YML
+  git add -A && git commit -qm "seed FR-200" )
+clone2="$ROOT/repo.case12-clone"
+git clone -q "$seed" "$clone2"
+# Sibling advances origin to FR-400 AFTER the clone → clone's origin/main is now stale.
+( cd "$seed"
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-400
+    milestone: m-sibling
+    reserved_at: "2026-03-01"
+    summary: "merged to origin after the clone"
+YML
+  git add -A && git commit -qm "origin advances to FR-400" )
+cd "$clone2"
+git config user.email t@example.com; git config user.name tester
+# Do NOT set FORGE_RESERVE_NO_FETCH — the fetch is exactly what we are testing.
+got="$("$HELPER" fr --milestone m-x)"
+check "case12 fetch refreshes stale origin/main (FR-400) -> FR-401" "$got" "FR-401"
+
 # --- Report -----------------------------------------------------------------
 printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
 [ "$FAILED" -eq 0 ]

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

@@ -36,6 +36,29 @@ fi
 
 Surface the init if it ran (*"populated N uninitialised submodule(s) before baseline"*). A `+`/`U` line (divergent/conflicted submodule) is **not** an init case — STOP under Rule 4; it signals real submodule movement. (Desire-path: canvaz m-TIDES01 — empty `external/JUCE` failed the first CMake configure mid-task.)
 
+**Gitignored artifacts.** A fresh worktree is a clean checkout of *tracked* files only. Anything gitignored but required — `.mcp.json` (MCP server config, often secret-bearing so it MUST stay gitignored), `.env.local`, experimental hook configs — is simply **absent**, and the failure is silent: MCP servers that never appear, an env-dependent command that misbehaves — no clear "missing config" error. `orchestrating` hydrates these when *it* creates the worktree, but a worktree from any other origin (a manual `git worktree add`, a `chief-of-staff` stream, a fresh clone) does not. So assert it here, regardless of how the workspace was created. Advisory and guarded — a clean no-op when `orchestration.worktree_hydrate` is unset or nothing applies, so existing installs are unaffected:
+
+```bash
+# Copy required-but-gitignored artifacts named in orchestration.worktree_hydrate from the
+# superproject (the MAIN checkout, resolved from the shared git common dir — this assertion
+# runs INSIDE the worktree), guarded source-exists && dest-absent. Never overwrites, never
+# git-adds — the file stays gitignored/untracked in both trees (a secret like .mcp.json never
+# enters git history). No-op when the key is absent or nothing applies.
+repo_root=$(git rev-parse --show-toplevel)
+super=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's#/\.git/modules/.*##;s#/\.git/worktrees/.*##;s#/\.git$##')
+sed -n '/^orchestration:/,/^[^[:space:]#]/p' "$repo_root/.forge/project.yml" 2>/dev/null \
+  | sed -n '/^[[:space:]]*worktree_hydrate:/,/^[[:space:]]*[a-z_]*:/p' \
+  | sed -n 's/^[[:space:]]*-[[:space:]]*//p' | tr -d "\"'" \
+  | while IFS= read -r rel; do                   # line-based: robust across sh/bash/zsh; a path may contain spaces
+      [ -n "$rel" ] && [ -n "$super" ] && [ "$super" != "$repo_root" ] || continue  # no key / main checkout → no-op
+      [ -e "$super/$rel" ] && [ ! -e "$repo_root/$rel" ] || continue                # source-exists && dest-absent
+      mkdir -p "$(dirname "$repo_root/$rel")"; cp -p "$super/$rel" "$repo_root/$rel"
+      echo "hydrated: $rel"
+    done
+```
+
+The loop prints one `hydrated: {path}` line per artifact it copied — surface those before the baseline (*"hydrated N gitignored artifact(s) before baseline"*), mirroring the submodule surface line; no output means nothing needed hydrating. The `$super != $repo_root` guard makes this a natural no-op in a non-worktree (main) checkout — where superproject and checkout are the same tree and there is nothing to hydrate from.
+
 ## Baseline Snapshot
 
 Run **before the first task begins**. Makes failure causality mechanical — no self-assessment.

package/template/.forge/FORGE.md

@@ -59,6 +59,8 @@ Where worktrees live and what they're named — single source of truth, base con
 
 **Recorded path is authoritative once set** — `lifecycle.worktree_path` (milestone) / `runtime.worktree` (stream) is read verbatim, never re-derived; changing `worktree_root` affects only new worktrees; move a live worktree only with `git worktree move` + update the record. No recorded path → resolve from the convention. `forge` boot and `chief-of-staff` adoption **validate advisorily**: recorded path outside the resolved root → warn (never block, never move); an explicit `worktree_root` is honored.
 
+**`orchestration.worktree_hydrate`** (optional, `project.yml`; forge#18) lists superproject-relative paths to required-but-gitignored artifacts (e.g. `.mcp.json`) a fresh worktree's tracked-only checkout lacks. Copy is guarded `source-exists && dest-absent` — never overwrites, never `git add`s, so the secret stays untracked in both trees. Applied by `orchestrating` at creation and re-asserted idempotently in `executing`'s Workspace Prerequisites, covering worktrees of any origin. Omit ⇒ no propagation. The per-worktree runtime counterpart of the install-time carve-out propagation below (State Ownership § Stable shared).
+
 ## Workflow Tiers
 
 Auto-detects complexity. Override: "Use Quick/Standard/Full tier."

package/template/.forge/templates/project.yml

@@ -99,6 +99,20 @@ verification:
 #                                    # only — the private key lives host-side, in the deploy Environment).
 #                                    # Empty ⇒ git config gpg.ssh.allowedSignersFile.
 
+# orchestration:                     # OPTIONAL — worktree behavior (M10 / streams). Absent → defaults.
+#   worktree_root: ""                # Where Forge worktrees live. Default ../<repo-basename>-worktrees.
+#                                    #   Relative → resolves against repo root; absolute / ~ honored verbatim.
+#   worktree_hydrate: []             # OPTIONAL list of superproject-relative paths — required-but-gitignored
+#                                    #   artifacts copied into a fresh worktree so it can build and reach its
+#                                    #   tools (a clean worktree checks out TRACKED files only). Guarded
+#                                    #   source-exists && dest-absent: never overwrites, never git-adds, so a
+#                                    #   secret-bearing file stays gitignored/untracked in both trees and never
+#                                    #   enters git history (.mcp.json the canonical case). Applied by
+#                                    #   orchestrating at creation AND asserted in executing's Workspace
+#                                    #   Prerequisites → worktrees of ANY origin covered. Omit → no propagation.
+#                                    #   e.g. [".mcp.json", ".env.local"]. Dependency install stays with the
+#                                    #   executing/verifying preflight, not this key.
+
 success_criteria:                   # How do we know we're done?
   - ""                              # e.g., "User can create and edit posts"
   - ""                              # e.g., "All tests pass with >80% coverage"