dorfl 0.0.0 → 0.1.1

package/dist/prd-to-spec.js

@@ -0,0 +1,706 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, rmdirSync, } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import { run, git, gitMv } from './git.js';
+import { resolveProtocolDoc } from './prompt.js';
+import { WORK_ROOT } from './work-layout.js';
+/** The `prd → spec` cutover this verb enacts (ADR §7e). */
+export const MIGRATION = {
+    from: 'prd',
+    to: 'spec',
+    fromFolder: 'prds',
+    toFolder: 'specs',
+    configKeys: [{ from: 'prdsLandIn', to: 'specsLandIn' }],
+};
+/**
+ * The FULL set of protocol docs `setup` propagates into a repo's
+ * `work/protocol/`. The re-sync copies EACH from the package's canonical source
+ * (via {@link resolveProtocolDoc}) so the migrated repo carries the new `spec`
+ * contract. Kept in lockstep with `skills/setup/protocol/` (the source of truth)
+ * and the `vendor-protocol` build step (which vendors these into `dist/protocol/`
+ * so the published CLI is self-contained).
+ */
+export const PROTOCOL_DOCS = [
+    'WORK-CONTRACT.md',
+    'CLAIM-PROTOCOL.md',
+    'REVIEW-PROTOCOL.md',
+    'SURFACE-PROTOCOL.md',
+    'TASKING-PROTOCOL.md',
+    'ADR-FORMAT.md',
+    'task-template.md',
+    'spec-template.md',
+];
+// ───────────────────────────────────────────────────────────────────────────
+// Layer: keep-case replace (the bespoke sweep — see the tooling JSDoc above).
+// ───────────────────────────────────────────────────────────────────────────
+/** Upper-case the first letter of a word (`prd → Prd`). */
+function capitalise(word) {
+    return word.length === 0 ? word : word[0].toUpperCase() + word.slice(1);
+}
+/**
+ * Keep-case replace EVERY occurrence of `from` with `to` across the three case
+ * variants — lower (`prd → spec`), Capitalised (`Prd → Spec`), and UPPER
+ * (`PRD → SPEC`) — preserving the shape of each hit. Deliberately does a plain
+ * substring replace (no word boundary) so it rewrites `prd` inside identifiers
+ * like `prdsLandIn`/`work/prds/`; callers scope it to the tokens they mean to
+ * rewrite (a whole config key, a frontmatter-field line, a path). The bespoke
+ * dependency-free sweep the tooling JSDoc justifies over `change-case`.
+ */
+export function keepCaseReplace(text, from, to) {
+    const variants = [
+        [from.toUpperCase(), to.toUpperCase()],
+        [capitalise(from), capitalise(to)],
+        [from.toLowerCase(), to.toLowerCase()],
+    ];
+    let out = text;
+    for (const [f, t] of variants) {
+        out = out.split(f).join(t);
+    }
+    return out;
+}
+/**
+ * Is the repo QUIESCENT enough to migrate (ADR §7e, 1a)? Refuse if ANY of:
+ *   - the working tree is DIRTY (uncommitted/untracked changes), OR
+ *   - a per-item LOCK ref is held (`refs/dorfl/lock/*`), OR
+ *   - an in-progress `work/<from>-*`/`work/<to>-*` work-branch exists (a branch
+ *     that is NOT merged into the current tip = unlanded work in flight).
+ *
+ * Returns the FIRST violation (dirty tree dominates, then locks, then branches),
+ * naming the offender, or `undefined` when quiescent. Read-only: it inspects the
+ * LOCAL repo's refs + status (the fixture/downstream case where the migration
+ * runs in-place). The quiescence gate is what makes layer (d) safe: with no held
+ * lock and no in-flight branch, only INERT refs remain to rename.
+ */
+export function checkQuiescence(repoPath, migration = MIGRATION, env = undefined) {
+    // 1. Dirty tree dominates — never migrate over uncommitted work.
+    const status = run('git', ['status', '--porcelain'], repoPath, { env });
+    if (status.status !== 0) {
+        return { kind: 'dirty-tree', offender: '(git status failed)' };
+    }
+    const dirty = status.stdout
+        .split('\n')
+        .map((l) => l.trimEnd())
+        .filter((l) => l !== '');
+    if (dirty.length > 0) {
+        return {
+            kind: 'dirty-tree',
+            offender: dirty.map((l) => l.slice(3).trim()).join(', '),
+        };
+    }
+    // 2. A held per-item lock ref (`refs/dorfl/lock/<entry>`). Any such LOCAL ref
+    //    means an item is claimed/in-flight — refuse, naming the entry.
+    const locks = run('git', ['for-each-ref', '--format=%(refname)', 'refs/dorfl/lock/'], repoPath, { env });
+    if (locks.status === 0) {
+        const held = locks.stdout
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.startsWith('refs/dorfl/lock/'));
+        if (held.length > 0) {
+            return { kind: 'held-lock', offender: held[0] };
+        }
+    }
+    // 3. An in-progress `work/<from>-*` / `work/<to>-*` branch carrying UNLANDED
+    //    work (a local branch not merged into HEAD). A branch already merged into
+    //    the current tip is inert; an unmerged one is work in flight — refuse.
+    const branches = run('git', [
+        'for-each-ref',
+        '--format=%(refname:short)',
+        `refs/heads/${WORK_ROOT}/${migration.from}-*`,
+        `refs/heads/${WORK_ROOT}/${migration.to}-*`,
+    ], repoPath, { env });
+    if (branches.status === 0) {
+        const names = branches.stdout
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l !== '');
+        for (const branch of names) {
+            // Merged into the current tip ⇒ inert (safe to rename); otherwise it
+            // carries unlanded work ⇒ refuse, naming the branch.
+            const merged = run('git', ['merge-base', '--is-ancestor', branch, 'HEAD'], repoPath, { env });
+            if (merged.status !== 0) {
+                return { kind: 'in-progress-branch', offender: branch };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Re-sync the target repo's `work/protocol/*` from the package's canonical
+ * source (the deterministic part of the `setup` skill — copy the docs verbatim +
+ * bump `VERSION`). Resolves each doc's SOURCE via {@link resolveProtocolDoc} with
+ * NO `cwd`, so it reads the package-vendored (`dist/protocol/`) or dev-source
+ * (`skills/setup/protocol/`) copy — NEVER the target repo's own (old) copy. This
+ * is how the migrated repo picks up the new `spec` contract before its data is
+ * converted. Idempotent: a doc already byte-identical is reported `unchanged`.
+ * A doc whose SOURCE cannot be resolved is reported `skipped` (NOT copied, NEVER
+ * a VERSION-bump) rather than silently bumping VERSION with nothing copied.
+ *
+ * `dryRun` reports what WOULD be copied without writing. `resolveDoc` overrides
+ * how a doc's source path is resolved (defaults to {@link resolveProtocolDoc});
+ * it exists so a test can force a non-resolvable source (a path that does not
+ * exist) to exercise the skip path.
+ */
+export function resyncProtocol(repoPath, options = {}) {
+    const protocolDir = join(repoPath, WORK_ROOT, 'protocol');
+    const resolveDoc = options.resolveDoc ?? ((name) => resolveProtocolDoc(name));
+    const docs = [];
+    for (const name of PROTOCOL_DOCS) {
+        // Resolve the SOURCE (package/dev), never the target's adopted copy.
+        const source = resolveDoc(name);
+        const destAbs = join(protocolDir, name);
+        const destRel = relative(repoPath, destAbs);
+        const sourceExists = existsSync(source);
+        if (!sourceExists) {
+            // The source doc could not be resolved: copy NOTHING and record the doc as
+            // SKIPPED (never a change). This is the latent-bug fix: a non-resolvable
+            // source must not count as `changed` and bump `VERSION` while copying no
+            // file. `unchanged: false` here is honest (the dest was not made to match a
+            // source), but `skipped: true` keeps it OUT of the VERSION-bump tally.
+            docs.push({ name, dest: destRel, unchanged: false, skipped: true });
+            continue;
+        }
+        // Source resolved: a doc is CHANGED (VERSION-bump-worthy) only when the dest
+        // is absent OR its content differs from the source. An identical dest is a
+        // no-op copy (`unchanged`), so an already-synced re-run stays a true no-op.
+        const unchanged = existsSync(destAbs) &&
+            readFileSync(source, 'utf8') === readFileSync(destAbs, 'utf8');
+        if (!options.dryRun) {
+            mkdirSync(dirname(destAbs), { recursive: true });
+            copyFileSync(source, destAbs);
+        }
+        docs.push({ name, dest: destRel, unchanged, skipped: false });
+    }
+    const versionAbs = join(protocolDir, 'VERSION');
+    const versionRel = relative(repoPath, versionAbs);
+    // Bump VERSION only when a doc was ACTUALLY COPIED with new content, or when
+    // VERSION is absent AND at least one doc was genuinely synced (copied). A
+    // SKIPPED doc (unresolvable source, nothing copied) is NEVER a change —
+    // counting it would bump VERSION without copying a single doc (the latent bug),
+    // and the write-when-absent fallback must ALSO require a real copy so an
+    // all-skipped resync leaves no VERSION behind. A re-run on an already-synced
+    // repo must stay a true no-op — otherwise the (always-fresh) `synced-at`
+    // timestamp would dirty the tree on every idempotent re-run.
+    const anyDocChanged = docs.some((d) => !d.unchanged && !d.skipped);
+    const anyDocSynced = docs.some((d) => !d.skipped);
+    if (!options.dryRun &&
+        (anyDocChanged || (anyDocSynced && !existsSync(versionAbs)))) {
+        mkdirSync(dirname(versionAbs), { recursive: true });
+        const today = new Date().toISOString().slice(0, 10);
+        writeFileSync(versionAbs, [
+            `protocol-version: ${today}`,
+            'synced-from: skills/setup/protocol/',
+            `synced-at: ${new Date().toISOString()}`,
+            'source-commit: dorfl prd-to-spec',
+            '',
+        ].join('\n'));
+    }
+    return { docs, versionPath: versionRel };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Layer 3a: the FOLDER move (in lockstep with work-layout.ts).
+// ───────────────────────────────────────────────────────────────────────────
+/** The four lifecycle sub-folders under `work/<from>s/` the move relocates. */
+const LIFECYCLE_SUBFOLDERS = [
+    'proposed',
+    'ready',
+    'tasked',
+    'dropped',
+];
+/**
+ * Move `work/<from>s/{proposed,ready,tasked,dropped}/ → work/<to>s/…`. The
+ * DESTINATION spellings match `work-layout.ts`'s post-cutover folder names in
+ * lockstep — this layer moves the DATA folders the CODE already renamed.
+ *
+ * A sub-folder with TRACKED files is `git mv`'d (renames preserve history); a
+ * sub-folder that exists on disk but has NO tracked files (an empty staging dir
+ * `setup` created — git never tracks empty dirs, so `git mv` would fatal on it)
+ * is instead removed with a plain `rmdir` so no stray `work/<from>s/` folder is
+ * left to leak (the empty dir carries no data). Only folders that EXIST are
+ * touched (an absent sub-folder is skipped), so it is idempotent AND
+ * partial-repo safe: a second run finds `work/<from>s/*` gone and does nothing.
+ * `dryRun` reports the moves without touching git or the filesystem.
+ */
+export function migrateFolders(repoPath, migration = MIGRATION, options = {}) {
+    const moves = [];
+    for (const sub of LIFECYCLE_SUBFOLDERS) {
+        const fromRel = `${WORK_ROOT}/${migration.fromFolder}/${sub}`;
+        const toRel = `${WORK_ROOT}/${migration.toFolder}/${sub}`;
+        const fromAbs = join(repoPath, fromRel);
+        if (!existsSync(fromAbs)) {
+            continue;
+        }
+        const tracked = run('git', ['ls-files', '--', fromRel], repoPath)
+            .stdout.split('\n')
+            .some((l) => l.trim() !== '');
+        if (!tracked) {
+            // An empty/untracked on-disk staging dir: nothing for git to move, but
+            // leave no stray `work/<from>s/` behind. Best-effort rmdir (only removes
+            // an empty dir; a dir with untracked files stays and is reported).
+            if (!options.dryRun) {
+                try {
+                    rmdirSync(fromAbs);
+                }
+                catch {
+                    // non-empty untracked dir — leave it; the leak scan will surface it.
+                }
+            }
+            continue;
+        }
+        moves.push({ from: fromRel, to: toRel });
+        if (!options.dryRun) {
+            gitMv(fromRel, toRel, repoPath);
+        }
+    }
+    // Prune a now-empty `work/<from>s/` parent so no stray folder leaks.
+    if (!options.dryRun) {
+        const parent = join(repoPath, WORK_ROOT, migration.fromFolder);
+        try {
+            rmdirSync(parent);
+        }
+        catch {
+            // still has (untracked) content — leave it for the leak scan to surface.
+        }
+    }
+    return moves;
+}
+/**
+ * Which `work/` folders carry ITEMS whose bodies/frontmatter may reference the
+ * retired word — the FULL set including terminal/history folders, because
+ * done-items ARE converted (ADR §7e: a `done/` full of dangling `prd:` refs is a
+ * broken repo, so determinism overrides the old "don't touch done" convenience).
+ * Paths are repo-relative and walked recursively. `work/specs/*` is included so
+ * items ALREADY moved by layer 3a (whose bodies may still say `work/prds/…`) are
+ * swept too. `work/protocol/` is EXCLUDED — layer 2 owns it (verbatim contract
+ * copies, not data). Each entry is a path UNDER `work/` (the `WORK_ROOT` prefix
+ * is prepended by the walker).
+ */
+const ITEM_CONTENT_FOLDERS = [
+    'tasks/backlog',
+    'tasks/ready',
+    'tasks/done',
+    'tasks/cancelled',
+    // BOTH the post-move `specs/*` locations AND the pre-move `prds/*` locations
+    // are walked: after a real (non-dry-run) migration the items live in `specs/*`
+    // (layer 3a moved them first) and `prds/*` is empty; under `--dry-run` the
+    // folders are NOT moved, so the items are still in `prds/*` — walking both makes
+    // the content sweep (and its dry-run report) accurate in either order, and it
+    // stays idempotent (an empty folder contributes nothing).
+    'prds/proposed',
+    'prds/ready',
+    'prds/tasked',
+    'prds/dropped',
+    'specs/proposed',
+    'specs/ready',
+    'specs/tasked',
+    'specs/dropped',
+    'notes/observations',
+    'notes/ideas',
+    'notes/findings',
+    'questions',
+];
+/**
+ * Recursively collect every `.md` file under a `work/`-relative folder (the entry
+ * is UNDER `work/` — e.g. `'tasks/done'` — and `WORK_ROOT` is prepended here).
+ * Returns repo-relative paths WITH the `work/` prefix.
+ */
+function collectMarkdown(repoPath, folderUnderWork) {
+    return collectMarkdownRel(repoPath, `${WORK_ROOT}/${folderUnderWork}`);
+}
+/** Recursively collect every `.md` file under a repo-relative folder path. */
+function collectMarkdownRel(repoPath, folderRel) {
+    const abs = join(repoPath, folderRel);
+    if (!existsSync(abs)) {
+        return [];
+    }
+    const out = [];
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+        const childRel = `${folderRel}/${entry.name}`;
+        if (entry.isDirectory()) {
+            out.push(...collectMarkdownRel(repoPath, childRel));
+        }
+        else if (entry.name.toLowerCase().endsWith('.md')) {
+            out.push(childRel);
+        }
+    }
+    return out;
+}
+/**
+ * Rewrite the retired word in ONE item's text, SCOPED to genuine STRUCTURAL
+ * refs so it never corrupts prose or an immutable provenance SLUG (a landed
+ * item's `slug: prd-to-spec-…` must survive verbatim — a slug can never be
+ * renamed):
+ *
+ *   - the `prd:` frontmatter KEY at line start (`prdAfter:` too), NOT a `prd`
+ *     inside a value/slug;
+ *   - `work/prds/…` folder paths and a bare `prds/` folder segment;
+ *   - `work/prd-<slug>` branch refs (the `work/` prefix makes it unambiguous —
+ *     a bare `prd-<slug>` is NOT rewritten because it is indistinguishable from
+ *     a provenance slug fragment; a genuine bare lock entry lives on a git ref,
+ *     which {@link migrateRefs} handles, not in an item body);
+ *   - `prd:<slug>` CLI-arg tokens (a `prd:` at a non-word boundary followed by a
+ *     slug char), NOT a `prd:` embedded in a longer word.
+ *
+ * Returns the new text (unchanged when nothing matched). PURE — no IO — so it is
+ * trivially testable and the caller decides whether to write. Exported for reuse
+ * + the fixture test's determinism assertion.
+ */
+export function migrateItemContent(text, migration = MIGRATION) {
+    const from = migration.from;
+    let out = text;
+    // (i) The frontmatter FIELD key on its own line: `prd:` → `spec:` (keep-case),
+    //     matched at line start (optionally indented) so only the KEY is rewritten,
+    //     never a `prd` inside a value/slug. Also `prdAfter:` if it ever appears.
+    out = out.replace(new RegExp(`^(\\s*)(${from})(After)?(\\s*:)`, gimFlags()), (_m, indent, word, after, colon) => indent +
+        keepCaseReplace(word, from, migration.to) +
+        (after ?? '') +
+        colon);
+    // (ii) Folder-path refs `work/prds/…` → `work/specs/…` (keep-case on the
+    //      plural segment). A whole-path token, so a bare `prds/` inside a longer
+    //      path is caught by the segment replace below too.
+    out = replaceToken(out, `${WORK_ROOT}/${migration.fromFolder}`, `${WORK_ROOT}/${migration.toFolder}`);
+    out = replaceToken(out, `${migration.fromFolder}/`, `${migration.toFolder}/`);
+    // (iii) Inert `work/<from>-<slug>` branch refs: the `work/` prefix makes this
+    //       unambiguous (never a provenance-slug fragment), so a keep-case prefix
+    //       replace is safe. A BARE `<from>-<slug>` is deliberately NOT rewritten
+    //       (it is indistinguishable from a slug like `prd-to-spec-…`); a genuine
+    //       bare lock entry lives on a git ref (`migrateRefs`), not an item body.
+    out = replaceToken(out, `${WORK_ROOT}/${from}-`, `${WORK_ROOT}/${migration.to}-`);
+    // (iv) `<from>:<slug>` CLI-arg tokens (`prd:my-feature`): only at a non-word
+    //      boundary followed by a slug char, so a `prd:` mid-word is untouched and
+    //      the frontmatter KEY (line-start, handled by (i)) is not double-hit.
+    out = out.replace(new RegExp(`(^|[^A-Za-z0-9_])(${from})(:[A-Za-z0-9])`, gimFlags()), (_m, pre, word, tail) => pre + keepCaseReplace(word, from, migration.to) + tail);
+    return out;
+}
+/** Case-insensitive, multiline, global regex flags. */
+function gimFlags() {
+    return 'gim';
+}
+/**
+ * Keep-case replace a fixed TOKEN wherever it appears (all three case variants),
+ * a thin wrapper over {@link keepCaseReplace} scoped to a specific substring so
+ * the intent (rewrite THIS token) is explicit at the call site.
+ */
+function replaceToken(text, from, to) {
+    return keepCaseReplace(text, from, to);
+}
+/**
+ * Rewrite the retired word across EVERY item in the data folders (incl.
+ * `done/`/`tasked/` — determinism). Writes each changed file in place (unless
+ * `dryRun`), returning the list of files that changed. Idempotent: a file
+ * already in the `spec` shape produces identical text and is not listed.
+ */
+export function migrateAllItemContent(repoPath, migration = MIGRATION, options = {}) {
+    const changed = [];
+    for (const folder of ITEM_CONTENT_FOLDERS) {
+        for (const rel of collectMarkdown(repoPath, folder)) {
+            const abs = join(repoPath, rel);
+            const before = readFileSync(abs, 'utf8');
+            const after = migrateItemContent(before, migration);
+            if (after !== before) {
+                changed.push({ path: rel });
+                if (!options.dryRun) {
+                    writeFileSync(abs, after);
+                }
+            }
+        }
+    }
+    return changed;
+}
+/**
+ * Rewrite the retired config KEYS in `.dorfl.json` (`prdsLandIn → specsLandIn`),
+ * preserving each key's VALUE and the file's surrounding formatting — a TEXTUAL
+ * key rename on the raw JSON, NOT a parse+reserialise (which would drop unknown
+ * keys / reflow the file). Only renames a key that is actually present, so it is
+ * idempotent (a config already on `specsLandIn` changes nothing) and safe on a
+ * repo with no `.dorfl.json`. Returns the keys renamed. `dryRun` reports without
+ * writing.
+ */
+export function migrateConfig(repoPath, migration = MIGRATION, options = {}) {
+    const configAbs = join(repoPath, '.dorfl.json');
+    if (!existsSync(configAbs)) {
+        return [];
+    }
+    const before = readFileSync(configAbs, 'utf8');
+    let after = before;
+    const renamed = [];
+    for (const { from, to } of migration.configKeys) {
+        // Match the quoted JSON key exactly: `"prdsLandIn"` → `"specsLandIn"`.
+        const needle = `"${from}"`;
+        if (after.includes(needle)) {
+            after = after.split(needle).join(`"${to}"`);
+            renamed.push({ from, to });
+        }
+    }
+    if (after !== before && !options.dryRun) {
+        writeFileSync(configAbs, after);
+    }
+    return renamed;
+}
+/**
+ * Rename INERT local git refs carrying the retired word: per-item lock refs
+ * `refs/dorfl/lock/<from>-<slug>` → `…/<to>-<slug>` and work-branches
+ * `refs/heads/work/<from>-<slug>` → `…/work/<to>-<slug>`. The {@link
+ * checkQuiescence} gate guarantees NO lock is held and NO in-flight branch
+ * exists, so every ref reaching here is inert (a leftover created before the
+ * cutover) and a plain rename is safe. Uses `git update-ref` for lock refs (they
+ * are not branches) and `git branch -m` for work-branches. Idempotent: a ref
+ * already on the `<to>-` spelling is left alone; `dryRun` reports without
+ * touching refs.
+ */
+export function migrateRefs(repoPath, migration = MIGRATION, options = {}) {
+    const env = options.env;
+    const renames = [];
+    // Lock refs: `refs/dorfl/lock/<from>-<slug>` → `refs/dorfl/lock/<to>-<slug>`.
+    const lockPrefix = 'refs/dorfl/lock/';
+    const locks = run('git', ['for-each-ref', '--format=%(refname) %(objectname)', lockPrefix], repoPath, { env });
+    if (locks.status === 0) {
+        for (const line of locks.stdout.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '')
+                continue;
+            const [ref, sha] = trimmed.split(/\s+/);
+            const entry = ref.slice(lockPrefix.length);
+            if (!entry.startsWith(`${migration.from}-`))
+                continue;
+            const newEntry = migration.to + entry.slice(migration.from.length);
+            const newRef = lockPrefix + newEntry;
+            renames.push({ from: ref, to: newRef });
+            if (!options.dryRun) {
+                git(['update-ref', newRef, sha], repoPath, { env });
+                git(['update-ref', '-d', ref], repoPath, { env });
+            }
+        }
+    }
+    // Work-branches: `work/<from>-<slug>` → `work/<to>-<slug>`.
+    const branchPrefix = `${WORK_ROOT}/${migration.from}-`;
+    const branches = run('git', [
+        'for-each-ref',
+        '--format=%(refname:short)',
+        `refs/heads/${branchPrefix}*`,
+    ], repoPath, { env });
+    if (branches.status === 0) {
+        for (const line of branches.stdout.split('\n')) {
+            const branch = line.trim();
+            if (branch === '' || !branch.startsWith(branchPrefix))
+                continue;
+            const newBranch = `${WORK_ROOT}/${migration.to}-${branch.slice(branchPrefix.length)}`;
+            renames.push({
+                from: `refs/heads/${branch}`,
+                to: `refs/heads/${newBranch}`,
+            });
+            if (!options.dryRun) {
+                git(['branch', '-m', branch, newBranch], repoPath, { env });
+            }
+        }
+    }
+    return renames;
+}
+/**
+ * The DATA-tree forward+reverse leak scan — the acceptance GATE for the
+ * command's OUTPUT (ADR §7e: the leak scan is exhaustive-by-construction). This
+ * is the DATA analogue of the source-part `prd-to-spec-leak-scan.test.ts`
+ * (which scans `src/`/`skills/`/`docs/`): here it walks the CONVERTED `work/`
+ * tree + `.dorfl.json` + the git refs.
+ *
+ *   - **FORWARD:** fails on any surviving retired word (`prd`/`Prd`/`PRD`) in a
+ *     data STRUCTURE position — a frontmatter `prd:` KEY, a `work/prds/…` folder
+ *     path, a `work/prd-<slug>` branch ref, a `prd-<slug>` lock entry, a config
+ *     key `prdsLandIn`, or a `prd:<slug>` token. It deliberately IGNORES the
+ *     retired word in running PROSE (a body sentence, an immutable provenance
+ *     slug like `prd-to-spec-…`) — those are the artifact word in narrative, not
+ *     a dangling structural ref, exactly as the source-part scan's option-A cut.
+ *   - **REVERSE:** fails on genuine English CORRUPTED by a blind keep-case sweep
+ *     (`espec…`→`esspec…`-style mangles) — the guard that `spec`'s English
+ *     collisions were not mangled.
+ *
+ * A green scan on the converted fixture is the proof the four layers left no
+ * dangling structural `prd`. Returns every leak (empty ⇒ green).
+ */
+export function scanForLeaks(repoPath, migration = MIGRATION, env = undefined) {
+    const leaks = [];
+    const from = migration.from;
+    // STRUCTURAL forward patterns: a surviving retired word in a data position.
+    const structural = [
+        {
+            pattern: new RegExp(`^\\s*${from}(After)?\\s*:`, 'i'),
+            why: `surviving '${from}:' frontmatter key`,
+        },
+        {
+            pattern: new RegExp(`${WORK_ROOT}/${migration.fromFolder}(/|\\b)`, 'i'),
+            why: `surviving '${WORK_ROOT}/${migration.fromFolder}/' folder path`,
+        },
+        {
+            // A bare `prds/` folder ref, but ONLY a real on-disk path shape:
+            // lowercase `prds/` followed by a lifecycle subfolder. Deliberately NO
+            // `'i'` flag + a required lifecycle segment, so a prose acronym-plural
+            // like `slices/PRDs/code` or `PRDs/ADRs` (the artifact word `PRDs` + `/`
+            // + another word) is NOT mis-flagged as a folder ref (the option-A prose
+            // exemption). The `${WORK_ROOT}/${fromFolder}` pattern above still
+            // catches a rooted `work/prds/...` path case-insensitively as the backstop.
+            pattern: new RegExp(`\\b${migration.fromFolder}/(proposed|ready|tasked|dropped)\\b`),
+            why: `surviving '${migration.fromFolder}/' folder ref`,
+        },
+        {
+            pattern: new RegExp(`${WORK_ROOT}/${from}-`, 'i'),
+            why: `surviving '${WORK_ROOT}/${from}-' branch ref`,
+        },
+        {
+            pattern: new RegExp(`(^|[^A-Za-z])${from}:[A-Za-z0-9]`, 'i'),
+            why: `surviving '${from}:<slug>' arg`,
+        },
+    ];
+    // Config-key survivors (the exact keys the config layer renames).
+    const configKeyPatterns = migration.configKeys.map(({ from: key }) => ({
+        pattern: new RegExp(`"${key}"`),
+        why: `surviving '${key}' config key`,
+    }));
+    // Corrupted-English (reverse) shapes a blind sweep would have produced.
+    const corrupted = [
+        { pattern: /esspec/i, why: 'especially → esspec… (mangle)' },
+        { pattern: /speccif/i, why: 'specify/specific → speccif… (mangle)' },
+        { pattern: /inspecc/i, why: 'inspect → inspecc… (mangle)' },
+        { pattern: /respecc/i, why: 'respect → respecc… (mangle)' },
+    ];
+    const scanText = (where, text, keyPatterns) => {
+        const lines = text.split('\n');
+        lines.forEach((line, idx) => {
+            for (const { pattern, why } of structural) {
+                const m = pattern.exec(line);
+                if (m) {
+                    leaks.push({
+                        where: `${where}:${idx + 1}`,
+                        token: m[0],
+                        lens: 'forward',
+                        why,
+                    });
+                }
+            }
+            for (const { pattern, why } of keyPatterns) {
+                const m = pattern.exec(line);
+                if (m) {
+                    leaks.push({
+                        where: `${where}:${idx + 1}`,
+                        token: m[0],
+                        lens: 'forward',
+                        why,
+                    });
+                }
+            }
+            for (const { pattern, why } of corrupted) {
+                const m = pattern.exec(line);
+                if (m) {
+                    leaks.push({
+                        where: `${where}:${idx + 1}`,
+                        token: m[0],
+                        lens: 'reverse',
+                        why,
+                    });
+                }
+            }
+        });
+    };
+    // Walk every converted data item (the FULL folder set, incl. done/tasked).
+    for (const folder of ITEM_CONTENT_FOLDERS) {
+        for (const rel of collectMarkdown(repoPath, folder)) {
+            scanText(rel, readFileSync(join(repoPath, rel), 'utf8'), []);
+        }
+    }
+    // The config file (the key layer).
+    const configAbs = join(repoPath, '.dorfl.json');
+    if (existsSync(configAbs)) {
+        scanText('.dorfl.json', readFileSync(configAbs, 'utf8'), configKeyPatterns);
+    }
+    // The FOLDER TREE itself: a surviving `work/prds/` directory (empty ⇒ no
+    // file, but the folder still leaks). Report it structurally.
+    const strayFolder = join(repoPath, WORK_ROOT, migration.fromFolder);
+    if (existsSync(strayFolder)) {
+        leaks.push({
+            where: `${WORK_ROOT}/${migration.fromFolder}`,
+            token: `${WORK_ROOT}/${migration.fromFolder}`,
+            lens: 'forward',
+            why: `surviving '${WORK_ROOT}/${migration.fromFolder}/' folder`,
+        });
+    }
+    // The git refs (lock refs + branches carrying the retired word).
+    for (const spec of [
+        {
+            args: ['for-each-ref', '--format=%(refname)', 'refs/dorfl/lock/'],
+            where: 'refs/dorfl/lock',
+        },
+        {
+            args: [
+                'for-each-ref',
+                '--format=%(refname:short)',
+                `refs/heads/${WORK_ROOT}/`,
+            ],
+            where: 'refs/heads',
+        },
+    ]) {
+        const res = run('git', spec.args, repoPath, { env });
+        if (res.status !== 0)
+            continue;
+        for (const line of res.stdout.split('\n')) {
+            const ref = line.trim();
+            if (ref === '')
+                continue;
+            if (new RegExp(`(^|/)${from}-`, 'i').test(ref) ||
+                new RegExp(`/${from}-`, 'i').test(ref)) {
+                leaks.push({
+                    where: spec.where,
+                    token: ref,
+                    lens: 'forward',
+                    why: `surviving '${from}-' git ref`,
+                });
+            }
+        }
+    }
+    return leaks;
+}
+/**
+ * Run the self-contained `prd → spec` migration end-to-end (ADR §7e, decision
+ * B): quiescence gate → setup re-sync → four-layer data migration → leak scan.
+ * On a quiescence violation it REFUSES (returns `{refused}`, runs no layer). The
+ * thin `dorfl prd-to-spec` CLI shell formats this result; the fixture test
+ * asserts each field. `dryRun` threads through every layer.
+ */
+export function runPrdToSpec(options) {
+    const { repoPath } = options;
+    const migration = options.migration ?? MIGRATION;
+    const dryRun = options.dryRun === true;
+    const env = options.env;
+    const refused = checkQuiescence(repoPath, migration, env);
+    if (refused) {
+        return {
+            refused,
+            dryRun,
+            folderMoves: [],
+            contentRewrites: [],
+            configRewrites: [],
+            refRenames: [],
+            leaks: [],
+        };
+    }
+    // 2. Setup contract re-sync FIRST (decision B).
+    const resync = resyncProtocol(repoPath, { dryRun });
+    // 3a. Folders (git mv) — before content, so the content sweep also fixes the
+    //     moved items' own `work/prds/…` body refs in their NEW location.
+    const folderMoves = migrateFolders(repoPath, migration, { dryRun });
+    // 3b. Item content (frontmatter + inert refs) across ALL items incl. done/.
+    const contentRewrites = migrateAllItemContent(repoPath, migration, { dryRun });
+    // 3c. Config key rename.
+    const configRewrites = migrateConfig(repoPath, migration, { dryRun });
+    // 3d. Inert git refs (lock refs + work-branches).
+    const refRenames = migrateRefs(repoPath, migration, { dryRun, env });
+    // The acceptance GATE over the converted tree (skipped under dry-run, where
+    // nothing was written so the tree still carries the pre-migration data).
+    const leaks = dryRun ? [] : scanForLeaks(repoPath, migration, env);
+    return {
+        dryRun,
+        resync,
+        folderMoves,
+        contentRewrites,
+        configRewrites,
+        refRenames,
+        leaks,
+    };
+}
+//# sourceMappingURL=prd-to-spec.js.map