@pareto4/pp-core 1.12.1 → 1.13.0

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

@@ -0,0 +1,527 @@
+"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,
+};

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

@@ -4,7 +4,8 @@
  *
  * A tier is a named preset over the existing gate booleans
  * `workflow.{research, pattern_mapper, plan_check, verifier,
- * nyquist_validation, code_review, post_planning_gaps, security_enforcement}`:
+ * nyquist_validation, code_review, post_planning_gaps, security_enforcement,
+ * vault_review}`:
  *
  *   light    — planner and executor only; every gate off.
  *   standard — verifier and code review (with its fix loop) on, plan checker
@@ -14,6 +15,11 @@
  *              bounce on, and the fresh-install verification slot
  *              (`install_verification`).
  *
+ * `vault_review` is the agent practice review (`pp-vault-reviewer`): on only in
+ * heavy, and spawned only where the project's vault practices apply
+ * (`vaultReviewApplies`, src/vault.cts). The vault's load, trace and audit gates
+ * are NOT tier gates: they are cheap code checks and run in every tier.
+ *
  * ## Precedence (`resolvePhaseTier`)
  *
  *   CLI `--tier` > the phase's ROADMAP entry `**Tier:**` field > project
@@ -32,7 +38,8 @@
  *
  * ## Proposal (`proposePhaseTier`)
  *
- *   heavy    — a plan touches a gate, init, redaction, config-precedence or
+ *   heavy    — a plan touches a gate (the vault's gate, verdict and redaction
+ *              owners included), init, redaction, config-precedence or
  *              hook-dispatch file (`HEAVY_PATH_RULES`), or — before any plan
  *              exists — the requirement tags or ROADMAP text name one
  *              (`HEAVY_TEXT_RULES`);
@@ -83,6 +90,7 @@ exports.TIER_GATE_KEYS = [
     'code_review',
     'post_planning_gaps',
     'security_enforcement',
+    'vault_review',
 ];
 /**
  * The plan-checker loop's current maximum: plan-phase §12 "Revision Loop (Max
@@ -184,6 +192,11 @@ exports.HEAVY_PATH_RULES = Object.freeze([
     { category: 'gate', example: 'src/ui-safety-gate.cts', pattern: new RegExp(`${LIB}(?:[^/]+/)*[^/]*gate[^/]*\\.c?[jt]s$`) },
     { category: 'gate', example: 'src/check-command-router.cts', pattern: new RegExp(`${LIB}(?:check-command-router|prohibition-enforcement|gap-checker|plan-graph|dispatch-plan)\\.c?[jt]s$`) },
     { category: 'gate', example: 'src/practices-review-check.cts', pattern: new RegExp(`${LIB}[^/]+-(?:check|guard)\\.c?[jt]s$`) },
+    // The vault's gate, verdict and redaction owners (`vault`, `vault-trace`,
+    // `vault-audit`, `vault-review`, `vault-practices`, …): a phase editing them
+    // changes what the load, trace and audit gates decide and what remote text is
+    // redacted, so it is proposed heavy.
+    { category: 'gate', example: 'src/vault.cts', pattern: new RegExp(`${LIB}vault[^/]*\\.c?[jt]s$`) },
     { category: 'init', example: 'src/init.cts', pattern: new RegExp(`${LIB}init[^/]*\\.c?[jt]s$`) },
     { category: 'redaction', example: 'src/observability/redaction.cts', pattern: /(?:^|\/)[^/]*(?:redact|secret)[^/]*$/i },
     { category: 'config-precedence', example: 'src/config-loader.cts', pattern: new RegExp(`${LIB}(?:config[^/]*|configuration|federated-config|capability-activation|phase-tier)\\.c?[jt]s$`) },

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

@@ -60,6 +60,10 @@ const plan_graph_cjs_1 = require("./plan-graph.cjs");
 const dispatch_plan_cjs_1 = require("./dispatch-plan.cjs");
 const phase_tier_cjs_1 = require("./phase-tier.cjs");
 const install_run_cjs_1 = require("./install-run.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- loop-resolver.cjs is an export= CommonJS module
+const loopResolver = require("./loop-resolver.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-manifest.cjs is an export= CommonJS module
+const phaseManifest = require("./phase-manifest.cjs");
 const { planningDir, withPlanningLock, milestonePathsFor } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 const { readModifyWriteStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, syncStateFrontmatter, withStateLock, updatePerformanceMetricsSection, } = stateMod;
@@ -452,7 +456,22 @@ function cmdPhaseDispatchPlan(cwd, args, raw) {
     });
     const phaseDirRel = node_path_1.default.relative(cwd, built.phaseDir).split(node_path_1.default.sep).join('/');
     const tier = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, parsed.phase, parsed.tier);
-    output((0, dispatch_plan_cjs_1.computeDispatchPlan)(built.result['phase'], phaseDirRel, plans, policy, tier, { planBounceScript: tier.plan_bounce_script }), raw);
+    // The executor brief: active execute:pre `into: executor` contributions,
+    // resolved by the loop resolver under this phase's tier. An unreadable config
+    // refuses here exactly as `loop render-hooks` does — a brief computed from
+    // swallowed defaults would silently drop a capability's executor contract.
+    const hooks = loopResolver.resolveProjectLoopHooks(cwd, 'execute:pre', { phaseTier: tier, what: 'phase.dispatch-plan' });
+    if (!hooks.ok) {
+        error(hooks.message, hooks.reason === 'config_unreadable' ? ERROR_REASON.CONFIG_PARSE_FAILED : undefined);
+        return;
+    }
+    const executorContributions = loopResolver.contributionsInto(hooks.resolved, 'executor');
+    // The agent practice review's one applicability predicate (src/vault.cts),
+    // required lazily: only this command needs the vault module here.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const vaultMod = require('./vault.cjs');
+    const vaultReview = vaultMod.vaultReviewApplies(cwd);
+    output((0, dispatch_plan_cjs_1.computeDispatchPlan)(built.result['phase'], phaseDirRel, plans, policy, tier, { planBounceScript: tier.plan_bounce_script, vaultReview, executorContributions }), raw);
 }
 /**
  * `phase.install-run <phase> [--tarball <tgz>] [--package-dir <dir>] [--no-build]`:
@@ -479,6 +498,36 @@ function cmdPhaseInstallRun(cwd, args, raw) {
  * `phase.tier <phase> [--tier light|standard|heavy]`: the phase's resolved
  * ceremony tier — tier, source, gate set, suppressed gates (src/phase-tier.cts).
  */
+/**
+ * `phase.manifest start|record <phase>`: write `.phase-manifest.json`, the
+ * file `/pp-undo --phase` reads (src/phase-manifest.cts). `start` anchors the
+ * phase at HEAD (write-once); `record` lists `<startCommit>..HEAD`. Always
+ * exits 0: a refusal is reported (`ok: false`, `reason`) and the caller
+ * continues — `/pp-undo` then falls back to its git-log search.
+ */
+function cmdPhaseManifest(cwd, args, raw) {
+    const usage = 'Usage: phase manifest start|record <phase>';
+    const positional = args.filter((a) => a !== '--raw');
+    const action = positional[0];
+    const phaseArg = positional[1];
+    if ((action !== 'start' && action !== 'record') || !phaseArg || positional.length > 2) {
+        error(usage, ERROR_REASON.USAGE);
+        return;
+    }
+    const built = buildPhasePlanIndex(cwd, phaseArg);
+    if (built.fatal !== undefined) {
+        error(built.fatal);
+        return;
+    }
+    if (built.phaseDir === null) {
+        const result = { ok: false, action, reason: phaseManifest.PHASE_MANIFEST_WRITE_REASON.PHASE_DIR_UNRESOLVABLE };
+        output(result, raw, phaseManifest.renderManifestResult(result));
+        return;
+    }
+    const opts = { root: cwd, phaseDir: built.phaseDir, cwd };
+    const result = action === 'start' ? phaseManifest.recordPhaseStart(opts) : phaseManifest.recordPhaseCommits(opts);
+    output(result, raw, phaseManifest.renderManifestResult(result));
+}
 function cmdPhaseTier(cwd, args, raw) {
     const usage = 'Usage: phase tier <phase> [--tier light|standard|heavy]';
     const parsed = (0, phase_tier_cjs_1.parseTierFlag)(args.filter((a) => a !== '--raw'));
@@ -1661,6 +1710,7 @@ module.exports = {
     cmdPhaseInstallRun,
     cmdPhaseTier,
     cmdPhaseTierPropose,
+    cmdPhaseManifest,
     cmdPhaseAdd,
     cmdPhaseAddBatch,
     cmdPhaseMvpMode,