@jaybeeuu/agent-cortex 2.8.0 → 2.10.0

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

@@ -0,0 +1,150 @@
+---
+name: prioritise-work
+description: Sets, updates and validates the committed prioritisation strategy that bead scoring ranks against. Use when choosing what to work on next, when the strategy file is missing or stale, or when asked to "set the strategy".
+---
+
+# Prioritise Work
+
+Owns one artefact: the **strategy file**, the rubric a scorer reads before it judges a bead's reach, impact, confidence and effort. The skill interviews the owner to write or update it, and validates it before any scorer reads it.
+
+The strategy is a **committed file**, never a bead and never a scratch note. A rubric is reviewed, diffed and versioned as text; a bead carries progress and decisions about *work*, not the durable document that judges work. The tracker convention draws the same line: operational state — progress, decisions, refs — goes in the bead trail, and a document a reviewer diffs stays a file. Keep the strategy a file even when a bead could hold the same words, because then nobody can review a change to the rubric.
+
+## When to use
+
+- "What should I work on next?" — and there is no strategy file, or the one there is predates the current month.
+- "Set the strategy", "update the priorities", "we are optimising something else this month".
+- "This should be higher", "that is not the priority" — a challenge to the order, which is a strategy signal. See [CHALLENGE.md](CHALLENGE.md).
+- A scorer reports a score with no `strategyVersion`, or with one older than the file's.
+- Before ranking a backlog: the rubric has to be valid first.
+
+## When NOT to use
+
+- Shaping one feature — use `plan`; that skill scopes a feature, this one orders the work.
+- Recording an idea — use `record-idea`; tracker questions, or where a bead's state lives — use `bd-tool`.
+- Writing a PRD or a design document — use `write-a-prd`.
+
+## The strategy file
+
+| Item | Value |
+|---|---|
+| Default path | `.agent-cortex/working-docs/strategy.md`, relative to the repository root |
+| Override | `--file <path>` on every subcommand |
+| Contents | a version integer, a date, five required sections, and an optional `## Deadline tiers` table |
+| Daily line | one `- daily: <scope>, <scope> — <why>` bullet under `## Current themes` |
+| Lifetime | committed; edited by interview, then versioned with `bump` |
+
+The working-docs root is the scratch directory the HITL handoff also uses: `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md`. The strategy sits beside it and is the one file in that directory the repository commits.
+
+The default path resolves against the **repository root**, found by walking up for a `.git` entry, not against the directory the shell is in. Run `init` from any subdirectory and you still get the one strategy the repository owns. An override behaves differently: a relative `--file` resolves against the current directory, and an absolute one is taken as given.
+
+That directory's contents are usually ignored (`working-docs/*`), so track the strategy explicitly. Add the un-ignore line to the consuming repository's `.gitignore` once:
+
+```gitignore
+!.agent-cortex/working-docs/strategy.md
+```
+
+Use that rather than `git add -f`: an ignored file disappears from `git status`, so the next update is committed by nobody.
+
+**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
+
+1. Confirm the file is absent:
+
+```bash
+node <skill-scripts>/strategy.mjs validate
+```
+
+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.
+
+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:
+
+```bash
+node <skill-scripts>/strategy.mjs init
+```
+
+It stamps the date and leaves the version at `1`, and refuses to overwrite an existing file.
+
+3. Interview the owner. Ask one question at a time and write the answer under the section the table below names. Replace the guidance comment with the owner's own words; do not paraphrase a figure they gave.
+
+4. Validate before committing. `validate` prints the filled rubric to stdout only when it passes, and names every defective field or section on stderr otherwise:
+
+```bash
+node <skill-scripts>/strategy.mjs validate
+```
+
+5. Commit the file with the un-ignore line. The interview is finished only when `validate` exits 0 and `git ls-files --error-unmatch .agent-cortex/working-docs/strategy.md` succeeds.
+
+### 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.
+
+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.
+
+8. Bump the version and record the date and the reason, then validate:
+
+```bash
+node <skill-scripts>/strategy.mjs bump --reason "<why the rubric changed>"
+```
+
+The bump refuses a file that is not already valid and refuses an empty reason, raises the version by exactly one, writes today's date in UTC, and appends `- <date> v<n>: <reason>` to the change log. Report the old and new version to the owner.
+
+9. Commit the file. The version is what a score's `strategyVersion` points at, so a bump with no commit leaves scores pointing at a rubric nobody else has.
+
+### Interview questions
+
+One question produces one section. Ask them in this order; each answer is one to four lines.
+
+| Ask | Write into |
+|---|---|
+| What are you optimising this month? Name the outcome, not the feature. | `## Current themes` |
+| What must a bead change to be worth doing now? | `## What counts as value` |
+| When should a score be distrusted — which evidence is missing? | `## How to judge confidence` |
+| What are you deliberately not doing this month, however good it looks? | `## Explicitly out of scope` |
+| How long did comparable work take recently? Anchor the effort scale to it. | `## How to calibrate effort` |
+
+The confidence question matters as much as the other four: effort and impact estimates are judgements, and the strategy is the only place the owner states how far to trust one.
+
+## 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.
+
+## Hand edits and forgotten bumps
+
+A hand edit that changes a section but forgets `bump` still passes `validate`: the shape is intact, so nothing can tell the content moved. The protection is the version a score records — a scorer stores the `strategyVersion` it scored against, so a reader compares the two numbers and re-scores when they differ. The change log closes the rest of the gap: `validate` fails when its newest line names a version the header does not, so a raised version with no recorded reason is caught.
+
+## Red Flags
+
+- Red flag: moving the strategy into a bead, a label or a scratch file because it is "just a rubric".
+- Red flag: editing a strategy and skipping `bump`, or hand-raising the version, so the record hides the change.
+- Red flag: editing a score to satisfy a challenge, instead of changing the rubric that produced it.
+- Red flag: scoring against a file whose `validate` was never run — a malformed rubric scores silently.
+
+## Verification checklist
+
+- [ ] `node <skill-scripts>/strategy.mjs validate` exits 0 and printed the rubric, and every section carries the owner's words.
+- [ ] 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.
+
+## See Also
+
+- [CHALLENGE.md](CHALLENGE.md) — the sequence, the refusals and the no-change path when the order is challenged.
+- [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/challenge.mjs

@@ -0,0 +1,505 @@
+// @ts-check
+// Turn a priority challenge into a strategy review, and refuse a silent reorder.
+//
+// "This should be higher" is a signal that the rubric is wrong, stale or shifted — not an
+// instruction to edit one score. The only way an item moves is for the rubric that produces
+// its score to change, and a rubric change is a `bump`: a new version, a new date, and one
+// line in the change log saying why. This script is that rule made mechanical.
+//
+// It reads the strategy file, checks the version actually moved, diffs the order before
+// against the order after, and prints one bead-trail entry recording the challenge and its
+// resolution. It never writes to the tracker and never edits the strategy file: the trail
+// entry is appended by the caller with `bd note`.
+//
+// The entry embeds the words the human used, so it must reach `bd` as data and never as a
+// shell string. `--out <path>` writes the entry to a file, and `bd note <bead> --file
+// <path>` reads it back verbatim — no quoting, no expansion, nothing to escape.
+//
+// The trail entry's shape is `run-pipeline-stage/scripts/trail-entry.mjs`'s — the header
+// with a content fingerprint, then Outcome, Evidence and What is left. That script is the
+// repo's one trail writer, and importing it across skills would break in the flat Claude
+// Code install, so the four lines are rendered here instead and a test pins this renderer
+// to that one.
+//
+// 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.
+//
+//   node challenge.mjs record --bead <id> --challenge "<words the human used>" \
+//     --resolution <changed|no-change> --reason "<one line>" --from-version <n> \
+//     [--before <ids>] [--after <ids>] [--file <path>] [--at <rfc3339>] [--out <path>] \
+//     [--json]
+//
+// Exit codes: 0 recorded, 1 refused, 2 the caller asked for something malformed.
+
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { DEFAULT_FILE, UsageError, resolveStrategyPath, validateStrategy } from './strategy.mjs';
+
+// ─── Contract ─────────────────────────────────────────────────────────────────
+
+/** The two resolutions a strategy review can reach. @typedef {'changed' | 'no-change'} Resolution */
+
+/**
+ * Both are valid outcomes. "no-change" is not a failure: the challenge was answered by the
+ * rubric as written, and the trail records that answer.
+ * @type {readonly Resolution[]}
+ */
+export const RESOLUTIONS = /** @type {const} */ (['changed', 'no-change']);
+
+/** The stage this entry carries. The trail reads a stage per entry, so a challenge has one. */
+export const STAGE = 'challenge';
+
+/** A resolved challenge ends the same way whether or not the rubric moved. */
+export const OUTCOME = /** @type {const} */ ('done');
+
+/** The fingerprint width, matching trail-entry.mjs. */
+const FINGERPRINT_LENGTH = 16;
+
+/** A refusal: the recording would hide the thing it exists to expose. Exit code 1. */
+export class ChallengeError extends Error {}
+
+/** One item that moved. Positions are 1-based, 1 being the top of the order.
+ * @typedef {object} Move
+ * @property {string} id
+ * @property {number} from
+ * @property {number} to
+ * @property {number} delta  Positive when the item moved up.
+ */
+
+/**
+ * What a positional diff found.
+ * @typedef {object} OrderDiff
+ * @property {Move[]} moved      In both orders, at a different position.
+ * @property {{ id: string, to: number }[]} added     Only in the new order.
+ * @property {{ id: string, from: number }[]} dropped Only in the old order.
+ * @property {boolean} identical
+ */
+
+/**
+ * A recorded challenge.
+ * @typedef {object} ChallengeReport
+ * @property {string} bead
+ * @property {Resolution} resolution
+ * @property {number} fromVersion
+ * @property {number} version
+ * @property {string} updated
+ * @property {string} reason
+ * @property {string} evidence
+ * @property {string} remaining
+ * @property {string} entry
+ * @property {string} fingerprint
+ * @property {OrderDiff} [order]  Absent when the caller named no order.
+ */
+
+// ─── Value helpers ────────────────────────────────────────────────────────────
+
+/** Collapse a value onto one line, so a field never breaks the entry's shape.
+ * @param {string} value @returns {string} */
+export function oneLine(value) {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Split a comma-separated order into bead ids. A duplicate id would make "where did it
+ * move to" ambiguous, so it is rejected rather than silently deduplicated.
+ * @param {string} value @returns {string[]}
+ */
+export function parseOrder(value) {
+  const ids = value
+    .split(',')
+    .map((id) => id.trim())
+    .filter((id) => id !== '');
+  if (ids.length === 0) throw new UsageError('an order needs at least one bead id');
+  const seen = new Set();
+  for (const id of ids) {
+    if (seen.has(id)) throw new UsageError(`the order names "${id}" twice`);
+    seen.add(id);
+  }
+  return ids;
+}
+
+/**
+ * Diff two ranked id lists by position. Deterministic: items are reported by their new
+ * position, then the arrivals, then the departures by their old position, so two runs over
+ * the same input print the same words in the same order.
+ *
+ * The maps are filled from the lists, so iterating them already yields ascending positions;
+ * the sorts keep that order true whatever order the maps were filled in.
+ * @param {string[]} before @param {string[]} after @returns {OrderDiff}
+ */
+export function diffOrder(before, after) {
+  /** @type {Map<string, number>} */
+  const beforeAt = new Map(before.map((id, index) => [id, index + 1]));
+  /** @type {Map<string, number>} */
+  const afterAt = new Map(after.map((id, index) => [id, index + 1]));
+
+  /** @type {Move[]} */
+  const moved = [];
+  /** @type {{ id: string, to: number }[]} */
+  const added = [];
+  /** @type {{ id: string, from: number }[]} */
+  const dropped = [];
+
+  for (const [id, to] of afterAt) {
+    const from = beforeAt.get(id);
+    if (from === undefined) added.push({ id, to });
+    else if (from !== to) moved.push({ id, from, to, delta: from - to });
+  }
+  for (const [id, from] of beforeAt) {
+    if (!afterAt.has(id)) dropped.push({ id, from });
+  }
+
+  moved.sort((a, b) => a.to - b.to);
+  added.sort((a, b) => a.to - b.to);
+  dropped.sort((a, b) => a.from - b.from);
+
+  return { moved, added, dropped, identical: moved.length === 0 && added.length === 0 && dropped.length === 0 };
+}
+
+/**
+ * Name every movement in one clause, so the trail says what moved rather than that
+ * something did.
+ * @param {OrderDiff} diff @returns {string}
+ */
+export function describeMoves(diff) {
+  const parts = [
+    ...diff.moved.map((move) => `${move.id} #${move.from}→#${move.to}`),
+    ...diff.added.map((entry) => `${entry.id} new at #${entry.to}`),
+    ...diff.dropped.map((entry) => `${entry.id} dropped from #${entry.from}`),
+  ];
+  return parts.length === 0 ? 'nothing moved' : parts.join(', ');
+}
+
+// ─── The trail entry ──────────────────────────────────────────────────────────
+
+/**
+ * The entry's content fingerprint, computed the way trail-entry.mjs computes it: the same
+ * fields fired twice are the same entry, so a repeated fire appends no near-duplicate.
+ * @param {object} input
+ * @param {string} input.beadId
+ * @param {string} input.stage
+ * @param {string} input.outcome
+ * @param {string} input.evidence
+ * @param {string} input.remaining
+ * @returns {string}
+ */
+export function fingerprintEntry({ beadId, stage, outcome, evidence, remaining }) {
+  const key = [beadId, stage, outcome, evidence, remaining, '', '', '', ''].join('\u0000');
+  return createHash('sha256').update(key).digest('hex').slice(0, FINGERPRINT_LENGTH);
+}
+
+/**
+ * The note text: a timestamped header carrying the fingerprint, then the three mandatory
+ * fields. No refs line — a challenge names no commit, branch or pull request.
+ * @param {object} input
+ * @param {string} input.at
+ * @param {string} input.stage
+ * @param {string} input.outcome
+ * @param {string} input.evidence
+ * @param {string} input.remaining
+ * @param {string} input.fingerprint
+ * @returns {string}
+ */
+export function buildEntry({ at, stage, outcome, evidence, remaining, fingerprint }) {
+  return [
+    `[${at}] [${stage}] trail:${fingerprint}`,
+    `Outcome: ${outcome}`,
+    `Evidence: ${oneLine(evidence)}`,
+    `What is left: ${oneLine(remaining)}`,
+  ].join('\n');
+}
+
+// ─── The review ───────────────────────────────────────────────────────────────
+
+/**
+ * Hold one challenge against the strategy file and decide what may be recorded.
+ *
+ * Three refusals, and each one is a failure mode this skill exists to prevent:
+ *  - the strategy is invalid, so no score can honestly be judged against it;
+ *  - the resolution says "changed" but the version did not rise, or says "no-change" while
+ *    the version rose — the record would contradict the file;
+ *  - the order moved while the version stayed put. That is the silent reorder itself.
+ *
+ * @param {object} input
+ * @param {string} input.text        The strategy file's contents.
+ * @param {string} input.beadId
+ * @param {string} input.challenge   The words the human used.
+ * @param {Resolution} input.resolution
+ * @param {string} input.reason      Why the rubric did or did not change.
+ * @param {number} input.fromVersion The version the challenged order was scored against.
+ * @param {string[]} [input.before]
+ * @param {string[]} [input.after]
+ * @param {string} input.at
+ * @returns {ChallengeReport}
+ */
+export function reviewChallenge({ text, beadId, challenge, resolution, reason, fromVersion, before, after, at }) {
+  const strategy = validateStrategy(text);
+  if (!strategy.ok) {
+    throw new ChallengeError(
+      'the strategy is not valid, so no score can be judged against it:\n' +
+        strategy.errors.map((error) => `  - ${error}`).join('\n'),
+    );
+  }
+  const version = /** @type {number} */ (strategy.version);
+  const updated = /** @type {string} */ (strategy.updated);
+  const cleanReason = oneLine(reason);
+  if (cleanReason === '') throw new ChallengeError('a challenge is recorded with its reasoning — pass --reason');
+  if (oneLine(challenge) === '') throw new ChallengeError('a challenge is recorded with the words that raised it — pass --challenge');
+
+  if (before === undefined !== (after === undefined)) {
+    throw new ChallengeError('--before and --after go together: one order to compare is not a comparison');
+  }
+  const order = before !== undefined && after !== undefined ? diffOrder(before, after) : undefined;
+
+  if (resolution === 'changed') {
+    if (version <= fromVersion) {
+      throw new ChallengeError(
+        `resolution "changed" but the strategy version did not rise (v${fromVersion} → v${version}): ` +
+          'edit the rubric, then run "bump --reason", or record "no-change" if the rubric stands',
+      );
+    }
+    if (order === undefined) {
+      throw new ChallengeError('resolution "changed" needs --before and --after, so the record names what moved');
+    }
+  } else if (version !== fromVersion) {
+    throw new ChallengeError(
+      `the strategy version moved (v${fromVersion} → v${version}), so the resolution is "changed", not "no-change"`,
+    );
+  }
+
+  // The guard, whichever way round the caller passed the arguments: an order that moved
+  // while the version stayed put is a score edited without the rubric moving.
+  if (order !== undefined && !order.identical && version === fromVersion) {
+    throw new ChallengeError(
+      `the order moved (${describeMoves(order)}) but the strategy stayed at v${version}: ` +
+        'a reorder without a rubric change is the silent reorder this skill refuses — ' +
+        'change the rubric and bump, or leave the order alone',
+    );
+  }
+
+  const evidence =
+    resolution === 'changed'
+      ? `challenged "${oneLine(challenge)}"; strategy v${fromVersion} → v${version} (updated ${updated}); ` +
+        `rubric reason: ${cleanReason}; order ${/** @type {string[]} */ (after).length} items, ` +
+        `${/** @type {OrderDiff} */ (order).moved.length} moved: ${describeMoves(/** @type {OrderDiff} */ (order))}`
+      : `challenged "${oneLine(challenge)}" against v${version} (updated ${updated}); ` +
+        `no rubric change: ${cleanReason}; the order did not move`;
+
+  const remaining =
+    resolution === 'changed'
+      ? `nothing — scores are re-ranked against strategy v${version}`
+      : `nothing — the queue stands and the challenge is answered`;
+
+  const fingerprint = fingerprintEntry({ beadId, stage: STAGE, outcome: OUTCOME, evidence, remaining });
+  return {
+    bead: beadId,
+    resolution,
+    fromVersion,
+    version,
+    updated,
+    reason: cleanReason,
+    evidence: oneLine(evidence),
+    remaining,
+    entry: buildEntry({ at, stage: STAGE, outcome: OUTCOME, evidence, remaining, fingerprint }),
+    fingerprint,
+    ...(order === undefined ? {} : { order }),
+  };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+/** @type {readonly string[]} */
+export const COMMANDS = /** @type {const} */ (['record']);
+
+const USAGE = `Usage: node challenge.mjs record [options]
+
+  record   Check the challenge against the strategy and print one bead-trail entry.
+
+Options:
+  --bead <id>           The bead whose priority was challenged. Required.
+  --challenge <words>   What the human said. Required.
+  --resolution <r>      changed | no-change. Required.
+  --reason <text>       Why the rubric changed, or why it stands. Required.
+  --from-version <n>    Strategy version the challenged order was scored against. Required.
+  --before <ids>        The order before the review, highest first, comma-separated.
+  --after <ids>         The order after the review, highest first, comma-separated.
+  --file <path>         Strategy file (default: ${DEFAULT_FILE}, relative to the repository root)
+  --at <rfc3339>        Timestamp for the entry header (default: now, UTC)
+  --out <path>          Write the entry to a path, so the tracker reads it as data. Use this.
+  --json                Print a machine report instead of the entry text
+  -h, --help            Show this text
+
+stdout is the trail entry alone; status goes to stderr. Append it from a file, never as a
+shell string: the entry carries the words the human used, and a quote in those words must
+not end the quoting.
+
+  node challenge.mjs record … --out /tmp/entry.txt
+  bd note <bead> --file /tmp/entry.txt
+
+\`bd note <bead> "$(cat /tmp/entry.txt)"\` is the same thing: a command substitution is data,
+not shell code, so nothing in the entry is expanded twice. This script never writes to the
+tracker and never edits the strategy file.
+`;
+
+/**
+ * Parse the CLI's argv.
+ * @param {string[]} argv
+ * @returns {{ command: string, bead: string, challenge: string, resolution: Resolution,
+ *   reason: string, fromVersion: number, before?: string[], after?: string[],
+ *   file: string, at?: string, out?: string, json: boolean }}
+ */
+export function parseArgs(argv) {
+  /** @type {Record<string, string>} */
+  const values = {};
+  /** @type {string | undefined} */
+  let command;
+  let json = false;
+
+  /** @type {readonly string[]} */
+  const flags = ['--bead', '--challenge', '--resolution', '--reason', '--from-version', '--before', '--after', '--file', '--at', '--out'];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (flags.includes(arg)) {
+      const value = argv[++i];
+      if (value === undefined) throw new UsageError(`${arg} needs a value`);
+      values[arg] = value;
+      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(', ')}`);
+  for (const required of ['--bead', '--challenge', '--resolution', '--reason', '--from-version']) {
+    if (values[required] === undefined) throw new UsageError(`${required} is required`);
+  }
+
+  const resolution = values['--resolution'];
+  if (!RESOLUTIONS.includes(/** @type {Resolution} */ (resolution))) {
+    throw new UsageError(`--resolution must be ${RESOLUTIONS.join(' or ')}, got "${resolution}"`);
+  }
+
+  const rawVersion = values['--from-version'];
+  if (!/^\d+$/.test(rawVersion)) throw new UsageError(`--from-version must be an integer, got "${rawVersion}"`);
+
+  return {
+    command,
+    bead: values['--bead'],
+    challenge: values['--challenge'],
+    resolution: /** @type {Resolution} */ (resolution),
+    reason: values['--reason'],
+    fromVersion: Number(rawVersion),
+    ...(values['--before'] === undefined ? {} : { before: parseOrder(values['--before']) }),
+    ...(values['--after'] === undefined ? {} : { after: parseOrder(values['--after']) }),
+    file: values['--file'] ?? DEFAULT_FILE,
+    ...(values['--at'] === undefined ? {} : { at: values['--at'] }),
+    ...(values['--out'] === undefined ? {} : { out: values['--out'] }),
+    json,
+  };
+}
+
+/**
+ * @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.
+ * @param {string} [options.now]                        Timestamp for the entry; 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(),
+  now,
+}) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    write(USAGE);
+    return 0;
+  }
+
+  /** @type {ReturnType<typeof parseArgs>} */
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    writeError(`challenge: ${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const file = await resolveStrategyPath({ file: options.file, cwd });
+
+  try {
+    /** @type {string} */
+    let text;
+    try {
+      text = await readFile(file, 'utf8');
+    } catch {
+      throw new ChallengeError(`${file} does not exist — there is no rubric to challenge; run "strategy.mjs init" and interview the owner`);
+    }
+
+    const report = reviewChallenge({
+      text,
+      beadId: options.bead,
+      challenge: options.challenge,
+      resolution: options.resolution,
+      reason: options.reason,
+      fromVersion: options.fromVersion,
+      before: options.before,
+      after: options.after,
+      at: options.at ?? now ?? new Date().toISOString(),
+    });
+
+    if (options.out !== undefined) {
+      await writeFile(resolve(cwd, options.out), `${report.entry}\n`, 'utf8');
+      writeError(`  entry: ${resolve(cwd, options.out)}\n`);
+    }
+
+    if (options.json) {
+      write(`${JSON.stringify({ file, ...report }, null, 2)}\n`);
+    } else {
+      write(`${report.entry}\n`);
+    }
+
+    // The entry must reach the tracker as data, so the hint names a file and never a quoted
+    // string. A caller that passed no --out is told how to get one.
+    const next =
+      options.out === undefined
+        ? `  next: bd note ${report.bead} --file <path> — pass --out <path> to write the entry there`
+        : `  next: bd note ${report.bead} --file ${resolve(cwd, options.out)}`;
+
+    writeError(
+      `✓ ${report.bead}: resolution=${report.resolution}, strategy v${report.fromVersion} → v${report.version}` +
+        (report.order === undefined ? '\n' : `\n  moved: ${describeMoves(report.order)}\n`) +
+        `${next}\n`,
+    );
+    return 0;
+  } catch (error) {
+    const kind = error instanceof UsageError ? 'usage' : 'refused';
+    writeError(`challenge ${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;
+    });
+}