hotmilk 0.1.13 → 0.1.14

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,81 @@
+# 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.
+
+## 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/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

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

@@ -0,0 +1,73 @@
+# Verify gate (Phase 3)
+
+**Load when:** Phase 3 runs — finalists exist and evidence-backed recommendation is next.
+
+**Do NOT load when:** Scope not pinned (scope-gate). No finalists yet (shortlist-gate). User only asked for a link or doc lookup with no recommendation — use skill resolution ladder inline.
+
+## Verify ladder (per finalist)
+
+Run passes in order. Stop early when **done** criteria pass for the asked question depth.
+
+| Pass | Source               | Skill / tool                                                                            | Proves                                                                                 |
+| ---- | -------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| 1    | Official docs        | fetch / web-search / brave-search                                                       | API contract, supported versions, install, license statement                           |
+| 2    | Changelog / releases | same                                                                                    | Breaking changes, release cadence                                                      |
+| 3    | Repository           | **`/skill:deepwiki`** or README                                                         | Architecture, scope, documented limits                                                 |
+| 4    | Source / history     | **`/skill:librarian`** or **`/skill:opensrc`** + `rg`/`find` on `$(opensrc path <pkg>)` | Internals, edge cases, performance, "why" — source **search**, not candidate discovery |
+| 5    | Issues / security    | librarian / gh / advisory DB                                                            | Open blockers, CVE status                                                              |
+
+**Contract questions** → pass 1–2 often enough. **Internals / performance** → pass 4 required. Do not skip pass 1 because pass 4 is tempting.
+
+## Holistic verify (cross-layer picks)
+
+When scope-gate chose **Holistic**, run per-finalist passes **and** this integration table before Phase 4:
+
+| Row                     | Check                                                       |
+| ----------------------- | ----------------------------------------------------------- |
+| API compatibility       | Shared types, auth tokens, error shapes across layers       |
+| Shared auth / identity  | One login story; no duplicate secret stores                 |
+| Deployment coupling     | Can layers deploy independently? Single rollback path?      |
+| Data / schema alignment | Migrations, IDs, event contracts between components         |
+| Ops surface             | One observability story; avoid N unrelated agents           |
+| Rollback                | Partial failure — which layer reverts without orphan state? |
+
+Holistic **done** requires at least one integrated stack story (not independent per-layer winners) with citations per layer.
+
+## Per-finalist checklist
+
+| Row         | Required for production pick                                  |
+| ----------- | ------------------------------------------------------------- |
+| License     | SPDX or README license — compatible with stated use           |
+| Maintenance | Last release or commit within acceptable window for risk tier |
+| API fit     | Maps to must-haves from scope-gate with doc citation          |
+| Ops fit     | Install size, runtime deps, platform support                  |
+| Exit path   | Migration or wrap cost if pick fails                          |
+
+## Unavailable source fallbacks
+
+| Situation                       | Fallback                                                              |
+| ------------------------------- | --------------------------------------------------------------------- |
+| Docs site down                  | Cached README, deepwiki, tagged release tree; say source is secondary |
+| Private repo                    | Only public evidence; flag "cannot verify internals"                  |
+| Archived project                | Recommend against unless user explicitly accepts unmaintained risk    |
+| opensrc / librarian unavailable | Official docs + changelog only; widen **Evidence gaps** in verdict    |
+| Conflicting blog vs docs        | **Docs win** unless source inspection proves blog correct             |
+
+## Done criteria (Phase 3 complete)
+
+Verify gate is **done** when:
+
+1. Every **finalist** has pass 1 complete; passes 2–5 match question depth
+2. At least one finalist has clear **pick** support with citations (doc URL or permalink)
+3. Alternatives have explicit **why not** or tie-breaker
+4. **Evidence gaps** listed — empty only when passes required for scope are satisfied
+
+If done criteria fail, do **not** emit Phase 4 recommendation. State missing evidence and offer next verify step or user waiver.
+
+## Handoff after verify
+
+| Next user intent                  | Skill                                 |
+| --------------------------------- | ------------------------------------- |
+| Implement integration in hotmilk  | **`/skill:pioneer`**                  |
+| Large multi-agent integration bet | **`/skill:tcz-agent-converge`**       |
+| Prompt/skill edit from research   | **`/prompt-eval <path>`** before ship |

package/skills/update-docs/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: update-docs
+description: Sync documentation to code and config — README, CONTRIBUTING, AGENTS.md, CLAUDE.md, docs/, manifests, CI, config templates (e.g. hotmilk.json), and post-merge doc drift. Use for /update-docs, update docs, sync docs, docs drift, stale README, or after changes to commands, defaults, toggles, dependencies, or module layout.
+---
+
+# Update docs
+
+Reconcile docs with **code and config as source of truth**. Fix drift; do not rewrite for voice or expand scope.
+
+## Scenario router (read first)
+
+| User signal                                    | Route                                                                                                                     |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| "Sync all docs" / post-release / manifest work | **Full** — Phase 0 → 4; read entire [`doc-inventory.md`](references/doc-inventory.md)                                     |
+| Named file only (`README`, one doc file)       | **Targeted** — Phase 1–3 on that file + its truth sources from inventory                                                  |
+| User just shipped code; docs maybe stale       | **Post-ship** — read ONLY **Post-ship triggers** in `doc-inventory.md`; do NOT load `drift-verification.md` until Phase 4 |
+| User wants new docs / rewrite tone             | **Stop** — sync fixes truth; ask whether to write new content separately                                                  |
+
+**References:** Do **not** read `references/` until a phase below requires it. Each reference states load conditions at the top.
+
+## Phase map
+
+Skip phases that do not apply. State which phase was skipped and why.
+
+```text
+0. Scope           → doc-inventory.md          (Full sync — MANDATORY READ ENTIRE FILE)
+1. Recon           → truth files + target docs (read-only)
+2. Diff            → drift list only           (no edits yet)
+3. Patch           → minimal surgical edits    (one theme per pass unless user asked batch)
+4. Verify          → drift-verification.md     (MANDATORY READ ENTIRE FILE before reporting done)
+```
+
+## Recon rules (Phase 1)
+
+| Rule            | Detail                                                                                                                                    |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Truth first     | Read listed source-of-truth files before editing any doc                                                                                  |
+| No invention    | If truth is silent, report the gap — do not guess commands, paths, or defaults                                                            |
+| Truth conflicts | When doc, manifest, and CI disagree: **CI > manifest scripts/targets > source comments**; report the conflict instead of picking silently |
+| Scope           | Touch only doc files implicated by the diff; no drive-by style edits                                                                      |
+| Language        | Match each file's existing language and heading style                                                                                     |
+
+## Patch rules (Phase 3)
+
+| Do                                                                         | Do not                                                                     |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Fix factual drift (commands, paths, defaults, version pins, module layout) | Rewrite unrelated sections for "clarity"                                   |
+| Keep tables and lists aligned when two docs cover the same fact            | Duplicate long prose — prefer one canonical section + link                 |
+| Update config samples when **code** defaults changed                       | Change runtime defaults in code while "fixing" docs unless user asked      |
+| Preserve technical terms and command literals                              | Translate or rephrase during drift sync unless user asked for localization |
+
+## Output (Phase 4)
+
+Emit after the verify checklist passes (or list blockers):
+
+```markdown
+## Doc sync report
+
+**Scope:** full | targeted | post-ship
+**Truth sources read:** …
+**Files patched:** … (or none)
+
+### Drifts fixed
+
+- …
+
+### Gaps (no truth — not patched)
+
+- …
+
+### Verify
+
+- [ ] …
+```
+
+## Anti-patterns
+
+| Do not                                                              | Why                                     | Do instead                                       |
+| ------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------ |
+| Read `references/` without a matching route                         | Token waste                             | Router row first                                 |
+| Edit docs before reading truth files                                | Propagates stale claims                 | Phase 1 recon                                    |
+| Full README rewrite on a targeted request                           | Review noise                            | Named file only                                  |
+| Add a `docs/` tree when the repo has none                           | Scope creep                             | Skip; mention only if user wants new docs        |
+| "Improve" prose without drift                                       | Style ≠ sync                            | Diff list must cite a truth mismatch             |
+| Skip verify after patch                                             | Drift returns unnoticed                 | Phase 4 checklist                                |
+| Copy root manifest commands into every package README in a monorepo | Wrong scope; breaks package-local truth | Root ↔ root manifest; package ↔ package manifest |