@jaybeeuu/agent-cortex 2.0.0 → 2.2.0

package/docs/ideas/state-in-beads-not-md.md

@@ -1,69 +0,0 @@
-# Idea: state-in-beads-not-md
-
-## Status
-Recorded as bead `agnt-ctx-ul91` (2026-09-22) — awaiting `plan`. Merged with
-`bead-progress-notes-for-session-resumption.md` into one bead state model design (this file is
-Part 1: WHERE state lives).
-
-## Created
-2026-08-30
-
-## Problem
-Skills write a lot of operational documents that are never meant to be committed or read
-by humans at rest — they describe transient notes/current state. Today they land as md files:
-- `hitl-collab` writes `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md` — one file per
-  bead, near-duplicating information that already lives (or should live) on the bead.
-- `run-pipeline-stage` / `ralph` write `.agent-cortex/ralph/ralph-{bead-id}.log` and
-  `.agent-cortex/ralph/progress.md` for live progress surfacing.
-These files duplicate bead state, rot as the bead changes, and fragment context across
-files + beads. They're also invisible to `bd` tooling (search, deps, sync).
-
-## Who benefits
-Every agent skill run that produces state (hitl-collab, ralph, run-pipeline-stage, plan,
-and any future skill that takes notes). The author benefits from a single source of truth,
-and ralph/pipeline state stops living in a `.agent-cortex` attic that drifts from the beads.
-
-## Proposed outcome
-A general rule stored in agent docs: **any artifact that is notes/current state — not
-intended as committable durable documentation — lives in the bead's fields** (`--notes`,
-`--context`, `--design`), not in md files.
-- Durable, committable docs (SKILL.md, REFERENCE.md, playbooks/, prompts/, docs/) stay files.
-- `hitl-collab` handoff: write the handoff content into the HITL bead (`--context`/`--notes`),
-  drop the `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md` file flow.
-- ralph progress/log lines: feed a live progress view off the beads (or a temp/log file kept
-  explicitly out of the `working-docs` convention) — spike details during planning.
-- `record-idea`'s caveat: this same principle is what `record-ideas-as-beads` already applies
-  to idea records; this idea generalises it to operational/state artifacts.
-
-## Validity check
-- Evidence we already have: `bd` fields (`--notes`, `--context`, `--design`) support the content
-  model; `record-ideas-as-beads` already proves bead-field content is workable for structured
-  records (design decided 2026-08-25). Bead notes are multi-line and markdown-capable.
-- Riskiest assumption: live progress surfacing (ralph's log tail / progress.md) can be
-  satisfied without a scratch file — the bead-update round-trip may be too slow/chatty for
-  high-frequency log lines; may need a per-run scratch log that is explicitly ephemeral and
-  deleted on close, rather than a persistent working doc.
-- What would invalidate this idea: if bead fields become unwieldy for large attachments (e.g.
-  long PR summaries), or if a future agent needs shared state that must not be per-bead
-  (cross-bead coordination) — that's a different problem, not a per-bead note.
-
-## Constraints
-- Bead content is portable and searchable: `bd show <id>` must remain a comfortable read
-  surface for handoff/notes.
-- Never regress committable docs into beads (AGENTS.md/skills stay in-repo markdown).
-- P2 (medium): actively annoying today — hitl-collab handoff docs are already duplicating
-  bead state.
-
-## Next validation step
-Pick one skill (hitl-collab is the smallest, clearest case): prototype writing the handoff
-into the bead's `--context` (or `--notes`) and read it back with `bd show`, confirm the
-HITL reader (ralph/plan/handoff skill) can consume bead-stored handoffs; then extend the
-rule to ralph progress with an ephemeral-scratch-log fallback if needed.
-
-## Notes
-Cross-link: sibling idea `record-ideas-as-beads` (fleshed out 2026-08-25) covers ideas
-specifically — once it lands, docs/ideas/ disappears and this record becomes a bead too.
-The rule here is the generalisation: beads are for state, files are for durable docs.
-Skills that currently write working docs: `hitl-collab` (handoff.md), `ralph` +
-`run-pipeline-stage` (ralph-*.log, progress.md). Update `bd-tool`/`git-workflow`/AGENTS.md
-conventions if the rule lands.

package/docs/ideas/subagent-visibility.md

@@ -1,72 +0,0 @@
-# Idea: subagent-visibility
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-08-25
-
-## Problem
-The bundled `subagent` extension delegates work to separate `pi` processes with isolated
-context windows. It streams output live, shows per-agent usage stats (turns, tokens, cost), and
-supports abort — but after a run there's no retained record of what each subagent actually did
-(files touched, decisions, blockers), and while a run is in flight there's no richer
-dashboard-level view of what each agent is up to. There's also no way to influence a running
-subagent: you can only watch or Ctrl+C the whole thing. For the ralph-style parallel dispatches
-(up to 5 concurrent chores) this is a real blind spot.
-
-## Who benefits
-The author, whenever running parallel subagent work (ralph pipeline chores, parallel research).
-A live dashboard helps during runs; persisted per-run reports turn subagent work into a
-reviewable after-action record (which also complements the HITL/summary flow). Mid-run steering
-reduces wasted tokens from subagents heading the wrong way and having to restart.
-
-## Proposed outcome
-Expand (or adopt, if a store extension fits) subagent tooling to give:
-
-1. **Live dashboard** — richer TUI during runs: per-agent status (phase, current tool call,
-   files touched), so you can see what each parallel subagent is doing without digging into
-   streamed output.
-2. **Persisted reports** — a per-run record per subagent (what it did, files changed,
-   decisions, blockers), stored for after-action review. Persistence should follow the repo
-   convention: write to `~/.pi/agent-cortex/`, tagged with project path for per-project slicing.
-3. **Mid-run steering** — send a message to a running subagent to change its direction
-   ("skip that, focus on X") rather than killing and restarting.
-
-Decision from the interview: **evaluate the pi extension store first** — if a maintained
-extension already covers dashboard + reports (and ideally steering), adopt it; otherwise expand
-the bundled `subagent` extension. Building is a fallback, not the default.
-
-## Validity check
-- Evidence we already have: the bundled `subagent` extension is a working base — it already
-  spawns `pi` subprocesses, streams, and collects usage data, so the hooks for a dashboard and
-  reports exist in some form. The repo has a data convention (`~/.pi/agent-cortex/`, per-project
-  tagging) that reports would slot into.
-- Riskiest assumption: that mid-run steering is technically feasible — subagents run as separate
-  `pi` processes, so steering likely needs a message channel (e.g. a FIFO / IPC pipe into the
-  running process, or a PI-native way to inject input). If the process model doesn't allow input
-  mid-run, the interaction half collapses to "abort and re-dispatch with corrected instruction".
-- What would invalidate this idea: if store extensions are all visibility-only (no steering) and
-  the process model rules out mid-run input, the remaining value is dashboard + reports only.
-  Also, if subagents use private pipes that block reading live state cheaply, the dashboard may
-  be constrained to what the streamer already shows.
-
-## Constraints
-- Keep it lightweight and consistent with the repo's extension conventions (no internal LLM
-  calls in the extension itself).
-- Should compose with ralph's parallel dispatch (up to 5 concurrent chores) without making the
-  TUI unusable.
-- Steering must be safe: a message is advisory input to the subagent, not a force-kill;
-  abort stays available.
-
-## Next validation step
-Two-part check before building: (1) search the pi extension store for subagent/dashboard/steering
-extensions and evaluate against this wishlist; (2) verify whether a running `pi` subagent
-process accepts input mid-run (checked against how the subagent extension spawns processes and
-whether PI exposes any IPC/input channel) — this decides whether steering is scoped in.
-
-## Notes
-Recorded 2026-08-25. Interview decisions: visibility = both live dashboard AND persisted
-per-run reports; interaction = mid-run steering (not approve-gates, not pause/resume); path =
-evaluate store first, fall back to expanding the bundled `subagent` extension. Complements
-`unified-ci-pipeline` (pipeline visibility) and the ralph parallelism work in this repo.

package/docs/ideas/task-session-context.local.md

@@ -1,95 +0,0 @@
-# Idea: task-session-context
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-08-25
-
-## Problem
-Coding sessions accumulate context turn by turn: every question, every tool call, every
-tangent stays in the window until it's manually compacted or the session is restarted. Keeping
-the context small and relevant is an active management burden — the author has to notice the
-bloat, decide what matters, and intervene. Long conversations either burn tokens or require
-frequent manual resets that drop useful memory.
-
-## Who benefits
-The author, daily. Removing context management from the loop means sessions stay small and
-focused no matter how long the overall thread runs. It also produces a durable, reviewable log
-of work: each task's bead + summary memory is an audit trail of what was done and why.
-
-## Proposed outcome
-A workflow organised around **tasks** instead of sessions. Whenever the user does something
-discrete — asks a new question, records an idea, fleshes out a piece of work — it **begins a
-task**:
-
-1. **Task = blank session with memory context.** The task starts a fresh, self-contained
-   session. It does NOT get every turn and tool call of the parent conversation — only access
-   to the accumulated **memories** of what came before (a summary/compressed view, not the raw
-   transcript).
-2. **Self-contained execution.** The task works on its own: it takes action, and **records
-   memories along the way** as it produces outcomes.
-3. **Single summary memory on completion.** The last thing a task does is write one summary
-   memory capturing its outcome. These memories are additive — the running memory store grows as
-   tasks complete.
-4. **Fresh session continues the thread.** Once the task completes, a new session starts with
-   access to the memories — including the new summary — so to the user it feels like one
-   continuous thread, but each underlying session stays small.
-
-**Ties into beads (bd):** "the completion of a bead is the completion of a task". A bead becomes
-the log of work completed: the task's outcome is recorded on/with the bead, the fresh session
-starts, and the bead is accompanied by **referential memory** (a pointer/memory entry that links
-the outcome to the bead). So the bead doubles as the durable record AND the context-boundary
-marker: starting a bead is the trigger for task-session separation.
-
-**The bead is the artifact — the session is disposable.** Once a task is complete, the whole
-conversation context is no longer needed; the bead is the artifact. The current conversation is
-the live example: recording this idea is a task, and when it's done the transcript of every turn
-and tool call can be discarded — what remains is the record plus its summary/referential memory.
-This is the load-bearing philosophical point of the idea: sessions exist to serve tasks, not the
-other way around. Context is an implementation detail of a single task; the bead is the durable
-unit of history.
-
-The mechanism likely needs: a memory store (per-project, e.g. under `~/.pi/agent-cortex/` or a
-records convention), a session-scoping rule (what memories a fresh task session is seeded with),
-the summary-writing step, and the bead ↔ memory linkage.
-
-## Validity check
-- Evidence we already have: the repo already runs on beads as the unit of work (bd), and the
-  ralph pipeline already treats beads as self-contained executable units — so task-per-bead
-  separation is a natural extension of an existing pattern. Existing ideas
-  (`record-ideas-as-beads`, `pi-task-memory`, `extension-manifests`) all push in the direction of
-  making agent-cortex the declared, memory-rich source of truth.
-- Riskiest assumption: that a fresh session seeded with *memories only* (no raw transcript) is
-  sufficient context for a task — the compression of a conversation into memories must not lose
-  the specifics a task needs. Also: whether the harness (pi/Claude) even supports programmatic
-  session spawning with a seed context cleanly enough for this to feel seamless.
-- What would invalidate this idea: if memory-as-context proves lossy in a way that keeps tasks
-  mis-executing (then the blank-session model needs the raw transcript after all, defeating the
-  point); or if the session boundary machinery (start/stop/spawn with seed) fights the harness.
-
-## Constraints
-- Sessions must stay small — this is the whole point; memory is the interface, not the transcript.
-- Memories are additive and durable; the summary memory is the handoff contract between tasks.
-- The bead is the work log AND the context boundary: no task completion without its summary
-  memory and bead record.
-- Must not break the existing task loops (ralph pipeline stages, HITL handoffs) — it should
-  compose with them, not fork them.
-
-## Next validation step
-Flesh-out session (proposed by the author): nail down the trigger rules (what counts as "begin a
-task"), the memory store schema and what a "memory" is vs a summary, how a fresh session gets
-seeded, and how the bead carries the summary + referential memory. Then a spike: one task
-completing with summary → fresh session seeded → verify the thread feels continuous.
-
-## Notes
-Recorded 2026-08-25. The author explicitly wants to flesh this out later — this record captures
-the working concept. It connects several existing ideas: `record-ideas-as-beads` (beads as the
-unit of everything), `pi-task-memory` (memory as a first-class mechanism), and
-`subagent-visibility` (visibility into what task sessions do).
-
-**Amendment (2026-08-30):** see `self-flushing-session` — the sharper mechanism record for this
-principle: agent autonomously decides when to flush, beads *are* the memory store (no separate
-system), a parent session bead holds the conversation with child outcome beads discovered
-progressively, and the bead ID is the only thing kept across a flush. This record remains the
-principle; `self-flushing-session` is the mechanism.

package/docs/ideas/task-session-context.md

@@ -1,89 +0,0 @@
-# Idea: task-session-context
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-08-25
-
-## Problem
-Coding sessions accumulate context turn by turn: every question, every tool call, every
-tangent stays in the window until it's manually compacted or the session is restarted. Keeping
-the context small and relevant is an active management burden — the author has to notice the
-bloat, decide what matters, and intervene. Long conversations either burn tokens or require
-frequent manual resets that drop useful memory.
-
-## Who benefits
-The author, daily. Removing context management from the loop means sessions stay small and
-focused no matter how long the overall thread runs. It also produces a durable, reviewable log
-of work: each task's bead + summary memory is an audit trail of what was done and why.
-
-## Proposed outcome
-A workflow organised around **tasks** instead of sessions. Whenever the user does something
-discrete — asks a new question, records an idea, fleshes out a piece of work — it **begins a
-task**:
-
-1. **Task = blank session with memory context.** The task starts a fresh, self-contained
-   session. It does NOT get every turn and tool call of the parent conversation — only access
-   to the accumulated **memories** of what came before (a summary/compressed view, not the raw
-   transcript).
-2. **Self-contained execution.** The task works on its own: it takes action, and **records
-   memories along the way** as it produces outcomes.
-3. **Single summary memory on completion.** The last thing a task does is write one summary
-   memory capturing its outcome. These memories are additive — the running memory store grows as
-   tasks complete.
-4. **Fresh session continues the thread.** Once the task completes, a new session starts with
-   access to the memories — including the new summary — so to the user it feels like one
-   continuous thread, but each underlying session stays small.
-
-**Ties into beads (bd):** "the completion of a bead is the completion of a task". A bead becomes
-the log of work completed: the task's outcome is recorded on/with the bead, the fresh session
-starts, and the bead is accompanied by **referential memory** (a pointer/memory entry that links
-the outcome to the bead). So the bead doubles as the durable record AND the context-boundary
-marker: starting a bead is the trigger for task-session separation.
-
-**The bead is the artifact — the session is disposable.** Once a task is complete, the whole
-conversation context is no longer needed; the bead is the artifact. The current conversation is
-the live example: recording this idea is a task, and when it's done the transcript of every turn
-and tool call can be discarded — what remains is the record plus its summary/referential memory.
-This is the load-bearing philosophical point of the idea: sessions exist to serve tasks, not the
-other way around. Context is an implementation detail of a single task; the bead is the durable
-unit of history.
-
-The mechanism likely needs: a memory store (per-project, e.g. under `~/.pi/agent-cortex/` or a
-records convention), a session-scoping rule (what memories a fresh task session is seeded with),
-the summary-writing step, and the bead ↔ memory linkage.
-
-## Validity check
-- Evidence we already have: the repo already runs on beads as the unit of work (bd), and the
-  ralph pipeline already treats beads as self-contained executable units — so task-per-bead
-  separation is a natural extension of an existing pattern. Existing ideas
-  (`record-ideas-as-beads`, `pi-task-memory`, `extension-manifests`) all push in the direction of
-  making agent-cortex the declared, memory-rich source of truth.
-- Riskiest assumption: that a fresh session seeded with *memories only* (no raw transcript) is
-  sufficient context for a task — the compression of a conversation into memories must not lose
-  the specifics a task needs. Also: whether the harness (pi/Claude) even supports programmatic
-  session spawning with a seed context cleanly enough for this to feel seamless.
-- What would invalidate this idea: if memory-as-context proves lossy in a way that keeps tasks
-  mis-executing (then the blank-session model needs the raw transcript after all, defeating the
-  point); or if the session boundary machinery (start/stop/spawn with seed) fights the harness.
-
-## Constraints
-- Sessions must stay small — this is the whole point; memory is the interface, not the transcript.
-- Memories are additive and durable; the summary memory is the handoff contract between tasks.
-- The bead is the work log AND the context boundary: no task completion without its summary
-  memory and bead record.
-- Must not break the existing task loops (ralph pipeline stages, HITL handoffs) — it should
-  compose with them, not fork them.
-
-## Next validation step
-Flesh-out session (proposed by the author): nail down the trigger rules (what counts as "begin a
-task"), the memory store schema and what a "memory" is vs a summary, how a fresh session gets
-seeded, and how the bead carries the summary + referential memory. Then a spike: one task
-completing with summary → fresh session seeded → verify the thread feels continuous.
-
-## Notes
-Recorded 2026-08-25. The author explicitly wants to flesh this out later — this record captures
-the working concept. It connects several existing ideas: `record-ideas-as-beads` (beads as the
-unit of everything), `pi-task-memory` (memory as a first-class mechanism), and
-`subagent-visibility` (visibility into what task sessions do).

package/docs/ideas/test-data-creation-helpers.md

@@ -1,92 +0,0 @@
-# Idea: Test data creation helpers
-
-## Status
-Backlog idea (not implementation-ready) — priority P2 (moderate)
-
-## Created
-2026-09-14
-
-## Problem
-Agents writing tests reach for test data the lazy way, in three shapes:
-
-1. **Shared module-scope objects used as fixtures.** Because the object is built once at
-   top-level scope and reused, every test mutates the same instance — state leaks between
-   tests, and a passing test can depend on the order in which others ran. Failures are
-   order-dependent and hard to reproduce in isolation.
-2. **Data built outside the test rather than inline.** The reader — and the next agent — must
-   scroll away from the assertion to find what the input actually was, so the test stops
-   reading as an example of the behaviour under test.
-3. **No small configurable helper.** Instead of a factory with sensible defaults and an
-   overrides argument, each test re-spells the entire literal. One field change means editing
-   every call site, and the tests silently drift apart from one another.
-
-Net effect: tests that are annoying to read, annoying to change, and occasionally lie. The
-cost is paid again on every subsequent edit.
-
-## Who benefits
-Everyone who reads or changes the suite: the author reviewing a diff, the reviewer agent
-auditing a PR, and later agents picking the code up cold. It also cuts churn in ralph pipeline
-runs, where agents write tests unattended and nobody corrects a sloppy fixture habit in the
-moment. Test authors write less boilerplate; reviewers have less to query.
-
-## Proposed outcome
-Skill-only guidance (no shipped helper code) telling the agent how to create test data:
-
-- **Build data inline in the test** (or in a helper called from it), so the test body shows the
-  shape of its own input.
-- **No shared mutable top-level fixture.** If data must be reused, it is produced fresh per
-  test by a function — a factory, not a constant. Module-scope constants are acceptable only
-  when genuinely immutable and read-only.
-- **Prefer a small configurable helper** — a factory taking partial overrides with defaults for
-  the rest — over repeated full literals. Build the helper only when reuse justifies it; a
-  single test's data stays a plain inline object.
-- **Name and locate the helper conventionally** so the next agent finds it (colocated with the
-  tests, named for what it builds).
-
-Landing: the rule belongs in `style-tests`, the skill that already governs test-writing
-conventions, with `tdd` and `engineering` pointing at it so the habit lands at authoring time.
-Per the repo's keep-skill-bodies-small convention it is a red-flag row plus a checklist item,
-not a new essay.
-
-## Validity check
-- Evidence we already have: the pattern is observed repeatedly in agent-authored tests
-  (module-scope fixtures mutated across tests, full literals duplicated per test); `style-tests`
-  already asserts behaviour-over-structure and mock discipline, so a data-construction rule fits
-  its existing remit without new philosophy; and the sibling idea `ban-content-assertion-tests`
-  shows this class of test-quality gap is real and gets fixed the same way — skill-only, red flag
-  plus checklist item. The repo already ships skills governing how tests are written, so there is
-  a known enforcement point and no new mechanism to invent.
-- Riskiest assumption: that a prose rule actually changes agent behaviour. The content-assertion
-  idea rests on the same assumption; if agents keep reaching for module-scope fixtures after the
-  rule lands, the fix is a review gate rather than more wording. Second-riskiest: that "no shared
-  top-level fixture" is not overly absolute — a genuinely immutable shared constant (a frozen
-  canonical example) is fine, so the wording must target mutability and per-test freshness, not
-  top-level scope by itself.
-- What would invalidate this idea: finding that the real cause is not agent habit but a missing
-  convention in the target projects (nowhere for a helper to live, so inline literals are the only
-  option), or that a project's test framework already ships builders the agent simply fails to
-  find — either would move the fix to discoverability or enforcement rather than a style rule.
-
-## Constraints
-- **Skill-only.** No helper library shipped from this plugin — each project owns its factories.
-- Keep `style-tests` at ~100 lines: add a red-flag row and a verification-checklist item; do not
-  expand the skill's philosophy.
-- Do not ban top-level constants outright — the rule targets mutable shared state and per-test
-  freshness.
-- Small scope: no pipeline changes beyond pointing `tdd`/`engineering` at the rule.
-
-## Next validation step
-Before implementing, grep the agent-authored tests in this repo (and one or two target projects)
-for module-scope fixture objects versus inline/per-test construction, to confirm the pattern is as
-frequent as the anecdote suggests and to capture two or three concrete before/after examples. If
-it is real, land the red-flag row in `style-tests`, add the pointer lines in `tdd`/`engineering`,
-then check the next ralph run's tests for it.
-
-## Notes
-Recorded 2026-09-14 (P2). Interview was deliberately short — this is a capture, not a spec. Timing
-signal: "it's annoying" — a recurring, low-severity papercut that costs a little on every test
-edit rather than a project-breaking defect, hence P2 rather than the P1 carried by adjacent
-content-assertion work. Stance locked in interview: skill-only guidance, no shipped helper code;
-the fix is teaching the agent the pattern, not providing a library. Related:
-`ban-content-assertion-tests.md` (same enforcement point, same shape of fix),
-`test-planning-stage-bead-in-feature-planning.md` (test-stage quality in the pipeline).

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

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

package/docs/ideas/unified-ci-pipeline.md

@@ -1,28 +0,0 @@
-# Idea: Unified CI Pipeline with Parallel Checks
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Why it might be useful
-The current CI setup has two problems:
-1. **Slow feedback** — checks run serially, making the pipeline slower than it needs to be.
-2. **Broken releases** — the release job (version branch creation) is a separate pipeline, so it can fire even when checks fail. A broken commit can reach the version branch.
-
-Combining them gives faster feedback (parallel checks) and a safety gate (release step only runs if all checks pass).
-
-## How we might do it
-- Merge the check pipeline and release pipeline into a single pipeline.
-- Fan out all checks to run in parallel.
-- Make the version branch creation a downstream job/step that depends on all checks passing.
-
-## When to think about it
-When CI pipeline speed or release safety becomes a recurring friction — e.g. after the changesets/release workflow is fully set up and seeing real traffic.
-
-## Priority
-P2 — infrastructure quality-of-life. Not blocking current work, but a clear improvement once the release flow stabilises.
-
-## Notes
-- Setup job with artifact infrastructure added (2026-08): install + build now happen once in a `setup` job, artifacts are shared with downstream jobs via upload/download-artifact. This is the first step toward the unified pipeline vision.
-- Depends on the changesets release workflow being in place (P1 beads `agnt-ctx-d1ht`, `agnt-ctx-5bcu`).
-- Should be straightforward once the pipeline shape is settled.
-- **Release pipeline fires on every push to main** — this wastes CI minutes. It should only run when there are changesets to process (e.g. when the version packages PR is merged, or when new changesets land on main). Add a path filter or a pre-check that skips the job when no `.changeset/*.md` files changed.

package/docs/ideas/unify-the-ticket-and-task-decomposition-workflows.md

@@ -1,71 +0,0 @@
-# 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/ideas/worktree-housekeeping-for-closed-beads.md

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