chore(intake): file pearl pattern-catalog and codex runtime spec as TODOs

Moved three inbox notes into docs/design/ so the task body links survive: pearl's two pattern-catalog handoffs and codex's v0 generic-agent-runtime spec. Added two corresponding TODOs under Rulesets Open Work, both [#C].

1 files changed, 50 insertions, 0 deletions

diff --git a/docs/design/2026-05-27-pattern-catalog-pearl-notes.org b/docs/design/2026-05-27-pattern-catalog-pearl-notes.org
new file mode 100644
index 0000000..f6d4a8c
--- /dev/null
+++ b/docs/design/2026-05-27-pattern-catalog-pearl-notes.org
@@ -0,0 +1,50 @@
+#+TITLE: UI pattern standardization across projects
+#+DATE: [2026-05-27 Wed]
+#+SOURCE: pearl issue-sources Phase-5 verify walk-through
+
+* Context
+
+Surfaced during pearl issue-sources verify on 2026-05-27. A pattern landed in pearl that Craig liked and asked how to standardize across projects so the next project benefits. This is the cross-project meta-question he wanted filed somewhere his agenda would catch it.
+
+* Two patterns worth naming
+
+** "All info you need, in one completing-read"
+
+What pearl's =pearl-pick-source= does: every fetch source (Linear favorites + saved queries) goes into one =completing-read= with a typed prefix and the name. The candidate string reads as =[view] Active bugs= / =[project] Platform= / =[saved] My open=, sorted by Linear's =sortOrder= then alphabetically. The user sees kind, identity, and natural rank in one scan, picks once, and is done. No second prompt to disambiguate, no mode switch, no menu chain.
+
+Cost was a small helper that maps source-plist to display string. The win was the picker collapsing to one decision rather than three.
+
+The pattern generalizes anywhere a project has N candidates and the *kind* of candidate matters as much as the name. Pearl reaches for it again in the planned ad-hoc builder rewrite and in =pearl-refine-current-source=.
+
+** The "magit transient" pattern (Craig's specific reference)
+
+A bottom-popup screen with toggleable button rows showing current state, with key bindings printed inline, and a single keybinding to summon it. The reference is magit's =transient.el= library, which is actual library code rather than just a UI convention. Craig described the music-player UX equivalent. The win is "all the levers in one place, with affordances visible, and one chord to get there from anywhere."
+
+Pearl uses transient lightly today (=pearl-menu= behind =C-; L m=) but doesn't yet exploit toggleable state-indicator buttons. The ad-hoc builder rewrite would be a natural place.
+
+* The meta-question
+
+Craig's actual question isn't about either pattern. It's: *how do good patterns travel from project A to project B?*
+
+Three angles worth thinking through:
+
+1. *A pattern catalog.* A written record of patterns that worked, with the context that made each one work. Lives somewhere durable. Without it, every project re-derives the same patterns from scratch and the discoveries don't compound.
+
+2. *A surfacing mechanism.* Even with a catalog, how does the right pattern show up at the right moment? "You're about to write a multi-prompt completing-read chain. Consider the one-prompt + typed-prefix shape instead." A passive catalog only helps if Craig or the agent thinks to consult it. Active surfacing is the harder problem.
+
+3. *Where patterns live.* Three plausible homes: this rulesets repo (next to existing rules + skills), a Linear-style document workspace, or per-project notes that cross-link. Each shapes who reads them and when. Rulesets has the agent-visibility advantage. Every session loads it.
+
+* My read on spec scope
+
+Brainstorm-level, not implementation-ready. The questions above aren't one-line decisions:
+
+- Does the catalog get a structured format (one pattern per file, frontmatter, slug) or a free-form doc?
+- Is the surfacing mechanism agent-driven (the model spots the pattern opportunity) or human-driven (Craig grep-searches when he feels stuck)?
+- Does the catalog include anti-patterns (things that didn't work, with the reason) or only what worked?
+- How do patterns get into the catalog? Every time one lands, or batch reviews on cadence?
+
+A one-page spec along the lines of pearl's =docs/issue-sources-spec.org= (problem + design + open questions + acceptance) would land the shape before any implementation. Recommend doing that before writing any catalog file or any agent prompt change.
+
+* What I might be pulled in for
+
+Craig flagged he'd work on this with the rulesets project and that spec-reviews might come back this way. Standing by for those.