@jaybeeuu/agent-cortex 2.8.0 → 2.10.0

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

@@ -0,0 +1,756 @@
+// @ts-check
+// The strategy file: create it, validate it, version it.
+//
+// The prioritisation strategy is a committed document — the rubric a scorer reads
+// before it judges a bead's reach, impact, confidence and effort. It is never a bead
+// 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:
+//
+//   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
+//
+// `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
+// together. Status goes to stderr, so `validate > rubric.md` captures the rubric alone.
+//
+// The script reads and writes one file and shells out to nothing — it never calls `bd`.
+// A test puts a stub `bd` on PATH and asserts it is never invoked.
+//
+// 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.
+
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// ─── Contract ─────────────────────────────────────────────────────────────────
+
+/**
+ * The sections every strategy must carry, in reading order. One interview question
+ * produces each one, so the template, the skill's questions and this list agree.
+ * @type {readonly string[]}
+ */
+export const REQUIRED_SECTIONS = [
+  'Current themes',
+  'What counts as value',
+  'How to judge confidence',
+  'Explicitly out of scope',
+  'How to calibrate effort',
+];
+
+/**
+ * The default location, relative to the consuming repository's root: the working-docs
+ * root, beside the HITL handoff directories. It is the one file in that directory the
+ * repository commits.
+ */
+export const DEFAULT_FILE = '.agent-cortex/working-docs/strategy.md';
+
+/**
+ * The shipped template, resolved from this script rather than from a hardcoded path, so
+ * it is found in both install layouts (grouped on pi, flattened on Claude Code).
+ */
+export const TEMPLATE_FILE = fileURLToPath(new URL('../templates/strategy.md', import.meta.url));
+
+/**
+ * The section that records why the rubric changed. Optional in a hand-written file —
+ * `bump` adds it when it is absent — so a strategy created before this section existed
+ * stays valid.
+ */
+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}$/;
+
+/** A markdown heading, with its title captured. */
+const HEADING = /^\s*##\s+(.*?)\s*$/;
+
+/** The version and the date are stored as bold key/value lines, so a reader can grep them. */
+const FIELD = /^[ \t]*[-*][ \t]*\*\*([A-Za-z]+):\*\*[ \t]*(\S.*?)[ \t]*$/;
+
+/** The markup in front of a field's value, so a new value replaces the old one whole. */
+const FIELD_PREFIX = /^([ \t]*[-*][ \t]*\*\*[A-Za-z]+:\*\*[ \t]*)\S.*?[ \t]*$/;
+
+/** One change-log line: the date it landed, the version it produced, and the reason. */
+const CHANGE_LOG_ENTRY = /^[ \t]*[-*][ \t]+(\d{4}-\d{2}-\d{2})[ \t]+v(\d+):[ \t]*(.+?)[ \t]*$/;
+
+/** One row of the deadline-tier table, with the cells the pipes delimit. */
+const TIER_ROW = /^[ \t]*\|(.*)\|[ \t]*$/;
+
+/** The table's header row, skipped as a label rather than read as a tier. */
+const TIER_HEADER = /^(remaining|time|when|deadline)$/i;
+
+/** The table's `|---|:--:|` rule, which carries no value. */
+const TIER_RULE = /^:?-{2,}:?$/;
+
+/** `within 7d` and `<= 7d`: the factor earned at or inside this much time left. */
+const TIER_WITHIN = /^(?:within|<=)\s+(\d+)\s*([mhd])$/i;
+
+/** `more than 7d` and `> 7d`: the factor for anything further out. */
+const TIER_BEYOND = /^(?:more than|>)\s+(\d+)\s*([mhd])$/i;
+
+/** `overdue`: the factor for a deadline already passed. */
+const TIER_OVERDUE = /^overdue$/i;
+
+/** A factor: a positive number, in the plain form a reader can check. */
+const TIER_FACTOR = /^\d+(?:\.\d+)?$/;
+
+/** How long each unit in a tier row lasts. */
+const TIER_UNIT_MINUTES = Object.freeze(/** @type {const} */ ({ m: 1, h: 60, d: 1440 }));
+
+/** How many milliseconds a minute holds, for turning a tier's minutes into a distance. */
+const MS_PER_MINUTE = 60_000;
+
+/**
+ * One deadline tier: the factor a bead earns at a stated distance from its deadline.
+ * @typedef {{ kind: 'overdue', factor: number }
+ *   | { kind: 'within', minutes: number, factor: number }
+ *   | { kind: 'beyond', minutes: number, factor: number }} DeadlineTier
+ */
+
+/**
+ * What `parseDeadlineTiers` found.
+ * @typedef {object} DeadlineTiersReport
+ * @property {boolean} ok
+ * @property {DeadlineTier[]} tiers  The parsed tiers, or the documented default when absent.
+ * @property {string[]} errors       One line per defect in the table.
+ */
+
+/** A usage mistake: the caller asked for something malformed. Exit code 2. */
+export class UsageError extends Error {}
+
+/** The strategy file is absent, or its shape is wrong. Exit code 1. */
+export class StrategyError extends Error {}
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * What `validate` found.
+ * @typedef {object} StrategyReport
+ * @property {boolean} ok
+ * @property {number} [version]  Present only when the version parses.
+ * @property {string} [updated]  Present only when the date parses.
+ * @property {string[]} errors   One line per defect, each naming the field or section.
+ */
+
+/**
+ * What `bump` produced.
+ * @typedef {object} BumpReport
+ * @property {number} from
+ * @property {number} to
+ * @property {string} updated
+ * @property {string} reason
+ * @property {string} line  The change-log line the bump appended.
+ * @property {string} text
+ */
+
+// ─── Value helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Every `**Key:** value` line in the text, keyed by the lower-cased key.
+ * @param {string} text @returns {Map<string, string>}
+ */
+function fields(text) {
+  /** @type {Map<string, string>} */
+  const found = new Map();
+  for (const line of text.split('\n')) {
+    const match = FIELD.exec(line);
+    if (match === null) continue;
+    const key = match[1].toLowerCase();
+    if (!found.has(key)) found.set(key, match[2]);
+  }
+  return found;
+}
+
+/**
+ * Replace the value of a `**Key:** value` line, keeping its markup and indentation.
+ * Throws when the line is absent, because a bump that cannot date the file has nothing
+ * honest to write.
+ * @param {string} text @param {string} key @param {string} value @returns {string}
+ */
+function setField(text, key, value) {
+  const wanted = key.toLowerCase();
+  let replaced = false;
+  return text
+    .split('\n')
+    .map((line) => {
+      const match = FIELD.exec(line);
+      if (replaced || match === null || match[1].toLowerCase() !== wanted) return line;
+      replaced = true;
+      return line.replace(FIELD_PREFIX, (_match, prefix) => `${prefix}${value}`);
+    })
+    .join('\n');
+}
+
+/**
+ * The body lines of `## <title>`, or null when the heading is absent. The body stops at
+ * the next `##` heading; a `###` sub-heading stays body.
+ * @param {string[]} lines @param {string} title @returns {string[] | null}
+ */
+function sectionBody(lines, title) {
+  const wanted = title.toLowerCase();
+  const start = lines.findIndex((line) => HEADING.exec(line)?.[1].toLowerCase() === wanted);
+  if (start === -1) return null;
+
+  const body = [];
+  for (const line of lines.slice(start + 1)) {
+    if (HEADING.test(line)) break;
+    body.push(line);
+  }
+  return body;
+}
+
+/**
+ * The minutes a tier row's `<number><unit>` names.
+ * @param {string} count @param {string} unit @returns {number}
+ */
+function tierMinutes(count, unit) {
+  const key = /** @type {'m'|'h'|'d'} */ (unit.toLowerCase());
+  return Number(count) * TIER_UNIT_MINUTES[key];
+}
+
+/**
+ * One table row as a tier, or a message naming what the row got wrong.
+ * @param {string} when        The "Remaining" cell.
+ * @param {string} factorText  The "Factor" cell.
+ * @returns {{ tier: DeadlineTier } | { error: string }}
+ */
+function parseTierRow(when, factorText) {
+  const factor = TIER_FACTOR.test(factorText) ? Number(factorText) : 0;
+  if (factor <= 0) return { error: `factor "${factorText}" is not a positive number` };
+
+  if (TIER_OVERDUE.test(when)) return { tier: { kind: 'overdue', factor } };
+  const within = TIER_WITHIN.exec(when);
+  if (within !== null) return { tier: { kind: 'within', minutes: tierMinutes(within[1], within[2]), factor } };
+  const beyond = TIER_BEYOND.exec(when);
+  if (beyond !== null) return { tier: { kind: 'beyond', minutes: tierMinutes(beyond[1], beyond[2]), factor } };
+  return { error: `"${when}" is not "overdue", "within <time>" or "more than <time>"` };
+}
+
+/**
+ * Read the deadline tiers out of a strategy: the `## Deadline tiers` table, or the
+ * documented default when the section is absent or carries no row.
+ *
+ * A table that is present must be complete — exactly one `overdue` row, exactly one
+ * `more than <time>` row, and at least one `within <time>` row — because a factor that
+ * silently fell back to a default would make the rise depend on a file the reader cannot
+ * see. Every defect is reported, so one run fixes the whole table.
+ * @param {string} text @returns {DeadlineTiersReport}
+ */
+export function parseDeadlineTiers(text) {
+  const body = sectionBody(text.split('\n'), DEADLINE_TIERS_SECTION);
+  if (body === null) return { ok: true, tiers: [...DEFAULT_DEADLINE_TIERS], errors: [] };
+
+  /** @type {DeadlineTier[]} */
+  const rows = [];
+  /** @type {string[]} */
+  const errors = [];
+  let firstTableLine = true;
+
+  for (const line of body) {
+    const cells = TIER_ROW.exec(line)?.[1].split('|');
+    if (cells === undefined || cells.length !== 2) continue;
+    const when = cells[0].trim();
+    const factorText = cells[1].trim();
+    const isFirst = firstTableLine;
+    firstTableLine = false;
+    if (isFirst && TIER_HEADER.test(when)) continue;
+    if (TIER_RULE.test(when) || TIER_RULE.test(factorText)) continue;
+
+    const parsed = parseTierRow(when, factorText);
+    if ('error' in parsed) {
+      errors.push(`${DEADLINE_TIERS_SECTION}: row "| ${when} | ${factorText} |" — ${parsed.error}`);
+      continue;
+    }
+    rows.push(parsed.tier);
+  }
+
+  if (rows.length === 0 && errors.length === 0) {
+    return { ok: true, tiers: [...DEFAULT_DEADLINE_TIERS], errors: [] };
+  }
+
+  if (errors.length === 0) {
+    const count = (/** @type {DeadlineTier['kind']} */ kind) => rows.filter((tier) => tier.kind === kind).length;
+    if (count('overdue') !== 1) errors.push(`${DEADLINE_TIERS_SECTION}: needs exactly one "overdue" row, found ${count('overdue')}`);
+    if (count('beyond') !== 1) errors.push(`${DEADLINE_TIERS_SECTION}: needs exactly one "more than <time>" row, found ${count('beyond')}`);
+    if (count('within') === 0) errors.push(`${DEADLINE_TIERS_SECTION}: needs at least one "within <time>" row`);
+  }
+
+  if (errors.length > 0) return { ok: false, tiers: [...DEFAULT_DEADLINE_TIERS], errors };
+
+  const within = rows
+    .filter((tier) => tier.kind === 'within')
+    .sort((a, b) => (a.kind === 'within' && b.kind === 'within' ? a.minutes - b.minutes : 0));
+  const beyond = rows.filter((tier) => tier.kind === 'beyond');
+  const overdue = rows.filter((tier) => tier.kind === 'overdue');
+  return { ok: true, tiers: [...within, ...beyond, ...overdue], errors: [] };
+}
+
+/**
+ * What a deadline is worth `remainingMs` from now: the factor from the narrowest `within`
+ * tier the remaining time fits inside, the overdue factor once the moment has passed, and
+ * the `more than` factor beyond every tier.
+ *
+ * The boundaries are the whole contract, so each falls on one stated side: with exactly one
+ * day left a bead earns the `within 1d` factor, and a millisecond more drops it to
+ * `within 2d`; a bead whose deadline is exactly now has not slipped yet, so it is not
+ * overdue.
+ * @param {number} remainingMs
+ * @param {DeadlineTier[]} [tiers]
+ * @returns {{ factor: number, overdue: boolean }}
+ */
+export function deadlineMultiplier(remainingMs, tiers = DEFAULT_DEADLINE_TIERS) {
+  /** @type {{ minutes: number, factor: number }[]} */
+  const within = [];
+  let beyond = 1;
+  let overdue = 1;
+  for (const tier of tiers) {
+    if (tier.kind === 'within') within.push({ minutes: tier.minutes, factor: tier.factor });
+    else if (tier.kind === 'beyond') beyond = tier.factor;
+    else overdue = tier.factor;
+  }
+  within.sort((a, b) => a.minutes - b.minutes);
+
+  if (remainingMs < 0) return { factor: overdue, overdue: true };
+  for (const tier of within) {
+    if (remainingMs <= tier.minutes * MS_PER_MINUTE) return { factor: tier.factor, overdue: false };
+  }
+  return { factor: beyond, overdue: false };
+}
+
+/**
+ * Whether a body carries anything a scorer can read. An HTML comment is guidance, not
+ * content, so a template copied and never filled in is empty rather than filled.
+ * @param {string[]} body @returns {boolean}
+ */
+function hasContent(body) {
+  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;
+    }
+    if (trimmed !== '') return true;
+  }
+  return false;
+}
+
+/** Today's date in UTC, as the file records it. @returns {string} */
+export function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/** Collapse a value onto one line, so a change-log entry stays one line. @param {string} value @returns {string} */
+function oneLine(value) {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Whether `value` is a calendar date the file can commit to, not merely a date V8 can
+ * parse. V8's ISO parser rolls an impossible date into the following month — `2026-02-31`
+ * becomes 3 March — so `Date.parse` proves nothing here. Rebuild the date from its parts
+ * and compare the round trip instead: a rolled date no longer matches what was written.
+ * @param {string} value @returns {boolean}
+ */
+function isCalendarDate(value) {
+  if (!DATE.test(value)) return false;
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+
+/**
+ * Validate a strategy's shape: a positive-integer version, an ISO date, and every
+ * required section present and carrying content. Every defect is reported, so one run
+ * fixes the whole file.
+ * @param {string} text @returns {StrategyReport}
+ */
+export function validateStrategy(text) {
+  /** @type {string[]} */
+  const errors = [];
+  const found = fields(text);
+
+  const rawVersion = found.get('version');
+  /** @type {number | undefined} */
+  let version;
+  if (rawVersion === undefined) {
+    errors.push('missing field: "**Version:**" — the integer this rubric revision carries');
+  } else if (!/^\d+$/.test(rawVersion)) {
+    errors.push(`version must be an integer, got "${rawVersion}"`);
+  } else if (Number(rawVersion) < 1) {
+    errors.push(`version must be 1 or more, got "${rawVersion}"`);
+  } else {
+    version = Number(rawVersion);
+  }
+
+  const updated = found.get('updated');
+  if (updated === undefined) {
+    errors.push('missing field: "**Updated:**" — the date this rubric last changed');
+  } else if (!isCalendarDate(updated)) {
+    errors.push(`updated must be a calendar date (YYYY-MM-DD), got "${updated}"`);
+  }
+
+  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}"`);
+    else if (!hasContent(body)) errors.push(`required section is empty: "## ${title}"`);
+  }
+
+  // The change log and the version answer the same question, so they must agree: the
+  // newest entry names the version the file carries. A hand-raised version, or a bump
+  // whose log line was deleted, leaves the record of *why* the rubric moved missing.
+  const changeLog = sectionBody(lines, CHANGE_LOG_SECTION);
+  const entries = (changeLog ?? []).map((line) => CHANGE_LOG_ENTRY.exec(line)).filter((match) => match !== null);
+  const newest = entries[entries.length - 1];
+  if (newest !== null && newest !== undefined && version !== undefined && Number(newest[2]) !== version) {
+    errors.push(
+      `the newest "## ${CHANGE_LOG_SECTION}" entry names v${newest[2]} but the version is v${version} — ` +
+        'run "bump --reason" to move both together, never one alone',
+    );
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    ...(version === undefined ? {} : { version }),
+    ...(updated === undefined ? {} : { updated }),
+  };
+}
+
+/**
+ * Append one line to the change-log section, adding the section when the file has none.
+ * The line lands last, because the log reads oldest first, and the section's own guidance
+ * comment stays above it.
+ * @param {string} text @param {string} line @returns {string}
+ */
+function appendChangeLog(text, line) {
+  const lines = text.split('\n');
+  const start = lines.findIndex((each) => HEADING.exec(each)?.[1].toLowerCase() === CHANGE_LOG_SECTION.toLowerCase());
+  if (start === -1) {
+    const body = text.endsWith('\n') ? text : `${text}\n`;
+    return `${body}\n## ${CHANGE_LOG_SECTION}\n\n${line}\n`;
+  }
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (HEADING.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+
+  const body = lines.slice(start + 1, end);
+  while (body.length > 0 && body[body.length - 1].trim() === '') body.pop();
+  while (body.length > 0 && body[0].trim() === '') body.shift();
+  const tail = lines.slice(end);
+  // The log is one contiguous list, so the new line follows the previous one directly — but
+  // a guidance comment above it is not a list item, and markdown needs a blank line there.
+  const gap = body.length > 0 && body[body.length - 1].trim().endsWith('-->');
+  const rebuilt = [
+    ...lines.slice(0, start + 1),
+    '',
+    ...body,
+    ...(gap ? [''] : []),
+    line,
+    ...(tail.length > 0 ? [''] : []),
+    ...tail,
+  ];
+  const joined = rebuilt.join('\n');
+  return joined.endsWith('\n') ? joined : `${joined}\n`;
+}
+
+/**
+ * Raise the version by one, record the date and append the one-line reason, refusing a
+ * file that is not valid first: bumping a malformed rubric would only make the
+ * malformation look reviewed. A bump with no reason would leave the record of *why* the
+ * rubric moved missing, which is the same defect the change log exists to prevent.
+ * @param {string} text
+ * @param {{ today: string, reason: string }} options
+ * @returns {BumpReport}
+ */
+export function bumpStrategy(text, { today, reason }) {
+  const report = validateStrategy(text);
+  if (!report.ok) {
+    throw new StrategyError(`refusing to bump an invalid strategy:\n${report.errors.map((e) => `  - ${e}`).join('\n')}`);
+  }
+  const cleanReason = oneLine(reason ?? '');
+  if (cleanReason === '') {
+    throw new StrategyError(
+      'refusing to bump without a reason: pass --reason "<why the rubric changed>" so the change log says why',
+    );
+  }
+  const from = /** @type {number} */ (report.version);
+  const to = from + 1;
+  const line = `- ${today} v${to}: ${cleanReason}`;
+  const bumped = setField(setField(text, 'Version', String(to)), 'Updated', today);
+  return { from, to, updated: today, reason: cleanReason, line, text: appendChangeLog(bumped, line) };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+/** @type {readonly string[]} */
+export const COMMANDS = /** @type {const} */ (['init', 'validate', 'bump']);
+
+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.
+
+Options:
+  --file <path>    Strategy file (default: ${DEFAULT_FILE}, relative to the repository root)
+  --today <date>   Date to record on init/bump (default: today, UTC; YYYY-MM-DD)
+  --reason <text>  Why the rubric changed. Required by "bump": it becomes the change-log line.
+  -h, --help       Show this text
+
+The strategy is a committed file in the working-docs root, never a bead. This script
+never writes to the tracker.
+`;
+
+/**
+ * Parse the CLI's argv.
+ * @param {string[]} argv
+ * @returns {{ command: string, file: string, today?: string, reason?: string }}
+ */
+export function parseArgs(argv) {
+  /** @type {string | undefined} */
+  let command;
+  /** @type {string | undefined} */
+  let file;
+  /** @type {string | undefined} */
+  let today;
+  /** @type {string | undefined} */
+  let reason;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--file') {
+      file = argv[++i];
+      if (file === undefined) throw new UsageError('--file needs a value');
+      continue;
+    }
+    if (arg === '--reason') {
+      reason = argv[++i];
+      if (reason === undefined) throw new UsageError('--reason needs a value');
+      if (reason.trim() === '') throw new UsageError('--reason needs a non-empty value');
+      continue;
+    }
+    if (arg === '--today') {
+      today = argv[++i];
+      if (today === undefined) throw new UsageError('--today needs a value');
+      if (!isCalendarDate(today)) {
+        throw new UsageError(`--today must be a calendar date (YYYY-MM-DD), got "${today}"`);
+      }
+      continue;
+    }
+    if (arg.startsWith('-')) throw new UsageError(`unexpected argument: ${arg}`);
+    if (command !== undefined) throw new UsageError(`unexpected argument: ${arg}`);
+    if (!COMMANDS.includes(arg)) throw new UsageError(`unknown command "${arg}"`);
+    command = arg;
+  }
+
+  if (command === undefined) throw new UsageError(`a command is required: ${COMMANDS.join(', ')}`);
+  if (reason !== undefined && command !== 'bump') throw new UsageError('--reason only applies to "bump"');
+  if (command === 'bump' && reason === undefined) {
+    throw new UsageError('"bump" needs --reason "<why the rubric changed>" — the change log records it');
+  }
+  return { command, file: file ?? DEFAULT_FILE, ...(today === undefined ? {} : { today }), ...(reason === undefined ? {} : { reason }) };
+}
+
+/**
+ * The deepest ancestor of `start`, itself included, that carries a `.git` entry — the
+ * repository root the default strategy path is documented against. A worktree or submodule
+ * 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>}
+ */
+export async function findRepositoryRoot(start) {
+  const from = resolve(start);
+  let directory = from;
+  for (;;) {
+    const found = await access(join(directory, '.git')).then(
+      () => true,
+      () => false,
+    );
+    if (found) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) return from;
+    directory = parent;
+  }
+}
+
+/**
+ * The absolute path of the strategy file for one run. The default path resolves against
+ * the repository root, so a caller run from any subdirectory reads the one strategy the
+ * repository owns; an explicit `--file` is taken as given, relative to the cwd or
+ * absolute. Exported so another skill's script reads the strategy through the same rule
+ * rather than re-deriving it — one strategy, one location, one resolver.
+ * @param {object} [options]
+ * @param {string} [options.file]  Path as the caller supplied it.
+ * @param {string} [options.cwd]   Directory a relative path resolves against.
+ * @returns {Promise<string>}
+ */
+export async function resolveStrategyPath({ file = DEFAULT_FILE, cwd = process.cwd() } = {}) {
+  const base = file === DEFAULT_FILE ? await findRepositoryRoot(cwd) : cwd;
+  return resolve(base, file);
+}
+
+/**
+ * Build the report text for one failed run.
+ * @param {string} file @param {string[]} errors @returns {string}
+ */
+function formatErrors(file, errors) {
+  return `${file} is not a valid strategy:\n${errors.map((e) => `  - ${e}`).join('\n')}\n`;
+}
+
+/**
+ * @param {object} options
+ * @param {string[]} options.argv                     CLI arguments (without node/script).
+ * @param {(chunk: string) => void} [options.write]    stdout sink; injectable for tests.
+ * @param {(chunk: string) => void} [options.writeError] stderr sink; injectable for tests.
+ * @param {string} [options.cwd]                       Directory to resolve from: the default
+ *                                                     path's search start, and the base for
+ *                                                     a relative --file.
+ * @param {string} [options.today]                     Date to record; injectable for tests.
+ * @returns {Promise<number>} process exit code.
+ */
+export async function runCli({
+  argv,
+  write = (chunk) => process.stdout.write(chunk),
+  writeError = (chunk) => process.stderr.write(chunk),
+  cwd = process.cwd(),
+  today,
+}) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    write(USAGE);
+    return 0;
+  }
+
+  /** @type {{ command: string, file: string, today?: string, reason?: string }} */
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    writeError(`strategy: ${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
+    return 2;
+  }
+
+  // The default path is documented as relative to the repository root, so `init` run from a
+  // subdirectory writes the one strategy the root owns instead of a second one. Any other
+  // `--file` — and every absolute path — is taken as given, relative to the cwd.
+  const file = await resolveStrategyPath({ file: options.file, cwd });
+  const date = today ?? options.today ?? todayIso();
+
+  try {
+    if (options.command === 'init') {
+      let template;
+      try {
+        template = await readFile(TEMPLATE_FILE, 'utf8');
+      } catch {
+        throw new StrategyError(`the shipped template is missing at ${TEMPLATE_FILE}`);
+      }
+      const existing = await readFile(file, 'utf8').then(
+        () => true,
+        () => false,
+      );
+      if (existing) {
+        throw new StrategyError(
+          `${file} already exists — run "validate" to check it, or "bump" to record an update`,
+        );
+      }
+      await mkdir(dirname(file), { recursive: true });
+      await writeFile(file, setField(template, 'Updated', date), 'utf8');
+      writeError(`✓ wrote ${file} — answer the five questions, then run "validate"\n`);
+      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>`,
+      );
+    }
+
+    if (options.command === 'bump') {
+      const bumped = bumpStrategy(text, { today: date, reason: options.reason ?? '' });
+      const check = validateStrategy(bumped.text);
+      if (!check.ok) throw new StrategyError(`the bump produced an invalid file — ${check.errors.join('; ')}`);
+      await writeFile(file, bumped.text, 'utf8');
+      writeError(`✓ ${file}: version ${bumped.from} → ${bumped.to}, updated ${bumped.updated}\n  change log: ${bumped.line}\n`);
+      return 0;
+    }
+
+    const report = validateStrategy(text);
+    if (!report.ok) {
+      writeError(formatErrors(file, report.errors));
+      return 1;
+    }
+    writeError(
+      `✓ ${file}: version ${report.version}, updated ${report.updated}, ` +
+        `${REQUIRED_SECTIONS.length} required sections present\n`,
+    );
+    write(text.endsWith('\n') ? text : `${text}\n`);
+    return 0;
+  } catch (error) {
+    const kind = error instanceof UsageError ? 'usage' : 'failed';
+    writeError(`strategy ${kind}: ${error instanceof Error ? error.message : String(error)}\n`);
+    return error instanceof UsageError ? 2 : 1;
+  }
+}
+
+// Only run the CLI when invoked directly, so tests can import the module.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCli({ argv: process.argv.slice(2) })
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = 1;
+    });
+}