forge-orkes 0.67.0 → 0.68.1

package/bin/create-forge.js

@@ -52,31 +52,22 @@ const FORGE_END = '<!-- forge:end -->';
 
 // --- File classification for upgrades ---
 
-// Framework-owned: Forge controls these entirely
+// Framework-owned: Forge controls these entirely. Auto-clean removes files that
+// dropped out of the template — but ownership is decided per top-level UNIT
+// (a skill DIR under .claude/skills/, an agent FILE under .claude/agents/), and
+// only the template defines which units Forge shipped. A unit the base template
+// never shipped — user-authored, vendored-parity, or an opt-in experimental
+// skill installed separately (e.g. m10's orchestrating, the convention packs) —
+// is NOT framework content and is preserved, never swept, even though it lives
+// under a framework-owned dir. Deleting it would destroy work Forge never owned,
+// and .claude/ is frequently gitignored, so the loss is unrecoverable. Files
+// removed from WITHIN a still-shipped unit (e.g. a renamed helper inside a
+// template skill dir) stay cleanable — their unit is still present in the
+// template. See upgradeDir(). Experimental skills are additionally diffed
+// against their shipped sources by detectExperimentalStaleness() (report-only;
+// re-sync consent lives in the /upgrading skill layer).
 const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
 
-// Experimental / opt-in skills installed separately (e.g. from experimental/m10).
-// They are NOT in the shipped base template, so the framework-owned auto-clean
-// would otherwise delete them on upgrade. Preserve them instead.
-//
-// The npm tarball ships experimental/ alongside bin/ + template/, so this route
-// CAN diff an installed experimental skill against its same-tarball source:
-// detectExperimentalStaleness() reports unchanged|stale with the differing files.
-// (Blind preservation is what silently froze these pre-0.33.0 — issue #5: a base
-// migration that changed experimental-skill behavior became a no-op.) Detection
-// only — consent for a re-sync lives in the /upgrading skill layer, and
-// load-bearing conventions are still promoted to base (FORGE.md) rather than
-// left to a frozen skill. This preserve-list gates auto-clean only; staleness
-// discovery is by directory scan of the shipped experimental/ tree.
-const EXPERIMENTAL_SKILL_PATHS = ['.claude/skills/orchestrating'];
-
-function isExperimentalSkillPath(displayPath) {
-  const norm = displayPath.split(path.sep).join('/');
-  return EXPERIMENTAL_SKILL_PATHS.some(
-    (p) => norm === p || norm.startsWith(p + '/')
-  );
-}
-
 // Compare dotted numeric versions (e.g. "0.19.1"). Returns 1 if a>b, -1 if a<b, 0 if equal.
 function compareVersions(a, b) {
   const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
@@ -259,9 +250,15 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
     const srcPath = path.join(srcDir, rel);
     if (!fs.existsSync(srcPath)) {
       const displayPath = path.join(relDir, rel);
-      // Never auto-clean opt-in experimental skills — they live outside the base template.
-      if (autoClean && isExperimentalSkillPath(displayPath)) {
-        result.preserved.push(displayPath);
+      // Ownership is per top-level unit: the first path segment of `rel` is the
+      // skill dir (or, for flat agents, the file itself). If the template no
+      // longer ships that unit at all, the file is user-authored, vendored, or an
+      // opt-in experimental skill — not Forge's to delete. Preserve it. Only
+      // files whose unit the template STILL ships (a stale file inside a shipped
+      // skill dir) remain removal candidates.
+      const topUnit = rel.split(path.sep)[0];
+      if (autoClean && !fs.existsSync(path.join(srcDir, topUnit))) {
+        result.preserved.push(`${displayPath} (kept — not shipped by the base template)`);
         continue;
       }
       const destPath = path.join(destDir, rel);
@@ -374,6 +371,30 @@ function mergeManagedDeny(destSettings, srcSettings) {
   }
 }
 
+/**
+ * Union the template's managed allow rules into the project's permissions.allow.
+ * Additive — a user's own allow/deny entries are untouched (mirrors
+ * mergeManagedDeny). Forge automates a worktree-heavy workflow (streams, the
+ * slice runner, orchestration/human-verified teardown), but the harness auto-mode
+ * classifier soft-denies `git worktree remove` for a worktree the session didn't
+ * create in-session, and a Remote-Control / detached session cannot enter
+ * bypassPermissions after launch. A NARROW allow rule survives auto mode and runs
+ * before the classifier, so the automating session can clean up its own worktrees.
+ * These are read/teardown of Forge-managed worktrees only — `remove` is git-guarded
+ * (refuses on a dirty/untracked tree without --force) and, in the Forge flow, only
+ * ever runs on a merged, human-verified worktree. It never touches commits or
+ * branches — worktree removal drops a checkout, not history.
+ */
+function mergeManagedAllow(destSettings, srcSettings) {
+  const srcAllow = (srcSettings.permissions && srcSettings.permissions.allow) || [];
+  if (!srcAllow.length) return;
+  destSettings.permissions = destSettings.permissions || {};
+  const destAllow = destSettings.permissions.allow || (destSettings.permissions.allow = []);
+  for (const rule of srcAllow) {
+    if (!destAllow.includes(rule)) destAllow.push(rule);
+  }
+}
+
 /**
  * Strip the legacy *inline* active-skill guard from PreToolUse (forge#12). It was
  * an inline `if [ ! -f .../.forge/.active-skill ]; then ... exit 2; fi` one-liner;
@@ -437,6 +458,7 @@ function upgradeSettings() {
   // Additively install framework-managed safety guardrails (ADR-017)
   mergeManagedHooks(destSettings, srcSettings);
   mergeManagedDeny(destSettings, srcSettings);
+  mergeManagedAllow(destSettings, srcSettings);
 
   const after = JSON.stringify(destSettings);
   if (before === after) return 'unchanged';
@@ -949,7 +971,7 @@ async function upgrade() {
     if (results.preserved.length > 0) {
       say(`  Preserved (${results.preserved.length}):`);
       for (const f of results.preserved) {
-        say(`    ${f} (kept — opt-in experimental skill)`);
+        say(`    ${f}`);
       }
       for (const e of experimental) {
         say(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.67.0",
+  "version": "0.68.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/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.58.3",
+    "version": "0.68.0",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {
@@ -48,6 +48,11 @@
       "Edit(**/.secrets/**)",
       "Edit(**/*.pem)",
       "Edit(**/*.key)"
+    ],
+    "allow": [
+      "Bash(git worktree remove *)",
+      "Bash(git worktree prune)",
+      "Bash(git worktree prune *)"
     ]
   },
   "hooks": {

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

@@ -139,7 +139,7 @@ Source version (`{source}/packages/create-forge/package.json`) **<** installed (
 
 Dev mode syncs from a checkout, so it keeps file-classification semantics — **the npm bin's sync behavior is the spec**; do not re-derive it here. Categories:
 
-- **Framework-owned** (`.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.forge/FORGE.md`) → overwrite when different; a local skill dir absent from the template defers to the experimental pass below (only no-source dirs report *removed from template* — never deleted).
+- **Framework-owned** (`.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.forge/FORGE.md`) → overwrite when different. Ownership is per top-level **unit** — a skill DIR under `.claude/skills/`, a flat agent FILE under `.claude/agents/`: a unit the template doesn't ship (user-authored, vendored-parity, or an opt-in experimental skill) is **preserved, never deleted**; only stale files *inside* a still-shipped skill dir are cleaned. Experimental skills additionally get the staleness pass below.
 - **Template-only** (`.forge/templates/**`, `.forge/migrations/**`, `.forge/adapters/**`, `.forge/gitignore` → `.forge/.gitignore`) → overwrite; `.forge/FORGE.md` lands BEFORE the CLAUDE.md pass.
 - **Additive** (`.claude/hooks/**` incl. `tests/`, `.claude/rules/**`, `.forge/checks/**`) → add + overwrite template-shipped files, never delete local extras, `chmod +x` synced `*.sh`.
 - **Import-managed** `CLAUDE.md` → the bin's `ensureClaudeMdImport()` cases verbatim; user content outside a forge section is never modified.

package/template/.forge/checks/forge-jarvis-dispatch.sh

@@ -91,17 +91,25 @@ materialize_work_order() {
   # Prefer the worktree's OWN milestone — .forge/phases/ carries the repo's whole milestone
   # history (32 dirs on the forge repo), so "the only milestone dir" is a fixture-world
   # assumption. The Worktree Convention names the branch forge/{anchor} with anchor =
-  # {milestone-id}[-{session}]; derive the id and pick that milestone's dir.
+  # {milestone-id}[-{session}]; derive the id and pick that milestone's dir. The id's own
+  # m- may be a strippable prefix (m-40 → milestone-40) or PART of a labeled id kept
+  # verbatim (m-EVT01 → milestone-m-EVT01) — canvaz first run 2026-07-22: stripping it
+  # unconditionally missed milestone-m-EVT01 and fell through to a 38-dir refusal. Try the
+  # anchor verbatim before the m--stripped form, then both again minus one trailing
+  # -{session} token; first existing dir wins (exact/longer forms first).
   _mdir=""
   _branch="$(git -C "$WORKTREE" branch --show-current 2>/dev/null)"
   case "$_branch" in
-    forge/m-*)
-      _anchor="${_branch#forge/m-}"                                   # 40 | 40-a1b2c3d4 | R61-002
-      [ -d "$WORKTREE/.forge/phases/milestone-$_anchor" ] && _mdir="$WORKTREE/.forge/phases/milestone-$_anchor"
-      if [ -z "$_mdir" ]; then
-        _short="${_anchor%-*}"                                        # strip one trailing -token (session suffix)
-        [ "$_short" != "$_anchor" ] && [ -d "$WORKTREE/.forge/phases/milestone-$_short" ] && _mdir="$WORKTREE/.forge/phases/milestone-$_short"
-      fi ;;
+    forge/*)
+      _anchor="${_branch#forge/}"                    # m-40 | m-40-a1b2c3d4 | m-EVT01-e6063597
+      _short="${_anchor%-*}"                         # minus one trailing -token (session suffix)
+      for _cand in "$_anchor" "${_anchor#m-}" "$_short" "${_short#m-}"; do
+        [ -n "$_cand" ] || continue
+        if [ -d "$WORKTREE/.forge/phases/milestone-$_cand" ]; then
+          _mdir="$WORKTREE/.forge/phases/milestone-$_cand"
+          break
+        fi
+      done ;;
   esac
   # Fallback (non-git fixture dirs / unconventional branches): a SINGLE milestone dir is
   # unambiguous; several without a branch-derived pick is a refusal, never a guess.

package/template/.forge/checks/tests/forge-jarvis-dispatch.test.sh

@@ -157,6 +157,41 @@ else
   bad "dry-run side effects" "dry-run wrote work-order files"
 fi
 
+# --- 13-14. BRANCH-DERIVED MILESTONE PICK (canvaz first run 2026-07-22): with several
+#     milestone dirs, the forge/{anchor} branch names the one to build. The id's m- may be
+#     strippable (m-40 → milestone-40) or part of a labeled id (m-EVT01 → milestone-m-EVT01);
+#     unconditional stripping refused a clean labeled-id dispatch. These fixtures are real
+#     git repos — cases 9-12 (mktemp dirs) never reach the branch path.
+mkbranch() { git -C "$1" init -q -b "$2" 2>/dev/null || { git -C "$1" init -q && git -C "$1" checkout -q -b "$2"; }; }
+
+# 13. labeled id: forge/m-EVT01-<session> resolves milestone-m-EVT01 (m- is part of the id)
+LSLICE="$ROOT/labeled-wt"
+mkdir -p "$LSLICE/.forge/phases/milestone-m-EVT01/1-evt" "$LSLICE/.forge/phases/milestone-5/1-decoy"
+printf 'evt plan\n' > "$LSLICE/.forge/phases/milestone-m-EVT01/1-evt/plan-01.md"
+printf 'decoy\n'    > "$LSLICE/.forge/phases/milestone-5/1-decoy/plan-01.md"
+mkbranch "$LSLICE" forge/m-EVT01-e6063597
+err13="$(sh "$DISPATCH" --slice "$LSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q '^  - 1-evt$' "$LSLICE/slice.yml" 2>/dev/null \
+   && grep -q 'evt plan' "$LSLICE/phases/1-evt/plan.md" 2>/dev/null && [ ! -d "$LSLICE/phases/1-decoy" ]; then
+  ok "labeled milestone id: branch picks milestone-m-EVT01 among several dirs (m- kept)"
+else
+  bad "labeled-id branch pick" "rc=$rc err=$err13"
+fi
+
+# 14. numeric id + session suffix: forge/m-40-<session> still resolves milestone-40 (m- stripped)
+QSLICE="$ROOT/numeric-wt"
+mkdir -p "$QSLICE/.forge/phases/milestone-40/1-num" "$QSLICE/.forge/phases/milestone-39/1-decoy"
+printf 'num plan\n' > "$QSLICE/.forge/phases/milestone-40/1-num/plan-01.md"
+printf 'decoy\n'    > "$QSLICE/.forge/phases/milestone-39/1-decoy/plan-01.md"
+mkbranch "$QSLICE" forge/m-40-a1b2c3d4
+err14="$(sh "$DISPATCH" --slice "$QSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q '^  - 1-num$' "$QSLICE/slice.yml" 2>/dev/null \
+   && grep -q 'num plan' "$QSLICE/phases/1-num/plan.md" 2>/dev/null && [ ! -d "$QSLICE/phases/1-decoy" ]; then
+  ok "numeric milestone id: branch picks milestone-40 among several dirs (m- stripped)"
+else
+  bad "numeric-id branch pick" "rc=$rc err=$err14"
+fi
+
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]