@jaybeeuu/agent-cortex 1.41.1 → 1.43.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/ban-content-assertion-tests.md

@@ -1,7 +1,9 @@
 # Idea: ban-content-assertion-tests
 
 ## Status
-Backlog idea (not implementation-ready) — priority P1 (high)
+Filed as epic `agnt-ctx-h9gt` (2026-10-06) — awaiting `prd-to-tasks`. Slice 1 (the
+`style-tests` ban) shipped earlier in `daa77c8` (PR #143); this epic covers the review-gate
+enforcement and the skill sweep.
 
 ## Created
 2026-08-30

package/docs/ideas/dedicated-review-tests-skill.md

@@ -0,0 +1,71 @@
+# Idea: Dedicated review-tests skill
+
+## Status
+Backlog idea (not implementation-ready) — priority P2 (moderate), timing: follows `agnt-ctx-h9gt`
+
+## Created
+2026-10-06
+
+## Problem
+Test review has no home of its own in the ralph pipeline. The review stage invokes
+`review-security` for a dedicated security pass, then falls back to `style-code` and
+`style-tests` for everything else. `style-tests` is a *writing* skill — it states conventions
+before tests are authored — so a reviewer reading it has to invert authoring guidance into
+review findings. The result is that test defects are caught by whatever the reviewer happens to
+notice rather than by an explicit checklist, and each new class of defect (the content-assertion
+ban being the first) has to be bolted onto the review template individually.
+
+## Who benefits
+- **The author**, who stops triaging test defects that a structured review should have caught.
+- **Ralph stage runners**, who get an explicit finding checklist instead of inferring one from a
+  writing-conventions skill.
+- **Future skill authors**, who get one place to add a test-review rule rather than editing the
+  review template, the review playbook, and `style-tests` in lockstep.
+
+## Proposed outcome
+A `review-tests` skill — a peer to `review-security` — that specifies what a reviewer checks in
+a test suite: assertion quality (does each assertion prove the behaviour under test),
+mock discipline (boundaries only, never internals), test-data construction (vital data inline,
+fresh per test, no shared mutable fixtures), determinism (no sleeps, no real clocks, every async
+interaction awaited), and coverage gaps against the task's stated behaviours.
+
+Broad scope, narrow use: the skill is generic test-review guidance, invoked as a stage step by
+the ralph review playbook (and available to a human reviewer or a `git-workflow` PR review).
+Once it exists, the content-assertion check added by `agnt-ctx-h9gt` becomes one row inside it
+rather than a standing instruction in the review template.
+
+## Validity check
+- Evidence we already have: the review stage already delegates to skills for every other
+  concern (`review-security` for security, `style-code` for code shape, `style-documentation`
+  for docs) — test review is the gap in an otherwise uniform pattern. The content-assertion
+  ban was bolted onto the review template precisely because no skill owned test review.
+- Riskiest assumption: that a *review* checklist is meaningfully different from `style-tests`
+  read critically. If a reviewer can derive the findings from the existing authoring skill with
+  no loss, this becomes a second statement of the same rules — exactly the two-homes problem
+  `agnt-ctx-h9gt` avoids by keeping `style-tests` canonical.
+- What would invalidate this idea: if `agnt-ctx-h9gt`'s review-gate change turns out to be
+  sufficient — if the review stage, with the content-assertion check in hand, stops missing
+  test defects — then the dedicated skill earns nothing and should be dropped.
+
+## Constraints
+- `style-tests` stays the canonical statement of test conventions; `review-tests` must cite it
+  and add only the reviewer's framing, or the two will drift.
+- Must not duplicate `review-security`'s ground or re-run the test suite (that is the verify
+  stage's job).
+- Invoked from the review playbook, so it must be cheap to load — no expansion of the review
+  stage's token budget beyond one skill read.
+- Follows `agnt-ctx-h9gt`; the content-assertion rule must not be restated in a second place
+  until this skill exists to hold it.
+
+## Next validation step
+After `agnt-ctx-h9gt` has run through the pipeline at least once, collect the test-related
+findings its review stage actually produces across a few PRs. If reviewers keep requesting
+changes on test grounds that the template does not name, that list is the skill's first
+checklist and the idea is confirmed; if the template covers them, drop the idea.
+
+## Notes
+Floated by the author on 2026-10-06 while scoping `agnt-ctx-h9gt`. Stance locked in the
+interview: broad scope (generic test review, not a pipeline-specific gate), used in the ralph
+pipeline, priority P2 with the trigger being `agnt-ctx-h9gt`'s real-world review findings.
+Deliberately kept as an idea rather than folded into `agnt-ctx-h9gt` so it passes the same
+validity check as every other backlog entry.

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/ideas/unify-the-ticket-and-task-decomposition-workflows.md

@@ -0,0 +1,71 @@
+# Idea: Unify the ticket and task decomposition workflows
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-10-13
+
+## Problem
+The planning skills assume a fixed split between tickets and tasks, and implement
+decomposition in three places that do not agree:
+
+- `prd-to-tasks` slices a PRD into epics and task beads, then expands each task through
+  `create-task` into pipeline chore beads for ralph.
+- `spec-to-tickets` slices a spec into a ticket map, drafts bodies, and creates tickets in
+  a tracker (Jira, GitLab, GitHub, or beads).
+- `plan` Phase 2 re-implements the slicing logic inline rather than delegating.
+
+There is no model for a ticket that itself needs breaking into tasks, and no single place
+that owns decomposition. Which skill to use depends on the tracker rather than on the work.
+
+## Who benefits
+The author, and any agent running the planning skills. One decomposition path replaces
+three overlapping ones, and a ticket in any tracker can be created and then broken into
+tasks without switching skills.
+
+## Proposed outcome
+A single coherent model in which a ticket — in any tracker, including beads — can be
+created and then decomposed into tasks, with the tracker acting as an adapter rather than
+defining a separate skill. The exact shape is deliberately undecided; this record captures
+the problem, not a design.
+
+## Validity check
+- Evidence we already have: three implementations of spec-to-units slicing (`plan` Phase 2
+  inline, `prd-to-tasks`, `spec-to-tickets`); `prd-to-tasks` has eight dependents plus a
+  generated agent file; the only substantive difference between the two decomposition
+  skills is the creation contract — `create-task` expands AFK tasks into ralph's chore
+  tree, while `spec-to-tickets` uses a generic tracker adapter.
+- Riskiest assumption: not yet identified — this needs a thinking-through pass. Candidates
+  to test: (a) the ticket/task split can be unified without losing ralph's execution
+  contract; (b) the refactor is affordable given its blast radius; (c) the duplication is
+  causing enough harm to justify it at all.
+- What would invalidate this idea: if ralph's requirements — chore-tree expansion via
+  `create-chores.ts`/`pipeline.json`, epic branches, AFK/HITL classification — cannot be
+  expressed as a tracker adapter behind one slicing skill, then the split is load-bearing
+  and should stay. It would also be invalidated if the duplication never produces concrete
+  drift.
+
+## Constraints
+- Ralph's execution contract is fixed and must keep working: chore expansion, the epic PR
+  flow, and AFK/HITL classification.
+- Open beads `agnt-ctx-s5xd.4` and `agnt-ctx-s5xd.4.4` are already rewriting
+  `prd-to-tasks` and `plan`'s tagging for the `execution:` label model. Any refactor has to
+  land after that epic or it will collide.
+- Skills target ~150 lines, so a unified decomposition skill would need its tracker
+  adapters and formats split into support files.
+
+## Next validation step
+Once the s5xd two-axis epic lands, enumerate exactly what `create-task` and ralph require
+from a decomposition — classification, chore tree, epic hierarchy, labels — and test
+whether each can be expressed as a tracker adapter behind one slicing skill. That is the
+cheapest step that would firm up or kill the idea.
+
+## Notes
+- The open question at the heart of it: are "ticket" and "task" the same thing at different
+  granularities, or genuinely different things? Related: is a ticket a ralph task, or
+  something a ralph task is created from?
+- Priority P3 by the author's call — it blocks other planning work rather than being
+  polish.
+- Filed during the `write-a-ticket` / `spec-to-tickets` work (bead `agnt-ctx-vgzj`), where
+  the overlap first became concrete.

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

@@ -0,0 +1,103 @@
+# `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. Do not rely on it in Copilot CLI as
+"invoke-only" — there it means "unreachable through the model-facing skill tool".
+
+## 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") |
+| Copilot CLI (1.0.55 locally, 1.0.80/1.0.83 upstream) | N/A — no copy; `plugin.json` `"skills": "skills/"` serves the repo tree in place | Auto-invocation suppressed, but explicit model invocation fails; `/skill-name` works | `plugin.json:12`; [github/copilot-cli#4438](https://github.com/github/copilot-cli/issues/4438) (open, retested 1.0.83) |
+
+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 all three 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.
+
+**Copilot CLI.** The field is not in GitHub's skill documentation, which lists only
+`name`, `description`, `license`, and `allowed-tools`. In practice the CLI filters
+flagged skills out of the `skill()` tool's resolution list, so the model cannot call
+them even when the user names one: `Skill not found`. Only the interactive
+`/skill-name` slash command reaches a flagged skill, and `-p` mode has no slash path.
+Upstream issue #4438 is open.
+
+Local probing was not possible: the installed CLI is 1.0.55 (no `copilot skill`
+subcommand), and prompt runs are refused by this machine's org policy. The upstream
+report is the evidence for Copilot, tested on 1.0.80 and 1.0.83 — newer than 1.0.55,
+so this may differ locally, in either direction.
+
+## Options for "explicit invocation only", evaluated
+
+| Option | Portable? | Enforced? | Verdict |
+| --- | --- | --- | --- |
+| `disable-model-invocation: true` | pi + Claude Code yes; Copilot suppresses but breaks tool-based invocation | Yes on pi/Claude | **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, Copilot undefined | 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. Accept, and document, that on Copilot CLI it
+also blocks model-mediated invocation, including `-p` runs — if a workflow needs
+non-interactive access to such a skill, do not set the field and instead disable the
+skill in that user's Copilot config (`copilot skill disable <name>`, or the `/skills`
+toggle), which is harness-native and per-user.
+
+## 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
+node bin/agent-cortex.mjs install copilot --output /var/tmp/dmi-check/copilot
+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
+```
+
+The Copilot run writes only composed agent files — there is no skill copy to inspect.

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,11 @@ 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; Copilot CLI suppresses auto-routing but then cannot reach the skill
+  through its model-facing tool. See `docs/research/disable-model-invocation.md`.
 
 ## Description format rules
 

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

@@ -1,5 +1,27 @@
 # 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 and Copilot analysis stands.
+
 ## Problem and target outcome
 
 - **What we are solving.** agent-cortex ships agents and skills to three harnesses (pi, Claude
@@ -155,7 +177,9 @@ pi extension loads from `node_modules/` and an optional one is materialised from
   `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).