migrate-docs

/migrate-docs — adopt an old docs layout into the registry

This project's docs may predate the registry: standing plans under plans/ and experiment scratch under exp/. This command adopts them into docs/registry/ so lineage tooling (thread_tree, edges, freezes) works. The tool never guesses history — the human confirms every decision.

Steps

1. Scan. mcp__projtool__reconcile_docs (read-only, never raises) reports drift as findings. Present them grouped by kind, one line each: unregistered_experiment_dir, unregistered_thread_dir, unregistered_plan, invalid_record, broken_doc_ref, graph_violation, runs_index_corrupt. If it comes back clean and there are no plans/ or exp/ directories, the project is already migrated (or has nothing to adopt) — say so and stop.

2. Dry-run. mcp__projtool__migrate_docs_layout() (no args) returns a proposal. Show it as a table:

   • threads_to_create — proposed threads, each with its source from_plan;
   • experiments — each with suggested_thread, suggestion_reason, runs_found, and suggested_status;
   • already_registered — what's left alone. The dry-run always works — dirty plan files are checked at apply time, not here.

3. Confirm the mapping WITH THE USER. The suggested_* fields are suggestions, not decisions. Build a mapping that decides every proposed experiment — the tool refuses a partial mapping. For each <exp_slug>, the value is {"thread": <existing/proposed thread slug | thr_ id | "_scratch" | "skip">} with an optional "status" override (planned | running | finalized | abandoned). "_scratch" routes it under the built-in scratch thread; "skip" leaves it unadopted (and still counts as a decision). Walk the user through it; do not fill it in yourself.

4. Apply. mcp__projtool__migrate_docs_layout(apply=True, mapping={...}). If it refuses because plan files have uncommitted changes, it names them — commit those first (narrow git add) and re-apply. Report the summary: created threads, imported experiments (stamped imported, with no edges and an empty frozen block — the tool never reconstructs history), runs backfilled, and plan files git-mv'd into threads/<slug>/plan.md. Then run reconcile_docs again and show it comes back clean (or exactly what remains).