@jaybeeuu/agent-cortex 1.39.0 → 1.41.0

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

@@ -1,7 +1,9 @@
 # Idea: Improve PI System Prompt
 
 ## Status
-Backlog idea (not implementation-ready)
+Backlog idea (not implementation-ready) — first slice (circuit-breakers, check-in triggers,
+atomic-change discipline) implemented as the `agent-guardrails` pi extension; 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.
@@ -26,9 +28,10 @@ High — after current work lands. Directly impacts daily productivity and token
 - 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)?
-- How should circuit-breakers interact with skills like `run-pipeline-stage` that already have structured workflows?
 
 ## Notes
+- **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

@@ -0,0 +1,95 @@
+# 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/record-idea-implementation-questions.md

@@ -0,0 +1,68 @@
+# 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/self-flushing-session.md

@@ -0,0 +1,72 @@
+# 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".

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

@@ -0,0 +1,69 @@
+# 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/task-session-context.local.md

@@ -0,0 +1,95 @@
+# 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/test-data-creation-helpers.md

@@ -0,0 +1,92 @@
+# 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

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

@@ -0,0 +1,39 @@
+# 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.