@jaybeeuu/agent-cortex 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,417 @@
 # Changelog
 
+## 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
+
+- 683808c: State the bead-state rule in `bd-tool` and `AGENTS.md`: operational state (progress, what a stage
+  learned, the decisions taken, branch/PR/commit/worktree refs) lives in bead fields, while durable
+  committable documents stay files, and `handoff.md` plus the working-docs artefact directory are
+  unchanged. The built-in statuses carry the working state — `bd statuses` lists all seven, so no
+  state label is added. What happened goes in the trail with `bd note`, which appends. The text names
+  `stage=` as forbidden for state, with the reason: `bd set-state` removes the existing label for the
+  dimension it sets, so it would rewrite a chore's route. Ship this in the same release as the
+  removal of the `ralph-*.log` and `progress.md` writer sites (`agnt-ctx-ul91.1`): a published
+  version that states the rule while a skill still writes progress files would contradict itself.
+- 87ebb46: Give the pipeline one shared writer for the bead trail, and stop the file-based progress logs.
+
+  `skills/workflow/run-pipeline-stage/scripts/trail-entry.mjs` appends one checkpoint to a bead's
+  notes with `bd note` and records the refs the caller names as provenance events. Every entry
+  carries the three mandatory fields — Outcome (`done`/`blocked`/`partial`), Evidence (a test or lint
+  result, the commit, command output), and What is left — so a fresh session resumes from
+  `bd show <id>` alone.
+
+  A `--commit` ref is resolved through `git rev-parse` to the full 40-character lowercase SHA before
+  recording, because `bd provenance record --ref-kind git-sha` refuses an abbreviated one; a ref that
+  does not resolve records nothing. Transient database failures — `failed to open database ...
+context canceled`, the shape two concurrent writers produce on embeddeddolt — are retried with
+  bounded backoff, each retry re-reads the bead first so a write that landed before its call reported
+  failure is never duplicated, and no call holds the database across a long operation. Recording is
+  idempotent for one writer: the entry carries a fingerprint of its own content, so a repeated fire
+  appends nothing. Two concurrent fires of one transition can each append — `bd note` has no
+  conditional append — so the pipeline fires each transition from one worker.
+
+  `run-pipeline-stage` and `ralph` now call that script at every stage transition, and no shipped
+  skill, agent, or stage template writes a per-parent log file or a rendered progress view any more.
+  Ralph's log polling, its `state.json` `logLine` bookmark, and both wake sections' log-flush
+  procedure go with them: progress is read from the bead (`bd show`, `bd provenance log`), which is
+  the record the worker writes directly.
+
+- 4e1bcc5: Add `implement-task`, the skill that owns the task around the loop: criteria, scope, and proof.
+
+  `tdd` owns the red-green loop and the `style-*` skills own the standards, but nothing owned the task
+  — reading the acceptance criteria, proving each one, staying in scope, and taking only pragmatic
+  boy-scout fixes. `implement-task` fills that gap with four load-bearing sections: the criteria →
+  evidence table, written before code and filled with observable evidence at Finish; the scope rule,
+  where an out-of-scope finding becomes a bead instead of an edit; the boy-scout rule, which allows a
+  fix only inside a file the task already touches and only where it serves the task; and the mutation
+  check, inherited from `style-tests` and applied to every test that claims a behaviour. A criterion
+  with no named check is a blocker, not a guess.
+
+  The `code` stage playbook now invokes `implement-task` as its first step and routes through it to
+  `tdd` and the style skills, `tdd` links to it for criteria and scope rather than carrying those
+  rules itself, and `using-agent-skills` routes a task-implementation request to it while leaving a
+  bare "write a test for X" on `tdd`.
+
+- 27b513b: Fork the planner ↔ ralph peer channel per harness instead of describing it as PI-only. The channel
+  now renders through `token-map.json`: `{{TOOL:peer_send}}` and `{{TOOL:peer_list}}` become
+  `peer_send` and `peer_list` in a pi install, and Claude Code's built-in `SendMessage` and
+  `ListAgents` in a claude install. Both harnesses carry the same seven message kinds and the same
+  acknowledgement rule — the kinds table and the reply rule are byte-identical between the two
+  renders, and only the `### Transport` subsection differs.
+
+  Claude Code's cross-session messaging is built in from v2.1.224 (v2.1.234 on native Windows):
+  `ListAgents` returns the peers a session can reach with the address of each, and `SendMessage`
+  delivers to that address, so a named peer session is addressable and no manual-handoff-only fork is
+  needed. `pi-peer`'s `peer_get` and `peer_await` have no Claude Code counterpart, so they are named
+  only inside the harness-labelled `pi-peer` runbook: a null mapping would drop the token and leave
+  the sentence that named it broken.
+
+  `test/skill-transport-render.test.mjs` stages both installs and asserts the per-harness rendered
+  text, so a harness that loses its mechanism fails the suite rather than silently degrading.
+
+- 49b34d7: Document the planner ↔ ralph message convention on top of `@cryptolibertus/pi-peer`. The `ralph`
+  skill now publishes its peer identity at start (`PI_PEER_ID=ralph`), answers inbound `handoff`,
+  `get` and `ask` messages, and reports `update`/`done`/`blocked`/`failed` to the planner as work
+  dispatches, finishes, parks on a human gate or fails. The `plan` skill sends a `handoff` message
+  naming the handoff bead once it exists, treats ralph's `blocked` messages as its pending-human
+  surface, and keeps the manual instruction as the handoff path for a session with no reachable
+  receiver.
+
+  The shared convention — the kind-to-intent table, the acknowledgement rule, the two-entry
+  `.pi/peers.json` requirement and the one-way discovery failure a single entry causes, the
+  `.pi/peers.json` and `.pi/peer-*` paths to gitignore, and the rule to send through `peer_send` rather than typing into a
+  busy session — lives once in `skills/workflow/ralph/REFERENCE.md` and is cross-referenced from
+  `plan`. pi-peer keeps ownership of discovery, delivery, idle wake and the ledger; no registry,
+  inbox, watcher or transport is implemented here. The tools are named through `{{TOOL:...}}` tokens so
+  one skill text serves both harnesses; the per-harness fork is its own changeset.
+
+- 2610b78: Add the `post-merge` pipeline stage and the deterministic check it runs.
+  `skills/workflow/ralph/scripts/post-merge-check.mjs` reads `gh run list` for the base branch's merge
+  commit and exits `0` passed, `1` failed, `2` inconclusive — no model, no tokens, zero runtime
+  dependencies, async only. A failing run files exactly one P1 escalation bead carrying the run URL
+  and the failing job name; the `post-merge-run:<id>` marker in its description makes a second run
+  file nothing. It never retries, never re-runs the workflow, never reopens the parent, and is
+  GitHub-only in v1 (a repository `gh` cannot resolve to a GitHub host, or a commit with no run, is
+  inconclusive and files nothing). `create-chores.mjs` pre-creates the chore labelled
+  `lifecycle:post-merge`, blocked behind the `lifecycle:feature-pr` gate rather than behind a stage,
+  so it becomes ready only once a human merges and closes the gate; a re-run still creates nothing.
+  The script reads the repository slug and base branch from `gh repo view`, so no slug or branch is
+  baked in. `housekeeping` and `post-merge` are siblings on the gate and neither waits on the other,
+  because an inconclusive check must not strand the worktree reclamation.
+- 241ab8f: Add the `post-merge-watch` pi extension: poll the post-merge check and wake an idle session with
+  the verdict.
+
+  `pi --post-merge-watch <bead>` polls
+  `skills/workflow/ralph/scripts/post-merge-check.mjs` every 15 s (up to 40 checks) and, when the
+  script reports a verdict, sends one message with
+  `pi.sendMessage(..., { deliverAs: "followUp", triggerTurn: true })`, so a session that is idle
+  starts a turn with the result. The message names the bead, the verdict, the exit code, the reason,
+  the run URL, the project, and the number of checks; the same fields ride along as message
+  `details`.
+
+  The extension owns no verdict logic: the check's exit code is the verdict (`0` passed, `1` failed,
+  anything else inconclusive, including a timeout kill), and the run URL is forwarded from the
+  script's JSON report. It makes no model call, imports pi as types only, registers its CLI flag in
+  the extension factory, and spawns no process or writes no state when the flag is absent. Each
+  invocation passes `--wait 0`, so the poll interval and the bound live in the extension and a
+  stopped watch never blocks on a child process.
+
+  State lives under `~/.pi/agent-cortex/post-merge-watch/`, one file per project path and bead (the
+  name carries a digest of both, so two projects watching one bead never collide), and is removed
+  when the watch settles or the session shuts down. The pending timer is unref'd and cancelled on
+  shutdown, so an abandoned watch leaves no orphan timer and no state file. The default check script
+  is resolved relative to the extension file, so the staged pi package (`extensions/` beside
+  `skills/`) needs no hardcoded absolute path; `AGENT_CORTEX_POST_MERGE_CHECK` overrides it. PI only:
+  Claude Code uses its own watch tools.
+
+- ee5d09f: Fork the post-merge stage's watch per harness instead of leaving a long run unwatched. The stage
+  playbook now carries a `## Watch transport` section whose single mechanism name renders through
+  `token-map.json`: `{{TOOL:post_merge_watch}}` becomes `post-merge-watch` — this package's own
+  extension, which re-runs the check on a timer and wakes an idle session with the verdict — in a pi
+  install, and Claude Code's built-in `ScheduleWakeup` tool in a claude install. The stage
+  instructions, the three verdicts, the never-retry rule, the escalation rule and the close rule stay
+  one authored copy: the two renders differ on exactly one line.
+
+  The Claude capability is established from the installed binary (2.1.294), not assumed.
+  `ScheduleWakeup` is a registered tool whose own description names the case in point — "when actively
+  polling external state the harness can't notify you about (a CI run, a deploy, a remote queue), pick
+  the delay from how fast that state actually changes" — it takes `delaySeconds` clamped to
+  60–3600, `prompt`, `reason`, `noop` and `stop`, and a built-in system reminder says "If polling in a
+  loop, use ScheduleWakeup instead of retrying". A live probe was impossible: `claude -p` in this
+  environment reports "Not logged in · Please run /login". Because availability is a property of the
+  session rather than of the tool's existence, the section also states the fallback in prose — one run
+  with `--wait 1800` — so no harness is assumed to have a watcher and neither render loses a name.
+
+  `test/post-merge-transport-render.test.mjs` stages both installs and asserts the per-harness rendered
+  playbook, the byte-identical remainder, and the no-watcher fallback, so a harness that loses its
+  mechanism fails the suite rather than silently degrading.
+
+- b698f2d: Read a half-finished bead in one bounded command, without opening the transcript.
+
+  `skills/workflow/run-pipeline-stage/scripts/recover-brief.mjs` is the read side of the bead trail
+  that `trail-entry.mjs` writes. One invocation prints what a session needs to continue: status and
+  state labels, the newest trail entries with their Evidence and What is left, the provenance refs,
+  the blocking dependencies, and the acceptance criteria.
+
+  The bound is enforced, not promised. `bd show` returns the whole note — no option asks it for the
+  last few entries — and it prints 89 lines and about 6.5 KB for a bare bead carrying 20 entries,
+  about 120 lines and about 8 KB for a realistic one with acceptance criteria, a blocker, provenance
+  refs and a description. The brief prints the newest `--trail` entries (default 3), summarises the
+  rest by count, clips any single field, and
+  holds its whole output to a line budget (default 40) even when the requested window is wider than
+  that: it shrinks the window, names what it left out, and never prints more lines than `--max-lines`.
+
+  It reads only. Every `bd` call is one of the read subcommands and carries `--readonly`, and a call
+  that is not on the allow-list is refused before it reaches the binary, so the brief cannot write a
+  note, a status or a provenance event. Each section states plainly when a bead has no trail, no
+  refs, no acceptance criteria or no blockers, instead of printing an empty heading.
+
+  The note is one text blob, so the brief splits it itself: a writer header starts a stamped entry
+  whose body runs only over the writer's `Field: value` lines, and any other text is an entry of its
+  own. A note appended by hand therefore prints wherever it lands — before a stamped entry, between
+  two of them, or after the last one — and the trail count includes it. `next:` claims "no trail
+  entry" only when the bead carries no trail, and says the entries record no next step when they
+  exist without a `What is left` field.
+
+  `run-pipeline-stage`, `ralph` and the stage-runner prompt now document the brief as the first read of
+  a bead's trail, with `bd show` and `bd provenance log` reserved for the history the window left out.
+
+- 1e97223: Rejections now carry data. A review that rejects a bead applies exactly one `defect:<class>` label
+  from a closed list of eight classes — `test-unproven`, `test-cannot-fail`, `criteria-unmet`,
+  `scope-creep`, `style-violation`, `missing-proof`, `regression`, `docs-drift` — plus the specific
+  reason in the rejection text.
+
+  The new `review-defects` skill defines the vocabulary, with one worked example per class in
+  `EXAMPLES.md`. The review playbook instructs one label per rejection, states that a class outside
+  the list is a review defect in itself, and says the review that confirms a fix removes the label and
+  records the removal in its trail entry. The label classifies the defect; the bead's status still
+  says where the work is, so no state label is added. Because the rejected chore is normally already
+  closed, the two queries that read the vocabulary pass `--all`: one class with
+  `bd list -l defect:<class> --all`, and every defect with `bd list --label-pattern 'defect:*' --all`.
+  `bd-tool` indexes the label and points at `review-defects` for the vocabulary and the queries.
+
+- 7ce04e0: Add `agent-cortex self-update` (and its `ctx` / `cortex` aliases): update the globally installed CLI
+  through the manager that owns the install, then refresh the harness installs with the newly
+  installed binary. The owner is inferred from the running entry point's real path — pnpm's
+  `global/<v>` and `store/<v>/links` layouts, or npm's `lib/node_modules` — then confirmed by asking
+  that manager for its own global listing and matching this package's name and version, so a manager
+  on `PATH` is never used in place of the real owner: an unidentified or unconfirmed owner prints the
+  exact command and exits non-zero. It reports the installed version (read from the manifest beside
+  the entry point), the published version (from the confirmed manager's `view`), the owner, and the
+  command, and `--check` stops after the report writing nothing. A registry error is a distinct
+  failure that offers no update, and a failed install reports the manager's stderr and runs nothing
+  after it. Every process is spawned with an argv array (`execFile` / `spawn`), never a shell string.
+- 2624dce: `self-update` now reports the version boundary and only refreshes when the CLI changed. After a
+  successful install it reads the version the newly installed binary reports and prints
+  `cli        <before> → <after>`, then hands the terminal to that binary's `update -a` and exits with
+  the refresh's own exit code, so a failed refresh is visible to the caller. The refresh is skipped in
+  three cases: `--check`, a failed update, and an install already at the published version (which now
+  also installs nothing and points at `agent-cortex update -a` instead). A refresh that cannot start
+  prints the reason and the exact command to run by hand instead of exiting 1 silently. The README,
+  `docs/dev-loop.md` and `--help` document the act-by-default behaviour, `--check`, the owner
+  detection rule, and the re-exec chain with its failure output.
+- 8925019: Add the `session-clear` extension, which registers `/clear` in pi: keep the session display name,
+  model, thinking level, and active agent, and drop the transcript context. It captures the identity
+  as plain data, replaces the session with `ctx.newSession({ parentSession })` so the cleared session
+  stays the parent in `/tree` and `/resume`, then the replacement instance re-applies the name and
+  restores the model and thinking level only when they differ from the replacement's own values. It
+  appends a `session-clear` provenance entry, reports the clear in one line, never prompts, never
+  summarises, and never deletes the cleared session file. PI-only: Claude Code already ships `/clear`,
+  so the audit in `docs/claude-hooks.md` records no hook port.
+- 0936de5: Make a test's name an assertion contract, and require a mutation check before a test is done.
+
+  `style-tests` now states that every clause of a test name must be an assertion: a count in the name
+  asserts a count, a state asserts that state, and a "not" asserts the absence. The Workflow gains the
+  mutation check — disable the claimed behaviour and confirm each named test fails — and Red Flags
+  names the case that motivated it, a test named "one notice" proven only by `toBeDefined()`. The
+  worked pair lives in `EXAMPLES.md` under _A test name is a claim_. The review playbook now requires
+  the reviewer to map each clause of a changed test's name to the assertion that proves it, to reject a
+  test whose name outruns its assertions, and to block a test change that carries no evidence the
+  mutation check ran.
+
+### Patch Changes
+
+- 82dbed0: A stop that needs a human decision becomes a bead, not a label: `bd-tool` and `AGENTS.md` now say
+  to create an `execution:hitl` task carrying the question, then make the waiting bead depend on it
+  with `bd dep add <waiting> <decision>`. The waiting bead leaves `bd ready` while the decision
+  becomes work a human can take, so one answer releases work that is already scoped. `--status
+blocked` is kept for a stop no bead can carry, such as a fix-round cap, and `bd note` records the
+  stop and its reason.
+
 ## 2.7.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, …
@@ -81,7 +82,8 @@ temp-dir install plus structural checks:
   the whole plugin — every skill and agent in it — with that one field. Hand-authored
   extras — `.mcp.json` and `scripts/` — are copied into every install from the `claude-extras/`
   dir, which is their canonical store. See `docs/claude-hooks.md` for the
-  extension→hook mapping and the rejections (auto-name, agent-guardrails, skill-stats, subagent, agent-modes).
+  extension→hook mapping and the rejections (auto-name, agent-guardrails, skill-stats, subagent, agent-modes,
+  session-clear, post-merge-watch).
 
 Edit the sources (`agents/<name>/` composable dirs, `skills/**`,
 `hooks/claude/`, `claude-extras/`, `package.json`), never anything under the materialised
@@ -206,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 |
@@ -287,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
@@ -427,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
@@ -443,6 +446,27 @@ 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. Between tasks it clears the context
+with `/clear`, and only after writing what was decided, what is open and what comes next to the bead
+trail and the memory. The tracker, not the window, holds the state that matters.
+
+```sh
+claude --agent agent-cortex:guppi
+```
+
+Its authority is prioritisation, not action. `prioritise-work` owns the committed strategy file;
+`score-bead` records the score and `hitl-queue` prints the order. guppi reports them and never
+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
@@ -457,7 +481,8 @@ extension→hook audit.
 #### Not ported / follow-ups
 
 - Only `session-start` and `notify` had Claude equivalents (both ported to hooks); the other
-  pi `extensions/` (auto-name, agent-guardrails, skill-stats, subagent, agent-modes) have none — `output-style`
+  pi `extensions/` (auto-name, agent-guardrails, skill-stats, subagent, agent-modes,
+  post-merge-watch) have none — `output-style`
   reaches Claude through the managed `CLAUDE.md` section instead; the audit and
   rejection rationale live in `docs/claude-hooks.md`.
 - Ralph follow-ups: multi-feature epic branches, and a GitHub-trigger routine to auto-resume
@@ -504,6 +529,61 @@ Only plain release versions are compared, so a prerelease on either side also re
 The command is read-only: it stats and reads those manifests, and never installs, writes, or
 reaches the network.
 
+## Updating the CLI itself (`agent-cortex self-update`)
+
+`agent-cortex self-update` updates the globally installed CLI through the manager that installed it,
+then refreshes the harness installs with the newly installed binary.
+
+```sh
+agent-cortex self-update           # report, update, then refresh the harness installs
+agent-cortex self-update --check   # report the versions and the command, write nothing
+```
+
+The owning manager is inferred from the running entry point's real path, then confirmed — never
+assumed. A pnpm install lives under `<prefix>/global/<v>/…` (and the store link that path resolves
+into), an npm install under `<prefix>/lib/node_modules/…`, and the manager binary is taken from that
+`<prefix>` rather than from `PATH`. That matters because two managers can be installed and only one
+of them owns this copy: running the manager on `PATH` would update the wrong store or fail. The
+confirmation asks the inferred manager for its own global listing and matches this package's name
+and version. An owner that cannot be inferred or confirmed prints the exact command and exits
+non-zero — both managers' commands when it cannot even infer the layout, because that choice is
+the user's. The CLI never falls back to a manager found on `PATH`.
+
+The report gives the installed version (read from the manifest beside the entry point, so even a
+stale process reports what is on disk), the published version (from the confirmed manager's `view`),
+the owner, and the command it would run. A registry error is its own failure: it prints the
+manager's error, offers no update, and exits non-zero. A failed install reports the manager's stderr
+and runs nothing after it. Once the install succeeds, the command reports the CLI version before and
+after (`cli        1.2.3 → 1.4.0`, read from the binary the update just installed, because the
+running process is still the old code), then hands the terminal to the new binary's `update -a`. One
+command brings the CLI and the harness installs to the same version, and the exit code is the
+refresh's.
+
+The refresh spawns `<prefix>/bin/agent-cortex` from that same inferred prefix with an argv array and
+inherits the terminal, so the refresh's own output is what the user reads. It is skipped in three
+cases: `--check`, a failed update, and an install already at the published version (where
+`agent-cortex update -a` is the refresh that is left). A refresh that cannot start — the path is
+POSIX-shaped, while native Windows pnpm and npm write `.cmd` shims it does not match, and Node cannot
+start a `.cmd` without a shell — prints the reason and the exact command to run by hand, and exits
+non-zero. The CLI update has already succeeded by then, so `agent-cortex update -a` finishes the job.
+
+```sh
+# what it reports, for a copy installed by a pnpm that is not the one on PATH
+agent-cortex self-update --check
+#   installed  1.2.3
+#   published  1.4.0
+#   owner      pnpm (/opt/pnpm-home/bin/pnpm)
+#   status     update available: 1.2.3 → 1.4.0
+#   command    /opt/pnpm-home/bin/pnpm add -g @jaybeeuu/agent-cortex@latest
+
+# what a bare run adds after that report
+agent-cortex self-update
+#   ✓ /opt/pnpm-home/bin/pnpm add -g @jaybeeuu/agent-cortex@latest
+#   cli        1.2.3 → 1.4.0
+#   → refreshing installed harnesses with /opt/pnpm-home/bin/agent-cortex update -a
+#   …the new binary's own update report…
+```
+
 ## Refreshing installed harnesses (`agent-cortex update`)
 
 `agent-cortex update` re-runs a harness installer and reports what changed. It installs nothing
@@ -536,9 +616,8 @@ the installer wrote; harnesses already at the CLI version are listed as skipped.
 version is read back from the manifest its installer wrote, so a refresh that failed to
 materialise reports `unknown` rather than claiming the CLI version.
 
-This refreshes the installs, not the CLI. Bump the global package first
-(`pnpm add -g @jaybeeuu/agent-cortex@latest`), then update the harnesses — see
-[`docs/dev-loop.md`](docs/dev-loop.md).
+This refreshes the installs, not the CLI. `agent-cortex self-update` does both in one step; the
+[`docs/dev-loop.md`](docs/dev-loop.md) page records what a global reinstall has to fix.
 
 ## Migrating a beads workspace
 

package/agents/README.md

@@ -44,13 +44,13 @@ agents/ralph/
 `{{SECTION:wake}}` is the one seam where harness differences belong: the shared `agent.md`
 names no harness and no harness-specific tool, and every one of those facts lives in a
 `wake.md` that states its mechanism in one sentence, then covers **spawn** (tool and argument
-shape), **completion arrival**, **id tracking**, **log flush**, and **stop** behaviour.
+shape), **completion arrival**, **id tracking**, **trail reading**, and **stop** behaviour.
 `token-map.json`'s `wake.mechanism` table records the same fact machine-readably.
 
 | Harness | `wake.mechanism` | Completion arrives via | Id tracking | Stop means |
 |---------|------------------|------------------------|-------------|------------|
 | `pi` | `blocking-wait` | `wait_for_agents` returns as soon as a worker finishes, result inline | `agentId` only | stop calling `wait_for_agents` — nothing to kill |
-| `claude` | `event-driven` | harness re-invokes ralph with the result inline | task ID only, no `logLine` | simply stop — nothing to kill |
+| `claude` | `event-driven` | harness re-invokes ralph with the result inline | task ID only | simply stop — nothing to kill |
 
 ### Example: plan agent (no per-harness sections)
 
@@ -199,7 +199,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 +217,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