@limina-labs/momentum 0.33.0 → 0.35.0

package/adapters/antigravity/instructions/AGENTS.md

@@ -638,6 +638,9 @@ Use `infra:` for CI, build, deploy, tooling, and release-pipeline changes that d
 
 ## Project Extensions
 
-> Everything below this heading is preserved across `momentum upgrade`.
-> Add project-specific navigation, rules, cross-repo references, etc. here.
-> Anything above this heading is managed by momentum and may be replaced on upgrade.
+<!-- momentum:project-rules-pointer -->
+> **Project-specific rules live in `specs/project-rules.md`** — read it now.
+> Session-start self-audits, project constraints, and any project-specific
+> guidance are there, shared identically by every agent (ADR-0010). This
+> section is a momentum-managed pointer; edit `specs/project-rules.md`, not
+> this file.

package/adapters/codex/adapter.js

@@ -167,6 +167,10 @@ function transformCommandsIntoSkills(targetDir, recordManaged) {
 
   let count = 0;
   for (const file of fs.readdirSync(commandsDir)) {
+    // Skip macOS AppleDouble sidecars FIRST: `._complete-phase.md` ends with
+    // `.md`, so an endsWith check alone would mint a `._complete-phase/SKILL.md`
+    // junk skill dir (Phase 27 G4 — the source of the ._* skill-dir litter).
+    if (file.startsWith('._') || file === '.DS_Store') continue;
     if (!file.endsWith('.md')) continue;
     const name = file.replace(/\.md$/, '');
     const body = fs.readFileSync(path.join(commandsDir, file), 'utf8');
@@ -223,3 +227,6 @@ function renderSkillMarkdown(name, description, recipeBody) {
     recipeBody.endsWith('\n') ? recipeBody : recipeBody + '\n',
   ].join('\n');
 }
+
+// Phase 27 G4 — exported for the AppleDouble-filter regression test.
+module.exports.transformCommandsIntoSkills = transformCommandsIntoSkills;

package/adapters/codex/instructions/AGENTS.md

@@ -48,7 +48,7 @@ The shipped recipe set (one skill per recipe, all under
 | log | Append a manual narrative entry to the history of the phase bound to your branch (fallback: status.md) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
-| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062) |
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |
@@ -692,6 +692,9 @@ Use `infra:` for CI, build, deploy, tooling, and release-pipeline changes that d
 
 ## Project Extensions
 
-> Everything below this heading is preserved across `momentum upgrade`.
-> Add project-specific navigation, rules, cross-repo references, etc. here.
-> Anything above this heading is managed by momentum and may be replaced on upgrade.
+<!-- momentum:project-rules-pointer -->
+> **Project-specific rules live in `specs/project-rules.md`** — read it now.
+> Session-start self-audits, project constraints, and any project-specific
+> guidance are there, shared identically by every agent (ADR-0010). This
+> section is a momentum-managed pointer; edit `specs/project-rules.md`, not
+> this file.

package/adapters/codex/instructions/surfaces.md

@@ -24,7 +24,7 @@ The shipped recipe set (one skill per recipe, all under
 | log | Append a manual narrative entry to the history of the phase bound to your branch (fallback: status.md) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
-| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062) |
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |

package/adapters/opencode/adapter.js

@@ -173,6 +173,8 @@ function ensureCommandFrontmatter(targetDir) {
   }
   let count = 0;
   for (const file of fs.readdirSync(commandsDir)) {
+    // Skip AppleDouble sidecars first — `._x.md` ends with `.md` (Phase 27 G4).
+    if (file.startsWith('._') || file === '.DS_Store') continue;
     if (!file.endsWith('.md')) continue;
     const filePath = path.join(commandsDir, file);
     const body = fs.readFileSync(filePath, 'utf8');

package/adapters/opencode/instructions/AGENTS.md

@@ -48,7 +48,7 @@ The shipped recipe set (one command per recipe):
 | lanes | Work with lanes — concurrent workstreams in one repo (Rule 15) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
-| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062) |
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |
@@ -605,6 +605,9 @@ Use `infra:` for CI, build, deploy, tooling, and release-pipeline changes that d
 
 ## Project Extensions
 
-> Everything below this heading is preserved across `momentum upgrade`.
-> Add project-specific navigation, rules, cross-repo references, etc. here.
-> Anything above this heading is managed by momentum and may be replaced on upgrade.
+<!-- momentum:project-rules-pointer -->
+> **Project-specific rules live in `specs/project-rules.md`** — read it now.
+> Session-start self-audits, project constraints, and any project-specific
+> guidance are there, shared identically by every agent (ADR-0010). This
+> section is a momentum-managed pointer; edit `specs/project-rules.md`, not
+> this file.

package/adapters/opencode/instructions/surfaces.md

@@ -24,7 +24,7 @@ The shipped recipe set (one command per recipe):
 | lanes | Work with lanes — concurrent workstreams in one repo (Rule 15) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
-| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062) |
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |

package/bin/antigravity.js

@@ -29,6 +29,7 @@ const PLUGIN_NAME = 'momentum';
 function copyDirRecursive(src, dest, dryRun, log) {
   const entries = fs.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
+    if (entry.name.startsWith('._') || entry.name === '.DS_Store') continue; // Phase 27 G4 — no AppleDouble litter
     const s = path.join(src, entry.name);
     const d = path.join(dest, entry.name);
     if (entry.isDirectory()) {

package/bin/ecosystem.js

@@ -24,8 +24,11 @@ const {
   POINTER_END,
   PRIMARY_INSTRUCTION_CANDIDATES,
   findPrimaryInstructionFile,
+  findAllInstructionFiles,
   ensurePointerInjected,
+  ensurePointerInjectedAll,
   stripPointer,
+  stripPointerAll,
 } = require('../core/ecosystem/lib/pointer');
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -616,7 +619,7 @@ function cmdAdd(args) {
     // Idempotent: if the path matches, do nothing. If it differs, fail loud.
     if (existing.path === relPath) {
       console.log(`add: "${id}" is already registered (path ${relPath}). No changes.`);
-      ensurePointerInjected(absRepo, primary, root, manifest.name);
+      ensurePointerInjectedAll(absRepo, root, manifest.name);
       return;
     }
     throw new Error(
@@ -641,11 +644,12 @@ function cmdAdd(args) {
     'utf8',
   );
 
-  // Inject the fenced pointer into the target's primary instruction.
-  ensurePointerInjected(absRepo, primary, root, manifest.name);
+  // Inject the fenced pointer into EVERY instruction file (Phase 28 — every
+  // agent, not just the preferred one).
+  const injected = ensurePointerInjectedAll(absRepo, root, manifest.name);
 
   console.log(`Added member "${id}" (${role}) at ${relPath}.`);
-  console.log(`Pointer injected into ${path.relative(root, path.join(absRepo, primary))}.`);
+  console.log(`Pointer injected into ${injected.map((f) => path.relative(root, path.join(absRepo, f))).join(', ')}.`);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -686,10 +690,7 @@ function cmdRemove(args) {
   // remove must succeed even when the member repo is gone.
   const absRepo = path.resolve(root, member.path);
   if (fs.existsSync(absRepo)) {
-    const primary = findPrimaryInstructionFile(absRepo);
-    if (primary) {
-      stripPointer(path.join(absRepo, primary));
-    }
+    stripPointerAll(absRepo); // Phase 28 — strip from every instruction file
   }
 
   console.log(`Removed member "${id}".`);

package/bin/lanes.js

@@ -18,6 +18,7 @@ const { spawnSync } = require('child_process');
 
 const MOMENTUM_ROOT = path.resolve(__dirname, '..');
 const state = require(path.join(MOMENTUM_ROOT, 'core', 'lanes', 'lib', 'state'));
+const cleanup = require(path.join(MOMENTUM_ROOT, 'core', 'lanes', 'lib', 'cleanup'));
 
 // ─── small helpers ───────────────────────────────────────────────────────
 
@@ -39,7 +40,7 @@ function parseFlags(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--no-worktree' || a === '--rm-worktree' || a === '--execute' ||
-        a === '--force' || a === '--json' || a === '--ack-all') {
+        a === '--force' || a === '--json' || a === '--ack-all' || a === '--no-remote') {
       flags[a.slice(2)] = true;
     } else if (a.startsWith('--')) {
       flags[a.slice(2)] = argv[++i];
@@ -197,7 +198,7 @@ function cmdDone(cwd, argv) {
 function cmdClose(cwd, argv) {
   const { flags, positional } = parseFlags(argv);
   const id = positional[0];
-  if (!id) return fail('usage: momentum lanes close <lane-id> [--rm-worktree]');
+  if (!id) return fail('usage: momentum lanes close <lane-id> [--rm-worktree] [--force] [--no-remote]');
   const anchor = requireAnchor(cwd);
   if (!anchor) return;
   let lane;
@@ -206,10 +207,21 @@ function cmdClose(cwd, argv) {
   } catch (err) {
     return fail(err.message);
   }
-  if (flags['rm-worktree'] && lane.worktree) {
-    const res = git(cwd, 'worktree', 'remove', lane.worktree, '--force');
-    if (res.status === 0) console.log(`✓ worktree removed: ${lane.worktree}`);
-    else console.log(`⚠ could not remove worktree (${res.stderr.trim()}) — remove manually`);
+  // ENH-063: close does FULL cleanup — local + remote branch (default-branch-
+  // safe) + lane state, plus the worktree with --rm-worktree. Best-effort: an
+  // unmerged branch is refused (never force-deleted) but that does not fail close.
+  const res = cleanup.cleanupTarget({
+    cwd,
+    branch: lane.branch,
+    worktree: flags['rm-worktree'] ? lane.worktree : null,
+    laneId: id,
+    deleteRemote: !flags['no-remote'],
+    force: Boolean(flags.force),
+  });
+  const glyph = { removed: '✓', deleted: '✓', cleared: '✓', skipped: 'ℹ', blocked: '⚠' };
+  for (const a of res.actions) console.log(`  ${glyph[a.status] || '·'} ${a.step}: ${a.detail}`);
+  if (!res.ok) {
+    console.log(`⚠ some cleanup refused (${res.blocked.join(', ')}) — e.g. an unmerged branch; rerun with --force only if intended`);
   }
   console.log(`✓ lane '${id}' closed`);
 }
@@ -243,6 +255,13 @@ Usage:
   momentum lanes land <id> [--into <ref>] [--execute] [--force] [--mark-landed]
       --mark-landed      bookkeeping only: record an out-of-band merge that
                          already happened (done + merged lane → landed)
+  momentum lanes cleanup <branch> [--worktree P] [--lane ID] [flags]
+      Remove a spent branch's worktree + branch + lane state, default-branch-safe
+      --no-remote  skip origin delete   --force  allow -D / dirty worktree
+      --dry-run    report only          --keep-state  leave lane dir untouched
+  momentum lanes reconcile [--execute] [--into <ref>] [--json]
+      Sweep landed/merged lanes whose terminal merge happened out-of-band
+      (human/forge) and clean them once verified contained in <ref>
 
 State lives at <git-common-dir>/momentum/lanes — shared by all worktrees,
 untracked, no daemon. Substrate: plain git worktrees by default; treehouse
@@ -287,6 +306,10 @@ function dispatch(argv, cwd) {
       return delegate('signals', 'cmdInbox', rest);
     case 'land':
       return delegate('land', 'cmdLand', rest);
+    case 'cleanup':
+      return delegate('cleanup', 'cmdCleanup', rest);
+    case 'reconcile':
+      return delegate('reconcile', 'cmdReconcile', rest);
     case '--help':
     case '-h':
     case 'help':

package/bin/momentum.js

@@ -1348,11 +1348,32 @@ function upgrade(targetDir, agent, opts = {}) {
   // would dirty files mid-upgrade and break autostash restores).
   const pointerLib = require('../core/ecosystem/lib/pointer');
   const primaryRel = adapter.primaryInstruction.destination.join('/');
+
+  // Phase 28 (ADR-0010): migrate any authored `## Project Extensions` prose into
+  // specs/project-rules.md and rewrite that section as the managed pointer,
+  // BEFORE the marker-aware rewrite preserves it. Migrate-never-drop, idempotent.
+  if (!_dryRun) {
+    const projectRules = require('../core/lib/project-rules');
+    const migRes = projectRules.migrateProjectExtensions(
+      path.join(target, primaryRel),
+      path.join(target, 'specs'),
+      { projectName: getProjectName(target) }
+    );
+    if (migRes.appended) {
+      console.log(`  ↳ migrated ${primaryRel} Project Extensions → specs/project-rules.md (ADR-0010)`);
+    }
+  }
+
+  // Snapshot whether THIS agent's instruction file carries the pointer BEFORE
+  // the managed rewrite — we only ever PRESERVE it (BUG-022), never add one the
+  // file didn't have (adding would dirty files mid-upgrade and break autostash
+  // restores). Phase 28: since `upgrade` now runs per installed agent (G1), this
+  // preserves every agent's pointer; ADDING a missing pointer (cause #2) is
+  // `momentum ecosystem add`'s job, which now injects into all instruction files.
   let hadPointerBlock = false;
   try {
-    hadPointerBlock = pointerLib.POINTER_BEGIN_RE.test(
-      fs.readFileSync(path.join(target, primaryRel), 'utf8')
-    );
+    hadPointerBlock = fs.readFileSync(path.join(target, primaryRel), 'utf8')
+      .includes(pointerLib.POINTER_BEGIN_PREFIX);
   } catch (_e) { /* absent file → nothing to preserve */ }
 
   // Upgrade adapter-owned root instruction file
@@ -1620,6 +1641,7 @@ Ecosystem use — entry/exit commands (run from any repo):
                                       existing ecosystem
   momentum leave                      Detach THIS repo from its ecosystem
   momentum doctor                     Diagnose state + list available transitions
+  momentum doctor --clean [--execute] Sweep stray artifacts (AppleDouble/.bak/orphan worktrees)
   momentum antigravity plugin-pack    Pack momentum skills as a native Antigravity plugin ([--global])
 
 Ecosystem use — operator toolkit (advanced):
@@ -1982,12 +2004,27 @@ async function main() {
       // upgrade can only ever install files as new as the CLI itself.
       const staleWarning = formatStaleCliWarning(pkg.version, await updateCheckPromise);
       if (staleWarning) console.log(staleWarning);
-      // --autostash: stash a dirty tree, upgrade, restore. Dry-run writes
-      // nothing, so it never needs to stash.
+      // Phase 28 (ADR-0010): with no explicit --agent, refresh EVERY installed
+      // agent so no agent's instruction file silently drifts (cause #1 of the
+      // CLAUDE.md/AGENTS.md divergence). Explicit --agent targets that one.
+      let agentsToUpgrade;
+      if (agentExplicit) {
+        agentsToUpgrade = [agent];
+      } else {
+        const installed = loadInstalledState(path.resolve(targetDir));
+        const names = Object.keys(installed.agents || {});
+        agentsToUpgrade = names.length ? names : [agent];
+      }
+      if (agentsToUpgrade.length > 1) {
+        console.log(`Upgrading all installed agents: ${agentsToUpgrade.join(', ')}\n`);
+      }
+      // --autostash: stash a dirty tree, upgrade, restore — once around all
+      // agents. Dry-run writes nothing, so it never needs to stash.
+      const runAll = () => { for (const a of agentsToUpgrade) upgrade(targetDir, a, { dryRun }); };
       if (autostash && !dryRun) {
-        withAutostash(path.resolve(targetDir), () => upgrade(targetDir, agent, { dryRun }));
+        withAutostash(path.resolve(targetDir), runAll);
       } else {
-        upgrade(targetDir, agent, { dryRun });
+        runAll();
       }
     } catch (err) {
       console.error(`\nError: ${err.message}`);

package/bin/state-commands.js

@@ -103,10 +103,9 @@ function cmdLeave(args) {
   }
 
   if (state === 'broken-pointer') {
-    // Pointer present but no registration. Just strip pointer to recover.
-    const primary = pointerLib.findPrimaryInstructionFile(cwd);
-    if (primary) {
-      pointerLib.stripPointer(path.join(cwd, primary));
+    // Pointer present but no registration. Strip from every instruction file.
+    const stripped = pointerLib.stripPointerAll(cwd);
+    if (stripped.length) {
       console.log('Stripped dangling pointer. Now standalone.');
     } else {
       console.log('No pointer block found. No changes.');
@@ -129,8 +128,103 @@ function cmdLeave(args) {
   console.log(`✓ Left "${reg.ecosystemName}". Now standalone.`);
 }
 
+// ── Phase 27 G4 — stray-artifact sweep (`momentum doctor --clean`) ──────────
+
+const BAK_ROOTS = ['.claude', '.agents', '.opencode', '.codex', '.githooks', 'scripts'];
+
+/** Bounded walk collecting AppleDouble sidecars anywhere (always junk). */
+function walkAppleDouble(dir, acc, depth) {
+  if (depth > 8) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (e.name === '.git' || e.name === 'node_modules') continue;
+    const abs = path.join(dir, e.name);
+    if (e.name.startsWith('._') || e.name === '.DS_Store') { acc.appleDouble.push(abs); continue; }
+    if (e.isDirectory()) walkAppleDouble(abs, acc, depth + 1);
+  }
+}
+
+/** `.bak` files under a momentum-managed root only (never user backups). */
+function collectBaks(dir, acc, depth) {
+  if (depth > 8) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) collectBaks(abs, acc, depth + 1);
+    else if (e.name.endsWith('.bak')) acc.baks.push(abs);
+  }
+}
+
+/** Find stray artifacts: AppleDouble, momentum `.bak` litter, orphan worktrees. */
+function findStrayArtifacts(root) {
+  const { spawnSync } = require('child_process');
+  const acc = { appleDouble: [], baks: [], prunableWorktrees: [], orphanWorktreeDirs: [] };
+  walkAppleDouble(root, acc, 0);
+  for (const sub of BAK_ROOTS) collectBaks(path.join(root, sub), acc, 0);
+  for (const f of ['CLAUDE.md.bak', 'AGENTS.md.bak']) {
+    const p = path.join(root, f);
+    if (fs.existsSync(p)) acc.baks.push(p);
+  }
+  // registered worktrees whose directory is gone → prunable
+  const registered = new Set();
+  const wl = spawnSync('git', ['worktree', 'list', '--porcelain'], { cwd: root, encoding: 'utf8' });
+  if (wl.status === 0) {
+    for (const line of wl.stdout.split('\n')) {
+      if (line.startsWith('worktree ')) {
+        const p = line.slice('worktree '.length);
+        registered.add(realpathOf(p));
+        if (p !== root && !fs.existsSync(p)) acc.prunableWorktrees.push(p);
+      }
+    }
+  }
+  // .claude/worktrees/* leftover dirs not registered as git worktrees
+  const cw = path.join(root, '.claude', 'worktrees');
+  try {
+    for (const name of fs.readdirSync(cw)) {
+      const abs = path.join(cw, name);
+      if (fs.statSync(abs).isDirectory() && !registered.has(realpathOf(abs))) acc.orphanWorktreeDirs.push(abs);
+    }
+  } catch { /* no .claude/worktrees */ }
+  return acc;
+}
+
+function sweepStrayArtifacts(root, execute) {
+  const { spawnSync } = require('child_process');
+  const stray = findStrayArtifacts(root);
+  const total = stray.appleDouble.length + stray.baks.length
+    + stray.prunableWorktrees.length + stray.orphanWorktreeDirs.length;
+  const rel = (p) => path.relative(root, p) || p;
+
+  console.log(execute ? 'Cleaning stray artifacts:' : 'Stray artifacts (dry-run — pass --execute to remove):');
+  if (total === 0) { console.log('  ✓ none — tree is clean'); return 0; }
+
+  for (const p of stray.appleDouble) {
+    if (execute) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* ignore */ } }
+    console.log(`  ${execute ? '✓ removed' : '·'} AppleDouble: ${rel(p)}`);
+  }
+  for (const p of stray.baks) {
+    if (execute) { try { fs.rmSync(p, { force: true }); } catch { /* ignore */ } }
+    console.log(`  ${execute ? '✓ removed' : '·'} .bak: ${rel(p)}`);
+  }
+  for (const p of stray.orphanWorktreeDirs) {
+    if (execute) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* ignore */ } }
+    console.log(`  ${execute ? '✓ removed' : '·'} orphan worktree dir: ${rel(p)}`);
+  }
+  if (stray.prunableWorktrees.length) {
+    if (execute) spawnSync('git', ['worktree', 'prune'], { cwd: root });
+    for (const p of stray.prunableWorktrees) console.log(`  ${execute ? '✓ pruned' : '·'} stale worktree ref: ${rel(p)}`);
+  }
+  console.log(execute ? `✓ cleaned ${total} stray artifact(s)` : `${total} stray artifact(s) — rerun with --execute to remove`);
+  return 0;
+}
+
 function cmdDoctor(args) {
-  void args;
+  // Phase 27 G4 — `momentum doctor --clean [--execute]` sweeps stray artifacts.
+  if (args && args.includes('--clean')) {
+    return sweepStrayArtifacts(realpathOf(process.cwd()), args.includes('--execute'));
+  }
   const cwd = realpathOf(process.cwd());
   lib._clearRootCache();
   const state = stateLib.detectState(cwd);
@@ -176,6 +270,17 @@ function cmdDoctor(args) {
     }
   } catch (_err) { /* advisory is best-effort — never block doctor */ }
 
+  // Phase 27 G4 — stray-artifact advisory (best-effort, non-blocking).
+  try {
+    const stray = findStrayArtifacts(cwd);
+    const n = stray.appleDouble.length + stray.baks.length
+      + stray.prunableWorktrees.length + stray.orphanWorktreeDirs.length;
+    if (n > 0) {
+      console.log(`Advisory: ${n} stray artifact(s) (AppleDouble / .bak / orphan worktrees) — run \`momentum doctor --clean\` to review, \`--clean --execute\` to remove.`);
+      console.log('');
+    }
+  } catch { /* best-effort */ }
+
   const transitions = stateLib.availableTransitions(state, reg || {});
   if (transitions.length === 0) {
     console.log('No suggested next steps for this state.');
@@ -215,4 +320,6 @@ module.exports = {
   cmdLeave,
   cmdDoctor,
   formatStateLabel,
+  findStrayArtifacts,
+  sweepStrayArtifacts,
 };

package/core/commands/complete-phase.md

@@ -53,22 +53,34 @@ Verify, finalize, and release a completed phase.
      - Format as fenced code blocks with the command as the heading
      - This is the durable record that Rule 12 was honored — it must exist before the release section runs
 
-7. Update all tracking:
+7. Update all tracking (this happens BEFORE the release — see the Release
+   gate below; the release must never precede tracking):
    - `specs/phases/README.md` → mark `Complete`
-   - `specs/status.md` → remove this lane's row from the Active Phase table
-     (leave other lanes' rows untouched — Rule 15), update current phase,
-     add release version
-   - `specs/planning/roadmap.md` → update phase status
+   - `specs/status.md` → (a) header **`Latest Release`** = this version + name;
+     (b) add the phase's row to the **Completed Phases** table; (c) remove this
+     lane's row from the Active Phase table (leave other lanes' rows untouched —
+     Rule 15); (d) update Current Phase
+   - `specs/planning/roadmap.md` → update phase status → Complete (+ version)
    - `specs/changelog/YYYY-MM.md` → add release entry
 
 ### Release
 
-> **Gate (Rule 12):** Do NOT enter Release if `retrospective.md` lacks a `## Verification Evidence` section. If evidence is missing, return to Step 3 and capture it.
-
-8. Commit all remaining changes and push:
+> **Gate A (Rule 12):** Do NOT enter Release if `retrospective.md` lacks a `## Verification Evidence` section. If evidence is missing, return to Step 3 and capture it.
+>
+> **Gate B (tracking-before-release):** Do NOT merge, tag, or release until ALL
+> tracking that reflects this release (Step 7 — `status.md` `Latest Release` +
+> Completed Phases row, `specs/phases/README.md`, `roadmap.md`, the changelog)
+> is written AND committed on the phase branch (Step 8). The release must never
+> precede tracking — otherwise `status.md` says "in progress" while the tag is
+> already public. Confirm the working tree is clean of tracking edits (Step 8
+> committed them) before Step 9's approval and Step 10's merge/tag.
+
+8. Commit all remaining changes (retrospective + ALL Step-7 tracking) and push.
+   This commit MUST land before the merge/tag — it is Gate B:
    ```bash
    git add -A
    git commit -m "docs: complete Phase N - {phase name}"
+   git status --porcelain   # expect empty — tracking is committed (Gate B satisfied)
    git push origin phase-N-shortname
    ```
 
@@ -77,7 +89,7 @@ Verify, finalize, and release a completed phase.
    `[staging, main]`) in order. The plan stops at the universal git primitives
    (`git merge` + `git tag -a` + `git push origin <tag>`); forge-specific
    release creation and registry publishes are NOT listed here — they run
-   from `## Project Extensions` + `specs/config.md` (`release_command`,
+   from `specs/project-rules.md` + `specs/config.md` (`release_command`,
    `publish_target`, `release_flow`) after the tag is pushed.
    ```
    Ready to release vX.Y.Z. This will:
@@ -86,7 +98,7 @@ Verify, finalize, and release a completed phase.
      3. Tag vX.Y.Z and push the tag
 
    Project-specific release/publish/deploy (forge release, npm publish, …)
-   run from ## Project Extensions + specs/config.md after the tag lands.
+   run from specs/project-rules.md + specs/config.md after the tag lands.
 
    Proceed?
    ```
@@ -114,35 +126,60 @@ Verify, finalize, and release a completed phase.
     git push origin <branch_flow[1]>
 
     # final step — tag + push the tag (universal git; forge release + publish
-    # are project-specific — run them from ## Project Extensions now)
+    # are project-specific — run them from specs/project-rules.md now)
     git tag -a vX.Y.Z -m "Phase N: {phase name}"
     git push origin vX.Y.Z
     ```
-    For `end_state: feature-branch-only` (config), SKIP the merge
-    sequence — the branch is already pushed; only tag (if the project tags
-    releases on the feature branch) per `## Project Extensions`. For
-    `end_state: staging-promotion`, merge to `branch_flow[0]` only and stop;
-    tag + release happen after the user promotes to `main`.
+    **`end_state` variants** (config; the sequence above is the
+    `merge-after-yes` default):
+    - `feature-branch-only` — SKIP the merge/tag; the branch is pushed, the
+      human owns merge + release.
+    - `staging-promotion` — merge to `branch_flow[0]` only, then STOP; the human
+      promotes to `main` and tags.
+    - `open-pr` — do NOT merge; push the branch and open a PR for review
+      (config-gated, agent-run — `git_forge=github`: `gh pr create`; GitLab:
+      `glab mr create`), then STOP. Merge happens on the forge on human approval.
+
+    **Human handshake → verify → clean** (every non-`merge-after-yes`
+    end_state). Step-13 auto-cleanup only fires when the AGENT did the terminal
+    merge. When a human/forge does it, NEVER clean on trust: ask the user to
+    confirm once they have merged/promoted, then verify + clean in one step —
+    ```bash
+    momentum lanes reconcile            # is the branch a verified ancestor of the terminal branch yet?
+    momentum lanes reconcile --execute  # only once it shows 'landed' — cleans worktree + branch + state
+    ```
+    `reconcile` refuses to clean a lane whose branch is not yet contained in the
+    terminal branch — a "yes, I merged it" is never taken on trust (Rule 12).
 
 12. Report summary to user:
     - What was delivered
     - Tag URL (`git push origin vX.Y.Z` output) — forge release/publish
-      status from `## Project Extensions` if any ran
+      status from `specs/project-rules.md` if any ran
     - What's next
 
-13. Delete the merged phase branch (ENH-042 — now that merge → main + release
-    are confirmed; do NOT skip this, or stale branches accumulate on origin):
+13. Clean up the spent phase branch (ENH-042 / BUG-026 — now that merge → main
+    + release are confirmed; do NOT skip, or stale branches/worktrees/state
+    accumulate). One command removes ALL of it, default-branch-safe:
     ```bash
-    git branch -d phase-N-shortname             # local — `-d` (not `-D`) refuses if unmerged
-    git push origin --delete phase-N-shortname  # remote
+    # worktree (if the phase ran in a lane) + local branch + remote branch
+    # (skipped when it is the forge default — BUG-025 guard) + lane state.
+    momentum lanes cleanup phase-N-shortname
+    #   --lane <id>   if this phase ran as a registered `momentum lanes` lane
+    #   --force       only to override an unmerged-branch refusal AFTER you have
+    #                 verified the branch actually landed
     ```
+    If cleanup reports `blocked` on the remote branch because it is the forge
+    DEFAULT, STOP — that is the BUG-025 hijack. Reassign the default to the
+    terminal branch first (e.g. `git_forge=github`: `gh repo edit
+    --default-branch main`), then rerun. `-d` (not `-D`) refuses an unmerged
+    branch by design — investigate rather than force.
 
 14. Branch-hygiene self-audit (ENH-042) — confirm no released phase left a
-    dangling branch:
+    dangling branch or worktree:
     ```bash
-    # Any origin branch for an already-released phase should be gone.
     git branch -r | grep -E 'origin/(phase-|chore/|audit/)' || echo "✓ clean — no stale branches"
+    git worktree list                                        # no leftover lane worktrees for landed work
     ```
-    For each match, verify it is fully merged into `main`
-    (`git branch -r --merged main`) and delete it per step 13. Leave any
+    For each stale match, verify it is fully merged into `main`
+    (`git branch -r --merged main`) and clean it per step 13. Leave any
     *unmerged* branch alone and surface it to the user.

package/core/commands/lanes.md

@@ -75,7 +75,7 @@ landing) and ack what you've acted on.
 momentum lanes done <id>          # enter the landing queue
 momentum lanes land <id>          # validate: turn, freshness, graded gate
 momentum lanes land <id> --execute# merge --no-ff into the CURRENT branch
-momentum lanes close <id> [--rm-worktree]
+momentum lanes close <id> [--rm-worktree]   # retire: full cleanup (branch + state)
 ```
 
 Landing follows the Rule 6 **Landing Order**: one lane at a time, run the
@@ -87,6 +87,23 @@ with a non-empty `## Verification Evidence` section (Rule 12).
 `land` never pushes — pushes to protected branches keep their own
 approval gate.
 
+### Cleanup — a landed lane is spent (BUG-026)
+
+```bash
+momentum lanes reconcile             # report lanes now merged out-of-band (human/forge)
+momentum lanes reconcile --execute   # clean them: worktree + branch + state
+momentum lanes cleanup <branch> [--worktree P] [--dry-run]   # one branch, manually
+```
+
+When the AGENT lands on the terminal branch (`branch_flow` last entry),
+`land --execute` **auto-cleans** the worktree + branch + lane state
+(default-branch-safe; `--keep` opts out). When a HUMAN or the FORGE does
+the terminal merge (`end_state` `staging-promotion` / `feature-branch-only`
+/ `open-pr`), cleanup is deferred: run `momentum lanes reconcile` — it
+cleans only lanes whose branch is a **verified ancestor** of the terminal
+branch (a "yes, I merged it" is never trusted, Rule 12). Cleanup never
+deletes a branch that is the forge default (the BUG-025 guard).
+
 ## Tracking
 
 Opening/closing lanes is not itself phase history; the WORK inside a lane