@jaybeeuu/agent-cortex 2.9.0 → 2.11.0

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';
@@ -64,6 +71,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 +110,49 @@ 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.
+ * @property {'file' | 'default'} source  Whether the tiers were read from the file.
+ */
+
 /** A usage mistake: the caller asked for something malformed. Exit code 2. */
 export class UsageError extends Error {}
 
@@ -163,6 +237,126 @@ 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: [], source: 'default' };
+
+  /** @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);
+  }
+
+  // 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: [], source: 'default' };
+  }
+
+  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, 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: [], source: 'file' };
+}
+
+/**
+ * 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 +435,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}"`);
@@ -337,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)
@@ -414,9 +756,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 (;;) {
@@ -447,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}
@@ -516,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/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,18 @@ 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, and one proof guard that follows the bead's state — unpushed commits on an open bead, unproven content on a closed one.
+
+**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.
+
+**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.