@jaybeeuu/agent-cortex 2.9.0 → 2.10.0

package/skills/workflow/prioritise-work/scripts/strategy.mjs

@@ -64,6 +64,30 @@ export const TEMPLATE_FILE = fileURLToPath(new URL('../templates/strategy.md', i
  */
 export const CHANGE_LOG_SECTION = 'Change log';
 
+/**
+ * The section that tunes the deadline factor a ranked queue applies. Optional in a
+ * hand-written file: a strategy created before the tiers existed ranks on
+ * `DEFAULT_DEADLINE_TIERS`, and `init` copies a table the owner can edit.
+ */
+export const DEADLINE_TIERS_SECTION = 'Deadline tiers';
+
+/**
+ * The deadline tiers the queue uses when the strategy carries none. The numbers live here
+ * once, as the documented default, so a caller that never opens the strategy still ranks
+ * predictably; a strategy overrides them, so the rise tunes without a code change.
+ *
+ * A boundary belongs to the tier that names it: with exactly one day left a bead earns the
+ * `within 1d` factor, and a millisecond more drops it to `within 2d`. A bead whose deadline
+ * is exactly now has not slipped yet, so it is not overdue; `overdue` covers the past.
+ */
+export const DEFAULT_DEADLINE_TIERS = /** @type {DeadlineTier[]} */ ([
+  { kind: 'within', minutes: 1440, factor: 4 },
+  { kind: 'within', minutes: 2880, factor: 2 },
+  { kind: 'within', minutes: 10080, factor: 1.5 },
+  { kind: 'beyond', minutes: 10080, factor: 1 },
+  { kind: 'overdue', factor: 8 },
+]);
+
 /** The shape of a date: four digits, two, two. Whether it exists is a separate question. */
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 
@@ -79,6 +103,48 @@ const FIELD_PREFIX = /^([ \t]*[-*][ \t]*\*\*[A-Za-z]+:\*\*[ \t]*)\S.*?[ \t]*$/;
 /** One change-log line: the date it landed, the version it produced, and the reason. */
 const CHANGE_LOG_ENTRY = /^[ \t]*[-*][ \t]+(\d{4}-\d{2}-\d{2})[ \t]+v(\d+):[ \t]*(.+?)[ \t]*$/;
 
+/** One row of the deadline-tier table, with the cells the pipes delimit. */
+const TIER_ROW = /^[ \t]*\|(.*)\|[ \t]*$/;
+
+/** The table's header row, skipped as a label rather than read as a tier. */
+const TIER_HEADER = /^(remaining|time|when|deadline)$/i;
+
+/** The table's `|---|:--:|` rule, which carries no value. */
+const TIER_RULE = /^:?-{2,}:?$/;
+
+/** `within 7d` and `<= 7d`: the factor earned at or inside this much time left. */
+const TIER_WITHIN = /^(?:within|<=)\s+(\d+)\s*([mhd])$/i;
+
+/** `more than 7d` and `> 7d`: the factor for anything further out. */
+const TIER_BEYOND = /^(?:more than|>)\s+(\d+)\s*([mhd])$/i;
+
+/** `overdue`: the factor for a deadline already passed. */
+const TIER_OVERDUE = /^overdue$/i;
+
+/** A factor: a positive number, in the plain form a reader can check. */
+const TIER_FACTOR = /^\d+(?:\.\d+)?$/;
+
+/** How long each unit in a tier row lasts. */
+const TIER_UNIT_MINUTES = Object.freeze(/** @type {const} */ ({ m: 1, h: 60, d: 1440 }));
+
+/** How many milliseconds a minute holds, for turning a tier's minutes into a distance. */
+const MS_PER_MINUTE = 60_000;
+
+/**
+ * One deadline tier: the factor a bead earns at a stated distance from its deadline.
+ * @typedef {{ kind: 'overdue', factor: number }
+ *   | { kind: 'within', minutes: number, factor: number }
+ *   | { kind: 'beyond', minutes: number, factor: number }} DeadlineTier
+ */
+
+/**
+ * What `parseDeadlineTiers` found.
+ * @typedef {object} DeadlineTiersReport
+ * @property {boolean} ok
+ * @property {DeadlineTier[]} tiers  The parsed tiers, or the documented default when absent.
+ * @property {string[]} errors       One line per defect in the table.
+ */
+
 /** A usage mistake: the caller asked for something malformed. Exit code 2. */
 export class UsageError extends Error {}
 
@@ -163,6 +229,124 @@ function sectionBody(lines, title) {
   return body;
 }
 
+/**
+ * The minutes a tier row's `<number><unit>` names.
+ * @param {string} count @param {string} unit @returns {number}
+ */
+function tierMinutes(count, unit) {
+  const key = /** @type {'m'|'h'|'d'} */ (unit.toLowerCase());
+  return Number(count) * TIER_UNIT_MINUTES[key];
+}
+
+/**
+ * One table row as a tier, or a message naming what the row got wrong.
+ * @param {string} when        The "Remaining" cell.
+ * @param {string} factorText  The "Factor" cell.
+ * @returns {{ tier: DeadlineTier } | { error: string }}
+ */
+function parseTierRow(when, factorText) {
+  const factor = TIER_FACTOR.test(factorText) ? Number(factorText) : 0;
+  if (factor <= 0) return { error: `factor "${factorText}" is not a positive number` };
+
+  if (TIER_OVERDUE.test(when)) return { tier: { kind: 'overdue', factor } };
+  const within = TIER_WITHIN.exec(when);
+  if (within !== null) return { tier: { kind: 'within', minutes: tierMinutes(within[1], within[2]), factor } };
+  const beyond = TIER_BEYOND.exec(when);
+  if (beyond !== null) return { tier: { kind: 'beyond', minutes: tierMinutes(beyond[1], beyond[2]), factor } };
+  return { error: `"${when}" is not "overdue", "within <time>" or "more than <time>"` };
+}
+
+/**
+ * Read the deadline tiers out of a strategy: the `## Deadline tiers` table, or the
+ * documented default when the section is absent or carries no row.
+ *
+ * A table that is present must be complete — exactly one `overdue` row, exactly one
+ * `more than <time>` row, and at least one `within <time>` row — because a factor that
+ * silently fell back to a default would make the rise depend on a file the reader cannot
+ * see. Every defect is reported, so one run fixes the whole table.
+ * @param {string} text @returns {DeadlineTiersReport}
+ */
+export function parseDeadlineTiers(text) {
+  const body = sectionBody(text.split('\n'), DEADLINE_TIERS_SECTION);
+  if (body === null) return { ok: true, tiers: [...DEFAULT_DEADLINE_TIERS], errors: [] };
+
+  /** @type {DeadlineTier[]} */
+  const rows = [];
+  /** @type {string[]} */
+  const errors = [];
+  let firstTableLine = true;
+
+  for (const line of body) {
+    const cells = TIER_ROW.exec(line)?.[1].split('|');
+    if (cells === undefined || cells.length !== 2) continue;
+    const when = cells[0].trim();
+    const factorText = cells[1].trim();
+    const isFirst = firstTableLine;
+    firstTableLine = false;
+    if (isFirst && TIER_HEADER.test(when)) continue;
+    if (TIER_RULE.test(when) || TIER_RULE.test(factorText)) continue;
+
+    const parsed = parseTierRow(when, factorText);
+    if ('error' in parsed) {
+      errors.push(`${DEADLINE_TIERS_SECTION}: row "| ${when} | ${factorText} |" — ${parsed.error}`);
+      continue;
+    }
+    rows.push(parsed.tier);
+  }
+
+  if (rows.length === 0 && errors.length === 0) {
+    return { ok: true, tiers: [...DEFAULT_DEADLINE_TIERS], errors: [] };
+  }
+
+  if (errors.length === 0) {
+    const count = (/** @type {DeadlineTier['kind']} */ kind) => rows.filter((tier) => tier.kind === kind).length;
+    if (count('overdue') !== 1) errors.push(`${DEADLINE_TIERS_SECTION}: needs exactly one "overdue" row, found ${count('overdue')}`);
+    if (count('beyond') !== 1) errors.push(`${DEADLINE_TIERS_SECTION}: needs exactly one "more than <time>" row, found ${count('beyond')}`);
+    if (count('within') === 0) errors.push(`${DEADLINE_TIERS_SECTION}: needs at least one "within <time>" row`);
+  }
+
+  if (errors.length > 0) return { ok: false, tiers: [...DEFAULT_DEADLINE_TIERS], errors };
+
+  const within = rows
+    .filter((tier) => tier.kind === 'within')
+    .sort((a, b) => (a.kind === 'within' && b.kind === 'within' ? a.minutes - b.minutes : 0));
+  const beyond = rows.filter((tier) => tier.kind === 'beyond');
+  const overdue = rows.filter((tier) => tier.kind === 'overdue');
+  return { ok: true, tiers: [...within, ...beyond, ...overdue], errors: [] };
+}
+
+/**
+ * What a deadline is worth `remainingMs` from now: the factor from the narrowest `within`
+ * tier the remaining time fits inside, the overdue factor once the moment has passed, and
+ * the `more than` factor beyond every tier.
+ *
+ * The boundaries are the whole contract, so each falls on one stated side: with exactly one
+ * day left a bead earns the `within 1d` factor, and a millisecond more drops it to
+ * `within 2d`; a bead whose deadline is exactly now has not slipped yet, so it is not
+ * overdue.
+ * @param {number} remainingMs
+ * @param {DeadlineTier[]} [tiers]
+ * @returns {{ factor: number, overdue: boolean }}
+ */
+export function deadlineMultiplier(remainingMs, tiers = DEFAULT_DEADLINE_TIERS) {
+  /** @type {{ minutes: number, factor: number }[]} */
+  const within = [];
+  let beyond = 1;
+  let overdue = 1;
+  for (const tier of tiers) {
+    if (tier.kind === 'within') within.push({ minutes: tier.minutes, factor: tier.factor });
+    else if (tier.kind === 'beyond') beyond = tier.factor;
+    else overdue = tier.factor;
+  }
+  within.sort((a, b) => a.minutes - b.minutes);
+
+  if (remainingMs < 0) return { factor: overdue, overdue: true };
+  for (const tier of within) {
+    if (remainingMs <= tier.minutes * MS_PER_MINUTE) return { factor: tier.factor, overdue: false };
+  }
+  return { factor: beyond, overdue: false };
+}
+
 /**
  * Whether a body carries anything a scorer can read. An HTML comment is guidance, not
  * content, so a template copied and never filled in is empty rather than filled.
@@ -241,6 +425,9 @@ export function validateStrategy(text) {
   }
 
   const lines = text.split('\n');
+  const tiers = parseDeadlineTiers(text);
+  if (!tiers.ok) errors.push(...tiers.errors);
+
   for (const title of REQUIRED_SECTIONS) {
     const body = sectionBody(lines, title);
     if (body === null) errors.push(`missing required section: "## ${title}"`);
@@ -414,9 +601,12 @@ export function parseArgs(argv) {
  * carries `.git` as a file, so existence is the whole test. Walks with `node:fs/promises`
  * and never shells out, because this script spawns nothing. Falls back to `start` when no
  * ancestor is a repository, so a run outside one writes where the caller stands.
+ *
+ * Exported for the same reason as `resolveStrategyPath`: another skill's default path is
+ * documented against the repository root, and two walkers would be two answers.
  * @param {string} start @returns {Promise<string>}
  */
-async function findRepositoryRoot(start) {
+export async function findRepositoryRoot(start) {
   const from = resolve(start);
   let directory = from;
   for (;;) {

package/skills/workflow/prioritise-work/templates/strategy.md

@@ -6,7 +6,8 @@ confidence and effort. Keep it short enough that you actually maintain it.
 
 It lives in the repository as a committed file, never in the tracker, so a reviewer can
 diff how the judgement changed. Every `##` section below is required: leave one empty and
-the validator names it. Set the version and the date with
+the validator names it. `## Deadline tiers` is the one exception — omit it and the queue
+ranks on its documented default. Set the version and the date with
 `node <skill-scripts>/strategy.mjs bump` after you edit the content.
 -->
 
@@ -50,6 +51,31 @@ For example: 1 = half a day, one file; 3 = two to three days, one module with it
 5 = a week or more, several modules or a migration.
 -->
 
+## Deadline tiers
+
+<!--
+What a bd `--due` date does to a bead's rank in the HITL queue. The queue multiplies its
+total by the factor of the narrowest row the remaining time fits inside, and a bead with
+no deadline keeps the "more than" factor. Write each time as a number and one of `m`, `h`
+or `d`, as in `within 1d`; read the rows in this order, narrowest first. A table needs
+exactly one `overdue` row, exactly one `more than` row and at least one `within` row, and
+`validate` names any row it cannot read.
+
+A boundary belongs to the row that names it: exactly one day left earns 4, and a
+millisecond more earns 2. A bead whose deadline is exactly now has not slipped yet, so it
+is not overdue. A strategy with no table falls back to the queue's documented default, so
+the rows below are the shipped values: edit a number, then `bump`, and the next queue run
+uses it.
+-->
+
+| Remaining | Factor |
+|---|---|
+| within 1d | 4 |
+| within 2d | 2 |
+| within 7d | 1.5 |
+| more than 7d | 1 |
+| overdue | 8 |
+
 ## Change log
 
 <!--

package/skills/workflow/ralph/REFERENCE.md

@@ -231,11 +231,16 @@ A worktree outlives its bead: ralph leaves the directory behind when a feature c
 ```bash
 node skills/workflow/ralph/scripts/prune-worktrees.mjs                  # remove closed-bead worktrees, report the rest
 node skills/workflow/ralph/scripts/prune-worktrees.mjs --remove-orphans # also remove open-bead and missing-bead worktrees
+node skills/workflow/ralph/scripts/prune-worktrees.mjs --base <ref>     # prove content against <ref>, not origin/HEAD
 ```
 
 **Candidacy comes from bead state, never from git ancestry.** The repo squash-merges, so every landed branch still reports as unmerged. A directory named after a bead that `bd show` reports `closed` is the only proof that admits removal; an open bead, a missing bead, or a bead `bd` could not answer for is kept unless `--remove-orphans` asks otherwise. A bead `bd` could not read is never removed, whatever the flags say.
 
-**A candidate that fails a guard is refused, and the reason is printed.** The guards are: dirty working tree, `locked` worktree, detached HEAD, directory not registered with git, branch with no upstream, and branch with unpushed commits.
+**A candidate that fails a guard is refused, and the reason is printed.** The guards are: dirty working tree, `locked` worktree, detached HEAD, directory not registered with git or unreadable, branch with unpushed commits, and branch whose content is not proven landed.
+
+**No upstream is not a refusal by itself.** A merge that deletes the branch also deletes the local branch's upstream, so a closed bead's branch with no remote-tracking branch is the normal end of landed work. The guard is content: the base must hold the branch's own version of every path the branch changed since their merge base. That compares content, never history, so removal discards every commit the base does not contain, an empty commit or a change the branch added and reverted included, together with its message. The test is one-sided, so a base that moved on after the branch was cut still proves the branch landed. On a bead that is not closed, no upstream stays a refusal on its own.
+
+**The base is the remote's default branch,** read from `origin/HEAD` so that no branch name is hardcoded. `--base <ref>` names another, such as a release branch. A base that cannot be resolved, or that resolves to the worktree's own commit, keeps the worktree and refuses.
 
 **Removal is three commands.** `git worktree remove <path>`, then `git branch -D <branch>`, then `git push origin --delete <branch>`. The remote branch name is the worktree's own checked-out branch, so ralph's `feature/<parent-id>` deletes `origin/feature/<parent-id>`. A remote ref that git already reports as gone is not a failure.
 

package/skills/workflow/ralph/scripts/prune-worktrees.mjs

@@ -5,6 +5,20 @@
 // reads bead state, not git ancestry: this repo squash-merges, so every ancestry
 // test reports a landed branch as unmerged.
 //
+// A merge that deletes its branch also deletes the local branch's upstream, so a
+// closed bead with no remote-tracking branch is the normal end of a landed branch.
+// Only the content can tell that apart from a branch that was never pushed: the
+// branch goes when the base holds the branch's own version of every path the
+// branch changed since their merge base, and stays otherwise. The test is
+// one-sided on purpose: this repo squash-merges, so a base that moved on after the
+// branch was cut holds paths the branch never had, and demanding tree equality
+// would keep every branch but the last one landed.
+//
+// The test proves content, never history. A branch removed here is discarded
+// together with every commit the base does not contain — a reverted change and a
+// run of empty commits both go, and so do their messages. The base is the remote's
+// default branch, never a hardcoded name.
+//
 // Zero dependencies: run with `node prune-worktrees.mjs`.
 
 import { execFile } from 'node:child_process';
@@ -154,15 +168,134 @@ async function classifyBead(id, exec) {
   return { classification: status === 'closed' ? 'closed-bead' : 'open-bead', beadStatus: status };
 }
 
+/**
+ * Resolve the branch a worktree's content must be contained in before its local
+ * branch may be dropped. The remote's default branch is the generic answer:
+ * `origin/HEAD` is a symbolic ref to whatever the remote calls its default
+ * branch, so no branch name is baked in here.
+ * @param {string} repoRoot
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @returns {Promise<string | null>} the base ref, or null when git cannot name one.
+ */
+async function resolveBaseRef(repoRoot, git) {
+  const result = await git(repoRoot, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+  if (!result.ok) return null;
+  const ref = result.stdout.trim();
+  return ref === '' ? null : ref;
+}
+
+/**
+ * Split the output of `git diff --name-only -z` into paths. `-z` is what makes the
+ * round trip lossless: without it git C-quotes a path holding a non-ASCII byte, a
+ * double quote, a backslash or a newline, and a quoted name fed back as a
+ * pathspec names no path. With it, every path arrives raw and NUL-terminated, so
+ * a path holding a newline stays one path.
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+function splitNulPaths(stdout) {
+  // The output ends with a NUL, so the split leaves one empty entry to drop. A
+  // path is never empty, so no real path is lost with it.
+  return stdout.split('\0').filter((entry) => entry !== '');
+}
+
+/**
+ * Decide whether a branch with no upstream branch still holds work. Removing such
+ * a branch is only safe when the base holds the branch's own version of every path
+ * the branch changed — the squash-merge case. Anything unprovable keeps the
+ * worktree.
+ *
+ * One-sided containment, in three steps: take the merge base of the base and the
+ * branch, list the paths the branch changed since that merge base, then require the
+ * base to agree with the branch on those paths alone. Paths only the base added or
+ * changed lie outside that set and are ignored, so a base that advanced after the
+ * branch was cut still proves the branch landed.
+ *
+ * A status filter on the two-sided diff would be simpler and is wrong: `D` is the
+ * same status whether the branch deleted a path or the base never had it, so a
+ * filter cannot tell a deletion the base already carries from one it does not.
+ *
+ * Restricting to the branch's own paths is what makes an overlap detectable: when
+ * the base later changed a path the branch also changed, the two versions differ
+ * and the branch is not proven landed. A deletion on both sides agrees, so it is
+ * proven; a deletion on one side only is not.
+ *
+ * The branch's changed paths are read from git and then handed straight back to a
+ * second git call as pathspecs, so that round trip has to be exact. Two escapes
+ * make it inexact and both end in a false "proven": a path git would C-quote
+ * prints as a quoted string that names no path, and a path starting with `:` is
+ * read as pathspec magic instead of a name. Neither alone is sufficient to fix,
+ * so the first diff reads with `-z` and the second is run with
+ * `--literal-pathspecs`.
+ * @param {{ path: string, branch: string, beadClosed: boolean }} target
+ * @param {string | null} baseRef
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @returns {Promise<string | null>} a refusal reason, or null when nothing is lost.
+ */
+async function findLostWork({ path, branch, beadClosed }, baseRef, git) {
+  if (!beadClosed) {
+    return `branch ${branch} has no remote-tracking branch and its bead is not closed`;
+  }
+  if (baseRef === null) {
+    return `branch ${branch} has no remote-tracking branch and the base branch cannot be resolved, so its content cannot be proven landed`;
+  }
+  const tip = await git(path, ['rev-parse', '--verify', 'HEAD']);
+  if (!tip.ok) {
+    const detail = tip.stderr.trim();
+    const suffix = detail === '' ? '' : `: ${detail}`;
+    return `branch ${branch} has no remote-tracking branch and its tip cannot be read${suffix}`;
+  }
+  const baseTip = await git(path, ['rev-parse', '--verify', '--quiet', `${baseRef}^{commit}`]);
+  if (!baseTip.ok) {
+    const detail = baseTip.stderr.trim();
+    const suffix = detail === '' ? '' : `: ${detail}`;
+    return `branch ${branch} has no remote-tracking branch and ${baseRef} cannot be compared with it${suffix}`;
+  }
+  // A base that resolves to the branch being deleted compares the branch with
+  // itself: the diff is empty whatever the branch holds, so the guard cannot fail.
+  if (tip.stdout.trim() === baseTip.stdout.trim()) {
+    return `branch ${branch} has no remote-tracking branch and ${baseRef} resolves to this branch's own commit, so the comparison would prove nothing`;
+  }
+  const mergeBase = await git(path, ['merge-base', baseRef, 'HEAD']);
+  if (!mergeBase.ok) {
+    const detail = mergeBase.stderr.trim();
+    const suffix = detail === '' ? '' : `: ${detail}`;
+    return `branch ${branch} has no remote-tracking branch and ${baseRef} cannot be compared with it${suffix}`;
+  }
+  const touched = await git(path, ['diff', '--name-only', '-z', '--no-renames', mergeBase.stdout.trim(), 'HEAD', '--']);
+  if (!touched.ok) {
+    const detail = touched.stderr.trim();
+    const suffix = detail === '' ? '' : `: ${detail}`;
+    return `branch ${branch} has no remote-tracking branch and ${baseRef} cannot be compared with it${suffix}`;
+  }
+  const changedPaths = splitNulPaths(touched.stdout);
+  // Nothing but empty commits: no content to prove, and no content to lose.
+  if (changedPaths.length === 0) return null;
+  // `--literal-pathspecs` is a git global option, so it precedes the subcommand.
+  // It keeps a leading `:` in a real filename from being read as pathspec magic.
+  const unproven = await git(path, ['--literal-pathspecs', 'diff', '--name-only', '-z', '--no-renames', 'HEAD', baseRef, '--', ...changedPaths]);
+  if (!unproven.ok) {
+    const detail = unproven.stderr.trim();
+    const suffix = detail === '' ? '' : `: ${detail}`;
+    return `branch ${branch} has no remote-tracking branch and ${baseRef} cannot be compared with it${suffix}`;
+  }
+  const unprovenPaths = splitNulPaths(unproven.stdout).length;
+  if (unprovenPaths > 0) {
+    return `branch ${branch} has no remote-tracking branch and ${baseRef} does not hold this branch's version of ${unprovenPaths} path(s), so its commits may never have been pushed`;
+  }
+  return null;
+}
+
 /**
  * Reasons git refuses to tear a worktree down. A worktree removed anyway would
  * throw away uncommitted work or an unpushed branch, so every reason keeps the
  * worktree in place.
- * @param {{ path: string, registered: { branch: string | null, locked: string | null } | undefined }} target
+ * @param {{ path: string, registered: { branch: string | null, locked: string | null } | undefined, beadClosed: boolean }} target
  * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @param {string | null} baseRef
  * @returns {Promise<{ branch: string | null, reasons: string[] }>}
  */
-async function findRefusals({ path, registered }, git) {
+async function findRefusals({ path, registered, beadClosed }, git, baseRef) {
   /** @type {string[]} */
   const reasons = [];
 
@@ -183,7 +316,8 @@ async function findRefusals({ path, registered }, git) {
 
   const upstream = await git(path, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
   if (!upstream.ok) {
-    reasons.push(`branch ${registered.branch} has no remote-tracking branch`);
+    const lost = await findLostWork({ path, branch: registered.branch, beadClosed }, baseRef, git);
+    if (lost !== null) reasons.push(lost);
     return { branch: registered.branch, reasons };
   }
   const trackingRef = upstream.stdout.trim();
@@ -231,12 +365,14 @@ async function removeWorktree(repoRoot, { path, branch }, git) {
  * @param {object} options
  * @param {string} options.repoRoot                              Repository to prune.
  * @param {boolean} [options.removeOrphans]                       Also remove worktrees whose bead is open or missing.
+ * @param {string} [options.base]                                 Ref the content check compares against; defaults to the remote's default branch.
  * @param {(args: string[]) => Promise<string>} [options.exec]    bd runner; injectable for tests.
  * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} [options.git]  git runner; injectable for tests.
  * @returns {Promise<PruneResult>}
  */
-export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = false, git = runGit }) {
+export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = false, git = runGit, base }) {
   const registered = await readRegisteredWorktrees(repoRoot);
+  const baseRef = base ?? (await resolveBaseRef(repoRoot, git));
   /** @type {WorktreeEntry[]} */
   const entries = [];
 
@@ -252,7 +388,11 @@ export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = f
     // an unreadable bead is never removed at all.
     const wanted = classification === 'closed-bead' || (classification !== 'unclassified' && removeOrphans);
     if (wanted) {
-      const { branch, reasons } = await findRefusals({ path, registered: registered.get(path) }, git);
+      const { branch, reasons } = await findRefusals(
+        { path, registered: registered.get(path), beadClosed: classification === 'closed-bead' },
+        git,
+        baseRef,
+      );
       entry.branch = branch;
       if (reasons.length > 0) {
         entry.outcome = 'refused';
@@ -275,19 +415,56 @@ export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = f
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
-const USAGE = `Usage: node prune-worktrees.mjs [--remove-orphans]
+const USAGE = `Usage: node prune-worktrees.mjs [--remove-orphans] [--base <ref>]
 
 Removes worktrees under .agent-cortex/worktrees whose bead is closed, then
 reports the rest. A worktree whose bead is open or missing is an orphan: it is
 only removed when --remove-orphans is passed. Run from anywhere inside the
 repository.
+
+A closed bead's branch may have no remote-tracking branch, because many merge
+methods delete the remote branch when the work lands. Such a branch is removed
+only when the base holds the branch's own version of every path the branch changed
+since their merge base. That proves content and never history: removal discards
+every commit the base does not contain, such as a reverted change or an empty
+commit, together with its message. The base defaults to the remote's default
+branch (origin/HEAD); --base names another ref, such as a release branch. A base
+that cannot be resolved, or that resolves to the worktree's own branch, keeps the
+worktree and refuses.
 `;
 
 /** Every flag the CLI accepts. */
 const REMOVE_ORPHANS_FLAG = '--remove-orphans';
+const BASE_FLAG = '--base';
 
 class UsageError extends Error {}
 
+/**
+ * @param {string[]} argv
+ * @returns {{ removeOrphans: boolean, base: string | undefined }}
+ */
+function parseArgs(argv) {
+  let removeOrphans = false;
+  /** @type {string | undefined} */
+  let base;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === REMOVE_ORPHANS_FLAG) {
+      removeOrphans = true;
+      continue;
+    }
+    if (arg === BASE_FLAG) {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('-')) throw new UsageError(`${BASE_FLAG} needs a git ref`);
+      base = value;
+      index += 1;
+      continue;
+    }
+    throw new UsageError(`unexpected argument: ${arg}`);
+  }
+  return { removeOrphans, base };
+}
+
 /**
  * Resolve the repository root from any directory inside it — the main checkout
  * or a linked worktree. The shared `.git` directory is one level below the root
@@ -313,14 +490,12 @@ export async function runCli({ argv, cwd = process.cwd(), exec = runBd, git = ru
     write(USAGE);
     return 0;
   }
-  const unknown = argv.filter((arg) => arg !== REMOVE_ORPHANS_FLAG);
-  if (unknown.length > 0) throw new UsageError(`unexpected argument: ${unknown[0]}`);
-  const removeOrphans = argv.includes(REMOVE_ORPHANS_FLAG);
+  const { removeOrphans, base } = parseArgs(argv);
 
   const repoRoot = await resolveRepoRoot(cwd);
   if (repoRoot === null) throw new Error('not inside a git repository');
 
-  const { entries, exitCode } = await pruneWorktrees({ repoRoot, exec, removeOrphans, git });
+  const { entries, exitCode } = await pruneWorktrees({ repoRoot, exec, removeOrphans, git, base });
 
   write(`Scanning ${join(repoRoot, '.agent-cortex', 'worktrees')}\n`);
   for (const entry of entries) {

package/token-map.README.md

@@ -87,6 +87,15 @@ rather than inventing a dotted form:
   runtime env var (expanded per context by Claude Code) points at wherever the plugin
   actually runs from. A literal home path in substituted files would break under
   cache-copy, so the installer passes the env form through verbatim.
+- **`layouts`** — the tree each installer stages a resource into, for the resources whose
+  shape differs per harness. Only `skills` differs: the repository nests every skill one group
+  deep (`skills/<group>/<name>/`), and `bin/installers/pi.mjs` preserves that, while Claude
+  Code's plugin scan discovers `skills/<name>/SKILL.md` directly under `skills/`, so
+  `bin/installers/claude.mjs` copies every skill flat. A `{{PATH:skills/…}}` row is authored
+  against the repository tree; resolution reads the harness's row here and drops the group
+  segment when the harness stages skills flat, so the row names a file the install contains.
+  The row is a harness fact, not a repository one, which is why it lives here rather than in
+  the resolver: a harness that stages skills differently changes this table, not the code.
 - **`agents`** — the `agent-cortex:` name-prefix convention per harness (claude strips the
   prefix during conversion). Agent names themselves do not get per-row mappings because
   the prefix rule covers all of them — every agent is composed from `agents/<name>/` for
@@ -147,13 +156,16 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
 3. For `TOOL`: look up the canonical key, replace with the harness name; null → drop/omit;
    unknown → throw.
 4. For `PATH`: named key → resolve from `paths`; anything else → resolve relative to
-   `plugin_root`; `${ENV_VAR}` values pass through verbatim for runtime expansion.
+   `plugin_root`, after mapping a `skills/…` row onto the harness's staged shape from
+   `layouts`; `${ENV_VAR}` values pass through verbatim for runtime expansion.
 5. Reject a map `version` they do not implement.
 
 ## Authoring guidance
 
 - Write tokens with the **canonical authoring names**: `Use {{TOOL:task}} to spawn
-  subagents`, `Read {{PATH:skills/workflow/plan/SKILL.md}}`.
+  subagents`, `Read {{PATH:skills/workflow/plan/SKILL.md}}`. Write a skill path row in this
+  repository's grouped form, `skills/<group>/<name>/<file>`; each install maps it onto the
+  shape it stages (see `layouts`), so one authored row names a real file on both harnesses.
 - Never embed a harness-specific name in the canonical sources (`agents/<name>/agent.md`,
   `skills/**/SKILL.md`) — that defeats the map. The materialised Claude plugin
   (`~/.agent-cortex/claude`), the generated `agents/*.agent.md` files, and any installed

package/token-map.json

@@ -8,7 +8,7 @@
     "decision": "Adopt the {{TOOL:name}} / {{PATH:name}} / {{SECTION:name}} grammar already standardised by ADR #63 (agents/README.md) rather than a dotted {{tool.name}} form. The uppercase type prefix disambiguates token kinds at a glance, keeps tool/path/section names in one namespace collision-free, and matches the token grammar skills are already written against.",
     "types": {
       "TOOL": "{{TOOL:<canonical tool key>}} — replaced at install time with the bound harness's tool name (see tools).",
-      "PATH": "{{PATH:<path key or relative path>}} — replaced at install time with the harness-resolved path (see paths).",
+      "PATH": "{{PATH:<path key or relative path>}} — replaced at install time with the harness-resolved path (see paths; a relative arg under skills/ is mapped onto the harness's staged shape first — see layouts).",
       "SECTION": "{{SECTION:<name>}} — replaced by the agent composer with <harness>/<name>.md section content. Not a global substitution; out of scope for token-map.json (see contract)."
     }
   },
@@ -51,6 +51,13 @@
       "pi": { "base": "plugin_root", "relative": "docs/skills/skill-anatomy.md" }
     }
   },
+  "layouts": {
+    "description": "The tree each installer stages a resource into. `{{PATH:...}}` resolution reads it: a row is authored against the repository tree, so a harness that stages a resource in a different shape needs the row mapped onto its own. Only `skills` differs — Claude Code's plugin scan discovers `skills/<name>/SKILL.md` directly under `skills/`, so bin/installers/claude.mjs copies every skill flat and the group segment an authored row carries is dropped; bin/installers/pi.mjs preserves the repository grouping, so the row resolves as written.",
+    "skills": {
+      "claude": "flat",
+      "pi": "grouped"
+    }
+  },
   "agents": {
     "prefix": {
       "claude": "",
@@ -110,6 +117,7 @@
       "TOOL unknown: a {{TOOL:<key>}} with no entry in tools is a hard error — the map must be extended. This mirrors the generators (bin/installers/claude.mjs, bin/installers/pi.mjs), which throw on unknown tools.",
       "PATH named key: replace {{PATH:<key>}} with the resolved value of paths.<key>.<harness>.",
       "PATH relative: replace {{PATH:<relative>}} with plugin_root + '/' + <relative> (e.g. {{PATH:skills/workflow/plan/SKILL.md}}).",
+      "PATH relative skill: a relative arg whose first segment is `skills` is authored against the repository tree, which nests every skill at skills/<group>/<name>/<file>. Map it onto the harness's staged shape from layouts.skills.<harness>: `grouped` keeps it as written, `flat` drops the group segment (skills/<name>/<file>) because that installer copies skills flat. An arg with fewer than three segments is a hard error — no install has a skill one level under skills/.",
       "PATH resolution: a value may be a literal string, an ${ENV_VAR} token, or a {base, relative} spec. Resolve {base, relative} by joining relative onto the resolved base. Leave ${ENV_VAR} values verbatim — the harness expands them at runtime (claude's ${CLAUDE_PLUGIN_ROOT}).",
       "PATH unknown base: a {base, relative} spec whose base is not a key in paths is a hard error.",
       "SECTION: {{SECTION:<name>}} is resolved by the agent composer from <agents_dir>/<harness>/<name>.md; token-map.json does not substitute it. Installers must leave SECTION tokens untouched for the composer.",