greprag 5.49.6 → 5.49.9

package/skill/templates/chip-leader.md

@@ -0,0 +1,188 @@
+# Chip Leader — plan a MULTI-CHIP mission before the first spawn
+
+> Loaded via `greprag load chip-leader` — usually from *within* `greprag load
+> chip-spawn` (its "Part of a multi-chip mission?" gate), the moment you realize
+> ≥2 chips aim at one objective, or you're about to spawn a 2nd chip. A single
+> chip → straight to `greprag load chip-spawn`. Two or more → STOP, pick a mode
+> below, and plan first.
+
+`chip-spawn` launches one worker correctly; **chip-leader is the commander** who
+plans the whole mission *before* any worker deploys and reconciles them *after*.
+Topology is a planning decision, not an execution afterthought — draw the map
+before mobilizing the troops.
+
+**Hard fire:** the moment you're about to spawn the **2nd chip**, stop and plan.
+Spawn-then-plan is the exact failure this prevents.
+
+## Two modes — pick ONE before planning
+
+Forks on one question: **do the chips share one objective, or are they independent?**
+
+| | **Mode A — Mission** | **Mode B — Orchestrator** |
+|---|---|---|
+| **When** | ≥2 chips at ONE objective, usually ONE repo | N independent issues, often DIFFERENT repos |
+| **Relationship** | chips have seams — shared files, data contracts, ordering | disjoint by construction — no seams |
+| **Branching** | one integration branch `feature/<slug>`; chips base off it, merge into it | each chip self-contained in its OWN repo; no integration branch |
+| **Merge** | leader reconciles all → ONE reviewed merge to master | each chip merges to ITS OWN repo's default, independently |
+| **Gate** | whole feature run end-to-end on the integration worktree | per-chip verification; no cross-chip gate |
+| **Leader's core job** | merge-reconciliation across seams | **dispatch + completion judgment** — chips report back, you adjudicate |
+
+Both modes share decompose, dispatch (via `greprag load chip-spawn`), the label
+discipline, and the single-watcher rule. They diverge on topology and the back
+half (reconcile vs. adjudicate).
+
+## Mode A — Mission
+
+### The invariant that drives everything
+
+`master` is the production trunk — `git push origin master` deploys. So:
+- **Merged = ships on the next deploy.** A flag gates *behavior*, not *startup
+  code*: schema/migration statements and import-time side effects run regardless
+  of any feature flag. "Flag-gated" ≠ "inert on master."
+- **Chips NEVER merge directly to master.** They reconcile on a feature
+  integration branch. Master only ever holds verified, deployable work.
+- One objective → **one integration branch** → **one reviewed merge to master**.
+
+### Phase 1 — Decompose
+
+Break the objective into workstreams (one per chip). For each, name:
+- **Label** — a stable letter (`A`, `B`, `C`…). It becomes the chip's title prefix
+  (`Chip A: <verb>`) and the one handle you *and* the chip use end-to-end (title,
+  report-back self-ID, merge log). Letters, not numbers — workstream IDs, not an
+  execution order.
+- **Parallel or sequential** — can it run independently, or need another's output?
+- **Seams** — every place two workstreams touch: *shared file* (both edit the same
+  module → serialize at merge), *data contract* (one produces what another consumes
+  → producer merges first), *ordering dependency* (B meaningless until A lands).
+- Disjoint workstreams (no shared file, no contract) → merge in any order.
+
+Output the plan explicitly and **confirm it with the user before dispatching.**
+
+### Phase 2 — Topology
+
+Detect the default branch first (`git -C <main> symbolic-ref refs/remotes/origin/HEAD`
+→ strip prefix; fallback `master`), then:
+
+```bash
+git -C <main> worktree add .claude/worktrees/feature-<slug> -b feature/<slug> <default>
+```
+
+Decide + write down: each chip's **base branch** = `feature/<slug>` (not master);
+each chip's **merge target** = `feature/<slug>` (never master); **merge order**
+(seam-sharers serialize, producer/base first; disjoint chips free); **test gate**
+(the `feature-<slug>` worktree is where the whole feature runs end-to-end).
+
+### Phase 3 — Dispatch
+
+Spawn each chip via `greprag load chip-spawn`, and in each brief include the four
+things the plan decided:
+1. **Its seam** — which files/contracts it shares, and what to leave clean.
+2. **Its base branch** — branch off `feature/<slug>` (adjust chip-spawn's Block 1
+   `git worktree add ... <base>`).
+3. **Its merge target** — `feature/<slug>`, never master. Chips commit to their own
+   branch + report back; the leader does the merges.
+4. **Its label** — three places (spawn title alone does NOT reach FleetView's
+   watcher registry, which is auto-generated):
+   - **Spawn title** — `Chip <Label>: <verb phrase>`.
+   - **Registry retitle (Block 1)** — give the chip a line to run right after
+     worktree setup: `greprag session retitle <its-own-8hex> "Chip <Label> — <workstream>"`.
+   - **Report-back self-ID** — open its report with its label ("Chip B — DONE: …").
+
+Arm ONE inbox watcher for all the chips' reports (never double-arm).
+
+**Spawning is a commitment.** A `spawn_task` is not a draft: launching creates a
+worktree + branch, and even a queued chip occupies its slug. Finalize the brief
+before you spawn; to change/replace a chip, **cancel the old one FIRST** (dismiss
+if queued; for a launched one, stop the session, then `git worktree remove` +
+`git branch -D`), then spawn. Same-slug collision → spawn the replacement under a
+fresh slug rather than fighting an OS file lock.
+
+### Phase 4 — Reconcile + integrate
+
+As chips report `DONE`:
+1. **Merge into `feature/<slug>` in the planned order** (`--no-ff`, from the
+   integration worktree). Seam-sharers: base first, then the dependent.
+2. **On conflict at a seam** — expected; resolve it (you mapped it in Phase 1). On
+   an *unexpected* conflict, stop and re-examine the decomposition.
+3. **Recommend closing the chip out** as soon as its commits are reconciled (or
+   even just committed + reported) — the branch survives the session; you need the
+   branch, not the live session, to merge later. Don't wait to be asked.
+4. **Run the full feature end-to-end on the integration worktree** — the gate.
+5. **One reviewed merge to master, then clean up.** Only after the gate passes:
+   `feature/<slug>` → master, then deploy. Then sweep the worktrees (the cleanup
+   skill keys on "merged into master," so it won't remove chips until then).
+
+**PRUNE AT THE MERGE (HARD RULE).** Each chip's *worktree* dies the moment its
+branch merges into its target — same breath, never batched. The *branch* is the
+safety net and lives until the master merge. Stale worktrees pile up precisely
+because cleanup was deferred.
+
+## Mode B — Orchestrator (independent fan-out, cross-repo)
+
+A list of independent issues, each self-contained in its own repo. Nothing to
+integrate — every chip lives and ships on its own. Your job is **dispatch +
+completion judgment**: each chip reports back because you hold the "done"
+criterion.
+
+### B1 — Decompose AND screen
+
+One chip per issue — but **screen each candidate first; not every issue is a
+chip.** A chip must be a self-contained coding task in a clean git repo. Drop the
+rest and say why: interactive-with-operator (needs his login/judgment), ops/comms
+(submissions, third-party coordination, email), cross-repo config writes (e.g.
+editing a skill under `~/.claude` — not a clean worktree target; do inline),
+operator-owned manual tasks. (Reporting "none of these are chips" is a correct,
+useful result.)
+
+For each survivor record: **Label** (`A`/`B`/`C`…), **Target repo** (its root,
+from `~/.greprag/projects.json` → becomes the chip's `cwd`), **Completion
+criterion** (what "done" means, in YOUR words — you'll judge against it).
+
+Output the screened plan (chips + dropped non-chips with reasons); confirm before
+dispatch.
+
+### B2 — Topology: none shared
+
+No integration branch. Each chip: **cwd** = its own repo root; **base branch** =
+that repo's own default (detect per-repo); **merge target** = that repo's default,
+or hold-for-review (default to hold so you adjudicate before anything ships).
+
+### B3 — Dispatch
+
+Spawn each via `greprag load chip-spawn` with: `cwd` set; Block 1 worktree off the
+repo's default; the label discipline; Block 2 reporting to **your** session; the
+**completion criterion embedded in the brief**. Arm ONE watcher. Re-dispatch
+discipline (cancel-before-respawn) identical to Mode A.
+
+### B4 — Adjudicate (replaces reconcile)
+
+As each chip reports `DONE`: **verify against the criterion** (read the diff, run
+it if needed — don't take "DONE" on faith); **decide per chip** (merge to its own
+repo's default + deploy, or send back with specifics); **surface close-out per
+chip** as it lands. No single end-of-mission master merge — N independent ones.
+
+## Safety rules
+
+- **Never spawn the 2nd chip without picking a mode + planning.** Mode A for one
+  shared objective; Mode B for independent issues.
+- **Mode B: screen before you spawn.** Interactive, ops/comms, cross-repo-config,
+  operator-owned tasks are NOT chips.
+- **Never spawn a chip while a stale one for the same workstream is in flight —
+  CANCEL first.** `spawn_task` is a stateful commitment.
+- **Mode A: never merge a chip branch to master.** Integration branch only.
+- **Never let "it's flag-gated" justify merging untested work to master.**
+  Migrations and startup code ignore feature flags.
+- **Confirm the decomposition with the user before dispatch.** Wrong seams =
+  painful merges.
+- **Surface close-out proactively** as each chip reconciles.
+
+## Execution depth (advanced)
+
+Orthogonal to mode: each workstream also picks a *vehicle* — bare subagent, a
+leader-direct workflow, a simple chip, or an **orchestrator chip** (a lean chip
+running an inner workflow swarm in its own worktree, for mixed-model missions
+needing isolation + a human gate). Mixed-model work cannot be a simple chip
+(`spawn_task` has no model param → chips are session-locked). Don't over-stack: a
+one-file fix gets a subagent, not a three-tier hierarchy. If you need the
+orchestrator-chip brief addendum or the recovery recipe for a chip mistakenly
+merged to master, ask the operator — those live in the chip-leader skill docs.

package/skill/templates/chip-spawn.md

@@ -2,11 +2,11 @@
 
 The `pre-spawn-check` PreToolUse hook **validates** chip prompts at the spawn boundary, but **cannot inject content** — `modifiedInput` is silently dropped by the CCD harness for MCP `spawn_task` calls (see `adr/spawn-task-hook-mode.md` 2026-05-27 entry). The agent writes Block 1 + Block 2 into the prompt itself. Validator rejects with `permissionDecision: deny` and a remediation reason if Block 1 or Block 2 markers are missing.
 
-> **Part of a multi-chip mission?** If this chip is one of ≥2 aimed at a single objective, you should already be inside a `/chip-leader` plan — your **base branch** and **merge target** (the integration branch, *never* master) come from it. If you're not, stop and run `/chip-leader` first. A lone chip targeting its own objective proceeds here directly.
+> **Part of a multi-chip mission?** If this chip is one of ≥2 aimed at a single objective, you should already be inside a chip-leader plan — your **base branch** and **merge target** (the integration branch, *never* master) come from it. If you're not, stop and run `greprag load chip-leader` first. A lone chip targeting its own objective proceeds here directly.
 
 ## What the agent provides
 
-- `title: "Chip: <verb-phrase>"` — `Chip: ` prefix enforced. **Multi-chip mission?** Use the leader-assigned label: `"Chip <Label>: <verb-phrase>"` (Label = `A`/`B`/`C`… per workstream, from `/chip-leader`) — e.g. `"Chip B: Build freshness engine"`. The validator accepts `Chip: `, `Chip A: `, `Chip 1: ` (regex `^Chip( [A-Za-z0-9]+)?: `). The label is the shared handle the leader and chip both use end-to-end (title → report-back self-ID → merge references).
+- `title: "Chip: <verb-phrase>"` — `Chip: ` prefix enforced. **Multi-chip mission?** Use the leader-assigned label: `"Chip <Label>: <verb-phrase>"` (Label = `A`/`B`/`C`… per workstream, from chip-leader) — e.g. `"Chip B: Build freshness engine"`. The validator accepts `Chip: `, `Chip A: `, `Chip 1: ` (regex `^Chip( [A-Za-z0-9]+)?: `). The label is the shared handle the leader and chip both use end-to-end (title → report-back self-ID → merge references).
 - `prompt:` — Block 1 + task body + Block 2 (templates below).
 - `cwd:` — optional, lands the chip in a different project root. Repo paths: `~/.greprag/projects.json`.
 
@@ -33,7 +33,7 @@ Your parent's session id is `<8-hex-parent>`. The `IN-FLIGHT` ping is non-negoti
 ---
 ````
 
-**Multi-chip mission (`/chip-leader`)?** The spawn title alone does NOT reach FleetView's watcher registry — that title is auto-generated by gpt-5.4-nano from your opening turn. So the leader will have you **stamp your registry title in Block 1**, right after the `cd` into the worktree:
+**Multi-chip mission (`greprag load chip-leader`)?** The spawn title alone does NOT reach FleetView's watcher registry — that title is auto-generated by gpt-5.4-nano from your opening turn. So the leader will have you **stamp your registry title in Block 1**, right after the `cd` into the worktree:
 
 ```bash
 greprag session retitle <your-own-8hex> "Chip <Label> — <workstream>"
@@ -86,4 +86,4 @@ Chips never `npm link` from the worktree — dangling symlinks silently break th
 
 ## Parent merge discipline — prune at the merge (HARD RULE)
 
-When you (the parent) merge a chip branch — via `/commit` or raw `git merge` — prune in the same breath: junction guard (`~/.claude/skills/commit/guard-junctions.sh <worktree>`), `git worktree remove .claude/worktrees/<slug>`, and `git branch -d chip/<slug>` once merged. Deferred cleanup = stale worktrees piling up (field state 2026-06-10: 3 leftovers). Multi-chip missions: worktree dies at the feature-branch merge; the branch lives until the master merge (`/chip-leader` Phase 4).
+When you (the parent) merge a chip branch — via `/commit` or raw `git merge` — prune in the same breath: junction guard (`~/.claude/skills/commit/guard-junctions.sh <worktree>`), `git worktree remove .claude/worktrees/<slug>`, and `git branch -d chip/<slug>` once merged. Deferred cleanup = stale worktrees piling up (field state 2026-06-10: 3 leftovers). Multi-chip missions: worktree dies at the feature-branch merge; the branch lives until the master merge (chip-leader Phase 4).