🐛 Keep parallel task groups from clobbering shared progress files

lead-dev-os/skills/step3-implement-tasks/SKILL.md

@@ -35,7 +35,7 @@ Shared procedures used by more than one step:
 - **Executor subagents never commit** — the orchestrator commits after verifying each group's work. When groups ran in parallel, stage each group's files separately so each group still gets its own atomic commit.
 - **Never delete tests, weaken assertions, skip migrations, or use `--no-verify`** to get to green — in your own work or by accepting it from a subagent. Surface the failure instead.
 - **Bounded retries everywhere.** Test-failure fixes: 2 attempts. Verification fix cycles: 2 rounds. After the limit, stop and report — the user would rather debug a stuck group with you than inherit silently disabled tests.
-- **Check off tasks in `tasks.md` as each completes**, not in a batch at the end. This protects progress if the session is interrupted.
+- **Check off tasks in `tasks.md` as each completes**, not in a batch at the end. This protects progress if the session is interrupted. Exception: executors running in a parallel wave never write `tasks.md` (or `agents-context/`) — they report completions via `plans/group-N-updates.md` and the orchestrator checks the boxes at commit time, so concurrent groups can't clobber each other's bookkeeping.
 
 ## Error handling
 

lead-dev-os/skills/step3-implement-tasks/shared/verification-agents.md

@@ -32,7 +32,9 @@ standards:
 - Quality — dead code, leftover debug output, TODO stubs presented as done,
   swallowed errors?
 - Context updates — were the "Update after completing" concept files
-  actually updated, and agents-context/README.md kept in sync?
+  actually updated and agents-context/README.md kept in sync? (If this
+  group ran in a parallel wave, the updates are proposed in
+  <spec-path>/plans/group-<N>-updates.md instead — check that file.)
 
 Do not report style nitpicks that no loaded standards file backs.
 

lead-dev-os/skills/step3-implement-tasks/steps/execute-orchestrated.md

@@ -6,15 +6,15 @@ The main conversation acts as an orchestrator: each group is executed by a fresh
 
 Work through the approved execution schedule wave by wave:
 
-1. **Parallel dispatch — one executor subagent per group in the current wave**, all in a single tool-call batch (`subagent_type: "general-purpose"`), using the prompt template below. Each executor starts with a fresh context and reads everything it needs from disk — never assume it inherits knowledge from this conversation. Dispatch a wave only when every group it depends on has been committed. If anything since planning has cast doubt on a wave's independence (a plan amended mid-run, drift reported by an earlier executor), re-check the two wave conditions — no dependency, disjoint file sets — and serialize when in doubt.
+1. **Parallel dispatch — one executor subagent per group in the current wave**, all in a single tool-call batch (`subagent_type: "general-purpose"`), using the prompt template below. When the wave holds 2+ groups, append the **parallel-wave addendum** (below the prompt template) to each executor's prompt — the plans' "File operations" lists are disjoint, but `tasks.md` and `agents-context/` are shared by every group, so concurrent executors must not write them. Each executor starts with a fresh context and reads everything it needs from disk — never assume it inherits knowledge from this conversation. Dispatch a wave only when every group it depends on has been committed. If anything since planning has cast doubt on a wave's independence (a plan amended mid-run, drift reported by an earlier executor), re-check the two wave conditions — no dependency, disjoint file sets — and serialize when in doubt.
 
 2. **Verify — trust but verify.** When an executor returns, run the group's verification command from `plans/group-<N>.md` yourself. Do not take the executor's report at face value.
 
 3. **Dispatch the verification pair** — implementation-reviewer and test-verifier in parallel, per [../shared/verification-agents.md](../shared/verification-agents.md). On blocking findings, run that file's bounded fix cycle (redispatch an executor scoped to the findings; max 2 rounds). Advisory findings go into the group report.
 
 4. **Review the diff** briefly yourself for scope creep, deleted tests, or weakened assertions — the reviewer checks this too, but the orchestrator owns the commit.
 
-5. **Commit.** Executors never commit — the orchestrator commits after verifying. When groups ran in parallel, stage each group's files separately (use the plan's "File operations" list) so each group still gets its own atomic commit. Commit message: what the group shipped (not how), referencing the spec folder name. Don't sweep up unrelated changes — if the user has uncommitted edits outside this group's scope, ask before staging anything.
+5. **Commit.** Executors never commit — the orchestrator commits after verifying. When groups ran in parallel: first apply the group's `plans/group-<N>-updates.md` yourself — check off its completed tasks in `tasks.md`, create/update the proposed concept files, and keep `agents-context/README.md` in sync — then stage the plan's "File operations" list **plus** those bookkeeping changes, so each group still gets its own atomic commit that includes its checkboxes and context updates. Commit message: what the group shipped (not how), referencing the spec folder name. Don't sweep up unrelated changes — if the user has uncommitted edits outside this group's scope, ask before staging anything.
 
 6. **Report and continue:**
    - Group N complete
@@ -71,3 +71,25 @@ Final report (structured):
 - Plan drift found and how the plan was amended (if any)
 - Blockers or open questions (if any)
 ```
+
+## Parallel-wave addendum
+
+Append to the executor prompt only when the wave holds 2+ groups:
+
+```
+Parallel-wave addendum — this group runs concurrently with other groups
+in the same working tree:
+
+- Do NOT modify tasks.md or any file under agents-context/ — they are
+  shared with the other groups' executors, and concurrent writes clobber
+  each other. This overrides steps 5 and 6 above.
+- Instead, write <spec-path>/plans/group-<N>-updates.md with two sections:
+  1. Completed tasks — the task numbers from Group N to check off in
+     tasks.md
+  2. Context updates — each concept file to create or update, with its
+     full proposed content, plus the agents-context/README.md entries to
+     add or refresh (index entry, Load-When Cheatsheet, cross-references)
+
+The orchestrator applies this file and commits it together with your
+group's changes.
+```

tests/test_skill_content.sh

@@ -262,6 +262,18 @@ else
   fail "step3 does not reference Execution Waves"
 fi
 
+if grep -q 'Parallel-wave addendum' "$STEP3_DIR/steps/execute-orchestrated.md" 2>/dev/null; then
+  pass "step3 parallel-wave executors get the shared-file addendum"
+else
+  fail "step3 missing parallel-wave addendum"
+fi
+
+if grep -rq 'group-<N>-updates.md' "$STEP3_DIR" 2>/dev/null; then
+  pass "step3 parallel-wave bookkeeping goes through group-N-updates.md"
+else
+  fail "step3 missing group-N-updates.md bookkeeping mechanism"
+fi
+
 # --- Full-suite backstop gate ---
 
 echo ""