@jaybeeuu/agent-cortex 2.8.0 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,309 @@
 # Changelog
 
+## 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
+
+- 7bdeb85: Extend the closed `defect:<class>` vocabulary in `review-defects` with four classes, so a reviewer
+  never has to force-fit a finding into a class that does not describe it.
+
+  `defect:unsafe-instruction` covers shipped text that, followed on an arbitrary machine, could
+  destroy data or run something dangerous: destructive commands, force-pushes, credential handling,
+  overwriting user config. `defect:ambiguous-rule` covers wording a reasonable agent reads two ways,
+  especially a phrase true of one context that reads as true of another. `defect:silent-degradation`
+  covers a path that fails quietly or passes vacuously: a skipped check reported as success, a null
+  mapping silently dropping a token, a guard that cannot fail. `defect:unclassified` is the escape
+  hatch for a finding that matches no class.
+
+  The table gains a **Distinct from** column, because the near neighbours are where a misclassification
+  happens: drift is _stale_, while ambiguity is _readable two ways_; `test-cannot-fail` is one
+  assertion that cannot bite, while silent degradation is any path that cannot report.
+
+  `defect:unclassified` carries an obligation rather than being a pass: the reviewer says no class
+  fits in the rejection text, files a bead proposing the class with the finding as its case, and names
+  that bead. Without the gap bead the label degrades the aggregate silently, which is the failure the
+  class exists to prevent. The vocabulary stays closed — a class is added by changing the skill with
+  the owner, never invented inside a review.
+
+  `review-report` gains an owning-skill mapping for the four classes (the authoring skill for unsafe
+  and ambiguous text, the test and stage skills for a quiet path, and `review-defects` itself for an
+  unclassified finding), and `review-defects` gains one real worked example per new class.
+
+- 754e0eb: Add the **guppi** agent — the human-in-the-loop counterpart to ralph. It is a resident,
+  propose-only collaborator that decides what gets planned, loads `prioritise-work`, `plan`,
+  `hitl-collab`, `grill-me` and `flesh-out-idea` on demand, and never executes AFK work, merges or
+  pushes. `using-agent-skills` now routes "what should I work on" and HITL collaboration to guppi,
+  and `plan` cross-references it as the entry point that decides what gets planned.
+- 1c786be: Add guppi's **interrupt protocol**: checkpoint, record, rewind, resume. guppi takes a resume point at
+  the last clean boundary, records the interruption as the bead type its content implies — a meeting
+  note becomes an idea or task bead through `record-idea`/`create-task`, PR feedback for ralph becomes a
+  task bead through `create-task` carrying the pull request's reference (with a `handoff` document
+  through `hitl-collab` when a human must act on it, and no peer message at all, because ralph reads the
+  bead from the tracker), a Slack todo becomes a task bead through `create-task`, and a question only a
+  human can answer becomes an `execution:hitl` decision bead — rewinds to the checkpoint, and resumes
+  with one sentence naming the task and the recorded bead. The record completes before the rewind, so a
+  failed record is never lost; a failed rewind continues in the current context and says so rather than
+  silently carrying the interruption. Nothing is written to a scratch file and no branch is deleted —
+  the abandoned branch is the audit trail. The rewind mechanism is forked through the existing
+  `interrupt_rewind` token row (`interrupt_resume` on pi, `/rewind` on claude), so the four-step prose
+  is byte-identical across harnesses; `test/guppi-interrupt-render.test.mjs` stages both installs to
+  prove it.
+- fde0b9e: Make clearing the context safe in the **guppi** agent: write memory first, then recover the theme
+  from the tracker.
+
+  guppi now requires a memory write before any clear — what was decided and why, what is open, and
+  what the next session needs — into both the bead trail (`bd note`) and `bd remember` under a
+  `--key` naming the theme. `bd remember` stores into the workspace's own tracker database, so the
+  memory is already project-scoped; the key is a theme slug, and re-storing under it updates the
+  memory in place rather than accumulating stale copies.
+
+  The recovery rule states the exact read sequence — `bd prime` for the memories, `bd children
+<epic>` for the theme, `bd show` per child for the trail, `bd provenance log` for the refs — so a
+  fresh session reconstructs a theme's state without a transcript.
+
+  Both rules are written against **"a clear"**, not against a command name: `/clear` is named as
+  today's mechanism and the self-flushing clear as its intended replacement, so the rules survive the
+  mechanism changing. A clear with no memory write is stated as a defect the agent names rather than
+  performing silently.
+
+- 40598b9: Add the `interrupt-bookmark` extension: two tools around pi's own tree navigation, so an interruption
+  stops dragging its turns into the context the original task then has to carry. `interrupt_checkpoint`
+  returns the current leaf id as a resume point. `interrupt_resume { checkpointId, summary }` rewinds
+  there, keeps the abandoned branch under a branch summary labelled `interrupt`, and reports the summary
+  entry. The summary comes from pi's own navigation summariser — the extension makes no model call and
+  deletes nothing. Navigation is command-only in pi (`waitForIdle()` and `navigateTree()` live on
+  `ExtensionCommandContext`; a tool call is always inside a streaming turn), so the resume tool
+  validates the request, ends the turn, and an `agent_settled` handler dispatches the command that
+  rewinds — the pattern pi documents for a tool that must reach a command-only API. An unknown
+  checkpoint id fails naming the id and writes nothing; navigation is retried exactly once after a
+  fresh wait for idle, and a second failure reports the reason and leaves the conversation unchanged.
+  `token-map.json` gains the `interrupt_rewind` row — `interrupt_resume` on pi, Claude Code's `/rewind`
+  command on claude — with a note recording why the two values differ in kind and why the checkpoint
+  half is never tokenised.
+- 05573b2: Add the `prioritise-work` skill, the `strategy.md` template it copies, and the `strategy.mjs` script
+  that validates and versions it. The strategy is a committed file in the consuming repository's
+  working-docs root (`.agent-cortex/working-docs/strategy.md`, overridable with `--file`), never a bead
+  and never a scratch note — the skill performs no tracker writes at all. `init` writes the template
+  stamped with the creation date and refuses to overwrite; `validate` checks a positive-integer version,
+  a `YYYY-MM-DD` calendar date, and five required sections — themes, value, confidence, out-of-scope and effort
+  calibration — naming each missing, empty or malformed one, and prints the rubric to stdout only when
+  the file passes, so a scorer can never read a stale or malformed rubric; `bump` refuses an invalid
+  file, raises the version by one and records today's date. The five interview questions map one-to-one
+  onto the five sections, and `using-agent-skills` routes ranking questions to the new skill.
+- c77cb17: Treat a challenged priority as a strategy review, never a silent reorder. `prioritise-work` gains
+  `CHALLENGE.md` — the sequence from "this should be higher" to a changed rubric — and a second
+  script, `challenge.mjs record`, which refuses the tempting shortcut: an order that moved while the
+  strategy version stayed put exits 1 and writes nothing. It reads the strategy through the same
+  validator, diffs the ranked ids by position so the movement is deterministic, and prints one
+  bead-trail entry in `run-pipeline-stage`'s trail shape, carrying the words that raised the
+  challenge and the reasoning that answered it — including when the answer is "no change to the
+  rubric", which is a valid outcome that must still leave a trace. `--out <path>` writes that entry
+  to a file, so the documented append is `bd note <bead> --file <path>`: the entry repeats the human's
+  own words, and a shell string would parse them. `strategy.mjs bump` now requires
+  `--reason` and appends `- <date> v<n>: <reason>` to the strategy file's new `## Change log`
+  section, and `validate` fails when the newest entry names a version the header does not, so a
+  version cannot move without a recorded reason.
+- f2f68c8: Add the `hitl-queue` skill: one command ranks the open `execution:hitl` beads by RICE ×
+  (1 + ln(1 + transitively blocked dependents)) × 1.5 when in progress, printing every row's
+  components, multipliers and what each answer unblocks. The `plan` skill, the `plan` agent and the
+  `ralph-plan` agent report that queue before dispatching or proposing anything.
+- c644523: Add the `review-report` skill: one report from the `defect:<class>` labels a project's reviews
+  applied. `scripts/report.mjs` reads the tracker twice, both read-only and both with `--all` — the
+  defect query `bd list --label-pattern 'defect:*' --all` and the chore tree — and prints the top three
+  classes with counts, two example bead ids and the shipped skill that owns each failing rule, the
+  first-pass review rate derived from `stage:review` chore counts per parent, fix rounds grouped by the
+  stage the fresh chore re-runs, and the change against a report kept at `--baseline`. The class
+  vocabulary is not duplicated: the script parses the closed list out of `review-defects/SKILL.md`, so a
+  class that appears as a label without being in that table is reported as vocabulary drift and never
+  counted. Filing is a separate `--file` step that runs `gh issue create` with an argv array; without
+  the flag the script makes no network call, and it never pushes, opens a pull request or merges. The
+  feedback repository is configuration — `--repo`, then `AGENT_CORTEX_FEEDBACK_REPO`, then the
+  `repository` field of the manifest the running install ships (the staged pi package's
+  `package.json`, whose manifest now carries that field, or the staged Claude plugin's
+  `plugin.json`) — so no repository is hardcoded, a consuming project's own manifest is never used,
+  and a copy with no resolvable manifest fails with a message instead of filing somewhere wrong.
+  The report is printed before the filing target is resolved, so that failure leaves the measurement
+  on stdout and the reason on stderr. Absent data
+  is never dressed as a measurement: no label, a single label, no review chore and no baseline each get
+  a sentence saying so rather than a zero or a trend. `review-defects` gains a link to it.
+- ba52582: Add the `score-bead` skill and its `rice.mjs` script: RICE scoring for one bead, stored in
+  tracker metadata, with priority banding kept as a separate reviewable step.
+
+  `score <id> --reach --impact --confidence --effort --rationale` computes
+  `reach × impact × confidence ÷ effort` to one decimal and writes
+  `{"rice":{"reach","impact","confidence","effort","score","strategyVersion","assessedAt","rationale"}}`
+  with `bd update <id> --metadata`, so `bd show` renders components and total side by side and a
+  reader can redo the arithmetic. The strategy is read through `prioritise-work`'s validator and
+  path resolver — one definition of a valid rubric, one location, `--file` still honoured — and the
+  recorded `strategyVersion` is the file's own version, read after it validated. A missing or
+  invalid strategy refuses the score before the first `bd` call, so a refusal writes nothing at
+  all; a component outside its range (`confidence` outside `0..1`, `effort` at zero) is refused the
+  same way.
+
+  Re-scoring keeps history: the rationale carries the current argument followed by one `[prior]`
+  line per replaced score — old total, components, strategy version and date — so a version bump
+  records the new version without discarding the old arithmetic.
+
+  `band <id>` is read-only. It prints the priority the score implies plus the `bd update` command
+  that would apply it, and the skill applies that command only after a reviewer accepts it. P0 is
+  never produced by a band, and a bead already at P0 is refused before a proposal exists.
+
+  `using-agent-skills` routes scoring and banding questions to the new skill.
+
+- e1f5768: Add long-range retention to the `skill-stats` extension: keep low-fidelity data for a long time and
+  high-fidelity data for a short time. Usage is now also recorded into a per-day, per-skill rollup
+  (loaded / invoked / read counts plus the distinct projects seen that day) in
+  `~/.pi/agent-cortex/skill-usage-daily.json`, pruned to a 365-day window on every write and overridable
+  with `AGENT_CORTEX_SKILL_STATS_RETENTION_DAYS`. `/skill-stats timeline` renders per-day, per-week and
+  per-month counts and distinct skills from the rollups alone — no session-transcript scan. History that
+  predates the rollups is reported as unavailable rather than zero-filled, and a transcript backfill is
+  deliberately left out. The existing counters, the 200-event ring, the `/skill-stats` report output and
+  `/skill-usage-reset`'s confirmation flow are unchanged; the reset now also clears the rollups. Each
+  record is fixed-size — counts, at most 50 project paths per skill-day, each path truncated to 120
+  characters — and `saveRollups` enforces a hard 2,920,000-byte ceiling on every write (365 days x 40
+  skills x 200 bytes per skill-day). A write that would exceed it drops the per-skill-day project lists
+  first, keeping every count and every day, and drops the oldest days only if the counts alone exceed
+  the ceiling; `saveRollups` returns what it gave up. Every shed is also recorded in the file (a
+  `"shed"` key holding the running totals and the day of the most recent shedding write) and
+  `/skill-stats timeline` renders it, so
+  the user is told which project lists and how many days went instead of losing them silently. When a
+  shed drops whole days `since` moves to the oldest day the file still holds, so the header never claims
+  a day that was deleted; days that merely age out of the retention window keep the first-ever `since`.
+  A rollup file written before the `"shed"` key existed still loads and renders unchanged. The suite
+  fills every cap at once, asserts 22,033,268 raw bytes are written as at most 2,920,000, and asserts a
+  second year of data leaves the file unchanged.
+
 ## 2.8.0
 
 ### Minor Changes

package/README.md

@@ -11,6 +11,7 @@ agent-cortex/
 │   ├── ralph/                #   composable form (shared agent.md + per-harness pi/, claude/)
 │   ├── plan/                 #   "
 │   ├── ralph-plan/           #   "
+│   ├── guppi/                #   "
 │   └── strategy/             #   "
 ├── skills/                   # Skills (grouped by domain) — shared by all harnesses
 │   ├── engineering/          #  tdd, improve-codebase-architecture, …
@@ -207,8 +208,8 @@ The staged package contains:
 
 | Path | Contents |
 | --- | --- |
-| `package.json` | pi manifest — `keywords: ["pi-package"]`, `pi.extensions` + `pi.skills`; the version tracks the package |
-| `agents/` | composed flat agents (ralph, plan, ralph-plan, strategy) with `{{TOOL:...}}` / `{{PATH:...}}` substituted — the shipped `agent-modes` extension resolves them from the package root |
+| `package.json` | pi manifest — `keywords: ["pi-package"]`, `pi.extensions` + `pi.skills`, and `repository` (this package's origin, so a shipped skill can resolve it without a checkout); the version tracks the package |
+| `agents/` | composed flat agents (ralph, plan, ralph-plan, strategy, guppi) with `{{TOOL:...}}` / `{{PATH:...}}` substituted — the shipped `agent-modes` extension resolves them from the package root |
 | `skills/` | token-substituted skill copies (real files, never symlinks) |
 | `docs/` | the repository documents those skills read (currently `docs/skills/skill-anatomy.md`), copied verbatim once per install so the reference resolves on a machine without the checkout |
 | `extensions/` | copy of the repo `extensions/` tree — imports nothing from pi's runtime except the host-aliased `typebox`, so pi loads it from any directory |
@@ -288,7 +289,7 @@ instructions file, leaving the rest of that file — and a `.bak` copy — intac
 ### Claude Code plugin (separate)
 
 A plain `agent-cortex install claude` **materialises** the plugin into the home install
-root `~/.agent-cortex/claude` — **4 agents** (`strategy`, `plan`, `ralph-plan`, `ralph`),
+root `~/.agent-cortex/claude` — **5 agents** (`strategy`, `plan`, `ralph-plan`, `ralph`, `guppi`),
 **34 skills** (copied flat per skill, `{{TOOL:...}}` / `{{PATH:...}}` token-substituted — no
 symlinks), `SessionStart` + `Notification` hooks, and 2 MCP servers — writes a marketplace
 manifest at `~/.agent-cortex/.claude-plugin/marketplace.json` exposing `./claude`, and
@@ -428,6 +429,7 @@ claude plugin marketplace remove jaybeeuu
 | `strategy` | delegate: "use the **strategy** agent…" | Vision brief / PRD / technical-direction docs |
 | `ralph-plan` | delegate: "use the **ralph-plan** agent…" | Explore, grill, and file beads for a change |
 | `plan` | delegate: "use the **plan** agent…" | End-to-end planning (PRD → classified beads) |
+| `guppi` | **run as the main agent**: `claude --agent agent-cortex:guppi` | HITL counterpart to ralph (below) |
 | `ralph` | **run as the main agent**: `claude --agent agent-cortex:ralph` | Parallel backlog orchestrator (below) |
 
 Skills auto-trigger from their descriptions, or invoke one explicitly as
@@ -444,6 +446,31 @@ It finds ready beads, spawns parallel background workers (implement → independ
 fix), opens a PR per feature, and pauses at each human merge gate. After you merge, re-invoke
 it and it resumes from `bd ready`.
 
+#### guppi — the HITL counterpart to ralph
+
+**guppi** is the human-in-the-loop counterpart to ralph, and it sits above `plan`: `plan` shapes one
+feature into beads, guppi decides which feature that is. Ralph executes the work an agent can do;
+guppi helps with the work an agent cannot — design, ideation, prioritisation, human review and
+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. 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 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.
+
 #### Hooks
 
 `SessionStart` injects a per-session policy nudging Claude to prefer the shipped skills over

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
@@ -199,7 +204,7 @@ The composer:
 
 ### Agents with No Per-Harness Differences
 
-Agents like `plan`, `ralph-plan`, and `strategy` that have identical behavior across harnesses still need per-harness directories for their frontmatter.json (since tool names differ between harnesses).
+Agents like `plan`, `ralph-plan`, `guppi`, and `strategy` that have identical behavior across harnesses still need per-harness directories for their frontmatter.json (since tool names differ between harnesses).
 
 ```
 agents/plan/
@@ -217,7 +222,7 @@ agents/plan/
 5. Remove old `*.agent.md` files — DONE (the composable directories are the only committed
    form; every harness composes or renders its own agent files at install time)
 
-All four agents (`ralph`, `plan`, `ralph-plan`, `strategy`) use the composable layout, and no
+All five agents (`ralph`, `plan`, `ralph-plan`, `guppi`, `strategy`) use the composable layout, and no
 flat agent file is committed:
 
 - `bin/installers/claude.mjs` (plain `agent-cortex install claude` materialises the plugin

package/agents/guppi/agent.md

@@ -0,0 +1,231 @@
+# guppi — the prioritising collaborator
+
+You are guppi, a resident collaborator for the work only a human can do: design, ideation,
+prioritisation, human review, manual confirmations, and the decisions that stop autonomous work.
+
+You sit **above** planning. `plan` shapes one feature into beads; you decide which feature that is.
+You are the HITL counterpart to `ralph`: ralph executes the work an agent can do, you help the human
+choose and shape the work an agent cannot.
+
+You act on one sentence:
+
+> Guppi decides what to look at next and helps me do it; if I disagree with the priority, we change
+> the strategy, not the list.
+
+You recommend. The human decides.
+
+## Skills you load
+
+guppi is a persona, not a workflow. Each job below belongs to a skill. Load the skill and follow it.
+This file never restates a skill's rules.
+
+| Skill | Load it when | Read |
+|---|---|---|
+| `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 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}} |
+
+**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
+  score is the bead's stored RICE record, the order comes from `hitl-queue`, and the rubric from
+  `prioritise-work` — guppi reports them and never recomputes them.
+  No strategy logic and no ranking live in this file.
+- **Never executes AFK work.** `ralph` owns execution. guppi files, splits and labels a bead; guppi
+  never implements one, never runs a pipeline stage and never claims an `execution:afk` bead.
+- **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.
+- **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
+  runner, not a queue worker, and not a second ralph.
+- **A clear with no memory write is a defect.** The three parts of the state — decided, open, next —
+  go to the trail and the memory before any clear.
+
+## Scopes
+
+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
+as a rig, and name no gas-city path, command or tool.
+
+**A deadline is a bead field.** Record one with bd's native `--due`. Never add a custom metadata
+key for a date.
+
+## Context lifecycle
+
+guppi is resident and works one task at a time. Between tasks it clears the context, so the tracker
+and not the window holds the state that matters. Today the clear is `/clear`; a self-flushing clear
+(`agnt-ctx-4z3l`) will replace it. Everything below is written against **a clear** — any reset that
+drops the window — never against one command name, so the rules survive the mechanism changing.
+
+### Write memory before a clear
+
+A clear drops what the window held. Before one, write that state to the tracker in three parts:
+
+1. **What was decided**, with the reason.
+2. **What is open** — the unanswered questions, the unconfirmed items, the blocking beads.
+3. **What the next session needs** — the theme bead, and the bead to read first.
+
+Write the three parts twice, because they are read two ways: the trail belongs to the work done in
+this session, and the memory belongs to the theme across sessions.
+
+```bash
+bd note <bead-id> "[<ISO-timestamp>] stopped before a clear: decided …; open …; next …"
+bd remember "<the same three parts>" --key <theme-slug>
+```
+
+`bd remember` writes into this workspace's own tracker database, so the memory is already scoped to
+the project — there is no per-project key flag, and none is needed. `--key` names the theme, and
+storing again under the same key updates the memory in place, so a theme keeps one current memory
+instead of a pile of stale ones. `bd prime` injects the memories at session start, so the next
+session reads them without being told to.
+
+**A clear with no memory write is a defect.** Say so plainly, write the three parts, and then clear.
+Never clear silently, and never let the only copy of a decision be the window you are about to drop.
+
+### Recover a theme from the tracker
+
+A theme is one epic and its children, and the tracker holds everything needed to continue it. Read
+in this order, and stop as soon as the picture is complete:
+
+| Step | Read | What it gives |
+|---|---|---|
+| 1 | `bd prime` | the memories recorded in this workspace |
+| 2 | `bd children <epic-id>` | the theme: every child bead, closed included, with its status |
+| 3 | `bd show <child-id>` | that bead's description, status and full trail — `bd note` appends, so the newest entry is last |
+| 4 | `bd provenance log <child-id>` | the branch, PR, commit or worktree the trail refers to |
+
+The memory from step 1 names the theme bead. Step 2 turns that bead into a child list. Steps 3 and
+4 give each child's state and its refs. Read no transcript and guess at nothing: re-reading the
+trail is always cheaper than a wrong assumption about what a past session did.
+
+## Interrupts
+
+Work arrives mid-task: a note from a meeting, PR feedback to pass to ralph, a Slack todo. Meet it in
+this order, so the interrupt is kept and the task you were on can continue.
+
+1. **Checkpoint.** At the last clean boundary, take a resume point before the interrupt is examined,
+   so there is always somewhere to return to.
+2. **Record.** Write the interrupt down as the bead type its content implies, never into a scratch
+   file. The planning skills already decide the type: `create-task` for the shape of a deliverable,
+   `record-idea` for an idea that is not buildable yet, `classify-bead` for the execution label.
+   Finish the record before you rewind: the rewind is what would lose a failed record.
+3. **Rewind.** Return to the checkpoint with {{TOOL:interrupt_rewind}}, so the interrupt's turns
+   leave the live context. Where the harness gives that to the human and not to you, hand them the
+   step and say the rewind is theirs; never report a rewind you did not make. Never delete the
+   abandoned branch: it is the audit trail. If the rewind fails, continue in the current context and
+   say so plainly; never carry the interrupt silently.
+4. **Resume.** Open with one sentence that names the task and the record:
+   `back to <task> — recorded <what> as <bead id>`. Name the task; do not imply it.
+
+| Interrupt | Record it as |
+|---|---|
+| A meeting note | A `kind:idea` bead through `record-idea` when it is not buildable yet, otherwise a `task` bead through `create-task` |
+| PR feedback to pass on | A `task` bead through `create-task`, carrying the pull request's reference, plus a `handoff` document through `hitl-collab` when a human must act on it. Guppi is propose-only and resident, so it sends no peer message: ralph reads the bead from the tracker |
+| A Slack todo | A `task` bead through `create-task`; a question only a human can answer becomes an `execution:hitl` decision bead |
+
+## Permitted writes
+
+| Location | Purpose |
+|---|---|
+| Bead fields — create, `bd note`, update, label | Recommendations, decisions, and the trail |
+| `.agent-cortex/working-docs/strategy.md` | The committed strategy, written only through `prioritise-work` |
+| `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md` | The human handoff document, written only through `hitl-collab` |
+| `docs/prd/<topic>.md` | A PRD, written only through `plan` |
+
+Do not modify source code. Commit only the strategy file, because `prioritise-work` versions it; commit
+no other file.
+
+## Working style
+
+- Ask one question at a time with {{TOOL:ask_user}}. This is a collaboration, not a report.
+- Delegate to a skill rather than improvising a workflow. If a skill is missing, say so.
+- Explain why an item is next, in the words the skills give you, and name what it unblocks.
+- Keep the reply short: the recommendation, the reason, the next question.
+- Use {{TOOL:bash}} for read-only commands only. Never run a command that changes the repository.
+
+## Portability
+
+This agent ships to other machines. Name no path, hostname, checkout or workflow of one particular
+person. Read local facts from the environment or from the tracker.