hotmilk 0.1.13 → 0.1.15

package/skills/pioneer/references/observational-memory-routing.md

@@ -0,0 +1,90 @@
+# Observational memory (compaction continuity)
+
+**Load when:** the session is **long**, compactions are frequent, and you need **why** decisions were made to survive summarization — not when you need a user-visible plan file or spec artifact.
+
+**Do NOT load when:** planning-with-files, Plannotator, or OpenSpec SDD is the chosen plan authority — OM is **background session memory**, not plan truth.
+
+**Canonical matrix:** [README § Workflow routing](../../../README.md#workflow-routing) (user-facing); this file is agent routing detail.
+
+## When to use
+
+| Signal                                                                  | Route here                                                        |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Multi-day refactor, deep debug, architecture exploration, migration arc | `extensions.observational-memory: true` after `/mode` + `/reload` |
+| User asks why context was lost after compaction / “session feels reset” | Enable OM; start a **clean session** after V3 upgrade             |
+| Large tool output already handled by context-mode                       | Keep **context-mode on**; add OM only for **decision rationale**  |
+| User wants explicit on-disk plan + `/clear` recovery                    | **planning-with-files** — OM does not replace `task_plan.md`      |
+| Human plan approval before writes                                       | **Plannotator** — OM is not an approval gate                      |
+| Cross-cutting feature with proposal/spec/design                         | **OpenSpec SDD** — artifacts are contract; OM is supplementary    |
+
+**Tie-breaker vs other memory layers:** corpus search / huge outputs → **context-mode** (`ctx_*`); readable plan files → **planning-with-files**; compaction-injected session rationale → **observational-memory**.
+
+## 向く / 向かない (suited vs not suited)
+
+Inspired by [Armin Ronacher — _The Coming Loop_](https://lucumr.pocoo.org/2026/6/23/the-coming-loop/) (2026-06-23): loops and compactions help when progress is measurable; they hurt when judgment and durable contracts are outsourced.
+
+| 向く (use observational-memory)                             | Why                                               | 向かない (use another path)                 | Why                                                   |
+| ----------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------- |
+| Long session with repeated compactions                      | Observations + reflections inject before summary  | One-shot small fix                          | Overhead; Chat Plan + `verify:` is enough             |
+| Preserve **why** a design choice was made across days       | Durable reflections distill rationale             | User-visible plan checklist                 | Use **Plannotator** or **planning-with-files**        |
+| Deep debugging with rejected hypotheses to avoid reopening  | Observation timeline grounds the agent            | Feature spec / acceptance criteria          | Use **OpenSpec SDD**                                  |
+| Pair with **pi-goal** for multi-turn arcs                   | OM captures tactical “why”; goal holds north-star | Same task also needs SDD proposal/spec      | SDD artifacts are authority; OM is supplementary only |
+| Faster compaction (memory work incremental)                 | Upstream design goal for V3                       | `/clear` full session recovery              | Use **planning-with-files** on-disk files             |
+| Engineer wants `recall` to trace observation/reflection IDs | Auditable session memory                          | Replace **context-mode** FTS5 for logs/docs | Different layer — use **ctx_search** / **ctx_index**  |
+
+**Harness takeaway:** OM is **implicit session memory**. Return human judgment via plan paths (Plannotator / SDD) and PR review — do not treat reflections as spec or hidden plan authority.
+
+## Prerequisites
+
+| Requirement | Check                                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------------- |
+| Toggle      | `extensions.observational-memory: true` — if off, say compaction memory unavailable; do not fake `recall`     |
+| Extension   | `pi-observational-memory` loaded via `/reload` after `/mode`                                                  |
+| Pi version  | Targets Pi **0.74+** peers; hotmilk ships **0.80**                                                            |
+| V3 upgrade  | V3 does **not** read V2 settings or memory — new clean session after upgrade                                  |
+| Model cost  | Observer/reflector agents may call a separate model — configure in extension settings; default off in hotmilk |
+
+## Coexistence matrix
+
+| Layer                      | Tool / path                            | Relationship to OM                                            |
+| -------------------------- | -------------------------------------- | ------------------------------------------------------------- |
+| Large output / corpus      | **context-mode** (`ctx_*`)             | Complementary — OM ≠ indexed corpus                           |
+| Shell output compaction    | **rtk-optimizer** + context-mode       | Complementary — orthogonal to session observations            |
+| Codebase map               | **graphify**                           | Run Phase 0 recon; OM does not replace `graphify-out/`        |
+| Session objective          | **pi-goal**                            | Goal = north-star; OM = tactical rationale                    |
+| Plan authority             | PWF / Plannotator / SDD                | **One plan truth** — OM must not contradict chosen plan files |
+| Persistent external memory | Engram / other packages (if installed) | Separate product — hotmilk does not bundle Engram by default  |
+
+**Recommended stack (long coding session):** `context-mode: true` + `graphify` Phase 0 + optional `observational-memory: true` + one plan path when scope grows past chat.
+
+## Workflow
+
+```text
+1. Confirm session will span compactions (not a one-file typo)
+2. /mode → observational-memory ON → /reload
+3. Work normally — observer/reflector run in background
+4. On compaction, injected memory preserves decisions and rejected paths
+5. Use recall tool when you need observation/reflection provenance
+6. When scope needs spec or approval → pick plan path; do not let OM replace it
+```
+
+## Anti-patterns
+
+| Do not                                              | Why                                     | Do instead                                        |
+| --------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |
+| Treat reflections as OpenSpec / SDD substitute      | Hidden memory ≠ reviewable contract     | SDD artifacts + optional OM                       |
+| OM + planning-with-files on same markdown plan file | Two writers on one “truth”              | PWF files vs OM session store — separate concerns |
+| Default ON for all users                            | Extra model cost; V3 migration friction | hotmilk default **off**; enable for long sessions |
+| Skip clean session after V2 → V3                    | Format mismatch; stale memory           | New session per upstream README                   |
+| Disable context-mode and expect OM to index logs    | Wrong layer                             | `ctx_index` / `ctx_search` for corpus             |
+
+## Fallback when toggle off
+
+Say observational memory is unavailable. For compaction loss:
+
+- Enable toggle and `/reload`, **or**
+- Use **planning-with-files** for durable files, **or**
+- Use **context-mode** to index key docs/logs, **or**
+- Narrow scope to Chat Plan with explicit `verify:` checkpoints.
+
+Upstream: [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) · npm `pi-observational-memory@3.x`

package/skills/pioneer/references/openspec-routing.md

@@ -0,0 +1,50 @@
+# OpenSpec / SDD routing
+
+**Load when:** Plan routing chose **OpenSpec SDD** (Phase 3b) or Phase 4 OpenSpec execute.
+
+**Do NOT load when:** Chat Plan path is chosen — use [`chat-plan.md`](chat-plan.md) instead.
+
+**Primary skill — MANDATORY:** load **`/skill:gentle-ai`** for phase chain, `/sdd-status`, `/sdd-continue`, preflight, delegation, and verify/sync/archive rules. This file is a pioneer gate only — not a second copy of gentle-ai.
+
+## Pre-SDD checklist (pioneer gate)
+
+Before proposal/spec work, confirm via **`/skill:gentle-ai`**:
+
+| Gate              | Check                                                                                                    |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| Session preflight | SDD preflight choices captured this session (execution mode, artifact store, PR strategy, review budget) |
+| Init guard        | `openspec/config.yaml` exists or `/sdd-init` runs first                                                  |
+| Toggle            | `extensions.gentle-ai: true` — if off, **stop**; Chat Plan only                                          |
+
+## Gate
+
+If `openspec/config.yaml` is missing, run **`/sdd-init`** (or enable `sdd-init` in `/mode`) before proposal/spec work.
+
+## Artifacts
+
+Artifacts live under `openspec/changes/<change>/`. See **`/skill:gentle-ai`** for phase chain and file roles.
+
+## Grill → OpenSpec
+
+Grill output (`## Proposed CONTEXT.md`, `## Proposed ADR`) feeds proposal/design — sync into OpenSpec artifacts, not only chat.
+
+## Pioneer NEVER
+
+- Do not skip **verify** or **sync** because chat plan "looks done".
+- Do not mix chat `Plan:` and OpenSpec artifacts for the same change unless the user explicitly wants a sketch first.
+- Do not downgrade an **active** OpenSpec change to Chat Plan when gentle-ai becomes unavailable mid-flow.
+
+## Mid-flow recovery (gentle-ai lost during SDD)
+
+Triggers: `/mode` disables `extensions.gentle-ai`, gentle-ai skill missing after SDD artifacts exist, or `/sdd-continue` fails because SDD runtime is gone.
+
+| Step | Action                                                                                                                                                                                                                           |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | **Stop** apply/verify/sync/archive — do not emit chat `Plan:` for the same change                                                                                                                                                |
+| 2    | Tell user: _"OpenSpec change `<change>` is in progress. SDD requires gentle-ai. Enable `extensions.gentle-ai`, `/reload`, then `/sdd-status` and `/sdd-continue` — do not switch to Chat Plan or you will lose artifact gates."_ |
+| 3    | Preserve artifacts under `openspec/changes/<change>/`; note last completed phase in chat                                                                                                                                         |
+| 4    | Resume only via **`/skill:gentle-ai`** (`/sdd-status` → `/sdd-continue`) after gentle-ai is back                                                                                                                                 |
+
+**Forbidden:** abandoning SDD artifacts, re-planning the same scope in chat, or implementing without verify/sync because gentle-ai dropped.
+
+After large code changes, mention `graphify update .` if the project uses graphify.

package/skills/pioneer/references/plannotator-routing.md

@@ -0,0 +1,83 @@
+# Plannotator (Phase 3b)
+
+**Load when:** Plan routing chose **Plannotator** (human approval gate before execution).
+
+**Do NOT load when:** Chat Plan, OpenSpec SDD, or planning-with-files is the chosen plan authority — use the matching reference instead.
+
+**Canonical matrix:** [README § Workflow routing](../../../README.md#workflow-routing).
+
+## When to use
+
+| Signal                                                                 | Route here                  |
+| ---------------------------------------------------------------------- | --------------------------- |
+| Medium scope, bounded checklist, human must approve plan before writes | Plannotator                 |
+| User asks for plan review in browser, `/plannotator`, or `--plan`      | Plannotator                 |
+| Gray zone where approval matters more than spec artifacts              | Plannotator over Chat Plan  |
+| Cross-cutting, >400 changed lines, proposal/spec needed                | OpenSpec instead            |
+| Heavy research, `/clear` recovery, findings/progress split             | planning-with-files instead |
+
+**Tie-breaker vs OpenSpec:** approval is the primary goal → Plannotator; spec/design/tasks contract is the primary goal → OpenSpec.
+
+## Prerequisites
+
+| Requirement         | Check                                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------- |
+| Toggle              | `extensions.plannotator: true` — if off, fall back to Chat Plan or OpenSpec per pioneer routing |
+| Extension           | `@plannotator/pi-extension` loaded via `/reload` after `/mode`                                  |
+| Graph (recommended) | Phase 0 graph recon before planning — read `graphify-out/GRAPH_REPORT.md` when present          |
+
+## Workflow
+
+```text
+1. Phase 0 graph recon (when non-trivial)
+2. Optional /goal alignment
+3. /plannotator plans/<name>.md  OR  --plan plans/<name>.md
+4. Agent writes plan + checklist in planning phase (plan file only)
+5. plannotator_submit_plan → browser Approve / Deny / Approve with notes
+6. executing phase → gentle-ai Work Routing Ladder; mark [DONE:n] per item
+7. Optional plannotator-review on diff before ship
+```
+
+## Artifact rules
+
+| Artifact                                     | Owner                                                                      |
+| -------------------------------------------- | -------------------------------------------------------------------------- |
+| `plans/*.md`                                 | Plannotator (single plan authority)                                        |
+| `task_plan.md`, `findings.md`, `progress.md` | planning-with-files — **do not share** with Plannotator plan path          |
+| `openspec/changes/<change>/`                 | OpenSpec — Plannotator may gate **after tasks**, not replace SDD artifacts |
+
+Link across layers in prose only (`See findings.md §3`) — do not make two files the same plan authority.
+
+## Execute (Phase 4)
+
+After browser approval, load **`/skill:gentle-ai`** and follow its Work Routing Ladder.
+
+- `extensions.subagents: false` → inline execute; say delegation skipped
+- `extensions.gentle-ai: false` → inline execute after approval; no SDD mid-flow
+
+**Verify:** per-step checks in plan + **`AGENTS.md`** (`bun test`, `bun run check`).
+
+## SDD combination (optional)
+
+When OpenSpec tasks are complete and human approval is still required:
+
+```text
+sdd-tasks done → emit plan-review (tasks summary) → Plannotator approve → sdd-apply
+```
+
+SDD artifacts remain authoritative; Plannotator is the execution gate only.
+
+## Fallback when Plannotator is off
+
+- Say **"Plannotator skipped: extension off"**
+- Re-route: approval needed → Chat Plan with explicit user OK in chat; spec needed → OpenSpec
+- Do not invoke `/plannotator`, `plannotator_submit_plan`, or `--plan` mode
+
+## Anti-patterns
+
+| Do not                                                    | Do instead                                         |
+| --------------------------------------------------------- | -------------------------------------------------- |
+| Start Plannotator mid-active SDD as second plan authority | Finish or pause SDD; use plan-review on tasks only |
+| Share `task_plan.md` with Plannotator                     | Separate paths: `.planning/` vs `plans/`           |
+| Chat Plan then switch to Plannotator same task            | Pick one plan path at Phase 3                      |
+| Skip browser approval and write source in planning phase  | Stay in planning until Approve                     |

package/skills/pioneer/references/prompt-eval-gate.md

@@ -0,0 +1,38 @@
+# Prompt-eval gate
+
+**Load when:** A skill or prompt file was edited and the asset will ship (commit, PR, or user asks to harden).
+
+**Do NOT load when:** Read-only tasks; no edits to prompts or skills.
+
+## Enter (mandatory)
+
+Run when **any** of:
+
+- This session edited a file under `skills/` or `prompts/`
+- User invokes `/prompt-eval <path>`
+- Scenario router: "Skill or prompt edit just completed"
+
+## Skip
+
+Say **"prompt-eval skipped: …"** when:
+
+- No prompt/skill edits this session
+- User explicitly ships without hardening
+
+## Run (mandatory)
+
+Invoke **`/prompt-eval <path>`** where `<path>` is the edited skill or prompt file.
+
+Pi resolves `/prompt-eval` to the shipped prompt. Do not read `prompts/*.md` by file path.
+
+If `/prompt-eval` is unavailable, report `prompt-eval skipped: prompt not available`.
+
+## Phase placement
+
+- **Edits-only task:** run after Phase 3 plan (if any) or immediately before ship
+- **Mixed task:** run after Phase 4 execute when skill/prompt files changed
+
+## Pioneer NEVER
+
+- Self re-read the target as "evaluation" — fresh executor required
+- Ship hardened assets without static coherence check (prompt-eval Step 0)

package/skills/pioneer/references/shazam-routing.md

@@ -0,0 +1,58 @@
+# Shazam routing (execute-time structure)
+
+**Load when:** `extensions.shazam: true`, editing shared modules, or user asks for impact analysis / post-edit LSP verify.  
+**Do not load when:** Phase 0 graph recon only, plan routing, or `extensions.shazam: false`.
+
+Canonical user doc: [README § Workflow routing](../../../README.md#workflow-routing).
+
+## Role (not graph-wiki)
+
+| Layer             | Tool                       | When                                                           |
+| ----------------- | -------------------------- | -------------------------------------------------------------- |
+| **Recon map**     | graphify (`graphify-out/`) | Phase 0 — persistent architecture, cross-module queries        |
+| **Execute guard** | pi-shazam (`shazam_*`)     | Phase 4 — impact before edit, verify after edit, symbol lookup |
+| **Corpus / logs** | context-mode (`ctx_*`)     | Large outputs — not code structure                             |
+| **TDD loop**      | pi-red-green (`/tdd`)      | Test-first workflow — pairs with `shazam_verify` after edits   |
+
+**Do not treat shazam as graphify replacement.** graphify answers "how does the system relate?"; shazam answers "what breaks if I change this symbol?" and "did LSP pass after the edit?".
+
+## Coexistence matrix
+
+| Pair                            | Relationship                                                                              |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| graphify + shazam               | **Recommended** — graphify recon first; shazam during execute                             |
+| shazam + red-green              | **Complementary** — TDD drives tests; `shazam_verify` catches type/lint/format            |
+| shazam + context-mode           | **Non-conflicting** — different tool channels                                             |
+| shazam + pi-lens (if installed) | **Overlap** on LSP/lint — pick one primary verify path per task                           |
+| shazam MCP + Pi extension       | **Pick one** — bundled path is Pi extension; do not duplicate MCP server for same session |
+
+## Pioneer phase map
+
+```text
+Phase 0  → graphify (GRAPH_REPORT.md / graph query)
+Phase 4  → before shared-module edit: shazam_impact
+           after edit: shazam_verify (+ bun test per AGENTS.md)
+           optional: shazam_changes when reviewing git diff risk
+```
+
+Skip shazam when the task is docs-only, config-only with no LSP, or a one-line typo with no blast radius.
+
+## Prerequisites
+
+- **LSP servers** for the language (e.g. `typescript-language-server`, `pyright`, `gopls`) — verify quality depends on them.
+- **Windows:** upstream notes tree-sitter native limits — document in README; default off on Windows if unsupported.
+- **Session start hook:** shazam may inject overview into system prompt — large repos can add latency; keep toggle off when not needed.
+
+## Anti-patterns
+
+| Do not                                                           | Why                                            | Do instead                           |
+| ---------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------ |
+| `shazam_overview` instead of graphify for architecture questions | No persistent graph; misses cross-session wiki | Phase 0 graphify                     |
+| Skip `shazam_impact` before wide refactor                        | Hidden blast radius                            | impact → edit → verify               |
+| Trust `shazam_verify` PASS without tests                         | LSP green ≠ behavior correct                   | tests + verify                       |
+| graphify query + shazam lookup for same question in one turn     | Token waste                                    | Pick the layer that fits             |
+| Enable shazam MCP and bundled extension together                 | Duplicate tools                                | Pi extension via hotmilk toggle only |
+
+## Fallback when toggle off
+
+Say shazam unavailable. Use graphify for structure, `read`/`grep` for local symbols, and project test/lint commands in `verify:`.

package/skills/recommend-research/SKILL.md

@@ -1,13 +1,101 @@
 ---
 name: recommend-research
-description: "Single entry for technology recommendations: judge scope, shortlist, then verify with docs and source. [Triggers: recommend research, technology choice, library comparison, stack evaluation, OSS research, repo]"
+description: Single entry for technology recommendations — judge scope, shortlist 3–5 candidates, verify with docs and source. Use when the user asks to compare libraries, evaluate stack choices, research OSS alternatives, pick dependencies, or needs evidence-backed technology advice. Triggers include recommend research, technology choice, library comparison, stack evaluation, OSS research, repo research, deepwiki, librarian, opensrc, brave-search.
 ---
 
 # Recommend research
 
-1. **Scope** — Multiple moving parts (stack, practice, integration across layers) → holistic evaluation. One category or one library family → narrow track.
-2. **Shortlist** — Use curated surveys and comparisons when you need options fast; then cut to a few candidates.
-3. **Verify** — Official docs for contracts and usage; repository / local checkout when internals, edge cases, or performance matter.
-4. **Mechanics** — Web search and doc pages for reading; `ghq` or `git clone` when the tree must be local.
+Single orchestration skill for **evidence-backed technology recommendations**.
 
-If the repo ships extra skills under `./skills/`, load those `SKILL.md` files only when this flow is not enough.
+## Scenario router (read first)
+
+| User signal                                | Route                                                                       |
+| ------------------------------------------ | --------------------------------------------------------------------------- |
+| Stack / practice / cross-layer integration | **Holistic** — [`scope-gate.md`](references/scope-gate.md)                  |
+| One library family or one category         | **Narrow** — [`scope-gate.md`](references/scope-gate.md)                    |
+| User already named 1–2 candidates          | Skip shortlist survey; go to verify                                         |
+| User wants internals / why / source proof  | Verify path → librarian or opensrc (see ladder)                             |
+| Public GitHub repo docs / architecture     | deepwiki when available                                                     |
+| First use / "show example"                 | [`example-narrow.md`](references/example-narrow.md) — read-only walkthrough |
+
+**References:** Do **not** read `references/` unless a phase below applies. Each reference states its load trigger at the top.
+
+## Phase map
+
+```text
+1. Scope           → scope-gate.md          (MANDATORY - READ ENTIRE FILE)
+2. Shortlist       → shortlist-gate.md      (MANDATORY - READ ENTIRE FILE)
+3. Verify          → verify-gate.md         (MANDATORY - READ ENTIRE FILE)
+4. Recommend       → chat verdict (see below)
+```
+
+Skip phases that do not apply. Say which phase was skipped and why.
+
+## Evidence tools (by job)
+
+| Job                          | Tools                                            | Phase                                     |
+| ---------------------------- | ------------------------------------------------ | ----------------------------------------- |
+| **Discovery search**         | brave-search, web-search                         | Shortlist seed, verify pass 1–2           |
+| **Repo / docs intelligence** | deepwiki, librarian                              | Verify pass 3–5                           |
+| **Source access + search**   | opensrc + `rg`/`find` on `$(opensrc path <pkg>)` | Verify pass 4 only — not shortlist survey |
+
+opensrc fetches cached source; it does **not** discover candidates. Use discovery search first; opensrc when finalists exist and internals matter.
+
+## Skill resolution ladder
+
+When a research skill is needed, resolve in order — stop at first hit. Announce which step forced a behavior change.
+
+**Portable resolution:** If `/skill:` slash commands are unavailable, load the same capability from `<available_skills>` or `.atl/skill-registry.md` by path — keep this ladder order; do not swap opensrc before official docs for contract questions.
+
+| Step | Skill                              | When                                                                            |
+| ---- | ---------------------------------- | ------------------------------------------------------------------------------- |
+| 1    | **deepwiki** (`/skill:deepwiki`)   | Public GitHub repo; architecture / how-it-works questions                       |
+| 2    | **librarian** (`/skill:librarian`) | Implementation proof, permalinks, git history, issue/PR context                 |
+| 3    | **opensrc** (`/skill:opensrc`)     | Finalist known; read or **search within** local source (`rg` on `opensrc path`) |
+| 4    | **brave-search** or **web-search** | Current docs, surveys, release notes, fact-check                                |
+| 5    | Project fallback                   | `./skills/` — load matching `SKILL.md` only when this flow is not enough        |
+
+Path-specific notes:
+
+- **Conceptual / API contract** → official docs first (verify-gate); deepwiki/librarian only when docs are thin or disputed
+- **Internals / performance / edge cases** → librarian or opensrc before blog posts
+- **Hotmilk planning after pick** → pioneer or tcz-agent-converge when integration is large or ambiguous (resolve via ladder step 5 if slash unavailable)
+
+## Recommend output (Phase 4)
+
+Emit a concise verdict only when verify-gate **done** criteria pass.
+
+```markdown
+## Recommendation
+
+**Pick:** …
+**Why:** … (cite docs or permalinks)
+**Tradeoffs:** …
+**Alternatives considered:** …
+**Reversibility:** swap cost / migration note
+**Evidence gaps:** … (if any — do not hide)
+```
+
+If evidence is insufficient, say what is missing and which verify step would close it — do not fake certainty.
+
+## Anti-patterns
+
+| Do not                                      | Why                                | Do instead                                               |
+| ------------------------------------------- | ---------------------------------- | -------------------------------------------------------- |
+| Read `references/` without a matching phase | Wastes tokens; wrong workflow      | Load only when scope, shortlist, or verify phase applies |
+| Pick from GitHub stars alone                | Stars ≠ maintenance, security, fit | shortlist-gate criteria + verify-gate maintenance checks |
+| Skip license check for production deps      | Legal / compliance risk            | verify-gate license row for every finalist               |
+| Treat one blog post as API contract         | Drift from official docs           | Official docs first; blog as secondary signal only       |
+| Clone every repo before reading docs        | Wastes time                        | Docs pass first; opensrc/librarian when internals matter |
+| Recommend before verify **done**            | Plausible-but-wrong picks ship     | Finish verify-gate; list evidence gaps explicitly        |
+| Shortlist >5 without user ask               | Review paralysis                   | Cap at 3–5; ask user to widen scope if needed            |
+| Ignore archived / unmaintained repos        | Future breakage                    | verify-gate maintenance gate — drop or flag              |
+| Use training-data memory for "latest"       | Stale version / API claims         | web-search or brave-search for current facts             |
+| Holistic stack pick from one library doc    | Misses integration constraints     | scope-gate holistic path + verify-gate holistic table    |
+| AGPL/SSPL in proprietary SaaS               | Compliance blockers                | verify-gate license row + deployment model               |
+| Vendor SDK as only integration path         | Lock-in without exit               | Require exit path row; thin wrapper or second finalist   |
+| Pre-1.0 semver for production               | Breaking API without pin strategy  | Flag risk; require changelog pass or user waiver         |
+
+---
+
+Read the **entire** reference for the active phase before shortlisting or recommending.

package/skills/recommend-research/references/example-narrow.md

@@ -0,0 +1,53 @@
+# Example: narrow track (reference walkthrough)
+
+**Load when:** First use of this skill, or user asks for an example / how the flow works.
+
+**Do NOT load when:** Active phase work is underway — follow scope → shortlist → verify instead.
+
+## Scenario
+
+User: "Rust HTTP client for this service — reqwest vs ureq vs hyper?"
+
+## Phase 1 — Scope (scope-gate)
+
+- Track: **Narrow** — one library family (HTTP client).
+- Must-haves: async, TLS, JSON body helpers, MIT/Apache OK.
+- Incumbent baseline: stdlib only (manual `TcpStream` + hand-rolled HTTP).
+- One-line pin: "Pick async Rust HTTP client for outbound JSON APIs; TLS required."
+
+## Phase 2 — Shortlist (shortlist-gate)
+
+| Finalist | One-line rationale                                          |
+| -------- | ----------------------------------------------------------- |
+| reqwest  | Ecosystem default; async + TLS + JSON ergonomics            |
+| ureq     | Sync-only; drop if async is hard must-have                  |
+| hyper    | Low-level; keep if user needs control over middleware stack |
+
+Dropped: ureq — violates async must-have.
+
+If all candidates fail cut criteria → relax one must-have with user, widen category, or stop with "no evidence-backed pick."
+
+## Phase 3 — Verify (verify-gate)
+
+Per finalist (reqwest, hyper):
+
+1. **Pass 1** — Official docs: async API, TLS feature flags, MSRV, license.
+2. **Pass 2** — Changelog: recent release cadence, breaking changes in last 12mo.
+3. **Pass 4** (if performance questioned) — opensrc on hot path or librarian for issue history.
+
+Evidence gaps: none if pass 1–2 satisfy must-haves.
+
+## Phase 4 — Recommend (SKILL.md template)
+
+```markdown
+## Recommendation
+
+**Pick:** reqwest
+**Why:** Official async + TLS docs match must-haves; active releases (cite doc URL)
+**Tradeoffs:** Heavier deps than hyper; less control than raw hyper stack
+**Alternatives considered:** hyper — more control, more boilerplate; ureq dropped (sync-only)
+**Reversibility:** Medium — HTTP client swap touches call sites and middleware
+**Evidence gaps:** (none)
+```
+
+Skill resolution during verify: web-search/brave-search for docs (step 4); opensrc only if user asks about connection pooling internals.

package/skills/recommend-research/references/scope-gate.md

@@ -0,0 +1,46 @@
+# Scope gate (Phase 1)
+
+**Load when:** Phase 1 runs — before shortlist or verify. User intent for technology choice is present but track is not yet pinned.
+
+**Do NOT load when:** User already committed to holistic vs narrow in chat; skip to shortlist-gate or verify-gate. User only wants internals of a named library — load verify-gate directly.
+
+## Decision tree
+
+| Signal                                                          | Track                    | Examples                                                                      |
+| --------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------- |
+| Multiple moving parts, stack, practice, cross-layer integration | **Holistic**             | "Auth for Workers + D1 + frontend", "observability stack", "monorepo tooling" |
+| One category or one library family                              | **Narrow**               | "Rust HTTP client", "Zod vs Valibot", "test runner for this repo"             |
+| User named exactly one candidate                                | **Narrow (verify-only)** | Skip shortlist-gate; verify that candidate + one obvious alternative          |
+
+Say which track you chose and why in one sentence.
+
+## Holistic checklist
+
+Before shortlisting, pin:
+
+| Topic                | Question                                                |
+| -------------------- | ------------------------------------------------------- |
+| Decision owner       | Who lives with this choice in 6 months?                 |
+| Reversibility        | Swap cost — migration, API surface, team skill?         |
+| Evidence bar         | What would falsify the leading option?                  |
+| Constraints          | Runtime, license, hosting, team language, existing deps |
+| Integration surfaces | Which layers/modules must agree?                        |
+
+Holistic scope → shortlist **per layer or concern**, not one flat list of unrelated libraries.
+
+## Narrow checklist
+
+| Topic               | Question                                                |
+| ------------------- | ------------------------------------------------------- |
+| Category boundary   | What is in / out of scope for this pick?                |
+| Must-haves          | Hard requirements (license, protocol, size, sync/async) |
+| Nice-to-haves       | Tie-breakers only — not gate zero                       |
+| Default alternative | Name the incumbent or "do nothing" baseline             |
+
+## Stop / escalate
+
+| Condition                                      | Action                                                                                         |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Requirements contradictory                     | One clarifying question; do not shortlist yet                                                  |
+| Pick is product/business not technical         | Say so; ask for product constraints before research                                            |
+| Scope spans hotmilk bundled extension manifest | Note `pioneer` bundled-extension pins; hand off after recommendation if implementation follows |

package/skills/recommend-research/references/shortlist-gate.md

@@ -0,0 +1,69 @@
+# Shortlist gate (Phase 2)
+
+**Load when:** Phase 2 runs — scope track is pinned and finalists are not yet chosen.
+
+**Do NOT load when:** User supplied a final candidate list (≤5) and asked for verify only. Holistic scope not yet pinned — load scope-gate first.
+
+## Target size
+
+| Rule        | Detail                            |
+| ----------- | --------------------------------- |
+| Default cap | **3–5** finalists                 |
+| Minimum     | 2 when a comparison was requested |
+| Widen       | Ask user before exceeding 5       |
+
+Cut aggressively. Surveys seed options; they do not replace verify.
+
+## Seed sources (fast pass)
+
+Use curated surveys and comparisons to seed — then drop weak fits before verify spends tokens.
+
+| Source type                                 | Use for                                                                                                                  |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Official "comparison" / "alternatives" docs | Category leaders                                                                                                         |
+| Trusted survey posts (dated)                | Breadth — always date-check                                                                                              |
+| Repo README "similar projects"              | Maintainer view                                                                                                          |
+| Existing project deps / lockfiles           | Incumbent and neighbors — names only; use opensrc in verify pass 4 to read/search those deps, not to seed new categories |
+
+**Do not** treat seed sources as evidence. They only populate the shortlist.
+
+## Cut criteria (apply before verify)
+
+Drop a candidate when **any** hard fail:
+
+| Gate        | Fail signal                                                         |
+| ----------- | ------------------------------------------------------------------- |
+| Maintenance | Archived, no release >18mo, bus factor 1 with no activity           |
+| License     | Incompatible with stated deployment (GPL in proprietary SaaS, etc.) |
+| Constraint  | Violates must-have from scope-gate (runtime, protocol, size)        |
+| Fit         | Solves adjacent problem, not the asked category                     |
+| Risk        | Unresolved security advisory without fix path                       |
+
+Keep a **dropped** note (one line each) for transparency when user may ask "why not X?".
+
+## Empty shortlist recovery
+
+When **every** candidate fails cut criteria:
+
+| Step | Action                                                                         |
+| ---- | ------------------------------------------------------------------------------ |
+| 1    | List hard fails per dropped option (one line each)                             |
+| 2    | Ask user to relax one must-have, widen category, or accept higher risk tier    |
+| 3    | Re-seed with broader survey pass — do not verify until ≥2 finalists remain     |
+| 4    | If still empty → stop; no Phase 4 verdict. State constraints vs market reality |
+
+## Thinking before cut
+
+Ask internally (or one user question if blocking):
+
+- **Reversibility:** Is this a experiment-friendly pick or a multi-year bet?
+- **Evidence bar:** What single fact would eliminate each finalist?
+- **Incumbent:** Is "keep current dep / stdlib / no new dep" on the list?
+
+## Done → Phase 3
+
+Shortlist gate is **done** when:
+
+1. 3–5 finalists (or 2 for strict either-or) listed with one-line rationale each
+2. Dropped notable options summarized if user named them
+3. Next step declared: verify-gate per finalist