@pareto4/pp-core 1.13.0 → 1.18.0

package/pp-core/bin/lib/phase-manifest.cjs

@@ -1,527 +0,0 @@
-"use strict";
-/**
- * Phase manifest — the writer of `.phase-manifest.json`, which `/pp-undo
- * --phase` reads (`manifest.phases[NN].commits`, reverted newest first).
- *
- * Command surface (routed by phase.cts):
- *   pp-tools phase manifest start  <phase>   anchor the phase: startCommit = HEAD, write-once
- *   pp-tools phase manifest record <phase>   commits = rev-list --reverse --no-merges <startCommit>..HEAD
- *
- * execute-phase calls `start` before its first executor and `record` after
- * every wave's tracking commit and after the phase completion commit, so the
- * list always covers the phase's executor, merge and tracking commits. Both
- * are orchestrator writes; no executor calls them.
- *
- * The manifest sits two levels above the phase directory:
- * `.planning/.phase-manifest.json` on the flat layout (the file `/pp-undo`
- * reads), `.planning/workstreams/<ws>/.phase-manifest.json` on a partitioned
- * one, so two workstreams' `05` entries never share a file. It is local
- * execution metadata: the writer adds `.phase-manifest.json` to the
- * repository's shared `info/exclude`, so the file never shows as untracked
- * (which `/pp-undo`'s clean-tree guard would refuse) and is never committed by
- * a broad `git add`.
- *
- * Never throws; a refusal is `{ ok: false, action, reason }` with a
- * `PHASE_MANIFEST_WRITE_REASON` member, and the workflows print the one-line
- * rendering and continue — a manifest that could not be written leaves
- * `/pp-undo --phase` on its git-log fallback, which is what it had before.
- *
- * `readPhaseManifestEntry` is the READER: the phase's recorded `startCommit`
- * and `commits`, read from exactly the file the writer writes, or the named
- * ground on which there is no usable record. `vault audit` scopes its diff
- * from it (src/vault-audit.cts).
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
-/** The manifest file `/pp-undo` reads. */
-const PHASE_MANIFEST_FILE = '.phase-manifest.json';
-/**
- * Every sha is interpolated into a git ARGV, where a leading `-` would be read
- * as a flag. The manifest is editable planning data, so this is the one shape
- * a sha may have.
- */
-const COMMIT_SHA_SHAPE = /^[0-9a-fA-F]{7,64}$/;
-/** The leading `NN` or `NN.M` token of a phase directory slug. */
-const PHASE_SLUG_SHAPE = /^(\d+(?:\.\d+)?)/;
-const TOKEN_MAX = 120;
-/** Why `recordPhaseStart` / `recordPhaseCommits` wrote nothing. */
-const PHASE_MANIFEST_WRITE_REASON = Object.freeze({
-    /** The phase directory is not an existing directory inside the project root. */
-    PHASE_DIR_UNRESOLVABLE: 'phase-dir-unresolvable',
-    /** The phase directory's name does not begin with an `NN` or `NN.M` token. */
-    PHASE_SLUG_UNRECOGNISED: 'phase-slug-unrecognised',
-    /** git could not name the commit HEAD points at (an unborn branch, or no repository). */
-    HEAD_UNRESOLVABLE: 'head-unresolvable',
-    /** The manifest exists and is not a JSON object with an object `phases`; it is left untouched. */
-    MANIFEST_MALFORMED: 'manifest-malformed',
-    /** `record` found no start commit for this phase — `start` never ran for it. */
-    START_NOT_RECORDED: 'start-not-recorded',
-    /** `record` found a start commit that git does not verify. */
-    START_UNVERIFIABLE: 'start-unverifiable',
-    /**
-     * `start` found no anchor for this phase, and its directory already holds a
-     * `*-SUMMARY.md`: the phase has been executed, so HEAD sits AFTER its own
-     * commits and an anchor there would put the phase's work outside its own
-     * range. Nothing is written.
-     */
-    PHASE_ALREADY_EXECUTED: 'phase-already-executed',
-    /** The manifest could not be written (an errno is in `detail`). */
-    WRITE_FAILED: 'write-failed',
-});
-function boundedToken(v) {
-    let s;
-    try {
-        s = typeof v === 'string' ? v : JSON.stringify(v) ?? String(v);
-    }
-    catch {
-        s = String(v);
-    }
-    s = s.replace(/[\r\n]+/g, ' ');
-    return s.length > TOKEN_MAX ? `${s.slice(0, TOKEN_MAX)}…` : s;
-}
-function errnoOf(e) {
-    const code = e?.code;
-    return typeof code === 'string' && code.length > 0 ? boundedToken(code) : 'unknown error';
-}
-/** Is this resolved absolute path the root itself, or somewhere beneath it? */
-function isContainedIn(abs, rootAbs) {
-    return abs === rootAbs || abs.startsWith(rootAbs + node_path_1.default.sep);
-}
-/** The root with every symlinked component resolved (a macOS temp root is `/var` and `/private/var` at once). */
-function resolvedRootOf(rootAbs) {
-    try {
-        return node_fs_1.default.realpathSync(rootAbs);
-    }
-    catch {
-        return rootAbs;
-    }
-}
-/**
- * Is this manifest entry stamped for a DIFFERENT phase directory? Entries are
- * keyed by phase NUMBER, and `/pp-new-milestone --reset-phase-numbers` reuses
- * numbers, so a new milestone's `01-new` would otherwise inherit `01-old`'s
- * anchor and commits. An entry with NO stamp (legacy or hand-written) is not
- * stale.
- */
-function isStaleEntry(entry, slug) {
-    return typeof entry.phaseDir === 'string' && entry.phaseDir !== slug;
-}
-/**
- * Where this phase's manifest lives, or the named ground on which it cannot.
- * `phaseDir` resolves against `cwd`, then against `root`; the first that is an
- * existing directory CONTAINED in the root wins, lexically or with symlinks
- * resolved on both sides.
- */
-function resolveManifestTarget(opts) {
-    const unresolvable = { ok: false, reason: PHASE_MANIFEST_WRITE_REASON.PHASE_DIR_UNRESOLVABLE };
-    if (typeof opts?.root !== 'string' || opts.root === '')
-        return unresolvable;
-    if (typeof opts?.phaseDir !== 'string' || opts.phaseDir === '' || opts.phaseDir.includes('\0'))
-        return unresolvable;
-    const rootLexical = node_path_1.default.resolve(opts.root);
-    const rootReal = resolvedRootOf(rootLexical);
-    const bases = [typeof opts.cwd === 'string' && opts.cwd !== '' ? opts.cwd : process.cwd(), rootLexical];
-    let phaseDirAbs = null;
-    let rootAbs = rootLexical;
-    for (const base of bases) {
-        const abs = node_path_1.default.resolve(base, opts.phaseDir);
-        try {
-            if (!node_fs_1.default.statSync(abs).isDirectory())
-                continue;
-        }
-        catch {
-            continue;
-        }
-        if (isContainedIn(abs, rootLexical)) {
-            phaseDirAbs = abs;
-            rootAbs = rootLexical;
-            break;
-        }
-        const real = resolvedRootOf(abs);
-        if (isContainedIn(real, rootReal)) {
-            phaseDirAbs = real;
-            rootAbs = rootReal;
-            break;
-        }
-    }
-    if (phaseDirAbs === null)
-        return unresolvable;
-    const slugMatch = PHASE_SLUG_SHAPE.exec(node_path_1.default.basename(phaseDirAbs));
-    if (!slugMatch)
-        return { ok: false, reason: PHASE_MANIFEST_WRITE_REASON.PHASE_SLUG_UNRECOGNISED };
-    const manifestAbs = node_path_1.default.join(node_path_1.default.dirname(node_path_1.default.dirname(phaseDirAbs)), PHASE_MANIFEST_FILE);
-    if (!isContainedIn(manifestAbs, rootAbs))
-        return unresolvable;
-    return {
-        ok: true,
-        target: {
-            rootAbs,
-            manifestAbs,
-            manifestPath: node_path_1.default.relative(rootAbs, manifestAbs).split(node_path_1.default.sep).join('/'),
-            rawToken: slugMatch[1],
-            phaseDirAbs,
-            phaseSlug: node_path_1.default.basename(phaseDirAbs),
-        },
-    };
-}
-/**
- * The existing manifest, parsed for an ADDITIVE write — or `null` when it must
- * not be overwritten: unparseable JSON, a non-object document or a non-object
- * `phases`. An absent file is an empty document, not a refusal.
- */
-function readManifestForWrite(manifestAbs) {
-    if (!node_fs_1.default.existsSync(manifestAbs))
-        return { doc: {}, phases: {}, raw: null };
-    try {
-        const raw = node_fs_1.default.readFileSync(manifestAbs, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
-            return null;
-        const doc = parsed;
-        if (doc.phases === undefined)
-            return { doc, phases: {}, raw };
-        if (!doc.phases || typeof doc.phases !== 'object' || Array.isArray(doc.phases))
-            return null;
-        return { doc, phases: doc.phases, raw };
-    }
-    catch {
-        return null;
-    }
-}
-/** The key this phase's entry lives under: an existing spelling wins, else the slug's own token. */
-function manifestKeyFor(phases, rawToken) {
-    const spellings = [rawToken, String(Number(rawToken))];
-    return spellings.find((key) => Object.prototype.hasOwnProperty.call(phases, key)) ?? rawToken;
-}
-/** The entry under `key` as a plain object, `{}` when absent, `null` when present and not an object. */
-function manifestEntryOf(phases, key) {
-    if (!Object.prototype.hasOwnProperty.call(phases, key))
-        return {};
-    const entry = phases[key];
-    return entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : null;
-}
-/** Two-space JSON with a trailing newline — the one serialization, so a re-record is byte-stable. */
-function serializeManifest(doc) {
-    return `${JSON.stringify(doc, null, 2)}\n`;
-}
-/** Write atomically (sibling temp file, then rename). Returns `null` on success, else an errno. */
-function writeManifestAtomic(manifestAbs, serialized) {
-    const tmp = `${manifestAbs}.${process.pid}.tmp`;
-    try {
-        node_fs_1.default.writeFileSync(tmp, serialized, 'utf8');
-        node_fs_1.default.renameSync(tmp, manifestAbs);
-        return null;
-    }
-    catch (err) {
-        try {
-            node_fs_1.default.unlinkSync(tmp);
-        }
-        catch {
-            // Nothing to remove, or it cannot be removed; the refusal stands.
-        }
-        return errnoOf(err);
-    }
-}
-/** Has this phase already been executed? `null` when the directory cannot be listed. */
-function phaseHasSummary(phaseDirAbs) {
-    try {
-        return node_fs_1.default.readdirSync(phaseDirAbs).some((name) => name.endsWith('-SUMMARY.md'));
-    }
-    catch {
-        return null;
-    }
-}
-/** A verified commit sha from a `rev-parse --verify` probe, or `null`. */
-function verifiedSha(exec, rev, cwd) {
-    const probe = exec(['rev-parse', '--verify', rev], { cwd });
-    if (probe.exitCode !== 0 || probe.error)
-        return null;
-    const sha = String(probe.stdout || '').trim();
-    return COMMIT_SHA_SHAPE.test(sha) ? sha : null;
-}
-/** The exclude pattern: the basename, so the flat and the workstream manifests are both covered. */
-const EXCLUDE_LINE = PHASE_MANIFEST_FILE;
-/**
- * Keep the manifest out of git: add `.phase-manifest.json` to the repository's
- * SHARED `info/exclude` (the git common dir, so every linked worktree is
- * covered), never to the project's own committed `.gitignore`. Best effort:
- * returns `added`, `present` or `failed`, and never throws.
- */
-function ensureManifestExcluded(exec, rootAbs) {
-    try {
-        const r = exec(['rev-parse', '--git-common-dir'], { cwd: rootAbs });
-        if (r.exitCode !== 0 || r.error)
-            return 'failed';
-        const common = String(r.stdout || '').trim();
-        if (common === '')
-            return 'failed';
-        const commonAbs = node_path_1.default.resolve(rootAbs, common);
-        const excludeAbs = node_path_1.default.join(commonAbs, 'info', 'exclude');
-        let current = '';
-        try {
-            current = node_fs_1.default.readFileSync(excludeAbs, 'utf8');
-        }
-        catch {
-            current = '';
-        }
-        if (current.split(/\r?\n/).some((line) => line.trim() === EXCLUDE_LINE))
-            return 'present';
-        node_fs_1.default.mkdirSync(node_path_1.default.dirname(excludeAbs), { recursive: true });
-        const sep = current === '' || current.endsWith('\n') ? '' : '\n';
-        node_fs_1.default.appendFileSync(excludeAbs, `${sep}# pp-core: local phase manifest, read by /pp-undo --phase\n${EXCLUDE_LINE}\n`, 'utf8');
-        return 'added';
-    }
-    catch {
-        return 'failed';
-    }
-}
-/**
- * Anchor the phase: `phases[NN].startCommit = HEAD`, WRITE-ONCE.
- *
- *   1. WRITE-ONCE. An entry for THIS phase directory that already carries a
- *      start commit is left byte-identical (`unchanged: true`), so a resume or
- *      a `--gaps-only` run keeps the anchor the phase started from.
- *   2. ALREADY EXECUTED. With no usable anchor, a phase directory that already
- *      holds a `*-SUMMARY.md` is refused (`phase-already-executed`); HEAD on an
- *      executed phase sits after its own commits.
- *   3. STALE. An entry stamped for another phase directory is REPLACED by a
- *      fresh `{ startCommit, phaseDir }`; its old commits are dropped
- *      (`replacedStale: true`).
- *
- * Every write stamps `phaseDir` with the directory basename. Never throws.
- */
-function recordPhaseStart(opts) {
-    const action = 'start';
-    try {
-        const exec = typeof opts?.exec === 'function' ? opts.exec : shell_command_projection_cjs_1.execGit;
-        const resolved = resolveManifestTarget(opts);
-        if (!resolved.ok)
-            return { ok: false, action, reason: resolved.reason };
-        const { target } = resolved;
-        const read = readManifestForWrite(target.manifestAbs);
-        if (read === null)
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.MANIFEST_MALFORMED };
-        const key = manifestKeyFor(read.phases, target.rawToken);
-        const entry = manifestEntryOf(read.phases, key);
-        if (entry === null)
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.MANIFEST_MALFORMED };
-        const stale = isStaleEntry(entry, target.phaseSlug);
-        if (!stale && typeof entry.startCommit === 'string' && COMMIT_SHA_SHAPE.test(entry.startCommit)) {
-            return { ok: true, action, manifestPath: target.manifestPath, phase: key, startCommit: entry.startCommit, unchanged: true };
-        }
-        // Checked before HEAD is read: a refusal asks git nothing.
-        const executed = phaseHasSummary(target.phaseDirAbs);
-        if (executed === null)
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.PHASE_DIR_UNRESOLVABLE };
-        if (executed)
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.PHASE_ALREADY_EXECUTED };
-        const head = verifiedSha(exec, 'HEAD^{commit}', target.rootAbs);
-        if (head === null)
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.HEAD_UNRESOLVABLE };
-        const fresh = stale ? { startCommit: head, phaseDir: target.phaseSlug } : { ...entry, startCommit: head, phaseDir: target.phaseSlug };
-        const doc = { ...read.doc, phases: { ...read.phases, [key]: fresh } };
-        const failure = writeManifestAtomic(target.manifestAbs, serializeManifest(doc));
-        if (failure !== null)
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.WRITE_FAILED, detail: failure };
-        const excluded = ensureManifestExcluded(exec, target.rootAbs);
-        return {
-            ok: true,
-            action,
-            manifestPath: target.manifestPath,
-            phase: key,
-            startCommit: head,
-            unchanged: false,
-            excluded,
-            ...(stale ? { replacedStale: true } : {}),
-        };
-    }
-    catch (err) {
-        return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.WRITE_FAILED, detail: errnoOf(err) };
-    }
-}
-/**
- * Close the phase's range: `phases[NN].commits` =
- * `git rev-list --reverse --no-merges <startCommit>..HEAD`, oldest first.
- * Recomputed from the anchor on every call, so two consecutive records leave
- * the file byte-identical. An empty list is a valid record. No anchor, or an
- * entry stamped for another phase directory, answers `start-not-recorded`.
- * Never throws.
- */
-function recordPhaseCommits(opts) {
-    const action = 'record';
-    try {
-        const exec = typeof opts?.exec === 'function' ? opts.exec : shell_command_projection_cjs_1.execGit;
-        const resolved = resolveManifestTarget(opts);
-        if (!resolved.ok)
-            return { ok: false, action, reason: resolved.reason };
-        const { target } = resolved;
-        const read = readManifestForWrite(target.manifestAbs);
-        if (read === null)
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.MANIFEST_MALFORMED };
-        const key = manifestKeyFor(read.phases, target.rawToken);
-        const entry = manifestEntryOf(read.phases, key);
-        if (entry === null)
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.MANIFEST_MALFORMED };
-        if (isStaleEntry(entry, target.phaseSlug)) {
-            return {
-                ok: false,
-                action,
-                reason: PHASE_MANIFEST_WRITE_REASON.START_NOT_RECORDED,
-                detail: 'the entry under this phase number was recorded for another phase directory',
-            };
-        }
-        const start = entry.startCommit;
-        if (typeof start !== 'string' || !COMMIT_SHA_SHAPE.test(start)) {
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.START_NOT_RECORDED };
-        }
-        if (verifiedSha(exec, `${start}^{commit}`, target.rootAbs) === null) {
-            return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.START_UNVERIFIABLE };
-        }
-        const listed = exec(['rev-list', '--reverse', '--no-merges', `${start}..HEAD`], { cwd: target.rootAbs });
-        if (listed.exitCode !== 0 || listed.error) {
-            return {
-                ok: false,
-                action,
-                reason: PHASE_MANIFEST_WRITE_REASON.HEAD_UNRESOLVABLE,
-                detail: 'git rev-list could not list the commits since the start commit',
-            };
-        }
-        const commits = String(listed.stdout || '')
-            .split('\n')
-            .map((line) => line.trim())
-            .filter((line) => COMMIT_SHA_SHAPE.test(line));
-        const doc = { ...read.doc, phases: { ...read.phases, [key]: { ...entry, commits, phaseDir: target.phaseSlug } } };
-        const serialized = serializeManifest(doc);
-        if (serialized !== read.raw) {
-            const failure = writeManifestAtomic(target.manifestAbs, serialized);
-            if (failure !== null)
-                return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.WRITE_FAILED, detail: failure };
-        }
-        return { ok: true, action, manifestPath: target.manifestPath, phase: key, startCommit: start, commits, commitCount: commits.length };
-    }
-    catch (err) {
-        return { ok: false, action, reason: PHASE_MANIFEST_WRITE_REASON.WRITE_FAILED, detail: errnoOf(err) };
-    }
-}
-/** The one-line operator rendering of a writer result; the workflows print it and continue. */
-function renderManifestResult(result) {
-    const r = (result && typeof result === 'object' ? result : {});
-    if (r.ok !== true)
-        return `Phase manifest not written: ${boundedToken(r.reason ?? 'unknown')}`;
-    const sha7 = typeof r.startCommit === 'string' ? r.startCommit.slice(0, 7) : '';
-    if (r.action === 'record') {
-        return `Phase ${boundedToken(r.phase)}: ${Number(r.commitCount)} commit(s) recorded from ${sha7}..HEAD in ${boundedToken(r.manifestPath)}`;
-    }
-    return (`Phase ${boundedToken(r.phase)} anchored at ${sha7} in ${boundedToken(r.manifestPath)}` +
-        (r.unchanged === true ? ' (already anchored; unchanged)' : '') +
-        (r.replacedStale === true ? ' (replaced a stale entry recorded for another phase directory)' : ''));
-}
-// ─── The reader ───────────────────────────────────────────────────────────────
-/**
- * Why a phase has no usable manifest record. The strings are shared with the
- * write reasons where the fact is the same (an unkeyable slug, an unparseable
- * file), so one fact has one spelling.
- */
-const PHASE_MANIFEST_READ_MISS = Object.freeze({
-    /** The phase directory's name does not begin with an `NN` or `NN.M` token. */
-    PHASE_SLUG_UNRECOGNISED: PHASE_MANIFEST_WRITE_REASON.PHASE_SLUG_UNRECOGNISED,
-    /** No manifest at the writer's location for this phase directory. */
-    MANIFEST_NOT_FOUND: 'manifest-not-found',
-    /** A manifest exists and is not a JSON object with an object `phases`. */
-    MANIFEST_MALFORMED: PHASE_MANIFEST_WRITE_REASON.MANIFEST_MALFORMED,
-    /** The manifest parsed and holds no usable entry for this phase under either key spelling. */
-    PHASE_ENTRY_MISSING: 'phase-entry-missing',
-    /** The phase's entry exists and records neither a start commit nor any commit. */
-    NO_COMMITS_RECORDED: 'no-commits-recorded',
-});
-/** The one sentence a stale entry is disclosed with. */
-function staleEntryNote(key, recorded, slug) {
-    return (`the phase manifest entry "${boundedToken(key)}" is stale: it was recorded for phase directory ` +
-        `"${boundedToken(recorded)}", not "${boundedToken(slug)}" (a phase number reused after a milestone reset), ` +
-        'so its startCommit and commits were ignored');
-}
-/**
- * Read this phase's record from the manifest the writer keeps — the file two
- * levels above the phase directory, the same location `recordPhaseStart`
- * writes — or name the ground on which there is none.
- *
- * Both key spellings (`05` and `5`) are read before answering, so an anchor
- * under one is not hidden by a commit list under the other. An entry stamped
- * for ANOTHER phase directory is stale (a phase number reused after a
- * milestone reset): it is no record for this phase, and it is disclosed in
- * `notes`. An unstamped (legacy) entry counts as this phase's. A manifest
- * location outside `root` is never read. Pure read; never throws.
- */
-function readPhaseManifestEntry(opts) {
-    const none = (miss, notes = []) => ({ commits: [], startCommit: null, miss, notes });
-    try {
-        const phaseDirAbs = node_path_1.default.resolve(opts.phaseDir);
-        const slug = node_path_1.default.basename(phaseDirAbs);
-        const slugMatch = PHASE_SLUG_SHAPE.exec(slug);
-        if (!slugMatch)
-            return none(PHASE_MANIFEST_READ_MISS.PHASE_SLUG_UNRECOGNISED);
-        const manifestAbs = node_path_1.default.join(node_path_1.default.dirname(node_path_1.default.dirname(phaseDirAbs)), PHASE_MANIFEST_FILE);
-        const rootAbs = node_path_1.default.resolve(opts.root);
-        if (!isContainedIn(manifestAbs, rootAbs) && !isContainedIn(resolvedRootOf(node_path_1.default.dirname(manifestAbs)), resolvedRootOf(rootAbs))) {
-            return none(PHASE_MANIFEST_READ_MISS.MANIFEST_NOT_FOUND);
-        }
-        if (!node_fs_1.default.existsSync(manifestAbs))
-            return none(PHASE_MANIFEST_READ_MISS.MANIFEST_NOT_FOUND);
-        let phases;
-        try {
-            const parsed = JSON.parse(node_fs_1.default.readFileSync(manifestAbs, 'utf8'));
-            const candidate = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed.phases : undefined;
-            if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
-                return none(PHASE_MANIFEST_READ_MISS.MANIFEST_MALFORMED);
-            phases = candidate;
-        }
-        catch {
-            return none(PHASE_MANIFEST_READ_MISS.MANIFEST_MALFORMED);
-        }
-        const rawToken = slugMatch[1];
-        const keys = [...new Set([rawToken, String(Number(rawToken))])];
-        const notes = [];
-        let present = false;
-        let startCommit = null;
-        let commits = null;
-        for (const key of keys) {
-            if (!Object.prototype.hasOwnProperty.call(phases, key))
-                continue;
-            const entry = phases[key];
-            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
-                continue;
-            const record = entry;
-            if (isStaleEntry(record, slug)) {
-                notes.push(staleEntryNote(key, record.phaseDir, slug));
-                continue;
-            }
-            present = true;
-            if (startCommit === null && typeof record.startCommit === 'string' && COMMIT_SHA_SHAPE.test(record.startCommit)) {
-                startCommit = record.startCommit;
-            }
-            if (commits === null && Array.isArray(record.commits) && record.commits.length > 0) {
-                commits = record.commits.filter((c) => typeof c === 'string');
-            }
-        }
-        if (commits !== null || startCommit !== null)
-            return { commits: commits ?? [], startCommit, miss: null, notes };
-        return none(present ? PHASE_MANIFEST_READ_MISS.NO_COMMITS_RECORDED : PHASE_MANIFEST_READ_MISS.PHASE_ENTRY_MISSING, notes);
-    }
-    catch {
-        return none(PHASE_MANIFEST_READ_MISS.MANIFEST_NOT_FOUND);
-    }
-}
-module.exports = {
-    PHASE_MANIFEST_FILE,
-    PHASE_MANIFEST_WRITE_REASON,
-    PHASE_MANIFEST_READ_MISS,
-    COMMIT_SHA_SHAPE,
-    readPhaseManifestEntry,
-    recordPhaseStart,
-    recordPhaseCommits,
-    renderManifestResult,
-};