@seanmars/tospec 0.23.0 → 0.26.0-beta

package/dist/core/migrate.js

@@ -1,13 +1,15 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { moveDirectory, moveFile } from './archive.js';
+import { formatArchiveStamp, moveDirectory, moveFile } from './archive.js';
 import { serializeConfig } from './config-prompts.js';
-import { formatLocalDate } from '../utils/timestamp.js';
-import { buildCodeFenceMask, normalizeDocument } from './parsers/requirement-text.js';
-import { parseDeltaSpec, parseRequirementBlocks } from './parsers/requirement-blocks.js';
+import { CREATED_PATTERN, formatLocalDate, parseStampedName } from '../utils/timestamp.js';
+import { buildCodeFenceMask, normalizeDocument, stripClosingHashes } from './parsers/requirement-text.js';
+import { MarkdownParser, findSection } from './parsers/markdown-parser.js';
+import { isDeltaSectionHeader, matchRequirementHeader, parseDeltaSpec, parseRequirementBlocks, sectionHeaderKey, } from './parsers/requirement-blocks.js';
 import { emitSuccess } from '../commands/shared-output.js';
-import { isMissingPathError } from '../utils/file-system.js';
+import { isDirectoryEntry, isMissingPathError } from '../utils/file-system.js';
+import { validateNewChangeName } from '../utils/change-utils.js';
 /**
  * `tospec migrate [openspec-dir]` — one-shot conversion of an OpenSpec project
  * layout into the tospec layout, written to `<cwd>/tospec`.
@@ -17,13 +19,17 @@ import { isMissingPathError } from '../utils/file-system.js';
  *   metadata filename `.openspec.yaml` → `.tospec.yaml`.
  * - archive dir names: `YYYY-MM-DD-<name>` → `YYYYMMDD_000000-<name>`
  *   (tospec splits stamp/name on the first hyphen, so the OpenSpec date
- *   prefix would parse wrong if left as-is).
+ *   prefix would parse wrong if left as-is). A dir with no date prefix is
+ *   stamped from its `created` date, else today, and reported.
  * - main specs OpenSpec left in delta form (`## ADDED Requirements` at top
  *   level) or headerless (bare `### Requirement:` list) are rebuilt into the
  *   `# <name> Specification / ## Purpose / ## Requirements` shape tospec
  *   validates. MODIFIED blocks are kept (they carry the full updated text),
  *   REMOVED requirements are dropped and RENAMED ones are renamed, both
- *   through the project's own delta parser and both reported.
+ *   through the project's own delta parser and both reported. Any other `##`
+ *   section is kept, after the requirements, and the text above the first `##`
+ *   stays above Purpose, under the source's own title when it has one. A `#`
+ *   heading that ends Purpose stays below it, with the text under it.
  *
  * The source directory is never modified.
  */
@@ -31,10 +37,16 @@ const METADATA_SOURCE = '.openspec.yaml';
 const METADATA_TARGET = '.tospec.yaml';
 const TARGET_SCHEMA = 'sdd';
 const PURPOSE_STUB = 'TBD - migrated from OpenSpec; refine this purpose statement.';
-const DELTA_HEADER = /^## (ADDED|MODIFIED|REMOVED|RENAMED) Requirements\s*$/;
-const PURPOSE_HEADER = /^## Purpose\s*$/;
-/** Any Markdown heading — what ends the `## Purpose` body. */
-const ANY_HEADER = /^#{1,6}\s/;
+/**
+ * A `#` or `##` heading: what ends the `## Purpose` body, as it ends the
+ * section for MarkdownParser. A `###` subheading under Purpose is part of it.
+ */
+const PURPOSE_END_HEADER = /^#{1,2}\s/;
+/**
+ * A level-1 heading: the title a source spec may carry above its sections, or
+ * the heading that ends Purpose and opens text no `##` section holds.
+ */
+const TITLE_HEADER = /^#\s/;
 const ARCHIVE_DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})-(.+)$/;
 /** The `--json` null-shape; mirrors the success payload with `migrate` nulled. */
 export const MIGRATE_FAILURE_PAYLOAD = { migrate: null, root: null };
@@ -55,18 +67,39 @@ export class MigrateError extends Error {
         };
     }
 }
+/**
+ * The archive stamp of local midnight on a `YYYY-MM-DD` day, or null when the
+ * text names no real day (`2026-13-45` would roll over into another one).
+ *
+ * A `created` written as `YYYY-MM-DDTHH:mm:ss` gives its day only: every other
+ * stamp this migration assigns is a midnight, and one change stamped with its
+ * hour would sort apart from the others archived on that day.
+ */
+function dayStamp(day) {
+    const match = CREATED_PATTERN.exec(day);
+    if (!match)
+        return null;
+    const date = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+    return formatLocalDate(date) === day.slice(0, 10) ? formatArchiveStamp(date) : null;
+}
 /**
  * Converts an OpenSpec archive dir name (`YYYY-MM-DD-<name>`) to the tospec
  * stamp form (`YYYYMMDD_000000-<name>`). OpenSpec only recorded the date, so the
- * time part is zero-filled. Names without the date prefix pass through.
+ * time part is zero-filled. A name already stamped passes through.
+ *
+ * A name with no date (moved into the archive by hand) is stamped from
+ * `created`, else today, and `stamped` says so: left bare, the dashboard read
+ * `no-date-change` as stamp `no`, name `date-change`.
  */
-export function convertArchiveDirName(dirName) {
-    const match = dirName.match(ARCHIVE_DATE_PREFIX);
-    if (!match) {
-        return dirName;
-    }
-    const [, year, month, day, name] = match;
-    return `${year}${month}${day}_000000-${name}`;
+export function convertArchiveDirName(dirName, created = formatLocalDate()) {
+    if (parseStampedName(dirName))
+        return { name: dirName, stamped: false };
+    const prefixed = dirName.match(ARCHIVE_DATE_PREFIX);
+    const prefixStamp = prefixed ? dayStamp(`${prefixed[1]}-${prefixed[2]}-${prefixed[3]}`) : null;
+    if (prefixed && prefixStamp)
+        return { name: `${prefixStamp}-${prefixed[4]}`, stamped: false };
+    const stamp = dayStamp(created) ?? dayStamp(formatLocalDate());
+    return { name: `${stamp}-${dirName}`, stamped: true };
 }
 /**
  * Rebuilds a main spec that is in delta form or headerless into the shape
@@ -82,9 +115,16 @@ export function normalizeMainSpec(content, capabilityName) {
     for (let i = 0; i < lines.length; i++) {
         if (fenceMask[i])
             continue;
-        if (DELTA_HEADER.test(lines[i]))
+        // The delta parser's own test, as the rebuild below reads with it. A local
+        // regex that took only `## ADDED Requirements` copied a spec headed
+        // `## Added Requirements` unconverted when it had a Purpose, so its REMOVED
+        // entries stayed and validate then refused the spec.
+        if (isDeltaSectionHeader(lines[i]))
             hasDelta = true;
-        if (PURPOSE_HEADER.test(lines[i]))
+        // Same reading for the Purpose: a regex taking only `## Purpose` called a
+        // well-formed spec headed `## purpose` headerless and rebuilt it, with the
+        // TBD stub in place of its Purpose.
+        if (sectionHeaderKey(lines[i]) === 'purpose')
             hasPurpose = true;
     }
     if (!hasDelta && hasPurpose) {
@@ -136,16 +176,33 @@ export function normalizeMainSpec(content, capabilityName) {
         // with an empty shell.
         return null;
     }
-    const purposeText = extractPurpose(lines, fenceMask) || PURPOSE_STUB;
+    const lead = extractLead(lines, fenceMask);
+    const purpose = extractPurpose(lines, fenceMask);
+    const { requirementsPreamble, sections } = collectUnslottedSections(lines, fenceMask);
+    // The lead stays above Purpose, where it stood. When it carries its own `#`
+    // title it replaces the generated one: writing both put two titles on one
+    // spec, and dropping the source's lost a title somebody chose.
+    const head = lead.hasTitle
+        ? [lead.text]
+        : [`# ${capabilityName} Specification`, ...(lead.text ? ['', lead.text] : [])];
+    // Kept sections go after the requirements, in source order. A `##` ends the
+    // section before it, so they change neither the Purpose nor the requirements
+    // the main-spec readers see.
+    // The Purpose tail stays below Purpose, where it stood, not with the kept
+    // sections. Above `## Requirements`, every reader ends Purpose at the `#`, and
+    // `## Requirements` ends the tail.
     const rebuilt = [
-        `# ${capabilityName} Specification`,
+        ...head,
         '',
         '## Purpose',
-        purposeText,
+        purpose.text || PURPOSE_STUB,
+        ...(purpose.tail ? ['', purpose.tail] : []),
         '',
         '## Requirements',
         '',
+        ...(requirementsPreamble ? [requirementsPreamble, ''] : []),
         [...blocks.values()].join('\n\n'),
+        ...sections.flatMap((section) => ['', section]),
         '',
     ].join('\n');
     return {
@@ -157,25 +214,137 @@ export function normalizeMainSpec(content, capabilityName) {
     };
 }
 /**
- * The text under `## Purpose`, up to the next heading of any level — a
- * `### Requirement:` ends it just as a second `##` section does.
+ * The text under `## Purpose`, up to the next `#` or `##` heading or the first
+ * requirement header, whose block is already collected. Ending at a heading of
+ * any level dropped a `###` subheading and the text under it.
+ *
+ * `tail` is the `#` heading that ends Purpose and the text under it, up to the
+ * next `##` section or requirement header, where `collectUnslottedSections`
+ * starts or cuts a section. It sits inside the `## Purpose` section that
+ * collector skips, so nothing else keeps it.
  */
 function extractPurpose(lines, fenceMask) {
-    const collected = [];
-    let inPurpose = false;
+    const purpose = [];
+    const tail = [];
+    let state = 'before';
     for (let i = 0; i < lines.length; i++) {
         if (!fenceMask[i]) {
-            if (PURPOSE_HEADER.test(lines[i])) {
-                inPurpose = true;
+            if (state !== 'tail' && sectionHeaderKey(lines[i]) === 'purpose') {
+                state = 'purpose';
                 continue;
             }
-            if (inPurpose && ANY_HEADER.test(lines[i]))
+            const isRequirement = matchRequirementHeader(lines[i]) !== null;
+            if (state === 'purpose' && TITLE_HEADER.test(lines[i]))
+                state = 'tail';
+            else if (state === 'purpose' && (PURPOSE_END_HEADER.test(lines[i]) || isRequirement))
+                break;
+            else if (state === 'tail' && (sectionHeaderKey(lines[i]) !== null || isRequirement))
                 break;
         }
-        if (inPurpose)
-            collected.push(lines[i]);
+        if (state === 'purpose')
+            purpose.push(lines[i]);
+        else if (state === 'tail')
+            tail.push(lines[i]);
+    }
+    return { text: purpose.join('\n').trim(), tail: tail.join('\n').trim() };
+}
+/**
+ * The text above the first `##` section, which the rebuild otherwise dropped
+ * along with the source title. Cut at the first requirement header, as a
+ * section is: a headerless spec's blocks start there. `hasTitle` says whether
+ * it holds a `#` heading, so the caller does not write a second title over it.
+ */
+function extractLead(lines, fenceMask) {
+    const collected = [];
+    let hasTitle = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (!fenceMask[i]) {
+            if (sectionHeaderKey(lines[i]) !== null || matchRequirementHeader(lines[i]) !== null)
+                break;
+            // A `# Purpose` names a section, not the spec: taken as the title, it
+            // became the spec's H1 in place of the generated one.
+            if (TITLE_HEADER.test(lines[i]) && !isPurposeHeading(lines[i]))
+                hasTitle = true;
+        }
+        collected.push(lines[i]);
+    }
+    return { text: collected.join('\n').trim(), hasTitle };
+}
+/** A `#` heading titled Purpose, compared as `sectionHeaderKey` compares a `##` one. */
+function isPurposeHeading(line) {
+    return stripClosingHashes(line.replace(TITLE_HEADER, '')).trim().toLowerCase() === 'purpose';
+}
+/**
+ * Sections whose text, up to the first requirement header, goes under the
+ * rebuilt `## Requirements`: the source one, and the delta sections holding
+ * whole blocks. REMOVED and RENAMED hold entries the rebuild has applied, not
+ * text for the spec.
+ */
+const PREAMBLE_SECTION_KEYS = new Set([
+    'requirements',
+    'added requirements',
+    'modified requirements',
+]);
+/**
+ * The text of every `##` section the rebuild has no slot for (neither Purpose
+ * nor a delta section), which it otherwise dropped without a word. Each is cut
+ * at its first requirement header: every line from there to the next `#`
+ * heading belongs to a block already collected. The text a source
+ * `## Requirements`, ADDED or MODIFIED section holds before its first block is
+ * returned on its own, to go under the rebuilt header rather than into a
+ * second one.
+ */
+function collectUnslottedSections(lines, fenceMask) {
+    const preambles = [];
+    const sections = [];
+    // `bareTitle` marks a `#` heading. Its key is '' as a `##` titled blanks
+    // alone keys '', so the key could not tell them apart: an empty `##  ` was
+    // kept as if it were a heading.
+    let current = null;
+    let cut = false;
+    const flush = () => {
+        if (current === null || current.key === 'purpose')
+            return;
+        // An empty `##` section is dropped, but a bare `#` heading is the author's
+        // text in its own right: the requirement after it is in a block already, so
+        // dropping the chunk dropped the heading without a word.
+        if (!current.bareTitle && !current.body.some((line) => line.trim() !== ''))
+            return;
+        if (PREAMBLE_SECTION_KEYS.has(current.key))
+            preambles.push(current.body.join('\n').trim());
+        else if (!isDeltaSectionHeader(current.header))
+            sections.push([current.header, ...current.body].join('\n').trimEnd());
+    };
+    for (let i = 0; i < lines.length; i++) {
+        if (!fenceMask[i]) {
+            const key = sectionHeaderKey(lines[i]);
+            if (key !== null) {
+                flush();
+                current = { header: lines[i], key, body: [], bareTitle: false };
+                cut = false;
+                continue;
+            }
+            // A `#` heading ends the block before it, as the block parser ends it, so
+            // it and the text under it are in no block. Kept on their own, after the
+            // requirements: below a cut nothing else collects them. In a section that
+            // goes under `## Requirements` it starts its own text too, even before a
+            // block: written into the preamble, it ended the rebuilt section above
+            // every requirement, which no reader then saw.
+            const endsPreamble = current !== null && (PREAMBLE_SECTION_KEYS.has(current.key) || isDeltaSectionHeader(current.header));
+            if ((cut || endsPreamble) && TITLE_HEADER.test(lines[i])) {
+                flush();
+                current = { header: lines[i], key: '', body: [], bareTitle: true };
+                cut = false;
+                continue;
+            }
+            if (matchRequirementHeader(lines[i]) !== null)
+                cut = true;
+        }
+        if (current !== null && !cut)
+            current.body.push(lines[i]);
     }
-    return collected.join('\n').trim();
+    flush();
+    return { requirementsPreamble: preambles.join('\n\n'), sections };
 }
 /**
  * Retitles a requirement block. The parser guarantees the block's first line is
@@ -203,10 +372,15 @@ function convertMetadata(raw, defaults) {
     return stringifyYaml(parsed);
 }
 /** Appends prose as a YAML literal block so its Markdown characters stay verbatim. */
-function appendContext(config, context) {
+export function appendContext(config, context) {
     const prefix = config.endsWith('\n') ? config : `${config}\n`;
     const normalized = normalizeDocument(context);
-    const trailingNewlines = normalized.match(/\n*$/)?.[0].length ?? 0;
+    // Counted by a scan: unanchored, `/\n*$/` retried from every newline of an
+    // inner run, and a project.md with 80k blank lines in its middle took 2.5 s.
+    let end = normalized.length;
+    while (end > 0 && normalized[end - 1] === '\n')
+        end--;
+    const trailingNewlines = normalized.length - end;
     // YAML block chomping: strip, clip, or keep the trailing newlines.
     let chomping;
     if (trailingNewlines === 0)
@@ -256,6 +430,47 @@ export class MigrateCommand {
         const activeChanges = await listDirs(path.join(source, 'changes'), 'archive');
         const archivedChanges = await listDirs(path.join(source, 'changes', 'archive'), 'archive');
         const specDirs = await listDirs(path.join(source, 'specs'));
+        // Refused rather than copied: status, instructions and archive all reject a
+        // change whose name fails validateChangeName, so a migrated `Bad_Name` was
+        // listed but could not be worked on. Held to the create-time rule, since
+        // migrate writes these directories: a `nul` copy cannot be checked out on
+        // Windows. Renaming it here was weighed and
+        // dropped: two source names can map to one kebab id, and the source stays
+        // read-only, so the reader renames it there and reruns.
+        const invalidNames = activeChanges.flatMap((name) => {
+            const validation = validateNewChangeName(name);
+            return validation.valid ? [] : [`${name} (${validation.error})`];
+        });
+        if (invalidNames.length > 0) {
+            const changesDir = path.join(source, 'changes');
+            throw new MigrateError(`Invalid change names in ${changesDir}: ${invalidNames.join('; ')}`, {
+                code: 'migrate_change_name_invalid',
+                fix: `Rename each listed directory under ${changesDir} to a kebab-case name Windows also accepts (e.g. add-auth, not nul or con), then rerun tospec migrate.`,
+            });
+        }
+        const archiveDir = path.join(source, 'changes', 'archive');
+        const archivePlan = await Promise.all(archivedChanges.map(async (dir) => ({
+            dir,
+            ...convertArchiveDirName(dir, await readCreatedDate(path.join(archiveDir, dir))),
+        })));
+        // Refused before anything is written: `2025-03-04-x` and an undated `x`
+        // created that day both become `20250304_000000-x`, and the second copy
+        // would merge into the first. Compared without case, as a case-insensitive
+        // file system (Windows, default macOS) merges names that differ only in it.
+        const byTarget = new Map();
+        for (const { dir, name } of archivePlan) {
+            const key = name.toLowerCase();
+            byTarget.set(key, [...(byTarget.get(key) ?? []), dir]);
+        }
+        const collisions = archivePlan
+            .filter(({ name }) => byTarget.get(name.toLowerCase()).length > 1)
+            .map(({ dir, name }) => `${dir} -> ${name}`);
+        if (collisions.length > 0) {
+            throw new MigrateError(`Archive dirs in ${archiveDir} map to the same tospec name: ${collisions.join('; ')}`, {
+                code: 'migrate_archive_name_collision',
+                fix: `Rename each colliding directory under ${archiveDir} to a distinct name, then rerun tospec migrate.`,
+            });
+        }
         // JSON mode is non-interactive, so the caller has to say --force up front.
         if (options?.json && !options?.force) {
             throw new MigrateError('migrate --json is non-interactive and needs confirmation up front.', {
@@ -282,6 +497,11 @@ export class MigrateCommand {
             removedRequirements: [],
             renamedRequirements: [],
             renamedKept: [],
+            skipped: await listUnmigratedEntries(source),
+            stampedArchives: archivePlan
+                .filter(({ stamped }) => stamped)
+                .map(({ dir, name }) => `${dir} -> ${name}`)
+                .sort(),
         };
         // Two-phase: build the whole tree in a sibling staging dir, then promote it.
         // A mid-migration failure cleans staging and leaves the target untouched, so
@@ -297,9 +517,12 @@ export class MigrateCommand {
                 const specFile = path.join(source, 'specs', dir, 'spec.md');
                 if (!(await exists(specFile))) {
                     summary.specs.skippedEmpty++;
+                    // The count alone hid that a README.md or other file beside the
+                    // missing spec.md was left behind with the directory.
+                    summary.skipped.push(`specs/${dir}/`);
                     continue;
                 }
-                await fs.cp(path.join(source, 'specs', dir), path.join(staging, 'specs', dir), { recursive: true });
+                await copyContent(path.join(source, 'specs', dir), path.join(staging, 'specs', dir));
                 const content = await fs.readFile(specFile, 'utf-8');
                 const normalized = normalizeMainSpec(content, dir);
                 if (normalized) {
@@ -314,16 +537,17 @@ export class MigrateCommand {
                 }
                 summary.specs.copied++;
             }
+            summary.skipped.sort();
             for (const dir of activeChanges) {
                 const dest = path.join(staging, 'changes', dir);
-                await fs.cp(path.join(source, 'changes', dir), dest, { recursive: true });
+                await copyContent(path.join(source, 'changes', dir), dest);
                 if (await this.migrateMetadata(dest))
                     summary.changes.metadataCreated++;
                 summary.changes.active++;
             }
-            for (const dir of archivedChanges) {
-                const dest = path.join(staging, 'changes', 'archive', convertArchiveDirName(dir));
-                await fs.cp(path.join(source, 'changes', 'archive', dir), dest, { recursive: true });
+            for (const { dir, name } of archivePlan) {
+                const dest = path.join(staging, 'changes', 'archive', name);
+                await copyContent(path.join(source, 'changes', 'archive', dir), dest);
                 const created = dir.match(ARCHIVE_DATE_PREFIX);
                 const createdDate = created ? `${created[1]}-${created[2]}-${created[3]}` : undefined;
                 if (await this.migrateMetadata(dest, createdDate))
@@ -339,7 +563,6 @@ export class MigrateCommand {
         if (options?.json) {
             // A migrated project has no skills until `tospec init` runs, and the
             // deferred ticket stubs are a deliberate gap a caller must know about.
-            // tospec/decisions/20260916_121552-migrated-changes-defer-ticket-stubs.md
             const migratedChangeCount = summary.changes.active + summary.changes.archived;
             emitSuccess({
                 migrate: {
@@ -365,6 +588,12 @@ export class MigrateCommand {
         if (summary.removedRequirements.length > 0) {
             console.log(`  REMOVED requirements dropped during normalization: ${summary.removedRequirements.join(', ')}`);
         }
+        if (summary.skipped.length > 0) {
+            console.log(`  Warning: not migrated, copy by hand if still needed: ${summary.skipped.join(', ')}`);
+        }
+        if (summary.stampedArchives.length > 0) {
+            console.log(`  Warning: undated archive dirs stamped from created (else today), not their archive date: ${summary.stampedArchives.join(', ')}`);
+        }
         switch (summary.context) {
             case 'carried':
                 console.log(`  Context: project.md -> config.yaml context:`);
@@ -460,7 +689,12 @@ export class MigrateCommand {
         await fs.rm(staging, { recursive: true, force: true });
     }
 }
-/** First non-empty line of proposal.md's `## Why` section, else a marker. */
+/**
+ * First non-empty line of proposal.md's Why section, else a marker. The section
+ * validate reads as Why (`requiredSections`, through `findSection`): a regex of
+ * its own took only `## Why`, so `## why`, `## Why ##` and `### Why` passed
+ * validate and lost their goal here, and a fenced example supplied one.
+ */
 async function extractGoal(changeDir) {
     const fallback = 'Migrated from OpenSpec';
     let content;
@@ -470,20 +704,9 @@ async function extractGoal(changeDir) {
     catch {
         return fallback;
     }
-    const lines = normalizeDocument(content).split('\n');
-    let inWhy = false;
-    for (const line of lines) {
-        if (/^## Why\s*$/.test(line)) {
-            inWhy = true;
-            continue;
-        }
-        if (inWhy && /^#{1,2} /.test(line))
-            break;
-        if (inWhy && line.trim().length > 0) {
-            return line.trim();
-        }
-    }
-    return fallback;
+    const why = findSection(new MarkdownParser(content).getSections(), 'Why');
+    const first = why?.content.split(/\r?\n/).find((line) => line.trim().length > 0);
+    return first?.trim() || fallback;
 }
 /**
  * False only for a path that is not there. Every caller treats `false` as
@@ -501,16 +724,69 @@ async function exists(p) {
         throw error;
     }
 }
+/**
+ * The `created` day of a source change's `.openspec.yaml`, or undefined when
+ * there is none to read. A file that does not parse is left to
+ * `migrateMetadata`, which reports it when it converts the file.
+ */
+async function readCreatedDate(changeDir) {
+    try {
+        const parsed = parseYaml(await fs.readFile(path.join(changeDir, METADATA_SOURCE), 'utf-8'));
+        const created = parsed?.created;
+        return typeof created === 'string' ? created : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Copies a source change or spec dir by its content. `fs.cp` on a link copies
+ * the link, so a linked source would come out as a link in tospec/ still
+ * pointing outside it, and the migrated content would never be the project's.
+ * Links inside the dir are copied as before.
+ */
+async function copyContent(from, to) {
+    await fs.cp(await fs.realpath(from), to, { recursive: true });
+}
 /** Names of the `.md` files directly in `dir`. Unreadable dir → empty list. */
 async function listMarkdownFiles(dir) {
     const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
     return entries.filter((entry) => entry.isFile() && entry.name.endsWith('.md')).map((entry) => entry.name);
 }
-/** Sorted subdirectory names, minus `exclude`. Unreadable dir → empty list. */
+/** Top-level source entries migrate reads; every other one is left behind. */
+const MIGRATED_TOP_LEVEL = new Set(['config.yaml', 'project.md', 'specs', 'changes']);
+/**
+ * The source entries no step reads: top-level items outside
+ * `MIGRATED_TOP_LEVEL`, and whatever `listDirs` drops (files, dangling links)
+ * from `specs/`, `changes/` and `changes/archive/`. Sorted, `/`-separated.
+ */
+async function listUnmigratedEntries(source) {
+    const skipped = [];
+    const collect = async (relative, isMigrated) => {
+        const dir = path.join(source, relative);
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const isDir = isDirectoryEntry(dir, entry);
+            if (!isMigrated(entry, isDir))
+                skipped.push(`${relative}${entry.name}${isDir ? '/' : ''}`);
+        }
+    };
+    await collect('', (entry) => MIGRATED_TOP_LEVEL.has(entry.name));
+    await collect('specs/', (_, isDir) => isDir);
+    // `archive` by name, as `listDirs` excludes it: it is read on its own below.
+    await collect('changes/', (entry, isDir) => isDir || entry.name === 'archive');
+    await collect('changes/archive/', (_, isDir) => isDir);
+    return skipped.sort();
+}
+/**
+ * Sorted subdirectory names, linked ones included, minus `exclude`. Unreadable
+ * dir → empty list. Linked ones count because every command reading the
+ * migrated project follows them; left out, they were listed as not migrated.
+ */
 async function listDirs(dir, exclude) {
     const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
     return entries
-        .filter((entry) => entry.isDirectory() && entry.name !== exclude)
+        .filter((entry) => isDirectoryEntry(dir, entry) && entry.name !== exclude)
         .map((entry) => entry.name)
         .sort();
 }