sw-migrate · diff
git:20261004.f53eeae to git:20261005.f6452e3
36 added, 25 removed. Audit A to A.
---
name: sw-migrate
description: Use when the user wants to convert an existing docs folder, task index, markdown task tables, backlog or changelog into a Superwiki vault, or invokes sw-migrate or sw:migrate.
---
# sw-migrate
- Converts a project that tracks work in markdown tables into a Superwiki vault: one file per task, wikilinks, an append-only log. A script does the bulk conversion from a mapping you write; you only read samples, never the whole index.
+ Converts a project that tracks work in markdown tables into a Superwiki vault: one file per task, wikilinks, an append-only log. A script inspects the existing files and does the conversion from a mapping you write. You never read the index yourself; it can be hundreds of kilobytes.
Run everything from the project root. `<skill-dir>` is this skill's directory; `<init-dir>` is the sw-init skill's directory (a sibling folder).
## Preconditions
Stop and tell the user if any of these fails; do not work around them.
- The project is a git repository, and `git status --porcelain -- docs AGENTS.md CLAUDE.md` is empty: the files this skill rewrites have no uncommitted changes. Uncommitted changes elsewhere do not block; mention them in the report so the user does not mistake them for the migration's.
- `docs/.sw/config.json` does not exist (already a vault). Empty folders left by an earlier, undone attempt are not a vault; ignore them.
- Node 18 or newer.
## Steps
- 1. **Branch**: `git switch -c sw-migrate`. All changes stay on this branch. Never merge, push or delete the branch yourself.
- 2. **Sample, do not read.** The index can be hundreds of kilobytes.
- - `ls docs docs/*/ | head -60` for the layout.
- - `grep -n '^|' docs/<index> | awk 'length > 0' | cut -c1-200 | head -40` for table headers and a few rows.
- - `grep -n '^## ' docs/<detail file> | head` and about 30 lines of one section, if tasks have detail files.
- - The status values in use: `grep -o '| *[A-Za-z ✅]* *|' ... | sort | uniq -c` on the status column, or read ten rows.
- 3. **Write the mapping** to a temporary file outside the repo. `node <skill-dir>/scripts/migrate.mjs --help` prints the format. Decide:
- - which columns are id, title, status, dependencies, milestone, order, dates;
- - every status value → `todo`, `in-progress`, `done` or `cancelled`;
+ 1. **Branch.** The conversion belongs on its own branch. If the project lets you run git, `git switch -c sw-migrate`; if it does not, or you are already on a branch the user made for this, ask the user to confirm the branch and stay on it. Never merge, push or delete a branch yourself.
+ 2. **Inspect**: `node <skill-dir>/scripts/migrate.mjs --inspect`. It prints, for every file that lists tasks: the tables with their line, row count and columns, the values of status-like columns with their counts, and how many per-task headings a file has. It also warns when `docs/wiki/`, `docs/tasks/` or `docs/plans/` already exist. This output is all you need for the mapping; do not open the files.
+ 3. **Write the mapping** to a temporary file outside the repo. `node <skill-dir>/scripts/migrate.mjs --help` prints the format. Decide, from the inspect output:
+ - the index file, and which columns are id, title, status, dependencies, milestone, order and dates;
+ - every status value → `todo`, `in-progress`, `done` or `cancelled`. Write the value as inspect shows it; decoration such as a check mark is already stripped;
- the marker for soft dependencies, if the project has them;
- - which other columns to keep as body sections (sources, notes);
+ - other columns worth keeping: as frontmatter (`fields`, for short values such as a review class) or as a body section (`sections`, for prose such as sources and notes);
- where per-task detail sections live and their heading prefix;
- - the changelog file and its columns, if any.
- 4. **Dry run**: `node <skill-dir>/scripts/migrate.mjs --mapping <file> --dry-run`.
- 5. **Show the user the mapping and the dry-run report, and wait for approval.** State the task counts per status next to the project's own numbers (its summary table, or a `grep -c`). If they differ, find out why before going on. Fix every line under `problems`.
- 6. **Convert**: the same command without `--dry-run`, then the `init.mjs` command the report prints (replace the area names with real ones), then `node docs/.sw/sw.mjs status` and `node docs/.sw/sw.mjs lint`.
- 7. **Verify**: `status` totals equal the dry-run counts and the project's own numbers; `lint` has 0 errors. Lint errors here are real inconsistencies in the source (a task started before its dependency finished, a dependency cycle). Report them; do not edit task files to make them pass.
+ - the table that is the changelog, if any. It may be in the index file itself;
+ - `archiveAlso`: anything in `docs/wiki/`, `docs/tasks/` or `docs/plans/` that the mapping does not consume. Superwiki owns those folders.
+ 4. **Dry run**: `node <skill-dir>/scripts/migrate.mjs --mapping <file> --dry-run`. The report has two parts:
+ - `PROBLEMS`: each one must be fixed, in the mapping or in the files, and the dry run repeated until it says `no problems`. An unknown status is a question for the user, not a guess.
+ - "For information": files whose links were rewritten, detail sections without a row, links that now point into the archive. Nothing to fix; pass the counts on.
+ 5. **Show the user the mapping and the dry-run report, and wait for approval.** Put the task counts per status next to the project's own numbers (inspect's status counts, or the project's summary table). If they differ, find out why before going on.
+ 6. **Convert**: the same command without `--dry-run`, then the `init.mjs` command the report prints, with real area names in place of the repeated ids, then `node docs/.sw/sw.mjs status` and `node docs/.sw/sw.mjs lint`.
+ 7. **Verify.** `status` shows `ready` and `blocked` where the report said `todo`: their sum must equal the todo count, and the other counts must match as they are. `lint` must have 0 errors. An error here is a real inconsistency in the source (a task started before its dependency finished, a dependency cycle): report it; do not edit task files to make it pass.
8. **Report** what moved where, the counts, the lint result, and what is left for a human decision (next section). Commit only if the user asks.
- ## What the script does not do
+ ## What the conversion does
+ So that you can tell the user without looking:
+
+ - every row of the task tables becomes `docs/tasks/<ID>.md`, with its detail section and the kept columns as the body;
+ - the changelog becomes `docs/log.md`, oldest entry first;
+ - the index, the detail files, the changelog and everything in `archiveAlso` move to `docs/legacy/`, keeping their layout;
+ - links to tasks become wikilinks everywhere under `docs/`, so other documents are edited too; the report lists them;
+ - `init.mjs` then adds `docs/index.md`, the viewer, the CLI and the Superwiki block in `AGENTS.md`.
+
+ ## What it leaves for the user
+
Tell the user about each of these; act only on what they choose.
| Left over | Where it is | Options |
- |---|---|---|
- | Rules and conventions written in the old index | `docs/legacy/` | most are replaced by the Superwiki block in `AGENTS.md`; project-specific ones go to `AGENTS.md` outside the Superwiki block |
+ | --- | --- | --- |
+ | Rules and conventions written in the old index | `docs/legacy/` | most are replaced by the Superwiki block in `AGENTS.md`; project-specific ones go to `AGENTS.md` outside that block |
| Milestones, glossaries, decision records in the old index | `docs/legacy/` | turn into `docs/wiki/` pages with `type:` and `summary:`, and list them in `index.md` |
- | Research, specs, decisions in other folders | unchanged, outside the vault | leave, or move into `raw/` (sources) or `wiki/` (maintained pages) |
- | Plans written by other tools | unchanged | leave, or move to `docs/plans/<ID>-plan.md` when a plan belongs to exactly one task |
- | The old viewer or scripts that parse the old index | unchanged | delete once `docs/viewer.html` shows the same numbers |
- | Instructions in `AGENTS.md` / `CLAUDE.md` that describe the old index | unchanged | rewrite to point at the Superwiki rules; show the diff first |
+ | Research, specs, decisions in other folders | in place, outside the vault | leave, or move into `raw/` (sources) or `wiki/` (maintained pages) |
+ | Plans written by other tools | in place, or in the archive if they were under `docs/plans/` | leave, or turn one into `docs/plans/<ID>-plan.md` when it belongs to exactly one task |
+ | The old viewer or scripts that parse the old index | in place | delete once `docs/viewer.html` shows the same numbers |
+ | Instructions in `AGENTS.md` / `CLAUDE.md`, and links in files outside `docs/`, that point at the old index | in place | rewrite to point at the Superwiki rules and the new task files; show the diff first |
+ | Task files that carry a long history (plan, review record, daily notes in one section) | `docs/tasks/` | leave; new tasks keep the plan in `docs/plans/` and history in the log |
`docs/legacy/` is an archive, not part of the vault. Delete it only when the user says so.
## Common mistakes
- - Reading the whole index to "understand it first". Samples are enough; the dry run tells you what did not parse.
+ - Opening the index or the detail files to "understand them first". Inspect and the dry run tell you what is there and what did not parse.
- Mapping a status the script reported as unknown to `todo` without asking. Ask what it means.
+ - Leaving a line under `PROBLEMS` and converting anyway.
- Fixing lint errors by changing statuses. The old data was inconsistent; the user decides which side is right.
- - Hand-editing hundreds of links. If the script missed a link shape, fix the mapping or report it.
+ - Hand-editing links. If the script missed a link shape, report it.