@jaybeeuu/agent-cortex 1.42.0 → 2.0.0

package/docs/claude-hooks.md

@@ -14,7 +14,7 @@ UI surface. Each decision below is grounded in the Claude Code hooks reference.
 
 | pi extension | Claude port | Decision |
 |---|---|---|
-| `session-start.ts` | `SessionStart` hook commands | **Port** (extended) |
+| `session-start/` | `SessionStart` hook commands | **Port** (extended) |
 | `auto-name.ts` | — | **Reject** — built-in |
 | `agent-guardrails/` | — | **Reject** — pi-only (no system-prompt hook) |
 | `notify/` | `Notification` hook + `scripts/notify.mjs` | **Port** |
@@ -22,10 +22,11 @@ UI surface. Each decision below is grounded in the Claude Code hooks reference.
 | `subagent/` | — | **Reject** — native |
 | `agent-modes/` | — | **Reject** — no equivalent |
 
-## `session-start.ts` → SessionStart (port)
+## `session-start/` → SessionStart (port)
 
-pi injects skill-availability hints + project context files (AGENTS.md,
-`docs/user-preferences.md`) into every session. Claude Code already loads
+pi injects the project context files (AGENTS.md, `docs/user-preferences.md`)
+into every session; it lists no skills, since pi's system prompt already names
+every skill with its `SKILL.md` path. Claude Code already loads
 `AGENTS.md` natively and the existing SessionStart hook nudge ("Load AGENTS.md
 and active beads context…") plus the style-skill policy (PR #57) cover the
 context side. This bead closes the remaining gap: a skill-policy command listing

package/docs/commit-signing.md

@@ -0,0 +1,231 @@
+# Commit signing
+
+GitHub has refused merges here with **"Merging is blocked — Commits must have verified
+signatures"**. The instinctive reading — "agents don't sign, so of course" — is wrong:
+agent and human commits on this repo are GPG-signed and verified. The unsigned commits
+are the ones `github-actions[bot]` writes, and only because `GITHUB_TOKEN` cannot hold a
+signing key. This note records what is actually signed, what the API says about
+enforcement, and the release policy that follows.
+
+## What is signed, and what is not
+
+The agent environment signs automatically. Global git config has `commit.gpgsign=true`
+and the secret key `DF657A88675E4AF8F7D65192A8F2E11DE960BE54` (Josh Bickley-Wallace,
+the `noreply` address) is present, so every commit an agent makes is signed without any
+per-commit step. Verified against the API:
+
+| Commit | Author | `verification` |
+|---|---|---|
+| `63f3bef` (PR #181 head) | jaybeeuu | `verified=true reason=valid` |
+| `7f99e4c` (PR #182 head) | jaybeeuu | `verified=true reason=valid` |
+| `9443f55` (PR #168 head) | github-actions[bot] | `verified=false reason=unsigned` |
+
+`changesets/action` commits as `github-actions[bot]` using `secrets.GITHUB_TOKEN`, and
+GitHub does not sign commits made with a token. That is a property of the token, not a
+missing configuration step — no amount of workflow YAML changes it.
+
+Landed history looks uniformly `valid` for a different reason: the commit the merge creates
+is signed by GitHub. `dd347471b1`, the commit that landed PR #161 ("chore: version
+packages", authored by `github-actions[bot]`), has `committer=GitHub` and
+`verification.verified=true reason=valid`. The bot's unsigned branch commit never reached
+`main`; the squash commit GitHub created did, and GitHub signed it.
+
+That is what this repository's history proves, and it is all it proves. It does **not**
+prove that a squash merge escapes an *enforced* signature rule.
+
+## Squash does not bypass an enforced signature rule
+
+The landing commit being GitHub-signed does not exempt the pull request from the check:
+a ruleset that requires signatures inspects the head-branch commits too. GitHub's ruleset
+reference, ["Require signed commits"](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-signed-commits)
+(quoted verbatim, checked 2026-10-27):
+
+> When GitHub evaluates whether a pull request can be merged, it creates a test merge commit
+> whose parents are the latest commit on the base branch and the pull request's head commit.
+> GitHub checks the commits introduced by this test merge, including commits from the head
+> branch. As a result, unsigned commits on the head branch can block a squash merge, even
+> though GitHub would sign the final squash commit. This restriction can also apply to the
+> author of the pull request.
+
+and the remedy it documents:
+
+> To merge a blocked pull request, rewrite and sign the unsigned commits on the head branch,
+> or ask someone with permission to bypass the applicable protections to merge the pull
+> request.
+
+So "squash it and let GitHub re-sign" is not a way *around* the check — it is only the reason
+landed history reads `valid` when no signature rule is in force. If a signature rule is
+enforced, the remedy is a signed commit, not a different merge method.
+
+## What the ruleset API shows — and what it cannot
+
+No `required_signatures` rule is visible to the tokens available here, at any level.
+Read-only probes:
+
+```
+$ gh api repos/jaybeeuu/agent-cortex/rules/branches/main --jq '[.[].type]'
+["deletion","non_fast_forward","required_linear_history",
+ "required_status_checks","pull_request"]
+```
+
+Every effective rule on `main` comes from `ruleset_id 22101709` with
+`ruleset_source_type: Repository`. That is evidence rather than silence, because the endpoint
+is not repository-scoped by construction: it is documented to return rules "regardless of the
+level at which they are configured (e.g. repository or organization)", and its own response
+schema includes a `ruleset_source_type: "Organization"` example ([REST reference, "Get rules for a branch"](https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch), checked
+2026-10-27). There is no `required_signatures` rule in it, and its `pull_request` parameters
+allow `["merge","squash","rebase"]`. The other read paths agree:
+
+```
+$ gh api repos/jaybeeuu/agent-cortex/branches/main/protection
+{"message":"Branch not protected", ... "status":"404"}
+
+$ gh api orgs/jaybeeuu/rulesets
+{"message":"Not Found", ... "status":"404"}
+```
+
+Two explanations remain. The branch-rule read above weighs heavily against the first, without
+formally eliminating it:
+
+1. **An organization-level ruleset enforces signatures.** This is the weaker of the two now:
+   the applied-rule read covers every level and shows no organization-sourced rule, so this
+   survives only on an undocumented possibility that the endpoint filters by caller
+   visibility. Org ruleset *definitions* do separately require organization administration
+   read, which the current token does not hold (scopes: `gist, read:org, repo, workflow`), so
+   a `404` on `orgs/jaybeeuu/rulesets` is inconclusive — it may mean "none exist" or "you may
+   not see them". Note that the ruleset's `bypass_actors` is empty and
+   `current_user_can_bypass` is `"never"`, so repository admin does **not** bypass it.
+2. **The UI message was stale** — shown while a signature rule was active, before ruleset
+   `22101709` was last updated (2026-09-13).
+
+Closing this out needs a merge attempt (a mutation) or org-admin access: see *The enforcing
+rule: still open (AC1)* and the human follow-ups below.
+
+One adjacent rule is worth knowing, though it cannot fire here. Ruleset `22101709` sets
+`require_extra_approval_for_unattributed_changes: true`, which adds one approval when a pull
+request is an unattributed Copilot pull request — but GitHub documents that the setting "has
+no effect if the ruleset requires zero approvals" ([available rules for rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#additional-approval-for-unattributed-copilot-pull-requests),
+checked 2026-10-27), and this ruleset sets `required_approving_review_count: 0`. A blocked
+merge box here is the missing `statusCheckRollup` on a Version Packages PR or a missing
+code-owner review, not this setting.
+
+## Policy: land bot-authored PRs by squash merge
+
+Adopted: **Option A — no signing key in CI.** So long as no signature rule is enforced, no
+unsigned commit is required to land a release: the merge produces a commit GitHub signs, so
+the only requirement is the merge method.
+
+Squash-merge Version Packages PRs (`gh pr merge <n> --squash`). GitHub rewrites the bot's
+unsigned branch commit into a single commit that it signs as committer, which is exactly
+what `dd347471b1` demonstrates. Squash is the only path that lands a GitHub-signed commit:
+`allow_merge_commit` is `false` in the repository merge settings, so a true merge commit is
+impossible, and `required_linear_history` on `main` means a pull request "must use a squash
+merge or a rebase merge". The ruleset's `allowed_merge_methods`
+(`["merge","squash","rebase"]`) leaves both open — its `merge` entry is already dead because
+the repository disables merge commits. Of those two, only squash produces a commit GitHub
+creates and signs: rebase-and-merge is documented to add the head-branch commits "without
+commit signature verification", because the commit it creates is modified and GitHub "can't
+therefore sign it as a generic system user" ([about merge methods](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github),
+checked 2026-10-27). For a `github-actions[bot]` head commit that means an unsigned commit on
+`main`, so rebase is not an acceptable path here even though the settings permit it.
+
+Note the limit of this remedy: squash re-signs the landing commit, it does not bypass an
+enforced signature rule (see above). It works here because no such rule is currently
+enforced against this repository.
+
+Consequence: the release automation stays fully automated and no signing key enters CI —
+provided no signature rule is enforced. See the contingency below.
+
+### Contingency: the enforcing rule turns out to be real at organization level
+
+The policy above holds only while a squash merge is permitted. If the merge probe or an org
+admin confirms an organization-level `required_signatures` rule, Option A's premise fails:
+GitHub would then refuse the squash merge as well, because it validates the pull request's
+head commits through the test merge. In that case:
+
+1. Do not keep re-attempting the squash merge, and do not treat a bypass as the workaround —
+   a bypass is a human permission decision, not a release path.
+2. The release path must produce signed commits, which means Option B (import a key into the
+   release job) or having a key-holding actor sign the release commit. That change must land
+   with the access audit and rotation procedure Option B requires.
+3. Until then, releasing is a human step performed with bypass permission, recorded as a
+   HITL note on the bead.
+
+The applied-rule read returns no organization-sourced rule, but org ruleset definitions stay
+unreadable from a repository-scoped token, so re-check the read before assuming the absence
+persists.
+
+### Option B, rejected as the default
+
+Importing a GPG key into the release job (`GPG_PRIVATE_KEY` + `GPG_PASSPHRASE` secrets and
+a `git commit --amend -S` step) would make the *branch* commit signed too. It is rejected as
+the default because, while no signature rule is enforced, it buys nothing the squash merge
+does not already give — the branch commit is discarded on merge — while placing a
+long-lived private key in repository secrets. That trade-off inverts if a signature rule is
+confirmed enforced: Option B then becomes necessary (see the contingency above). Either way,
+if it is revisited the same change must carry an access audit (who and what can read the
+secret) and a rotation procedure (key expiry, re-issue, revocation). Neither exists today,
+and adding the key without them is not acceptable.
+
+## When the signature check fires
+
+| Situation | Remedy |
+|---|---|
+| Bot-authored PR blocked on signatures, rule **confirmed** enforced | A squash merge will not help — GitHub checks head-branch commits through its test merge. Rewrite the branch so its commits are signed (`git rebase --exec 'git commit --amend -S --no-edit'` or an amend plus force-push), then merge; otherwise a person with bypass permission merges it. |
+| Bot-authored PR blocked, `rules/branches/main` lists no `required_signatures` rule | The block is most likely not signatures. Read the merge box first: missing required status checks (an empty `statusCheckRollup` on a Version Packages PR is the common case) or a missing code-owner review fully explain `mergeStateStatus=BLOCKED`. |
+| An agent commit is reported unsigned | Check `git config --get commit.gpgsign` and `gpg --list-secret-keys`; re-sign with `git commit --amend -S --no-edit` and force-push the branch. |
+| The block persists with no visible cause | Read `gh api repos/<owner>/<repo>/rules/branches/<branch>`. That endpoint covers every level, so no `required_signatures` entry means no active signature rule applies as far as this read can see — if the block still looks like signatures, have an org admin confirm the org rulesets rather than guessing. |
+
+## The enforcing rule: still open (AC1)
+
+The parent bead's first acceptance criterion — "Enforcing rule identified, or the UI message
+shown to be stale — with the merge API's error text quoted either way" — is **open**. No
+merge API error text exists yet, because obtaining it requires a merge attempt, which is a
+mutation and therefore a human step. Read-only evidence narrows the question sharply but
+does not close it:
+
+1. **No repository-level signature rule was blocking on 2026-10-13.** PR #161's head
+   `fe7ef84` is `verification.verified=false reason=unsigned`, and the PR was squash-merged
+   at `2026-10-13T21:46:06Z` — after ruleset `22101709`'s last update
+   (`2026-09-13T21:11:23.985+01:00`, i.e. `2026-09-13T20:11:23Z`). An unsigned head landed
+   after the ruleset's last edit, so neither that ruleset nor anything older in it enforced
+   signatures then.
+2. **PR #168's current block needs no signature rule to explain it.**
+   `gh pr view 168 --json state,mergeable,mergeStateStatus,statusCheckRollup,reviews` returns
+   `state=OPEN`, `mergeable=MERGEABLE`, `mergeStateStatus=BLOCKED`,
+   `statusCheckRollup=[]`, `reviews=[]`. All five required checks (`Test`, `Lint`,
+   `Claude plugin materialiser check`, `Changeset check`, `Setup`) are unreported, and
+   `require_code_owner_review` is on with no reviews. `required_status_checks` plus the
+   missing code-owner review fully account for `BLOCKED`.
+3. **The applied-rule read comes back clean, including at organization level.**
+   `rules/branches/{branch}` is documented to return every active rule "regardless of the
+   level at which they are configured (e.g. repository or organization)", so it is the read
+   that *would* surface an organization-level rule. The live read returns five rules, all
+   `ruleset_source_type: Repository` from `ruleset_id 22101709`, and none of them is
+   `required_signatures`. On the documented contract that is positive evidence that no
+   organization-level signature rule is applied to `main` today, not an unreadable gap. The
+   honest residual is narrower: whether this endpoint filters by caller visibility is
+   undocumented, and org ruleset *definitions* stay unreadable with the current token —
+   `gh api orgs/jaybeeuu/rulesets` returns `{"message":"Not Found", ... "status":"404"}` and
+   `gh api orgs/jaybeeuu` adds `gh: This API operation needs the "admin:org" scope`. So "no
+   org rule is applied" is read; "no org ruleset exists" is not.
+
+Status: **open, pending a human merge probe or org-admin inspection** (see below). The read
+above narrows the question but cannot close AC1, which turns on the merge API's own error
+text; the merge probe supplies that.
+
+## Human-only follow-ups
+
+These need repository or organization settings and cannot be done by an agent:
+
+- **Merge probe — closes AC1.** Run `gh pr merge 168 --squash` (or
+  `PUT /repos/jaybeeuu/agent-cortex/pulls/168/merge`) and record the verbatim error text
+  here. A signature error confirms an invisible rule and triggers the contingency above; a
+  status-check error confirms the message was stale and closes the criterion as
+  "UI message stale".
+- **Inspect org rulesets.** Open `https://github.com/organizations/jaybeeuu/settings/rules`
+  and confirm whether a ruleset targets `jaybeeuu/agent-cortex` with "Require signed
+  commits". Record the answer here.
+- **Confirm the merge method.** If squash-merge is the documented path, consider removing
+  `rebase` from `allowed_merge_methods` so a rebase merge cannot add an unsigned bot
+  commit to `main`.

package/docs/ideas/enable-signed-commit-enforcement-changesets-bot-commits-must-be-signed.md

@@ -30,4 +30,13 @@ The author. Main-branch history becomes verifiably authentic — every commit at
 Determine how the changesets commit gets signed in CI on this repo — cheapest prototype: scratch repo (or the version branch) exercising the signing path end-to-end without touching `main`'s rule, then evaluate the rule change on `main`.
 
 ## Notes
-Recorded 2026-09-02. Backlog capture only — no active work planned; revisit after the install-manager epic (pi/claude/copilot) settles. Adjacent to `docs/ideas/unified-ci-pipeline.md` (CI/release restructure).
+Recorded 2026-09-02. Backlog capture only — no active work planned; revisit after the install-manager epic (pi/claude/copilot) settles. Adjacent to `docs/ideas/unified-ci-pipeline.md` (CI/release restructure).
+
+Updated 2026-10-28: `docs/commit-signing.md` records the investigation and the decided policy.
+The applied-rule read shows no `required_signatures` rule on `main` at repository or
+organization level (org ruleset *definitions* stay unreadable with a repository-scoped token),
+and Version Packages PRs land by squash merge, whose landing commit GitHub signs — so releases
+stay automated with no key in CI, and the CI signing key this idea points at is rejected as the
+default. That rejection does not settle the idea: GitHub checks head-branch commits through its
+test merge, so enabling enforcement would still require the signed CI commit, exactly as
+`Next validation step` describes.

package/docs/ideas/extension-manifests.md

@@ -7,6 +7,11 @@ harness's native dependency fields plus committed settings templates. See the de
 prune TUI was rejected (see "Prune rejected") and the proposed declared-vs-installed diff was
 dropped — `agent-cortex install <harness>` reconciles instead.
 
+The mechanism recorded under "What shipped" has since been removed (2026-10-24,
+`agnt-ctx-7kru.1`): `pi.packages`, `lib/pi-packages.mjs` and `--no-provision` are gone, and the
+required pi packages now travel inside the staged package at `~/.agent-cortex/pi` instead of
+being provisioned into pi's user scope.
+
 ## Created
 2026-08-25
 

package/docs/research/disable-model-invocation.md

@@ -0,0 +1,82 @@
+# `disable-model-invocation` across harnesses
+
+Decision record for the frontmatter field this repo uses to keep rare or destructive
+skills out of automatic model routing (bead `agnt-ctx-yf24`).
+
+**Verdict:** rely on it for pi and Claude Code.
+
+## What the field does
+
+`disable-model-invocation: true` removes a skill from the list the model is offered.
+The user can still invoke it explicitly. It does not summarise, rewrite, or
+otherwise change how the body loads, which is what `docs/skills/skill-anatomy.md`
+previously implied.
+
+## Preservation and honouring
+
+| Harness | Field survives materialisation | Loader honours it | Evidence |
+| --- | --- | --- | --- |
+| pi 1.4.0 | Yes — byte-identical copy | Yes — hidden from the prompt, `/skill:name` still works | `bin/installers/pi.mjs:182-204`, `scripts/lib/compose-agent.mjs:69-95`; `dist/core/skills.js:262` (parse) and `:279` (filter); `docs/skills.md:53` |
+| Claude Code 2.1.294 | Yes — byte-identical copy | Yes — Claude cannot invoke it, `/skill-name` still works | `bin/installers/claude.mjs:160-201`, same token helper; [Claude Code skills docs](https://code.claude.com/docs/en/skills) ("Control who invokes a skill") |
+
+Both materialisers copy `SKILL.md` as text and rewrite only `{{TOOL:...}}` /
+`{{PATH:...}}` tokens, so frontmatter keys they do not know pass through untouched —
+nothing re-serialises YAML. Verified by installing both harnesses into
+`/var/tmp/dmi-check` and diffing `skills/productivity/teach/SKILL.md` (the repo's
+only current user of the field): both copies are byte-identical to the source.
+`claude plugin validate /var/tmp/dmi-check/claude/skills` passes, i.e. Claude Code's
+own validator accepts the field rather than warning about it.
+
+pi was probed against the materialised tree with its own loader: 32 skills loaded,
+31 advertised, `teach` parsed with `disableModelInvocation: true` and absent from
+`formatSkillsForPrompt` output.
+
+## Per-harness detail
+
+**pi.** Documented and implemented. `docs/skills.md:53`: "Set
+`disable-model-invocation: true` in frontmatter when a skill should be available only
+through its explicit command", with the frontmatter table listing it as "Hide the
+skill from automatic model selection".
+
+**Claude Code.** Documented, and the docs are explicit about the enforcement: "Claude
+can't invoke the skill on its own … If Claude tries anyway, Claude Code blocks the
+call and instructs it not to reproduce the deploy steps another way", and it "removes
+the skill from Claude's context entirely".
+
+Two Claude-specific caveats:
+
+- The field is a Claude Code extension, not part of the
+  [Agent Skills spec](https://agentskills.io/specification), whose six fields
+  (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`)
+  are otherwise exhaustive. Claude Code ignores unknown fields, but packing or
+  uploading a skill to claude.ai (or through the Skills API) "fails with a hard error
+  instead of ignoring the field". Our plugin path is unaffected; a skill we ever
+  publish to claude.ai must drop the field.
+- `skillOverrides` does not apply to plugin skills, and our install is a plugin. The
+  frontmatter field itself still applies there — only that settings-based alternative
+  is unavailable.
+
+## Options for "explicit invocation only", evaluated
+
+| Option | Portable? | Enforced? | Verdict |
+| --- | --- | --- | --- |
+| `disable-model-invocation: true` | pi + Claude Code yes | Yes | **Recommended** where suppressing auto-routing is the point and the explicit path is a human typing `/name` |
+| Naming convention (e.g. `manual-*`) | Yes | No — no harness reads names | Rejected: a human signal we already get from the body |
+| `metadata:` block | Yes (spec-legal) | No — pi and Claude read top-level keys only | Rejected: documentation that looks like enforcement |
+| Keep such skills out of `skills/` | Yes | Yes, by not shipping the skill | Rejected: gives up the per-harness install entirely |
+
+## Recommendation
+
+Use the field when the danger is fuzzy automatic matching and the intended explicit
+path is a human typing `/skill-name`: that is the case for a migration skill whose
+`--apply` renames labels workspace-wide.
+
+## Reproducing
+
+```sh
+node bin/agent-cortex.mjs install claude  --output /var/tmp/dmi-check/claude
+node bin/agent-cortex.mjs install pi      --output /var/tmp/dmi-check/pi
+diff skills/productivity/teach/SKILL.md /var/tmp/dmi-check/claude/skills/teach/SKILL.md
+diff skills/productivity/teach/SKILL.md /var/tmp/dmi-check/pi/skills/productivity/teach/SKILL.md
+claude plugin validate /var/tmp/dmi-check/claude/skills
+```

package/docs/research/skill-design-research.md

@@ -35,7 +35,7 @@ The headline finding: **agent-cortex skills are well-structured but systematical
 | Cross-skill references | Explicit inline calls: "run `/grill-with-docs`" | Implicit — no inline cross-refs | agent-cortex weaker |
 | Shared vocabulary file | `CONTEXT.md` at repo root; skills told to read it | None | Missing in agent-cortex |
 | Skill manifest | Flat JSON array of skill paths | Same | ✅ Aligned |
-| `disable-model-invocation` | Used for pure prompt-injection skills | Not used | Feature gap |
+| `disable-model-invocation` | Used for pure prompt-injection skills | Used by `teach`; semantics now documented in `docs/skills/skill-anatomy.md` | Field adopted; rationale corrected |
 | Missing SKILL.md | 0 | 1 (`prd-to-epics`) | Bug in agent-cortex |
 
 ### 2.2 Tone and Voice
@@ -251,7 +251,7 @@ These are patterns present in `mattpocock/skills` that have no equivalent here a
 
 2. **Philosophy sections in skills** — `tdd` doesn't just describe TDD, it argues *why* horizontal slicing is wrong. This bakes intent into the skill so the agent handles novel cases correctly (backed by CoT rationale evidence).
 
-3. **`disable-model-invocation: true`** — for skills that *are* the prompt (pure injection, no interpretation). Prevents the model from summarising/transforming the skill content before executing it.
+3. **`disable-model-invocation: true`** — hides a skill from automatic model routing so only an explicit `/skill-name` invocation reaches it. See `docs/research/disable-model-invocation.md` for per-harness behaviour and caveats.
 
 4. **Composability by design** — skills reference each other by slash-command inline. This keeps each skill shorter and creates a network of reusable primitives rather than monolithic blobs.
 

package/docs/skills/skill-anatomy.md

@@ -11,7 +11,10 @@ Required fields:
 
 Optional fields:
 - `argument-hint`: input prompt shown to users at invocation.
-- `disable-model-invocation`: for deterministic prompt-injection skills that should not be summarized/interpreted.
+- `disable-model-invocation`: hides the skill from automatic model routing; explicit
+  `/skill-name` invocation still works. Set it when the danger is a fuzzy description
+  match, e.g. a skill whose steps are destructive. Preserved and honoured by pi and
+  Claude Code. See `docs/research/disable-model-invocation.md`.
 
 ## Description format rules
 
@@ -31,7 +34,7 @@ Optional fields:
 
 ## Tool references
 
-Reference agent tools by `{{TOOL:name}}` token (canonical copilot name), never a
+Reference agent tools by `{{TOOL:name}}` token (canonical authoring name), never a
 hardcoded harness-specific name such as `bash`, `task`, or `read_agent` — installers
 substitute the per-harness name from `token-map.json` at install time. Add any new tool
 to the map's `tools` section in the same change; unknown tokens are hard errors. See

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

@@ -1,10 +1,33 @@
 # Technical Direction: Harness config and third-party extensions
 
+## Status
+
+**Partly superseded (2026-10-24) by the staged-package model** (`agnt-ctx-7kru`). Two premises
+below no longer hold:
+
+- **The pi half landed without bundling.** `agent-cortex install pi` stages a self-contained
+  package at `~/.agent-cortex/pi` and copies the required third-party packages — resolved
+  through Node's own resolution — into that tree's `node_modules/`, instead of declaring
+  `bundledDependencies` in the published tarball. pi loads a local directory and resolves no
+  npm packages itself, so a tarball's `node_modules/` reached nobody; bundling also forced a
+  repo-wide `node-linker=hoisted`, surrendering pnpm's isolated resolution for the workspace.
+- **pi's own settings are no longer installer output.** The installer writes nothing into
+  `~/.pi/agent`; it registers the staged package by driving pi's own `pi install` /
+  `pi remove` commands, which own `settings.json` → `packages[]`. `pi/settings.json` and
+  `pi/keybindings.json` are reference templates. Registration's invariant is **one
+  agent-cortex source**: a source pointing at a raw agent-cortex checkout is removed first,
+  and one that survives `pi remove` fails the run rather than leave two sources configured
+  that both load.
+
+`pi.packages` and `lib/pi-packages.mjs` are deleted, so the bespoke-pi-mechanism problem this
+memo was written to settle is closed. The Claude analysis stands; Copilot CLI is no longer a
+deploy target (`agnt-ctx-2rl`).
+
 ## 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
+- **What we are solving.** agent-cortex ships agents and skills to two harnesses (pi, Claude
+  Code) 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
@@ -29,9 +52,6 @@
 - **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
@@ -64,7 +84,7 @@
   --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.
+  settings.
 - **Risks.** Loading TS extensions from bundled `node_modules/`; maintaining the Claude
   cross-marketplace allowlist.
 
@@ -106,8 +126,6 @@ the epic, and delete `pi.packages` + `lib/pi-packages.mjs` from `main`.
 - **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
@@ -138,8 +156,6 @@ pi extension loads from `node_modules/` and an optional one is materialised from
   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`.
 
@@ -153,9 +169,9 @@ pi extension loads from `node_modules/` and an optional one is materialised from
   (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);
+- Code evidence (as of 2026-09 — `pi.packages` and `lib/pi-packages.mjs` were removed in
+  `agnt-ctx-7kru.1`, see Status): `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

@@ -13,14 +13,21 @@
 
 ## Current-state constraints
 
-- bd CLI is a global binary (`~/.local/bin/bd`); label ops: `bd label list-all [--json]`,
-  `bd list --label-pattern/regex [--json]`, `bd label add/remove` (batch multiple ids).
+- bd is a globally installed CLI resolved from `PATH` (whatever single `bd` is on PATH —
+  Homebrew, npm, or the install script); `BD_PATH` is the override for machines where `bd` is
+  not on PATH. Skill scripts invoke `BD_PATH || 'bd'` and never hardcode an install path.
+  Label ops: `bd label list-all [--json]`, `bd list --label-pattern/regex [--json]`,
+  `bd label add/remove` (batch multiple ids).
+- A `bd` whose install target has been removed (`~/.local/bin` orphans, dangling pnpm shims)
+  must not be pinned: it can be a schema behind the workspace DB and fail with a schema
+  version mismatch. Keep exactly one `bd` on PATH so `bd` and the DB version agree.
 - `bd list` supports `--label-pattern`/`--json`; `bd count` does NOT support `--label-pattern`.
 - `bd ready --label-pattern 'stage:*'` works; `bd ready -l execution:afk` verified.
-- 3 script packages exist with per-skill `package.json` + own `pnpm-workspace.yaml` +
-  own `pnpm-lock.yaml` (create-task, validate-agent-dir, run-pipeline-stage). They are NOT
-  members of the root workspace (root glob `skills/*/scripts` does not match the nested
-  `skills/<domain>/<name>/scripts`; root lockfile has zero refs to them).
+- 3 script packages still exist with their own `package.json` (create-task,
+  validate-agent-dir, run-pipeline-stage). They ARE root workspace members (root glob
+  `skills/**/scripts`; all three are in the root `pnpm-lock.yaml`). Residual per-skill
+  `pnpm-lock.yaml` (all three) and `pnpm-workspace.yaml` (validate-agent-dir,
+  run-pipeline-stage) are stale artefacts of the pre-D2 layout.
 - All 3 scripts are stdlib-only (`node:child_process`, `node:fs`, `node:path`, `node:url`).
 - Extensions (`extensions/skill-stats`) have real peer deps on `@earendil-works/pi-coding-agent`
   — they remain workspace members with their own package.json.
@@ -162,8 +169,9 @@
 
 ## References
 
-- 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.
+- Code evidence: `bin/agent-cortex.mjs` + `lib/cli.mjs` (CLI surface),
+  `skills/*/*/scripts/package.json` (3, root workspace members), 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/docs/user-preferences.md

@@ -1,8 +1,8 @@
 # User Preferences
 
 This file records personal development preferences for the author (**jaybeeuu**).
-Both Copilot CLI agents and PI coding agents should read this file for user-level
-context when making tooling and workflow decisions.
+Both pi and Claude Code agents should read this file for user-level context when
+making tooling and workflow decisions.
 
 ## Package manager
 

package/extensions/agent-modes/README.md

@@ -39,9 +39,9 @@ contract:
    from the tool set with a warning.
 
 Flat `agents/*.agent.md` files are parsed as a fallback when an agent has no
-composable directory — they are generated output (scripts/build-copilot-agents.mjs)
-but may exist for non-migrated agents. A composable directory always wins over its
-flat counterpart for the same agent id.
+composable directory — a staged pi package carries flat renders, and a hand-written
+agent may be a single flat file. A composable directory always wins over its flat
+counterpart for the same agent id.
 
 ## Development
 

package/extensions/agent-modes/discover.test.ts

@@ -244,6 +244,25 @@ describe("discoverAgents (flat fallback)", () => {
     assert.deepEqual(strategy.tools, ["bash", "fetch_content", "read"]);
     assert.match(strategy.prompt, /Flat body of strategy\./);
   });
+  it("reads a space-separated scalar tools list instead of falling back to defaults", () => {
+    const fx = track(makeFixture());
+    writeFlatAgent(fx, "ralph", FLAT_FRONTMATTER("ralph", '"bash read grep task"'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    // A collapsed scalar would land on DEFAULT_TOOLS, lifting the restriction
+    // rather than applying it — the tool names must survive the parse.
+    assert.deepEqual(agents[0].tools, ["bash", "grep", "read", "task"]);
+  });
+
+  it("reads a comma-separated scalar tools list", () => {
+    const fx = track(makeFixture());
+    writeFlatAgent(fx, "ralph", FLAT_FRONTMATTER("ralph", '"bash, view, task"'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.deepEqual(agents[0].tools, ["bash", "read", "task"]);
+  });
 });
 
 // ─── loadTokenMap ────────────────────────────────────────────────────────────