@jaybeeuu/agent-cortex 2.10.0 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 2.11.0
+
+### Minor Changes
+
+- 0a98d7b: Open a `prioritise-work` run with a summary of the committed strategy instead of a question. A new
+  `strategy.mjs summary` subcommand validates the file first, then prints a handful of lines — the
+  path it read, the version, the newest change-log entry, the themes, the two admissibility lists as
+  up to two bullets each, and the deadline factors when the file states them — so the digest cannot
+  describe a strategy that is not on disk. The skill shows it and asks "what should change?" before
+  the interview; with no strategy file it exits `3` and the skill goes straight to the first-run
+  interview with no digest; with an invalid or partly missing one it exits `1` and names what is wrong
+  rather than presenting it as current. The change requires no new section of the strategy file, so
+  every strategy already committed still validates: `## What counts as value` and `## Explicitly out
+of scope` are summarised as the admissibility lists they are, never as a ranking order, and
+  `## Deadline tiers` is summarised narrowest first, the order the queue applies the factors, whatever
+  order the file holds the rows in.
+
+  The script contract moved to the skill's `REFERENCE.md` so `SKILL.md` stays within its length target.
+
+### Patch Changes
+
+- 5a6a14a: Let the content proof decide a closed bead's worktree, whatever its upstream is.
+  `prune-worktrees.mjs` still refused every worktree ralph created, because ralph
+  cuts its branch from the remote base (`git worktree add -b feature/<id> …
+origin/main`), `branch.autoSetupMerge` makes that base the branch's upstream, and
+  the squash merge that lands the work rewrites its commits — so the branch stays
+  ahead of its own base for ever and the unpushed-commit check, which ran first,
+  always fired. A closed bead is now decided by content alone: the base must hold
+  the branch's own version of every path the branch changed since their merge base,
+  and the refusal names that content when it does not. An open bead keeps the
+  upstream refusal, and with no upstream it is refused whatever the content says.
+  The base guard now tests the ref instead of the tip: a base that names the
+  worktree's own branch (local or remote-tracking) is a self-comparison and
+  refuses, while a branch cut from the base and never committed to holds the base's
+  own commit and is removed — the case every fresh ralph worktree used to reach.
+
 ## 2.10.0
 
 ### Minor Changes

package/agents/guppi/agent.md

@@ -92,7 +92,8 @@ A wish for a different order is a `prioritise-work` change, never a boundary one
 - **Never merges.** A pull request is a human gate. guppi may read one and hand it to a reviewer.
 - **Never pushes.** No `git push`, no release, no version bump of this package.
 - **Never overrides a priority silently.** "This should be higher" means the strategy is wrong,
-  stale, or has shifted. Open the `prioritise-work` interview, record the change, then re-rank.
+  stale, or has shifted. Run `prioritise-work`, which opens with a digest of the current strategy,
+  record the change, then re-rank.
 - **Never invents a strategy.** If the strategy file is missing or invalid, say so plainly and offer
   the interview. Do not guess priorities.
 - **Propose-only and resident.** guppi is a standing collaborator in one session. It is not a task

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"

package/skills/workflow/prioritise-work/REFERENCE.md

@@ -0,0 +1,34 @@
+# The strategy scripts
+
+The contract behind [SKILL.md](SKILL.md): what each subcommand prints, and the exit codes the
+skill routes on. The workflow lives in `SKILL.md`; this file is the reference for one run.
+
+Two scripts, five subcommands, zero dependencies, no tracker access. `strategy.mjs` reads and
+writes the strategy file; `challenge.mjs` reads it and prints a trail entry. No run creates, tags
+or closes a bead.
+
+| Command | Behaviour | Exit |
+|---|---|---|
+| `init` | Writes the template, stamped with today's date; refuses an existing file | 0 written, 1 refused |
+| `validate` | Checks the version integer, the date, the change log, the deadline tiers and every required section; prints the file to stdout when valid | 0 valid, 1 invalid |
+| `bump` | Refuses an invalid file or an empty `--reason`, raises the version by one, records today, appends the change-log line | 0 bumped, 1 invalid file, 2 no or empty `--reason` |
+| `summary` | Validates first, then prints the digest a run opens with: the path it read, the version, the newest change-log entry, the themes and the two admissibility lists as up to two bullets each, and the deadline factors when the file states a table | 0 summarised, 1 invalid, 3 no file |
+| `record` (`challenge.mjs`) | Refuses an order or a resolution the strategy does not support; prints one bead-trail entry | 0 recorded, 1 refused |
+
+`summary` is the one command that separates "absent" from "wrong". It exits `3` only when the file
+is not there, because the skill's next move is the first-run interview and no digest; a file that is
+present but fails the shape check exits `1` with the validator's own lines, never a digest. Both
+paths print nothing to stdout, so a caller can show whatever arrives there without deciding what to
+hide.
+
+`validate` splits its output: status and errors go to stderr, the rubric goes to stdout.
+`validate > rubric.md` captures the rubric alone, which is how a scorer loads it. A failing run names
+the file and lists one line per defect, so one fix round clears the whole file.
+
+The date is checked as a **calendar** date, not as a shape. `2026-02-31` and `2026-04-31` fail in
+both `validate` and `--today`, because V8's ISO parser rolls them into the next month and accepts
+them; `2024-02-29` passes and `2026-02-29` does not. A rolled date records a change on a day it did
+not happen.
+
+Exit code 2 means a malformed call — an unknown subcommand, a bad `--today`, or a missing or empty
+`--reason`. `--today YYYY-MM-DD` exists so a test pins the recorded date; a person accepts the default.

package/skills/workflow/prioritise-work/SKILL.md

@@ -47,17 +47,29 @@ Use that rather than `git add -f`: an ignored file disappears from `git status`,
 
 **One strategy, one workspace.** A rubric answers the question "what is worth doing here", so each bd workspace carries its own. The HITL queue reads several scopes at once; the **personal** scope's strategy is therefore also where the daily line lives, and the queue quotes it above the ranked list to say which scope the day belongs to. Write it under `## Current themes`, name the scopes first, then an em dash and the reason. `validate` does not require it: a strategy with no daily line is valid, and the queue says the note is missing rather than inventing one.
 
-## Workflow
-
-### First run — no strategy file
+## Step one — summarise what is already there
 
-1. Confirm the file is absent:
+A run never opens with a question. Run the summary first: it reads the committed file, so it cannot describe a strategy that is not on disk, and it shows the owner what they are about to edit.
 
 ```bash
-node <skill-scripts>/strategy.mjs validate
+node <skill-scripts>/strategy.mjs summary
 ```
 
-It exits 1 and names the path it looked for. Do not search the repository for an alternative: one strategy, one location, or two scorers rank against two rubrics.
+The digest is all it prints: the path it read, the version, the newest change-log entry, the themes, the two admissibility lists as up to two bullets each, and — when the file states a table — the deadline factors in the order the queue applies them. It is not a re-print — open the file for what a cut line left out.
+
+| Exit | The file | What to do |
+|---|---|---|
+| 0 | valid | Show the digest, then ask "what should change?" |
+| 3 | absent | Say there is no strategy yet and take the first-run interview below. Print no digest. |
+| 1 | invalid or partly missing | Never present it as current. Say what it named — the empty or missing section, the field it could not read — and fix the file or re-interview before anything is scored against it. |
+
+**The file gains no new section.** An admissibility heading would fail every strategy already committed, because `validate` gates them all. The file says what is worth doing and what is not: `## Current themes` is what the month is for, `## What counts as value` is the test a bead must pass, and `## Explicitly out of scope` is the work the month rules out — the last two are the digest's **admissibility** lines. What orders the beads that pass them is the **scoring rubric**, RICE with its multipliers, never this file. The one ordered rule set the file states is `## Deadline tiers`, and the digest prints its rows narrowest first whatever order the file holds them in; with no table the documented default applies and the digest says nothing about deadlines.
+
+## Workflow
+
+### First run — no strategy file
+
+1. The summary exited `3`: the file is absent. Do not search the repository for an alternative — one strategy, one location, or two scorers rank against two rubrics.
 
 2. Write the shipped template to that path. This is the copy step — the script resolves its own template, so it works from either install layout:
 
@@ -79,7 +91,7 @@ node <skill-scripts>/strategy.mjs validate
 
 ### Later runs — the file exists
 
-6. Read the current strategy and check its `**Updated:**` date. A date from an earlier month is stale: re-run the interview before scoring anything against it.
+6. The summary is step one above, so the version and the last change are already in front of the owner. A last change from an earlier month is stale: re-run the interview before scoring anything against it.
 
 7. Ask the four questions again, plus the confidence question, and edit the sections that changed. Edit the deadline-tier table too when a due date should move a rank further or sooner.
 
@@ -109,20 +121,7 @@ The confidence question matters as much as the other four: effort and impact est
 
 ## The scripts
 
-Two scripts, four subcommands, zero dependencies, no tracker access. `strategy.mjs` reads and writes the strategy file; `challenge.mjs` reads it and prints a trail entry. No run creates, tags or closes a bead.
-
-| Command | Behaviour | Exit |
-|---|---|---|
-| `init` | Writes the template, stamped with today's date; refuses an existing file | 0 written, 1 refused |
-| `validate` | Checks the version integer, the date, the change log, the deadline tiers and every required section; prints the file to stdout when valid | 0 valid, 1 invalid |
-| `bump` | Refuses an invalid file or an empty `--reason`, raises the version by one, records today, appends the change-log line | 0 bumped, 1 refused |
-| `record` (`challenge.mjs`) | Refuses an order or a resolution the strategy does not support; prints one bead-trail entry | 0 recorded, 1 refused |
-
-`validate` splits its output: status and errors go to stderr, the rubric goes to stdout. `validate > rubric.md` captures the rubric alone, which is how a scorer loads it. A failing run names the file and lists one line per defect, so one fix round clears the whole file.
-
-The date is checked as a **calendar** date, not as a shape. `2026-02-31` and `2026-04-31` fail in both `validate` and `--today`, because V8's ISO parser rolls them into the next month and accepts them; `2024-02-29` passes and `2026-02-29` does not. A rolled date records a change on a day it did not happen.
-
-Exit code 2 means a malformed call — an unknown subcommand or a bad `--today`. `--today YYYY-MM-DD` exists so a test pins the recorded date; a person accepts the default.
+Four subcommands of `strategy.mjs` and one of `challenge.mjs`, all zero dependencies with no tracker access: [REFERENCE.md](REFERENCE.md) lists what each one prints and the exit codes the steps above route on.
 
 ## Hand edits and forgotten bumps
 
@@ -137,7 +136,7 @@ A hand edit that changes a section but forgets `bump` still passes `validate`: t
 
 ## Verification checklist
 
-- [ ] `node <skill-scripts>/strategy.mjs validate` exits 0 and printed the rubric, and every section carries the owner's words.
+- [ ] The run opened with the digest — file, version, last change, themes, admissibility, deadline factors — before it asked anything, and `node <skill-scripts>/strategy.mjs validate` exits 0 with the rubric printed.
 - [ ] The version is one higher than the previous file for an update, or `1` for a new one, and the change log names it.
 - [ ] A challenged order moved only after a bump, and the record names what moved.
 - [ ] No bead was created, tagged or closed by this skill; `git ls-files --error-unmatch .agent-cortex/working-docs/strategy.md` succeeds.
@@ -145,6 +144,7 @@ A hand edit that changes a section but forgets `bump` still passes `validate`: t
 ## See Also
 
 - [CHALLENGE.md](CHALLENGE.md) — the sequence, the refusals and the no-change path when the order is challenged.
+- [REFERENCE.md](REFERENCE.md) — every subcommand, what it prints, and the exit codes that tell a first run from an invalid strategy.
 - [plan](../../workflow/plan/SKILL.md) — shapes one feature into beads; this skill orders the beads that exist.
 - [bd-tool](../../productivity/bd-tool/SKILL.md) — where operational state lives, and why a durable document does not belong there.
 - [score-bead](../../workflow/score-bead/SKILL.md) — turns this rubric into a RICE record on a bead; the queue's daily line is read by [hitl-queue](../hitl-queue/SCOPES.md).

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

@@ -6,11 +6,12 @@
 // and never a scratch file: operational state belongs in the bead trail, and durable
 // documents that are reviewed, diffed and versioned belong in git.
 //
-// Three subcommands, and nothing else:
+// Four subcommands, and nothing else:
 //
 //   node strategy.mjs init     [--file <path>]             write the template
 //   node strategy.mjs validate [--file <path>]             check the shape, then print it
 //   node strategy.mjs bump     [--file <path>] [--today d] raise the version, set the date
+//   node strategy.mjs summary  [--file <path>]             the digest a run opens with
 //
 // `validate` prints the rubric to stdout only after it passes, so a scorer can never
 // read a stale or malformed strategy: the file and the proof of its shape arrive
@@ -22,8 +23,14 @@
 // Zero runtime dependencies, async fs only. `skills/*/scripts` sits outside the
 // check-no-sync scan, and this script stays async anyway so the rule holds everywhere.
 //
-// Exit codes: 0 the file is valid, 1 the file is invalid or the operation refused,
-// 2 the caller asked for something malformed.
+// `summary` is what the skill prints before it asks anything, and it exists so the digest
+// is read off the file rather than re-derived by an agent: it validates first, then reports
+// the version, the newest change-log entry, the themes, the two admissibility lists and the
+// deadline factors — each one read from the file, none restated from elsewhere.
+//
+// Exit codes: 0 the file is valid or summarised, 1 the file is invalid or the operation
+// refused, 2 the caller asked for something malformed, 3 `summary` found no strategy file —
+// a first run, which the skill answers with the interview and no digest.
 
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
@@ -143,6 +150,7 @@ const MS_PER_MINUTE = 60_000;
  * @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.
+ * @property {'file' | 'default'} source  Whether the tiers were read from the file.
  */
 
 /** A usage mistake: the caller asked for something malformed. Exit code 2. */
@@ -268,7 +276,7 @@ function parseTierRow(when, factorText) {
  */
 export function parseDeadlineTiers(text) {
   const body = sectionBody(text.split('\n'), DEADLINE_TIERS_SECTION);
-  if (body === null) return { ok: true, tiers: [...DEFAULT_DEADLINE_TIERS], errors: [] };
+  if (body === null) return { ok: true, tiers: [...DEFAULT_DEADLINE_TIERS], errors: [], source: 'default' };
 
   /** @type {DeadlineTier[]} */
   const rows = [];
@@ -294,8 +302,10 @@ export function parseDeadlineTiers(text) {
     rows.push(parsed.tier);
   }
 
+  // A heading with no readable row states no tiers, so the default applies and the file is
+  // not credited with a table it does not carry.
   if (rows.length === 0 && errors.length === 0) {
-    return { ok: true, tiers: [...DEFAULT_DEADLINE_TIERS], errors: [] };
+    return { ok: true, tiers: [...DEFAULT_DEADLINE_TIERS], errors: [], source: 'default' };
   }
 
   if (errors.length === 0) {
@@ -305,14 +315,14 @@ export function parseDeadlineTiers(text) {
     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 };
+  if (errors.length > 0) return { ok: false, tiers: [...DEFAULT_DEADLINE_TIERS], errors, source: 'file' };
 
   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: [] };
+  return { ok: true, tiers: [...within, ...beyond, ...overdue], errors: [], source: 'file' };
 }
 
 /**
@@ -524,16 +534,161 @@ export function bumpStrategy(text, { today, reason }) {
   return { from, to, updated: today, reason: cleanReason, line, text: appendChangeLog(bumped, line) };
 }
 
+// ─── Summary ──────────────────────────────────────────────────────────────────
+
+/**
+ * How many bullets the digest quotes from each admissibility list. Two keeps the digest a
+ * handful of lines; the count of what it left out points the reader back at the file.
+ */
+const SUMMARY_ITEMS = 2;
+
+/** The longest one bullet may run in the digest, so one answer cannot re-print a section. */
+const SUMMARY_ITEM_LENGTH = 100;
+
+/**
+ * The items under one heading: each bullet with the continuation lines that belong to it,
+ * and the template's HTML-comment guidance skipped. A bullet that wraps over several lines
+ * is one item, so a quoting rule is read whole rather than sliced at its first line.
+ * @param {string[]} lines @param {string} title @returns {string[]}
+ */
+function sectionItems(lines, title) {
+  const body = sectionBody(lines, title);
+  if (body === null) return [];
+
+  /** @type {string[]} */
+  const items = [];
+  let inComment = false;
+  for (const line of body) {
+    const trimmed = line.trim();
+    if (inComment) {
+      if (trimmed.includes('-->')) inComment = false;
+      continue;
+    }
+    if (trimmed.startsWith('<!--')) {
+      if (!trimmed.includes('-->')) inComment = true;
+      continue;
+    }
+    const bullet = /^[-*][ \t]+(.+)$/.exec(trimmed);
+    if (bullet !== null) {
+      items.push(bullet[1].trim());
+      continue;
+    }
+    if (trimmed === '' || items.length === 0) continue;
+    items[items.length - 1] = `${items[items.length - 1]} ${trimmed}`;
+  }
+  return items;
+}
+
+/**
+ * One item as the digest shows it, cut when it is long. A cut item says so, because a
+ * silently shortened rule reads as the whole rule.
+ * @param {string} item @returns {string}
+ */
+function shorten(item) {
+  return item.length <= SUMMARY_ITEM_LENGTH ? item : `${item.slice(0, SUMMARY_ITEM_LENGTH).trimEnd()}…`;
+}
+
+/**
+ * One section as a single digest line: at most `SUMMARY_ITEMS` bullets, then how many the
+ * digest left out, so the reader knows the file still says more.
+ * @param {string[]} items @returns {string}
+ */
+function digestLine(items) {
+  const shown = items.slice(0, SUMMARY_ITEMS).map(shorten);
+  if (shown.length === 0) return '(none written)';
+  const hidden = items.length - shown.length;
+  return hidden === 0 ? shown.join(' · ') : `${shown.join(' · ')} · (+${hidden} more in the file)`;
+}
+
+/**
+ * A tier's distance in the largest unit that divides it, so the digest repeats the spelling
+ * the table uses: 1440 minutes reads `1d`, and 90 reads `90m`.
+ * @param {number} minutes @returns {string}
+ */
+function spanText(minutes) {
+  if (minutes % TIER_UNIT_MINUTES.d === 0) return `${minutes / TIER_UNIT_MINUTES.d}d`;
+  if (minutes % TIER_UNIT_MINUTES.h === 0) return `${minutes / TIER_UNIT_MINUTES.h}h`;
+  return `${minutes}m`;
+}
+
+/**
+ * One tier as the digest shows it: the phrase the table's row uses, then the factor.
+ * @param {DeadlineTier} tier @returns {string}
+ */
+function tierText(tier) {
+  if (tier.kind === 'overdue') return `overdue ×${tier.factor}`;
+  return `${tier.kind === 'within' ? 'within' : 'more than'} ${spanText(tier.minutes)} ×${tier.factor}`;
+}
+
+/**
+ * The deadline factors as one digest line, narrowest row first. The order is part of the
+ * rule — the queue multiplies by the narrowest row the remaining time fits inside — so the
+ * whole table prints: a truncated order would summarise a different rule.
+ * @param {DeadlineTier[]} tiers @returns {string}
+ */
+function deadlineLine(tiers) {
+  return tiers.map(tierText).join(' · ');
+}
+
+/**
+ * When the rubric last changed and why: the newest change-log entry, because the log is
+ * written oldest first and `validate` already proves it names the version the file carries.
+ * A file with no entry says so rather than borrowing the header date as a reason.
+ * @param {string[]} lines @param {string} updated @returns {string}
+ */
+function lastChange(lines, updated) {
+  const entries = (sectionBody(lines, CHANGE_LOG_SECTION) ?? [])
+    .map((line) => CHANGE_LOG_ENTRY.exec(line))
+    .filter((match) => match !== null);
+  const newest = entries[entries.length - 1];
+  if (newest === null || newest === undefined) return `${updated} — no change-log entry, so no reason is on file`;
+  return `${newest[1]} v${newest[2]}: ${newest[3]}`;
+}
+
+/**
+ * The digest the skill opens with: the file it read, the version, the newest change-log
+ * entry, the themes, the two admissibility lists, and the deadline factors when the file
+ * states them — a handful of lines, never a re-print.
+ *
+ * Nothing here is a ranking order, and the labels must not suggest one. `## What counts as
+ * value` and `## Explicitly out of scope` are admissibility: the test a bead passes to earn
+ * work, and the work the month rules out. What orders the beads that pass them is the
+ * scoring rubric — RICE with its multipliers — not this file. The one ordered rule set the
+ * file does state is `## Deadline tiers`, printed in its own order and omitted entirely when
+ * the section is absent, because the documented default then applies and the file is silent.
+ *
+ * None of these is a section of its own and none must become one. `validate` gates every
+ * strategy already committed, so a new required section would fail all of them.
+ * @param {string} text @param {string} file @param {StrategyReport} report  A passing report.
+ * @returns {string}
+ */
+export function summariseStrategy(text, file, report) {
+  const lines = text.split('\n');
+  const digest = [
+    `${file} — strategy v${report.version}`,
+    `  last change: ${lastChange(lines, report.updated ?? 'no date recorded')}`,
+    `  themes: ${digestLine(sectionItems(lines, 'Current themes'))}`,
+    `  admissibility — what counts as value: ${digestLine(sectionItems(lines, 'What counts as value'))}`,
+    `  admissibility — out of scope: ${digestLine(sectionItems(lines, 'Explicitly out of scope'))}`,
+  ];
+  const tiers = parseDeadlineTiers(text);
+  if (tiers.source === 'file') digest.push(`  deadline factors: ${deadlineLine(tiers.tiers)}`);
+  return `${digest.join('\n')}\n`;
+}
+
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
 /** @type {readonly string[]} */
-export const COMMANDS = /** @type {const} */ (['init', 'validate', 'bump']);
+export const COMMANDS = /** @type {const} */ (['init', 'validate', 'bump', 'summary']);
 
 const USAGE = `Usage: node strategy.mjs <${COMMANDS.join('|')}> [options]
 
   init       Write the shipped template to the strategy path. Refuses to overwrite.
   validate   Check the shape and print the file to stdout only when it passes.
   bump       Raise the version by one, record today's date and append the reason.
+  summary    Print the digest to open a run with: path, version, last change, admissibility,
+             deadline factors. Exits 3 when no strategy file exists, so a first run is told
+             apart from a strategy that is present but invalid.
 
 Options:
   --file <path>    Strategy file (default: ${DEFAULT_FILE}, relative to the repository root)
@@ -637,6 +792,15 @@ export async function resolveStrategyPath({ file = DEFAULT_FILE, cwd = process.c
   return resolve(base, file);
 }
 
+/**
+ * The one line every subcommand prints when the strategy file is not there yet. Reused so
+ * `summary` and `validate` cannot drift into two descriptions of the same absence.
+ * @param {string} file @returns {string}
+ */
+function missingMessage(file) {
+  return `${file} does not exist — run "init" and interview the owner, or pass --file <path>`;
+}
+
 /**
  * Build the report text for one failed run.
  * @param {string} file @param {string[]} errors @returns {string}
@@ -706,14 +870,33 @@ export async function runCli({
       return 0;
     }
 
+    // `summary` separates the two states the skill answers differently: no file is a first
+    // run, which takes the interview and no digest; a file that fails the shape check is
+    // reported as what it is, never as the current strategy.
+    if (options.command === 'summary') {
+      /** @type {string} */
+      let current;
+      try {
+        current = await readFile(file, 'utf8');
+      } catch {
+        writeError(`${missingMessage(file)}\n`);
+        return 3;
+      }
+      const currentReport = validateStrategy(current);
+      if (!currentReport.ok) {
+        writeError(formatErrors(file, currentReport.errors));
+        return 1;
+      }
+      write(summariseStrategy(current, file, currentReport));
+      return 0;
+    }
+
     /** @type {string} */
     let text;
     try {
       text = await readFile(file, 'utf8');
     } catch {
-      throw new StrategyError(
-        `${file} does not exist — run "init" and interview the owner, or pass --file <path>`,
-      );
+      throw new StrategyError(missingMessage(file));
     }
 
     if (options.command === 'bump') {

package/skills/workflow/ralph/REFERENCE.md

@@ -236,11 +236,13 @@ node skills/workflow/ralph/scripts/prune-worktrees.mjs --base <ref>     # prove
 
 **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 or unreadable, branch with unpushed commits, and branch whose content is not proven landed.
+**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, and one proof guard that follows the bead's state — unpushed commits on an open bead, unproven content on a closed one.
 
-**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.
+**A closed bead is decided by content alone, whatever its upstream is.** Ralph cuts its branch from the remote base (`git worktree add -b feature/<id> … origin/main`), so `branch.autoSetupMerge` makes that base the branch's upstream, and a squash merge rewrites the commits: the branch stays ahead of its own upstream for ever. Counting commits against that upstream refuses every landed ralph worktree. So the guard is content, upstream or not: the base must hold the branch's own version of every path the branch changed since their merge base. No upstream is not a refusal by itself — a merge that deletes the branch also deletes its upstream, so no remote-tracking branch is the normal end of landed work. 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.
 
-**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.
+**An open bead is decided by its upstream.** With no upstream it is refused on that alone, whatever its content says; with one, every commit must be pushed to it.
+
+**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 names the worktree's own branch, 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

@@ -14,6 +14,15 @@
 // 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
@@ -200,10 +209,45 @@ function splitNulPaths(stdout) {
 }
 
 /**
- * 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.
+ * 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
@@ -227,46 +271,51 @@ function splitNulPaths(stdout) {
  * 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 {{ 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 }, baseRef, git) {
+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 `branch ${branch} has no remote-tracking branch and the base branch cannot be resolved, so its content cannot be proven landed`;
+    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 `branch ${branch} has no remote-tracking branch and its tip cannot be read${suffix}`;
+    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 `branch ${branch} has no remote-tracking branch and ${baseRef} cannot be compared with it${suffix}`;
+    return refuse(`${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`;
+  // 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 `branch ${branch} has no remote-tracking branch and ${baseRef} cannot be compared with it${suffix}`;
+    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 `branch ${branch} has no remote-tracking branch and ${baseRef} cannot be compared with it${suffix}`;
+    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.
@@ -277,11 +326,11 @@ async function findLostWork({ path, branch, beadClosed }, baseRef, git) {
   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}`;
+    return refuse(`${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 refuse(`${baseRef} does not hold this branch's version of ${unprovenPaths} path(s), so its content is not landed`);
   }
   return null;
 }
@@ -315,12 +364,18 @@ async function findRefusals({ path, registered, beadClosed }, git, baseRef) {
   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) {
-    const lost = await findLostWork({ path, branch: registered.branch, beadClosed }, baseRef, git);
+  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);
@@ -422,15 +477,20 @@ 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.
+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. */