@jaybeeuu/agent-cortex 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,178 @@
 # 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

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,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

package/agents/README.md

@@ -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

package/agents/guppi/agent.md

@@ -0,0 +1,162 @@
+# 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 a planning session must report that queue before it proposes anything. | {{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.
+
+## 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.
+
+**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.

package/agents/guppi/claude/frontmatter.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-cortex:guppi",
+  "description": "Resident prioritising collaborator for human-in-the-loop work. Recommends what to look at next from the committed strategy, then helps plan, grill, flesh out or hand off the chosen item. Use when asking 'what should I work on', choosing the next HITL item, or disagreeing with a priority.",
+  "tools": ["Bash", "Read", "Edit", "Write", "Grep", "Glob", "AskUserQuestion", "Task", "Skill"],
+  "argumentHint": "Guppi — what should I look at next?"
+}

package/agents/guppi/pi/frontmatter.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-cortex:guppi",
+  "description": "Resident prioritising collaborator for human-in-the-loop work. Recommends what to look at next from the committed strategy, then helps plan, grill, flesh out or hand off the chosen item. Use when asking 'what should I work on', choosing the next HITL item, or disagreeing with a priority.",
+  "tools": ["bash", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill", "interrupt_checkpoint", "interrupt_resume"],
+  "argumentHint": "Guppi — what should I look at next?"
+}

package/agents/plan/agent.md

@@ -6,6 +6,12 @@ You follow the **plan** skill workflow. The skill is defined in `{{PATH:skills/w
 
 ## Workflow summary
 
+### Phase 0 — Report the HITL queue
+1. Load the `hitl-queue` skill and report its queue exactly as the script prints it — before asking
+   the user anything, presenting a plan, or dispatching a task.
+2. Name the top item plainly: its id, its title, and what answering it unblocks. When nothing is
+   scored, report the unscored list and ask which bead to score rather than picking one by feel.
+
 ### Phase 1 — Understand and specify
 1. Ask the user to describe the problem, goal, or feature.
 2. Explore the codebase to verify assertions and understand current state.

package/agents/ralph-plan/agent.md

@@ -24,6 +24,12 @@ Do **not** write anywhere else. No source files, no READMEs, no tracked docs, no
 ### 1. Load context
 Invoke the **beads** skill (set workspace root, run `bd prime`). Hold the output in memory.
 
+Then report the HITL queue: load the **hitl-queue** skill, run its `queue` subcommand, and report
+the list exactly as the script prints it, naming the top item — its id, its title, and what
+answering it unblocks. It is the first thing the session says, before any sub-agent is dispatched
+or any plan is proposed. When nothing is scored, report the unscored list and ask which bead to
+score rather than picking one by feel.
+
 If the input looks like a PRD (product requirements document), invoke the **prd-to-tasks** skill first — it handles exploration, user quizzing, and creates epics and task beads directly. Then continue from step 7 (Agree with the user).
 
 ### 2. Understand the request

package/bin/installers/claude.mjs

@@ -75,6 +75,7 @@ import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens } from "../../scripts/lib/compose-agent.mjs";
 import { installDocs } from "../../scripts/lib/docs.mjs";
 import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
+import { normaliseRepository } from "../../scripts/lib/manifest.mjs";
 import { flattenSkillLinks } from "../../scripts/lib/skill-links.mjs";
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
@@ -268,26 +269,6 @@ async function copyTree(src, dest, transform, dryRun) {
   return { md, files };
 }
 
-/**
- * Normalise package.json's `repository` field into the string Claude Code's
- * plugin manifest requires. npm permits a string or an object
- * (`{ type, url, directory }`); Claude rejects anything but a string, and one
- * invalid manifest makes the whole plugin fail to load, so the object form must
- * never be copied through. Prefer `url`, fall back to `directory`, and omit the
- * field when neither is usable rather than emitting junk.
- * @param {unknown} repository  parsed package.json `repository` value
- * @returns {string | undefined}
- */
-function normaliseRepository(repository) {
-  if (typeof repository === "string") return repository.trim() === "" ? undefined : repository;
-  if (repository === null || typeof repository !== "object") return undefined;
-  const { url, directory } = /** @type {{ url?: unknown, directory?: unknown }} */ (repository);
-  for (const candidate of [url, directory]) {
-    if (typeof candidate === "string" && candidate.trim() !== "") return candidate;
-  }
-  return undefined;
-}
-
 /**
  * plugin.json manifest; version tracks the package so it can never go stale.
  * @param {string} root

package/bin/installers/pi.mjs

@@ -12,7 +12,9 @@
 //
 //   <output>/package.json            pi manifest — keywords ["pi-package"],
 //                                    pi.extensions + pi.skills (conventional
-//                                    dirs plus the bundled third-party packages)
+//                                    dirs plus the bundled third-party packages),
+//                                    repository (this package's origin, so the
+//                                    shipped skills resolve it from the install)
 //   <output>/agents/<slug>.agent.md  composed flat agents (agents/<name>/
 //                                    agent.md + pi/ harness dirs, {{TOOL:...}} /
 //                                    {{PATH:...}} substituted against
@@ -122,6 +124,7 @@ import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens, translateToolList } from "../../scripts/lib/compose-agent.mjs";
 import { installDocs } from "../../scripts/lib/docs.mjs";
 import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
+import { normaliseRepository } from "../../scripts/lib/manifest.mjs";
 
 const PI = "pi";
 
@@ -137,7 +140,7 @@ const PI = "pi";
 /**
  * The generated package's pi manifest (`//` carries the generated-file marker).
  * @typedef {{ "//": string, name: string, version: string, private: boolean,
- *             description: string, type: string, keywords: string[],
+ *             description: string, repository?: string, type: string, keywords: string[],
  *             pi: { extensions: string[], skills: string[] } }} PiManifest
  */
 
@@ -1338,6 +1341,9 @@ async function buildManifest({ root, dependencies }) {
     version: typeof pkg?.version === "string" ? pkg.version : "0.0.0",
     private: true,
     description: "agent-cortex pi resources — generated by `agent-cortex install pi`",
+    // Where this package came from, carried so the installed artefact states its own origin:
+    // the shipped skills read it instead of assuming a checkout or a hardcoded slug.
+    repository: normaliseRepository(pkg?.repository),
     type: "module",
     keywords: ["pi-package"],
     pi: {