forge-orkes 0.19.0 → 0.19.2

package/bin/create-forge.js

@@ -18,6 +18,29 @@ const FORGE_END = '<!-- forge:end -->';
 // Framework-owned: Forge controls these entirely
 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.
+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);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
 // Template-only: reference templates Forge controls
 const TEMPLATE_ONLY_DIRS = ['.forge/templates', '.forge/migrations'];
 
@@ -106,7 +129,7 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
   const srcDir = path.join(templateDir, relDir);
   const destDir = path.join(targetDir, relDir);
 
-  const result = { updated: [], added: [], unchanged: [], removed: [] };
+  const result = { updated: [], added: [], unchanged: [], removed: [], preserved: [] };
 
   if (!fs.existsSync(srcDir)) return result;
 
@@ -138,6 +161,12 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
   for (const rel of destFiles) {
     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);
+        continue;
+      }
       const destPath = path.join(destDir, rel);
       if (autoClean) {
         fs.unlinkSync(destPath);
@@ -381,7 +410,7 @@ function detectLegacyStateIndex() {
   }
 
   // Legacy markers: shared accumulators or per-milestone narrative drifted in.
-  if (/^\s*desire_paths:|^\s*metrics:|current_status:/m.test(content)) return true;
+  if (/^\s*(desire_paths|metrics|current_status):/m.test(content)) return true;
   // A slim registry is small; KBs of index.yml means narrative crept in.
   if (Buffer.byteLength(content, 'utf-8') > 4096) return true;
 
@@ -468,11 +497,28 @@ async function upgrade() {
   console.log(`  Installed: v${installedVersion}`);
   console.log(`  Available: v${pkgVersion}\n`);
 
+  // Downgrade guard: refuse to roll backward (overwrites newer framework files
+  // with older ones and deletes files newer versions added). Almost always a
+  // stale npx cache serving an old forge-orkes. Override with --force.
+  const force = process.argv.includes('--force');
+  if (
+    installedVersion !== 'unknown' &&
+    compareVersions(pkgVersion, installedVersion) < 0 &&
+    !force
+  ) {
+    console.error(`  ✖ Refusing to downgrade: installed v${installedVersion} is newer than available v${pkgVersion}.`);
+    console.error(`    This usually means a stale npx cache served an old forge-orkes.`);
+    console.error(`    Fix:  npx forge-orkes@latest upgrade   (or clear the cache: rm -rf ~/.npm/_npx)`);
+    console.error(`    To downgrade intentionally: forge-orkes upgrade --force\n`);
+    process.exit(1);
+  }
+
   const results = {
     updated: [],
     added: [],
     unchanged: [],
     removed: [],
+    preserved: [],
   };
 
   // 1. Process framework-owned directories (auto-clean stale files)
@@ -482,6 +528,7 @@ async function upgrade() {
     results.added.push(...dirResult.added);
     results.unchanged.push(...dirResult.unchanged);
     results.removed.push(...dirResult.removed);
+    results.preserved.push(...dirResult.preserved);
   }
 
   // 2. Process template-only directories
@@ -491,6 +538,7 @@ async function upgrade() {
     results.added.push(...dirResult.added);
     results.unchanged.push(...dirResult.unchanged);
     results.removed.push(...dirResult.removed);
+    results.preserved.push(...dirResult.preserved);
   }
 
   // 2b. Sync the forge .gitignore. Shipped as `gitignore` (npm strips dotfiles
@@ -560,6 +608,14 @@ async function upgrade() {
     console.log();
   }
 
+  if (results.preserved.length > 0) {
+    console.log(`  Preserved (${results.preserved.length}):`);
+    for (const f of results.preserved) {
+      console.log(`    ${f} (kept — opt-in experimental skill)`);
+    }
+    console.log();
+  }
+
   console.log(`  Upgraded to v${pkgVersion}\n`);
 
   runPostUpgradeMigrationChecks();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.19.0",
+  "version": "0.19.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/skills/forge/SKILL.md

@@ -15,13 +15,13 @@ Entry point. Detect tier, route skills, manage transitions. New projects → ini
 
 Rollup procedure (deterministic + idempotent):
 1. Glob `.forge/state/milestone-*.yml`.
-2. For each, read `milestone.id`, `milestone.name`, `current.status`, `lifecycle.{deferred_at, resumed_at}`, `current.last_updated`.
+2. For each, read `milestone.id`, `milestone.name`, `current.status`, `lifecycle.{deferred_at, resumed_at}`, and the last-touched date as `current.last_updated` → else legacy `progress.last_update` → else null. (The fallback keeps pre-0.19.0 milestone files self-sourcing without editing them; active milestones gain `current.last_updated` on their next transition.)
 3. Derive the registry `status`:
    - **deferred** — `lifecycle.deferred_at` set and not superseded by a later `resumed_at`
    - **complete** — `current.status == complete`
    - **not_started** — `current.status == not_started`
    - **active** — otherwise
-4. Rewrite `index.yml` `milestones:` (sorted by id) as `{id, name, status, last_updated: current.last_updated}`. No other keys.
+4. Rewrite `index.yml` `milestones:` (sorted by id) as `{id, name, status, last_updated}` (date from step 2's fallback). No other keys.
 
 Output is a pure function of the milestone files, so two sessions regenerating it produce identical bytes — it never needs a hand-merge. **Only the main/orchestrator session runs rollup; worktree agents never write `index.yml`** (they edit only their own `milestone-{id}.yml`).
 

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

@@ -18,6 +18,10 @@ Check if `.forge/dev-source` exists in the project root.
 
 Template directory: `{source}/packages/create-forge/template/`.
 
+### Downgrade guard
+
+Read the source version (`{source}/packages/create-forge/package.json` `version`) and the installed version (`.claude/settings.json` `forge.version`). **If source < installed, STOP** — do not sync. Report: *"Refusing to downgrade: installed v{installed} is newer than source v{source}. Point dev-source at a newer checkout, or confirm an intentional downgrade."* Only proceed on explicit user override. (Rolling backward overwrites newer framework files and deletes files newer versions added — and with `.claude/` often gitignored, it is unrecoverable.)
+
 ## Step 2: File Classification
 
 | Category | Paths | Behavior |
@@ -28,6 +32,8 @@ Template directory: `{source}/packages/create-forge/template/`.
 
 **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
+**Preserve experimental skills.** Opt-in skills installed separately (e.g. `.claude/skills/orchestrating/` from `experimental/m10/`) are not in the base template. Never flag them as "removed from template" or delete them — leave them untouched.
+
 ## Step 3: Sync Framework-Owned Files
 
 For each framework-owned file in the source template:
@@ -152,7 +158,7 @@ Add the layers field now? (yes/no/show guide)
 Run from project root:
 
 ```bash
-grep -qE 'desire_paths:|metrics:|current_status:' .forge/state/index.yml && echo "legacy index"
+grep -qE '^[[:space:]]*(desire_paths|metrics|current_status):' .forge/state/index.yml && echo "legacy index"
 wc -c .forge/state/index.yml   # slim registry is a few hundred bytes; KBs = narrative drifted in
 ```
 

package/template/.forge/migrations/0.19.0-worktree-safe-state.md

@@ -20,9 +20,10 @@ Two problems this release fixes:
 ## Detection
 
 ```bash
-# Bloated/legacy index.yml — large, or still carrying desire_paths/metrics/narrative
+# Bloated/legacy index.yml — large, or still carrying the metrics/desire-paths/narrative blocks
 wc -c .forge/state/index.yml                 # » a few hundred bytes once migrated; KBs means legacy
-grep -nE 'desire_paths:|metrics:|current_status:' .forge/state/index.yml   # any hit → migrate
+# Anchored so the file's own explanatory comments don't false-positive:
+grep -nE '^[[:space:]]*(desire_paths|metrics|current_status):' .forge/state/index.yml   # any hit → migrate
 ```
 
 The installer also prints a notice after `upgrade` when it detects a legacy `index.yml`.
@@ -60,7 +61,13 @@ For each entry under the old `desire_paths:` lists, create one file under `.forg
 .forge/state/desire-paths/{YYYY-MM-DD}-{type}-{milestone}-{slug}.yml
 ```
 
-Map the old list name to `type` (`deviation_patterns→deviation_pattern`, `tier_overrides→tier_override`, etc.). An old `occurrences: N` becomes **N files** (or one file plus a note — recurrence is now derived by counting files, not a stored number). Then delete the `desire_paths:` block from `index.yml`.
+Map the old list name to `type` (`deviation_patterns→deviation_pattern`, `tier_overrides→tier_override`, etc.). Migrate **one file per entry** — do *not* fabricate one-file-per-occurrence. The old `occurrences: N` is only an aggregate; collapse it to a single file and keep the count in a field (e.g. `detail.historical_occurrences: N`) if you want it. Forward recurrence is counted from *new* files.
+
+**Resolved vs open:**
+- **Still-open / could-recur** → file under `.forge/state/desire-paths/` (counts toward the future 3+ detection).
+- **Already resolved** (pattern fixed / framework already evolved) → file under `.forge/state/desire-paths/resolved/`. The active check globs `desire-paths/*.yml` (top level only), so `resolved/` is preserved for the audit trail but excluded from the count — matching how the `forge` skill archives resolved groups.
+
+Then delete the `desire_paths:` block from `index.yml`.
 
 ### 4. Drop `metrics:`
 
@@ -78,14 +85,18 @@ git commit -m "chore(forge): migrate to worktree-safe state (0.19.0)"
 ## Post-migration verification
 
 ```bash
-# index.yml is small and registry-only
-grep -qE 'desire_paths:|metrics:|current_status:' .forge/state/index.yml && echo "STILL LEGACY" || echo "OK: registry-only"
+# index.yml is registry-only — parse the YAML and check actual keys (a text grep
+# false-positives on the file's explanatory comments). Uses ruby (no pip yaml needed):
+ruby -ryaml -e 'd=YAML.load_file(".forge/state/index.yml"); bad=d.key?("metrics")||d.key?("desire_paths")||(d["milestones"]||[]).any?{|m| m.is_a?(Hash) && (m.key?("current_status")||m.key?("overall_percent"))}; puts bad ? "STILL LEGACY" : "OK: registry-only"'
+
+# (grep alternative — anchored + comment-stripped so it doesn't match the header)
+grep -vE '^[[:space:]]*#' .forge/state/index.yml | grep -qE '^[[:space:]]*(desire_paths|metrics|current_status):' && echo "STILL LEGACY" || echo "OK: registry-only"
 
 # rollup is idempotent — running /forge twice produces no diff to index.yml
 git diff --quiet .forge/state/index.yml && echo "OK: stable" || echo "rollup changed index — commit it"
 
-# desire-paths now live as files
-ls .forge/state/desire-paths/ 2>/dev/null
+# desire-paths now live as files (active at top level, resolved/ archived separately)
+ls .forge/state/desire-paths/ .forge/state/desire-paths/resolved/ 2>/dev/null
 ```
 
 ## What changes downstream

package/template/.forge/templates/state/index.yml

@@ -17,8 +17,9 @@ milestones:                            # Registry rolled up from state/milestone
     status: not_started                # mirrors current.status: not_started | active | deferred | complete
     last_updated: null                 # mirrors current.last_updated — used for resume default selection
 
-# NOTE — removed from this file by design (M11):
-#   metrics:      had zero writers; derive from `git log` if ever needed.
-#   desire_paths: now append-only files under state/desire-paths/ (one per
-#                 observation) so concurrent agents never collide. Occurrence
-#                 counts are derived by globbing that directory, not mutated here.
+# NOTE — removed from this file by design (M11). (Tokens below are spaced to
+# avoid tripping naive legacy-detection greps that scan for "<key>:".)
+#   metrics    — had zero writers; derive from `git log` if ever needed.
+#   desire-paths — now append-only files under state/desire-paths/ (one per
+#                  observation) so concurrent agents never collide. Occurrence
+#                  counts are derived by globbing that directory, not mutated here.