@jaybeeuu/agent-cortex 2.8.0 → 2.10.0

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.

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

@@ -0,0 +1,59 @@
+# Deadlines
+
+A `--due` date is the one deadline field, and `bd` already stores it. The queue multiplies the
+total by the factor of the narrowest tier the remaining time fits inside. The table is the
+strategy's to tune, the boundary is arithmetic, and the row prints what it applied.
+
+## The shipped table
+
+| Time left | Factor |
+|---|---|
+| more than a week | 1 |
+| within a week | 1.5 |
+| within two days | 2 |
+| within a day | 4 |
+| overdue | 8 |
+
+Those numbers are the **shipped default**: a strategy with no `## Deadline tiers` section ranks on
+this table, and so does a run whose header says `strategy unknown`.
+
+## A strategy's table
+
+The strategy's optional `## Deadline tiers` section carries the table a repository tunes, so
+moving a tier is a strategy edit and a `bump`, never a code change. A row reads
+`| <when> | <factor> |`, narrowest first, and `<when>` is `within <n><m|h|d>`,
+`more than <n><m|h|d>` or `overdue`.
+
+A table that is present must carry exactly one `overdue` row, exactly one `more than` row and at
+least one `within` row, and `validate` exits 1 naming every row it cannot read — a malformed table
+never falls back to the default in silence.
+
+## Where a boundary falls
+
+A boundary falls on the side that names it: with exactly one day left a bead 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 bead with no due date sits outside the tiers and keeps the factor 1, so tuning a row
+never lifts undated work by accident.
+
+## The deadline clause in a row
+
+A ranked row shows the deadline, the time left and the factor, and an overdue bead is flagged
+rather than lifted in silence:
+
+```text
+2  bd-2  8.0  rice 4.2 = R4 · I3 · C0.7 · E2  ×1.00 dependents(0)  ×1.0  deadline ×8 OVERDUE by 1d (due 2026-11-14T08:59Z)
+```
+
+An unscored row has no total to multiply, so it shows the due moment and `OVERDUE` with no factor
+at all:
+
+```text
+-  bd-6  —  unscored — no rice metadata  OVERDUE by 2d 11h (due 2026-11-13T00:00Z)
+```
+
+## Deferral
+
+`--defer` is bd's own field and bd's own rule, so the queue reads it rather than inventing a second
+one. `bd ready` wakes a bead whose defer date has passed, while `bd list` keeps reporting the stale
+`deferred` status it was parked in, so the queue applies that same wake rule to `defer_until`. A
+bead deferred into the future is absent and counted; a bead whose defer date has passed is listed.

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

@@ -0,0 +1,89 @@
+# One recommendation
+
+The queue is a list; a session that has to decide says one item and stops. `recommend.mjs` prints
+that one row — the same total, components and multipliers the queue computed, plus the line of the
+strategy that justifies it — and states a condition instead of choosing whenever it cannot justify
+a row.
+
+Every run ends in one of five answers: the block, or one of the four conditions that replace it.
+
+It ranks nothing. The bead is `rows[0]` of the queue, or the bead the human named, and every number
+on the block is the row's own.
+
+## The three commands
+
+```bash
+node <skill-scripts>/../../prioritise-work/scripts/strategy.mjs validate    # prints the rubric
+node <skill-scripts>/recommend.mjs recommend --json     # the top row, structured
+node <skill-scripts>/recommend.mjs recommend --why "<one line of the rubric>"
+```
+
+`validate` first, because the printed rubric is the only text a justification may be quoted from.
+`--json` second, to read the row's id and totals. `--why` last, once the line that justifies that
+bead has been chosen from the rubric.
+
+## The quote rule
+
+`--why` names a line, or part of one, from the strategy file. The script finds that line in the
+file, prints it verbatim with the section it sits under, and refuses the run (exit `2`) when no line
+contains it. Guidance comments in the file are not quotable: they are instructions for whoever
+writes the rubric, not the owner's own words.
+
+```text
+why: "shorter review turnaround for human-gated work." · Current themes
+```
+
+A quote the file does not hold is a refused run rather than a weaker reason, so an invented
+justification cannot reach the human.
+
+## The block
+
+```text
+Recommendation · tst-a · total 10.0 · strategy v2
+Ship the decision queue
+rice 4.2 = R4 · I3 · C0.7 · E2  ×2.39 dependents(3)  ×1.0
+unblocks tst-c, tst-d, tst-e
+why: "shorter review turnaround for human-gated work." · Current themes
+```
+
+Five lines: the bead and its total, its title, the four components with the unblocking multiplier
+and the work-in-progress multiplier, the beads the answer releases, and the strategy line. One
+recommendation, never the list the row came from.
+
+## When the human names a bead
+
+`--bead <id>` recommends the bead the human named instead of the top row. The block is the same,
+and one line is added when the queue put a different bead first:
+
+```text
+queue top: tst-a · total 10.0 · Ship the decision queue
+```
+
+That line is the whole of the disagreement. The human's choice stands, and a wish to see it first
+is a strategy change through `prioritise-work`, never a silent override.
+
+## The stated conditions
+
+Each one leads with `No recommendation`, names the condition, and offers the one step that clears
+it. None of them guesses a bead, and none of them is a failure of the run: exit `0` means an answer
+was printed, whichever answer it was.
+
+| First line | What it means | The step it offers |
+|---|---|---|
+| `No recommendation · no usable strategy` | The file is absent, or `validate` rejected it; every defect is listed | Write or fix it with `prioritise-work` |
+| `No recommendation · nothing is scored` | The queue holds beads, and not one carries a `rice` record | Score one bead with `score-bead` |
+| `No recommendation · the queue is empty` | No open `execution:hitl` bead exists; the excluded idea and deferred counts are printed | File the decision as an `execution:hitl` bead, or lift a deferral |
+| `No recommendation · <id> is not in the queue` | The bead the human named is not an open `execution:hitl` bead | Check it with `bd show`, then name one from the queue |
+
+| Option | Effect |
+|---|---|
+| `--why "<line>"` | The strategy line that justifies the choice; required before a block is printed |
+| `--bead <id>` | Recommend the bead the human named, noting the queue's own top choice |
+| `--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 state name |
+
+Exit `1` means a `bd` call failed, and exit `2` means a malformed call — an unknown option, or a
+`--why` the strategy does not contain. `BD_PATH` pins the `bd` binary. The script makes no writes:
+the tracker calls are `bd list` and `bd dep list`, nothing else.

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

@@ -0,0 +1,118 @@
+# Scopes
+
+The scope list says which bd workspaces the queue reads, and which one it may write. It is a
+**file**, never code: a path in a script would name one person's machine, and a scope list does
+not.
+
+## The file
+
+| Item | Value |
+|---|---|
+| Default | `.agent-cortex/scopes.json`, relative to the repository root |
+| User level | `<AGENT_CORTEX_HOME>/scopes.json`, then `~/.agent-cortex/scopes.json` |
+| Override | `--scopes <path>` |
+| Fallback | no file found: one scope, named `code`, for the current workspace, writable |
+
+The project list is read first, so a repository can commit the scopes its work spans. The user
+list is the personal one: it travels with the person, not the checkout. With neither, the queue
+behaves as it did before scopes existed — one workspace, one list.
+
+```json
+{
+  "scopes": [
+    { "name": "code", "path": ".", "kind": "code", "readOnly": false },
+    { "name": "notes", "path": "~/personal", "kind": "personal", "readOnly": true },
+    { "name": "ops", "path": "../ops", "kind": "ops" }
+  ]
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `name` | yes | The tag every row from this scope carries. Unique within the file. |
+| `path` | yes | The workspace. `~` is the home directory; a relative path resolves against the repository root of the list itself, never the directory the run started in. The queue reports the resolved absolute path, never the text this field holds. |
+| `kind` | no | `code`, `personal` or `ops`. Default `code`. A `personal` scope is the one a shared invocation withholds. |
+| `readOnly` | no | Default `true`. A scope you did not mark writable is read-only. |
+
+## One writable scope
+
+The **current workspace** — the nearest ancestor of the run's directory that carries its own
+`.beads` — is the only scope a command may write to. A scope is writable only when it is not
+marked read-only *and* its resolved path is that workspace, so a list copied onto another machine
+cannot widen the writable set: the same entry that is writable in your checkout is read-only in
+mine.
+
+The queue writes nothing today — its tracker calls are `bd list` and `bd dep list`. The rule is
+enforced anyway, at the one function every tracker call for a scope passes through, so a later
+change cannot quietly write to the wrong workspace:
+
+```js
+guardRunner(scope, bd)          // refuses any call that is not one of the two reads
+```
+
+## Availability
+
+A scope is read only when it can be:
+
+- **the directory exists**, and
+- **it carries its own `.beads`**, because bd resolves a workspace by walking *up* from the
+  current directory. A configured directory with no tracker of its own would otherwise read the
+  enclosing workspace's beads and tag them with the wrong scope, which is a privacy failure and a
+  correctness one.
+
+Anything else is reported `unavailable` with the reason, above the list, and skipped. A `bd` call
+that fails marks its own scope unavailable and leaves the others alone, so one broken workspace
+never costs the whole queue. Exit code stays `0`.
+
+## The daily scope note
+
+Above the ranked list the queue prints one line: which scopes the day belongs to, and the
+strategy line that says so.
+
+```
+today · personal, code — "daily: personal, code — Monday and Tuesday are the personal objectives" (strategy v3, "## Current themes", scope notes)
+```
+
+The line is read from the **personal scope's** own strategy, at the documented default path
+inside that workspace, so the note is personal strategy text and never a copy of it. Write it as
+one bullet under `## Current themes`:
+
+```markdown
+- daily: personal, code — Monday and Tuesday are the personal objectives
+```
+
+The scope names before the em dash are what the note leads with; the rest is the reason, quoted
+verbatim. The citation names the strategy version, the section the line sat under, and the scope
+it was read from. When no personal scope is configured, or none carries a `daily:` line, the note
+says that and names what to add — it never invents one.
+
+## The privacy boundary
+
+- **A read-only scope receives no write.** Enforced by `guardRunner`, tested with a mutation.
+- **A shared invocation reads no personal scope at all.** `--shared`, or
+  `AGENT_CORTEX_QUEUE_SHARED=1`, marks output that will leave this machine — a CI log, a pasted
+  report, a handoff to another agent. Personal scopes are then `withheld`: not read, not ranked,
+  not quoted, and counted in the header so nothing disappears silently. **A withheld scope
+  publishes neither its name nor its path**, because both identify a workspace the reader may not
+  see: the header prints the count, and `--json` prints `null` for both fields.
+- **A withheld scope publishes no `name` and no `path`.** Both identify the workspace the reader
+  may not see — a path encodes the home directory, and a name is whatever the owner called it —
+  so `--json` carries `null` for both. `kind`, `readOnly` and `writable` remain, because the
+  header already says a personal scope was withheld.
+- **A personal row appears only in a local invocation.** Local is the default, because the person
+  reading their own queue on their own machine is the common case.
+- **Nothing personal is written anywhere.** The queue copies no bead text into another workspace
+  because it writes no bead at all, and the daily line is quoted, never re-filed.
+
+## Reading the queue
+
+```bash
+node <skill-scripts>/queue.mjs queue                     # every configured scope
+node <skill-scripts>/queue.mjs queue --scopes ./list.json
+node <skill-scripts>/queue.mjs queue --shared             # output that leaves this machine
+node <skill-scripts>/queue.mjs queue --json                # scope statuses and the note, structured
+```
+
+`--json` carries the same answer with every derived field: each scope's `status`, `reason`,
+`readOnly` and `writable`, the daily note, and the withheld counts. A withheld scope has `null`
+for `name` and `path`.

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

@@ -0,0 +1,150 @@
+---
+name: hitl-queue
+description: Ranks the open execution:hitl beads across every configured bd workspace into one list ordered by RICE, transitively blocked dependents, work in progress and the time left to each due date, prints what each answer unblocks and which scope each row came from, notes which scope the day belongs to, and recommends one item from that list with the line of the strategy that justifies it. Use when deciding which human decision to answer next, when a session cold-starts and must say one item, when a planning session starts, or when asked "what needs my decision", "show the queue", "what should we look at" or "what should I answer first".
+---
+
+# HITL Queue
+
+Owns one output: **the ranked list of beads waiting for a human answer**, read from every configured workspace and tagged with the scope each row came from. Each row carries its own arithmetic, so the owner can check *why* one decision outranks another instead of trusting a number.
+
+A queue is not a priority. The RICE score is `score-bead`'s judgement, the band it implies is reviewed there, and this skill only orders beads by a number that already exists. Where no score exists, the queue says so and ranks nothing: inventing an order would hide the gap a person has to fill.
+
+## When to use
+
+- A planning session starts and the owner needs to know which decision comes first.
+- "What needs my decision?", "show the queue", "what should I answer first?".
+- "What should we look at?" — a cold start that must say one item rather than print the list. See [RECOMMEND.md](RECOMMEND.md).
+- Before dispatching work from a backlog of HITL beads: the answer unblocks the work, so the order of answers is the order of the work.
+- A bead was scored or re-scored and the order should follow the new number.
+
+## When NOT to use
+
+- Judging one bead's components — use `score-bead`. This skill reads a score, it never makes one.
+- Writing or bumping the rubric the score rests on — use `prioritise-work`.
+- Choosing what to *build* next with an agent — `ralph` drains `execution:afk` beads, and ideas are ranked by `flesh-out-idea`.
+- Recording a new idea — use `record-idea`.
+
+## The formula
+
+```
+total = rice × (1 + ln(1 + dependents)) × (in progress ? 1.5 : 1) × deadline
+```
+
+| Term | Meaning |
+|---|---|
+| `rice` | The stored `score` from the bead's `rice` metadata, written by `score-bead`. Never recomputed here. |
+| `dependents` | Distinct beads that wait on this answer, **transitively**. |
+| `1.5` | Work in progress outranks equal work not started, so the queue drains WIP first. |
+| `deadline` | The strategy's tier factor for the time left until the bead's `--due`; `1` when it has no due date. |
+
+The dependent count is the load-bearing term. A bead blocking A, which blocks B, which blocks C, unblocks **three**. The walk follows `bd dep list <id> --direction up` from bead to bead, and collects **beads, not paths**: when the graph reconverges (a diamond — one bead reached by two routes), it is counted once, because counting paths would measure the shape of the graph instead of the work an answer releases.
+
+Two edges of the walk are deliberate: only `blocks` edges count, because a related or duplicate edge is not something anyone waits on; and the walk passes through every bead while counting only live ones, because a closed bead is still a link in the chain but finished work cannot be unblocked. `1 + ln(1 + n)` is logarithmic on purpose: unblocking thirty chores must not drown the list under one row, and zero dependents scores `1`, so a bead that unblocks nothing is not penalised — it is simply not lifted.
+
+## Deadlines
+
+A `--due` date is the one deadline field, and `bd` already stores it. The queue multiplies the total by the factor of the narrowest tier the time left fits inside; those factors are the **shipped default**, and a strategy's optional `## Deadline tiers` section replaces them, so moving a tier is a strategy edit and a `bump`, never a code change. A bead with no due date keeps the factor 1. [DEADLINES.md](DEADLINES.md) carries the shipped table, the row syntax, the `validate` rule, the boundary and the defer rule.
+
+## Scopes
+
+A scope is one bd workspace. The queue reads every one and writes to none; the current workspace is the only writable scope, so every other is read-only, and a missing workspace is `unavailable` and skipped. A shared invocation (`--shared`, or `AGENT_CORTEX_QUEUE_SHARED=1`) withholds every personal scope and the daily note, and prints the count. [SCOPES.md](SCOPES.md) carries the list format, the writable rule, the daily note and the boundary.
+
+## The report
+
+One flat list, no sections, ranked first and unscored last:
+
+```
+HITL decision queue · 3 ranked, 1 unscored · 3 scopes, 1 unavailable · strategy v2
+total = rice × (1 + ln(1 + dependents)) × 1.5 in-progress × deadline tier · ties break on rice, then scope, then id · unscored last
+excluded: 3 kind:idea beads (--include-ideas ranks them)
+today · personal, code — "daily: personal, code — Monday and Tuesday are the personal objectives" (strategy v3, "## Current themes", scope notes)
+unavailable: ops (/srv/ops) — workspace does not exist
+
+1  code    bd-7  10.0  rice 4.2 = R4 · I3 · C0.7 · E2  ×2.39 dependents(3)  ×1.0
+    Ship the queue — unblocks bd-8, bd-9, bd-10
+2  notes   bd-2   8.0  rice 4.2 = R4 · I3 · C0.7 · E2  ×1.00 dependents(0)  ×1.0  deadline ×8 OVERDUE by 1d (due 2026-11-14T08:59Z)
+    Decide the API shape — unblocks nothing
+-  code    bd-4     —  unscored — no rice metadata (score it with score-bead)
+    Decide the rollout — unblocks nothing
+```
+
+Every row carries its rank, scope, id, total, the four components the score was computed from, all three multipliers, a deadline clause when the bead has a due date, the title, and one clause naming what the answer unblocks — the scope tag keeps two workspaces that reuse a bead id apart. An unscored row keeps its place at the end of the same list with the reason: no `rice` metadata, no score inside a `rice` record, or scored against an older strategy version (that last one is ranked and marked `scored at strategy v2, current v3`). `--json` prints the same answer with every derived field, including each scope's status and the daily note, for a caller that needs to act on it.
+
+### One item, not the list
+
+A session that must decide says one row and stops. `recommend.mjs` prints the top row with the line of the strategy that justifies it, and a stated condition with one next step when it cannot justify a row. It ranks nothing: the total, the components and the multipliers are the row's own. [RECOMMEND.md](RECOMMEND.md) carries the four stated conditions, the `--why` rule and the `--bead` form for a bead the human named. When that item is done, `boundary.mjs` compares the theme's next item against the queue's top item and prints both scores, and [BOUNDARY.md](BOUNDARY.md) carries the block, the three outcomes and the options.
+
+```bash
+node <skill-scripts>/recommend.mjs recommend --json          # the top row, structured
+node <skill-scripts>/recommend.mjs recommend --why "<line>"  # the block to say
+```
+
+## Ordering rules
+
+- **Ranked by total, descending.** The total is rounded to one decimal *before* ranking, so the number a reader sees is the number the order was decided by.
+- **Ties break on rice, then scope, then id.** `ln` flattens, so different dependent counts can reach the same one-decimal total; a fixed tie-break means two runs over one backlog print byte-identical output. The scope breaks the tie before the id because two workspaces may hold the same bead id.
+- **Unscored beads never earn a rank.** They are listed, not placed, and never compared by title or by priority.
+
+## Workflow
+
+1. **Check the strategy is readable.** The queue compares each score's `strategyVersion` against the file to mark stale scores, and reads its deadline tiers. Run `strategy.mjs validate` first. A missing or invalid strategy does not stop the queue — the scores are already on the beads — but the header then reports `strategy unknown`, no staleness, and the shipped deadline default.
+
+2. **Run the queue.** This is the hand-run form: no planner, no agent, one command.
+
+```bash
+node <skill-scripts>/queue.mjs queue
+```
+
+3. **Report it as printed**, then name the top item plainly: id, title, and what answering it unblocks. Do not group by priority, re-sort, or drop the unscored rows — the flat list is the answer.
+
+4. **Score what is unscored, one bead at a time.** Load `score-bead`, judge the four components against the strategy, and record the score. Re-run the queue; the bead takes its place.
+
+```bash
+node <skill-scripts>/queue.mjs queue --file <path> --include-ideas
+```
+
+| Option | Effect |
+|---|---|
+| `--scopes <path>` | Scope list. Default `.agent-cortex/scopes.json` from the repository root, then `~/.agent-cortex/scopes.json`, then the current workspace alone. |
+| `--shared` | Output that leaves this machine: personal scopes are not read, and the daily note is withheld. |
+| `--file <path>` | Strategy file. Default `.agent-cortex/working-docs/strategy.md`, relative to the repository root. |
+| `--include-ideas` | Rank `kind:idea` beads too. They are excluded by default — see below. |
+| `--cwd <dir>` | Directory the current workspace, its strategy path and `bd` resolve from. |
+| `--json` | Print the report as JSON, including each scope's status and the daily note, for a caller that needs to act on it. |
+
+`BD_PATH` pins the `bd` binary. Exit `0` means the queue was built, including a run that ranked nothing or skipped an unavailable scope; exit `1` means an internal failure, and exit `2` a malformed argument or a scope list that cannot be read. The script makes no writes: the tracker calls are `bd list` and `bd dep list`, nothing else, and a read-only scope receives no other call.
+
+## What the queue leaves out
+
+- **Ideas, by default.** `kind:idea` beads are HITL by convention but deliberately unshaped: a RICE score on an idea measures a guess about a guess, and the idea backlog is ranked by `flesh-out-idea` instead. An idea that outranks a ripe decision would send the owner into an interview they did not choose. The count is printed so nothing is dropped silently; `--include-ideas` ranks them when the backlog is what the owner is working.
+- **Deferred and closed beads.** A bead deferred into the future stays out of the queue until that date passes, and the count is printed; the queue never adds a second deferral concept. Finished work waits on nothing.
+
+## Red Flags
+
+- Red flag: writing to a scope the list did not mark writable, so personal work lands in a code workspace.
+- Red flag: reporting only the scopes that answered, so a missing workspace looks like an empty backlog — or inventing a daily note instead of quoting the strategy line.
+- Red flag: scoring a bead inside this skill, so the queue's order rests on an unreviewed number.
+- Red flag: ranking an unscored bead by its priority or its title, so the list looks complete and hides the gap.
+- Red flag: counting dependency paths instead of distinct beads, so a diamond inflates one row above its real value.
+- Red flag: re-sorting or grouping the flat list before reporting it, so the order the owner reads is not the order that was computed.
+- Red flag: hardcoding a deadline factor in the script, so the owner cannot tune the rise without a release.
+- Red flag: excluding ideas or deferrals without printing how many were excluded.
+
+## Verification checklist
+
+- [ ] The report is one flat list: ranked rows first, unscored rows last, no sections.
+- [ ] Every row is tagged with its scope, every unavailable scope is named with its reason, and the daily note above the list quotes the strategy line with its version and section.
+- [ ] Each row shows the rank, scope, id, total, the four components, all three multipliers, the title and what the answer unblocks.
+- [ ] A bead blocking three others ranks above an equal bead blocking none; an in-progress bead ranks above an equal not-started one.
+- [ ] A bead due in three days ranks above an otherwise identical bead with no due date; an overdue bead is flagged `OVERDUE` and carries the top tier of the table in force. Every row with a due date shows the due moment and the time left, only a ranked row shows a factor, and a changed tier moves the rank with no code change.
+- [ ] With no scores, the header says nothing can be ranked and every candidate is listed unscored with a reason.
+- [ ] Two identical runs printed byte-identical output, and the excluded idea and deferred counts were reported, or the header said there were none.
+- [ ] A session that had to decide said one block: the bead, its components, both multipliers, the unblocked beads and the quoted strategy line — or one stated condition with its next step.
+
+## See Also
+
+- [SCOPES.md](SCOPES.md) — the scope list: its file, its default, the writable rule and the privacy boundary.
+- [score-bead](../score-bead/SKILL.md) — owns the `rice` record this queue reads, and the band proposal.
+- [prioritise-work](../prioritise-work/SKILL.md) — owns the strategy file and its version.
+- [bd-tool](../../productivity/bd-tool/SKILL.md) — the tracker commands, and where operational state lives.
+- [hitl-collab](../hitl-collab/SKILL.md) — the handoff document for a decision that needs more than an answer.