Plans migration playbooks

import { Aside, Steps } from ‘@astrojs/starlight/components’;

Canonical Plans live in ScrivaDB. Repository plans/**/*.{yaml,yml,json} files are optional inert replicas (YAML default on export; JSON opt-in). These playbooks are the supported operator paths after the ScrivaDB cutover (design freeze).

`wd plan scan`, `wd plan import`, and `wd plan status` are retired: they remain only as hidden aliases and cannot affect canonical definition, lifecycle, or execution. Use `import-legacy`, `create`, and the lifecycle commands in each playbook below.

1. Fresh DB-native use

No plans/ directory required.

1. Register the project if needed (wd projects open-local .).

2. Create a Plan:

   wd plan create --name feature-x --goal "ship it" \
     --task t1:implement --task t2:review

3. Inspect and run:

   wd plan list
   wd plan show <plan-id>
   wd plan run <plan-id> --mode autopilot   # or pipeline | orchestrator | manual

4. Complete or archive when appropriate (wd plan complete / wd plan archive).

2. Importing a legacy repository

Use this once per project that still has plans/{pending,in_progress,completed,archived}/*.yaml (or flat plans/*.yaml).

1. Clone or open the repo and ensure the daemon knows the project.

2. Classify without writing:

   wd plan import-legacy --report --json

3. Import into ScrivaDB (source files left untouched):

   wd plan import-legacy

4. Verify:

   wd plan list
   wd plan show <plan-id>

5. Matching content hash on re-import is a no-op (skipped). Differing hash → conflicted with no mutation — resolve by editing the canonical Plan (wd plan update paths) or restoring from backup, not by re-scanning.

Do **not** rely on daemon startup or the retired `wd plan scan` to re-authorize Status from directories. Startup scan is retired.

3. Optionally publishing a replica PR

Publish an inert YAML (default) or JSON (--format json) projection for human review. Never required for create/run. Replicas are never execution SoT; import-legacy / scan discover YAML only.

1. Ensure the Plan revision you want is in ScrivaDB (wd plan show <id>).

2. Export onto a dedicated branch and open/reuse a PR:

   wd plan sync-to-repo <plan-id> --base <integration-or-main>
   # optional path / format:
   wd plan sync-to-repo <plan-id> --base main --path plans/pending/feature-x.yaml
   wd plan sync-to-repo <plan-id> --base main --format json

3. Review the PR. Editing the exported replica does not change listing or execution.

4. Repeating the same revision/hash for the same repo/ref/path returns the prior sync result (no duplicate PR spam).

4. Recovering from a backup

Git alone cannot rebuild execution evidence. Use a Plan backup bundle.

1. On the source:

   wd plan backup export --all -o plans-backup.json

2. Transfer the bundle to the destination (not via plans/ YAML alone).

3. On the destination:

   wd plan backup restore plans-backup.json --dry-run
   wd plan backup restore plans-backup.json --on-conflict skip
   wd plan list
   wd plan show <plan-id>
   wd plan run <plan-id> --mode manual

Full cadence and conflict policy: Plan backup and restore.

5. Resolving an export conflict

sync-to-repo refuses to overwrite a non-Warden file at the target path on the export branch.

1. Read the structured conflict from the CLI/API/MCP response (outcome=conflict / error message naming the path).
2. Choose one:
   • Different path — re-run with --path plans/pending/<other-name>.yaml (or another free path under plans/).
   • Keep foreign file — leave the canonical Plan unchanged; do not force-overwrite.
   • Replace after review — manually resolve on the export branch outside warden, or delete/move the conflicting file with an explicit operator commit, then re-run sync-to-repo.
3. Confirm the ScrivaDB Plan is intact: wd plan show <plan-id> (revision/hash unchanged by a failed sync).

Import conflicts (legacy YAML vs existing canonical hash) are separate: `import-legacy` reports `conflicted` and never clobbers. Fix the canonical record deliberately, or use backup restore with an explicit `--on-conflict` policy.

Deferred (follow-up issues)

Hub network transport (#586) remains deferred by design — see Plans concepts and the Phase 12 acceptance report in-repo (docs/specs/2026-09-30-scrivadb-canonical-plans-acceptance.md).

JSON export format (#585) is shipped as an opt-in inert replica (--format json); YAML remains the default. JSON files are never scan/import-legacy authority.