@jaybeeuu/agent-cortex 1.42.0 → 1.43.0

package/.agents/skills/style-versioning/SKILL.md

@@ -54,11 +54,29 @@ Fix status bead showing wrong priority after update
 
 ### Rules
 
+- **Every PR adds a changeset.** CI fails otherwise. The only opt-out is the
+  `no-publish` label (see below).
 - The frontmatter package name must match exactly: `"@jaybeeuu/agent-cortex"`
 - The description should be one or two sentences, user-facing (it goes into CHANGELOG.md)
 - One changeset per PR. If a PR has multiple unrelated changes, use multiple changeset files.
 - The filename doesn't matter to changesets — only the frontmatter and description do.
 
+## The PR gate
+
+`changeset-check` runs on every pull request and fails it unless the PR adds a
+`.changeset/*.md` file. **Publishing is the default; `no-publish` is the only
+opt-out** — skipping a release is an explicit, reviewable decision, never an accident.
+
+| Exemption | Applies to |
+|---|---|
+| `changeset-release/*` head branch, or actor `github-actions[bot]` | the changesets bot's Version Packages PR — it consumes changesets and adds none of its own |
+| `no-publish` label | a PR that genuinely ships nothing |
+
+The `no-publish` label must exist in the repository's label settings — a one-off
+human step (`gh label create no-publish`), not something a PR can ship. If the gate
+fails and the PR really ships nothing, ask for the label; do not manufacture a
+changeset to make it green.
+
 ## After merge to main
 
 The `release` job in `.github/workflows/ci.yml` handles everything automatically:
@@ -72,7 +90,54 @@ The `release` job in `.github/workflows/ci.yml` handles everything automatically
 
 `changesets/action` execs the `version`/`publish` inputs without a shell, so each
 must be a single unquoted command token — keep release logic in pnpm scripts
-(`version-packages`, `publish-package`), never inline shell strings.
+(`version-packages`, `publish-package`, `publish-noop`), never inline shell strings.
+
+### Approve CI on the Version Packages PR
+
+The version PR arrives `BLOCKED` with an empty check list, and nothing is broken:
+`changesets/action` pushes that branch with `GITHUB_TOKEN`, so GitHub parks the CI
+run the push creates behind **“Approve workflows to run”** (`action_required`, zero
+jobs). A parked run reports no checks, so the five required contexts are
+unsatisfiable until someone approves it. Approve it from the PR's merge box, or:
+
+```bash
+run=$(gh run list --branch changeset-release/main --limit 20 \
+  --json databaseId,conclusion --jq 'map(select(.conclusion=="action_required"))[0].databaseId')
+gh api -X POST "repos/{owner}/{repo}/actions/runs/$run/approve"
+```
+
+An approval is per head commit. Every merge to `main` force-updates the version
+branch and starts a fresh parked run, so approve immediately before merging the
+version PR — not once per release. Do not reach for a PAT or GitHub App token to
+skip this: one click is cheaper than a long-lived credential in repository
+secrets, and the `GITHUB_TOKEN` the job already holds cannot approve its own run.
+
+Which of the two publish scripts runs is decided per push, not hard-coded: labels are
+invisible on a push event, so the job resolves the PR merged for the pushed commit via
+the GitHub API and reads its labels — `publish-noop` when the PR carried `no-publish`,
+`publish-package` otherwise. That needs no new secret or scope; the job already holds
+`GITHUB_TOKEN` and `pull-requests: write`. A direct push with no merged PR resolves to
+no labels and so publishes, which keeps a genuine publish of an already-published
+version failing loudly — there is deliberately no idempotency guard.
+
+### Merge method and commit signatures
+
+Land a Version Packages PR with `gh pr merge <n> --squash`. Agent and human commits here are
+GPG-signed by the environment and verify as `valid`; the `github-actions[bot]` commit is
+`unsigned` because `GITHUB_TOKEN` cannot sign. The commit that lands is signed by GitHub,
+which is why `main`'s history reads `valid`: PR #161's unsigned head `fe7ef84` landed as
+`dd347471b1` with `committer=GitHub`, `verified=true`.
+
+Squash re-signs the landing commit; it does not escape an enforced signature rule. GitHub
+evaluates a pull request by creating a test merge commit and checking the commits it
+introduces — head-branch commits included — so an enforced `required_signatures` rule blocks
+a squash merge too, and the remedy is then a signed commit on the branch, not another merge
+method. `allow_merge_commit` is off and `required_linear_history` is on, so a merge commit is
+not an option — squash or rebase only, and only squash lands a commit GitHub signs.
+
+See `docs/commit-signing.md` for the evidence, the ruleset reads that show only
+repository-level rules applying to `main` (a read that covers organization rules too), and the
+human-only follow-ups, including the merge probe that closes AC1.
 
 ### Version lockstep
 
@@ -88,9 +153,15 @@ All version numbers stay in lockstep automatically:
 
 - **Running `pnpm changeset`**: Interactive, wastes tokens. Write the file directly.
 - **Bumping versions manually**: Don't touch `"version"` in `package.json` or `plugin.json`. Create a changeset.
-- **Skipping the changeset**: A PR without a changeset won't trigger a release. The changesets bot will remind you.
+- **Omitting the changeset**: CI fails the PR. Publishing is the default; the only
+  opt-out is the `no-publish` label, which must already exist in the repo's settings.
 - **Wrong bump type**: `patch` for fixes, `minor` for additions, `major` for breakage. When in doubt, ask the user.
 - **Wrong package name in frontmatter**: Must be `"@jaybeeuu/agent-cortex"` exactly.
+- **Merging a Version Packages PR with anything but squash**: the bot's commit is unsigned,
+  and squash is the path this repo has landed on (a rebase merge adds the head-branch commit
+  without signature verification).
+  Squash does not, however, bypass an enforced signature rule — if one is confirmed, the
+  branch needs a signed commit. See `docs/commit-signing.md`.
 
 ## What changed from the old workflow
 

package/.github/workflows/ci.yml

@@ -5,6 +5,12 @@ on:
     branches:
       - main
   pull_request:
+    # The default types (opened/synchronize/reopened) would make the documented
+    # `no-publish` opt-out unreachable: labelling a PR after the check failed
+    # would never re-trigger it, and a manual re-run replays the original event
+    # payload. Label events keep the gate honest in both directions — adding the
+    # label turns it green, removing it turns it red again.
+    types: [opened, synchronize, reopened, labeled, unlabeled]
 
 jobs:
   setup:
@@ -42,6 +48,12 @@ jobs:
 
   changeset-check:
     name: Changeset check
+    # The gate is a pure, idempotent recomputation of the diff plus PR metadata,
+    # so every pull_request event must run it. Do NOT narrow this to the
+    # labels that can change the verdict: GitHub reports a skipped job as a
+    # success (docs.github.com - about-status-checks), so skipping on unrelated
+    # label churn would silently turn a failing gate green and let a
+    # changeset-less PR merge.
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
@@ -49,35 +61,25 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Check for changeset
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      # Publishing is the default: every PR must add a changeset. The only
+      # exemptions are the changesets bot's Version Packages PR (it consumes
+      # changesets and adds none) and PRs explicitly labelled `no-publish`.
+      # Deciding that in code keeps the rule unit-tested; this step only feeds
+      # it the diff and the PR metadata.
+      - name: Require a changeset unless labelled no-publish
         env:
           BASE_REF: ${{ github.event.pull_request.base.ref }}
+          PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          PR_ACTOR: ${{ github.event.pull_request.user.login }}
+          PR_LABELS: ${{ toJSON(github.event.pull_request.labels.*.name) }}
         run: |
-          # Paths that require a changeset when modified
-          VERSIONED_PATHS='extensions/|skills/|agents/|package\.json|plugin\.json'
-
-          changed=$(git diff --name-only "origin/${BASE_REF}...HEAD")
-          echo "Changed files:"
-          echo "$changed"
-
-          versioned=$(echo "$changed" | grep -E "$VERSIONED_PATHS" || true)
-          if [ -z "$versioned" ]; then
-            echo "No versioned paths changed — skipping changeset check."
-            exit 0
-          fi
-
-          changesets=$(echo "$changed" | grep -E '^\.changeset/.*\.md$' | grep -v 'README.md' || true)
-          if [ -z "$changesets" ]; then
-            echo ""
-            echo "::error::This PR modifies versioned paths but does not include a changeset."
-            echo "Run 'pnpm changeset' to add one. See: style-versioning skill."
-            echo ""
-            echo "Versioned paths changed:"
-            echo "$versioned"
-            exit 1
-          fi
-
-          echo "Changeset found: $changesets"
+          git diff --name-status "origin/${BASE_REF}...HEAD" | node scripts/check-changeset.mjs
 
   lint:
     name: Lint
@@ -263,6 +265,22 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # Labels are invisible on a push event, so resolve the PR merged for this
+      # commit through the API and read its labels. No new secret or scope: the
+      # job already holds pull-requests: write, gh is preinstalled, and
+      # GITHUB_TOKEN is already here. A commit with no merged PR (direct push)
+      # resolves to no labels — publish stays the default, so attempting to
+      # publish an already-published version still fails loudly.
+      - name: Resolve publish command
+        id: gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          labels=$(gh api "repos/${{ github.repository }}/commits/${{ github.sha }}/pulls" \
+            --jq '[.[] | select(.merged_at != null) | .labels[].name]')
+          publish=$(node scripts/resolve-publish-command.mjs "$labels")
+          echo "publish=${publish}" >> "$GITHUB_OUTPUT"
+
       - name: Create Release Pull Request or Publish
         id: changesets
         uses: changesets/action@v1
@@ -277,7 +295,9 @@ jobs:
           # committed needs regenerating) before the action commits, so the
           # Version Packages PR always passes the drift gates.
           version: pnpm version-packages
-          publish: pnpm publish-package
+          # pnpm publish-package when the merged PR is unlabelled, pnpm
+          # publish-noop when it carries `no-publish`.
+          publish: ${{ steps.gate.outputs.publish }}
           commit: "chore: version packages"
           title: "chore: version packages"
         env:

package/AGENTS.md

@@ -13,7 +13,7 @@ available in the author's coding sessions.
 
 ```
 agent-cortex/
-├── package.json           # PI package manifest (pi: { extensions, skills, packages })
+├── package.json           # PI package manifest (pi: { extensions, skills }) + pi runtime deps
 ├── plugin.json            # GitHub Copilot plugin manifest — agents, skills, MCP servers
 ├── agents/                # Custom agents — canonical composable <name>/ dirs
 │   ├── *.agent.md         #   generated from <name>/ by scripts/build-copilot-agents.mjs
@@ -38,7 +38,7 @@ agent-cortex/
 ├── claude-extras/        # Hand-authored Claude plugin extras
 │   ├── .mcp.json         # MCP servers (context7, github) — copied into installs
 │   └── scripts/          # statusline-command.sh — copied into installs (executable)
-└── package.json          # PI package manifest (pi: { extensions, skills, packages })
+└── package.json          # PI package manifest (pi: { extensions, skills }) + pi runtime deps
 ```
 
 ## Versioning
@@ -53,6 +53,11 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
 
 ## Coding Conventions
 
+- **Landing method**: pull requests are squash-merged. Merge commits are disabled in the
+  repository settings and `main` requires linear history, so a branch's own commit shape never
+  reaches `main` — bring a behind branch up to date by merging `main` in rather than rebasing it.
+  `docs/commit-signing.md` records why squash is the only landing path that produces a signed
+  commit; the rebase-versus-merge reasoning lives in the `git-workflow` skill.
 - **Never block the main thread**: no `*Sync` functions (`readFileSync`, `spawnSync`, …).
   Tooling code in `bin/`, `scripts/`, `lib/`, `hooks/`, and `test/` must be async —
   enforced by `scripts/check-no-sync.mjs` (runs via `pnpm lint`). Skill-owned
@@ -63,6 +68,12 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
 
 ## Skill Conventions
 
+- **Skills are portable, not repo documentation.** `skills/` is installed onto arbitrary machines
+  (Copilot, pi, Claude Code), so it describes general practice and the author's portable
+  preferences — never how this repository is configured or how to work in it. Facts about this
+  checkout (branch bases, merge method, signature rules, required checks, release mechanics) belong
+  in `AGENTS.md`, `docs/`, or the tracker. Repo-local `.agents/skills/` follows the same rule: a
+  skill is a skill, not a place for this repo's configuration.
 - `SKILL.md` must include a YAML front-matter block with `name` and `description`.
 - `description` must be ≤ 1024 characters. First sentence: what it does. Second: "Use when…".
 - Keep `SKILL.md` near the ~150-line target in `docs/skills/skill-anatomy.md`, overflowing into
@@ -96,6 +107,16 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
   `--output <dir>` is the generate-only form (tests/CI materialiser checks); `ralph`
   is authored natively in `agents-native/` and copied verbatim; the other agents compose from their
   `claude/` harness dirs).
+- The pi package is materialised by `bin/installers/pi.mjs`: `agent-cortex install pi` stages a
+  self-contained pi package in `~/.agent-cortex/pi` (manifest, flat rendered agents, token-substituted
+  skills, a copy of `extensions/`, `token-map.json`, and the bundled `pi.packages` closure under
+  `node_modules/`) and registers that directory with pi through the `pi` CLI — pi's own
+  `~/.pi/agent/settings.json` is read, never written. `--output <dir>` stages only (no registration,
+  no sweep) and `--dry-run` reports the plan. Once registration succeeds, a one-shot migration sweeps
+  the copies the pre-staged-model installer rendered into `~/.pi/agent`, attributing them by name from
+  the package root and recording completion in `~/.agent-cortex/legacy-sweep.json`; `~/.pi/agent/extensions`
+  is never touched. Run it from the main checkout: the staged package is a snapshot of the checkout you
+  invoked, so a run from a ralph worktree stages that worktree's content.
 - Keep orchestration logic in the agent file; extract shared per-task workflow into a skill
   so it can be reused (e.g. ralph delegates per-task stage execution to `run-pipeline-stage`).
 

package/CHANGELOG.md

@@ -1,5 +1,171 @@
 # Changelog
 
+## 1.43.0
+
+### Minor Changes
+
+- b6fe713: `agent-cortex install pi` now sweeps the artifacts the pre-staged-model
+  installer rendered into pi's own user directory. Once the staged package at
+  `~/.agent-cortex/pi` is registered, those copies are a second source of the same
+  agent or skill — the skill-collision diagnostics the staged model exists to
+  remove — so the installer removes the ones it can attribute to agent-cortex:
+  `agents/<name>.agent.md` and `skills/<group>/<name>` for agents and skills it
+  ships or once shipped (`pipeline-worker`, the `migration` skill), plus a
+  `.agent-cortex-install.json` path record left in that directory listing those
+  copies.
+
+  The sweep is a one-time migration, not a standing rule: attribution is by name
+  from the package root, which cannot tell a rendered copy from a file you wrote
+  under the same name, so a finished migration is recorded in
+  `~/.agent-cortex/legacy-sweep.json` — keyed by the pi user directory, never
+  inside it — and nothing there is removed again. A completed migration leaves
+  `~/.pi/agent` with no agent-cortex file in it. Only a migration that removed
+  everything it attributed, from directories it could read, is recorded: a copy
+  that could not be deleted, or a directory that could not be listed, is warned
+  about and retried on the next install, and a record that cannot be written
+  warns without failing an install that has already registered. Files whose name this package
+  does not ship are left alone, and pi's
+  `extensions/` directory is never touched — no installer has ever written there,
+  so its contents are yours. pi's own `settings.json` and `keybindings.json` are
+  never touched either.
+
+  The sweep runs only after registration succeeds, follows the settings file the
+  installer reads (`~/.pi/agent`), and is skipped entirely by `--dry-run` and
+  `--output <dir>`. A pi agent dir relocated with `PI_CODING_AGENT_DIR` keeps its
+  copies: the installer does not inspect it.
+
+- b6fe713: `agent-cortex install pi` now registers the staged package with pi: after
+  staging `~/.agent-cortex/pi` it drives pi's own `pi install` so pi loads the
+  agents, skills, and extensions from that directory. Registration is idempotent
+  by state — a re-run after `git pull && agent-cortex install pi` changes nothing —
+  and a source pointing at a raw agent-cortex checkout is removed first, so exactly
+  one agent-cortex source stays configured. A superseded source that `pi remove`
+  cannot drop fails the install rather than reporting success — two configured
+  sources both load, so leaving both in place is a failed registration, not a
+  warning. The installer still writes nothing into `~/.pi/agent`; it only reads
+  pi's `settings.json` to decide the plan. A missing `pi` CLI warns and prints the
+  exact commands (failing only with `--require-register`), and `--dry-run` prints
+  the registration plan without writing or spawning anything. `--output <dir>`
+  remains the stage-only form.
+- b6fe713: `agent-cortex install pi` now stages a self-contained pi package at
+  `~/.agent-cortex/pi` (manifest, agents, skills, extensions, and the bundled
+  pi-questions / pi-web-access trees) instead of writing into pi's own
+  `~/.pi/agent` directories. Register the staged package with `pi install
+~/.agent-cortex/pi`. `--no-provision` is gone — the required packages travel
+  inside the staged tree — and the installer no longer materialises pi's
+  `settings.json` / `keybindings.json`.
+
+  The committed `pi/settings.json` template drops its `npm:pi-questions` and
+  `npm:pi-web-access@0.10.7` entries for the same reason: once the staged package
+  carries those tools, the `packages` array holds only the optional personal
+  toolset (`@getpipher/vision`, `@hypabolic/pi-hypa`, `context-mode`), so there is
+  one source of truth for `ask_questions` / `fetch_content` instead of two that can
+  drift. Its `../../src/agent-cortex` entry goes too, so the staged package is the
+  only agent-cortex source pi loads.
+
+  The `subagent` extension discovers agents from the package it ships inside as
+  well as from pi's own user agent dir, so a staged package supplies the agents it
+  ships instead of depending on `~/.pi/agent` copies. A source checkout's
+  composable `agents/` tree is left to `agent-modes`, which composes it at runtime;
+  the flat renders committed there are for other harnesses and are not read as pi
+  agents. Frontmatter `tools` written as a YAML sequence is accepted alongside the
+  scalar form.
+
+### Patch Changes
+
+- e15cf37: Stop documenting a fixed local-bin `bd` path as the authoritative bd binary. The migration technical-direction doc now describes `bd` as resolved from `PATH` with `BD_PATH` as the override, warns against pinning an orphaned binary (schema-version mismatch risk), and its script-package constraint reflects the post-D2 root workspace membership.
+- 937f610: Document the commit-signing expectation behind the "Commits must have verified signatures"
+  merge block. Agent commits are GPG-signed by the environment and verify as `valid`; the
+  `github-actions[bot]` commit on a Version Packages PR is `unsigned` because `GITHUB_TOKEN`
+  cannot sign. The squash merge GitHub performs re-signs the commit that lands, which is why
+  `main`'s history reads `valid` — but a squash merge does **not** escape an enforced signature
+  rule, since GitHub checks head-branch commits through its test merge, so the remedy in that
+  case is a signed commit rather than a different merge method. The new `docs/commit-signing.md`
+  records the evidence, the ruleset reads that show no signature rule applied to `main` at
+  either repository or organization level (while org ruleset definitions stay unreadable), the
+  open acceptance criterion with its human merge probe, and the release policy: land Version
+  Packages by squash merge, never put a signing key in CI secrets, with an explicit
+  contingency if an organization-level signature rule turns out to be enforced.
+  `style-versioning` points at it.
+- 0f9b7f8: Drop the hardcoded skill blurb from the pi `session-start` extension. The blurb advertised three
+  skills with `/skill:<name>` syntax that pi cannot resolve, and pi's own system prompt already lists
+  every discovered skill with its absolute `SKILL.md` path, so the local copy was incomplete and
+  drifted from `skills/` silently — verbatim text an agent reads first each session (and on
+  2026-10-27 misread a missing-extension outage as a missing-skills problem). Session start now
+  injects only the project context files (AGENTS.md, `docs/user-preferences.md`). The extension moves
+  to `extensions/session-start/` (`index.ts`, `package.json`, `README.md`, `index.test.ts`) per the
+  one-directory-per-extension convention; the new test pins the contract: no `/skill:` syntax, no
+  hardcoded skill names, context files injected when present, nothing injected when absent.
+- 6be3679: Stop the Release job re-publishing an already-published version. Every PR now
+  has to add a changeset unless it is labelled `no-publish` (the changesets bot's
+  Version Packages PR is exempt), and the Release job resolves the merged PR's
+  labels for the pushed commit before choosing between `publish-package` and the
+  new `publish-noop` script. `README.md` and the `style-versioning` skill document
+  the gate, including the out-of-band requirement that the `no-publish` label exists
+  in the repository's label settings before the opt-out can work.
+- f86c767: `agent-cortex install pi` no longer registers the git worktree it was invoked from as the pi package source. When the package root is a linked worktree (its `.git` is a file and `git rev-parse --git-common-dir` differs from `--git-dir`), the settings `packages` entry now resolves to the main checkout, with a warning naming the checkout that was registered instead. Previously a run inside `.agent-cortex/worktrees/<id>` left `~/.pi/agent/settings.json` pointing at that gitignored, ephemeral worktree — which dangles as soon as the worktree is removed.
+- 0ad2576: Fix subagents starting with no tools at all. `agent-cortex install pi` rendered
+  each generated agent's tool list as one space-separated scalar
+  (`tools: "bash read grep find task …"`), but every consumer splits that scalar on
+  commas: the subagent extension turned it into `pi --tools "<one bogus name>"`,
+  whose allowlist matched no tool, so delegated agents (ralph, pipeline workers)
+  ran with only MCP tools and reported the `task` tool — and every other tool — as
+  missing. The pi renderer now emits the comma-separated form that
+  `parseFrontmatter`, the subagent extension, and `pi --tools` all agree on;
+  `parseToolList` in the subagent extension and agent-modes' flat-frontmatter
+  parser accept comma- and whitespace-separated lists so a re-render cannot
+  silently zero out a tool list again; and a round-trip test asserts a rendered
+  agent's tools survive the parse.
+- 65cb7f8: The `git-workflow` skill now says how to bring a behind branch up to date, and
+  why the answer is usually "merge the base in" rather than "rebase". `git rebase`
+  drops merge commits and the patches they carry, so rebasing a branch that has
+  already merged the base silently reverts what that merge resolved — the conflict
+  resolutions, and any fix from the base the merge brought in — and the result
+  reads like a regression in the branch's own change. `--rebase-merges` keeps the
+  structure but re-opens the same conflicts, so it earns its cost only when the
+  branch history is the deliverable. Rebasing stays right for a linear branch that
+  has not been reviewed yet, and then it needs `--force-with-lease`.
+
+  The choice follows from the repository's landing method, not from taste: a squash
+  merge collapses the branch, so its shape never reaches the base branch, while a
+  rebase-and-merge requires linear history and therefore a rebase before the first
+  review rather than after a merge. `AGENTS.md` now records this repository's
+  answer — squash merge, merge commits disabled, `main` requires linear history —
+  because that is a fact about this checkout, not portable practice.
+
+- 2ae24da: Document what `disable-model-invocation` actually does and how each harness handles it: preserved and honoured by pi and Claude Code, honoured by Copilot CLI but at the cost of model-mediated invocation. Corrects the front-matter guidance in `docs/skills/skill-anatomy.md`, which described the field as affecting how the body is interpreted.
+- 5da1d45: Make pipeline-stage workers prove they delivered, and stop dispatch from being
+  improvised.
+
+  A stage worker's `---REPORT---` was taken at face value: nothing instructed it to
+  commit or push, and nothing checked the worktree afterwards. A worker could
+  report `OUTCOME: SUCCESS` and leave its changes uncommitted, and ralph would
+  advance the parent and open the feature PR from a branch holding none of the
+  work. Six runs needed a human to finish the tree by hand.
+
+  - The stage contract now requires delivery: the stage-runner prompt and the
+    code, fix, and document playbooks commit and push before reporting, and the
+    REPORT gained `COMMIT`, `PUSHED`, and `PR` fields.
+  - `scripts/lib/verify-worker-tree.mjs` checks the worktree itself — clean tree,
+    at least one commit ahead of the recorded base — so ralph gates each stage on
+    evidence rather than on the worker's prose.
+  - ralph stops and reports a missing subagent tool instead of backgrounding
+    `pi -p … &`. That substitution has no completion signal, so a finished worker
+    and a killed one look identical — the trap that produced the buffered-log and
+    post-exit liveness misreadings.
+  - `token-map.json` records that pi's `task`/`read_agent`/`wait_for_agents` come
+    from this repo's `extensions/subagent`, not from pi.
+
+- 931a20e: Document the one manual step in the release loop: the Version Packages PR arrives
+  `BLOCKED` with an empty check list because `changesets/action` pushes that branch
+  with `GITHUB_TOKEN`, so GitHub parks the CI run the push creates behind "Approve
+  workflows to run" and a parked run reports nothing. Approve it — merge box click,
+  or the documented `gh api … /approve` one-liner — and the five required checks
+  start. The approval is per head commit, so it is needed again after any further
+  merge to `main`, which force-updates the version branch. Adding a PAT or GitHub App
+  token would let the bot trigger its own CI, but one click per release is a better
+  trade than a long-lived credential in repository secrets.
+
 ## 1.42.0
 
 ### Minor Changes