@jaybeeuu/agent-cortex 1.40.0 → 1.41.0

package/docs/ideas/test-planning-stage-bead-in-feature-planning.md

@@ -0,0 +1,68 @@
+# Idea: Test-planning stage bead in feature planning
+
+## Status
+Absorbed into bead `agnt-ctx-rig0` (2026-09-22) — the verification beads in that design's
+design stage generalise this idea's provable-outcome / completion-criterion motivation. Not a
+standalone bead.
+
+## Created
+2026-09-03
+
+## Problem
+Tests get under-planned: features are split into beads around implementation
+(code, verify, review) but nobody plans *what* needs testing or *how we know
+it's done* before the work starts. Verification ends up ad hoc — a verify
+stage runs whatever tests exist rather than the tests the feature actually
+needs.
+
+## Who benefits
+- The agent running the pipeline (ralph / run-pipeline-stage) — has an explicit
+  test plan to execute against instead of improvising a verify pass.
+- The human reviewer — a stated definition of done for testing makes the PR
+  gate checkable ("did the planned tests land?").
+- The feature itself — testability becomes a planning output, not an accident.
+
+## Proposed outcome
+When a feature is planned, the planning phase also produces a
+test/verification planning stage bead: what behaviour to test, at what level
+(unit/integration/e2e), key cases and edge cases, and an explicit completion
+criterion — the answer to "how do we know it's done?" The bead sits between
+feature planning and implementation, so test planning happens once at plan
+time rather than being rediscovered per-task.
+
+## Validity check
+- Evidence we already have: verify-stage chores exist today but run generic
+  checks (`playbooks/verify.md`, `run-pipeline-stage`); nothing at plan time
+  defines the feature's test surface or a testing definition of done — PR
+  reviews have to reconstruct what should have been tested.
+- Riskiest assumption: a test-plan bead is actually useful to the executing
+  agent and isn't just ceremony that duplicates what the code bead already
+  implies ("write tests that cover this feature"). Cheap to validate: try it
+  on one feature and judge whether the verify stage runs a materially better
+  test pass.
+- What would invalidate this idea: if RALPH's verify stage already produces
+  adequate coverage decisions from the playbook alone, the extra bead adds
+  overhead without changing outcomes.
+
+## Constraints
+- Pipeline shape is fixed by the existing bead/pipeline contract
+  (create-task chores, ralph stage dispatch) — the new bead type must slot in
+  without a pipeline redesign.
+- No new runtime for test execution — the bead plans; existing verify tooling
+  executes.
+- Must stay lightweight: test planning for its own sake is the failure mode.
+
+## Next validation step
+Run a two-feature pilot: for the next two planned features, hand-write a
+test/verification plan bead (without wiring it into the pipeline) and compare
+the resulting verify passes against a control feature planned the current
+way. If the planned features demonstrably get better test coverage, wire the
+bead type into the planning skill.
+
+## Notes
+- User framing: "planning, then test/verification planning — how do we know
+  it's done?" The completion criterion is the heart of the idea, not the bead
+  itself.
+- Priority: medium — next planning-skill iteration, not blocking current work.
+- The definition-of-done answer could eventually feed the HITL PR gate
+  (reviewer checks planned-tests-vs-landed-tests).

package/docs/ideas/worktree-housekeeping-for-closed-beads.md

@@ -0,0 +1,39 @@
+# Idea: Worktree housekeeping for closed beads
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-09-13
+
+## Problem
+Ralph runs each bead in a dedicated worktree under `.agent-cortex/worktrees/<parent-id>` and only cleans up when a human manually removes it — the `git-workflow` skill's "Worktree lifecycle" step is discretionary, not enforced. Closed, merged beads leave their worktrees behind, and crashed or abandoned runs leave orphaned ones. The worktree set drifts from the actual bead/PR state with no mechanism to converge it.
+
+## Who benefits
+- The author, who currently accumulates stale worktrees and must identify and remove them by hand.
+- Future ralph/agent sessions, which skip reading a worktree set polluted by dead state and avoid accidentally reusing an abandoned worktree for a new bead.
+- Confident teardown: knowing a merged feature's worktree is gone makes "is this still live?" checks unnecessary.
+
+## Proposed outcome
+Two tiers of cleanup:
+- **Minor (deterministic)**: when a ralph run's PRs merge and its beads close, the associated worktrees are removed as part of the close-off — no LLM judgement needed.
+- **Major (broader)**: a reusable housekeeping pass that finds and reports orphaned or abandoned worktrees (no corresponding live bead, no open PR / stale branch), usable on demand.
+
+Cleanup is safe-first: it must not remove a worktree whose branch or bead is still active, and unmerged/abandoned worktrees should be surfaced rather than silently deleted.
+
+## Validity check
+- Evidence we already have: `git-workflow` SKILL.md already documents "after the PR is merged or closed, clean up the worktree" as a manual step — the intent exists, only the enforcement is missing. Ralph already knows the full mapping of bead → worktree → PR, so it has all the data a deterministic cleanup needs.
+- Riskiest assumption: worktree state can be derived reliably from bead state + git state (that a "closed bead" always means its worktree is safe to remove, and that orphan detection can distinguish abandoned worktrees from merely idle ones). If the bead/PR mapping is lossy — e.g. beads close without recording whether the PR merged — the deterministic rule could remove an unmerged feature's worktree.
+- What would invalidate this idea: if the cost of a false positive cleanup (losing an unmerged feature's worktree or its local branches) outweighs the cost of the current manual drift; or if ralph's lifecycle already converges worktrees in practice and the observed accumulation is negligible.
+
+## Constraints
+- Human merge gates stay non-negotiable — cleanup must never imply or require auto-merging.
+- No destructive action on anything the mapping can't positively classify (unmerged features, active beads, open PRs) — default to reporting.
+- Both the skill and the deterministic script live in this repo (`skills/`, `scripts/`); final split between skill, script, or both is a design-time decision.
+
+## Next validation step
+List worktrees across a few real (recently completed) ralph sessions and compare against bead/PR state to measure actual accumulation and test whether closed-bead → safe-to-remove always holds. This both quantifies the problem and de-risks the riskiest assumption.
+
+## Notes
+- Interview left two design-time decisions open: (1) whether cleanup lives as a skill, a script, or both; (2) whether it runs at session start, inside the ralph loop, or as an on-demand command — "maybe both" was the lean.
+- Related backlog neighbours worth reconciling when this is planned: `deployment-beads-for-post-merge-pipelines.md` (post-merge lifecycle), `record-ideas-as-beads.md` if the major housekeeping pass becomes a scheduled bead.

package/docs/technical-direction/harness-config.md

@@ -0,0 +1,161 @@
+# Technical Direction: Harness config and third-party extensions
+
+## Problem and target outcome
+
+- **What we are solving.** agent-cortex ships agents and skills to three harnesses (pi, Claude
+  Code, Copilot CLI) and needs a declared, reproducible set of *third-party* extensions those
+  agents depend on (pi packages / Claude plugins). Two bespoke mechanisms currently exist and
+  disagree: `main` declares packages in `package.json` → `pi.packages` and provisions them from
+  `lib/pi-packages.mjs`; the unmerged pi-harness epic (`agnt-ctx-dfq3`) declares them in
+  `pi.extensions.json` / `claude.extensions.json` and provisions them via `agent-cortex ext
+  install`. **Neither file is read by any harness** — both are agent-cortex inventions.
+- **Target outcome.** One idiomatic mechanism per harness: extensions the agents *require* are
+  resolved by the harness's native dependency field; extensions that are *optional* are declared
+  in the harness's committed settings template. No bespoke manifest format survives.
+- **Why now.** The epic is unmerged and diverging from `main` (7 commits behind), and PR #142
+  (`ext prune`) was closed as redundant with the harnesses' own package management. Keeping both
+  models means keeping the drift the original idea set out to remove.
+
+## Current-state constraints
+
+- **Public package.** `publishConfig.access: public`, npm `@jaybeeuu/agent-cortex@1.40.0` — every
+  bundled dependency or committed template affects anyone who installs the package, not just the
+  author.
+- **pi is idiomatic two ways.** Machine state is `~/.pi/agent/settings.json` → `packages[]`, owned
+  by `pi install/remove/list`. A package's own resource declarations live in `package.json` → `pi`
+  (`extensions`, `skills`, `prompts`, `themes`); third-party pi packages are depended on via
+  `dependencies` + `bundledDependencies` and referenced through `node_modules/…`. **There is no
+  `pi.packages` field** — pi ignores it.
+- **Claude is idiomatic two ways.** Machine state is `~/.claude/settings.json` → `enabledPlugins`
+  + `extraKnownMarketplaces`. A plugin declares other plugins in `.claude-plugin/plugin.json` →
+  `dependencies`, which Claude Code resolves and auto-installs.
+- **Copilot has no dependency mechanism.** `copilot plugin install/list/uninstall` exists, but its
+  state is auto-managed `~/.copilot/config.json` (not committable) and `plugin.json` declares no
+  dependencies.
+- **The epic already built two-thirds of the target.** Unmerged commit `afab2c6` (F3) materialises
+  `pi/settings.json` + `pi/keybindings.json` from committed templates with merge-keep-personal and
+  the CLI owning `packages`; `1ff212d` (F4) makes bundled pi extensions load via package
+  registration. Only `1e0e970` (F5, the bespoke manifests) is off-direction.
+- **Unknowns resolved during this memo:** pi bundling is feasible (see Validation plan); Claude
+  dependency auto-install is real but cross-marketplace needs an allowlist; Claude currently
+  declares **zero** third-party plugins.
+
+## Options considered
+
+### Option A: one bespoke config per harness
+
+- **Approach.** A `config/<harness>.json` (or the epic's `*.extensions.json`) holds settings and
+  the extension list; the CLI provisions from it.
+- **Pros.** Uniform across harnesses; full control; explicit single place to look.
+- **Cons.** A third format that neither harness reads; duplicates the native `packages` /
+  `enabledPlugins` fields; re-creates the manifest-vs-machine drift the idea exists to remove.
+- **Risks.** The redundancy that made `ext prune` (F6) not worth building.
+
+### Option B: native dependency fields + committed settings templates *(recommended)*
+
+- **Approach.** Required extensions → `dependencies` + `bundledDependencies` (pi) and
+  `.claude-plugin/plugin.json` `dependencies` (Claude). Optional extensions → the harness's own
+  committed settings template (`pi/settings.json` `packages`; `claude/settings.json`
+  `enabledPlugins` + `extraKnownMarketplaces`), materialised with merge-keep-personal. Drop the
+  bespoke manifests, the `ext install`/`ext prune` family, and the separate diff command —
+  `agent-cortex install <harness>` reconciles.
+- **Pros.** Idiomatic; no bespoke format; each harness resolves its own required deps; the
+  optional list lives in the file the harness already reads, so `pi list` / `claude plugin list
+  --json` are the exact machine-state comparison; drift self-heals on install.
+- **Cons.** pi bundling shifts update cadence to agent-cortex releases and grows the tarball;
+  Claude cross-marketplace deps need an allowlist; the committed template also carries personal
+  settings; Copilot gets nothing.
+- **Risks.** Loading TS extensions from bundled `node_modules/`; maintaining the Claude
+  cross-marketplace allowlist.
+
+### Option C: fully delegate to the harnesses
+
+- **Approach.** pi bundles its deps, Claude auto-installs plugin deps, `install` only registers;
+  there is no optional layer at all.
+- **Pros.** Least code; no declaration surface to maintain.
+- **Cons.** No way to declare the optional/opt-in personal toolset; the original problem —
+  "the toolset isn't reproducible or documented" — goes unsolved for everything not strictly
+  required.
+- **Risks.** Silently drops the reproducibility goal.
+
+## Recommendation
+
+**Option B.** It is the only option that satisfies both halves of the problem: *required*
+extensions resolve through the harness's own mechanism (so an agent's tools can't be missing),
+and *optional* ones stay declared and reproducible without inventing a format the harnesses
+ignore. It also deletes the most code — the two competing bespoke models, `lib/pi-packages.mjs`,
+and the `ext` command family — rather than adding a third.
+
+Alternatives were not chosen because: **A** keeps a third format and the drift it causes; **C**
+abandons the declared-toolset goal that started the work.
+
+**Concrete disposition:** salvage the epic's F3 (`afab2c6`) and F4 (`1ff212d`) — they *are* the
+settings-template and bundled-dependency mechanisms — drop F5/F6 (`1e0e970` and PR #142), close
+the epic, and delete `pi.packages` + `lib/pi-packages.mjs` from `main`.
+
+## Tradeoffs accepted
+
+- **pi bundling changes update cadence.** Bundled pi packages are pinned by agent-cortex's
+  `package.json` ranges and update when agent-cortex releases, not via `pi update`. Accepted: it
+  makes the required toolset a property of agent-cortex rather than of the machine.
+- **Tarball size.** `pi-web-access` pulls 5 runtime deps (readability, linkedom, p-limit, turndown,
+  unpdf). Accepted for the required set; the optional set stays provisioned, not bundled.
+- **Claude cross-marketplace allowlist.** If a required Claude plugin lives in another
+  marketplace, agent-cortex's `marketplace.json` must list it in
+  `allowCrossMarketplaceDependenciesOn`. Accepted; currently moot (zero declared plugins).
+- **Committed personal settings.** `pi/settings.json` already carries models/theme; the template
+  model makes the repo own the whole pi settings surface. Accepted; F3's merge preserves personal
+  keys and only `packages` is CLI-owned.
+- **Copilot gets no mechanism.** Documented exception — the README says `copilot plugin install`.
+  Accepted because Copilot has no dependency field and no committable config.
+- **No dedicated diff command.** A read-only `status` is deferred until drift is shown to hurt.
+
+## Validation plan
+
+Run before implementation (three already run during this memo):
+
+1. **Can `pi-questions` / `pi-web-access` be bundled and load from `node_modules/`?** ✅ *Ran.*
+   `pi-questions@0.3.4` is a single extension file with no deps or install-time state;
+   `pi-web-access@0.10.7` is an extension + skills with 5 runtime deps. Both are conventional pi
+   packages — bundling is feasible. Success signal: a scratch package depending on both loads
+   `ask_questions` / `fetch_content` in a fresh pi session.
+2. **Does Claude's `plugin.json` `dependencies` auto-install from agent-cortex's marketplace?**
+   ✅ *Ran.* Yes, but cross-marketplace deps require `allowCrossMarketplaceDependenciesOn` in the
+   root `marketplace.json`, and version constraints need `{plugin-name}--v{version}` git tags.
+3. **Does F3 reconcile `packages` when the template drops one?** ✅ *Ran.* Yes — the CLI owns
+   `packages` outright, so removing an entry from the template removes it on next install. The
+   documented limitation is the reverse (ad-hoc `pi install` entries don't persist), which is
+   intended.
+
+Still to run before shipping: a scratch end-to-end install on a clean `HOME` proving a required
+pi extension loads from `node_modules/` and an optional one is materialised from the template.
+
+## Revisit triggers
+
+- pi or Claude ship a first-class *optional* dependency field, making the settings template
+  unnecessary.
+- Claude still declares zero third-party plugins after the migration — then Claude parity is
+  speculative and should be dropped rather than maintained.
+- Bundling `pi-web-access`'s native-ish dependency tree (unpdf, linkedom) proves brittle or
+  unacceptable on a fresh machine.
+- Copilot gains a committable config or a plugin dependency field — revisit the documented
+  exception.
+- Drift between the committed template and the machine becomes a recurring annoyance — add the
+  deferred read-only `status`.
+
+## References
+
+- pi docs, *Settings* and *Packages* (installed at
+  `…/@earendil-works/pi-coding-agent@0.85.1/docs/settings.md`, `…/docs/packages.md`): `packages`
+  array is the machine store; the `pi` manifest keys are `extensions`/`skills`/`prompts`/`themes`;
+  other pi packages are bundled and referenced through `node_modules/`.
+- Claude Code, *Constrain plugin dependency versions* — https://code.claude.com/docs/en/plugin-dependencies
+  (auto-install, cross-marketplace allowlist, tag naming).
+- Claude Code, *Settings* — https://code.claude.com/docs/en/settings (`enabledPlugins`,
+  `extraKnownMarketplaces`).
+- GitHub Copilot CLI, *Plugin reference* — https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
+  and *Configuration directory* — https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference
+- Code evidence: `package.json` (`pi.packages`), `lib/pi-packages.mjs` (main's provisioner);
+  `pi.extensions.json`, `claude.extensions.json`, `lib/extension-manifest.mjs` (epic F5, `1e0e970`);
+  `bin/installers/pi.mjs` settings materialisation (epic F3, `afab2c6`);
+  `docs/ideas/extension-manifests.md` (the originating idea).

package/docs/technical-direction/migration-execution-labels.md

@@ -1,11 +1,15 @@
-# Technical Direction: Execution-Label Migration Tooling (two-axis model)
+# Technical Direction: Migration Tooling (two-axis model)
 
 ## Problem and target outcome
 
 - Migrate all beads workspaces from `implementation-type:afk|hitl` to `execution:afk|hitl`
   (strict rename, agent-agnostic) as part of the two-axis workflow model epic.
-- Provide a repo-agnostic tool + skill any workspace can run, and a single-package.json
-  script tooling story across the agent-cortex repo.
+- Migrate loose idea markdown files (`docs/ideas/*.md`) to first-class `kind:idea` beads
+  in any workspace.
+- Both migrations are **steps in one versioned migration command** — `agent-cortex migrate`
+  (aliased `ctx migrate`), which detects a repo's current migration version and applies
+  ordered steps up to the latest. Repo-agnostic tool + skill any workspace can run, and a
+  single-package.json script tooling story across the agent-cortex repo.
 
 ## Current-state constraints
 
@@ -22,6 +26,8 @@
   — they remain workspace members with their own package.json.
 - `node_modules` gitignored; per-skill modules are installed manually today — a fragility in
   fresh clones and PI-installed contexts.
+- The CLI (`bin/agent-cortex.mjs` + `lib/cli.mjs`) is already zero-dep stdlib-only and is the
+  natural home for a migrate command; it currently wires only `install <harness>`.
 
 ## Decisions (locked in planning session)
 
@@ -45,28 +51,40 @@
 - Fresh-clone/installed-context verification: `pnpm install` at root then
   `pnpm -r typecheck` + `pnpm -r test` (or root `node --test` wiring) cover all scripts.
 
-### D3: Migration tool shape
-
-- Script: `skills/productivity/migration/scripts/rename-execution-labels.mjs` — zero-dep,
-  `// @ts-check` + JSDoc.
-- Behavior:
-  1. Enumerate: `bd list --label-pattern 'implementation-type:*' --json`.
-  2. Group bead ids by label value (afk | hitl). A bead carrying both gets both execution labels.
-  3. Dry-run (default): print per-bead plan + summary counts; zero writes; exit 0.
-  4. Apply (`--apply`): batched `bd label add execution:<v> <ids...>` then
-     `bd label remove implementation-type:<v> <ids...>` per group.
-  5. Idempotent: re-run finds zero targets → no-op.
-  6. Fail loudly if `bd` unavailable or any subcommand errors.
-- Scope: rename ALL beads carrying `implementation-type:*` (including closed) — the F7
-  acceptance "zero implementation-type:* labels remain" requires it, and bd label history
-  tolerates it.
+### D3: Migration command — versioned registry in the CLI
+
+- Command: `agent-cortex migrate` (alias `ctx migrate`), wired into `bin/agent-cortex.mjs`
+  + `lib/cli.mjs` (parseArgs + buildHelpText), zero-dep stdlib-only like the rest of the CLI.
+- A **versioned migration registry**: each step declares the version it migrates to.
+  `migrate` detects the current version of the target repo's state and applies each step in
+  order up to the latest. Steps:
+  1. **v1: label rename** (F1) — `implementation-type:afk|hitl` → `execution:afk|hitl`:
+     `bd list --label-pattern 'implementation-type:*' --json`; group ids by label value
+     (a bead with both gets both); dry-run default (per-bead plan + summary, zero writes,
+     exit 0); `--apply` batched `bd label add execution:<v> <ids...>` then
+     `bd label remove implementation-type:<v> <ids...>` per group; idempotent re-run
+     (zero targets → no-op); fail loudly if `bd` missing or a subcommand errors.
+     Scope: ALL beads including closed (F7 acceptance "zero implementation-type:* labels
+     remain" requires it; bd label history tolerates it).
+  2. **v2: ideas → beads** (F2) — `docs/ideas/*.md` (default, `--dir` override) →
+     `kind:idea` beads: map template sections to bead fields (Problem→--description,
+     How→--design, When/Priority/Validity/Constraints/Notes→--notes, referential→--context),
+     `bd create -l kind:idea -p <preserved priority, default P4>`; preserve content
+     fidelity (keep section markers inside fields); dry-run; safe deletion order
+     (docs/ideas/ + new-idea.sh only after F3 lands); `record-ideas-as-beads.md` migrates
+     itself last.
+- Shared plumbing: preflight (detect current version), `--dry-run` (default), `--apply`,
+  per-step verification, and a final summary. Do NOT run v1 against agent-cortex's own
+  .beads — the repo cutover is feature F7 (landed after skill updates so ralph never
+  deadlocks).
 
 ### D4: Migration skill
 
 - Location: `skills/productivity/migration/SKILL.md` (productivity = workflow tooling).
-- Docs the full sequence for any workspace: preflight (count via `bd label list-all`),
-  dry-run, apply, post-checks (grep stale refs; `bd ready -l execution:afk` smoke), plus
-  pointers to idea-file migration (F2) and skill/doc updates (F3/F4/F5/F6).
+- Docs the full sequence for any workspace: preflight (current-version detection),
+  `agent-cortex migrate` dry-run, apply, post-checks (grep stale refs; `bd ready -l
+  execution:afk` smoke), plus pointers to idea-file migration (F2) and skill/doc updates
+  (F3/F4/F5/F6).
 - Repo-agnostic: no agent-cortex-specific paths in the runnable steps.
 
 ### D6: npm packaging hygiene (no build step — F9)
@@ -106,17 +124,31 @@
 - Cons: 3 orphaned mini-workspaces, manual install fragility, resolution doc dance
   (`<skill-scripts>/node_modules/.bin/tsx`), contradicts single-package.json preference.
 
+### Option D: standalone one-off migration script (original D3, superseded)
+- Was: `skills/productivity/migration/scripts/rename-execution-labels.mjs` as a standalone
+  script with its own skill. Superseded by the unified `migrate` command: the label rename
+  is migration step v1 inside the same versioned registry as the idea-file migration (F2),
+  sharing preflight/dry-run/verify plumbing. Rationale (user directive, 2026-09-13): the
+  target is a migration *command* that converts any given repo from the current version to
+  the latest — one surface, not N ad-hoc scripts; also aligns with the planned `ctx`
+  alias/version/update surface (docs/ideas/ctx-alias-version-and-update-commands.md).
+
 ## Tradeoffs accepted
 
 - Scripts use JSDoc annotations where types matter; `tsc --noEmit` with `checkJs` keeps a
   typecheck gate at root.
 - Closed beads get their history labels renamed — accepted for a clean label space.
+- migrate command grows the CLI surface beyond `install`; kept small (one register of
+  versioned steps) to avoid a second mechanism drifting from bd's own state.
 
 ## Validation plan
 
 - F1-T3: scratch beads workspace (temp dir): create test beads with both labels + a dep pair,
   dry-run (assert zero writes), apply, verify rename, re-run idempotence, `bd ready -l
   execution:afk` smoke, then run the migration skill end-to-end once.
+- F2-T1: scratch repo with several idea `.md` files: `agent-cortex migrate` v2 dry-run
+  (zero writes), apply, verify kind:idea beads with content fidelity + priorities, delete
+  file flow, re-run idempotence.
 - F8-T3: fresh clone (or temp copy) + `pnpm install` at root; `pnpm -r typecheck` and
   `pnpm -r test` green; scripts execute via bare `node`.
 
@@ -125,8 +157,13 @@
 - A future script needs third-party deps at runtime → revisit D1 (either root dep or
   per-package re-introduction).
 - New extension with conflicting devDeps → revisit D2 membership rules.
+- A third migration step appears → extend the registry in place; if steps start sharing
+  little plumbing, revisit the unified-command decision (Option D).
 
 ## References
 
-- Code evidence: `skills/*/scripts/package.json` (3 orphaned), root `package.json` +
-  `pnpm-workspace.yaml`, bd CLI help (`bd list`, `bd label`), epic `agnt-ctx-s5xd` notes.
+- Code evidence: `bin/agent-cortex.mjs` + `lib/cli.mjs` (CLI surface), `skills/*/scripts/
+  package.json` (3 orphaned), root `package.json` + `pnpm-workspace.yaml`, bd CLI help
+  (`bd list`, `bd label`, `bd create`), epic `agnt-ctx-s5xd` notes.
+- Idea file: `docs/ideas/ctx-alias-version-and-update-commands.md` (ctx alias + version/update
+  surface that `migrate` joins).

package/extensions/agent-guardrails/README.md

@@ -0,0 +1,45 @@
+# Agent Guardrails
+
+Appends behavioural circuit-breakers to the PI system prompt once per user prompt.
+
+This is the first slice of `docs/ideas/improve-pi-system-prompt.md`: the highest-leverage
+token reduction is behavioural, not structural. The extension injects a stable block via
+the `before_agent_start` hook — which fires once per user prompt, before the agent loop — so
+the rules apply to every turn of the run without rewriting Pi's default prompt.
+
+## Rules
+
+- **Circuit-breakers** — two strikes then stop; never repeat a tool call without a stated
+  rationale; check in when a cycle produces no progress.
+- **Check-in triggers** — stop and present options when retries fail, the requirement is
+  ambiguous, a decision with trade-offs is needed, scope must expand, an action is
+  destructive, or you are blocked.
+- **Atomic changes** — one concern per change; smallest diff that works; no tangential
+  refactoring or cleanup.
+
+A structured workflow (a skill or pipeline stage with its own explicit retry and check-in
+rules) takes precedence where it is explicit.
+
+## Structure
+
+```
+agent-guardrails/
+├── README.md           # This file
+├── index.ts            # Extension entry point — appends on before_agent_start
+├── guardrails.ts       # The guardrails text + appendGuardrails composition
+└── guardrails.test.ts  # Composition tests
+```
+
+## Testing
+
+```bash
+cd extensions/agent-guardrails
+node --test --import tsx/esm guardrails.test.ts
+```
+
+## Design notes
+
+- The block is a stable constant appended after any chained system-prompt changes, so the
+  prompt-cache prefix is preserved.
+- `appendGuardrails` is idempotent — a prompt that already carries the marker is returned
+  unchanged, so a duplicate extension load cannot double the rules.

package/extensions/agent-guardrails/guardrails.test.ts

@@ -0,0 +1,42 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { GUARDRAILS, GUARDRAILS_MARKER, appendGuardrails } from "./guardrails.ts";
+
+// ─── appendGuardrails ─────────────────────────────────────────────────────────
+
+describe("appendGuardrails", () => {
+  it("appends the guardrails block after the base prompt", () => {
+    const result = appendGuardrails("You are a helpful agent.");
+
+    assert.ok(result.startsWith("You are a helpful agent."));
+    assert.ok(result.includes(GUARDRAILS));
+  });
+
+  it("preserves a chained base prompt from earlier handlers", () => {
+    const base = "Base prompt.\n\n---\nAgent mode instructions.";
+    const result = appendGuardrails(base);
+
+    assert.ok(result.startsWith(base));
+  });
+
+  it("trims trailing whitespace before appending", () => {
+    const result = appendGuardrails("Base prompt.\n\n");
+
+    assert.equal(result, `Base prompt.\n\n${GUARDRAILS}`);
+  });
+
+  it("is idempotent when applied twice", () => {
+    const once = appendGuardrails("Base prompt.");
+    const twice = appendGuardrails(once);
+
+    assert.equal(twice, once);
+    assert.equal(twice.split(GUARDRAILS_MARKER).length - 1, 1);
+  });
+
+  it("returns the prompt unchanged when the guardrails are already present", () => {
+    const existing = `Base prompt.\n\n${GUARDRAILS}`;
+
+    assert.equal(appendGuardrails(existing), existing);
+  });
+});

package/extensions/agent-guardrails/guardrails.ts

@@ -0,0 +1,66 @@
+/**
+ * Behavioural guardrails for the PI system prompt.
+ *
+ * The first slice of docs/ideas/improve-pi-system-prompt.md: hard circuit-breakers
+ * against wasted retries, explicit check-in triggers, and atomic-change discipline.
+ * Kept as a stable constant so it can be appended to every turn's system prompt
+ * without invalidating the prompt-cache prefix.
+ *
+ * The marker doubles as an idempotency guard: if a chained system prompt already
+ * carries the block (e.g. the extension loaded twice), it is not appended again.
+ */
+
+export const GUARDRAILS_MARKER = "## Operating discipline (agent-cortex)";
+
+export const GUARDRAILS = `${GUARDRAILS_MARKER}
+
+Behavioural circuit-breakers for every task. They override the instinct to keep
+retrying. A structured workflow (a skill or pipeline stage with its own explicit
+retry and check-in rules) takes precedence where it is explicit.
+
+### Circuit-breakers
+
+- **Two strikes, then stop.** If the same command, test, or fix fails twice for
+  the same reason, stop. Do not attempt a third variation. Report what you tried
+  and ask how to proceed.
+- **No repeat without rationale.** Never re-run a tool call with the same input
+  unless you can state, in one sentence, what changed and why it will now
+  succeed. If you cannot, stop and ask.
+- **No progress, no next cycle.** If a full cycle of work produces no observable
+  progress, check in instead of starting another cycle.
+
+### Check in when…
+
+Stop and present options instead of continuing when any of these is true:
+
+- Two attempts at the same problem have failed.
+- The requirement is ambiguous, or two instructions conflict.
+- The work needs a decision the user has not made, or a choice with material
+  trade-offs.
+- You need to change something outside the task's stated scope.
+- The next action is destructive or hard to reverse.
+- You are blocked and no in-scope action will unblock you.
+
+When checking in, state: what you tried, what happened, the options, and your
+recommendation.
+
+### Atomic changes
+
+- **One concern per change.** Do not refactor, rename, reformat, or tidy code the
+  task does not require. Record it and leave it for a separate change.
+- **Smallest diff that works.** Make the minimal change that satisfies the
+  requirement.
+- Never mix a fix with unrelated cleanup in the same change.
+`;
+
+/**
+ * Append the guardrails block to a system prompt.
+ *
+ * The base prompt is preserved verbatim (minus trailing whitespace) so callers
+ * can chain this after other `before_agent_start` handlers. Idempotent: a prompt
+ * that already contains the marker is returned unchanged.
+ */
+export function appendGuardrails(systemPrompt: string): string {
+  if (systemPrompt.includes(GUARDRAILS_MARKER)) return systemPrompt;
+  return `${systemPrompt.trimEnd()}\n\n${GUARDRAILS}`;
+}

package/extensions/agent-guardrails/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Agent Guardrails Extension
+ *
+ * Appends behavioural circuit-breakers to the PI system prompt on every turn:
+ * hard retry limits, explicit check-in triggers, and atomic-change discipline
+ * (the first slice of docs/ideas/improve-pi-system-prompt.md).
+ *
+ * The block is stable text appended after any chained system-prompt changes, so
+ * it keeps the prompt-cache prefix intact while remaining authoritative for the
+ * model. See guardrails.ts for the rules and appendGuardrails for composition.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendGuardrails } from "./guardrails.ts";
+
+export { GUARDRAILS, GUARDRAILS_MARKER, appendGuardrails } from "./guardrails.ts";
+
+export default function agentGuardrailsExtension(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => {
+    return { systemPrompt: appendGuardrails(event.systemPrompt) };
+  });
+}

package/extensions/agent-guardrails/node_modules/.bin/pi

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
+else
+  exec node  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
+fi

package/extensions/agent-guardrails/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi