@jaybeeuu/agent-cortex 1.40.0 → 1.41.1

package/docs/ideas/extension-manifests.md

@@ -1,7 +1,11 @@
 # Idea: extension-manifests
 
 ## Status
-Backlog idea (not implementation-ready)
+**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.
 
 ## Created
 2026-08-25
@@ -12,12 +16,13 @@ live implicit in the machine's state (`~/.pi/agent/extensions/`) with no declare
 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's no way to uninstall cleanly.
+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 prune CLI makes extension experimentation fast and safe.
+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
@@ -37,10 +42,41 @@ Key decisions from the interview:
    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`
@@ -48,11 +84,11 @@ are deliberately excluded from the manifests — only third-party extensions are
   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). Also, the TUI prune needs the local extension store's shape
-  (`~/.pi/agent/extensions/` for pi; whatever Claude uses) to be introspectable.
+  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), or if the pi/Claude installers don't expose
-  the store in a way that supports listing + uninstall for the TUI.
+  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.
@@ -62,14 +98,19 @@ are deliberately excluded from the manifests — only third-party extensions are
 - If any local data is persisted (e.g. prune history), write to `~/.pi/agent-cortex/`.
 
 ## Next validation step
-Confirm the install surface for each harness: how `pi install <source>` works for the pi side,
-and how Claude/Copilot plugins get installed, plus whether each store can be listed and
-uninstalled programmatically (needed for the prune TUI). Then prototype the manifest + one
-harness's install-on-update path.
+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. Prune uninstalls locally only;
-the manifest stays GitHub-managed. 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.
+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,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).