@jaybeeuu/agent-cortex 2.7.0 → 2.9.0

package/skills/style/style-tests/EXAMPLES.md

@@ -434,6 +434,36 @@ for (const item of cart.items) {
 expect(cart.items.map((item) => item.price)).toStrictEqual([10, 20, 30]);
 ```
 
+### A test name is a claim
+
+The name says what the test proves. Read it as a list of assertions and check that each one
+appears in the body. A clause with no assertion is a requirement the suite never enforces, so the
+test stays green while the behaviour breaks.
+
+```ts
+// ❌ Instead — the name claims one notice; the body only claims that something exists.
+// Remove the notice and this test still passes, because a list is always defined.
+it("sends one notice", async () => {
+  await publishAll(recipients);
+
+  expect(await notices.list()).toBeDefined();
+});
+
+// ✅ Write — the count in the name is asserted, so two notices and no notices both fail
+it("sends one notice", async () => {
+  await publishAll(recipients);
+
+  expect(await notices.list()).toHaveLength(1);
+});
+```
+
+A state in the name works the same way — "returns the cached user" needs an assertion that the
+returned user came from the cache, not that a user came back — and a "not" needs an assertion of
+the absence, such as a call count of zero.
+
+The *Workflow* mutation check catches this at run time: disable the behaviour and the bad form
+above stays green, while the good form goes red.
+
 ## Determinism and async
 
 ```ts

package/skills/style/style-tests/SKILL.md

@@ -25,6 +25,7 @@ description: Defines test-writing conventions — assertion strategy, mock disci
 - **Integration and e2e exercise real services.** Run the genuine collaborator — Postgres, Redis, a queue, object storage via TestContainers or LocalStack — never a fake that drifts from the real contract. Reserve e2e for a small number of smoke tests proving the system hangs together.
 - **No more tests than needed.** Every test earns its cost by pinpointing exactly where a failure lies. A test that cannot localise a fault adds maintenance weight without signal.
 - **One behaviour per test.** A test should fail for exactly one reason; several unrelated assertions turn a failure into a debugging exercise.
+- **A test's name is a claim, and every clause of it is an assertion.** A count in the name — "one notice", "both callers", "no retries" — asserts that count; a state in the name asserts that state; a "not" in the name asserts the absence. A name that outruns its assertions states a requirement the test never proves, so the test cannot fail for the reason its name promises. See _Red Flags_, and the "one notice" pair under _A test name is a claim_ in `EXAMPLES.md`.
 - **Test code is production code.** Linted, typechecked, properly typed — no `any`, no unsafe casts, no shortcuts in constructing data. Tolerate WETness where it leaves tests more descriptive.
 - **All setup and assertion data is visible inline.** Show exactly and only the values that explain the case; a helper with sensible defaults keeps it terse.
 - **Deterministic and performant.** A failing or flaky test is investigated now. Deferring is acceptable only against a top-priority bead.
@@ -71,7 +72,9 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 
 5. **Write targeted assertions.** Prefer `toMatchObject` over asserting every property. Multiple assertions are fine when they all verify the same behaviour. Avoid asserting call counts when asserting call arguments already covers the behaviour. Assert behaviour the file participates in, never its static contents.
 
-6. **Review against the checklist below.** Read the test as if you are seeing the codebase for the first time.
+6. **Run the mutation check.** Before you finish, disable or revert each behaviour a test claims, then run the suite. Every test named for that behaviour must fail. A named test that still passes proves nothing about its name: it is the _Red Flags_ row on empty implementations, applied to the whole name. Restore the behaviour and confirm the suite is green again.
+
+7. **Review against the checklist below.** Read the test as if you are seeing the codebase for the first time.
 
 ## Red Flags
 
@@ -80,7 +83,8 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 | Asserting static file content — an expected config/markdown/terraform string, or a snapshot of static content | Assert the behaviour the file participates in: data inserted into a template, a header compiled correctly, a deployed service ready to serve traffic |
 | Shared mutable top-level fixture reused across tests | Build fresh data per test via a factory; a module-scope constant only when genuinely immutable and read-only |
 | Repeated full literals for the same shape | A small configurable factory taking partial overrides with sensible defaults |
-| A test with no assertion, or one that cannot fail (`expect(result).toBeDefined()`) | Assert the observable contract — a specific value the code must produce |
+| A test with no assertion, or one that passes against an empty implementation (`expect(result).toBeDefined()`) | Assert the observable contract — a specific value the code must produce |
+| A test name whose claim no assertion mentions — "one notice" proven only by `toBeDefined()`, a count proven by truthiness | Assert every clause of the name: the count (`toHaveLength(1)`), the state, the absence |
 | Computing the expected value with the implementation's own logic | Hard-code the expected value from a known-good case; the test must not share the implementation's bug |
 | Mocking implementation details or internal module structure | Mock the genuine external boundary and test through the public interface |
 | An "integration" test that mocks the collaborator it is meant to integrate with | Run the real collaborator (TestContainers/LocalStack); a fake drifts from the real contract |
@@ -115,9 +119,8 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 
 ## Examples
 
-The full `❌ Instead` / `✅ Write` catalogue lives in `EXAMPLES.md`: behaviour over
-implementation, test data, mocking, integration and e2e, targeted assertions, structure and
-naming, determinism and async, isolation, and content assertions. Headline pairs:
+The full `❌ Instead` / `✅ Write` catalogue lives in `EXAMPLES.md` — including _A test name is a
+claim_, with the "one notice" pair. Headline pairs:
 
 | Instead of… | Write… |
 |---|---|
@@ -131,7 +134,8 @@ naming, determinism and async, isolation, and content assertions. Headline pairs
 - [ ] Test verifies behaviour, not implementation structure
 - [ ] Integration tests exercise the real collaborator — no mocking the engine you are integrating with
 - [ ] E2E smoke tests prove wiring, migrations, and the journey — not business rules covered lower down
-- [ ] Each test fails for exactly one reason, and its name states the behaviour
+- [ ] Each test fails for exactly one reason, and its name states only behaviour an assertion proves — count, state, and absence included
+- [ ] Mutation check run: each claimed behaviour was disabled, its named tests failed, and the suite is green again
 - [ ] No mocking of internal module details — only public interfaces
 - [ ] No `before`/`after` hooks for shared test state (infrastructure setup only)
 - [ ] Assertions are targeted — no over-asserting, no tautologies, no assertion-free tests

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

@@ -0,0 +1,134 @@
+---
+name: hitl-queue
+description: Ranks the open execution:hitl beads into one list ordered by RICE, transitively blocked dependents and work in progress, and prints what each answer unblocks. Use when deciding which human decision to answer next, when a planning session starts, or when asked "what needs my decision", "show the queue" or "what should I answer first".
+---
+
+# HITL Queue
+
+Owns one output: **the ranked list of beads waiting for a human answer**. 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?".
+- 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)
+```
+
+| 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. |
+
+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. 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.** A related or duplicate edge is not something anyone waits on.
+- **The walk passes through every bead; it counts only live ones.** A closed bead is still a link in the chain, so the walk continues past it, but finished work cannot be unblocked, so a closed dependent is not counted.
+
+`1 + ln(1 + n)` is logarithmic on purpose: unblocking thirty chores must not drown the list under one row. Zero dependents scores `1`, so a bead that unblocks nothing is not penalised — it is simply not lifted.
+
+## The report
+
+One flat list, no sections, ranked first and unscored last:
+
+```
+HITL decision queue · 2 ranked, 2 unscored · strategy v2
+total = rice × (1 + ln(1 + dependents)) × 1.5 in-progress · ties break on rice, then id · unscored last
+excluded: 3 kind:idea beads (--include-ideas ranks them)
+
+1  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  bd-2        6.3  rice 4.2 = R4 · I3 · C0.7 · E2  ×1.00 dependents(0)  ×1.5 in-progress
+    Decide the API shape — unblocks nothing
+-  bd-4          —  unscored — no rice metadata (score it with score-bead)
+    Decide the vendor — unblocks nothing
+```
+
+Every row carries its rank, id, total, the four components the score was computed from, both multipliers, the title, and one clause naming what the answer unblocks. 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 v1, current v2`).
+
+`--json` prints the same answer with every derived field, for a caller that needs to act on it.
+
+## 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 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.
+- **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. A missing or invalid strategy does not stop the run — the scores are already on the beads — but the header then reports `strategy unknown` and no staleness.
+
+```bash
+node <skill-scripts>/../../prioritise-work/scripts/strategy.mjs validate
+```
+
+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 --json     # the same answer, structured
+node <skill-scripts>/queue.mjs queue --file <path> --include-ideas
+```
+
+| Option | Effect |
+|---|---|
+| `--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 strategy path and `bd` resolve from. |
+| `--json` | Print the report as JSON. |
+
+`BD_PATH` pins the `bd` binary. Exit `0` means the queue was built, including a run that ranked nothing. Exit `1` means a `bd` call failed, and exit `2` means a malformed argument. The script makes no writes: the tracker calls are `bd list` and `bd dep list`, nothing else.
+
+## 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 beads.** A deferral is itself an answer, so a parked bead stays out of the queue until the owner lifts it (`bd update <id> --status open`). The count is printed.
+- **Closed beads.** Finished work waits on nothing.
+
+## Red Flags
+
+- 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: excluding ideas without printing how many were excluded.
+
+## Verification checklist
+
+- [ ] The report is one flat list: ranked rows first, unscored rows last, no sections.
+- [ ] Each row shows the rank, id, total, the four components, both 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.
+- [ ] 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.
+- [ ] The excluded idea and deferred counts were reported, or the header said there were none.
+
+## See Also
+
+- [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.