@jaybeeuu/agent-cortex 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,172 @@
 # Changelog
 
+## 2.11.0
+
+### Minor Changes
+
+- 0a98d7b: Open a `prioritise-work` run with a summary of the committed strategy instead of a question. A new
+  `strategy.mjs summary` subcommand validates the file first, then prints a handful of lines — the
+  path it read, the version, the newest change-log entry, the themes, the two admissibility lists as
+  up to two bullets each, and the deadline factors when the file states them — so the digest cannot
+  describe a strategy that is not on disk. The skill shows it and asks "what should change?" before
+  the interview; with no strategy file it exits `3` and the skill goes straight to the first-run
+  interview with no digest; with an invalid or partly missing one it exits `1` and names what is wrong
+  rather than presenting it as current. The change requires no new section of the strategy file, so
+  every strategy already committed still validates: `## What counts as value` and `## Explicitly out
+of scope` are summarised as the admissibility lists they are, never as a ranking order, and
+  `## Deadline tiers` is summarised narrowest first, the order the queue applies the factors, whatever
+  order the file holds the rows in.
+
+  The script contract moved to the skill's `REFERENCE.md` so `SKILL.md` stays within its length target.
+
+### Patch Changes
+
+- 5a6a14a: Let the content proof decide a closed bead's worktree, whatever its upstream is.
+  `prune-worktrees.mjs` still refused every worktree ralph created, because ralph
+  cuts its branch from the remote base (`git worktree add -b feature/<id> …
+origin/main`), `branch.autoSetupMerge` makes that base the branch's upstream, and
+  the squash merge that lands the work rewrites its commits — so the branch stays
+  ahead of its own base for ever and the unpushed-commit check, which ran first,
+  always fired. A closed bead is now decided by content alone: the base must hold
+  the branch's own version of every path the branch changed since their merge base,
+  and the refusal names that content when it does not. An open bead keeps the
+  upstream refusal, and with no upstream it is refused whatever the content says.
+  The base guard now tests the ref instead of the tip: a base that names the
+  worktree's own branch (local or remote-tracking) is a self-comparison and
+  refuses, while a branch cut from the base and never committed to holds the base's
+  own commit and is removed — the case every fresh ralph worktree used to reach.
+
+## 2.10.0
+
+### Minor Changes
+
+- 9d86a2d: Rank bd due dates in the `hitl-queue`. A bead's `--due` date now multiplies its total by the
+  factor of the narrowest tier its remaining time fits inside — `1` more than a week out, `1.5`
+  within a week, `2` within two days, `4` within a day, `8` once overdue. The numbers live in the
+  strategy's new optional `## Deadline tiers` table, so tuning them is a strategy edit and a
+  `bump`, never a code change; a strategy without that section ranks on the documented default,
+  and `validate` fails a table it cannot read. Each row shows the deadline, the time left and the
+  factor, an overdue bead is flagged `OVERDUE` rather than lifted in silence, and a bead with no
+  due date keeps the neutral factor. A deferred bead stays out of the queue until its
+  `defer_until` passes, applying bd's own wake rule to bd's own field.
+- 32395f6: Re-rank at every item boundary, with the comparison and the reason on the trail. `hitl-queue` gains
+  `boundary.mjs`: one command compares the theme's next item (the highest-ranked bead under the epic)
+  against the queue's top item, prints **both stored totals**, and says whether the scores point to
+  `stay` or `switch`. It computes no score — the totals, components and multipliers are the queue's —
+  and it recommends rather than switches: a run with no `--decide` writes nothing.
+
+  `--decide stay|switch|move` records the human's answer as one timestamped `bd note` on the theme
+  bead, carrying both scores and the reason, so a later session reads why the theme was kept or left.
+  A decision that contradicts the scores needs `--reason`, so an unexplained override cannot reach
+  the trail. A missing theme item, a named bead outside the queue and an empty queue are stated with
+  one next step instead of guessed.
+
+  The guppi agent gains its work unit: the theme is the current epic, a boundary is the completion of
+  one item, and every boundary ends in the documented trade-off — continue in the theme, switch
+  because higher-priority work waits elsewhere, or move because a break improves the next item. It
+  never leaves a theme without both scores on screen, and a wish for a different order stays a
+  `prioritise-work` change.
+
+- 763869c: Recommend one item from the queue and the strategy. `hitl-queue` gains `recommend.mjs`: one command
+  prints the queue's top row — its total, the four RICE components, the unblocking and
+  work-in-progress multipliers, what the answer unblocks — together with the line of the committed
+  strategy that justifies it, quoted from the file and refused when the file does not contain it.
+  `--bead <id>` recommends the bead a human named and notes the queue's own top choice in one line.
+
+  The guppi agent now opens a session with that one block and waits, answers "what should we look
+  at?" through the same steps, and states a condition with one next step instead of choosing when the
+  strategy is missing, nothing is scored, the queue is empty, or a named bead is not in the queue. It
+  still proposes only: no execution, no claim, no merge, no push.
+
+- 64b5deb: Resolve `{{PATH:skills/...}}` rows to the tree each install stages, so an agent row
+  always names a file the install contains. Claude Code stages skills flat
+  (`skills/<name>/SKILL.md`), so a row authored against the repository's grouped tree lost
+  its group segment and rendered as a bare relative path that resolved to nothing. The
+  staged shape is now declared per harness in `token-map.json`'s `layouts` table, the
+  claude installer resolves agent rows against the plugin root as it already did for
+  skills, and `test/rendered-paths-resolve.test.mjs` stages both installs and fails when
+  any rendered row names a file that is not there.
+- bed237e: Make the HITL queue scope-aware: it reads several `bd` workspaces and keeps one writable.
+
+  A scope list — `.agent-cortex/scopes.json` in the repository, then
+  `~/.agent-cortex/scopes.json` (`AGENT_CORTEX_HOME` overrides the root), then one implicit scope
+  for the current workspace — names each workspace, its kind (`code`, `personal`, `ops`) and whether
+  it is read-only. `readOnly` defaults to `true`, and a scope is writable only when it is not marked
+  read-only _and_ it is the current workspace, so a copied list cannot widen the writable set on
+  another machine.
+
+  Every configured scope contributes rows, each tagged with its scope. A scope whose directory is
+  missing or carries no `.beads` of its own is reported `unavailable` with the reason and skipped —
+  bd resolves a workspace by walking up, so the marker check is what stops one workspace's beads
+  being attributed to another. A failed `bd` call marks its own scope unavailable; the run still
+  exits `0`. A read-only scope passes through one guard that refuses any call other than the two
+  reads the queue issues, so the boundary survives a later edit.
+
+  One daily scope note sits above the ranked list, quoting the `- daily: <scope>, …` line from the
+  personal scope's own strategy and citing its version, section and scope. `--shared`
+  (`AGENT_CORTEX_QUEUE_SHARED=1`) marks output that leaves the machine: personal scopes are not read,
+  so personal rows and the daily note are withheld and counted.
+
+  `prioritise-work` documents the daily line, and guppi's agent text explains scopes, the note and the
+  privacy boundary.
+
+### Patch Changes
+
+- 7418a33: Prove that a refused boundary decision records nothing. The two refusal cases in
+  `test/boundary.test.mjs` now assert an empty trail as well as the message: `--decide` with an
+  outcome outside the three, and a decision against the scores with no `--reason`. The fake `bd` in
+  `test/helpers/fake-bd-queue.mjs` already records every `note` call, so the shared harness now
+  returns the trail a refused build left behind. A comment that claimed the parser refused a
+  bad `--decide` before the builder saw it was wrong for this case: the command line does refuse it,
+  but the test calls the builder directly, and the builder checks the runtime value itself, because
+  the union is a compile-time constraint only. No behaviour changes.
+- d8de6ba: Harden the guppi interrupt render test so a label that no longer sits with its own body fails.
+
+  The order assertion read the four step markers by offset, and the marker was the label, so the test
+  proved the four labels were ordered and nothing more. A render could keep every label in place and
+  exchange the two bodies — the record's text under `Rewind.`, the rewind's under `Record.` — inverting
+  the record-before-rewind rule the protocol exists to protect, and the test stayed green.
+
+  The test now reads the steps as (label, body) pairs and asserts the pair order, so each label must
+  carry its own body. No shipped text changed.
+
+- fd9c9a3: Remove a landed closed bead's worktree when the merge deleted its remote branch.
+  `prune-worktrees.mjs` refused every such worktree with "has no remote-tracking
+  branch", because a merge that deletes the branch also removes the local branch's
+  upstream — so the one case the script exists to handle failed housekeeping. A
+  missing upstream is now distinguished by content: with the tree clean and the
+  base branch holding the branch's own version of every path the branch changed
+  since their merge base, the worktree and its local branch are removed; otherwise
+  the worktree is kept and the refusal names the risk. The test is one-sided, so a
+  base that moved on after the branch was cut still proves the branch landed. It
+  proves content and never history: a removed branch is discarded with every
+  commit the base does not contain, such as a reverted change or an empty commit.
+  The base is the remote's default branch, read from `origin/HEAD` and never
+  hardcoded, with `--base <ref>` as the documented override; an unresolvable base
+  keeps the worktree and refuses. A base that resolves to the worktree's own
+  commit also keeps the worktree and refuses, because comparing a branch with
+  itself proves nothing.
+
+  The content proof also survives a path git would otherwise rewrite. The branch's
+  changed paths are read with `git diff --name-only -z` and split on NUL, then fed
+  back under `git --literal-pathspecs`, so a path holding a non-ASCII byte, a double
+  quote, a backslash, a leading colon or a newline round-trips exactly. Without both,
+  such a path matched no pathspec, the second diff came back empty, and a branch the
+  base never received was removed with an empty reason list.
+
+- 74ac309: Correct two shipped-text contradictions in the review docs: a count word that the data beside it
+  disproved, and a promise the sibling file did not keep.
+
+  `review-report`'s trend example is headed "re-run after two more rejections" but prints eight class
+  deltas, and one label per rejection makes that eight rejections. The heading now says eight, and the
+  sample is the script's own output over a tracker that took eight more rejections: eight classes
+  moved, the other four stayed, and the first-pass rate held because the rejections re-ran four
+  changes that already held a review cohort.
+
+  `review-defects` promised `EXAMPLES.md` carried "one real case per class". The file holds twelve
+  cases and eleven real observations, with `scope-creep` described as a situation because no recorded
+  case exists. The promise now says what the file delivers rather than inventing a case to satisfy it.
+
 ## 2.9.0
 
 ### Minor Changes

package/README.md

@@ -454,16 +454,20 @@ guppi helps with the work an agent cannot — design, ideation, prioritisation,
 manual confirmations. It is resident and propose-only: it recommends the next item and names the
 reason, then loads `plan`, `grill-me`, `hitl-collab`, `flesh-out-idea` or `prioritise-work` for the
 chosen item. It never executes AFK work, never merges and never pushes, and a disagreement with a
-priority opens a strategy review rather than a silent reorder. Between tasks it clears the context
-with `/clear`, and only after writing what was decided, what is open and what comes next to the bead
-trail and the memory. The tracker, not the window, holds the state that matters.
+priority opens a strategy review rather than a silent reorder. When that item is done it re-ranks
+at the boundary: the theme's next item against the queue's top item, both scores on screen, then one
+question — stay in the theme, switch to higher-priority work, or move for a single item. Between
+tasks it clears the context with `/clear`, and only after writing what was decided, what is open and
+what comes next to the bead trail and the memory. The tracker, not the window, holds the state that
+matters.
 
 ```sh
 claude --agent agent-cortex:guppi
 ```
 
 Its authority is prioritisation, not action. `prioritise-work` owns the committed strategy file;
-`score-bead` records the score and `hitl-queue` prints the order. guppi reports them and never
+`score-bead` records the score, and `hitl-queue` prints the order and recommends one item from it
+with the line of the strategy that justifies the choice. guppi reports them and never
 recomputes them. Personal work is a town-level bd scope — no rig, no polecats, no refinery, no merge
 queue.
 

package/agents/README.md

@@ -152,6 +152,11 @@ When composing the final agent file for a specific harness:
    files / installing for claude and pi; pi's `agent-modes` extension does the same at runtime. See the `contract` section of `token-map.json` and
    `token-map.README.md` for the rules.
 
+A `{{PATH:skills/…}}` row is authored against this repository's tree, which nests every skill
+one group deep, and resolves to the tree the harness stages. Claude Code stages skills flat, so
+the row loses its group segment there; the pi install keeps it. `token-map.json`'s `layouts`
+table records the shape per harness, so a row never names a file the install does not contain.
+
 The pi harness's `agent-modes` extension is a runtime consumer of this format: it
 composes agent prompts on the fly from `agent.md` + `pi/frontmatter.json`, substituting
 tokens against `token-map.json`'s pi column with no install step. See

package/agents/guppi/agent.md

@@ -23,7 +23,7 @@ This file never restates a skill's rules.
 |---|---|---|
 | `prioritise-work` | Choosing what to work on next, or the committed strategy is missing, stale or disputed. It owns the strategy file, runs the interview, and version-bumps the artefact. | {{PATH:skills/workflow/prioritise-work/SKILL.md}} |
 | `plan` | The human has chosen a feature, and it needs a PRD, a task breakdown and classified beads. | {{PATH:skills/workflow/plan/SKILL.md}} |
-| `hitl-queue` | The human needs to know which open decision to answer first, or a planning session must report that queue before it proposes anything. | {{PATH:skills/workflow/hitl-queue/SKILL.md}} |
+| `hitl-queue` | The human needs to know which open decision to answer first, or the session must open with one recommendation drawn from that queue. | {{PATH:skills/workflow/hitl-queue/SKILL.md}} |
 | `hitl-collab` | Work needs a human: a review, a manual step, a confirmation, or a handoff document. | {{PATH:skills/workflow/hitl-collab/SKILL.md}} |
 | `grill-me` | A plan or a design needs stress-testing before anyone acts on it. | {{PATH:skills/productivity/grill-me/SKILL.md}} |
 | `flesh-out-idea` | An idea bead needs deepening, or promotion to an epic with task children. | {{PATH:skills/planning/flesh-out-idea/SKILL.md}} |
@@ -31,6 +31,56 @@ This file never restates a skill's rules.
 **The strategy skill is `prioritise-work`.** It owns the committed strategy file, and it is the only
 skill in this list that writes that file.
 
+## Session start
+
+A session opens with **one** recommendation, never a list, and then waits. `hitl-queue` ranks, the
+strategy justifies, and guppi says the one item the two agree on.
+
+1. **Read the rubric.** Run `validate` in `prioritise-work`. It prints the file when it passes, and
+   that printed text is the only place a justification may be quoted from.
+2. **Read the queue's top row.** Run `recommend --json` in `hitl-queue`. The row carries the bead,
+   its total, the four components, both multipliers and the beads it unblocks. Report them as given;
+   guppi computes no score.
+3. **Say the block.** Choose the one line of the rubric that justifies that bead, and run
+   `recommend --why "<that line>"`. The script refuses a line the file does not contain, so an
+   invented reason fails before it is spoken. Say the block it prints, then **wait** for the human.
+
+**"What should we look at?"** is that same request in other words, and so is any opening that asks
+what to do next. Nothing about the session — the theme, the backlog, the last decision — replaces
+the three steps.
+
+**When the human names a bead instead**, pass it as `--bead <id>`. The recommendation is their bead,
+and the block adds one line naming the queue's own top choice. Where the two disagree, that line is
+the whole of the disagreement: the human's choice stands, and a wish to see another bead first is a
+strategy change through `prioritise-work`, never a silent override.
+
+### When nothing can be recommended
+
+Four conditions each stop at a stated result and one offered next step. Never fill the gap with a
+suggestion of your own, and never score or reorder anything to clear it.
+
+| The block says | What guppi offers |
+|---|---|
+| `No recommendation · no usable strategy` | The `prioritise-work` interview, which writes or bumps the file |
+| `No recommendation · nothing is scored` | `score-bead` on one bead, then the queue again |
+| `No recommendation · the queue is empty` | Filing the decision as an `execution:hitl` bead, or lifting a deferral |
+| `No recommendation · <id> is not in the queue` | `bd show <id>` to see why, then a bead from the queue |
+
+## The work unit
+
+A session works one **theme** — the current epic — and re-ranks at every **boundary**: the
+completion of one item (a decision recorded, a plan created, a handoff sent, a review given).
+
+At each boundary, run `boundary` in `hitl-queue` and say the block it prints: the theme's next item
+against the queue's top item, with both scores and the reason that names them. Then ask for one of
+three outcomes — **stay**, **switch** because higher-priority work waits elsewhere, or **move**
+because a break improves the next item — and pass the answer as `--decide`, which writes the
+comparison and the reason to the theme bead's trail with a timestamp.
+
+Never leave a theme without both scores on screen. Never record a decision the human did not give.
+A wish for a different order is a `prioritise-work` change, never a boundary one.
+{{PATH:skills/workflow/hitl-queue/BOUNDARY.md}} carries the block, the states and the options.
+
 ## Boundaries
 
 - **Recommends, never acts.** State the next item and the reason for it. The human chooses. The
@@ -42,7 +92,8 @@ skill in this list that writes that file.
 - **Never merges.** A pull request is a human gate. guppi may read one and hand it to a reviewer.
 - **Never pushes.** No `git push`, no release, no version bump of this package.
 - **Never overrides a priority silently.** "This should be higher" means the strategy is wrong,
-  stale, or has shifted. Open the `prioritise-work` interview, record the change, then re-rank.
+  stale, or has shifted. Run `prioritise-work`, which opens with a digest of the current strategy,
+  record the change, then re-rank.
 - **Never invents a strategy.** If the strategy file is missing or invalid, say so plainly and offer
   the interview. Do not guess priorities.
 - **Propose-only and resident.** guppi is a standing collaborator in one session. It is not a task
@@ -55,6 +106,25 @@ skill in this list that writes that file.
 A scope is one bd workspace. guppi reads several scopes and writes to one: the **current
 workspace**. Every other scope is read-only, whatever the request.
 
+The scope list is configuration, not this file: `.agent-cortex/scopes.json` in the repository, or
+`~/.agent-cortex/scopes.json` for the scopes that belong to the person rather than the checkout.
+The `hitl-queue` skill reads it and prints one ranked list across every scope it can read, tagging
+each row with the scope it came from. A scope that is absent or carries no tracker of its own is
+reported `unavailable` and skipped: a machine without the personal repo still has a queue. Read the
+list and the privacy rules from {{PATH:skills/workflow/hitl-queue/SCOPES.md}} rather than
+restating them here.
+
+**The daily note is the queue's first line about the day.** It names the scopes the day belongs to
+and quotes the personal strategy line it came from. Report it as printed, above the ranked list,
+and never paraphrase the quote: the citation is the point. Which scopes the day belongs to is the
+human's call, written in their own strategy — when the note says it is missing, offer the
+`prioritise-work` interview rather than choosing a scope.
+
+**Personal work stays in the personal scope.** Never copy a personal bead's text into a code
+workspace, a handoff document or a pull request, and never write to a scope other than the current
+workspace. An output that leaves the machine — a pasted report, a message to another agent, a PR
+body — comes from a `--shared` run, which withholds personal rows and the daily note.
+
 **Personal work is a town-level scope, never a rig.** A rig is a code-project container — refinery,
 witness, polecats, seeded patrols — and it suits code projects. Personal work belongs to the mayor
 role at town level: no rig, no polecats, no refinery, no merge queue. Never describe personal work

package/bin/installers/claude.mjs

@@ -156,10 +156,14 @@ function byName(a, b) {
 
 /**
  * Compose every agent from agents/<name>/ — all harnesses share the composable sources.
+ * `{{PATH:...}}` rows resolve against the plugin root, as they do in skills: a bare
+ * relative path would name a file relative to the reader's working directory, and the
+ * install ships the file under ${CLAUDE_PLUGIN_ROOT}.
  * @param {string} root
+ * @param {{ pluginRoot: string | undefined, warn: Warn }} options
  * @returns {Promise<{ files: { file: string, content: string }[] }>}
  */
-async function buildAgents(root) {
+async function buildAgents(root, { pluginRoot, warn }) {
   const files = [];
   const entries = (await readdir(join(root, "agents"), { withFileTypes: true })).sort((a, b) =>
     byName(a.name, b.name),
@@ -170,7 +174,7 @@ async function buildAgents(root) {
     const dir = join(root, "agents", entry.name);
     if (!(await isFile(join(dir, "agent.md"))) || !(await isFile(join(dir, "claude", "frontmatter.json")))) continue;
 
-    const fm = await composeAgent(root, entry.name, CLAUDE);
+    const fm = await composeAgent(root, entry.name, CLAUDE, { pluginRoot, resolveRelativePaths: true, warn });
     const slug = fm.name.startsWith(NAME_PREFIX) ? fm.name.slice(NAME_PREFIX.length) : fm.name;
     const header =
       `---\n` +
@@ -720,7 +724,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
       ? await installInstructions({ root, target: instructionsTarget, dryRun, warn: warnSink })
       : null;
 
-  const agents = await buildAgents(root);
+  const agents = await buildAgents(root, { pluginRoot: rootPlugin, warn: warnSink });
   const skillOut = join(out, "skills");
   const skills = await buildSkills(root, skillOut, { dryRun, pluginRoot: rootPlugin, tokenMap, warn: warnSink });
   const docs = await installDocs({ root, output: out, dryRun, tokenMap });

package/package.json

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

package/scripts/lib/compose-agent.mjs

@@ -8,22 +8,25 @@
 //   1. {{SECTION:name}} is replaced with <dir>/<harness>/<name>.md content.
 //   2. {{TOOL:key}} is replaced with the harness column of token-map.json.
 //   3. {{PATH:arg}} with a named key resolves through token-map.json's paths
-//      table; anything else is a relative path and stays verbatim.
+//      table; anything else is a relative path and stays verbatim, except that
+//      installers resolve it against the plugin root and map a `skills/…` row
+//      onto the tree that harness stages skills in (token-map.json `layouts`).
 // Substitution order is SECTION → TOOL → PATH (matches extensions/agent-modes).
 // Missing sections, unknown tool keys, or schema-invalid frontmatter are hard
 // errors: a committed generated file must never ship a literal token or a
 // silently dropped section.
 //
-// Options (the pi installer passes `dropNullTools`, `pluginRoot` and
-// `resolveRelativePaths`; the claude installer uses the strict defaults):
+// Options (both installers pass `pluginRoot` and `resolveRelativePaths`; pi also
+// passes `dropNullTools`):
 //   dropNullTools          replace null-mapped tool tokens with an empty string and
 //                          warn instead of throwing (pi's prose rule per the
 //                          token-map contract)
 //   pluginRoot             override the plugin_root used for resolved paths
 //                          (installers compute it from the actual install layout)
 //   resolveRelativePaths   non-keyed {{PATH:...}} args resolve to pluginRoot/arg
-//                          instead of staying verbatim (install time; without it
-//                          they stay bare for runtime resolution)
+//                          (a `skills/…` row mapped onto the harness's staged
+//                          skills shape) instead of staying verbatim (install
+//                          time; without it they stay bare for runtime resolution)
 //   warn                   callback for drop/omit warnings (default: no-op; the
 //                          pi installer collects them into its result)
 //
@@ -43,6 +46,7 @@ import { join } from "node:path";
  * @property {number} [version]
  * @property {Record<string, Record<string, string | null>>} tools
  * @property {Record<string, Record<string, string | PathSpec>>} paths
+ * @property {Record<string, Record<string, string>>} [layouts]
  */
 
 /**
@@ -100,6 +104,8 @@ function noop() {}
  *   with a warning when `dropNullTools`, otherwise throw.
  * - PATH: named key → resolve through the paths table (plugin_root overridable);
  *   non-keyed → join(pluginRoot, arg) when `resolveRelativePaths`, else verbatim.
+ *   A non-keyed `skills/…` arg is mapped onto the harness's staged shape first
+ *   (see stagedRelativePath).
  * - SECTION tokens are *not* handled here — the agent composer resolves them from
  *   the harness's section files before calling this.
  *
@@ -231,6 +237,36 @@ async function parseFrontmatter(path, name, harness) {
 
 // ─── Path resolution ─────────────────────────────────────────────────────────
 
+/**
+ * Map a repository-relative path onto the tree the harness stages it in.
+ *
+ * The repository nests every skill one group deep (skills/<group>/<name>/…), so
+ * an authored `skills/…` row is written in that grouped form. An installer that
+ * stages skills flat — Claude Code's plugin scan discovers skills/<name>/SKILL.md
+ * directly under skills/ — drops the group segment, and a row that kept it would
+ * name a directory the install does not have. The shape is a harness fact, read
+ * from token-map.json's layouts table, so a harness that stages skills
+ * differently needs no change here.
+ *
+ * @param {string} arg  Non-keyed {{PATH:...}} argument
+ * @param {string} harness
+ * @param {TokenMap} tokenMap
+ * @returns {string}
+ */
+function stagedRelativePath(arg, harness, tokenMap) {
+  const segments = arg.split("/");
+  if (segments[0] !== "skills") return arg;
+  // Every install ships a skill as a directory below skills/, so a shorter arg
+  // names nothing it can contain: fail now rather than render a dead row.
+  if (segments.length < 3) {
+    throw new Error(
+      `{{PATH:${arg}}} is not a staged path — a skill row is authored as skills/<group>/<name>/<file>`,
+    );
+  }
+  if (tokenMap.layouts?.skills?.[harness] !== "flat") return arg;
+  return [segments[0], segments[2], ...segments.slice(3)].join("/");
+}
+
 /**
  * Resolve a {{PATH:...}} argument for a harness's generated output.
  * Named keys resolve through token-map.json's paths table (recursively for
@@ -238,7 +274,7 @@ async function parseFrontmatter(path, name, harness) {
  * the installer beads own precise runtime path resolution (see token-map.README.md).
  * With the installer options (`pluginRoot`, `resolveRelativePaths`) the
  * plugin_root base and bare relative paths resolve against the actual install
- * layout instead.
+ * layout instead, and a `skills/…` row is mapped onto that layout.
  * @param {string} arg
  * @param {string} harness
  * @param {TokenMap} tokenMap
@@ -248,7 +284,9 @@ async function parseFrontmatter(path, name, harness) {
 function resolvePath(arg, harness, tokenMap, opts = {}) {
   const entry = tokenMap.paths?.[arg];
   if (!entry) {
-    if (opts.resolveRelativePaths && opts.pluginRoot) return join(opts.pluginRoot, arg);
+    if (opts.resolveRelativePaths && opts.pluginRoot) {
+      return join(opts.pluginRoot, stagedRelativePath(arg, harness, tokenMap));
+    }
     return arg;
   }
 

package/skills/review/review-defects/SKILL.md

@@ -111,7 +111,8 @@ class that keeps appearing is a gap in the stage before this one.
 
 ## Worked examples
 
-`EXAMPLES.md` carries one real case per class, with the rejection text a reviewer should write.
+`EXAMPLES.md` carries a case per class, with the rejection text a reviewer should write. Eleven are
+real observations; `scope-creep` is a described situation, because no recorded case exists.
 
 ## See Also
 

package/skills/review/review-report/EXAMPLES.md

@@ -99,16 +99,20 @@ the whole table rather than the top three.
 
 ## With a previous report
 
-The same project, recorded as a baseline one month earlier and re-run after two more rejections:
+The same project, recorded as a baseline one month earlier and re-run after eight more rejections:
 
 ```
 Change since the previous report
   Against /tmp/rr-example/trend/.agent-cortex-docs/defect-report.json, reported 2026-04-01T09:00:00Z
   criteria-unmet 1 (+1), docs-drift 1 (+1), missing-proof 1 (+1), and 5 more
-  First-pass review rate 75% (from 75%, no change)
+  First-pass review rate 33% (from 33%, no change)
+  Fix rounds review 12 (+8)
 ```
 
-The comparison reads the report the script wrote at `--baseline`, so it compares like with like.
+One label per rejection, so the eight rejections added eight labels: eight classes moved and the
+other four stayed where they were. The rejections re-ran four changes that already held a review
+cohort, so the rate did not move while the fix-round count did. The comparison reads the report the
+script wrote at `--baseline`, so it compares like with like.
 A class that did not change is not listed; when no class changed, the section says so. A baseline
 file with an unrecognised schema is refused rather than read as zeros, because a baseline that
 cannot be read must not become an invented trend.

package/skills/workflow/hitl-queue/BOUNDARY.md

@@ -0,0 +1,122 @@
+# The boundary re-rank
+
+A session that answers one item at a time drifts: the next item is whichever one was nearest, not
+whichever one matters most. This file defines the unit a session works in, and the one comparison
+it makes when that unit finishes.
+
+## The unit of work
+
+| Term | Meaning |
+|---|---|
+| **Theme** | The current epic. One theme at a time, and its children are the items it needs. |
+| **Item** | One thing the theme needs from a human: a decision answered, a plan shaped, a handoff written, a review given. |
+| **Boundary** | The completion of one item. The point where the session stops and checks whether the theme is still the right place to be. |
+
+The theme and its trail are the session's memory, not the window: a clear drops the window, and
+`bd show <epic-id>` still holds what was decided and why. [RECOMMEND.md](RECOMMEND.md) carries the
+one-item session start; this file carries what happens after that item is done.
+
+## The decision at every boundary
+
+One trade-off, three outcomes, and no fourth:
+
+| Outcome | When it is right | Read from the scores? |
+|---|---|---|
+| `stay` | Continue in the theme. The theme's next item still leads the queue. | Yes |
+| `switch` | Leave the theme, because higher-priority work waits elsewhere. | Yes |
+| `move` | Leave the theme for one item, because a break improves the next item. | No — a judgement, so it carries its own reason |
+
+The first two are readable from the two totals. A `move` is not: it is about what the next item
+needs, so it is always the human's reason and never the queue's.
+
+## The block
+
+```text
+Boundary · theme tst-t · strategy v2
+recommendation: switch — the queue's top item scores 8.0 against the theme's next 4.2, so higher-priority work waits elsewhere
+theme next  tst-a · total 4.2 · Decide the theme question
+queue top   tst-b · total 8.0 · Decide the outside question
+next: stay, switch or move is the human's call — nothing is recorded until they answer
+```
+
+**Both scores are always printed**, and the reason names both. That is the whole rule: an agent
+that leaves a theme without showing what it left for has asserted a priority it never displayed.
+A switch with no comparison on screen is a defect, not a summary.
+
+The recommendation is derived from the two stored totals and nothing else. The totals, the
+components and both multipliers are the queue's; this comparison computes no score, so the number
+a reader checks is the number the queue ranked by. [SKILL.md](SKILL.md) owns that arithmetic.
+
+## The record
+
+```bash
+node <skill-scripts>/boundary.mjs boundary --theme <epic-id>
+node <skill-scripts>/boundary.mjs boundary --theme <epic-id> --decide switch
+node <skill-scripts>/boundary.mjs boundary --theme <epic-id> --decide move --reason "<what the break buys>"
+```
+
+A run with no `--decide` prints the comparison and writes nothing. A run that names a decision
+writes one trail entry with `bd note` on the **theme bead** — the epic that owns the items — and
+prints it back:
+
+```text
+trail: tst-t · [2026-11-15T09:30:00.000Z] boundary: switch · theme next tst-a total 4.2 vs queue top tst-b total 8.0 · reason: the queue's top item scores 8.0 against the theme's next 4.2, so higher-priority work waits elsewhere
+```
+
+Three parts, and all three are required: the **timestamp**, **both scores**, and the **reason**.
+A later session reads `bd show tst-t` and sees why the theme was kept or left, without reading a
+transcript. An entry with a reason but no numbers cannot be checked, and an entry with numbers but
+no reason says nothing about intent.
+
+## Recommends, never switches
+
+- **The human decides.** `--decide` is the recording step, and it is passed after an answer, never
+  instead of asking for one. Nothing switches on its own.
+- **A decision against the recommendation needs `--reason`.** A `move` always does, and so does a
+  `stay` or `switch` that contradicts the two scores. The refusal is the point: an unexplained
+  override is the case the trail exists to catch.
+- **The boundary changes what to do next, never what outranks what.** The order is the queue's and
+  the rubric is the strategy's. A wish for a different order is a `prioritise-work` change, not a
+  boundary decision.
+
+## Which item is compared
+
+`--theme <epic-id>` names the theme. The theme's next item is the **highest-ranked item under that
+theme** in the queue, so the comparison cannot be steered by naming a weak one. `--next <id>` names
+another item when the session knows better, and the queue's top item is rank 1 either way.
+
+## The states that are stated instead of guessed
+
+| First line | What it means | The step it offers |
+|---|---|---|
+| `No boundary · the queue is empty` | No open `execution:hitl` bead exists | File the theme's next item, or lift a deferral |
+| `No boundary · theme <id> has no ranked item` | Nothing scored sits under that theme | Name the item with `--next`, or score it with `score-bead` |
+| `No boundary · <id> is not in the queue` | The named item is not an open scored `execution:hitl` bead | Name one from the queue, or score that bead |
+
+None of them guesses an item and none is a failure of the run: exit `0` means an answer was
+printed, whichever answer it was.
+
+| Option | Effect |
+|---|---|
+| `--theme <epic-id>` | The theme; required, because a boundary belongs to one |
+| `--next <id>` | The theme's next item, when the session names it instead |
+| `--decide <outcome>` | `stay`, `switch` or `move` — record the human's decision |
+| `--reason "<text>"` | Why that decision; required when it contradicts the recommendation |
+| `--file <path>` | Strategy file (default `.agent-cortex/working-docs/strategy.md`, relative to the repository root) |
+| `--include-ideas` | Rank `kind:idea` beads too, as the queue does |
+| `--cwd <dir>` | Directory the strategy path and `bd` resolve from |
+| `--json` | Print the answer as JSON, including the decision and the trail entry |
+
+Exit `1` means a `bd` call failed and exit `2` means a malformed call — a missing `--theme`, an
+outcome outside the three, or a decision against the scores with no reason. `BD_PATH` pins the `bd`
+binary.
+
+## Red Flags
+
+- Red flag: leaving a theme without the two scores on screen, so the reader has to trust the agent.
+- Red flag: recording a decision with no reason, or a reason with no numbers in the trail entry.
+- Red flag: switching because the agent judged the priority itself, instead of reading the queue.
+- Red flag: recomputing a total here, so the comparison and the queue can disagree.
+- Red flag: recording a decision the human has not given, so the session switches on its own.
+- Red flag: writing the trail entry to another scope, so a theme's history lands somewhere its
+  owner will not read.