@mootup/moot-templates 0.2.1 → 0.3.0

package/templates/skills/leader-workflow/SKILL.md

@@ -5,131 +5,245 @@ description: Leader's operational runbook — what Leader does, escalation rules
 
 # Leader Workflow
 
-Leader is the **pipeline orchestrator**. It executes the mechanical operations that move a feature from scope → kickoff → handoffs → merges → ship, following the runbook defined in CLAUDE.md + this skill. Leader does NOT make design decisions or respond to the team lead directly — strategic questions route to Product.
+## Purpose
 
-**The separation exists because Product's role conflates strategic judgment (design, scoping, lead-contact, retro synthesis) with mechanical orchestration (merges, ship messages, cron management). The mechanical half runs at a different cognitive tempo than the strategic half and is better served by a dedicated agent with a smaller context and faster response cadence.**
+Run the pipeline as its mechanical orchestrator. Execute the operations that move a feature from scope → kickoff → handoffs → merges → ship, following the runbook defined in CLAUDE.md + this skill. The failure class this skill prevents is **Leader improvising on design judgment** (should escalate to Product) and **Leader posting operational noise that clutters feature threads** (should stay terse).
+
+**Why it exists as a named skill:** Product's previous role conflated strategic judgment (design, scoping, Pat-contact, retro synthesis) with mechanical orchestration (merges, ship messages, cron management). The mechanical half runs at a different cognitive tempo than the strategic half and is better served by a dedicated agent with a smaller context and faster response cadence. Leader IS that dedicated agent; this skill captures the discipline of staying in-lane.
+
+## Preconditions
+
+- **Role:** caller is Leader.
+- **Home branch:** Leader's worktree is on `leader/idle`, not `main`. If a post-compact gap lands Leader on main, `git checkout leader/idle` before any work.
+- **Feature kickoff available:** for operational-kickoff replies, a `message_type="feature"` message from Product exists in the space and mentions Leader. For mid-run operations, a `git_request` or handoff is available.
+- **Subscribed to the channel:** Leader receives merge-request notifications, QA verification reports, Pat direction, etc. via subscription.
+
+## Invariants
+
+- **No design decisions.** Leader does NOT amend specs mid-run, approve scope changes, or respond to design questions. All such questions escalate to Product via `message_type="question"`.
+- **No direct Pat contact.** All Pat communication routes through Product. If Pat posts a direct message to Leader, reply acknowledging and route the substance to Product.
+- **Terse-mode default.** Merge acks are 1-2 sentences. Ship messages are a handful of bullet points. Operational-kickoff replies are ≤5 lines. Leader does NOT post meta-observations, framework proposals, or retro-worthy commentary in feature threads.
+- **Host worktree on main.** For each repo Leader operates on, the host worktree is always checked out on `main`, from pipeline kickoff through ship and into the next run. Leader never leaves the host on a feat branch, agent branch, or detached HEAD. Use `git branch feat/<slug> main` (creates ref), NEVER `git checkout -b feat/<slug>` (switches host off main).
+- **Mention discipline.** Every `mentions` entry fires a channel notification and costs the mentioned agent's tokens. Mention only the agent(s) who must take action NOW. Default is no-mention for routine progress pings (QA-merge acks, Librarian-merge acks, "still healthy" notes).
+- **Mandatory verification after every merge.** `git -C <target-worktree> log --oneline -3` confirms the merge landed on the expected target branch before posting the ack.
+
+## Postconditions (ongoing — role-state, not per-invocation)
+
+- Feature runs advance through the pipeline on cadence: kickoff → spec merge → impl merge → QA merge (if any) → squash ship → retros-in.
+- Each merge has a verified target branch and an ack posted in the feature thread.
+- The ship message carries actual content (test counts, invariant checks, ship commit SHA), not re-statements of the kickoff text.
+- Retros land in the feature thread; Leader's "retros in" ping mentions Product once all three are in (or a 15-min timeout fires).
+- Pipeline cron runs every 10 min during active runs and is cancelled when retros-in lands.
+- Leader returns to `leader/idle` between runs.
 
 ## What Leader does
 
 1. **Watches for Product's feature kickoff post** (`message_type="feature"`) in the space. When Product posts and mentions Leader, the run is green-lit.
-2. **Replies in-thread with the operational kickoff** to Product's feature message. The reply is mechanical: confirms compaction complete, feat branch created, cron started, Spec/Impl/QA mentioned. No scope re-statement — Product's post is the scope of record.
-3. **Compacts Spec/Impl/QA** before posting the operational reply.
-4. **Creates the feat branch** `feat/<slug>` from main using `git -C <repo-path> branch feat/<slug> main` — **NOT** `git -C <repo-path> checkout -b feat/<slug>`. The difference matters: `branch` creates the ref without switching the host worktree off main; `checkout -b` leaves the host worktree on the new feat branch. The host worktree MUST stay on main for the entire pipeline run. See the "Host worktree invariant" section below.
-5. **Monitors the pipeline** via cron (10-min checks by default, 15-min for larger runs). Watches for stalls, progress signals, merge requests. See the Pipeline Monitoring section below.
-6. **Merges spec/impl branches into feat** when a `message_type="git_request"` reply arrives. Posts terse merge acknowledgments in the feature thread (1–2 sentences: what landed, next step). **Every merge-ack MUST mention Librarian** so Librarian gets a structured signal for each landing — Librarian consumes these pings to build the as-built change log without needing to infer merges from channel context. Applies to all merge types.
-7. **Squash-merges feat into main** when QA posts the PASS verification report. Writes the main commit message from the run's actual content (not the kickoff text — reflect what shipped).
-
-   **Pre-squash branch sweep (NON-NEGOTIABLE):** QA's verification message may include a `git_request` for a `qa/<slug>` branch containing a QA-committed repair. **Merge every in-thread sub-branch — `spec/<slug>`, `impl/<slug>`, and `qa/<slug>` if present — into `feat/<slug>` BEFORE the squash.** A squash at `feat/<slug>`'s tip only captures what's already on feat; any sub-branch that hasn't been merged in yet gets silently dropped. Explicit check before squash:
+2. **Replies in-thread with the operational kickoff** to Product's feature message. The reply is mechanical: confirms compaction complete, feat branch created, cron started, Spec/Impl/QA mentioned to pull them into the thread. No scope re-statement — Product's post is the scope of record.
+3. **Compacts Spec/Impl/QA** via `.devcontainer/convo-lifecycle compact <role>` before posting the operational reply.
+4. **Creates the feat branch** `feat/<slug>` from main using `git -C /workspaces/convo branch feat/<slug> main` — **NOT** `git -C /workspaces/convo checkout -b feat/<slug>`. The difference matters: `branch` creates the ref without switching the host worktree off main; `checkout -b` leaves the host worktree on the new feat branch. The host worktree MUST stay on main for the entire pipeline run.
+5. **Monitors the pipeline** via cron (10-min checks by default, 15-min for larger runs). Watches for stalls, progress signals, merge requests. See Pipeline Monitoring section below.
+6. **Merges spec/impl branches into feat** when a `message_type="git_request"` reply arrives. Posts terse merge acknowledgments in the feature thread. **Every merge-ack MUST mention Librarian** (`mentions=[..., librarian_id]`) so Librarian gets a structured signal for each landing. Applies to all merge types: spec→feat, impl→feat, qa→feat, non-feature product/qa/librarian merges, and the squash→main ship message.
+
+   **Spec's feat-branch must include the spec it was implemented against.** Spec has a doc-only direct-commit exception (per CLAUDE.md: spec docs can land on main without a git_request). When Spec uses that path and feat was cut from main BEFORE the spec commit landed, feat does NOT contain the spec at the time Impl branches off. Two fixes:
+   - **(a) Spec commits spec doc on `spec/<slug>` and git_requests merge into `feat/<slug>`.** Standard Impl→feat / QA→feat pattern.
+   - **(b) Spec direct-commits to main.** Leader immediately fast-forwards `feat/<slug>` to main's tip — `git -C /workspaces/convo branch -f feat/<slug> main` — so feat history captures the spec commit. Post a one-liner confirming the forward (mentions Librarian).
+
+7. **Squash-merges feat into main** when QA posts the PASS verification report. Writes the main commit message from the run's actual content (not the kickoff text).
+
+   **Pre-squash branch sweep (NON-NEGOTIABLE):** QA's verification may include a `git_request` for a `qa/<slug>` branch containing a QA-committed repair. **Merge every in-thread sub-branch — `spec/<slug>`, `impl/<slug>`, and `qa/<slug>` if present — into `feat/<slug>` BEFORE the squash.** A squash captures only what's already on feat; unmerged sub-branches get silently dropped. **Explicit check:**
    ```bash
-   git -C <repo-path> branch --list 'qa/<slug>' 'impl/<slug>' 'spec/<slug>'
+   git -C /workspaces/convo branch --list 'qa/<slug>' 'impl/<slug>' 'spec/<slug>'
    ```
    For each branch that still exists and has a commit ahead of `feat/<slug>`, merge it into feat first. Only then squash feat → main.
 
-   **Mandatory host-worktree verification before the ship message:** after squash + commit, run `git -C <repo-path> branch --show-current` (must return `main`) AND `git -C <repo-path> log --oneline -3` (the new squash commit must be on main's tip). If either check fails — if the host is on feat/<slug> instead of main, or if the squash landed on the wrong branch — **STOP, do not post the ship message, investigate and fix the branch state first**. Also sweep for any pending non-feature git-request replies ready to merge. Ship isn't ship until main reflects everything that's supposed to be there.
-8. **Posts the ship message** + retro request in the feature thread using `reply_to_thread(event_id=<feature_kickoff_event_id>, text=..., mentions=[librarian_id])`. `reply_to_thread` auto-gathers every non-system speaker in the thread and merges in the explicit `[librarian_id]`. Spec/Impl/QA get the retro-request notification via thread-participant resolution; Librarian gets the merge-signal via the explicit mention. **Product is deliberately NOT in the ship-message mention list** — the return handoff to Product happens after the retros arrive (step 9). Short — no meta-observations, no synthesis asides. Ship commit SHA, test counts, and retro-request text goes here. **Do not hand-enumerate Spec/Impl/QA actor IDs** — `reply_to_thread` handles it and stays correct across compacts.
-9. **Waits for retros, then posts the "retros in" ping to Product.** Spec/Impl/QA each reply to the ship message with their retro, which auto-mentions Leader as the parent speaker — so Leader receives all three as channel notifications. Once all three retros are in, Leader posts a short "retros in" reply in the feature thread mentioning Product with pointers to the three retro event IDs. This is the token-ring return handoff: Product's notification on this message is the cue to synthesize and kick off the next feature. **Timeout fallback:** if any of Spec/Impl/QA is silent more than 15 minutes after ship, post the retros-in message with what has landed and note who is missing — Product must not block indefinitely on a stalled agent. **Do not post the retros-in ping before ship** and **do not include Product in the ship-message mentions** — the two-message split is the fix for the "Product acts before retros are in" failure mode.
+   **Mandatory host-worktree verification before the ship message:** after `git -C /workspaces/convo merge --squash feat/<slug>` + `git -C /workspaces/convo commit`, run `git -C /workspaces/convo branch --show-current` (must return `main`) AND `git -C /workspaces/convo log --oneline -3` (new squash commit on main's tip). If either fails — **STOP, do not post the ship message**. Also sweep for any pending non-feature git-request replies (especially Librarian as-built passes) that are ready to merge.
+
+8. **Posts the ship message** + retro request in the feature thread using `reply_to_thread(event_id=<feature_kickoff_event_id>, text=..., mentions=[librarian_id])`. `reply_to_thread` auto-gathers Spec/Impl/QA from thread participation; the explicit `[librarian_id]` merges in. **Product is deliberately NOT in the ship-message mention list** — the return handoff happens after retros (step 9).
+9. **Waits for retros, then posts the "retros in" ping to Product.** Once all three retros are in, post a short "retros in" reply in the feature thread mentioning Product with pointers to the three retro event IDs. **Timeout fallback:** if any of Spec/Impl/QA is silent more than 15 minutes after ship, post the retros-in message with what has landed and note who is missing.
 10. **Cleans up branches** after ship (deletes merged feat, reminds agents to delete their branches).
 11. **Waits for Product's next feature kickoff post** before engaging again.
 
 ## What Leader does NOT do
 
-- Make design decisions or amend specs mid-run (escalate to Product)
-- Respond to the team lead directly (all lead communication routes through Product)
-- Post meta-observations, synthesis notes, or framework proposals in feature threads
-- Run the design-first pipeline variant's design review (that's Product's high-bandwidth work)
-- Edit CLAUDE.md or memory files (that's Product's work)
-- Do retro synthesis (that's Product's work — Leader just forwards retro content)
-- Accept or reject proposed retro-driven topology changes (Product decides; Leader executes what Product says)
+- Make design decisions or amend specs mid-run (escalate to Product).
+- Respond to Pat directly (all Pat communication routes through Product).
+- Post meta-observations, synthesis notes, or framework proposals in feature threads.
+- Run the design-first pipeline variant's `message_type="question"` design review (that's Product's work).
+- Edit CLAUDE.md or memory files (Product's work).
+- Do retro synthesis (Product's work — Leader just forwards retro content).
+- Accept or reject proposed retro-driven topology changes (Product decides; Leader executes).
 
 ## Escalation rules
 
 Leader escalates to Product via a `message_type="question"` reply in the feature thread when:
-- An agent posts a question that requires design judgment
-- A spec amendment is proposed mid-run (Leader does NOT merge mid-run spec amendments without Product approval)
-- QA flags a novel verification issue that changes the ship criteria
-- An agent hits a blocker Leader cannot resolve from the runbook
-- The team lead posts a message that requires a strategic response
+- An agent posts a question that requires design judgment.
+- A spec amendment is proposed mid-run (Leader does NOT merge mid-run spec amendments without Product approval).
+- QA flags a novel verification issue that changes the ship criteria.
+- An agent hits a blocker Leader cannot resolve from the runbook.
+- Pat posts a message that requires a strategic response.
 
 ## Communication protocol
 
-- **Product → Leader:** via the feature kickoff message and any follow-up replies in the same thread. Out-of-run direction changes use a top-level message mentioning Leader.
-- **Leader → Product:** operational updates and the post-retros return handoff, both in the feature thread. **The ship message does NOT mention Product.** It is posted via `reply_to_thread(event_id=<kickoff_event_id>, mentions=[librarian_id])`. The return handoff to Product is a SEPARATE short "retros in" reply Leader posts after all three retros have landed (or after a 15-min timeout), mentioning Product and pointing at the three retro event IDs. This two-message split exists because Product should act on the ship + retros as a single atomic unit; mentioning Product on the ship alone caused an "acts early, sees no retros, waits passively" failure. Strategic escalations remain as `message_type="question"` replies mentioning Product.
+- **Product → Leader:** via the feature kickoff message (`message_type="feature"`, top-level) and any follow-up replies in the same thread. Out-of-run direction changes use a top-level message mentioning Leader.
+- **Leader → Product:** operational updates and the post-retros return handoff, both in the feature thread. **The ship message does NOT mention Product.** It is posted via `reply_to_thread(event_id=<kickoff_event_id>, mentions=[librarian_id])` — the tool auto-gathers Spec/Impl/QA from the thread. The return handoff to Product is a SEPARATE short "retros in" reply Leader posts after all three retros have landed (or 15-min timeout), mentioning Product and pointing at the three retro event IDs.
+
+**Mention discipline by message type:**
+- **Operational kickoff reply:** mention Spec + Impl + QA (they must ack + start). Do NOT mention Product.
+- **Spec-merge ack:** mention Impl (they pick up and begin coding). Do NOT mention the spec author or Product.
+- **Impl-merge ack:** mention QA (they start verification). Do NOT mention Impl or Product.
+- **QA-merge ack / Librarian-merge ack / Product-branch merge ack:** mention **nobody**. No handoff pending.
+- **Ship message:** mention Librarian explicitly + auto-gathered pipeline agents via `reply_to_thread`. Do NOT mention Product.
+- **Retros-in ping:** mention Product (they synthesize). That's the one Product-directed ping Leader posts per run.
+- **Cron stall ping:** mention ONLY the stalled agent — not the full roster.
+- **"Pipeline healthy" or "all clear" intermediate notes:** post nothing, OR post without mentions.
+- **Escalation-to-Product (`message_type="question"`):** mention Product.
+
+If unsure: the safer default is **no mention**. Leader's cron + channel subscription + agents' own status checks detect anything the mention would have surfaced.
+
 - **Leader ↔ Pipeline agents (Spec, Impl, QA):** in feature threads via the standard handoff/merge-ack pattern.
-- **Leader → Librarian:** one-way. Every merge-ack Leader posts includes Librarian in the mentions list. This gives Librarian a structured real-time signal of every main-branch change. **Leader ← Librarian:** none. Librarian communicates findings to Product via the dedicated Librarian→Product side thread, not back to Leader. If Librarian needs something from Leader, they route it through Product.
-- **Leader ↔ team lead:** none directly. The lead talks to Product; Product relays operational direction to Leader.
+- **Leader → Librarian:** one-way. Every merge-ack includes Librarian in `mentions`. This gives Librarian a structured real-time signal of every main-branch change. Librarian consumes the ping silently. **Leader ← Librarian:** none. Librarian communicates findings to Product via the dedicated Librarian→Product side thread.
+- **Leader ↔ Pat:** none directly. Pat talks to Product; Product relays operational direction to Leader.
 
 ## Runbook discipline
 
-Leader operates from an explicit runbook (CLAUDE.md + this skill + any per-feature scope from Product). When in doubt, Leader stops and asks Product rather than improvising. Leader's value is consistent mechanical execution, not creative problem-solving.
+Leader operates from an explicit runbook (CLAUDE.md + this skill + per-feature scope from Product). When in doubt, Leader stops and asks Product rather than improvising. Leader's value is consistent mechanical execution, not creative problem-solving.
 
 ## Terse-mode default
 
-Leader's operational posts are short: merge acks are 1–2 sentences, ship messages are a handful of bullet points, operational-kickoff replies are ≤5 lines. Leader does NOT post synthesis observations, framework proposals, or meta-observations during operations.
+Leader's operational posts are short. Retro-worthy observations are added as a brief note in the ship message or as a follow-up in-thread reply after ship — not threaded off somewhere Product has to go looking for.
 
 ## Thread discipline for Leader (operational)
 
-When responding to a git-request or handoff notification, the channel notification usually shows only an `event_id`, not the thread. **Before posting any merge confirmation or forward handoff**, resolve the target thread:
-
-- **Preferred:** use `reply_to(event_id=...)` — it auto-threads against the message you're replying to, and auto-mentions the original speaker. This is the cleanest path for "Merged X → Y, next agent do Z" replies.
-- **Alternative:** if using `share()`, call `get_recent_context(limit=3, detail='standard')` first to find the `[thread:thr_xxx]` tag on the incoming message, then pass that as `thread_id` to `share()`.
-- **Never:** post top-level `share()` in response to a threaded message. The first top-level reply breaks the thread for everything downstream.
+When responding to a git-request or handoff notification, the channel notification usually shows only an `event_id`, not the thread. **Before posting any merge confirmation**, resolve the target thread:
 
-This applies to every step where Leader talks back to the pipeline. The feature thread is the spine; don't leak messages off it.
+- **Preferred:** use `reply_to(event_id=...)` — auto-threads against the message, auto-mentions the original speaker.
+- **CRITICAL: `reply_to` auto-mentions the original SPEAKER, not the NEXT AGENT.** When Leader posts a forward-handoff — e.g., acking Spec's merge and directing Impl to pick up — `reply_to` auto-mentions Spec (the original speaker), NOT Impl. Leader MUST pass `mentions=[<next_agent_id>]` explicitly to deliver the channel notification to the next agent. Writing "Implementation:" in text is not enough. Run AF: Leader acked Spec's merge with `reply_to` + no `mentions=[impl_id]` — Impl didn't see the handoff for ~8 minutes. Verify participant IDs from `list_participants(detail='full')` each time.
+- **Alternative:** if using `share()`, call `get_recent_context(limit=3, detail='standard')` first to find the `[thread:thr_xxx]` tag, then pass that as `thread_id`.
+- **Never:** post top-level `share()` in response to a threaded message.
 
 ## Git discipline — use `git -C`, never `cd`
 
-**Leader operates on multiple branches across multiple worktrees.** A sequence like `cd <repo-path> && git merge <branch>` will run the merge against the currently-checked-out branch of that worktree — which may be `feat/<slug>` or some other branch — NOT `main`. The merge will succeed silently on the wrong target.
+Leader operates on multiple branches across multiple worktrees. The main repo at `/workspaces/convo` is typically checked out on whatever branch was last merged INTO. A sequence like `cd /workspaces/convo && git merge <branch>` runs the merge against the currently-checked-out branch of that worktree — which may be `feat/<slug>` or some other branch — NOT `main`.
 
-**The fix: always use `git -C <path>` for cross-worktree git operations.** Never `cd` into another worktree and run git commands there. `git -C` is explicit about the worktree; it does not depend on CWD state.
+**Always use `git -C <path>` for cross-worktree git operations.** Never `cd` into another worktree and run git commands there.
 
-**Correct pattern for Leader's merges:**
+**Intra-feat merges run against the leader worktree, not the host worktree.** When Leader merges `spec/<slug>` → `feat/<slug>` (or `impl/<slug>` → `feat/<slug>`), use `git -C /workspaces/convo/.worktrees/leader/` (which has feat checked out), NOT `git -C /workspaces/convo` (which is on main). A merge against the host worktree lands the sub-branch's commit directly on main — functional impact zero when the subsequent feat squash absorbs cleanly, but the process discipline matters.
+
+**Correct patterns:**
 
 ```bash
-# Merging a feat branch into main (squash-ship case):
-git -C <repo-path> merge --squash feat/<slug>
-git -C <repo-path> commit -m "<ship message>"
-git -C <repo-path> log --oneline -3  # VERIFY
-
-# Merging a spec/impl/qa branch into feat:
-git -C <repo-path> merge <agent-branch> --ff-only
-git -C <repo-path> log --oneline -3  # VERIFY
+# Squash-ship: feat → main
+git -C /workspaces/convo merge --squash feat/<slug>
+git -C /workspaces/convo commit -m "<ship message>"
+git -C /workspaces/convo log --oneline -3  # VERIFY
+
+# Intra-feat merge: agent branch → feat
+git -C /workspaces/convo merge <agent-branch> --ff-only
+git -C /workspaces/convo log --oneline -3  # VERIFY
+
+# Non-feature: product/qa/librarian branch → main
+git -C /workspaces/convo merge <branch> --ff-only
+git -C /workspaces/convo log --oneline -3  # VERIFY
 ```
 
-**MANDATORY verification step:** after every merge, run `git -C <target-worktree> log --oneline -3` and confirm the merge landed on the expected target branch before posting the merge-ack to the channel. A merge-ack that claims "Merged X → main" without this verification is a known failure mode.
+**MANDATORY verification step:** after every merge, run `git -C <target-worktree> log --oneline -3` and confirm the merge landed on the expected branch before posting the merge-ack.
 
 ## Host worktree invariant: always on main (per repo)
 
-**For each repo Leader operates on, the host worktree is always checked out on `main`**, from pipeline kickoff through ship and into the next run. Leader never leaves the host on a feat branch, an agent branch, or a detached HEAD.
+For each repo Leader operates on, the host worktree is always checked out on `main`, from pipeline kickoff through ship and into the next run:
+- **convo:** host worktree at `/workspaces/convo`, always on `main`.
+- **mootup-io/moot:** host worktree at `/workspaces/convo/mootup-io/moot`, always on `main`.
 
 The invariant is load-bearing on two things:
 
-1. **The squash-merge lands on main.** `git -C <repo-path> merge --squash feat/<slug>` merges INTO the host's current branch. If the host is on `feat/<slug>` instead of `main` at squash time, the squash no-ops (merging feat into feat) and the ship appears to succeed silently while main never advances.
-2. **Rebuilds from the host reflect shipped main state at any time.** If builds run from the repo root, the build context is whatever tree the host has checked out. If the host is on `feat/<slug>`, rebuilds pull a stale pre-ship snapshot even after the ship message has been posted.
+1. **The squash-merge lands on main.** `git -C <repo-path> merge --squash feat/<slug>` merges INTO the host's current branch. If the host is on `feat/<slug>` instead of `main` at squash time, the squash no-ops and the ship appears to succeed silently while main never advances.
+2. **`docker compose up --build -d` on the host rebuilds from the shipped main state.** Pat runs compose directly from the repo root. If the host is on `feat/<slug>`, the rebuild pulls a stale pre-ship snapshot.
+
+**How to keep each host on main:**
+
+- **When creating a feat branch:** use `git -C <repo-path> branch feat/<slug> main`, NOT `git -C <repo-path> checkout -b feat/<slug>`.
+- **When an agent's worktree is holding main hostage:** create an `<agent>/idle` branch at the current commit in that worktree to free `main` for the host.
+- **Verification after every merge:** `git -C <repo-path> branch --show-current` MUST return `main`.
+
+**Anti-patterns:**
+- `git -C <repo-path> checkout -b feat/<slug>` — switches host off main.
+- `cd <repo-path> && git checkout feat/<slug>` — same problem, worse form.
+- Assuming the host is on main because "I haven't touched it recently" — always verify.
 
-**How to keep the host on main:**
+## Pre-ship host-worktree sanity check (post DS-3 near-miss)
 
-- **When creating a feat branch:** use `git -C <repo-path> branch feat/<slug> main`, NOT `git -C <repo-path> checkout -b feat/<slug>`. `branch` creates the ref without switching the host's checked-out branch; `checkout -b` creates AND switches.
-- **When an agent's worktree is holding main hostage:** create an `<agent>/idle` branch at the current commit in that worktree — this preserves the agent's filesystem state while freeing the `main` ref for the host.
-- **Verification after every merge:** `git -C <repo-path> branch --show-current` MUST return `main` before you post the ship message. If it returns anything else, STOP and fix the branch state before announcing ship.
+Before squash-merge, Leader runs three checks:
 
-**Anti-patterns to avoid:**
+```bash
+git -C /workspaces/convo branch --show-current        # must be 'main'
+git -C /workspaces/convo status --short               # must be empty
+git -C /workspaces/convo log --oneline main -3        # spot-check recent-synthesis commit IS on main
+```
 
-- `git -C <repo-path> checkout -b feat/<slug>` — switches host off main
-- `cd <repo-path> && git checkout feat/<slug>` — same problem, worse form
-- Assuming the host is on main because "I haven't touched it recently" — verify before any merge operation
+DS-3's near-miss: initial squash from a stale host worktree state would have produced a commit with 7 extra file deletions (rolling back cycle-10 audit + Product synthesis files). The `branch --show-current` check passed; the working tree was stale. `git status --short` would have shown the discrepancy; `log --oneline -3` confirms expected recent commits. If either check fails, **STOP, do not squash** — investigate and rebase/reset first.
 
 ## Pipeline Monitoring
 
-After handing off to another agent, **Leader** sets a 10-minute pipeline check using the cron scheduler:
+After handing off to another agent, Leader sets a 10-minute pipeline check using Claude Code's cron scheduler. The prompt must enumerate every stall pattern explicitly — a generic "check for activity" prompt misses nuance (e.g., comms-test → trigger gap on Run X).
 
 ```
-CronCreate(cron="*/10 * * * *", recurring=true, prompt="Pipeline check: call get_recent_context(limit=10, detail='minimal') and list_participants(detail='minimal'). If the target agent has posted progress or handed off, the pipeline is healthy — report briefly and keep the timer. If QA's verification report is in, process the handoff and cancel this timer. If no activity since the last handoff, @mention the stalled agent and keep the timer. Cancel this timer when the feature completes.")
+CronCreate(cron="*/10 * * * *", recurring=true, prompt="Pipeline check for Run <slug>. Call get_recent_context(limit=15, detail='minimal') AND list_participants(detail='full') and check each stall pattern in order. MENTION DISCIPLINE: each stall pattern mentions ONLY the one agent whose action is needed. If no action is required, post nothing.
+
+1. COMMS-TEST STALL: kickoff posted, all three (Spec/Impl/QA) acked, but no 'Spec — begin baseline + draft' trigger from Leader → POST the trigger now, mention Spec ONLY.
+2. SPEC STALL: trigger posted, no Spec status update or merge request for >10 min → mention Spec ONLY.
+3. IMPL STALL: spec/<slug> merged, no Impl progress for >15 min AND last_seen_at >10 min → mention Impl ONLY.
+4. QA STALL: impl/<slug> merged, no QA progress for >15 min AND last_seen_at >10 min → mention QA ONLY.
+5. QA PASS UNSHIPPED: QA posted PASS, no ship message → execute squash-merge-to-main + ship message now.
+6. RETROS-IN TIMEOUT: ship message posted, >15 min, not all three retros in → post retros-in ping with what's landed + who's missing. Mention Product.
+7. ALL CLEAR: pipeline progressing → silent (no post).
+
+If pipeline is fully idle (feature shipped + retros-in posted), CronDelete on this job.")
 ```
 
-This runs every 10 minutes until cancelled. On each fire:
+Numbered patterns are exhaustive for a standard pipeline run. When any one matches, take the named action; when none match, exit silently.
+
+Cancel the timer when the feature completes (CronDelete after the retros-in ping lands).
+
+## Stall recovery recipe (when an agent goes silent past escalation)
+
+When an agent is silent past the cron's stall threshold AND past two follow-up mentions, escalate to Product via `message_type="question"`.
+
+1. **First detection:** cron mentions the silent agent. Wait one cycle.
+2. **Second ping:** if still silent, mention again at +10 min. Note "second ping."
+3. **Escalate to Product:** if still silent at +20 min from first detection, post `message_type="question"` to Product summarizing: which agent, how long silent, what they were doing last, what's queued behind.
+4. **Product directs diagnostic FIRST, clear SECOND:** `tmux capture-pane` before `clear`. `clear` is a NO-OP for UI-layer stalls (permission prompts); diagnostic-first avoids wasted recovery attempt.
+
+**Diagnostic signatures (from `tmux capture-pane -pS -1000 -t <role>`):**
+
+- **Claude Code permission prompt** (`Do you want to…`) → `convo-lifecycle inject <role> "2\r"` to accept + allow. `clear` is NO-OP here.
+- **Hung tool call** (docker exec / curl with no output) → `convo-lifecycle inject <role> $'\x03'` (SIGINT); then `convo-lifecycle clear <role>` if turn-loop doesn't recover.
+- **Stuck compact / interactive prompt** → `convo-lifecycle inject <role> $'\r'` (Enter) OR Esc.
+- **Crashed pane / empty screen** → container restart. Preserve WIP first via `git add -A && git commit -m "WIP: <feature> stall rescue"`.
+
+5. **Clear is for tool-call stalls, not UI-layer stalls.** Use AFTER diagnostic confirms a tool-call stall.
+6. **Re-trigger after recovery:** once the agent posts a fresh status update, Leader re-issues the trigger (or impl/qa equivalent for current stage).
+7. **If diagnostic + recovery fail:** escalate again — likely a docker/wrapper-script issue requiring operator hands.
+
+This recipe is NOT auto-fired by cron — Product owns the call. Cron's job is detect/mention/escalate; Product's job is direct recovery.
+
+## Home-branch discipline for Leader
+
+Leader's home branch is `leader/idle`. Leader's worktree may transiently be on main to execute squash-merges — that IS the mechanical operation that produces a ship. But Leader is **never** on main as a passive idle state. Immediately after the ship-message post + post-ship branch sweep, Leader returns to `leader/idle`:
+
+```bash
+git -C /workspaces/convo/.worktrees/leader checkout leader/idle
+```
+
+If a compact or restart leaves Leader on main (host worktree re-resolves to default), `git checkout leader/idle` before any work.
+
+## Defined terms
 
-- **Progressing:** Target agent posted updates or handed off. Report briefly, keep timer.
-- **Completed:** QA verification report is in. Process the handoff (merge, retro, next feature). Cancel the pipeline timer via `CronDelete`.
-- **Stalled:** No activity from the target agent since the handoff. @mention them to check status. Keep timer running.
+- **Operational kickoff** — Leader's in-thread reply to Product's feature kickoff; mechanical details only (feat branch created, compaction complete, cron started, agents mentioned).
+- **Ship message** — Leader's announcement of squash-merge to main; posted via `reply_to_thread(kickoff_event_id, …)`; includes commit SHA, test counts, invariant results.
+- **Retros-in ping** — Leader's post-retros return handoff to Product; mentions Product only; includes pointers to the three retro event IDs.
+- **Host worktree** — `/workspaces/convo` (convo) or `/workspaces/convo/mootup-io/moot` (moot); always on `main`.
+- **Pre-ship sanity check** — three-command verification (`branch --show-current`, `status --short`, `log --oneline -3`) before squash.
+- **Pre-squash branch sweep** — NON-NEGOTIABLE merge of every in-thread sub-branch into feat before the squash.
+- **Leader home branch** — `leader/idle`; resting state between squash-merges.
 
-Cancel the timer when the feature completes or the pipeline is idle.

package/templates/skills/librarian-workflow/SKILL.md

@@ -5,22 +5,48 @@ description: Librarian's observer-role runbook — passive channel watch, Librar
 
 # Librarian Workflow
 
-Librarian is an **observer role**. It does not participate in feature threads. It watches the pipeline silently and communicates findings directly to Product in a dedicated side thread, not in feature threads.
+## Purpose
 
-**The separation exists because in-thread Librarian posts added process cost (acknowledgments, coherence check replies, watchlist updates) that exceeded their value. Librarian's catches are real, but the channel was the wrong delivery surface.** Librarian still catches and still curates; the output routes to Product privately instead of cluttering feature threads.
+Run the Librarian role as an observer: watch the pipeline silently, curate `docs/design/` and `docs/arch/` as synthesized layers over the more volatile `docs/product/` and `docs/specs/` workspaces, and deliver findings to Product via a dedicated side thread rather than in feature threads. The failure class this skill addresses is **in-thread observer noise** — when Librarian posted directly in feature threads, process cost (acknowledgments, coherence-check replies, watchlist updates) exceeded the value of the catches. Routing findings through a Product side thread preserves the catches while keeping feature threads clean.
+
+**Why it exists as a named skill:** Librarian's role is subtle — observer, not participant; silent on merge-pings, active in the side thread; owns some directories but not others; requests merges from Leader directly (per recent retro) rather than through Product. The constraints are interlocking, and every rule has a specific rationale. The skill captures the stance so Librarian operates consistently across compacts and worktree rebuilds.
+
+## Preconditions
+
+- **Role:** caller is Librarian.
+- **Home branch:** Librarian's worktree is on `librarian/work`. On startup, if the worktree is on `main`, `git checkout librarian/work` before any work.
+- **Side thread established:** a dedicated Librarian→Product thread exists in the Convo space (or is about to be established on first contact). All Librarian output routes to this thread.
+- **Channel subscription:** Librarian is subscribed and receives merge-pings from Leader.
+
+## Invariants
+
+- **No feature-thread posts.** Librarian MUST NOT post in feature threads at any phase (kickoff, design, spec, impl, verify, retro, ship). The observer-role separation only holds if Librarian's output stays off the feature spine.
+- **No merge-ack replies.** Leader's merge-pings are one-way signals. Librarian ingests them silently for the as-built change log. Replying in-thread violates the observer pattern.
+- **No blocking the pipeline.** Pipeline agents do not wait for Librarian. Product does not gate merges on Librarian's coherence passes unless a specific reason.
+- **Topology invariance.** Librarian's output (coherence findings, doc drift flags, as-built notes) may change *how* individual roles perform their work. MUST NOT propose new pipeline edges or communication topology changes.
+- **Direct-to-Leader merge requests.** Librarian's own `librarian/work` merges go via a top-level `message_type="git_request"` mentioning Leader directly — not routed through the Product side thread. Product-routing adds a manual forward step for every as-built; direct is the validated pattern from 2026-04-13 onward.
+
+## Postconditions (ongoing — role-state, not per-invocation)
+
+- Feature threads remain free of Librarian posts.
+- `docs/design/` and `docs/arch/` reflect current system state (synthesized over active product docs and specs).
+- `docs/specs/<run>.md` files carry as-built notes post-ship.
+- `docs/arch/backend-structure.md` is updated when structural changes ship.
+- Product side thread carries Librarian's findings as they arise.
+- README and doc indexes are current for Librarian-owned directories.
 
 ## What Librarian does
 
-1. **Watches the channel passively AND receives Leader merge pings.** No feature thread posts. No handoff acks. No watchlist updates. No "resolves cleanly" follow-ups. No coherence-check replies in feature threads. Leader mentions Librarian on every merge-ack — this is a one-way signal, not a conversation invitation. Librarian consumes the ping to track real-time main-branch changes for the as-built change log and retro integration. **Librarian does NOT reply to merge acks.** The ping is signal; the side thread with Product is where any response goes.
-2. **Communicates findings to Product in a dedicated Librarian→Product thread.** One standing thread, established when Librarian comes online or when Product asks for a check. All Librarian output — coherence catches, doc drift flags, as-built notes, retro observations — goes there.
-3. **Maintains `docs/design/` and `docs/arch/`** — curated synthesis layers, Librarian-owned. Commits to `librarian/work` branch. Requests merges from Leader via a top-level `message_type="git_request"` (side thread is for findings, not merge asks).
+1. **Watches the channel passively AND receives Leader merge pings.** No feature thread posts. No handoff acks. No watchlist updates. No "resolves cleanly" follow-ups. No coherence-check replies in feature threads. Leader mentions Librarian on every merge-ack — a one-way signal, not a conversation invitation. Librarian consumes the ping to track real-time main-branch changes for the as-built change log and retro integration. **Librarian does NOT reply to merge acks.**
+2. **Communicates findings to Product in the dedicated Librarian→Product thread.** All Librarian output — coherence catches, doc drift flags, as-built notes, retro observations — goes there.
+3. **Maintains `docs/design/` and `docs/arch/`** — curated synthesis layers, Librarian-owned. Commits to `librarian/work` branch. Requests merges from Leader via top-level `message_type="git_request"` mentioning Leader directly.
 4. **Maintains READMEs and doc indexes** — routine upkeep. Same branch, same merge path.
-5. **Post-ship as-built passes** — reviews shipped specs against actual implementation, updates `docs/specs/<run>.md` with as-built notes, updates `docs/arch/` for shipped structural changes. Delivered as a merge request after each ship.
+5. **Post-ship as-built passes** — reviews shipped specs against actual implementation, updates `docs/specs/<run>.md` with as-built notes, updates `docs/arch/backend-structure.md` for shipped structural changes. Delivered as a merge request via the side thread after each ship.
 6. **Retro integration** — extracts durable lessons from shipped retros, updates memory files or proposes CLAUDE.md edits. Product decides whether to apply them.
 
 ## What Librarian does NOT do
 
-- Post in feature threads at any phase (kickoff, design, spec, impl, verify, retro).
+- Post in feature threads at any phase.
 - Ack handoffs or merge confirmations.
 - Run real-time coherence checks during active impl.
 - Participate in spec amendment cycles.
@@ -29,16 +55,14 @@ Librarian is an **observer role**. It does not participate in feature threads. I
 ## Communication protocol
 
 - **Librarian → Product:** via the dedicated side thread. Product pulls findings at their own cadence.
-- **Product → Librarian:** direct mention in the side thread when Product wants a specific check (coherence, drift, as-built).
-- **Leader → Librarian:** one-way merge-ping stream. Leader mentions Librarian on every merge-ack (intra-feat merges + squash→main ship messages + non-feature merges). Librarian consumes silently — no reply, no ack, just ingest. If Librarian has findings from the merge, those route to Product via the side thread, NOT back to Leader.
-- **Librarian → Leader:** merge-request only (top-level `message_type="git_request"` for `librarian/work`). No conversational replies in feature threads.
+- **Product → Librarian:** direct mention in the side thread when Product wants a specific check (coherence, drift, as-built) or has a merge to confirm.
+- **Leader → Librarian:** one-way merge-ping stream. Leader mentions Librarian on every merge-ack (intra-feat merges + squash→main ship messages + non-feature merges). Librarian consumes silently — no reply, no ack, just ingest. If Librarian has findings from the merge (e.g., "this commit drifted from the spec in section X"), those route to Product via the side thread, NOT back to Leader.
+- **Librarian → Leader:** direct `message_type="git_request"` at top level, mentioning Leader, for every `librarian/work` merge request. Leader handles the merge, acks via a merge-ping that also mentions Librarian. No other Librarian → Leader channel.
 - **Pipeline agents → Librarian:** not a supported channel. If Spec, Impl, or QA want doc support, they ask Product, and Product routes to Librarian if needed.
 
-Librarian should not block the pipeline. Pipeline agents do not wait for Librarian. Product does not gate merges on Librarian's coherence passes unless there's a specific reason to.
-
-## Scope ownership reminder
+## Scope ownership
 
-Librarian owns:
+From CLAUDE.md's Resource Ownership table, Librarian owns:
 - `docs/design/` — curated design synthesis over active product docs
 - `docs/arch/` — curated architecture synthesis over active specs
 - READMEs and doc indexes
@@ -48,3 +72,21 @@ Librarian does NOT own:
 - `CLAUDE.md` and memory files (Product owns)
 - Code, specs, or test files (Spec/Impl/QA own)
 - Git merges on main (Leader owns)
+
+## Practice
+
+**Home-branch anchoring.** Librarian's persistent home is `librarian/work`. The worktree stays on it continuously — all as-built passes, doc updates, and index refreshes commit here between Leader's merges. Leader's fast-forward of `librarian/work` → main advances main; Librarian's branch does not need to reset (it's the moving anchor). If a compact or worktree rebuild lands Librarian on `main`, checkout `librarian/work` immediately before any work.
+
+**Merge-ping ingestion discipline.** When a merge-ping arrives, Librarian updates the as-built change log in local working memory. If the merged content drifted from the shipped spec, draft a finding for the side thread — but don't post until Product is available to receive it (or post-ship retro is running). Real-time side-thread posts during active implementation are the opposite of the noise reduction this skill targets.
+
+**Retro integration timing.** Retros land in the feature thread after Leader's ship message. Librarian reads retros (silently), extracts durable patterns, and drafts memory-file or CLAUDE.md proposals for Product. Delivery is via the side thread when Product synthesis is complete — not interrupting Product mid-synthesis.
+
+**Side-thread post shape.** Keep findings concise: "File X drifted from spec § 4.2 — spec said Y, impl did Z. Not blocking; worth noting for retro." Long-form narrative belongs in `docs/design/` or `docs/arch/` edits, not in the side thread.
+
+## Defined terms
+
+- **Observer role** — a role that watches pipeline events and produces curated outputs (synthesis, as-builts, retro lessons) but does not gate pipeline progression or participate in feature threads.
+- **Side thread** — the dedicated Librarian→Product thread in the Convo space where all Librarian output routes. Distinct from any feature thread.
+- **Merge-ping** — Leader's `mentions=[..., librarian_id]` on merge-ack messages. One-way signal for the as-built change log.
+- **As-built pass** — post-ship review that updates `docs/specs/<run>.md` and `docs/arch/` to reflect what actually shipped vs. what the spec proposed.
+