@jaybeeuu/agent-cortex 2.8.0 → 2.10.0

package/skills/workflow/prioritise-work/templates/strategy.md

@@ -0,0 +1,87 @@
+# Prioritisation strategy
+
+<!--
+This file is the rubric a scorer reads before it judges a bead's reach, impact,
+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. `## 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.
+-->
+
+- **Version:** 1
+- **Updated:** YYYY-MM-DD
+
+## Current themes
+
+<!--
+What you are optimising this month, as two to four themes. Name the outcome rather than
+the feature: "shorter review turnaround", not "review tooling".
+-->
+
+## What counts as value
+
+<!--
+What a bead must change to be worth doing now. One line per value, written so a scorer
+can answer yes or no: "unblocks a human gate", "removes a manual step".
+-->
+
+## How to judge confidence
+
+<!--
+When to score confidence low: no evidence in the repository, unclear scope, no known
+user, an unproven dependency. Give the figure for each case, for example "0.3 with no
+reproduction, 0.8 with a failing test".
+-->
+
+## Explicitly out of scope
+
+<!--
+Work you are deliberately not doing this month, however good it looks. A scorer reads
+this to stop a shiny bead from outranking the theme.
+-->
+
+## How to calibrate effort
+
+<!--
+Anchor the effort scale to work you have recently completed here, so two scorers agree.
+For example: 1 = half a day, one file; 3 = two to three days, one module with its tests;
+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
+
+<!--
+One line per change to this rubric, oldest first, written by
+`node <skill-scripts>/strategy.mjs bump --reason "<why>"`. The newest line must name the
+version above: `validate` fails when the two disagree, because a version that moved with
+no recorded reason is a rubric change nobody can review.
+-->
+

package/skills/workflow/ralph/REFERENCE.md

@@ -231,11 +231,16 @@ 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, branch with unpushed commits, and branch whose content is not proven landed.
+
+**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.
+
+**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.
 
 **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

@@ -5,6 +5,20 @@
 // reads bead state, not git ancestry: this repo squash-merges, so every ancestry
 // test reports a landed branch as unmerged.
 //
+// A merge that deletes its branch also deletes the local branch's upstream, so a
+// closed bead with no remote-tracking branch is the normal end of a landed branch.
+// Only the content can tell that apart from a branch that was never pushed: the
+// branch goes when the base holds the branch's own version of every path the
+// branch changed since their merge base, and stays otherwise. The test is
+// one-sided on purpose: this repo squash-merges, so a base that moved on after the
+// branch was cut holds paths the branch never had, and demanding tree equality
+// would keep every branch but the last one landed.
+//
+// The test proves content, never history. A branch removed here is discarded
+// together with every commit the base does not contain — a reverted change and a
+// run of empty commits both go, and so do their messages. The base is the remote's
+// default branch, never a hardcoded name.
+//
 // Zero dependencies: run with `node prune-worktrees.mjs`.
 
 import { execFile } from 'node:child_process';
@@ -154,15 +168,134 @@ async function classifyBead(id, exec) {
   return { classification: status === 'closed' ? 'closed-bead' : 'open-bead', beadStatus: status };
 }
 
+/**
+ * Resolve the branch a worktree's content must be contained in before its local
+ * branch may be dropped. The remote's default branch is the generic answer:
+ * `origin/HEAD` is a symbolic ref to whatever the remote calls its default
+ * branch, so no branch name is baked in here.
+ * @param {string} repoRoot
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @returns {Promise<string | null>} the base ref, or null when git cannot name one.
+ */
+async function resolveBaseRef(repoRoot, git) {
+  const result = await git(repoRoot, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+  if (!result.ok) return null;
+  const ref = result.stdout.trim();
+  return ref === '' ? null : ref;
+}
+
+/**
+ * Split the output of `git diff --name-only -z` into paths. `-z` is what makes the
+ * round trip lossless: without it git C-quotes a path holding a non-ASCII byte, a
+ * double quote, a backslash or a newline, and a quoted name fed back as a
+ * pathspec names no path. With it, every path arrives raw and NUL-terminated, so
+ * a path holding a newline stays one path.
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+function splitNulPaths(stdout) {
+  // The output ends with a NUL, so the split leaves one empty entry to drop. A
+  // path is never empty, so no real path is lost with it.
+  return stdout.split('\0').filter((entry) => entry !== '');
+}
+
+/**
+ * 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.
+ *
+ * One-sided containment, in three steps: take the merge base of the base and the
+ * branch, list the paths the branch changed since that merge base, then require the
+ * base to agree with the branch on those paths alone. Paths only the base added or
+ * changed lie outside that set and are ignored, so a base that advanced after the
+ * branch was cut still proves the branch landed.
+ *
+ * A status filter on the two-sided diff would be simpler and is wrong: `D` is the
+ * same status whether the branch deleted a path or the base never had it, so a
+ * filter cannot tell a deletion the base already carries from one it does not.
+ *
+ * Restricting to the branch's own paths is what makes an overlap detectable: when
+ * the base later changed a path the branch also changed, the two versions differ
+ * and the branch is not proven landed. A deletion on both sides agrees, so it is
+ * proven; a deletion on one side only is not.
+ *
+ * The branch's changed paths are read from git and then handed straight back to a
+ * second git call as pathspecs, so that round trip has to be exact. Two escapes
+ * make it inexact and both end in a false "proven": a path git would C-quote
+ * prints as a quoted string that names no path, and a path starting with `:` is
+ * read as pathspec magic instead of a name. Neither alone is sufficient to fix,
+ * so the first diff reads with `-z` and the second is run with
+ * `--literal-pathspecs`.
+ * @param {{ path: string, branch: string, beadClosed: boolean }} target
+ * @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) {
+  if (!beadClosed) {
+    return `branch ${branch} has no remote-tracking branch and its bead is not closed`;
+  }
+  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`;
+  }
+  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}`;
+  }
+  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}`;
+  }
+  // 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`;
+  }
+  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}`;
+  }
+  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}`;
+  }
+  const changedPaths = splitNulPaths(touched.stdout);
+  // Nothing but empty commits: no content to prove, and no content to lose.
+  if (changedPaths.length === 0) return null;
+  // `--literal-pathspecs` is a git global option, so it precedes the subcommand.
+  // It keeps a leading `:` in a real filename from being read as pathspec magic.
+  const unproven = await git(path, ['--literal-pathspecs', 'diff', '--name-only', '-z', '--no-renames', 'HEAD', baseRef, '--', ...changedPaths]);
+  if (!unproven.ok) {
+    const detail = unproven.stderr.trim();
+    const suffix = detail === '' ? '' : `: ${detail}`;
+    return `branch ${branch} has no remote-tracking branch and ${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 null;
+}
+
 /**
  * Reasons git refuses to tear a worktree down. A worktree removed anyway would
  * throw away uncommitted work or an unpushed branch, so every reason keeps the
  * worktree in place.
- * @param {{ path: string, registered: { branch: string | null, locked: string | null } | undefined }} target
+ * @param {{ path: string, registered: { branch: string | null, locked: string | null } | undefined, beadClosed: boolean }} target
  * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @param {string | null} baseRef
  * @returns {Promise<{ branch: string | null, reasons: string[] }>}
  */
-async function findRefusals({ path, registered }, git) {
+async function findRefusals({ path, registered, beadClosed }, git, baseRef) {
   /** @type {string[]} */
   const reasons = [];
 
@@ -183,7 +316,8 @@ async function findRefusals({ path, registered }, git) {
 
   const upstream = await git(path, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
   if (!upstream.ok) {
-    reasons.push(`branch ${registered.branch} has no remote-tracking branch`);
+    const lost = await findLostWork({ path, branch: registered.branch, beadClosed }, baseRef, git);
+    if (lost !== null) reasons.push(lost);
     return { branch: registered.branch, reasons };
   }
   const trackingRef = upstream.stdout.trim();
@@ -231,12 +365,14 @@ async function removeWorktree(repoRoot, { path, branch }, git) {
  * @param {object} options
  * @param {string} options.repoRoot                              Repository to prune.
  * @param {boolean} [options.removeOrphans]                       Also remove worktrees whose bead is open or missing.
+ * @param {string} [options.base]                                 Ref the content check compares against; defaults to the remote's default branch.
  * @param {(args: string[]) => Promise<string>} [options.exec]    bd runner; injectable for tests.
  * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} [options.git]  git runner; injectable for tests.
  * @returns {Promise<PruneResult>}
  */
-export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = false, git = runGit }) {
+export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = false, git = runGit, base }) {
   const registered = await readRegisteredWorktrees(repoRoot);
+  const baseRef = base ?? (await resolveBaseRef(repoRoot, git));
   /** @type {WorktreeEntry[]} */
   const entries = [];
 
@@ -252,7 +388,11 @@ export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = f
     // an unreadable bead is never removed at all.
     const wanted = classification === 'closed-bead' || (classification !== 'unclassified' && removeOrphans);
     if (wanted) {
-      const { branch, reasons } = await findRefusals({ path, registered: registered.get(path) }, git);
+      const { branch, reasons } = await findRefusals(
+        { path, registered: registered.get(path), beadClosed: classification === 'closed-bead' },
+        git,
+        baseRef,
+      );
       entry.branch = branch;
       if (reasons.length > 0) {
         entry.outcome = 'refused';
@@ -275,19 +415,56 @@ export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = f
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
-const USAGE = `Usage: node prune-worktrees.mjs [--remove-orphans]
+const USAGE = `Usage: node prune-worktrees.mjs [--remove-orphans] [--base <ref>]
 
 Removes worktrees under .agent-cortex/worktrees whose bead is closed, then
 reports the rest. A worktree whose bead is open or missing is an orphan: it is
 only removed when --remove-orphans is passed. Run from anywhere inside the
 repository.
+
+A closed bead's branch 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.
 `;
 
 /** Every flag the CLI accepts. */
 const REMOVE_ORPHANS_FLAG = '--remove-orphans';
+const BASE_FLAG = '--base';
 
 class UsageError extends Error {}
 
+/**
+ * @param {string[]} argv
+ * @returns {{ removeOrphans: boolean, base: string | undefined }}
+ */
+function parseArgs(argv) {
+  let removeOrphans = false;
+  /** @type {string | undefined} */
+  let base;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === REMOVE_ORPHANS_FLAG) {
+      removeOrphans = true;
+      continue;
+    }
+    if (arg === BASE_FLAG) {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('-')) throw new UsageError(`${BASE_FLAG} needs a git ref`);
+      base = value;
+      index += 1;
+      continue;
+    }
+    throw new UsageError(`unexpected argument: ${arg}`);
+  }
+  return { removeOrphans, base };
+}
+
 /**
  * Resolve the repository root from any directory inside it — the main checkout
  * or a linked worktree. The shared `.git` directory is one level below the root
@@ -313,14 +490,12 @@ export async function runCli({ argv, cwd = process.cwd(), exec = runBd, git = ru
     write(USAGE);
     return 0;
   }
-  const unknown = argv.filter((arg) => arg !== REMOVE_ORPHANS_FLAG);
-  if (unknown.length > 0) throw new UsageError(`unexpected argument: ${unknown[0]}`);
-  const removeOrphans = argv.includes(REMOVE_ORPHANS_FLAG);
+  const { removeOrphans, base } = parseArgs(argv);
 
   const repoRoot = await resolveRepoRoot(cwd);
   if (repoRoot === null) throw new Error('not inside a git repository');
 
-  const { entries, exitCode } = await pruneWorktrees({ repoRoot, exec, removeOrphans, git });
+  const { entries, exitCode } = await pruneWorktrees({ repoRoot, exec, removeOrphans, git, base });
 
   write(`Scanning ${join(repoRoot, '.agent-cortex', 'worktrees')}\n`);
   for (const entry of entries) {

package/skills/workflow/run-pipeline-stage/playbooks/review.md

@@ -40,8 +40,11 @@ bd update <id> --add-label defect:test-unproven
   `review-defects` pass `--all` and a query without the flag finds nothing. Two findings of
   different kinds are two `BLOCKING_ISSUES` entries and one label: the class of the finding that
   must be fixed first.
-- A class that is not on the closed list is a review defect in itself. Say so under
-  `BLOCKING_ISSUES` and use the nearest real class — never invent a `defect:` label.
+- When no class fits, apply `defect:unclassified`, say so under `BLOCKING_ISSUES`, and file a bead
+  proposing the class with this finding as its case. The escape hatch is not a pass: without the
+  gap bead it silently degrades the aggregate the feedback loop reads.
+- Never invent a `defect:` label, and never apply a class that does not fit — that is a review
+  defect in itself. `defect:unclassified` is the only honest way to say no class fits.
 - The review that confirms the fix removes the label
   (`bd update <id> --remove-label defect:test-unproven`) and records the removal in its trail
   entry. A closed defect is a trail fact, never a second class.

package/skills/workflow/score-bead/FORMAT.md

@@ -0,0 +1,73 @@
+# Score Bead — Record, Bands and Trail
+
+The exact shapes `rice.mjs` reads and writes. Read this when a record looks wrong, when you need the band thresholds, or when you are auditing a re-score.
+
+## The metadata record
+
+One key, `rice`, written with `bd update <id> --metadata '{"rice":{…}}'`. `bd show` renders it under `METADATA`:
+
+```
+METADATA
+  rice: {"assessedAt":"2026-11-14T09:00:00.000Z","confidence":0.7,"effort":2,
+         "impact":3,"rationale":"unblocks the messaging epic — Current themes",
+         "reach":4,"score":4.2,"strategyVersion":2}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `reach` | number ≥ 0 | How much work the bead changes |
+| `impact` | number ≥ 0 | How much each unit of reach gains, on the rubric's scale |
+| `confidence` | number `0..1` | Probability that the reach, impact and effort estimates hold |
+| `effort` | number > 0 | Cost, on the rubric's effort calibration |
+| `score` | number, one decimal | `reach × impact × confidence ÷ effort` |
+| `strategyVersion` | integer | The strategy file's own version, read after it validated |
+| `assessedAt` | string | When the judgement was made — now in UTC, or `--at` copied verbatim |
+| `rationale` | string | Why these numbers, then the `[prior]` trail |
+
+The total is rounded once, at the end: `Math.round(value * 10) / 10`. Rounding a component instead would make the stored components disagree with the stored total.
+
+`--at` is a convention, not a guarantee. The flag documents an RFC 3339 UTC timestamp, but `score` writes the value exactly as given and never validates it, so a mistyped timestamp reaches the record unchanged. Omit the flag and the record carries the real time.
+
+`score` refuses, writing nothing, when:
+
+- the strategy file is missing, or `validate` rejects it — exit 1, with the reason;
+- a component is not a number, `confidence` falls outside `0..1`, or `effort` is zero or less — exit 2;
+- the rationale is empty — exit 2.
+
+Exit 1 means the run reached a judgement and refused it; exit 2 means the call was malformed and never got that far. Neither reaches the tracker: the components, the rationale and the strategy are all checked before the first `bd` call, so a refused score leaves no metadata, no note and no tag behind.
+
+## The band table
+
+| Score at least | Proposed priority |
+|---|---|
+| 8 | P1 |
+| 4 | P2 |
+| 1 | P3 |
+| 0 | P4 |
+
+Bands are highest-first and evaluated in order. P0 is absent and `bandFor` throws if a table ever yields it, so a computed score can never file a bead as an incident. The table lives in `rice.mjs` as `DEFAULT_BANDS`; changing it is a code change, reviewable like any other.
+
+`band <id>` prints the proposal and the command that would apply it:
+
+```
+✓ tst-6: score 4.2 → P2 (currently P3)
+  proposal only — review the components and the rationale, then apply: bd update tst-6 -p 2
+```
+
+It reads the bead with `bd show` and calls nothing else. A bead already at P0 is refused before a proposal exists, because an incident is not re-prioritised by a rubric. A bead with no numeric `score` is refused too — score it first, then band it.
+
+## The rationale trail
+
+The rationale holds the current argument, then one `[prior]` line per score it replaced, oldest first and ending with the score just replaced:
+
+```
+re-scored against the December rubric
+[prior] score 1 @ strategy v1, assessed 2026-10-01T00:00:00.000Z (reach 1, impact 1, confidence 0.5, effort 2)
+[prior] score 4.2 @ strategy v2, assessed 2026-11-14T09:00:00.000Z (reach 4, impact 3, confidence 0.7, effort 2)
+```
+
+Each line carries the superseded total, its components, the strategy version it was judged against and its date, so the old arithmetic stays checkable after the components are overwritten.
+
+Why the rationale and not a separate `history` array: the bead carries one record, `bd show` renders it in one place, and a re-score cannot drop the history by forgetting a second store. A reader greps `[prior]` to separate the trail from the prose. A record with no numeric `score` contributes no new line, but its existing trail is carried forward unchanged.
+
+Nothing caps the trail. Every re-score appends one line and drops none, so the field grows by a line per re-score for the whole life of the bead. In practice a bead is re-scored a handful of times, once per strategy version; treat a long trail as history, not as a defect.

package/skills/workflow/score-bead/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: score-bead
+description: Scores one bead RICE-style against the committed strategy and stores the components, total, confidence, rationale and strategy version in its metadata, then proposes a priority band for review. Use when a bead is unscored, when asked to "score this bead", "rank this work", or "what priority should this be".
+---
+
+# Score Bead
+
+Owns two things about one bead: the **RICE record** in its metadata, and a **band proposal** for its priority. The rubric the numbers are judged against is not this skill's — `prioritise-work` owns the strategy file, validates it and versions it.
+
+Score and band are two steps on purpose. `score` writes an auditable record; `band` only reads it and prints a proposal. A score is a judgement, so the priority it implies is reviewed before it lands. A script that re-prioritised the backlog silently would remove the review, not save it.
+
+## When to use
+
+- A bead appears in a queue with no `rice` metadata, or with a `strategyVersion` older than the strategy file.
+- "Score this bead", "rank this work", "is this a P1?", "what priority should this be".
+- Before dispatching work: an unscored bead cannot be compared with a scored one.
+
+## When NOT to use
+
+- Setting or updating the strategy — use `prioritise-work`. This skill reads the rubric and never writes it.
+- Recording an idea for later — use `record-idea`.
+- Changing where a bead's state lives — use `bd-tool`.
+- Ordering the whole backlog into one list — that is the [hitl-queue](../hitl-queue/SKILL.md) skill's job; this skill scores one bead.
+
+## The record
+
+`score` writes one metadata key, so a reader greps one key instead of parsing the bead:
+
+```json
+{"rice":{"reach":4,"impact":3,"confidence":0.7,"effort":2,"score":4.2,
+         "strategyVersion":2,"assessedAt":"2026-11-14T09:00:00.000Z",
+         "rationale":"unblocks the messaging epic — Current themes"}}
+```
+
+Components and total are both stored, so a reader can redo the arithmetic. The full shape, the band table and the rationale trail are in [FORMAT.md](FORMAT.md).
+
+## Workflow
+
+1. **Check the strategy is valid.** Load `prioritise-work` and run its validator:
+
+```bash
+node <skill-scripts>/../../prioritise-work/scripts/strategy.mjs validate
+```
+
+A missing or malformed strategy stops here. `score` refuses in that state and writes nothing, so fixing the rubric is the only useful next action. The path above is the default (`.agent-cortex/working-docs/strategy.md` relative to the repository root); pass `--file <path>` to `score` when the repository keeps it elsewhere, and the same `--file` to the validator.
+
+2. **Judge the four components against the strategy.** Each number must trace to a section of the rubric, and the rationale names that section.
+
+| Component | What it measures | Watch for |
+|---|---|---|
+| `reach` | How much work this changes — how many workflows, beads or users | Counting the author once, not the repeated cost |
+| `impact` | How much each unit of reach gains, on the rubric's own scale | A number the rubric does not define |
+| `confidence` | How sure the estimate is, as a probability `0..1` | A guess presented as a figure |
+| `effort` | Cost, on the effort calibration the rubric anchors | An effort that is a wish |
+
+3. **Record a confidence figure you can defend.** Use `0..1`, and let the rationale say what the evidence is and what is missing. `0.5` with "no comparable work yet" is honest; `0.9` with no evidence is a guess wearing a number. When you cannot estimate at all, lower the figure and name the gap rather than inflating it.
+
+4. **Score the bead.** One command, one record:
+
+```bash
+node <skill-scripts>/rice.mjs score <bead-id> --reach 4 --impact 3 --confidence 0.7 \
+  --effort 2 --rationale "unblocks the messaging epic — Current themes"
+```
+
+It computes `reach × impact × confidence ÷ effort` to one decimal, records the strategy version it validated, and writes the record with `bd update <id> --metadata`. It writes nothing when the strategy is missing or invalid, and nothing when a component falls outside its range.
+
+5. **Read back what landed.** `bd show <bead-id>` renders the `METADATA` block: the components, the total, the version and the rationale. Confirm the arithmetic before you trust the score.
+
+6. **Propose a band.** Separate command, read-only:
+
+```bash
+node <skill-scripts>/rice.mjs band <bead-id>
+```
+
+It prints `score 4.2 → P2 (currently P3)` and the exact command that would apply it.
+
+7. **Apply the band only after review.** Show the proposal — score, current priority, proposed priority, and the rationale — and run the printed `bd update <bead-id> -p <n>` only when the owner accepts it. Skip the step when the proposal equals the current priority.
+
+## Re-scoring keeps the history
+
+When the strategy version moves, re-score the bead. The new record carries the new `strategyVersion`, and the rationale keeps a `[prior]` line for every score it replaced — old score, components, version and date. The mechanism is the rationale text itself, not a second field: one record then holds both the current argument and its trail, and `bd show` renders all of it.
+
+So a re-score never needs a note to explain the change. Write the new rationale, score, and read the trail back to confirm the old total survived (see [FORMAT.md](FORMAT.md) for the rendered shape).
+
+## Priority is an output of review, not of arithmetic
+
+- **A band is a proposal.** The script never runs the update it prints; step 7 does, and only on acceptance.
+- **P0 is an incident.** A score never produces P0, and `band` refuses a bead that is already at P0 without proposing anything. An incident is declared by a person and cleared by a person; a rubric that could compute one would let a high-impact feature hide a production failure.
+- **A previous priority stays readable.** The rationale carries the scores a band decision was made from, so a reader sees why the priority moved.
+
+## Red Flags
+
+- Red flag: writing a confidence number with no evidence behind it, because the field needs a value.
+- Red flag: applying a band yourself, in the same breath as proposing it, so no review happens.
+- Red flag: scoring against a strategy whose `validate` was never run — the record then cites a version nobody checked.
+- Red flag: re-scoring and dropping the `[prior]` trail, so the priority change has no recorded reason.
+- Red flag: raising a P0 bead to make a queue look tidy.
+
+## Verification checklist
+
+- [ ] `strategy.mjs validate` exited 0 before the score ran.
+- [ ] `bd show <id>` shows a `rice` key whose components reproduce the total: `reach × impact × confidence ÷ effort`, one decimal.
+- [ ] The recorded `strategyVersion` equals the file's version after validation.
+- [ ] The rationale names the strategy section each component rests on, and the confidence is a figure the evidence supports.
+- [ ] A re-score carries a `[prior]` line for the score it replaced.
+- [ ] The band proposal was accepted by a reviewer before the priority changed, and no P0 bead was touched.
+
+## See Also
+
+- [prioritise-work](../../workflow/prioritise-work/SKILL.md) — owns the strategy file; run its `validate` before any score.
+- [hitl-queue](../hitl-queue/SKILL.md) — ranks the beads these scores belong to, and reads them back.
+- [bd-tool](../../productivity/bd-tool/SKILL.md) — where the record lives, and why a bead holds operational state rather than the rubric.