B-NA63-capture-m-0003-orchestration-lessons-as-durable-guidance
Status: closed/abandoned
Operational lessons from executing M-0003 (~24 PRs, ~30 parallel implementation runs, 2026-06-05/06). Each bit more than once before a countermeasure stuck. Triage decides the durable home per item — standard, convention doc, project-check, or task.
| # | Lesson | Candidate home |
|---|---|---|
| 1 | Shared-snapshot fixtures (CLI help goldens, choice lists) collide across parallel PRs: each branch re-snapshots knowing only its own change, so the second merge lands main red — or worse, merges textually clean but semantically wrong (one missing-import collision crashed every CLI invocation). Working countermeasure: serialize the PRs into a stack and regenerate fixtures from actual output at each level; regenerate-from-actual always beats hand-merging fixture content. | convention (PR workflow) + possible check: post-merge fixture regen drift |
| 2 | Migration/codemod contracts must enumerate every invocation-path class up front. M-0003’s contract counted scripts/ and validators/ callers; the third class (skills/<skill>/<helper>.ts) slipped through two completed tasks and needed a late member (T-HHR4-retire-skill-forwarders). Also: substring greps miss join()-constructed paths — 33 hidden references surfaced only via test failures. | standard (migration-task template section: “invocation-class inventory”) |
| 3 | Never pipe a gating command: git commit … | tail reports the pipe’s exit, swallowing pre-commit hook aborts — work strands as staged-but-uncommitted while the chain continues green. Assert the commit landed (git log -1) in any automation. | convention (already adjacent to the pipe-tail rule in plugin/skills/CLAUDE.md — extend it to git gating commands) |
| 4 | Automation shells don’t keep cwd across steps, and the default can silently become a linked worktree: multi-step git work must chain in one invocation or use git -C <abs> everywhere, and assert the branch before committing anything “on main”. Several near-miss commits landed on the wrong branch this way. | convention (orchestration/runbook) |
| 5 | Interrupted-run salvage: a stopped implementation run’s worktree usually holds complete staged work — a continuation pinned to the SAME worktree (audit staged state → finish → PR) preserves it; restarting from scratch wastes the work. | convention (orchestration/runbook) |
Closed 2026-08-16: superseded by D-VSLI-distributed-work-runner-architecture. Every lesson
here is about driving /sdlc:orchestrate and /sdlc:task-work by hand; both retire at cutover
and their sequencing becomes engine dispatch.