npm - @friedbotstudio/create-baseline - Versions diffs - 0.1.0 - Mend

@friedbotstudio/create-baseline 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (197) hide show

package/obj/template/.claude/skills/swarm-dispatch/SKILL.md ADDED Viewed

@@ -0,0 +1,212 @@
+---
+name: swarm-dispatch
+owner: baseline
+description: Execute a swarm plan wave by wave with filesystem isolation via git worktrees. For each wave, main context decides the scenario recipe + implementation contract for every task, then spawns one swarm-worker per task in parallel. Each worker executes its recipe and reports JSON status. Worktree merge-audit verifies write-set discipline before changes land on main. Aborts remaining waves on any audit or task failure.
+argument-hint: "<slug — matches .claude/state/swarm/<slug>.json>"
+---
+# swarm-dispatch — wave runner with worktree isolation
+Invoked after `/swarm-plan` + `/approve-swarm`. The architecture is the user's principle made concrete:
+> **Main context decides. Workers execute.**
+Per task, before dispatch, you (main context) produce two recipes:
+1. The **scenario recipe** — exactly which failing tests the worker should write.
+2. The **implementation contract** — exactly which source files the worker may touch and what behavior they must implement.
+The worker's prompt contains both recipes verbatim. The worker invokes `Skill(scenario)` then `Skill(implement)` and reports JSON. It makes no design decisions.
+## Isolation modes
+Read `project.json → swarm.isolation` (default `"auto"`):
+- `"auto"` → choose `worktree` if the project root is inside a git repo (`git rev-parse --is-inside-work-tree` succeeds), else `shared`.
+- `"worktree"` → require a git repo; bail if absent.
+- `"shared"` → never use worktrees; rely on `swarm_boundary_guard` for runtime enforcement.
+**Default path is `worktree`.** The rest of this document describes that mode. The `shared` fallback is at the end.
+## Prereqs (worktree mode)
+Verify in order, abort on any failure:
+1. `.claude/state/swarm/<slug>.json` exists, has `status: "planned"`, and a non-null `waves` array.
+2. `.claude/state/swarm_approvals/<slug>.approval` exists and begins with `APPROVED`.
+3. `.claude/state/swarm/active_wave.json` does **not** already exist (stale/racing dispatch — ask before clobbering).
+4. `git rev-parse --is-inside-work-tree` succeeds at the project root.
+5. Working tree is clean (`git status --porcelain` empty) **if** `project.json → swarm.refuse_dirty_tree` is true (default).
+Record the baseline: `git rev-parse HEAD` → this SHA is the reference every worktree will be compared against at merge time.
+## Per-wave loop
+For each wave in `plan.waves`, in order:
+### 1. Decide the recipes (main context)
+For every task in the wave, produce:
+- **Scenario recipe** — list of failing tests to write. Each: `name`, `covers`, `assertion`, `fixtures`. Plus `out-of-scope` list and `test target paths`.
+- **Implementation contract** — `failing_tests` (the paths the scenario step will produce), `write_set` (from the plan), behavior contract (the spec's §Behavior excerpts for the task's ACs, plus §Design data model + contracts), project conventions (from `project.json`).
+- **Style anchors** — 1–2 existing test files and 1–2 existing source files in the touched modules so the worker matches the project's idioms.
+This is where the heavy thinking lives. Do it before dispatch — once a worker is running, the recipe cannot be changed.
+### 2. Raise the barrier
+Write `.claude/state/swarm/active_wave.json`:
+```json
+{
+  "slug": "<slug>",
+  "wave": <n>,
+  "isolation": "worktree",
+  "baseline_ref": "<HEAD SHA>",
+  "started_at": <epoch>,
+  "write_sets": [
+    {"task_id": "T-001", "files": [...]},
+    {"task_id": "T-003", "files": [...]}
+  ]
+}
+```
+In worktree mode this file is consumed by `swarm_merge.sh` (which reads `baseline_ref`). `swarm_boundary_guard` is dormant — writes happen inside worktrees that don't contain `active_wave.json`.
+### 3. Update plan status
+Set each wave task's `status` to `"running"` inside `.claude/state/swarm/<slug>.json`.
+### 4. Dispatch the wave
+One message, N parallel `Agent` calls — one per task. Each uses:
+- `subagent_type: "swarm-worker"`
+- `isolation: "worktree"`
+- `run_in_background: true`
+Worker prompt template (self-contained — the worker has no memory of this conversation):
+```
+You are executing swarm task <T-XXX> from plan <slug>, in your own isolated
+git worktree. Your write_set is the ONLY set of files you may modify.
+# Task metadata
+- task_id: <T-XXX>
+- slug: <slug>
+- ACs covered: <AC list>
+- Component: <component id>
+# Spec excerpt (behavior contract)
+<paste §Behavior sequences for this task's ACs + §Design data-model/contract
+ rows the task touches. Keep under ~200 lines.>
+# Scenario recipe — what tests to write
+out-of-scope: [<scenarios explicitly NOT to write>]
+test target paths: <test file paths>
+style anchors: <1-2 existing test files>
+scenarios:
+- name: test_when_X_then_Y
+  covers: AC-001
+  assertion: "<one plain sentence>"
+  fixtures: [<paths/factories>]
+- name: test_when_A_then_B
+  covers: AC-002
+  assertion: "..."
+  fixtures: [...]
+- ...
+# Implementation contract
+write_set (STRICT — anywhere else fails the merge audit):
+- <file 1>
+- <file 2>
+- ...
+read_set (advisory):
+- <file 1>
+- ...
+style anchors: <1-2 existing source files>
+project conventions:
+  test.cmd: <...>
+  lint.cmd: <...>
+  tdd.test_globs: <...>
+# Your job
+1. Invoke Skill(scenario) with the scenario recipe + test target paths.
+2. If all expected tests are RED, invoke Skill(implement) with the failing test
+   paths, the write_set, the behavior contract above, and the project
+   conventions.
+3. Report JSON on your final line per the swarm protocol:
+   {"task_id": "<T-XXX>", "status": "done" | "failed",
+    "files_touched": [...], "note": "<one short line>"}
+```
+The `swarm-worker` agent's body already knows the protocol. The prompt contains the recipes; the worker executes them.
+### 5. Wait
+Do not respond to the user until every task in the wave has completed. Each `Agent` return gives you the worktree path (if the worker made changes) and the JSON summary line.
+### 6. Per-task merge-audit
+For each completed task:
+```
+.claude/skills/swarm-dispatch/swarm_merge.sh \
+  .claude/state/swarm/<slug>.json \
+  <task-id> \
+  <worktree-path>
+```
+Outcomes:
+- **Exit 0**: audit passed, patch applied to main, worktree removed. Update task `status: "done"`.
+- **Exit 1**: audit failed OR `git apply` failed. Worktree preserved for inspection. Update task `status: "failed"` with a `note` naming the offending file(s).
+- **No worktree path returned** (worker made no changes): the harness auto-cleans the empty worktree. Mark task per the worker's self-reported JSON.
+### 7. Clear the barrier
+Delete `.claude/state/swarm/active_wave.json`.
+### 8. Decide the wave's fate
+- Every task `done` → advance to the next wave.
+- Any task `failed` (worker-reported OR audit failure) → set plan `status: "failed"`, stop, surface the failed task(s) with their `note` and (for audit failures) the preserved worktree path.
+## After the last wave
+1. Set plan `status: "complete"`.
+2. Run `/integrate` on the full codebase — per-wave success is necessary but not sufficient; cross-component integration must be re-verified.
+3. If `/integrate` passes: tell the user "Swarm `<slug>` complete. `<N>` tasks across `<M>` waves. Next: `/document`."
+## Shared-mode fallback
+When isolation is `"shared"`:
+- No worktrees. Each `Agent` call uses `isolation` omitted or `"none"`.
+- `active_wave.json` carries `isolation: "shared"` and the union of write_sets (no `baseline_ref`).
+- `swarm_boundary_guard` is the runtime enforcer: writes in enforced paths must be in the union of active write_sets, else denied.
+- **No per-task merge-audit** (no worktrees to diff). The guard catches drift out of the wave; cross-task bleed within the wave is a known limitation.
+- After each wave: clear `active_wave.json`, update per-task status from the worker's self-reported JSON.
+Use shared mode deliberately — it trades real safety (physical isolation) for runtime permissiveness. Worktree mode is preferred whenever git is available.
+## Failure recovery
+- Plan stays in `"failed"` state for user inspection.
+- In worktree mode, failed tasks' worktrees are preserved. The user can `cd` in, read the worker's changes, and either:
+  - Manually finish + commit to main, then mark the task done in the plan.
+  - Drop the worktree (`git worktree remove --force <path>`) and re-plan.
+- In shared mode, partial writes may have landed on main. `git status` shows them; revert or keep as appropriate.
+- **Never auto-retry a failed task.** Failures warrant human attention.
+## Constraints
+- **Recipes are decided before dispatch.** Once a worker is running, you cannot change its recipe. Plan with that in mind.
+- **`run_in_background: true` is mandatory** on every `Agent` call inside a wave. Foreground calls would serialize the wave.
+- **`isolation: "worktree"` is mandatory** in worktree mode. Without it, the merge-audit guarantee collapses.
+- **One message, N parallel `Agent` calls.** Sequential issuance defeats parallelism.
+- **`subagent_type` is always `swarm-worker`.** No per-stack variants — stack-specific skill loading is handled by the worker template's `{{SKILLS}}` token at `/init-project` time, not by spawning different agents.
+- **Never touch source files from this skill.** This orchestrator only reads and updates `.claude/state/`. File edits happen inside workers; merges happen via `swarm_merge.sh`.
+- **`active_wave.json` lingering** after abnormal termination is recoverable: delete it, inspect per-task status, re-dispatch the first incomplete wave.

package/obj/template/.claude/skills/swarm-dispatch/swarm_merge.sh ADDED Viewed

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# swarm_merge.sh — post-task merge + audit tool for worktree-isolated swarm tasks.
+#
+# Usage:  swarm_merge.sh <plan-path> <task-id> <worktree-path>
+#
+# Inputs:
+#   <plan-path>      .claude/state/swarm/<slug>.json
+#   <task-id>        e.g. "T-001" — must exist in plan.tasks[].id
+#   <worktree-path>  absolute path to the git worktree created by Agent(isolation="worktree")
+#
+# Preconditions:
+#   .claude/state/swarm/active_wave.json exists and contains `baseline_ref`
+#   (the commit SHA recorded when the wave started). The audit diffs the
+#   worktree against this baseline.
+#
+# Behaviour:
+#   1. Loads the task's write_set from the plan.
+#   2. Computes changed files: `git -C <worktree> diff <baseline> --name-only`.
+#   3. AUDIT: every changed file must be in write_set. Any violation → fail loud,
+#      preserve the worktree, exit 1.
+#   4. If clean: `git -C <worktree> diff <baseline>` | `git -C <main> apply` to
+#      land the changes on main.
+#   5. Removes the worktree on success (`git worktree remove`).
+#
+# Exit codes:
+#   0   merge applied successfully (or task made no changes)
+#   1   audit failed, apply failed, or worktree could not be read
+#   2   bad invocation / missing inputs
+set -u
+if [ "${1:-}" = "" ] || [ "${2:-}" = "" ] || [ "${3:-}" = "" ]; then
+    echo "usage: swarm_merge.sh <plan-path> <task-id> <worktree-path>" >&2
+    exit 2
+fi
+PLAN="$1"
+TASK_ID="$2"
+WT="$3"
+ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+if [ ! -f "$PLAN" ]; then
+    echo "swarm_merge: plan not found at $PLAN" >&2
+    exit 2
+fi
+if [ ! -d "$WT" ]; then
+    echo "swarm_merge: worktree not found at $WT" >&2
+    exit 2
+fi
+PLAN="$PLAN" TASK_ID="$TASK_ID" WT="$WT" ROOT="$ROOT" python3 <<'PY'
+import json, os, subprocess, sys
+plan_path = os.environ['PLAN']
+task_id   = os.environ['TASK_ID']
+wt        = os.environ['WT']
+root      = os.environ['ROOT']
+plan = json.load(open(plan_path))
+task = next((t for t in plan.get('tasks', []) if t.get('id') == task_id), None)
+if task is None:
+    print(f"swarm_merge: task {task_id} not found in plan", file=sys.stderr)
+    sys.exit(2)
+write_set = set(task.get('write_set') or [])
+if not write_set:
+    print(f"swarm_merge: task {task_id} has empty write_set — refusing to merge", file=sys.stderr)
+    sys.exit(2)
+# Read baseline from active_wave.json
+active_path = os.path.join(root, '.claude/state/swarm/active_wave.json')
+try:
+    active = json.load(open(active_path))
+except Exception as e:
+    print(f"swarm_merge: active_wave.json unreadable: {e}", file=sys.stderr)
+    sys.exit(2)
+baseline = active.get('baseline_ref')
+if not baseline:
+    print("swarm_merge: active_wave.json missing baseline_ref", file=sys.stderr)
+    sys.exit(2)
+# Change detection: diff worktree against baseline.
+r = subprocess.run(
+    ['git', '-C', wt, 'diff', baseline, '--name-only'],
+    capture_output=True
+)
+if r.returncode != 0:
+    print(f"swarm_merge: `git diff` in worktree failed: {r.stderr.decode(errors='replace')}",
+          file=sys.stderr)
+    sys.exit(1)
+changed = [f for f in r.stdout.decode().splitlines() if f.strip()]
+# If task made no changes, nothing to merge — clean up and exit OK.
+if not changed:
+    rm = subprocess.run(['git', '-C', root, 'worktree', 'remove', wt], capture_output=True)
+    if rm.returncode != 0:
+        print(f"swarm_merge: worktree removal warned: {rm.stderr.decode(errors='replace').strip()}",
+              file=sys.stderr)
+    print(f"swarm_merge: OK — task {task_id} made no changes; worktree cleaned up")
+    sys.exit(0)
+# AUDIT: every changed file must be in the declared write_set.
+violations = [f for f in changed if f not in write_set]
+if violations:
+    print(f"swarm_merge: AUDIT FAIL — task {task_id} modified files outside its declared write_set:")
+    for v in sorted(violations):
+        print(f"  + {v}")
+    print(f"Declared write_set ({len(write_set)} file(s)):")
+    for f in sorted(write_set):
+        print(f"  - {f}")
+    print(f"Worktree preserved for inspection at: {wt}")
+    print(f"Branch: swarm/{task_id} (inspect with `git log swarm/{task_id}` or `git diff {baseline}..swarm/{task_id}`)")
+    sys.exit(1)
+# Audit passed. Extract full patch and apply to main.
+r = subprocess.run(['git', '-C', wt, 'diff', baseline], capture_output=True)
+if r.returncode != 0:
+    print(f"swarm_merge: `git diff` (full patch) failed: {r.stderr.decode(errors='replace')}",
+          file=sys.stderr)
+    sys.exit(1)
+patch = r.stdout
+if not patch.strip():
+    # Diff --name-only found files but full diff is empty — bizarre, but bail safely.
+    print(f"swarm_merge: diff was empty despite changed files. Worktree preserved at {wt}",
+          file=sys.stderr)
+    sys.exit(1)
+apply_r = subprocess.run(
+    ['git', '-C', root, 'apply', '--whitespace=nowarn', '-'],
+    input=patch, capture_output=True
+)
+if apply_r.returncode != 0:
+    print(f"swarm_merge: APPLY FAIL — patch from {wt} did not apply cleanly to main:")
+    print(apply_r.stderr.decode(errors='replace').strip())
+    print(f"Worktree preserved for inspection at: {wt}")
+    sys.exit(1)
+# Remove the worktree.
+rm = subprocess.run(['git', '-C', root, 'worktree', 'remove', wt], capture_output=True)
+if rm.returncode != 0:
+    # Not fatal — warn but consider the merge successful.
+    print(f"swarm_merge: WARNING — could not remove worktree at {wt}: "
+          f"{rm.stderr.decode(errors='replace').strip()}", file=sys.stderr)
+print(f"swarm_merge: OK — task {task_id} merged ({len(changed)} file(s))")
+for f in sorted(changed):
+    print(f"  + {f}")
+PY

package/obj/template/.claude/skills/swarm-plan/SKILL.md ADDED Viewed

@@ -0,0 +1,90 @@
+---
+name: swarm-plan
+owner: baseline
+description: Decompose an approved spec into a dependency-ordered swarm plan — one task per component, each with an explicit write_set. Produces `.claude/state/swarm/<slug>.json` with tasks + waves. The wave scheduler guarantees pairwise-disjoint write_sets within each wave so parallel dispatch is provably conflict-free.
+---
+# swarm-plan — Phase 5.5: decompose for parallel execution
+Invoked after `/approve-spec` and before `/tdd` on any spec that has ≥3 independent components worth parallelizing (per `project.json → swarm.min_tasks_worth_swarming`). For smaller specs, skip swarm and go straight to `/tdd` solo.
+## Prereqs
+1. `.claude/state/spec_approvals/<slug>.approval` exists (spec is human-approved).
+2. `docs/specs/<slug>.md` exists and passes `/spec-lint`.
+3. `docs/scout/<slug>.md` exists (component → file mapping is its job).
+If any prereq is missing, stop and surface what's needed.
+## Output contract
+`.claude/state/swarm/<slug>.json`:
+```json
+{
+  "slug": "<slug>",
+  "spec": "docs/specs/<slug>.md",
+  "created_at": <epoch>,
+  "status": "planned",
+  "tasks": [
+    {
+      "id": "T-001",
+      "title": "<what the task does — one line>",
+      "component": "<component id from C4 Component diagram>",
+      "acs": ["AC-001", "AC-002"],
+      "write_set": ["src/foo/bar.py", "tests/foo/test_bar.py"],
+      "read_set": ["src/common/http.py"],
+      "depends_on": []
+    }
+  ],
+  "waves": null
+}
+```
+You produce `tasks[]`. The validator (`validate.sh`) computes `waves[]` deterministically via Kahn-with-disjointness.
+## Steps
+1. **Read upstream**: the spec, the scout report, the approval token. If an older `.claude/state/swarm/<slug>.json` exists, confirm with the user whether to overwrite (replan) or abort.
+2. **Extract inputs** from the spec:
+   - **Components**: every `Component(id, …)` in the C4 Component diagram (there may be multiple C4 Component diagrams, one per container).
+   - **ACs**: every row in the Acceptance criteria table.
+   - **Dependency edges**: every `A --> B` in the spec's dependency-graph fence.
+   - **Behavior ↔ component mapping**: for each AC, the sequence diagram it references names participants; treat each non-actor, non-external participant as a component this AC touches.
+3. **Get file mapping** from the scout report: for each component id, the files that back it. If the spec introduces greenfield components not in the scout, propose new file paths and flag them under a "new_paths" note in your plan summary — they will be accepted by the boundary guard when declared in `write_set`.
+4. **Construct tasks** — one per component (per `swarm.granularity: component`):
+   - `id`: T-001, T-002, … in stable order.
+   - `title`: one-line imperative description.
+   - `component`: the C4 component id.
+   - `acs`: every AC whose sequence names this component.
+   - `write_set`: union of (component files) + (test files covering those ACs). Every file must be explicit; no globs.
+   - `read_set`: files this task will consult but not modify. Advisory; not enforced.
+   - `depends_on`: for each component B such that this component depends on B (per the dependency graph), include the task id of the task owning B.
+5. **Merge overlapping tasks where forced**:
+   - If two tasks share any file AND have no `depends_on` relationship, either introduce a `depends_on` edge (making them sequential across waves) or merge them into one task. Merging is preferred when they're on the same component.
+6. **Validate the plan**:
+   ```
+   .claude/skills/swarm-plan/validate.sh docs/specs/<slug>.md .claude/state/swarm/<slug>.json
+   ```
+   The validator checks: required fields, depends_on references resolve, DAG is acyclic, and assigns `waves[]`. If validation fails, it prints a precise error — fix the plan and re-run.
+7. **Surface the plan** to the user as a table:
+   ```
+   Swarm plan for <slug> — <N> tasks across <M> waves
+   wave 1:
+     T-001  webhook-worker       [AC-001, AC-002]   3 files
+     T-003  backoff-policy       [AC-004]           2 files
+   wave 2:
+     T-002  webhook-retry        [AC-003]           2 files  (needs T-001)
+   ```
+8. Tell the user: "Swarm planned at `.claude/state/swarm/<slug>.json`. Review it, then run `/approve-swarm <slug>`. After approval, run `/swarm-dispatch <slug>`."
+## Constraints
+- **Never dispatch from this skill.** Planning and execution are separated by a human consent gate (`/approve-swarm`).
+- **Every file in a `write_set` must be a concrete path**, not a glob. The boundary guard does string-level membership checks.
+- **The `validate.sh` script is the source of truth for wave assignment.** Do not hand-write `waves[]`.
+- **Greenfield files are allowed** in `write_set` even if they don't exist yet — the guard checks declared ownership, not disk presence.
+- **If validation keeps failing**, the problem is usually that two tasks share a file with no dependency. Either merge or introduce a dependency edge.

package/obj/template/.claude/skills/swarm-plan/validate.sh ADDED Viewed

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+# swarm-plan validator — verifies a draft plan and assigns waves deterministically.
+#
+# Usage: validate.sh <spec-path> <plan-path>
+#
+# Reads plan-path (JSON), performs:
+#   - schema check: required fields on every task
+#   - reference check: depends_on ids all resolve to tasks in the plan
+#   - acyclicity: DAG has no cycles (Kahn's algorithm)
+#   - wave assignment: topological sort with pairwise-disjoint write_set constraint
+#
+# On success, rewrites plan-path with `waves` populated. Exit 0.
+# On failure, prints the precise violation to stderr and exits non-zero.
+set -u
+if [ "${1:-}" = "" ] || [ "${2:-}" = "" ]; then
+  echo "usage: validate.sh <spec-path> <plan-path>" >&2
+  exit 2
+fi
+SPEC="$1"
+PLAN="$2"
+if [ ! -f "$PLAN" ]; then
+  echo "validate: plan not found at $PLAN" >&2
+  exit 2
+fi
+SPEC="$SPEC" PLAN="$PLAN" python3 <<'PY'
+import json, os, sys, time
+plan_path = os.environ["PLAN"]
+try:
+    plan = json.load(open(plan_path))
+except Exception as e:
+    print(f"validate: plan is not valid JSON: {e}", file=sys.stderr)
+    sys.exit(1)
+errs = []
+# Top-level fields.
+for k in ("slug", "spec", "tasks"):
+    if k not in plan:
+        errs.append(f"missing top-level field: {k}")
+tasks = plan.get("tasks") or []
+if not isinstance(tasks, list) or not tasks:
+    errs.append("tasks[] must be a non-empty array")
+# Per-task schema.
+REQ = {"id", "title", "component", "acs", "write_set", "depends_on"}
+ids = set()
+for i, t in enumerate(tasks):
+    if not isinstance(t, dict):
+        errs.append(f"task[{i}] is not an object"); continue
+    missing = REQ - set(t.keys())
+    if missing:
+        errs.append(f"task[{i}] missing fields: {sorted(missing)}")
+        continue
+    if not isinstance(t["id"], str) or not t["id"]:
+        errs.append(f"task[{i}].id must be a non-empty string")
+    if t["id"] in ids:
+        errs.append(f"duplicate task id: {t['id']}")
+    ids.add(t["id"])
+    for listfield in ("acs", "write_set", "depends_on"):
+        v = t.get(listfield)
+        if not isinstance(v, list) or not all(isinstance(x, str) for x in v):
+            errs.append(f"task {t.get('id', '?')}.{listfield} must be a list of strings")
+    if not t["write_set"]:
+        errs.append(f"task {t['id']}.write_set is empty — every task must declare at least one file")
+if errs:
+    for e in errs: print(f"validate: {e}", file=sys.stderr)
+    sys.exit(1)
+# depends_on references resolve.
+for t in tasks:
+    for d in t["depends_on"]:
+        if d not in ids:
+            errs.append(f"task {t['id']}.depends_on references unknown id: {d}")
+        if d == t["id"]:
+            errs.append(f"task {t['id']} depends on itself")
+if errs:
+    for e in errs: print(f"validate: {e}", file=sys.stderr)
+    sys.exit(1)
+# Cycle detection (Kahn's).
+indeg = {t["id"]: 0 for t in tasks}
+outedges = {t["id"]: [] for t in tasks}
+for t in tasks:
+    for d in t["depends_on"]:
+        # edge: d -> t (t depends on d; d must finish first).
+        outedges[d].append(t["id"])
+        indeg[t["id"]] += 1
+by_id = {t["id"]: t for t in tasks}
+ready = sorted([tid for tid, deg in indeg.items() if deg == 0])
+visited = 0
+topo_order = []
+indeg_work = dict(indeg)
+ready_work = list(ready)
+while ready_work:
+    nxt = ready_work.pop(0)
+    topo_order.append(nxt)
+    visited += 1
+    for n in sorted(outedges[nxt]):
+        indeg_work[n] -= 1
+        if indeg_work[n] == 0:
+            ready_work.append(n)
+    ready_work.sort()
+if visited != len(tasks):
+    unvisited = [tid for tid in indeg if indeg_work[tid] > 0]
+    print(f"validate: dependency graph has a cycle among: {unvisited}", file=sys.stderr)
+    sys.exit(1)
+# Wave assignment: greedy topological layering with pairwise-disjoint write_set.
+# Within a wave, all tasks share no files. Tasks whose deps are done AND whose
+# write_set doesn't clash with already-chosen wave members go in; others wait.
+indeg2 = dict(indeg)
+placed = set()
+waves = []
+remaining = set(ids)
+while remaining:
+    # Candidates: remaining tasks with indeg2 == 0.
+    candidates = sorted([tid for tid in remaining if indeg2[tid] == 0])
+    if not candidates:
+        # Shouldn't happen given acyclicity, but defensive.
+        print(f"validate: internal error — no candidates but tasks remain: {remaining}", file=sys.stderr)
+        sys.exit(1)
+    wave = []
+    wave_files = set()
+    # Greedy: heaviest task first (most files), so overflow tasks get pushed with
+    # smaller write_sets and can pack into later waves.
+    candidates.sort(key=lambda tid: (-len(by_id[tid]["write_set"]), tid))
+    overflow = []
+    for tid in candidates:
+        files = set(by_id[tid]["write_set"])
+        if files & wave_files:
+            overflow.append(tid)
+        else:
+            wave.append(tid)
+            wave_files |= files
+    if not wave:
+        # Every candidate conflicts with every other — impossible unless a single
+        # candidate had an internal duplicate; but then it's still placeable alone.
+        wave = [candidates[0]]
+        overflow = candidates[1:]
+        wave_files = set(by_id[candidates[0]]["write_set"])
+    wave.sort()
+    waves.append(wave)
+    for tid in wave:
+        remaining.discard(tid)
+        # Decrement indeg of descendants AFTER the whole wave is placed so the
+        # remaining wave members don't become each other's dependents mid-wave.
+    for tid in wave:
+        for n in outedges[tid]:
+            indeg2[n] -= 1
+plan["waves"] = waves
+plan["status"] = "planned"
+plan["validated_at"] = int(time.time())
+# Write back.
+with open(plan_path, "w") as f:
+    json.dump(plan, f, indent=2)
+# Human summary to stdout.
+print(f"validate: OK — {len(tasks)} task(s) in {len(waves)} wave(s).")
+for i, wave in enumerate(waves, start=1):
+    print(f"  wave {i}:")
+    for tid in wave:
+        t = by_id[tid]
+        nfiles = len(t["write_set"])
+        acs = ",".join(t["acs"]) if t["acs"] else "-"
+        deps = ",".join(t["depends_on"]) if t["depends_on"] else "-"
+        print(f"    {tid}  {t['component']:<24} [{acs}]  {nfiles} file(s)  deps={deps}")
+PY