@jaybeeuu/agent-cortex 2.1.0 → 2.2.0

package/docs/ideas/extension-manifests.md

@@ -1,121 +0,0 @@
-# Idea: extension-manifests
-
-## Status
-**Superseded (2026-09-22)** — the bespoke per-harness manifest model was replaced by each
-harness's native dependency fields plus committed settings templates. See the decision memo
-[`docs/technical-direction/harness-config.md`](../technical-direction/harness-config.md). The
-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
-
-## Problem
-PI extensions and Claude/Copilot plugins are installed individually (`pi install <ext>`) and
-live implicit in the machine's state (`~/.pi/agent/extensions/`) with no declared manifest of
-what the author uses or where it came from. A fresh machine, clean `~/.pi`, or a failed update
-leaves the environment without the expected extensions. The toolset isn't reproducible and
-isn't documented anywhere in the author's repos. Experimenting with an extension (install, try,
-remove) is also all manual, and there is no view of how the machine differs from the declared set.
-
-## Who benefits
-The author. Installing/updating agent-cortex becomes a reliable way to restore a known PI +
-Claude environment (agent-cortex + declared extensions in one step). The manifests document and
-reproduce the toolset across machines. A declared-vs-installed diff makes drift visible and
-repairable.
-
-## Proposed outcome
-agent-cortex ships **committed extension manifests** (reviewed and stored on GitHub) declaring
-which extensions to install — **per harness**: one manifest for PI extensions, one for
-Claude/Copilot plugins. On install or update of agent-cortex, it reads the manifests and
-installs the declared extensions. The manifests are the single source of truth.
-
-Key decisions from the interview:
-
-1. **No monitoring** — nothing observes installs, and the CLI never writes the manifests.
-   Adding an extension = edit the manifest, commit it, ship it. This keeps the source of truth
-   in GitHub where it belongs (and gets the usual PR/review flow).
-2. **Per-harness manifests** — separate records for the pi harness vs the Claude harness, each
-   carrying the extension source (git URL / package name) for that harness's installer. The
-   install-on-update path handles each harness with its own mechanism.
-3. **Prune CLI with a TUI** — a CLI command (e.g. `agent-cortex ext prune`) opens an interactive
-   TUI listing locally-installed extensions; selecting one **uninstalls** it from the local
-   environment. Removing from the manifest is done manually on GitHub. This supports the
-   experimentation loop: install → try → prune locally, then curate the manifest separately.
-   **Reversed 2026-09-21** — the harnesses already provide uninstall; see "Prune rejected".
-
-agent-cortex's own bundled extensions (auto-discovered via `pi install`, e.g. `skill-stats`)
-are deliberately excluded from the manifests — only third-party extensions are declared.
-
-## What shipped (2026-09-18)
-
-The pi half of the problem is solved without a new manifest file: the packages agent-cortex
-needs are declared in the **existing** package manifest at `package.json` → `pi.packages`, and
-`agent-cortex install pi` provisions them through the `pi` CLI into the pi user scope
-(`lib/pi-packages.mjs`). Reusing the shipped manifest beat introducing a parallel per-harness
-manifest file, which would have duplicated a declaration agent-cortex already publishes.
-
-Three properties are deliberate and should survive future changes: provisioning is
-**idempotent** (a package both declared in `~/.pi/agent/settings.json` and present in the pi npm
-store is skipped), **degrades gracefully** (a missing `pi` CLI or a failed install warns and the
-agent install still succeeds), and is **opt-out** via `--no-provision` — automatically off for the
-`--output` generate-only form, and never run on `--dry-run`.
-
-Still unbuilt: the Claude/Copilot manifest. `pi/settings.json` also lists these
-packages for the symlinked-checkout workflow (where pi auto-installs them); that redundancy is
-intentional until the manifest model is extended to both harnesses.
-
-## Prune rejected (2026-09-21)
-
-The prune half was implemented (F6, `agnt-ctx-17hc`) and then rejected: PR #142 was closed
-unmerged and its branch deleted. The harnesses already own extension package management —
-`pi install/remove/list` and `claude plugin install/uninstall/list --json` — so an interactive
-wrapper around uninstall added no capability. The implementation's recorded justification that
-"pi does not have a listing API" is **wrong**: `pi list` exists (verified on pi 0.85.1) and lists
-installed packages from user and project settings, so the hand-rolled settings reader duplicated
-it. What is genuinely missing is not an uninstall UI but reconciliation between the declared set
-and the installed set — now delivered by materialising the committed settings template at
-install time (see the [harness-config memo](../technical-direction/harness-config.md)).
-
-## Validity check
-- Evidence we already have: agent-cortex already has an install surface to hang this on
-  (`pi install` package discovery for the pi harness, plus the existing `bin/agent-cortex.mjs`
-  install command and `postinstall` script). The repo already carries a `plugin.json` (Claude
-  harness) alongside `package.json` (pi harness), showing the per-harness split is natural.
-- Riskiest assumption: that an automated install-on-update of declared extensions is safe and
-  desirable (auto-installing on every update could surprise, or fail mid-flight on a new
-  machine lacking auth/network). The store-shape question that gated the (now rejected) prune
-  TUI is resolved: both harnesses expose a listing API (`pi list`; `claude plugin list --json`).
-- What would invalidate this idea: if auto-install-on-update proves too disruptive (better as
-  an explicit `agent-cortex ext install` command). The prune half is already invalidated — see
-  "Prune rejected".
-
-## Constraints
-- Manifests live in this repo, committed via the normal PR flow — the CLI never edits them.
-- Install-on-update must be idempotent and safe to skip/fail gracefully (no hard breakage of
-  agent-cortex's own install on extension failure).
-- Follow the repo's extension conventions where relevant (lightweight, no internal LLM calls).
-- If any local data is persisted (e.g. prune history), write to `~/.pi/agent-cortex/`.
-
-## Next validation step
-None — the direction is settled. The store question is answered (both harnesses expose a listing
-API: `pi list`; `claude plugin list --json`), and the manifest model is superseded by native
-dependency fields plus committed settings templates. See the
-[harness-config memo](../technical-direction/harness-config.md) for the replacement.
-
-## Notes
-Recorded 2026-08-25. The idea was refined during the interview: initially framed as
-"record the extensions I use" (observer-based), corrected to a **committed manifest** model —
-recording happens by editing + committing, not by monitoring. The manifest stays GitHub-managed
-(the CLI never writes it); the prune CLI was rejected, so local uninstall stays with the
-harnesses' own commands. This idea is adjacent to `record-ideas-as-beads`: both make
-agent-cortex the declared source of truth for the author's environment and workflow.
-
-**Superseded 2026-09-22.** The declared toolset is now expressed through `package.json`
-dependencies (required) and committed settings templates (optional), not a bespoke manifest —
-see the [harness-config memo](../technical-direction/harness-config.md).

package/docs/ideas/improve-pi-system-prompt.md

@@ -1,43 +0,0 @@
-# Idea: Improve PI System Prompt
-
-## Status
-Backlog idea (not implementation-ready) — two slices implemented as pi extensions:
-`agent-guardrails` (circuit-breakers, check-in triggers, atomic-change discipline) and
-`output-style` (action-first reply shape, Simplified Technical English, restated context,
-shipped to pi via the system prompt and to Claude via a managed `CLAUDE.md` section).
-The rest of the idea is unscoped.
-
-## Why it might be useful
-PI's current system prompt is weak. Agents consistently get off track, spend excessive tokens spinning their wheels or going off on tangents, fail to check in when problems are hit, and generally behave like inexperienced code goblins. This wastes tokens, slows down task completion, and forces the user to constantly redirect the agent. A stronger system prompt would produce more focused, disciplined agents that know when to stop and ask.
-
-## How we might do it
-Build improved behavioural instructions into agent-cortex — layered on top of or replacing PI's default system prompt. Key improvements:
-
-1. **Loop prevention / circuit-breakers** — hard limits on retry attempts (e.g. 2-attempt limit before stopping and asking), no repeated tool execution without rationale
-2. **Task-focus discipline** — stronger scoping instructions, no tangential refactoring, atomic changes
-3. **Check-in triggers** — explicit rules for when the agent must stop and present options to the user
-
-A Gemini-generated execution protocol prompt exists as a possible starting point (see Notes), but will need significant customisation for agent-cortex.
-
-## When to think about it
-- Land the current work first (refactor-to-template epic, bead workflow polish, CI/CD pipeline)
-- **Next priority after current work** — this is urgent-ish
-
-## Priority
-High — after current work lands. Directly impacts daily productivity and token efficiency.
-
-## Open questions
-- Layer on top of PI's default prompt, or replace it entirely?
-- Should PI's current system prompt be reviewed for nonsense that can be chopped out?
-- Which guardrails from the Gemini starter are genuinely useful vs redundant with existing skills (e.g. `git-workflow` already covers destructive commands, `style-code` covers scope discipline)?
-
-## Notes
-- **Second slice (settled)**: reply shape is a separate extension from task discipline.
-  `agent-guardrails` decides whether work continues; `output-style` decides how the result
-  is reported (STE per ASD-STE100, action first, context restated — never a bead or phase
-  ID cited alone). Both are stable constants appended on `before_agent_start`.
-- **Precedence (settled by the first slice)**: the generic circuit-breakers yield to a structured
-  workflow — a skill or pipeline stage with its own explicit retry and check-in rules wins.
-- **Gemini starter prompt** exists (see conversation from 2026-08-05) covering loop prevention, action scope, context management, execution workflow order, and working state maintenance. Useful starting material but needs heavy customisation.
-- **Incompatibility to fix**: the starter's "Working State Maintenance" section proposes `.pi/PLAN.md` files for complex tasks. This is incompatible with agent-cortex — we use **beads (bd)** for task tracking and pipeline stages, not flat markdown plan files. This section needs to be replaced with bead-aware equivalents (e.g. updating bead notes, using pipeline stage state).
-- **Overlap with existing skills**: several guardrails already exist in agent-cortex skills (`git-workflow`, `style-code`, `run-pipeline-stage`). The biggest gaps are **loop prevention / circuit-breakers** and **check-in discipline** — these aren't enforced anywhere today.

package/docs/ideas/map-every-cortex-tool-to-a-real-pi-equivalent.md

@@ -1,95 +0,0 @@
-# Idea: Map every cortex tool to a real PI equivalent
-
-## Status
-Slice 1 shipped 2026-09 via bead agnt-ctx-f4au: `ask_user` → `ask_questions` and
-`skill` → `read` remapped in `token-map.json`; agent-modes startup warnings gone,
-verified in real pi sessions. Open follow-ons: full coverage audit of every frontmatter
-tool; dedicated skill-tool candidate if prompting proves insufficient.
-
-## Created
-2026-09-08
-
-## Problem
-On every pi startup, agent-modes warns once per declared tool that has no pi mapping:
-`[agent-modes] Tool "ask_user" has no PI equivalent — omitted from the tool set` (plus
-`{{TOOL:ask_user}}` token drops). Today `ask_user` and `skill` produce this noise across
-the `ralph-plan`, `plan`, and `strategy` modes.
-
-Worse than noise: dropping `ask_user` **silently removes interactive grilling** from
-`ralph-plan`/`plan` in pi — a functional gap disguised as a warning. The root cause is
-that `token-map.json` declares `pi: null` for `ask_user` and `skill`, and agent-modes
-omits null-mapped tools rather than mapping them to the real pi equivalent.
-
-## Who benefits
-- The author, in every pi session: clean startup, no recurring warnings.
-- `plan`/`strategy`/`ralph-plan` in pi: regain interactive user questioning (via
-  `ask_questions`) and a documented, reliable skill-loading path.
-- Anyone maintaining cortex: a codified principle so future harness gaps surface loudly
-  and are resolved deliberately instead of silently degrading agent capability.
-
-## Proposed outcome
-- **Principle**: every tool a cortex agent declares in its frontmatter must have a real
-  pi-side representation — either a native pi tool (mapped in `token-map.json`) or a pi
-  tool-extension package (found, adopted, or designed). An unmapped tool should be a
-  loud error, not a startup warning. "If pi needs more extensions to work, we add more."
-- **Coverage audit**: every tool across `agents/*/pi/frontmatter.json` checked against
-  the pi toolset; each gap resolved by mapping or by adopting/designing an extension.
-- **Immediate remaps**: `ask_user` → `ask_questions` (pi's native structured-questions
-  tool); `skill` → documented as "read the listed SKILL.md path" for now (pi has no
-  skill tool — skills are context-listed + read-loaded), with a dedicated skill tool
-  recorded as a follow-on design candidate if prompting proves insufficient.
-
-## Validity check
-- Evidence we already have:
-  - The warnings reproduce on every pi startup in agent-nexus (seen 2026-09-08).
-    `token-map.json` maps both `ask_user` and `skill` to `pi: null`, and its notes claim
-    pi ships no ask tool and no skill tool.
-  - That note is outdated for the questioning case: pi's equivalent is `ask_questions`, a
-    structured user-question tool provided by the **pi-questions** package (`pi install
-    npm:pi-questions`; declared in the author's pi/settings.json) — present in this session's
-    toolset, but extension-provided, not native to pi. Mapping `ask_user` to it restores
-    grilling in pi modes *when the package is installed*; making the package install
-    reproducible is the extension-manifests idea (see `extension-manifests.md`).
-  - pi's own skills docs (skills.md, step 3) confirm skills load via `read` and concede
-    "models don't always do this" — so a doc-now mapping is legitimate but the
-    self-invocation gap is real and acknowledged upstream.
-  - Precedent for external tools on pi exists: the pi-hypa package adds `hypa_*` tools
-    and context-mode adds `ctx_*` tools; distribution is `pi install npm:@...`.
-- Riskiest assumption: that `ask_questions` is a faithful-enough substitute inside
-  restricted mode tool lists — i.e. that mode tool filters will admit it and the
-  agents actually exercise mid-run questioning in pi.
-- What would invalidate this idea:
-  - If remapping `ask_user` → `ask_questions` does not restore questioning in pi modes
-    (e.g. mode tool lists are a hard allow-list that excludes it), the headline fix is
-    a no-op and the problem needs a different shape.
-  - If a package scan finds no existing skill tool AND prompting proves sufficient in
-    practice, the "skill tool later" half should be dropped or demoted to a note.
-
-## Constraints
-- Cortex conventions: extensions stay lightweight (no internal LLM calls); agents/skills
-  come from composable sources; `token-map.json` is the single source of truth for
-  cross-harness tool naming; changes ship via `pnpm changeset`.
-- pi intentionally has no permission popups — the mapping must map onto what pi is, not
-  force pi semantics to change.
-- agent-modes currently warns-and-omits null tools and passes unknown names through;
-  flipping gaps to loud errors changes that contract, and generated copilot/claude
-  output (which already has real mappings) must stay stable.
-
-## Next validation step
-- (done — shipped via agnt-ctx-f4au) Remap `ask_user` → `ask_questions` in `token-map.json`, then run a pi session in
-  `ralph-plan`/`plan` mode and confirm the tool is available and the startup warning is
-  gone. If it works, ship that remap first (smallest verifiable slice).
-- Scan npm/pi packages for an existing skill-invocation tool before designing one —
-  adopt over invent (same stance as the user's marketplace instinct).
-- Run the audit: list every tool across `agents/*/pi/frontmatter.json` and mark each as
-  mapped-native / mapped-extension / unmapped.
-
-## Notes
-- Current pi-mode declarations: `ralph-plan` = bash view edit create grep glob ask_user;
-  `plan` adds task read_agent skill; `strategy` adds ask_user skill web_fetch.
-- `token-map.json` notes for `ask_user` ("pi intentionally ships no permission-popup/ask
-  tool") and `skill` ("pi discovers skills but the agent loads them via read and
-  /skill:name") both need updating if the mappings change.
-- pi keeps skill affordances present without a skill tool via the always-listed
-  "Available skills — invoke when relevant" context block; the doc-now `skill` mapping
-  builds on that existing mechanism.

package/docs/ideas/model-selector.md

@@ -1,40 +0,0 @@
-# Idea: model-selector
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-07-12
-
-## Problem
-Selecting the right model for a task is manual and brittle. When a model is unavailable (rate-limited, down, or lacking capability), there's no automatic fallback. You have to know which model IDs to type into `/model` and remember which providers offer which capabilities.
-
-## Who benefits
-Anyone using PI who runs multiple models/providers. The extension makes model selection declarative: "I want to write code" → extension picks the best available model (and falls back if limits are hit).
-
-## Proposed outcome
-A PI extension that defines an abstraction for selecting models based on task/use case. Users declare "use case → model(s) with fallbacks" in config, and the extension handles selection and failover automatically.
-
-Key capabilities:
-- **Use-case profiles**: e.g. `code`, `chat`, `review`, `architect` — each maps to a primary model + ordered fallbacks
-- **Automatic fallback**: if the primary model returns a 429 or error, drop to the next in the chain
-- **Task-based selection**: think "I want this model to write code" instead of choosing a specific model ID
-- **Configurable**: profiles defined in settings.json or a dedicated config file
-
-## Validity check
-- Evidence we already have: The existing `tiny-model.ts` lib in this repo already shows the pattern of configuring a model by provider/id string and looking it up via `modelRegistry.find()`. The PI extension API supports `before_provider_response` (for catching 429s) and `model_select` events.
-- Riskiest assumption: That use-case profiles are a useful abstraction — users may prefer to just name a model family and let fallback be implicit.
-- What would invalidate this idea: If PI adds built-in model routing/fallback, or if users find the abstraction adds confusion rather than removing it.
-
-## Constraints
-- Must not add LLM calls internally (per extension conventions in AGENTS.md)
-- Must work with the existing `modelRegistry` API — no monkey-patching
-- Storage/config should go in settings.json or `~/.pi/agent-cortex/` (global, cross-project)
-
-## Next validation step
-Sketch the config schema and test it against real usage patterns. Does the profile abstraction hold up for the models/providers you actually use?
-
-## Notes
-- Initial conversation during planning session 2026-07-12. Idea recorded as backlog, to be fleshed out when time permits.
-- Could draw on patterns from OpenRouter's routing and the existing `modelOverrides` in models.json.
-- The `notify` extension already intercepts provider responses — similar pattern for catching rate limits.

package/docs/ideas/pi-task-memory.md

@@ -1,34 +0,0 @@
-# Idea: PI Task Memory Skill
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Why it might be useful
-PI has no built-in task memory. Agents lose context between sessions — they can't track what a task has done, what decisions were made, or where they left off. A skill that persists task-scoped knowledge in structured markdown would let agents pick up work without re-discovering context from scratch, and give humans a readable audit trail they can review or promote into real documentation.
-
-## How we might do it
-**Possibly build on top of `bd remember`** rather than creating a separate storage system. Worth exploring whether `bd remember`'s existing infrastructure (persistence, cross-session survival, auto-injection) could be extended with task-scoping and structure, vs building something standalone.
-- **Task-linked** — memories keyed to specific bead/task IDs so they can be retrieved in context
-- **Progressively discoverable** — the agent recalls relevant memories as it picks up work, not all at once
-- **Structured** — consistent format that's easy to scan, edit, or promote
-- **Promotable** — easy to elevate a memory into real repo documentation (e.g. `docs/`, `AGENTS.md`) once it's proven stable
-
-If `bd remember` turns out to be the right foundation, the skill would add **task-scoping discipline, structure, and a promotion workflow** on top. But that's to be determined.
-
-## When to think about it
-- After the current skill set stabilises (refactor-to-template work, bead workflow, CI/CD pipeline)
-- Not blocked by anything, but benefits from a stable foundation
-
-## Priority
-Low / backlog — useful but not urgent. Current memory surfaces (bd remember, context-mode) cover some of the gap already.
-
-## Open questions
-- What triggers writing a memory? (Agent decides? Skill hook on task close? Specific prompts?)
-- What does "progressively discoverable" mean in practice — agent reads task memories at session start, or on-demand when picking up a task?
-- What does "elevate into docs" look like — export memory to markdown file, or just reference the memory in docs?
-- How to structure memory keys for task-scoping? (e.g. `task-<bead-id>-<topic>`, or a naming convention?)
-
-## Notes
-- **What bd remember already provides**: persistent cross-session memories, auto-injection at `bd prime`, searchable via `bd memories <keyword>`, stored in Dolt database.
-- **Worth exploring**: could this skill layer task-scoping discipline (memories keyed to bead IDs), structured format, progressive discovery (not all memories at once), and a promotion workflow on top of `bd remember`? Or does it need its own system?
-- Could be a **PI extension** (event hooks) rather than a skill (invoked on-demand) if memories should be written automatically during task work.

package/docs/ideas/qa-extension.md

@@ -1,43 +0,0 @@
-# Idea: qa-extension
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-07-12
-
-## Problem
-When an agent needs clarification during a task (e.g. during a grilling session, resolving ambiguity, or making a recommendation), it has no structured way to ask the user a question and wait for an answer. The current workaround is unstructured prompting — the agent guesses, rambles, or proceeds with incomplete information. This makes grilling sessions less productive and wastes turns.
-
-## Who benefits
-Anyone using PI agents for interactive work — especially during planning, grilling, and design sessions where the model needs to ask a series of questions one at a time and get focused answers.
-
-## Proposed outcome
-A PI extension that registers a `qa` or `ask` tool that the LLM can call to ask the user a question. The tool:
-- Presents the question (and optionally multiple-choice options or a recommendation)
-- Pauses the agent and waits for the user's response
-- Returns the user's answer to the model so it can continue
-- Supports multi-turn Q&A sessions (series of questions)
-
-This mirrors the built-in `ask_clarification` / `question` tools in Claude Code, GitHub Copilot Chat, and similar coding agents.
-
-## Validity check
-- Evidence we already have: The PI extension API supports custom tools with user interaction via `ctx.ui` (input, confirm, select). The `subagent` extension already demonstrates complex async tool patterns. Claude Code and Copilot both ship this — it's a proven pattern.
-- Riskiest assumption: That the tool execution model in PI can support a "pause and wait for user input" flow without blocking the agent loop awkwardly.
-- What would invalidate this idea: If PI adds a built-in `ask_user` tool, or if the UX of blocking the agent loop for input feels worse than the current unstructured approach.
-
-## Constraints
-- Must work in both TUI and RPC modes (graceful fallback in non-interactive modes)
-- Should support at minimum: free-text input, confirm/deny, and multiple-choice selection
-- Questions and answers should be visible in the session history so they survive compaction
-- Must handle abort (Ctrl+C mid-question) gracefully
-
-## Next validation step
-1. **Investigate existing extensions first** — search PI's built-in tools, extension registry, and community repos for an existing `ask`/`qa`/`question` tool before building. May already be available.
-2. If no existing extension: check the PI tool execution model to see if a custom tool can return a partial result and then receive follow-up input from the user. Look at how `ctx.ui.input()` and `ctx.ui.confirm()` behave inside tool execution — can they block and return, or do they need a different pattern?
-
-## Notes
-- **Needs investigation** — check for existing PI extensions/tools before building.
-- Initial conversation 2026-07-12. Motivated by making grilling sessions more efficient — the grill-me skill asks one question at a time, and a structured Q&A tool would make that flow tighter.
-- Related to `grill-me` skill (`skills/productivity/grill-me/SKILL.md`) — this extension could become the runtime that grill-me delegates its questioning to.
-- Possible names: `/ask`, `qa`, `question` tool.

package/docs/ideas/record-idea-implementation-questions.md

@@ -1,68 +0,0 @@
-# Idea: record-idea-implementation-questions
-
-## Status
-Folded into bead `agnt-ctx-s5xd.2.2` (2026-09-22) — the `record-idea` bead rewrite absorbs these
-questions and the `## Design so far / provenance` section. Not a standalone bead.
-
-## Created
-2026-08-30
-
-## Problem
-The `record-idea` interview captures *why / how / when / priority* but not enough about the
-implementation to give a recorded idea a sufficient shape. Ideas often arrive with backstory —
-they've come from somewhere (a previous session, a conversation, a pain point in another
-skill), they carry partial design thoughts or ruled-out approaches, and a bare title plus
-"how we might do it" loses that detail. The record ends up thinner than the thinking that
-produced it.
-
-## Who benefits
-Anyone reading an idea record later (the author, plan agents, ralph) — a record with an
-implementation shape and its provenance is far easier to pick up than one that restates the
-title. The author also saves re-explaining context: capture it once, at the source.
-
-## Proposed outcome
-Extend the `record-idea` interview and template:
-
-1. **A fixed, short set of implementation questions** baked into the interview — roughly:
-   - Rough mechanism: what shape would the implementation take (skill / extension / agent /
-     script / convention)?
-   - Known constraints or tradeoffs already spotted?
-   - Existing design thoughts: anything already designed, sketched, or ruled out?
-2. **A couple of adaptive follow-ups** when the fixed answers open a thread worth pulling —
-   but explicitly bounded: this is capture, not solutionising. The moment the conversation
-   drifts into implementation detail, stop and record.
-3. **New template section** — e.g. `## Design so far / provenance` — where pre-existing
-   thoughts (where the idea came from, partial designs, discarded options) are recorded so
-   they survive under the title instead of being lost.
-
-## Validity check
-- Evidence we already have: the last few recorded ideas (self-flushing-session,
-  state-in-beads-not-md) arrived with real backstory — provenance and pre-existing design
-  choices were captured only because the session happened to cover them; the skill itself
-  doesn't ask. The existing interview already draws out why/how/when/priority, so adding two
-  more question groups is a small, natural extension.
-- Riskiest assumption: the balance between "capture shape" and "solutionising session".
-  Too many follow-ups and the interview bloats; the record becomes a design doc and the
-  author resists using the skill. Needs an explicit off-ramp ("enough — record it").
-- What would invalidate this idea: if the fixed questions mostly produce "unknown / not
-  thought about yet" answers — then the added friction isn't buying anything and the template
-  section stays empty. Watch whether follow-ups actually surface design thoughts in practice.
-
-## Constraints
-- Keep the interview fast: a couple of questions, a couple of bounded follow-ups, then record.
-- Must not turn into a solutionising session — capture existing thinking, don't generate new
-  design.
-- Lands naturally alongside the `record-ideas-as-beads` rewrite of `record-idea` (bead-based
-  creation): this skill change rides that migration rather than forking it.
-
-## Next validation step
-Fold the fixed questions + `## Design so far / provenance` section into `record-idea` next
-time it's exercised (or during the record-ideas-as-beads rewrite), then check the next few
-records: did they capture backstory that would otherwise have been lost, and did the
-interview stay short?
-
-## Notes
-Recorded 2026-08-30 (P2). Applies to the current file-based flow and the future bead-based
-flow (`record-ideas-as-beads` plans interview → `bd create --notes ...`; the provenance
-section maps into `--notes` with markers). Explicitly a capture improvement, not a design
-step — the line is: record what the user already thinks, don't co-design with them.

package/docs/ideas/record-ideas-as-beads.md

@@ -1,115 +0,0 @@
-# Idea: record-ideas-as-beads
-
-## Status
-Fleshed out 2026-08-25 — design decisions locked in an interview; not yet implemented.
-
-## Created
-2026-08-25
-
-## Problem
-Ideas currently live as loose markdown files in `docs/ideas/`. This sits awkwardly alongside
-the rest of the workflow, which is almost entirely bead-based (bd). Because ideas aren't beads,
-they can't be searched with `bd label`, can't express relationships/dependencies to real tasks,
-can't be given priority that surfaces alongside other work, and can't sync to remote via
-`bd dolt push`. There's no clean promotion path from "idea" to "epic" to "executable task".
-
-## Who benefits
-The author's daily planning loop. Ideas are the beginning of epics, so making them first-class
-beads gives a single coherent backlog where an idea can grow relationships to the tasks it
-spawns. The plan/agent-nexus agents benefit too: agent-nexus will eventually schedule work
-through planning stages (not just execution), and a beads-native idea record gives it a clean
-input to plan against.
-
-## Proposed outcome
-Record ideas as beads labelled `kind:idea`, replacing `docs/ideas/*.md` entirely (bead-only —
-files deleted after migration). `bd` already supports labels natively (`bd create -l`,
-`bd label add/list`). An idea bead maps directly to an epic; promoting it means spawning task
-beads as children and letting the idea bead become the epic node.
-
-## Fleshed-out design (decided 2026-08-25)
-
-### Label & identification
-- **`kind:idea` label** marks idea beads. Ideas do NOT use `deferred` status — they stay
-  `open` so they're visible to idea tooling; hiding from actionable work is done by exclusion,
-  not status.
-- **ralph excludes them**: ready queries use `bd ready --exclude-label kind:idea`
-  (verified: `bd ready` supports `--exclude-label`). Idea beads never appear as claimable work.
-- Optional companion labels: `priority:<0-4>`, `epic:<id>` once promoted.
-
-### Flesh-out workflow (the skill that consumes them)
-There should be a **flesh-out skill** (e.g. `flesh-out-idea`) that answers: *"which idea beads
-are ready to be fleshed out?"* This is `bd ready -l kind:idea` — the blocker-aware ready query
-scoped to ideas. Because `bd ready` already respects dependencies, an idea bead that
-`depends-on` in-flight work (e.g. "needs unified-ci-pipeline landed first") naturally shows as
-*not ready* until its deps close. That's exactly the semantics wanted:
-- `bd ready -l kind:idea` → list & pick an idea ready for fleshing.
-- The skill runs the record-idea-style interview (why / how / when / priority) at deeper depth,
-  updating the bead's description/design/notes as the idea ripens.
-- Once fleshed out enough, the idea can be promoted (below).
-
-### Promotion path: idea → epic → tasks
-Parent-child hierarchy (chosen over labels+deps only):
-1. Idea bead starts with `kind:idea`, type defaulted appropriately (still `task` type, or set
-   `epic` type on promotion).
-2. On promotion: `bd label add <idea> epic:<idea-id>` (or flip to an epic label), then spawn
-   task beads with `--parent <idea-id>` — children inherit the epic relationship natively.
-3. The idea bead becomes the epic node; its children are the executable tasks. Closing the
-   children resolves to the epic closing.
-
-### Content model (bead fields)
-Map the current idea-template sections onto bd fields:
-| md template field | bd field |
-|---|---|
-| Title | `--title` |
-| Problem / Why | `--description` |
-| How we might do it | `--design` |
-| When / Priority / Validity / Constraints / Notes | `--notes` (structured, keep section markers) |
-| anything referential | `--context` |
-
-Multiple sections per field use explicit markers (`## Validity check`, etc.) inside the field
-so the flesh-out interview can find/update them later.
-
-### Skill changes
-- **`record-idea`**: replace scaffold-file flow (`new-idea.sh` → `docs/ideas/x.md`) with bead
-  creation: interview → `bd create "<title>" -l kind:idea -d "<why>" --design "<how>"
-  --notes "<when/priority/validity>"`. Keep the interview; drop the markdown scaffold script.
-- New **`flesh-out-idea`** skill (see above) — validates readiness (`bd ready -l kind:idea`),
-  picks an idea, drives the deepening interview, updates the bead, optionally promotes.
-
-### Migration
-- Bulk-migrate the existing `docs/ideas/*.md` records to beads: read each file, map sections to
-  bd fields, `bd create -l kind:idea`, preserve priority. Run as a one-off (manual or scripted).
-- Then **delete `docs/ideas/`** — bead-only going forward.
-- Update `AGENTS.md` + any stale references that point at `docs/ideas/`.
-- The `record-idea` skill itself must unlearn the docs/ideas path.
-
-## Validity check
-- Evidence we already have: `bd ready --exclude-label` and `bd ready -l` both exist and compose
-  (label filtering + blocker-aware ready semantics) — the two core mechanisms this idea needs
-  are native, no feature build. `--parent` exists for the hierarchy. 9-10 idea files exist to
-  migrate; the record-idea skill and its script are the only two consumers of the file flow.
-- Riskiest assumption: that keeping ideas `open` (not `deferred`) + label exclusion is
-  discoverable enough — ralph, plan agents, and the author must remember the exclusion. The
-  `bd-tool` skill's labels table needs `kind:idea` documented with the exclusion convention.
-- What would invalidate this idea: if label-based exclusion leaks idea beads into `bd ready`
-  via some path (e.g. `bd ready` without the exclude flag), or if losing the scannable
-  `docs/ideas/` directory hurts occasional review more than bead queries help it.
-
-## Constraints
-- Ideas stay quick to scan: `bd list -l kind:idea` + `bd show <id>` should be a comfortable
-  replacement for opening the directory.
-- Idea beads must never appear in ralph's actionable-ready view.
-- `record-idea` and `bd-tool` skills stay consistent — no stale references to docs/ideas.
-- Priority of ideas uses the same P0-P4 scale as tasks (P4 = backlog default for ideas).
-
-## Next validation step
-Prototype one idea as a labelled bead: create it with `-l kind:idea`, confirm `bd ready`
-excludes it by default and `bd ready -l kind:idea` surfaces it; then promote it (add epic label,
-spawn a child task) to confirm the hierarchy reads correctly. If the prototype passes, do the
-bulk migration + skill updates.
-
-## Notes
-Interview on 2026-08-25 locked: labels over status (kind:idea + ralph exclusion), bead-only
-content (files deleted), parent-child promotion, and record-idea skill rewritten to create
-beads. Agent-nexus is the planned consumer. Once this lands, this very record becomes an
-idea-bead (and then this file is deleted — the migration eats its own tail).

package/docs/ideas/self-flushing-session.md

@@ -1,72 +0,0 @@
-# Idea: self-flushing-session
-
-## Status
-Backlog idea (not implementation-ready) — priority P1 (high)
-
-## Created
-2026-08-30
-
-## Problem
-Sessions hold context far longer than needed. Every turn, tangent, and tool call stays in
-the window until a human notices the bloat and compacts or resets. The opposite of the
-current default: the agent should own its context lifecycle. It holds context *just long
-enough* to record the immediate outcome — as a bead — and then dumps everything, keeping
-only the bead ID. State is the enemy: no more than the immediately useful context is kept
-at any moment.
-
-## Who benefits
-The author daily (token cost + focus — sessions never bloat, ever, regardless of how long
-the overall thread runs), and every future agent that must run long-lived threads. Beads
-become the entire memory surface: searchable, syncable, dependency-aware — no separate
-transcript or memory file to maintain.
-
-## Proposed outcome
-A session model where:
-1. **The agent decides when to flush.** No human noticing bloat and intervening — the agent
-   watches for task completion and purges its own context.
-2. **Hold just enough** to write the immediate outcome as a bead, then **dump all context,
-   keeping the bead ID**. The ID is the only thing that survives the flush.
-3. **Beads are the memories.** No separate memory store; the beads *are* the session memory.
-   Progressively discovered — a fresh context pulls in relevant beads on demand (by ID/deps/
-   labels) rather than exchanging the whole history every turn.
-4. **A parent bead represents the session.** One session bead per conversation; the child
-   memory beads (outcomes) hang under it, discovered progressively rather than loaded whole.
-
-Flush trigger to be fleshed out at design time: *"once a task is complete — that probably
-means a bead is written, but might not."* So: task completion is the event; bead-writing is
-the expected (but not guaranteed) artifact of it.
-
-## Validity check
-- Evidence we already have: beads natively support parent/child hierarchy (`--parent`), labels,
-  deps, search (`bd label`, `bd list`), and the ralph pipeline already treats beads as
-  self-contained executable units. `task-session-context` (recorded 2026-08-25) establishes the
-  "session is disposable, bead is the artifact" principle — this idea is the mechanism for it.
-- Riskiest assumption: an agent deciding to purge its *own* context is self-referential —
-  mid-flush failures, deciding to dump while in-flight state matters, or dumping too early
-  would lose work. Also: whether the harness (pi/Copilot CLI) exposes enough session-lifecycle
-  control (start/stop/seed context, hard reset mid-thread) to make the flush mechanical rather
-  than prompt-instructed.
-- What would invalidate this idea: if flush can't be made reliable as a mechanism (prompt-level
-  "now clear your context" is fragile — the harness may not actually drop context), or if
-  progressive discovery from beads proves lossy enough that flushed tasks mis-execute.
-
-## Constraints
-- State minimisation is the point: keep only what the current task needs.
-- The bead ID is the only cross-flush pointer — everything else must be re-discoverable.
-- Must compose with existing loops: ralph stages, HITL handoffs, record-idea flow.
-- Extension vs agent is unresolved by design: an **extension** could mechanize flush + bead
-  write via event hooks; an **agent** could own the session lifecycle and decide. Both recorded
-  as candidate shapes — decide at design time.
-
-## Next validation step
-Design-time fleshing-out: nail the flush trigger rules, the parent-session-bead structure,
-how a fresh context seeds itself (pull-by-ID vs pull-by-label), and whether pi/Copilot expose
-enough lifecycle control for a mechanical flush. Then a spike: one task completing → bead
-written → flush → fresh context re-seeding from the bead ID without losing the thread.
-
-## Notes
-Recorded 2026-08-30 (P1, high). Cross-linked with `task-session-context` (principle) — this
-record is the sharper mechanism: autonomous flush, beads-as-memory (no separate store), parent
-session bead. Also adjacent to `pi-task-memory` (progressive discovery of memories) and
-`state-in-beads-not-md` (notes/state live in beads, not files) — the three records converge on
-"beads are the durable unit; context is a disposable implementation detail".