@jaybeeuu/agent-cortex 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,274 @@
 # Changelog
 
+## 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
+
+- 464c761: Add `ctx update`, which refreshes installed harnesses by re-running their installers. Bare
+  `ctx update` lists every harness with its installed version and the CLI version, then asks which
+  to refresh; a non-interactive shell prints the same table plus the flags and exits non-zero
+  instead of blocking. `ctx update pi claude` refreshes exactly the named harnesses, `ctx update -a`
+  refreshes every harness that is not at the CLI version, and `ctx update -a -f` re-runs every
+  installer regardless of version. The report gives each harness its previous and new version and
+  the artifacts the installer wrote. Selection and reporting are the only additions: every refresh
+  goes through the existing `bin/installers/` entry points, so update-vs-install stays the
+  installer's decision.
+
+### Patch Changes
+
+- bfce679: Add a `housekeeping` pipeline stage that runs after the human merge gate. `create-chores.mjs` now
+  creates a `stage:housekeeping` chore labelled `lifecycle:housekeeping` and blocked behind the
+  `lifecycle:feature-pr` gate bead, so it stays out of `bd ready` until a human merges the PR and
+  closes the gate. A dispatched worker then runs `prune-worktrees.mjs` from the main checkout, retries
+  once on a non-zero exit, and fails the chore without closing it when a closed-bead worktree is still
+  refused. The four existing stages and the gate are unchanged.
+- 8d11154: Ship the skill anatomy doc into both installs. `write-a-skill` and `refactor-skill` read
+  `docs/skills/skill-anatomy.md`, but neither install contained it, so the reference was dead on any
+  machine without the checkout. Both installers now copy the document into the staged tree once per
+  install (`scripts/lib/docs.mjs`), and the skills name it through a new `{{PATH:skill_anatomy}}` entry
+  in `token-map.json`, so the token map stays the single source of the per-harness path. A new test
+  stages both installs and fails when a rendered skill references a repository doc the install does
+  not contain.
+
 ## 2.6.0
 
 ### Minor Changes

package/README.md

@@ -81,7 +81,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
@@ -209,6 +210,7 @@ The staged package contains:
 | `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 |
 | `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 |
 | `token-map.json` | the token map `agent-modes` reads from the package root |
 | `node_modules/` | the required third-party pi packages and their transitive closure |
@@ -243,9 +245,9 @@ never removes an entry you added. Each report gives the `pi remove` command that
 resolves it, with the resolved path, because `pi remove` resolves a relative
 argument against the current directory.
 
-Re-run `agent-cortex install pi` after every `git pull` to refresh the staged
-package; registration is already in place, so that re-run changes nothing in
-pi's settings. Verify with `pi list` and `pi config` (restart pi to apply).
+Re-run `agent-cortex install pi` (or `agent-cortex update pi`) after every `git pull` to refresh
+the staged package; registration is already in place, so that re-run changes nothing in pi's
+settings. Verify with `pi list` and `pi config` (restart pi to apply).
 
 Refreshing the installed runtime after a release, and trying uncommitted work without
 overwriting it, are recorded in [`docs/dev-loop.md`](docs/dev-loop.md).
@@ -408,8 +410,9 @@ from a different root is refreshed in place rather than re-pointed at the fresh
 install. Re-point it with
 `claude plugin marketplace remove jaybeeuu` and re-run the install.
 
-The plain install IS the update — there is no separate build step. (`--output <dir>` only
-generates a preview and never refreshes an installed plugin.)
+The plain install IS the update — there is no separate build step, and `agent-cortex update claude`
+is the same materialise-and-register run selected by name. (`--output <dir>` only generates a
+preview and never refreshes an installed plugin.)
 
 #### Uninstall
 
@@ -455,7 +458,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
@@ -474,7 +478,7 @@ version — picked up at install time) — then run
 `agent-cortex install claude` (re-materialises the home plugin, merges settings, and
 re-registers it; `--output <dir>` generates a preview only). The only committed file under
 `claude/` is the settings template; `~/.agent-cortex/claude` is generated in full
-(`.claude-plugin/plugin.json`, `agents/`, `skills/`, `hooks.json`, `.mcp.json`, `scripts/`)
+(`.claude-plugin/plugin.json`, `agents/`, `skills/`, `docs/`, `hooks.json`, `.mcp.json`, `scripts/`)
 so never edit anything under it. CI validates the Claude materialiser (structural checks on
 a temp-dir install) so sources and installer can never silently diverge.
 
@@ -502,6 +506,96 @@ 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
+itself: every refresh goes through the same path as `agent-cortex install <harness>`, so update and
+install can never disagree about what is out of date.
+
+```sh
+agent-cortex update                 # list the harnesses, then ask which to refresh
+agent-cortex update pi claude       # refresh exactly these, no prompt
+agent-cortex update -a              # refresh every harness not at the CLI version
+agent-cortex update -a -f           # re-run every installer regardless of version
+```
+
+The prompt lists every supported harness with its installed version, the CLI version, and a status
+marker (`current`, `stale`, `ahead`, `unknown`, or `missing`) — the data `agent-cortex version`
+reports, plus a row for a harness with no install. Answer with row numbers counted from the top
+row, `a` for every harness, or blank to cancel.
+
+A harness named on the command line always refreshes, whatever version it reports, and takes
+precedence over `-a`. `-a` refreshes every harness that does not report `current`, so an
+uninstalled, stale, ahead, or unreadable harness is refreshed. `-f` requires `-a`: alone it says
+nothing about which harnesses to touch. An unknown name fails before any installer runs.
+
+A shell that is not a terminal cannot answer the prompt, so a bare `agent-cortex update` there
+prints the same table plus the flags above and exits non-zero — a script can never mistake
+"nothing chosen" for "nothing to do".
+
+The report gives each refreshed harness its previous version, its new version, and the artifacts
+the installer wrote; harnesses already at the CLI version are listed as skipped. A harness's new
+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. `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
 
 `agent-cortex migrate` brings the `.beads` workspace it runs in — any repo, not just this

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)
 

package/agents/ralph/agent.md

@@ -14,14 +14,14 @@ Harness-agnostic rules (tool names and completion detection differ per harness
 - ALWAYS set the subagent's working directory to the feature worktree path when running stage chores.
 - ALWAYS keep the returned agent/task id in memory so you can read the result later.
 
-Each pipeline stage is a separate **chore bead**, pre-created by `create-chores.mjs` from the `create-task` skill's `pipeline.json` when the task is expanded, with `blocks` deps that encode the stage order. Ralph never creates a stage chore — dispatch is always "claim what `bd ready -l execution:afk` returns". Stage tags (`stage:*`) live on chore beads, not on the parent feature bead. Loop counts are derived by querying chore children of the parent, not stored in state. Orchestration state is derived entirely from beads — the only local state is `state.json` (worker-ID-to-bead mapping plus whatever wake-loop handle the wake section tracks) and per-parent log files.
+Each pipeline stage is a separate **chore bead**, pre-created by `create-chores.mjs` from the `create-task` skill's `pipeline.json` when the task is expanded, with `blocks` deps that encode the stage order. Ralph never creates a stage chore — dispatch is always "claim what `bd ready -l execution:afk` returns". Stage tags (`stage:*`) live on chore beads, not on the parent feature bead. Loop counts are derived by querying chore children of the parent, not stored in state. Orchestration state is derived entirely from beads — the only local state is `state.json`, holding the worker-ID-to-bead mapping plus whatever wake-loop handle the wake section tracks. Progress lives in the bead trail the workers write, never in a file Ralph tails.
 
 ## Branching model
 
 - **Single-feature epics** (epic has exactly one feature task child): skip the epic branch entirely. The feature branch (`feature/<parent-id>`) is based directly from `origin/main`. The HITL PR targets `main` directly. No epic PR is required.
 - **Multi-feature epics** (epic has two or more feature task children): each epic runs on `epic/<epic-id>` (base: `origin/main`, never local `main`). Each feature branch is based from its epic branch. Completed features PR into `epic/<epic-id>`; the completed epic PRs into `main`.
 - Each parent feature task runs on `feature/<parent-id>` in `.agent-cortex/worktrees/<parent-id>`.
-- Each implemented bead owns a child HITL PR-gate task bead (`lifecycle:feature-pr`, blocked by its own `document` chore) for PR review/merge.
+- Each implemented bead owns a child HITL PR-gate task bead (`lifecycle:feature-pr`, blocked by its own `document` chore) for PR review/merge, plus a `stage:post-merge` chore and a `stage:housekeeping` chore, each blocked behind that gate.
 - Completed features must be reviewed by PR merge from the agent branch (`feature/<parent-id>`) into its base (epic branch for multi-feature epics, `main` for single-feature epics), then the HITL PR task bead must be closed by a human before Ralph continues feature scheduling.
 - Completed multi-feature epics must be reviewed by PR merge into `main`.
 
@@ -63,7 +63,7 @@ A ready `execution:afk` bead of type `feature` with **no** children is not dispa
 2. Dispatch a **decomposition worker** in the feature worktree (`.agent-cortex/worktrees/<feature-id>`) whose whole job is to run the `create-task` hierarchy flow (`prd-to-tasks` → `create-task`) for that one **existing** feature — its planning bead and impl children only, never a second feature bead — and report the IDs it created. The worker builds one `execution:hitl` planning bead (`--parent <feature-id>`) plus `execution:afk` implementation task children (`--parent <feature-id>`, `--no-inherit-labels`), each wired with `bd dep add <impl-child> <planning-bead>` so the dependency — not an extra label — is the readiness gate. `create-task`'s feature path (its `SKILL.md` steps 5–6) is the authority for this shape.
 3. Record the worker in `inflight` as a **decomposition** entry — it holds no chore, so `choreId` is `null`:
    ```json
-   { "kind": "decompose", "choreId": null, "parentId": "<feature-id>", "title": "<feature title>", "agentId": "<agent-id>", "logLine": 1 }
+   { "kind": "decompose", "choreId": null, "parentId": "<feature-id>", "title": "<feature title>", "agentId": "<agent-id>" }
    ```
 4. On completion, confirm the children exist (`bd children <feature-id> --json`) rather than trusting the report, and surface the created IDs in chat. An empty list means the decomposition failed: record the feature for the shutdown summary and continue — do **not** re-dispatch.
 5. **Never re-dispatch a decomposition.** The bead creation it runs is not idempotent, so a second run duplicates the planning bead and every implementation child beside the first.
@@ -90,14 +90,18 @@ A ready `execution:afk` task bead with no `stage:*` chore children has nothing t
    The command is idempotent: it adopts an existing child by its `stage:<id>` or `lifecycle:feature-pr` label, creates only what is missing, skips deps that are already wired, and prints the resolved mapping either way. Re-running it is the recovery path for a failed expansion.
 3. Record the worker in `inflight` as an **expansion** entry — it has no chore to key on, so `choreId` is `null`:
    ```json
-   { "kind": "expand", "choreId": null, "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>", "logLine": 1 }
+   { "kind": "expand", "choreId": null, "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>" }
    ```
    That entry is what keeps it in the wait set and makes its completion attributable to the parent.
-4. The worker reports the returned mapping — `code`, `verify`, `review`, `document`, `featurePrReview` — and closes nothing. It emits **no** `---REPORT---` block and owns no bead, so there is nothing to parse and no close to confirm.
+4. The worker reports the returned mapping — `code`, `verify`, `review`, `document`, `post-merge`, `housekeeping`, `featurePrReview` — and closes nothing. It emits **no** `---REPORT---` block and owns no bead, so there is nothing to parse and no close to confirm.
 5. Its completion means the parent now has a `stage:*` chain: the event loop's next `bd ready -l execution:afk` pass picks up the `stage:code` chore (event loop step 7).
 
 **Expansion completion contract.** An expansion worker is dispatched like a stage worker but is not one: no chore claim, no `---REPORT---`, no leaf-bead close. Handle its completion with the expansion branch in event-loop step 3, which confirms the chain exists (`bd children <parent-id> --json | grep -c '"stage:'` prints one match per stage chore — the gate carries `lifecycle:feature-pr` and is not counted) and dispatches the ready `stage:code` chore. A count below the stage total in `pipeline.json` is a partial chain, whose missing stages never arrive, so re-dispatch the expansion instead of dispatching on. If the parent still has no `stage:*` children the expansion failed: surface the worker's output in chat, record the parent for the shutdown summary, and re-dispatch the expansion — `create-chores.mjs` is idempotent, so a second run adopts the chores that exist, creates only the missing ones, and reports the whole mapping. Either way, create nothing and close nothing yourself.
 
+**Housekeeping chore.** One stage runs outside the pipeline's ordering: `stage:housekeeping`, labelled `lifecycle:housekeeping` and blocked behind the PR gate bead, so it becomes ready only after a human merges the PR and closes the gate. Dispatch it with the **main checkout** as cwd — not the feature worktree — because the worktree it removes can be the parent's own. The worker runs `prune-worktrees.mjs`, retries once on a non-zero exit (exit `1` is normal: an open bead counts as survival), and then decides from the per-worktree report. It fails the chore and leaves it **open** when a `closed-bead` worktree is still `refused`; a `kept` or `refused` entry for an open bead is a normal report. Never close a chore over a worktree the script did not remove.
+
+**Post-merge check.** The `stage:post-merge` chore, labelled `lifecycle:post-merge`, is the other stage blocked behind the PR gate, so it too becomes ready only after a human merges and closes the gate. Dispatch it with the **main checkout** as cwd: the commit it reads landed on the base branch. The worker runs `post-merge-check.mjs` once and reports the exit status — `0` passed, `1` failed, `2` inconclusive. Exit `1` has already filed one P1 escalation bead (`lifecycle:post-merge-escalation`, carrying the run URL and the failing job); the worker leaves its chore **open** and closes nothing else. Exit `2` also leaves the chore open, with nothing filed. The stage never retries, never re-runs the workflow, never reverts the merge, never reopens the parent, and builds no `stage:fix` chain — no fix round repairs a commit that already merged. It and `stage:housekeeping` are siblings on the gate: neither waits on the other, because an inconclusive check must not block the worktree reclamation.
+
 **Never expand an existing bead by running `create-task`** (or any other command that creates a bead). `create-task` creates a bead first and expands second, so running it for an existing bead leaves a **second parent** beside the original, which stays chore-less and never gets dispatched. `create-chores.mjs` expands a bead that already exists; it never creates parents.
 
 ---
@@ -106,11 +110,11 @@ A ready `execution:afk` task bead with no `stage:*` chore children has nothing t
 
 Chores already exist and their deps already encode the order, so dispatch is claim-and-spawn — claim the ready chore (`bd update <chore-id> --claim`) and skip to the prompt.
 
-Load the universal stage runner prompt from the `run-pipeline-stage` skill's `prompts/stage-runner.md`, fill in all placeholders (including `<stage>` from the bead label, parent task description from `bd show <parent-id>`, prior SUMMARY/FILES_CHANGED from the last REPORT, chore bead ID, log path `.agent-cortex/ralph/ralph-<parent-id>.log`), and spawn a subagent in **background** mode using the spawning mechanism described in the wake section, running from the feature worktree. Stage-specific policy comes from that skill's `playbooks/<stage>.md`. The prompt's lifecycle, remediation, and REPORT sections are the worker's contract — pass them through verbatim, never restate or trim them.
+Load the universal stage runner prompt from the `run-pipeline-stage` skill's `prompts/stage-runner.md`, fill in all placeholders (including `<stage>` from the bead label, parent task description from `bd show <parent-id>`, prior SUMMARY/FILES_CHANGED from the last REPORT, chore bead ID, and the trail writer's path `<run-pipeline-stage-scripts>/trail-entry.mjs`), and spawn a subagent in **background** mode using the spawning mechanism described in the wake section, running from the feature worktree. Stage-specific policy comes from that skill's `playbooks/<stage>.md`. The prompt's lifecycle, remediation, and REPORT sections are the worker's contract — pass them through verbatim, never restate or trim them.
 
 Add the entry to `inflight` in `state.json`:
 ```json
-{ "kind": "stage", "choreId": "<chore-id>", "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>", "logLine": 1 }
+{ "kind": "stage", "choreId": "<chore-id>", "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>" }
 ```
 
 ---
@@ -128,16 +132,16 @@ bd show <id>                   # full detail, including the worker's notes
 Report status in chat from those commands. The only files Ralph owns are:
 
 - **`.agent-cortex/ralph/state.json`** — runtime bookkeeping only (worker-ID→bead mapping plus the wake loop's own handle).
-- **`.agent-cortex/ralph/ralph-*.log`** — per-parent log files written by subagents (e.g. `.agent-cortex/ralph/ralph-abc-123.log`). Keyed by **parent** bead ID so all chore stages for a feature share one log.
+- **The bead trail** — not a file Ralph writes: each worker appends its own entries with `trail-entry.mjs`, and Ralph reads them from `bd show` and `bd provenance log`.
 
 All orchestration state is derived from beads:
 
 ```json
 {
   "inflight": [
-    { "kind": "stage", "choreId": "xyz-456", "parentId": "abc-123", "title": "Add auth", "agentId": "agent-xyz-456", "logLine": 4 },
-    { "kind": "stage", "choreId": "def-789", "parentId": "ghi-101", "title": "Fix cache", "agentId": "agent-def-789", "logLine": 7 },
-    { "kind": "expand", "choreId": null, "parentId": "jkl-202", "title": "Expand billing", "agentId": "agent-jkl-202", "logLine": 1 }
+    { "kind": "stage", "choreId": "xyz-456", "parentId": "abc-123", "title": "Add auth", "agentId": "agent-xyz-456" },
+    { "kind": "stage", "choreId": "def-789", "parentId": "ghi-101", "title": "Fix cache", "agentId": "agent-def-789" },
+    { "kind": "expand", "choreId": null, "parentId": "jkl-202", "title": "Expand billing", "agentId": "agent-jkl-202" }
   ]
 }
 ```
@@ -145,8 +149,7 @@ All orchestration state is derived from beads:
 - **inflight[].kind**: `"stage"` for a dispatched stage chore (the only shape that carries a `choreId`), `"decompose"` for a feature-decomposition worker and `"expand"` for an expansion worker (both no chore — `choreId` is `null`). Every dispatched agent has an entry; anything missing from `inflight` is invisible to the wait set and to the HITL-pause check.
 - **inflight[].agentId**: the worker id the spawn call returned — the key every completion is correlated to its bead against, and the identifier the wake section's read/wait path takes (see that section).
 - **inflight[].choreId**: the chore bead currently being worked by the subagent.
-- **inflight[].parentId**: the parent feature task bead. Log file is `.agent-cortex/ralph/ralph-<parentId>.log`.
-- **inflight[].logLine**: the next line number to read from the parent's log file (1-based; start at 1). Updated after every poll.
+- **inflight[].parentId**: the parent feature task bead — the id every trail entry is read under (`bd show <parentId>`, `bd children <parentId>`).
 - **Loop counts are not stored here** — derive them from beads:
   - Fix round count = number of `stage:fix` chore children of `<parentId>` (closed ones count)
 
@@ -164,7 +167,7 @@ After initialization, Ralph waits for background agents to complete. Completions
 
 ### If a background agent completed
 
-1. **Flush** that bead's log using the procedure in the wake section to pick up any final lines for the chat summary (a mechanism that delivers the log with the completion needs no flush).
+1. **Read the worker's bead trail** — `bd show <chore-id>` for its entries and `bd provenance log <chore-id>` for the refs — and use it for the chat summary. There is no log file to flush.
 2. **Read** the completed agent's full output the way the wake section describes.
 3. **Re-read** `.agent-cortex/ralph/state.json` to identify the entry for that agent ID, then branch on its `kind`:
    - **`kind: "expand"` — expansion completion branch.** The worker claimed no chore, emits no `---REPORT---`, and owns no bead to confirm, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the parent now has `stage:*` chore children (`bd children <parent-id> --json | grep -c '"stage:'`) and surface the reported mapping in chat, then go straight to step 7 — the new `stage:code` chore is ready to dispatch. If the count is `0` — or below the stage total, which is a partial chain whose later stages never arrive — the expansion failed: surface the worker's output, record the parent for the shutdown summary, remove the entry, and re-dispatch the expansion — re-running `create-chores.mjs` is idempotent and is the recovery path, so it repairs the tree instead of duplicating it. Never create or close a bead for an expansion.
@@ -173,9 +176,9 @@ After initialization, Ralph waits for background agents to complete. Completions
 4. **Parse** the agent's `---REPORT---` block (see report format in the `run-pipeline-stage` skill).
 5. **Confirm** the worker closed its own leaf execution bead: `bd show <chore-id>` should read `closed`. If it is still open the worker died mid-stage — read its notes and re-dispatch. Never close it yourself.
 6. **Advance** the parent using the routing guidance in the `run-pipeline-stage` skill:
-   - **Success paths** (code → verify, verify SUCCESS → review, review SUCCESS → document): create nothing — closing the chore already unblocked the next stage of the pre-created chain. Point the parent's inflight entry at that newly ready `stage:*` chore and dispatch it (see _Dispatching a stage chore_ above), resetting logLine to 1.
+   - **Success paths** (code → verify, verify SUCCESS → review, review SUCCESS → document): create nothing — closing the chore already unblocked the next stage of the pre-created chain. Point the parent's inflight entry at that newly ready `stage:*` chore and dispatch it (see _Dispatching a stage chore_ above).
    - **Documenting → done**: close the parent feature bead (`bd close <parent-id>`), remove it from inflight, open/update the feature PR immediately (agent-branch → feature branch), report the PR URL in chat, then update the HITL PR gate bead with the PR URL.
-   - **Failure paths** (`OUTCOME: BLOCKED` from any stage): create nothing. The worker already closed its failed chore and built its own remediation — a `stage:fix` chore plus a fresh instance of the failed stage blocked on it. Run the cap backstop (see below); if the parent is at `maxFixRounds`, block the parent instead and record it for shutdown. Remove the inflight entry for this chore; the worker's beads appear in `bd ready` and are picked up in step 7.
+   - **Failure paths** (`OUTCOME: BLOCKED` from any stage): create nothing. The worker already closed its failed chore and built its own remediation — a `stage:fix` chore plus a fresh instance of the failed stage blocked on it. Run the cap backstop (see below); if the parent is at `maxFixRounds`, block the parent instead and record it for shutdown. Remove the inflight entry for this chore; the worker's beads appear in `bd ready` and are picked up in step 7. `post-merge` and `housekeeping` are the exceptions: neither builds a chain, and each leaves its chore **open**, so remove the inflight entry and hand the chore to a human — never re-dispatch it, and for `post-merge` report the escalation bead the check filed.
 7. **Check for newly ready beads**: run `bd ready -l execution:afk`. For each bead not yet tracked:
    - **Chore bead with `stage:*` label** (a worker-built remediation chore or a pre-created stage): find its parent via `bd show <chore-id>` (follow the `parent-child` dep). Run the cap backstop (see below). If under cap: dispatch it via _Dispatching a stage chore_. If at cap: block the parent (`bd update <parent-id> --status blocked --append-notes "<cap> reached"`) and record it for shutdown — create nothing.
    - **Childless `feature` bead, in-flight count < 5, no pending human action**: dispatch a decomposition worker (see _Feature decomposition_ above). Check `pendingHumanAction` with `node skills/workflow/ralph/scripts/pending-gates.mjs` — an unblocked `lifecycle:feature-pr` gate means a feature is awaiting a human merge, so hold new parent features. Gates still blocked behind their own pipeline are parked and do not count.

package/agents/ralph/claude/wake.md

@@ -1,6 +1,6 @@
 ## Wake mechanism (Claude Code — event-driven)
 
-**Mechanism: event-driven — the harness re-invokes you automatically when a background worker completes and delivers that worker's result inline, so there is no poll timer, no sleep, and no log flush.**
+**Mechanism: event-driven — the harness re-invokes you automatically when a background worker completes and delivers that worker's result inline, so there is no poll timer and no sleep.**
 
 ### Spawn
 
@@ -29,11 +29,11 @@ A completion is **delivered, not observed**: Claude Code re-invokes you automati
 Initialize `.agent-cortex/ralph/state.json` as `{ "inflight": [] }` — there is no timer handle to track.
 
 - **inflight[].agentId** — the task ID `Task` returned for that worker; it is the key the delivered completion is correlated to its bead, and the equivalent of `TaskGet`'s identifier when you need to inspect one worker.
-- **inflight[].logLine** — not used on Claude; leave it at `1`. Progress lines (`.agent-cortex/ralph/ralph-<parentId>.log`) are written by the workers themselves and surfaced by the harness with the completion.
+- **No trail bookmark** — nothing to track. Progress is read from the bead itself (`bd show <chore-id>`, `bd provenance log <chore-id>`): the worker writes it, so the harness delivers the completion with the result already in hand.
 
-### Log flush
+### Trail reading
 
-None. There is **no log tailing on Claude**: the completion is delivered with the result already in hand, so there is nothing to flush and nothing to poll. Produce the shared chat summaries from the delivered result instead.
+None beyond the completion itself. There is **nothing to tail and nothing to flush** on Claude: read the completed worker's bead once for its entries and refs, and produce the shared chat summary from the delivered result.
 
 ### Stop