# Update Loop Migrate generated loop contracts to dirtyloops v2 without recreating the accepted plan or rewriting history. ## 1. Discover Without Mutation Identify the loop doc root, Beads epic, stream name/slug, and accepted plan source. Inspect Beads and the generated tree before changing either. Run the bundled helper first in dry-run mode: ```sh node /scripts/migrate-v2.mjs \ --doc-root docs/implementation/ \ --epic \ --plan-source \ --coordinator-id \ --authored-path CONTEXT.md \ --authored-path adr/ADR-0001.md \ --dry-run ``` The helper classifies generated surfaces, legacy prompts, protected authored/history files, inferred context, planned actions, blockers, and execution readiness. Readiness is report-only during update: preserve authored files byte-for-byte and surface `needs-clarification` or `requires-reslice` for the next run instead of rewriting them. Do not apply when the migration report itself is blocked. Roadmaps, numbered phase docs, turn docs, and storyboards are protected by convention. Classify any other authored support file with one exact, repeatable `--authored-path ` argument. The helper requires each declared path to be an existing regular file, rejects generated-contract overlaps, case or symlink aliases, and path escapes, includes it in before/after hashes, and continues to block every undeclared ambiguous path. Use the same authored-path arguments for dry-run, apply, and idempotency validation. The dry-run also assembles the complete desired generated contract. Missing current schemas, stale run prompts, incomplete bindings, and ambiguous generated/authored paths appear before mutation. Completion criterion: the migration inputs are concrete and the dry-run has no blocker. ## 2. Protect Authored State The migration must preserve byte-for-byte: - roadmap and authored phase docs - every phase turn doc - storyboards - code and repository history - branches, PRs, Beads issue status, and dependencies It may normalize only the execution-policy line in `loop-state.md`; the original is archived first. If a phase or turn doc contains legacy orchestration policy, stop for manual classification. It may be an authored decision rather than generated sediment. For a loop whose generated IMPLEMENT and run prompt already declare dirtyloops v2, preserve legacy vocabulary in protected phase and turn history. Generated version markers classify the loop; historical wording does not reclassify it as v1 or authorize rewriting it. Completion criterion: protected-file hashes are recorded before mutation and every ambiguous file has been classified. ## 3. Apply Generated-File Migration Run the helper without `--dry-run` using the same inputs. It: - archives v1 `IMPLEMENT.md`, `loop-state.md`, run prompt, schemas, and legacy generated prompts under `.dirtyloops-migration-v1/` - writes a v2 `IMPLEMENT.md` with the preserved or inferred execution profile while preserving recognized goal, scope, decisions, phase ledger, gates, and branch/PR sections - writes one profile-aware `prompts/run-loop.md` - installs v2 execution-readiness, execution-summary, callback, runtime-activation, and runtime-generation schemas - installs the current Nicobailon RPC v1 `runtime/adapter.json` policy for Pi-bound v2 loops, or removes it from Codex-bound loops - removes archived legacy prompts and `swarm-report.schema.json` from the active execution surface - normalizes the mutable `loop-state.md` sidecar to the preserved or inferred `Execution profile` inside the transaction without hashing it into runtime generation identity - verifies protected hashes are unchanged - writes `migration-v2-report.json` - writes `runtime/activation.json` in the same transaction without adding coordinator identity to deterministic generation identity - stages and applies the complete contract through one `.dirtyloops-generation.lock`, writes `runtime/generation.json`, and compensates generated files plus Beads metadata on failure Never hand-delete ambiguous legacy files. Archive first; remove from the active surface only when the helper classifies them as generated prompts or schemas. Completion criterion: the helper reports `migrated` or `refreshed-v2`, protected hashes match, the report lists every archived and rewritten path, `runtime/generation.json` matches the active files, runtime status is `activation-required` for Pi or `activation-ready` for Codex, and no generation lock remains. ## 4. Migrate Beads Metadata Use commands supported by the installed `bd` version. Preserve epic/child ids, statuses, dependencies, descriptions, notes, and history. Replace only dirtyloops contract metadata: - set `dirtyloop_version` to `2` - set `execution_profile` to the explicit profile; migrate historical `Workflow: orchestrator-callback` to `orchestrator-callback`, otherwise default historical loops to `adaptive` - retain adaptive model, effort, helper-mission, and concurrency selection inside either ownership profile - add the strongly encouraged helper policy with a 20-mission per-stage ceiling and runtime-bounded active concurrency - add run-time orchestration-brief and model/effort/delegation choice flags - preserve user constraints for model, effort, cost, concurrency, review, branches, and PRs - replace fixed workflow, actor-default, selector, and swarm fields - retain callback safety as `runtime-when-used` for adaptive or required-per-stage-owner for orchestrator-callback Do not replace an explicit user constraint merely because it resembles a v1 default. When origin is ambiguous, report it and stop rather than guessing. Completion criterion: Beads retains the same plan graph and lifecycle state while advertising the v2 contract. ## 5. Validate Idempotency Run the helper a second time with the same arguments. It must return `already-v2` with no actions. Then verify: - active generated files contain no v1 workflow, fixed reasoning, selector-gate, mandatory-count, or `swarm_summary` policy - archived v1 material remains available - phase, roadmap, turn-doc, and storyboard hashes remain unchanged - Beads and `IMPLEMENT.md` agree on version and execution profile - JSON schemas and generated links are valid - Pi-bound loops have the current generated adapter policy and Codex-bound loops have none Refresh `.beads/issues.jsonl` when the repository tracks it. Completion criterion: file migration is idempotent, Beads and docs agree, authored/history content is preserved, and the final response links `migration-v2-report.json` plus any manual follow-up.