@jaybeeuu/agent-cortex 2.1.0 → 2.3.0

package/docs/ideas/ban-content-assertion-tests.md

@@ -1,75 +0,0 @@
-# Idea: ban-content-assertion-tests
-
-## Status
-Filed as epic `agnt-ctx-h9gt` (2026-10-06) — awaiting `prd-to-tasks`. Slice 1 (the
-`style-tests` ban) shipped earlier in `daa77c8` (PR #143); this epic covers the review-gate
-enforcement and the skill sweep.
-
-## Created
-2026-08-30
-
-## Problem
-Ralph pipeline chores write tests that assert on static content — config files, markdown,
-terraform files, snapshots of files that never change behaviour. These tests do not prove
-behaviour; they assert content. They are irrelevant, unhelpful, and a straight waste of
-tokens: they take time to write and run, break on unrelated edits, and add maintenance
-weight for zero behavioural signal.
-
-## Who benefits
-Every ralph-managed project. Chores stop burning tokens on meaningless tests, PRs stop
-carrying noise tests, and the suite stays a genuine behavioural signal instead of a content
-inventory. Reviewers (author + agents) get less churn to triage.
-
-## Proposed outcome
-A blanket ban — **no carve-outs**: tests that assert static file contents (config, md, tf,
-or any snapshot of static content) are never written. They prove nothing about behaviour and
-belong to neither the suite nor the PR.
-
-Landing it:
-1. **`style-tests`** — add an explicit red flag (and verification-checklist item): *asserting
-   static file content — config/md/tf snapshots. If the file never changes behaviour, the test
-   is a content assertion, not a behaviour test.* The existing "test behaviour, not
-   implementation" / "every test has a cost" principles already point here — make it explicit.
-2. **`ralph` + `run-pipeline-stage`** (minimum) — the pipeline instructions should warn stage
-   runners not to write content-assertion tests; a review gate checks for them.
-3. **Sweep the rest** — before implementation, review tdd, engineering, and other skills for
-   anything that encourages or tolerates content-assertion tests, and align them with the ban.
-
-## Validity check
-- Evidence we already have: `style-tests` already champions behaviour-over-structure and
-  test-cost discipline — the red flag slots straight into its existing table without new
-  philosophy. The observed trigger came from ralph runs producing such tests unprompted,
-  which shows the current skills don't discourage it.
-- Riskiest assumption: distinguishing "asserts static content" from legitimate integration
-  tests that happen to read files (e.g. a parser's golden output). The ban must be worded to
-  hit the former without chilling the latter — the line is *whether the assertion proves the
-  behaviour under test*, not whether a file is read.
-- What would invalidate this idea: if a case emerges where asserting file content IS the
-  behaviour (a generator, a config compiler, a template renderer) and the blanket wording
-  blocks a real test — the blanket ban explicitly accepts excluding those; if that carve-out
-  turns out to be needed after all, the wording needs revisiting.
-
-## Constraints
-- Blanket ban, no carve-outs in the initial landing.
-- Costs tokens and churn today — P1.
-- Keep `style-tests` ≤ ~100 lines: add the red flag + checklist item, don't expand philosophy.
-- Pipeline review gates (ralph HITL review) check for content-assertion tests before merge.
-
-## Next validation step
-When preparing for work: sweep the skills (style-tests, ralph, run-pipeline-stage, tdd,
-engineering, plan) for current wording that tolerates or invites content-assertion tests;
-then land the red flag in `style-tests` plus explicit warnings in the ralph skills, and
-verify a subsequent ralph run stops producing them.
-
-## Design so far / provenance
-Came from watching ralph pipeline runs generate tests that merely assert the contents of
-static files — e.g. config, md, and tf files — which is content-inventory, not behaviour
-proof. Stance locked in interview on 2026-08-30: blanket ban (no golden-file carve-out at
-initial landing); minimum skill scope = style-tests + ralph + run-pipeline-stage (+ tdd/
-engineering), with a broader skill sweep during prep; priority P1.
-
-## Notes
-Recorded 2026-08-30 (P1). This is a deliberate exception to the default "write tests —
-red-green-refactor" posture: not all assertions are tests of behaviour, and an assertion on
-immutable content is cost without signal. The `style-tests` skill is the enforcement point;
-ralph/run-pipeline-stage are where it keeps happening.

package/docs/ideas/bead-progress-notes-for-session-resumption.md

@@ -1,75 +0,0 @@
-# Idea: bead progress notes for session resumption
-
-## Status
-Recorded as bead `agnt-ctx-ul91` (2026-09-22) — awaiting `plan`. Merged with
-`state-in-beads-not-md.md` into one bead state model design (this file is Part 2: WHAT the
-progress trail contains).
-
-## Created
-2026-08-31
-
-## Problem
-A bead's notes field today records little until close, and agents hold all working state in
-the session window. If a session is terminated mid-task, the context dies with it — a fresh
-agent has to re-discover everything: what's done, what's blocked, what was tried, what was
-learned. That re-discovery burns tokens on work that was already completed, and the bead gives
-no way to pick up where the previous agent left off.
-
-## Who benefits
-The author (no lost momentum or re-discovery burn when sessions end), and every agent that
-picks up a bead mid-flight. The notes become a recovery contract: with a full progress trail on
-the bead, *any* agent — or a fresh session — can resume the thread without re-exploring.
-
-## Proposed outcome
-A prompted discipline: agents append to the bead's notes field **as they work**, capturing
-whatever is needed to recreate state if the session terminated:
-- **Key milestones** — stage transitions, chunks of completed work
-- **Decisions and why** — including rejected options
-- **Blocks** — what's stuck, and on what
-- **Discoveries and gotchas** — non-obvious findings, traps, environment quirks
-- **Problems solved and their solutions** — so the same discovery isn't repeated
-
-This is a checkpoint trail, not a transcript: brief, scan-friendly, high-signal. The goal is
-that a new agent can read the notes and resume with zero wasted discovery tokens.
-
-The mechanism is prompting — skills/agent files instruct agents to update the bead's notes at
-milestones (not a mechanical extension at first). It may later become a slight extension of the
-session-managing agent: the session manager prompts/checks that the bead trail is current
-before a session ends or flushes.
-
-## Validity check
-- Evidence we already have: `bd` supports multi-line markdown notes (`--notes`); ralph stages
-  already transition beads through the pipeline, so milestone points exist to hook into;
-  `state-in-beads-not-md` establishes bead fields as the home for this state.
-- Riskiest assumption: agents actually keep the trail updated under prompting alone — without a
-  mechanical check, discipline may lapse, and the trail rots. The extension shape (session agent
-  checks the trail is current pre-flush/close) is the likely fix, but that's a second step.
-- What would invalidate this idea: if notes grow into a transcript (cost + noise) instead of a
-  checkpoint trail; or if resumption needs more than notes (e.g. a scratch file of raw state)
-  anyway — then notes alone don't satisfy recovery.
-
-## Constraints
-- **Checkpoint trail, not transcript** — brief and scan-friendly; verbosity defeats the purpose.
-- Prompting discipline first; a mechanism (session-agent check/extension) is the later step.
-- Must not slow the ralph/run-pipeline-stage loops — the note write is a milestone action, not
-  a per-tool-call log.
-- Beads stay the single source of truth — no new scratch files (consistent with
-  `state-in-beads-not-md`).
-
-## Next validation step
-Pick one loop (run-pipeline-stage is the natural first) and add the milestone-note instruction
-to its skill: update `--notes` at stage start/end, decisions, blocks, discoveries. Verify a
-subsequent stage agent can resume purely from the notes (read `bd show` and continue) without
-re-reading the prior agent's log.
-
-## Notes
-- Priority: **P2** — backlog, not blocking. Annoying drift, nothing broken.
-- **Dependency**: this is the missing content contract for `self-flushing-session` — a flushed
-  session keeps only the bead ID, so the bead must carry enough trail to re-seed. Without these
-  notes, flush/resume is lossy.
-- Distinct from `state-in-beads-not-md` (WHERE state lives — rule/principle) and
-  `pi-task-memory` (cross-session memory store): this is the CONTENT of the bead's progress
-  trail and the prompting discipline that keeps it current. Composes with all three.
-- User's framing: possibly "a slight extension of the agent that manages its session" — the
-  session manager prompts/verifies the trail is current before session end, rather than a new
-  standalone mechanism.

package/docs/ideas/classify-beads-via-deterministic-script-with-agent-fallback.md

@@ -1,70 +0,0 @@
-# Idea: Classify beads via deterministic script with agent fallback
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-09-08
-
-## Problem
-`classify-bead` is one of the most frequently invoked skills, yet every invocation spawns a
-subagent — even when the classification is settled by fully deterministic lookups (an existing
-`implementation-type` label or the legacy `## Type` field) that need no agent at all. The
-remaining cases need first-principles rubric judgement, which the skill itself says is simple
-enough for "a small, cheap model". Running a full-size agent for all of it burns tokens on
-work a script plus a small model could do, and the cost multiplies across every caller:
-`create-task`, bead pickups, and ralph's pipeline stages.
-
-## Who benefits
-The author — classification is a top-called skill, so token spend per session drops
-meaningfully. Callers (`create-task`, pickups, ralph) get near-instant classification without a
-subagent round-trip, and keep the same semantics and output contract (AFK/HITL + the applied
-`bd tag` command).
-
-## Proposed outcome
-A deterministic classifier executable that callers invoke directly instead of spawning an
-agent. It resolves the deterministic cases itself (existing label → legacy `## Type` field →
-simple heuristics); only when a bead genuinely needs first-principles judgement does it
-escalate — ideally to a small/cheap model rather than a full agent. The current skill becomes
-the escalation/fallback layer (or a thin wrapper describing the script), preserving the
-existing precedence, the AFK bias, and the never-reclassify-a-labelled-bead rule.
-
-## Validity check
-- Evidence we already have: classification is one of the top-called skills with visibly high
-  token cost; the skill's own workflow already encodes deterministic-first precedence
-  (label → `## Type` → rubric), so many calls settle before any rubric reasoning; the skill
-  already asserts a small, cheap model suffices for the rubric step; the rubric is small and
-  stable, so it ports to a script cleanly.
-- Riskiest assumption: the deterministic share of real invocations is actually large — i.e.
-  most beads already carry a label or `## Type` field when classified. If most calls genuinely
-  need first-principles judgement, scripting the lookups saves little and the win shrinks to
-  model size alone. Secondary risk: a small model matches a full agent's rubric accuracy.
-- What would invalidate this idea: measurement shows most invocations land in the rubric
-  branch; or small-model accuracy is materially worse, causing AFK/HITL misroutes that surface
-  as failures at human review gates or in ralph's pipeline; or script+escalation complexity
-  across three harnesses (Copilot, pi, Claude Code) outweighs the token saving.
-
-## Constraints
-- Must be invocable from every harness where the skill ships (Copilot CLI, pi, Claude Code)
-  and from other skills' task-spawning paths.
-- Small-model routing depends on per-harness model configuration — ties into the
-  `model-selector` / `auto-model-selection` backlog.
-- Must preserve the existing rules: never overwrite a recorded label, prefer AFK, and keep the
-  reported output contract (classification + applied `bd tag` command).
-- The script must not load bead content into a calling agent's context when spawned as a task —
-  same isolation property the current skill has.
-
-## Next validation step
-Instrument or sample recent `classify-bead` invocations to measure the split between
-deterministic lookups (label / `## Type` present) and genuine rubric cases. This single number
-decides whether the win is "skip agent spawns entirely for most calls" (large) or "smaller
-model only" (modest) — cheap to gather, decisive for scope.
-
-## Notes
-- Overlaps with `model-selector.md` and `auto-model-selection.md`: which small model the
-  escalation uses is their problem to solve; this idea just wants the deterministic
-  classification off the agent path.
-- The skill already pushes callers to check `bd label list <id>` before spawning — a script
-  makes that check intrinsic instead of a caller-discipline reminder.
-- Classification output is a stable, tiny contract (two labels + one `bd tag`), which is what
-  makes a scripted rewrite low-risk versus other skills.

package/docs/ideas/ctx-alias-version-and-update-commands.md

@@ -1,65 +0,0 @@
-# Idea: ctx alias, version and update commands
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-09-02
-
-## Problem
-`agent-cortex` is a long name to type, and there is no way to see what is actually
-installed across the harnesses (pi / claude / copilot) or to bring an installed
-runtime up to date. The user currently inspects state manually or re-runs
-`agent-cortex install <harness>` after a release with no idea what changed.
-
-## Who benefits
-The author, in every coding session: a shorter command to reach the CLI, and two
-commands that answer "what's installed and is it current?" without remembering the
-install-manager internals. Anyone else using the plugin (published via npm) gets
-the same surface.
-
-## Proposed outcome
-- `ctx` as a shell alias for `agent-cortex`, installed by the CLI itself (appends to
-  the user's shell rc during setup/install).
-- `ctx version` reporting installed state per harness (pi / claude / copilot): which
-  artifacts are installed, their versions, and whether they match the CLI's release.
-- `ctx update` re-running the install for each harness whose installed state is stale.
-- Nothing here changes what installation does — the commands read and reuse the
-  install manager, not a parallel mechanism.
-
-## Validity check
-- Evidence we already have: the install epics (pi harness `agnt-ctx-dfq3` first, then
-  claude, then copilot) are already making the install manager authoritative per
-  harness; the F9 integration smoke (`agnt-ctx-t7xu`) will verify installed state
-  end-to-end and is the natural substrate for `version`.
-- Riskiest assumption: the install epics leave behind a stable, queryable notion of
-  "what is installed" (a fingerprint: version + presence per harness) that `version`
-  can read and `update` can compare against. If installed state stays implicit
-  (symlinks, unversioned copies), `version`/`update` have nothing reliable to report and
-  the idea deflates into a thin alias.
-- What would invalidate this idea: the harness epics ship without any record of
-  per-harness installed version, or `update` turns out to be indistinguishable from
-  a plain `install` (i.e. no stale/current distinction ever exists).
-
-## Constraints
-- Must reuse the install manager (one code path for install, version, update) — no
-  second mechanism that could drift.
-- Alias must be opt-in or clearly announced at install; overwriting an existing
-  `ctx` command in the user's shell is unacceptable (collision check first).
-- No version coupling invented per harness — installed version means the agent-cortex
-  release the harness artifact was materialised from.
-
-## Next validation step
-When the pi install epic (F3–F6) lands, check whether the installed artifacts carry a
-version fingerprint (file header comment or manifest). If yes, `ctx version` has its
-data source and the idea is implementation-ready; if not, the smoke-test epic
-(`agnt-ctx-543s`) must be asked to define one, which is also where `ctx update` gets
-its stale-detection.
-
-## Notes
-- Recorded from a session while the pi harness install manager epic was in flight;
-  priority felt like P3 — after the install epics merge, not folded into them.
-- `ctx` is a common shell name (context tools, context-mode). The alias install must
-  check for an existing command and surface the clash rather than silently override.
-- Idea belongs to the same surface as the install-manager epics: version/update are
-  the read/refresh side of the same CLI.

package/docs/ideas/ctx-feedback-command-for-capturing-ideas-from-any-machine.md

@@ -1,67 +0,0 @@
-# Idea: ctx feedback command for capturing ideas from any machine
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-09-02
-
-## Problem
-Ideas about agent-cortex (and the workflow around it) strike while working on the
-work laptop or other machines, where this repo — `docs/ideas/`, the beads tracker,
-the skills — is not the project in hand. Those ideas die or wait until back at the
-personal dev machine. There is no low-friction path from "idea in my head elsewhere"
-into this repo's backlog.
-
-## Who benefits
-The author: a capture path that works from any machine with the CLI installed and
-no requirement to be inside the repo. Same benefit as the `ctx alias/version/update`
-idea — a shared, short command surface on the work machine.
-
-## Proposed outcome
-- `ctx feedback` (or `agent-cortex feedback` until the alias exists) opens an
-  interactive curated capture: prompt for the idea, one-line summary, optional
-  context, and a check against existing issues/parked ideas to avoid duplicates.
-- The captured idea lands as a GitHub issue on the agent-cortex repo, tagged with a
-  stable label (e.g. `idea`) so it is distinguishable from bug reports/chores.
-- Curated, not one-shot: the flow forces the two minutes of thought the
-  `record-idea` skill requires, without requiring the skill's local scaffold.
-- Something downstream (a session, a manual sweep, or that skill itself) triages
-  `idea` issues into `docs/ideas/` records or beads for actual prioritisation.
-
-## Validity check
-- Evidence we already have: the author captures ideas regularly at the dev machine
-  (`docs/ideas/` has 20+ records, two added today), and explicitly wants a way to do
-  that from the work laptop. The `ctx` surface is already planned, so this rides an
-  existing idea rather than inventing a new command family.
-- Riskiest assumption: the work laptop has working GitHub auth (gh CLI or token) for
-  this repo. If it does not, the command needs its own credential story and the
-  "from any machine" promise quietly becomes "from any machine with a GitHub token".
-- What would invalidate this idea: a second capture surface (issues) that never gets
-  triaged into `docs/ideas/` — the repo would then have two idea stores drifting
-  apart, and feedback issues would accumulate unread. Also invalidated if the work
-  laptop auth friction turns out worse than the original "note it in a scratch file"
-  path.
-
-## Constraints
-- Must not duplicate the local capture flow — if the author is on the dev machine,
-  `record-idea` (a proper record with validity check) stays the canonical path; the
-  GitHub issue is the from-anywhere path.
-- Duplicate hygiene: the curated step must surface existing `idea` issues before
-  creating a new one.
-- No new long-lived auth secrets on the work laptop beyond what gh already uses.
-
-## Next validation step
-Check, on the work laptop, whether `gh auth status` (or an equivalent token) already
-covers the agent-cortex repo. If yes, the idea is implementation-ready — wire
-`ctx feedback` to `gh issue create` with the `idea` label. If not, that auth gap is
-the real problem to solve first.
-
-## Notes
-- Recorded back-to-back with `ctx-alias-version-and-update-commands.md`; sharing the
-  `ctx` surface and the P3 priority band.
-- Deliberately couples to GitHub issues (not the beads tracker): beads live on the
-  dev machine's dolt state, which is the wrong sink for a machine that cannot see
-  that state.
-- Needs a triage convention: either a periodic beat that converts `idea` issues into
-  `docs/ideas/` records, or the record-idea skill grows a "from issue" input mode.

package/docs/ideas/dedicated-review-tests-skill.md

@@ -1,71 +0,0 @@
-# Idea: Dedicated review-tests skill
-
-## Status
-Backlog idea (not implementation-ready) — priority P2 (moderate), timing: follows `agnt-ctx-h9gt`
-
-## Created
-2026-10-06
-
-## Problem
-Test review has no home of its own in the ralph pipeline. The review stage invokes
-`review-security` for a dedicated security pass, then falls back to `style-code` and
-`style-tests` for everything else. `style-tests` is a *writing* skill — it states conventions
-before tests are authored — so a reviewer reading it has to invert authoring guidance into
-review findings. The result is that test defects are caught by whatever the reviewer happens to
-notice rather than by an explicit checklist, and each new class of defect (the content-assertion
-ban being the first) has to be bolted onto the review template individually.
-
-## Who benefits
-- **The author**, who stops triaging test defects that a structured review should have caught.
-- **Ralph stage runners**, who get an explicit finding checklist instead of inferring one from a
-  writing-conventions skill.
-- **Future skill authors**, who get one place to add a test-review rule rather than editing the
-  review template, the review playbook, and `style-tests` in lockstep.
-
-## Proposed outcome
-A `review-tests` skill — a peer to `review-security` — that specifies what a reviewer checks in
-a test suite: assertion quality (does each assertion prove the behaviour under test),
-mock discipline (boundaries only, never internals), test-data construction (vital data inline,
-fresh per test, no shared mutable fixtures), determinism (no sleeps, no real clocks, every async
-interaction awaited), and coverage gaps against the task's stated behaviours.
-
-Broad scope, narrow use: the skill is generic test-review guidance, invoked as a stage step by
-the ralph review playbook (and available to a human reviewer or a `git-workflow` PR review).
-Once it exists, the content-assertion check added by `agnt-ctx-h9gt` becomes one row inside it
-rather than a standing instruction in the review template.
-
-## Validity check
-- Evidence we already have: the review stage already delegates to skills for every other
-  concern (`review-security` for security, `style-code` for code shape, `style-documentation`
-  for docs) — test review is the gap in an otherwise uniform pattern. The content-assertion
-  ban was bolted onto the review template precisely because no skill owned test review.
-- Riskiest assumption: that a *review* checklist is meaningfully different from `style-tests`
-  read critically. If a reviewer can derive the findings from the existing authoring skill with
-  no loss, this becomes a second statement of the same rules — exactly the two-homes problem
-  `agnt-ctx-h9gt` avoids by keeping `style-tests` canonical.
-- What would invalidate this idea: if `agnt-ctx-h9gt`'s review-gate change turns out to be
-  sufficient — if the review stage, with the content-assertion check in hand, stops missing
-  test defects — then the dedicated skill earns nothing and should be dropped.
-
-## Constraints
-- `style-tests` stays the canonical statement of test conventions; `review-tests` must cite it
-  and add only the reviewer's framing, or the two will drift.
-- Must not duplicate `review-security`'s ground or re-run the test suite (that is the verify
-  stage's job).
-- Invoked from the review playbook, so it must be cheap to load — no expansion of the review
-  stage's token budget beyond one skill read.
-- Follows `agnt-ctx-h9gt`; the content-assertion rule must not be restated in a second place
-  until this skill exists to hold it.
-
-## Next validation step
-After `agnt-ctx-h9gt` has run through the pipeline at least once, collect the test-related
-findings its review stage actually produces across a few PRs. If reviewers keep requesting
-changes on test grounds that the template does not name, that list is the skill's first
-checklist and the idea is confirmed; if the template covers them, drop the idea.
-
-## Notes
-Floated by the author on 2026-10-06 while scoping `agnt-ctx-h9gt`. Stance locked in the
-interview: broad scope (generic test review, not a pipeline-specific gate), used in the ralph
-pipeline, priority P2 with the trigger being `agnt-ctx-h9gt`'s real-world review findings.
-Deliberately kept as an idea rather than folded into `agnt-ctx-h9gt` so it passes the same
-validity check as every other backlog entry.

package/docs/ideas/deployment-beads-for-post-merge-pipelines.md

@@ -1,36 +0,0 @@
-# Idea: deployment beads for post-merge pipelines
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-08-31
-
-## Problem
-A task isn't done when the PR is merged — it's done when CI passes, it's merged, and in some cases *it's deployed*. Ralph's pipeline currently stops at `review` → open PR → human merge: there is no post-merge stage, so a merge that breaks CI or fails to deploy is discovered manually (or not at all). The definition of done is incomplete for projects with deployment/post-merge workflows.
-
-## Who benefits
-The author, running ralph-managed projects with release/deploy pipelines (e.g. agent-cortex's changesets release flow). No more manual pipeline watching after a merge; post-merge breakage is tracked and surfaced through the same bead system as everything else, so nothing silently rots in a CI dashboard.
-
-## Proposed outcome
-Deployment tracking becomes part of chore creation: when `create-task` (or `prd-to-tasks`) creates a task in a project that has a deployment/post-merge workflow, it also creates a **deployment bead** that gates "done" on the post-merge pipeline. A small/cheap model watches and reports on pipeline status. Failures are reported via a bead and **escalated to the author — never resolved by the agent**.
-
-## Validity check
-- Evidence we already have: ralph already opens review-gated PRs and pauses for human merges (the HITL gate pattern); `unified-ci-pipeline` documents real release-pipeline friction (release fires even on failed checks). Post-merge watching is the natural continuation of that arc.
-- Riskiest assumption: a small model can reliably watch and report pipeline status cheaply enough that the watch cost doesn't exceed the failure-detection benefit. Also: that "has a deploy workflow" is detectable at chore-creation time rather than needing per-project config.
-- What would invalidate this idea: post-merge failures are rare enough that manual checking is fine; the watcher can't distinguish real failures from flaky CI without burning tokens; or existing CI-native notifications (GitHub Actions alerts) already cover the gap.
-
-## Constraints
-- Must be cheap: small model, watch-and-report only. No internal LLM-driven resolution loops.
-- Failures escalate to the author (matches the HITL pattern) — the watcher reports, a human decides.
-- Must compose with the ralph pipeline as another stage/chore type, not fork it.
-- Deployment bead is created at chore-creation time where a post-merge workflow exists — part of `create-task`'s pipeline configuration (`skills/planning/create-task/pipeline.json`), generalised across ralph-managed projects.
-
-## Next validation step
-Survey which ralph-managed projects actually have post-merge/deploy workflows, and map where a deployment bead would slot into `create-task`'s chore breakdown. Check whether the changesets release flow (agent-cortex) is the natural first consumer.
-
-## Notes
-- Priority: **P2** — backlog, not blocking. Generalise: the deployment bead is part of chore creation, not a per-project add-on.
-- Distinct from `unified-ci-pipeline` (that idea is about CI speed + release gating, this is about post-merge/done definition).
-- Consistent with `state-in-beads-not-md`: the bead is the source of truth; pipeline status lands on a bead, not a scratch file.
-- "Escalated, not resolved" is the key design line — keeps the watcher cheap and keeps human judgment in the loop.

package/docs/ideas/design-and-delivery-as-separate-bead-trees/design-and-delivery-as-separate-bead-trees.md

@@ -1,99 +0,0 @@
-# Idea: Design and delivery as separate bead trees
-
-## Status
-Recorded as bead `agnt-ctx-rig0` (2026-09-22) — awaiting `plan`. Absorbs
-`test-planning-stage-bead-in-feature-planning.md`.
-
-## Created
-2026-09-03
-
-## Problem
-Today one bead tree mixes intent with execution: a feature is decomposed
-straight into delivery chores, so the *design* — what the feature is, its
-sub-components, and how each part is *proven to work* — never exists as a
-first-class structure. Verification degrades to per-chore verify passes that
-drift with implementation, and nothing asks "what is the provable outcome of
-this feature?" up front.
-
-## Who benefits
-- Planning agents (plan/prd-to-tasks) — design and verification get explicit
-  structure instead of being implicit in delivery chores.
-- Ralph / run-pipeline-stage — delivery work runs against a design tree it
-  doesn't need to understand; closure is mechanical.
-- The human reviewer — provable outcomes per feature give the PR gate a
-  checkable "how do we know it's worked?" criterion.
-- The codebase — delivery slices can be minimal (no building a whole domain
-  service to ship a slice), decoupled from design completeness.
-
-## Proposed outcome
-Two first-class, linked bead trees in the tracker:
-
-1. **Design tree** — an epic links to the features below it; a feature may
-   nest further features/sub-components. Below each feature sit its
-   **verification beads**: a demonstrable set that proves the design —
-   "explicitly, what is the provable outcome of that feature? how do we know
-   it's worked?" Verification is *part of the design stage*, not an
-   afterthought of delivery.
-2. **Delivery tree** — a separate structure of slices actually taken to
-   delivery. Delivery slices deliberately differ from design slices (you may
-   not need to build an entire domain service to deliver a slice of
-   functionality). Delivery links to design but is not the same as design:
-   each design and verification element is completed *by* a delivery bead,
-   but the mapping is not 1-to-1 (one delivery slice can complete several
-   design elements; one design element may need several delivery beads).
-
-Mechanics: one tracker, beads typed `design` / `verification` / `delivery`,
-plus a link class meaning "completes / is completed by" alongside today's
-"depends on". Ralph's contract shrinks: it does not need to understand the
-design tree any more than it already does — it can close a design bead when
-all delivery beads linked to it are completed.
-
-## Validity check
-- Evidence we already have: the pipeline restructures around stages
-  (create-task chores, ralph dispatch) tellingly reworked across #123/#124 —
-  verification keeps needing re-planning per delivery; the companion idea
-  "Test-planning stage bead in feature planning" independently converged on
-  the same "provable outcome / how do we know it's done" question, which
-  suggests a real structural gap, not a one-off itch.
-- Riskiest assumption: the double tree pays for itself — i.e. delivery slices
-  are *often enough* genuinely different from design slices, so the second
-  tree earns its bookkeeping; and bd (or a thin shim) can express typed beads
-  + link classes without brittle hacks. If real workstreams map 1-to-1 most
-  of the time, the extra tree is ceremony.
-- What would invalidate this idea: a pilot where the delivery tree mirrors the
-  design tree slice-for-slice; or where ralph's close-when-delivery-done rule
-  cannot be stated mechanically because delivery beads keep spanning design
-  elements unpredictably (unbounded fan-in/fan-out breaks the closure rule).
-
-## Constraints
-- One tracker, no new store: typed beads + a "completes" link class must fit
-  the existing beads model and tooling (bd link CLI today only expresses
-  "depends on").
-- Ralph's design-tree knowledge stays at the closure rule — no design
-  semantics leak into the execution pipeline.
-- Restructures planning stages: a design stage (verification inside it) and a
-  delivery stage, replacing the current single decomposition.
-- Backwards-compatible during rollout: existing single-tree epics keep
-  working while new work adopts the split.
-
-## Next validation step
-Pilot on the next new epic, without touching pipeline code: hand-draft the
-design tree (features → verification beads with stated provable outcomes) and
-the delivery tree as typed beads/docs, then check (a) how often delivery
-slices diverge from design slices, and (b) whether every design/verification
-element is closed by a mechanical all-delivery-beads-done rule. Also
-inventory bd's link/type/tag capabilities (bd link --help, tag support) to
-size the tracker work before proposing the pipeline change.
-
-## Notes
-- User framing: "planning and design should create a tree of beads; the epic
-  should be linked to the features below it; under each of those may be more
-  features or sub components; then below that are the verification beads."
-- "Delivery then is a separate tree — the slices of a design which are taken
-  to deliver will not, and should not be the same as the design slices."
-- Supersedes/absorbs the test-planning-stage-bead idea's motivation: the
-  verification beads here generalise that idea's test-plan bead (provable
-  outcome per feature). If this lands, fold the test-planning bead into the
-  design stage rather than shipping it standalone.
-- Priority: medium — next planning-skill iteration. Pipeline-wide restructure;
-  do not start until the current pipeline stabilises post-#127.

package/docs/ideas/enable-signed-commit-enforcement-changesets-bot-commits-must-be-signed.md

@@ -1,42 +0,0 @@
-# Idea: Enable signed-commit enforcement (changesets bot commits must be signed)
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-09-02
-
-## Problem
-GitHub's signed-commits protection on `main` (the "Require commit signing" rule) is currently disabled in this repo. Enabling it hardens main against impersonated/forged commits — but the automated release flow depends on the changesets bot's unsigned "chore: version packages" commits (which bump `package.json`/`plugin.json`/`CHANGELOG.md`). Flipping the rule on as-is would break releases.
-
-## Who benefits
-The author. Main-branch history becomes verifiably authentic — every commit attributable to a known key — protecting the npm-published package's supply chain, and releases keep flowing because the automation satisfies the same rule.
-
-## Proposed outcome
-`main` requires signed commits AND the automated changesets release commits satisfy that requirement — i.e. enabling "Require commit signing" no longer breaks the version-packages / release pipeline. Direction: the automation signs its own commits inside CI (no manual release steps).
-
-## Validity check
-- Evidence we already have: the rule is currently disabled (user statement). The release pipeline's version commits are created by the changesets action as `github-actions[bot]`, which does not sign by default — enabling the rule today fails those commits. Restructuring "how changesets works in CI" is therefore required, and this overlaps with the adjacent `unified-ci-pipeline` idea.
-- Riskiest assumption: that a clean path exists for GitHub Actions to produce signed commit(s) in this repo's flow without breaking or significantly complicating the automated loop (CI-hosted keys and ruleset exceptions both have setup costs and failure modes).
-- What would invalidate this idea: if the only workable fix forces human-run releases (moving versioning out of automation), the cost/benefit flips — the idea dies or reverts to the status quo of signing human commits only.
-
-## Constraints
-- Scope: this repo only.
-- Must not break the changesets-driven versioning loop (`package.json`/`plugin.json`/`CHANGELOG.md` stay in lockstep automatically).
-- CI changes go through the normal PR + review flow.
-- The release job is also the target of the pending npm OIDC publish work (agnt-ctx-0zy8) — both touch the same job, so sequencing matters when this idea graduates.
-
-## Next validation step
-Determine how the changesets commit gets signed in CI on this repo — cheapest prototype: scratch repo (or the version branch) exercising the signing path end-to-end without touching `main`'s rule, then evaluate the rule change on `main`.
-
-## Notes
-Recorded 2026-09-02. Backlog capture only — no active work planned; revisit after the install-manager epic (pi/claude/copilot) settles. Adjacent to `docs/ideas/unified-ci-pipeline.md` (CI/release restructure).
-
-Updated 2026-10-28: `docs/commit-signing.md` records the investigation and the decided policy.
-The applied-rule read shows no `required_signatures` rule on `main` at repository or
-organization level (org ruleset *definitions* stay unreadable with a repository-scoped token),
-and Version Packages PRs land by squash merge, whose landing commit GitHub signs — so releases
-stay automated with no key in CI, and the CI signing key this idea points at is rejected as the
-default. That rejection does not settle the idea: GitHub checks head-branch commits through its
-test merge, so enabling enforcement would still require the signed CI commit, exactly as
-`Next validation step` describes.