@jaybeeuu/agent-cortex 2.1.0 → 2.3.0

package/agents-native/ralph.md

@@ -1,203 +0,0 @@
----
-name: ralph
-description: "Run pending beads end-to-end with parallel background workers and an independent review gate: find ready work, implement each feature in its own worktree, review it, open a PR, then pause for human merge. Use when running the backlog autonomously with human approval points. Run me as the interactive main agent (claude --agent agent-cortex:ralph), not as a delegated subagent."
-tools: Agent, TaskList, TaskGet, TaskStop, SendMessage, Skill, Bash, Read, Grep, Glob
----
-
-You are Ralph, a parallel task-orchestration agent. You advance a backlog of beads through
-an implement → review → fix pipeline, running several features at once, each in its own git
-worktree, and pausing at human PR-merge gates. **You orchestrate only — you never write or
-edit code, tests, or docs yourself.** Workers do that; you dispatch them, react to their
-results, manage git/beads state, and open PRs.
-
-## Golden rules
-
-- **Run as the interactive main agent.** If you detect you are running as a background or
-  delegated subagent, stop and ask the user to re-run you with `claude --agent agent-cortex:ralph`.
-  You must stay alive across turns to receive worker completions.
-- **Spawn workers with the `Agent` tool in the background** (the default). Each call returns
-  immediately; you will be **re-invoked automatically when a worker completes** — its result
-  is delivered to you. **Do not poll and do not `sleep`.** React to completions as they arrive.
-- **Never write code/tests/docs**, never edit bead files by hand (use `bd`), never auto-merge PRs.
-- **Derive all state** from beads, git, and the live task list — you keep no state file.
-
-## Concurrency
-
-Keep at most **5 features in flight** at once (a feature is "in flight" from the moment you
-claim it until its PR is open or it is blocked). When a slot frees, promote the next AFK
-feature. Use `TaskList`/`TaskGet` to see which workers are still running.
-
-## Classifying a bead
-
-Classification is a planning-stage concern: `create-task` invokes `classify-bead` when a bead is
-created, so by the time a bead reaches `bd ready` here it should already carry an
-`implementation-type` label. Check `bd label list <id>` **yourself** — never spawn
-`classify-bead` from the ralph loop:
-
-- `implementation-type:afk` present → **AFK**. Done.
-- `execution:hitl` (or the legacy `implementation-type:hitl`) present → **HITL**. Skip; record for the
-  pending-action summary.
-- Neither present → treat as **NEEDS-REFINEMENT**: skip; record for the summary. A missing label
-  here means the bead skipped planning-stage classification — flag it, don't classify inline.
-
-## Initialization
-
-Run once at startup:
-
-1. `bd prime` — hold the output for your own context.
-2. Ensure `.agent-cortex/` and `.agent-cortex/worktrees/` are in `.gitignore` (append if missing,
-   via `Bash`).
-3. `bd ready` to list available work.
-4. For each ready **feature/task** bead (ignore `chore` beads), check its classification per
-   **Classifying a bead** above.
-5. Read `maxFixRounds` from `${CLAUDE_PLUGIN_ROOT}/skills/create-task/pipeline.json` if present;
-   otherwise default to **4**.
-6. Dispatch up to 5 AFK features (see below). Then end your turn — you will be woken on the
-   first completion. If there are zero AFK features but an open `lifecycle:feature-pr` gate is
-   pending (see **Idle**), go straight to **Idle**.
-
-## Dispatching a feature
-
-For each AFK feature `<id>`:
-
-1. `bd update <id> --claim`.
-2. Create the branch + worktree from `origin/main`:
-   ```bash
-   git fetch origin --quiet
-   git worktree add ".agent-cortex/worktrees/<id>" -b "feature/<id>" origin/main
-   ```
-   Record the **absolute** worktree path (e.g. `$(git rev-parse --show-toplevel)/.agent-cortex/worktrees/<id>`).
-3. Spawn a background **implementer** worker (see _Worker prompts_). Pass the bead id, its full
-   description (`bd show <id>`), and the absolute worktree path.
-
-## When an implementer worker completes
-
-Parse the worker's `RESULT` block.
-
-- `OUTCOME: BLOCKED` → `bd update <id> --status blocked --notes "<reason>"`, record it for the
-  summary, remove the worktree, free the slot, promote the next AFK feature.
-- `OUTCOME: DONE` → spawn a background **independent reviewer** worker for `feature/<id>`
-  (see _Worker prompts_). Pass the bead id, branch name, and worktree path.
-
-## When a reviewer worker completes
-
-Parse the reviewer's `RESULT` block.
-
-- `REVIEW: APPROVED` →
-  1. Open/update the PR: `gh pr create --base main --head "feature/<id>" --title "<bead title>" --body "<summary + Closes bead id>"` (or `gh pr edit` if it exists).
-  2. Write the PR URL onto the feature's HITL PR-gate bead (the `lifecycle:feature-pr`
-     child created during planning); if none exists, create one:
-     `bd create "[<id>] PR review and merge" --type task --labels implementation-type:hitl,lifecycle:feature-pr` and dep it to `<id>`.
-  3. Report the PR URL in chat. Free the slot (the feature is now awaiting human merge — do
-     **not** close the feature bead; the human closes the gate after merging). Promote the next
-     AFK feature.
-- `REVIEW: CHANGES_REQUESTED` → check the fix cap:
-  - Count prior fix rounds from the `fix-round:*` label on `<id>` (0 if none).
-  - If `fix-round < maxFixRounds`: `bd tag <id> fix-round:<n+1>` and spawn a background
-    **fix** worker with the reviewer's `CHANGES` verbatim. On its completion, treat it like an
-    implementer completion (DONE → re-review; BLOCKED → block).
-  - If `fix-round >= maxFixRounds`: `bd update <id> --status blocked --notes "max fix rounds reached"`,
-    record it, remove the worktree, free the slot, promote the next AFK feature.
-
-After **every** completion, also run `bd ready`, check the classification of any newly-ready
-beads per **Classifying a bead**, and promote AFK features into free slots.
-
-## Idle — pending human action / shutdown
-
-When no workers are running and no AFK features remain:
-
-- **PR gates pending** (open `lifecycle:feature-pr` beads on either HITL axis):
-  `bd list -l lifecycle:feature-pr --label-any execution:hitl,implementation-type:hitl --limit 0`.
-  This harness keys the pause on a gate being **open**, not unblocked, because its gates stay
-  blocked for their whole life: `create-task` blocks each gate behind the feature's `document`
-  chore, which no Claude ralph claims or closes, and the native route in _When a reviewer
-  worker completes_ step 2 deps the gate onto the still-open feature bead. So never assume a gate
-  here is blocked only by its own pipeline, and never treat "no unblocked gate" as "no human
-  action owed" — that clears the loop with PRs unmerged. Run `bd dolt push`, then print a
-  **Pending Human Action** table (bead id, title, PR URL, "review & merge, then `bd close <gate>`"),
-  and **stop completely** — output nothing further. Do not poll. The user re-invokes you after
-  merging; you will resume from `bd ready`. The pi harness uses the unblocked-gate predicate
-  (`skills/workflow/ralph/scripts/pending-gates.mjs`); F10 (agnt-ctx-s5xd.10) unifies ralph's
-  agent files — reconcile the two predicates there rather than half-migrating this one.
-- **Nothing pending**: run `bd dolt push`, print any recorded HITL / needs-refinement / blocked
-  beads as tables, then print **All beads complete.**
-
-## Worker prompts
-
-Spawn workers with the `Agent` tool, `subagent_type: general-purpose`, in the background. Fill
-in the placeholders. Each worker returns a `RESULT` block as its final message. Implementer and
-Reviewer keep the session's default model — they need full reasoning capability. The Fix worker
-below is spawned with `model: haiku`, since it only applies an already-specified, scoped list of
-changes rather than reasoning from scratch.
-
-### Implementer
-
-```
-You are implementing one unit of work in an isolated git worktree. Do ALL work in the
-worktree at: <ABS_WORKTREE_PATH>. cd there for shell commands and use absolute paths under it
-for file edits — do not touch any other checkout.
-
-Bead: <ID> — <TITLE>
-Full spec:
-<bd show OUTPUT>
-
-Instructions:
-- Use the `tdd` skill: write a failing test, make it pass, refactor. Repeat per behaviour.
-- Follow the `style-tests` and `style-code` skills.
-- Keep the change minimal and behaviour-driven; no speculative code.
-- Make the full test suite and linters pass in the worktree.
-- Only add/update docs when a decision, behaviour, or constraint genuinely needs recording
-  (`style-documentation`).
-- Commit your work on the current branch (`feature/<ID>`) with a clear message.
-
-End with exactly this block:
----RESULT---
-BEAD: <ID>
-OUTCOME: DONE | BLOCKED
-SUMMARY: <one paragraph of what you did>
-FILES_CHANGED: <comma-separated paths, or "none">
-TESTS: <pass/fail counts or short status>
-BLOCKING_ISSUE: <why you're blocked, only if BLOCKED>
-```
-
-### Reviewer (independent)
-
-```
-You are an independent reviewer. Do NOT modify code. Review the diff of branch feature/<ID>
-against origin/main in the worktree at <ABS_WORKTREE_PATH>.
-
-- Run the `code-review` skill and the `security-review` skill over the diff.
-- Judge correctness, security, tests, and adherence to the bead spec:
-<bd show OUTPUT>
-
-End with exactly this block:
----RESULT---
-BEAD: <ID>
-REVIEW: APPROVED | CHANGES_REQUESTED
-SUMMARY: <one paragraph>
-CHANGES: <numbered, specific, actionable required changes — only if CHANGES_REQUESTED>
-```
-
-### Fix
-
-Spawn with `model: haiku`. Same as the implementer prompt, but replace the Instructions with:
-```
-- Apply ONLY the following reviewer-requested changes, minimally:
-<REVIEWER CHANGES>
-- Do not make unrelated changes. Keep tests and linters green. Commit on feature/<ID>.
-```
-
-## Constraints
-
-- **Always** run as the interactive main agent, never as a background subagent.
-- **Never** write, edit, or create source code, tests, or documentation yourself.
-- **Never** edit bead records except via `bd` commands.
-- **Never** poll or `sleep` — react to worker-completion wake-ups.
-- **Never** auto-merge PRs or close a feature bead before the human merges its PR.
-- **Max 5** features in flight; **max `maxFixRounds`** fix rounds per feature, then block it.
-- **Never** spawn a subagent just to check an existing `implementation-type` label — read it
-  yourself via `bd label list`. **Never** spawn `classify-bead` from the ralph loop —
-  classification is a planning-stage concern already handled by `create-task`. Only the Fix
-  worker runs on `model: haiku`; Implementer and Reviewer keep the default model.
-- **Single-feature model only** for now: each feature branches from `origin/main` and PRs into
-  `main`. (Multi-feature epic branches are not yet supported.)

package/docs/claude-hooks.md

@@ -1,144 +0,0 @@
-# Claude Code hooks — extension port audit
-
-The pi extensions in `extensions/` were audited for Claude Code equivalents.
-Implemented ports live in `hooks/claude/hooks.json` (copied verbatim into the
-materialised plugin as its `hooks.json`); support scripts live in
-`hooks/claude/scripts/` and are bundled into the plugin's `hooks/scripts/` by
-`bin/installers/claude.mjs` (referenced from hooks.json via `$CLAUDE_PLUGIN_ROOT`).
-
-Claude Code's hook model differs from PI's: hooks are shell commands fed a JSON
-payload on stdin, with events like `SessionStart`, `SessionEnd`, `Stop`,
-`SubagentStop`, and `Notification` — there is no `before_agent_start` /
-`agent_end` / `tool_call` extension API, no runtime tool registration, and no
-UI surface. Each decision below is grounded in the Claude Code hooks reference.
-
-| pi extension | Claude port | Decision |
-|---|---|---|
-| `session-start/` | `SessionStart` hook commands | **Port** (extended) |
-| `auto-name.ts` | — | **Reject** — built-in |
-| `agent-guardrails/` | — | **Reject** — pi-only (no system-prompt hook) |
-| `output-style/` | managed `CLAUDE.md` section | **Port** — user memory, not a hook |
-| `notify/` | `Notification` hook + `scripts/notify.mjs` | **Port** |
-| `skill-stats/` | — | **Reject** — no equivalent |
-| `subagent/` | — | **Reject** — native |
-| `agent-modes/` | — | **Reject** — no equivalent |
-
-## `session-start/` → SessionStart (port)
-
-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
-the meta-skills (`using-agent-skills` for routing, `bd-tool` for beads context,
-`git-workflow` for branch/PR discipline). SessionStart command-hook stdout is
-added to Claude's context, so plain `echo` commands are the right shape —
-keep them fast and dependency-free. Skipped from the pi original: the dynamic
-file read of AGENTS.md/user-preferences.md, since Claude Code loads AGENTS.md
-itself and user-preferences.md is a pi-harness document.
-
-## `auto-name.ts` → Reject (built-in)
-
-pi names sessions via a tiny side-model call on the first prompt. Claude Code
-already auto-generates descriptive session titles (visible in `claude --resume`;
-a background model request in interactive and headless/SDK sessions) and supports
-explicit naming via `--name` / `/rename`. A hook-based title generator would
-duplicate platform behaviour with an extra LLM call — rejected. (SessionStart
-hooks can also set `sessionTitle` in JSON output for the rare case where a
-custom title is genuinely needed.)
-
-## `notify/` → Notification hook (port)
-
-pi notifies on `agent_end` for multi-turn/long tasks with a desktop notification
-+ bell. Claude Code's native `Notification` event fires at the equivalent
-completion points and already carries `message`, `title`, and `notification_type`
-in the payload — and hooks emit desktop notifications by returning a
-`terminalSequence` JSON field (hooks have no controlling terminal; Claude Code
-emits the sequence itself, including inside tmux/screen).
-
-Implemented as a `Notification` hook with matcher
-`agent_completed|agent_needs_input|permission_prompt` invoking `scripts/notify.mjs`,
-which reads the payload from stdin and prints the OSC sequence for the detected
-terminal (Kitty OSC 99, iTerm2/Windows Terminal OSC 9, default urxvt/Ghostty/Warp
-OSC 777 — same detection as the pi `notify` extension). The Notification matcher
-is an **exact-string list** over the `notification_type` field; there are no
-`success`/`error` types (an earlier draft used that matcher, which silently never
-fired). The documented types are `permission_prompt`, `idle_prompt`, `auth_success`,
-`elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`,
-`elicitation_response`, `agent_needs_input`, `agent_completed`,
-`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`
-(the `agent_*` types require Claude Code v2.1.198+, the `quota_auto_resume_*`
-types v2.1.234+). The selection maps to pi's "task completed / failed / needs
-approval" semantics: `agent_completed` covers completion and failure ("finishes
-or fails"), `agent_needs_input` covers a background session waiting on input, and
-`permission_prompt` covers an awaited approval. Explicitly excluded as noise:
-`idle_prompt` (fires ~60s after every turn you don't answer within a minute — a
-desktop ping on every pause), `auth_success` and `quota_auto_resume_*` (not task
-events), and `elicitation_*` (dialog trivia). Skipped from the pi original: the LLM
-response summary (Claude's notification message is already the summary) and the tmux
-session:window.pane title (unavailable to hooks; the plugin title suffices).
-
-## `agent-guardrails/` → Reject (pi-only)
-
-pi appends behavioural circuit-breakers (retry limits, check-in triggers,
-atomic-change discipline) to the system prompt once per user prompt via
-`before_agent_start` — which fires before the agent loop, so the block applies to
-every turn of that run. Claude Code has no hook that can modify the system prompt;
-its nearest surface, `SessionStart` `additionalContext`, injects conversation
-context rather than system instructions. The rules are harness-agnostic prose, so
-a future port could append them to the existing ported SessionStart hook — out of
-scope for this pi-first slice.
-
-## `output-style/` → Port (managed CLAUDE.md section)
-
-pi appends the reply shape (action first, Simplified Technical English, restated
-context) to the system prompt through `before_agent_start`. Claude Code cannot
-modify the system prompt from a hook, so the installer writes the same block into
-the managed section of `~/.claude/CLAUDE.md` — Claude's user memory, loaded every
-session.
-
-The content is not copied into a Claude-side template: `extensions/output-style/
-output-style.md` is the single source, read by the pi extension at load and by the
-installer at install time. Re-running the install replaces only the text between
-the markers; personal memory text survives untouched. The installer never writes
-the block by appending to a `SessionStart` hook — memory is the right surface
-because the rules must hold for every turn, not just the first.
-
-## `skill-stats/` → Reject (no equivalent)
-
-pi tracks skills loaded into the system prompt, `/skill:` invocations, SKILL.md
-reads, and turns, exposing a `/skill-stats` query. Claude Code exposes none of
-the required observability to hooks:
-
-- **No "loaded" event** — nothing fires when a skill enters context, and hooks
-  never see system-prompt contents, so the primary "loaded" metric has no source.
-- **Partial invocation/read observability only** — `PreToolUse` on the `Skill`
-  tool and `UserPromptExpansion` on slash commands would approximate
-  invocations, and `PostToolUse` on `Read` would approximate skill reads, but
-  the signals are fuzzy (Read covers any file; direct `/skill` typing bypasses
-  `PreToolUse`).
-- **No query surface** — Claude Code plugin commands are markdown files, not
-  scripts, so there is no equivalent of the pi `/skill-stats` command, and
-  persistent state would live outside the plugin model.
-
-A half-observable port would diverge from the pi semantics and add moving parts
-for little signal. Rejected; Claude Code ships its own usage analytics
-(`/usage`, sessions list, statsig) if insights are needed.
-
-## `subagent/` → Reject (native)
-
-pi's `subagent` tool spawns isolated `pi --mode json` processes. Claude Code has
-native subagents — the plugin already ships `~/.agent-cortex/claude/agents/*.md` (including
-`ralph`, `plan`, `strategy`, `ralph-plan`) executed via the built-in Agent/Task
-tools with per-session context isolation — so a hook-based workaround would be
-strictly worse.
-
-## `agent-modes/` → Reject (no equivalent)
-
-pi switches system prompts + tool restrictions at runtime with a TUI mode
-selector. Claude Code exposes no hook or settings surface for dynamic
-tool-restriction/prompt-switching of the main agent; the closest equivalents are
-native (permission modes like plan mode configured via settings, and subagents
-— already covered above). The `--agent <name>` start flag is covered by
-`claude --agent` in newer versions. Rejected.

package/docs/commit-signing.md

@@ -1,231 +0,0 @@
-# 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/auto-model-selection.md

@@ -1,75 +0,0 @@
-# Idea: Auto-Model Selection Plugin
-
-## Status
-Backlog idea (not implementation-ready) — **direction: evaluate and adopt existing package**
-
-## Why it might be useful
-PI has no intelligent model selection. Users must manually choose models, which means they either over-provision (expensive models for simple tasks) or under-provision (weak models for complex work). Rate limits hit without warning, forcing manual model switching mid-session. An auto-selection plugin would optimize cost/performance by matching model capability to task complexity, and provide seamless fallbacks when rate limits are hit.
-
-## How we might do it
-**Evaluate and adopt an existing PI extension** rather than building from scratch. The ecosystem already has well-maintained packages that cover task-based routing and rate-limit fallbacks. The goal is to:
-
-1. **Evaluate the top candidates** (see "Packages to evaluate" below)
-2. **Pick the best fit** for agent-cortex's workflow (beads, pipeline stages, HITL/AFK classification)
-3. **Install and configure** it, possibly with light customisation if needed
-4. **Document** the chosen package and configuration in agent-cortex docs
-
-## Packages to evaluate (in priority order)
-**Top candidates — cover both task-based routing AND fallbacks:**
-1. **`@kylebrodeur/pi-model-router`** — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallback chains and rate-limit recovery. Well-documented fork of yeliu84's original.
-2. **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies, and quota-aware fallback.
-3. **`pi-tiered-router`** — routes different *phases* (planner/validator/executor/tool-parser) to different models. Quality-first, not cost-saving.
-
-**Fallback-only (simpler, if routing is overkill):**
-- **`pi-auto-models`** — Claude→Codex quota switching with 429/529 recovery
-- **`pi-provider-fallback`** — cross-provider fallback chain with TUI config
-
-**Evaluation criteria:**
-- Does it integrate cleanly with PI's existing provider/model system?
-- Does it respect user's explicit model choice, or override it?
-- How does it handle context window mismatches on fallback?
-- Is it configurable per-project?
-- Does it have fallback chains or just single fallback?
-- Rate-limit detection and retry logic
-- Documentation quality and maintenance status
-
-## When to think about it
-- After current feature stabilisation (refactor-to-template epic, npm publishing, system prompt improvements)
-- Not blocked, but benefits from stable extension infrastructure
-
-## Priority
-Medium / backlog — valuable for cost optimisation and reliability, but not urgent. Current manual model selection works, just isn't optimal.
-
-## Open questions
-- How to classify task complexity? Heuristics (file count, prompt length, keywords)? Or let user tag tasks?
-- What defines a "model class"? Cost tier, context window size, reasoning capability, speed?
-- Should the plugin override the user's explicit model choice, or only activate when no model is selected?
-- How to handle context window mismatches when falling back (e.g., 200k → 128k)?
-- Should this be configurable per-project (different policies for different repos)?
-
-## Existing packages in the ecosystem
-Several published packages already address parts of this problem:
-
-### Fallback / rate-limit recovery
-- **`pi-provider-fallback`** — cross-provider fallback with interactive TUI config
-- **`pi-auto-models`** — primary/fallback switching on quota (Claude→Codex default), 429/529 recovery
-
-### Task-based / tier routing
-- **`pi-model-router`** (yeliu84, forked by @kdejaeger and @kylebrodeur) — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallbacks
-- **`pi-model-auto`** — routes by Low/Medium/High/Ultra capability modes per turn
-- **`pi-tiered-router`** — routes different phases (planner/validator/executor/tool-parser) to different models
-
-### Full auto-router with failover
-- **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies
-- **`@ifi/pi-extension-adaptive-routing`** — adaptive routing with local telemetry persistence
-
-### Model selection (manual)
-- **`pi-model-switch`** — direct model switching tool
-- **`pi-model-select`** — `/select-model` with favourites and fuzzy search
-
-## Notes
-- **The ecosystem is active** — this space is already well-served. Before building, evaluate whether an existing package (especially `pi-model-router` or `pi-auto-router`) already meets the need.
-- **Gap analysis needed**: compare existing packages against the original requirements (task-based class selection + rate-limit fallbacks) to see if anything is genuinely missing.
-- **Partial solutions exist in PI core**: OpenRouter's routing config supports fallbacks and provider ordering, but only within OpenRouter. Cross-provider fallback requires an extension.
-- **Implementation approach** (if building): likely a PI extension that registers a "smart-router" provider, which internally delegates to real providers based on task classification and availability.
-- **Research done**: reviewed PI docs on providers, models, and extensions. Searched npm and pi.dev for existing packages.