@limina-labs/momentum 0.33.0 → 0.34.0

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/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/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/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

@@ -1620,6 +1620,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):

package/bin/state-commands.js

@@ -129,8 +129,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 +271,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 +321,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
    ```
 
@@ -118,11 +130,26 @@ Verify, finalize, and release a completed phase.
     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
@@ -130,19 +157,29 @@ Verify, finalize, and release a completed phase.
       status from `## Project Extensions` 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

package/core/commands/start-phase.md

@@ -87,7 +87,19 @@ After setup, **executes the plan end-to-end autonomously** — no per-group appr
 
 9. Create git branch and initial commit:
    ```bash
-   git checkout main && git pull origin main
+   git checkout main
+   # Resilient when 'main' is unborn on the remote (fresh repo — BUG-025):
+   git ls-remote --heads origin main | grep -q . && git pull origin main || true
+   # BUG-025 safety net: the terminal branch must ALREADY be the remote default
+   # before ANY phase branch is pushed (founding normally established it). If it
+   # is still not on origin, establish it FIRST so phase-N can't hijack default:
+   if git remote get-url origin >/dev/null 2>&1 && ! git ls-remote --heads origin main | grep -q .; then
+     touch .momentum/merge-approved && git push -u origin main && git remote set-head origin main 2>/dev/null || true
+   fi
+   # Optional forge repair (only when git_forge=github AND gh is on PATH;
+   # non-fatal; idempotent). Fixes a repo whose default was ALREADY hijacked.
+   # Agent-run recipe step — momentum ships no forge code, stays forge-neutral:
+   command -v gh >/dev/null 2>&1 && gh repo edit --default-branch main 2>/dev/null || true
    git checkout -b phase-N-shortname
    git add specs/
    git commit -m "docs: start Phase N - {phase name}"
@@ -135,6 +147,10 @@ defaults below) and ask the user the gate question matching the project's
 - **`feature-branch-only`**: "All groups complete and verified. The feature
   branch `<phase-branch>` is pushed. Merge, tag, and release are yours to
   do. Review the branch?"
+- **`open-pr`**: "All groups complete and verified. Ready to push
+  `<phase-branch>` and open a PR for review? Merge + release happen when a
+  human approves and merges the PR on the forge; then `momentum lanes
+  reconcile --execute` cleans up the branch + worktree + state."
 
 Then append: "Project-specific release/publish/deploy steps (e.g.
 `npm publish`, forge release creation) run from `## Project Extensions` in

package/core/commands/start-project.md

@@ -96,7 +96,9 @@ If you're still exploring the idea, run `/brainstorm-idea` first.
     ```
     (On a brand-new repo this may be the first content commit on the default
     branch — the bootstrap exception to Rule 6. On a repo with existing code,
-    normal branch discipline applies.)
+    normal branch discipline applies. Founding pushes nothing; `/start-phase`
+    establishes the terminal branch as the remote default before it pushes the
+    first phase branch — BUG-025.)
 
 8. Report to user:
    - Summary of what was founded

package/core/config.js

@@ -52,7 +52,7 @@ const ENUMS = {
   publish_target: ['npm', 'pypi', 'crates-io', 'nuget', 'none', 'custom'],
   git_forge: ['github', 'gitlab', 'bitbucket', 'gitea', 'forgejo', 'bare-ssh'],
   release_flow: ['tag-and-publish', 'tag-and-deploy', 'tag-only', 'custom'],
-  end_state: ['merge-after-yes', 'staging-promotion', 'feature-branch-only'],
+  end_state: ['merge-after-yes', 'staging-promotion', 'feature-branch-only', 'open-pr'],
 };
 
 // Fields the CLI can infer from manifests + git remote. Used by drift detection.

package/core/lanes/lib/cleanup.js

@@ -0,0 +1,349 @@
+'use strict';
+
+/**
+ * Shared, forge-neutral cleanup action for a "spent" branch/lane
+ * (Phase 27 G0 — BUG-026 / ENH-063; see specs/phases/phase-27-lifecycle-cleanup).
+ *
+ * A phase/lane branch is "spent" once its work has landed on the terminal
+ * integration branch. `cleanupTarget()` removes what it leaves behind, in a
+ * fixed, idempotent, DEFAULT-BRANCH-SAFE order:
+ *
+ *   1. worktree      git worktree remove       (never the caller's own worktree)
+ *   2. local branch  git branch -d             (-D only with force; unmerged → blocked)
+ *   3. remote branch git push origin --delete  (SKIPPED when it is the forge default)
+ *   4. lane state    clear inbox/signals; leave a `cleaned` tombstone by default
+ *
+ * Pure git + node builtins; ships NO forge code — the optional `gh` default-branch
+ * assertion lives in the recipes, config-gated (momentum stays forge-neutral).
+ * Idempotent: anything already gone is reported `skipped`, never an error. The
+ * remote-default guard is load-bearing: it is the reason a hijacked default
+ * branch (BUG-025) can never be deleted out from under the repo.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const state = require('./state');
+
+function git(cwd, ...args) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+function ok(res) { return res && res.status === 0; }
+function out(res) { return ((res && res.stdout) || '').trim(); }
+function err(res) { return ((res && res.stderr) || '').trim(); }
+
+/** Real path (resolves symlinks like macOS /var → /private/var), best-effort. */
+function realpath(p) {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+}
+function samePath(a, b) {
+  return Boolean(a) && Boolean(b) && realpath(a) === realpath(b);
+}
+
+// ─── read-only git predicates ────────────────────────────────────────────
+
+function hasRemote(cwd, remote = 'origin') {
+  return ok(git(cwd, 'remote', 'get-url', remote));
+}
+
+function localBranchExists(cwd, branch) {
+  return ok(git(cwd, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`));
+}
+
+function remoteBranchExists(cwd, branch, remote = 'origin') {
+  const res = git(cwd, 'ls-remote', '--heads', remote, branch);
+  return ok(res) && out(res) !== '';
+}
+
+/** True when `ref` is contained in `container` (already merged / landed). */
+function isMerged(cwd, ref, container) {
+  return ok(git(cwd, 'merge-base', '--is-ancestor', ref, container));
+}
+
+/**
+ * The remote's default branch short name (e.g. "main"), or null when unknown.
+ * Prefers the locally-tracked symbolic ref; falls back to asking the remote
+ * (network) unless { network:false }.
+ */
+function remoteDefaultBranch(cwd, { remote = 'origin', network = true } = {}) {
+  const local = git(cwd, 'symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`);
+  if (ok(local) && out(local)) {
+    return out(local).replace(new RegExp(`^${remote}/`), '');
+  }
+  if (network) {
+    const ls = git(cwd, 'ls-remote', '--symref', remote, 'HEAD');
+    if (ok(ls)) {
+      const m = out(ls).match(/^ref:\s+refs\/heads\/(\S+)\s+HEAD/m);
+      if (m) return m[1];
+    }
+  }
+  return null;
+}
+
+/** Registered worktrees: [{ path, branch }]. */
+function worktreeList(cwd) {
+  const res = git(cwd, 'worktree', 'list', '--porcelain');
+  if (!ok(res)) return [];
+  const trees = [];
+  let cur = null;
+  for (const line of out(res).split('\n')) {
+    if (line.startsWith('worktree ')) { cur = { path: line.slice('worktree '.length), branch: null }; trees.push(cur); }
+    else if (line.startsWith('branch ') && cur) cur.branch = line.slice('branch '.length).replace('refs/heads/', '');
+  }
+  return trees;
+}
+
+// ─── the shared cleanup action ───────────────────────────────────────────
+
+/**
+ * Remove the artifacts a spent branch/lane leaves behind.
+ *
+ * @param {object} opts
+ *   cwd          where git runs (must NOT be inside `worktree`)
+ *   branch       branch to delete (local + remote)
+ *   worktree     worktree path to remove (optional)
+ *   laneId       lane-state id to clear (optional)
+ *   anchor       lane-state anchor (optional; derived from cwd)
+ *   deleteRemote delete origin/<branch> when safe (default true)
+ *   force        allow `git branch -D` / `worktree remove --force` (default false)
+ *   dryRun       report intended actions without performing them
+ *   keepState    keep the full lane dir untouched (default false → tombstone)
+ *   remote       remote name (default 'origin')
+ * @returns {{ ok:boolean, actions:Array<{step,status,detail}>, blocked:string[] }}
+ */
+function cleanupTarget(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const {
+    branch, worktree, laneId,
+    deleteRemote = true, force = false, dryRun = false, keepState = false,
+    remote = 'origin',
+  } = opts;
+  const anchor = opts.anchor || state.resolveAnchor(cwd);
+  const actions = [];
+  const blocked = [];
+  const record = (step, status, detail) => actions.push({ step, status, detail });
+
+  const selfRoot = out(git(cwd, 'rev-parse', '--show-toplevel'));
+
+  // 1. worktree — before the branch, since a checked-out branch blocks `-d`
+  if (worktree) {
+    const registered = worktreeList(cwd).find((w) => samePath(w.path, worktree));
+    if (!registered && !fs.existsSync(worktree)) {
+      record('worktree', 'skipped', `${worktree} — not present`);
+    } else if (samePath(worktree, selfRoot)) {
+      record('worktree', 'blocked', `refusing to remove the current worktree (${worktree}) — run cleanup from the integration checkout`);
+      blocked.push('worktree');
+    } else if (dryRun) {
+      record('worktree', 'would', `git worktree remove ${worktree}${force ? ' --force' : ''}`);
+    } else {
+      const args = ['worktree', 'remove', worktree];
+      if (force) args.push('--force');
+      const res = git(cwd, ...args);
+      if (ok(res)) {
+        record('worktree', 'removed', worktree);
+      } else {
+        record('worktree', 'blocked', `git worktree remove failed (${err(res) || 'dirty or locked'}) — rerun with --force`);
+        blocked.push('worktree');
+      }
+    }
+    git(cwd, 'worktree', 'prune');
+  }
+
+  // 2. local branch — skip if its worktree is still present
+  if (branch && localBranchExists(cwd, branch)) {
+    if (blocked.includes('worktree')) {
+      record('local-branch', 'skipped', `'${branch}' — worktree still present`);
+    } else if (dryRun) {
+      record('local-branch', 'would', `git branch -${force ? 'D' : 'd'} ${branch}`);
+    } else {
+      const res = git(cwd, 'branch', force ? '-D' : '-d', branch);
+      if (ok(res)) {
+        record('local-branch', 'deleted', branch);
+      } else {
+        record('local-branch', 'blocked', `'${branch}' not fully merged (git branch -d refused) — verify it landed, then rerun with --force`);
+        blocked.push('local-branch');
+      }
+    }
+  } else if (branch) {
+    record('local-branch', 'skipped', `'${branch}' — no local branch`);
+  }
+
+  // 3. remote branch — NEVER the forge default (BUG-025 guard)
+  if (branch && deleteRemote) {
+    if (!hasRemote(cwd, remote)) {
+      record('remote-branch', 'skipped', `no '${remote}' remote`);
+    } else if (!remoteBranchExists(cwd, branch, remote)) {
+      record('remote-branch', 'skipped', `${remote}/${branch} — not on the remote`);
+    } else {
+      const def = remoteDefaultBranch(cwd, { remote });
+      if (def && def === branch) {
+        record('remote-branch', 'blocked', `${remote}/${branch} is the forge DEFAULT branch — refusing to delete (BUG-025 guard); reassign the default first`);
+        blocked.push('remote-branch');
+      } else if (dryRun) {
+        record('remote-branch', 'would', `git push ${remote} --delete ${branch}`);
+      } else {
+        const res = git(cwd, 'push', remote, '--delete', branch);
+        if (ok(res)) {
+          record('remote-branch', 'deleted', `${remote}/${branch}`);
+        } else {
+          record('remote-branch', 'blocked', `git push --delete failed (${err(res)})`);
+          blocked.push('remote-branch');
+        }
+      }
+    }
+  }
+
+  // 4. lane state — clear heavy state, leave a `cleaned` tombstone by default
+  if (laneId && anchor) {
+    const dir = state.laneDir(anchor, laneId);
+    const manifest = state.readManifest(anchor, laneId);
+    if (!manifest && !fs.existsSync(dir)) {
+      record('lane-state', 'skipped', `no lane '${laneId}'`);
+    } else if (keepState) {
+      record('lane-state', 'skipped', `'${laneId}' — keepState`);
+    } else if (dryRun) {
+      record('lane-state', 'would', `clear '${laneId}' inbox + tombstone the manifest`);
+    } else {
+      try { fs.rmSync(state.inboxDir(anchor, laneId), { recursive: true, force: true }); } catch { /* absent */ }
+      if (manifest) {
+        try {
+          state.updateLane(anchor, laneId, { worktree: null, cleaned: true, cleanedAt: new Date().toISOString() });
+        } catch { /* ENOLANE race — nothing to tombstone */ }
+      }
+      record('lane-state', 'cleared', `'${laneId}' inbox removed; manifest tombstoned (cleaned)`);
+    }
+  }
+
+  return { ok: blocked.length === 0, actions, blocked };
+}
+
+// ─── default-branch establishment (BUG-025) ──────────────────────────────
+
+/**
+ * Ensure the terminal integration branch (e.g. main) is the branch a fresh
+ * forge repo adopts as its default — by making sure it is on the remote FIRST,
+ * before any phase branch is ever pushed. Pure git; the forge-side default
+ * assertion (`gh repo edit --default-branch`) is a recipe step, config-gated.
+ *
+ * Read-only by default (returns a plan the recipe acts on). With { push:true }
+ * it performs the founding bootstrap push when the remote lacks the branch.
+ *
+ * @returns {{ status:string, detail:string, pushed:boolean, defaultBranch?:string }}
+ *   status ∈ no-remote | no-local-branch | needs-push | push-failed | ok | default-mismatch
+ */
+function ensureTerminalBranchIsRemoteDefault(cwd, terminalBranch, opts = {}) {
+  const { push = false, remote = 'origin', setLocalHead = true } = opts;
+  if (!hasRemote(cwd, remote)) {
+    return { status: 'no-remote', detail: `no '${remote}' remote — nothing to establish`, pushed: false };
+  }
+  if (!localBranchExists(cwd, terminalBranch)) {
+    return { status: 'no-local-branch', detail: `local '${terminalBranch}' does not exist yet`, pushed: false };
+  }
+  let pushed = false;
+  if (!remoteBranchExists(cwd, terminalBranch, remote)) {
+    if (!push) {
+      return {
+        status: 'needs-push',
+        detail: `'${terminalBranch}' is not on ${remote} — push it FIRST (before any phase branch) so the forge adopts it as default`,
+        pushed: false,
+      };
+    }
+    const res = git(cwd, 'push', '-u', remote, terminalBranch);
+    if (!ok(res)) return { status: 'push-failed', detail: err(res), pushed: false };
+    pushed = true;
+  }
+  if (setLocalHead) git(cwd, 'remote', 'set-head', remote, terminalBranch);
+  const def = remoteDefaultBranch(cwd, { remote });
+  const isDefault = def === terminalBranch;
+  return {
+    status: isDefault || pushed ? 'ok' : 'default-mismatch',
+    detail: isDefault
+      ? `${remote} default is '${terminalBranch}'`
+      : `${remote} default is '${def || 'unknown'}' — run the forge assertion (e.g. gh repo edit --default-branch ${terminalBranch}) to repair`,
+    pushed,
+    defaultBranch: def,
+  };
+}
+
+// ─── CLI: `momentum lanes cleanup` ───────────────────────────────────────
+
+function parseCleanupArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--force' || a === '--dry-run' || a === '--no-remote' || a === '--keep-state' || a === '--json') {
+      flags[a.slice(2)] = true;
+    } else if (a.startsWith('--')) {
+      flags[a.slice(2)] = argv[++i];
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+
+/**
+ * `momentum lanes cleanup <branch> [--worktree P] [--lane ID] [--no-remote]
+ *  [--force] [--dry-run] [--keep-state] [--json]`
+ *
+ * A thin surface over cleanupTarget() for the recipes (complete-phase) and
+ * for manual use. When --lane is given but --branch/--worktree are omitted,
+ * they are read from the lane manifest.
+ */
+function cmdCleanup(cwd, argv) {
+  const { flags, positional } = parseCleanupArgs(argv);
+  let branch = positional[0];
+  const laneId = flags.lane || null;
+  let worktree = flags.worktree || null;
+
+  if (laneId) {
+    const anchor = state.resolveAnchor(cwd);
+    const lane = anchor && state.readManifest(anchor, laneId);
+    if (lane) {
+      branch = branch || lane.branch;
+      worktree = worktree || lane.worktree || null;
+    }
+  }
+  if (!branch && !worktree && !laneId) {
+    console.error('✗ usage: momentum lanes cleanup <branch> [--worktree P] [--lane ID] [--no-remote] [--force] [--dry-run] [--keep-state]');
+    return 1;
+  }
+
+  const result = cleanupTarget({
+    cwd, branch, worktree, laneId,
+    deleteRemote: !flags['no-remote'],
+    force: Boolean(flags.force),
+    dryRun: Boolean(flags['dry-run']),
+    keepState: Boolean(flags['keep-state']),
+  });
+
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : 1;
+  }
+
+  const glyph = { removed: '✓', deleted: '✓', cleared: '✓', skipped: 'ℹ', would: '·', blocked: '✗' };
+  for (const a of result.actions) {
+    console.log(`  ${glyph[a.status] || '·'} ${a.step}: ${a.detail}`);
+  }
+  if (result.ok) {
+    console.log(flags['dry-run'] ? '✓ dry-run — nothing changed' : '✓ cleanup complete');
+    return 0;
+  }
+  console.error(`✗ cleanup incomplete — blocked: ${result.blocked.join(', ')}`);
+  return 1;
+}
+
+module.exports = {
+  cleanupTarget,
+  ensureTerminalBranchIsRemoteDefault,
+  remoteDefaultBranch,
+  remoteBranchExists,
+  localBranchExists,
+  isMerged,
+  hasRemote,
+  worktreeList,
+  cmdCleanup,
+};

package/core/lanes/lib/land.js

@@ -41,17 +41,29 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const state = require('./state');
+const cleanup = require('./cleanup');
+const config = require('../../config');
 
 function git(cwd, ...args) {
   return spawnSync('git', args, { cwd, encoding: 'utf8' });
 }
 
+/** Terminal integration branch = last branch_flow entry (config), default 'main'. */
+function terminalBranch(repoRoot) {
+  try {
+    const cfg = config.readConfig(path.join(repoRoot, 'specs'));
+    const bf = cfg && cfg.branch_flow;
+    if (Array.isArray(bf) && bf.length) return bf[bf.length - 1];
+  } catch { /* config absent/unreadable — fall through */ }
+  return 'main';
+}
+
 function parseFlags(argv) {
   const flags = {};
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--execute' || a === '--force' || a === '--json' || a === '--mark-landed') flags[a.slice(2)] = true;
+    if (a === '--execute' || a === '--force' || a === '--json' || a === '--mark-landed' || a === '--keep') flags[a.slice(2)] = true;
     else if (a.startsWith('--')) flags[a.slice(2)] = argv[++i];
     else positional.push(a);
   }
@@ -294,6 +306,27 @@ function cmdLand(cwd, argv) {
   if (others.length) {
     console.log(`ℹ advisory rebase signal sent to ${others.length} open lane(s): ${others.map((l) => l.id).join(', ')}`);
   }
+
+  // Phase 27 (BUG-026): a lane that landed on the TERMINAL integration branch is
+  // spent — clean its worktree + branch + lane state now (default-branch-safe),
+  // unless --keep. Landing into an intermediate branch (e.g. staging under
+  // staging-promotion) is NOT spent — cleanup defers to `lanes reconcile`.
+  const terminal = terminalBranch(repoRoot);
+  if (flags.keep) {
+    console.log('ℹ --keep: worktree, branch, and lane state left in place');
+  } else if (into === terminal) {
+    const res = cleanup.cleanupTarget({
+      cwd, branch: lane.branch, worktree: lane.worktree, laneId: id, deleteRemote: true,
+    });
+    const glyph = { removed: '✓', deleted: '✓', cleared: '✓', skipped: 'ℹ', blocked: '⚠' };
+    for (const a of res.actions) console.log(`  ${glyph[a.status] || '·'} cleanup ${a.step}: ${a.detail}`);
+    if (!res.ok) {
+      console.log(`⚠ cleanup incomplete (${res.blocked.join(', ')}) — resolve, then: momentum lanes cleanup ${lane.branch}`);
+    }
+  } else {
+    console.log(`ℹ landed on '${into}' (not the terminal branch '${terminal}') — cleanup deferred to \`momentum lanes reconcile\` once it reaches '${terminal}'`);
+  }
+
   console.log('ℹ run the suite on the updated branch before the next landing (Rule 6 Landing Order)');
   return 0;
 }

package/core/lanes/lib/reconcile.js

@@ -0,0 +1,129 @@
+'use strict';
+
+/**
+ * `momentum lanes reconcile` — sweep lanes whose terminal merge happened
+ * OUT-OF-BAND (Phase 27 G3, BUG-026). For the `end_state`s where a human or the
+ * forge performs the terminal merge (`staging-promotion` after promotion,
+ * `feature-branch-only`, `open-pr`), the agent never auto-cleans at land time;
+ * this command detects lanes now contained in the terminal branch upstream and
+ * runs the same default-branch-safe `cleanupTarget()` on them.
+ *
+ * Validate-first: without --execute it only reports which lanes are landed
+ * (cleanable) vs still pending. `git fetch --prune` runs first (unless
+ * --no-fetch) so containment is judged against the freshest `origin/<terminal>`.
+ *
+ * Verify-before-clean (Rule 12): a lane is cleaned ONLY when its branch is a
+ * verified ancestor of the terminal branch — a human's "yes, I merged it" is
+ * never taken on trust.
+ */
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const state = require('./state');
+const cleanup = require('./cleanup');
+const config = require('../../config');
+
+function git(cwd, ...args) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+function ok(res) { return res && res.status === 0; }
+
+function terminalBranch(repoRoot) {
+  try {
+    const cfg = config.readConfig(path.join(repoRoot, 'specs'));
+    const bf = cfg && cfg.branch_flow;
+    if (Array.isArray(bf) && bf.length) return bf[bf.length - 1];
+  } catch { /* config absent — default below */ }
+  return 'main';
+}
+
+/** The best ref to test containment against: origin/<terminal> if present, else local. */
+function containerRef(cwd, terminal) {
+  if (ok(git(cwd, 'rev-parse', '--verify', '--quiet', `refs/remotes/origin/${terminal}`))) {
+    return `origin/${terminal}`;
+  }
+  return terminal;
+}
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--execute' || a === '--json' || a === '--no-fetch' || a === '--force') flags[a.slice(2)] = true;
+    else if (a.startsWith('--')) flags[a.slice(2)] = argv[++i];
+    else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+/**
+ * Classify a lane: landed (branch contained in the terminal ref, or already
+ * gone) vs pending (still not merged). Returns { lane, verdict, reason }.
+ */
+function classify(cwd, lane, container) {
+  const local = cleanup.localBranchExists(cwd, lane.branch);
+  const remote = cleanup.remoteBranchExists(cwd, lane.branch);
+  if (!local && !remote) {
+    // Branch already deleted everywhere — only residual worktree/state remains.
+    return { lane, verdict: 'landed', reason: `branch '${lane.branch}' already gone — residual state only` };
+  }
+  const ref = local ? lane.branch : `origin/${lane.branch}`;
+  if (cleanup.isMerged(cwd, ref, container)) {
+    return { lane, verdict: 'landed', reason: `'${lane.branch}' is contained in '${container}'` };
+  }
+  return { lane, verdict: 'pending', reason: `'${lane.branch}' not yet contained in '${container}'` };
+}
+
+function cmdReconcile(cwd, argv) {
+  const { flags } = parseFlags(argv);
+  const anchor = state.resolveAnchor(cwd);
+  if (!anchor) { console.error('✗ not inside a git repository'); return 1; }
+  const repoRoot = state.worktreeRoot(cwd);
+  const terminal = flags.into || terminalBranch(repoRoot);
+
+  if (!flags['no-fetch']) git(cwd, 'fetch', '--prune'); // best-effort; offline is fine
+  const container = containerRef(cwd, terminal);
+
+  // Sweep every non-cleaned, non-closed lane.
+  const lanes = state.listLanes(anchor).filter((l) => !l.cleaned && l.status !== 'closed');
+  const classified = lanes.map((l) => classify(cwd, l, container));
+  const landed = classified.filter((c) => c.verdict === 'landed');
+  const pending = classified.filter((c) => c.verdict === 'pending');
+
+  if (flags.json && !flags.execute) {
+    console.log(JSON.stringify({ terminal, container, landed, pending }, null, 2));
+    return 0;
+  }
+
+  console.log(`reconcile against '${container}' (terminal branch '${terminal}'):`);
+  if (!classified.length) console.log('  ℹ no open/landed lanes to reconcile');
+  for (const c of pending) console.log(`  · pending: ${c.lane.id} — ${c.reason}`);
+  for (const c of landed) console.log(`  ✓ landed:  ${c.lane.id} — ${c.reason}`);
+
+  if (!flags.execute) {
+    if (landed.length) {
+      console.log(`✓ ${landed.length} lane(s) cleanable — run with --execute to clean worktree + branch + state`);
+    } else {
+      console.log('✓ nothing to clean');
+    }
+    return 0;
+  }
+
+  let failures = 0;
+  for (const { lane } of landed) {
+    console.log(`cleaning '${lane.id}'…`);
+    const res = cleanup.cleanupTarget({
+      cwd, branch: lane.branch, worktree: lane.worktree, laneId: lane.id,
+      deleteRemote: true, 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) { failures++; console.log(`  ⚠ '${lane.id}' cleanup incomplete: ${res.blocked.join(', ')}`); }
+  }
+  console.log(`✓ reconcile complete — cleaned ${landed.length - failures}/${landed.length} landed lane(s); ${pending.length} still pending`);
+  return failures ? 1 : 0;
+}
+
+module.exports = { cmdReconcile, classify, terminalBranch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limina-labs/momentum",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Agent-agnostic, specs-driven development framework — single project or multi-project ecosystem",
   "homepage": "https://trymomentum.github.io",
   "bin": {