@mootup/moot-templates 0.2.1 → 0.3.1

package/templates/skills/memory-audit/SKILL.md

@@ -9,7 +9,31 @@ description: Recurring audit of operator memory entries. Every fifth pipeline re
 
 Operator memory accumulates organically as pipeline retros land. Most entries are useful at the moment of capture but their durable home is uncertain — some describe team-generic rules that belong in CLAUDE.md or a workflow skill, some restate rules already documented elsewhere, and some are genuinely operator-specific state that should stay local. Without a recurring audit the memory directory drifts: promotion candidates go unpromoted, already-promoted entries become redundant, and staleness accumulates.
 
-This skill is the steady-state cadence that keeps the memory layer in sync with the durable documentation layer.
+**Why it exists as a named skill:** the audit cadence (every fifth synthesis) and the three-criterion promotion rubric need to be applied consistently across cycles and curators. The skill encodes both so each audit produces a comparable artifact — the audit report — that future audits can diff against.
+
+## Preconditions
+
+- **Role:** the role that owns memory curation. In the default team topology, Product (who also owns retro synthesis and durable documentation). In topologies without Product, the role that edits CLAUDE.md and memory files.
+- **Cadence gate:** git log shows ≥ 5 retro synthesis commits since the last `memory audit:` commit on main. If the count is less, the skill is a no-op for this invocation.
+- **Main is current.** The curator's worktree has the current main tip so git-log grep commands run against complete history.
+
+## Invariants
+
+- **Topology invariance.** Audits may promote rules that change *how* individual roles perform their work; MUST NOT promote rules that change the pipeline topology (who talks to whom). Edge-adding or phase-crossing proposals are rejected at promotion time.
+- **Three-criterion rubric is MUST.** A memory entry is a promotion candidate only if all three conditions hold: validated across ≥3 pipeline runs, operator-agnostic, describes a rule. Skipping any criterion produces spurious promotions.
+- **Audit-closing commit subject starts with `memory audit:`.** The next cadence count depends on grepping git log for this prefix; other subjects break the anchor.
+- **Retirement happens with promotion, atomic.** When a memory entry is promoted, the memory file is deleted in the same commit as the durable edit (or the immediately-next). Orphaned-in-memory-and-durable is the drift state.
+
+## Postconditions
+
+- Every memory entry has been classified into exactly one of (a) already-promoted-retire, (b) needs-promotion-draft-and-retire, (c) keep-in-memory, (d) retire-unconditionally.
+- For (a) entries: memory files deleted; MEMORY.md index updated.
+- For (b) entries: durable artifact edited with promoted text; memory files deleted; MEMORY.md index updated.
+- For (c) entries: memory files updated if needed; left in place.
+- For (d) entries: memory files deleted; MEMORY.md index updated.
+- A product-facing audit report exists at `docs/product/memory-audit-<yyyy-mm-dd>.md` enumerating starting count, classification, and durable-doc edits.
+- An audit-closing commit exists on main with subject starting `memory audit: …`.
+- Audit reports older than three cycles are deleted (ratcheting).
 
 ## When to invoke
 
@@ -28,58 +52,61 @@ fi
 echo "retro-synthesis commits since last audit: $COUNT"
 ```
 
-If `COUNT >= 5`, run the audit. Otherwise no-op.
-
-The "synthesis" grep matches pipeline-run retrospective synthesis commits whose subject follows the convention `Run <label> synthesis — ...`. The audit-closing commit uses the subject prefix `memory audit: ...` so the next count cycle can find it.
-
-## Who runs it
-
-The role that owns memory curation. In the default team topology, that is Product (Product already owns retro synthesis and the durable-documentation layer). In a team topology without a Product role, the equivalent role — the one that edits CLAUDE.md and memory files — runs the audit.
+If `COUNT >= 5`, run the audit. Otherwise no-op. The `synthesis` grep matches retrospective synthesis commits whose subject follows `Run <label> synthesis — ...`.
 
 ## The three-criterion promotion rubric
 
 A memory entry is a promotion candidate only if all three conditions hold:
 
-1. **Validated across ≥3 pipeline runs.** A single-run observation is provisional; three runs establish that the rule is real and the failure mode recurs. Two-run entries stay in memory pending validation or refutation.
-2. **Operator-agnostic.** The rule applies to any team running this pipeline topology, not just to this operator or this specific deployment. Test: would another operator running the same team template benefit from this rule? If yes, it's team-generic. If no, it's operator-specific and stays in memory.
+1. **Validated across ≥3 pipeline runs.** A single-run observation is provisional; three runs establish the rule is real and the failure mode recurs. Two-run entries stay in memory pending validation or refutation.
+2. **Operator-agnostic.** The rule applies to any team running this pipeline topology, not just to this operator or deployment. Test: would another operator running the same team template benefit from this rule? If yes, team-generic. If no, operator-specific, stays in memory.
 3. **Describes a rule.** The entry is normative ("do X", "don't Y", "when X, then Y") not descriptive ("the current state is X" / "this commit fixed Y"). Descriptive entries are project state and belong in `project_*` memory regardless of how broadly applicable they might feel.
 
 All three are required. Borderline entries stay in memory until the next audit cycle, when more data may resolve the ambiguity.
 
 ## Classification outcomes
 
-Every entry falls into exactly one of four buckets:
-
-- **(a) Already promoted — retire.** The rule exists verbatim or near-verbatim in CLAUDE.md, a workflow skill, or another durable artifact. Retire the memory entry (delete the file and remove the `MEMORY.md` index line).
-- **(b) Needs promotion — draft and retire.** All three criteria hold and no durable home exists yet. Draft the promotion (new CLAUDE.md bullet, new skill section, or new checklist item) in a single commit; retire the memory entry in the same commit or the next one.
-- **(c) Keep in memory.** At least one criterion fails (operator-specific, single-run, descriptive). Update the memory entry if needed; leave it in place.
-- **(d) Retire unconditionally.** The entry is stale (documents a bug since fixed, references a subsystem no longer in the codebase) and no longer useful. Delete with no promotion.
+| Bucket | Meaning | Action |
+|---|---|---|
+| **(a) Already promoted** | Rule exists verbatim or near-verbatim in CLAUDE.md, a workflow skill, or another durable artifact | Retire the memory entry (delete file + remove MEMORY.md index line) |
+| **(b) Needs promotion** | All three criteria hold and no durable home exists yet | Draft promotion (new bullet / section / checklist item); retire entry in same or next commit |
+| **(c) Keep in memory** | At least one criterion fails (operator-specific, single-run, descriptive) | Update entry if needed; leave in place |
+| **(d) Retire unconditionally** | Stale (documents a fixed bug, references a defunct subsystem) | Delete with no promotion |
 
-## Execution recipe
+## Procedure
 
-1. **Resolve the count.** Run the git-log snippet above; confirm `COUNT >= 5`. If not, no-op and return.
+1. **Resolve the count.** Run the git-log snippet under "When to invoke"; confirm `COUNT >= 5`. If not, no-op and return.
 2. **Enumerate entries.** Read `MEMORY.md`. For each file it links to, open the memory file and note its frontmatter `type` (user / feedback / project / reference).
 3. **Classify.** For each entry, apply the three-criterion rubric and assign to (a), (b), (c), or (d).
-4. **Confirm promotion targets.** For each (b) entry, identify the most-specific durable home: a workflow skill if the rule is role-specific; CLAUDE.md if the rule spans roles; a checklist item in spec-checklist if the rule is spec-authoring discipline; and so on. If no natural home exists, demote to (c) pending a future refactor that creates one.
-5. **Draft promotions and retirements.** Edit durable artifacts to add the promoted text. Delete the corresponding memory files. Update `MEMORY.md` to remove the retired index lines.
-6. **Write the audit report.** Create a product-facing doc under `docs/product/` named `memory-audit-<yyyy-mm-dd>.md` that enumerates the starting count, the classification of each entry, and the set of durable-doc edits made. The report is useful for future audits (diff vs prior report) and for operator review.
-7. **Commit.** The commit message subject line MUST start with `memory audit:` so the next count cycle can anchor on it. Example: `memory audit: 2026-04-17 — retired 45 already-promoted, promoted 40, left 24 operator-specific`.
+4. **Confirm promotion targets.** For each (b) entry, identify the most-specific durable home:
+   - Workflow skill for role-specific rules
+   - CLAUDE.md for cross-role rules
+   - `spec-checklist` for spec-authoring discipline
+   - A new doc or skill if the rule spans an existing-doc boundary
+   If no natural home exists, demote to (c) pending a future refactor that creates one.
+5. **Draft promotions and retirements.** Edit durable artifacts to add promoted text. Delete corresponding memory files. Update `MEMORY.md` to remove retired index lines.
+6. **Write the audit report.** Create `docs/product/memory-audit-<yyyy-mm-dd>.md` enumerating starting count, classification of each entry, and durable-doc edits made.
+7. **Commit.** Subject line MUST start with `memory audit:`. Example: `memory audit: 2026-04-17 — retired 45 already-promoted, promoted 40, left 24 operator-specific`.
+8. **Delete audit reports older than three cycles** (ratcheting — see Practice).
 
-## What NOT to promote
+## Practice
 
-- **Operator identity, deployment specifics, or local-environment constraints.** These are operator-specific by definition.
-- **Historical session records.** `project_session_*` files are provenance, not rules.
-- **Stale bug-fix memories.** If a memory documents a bug that has since been fixed, retire it with disposition (d) — don't try to promote the fix itself.
-- **Workflow-topology changes.** Retros (and this audit's promotions) may change *how* individual roles perform their work but must NOT change the pipeline topology (who talks to whom). Topology changes go back as "performance/communication changes only."
+**What NOT to promote:**
+- **Operator identity, deployment specifics, local-environment constraints.** Operator-specific by definition.
+- **Historical session records** (`project_session_*`). Provenance, not rules.
+- **Stale bug-fix memories.** Documents a fixed bug → (d), no promotion.
+- **Workflow-topology changes.** Edge-adding or phase-crossing proposals violate topology invariance; reject at promotion time regardless of how team-generic they feel.
 
-## Audit-report ratcheting
+**Audit-report ratcheting.** Keep the most recent audit report. Delete reports older than three cycles — they're no longer actionable and the durable-doc state has moved on. The most-recent report provides the diff baseline for the next audit; older reports clutter `docs/product/`.
 
-Keep the most recent audit report. Delete audit reports older than three cycles — they're no longer actionable and the durable-doc state has moved on. The most-recent report provides the diff baseline for the next audit; older reports clutter `docs/product/` without adding value.
+**What success looks like.** A steady-state where (a) entries trend toward zero over several cycles — means retro synthesis is promoting candidates at the right cadence. (b) entries in the 0–5 range per cycle is healthy. (c) entries being the bulk of the memory file count is the goal — operator-specific state is what memory is for.
 
-## What success looks like
+If (a) entries are persistently large across cycles, the retro-synthesis step is under-promoting during normal synthesis and the audit is compensating. Flag to the retro-synthesis role via `message_type="question"`.
 
-A steady-state audit where the number of (a) entries (already-promoted-redundant) trends toward zero over several cycles. If (a) entries are persistently large, the retro-synthesis step is under-promoting during normal synthesis and the audit is compensating — flag this to the team via the next retro synthesis or a question message to the role that owns retro synthesis.
+## Defined terms
 
-A steady-state audit where (b) entries are in the 0–5 range per cycle. Larger (b) sets suggest the retro-synthesis step is skipping promotion candidates entirely — same diagnosis and same fix.
+- **Retro synthesis commit** — a git commit whose subject follows `Run <label> synthesis — ...`. Counted by the cadence gate.
+- **Audit-closing commit** — a git commit whose subject starts `memory audit:`. Anchors the next cadence count.
+- **MEMORY.md** — the memory directory's index file at `~/.claude/projects/<cwd>/memory/MEMORY.md`.
+- **Durable artifact** — a file outside the memory directory whose contents persist across sessions (CLAUDE.md, workflow skills, product docs, spec-checklist items).
 
-A steady-state audit where (c) entries are the bulk of the memory file count: this is healthy. Operator-specific state is what memory is for.

package/templates/skills/merge-to-main/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: merge-to-main
+description: Merge the current branch (or a named branch) into main from a worktree. Handles the worktree constraint where main is checked out at the host repo path. Defaults to the convo repo at /workspaces/convo; pass an explicit repo path for other repos on the same filesystem (e.g. mootup-io/moot).
+argument-hint: [branch-name (default: current branch)] [repo-path (default: /workspaces/convo)]
+---
+
+# Merge to Main
+
+## Purpose
+
+Fast-forward `main` with a named branch, working around the git-worktree constraint that prevents `git checkout main` from a non-host worktree. Used by Product for non-feature commits (roadmap edits, retro synthesis, product-doc updates) and by Leader for squash-merging shipped feature branches.
+
+**Why it exists as a named skill:** the worktree constraint is non-obvious — `git checkout main` from a worktree fails with "already used by worktree," and the fix (`git -C <repo-path>`) is specific to each repo's host location. Capturing the pattern once avoids every caller rediscovering it.
+
+## Preconditions
+
+- **Role:** caller is authorized to merge. Product owns non-feature merges day-to-day; Leader owns feature squash-merges. Other roles MUST request via `message_type="git_request"` rather than invoking this skill directly.
+- **Branch is mergeable.** Branch exists, is current (rebased on main) or rebaseable without conflict, and represents work intended to land on main.
+- **Repo path is correct.** Default is `/workspaces/convo` for the convo repo; for mootup-io/moot, `/workspaces/convo/mootup-io/moot`. Wrong repo path fails at step 4 with "not a git repository."
+- **Current worktree has clean tree.** Any uncommitted changes MUST be committed or stashed before merge; the rebase in step 3 will refuse to run against a dirty tree.
+
+## Invariants
+
+- **No `git checkout main` from a worktree.** It fails loudly on the current repo but is the pattern-error this skill exists to prevent; cover every branch-switching operation with `git -C <repo-path>`.
+- **Fast-forward only.** `--ff-only` is mandatory. Non-ff merges on main create merge commits, breaking the linear-history convention the pipeline depends on. If ff fails, the fix is `git rebase main` from the worktree, then retry — not `--no-ff`.
+- **No force-push to main.** Never. This skill does not push; if a caller is about to force-push main, they're in the wrong skill.
+- **Destructive operations require an authorization trail.** If rebase produces conflicts that require judgment, resolve them explicitly and reference the conflict resolution in the commit chain — don't silently take one side over the other.
+
+## Postconditions
+
+- `main` on the host repo is advanced to the branch's tip (or merged-into-tip if the branch was on top).
+- `git -C <repo-path> log --oneline -3` shows the new main with the merged commit(s).
+- The caller's worktree may be ahead of, behind, or even with the new main — not required to be synced automatically. Callers that need to sync their worktree call `git reset --hard main` as a follow-up.
+
+## Repo path reference
+
+| Repo | Host path |
+|---|---|
+| convo (default) | `/workspaces/convo` |
+| mootup-io/moot | `/workspaces/convo/mootup-io/moot` |
+
+The repo path is the directory containing the host worktree's `.git/` (or the gitfile pointing into it). All `git -C <repo-path>` commands in Procedure substitute this path.
+
+## Procedure
+
+1. **Determine source branch and repo path:**
+   ```bash
+   git branch --show-current
+   ```
+   The current branch is the default source; pass a branch name argument to override. The repo path defaults to `/workspaces/convo`.
+
+2. **Show what will be merged:**
+   ```bash
+   git log --oneline main..<branch>
+   git diff main...<branch> --stat
+   ```
+
+3. **Rebase onto main so the merge is a fast-forward:**
+   ```bash
+   git rebase main
+   ```
+   If conflicts occur, resolve before continuing.
+
+4. **Fast-forward main from the host repo:**
+   ```bash
+   git -C <repo-path> merge <branch> --ff-only
+   ```
+
+5. **Confirm the merge:**
+   ```bash
+   git -C <repo-path> log --oneline -3
+   ```
+
+## Practice
+
+**Merging agent branches into a feature branch.** For merging agent branches (e.g., `spec/<slug>`) into a feature branch (e.g., `feat/<slug>`), the same worktree constraint applies if the target branch is checked out elsewhere. Use the same `git -C <repo-path>` pattern, targeting whichever worktree has the branch checked out, or merge locally if the target branch is not checked out in any other worktree.
+
+**`git -C <repo-path> update-ref` as an alternative to `merge --ff-only`.** When the branch is already a clean fast-forward ahead of main (confirmed via `git log main..<branch>`), `update-ref` moves main directly without the merge dance:
+```bash
+git -C <repo-path> update-ref refs/heads/main <new-tip-sha> <expected-old-sha>
+```
+The `<expected-old-sha>` guards against concurrent updates. Faster than the merge form when the branch is clean; equivalent result. Prefer this when the branch is certain-ff and the worktree constraint makes normal merge unreachable.
+
+**After merging, clean up the per-feature branch.** `git branch -D <branch>` keeps the branch list clean. Home branches (`<role>/work`, `product/work`) are kept; per-feature branches (`product/<slug>`) are deleted after merge.
+
+## Common errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `'main' is already used by worktree` | Tried `git checkout main` from a worktree | Use `git -C <repo-path>` instead |
+| `Not possible to fast-forward` | Histories diverged (duplicate commits from another worktree) | `git rebase main` first, then retry |
+| `fatal: not a git repository` on `git -C <repo-path>` | Wrong repo path, or repo not cloned there | Verify with `ls <repo-path>/.git`. For mootup-io/moot, the path is `/workspaces/convo/mootup-io/moot` |
+| `update-ref: cannot lock ref` | `<expected-old-sha>` doesn't match current main | Someone else advanced main concurrently; re-read main tip and retry |
+
+## Defined terms
+
+- **Host repo** — the checked-out working copy at the repo's root path (e.g., `/workspaces/convo` for convo). Holds `main`.
+- **Worktree** — a secondary working copy under `<repo>/.worktrees/<role>/`. Cannot check out `main` because the host repo holds it.
+- **Repo path** — the filesystem path used as `<repo-path>` in `git -C`; the host repo's root directory.
+

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

@@ -1,69 +1,216 @@
 ---
 name: product-workflow
-description: Product's strategic workflow — pipeline variants (standard vs design-first), variant triage, spec length targets, Impl pre-draft rule, pipeline kickoff composition, retrospective synthesis, topology invariance. Invoke on Product startup.
+description: Product's strategic workflow — pipeline variants (standard vs design-first), variant triage, spec length targets, Impl pre-draft rule, pipeline kickoff composition (compact Leader, feature kickoff mention list), retrospective synthesis, topology invariance principle. Invoke on Product startup.
 ---
 
 # Product Workflow
 
-Product holds strategic direction, feature scoping, design decisions, and high-bandwidth negotiations with Spec during design-first runs. Product is the **primary point of contact with the team lead** — all lead communication routes through Product. Product owns CLAUDE.md edits, memory file curation, and retro synthesis. Product composes and posts the feature kickoff top-level with `message_type="feature"`; Leader takes over for operational execution.
+## Purpose
 
-Product does NOT run the pipeline cron, does NOT post operational merge acks in feature threads, and does NOT handle mechanical merges day-to-day. Those are Leader's responsibilities.
+Codify Product's strategic + process responsibilities: feature scoping, design decisions, Pat-facing negotiations, pipeline kickoff composition, retrospective synthesis, memory curation, topology invariance enforcement. The failure class this skill prevents is **Product drifting into operational work** (running cron, posting mechanical merge acks) or **Product delegating strategic judgment** (letting Spec or Leader make scope calls that should have come from Product). The skill keeps the strategic/operational split clean.
 
-## Pipeline Variants
+**Why it exists as a named skill:** Product's work is high-bandwidth, irregular, and spans multiple phases (scoping, design review, kickoff, synthesis, memory audit, skill/CLAUDE.md curation). No single sequential procedure captures it; instead the skill is a library of role-policies and decision rubrics referenced at specific phase entries. Re-reading at phase entry (not just session start) is load-bearing because different phases of Product's work exercise different sections.
 
-**Standard pipeline (small–medium features):** Product compacts Leader → Product posts feature kickoff (`message_type="feature"`) → Leader replies in-thread with operational kickoff (compact Spec/Impl/QA, create feat branch, start cron) → Spec → Impl → QA → Leader ships in-thread → Product reads retros from the thread.
+## Preconditions
 
-**Design-first pipeline (larger features):** Product writes scope with open questions → Product posts a `message_type="question"` design review to Spec directly (high-bandwidth strategic negotiation, Product-owned) → the team lead reviews (or Spec's judgment if the lead is away) → Product locks scope → Product compacts Leader → Product posts feature kickoff → Leader replies in-thread with operational kickoff (NO second compact — Spec retains design context) → Spec → Impl → QA → Leader ships → Product reads retros.
+- **Role:** caller is Product. Other roles interact with Product via channel messages (`message_type="question"` for escalations; `message_type="feature"` read for retros; etc.); they do not invoke this skill.
+- **Pat-context continuity:** Product's session has not been compacted recently if strategic continuity matters (e.g., mid-feature negotiation with Pat). Per pipeline discipline, Product is **never** compacted by Leader — that would lose the Pat-negotiation continuity this skill depends on.
+- **Home branch:** Product's worktree is on a `product/<slug>` branch, not `main`. If a checkout / post-compact gap leaves Product on main, start a new `product/<slug>` branch before editing.
+- **Phase entry context:** the caller has identified which phase is about to run (feature kickoff, design review, retro synthesis, memory audit, scope draft, CLAUDE.md edit). Different phases exercise different sections of this skill.
 
-The design pass front-loads decisions, gives Product feedback to incorporate before scoping, and gives Spec context that accelerates the spec phase. Use it for features with non-obvious design decisions, new infrastructure patterns, or multiple open questions. **Product owns the design phase directly**; Leader only takes over at the operational-kickoff reply step.
+## Invariants
 
-## Variant triage
+- **Topology invariance.** Product's synthesis-time filter MUST reject retro carry-forwards that change the pipeline topology (who talks to whom, when, review-cycle count). Node-internal changes (spec templates, impl disciplines, QA parity plans) pass; edge-adding changes reject.
+- **Pat-facing singleton.** All Pat↔pipeline communication routes through Product. Other agents MUST NOT post directly to Pat except for status updates Pat has subscribed to; questions and design input from Spec/Impl/QA/Leader come via channel message_types that Product relays or answers.
+- **Strategic/operational split.** Product does NOT run the pipeline cron, does NOT post operational merge acks in feature threads, does NOT handle mechanical merges of feature branches. Those are Leader's. Product owns scope, design, kickoff content, synthesis, memory, CLAUDE.md/skill edits.
+- **Approval-shape discipline.** When approving a Leader-escalated amendment, Product responses are ≤2 lines. Reasoning goes in synthesis, not in the approval message. Approve-with-background reads as soft veto and produces amendment yo-yo (DS-3 incident).
+- **Continuous pipeline operation.** When a pipeline run finishes (ship + retros + synthesis + memory-audit-if-triggered), Product auto-kicks-off the next pipeline-ready item per the predicate below. Pat's cycles are reserved for scoping decisions and OQ resolution.
 
-Design-first is for scope with semantic decisions, new contracts, novel patterns, or ≥2 non-obvious open questions. Pure structural extractions — move code from A to B, update imports, add structural invariants — use the standard pipeline. Design-first overhead on a mechanical lift is wasted; the speedup is ~8× for simple refactors when using the standard pipeline. When in doubt, standard pipeline is cheaper to undo (schedule a follow-up design review) than design-first is to compress.
+## Postconditions (ongoing — role-state, not per-invocation)
 
-## Spec length scales with churn, not template inertia
+- Pipeline feature kickoffs composed by Product with scope, baseline, invariants, ship criteria, retro carryover.
+- Retro synthesis commits land on main after each ship.
+- Memory audits run every fifth synthesis per the `memory-audit` skill's cadence gate.
+- CLAUDE.md and skills carry the durable rules from retro synthesis; topology-changing proposals were rejected at synthesis filter.
+- `product/<slug>` branches are the resting state; Product's worktree never lingers on main.
 
-For mechanical-lift refactors, budget spec length ~3× the LOC of the projected code diff. Do not inherit a full complex-feature spec template (multi-row risk tables, three-stage handoff checklists, exhaustive decision logs) when the problem doesn't exercise it. Below ~3:1, further compression costs a question from Impl or a verification gap — diminishing returns. Target 3:1 as the floor, not 2:1. Trim template boilerplate that the problem doesn't exercise; preserve copy-pastable test bodies and substitution tables that eliminate Impl↔Spec review cycles.
+## Continuous pipeline operation — auto-kickoff discipline
 
-## Impl pre-draft during standby
+**Default posture (Pat-directed 2026-04-19):** when a pipeline run finishes (ship + retros + synthesis + memory-audit-if-triggered), Product immediately kicks off the next pipeline-ready item from the queue without waiting for Pat's go-ahead. Pat's cycles are reserved for scoping decisions and OQ resolution, not for clicking "start."
 
-Standing rule: while Impl is idle waiting for Spec's handoff, Impl may pre-draft an implementation sketch in working memory — blast-radius analysis, substitution candidates, import impacts. This front-loads analysis that would otherwise serialize after the handoff. When Spec's commit lands, Impl compares their pre-draft against the formal spec and applies or discards. Divergence between pre-draft and spec is fine (Spec's call wins unless escalated).
+**Pipeline-ready predicate** — auto-kickoff applies if and only if ALL hold:
 
-## Pipeline Kickoff
+1. **Scoping doc exists** on main (sub-doc with OQs, threat model, structural invariants, ratio projection).
+2. **All OQs are Pat-resolved** (or marked Spec-resolvable in-draft per the "Spec resolves product-doc silences" pattern). If any OQ is labeled "Pat to resolve" or is otherwise blocking on Pat's judgment, STOP and escalate.
+3. **Dependencies landed** — every doc the sub-run `Depends on:` is shipped on main with synthesis merged. If a dependency is pipeline-running or not yet shipped, SKIP this item and pick the next pipeline-ready one.
+4. **No new Pat-directed question pending** — check the channel for any recent Pat message that changes direction or requests hold. If Pat asked for a pause, hold; otherwise proceed.
+5. **No operator prereq** required before kickoff — e.g., `terraform apply`, `npm org provisioning`, PyPI publish. If an operator prereq is named in the scoping doc, post a `message_type="question"` to Pat noting the prereq is blocking and HOLD.
 
-**Product** composes and posts the feature kickoff top-level with `message_type="feature"`, mentioning Leader. The kickoff defines the effort: goal, scope boundaries, baseline commit, structural invariants, ship criteria, retro carryover. Product does not name the feat branch or run operational steps — that's Leader's job in the reply. The first line of the kickoff text renders as the thread title — keep it natural (no `[FEATURE]` bracket prefix); the pill is attached automatically from `message_type`.
+**Queue order** — consult the Pat-locked sequence; do not re-shuffle without explicit Pat direction. If an item is not pipeline-ready per the predicate, skip to the next item that IS ready; note the skip in a status update so Pat sees the bypass.
 
-**Product** compacts Leader before posting the kickoff (gives Leader a clean context for the run). **Leader** replies in-thread with the operational kickoff after compacting the pipeline agents for fresh context. **Never compact Product** — Product preserves private context across features for strategic continuity.
+**Kickoff still respects variant triage.** Design-first items (novel surface, ≥2 non-obvious decisions, semantic work) kick off by posting a `message_type="question"` design review to Spec; standard-pipeline items kick off directly via the feature kickoff (`message_type="feature"`). The auto-kickoff rule doesn't skip the design-first pass — it just means Product initiates it without waiting for Pat to ask.
 
-Do NOT compact Librarian — Librarian operates independently and maintains its own context across features.
+**What "pipeline finished" means** for trigger purposes: the Leader ship message landed, the three retros posted, Product's synthesis commit merged to main, and any `memory audit:` cycle that triggered has landed. Last check passes → next kickoff.
 
-**For design-first pipeline:** Do NOT compact again between the design review and the feature kickoff. Spec's design review context is valuable and should be preserved.
+**Pat can interrupt at any time.** Pat may preempt the queue with "pause," "work on X instead," "hold on this one," or any other redirect. Auto-kickoff is a default, not a lock.
 
-**Do NOT mention Librarian on feature kickoffs or ship messages.** Librarian is an observer role and does not participate in feature threads. Standard kickoff mention list: `[Spec, Implementation, QA]`. Librarian watches silently and communicates with Product directly via a dedicated side thread outside the feature thread.
+**Status-update discipline.** When kicking off the next item, include the predicate check briefly in the kickoff message or in a preceding status update ("TE-1 shipped + synthesized + memory-audit merged; next up is UI rework #75 — OQs Pat-resolved, no operator prereq, dependencies clear; initiating design-first review now"). Gives Pat visibility without requiring a response.
 
-**Kickoff content comes from Product.** Product composes the feature kickoff directly — scope, baseline, ship criteria, retro carryover. Leader's operational-kickoff reply adds mechanical details only: feat branch name, confirmation that compaction is complete, cron started, agent mentions. Leader does not invent scope. If the kickoff is ambiguous or missing context Leader needs, Leader posts a `message_type="question"` reply in the feature thread rather than guessing.
+## Pipeline variants — standard vs design-first
 
-## Retrospective
+**Standard pipeline (small-medium features):** Product compacts Leader → Product posts feature kickoff (`message_type="feature"`) → Leader replies in-thread with operational kickoff (compact Spec/Impl/QA, create feat branch, start cron) → Spec → Impl → QA → Leader ships in-thread → Product reads retros from the thread.
 
-After QA verifies and Leader confirms a feature has shipped, Spec/Impl/QA each post one short retro message in the feature thread with `message_type="retro"` (as a `reply_to` against Leader's ship message). Each agent should consider:
+**Design-first pipeline (larger features):** Product writes scope with open questions → Product posts a `message_type="question"` design review to Spec directly (this is Product work, not Leader work, because it's high-bandwidth strategic negotiation) → Pat reviews (or Spec's judgment if Pat is away) → Product locks scope → Product compacts Leader → Product posts feature kickoff (`message_type="feature"`) → Leader replies in-thread with operational kickoff (NO second compact — Spec retains design context from the design-review pass) → Spec → Impl → QA → Leader ships in-thread → Product reads retros from the thread.
 
-- What went well in the process
-- What caused friction or confusion
-- What could be improved for next time (workflow, threading, handoff format, tooling)
-- Whether any step should become a skill or be automated
+The design pass front-loads decisions, gives Product feedback to incorporate before scoping, and gives Spec context that accelerates the spec phase. Use this for features with non-obvious design decisions, new infrastructure patterns, or multiple open questions. **Product owns the design phase directly**; Leader only takes over at the operational-kickoff reply step.
 
-**Keep retros short.** Bullet points, not paragraphs. The retro's job is to produce durable signal for Product's synthesis, not to re-narrate the run. Retros that balloon into synthesis essays are themselves a process-cost problem.
+**Variant triage.** Design-first is for scope with semantic decisions, new contracts, novel patterns, or ≥2 non-obvious open questions. Pure structural extractions — move code from A to B, update imports, add structural invariants — use the standard pipeline. R6 (design-first, auth_service) took ~6h; R7 (standard pipeline, nearly identical extraction shape) took ~45m. The 8× delta was design-first overhead producing no value for a mechanical lift. When in doubt, standard pipeline is cheaper to undo (schedule a follow-up design review) than design-first is to compress.
 
-**Do NOT mention Librarian on retro-request ship messages.** Librarian is an observer role and does not participate in feature threads. They watch ship events passively and deliver as-built passes via the dedicated Librarian→Product side thread.
+## Multi-sub-run features: ship cadence by sub-run character
 
-**Topology invariance principle:** Retros may change *how individual agents perform their work* (spec templates, impl disciplines, QA parity plans, handoff message content) but must NOT change the team interaction topology (who talks to whom, when they talk, the number of review cycles per run). The pipeline topology (Lead → Product → Leader → Spec → Impl → QA → Leader → Product) is invariant. Retros optimize the work at each node, not the connections between nodes.
+When a feature is carved into multiple sub-runs (AD had AD-a/b/c; AG had AG-a/b/c), the ship + synthesis cadence depends on whether the sub-runs are **fan-out** (identical transform across disjoint files) or **differentiated** (each sub-run has a distinct shape that informs the next).
 
-**Leader ensures the retros are visible in the feature thread** (Leader posts a "retros in" ping mentioning Product once all three retros are in, so Product gets a notification). Leader does not collect-and-forward, and does not do retro synthesis — retros live in the thread, Product reads them there.
+**Fan-out sub-runs: single-ship-at-end is the default.** The whole carve merges to `feat/<slug>` through each sub-run's Impl → QA cycle, but Leader does NOT squash-to-main between sub-runs. Leader ships the full `feat/<slug>` → main as one squash commit after the final sub-run's QA PASS. Retros happen once at the cumulative ship; Product synthesizes once. Retros between sub-runs produce diminishing signal because the pattern is identical by construction — the sub-run N's retros would mostly re-assert what sub-run N−1 already established. AG validated this: 3 sub-runs, 75 routes, 1 ship, 1 retro cycle, 1 synthesis. Voluntary early retros from Spec/Impl mid-carve are fine and get folded into the cumulative synthesis, but they are not canonical retro triggers.
 
-**Product reads retros and takes action** before the next run kicks off. Actions include updating CLAUDE.md, creating/updating memory files, modifying skills, or changing agent prompts. Observations without actions mean the same feedback surfaces next retro. Actions that would change the topology are rejected on principle — they go back as "performance/communication changes only."
+**Differentiated sub-runs: per-sub-run ship + retro + synthesis.** Each sub-run ships to main independently, retros land, Product synthesizes, THEN the next sub-run kicks off. The per-sub-run synthesis gate matters because each sub-run introduces new D-decisions and new signals that inform the next sub-run's design. AD validated this: AD-a (SDK bootstrap) shipped, retros produced the lock-file / msw-cookie / NodeNext rules that AD-b (templates) then applied on first try.
 
-**Invoke `memory-audit` during synthesis.** After posting the retro-synthesis commit, invoke the `memory-audit` skill. The skill computes the count of synthesis commits since the last `memory audit:` commit and runs the audit if the count has reached five. The skill is fast (a no-op in four out of five invocations) and keeps the memory/documentation drift bounded.
+**Discriminator at carve time.** Does sub-run N's shape inform sub-run N+1's design? If yes → differentiated → per-sub-run. If no → fan-out → single-ship-at-end. Spec proposes the carve in § 5 of the first sub-run's spec; if the character isn't obvious, Leader escalates to Product at the carve point via `message_type="question"` before committing to a ship cadence.
 
-**Spike before speccing tooling:** For infrastructure or CLI-interaction features (shell scripts, devcontainer setup, agent interaction), do a quick manual spike to validate assumptions before writing a full spec. Platform code (APIs, frontends) is predictable enough for spec-first. Shell + CLI interaction is not.
+## Ratio projection bands (reference)
+
+Project the spec-to-impl-source ratio based on run shape. Bands re-recalibrated across 20+ data points; extension-vs-greenfield split restored.
+
+**Tier bands (current):**
+
+- **Backend-primary extension:** 0.5–0.7 source-only / 0.9–1.1 whole-diff. Runs that extend existing route files / store modules / hook scripts without creating new modules.
+- **Backend-primary greenfield:** 0.6–1.2 source-only / 1.2–2.3 whole-diff. Novel-surface runs (first-of-kind subsystems).
+- **Frontend-primary greenfield:** 0.9–1.1 source-only / 1.3–1.6 whole-diff (1 data point: A-1 1.01; watch).
+- **Mixed-stack + infra+backend-bridge:** single data points per shape — too sparse for a band. Hold prior ranges pending more data.
+- **Infra-primary pure-Terraform:** 0.4–0.6 source-only (B-2 precedent).
+- **Routing-config / hardening-primitive sub-band:** 0.003–0.06 source-only (DS-5, reconciler-gate) — sub-20-LOC primitives with dense test coverage.
+- **Deploy-tooling:** 0.125–0.19 source-only (DX-1).
+- **Test-infra-tuning:** 0.15–0.40 source-only (AH-f-deflake, DS-3).
+
+**Spec length scales with churn, not template inertia.** Budget spec length ~3× the LOC of the projected code diff (floor). Below 3:1, further compression costs a question from Impl or a verification gap. Trim template boilerplate that the problem doesn't exercise; preserve the copy-pastable test bodies and substitution tables that eliminate Impl↔Spec review cycles.
+
+**New-surface-area runs sit at 4:1–6:1** even when the code diff is small; spec ratio scales with grounding work, not just diff line count.
+
+**Paste-and-go runs can sit below 3:1** without quality loss — when § 7's source is fully byte-for-byte and § 4 eliminates design-first round-trip via in-draft D-decisions. Run AA landed at 2.1:1 with zero amendments.
+
+**Dep-native tentpole decisions** collapse new-surface features to mechanical-lift ratios when a single D-decision removes primary code-branch risk (dep already provides the semantic natively: boto3 `AWS_ENDPOINT_URL`, httpx connection pooling, pydantic validators, etc.).
+
+**Source-vs-test LOC split.** Source-only ratios are narrower (~1.5–2.0:1 across recent backend runs) and are the honest signal for tier projection; whole-diff varies with test-framework weight. Future retros split impl LOC into source vs test and report both.
+
+## Spike-before-speccing vs. docs-first triage
+
+Earlier rule: "spike before speccing tooling" (devcontainer/infrastructure features, shell scripts, CLI tools). **Refinement: spike when the harness or platform behavior is undocumented; skip the spike when current docs give a confident answer.**
+
+Run AA's three OQs (SessionStart on resume, BLOCK rejection format, Stop hook tool-call log access) were all answerable from current Claude Code docs in ~60 seconds via the `claude-code-guide` subagent. Spec resolved them in-draft from docs without a spike, saving 30–60 minutes. Spike remains right when:
+- The behavior depends on undocumented runtime semantics
+- The docs answer is ambiguous or version-dependent
+- The cost of being wrong is high (destructive op, hard-to-undo template change)
+
+Otherwise: docs-first, spike-only-if-needed.
+
+## Impl pre-draft during standby (canonical — node-internal)
+
+Standing rule (promoted from R8 retro). While Impl is idle waiting for Spec's SPEC-READY handoff, Impl may pre-draft an implementation sketch in working memory — blast-radius analysis, substitution candidates, import impacts. Costs ~4 min of token time during the wait; front-loads analysis that would otherwise serialize after the handoff. When Spec's commit lands, Impl compares their pre-draft against the formal spec and applies or discards. Divergence is fine (Spec's call wins unless escalated).
+
+**Pre-draft for mechanical specs capped at ~5 min** (DX-1 refinement). Grep + target-file-read + exact-line-number confirmation — no full substitution-sketch drafting for paste-and-go runs.
+
+## Pipeline kickoff composition
+
+**Product** composes and posts the feature kickoff message top-level with `message_type="feature"`, mentioning Leader. The kickoff defines: goal, scope boundaries, baseline commit, structural invariants, ship criteria, retro carryover. Product does NOT name the feat branch or run operational steps.
+
+**Product compacts Leader before posting the kickoff** (gives Leader a clean context):
+
+```bash
+.devcontainer/convo-lifecycle compact leader
+```
+
+**Leader** replies in-thread with the operational kickoff after compacting the pipeline agents for fresh context. **Never compact Product** — Product preserves private context across features for Pat-negotiation continuity.
+
+```bash
+.devcontainer/convo-lifecycle compact spec
+.devcontainer/convo-lifecycle compact implementation
+.devcontainer/convo-lifecycle compact qa
+```
+
+Do NOT use `compact-all` — it includes Product. Do NOT compact Librarian — Librarian operates independently.
+
+**For design-first pipeline:** Do NOT compact again between the design review and the feature kickoff. Spec's design review context is valuable.
+
+**Do NOT mention Librarian on feature kickoffs or ship messages.** Observer role. Standard mention list: `[Spec, Implementation, QA]`.
+
+**Kickoff content comes from Product.** Leader's operational-kickoff reply adds mechanical details only: feat branch name, compaction confirmation, cron started, agent mentions. Leader does not invent scope. If the kickoff is ambiguous or missing context Leader needs, Leader posts `message_type="question"` in the feature thread rather than guessing.
+
+## Retrospective synthesis
+
+After QA verifies and Leader confirms a feature has shipped, Spec/Impl/QA each post one short retro message in the feature thread with `message_type="retro"` (as a `reply_to` against Leader's ship message).
+
+**Keep retros short.** Bullet points, not paragraphs. Retro's job: produce durable signal for Product's synthesis. Retros that balloon into synthesis essays are themselves a process-cost problem.
+
+**Retro authors MUST NOT propose new communication edges.** Retros propose changes to spec templates, impl disciplines, QA parity plans, handoff content, grep patterns, test-infra gotchas — all node-internal. Retros MUST NOT propose "agent X should talk to agent Y during phase Z," "add a new review round-trip," or any edge-adding change. Gaps go in (a) existing-edge reshaping, or (b) role-internal discipline.
+
+**Topology invariance principle.** Retros change *how* individual agents perform work; they do NOT change the team interaction topology. The pipeline topology (Pat → Product → Leader → Spec → Impl → QA → Leader → Product) is invariant.
+
+### Synthesis-time topology-change filter
+
+When reading each retro carry-forward, run this checklist BEFORE writing the carry-forward into the synthesis doc + skill edits:
+
+1. **Does it change WHO talks to whom?** New communication edge between agents that don't canonically talk during this phase → **REJECT** with topology-invariance reasoning. Name the rejection in the synthesis doc.
+2. **Does it change WHEN they talk?** A canonical edge existing earlier/later than topology prescribes → **REJECT.** Example: Impl posting status to Product mid-Impl (Product doesn't receive Impl status per topology — Leader does).
+3. **Does it add a review cycle?** "Spec reviews Impl's work before QA" or "Product reviews spec before Spec ships" → **REJECT.**
+4. **Does it change the number of retros, retro recipients, or retro format** beyond bullet-style content? → **REJECT.**
+
+Passes all four → carry-forward is safe to codify.
+
+If a carry-forward fails any check, the synthesis doc explicitly names the rejection with topology-invariance reasoning. **Do NOT soften to "candidate" or "watch one more run."** Soft-sanctioning produced the AH-e-bootstrap-backend → AH-f QA-pre-draft topology drift — retro proposed a new QA → Spec edge; synthesis filed it as a "candidate (1 data point)"; QA agent read the soft permission as license + repeated on AH-f; Pat caught and reaffirmed invariance 2026-04-19.
+
+**Concrete application — QA does NOT pre-draft during Spec/Impl phases.** QA starts work at the spec/<slug> merge signal. QA stays silent on the feature thread during Spec drafting and Impl coding. If QA observes something concerning via channel subscription, it is filed internally and surfaced at verification time through the canonical handoff. **Impl pre-draft is canonical** (same actors + direction as the existing Spec → Impl edge); QA pre-draft is a topology violation.
+
+### Memory audit cadence
+
+**Invoke `Skill(memory-audit)` during synthesis.** After posting the retro-synthesis commit, invoke the memory-audit skill. It computes the count of synthesis commits since the last `memory audit:` commit and runs the audit if the count has reached five. Fast (no-op in 4 of 5 invocations) and keeps memory/documentation drift bounded.
+
+### Failed approaches
+
+If an approach fails, revert fully and keep the docs. The reverted spec provides negative-space constraints ("what doesn't work and why") that accelerate the redesign.
+
+## Product approval-shape discipline (post DS-3 codification)
+
+When Spec self-authorizes within their amendment scope and Leader escalates for Product approval, Product responses MUST be approval-shape only — **terse approve/reject + minimal context**. Reasoning belongs in the synthesis retro, not the merge-approval message.
+
+**Rule:** approval messages are ≤2 lines:
+
+```
+Approve amendment-N (`<sha>`). Merge.
+```
+
+OR
+
+```
+Reject amendment-N. <one-line alternative direction>.
+```
+
+**Do NOT** attach full alternative reasoning inside an "approve" — Spec reads it as a soft veto and may swing back, costing an extra amendment cycle. If Product genuinely disagrees with Spec's chosen path, reject + direct; don't approve-with-background.
+
+DS-3's R-2 yo-yo (Product approved (b) with extended (a) reasoning → Spec swung to (a) → amendment-2 → amendment-4) traces to this gap. Cost: ~30 min thrash + 4 total amendments on what could have been 1-2.
+
+Full context and reasoning go into the run synthesis retro (post-ship), where the decision is reviewable without pushing additional amendment cycles into the active run.
+
+## Home-branch discipline
+
+Product uses per-work-item `product/<slug>` branches rather than a single persistent home — each retro synthesis, memory audit, CLAUDE.md edit, or skill-patch work item gets its own branch. Between work items the Product worktree is on the most-recent `product/<slug>` branch (the branch doesn't reset). **Never linger on `main`** — if a checkout or post-compact gap leaves Product on main, start a new `product/<slug>` branch before any edit or commit. See the home-branch-discipline block in CLAUDE.md.
+
+**Squash-merge ownership nuance:** Product's merge-to-main skill is invoked for `product/<slug>` branches when appropriate (retro syntheses, memory audits, CLAUDE.md / skill edits). Leader handles feature squash-merges; Product handles product-branch fast-forwards. The home-branch rule applies regardless of which merge path is used.
+
+## Defined terms
+
+- **Pipeline-ready** — predicate for auto-kickoff (scoping doc exists; OQs Pat-resolved; dependencies landed; no Pat-pause; no operator prereq blocking).
+- **Fan-out sub-runs** — multi-sub-run carves where sub-runs apply identical transforms to disjoint files; single-ship-at-end cadence.
+- **Differentiated sub-runs** — multi-sub-run carves where sub-run N's shape informs sub-run N+1; per-sub-run ship + retro + synthesis cadence.
+- **Topology invariance** — the rule that retros may change how agents perform work but MUST NOT change who talks to whom / when / in what review shape.
+- **Approval-shape** — Product response to Leader-escalated amendment: ≤2 lines, terse approve/reject, no reasoning.
+- **Product home branch** — per-work-item `product/<slug>` branches; never `main`.
 
-**Failed approaches:** If an approach fails, revert fully and keep the docs. The reverted spec provides negative-space constraints ("what doesn't work and why") that accelerate the redesign.