@jaybeeuu/agent-cortex 2.9.0 → 2.11.0

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

@@ -5,6 +5,29 @@
 // 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.
+//
+// A closed bead's upstream is never the arbiter. Ralph cuts its branch from the
+// remote base (`git worktree add -b feature/<id> … origin/<base>`), and
+// `branch.autoSetupMerge` then makes that base the branch's upstream. A squash
+// merge rewrites the commits, so the branch stays ahead of its own upstream for
+// ever: counting commits against it refuses every landed ralph worktree, which is
+// the one case the content test exists to decide. A closed bead is therefore
+// decided by content alone, whatever its upstream is. An open bead keeps the
+// upstream refusal, because nothing about an open bead is proven.
+//
+// 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 +177,174 @@ 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 !== '');
+}
+
+/**
+ * The opening clause of a content-proof refusal. Two situations reach the content
+ * check — a closed bead whose branch has lost its upstream, and a closed bead whose
+ * branch still tracks the base it was cut from — and both are refused for the same
+ * reason: the base does not hold the branch's content. The clause states which
+ * situation applies, so a reader can tell an unpublished branch from one whose
+ * upstream cannot prove it.
+ * @param {string} branch
+ * @param {string | null} upstream the branch's remote-tracking ref, or null when it has none.
+ * @returns {string}
+ */
+function contentLead(branch, upstream) {
+  return upstream === null
+    ? `branch ${branch} has no remote-tracking branch`
+    : `branch ${branch} is not proven by ${upstream}`;
+}
+
+/**
+ * True when `ref` names the worktree's own branch, locally or as its
+ * remote-tracking ref. Comparing such a ref with the branch is a self-comparison:
+ * the diff is empty whatever the branch holds, so it proves nothing.
+ * @param {string} path
+ * @param {string} ref
+ * @param {string} branch
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @returns {Promise<boolean>}
+ */
+async function namesOwnBranch(path, ref, branch, git) {
+  const resolved = await git(path, ['rev-parse', '--symbolic-full-name', ref]);
+  if (!resolved.ok) return false;
+  const name = resolved.stdout.trim();
+  if (name === `refs/heads/${branch}`) return true;
+  // `refs/remotes/<remote>/<branch>`, whatever the remote is called.
+  return name.startsWith('refs/remotes/') && name.endsWith(`/${branch}`);
+}
+
+/**
+ * Decide whether a closed bead's 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, upstream: string | null }} target
+ *   `upstream` is the branch's remote-tracking ref, or null when it has none.
+ * @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, upstream }, baseRef, git) {
+  if (!beadClosed) {
+    return `branch ${branch} has no remote-tracking branch and its bead is not closed`;
+  }
+  /** @param {string} clause @returns {string} */
+  const refuse = (clause) => `${contentLead(branch, upstream)}: ${clause}`;
+  if (baseRef === null) {
+    return refuse('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 refuse(`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 refuse(`${baseRef} cannot be compared with it${suffix}`);
+  }
+  // A base that names the branch being deleted compares the branch with itself,
+  // whatever the branch holds. The test is on the ref, not on the tip: a branch cut
+  // from the base and never committed to holds the base's own commit, and that is a
+  // real proof — it has no content of its own to lose.
+  if (await namesOwnBranch(path, baseRef, branch, git)) {
+    return refuse(`${baseRef} names this branch, 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 refuse(`${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 refuse(`${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 refuse(`${baseRef} cannot be compared with it${suffix}`);
+  }
+  const unprovenPaths = splitNulPaths(unproven.stdout).length;
+  if (unprovenPaths > 0) {
+    return refuse(`${baseRef} does not hold this branch's version of ${unprovenPaths} path(s), so its content is not landed`);
+  }
+  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 = [];
 
@@ -182,11 +364,18 @@ async function findRefusals({ path, registered }, git) {
   if (dirtyPaths > 0) reasons.push(`worktree is dirty: ${dirtyPaths} uncommitted path(s)`);
 
   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 trackingRef = upstream.ok ? upstream.stdout.trim() : null;
+
+  // A closed bead is decided by content alone, never by its upstream: a ralph
+  // branch is cut from the remote base, so it tracks that base and stays ahead of
+  // it after a squash merge rewrites its commits. Counting commits against such an
+  // upstream refuses every landed ralph worktree. An open bead with no upstream has
+  // nothing to prove, so it lands here too and refuses below.
+  if (beadClosed || trackingRef === null) {
+    const lost = await findLostWork({ path, branch: registered.branch, beadClosed, upstream: trackingRef }, baseRef, git);
+    if (lost !== null) reasons.push(lost);
     return { branch: registered.branch, reasons };
   }
-  const trackingRef = upstream.stdout.trim();
   const unpushed = await git(path, ['rev-list', '--count', `${trackingRef}..HEAD`]);
   if (!unpushed.ok) return { branch: registered.branch, reasons: [...reasons, `branch ${registered.branch} cannot be compared with ${trackingRef}: ${unpushed.stderr.trim()}`] };
   const unpushedCommits = Number.parseInt(unpushed.stdout.trim(), 10);
@@ -231,12 +420,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 +443,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 +470,61 @@ 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 is proven by content alone, whatever its upstream is: many
+merge methods delete the remote branch when the work lands, and a branch cut from
+the remote base tracks that base, which a squash merge leaves behind. 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 names the worktree's own branch compares the branch with itself, so it
+proves nothing: the worktree is kept and refused, as it is when no base resolves.
+
+An open bead is proven by its upstream instead, and only with --remove-orphans: its
+branch must carry an upstream and no commit unpushed to it. With no upstream it is
+refused whatever its content says.
 `;
 
 /** 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 +550,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.",