forge-orkes 0.80.0 → 0.80.2

package/bin/create-forge.js

@@ -588,12 +588,21 @@ function extractDetectionBlock(guideContent) {
  * with the exact guide pointer. There are NO per-version code branches: a new
  * guide that ships with a conformant Detection block is auto-covered.
  *
- * Range: installed < v <= source. `installedVersion` is the project's
+ * Range: installed <= v <= source. `installedVersion` is the project's
  * settings.json forge.version captured BEFORE the version stamp; `source` is
  * pkgVersion (this package's package.json) — never the template settings.json
  * literal, which is a placeholder the installer stamps at write time. Non-
  * interactive: the bin only warns and points at the guide; it never applies.
  *
+ * Lower bound is INCLUSIVE (issue #43): the version stamp always advances
+ * unconditionally, even when a MIGRATE hit was surfaced but declined that
+ * run — so an exclusive `installed < v` permanently hides a same-numbered
+ * guide the moment its own version gets stamped without being applied. This
+ * is safe to widen because the guide's own `## Detection` block is the real
+ * gate (repo-state-based: tracked file, size, absence of the post-migration
+ * artifact) — the version range only decides which guides are worth asking;
+ * a genuinely-already-applied guide's Detection block reports a no-op.
+ *
  * Returns the applying guides as [{version, guide, reason}] — the human warning
  * and the --json `migrations` key render the same findings.
  */
@@ -606,7 +615,7 @@ function runPostUpgradeMigrationChecks(installedVersion) {
     installedVersion && installedVersion !== 'unknown' ? installedVersion : '0.0.0';
   const source = pkgVersion;
 
-  // Select in-range guides: installed < v <= source. Parse {v} from the filename.
+  // Select in-range guides: installed <= v <= source. Parse {v} from the filename.
   let guides;
   try {
     guides = fs
@@ -618,7 +627,7 @@ function runPostUpgradeMigrationChecks(installedVersion) {
       .filter(Boolean)
       .filter(
         (g) =>
-          compareVersions(installed, g.version) < 0 &&
+          compareVersions(installed, g.version) <= 0 &&
           compareVersions(g.version, source) <= 0
       )
       .sort((a, b) => compareVersions(a.version, b.version));
@@ -885,6 +894,12 @@ async function upgrade() {
   //    initializing/upgrading skills' job, NOT the installer's — see makeGitHooksExecutable.
   upgradeAdditiveDir('.forge/git-hooks', results);
   makeGitHooksExecutable(path.join(targetDir, '.forge'));
+  // 2-bin. Sync the tracked worktree helper (0.78.0, ADR-031) — omitted from the
+  //    additive-sync category set until issue #41, so upgraded projects never
+  //    received .forge/bin/new-worktree.sh even though the weld's deny message
+  //    and migration guide both point at it. Additive, same reasoning as the
+  //    other .forge/ categories above.
+  upgradeAdditiveDir('.forge/bin', results);
 
   // 2a. Confirm stale framework-file removals before deleting (R066a). Defaults
   //     to yes (cleanup is the normal case); auto-confirms when non-interactive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.80.0",
+  "version": "0.80.2",
   "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-context-migrate.sh

@@ -26,8 +26,10 @@
 #
 # Classification rules (see phase 95 plan-01 task 1):
 #   - `## Locked Decisions` sub-headings (`### ...`) whose first word resolves
-#     to a milestone id (`M{N}`, `m-{N}`, `m{N}` — normalized to `m-{N}`) each
-#     become `context/{id}.md`. A heading with no resolvable id (e.g. a
+#     to a milestone id (`M{N}`, `m-{N}`, `m{N}` — normalized to `m-{N}`; or a
+#     labelled id like `M-EVT01`, `m-SEQPRIM01` — normalized to lowercase with
+#     the label preserved, e.g. `m-evt01`, `m-seqprim01`, never digit-stripped)
+#     each become `context/{id}.md`. A heading with no resolvable id (e.g. a
 #     drafting block, or a pointer-stub heading like "Historical Decisions")
 #     is NOT sharded — it lands in context-log.md verbatim.
 #   - `## Deferred Ideas` / `## Discretion Areas` top-level bullets whose text
@@ -120,7 +122,7 @@ awk_prog="$(mktemp 2>/dev/null || mktemp -t forge-context-migrate)"
 trap 'rm -f "$awk_prog"' EXIT INT TERM
 
 cat > "$awk_prog" <<'AWKEOF'
-function extract_id(line,    w, arr, n, tok, digits) {
+function extract_id(line,    w, arr, n, tok, digits, suffix) {
   w = line
   sub(/^### /, "", w)
   sub(/^- /, "", w)
@@ -129,12 +131,26 @@ function extract_id(line,    w, arr, n, tok, digits) {
   if (n < 1) return ""
   tok = arr[1]
   gsub(/[:,.]+$/, "", tok)
-  if (tok ~ /^[Mm]-?[0-9]+$/) {
-    digits = tok
+  # Purely-numeric ids (M53, m-53, m53) keep the original digit-only
+  # normalization. Labelled ids (M-EVT01, m-SEQPRIM01) must NOT be digit-
+  # stripped — that would collapse distinct labelled ids onto the same
+  # numeric suffix (m-EVT01 and m-SEQPRIM01 would both become m-01) — so
+  # their alphanumeric suffix is preserved VERBATIM, case included (issue
+  # #44): only the "m-" prefix is normalized, exactly like the numeric path
+  # never invents a digit convention of its own. Forge doesn't own the
+  # label's spelling — a project's own casing convention (e.g. m-EVT01, all
+  # caps) must survive the shard, or citations elsewhere in the repo stop
+  # matching the shard filename.
+  if (tok !~ /^[Mm]-?[A-Za-z0-9]+$/) return ""
+  suffix = tok
+  sub(/^[Mm]-?/, "", suffix)
+  if (suffix == "") return ""
+  if (suffix ~ /^[0-9]+$/) {
+    digits = suffix
     gsub(/[^0-9]/, "", digits)
     return "m-" digits
   }
-  return ""
+  return "m-" suffix
 }
 
 function add_id(id) {
@@ -288,6 +304,15 @@ END {
     }
   }
 
+  if (n_ids == 0 && n_noid > 0) {
+    print "forge-context-migrate: ERROR — 0 milestone id(s) resolved but " n_noid \
+      " Locked Decision heading(s) found with no resolvable id; this usually means the" \
+      " heading's id scheme doesn't match m-<number> or a labelled m-<label> form" \
+      " (check context.md's heading format before proceeding)" > "/dev/stderr"
+    print "forge-context-migrate: " n_ids " milestone id(s) processed"
+    exit 1
+  }
+
   print "forge-context-migrate: " n_ids " milestone id(s) processed"
 }
 AWKEOF

package/template/.claude/hooks/forge-release-fold.sh

@@ -28,7 +28,13 @@
 #   (3) unknown in both → exit 2 — the fold cannot ask the question, so it
 #       never emits a false verdict.
 #
-# merged = `git merge-base --is-ancestor <sha> <main-ref>`.
+# merged = `git merge-base --is-ancestor <sha> <main-ref>`, OR — when that
+# fails — a squash-merge equivalence check (see is_merged() below). GitHub's
+# squash-and-merge creates a brand-new commit on <main-ref> with no ancestor
+# relationship to the source branch, so the direct check alone is a permanent
+# false negative for any squash-merged unit whose branch/stream ref is still
+# live (issue #39, m-55; reproduced live via m-53/PR#38). The fallback stays
+# git-only, no network — NFR-030 unaffected.
 #
 # Validation is dispatched on forge.validation_event from the project's
 # .forge/project.yml (default: in_session_signoff; promotion_approval is the
@@ -171,6 +177,33 @@ hv_is_set() {
   '
 }
 
+# is_merged <sha> — merged rung of the fold. Direct ancestor check first
+# (unchanged cost/behavior for fast-forward / true-merge-commit units). On
+# failure, falls back to a squash-merge equivalence check: build an
+# unreferenced synthetic commit representing <sha>'s cumulative diff since it
+# diverged from $main_ref, then ask `git cherry` (patch-id based — the same
+# primitive git itself uses to detect already-applied/rebased/squashed
+# commits) whether an equivalent patch already landed on $main_ref. Squash-
+# and-merge creates a brand-new commit with no ancestor relationship to the
+# source branch, so the direct check alone is a permanent false negative for
+# every squash-merged unit whose branch/stream ref is still live (m-53/PR#38,
+# issue #39). Git-only, no network (NFR-030 preserved) — the synthetic commit
+# is never attached to a ref, so it's naturally garbage-collectable.
+is_merged() {
+  target="$1"
+  if git -C "$root" merge-base --is-ancestor "$target" "$main_ref" 2>/dev/null; then
+    return 0
+  fi
+  mb="$(git -C "$root" merge-base "$main_ref" "$target" 2>/dev/null)" || return 1
+  [ -n "$mb" ] || return 1
+  tgt_tree="$(git -C "$root" rev-parse -q --verify "$target^{tree}" 2>/dev/null)" || return 1
+  synth="$(git -C "$root" commit-tree "$tgt_tree" -p "$mb" -m squash-probe 2>/dev/null)" || return 1
+  case "$(git -C "$root" cherry "$main_ref" "$synth" 2>/dev/null)" in
+    -*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 # --- argument parsing ------------------------------------------------------
 
 unit=""
@@ -281,7 +314,7 @@ fi
 # validated REQUIRES merged — checked first, always. An unmerged unit is
 # unmerged no matter what any approval artifact says.
 
-if ! git -C "$root" merge-base --is-ancestor "$sha" "$main_ref" 2>/dev/null; then
+if ! is_merged "$sha"; then
   printf 'release_state=unmerged reason=not-on-main\n'
   exit 0
 fi

package/template/.claude/hooks/tests/forge-context-migrate.test.sh

@@ -159,6 +159,98 @@ src_after="$(cat "$SOURCE" | wc -c)"
 [ -n "$src_after" ] && pass "source context.md still readable after migration" || fail "source context.md unreadable after migration"
 grep -q "### M7 — Widget Registry" "$SOURCE" && pass "source context.md left untouched" || fail "source context.md was modified"
 
+# --- labelled milestone ids (issue #42, case preservation issue #44) --------
+# Non-numeric ids (M-EVT01, m-SEQPRIM01) must shard into distinct files —
+# digit-stripping them onto a shared "m-01" was the exact silent-collision
+# bug reported upstream. Purely-numeric ids must keep their existing
+# normalization (m-53 stays m-53, unaffected by the labelled-id path). The
+# label's own casing must survive verbatim (issue #44) — only the "m-"
+# prefix is normalized — since a project's own convention (e.g. an
+# all-caps label) is what the rest of its repo actually cites.
+
+LBLROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT" "$LBLROOT"' EXIT INT TERM
+LBLSRC="$LBLROOT/context.md"
+LBLDEST="$LBLROOT/.forge"
+mkdir -p "$LBLDEST"
+
+cat > "$LBLSRC" <<'FIXTURE'
+## Locked Decisions
+
+### M-EVT01 — Event pipeline
+
+- **Decision**: Emit events. Reason: because.
+
+### m-SEQPRIM01 — Sequencer primitives
+
+- **Decision**: Order things. Reason: also because.
+
+### m-53 — Numeric id alongside labelled ones
+
+- **Decision**: Still works numerically.
+
+## Deferred Ideas
+
+- m-EVT01: a follow-up scoped to the labelled id.
+
+## Needs Resolution
+
+(none)
+
+## Amendment Log
+
+(none)
+FIXTURE
+
+LBLOUT="$("$MIGRATE" --source "$LBLSRC" --dest "$LBLDEST" 2>&1)"
+LBLRC=$?
+[ "$LBLRC" -eq 0 ] && pass "labelled-id migration exits 0" || fail "labelled-id migration exits 0 (exit $LBLRC)"
+
+check_file "$LBLDEST/context/m-EVT01.md" "context/m-EVT01.md created (labelled id, prefix normalized)"
+check_file "$LBLDEST/context/m-SEQPRIM01.md" "context/m-SEQPRIM01.md created (distinct from m-EVT01, not digit-collapsed)"
+check_file "$LBLDEST/context/m-53.md" "context/m-53.md still created (numeric id unaffected by labelled-id path)"
+
+# check_file alone can't prove case survived — macOS's default case-insensitive
+# FS makes m-evt01.md and m-EVT01.md the same lookup. `ls` returns the actual
+# stored name; grep -x is case-sensitive regardless of the FS.
+lbl_listing="$(ls "$LBLDEST/context" 2>/dev/null)"
+echo "$lbl_listing" | grep -qx "m-EVT01.md" && pass "m-EVT01.md label case preserved verbatim on disk (issue #44)" || fail "label case NOT preserved — directory listing: $lbl_listing"
+echo "$lbl_listing" | grep -qx "m-SEQPRIM01.md" && pass "m-SEQPRIM01.md label case preserved verbatim on disk (issue #44)" || fail "label case NOT preserved — directory listing: $lbl_listing"
+
+lbl_count="$(ls "$LBLDEST"/context/*.md 2>/dev/null | wc -l | tr -d ' ')"
+[ "$lbl_count" -eq 3 ] && pass "labelled + numeric ids produce 3 distinct files, none collapsed" || fail "labelled-id run produced $lbl_count file(s), want 3"
+
+evt="$(cat "$LBLDEST/context/m-EVT01.md" 2>/dev/null)"
+check_has "m-EVT01.md carries its own Deferred entry (labelled-prefix match)" "$evt" "a follow-up scoped to the labelled id"
+
+# --- unresolvable id scheme guard (issue #42) --------------------------------
+# A context.md whose Locked Decisions headings don't match m-<number> or a
+# labelled m-<label> form at all (e.g. a different project's own convention)
+# must fail loudly instead of silently producing zero shards.
+
+BADROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT" "$LBLROOT" "$BADROOT"' EXIT INT TERM
+BADSRC="$BADROOT/context.md"
+BADDEST="$BADROOT/.forge"
+mkdir -p "$BADDEST"
+
+cat > "$BADSRC" <<'FIXTURE'
+## Locked Decisions
+
+### FEATURE-ABC — unrelated id scheme
+
+- **Decision**: Something.
+
+### FEATURE-XYZ — another unrelated id
+
+- **Decision**: Something else.
+FIXTURE
+
+BADOUT="$("$MIGRATE" --source "$BADSRC" --dest "$BADDEST" --dry-run 2>&1)"
+BADRC=$?
+[ "$BADRC" -ne 0 ] && pass "unresolvable id scheme exits non-zero instead of silently producing 0 shards" || fail "unresolvable id scheme should exit non-zero (exit $BADRC)"
+check_has "unresolvable id scheme prints an ERROR line" "$BADOUT" "ERROR"
+
 # --- summary -----------------------------------------------------------------
 
 printf '\n%s passed, %s failed\n' "$PASSED" "$FAILED"

package/template/.claude/hooks/tests/forge-release-fold.test.sh

@@ -24,7 +24,7 @@
 #   ./.claude/hooks/tests/forge-release-fold.test.sh ordering    # ordering controls
 # Filter tags (one arg, selects matching case blocks):
 #   unmerged merged grandfather human-verified signoff-tag stored-field
-#   exit-2 stable-sha ordering promotion forgery labeled
+#   exit-2 stable-sha ordering promotion forgery labeled squash
 # `promotion` + `forgery` (plan 51-01): validation_event=promotion_approval —
 # a CI-signed tag on a deploy sha CONTAINING the unit's landed sha validates;
 # tag deletion reverts; unsigned/wrong-key lookalikes and non-containing tags
@@ -791,9 +791,60 @@ lifecycle:
   check_absent "unsafe labeled id: no verdict on stdout" "$OUT" "release_state="
 fi
 
+# --- case: squash-merged unit resolves merged (issue #39, m-53/PR#38 shape) -----
+# GitHub squash-and-merge creates a brand-new commit on main with no ancestor
+# relationship to the source branch — the direct ancestor check alone
+# permanently misreports this as unmerged. Reproduces the real bug shape:
+# a live branch tip (resolved via streams/m-N.yml runtime.branch, exactly
+# resolution rule 1's `else` route — no lifecycle.worktree_branch in the state
+# file, matching the real m-53 fixture), plus an unrelated commit on main
+# between the branch's fork point and the squash (mirrors main advancing
+# independently in between — and would defeat a naive whole-tree-hash
+# comparison, which this repo's own investigation found fails under exactly
+# this kind of drift).
+if running squash; then
+  printf '\n--- case: squash-merged unit resolves merged (git merge --squash, not --no-ff) ---\n'
+  d="$(new_repo squash)"
+  write_milestone "$d" 120 'milestone:
+  id: 120
+  name: "fixture: squash-merged unit"
+
+current:
+  tier: standard
+  status: executing
+  last_updated: "2026-07-29"
+  human_verified: null
+
+lifecycle:
+  worktree_mode: active'
+  write_stream "$d" m-120 forge/m-120
+  git -C "$d" checkout -qb forge/m-120
+  # Real file content — an --allow-empty commit here would give the branch a
+  # zero-diff tip, making the squash-probe trivially match ANY zero-diff main
+  # commit regardless of the mechanism under test. Genuine content is what
+  # makes this a meaningful positive fixture.
+  printf 'feature work\n' > "$d/FEATURE.txt"
+  git -C "$d" add FEATURE.txt
+  git -C "$d" commit -qm "work on forge/m-120 (will be squash-merged)"
+  git -C "$d" checkout -q main
+  # Unrelated main-side drift between fork and squash, with its OWN real file
+  # content — mirrors main advancing independently in between, exactly like
+  # m-53/PR#38 (main gained m-54's declaration in between). Would defeat a
+  # naive whole-tree-hash comparison, which this repo's own investigation
+  # found fails under exactly this kind of drift.
+  printf 'unrelated\n' > "$d/OTHER.txt"
+  git -C "$d" add OTHER.txt
+  git -C "$d" commit -qm "unrelated main-side work"
+  git -C "$d" merge -q --squash forge/m-120 >/dev/null 2>&1
+  git -C "$d" commit -q -m "squash merge forge/m-120 (#120)"
+  run_fold "$d" m-120
+  check "squash-merged: exit 0" "$RC" "0"
+  check "squash-merged: resolves merged (no false negative on ancestor-check failure)" "$OUT" "release_state=merged reason=no-signoff"
+fi
+
 # --- summary -------------------------------------------------------------------
 if [ -n "$FILTER" ] && [ "$SELECTED" -eq 0 ]; then
-  printf 'ERROR: filter "%s" matched no cases (tags: unmerged merged grandfather human-verified signoff-tag stored-field exit-2 stable-sha ordering promotion forgery labeled)\n' "$FILTER" >&2
+  printf 'ERROR: filter "%s" matched no cases (tags: unmerged merged grandfather human-verified signoff-tag stored-field exit-2 stable-sha ordering promotion forgery labeled squash)\n' "$FILTER" >&2
   exit 2
 fi
 

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.80.0",
+    "version": "0.80.2",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {

package/template/.forge/migrations/0.80.0-context-md-sharding.md

@@ -76,6 +76,22 @@ echo "MIGRATE — .forge/context.md is a tracked, ${size}-byte monolithic file w
 
 ## Migration steps
 
+### 0. Dry-run first and check the processed count
+
+```bash
+.claude/hooks/forge-context-migrate.sh --dry-run
+```
+
+Confirm the `forge-context-migrate: N milestone id(s) processed` line names a
+plausible number of ids for your `context.md`'s actual Locked Decisions
+headings. The tool exits non-zero and prints an `ERROR` line instead of a
+silent `0 milestone id(s) processed` when it finds Locked Decisions headings
+it can't resolve to any milestone id (issue #42) — but a dry-run check is
+still worth doing before the destructive untrack step below, since a partial
+match (some headings resolve, some don't) still exits 0. Milestone ids must
+be `m-<number>` (`M53`, `m-53`) or a labelled `m-<label>` form (`M-EVT01`,
+`m-SEQPRIM01`); anything else won't shard.
+
 ### 1. Run the migration tool for real (not dry-run)
 
 From the repo root, with no flags — the tool resolves `--source` and `--dest`
@@ -87,7 +103,8 @@ omitted, defaulting to `<repo-root>/.forge/context.md` and `<repo-root>/.forge`:
 ```
 
 This reads `.forge/context.md` and writes `.forge/context/{id}.md` (one file
-per resolvable milestone heading, ids normalized to `m-{N}`),
+per resolvable milestone heading, numeric ids normalized to `m-{N}` and
+labelled ids lowercased and preserved, e.g. `m-evt01`),
 `.forge/context-log.md` (Amendment Log, Needs Resolution, and any undated
 drafting block that has no milestone id to shard by), and
 `.forge/context/_shared.md` if any Deferred Ideas / Discretion Areas entry