@opengsd/gsd-core 1.18.0 → 1.20.0

package/gsd-core/bin/lib/milestone-release-tags.cjs

@@ -0,0 +1,440 @@
+"use strict";
+/**
+ * Milestone Release Tags — #5705 (epic #3628, Phase 1).
+ *
+ * `gsd-tools milestone release-tags --map <file> [--dry-run]`: preflight and
+ * create annotated tags across the repositories listed in `sub_repos` from a
+ * caller-supplied map `[{ repo, tag, ref?, message?, skip? }]`.
+ *
+ * Contract (the result shape is read by Phases 2-3 of the epic, so it is fixed
+ * here and pinned by tests):
+ *
+ *   { ok, phase: 'preflight' | 'apply' | 'dry_run',
+ *     repos: { [key]: { status, tag?, commit?, reason?, error?,
+ *                       existing_commit?, requested_commit?, detached_head? } },
+ *     created: string[],            // "repo:tag" for every tag written
+ *     errors: [{ repo?, tag?, reason, error? }] }
+ *
+ * `key` is the normalized repo path. When one repo receives more than one
+ * non-skipped entry (two tags), every entry of that repo is keyed `repo:tag`
+ * instead, so no result is overwritten.
+ *
+ * Every entry is preflighted before the first write, so a predictable failure
+ * (unknown repo, bad tag name, unresolved ref, conflicting tag) writes nothing
+ * anywhere. Tag creation itself is not transactional across repositories: a
+ * failure after the first write is reported with the list of tags already
+ * written (`created`), never rolled back, and a re-run with the same map
+ * reports those tags as `already_tagged` and retries only the failed ones.
+ *
+ * Nothing is pushed, no existing tag is ever overwritten, and every git call is
+ * an argv array run with the target repository as cwd under a 15 s bound.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELEASE_TAG_REASONS = exports.MAX_RELEASE_TAG_ENTRIES = void 0;
+exports.preflightReleaseTags = preflightReleaseTags;
+exports.createReleaseTags = createReleaseTags;
+exports.cmdMilestoneReleaseTags = cmdMilestoneReleaseTags;
+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");
+const security_cjs_1 = require("./security.cjs");
+const command_arg_projection_cjs_1 = require("./command-arg-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output, ERROR_REASON } = ioMod;
+const error = ioMod.error;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderMod = require("./config-loader.cjs");
+const { loadConfig } = configLoaderMod;
+// ─── Constants ────────────────────────────────────────────────────────────
+/** Maximum entries accepted in one request. Exactly this many are accepted. */
+exports.MAX_RELEASE_TAG_ENTRIES = 256;
+/** Bound on every git subprocess (ms). */
+const RELEASE_TAG_GIT_TIMEOUT_MS = 15000;
+/** Largest `--map` file read from disk (bytes). */
+const MAX_MAP_FILE_BYTES = 1_048_576;
+/** Every reason code this module can emit — a closed set, pinned against CONTEXT.md. */
+exports.RELEASE_TAG_REASONS = Object.freeze([
+    'no_sub_repos',
+    'invalid_request',
+    'too_many_entries',
+    'repo_not_configured',
+    'repo_path_invalid',
+    'repo_missing',
+    'not_a_git_repo',
+    'tag_invalid',
+    'ref_unresolved',
+    'tag_conflict',
+    'duplicate_entry',
+    'git_timeout',
+    'tag_create_failed',
+]);
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function newResult(phase) {
+    // Null prototype: a hostile repo key such as `__proto__` is plain data.
+    return { ok: true, phase, repos: Object.create(null), created: [], errors: [] };
+}
+function topLevelError(reason, message) {
+    const result = newResult('preflight');
+    result.ok = false;
+    result.errors.push({ reason, error: message });
+    return result;
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Normalize a repository path to a forward-slash relative form, or null when
+ * it is absolute, contains a `..` segment (either separator), a NUL, or is
+ * empty. Backslashes are converted FIRST so `a\..\b` cannot slip past.
+ */
+function normalizeRepoPath(raw) {
+    const s = raw.replace(/\\/g, '/');
+    if (s === '' || s.includes('\0') || s.startsWith('/') || /^[A-Za-z]:/.test(s))
+        return null;
+    const segments = s.split('/');
+    if (segments.includes('..'))
+        return null;
+    const kept = segments.filter((seg) => seg !== '' && seg !== '.');
+    return kept.length === 0 ? null : kept.join('/');
+}
+function readSubRepos(cwd) {
+    const config = loadConfig(cwd);
+    const raw = config['sub_repos'];
+    const out = new Set();
+    if (!Array.isArray(raw))
+        return out;
+    for (const item of raw) {
+        if (typeof item !== 'string')
+            continue;
+        const n = normalizeRepoPath(item);
+        if (n !== null)
+            out.add(n);
+    }
+    return out;
+}
+/** Validate request shape. Returns a top-level failure, or null when well-formed. */
+function validateRequest(entries) {
+    if (!Array.isArray(entries)) {
+        return topLevelError('invalid_request', 'request must be a JSON array of entry objects');
+    }
+    if (entries.length > exports.MAX_RELEASE_TAG_ENTRIES) {
+        return topLevelError('too_many_entries', `request has ${entries.length} entries; the limit is ${exports.MAX_RELEASE_TAG_ENTRIES}`);
+    }
+    const result = newResult('preflight');
+    entries.forEach((entry, index) => {
+        const where = `entry ${index}`;
+        if (!isPlainObject(entry)) {
+            result.errors.push({ reason: 'invalid_request', error: `${where}: must be an object` });
+            return;
+        }
+        if (typeof entry['repo'] !== 'string') {
+            result.errors.push({ reason: 'invalid_request', error: `${where}: "repo" must be a string` });
+            return;
+        }
+        const repo = entry['repo'];
+        if (entry['skip'] === true)
+            return;
+        if (entry['skip'] !== undefined && typeof entry['skip'] !== 'boolean') {
+            result.errors.push({ repo, reason: 'invalid_request', error: `${where}: "skip" must be a boolean` });
+        }
+        if (typeof entry['tag'] !== 'string') {
+            result.errors.push({ repo, reason: 'invalid_request', error: `${where}: "tag" must be a string` });
+        }
+        for (const field of ['ref', 'message']) {
+            if (entry[field] !== undefined && typeof entry[field] !== 'string') {
+                result.errors.push({ repo, reason: 'invalid_request', error: `${where}: "${field}" must be a string` });
+            }
+        }
+    });
+    if (result.errors.length > 0) {
+        result.ok = false;
+        return result;
+    }
+    return null;
+}
+// ─── Preflight ────────────────────────────────────────────────────────────
+function runPreflight(cwd, entries, options, phase) {
+    const shape = validateRequest(entries);
+    if (shape)
+        return { result: shape, plans: [] };
+    const list = entries;
+    const exec = options.execGit ?? shell_command_projection_cjs_1.execGit;
+    const timeout = options.timeoutMs ?? RELEASE_TAG_GIT_TIMEOUT_MS;
+    const run = (dir, args) => exec(args, { cwd: dir, timeout });
+    const subRepos = readSubRepos(cwd);
+    if (subRepos.size === 0) {
+        return { result: topLevelError('no_sub_repos', 'no sub_repos configured in .planning/config.json'), plans: [] };
+    }
+    // A repo that receives more than one non-skipped entry is keyed `repo:tag`.
+    const perRepo = new Map();
+    for (const entry of list) {
+        if (entry.skip === true)
+            continue;
+        const k = normalizeRepoPath(entry.repo) ?? entry.repo;
+        perRepo.set(k, (perRepo.get(k) ?? 0) + 1);
+    }
+    // A repo given both a skip entry and a tag entry is contradictory; the check is
+    // order-independent so preflight never reports `skipped` for a repo that gets tagged.
+    const skippedRepos = new Set();
+    for (const entry of list) {
+        if (entry.skip === true)
+            skippedRepos.add(normalizeRepoPath(entry.repo) ?? entry.repo);
+    }
+    const result = newResult(phase);
+    const plans = [];
+    const seen = new Set();
+    for (const entry of list) {
+        const rawRepo = entry.repo;
+        const normalized = normalizeRepoPath(rawRepo);
+        const repo = normalized ?? rawRepo;
+        if (entry.skip === true) {
+            const skipKey = `skip\0${repo}`;
+            if (seen.has(skipKey)) {
+                result.ok = false;
+                result.errors.push({ repo, reason: 'duplicate_entry' });
+            }
+            else {
+                seen.add(skipKey);
+                // When the repo also has a tag entry, that entry records the duplicate_entry error
+                // under the same key; writing `skipped` here would overwrite it order-dependently.
+                if ((perRepo.get(repo) ?? 0) === 0)
+                    result.repos[repo] = { status: 'skipped' };
+            }
+            continue;
+        }
+        const tag = entry.tag;
+        const key = (perRepo.get(repo) ?? 0) > 1 ? `${repo}:${tag}` : repo;
+        const fail = (reason, extra = {}) => {
+            result.ok = false;
+            result.repos[key] = { status: 'error', tag, reason, ...extra };
+            result.errors.push({ repo, tag, reason, ...(extra.error ? { error: extra.error } : {}) });
+        };
+        if (skippedRepos.has(repo)) {
+            fail('duplicate_entry', { error: 'repo has both a skip entry and a tag entry' });
+            continue;
+        }
+        if (normalized === null || (0, security_cjs_1.tryWithinRoot)(normalized, cwd) === null) {
+            fail('repo_path_invalid', { error: 'repo path must be relative and stay inside the project root' });
+            continue;
+        }
+        if (!subRepos.has(normalized)) {
+            fail('repo_not_configured', { error: 'repo is not listed in sub_repos' });
+            continue;
+        }
+        const pairKey = `${normalized}\0${tag}`;
+        if (seen.has(pairKey)) {
+            result.ok = false;
+            result.errors.push({ repo, tag, reason: 'duplicate_entry' });
+            continue;
+        }
+        seen.add(pairKey);
+        const dir = node_path_1.default.join(cwd, normalized);
+        let isDir = false;
+        try {
+            isDir = node_fs_1.default.statSync(dir).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir) {
+            fail('repo_missing', { error: 'repo directory does not exist' });
+            continue;
+        }
+        const top = run(dir, ['rev-parse', '--show-toplevel']);
+        if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(top)) {
+            fail('git_timeout', { error: 'git rev-parse timed out' });
+            continue;
+        }
+        let isOwnWorkTree = false;
+        if (top.exitCode === 0) {
+            try {
+                // `.native` expands Windows 8.3 short names (RUNNER~1) the way git's long-form path does.
+                isOwnWorkTree = node_fs_1.default.realpathSync.native(top.stdout) === node_fs_1.default.realpathSync.native(dir);
+            }
+            catch {
+                isOwnWorkTree = false;
+            }
+        }
+        if (!isOwnWorkTree) {
+            fail('not_a_git_repo', { error: 'directory is not the root of a git work tree' });
+            continue;
+        }
+        if (tag === '' || tag.startsWith('-') || tag.includes('\0')) {
+            fail('tag_invalid', { error: 'tag name is empty or starts with "-"' });
+            continue;
+        }
+        const fmt = run(dir, ['check-ref-format', `refs/tags/${tag}`]);
+        if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(fmt)) {
+            fail('git_timeout', { error: 'git check-ref-format timed out' });
+            continue;
+        }
+        if (fmt.exitCode !== 0) {
+            fail('tag_invalid', { error: 'tag name rejected by git check-ref-format' });
+            continue;
+        }
+        const refOmitted = entry.ref === undefined;
+        const ref = entry.ref ?? 'HEAD';
+        if (ref === '' || ref.startsWith('-') || ref.includes('\0')) {
+            fail('ref_unresolved', { error: 'ref is empty or starts with "-"' });
+            continue;
+        }
+        const resolved = run(dir, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+        if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(resolved)) {
+            fail('git_timeout', { error: 'git rev-parse timed out' });
+            continue;
+        }
+        if (resolved.exitCode !== 0 || resolved.stdout === '') {
+            fail('ref_unresolved', { error: `ref "${ref}" does not resolve to a commit` });
+            continue;
+        }
+        const commit = resolved.stdout;
+        let detached;
+        if (refOmitted) {
+            const head = run(dir, ['symbolic-ref', '-q', 'HEAD']);
+            if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(head)) {
+                fail('git_timeout', { error: 'git symbolic-ref timed out' });
+                continue;
+            }
+            if (head.exitCode === 1)
+                detached = true;
+        }
+        const existing = run(dir, ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}^{commit}`]);
+        if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(existing)) {
+            fail('git_timeout', { error: 'git rev-parse timed out' });
+            continue;
+        }
+        if (existing.exitCode === 0 && existing.stdout !== '') {
+            if (existing.stdout === commit) {
+                result.repos[key] = { status: 'already_tagged', tag, commit, ...(detached ? { detached_head: true } : {}) };
+            }
+            else {
+                fail('tag_conflict', {
+                    error: 'tag already exists at a different commit',
+                    existing_commit: existing.stdout,
+                    requested_commit: commit,
+                });
+            }
+            continue;
+        }
+        const anyRef = run(dir, ['show-ref', '--verify', '--quiet', `refs/tags/${tag}`]);
+        if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(anyRef)) {
+            fail('git_timeout', { error: 'git show-ref timed out' });
+            continue;
+        }
+        if (anyRef.exitCode === 0) {
+            fail('tag_conflict', {
+                error: 'tag already exists and does not point at a commit',
+                existing_commit: null,
+                requested_commit: commit,
+            });
+            continue;
+        }
+        result.repos[key] = { status: 'would_create', tag, commit, ...(detached ? { detached_head: true } : {}) };
+        plans.push({
+            key,
+            repo: normalized,
+            dir,
+            tag,
+            message: entry.message === undefined || entry.message === '' ? tag : entry.message,
+            commit,
+            ...(detached ? { detached: true } : {}),
+        });
+    }
+    return { result, plans };
+}
+/** Validate a request without writing anything. */
+function preflightReleaseTags(cwd, entries, options = {}) {
+    return runPreflight(cwd, entries, options, 'preflight').result;
+}
+/**
+ * Preflight, then (unless `dryRun`) create each annotated tag in its own repo.
+ * A preflight failure returns before any write. A creation failure does not
+ * stop the remaining repos; the result lists every tag already written.
+ */
+function createReleaseTags(cwd, entries, options = {}) {
+    const dryRun = options.dryRun === true;
+    const { result, plans } = runPreflight(cwd, entries, options, dryRun ? 'dry_run' : 'apply');
+    if (!result.ok) {
+        result.phase = 'preflight';
+        return result;
+    }
+    if (dryRun)
+        return result;
+    const exec = options.execGit ?? shell_command_projection_cjs_1.execGit;
+    const timeout = options.timeoutMs ?? RELEASE_TAG_GIT_TIMEOUT_MS;
+    for (const plan of plans) {
+        const r = exec(['tag', '-a', '--message', plan.message, '--', plan.tag, plan.commit], { cwd: plan.dir, timeout });
+        if (r.exitCode === 0) {
+            result.repos[plan.key] = {
+                status: 'created',
+                tag: plan.tag,
+                commit: plan.commit,
+                ...(plan.detached ? { detached_head: true } : {}),
+            };
+            result.created.push(`${plan.repo}:${plan.tag}`);
+            continue;
+        }
+        const reason = (0, shell_command_projection_cjs_1.isSpawnTimeout)(r) ? 'git_timeout' : 'tag_create_failed';
+        const message = r.stderr || r.stdout || ((0, shell_command_projection_cjs_1.isSpawnTimeout)(r) ? 'git tag timed out' : 'git tag failed');
+        result.ok = false;
+        result.repos[plan.key] = { status: 'failed', tag: plan.tag, commit: plan.commit, reason, error: message };
+        result.errors.push({ repo: plan.repo, tag: plan.tag, reason, error: message });
+    }
+    return result;
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────
+/**
+ * `milestone release-tags --map <file> [--dry-run]`. `args` is the full argv
+ * tail (`['milestone', 'release-tags', ...flags]`). Prints the result as JSON
+ * and sets a non-zero exit code when `ok` is false.
+ */
+function cmdMilestoneReleaseTags(cwd, args, raw) {
+    const parsed = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['map'], booleanFlags: ['dry-run'], positionals: 2 }, error);
+    const mapArg = parsed['map'];
+    if (typeof mapArg !== 'string' || mapArg === '') {
+        error('--map <path-to-json-file> required for milestone release-tags', ERROR_REASON.USAGE);
+        return;
+    }
+    // A relative --map is relative to the shell's working directory, not the project root.
+    const mapPath = node_path_1.default.resolve(process.cwd(), mapArg);
+    let mapStat = null;
+    let statError = '';
+    try {
+        mapStat = node_fs_1.default.statSync(mapPath);
+    }
+    catch (e) {
+        statError = e instanceof Error ? e.message : String(e);
+    }
+    if (mapStat === null) {
+        error(`cannot read --map file: ${statError}`, ERROR_REASON.USAGE);
+        return;
+    }
+    // A FIFO or device reports size 0 and would bypass the size cap on read.
+    if (!mapStat.isFile()) {
+        error('--map must be a regular file', ERROR_REASON.USAGE);
+        return;
+    }
+    if (mapStat.size > MAX_MAP_FILE_BYTES) {
+        error(`--map file exceeds ${MAX_MAP_FILE_BYTES} byte limit (got ${mapStat.size})`, ERROR_REASON.USAGE);
+        return;
+    }
+    let text = '';
+    try {
+        text = node_fs_1.default.readFileSync(mapPath, 'utf-8');
+    }
+    catch (e) {
+        error(`cannot read --map file: ${e instanceof Error ? e.message : String(e)}`, ERROR_REASON.USAGE);
+        return;
+    }
+    const json = (0, security_cjs_1.safeJsonParse)(text, { maxLength: MAX_MAP_FILE_BYTES, label: '--map file' });
+    const result = json.ok
+        ? createReleaseTags(cwd, json.value, { dryRun: parsed['dry-run'] === true })
+        : topLevelError('invalid_request', json.error);
+    output(result, raw);
+    if (!result.ok)
+        process.exitCode = 1;
+}

package/gsd-core/bin/lib/milestone.cjs

@@ -38,8 +38,9 @@ const stateContract = require("./state-contract.cjs");
 const { publishStateContract } = stateContract;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs, isSentinelPhaseId, isSentinelPhaseDir, buildPhaseHeadingScanRegex, PHASE_HEADING_BASELINE } = phaseIdMod;
+const { isSentinelPhaseId, isSentinelPhaseDir, buildPhaseHeadingScanRegex, PHASE_HEADING_BASELINE } = phaseIdMod;
 const pattern_cjs_1 = require("./pattern.cjs");
+const milestone_release_map_cjs_1 = require("./milestone-release-map.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
 const { getMilestonePhaseFilter, extractCurrentMilestone, getMilestoneInfo, sliceMilestoneWindow, } = roadmapParserMod;
@@ -54,7 +55,7 @@ const planScanMod = require("./plan-scan.cjs");
 const { scanPhasePlans } = planScanMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { listMilestonePhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, listMilestonePhaseDirs, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
 const { planningPaths, resolvePhaseIdConvention } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 // ADR-3408 §8.3 / #3469: `writeStateMd` gets sync and NO preservation — the
@@ -72,43 +73,6 @@ const { syncAndPreserveStateMd, withStateLock, readModifyWriteStateMd, assertVer
 // the caller-supplied `--archive-version` override and the STATE.md-derived
 // live-read value, so a crafted value cannot escape `.planning/milestones/`.
 const ARCHIVE_VERSION_LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-/**
- * Scope an `updateTableCell` call to the `## Traceability` (or
- * `## Traceability Status`) heading's own section — up to the next H1/H2
- * heading — instead of handing it the WHOLE REQUIREMENTS.md content.
- *
- * F1 (#2245 review, BLOCKER): `updateTableCell` binds to the FIRST GFM table
- * found in whatever text it is given. The shipped requirements template
- * (gsd-core/templates/requirements.md) puts an `## Out of Scope` table
- * (`| Feature | Reason |`, no `Status` column) BEFORE `## Traceability` — so
- * an unscoped whole-file call targets the Out-of-Scope table instead, fails
- * with `{ok:false, reason:'unknown column: Status'}`, and the real
- * Traceability row is never flipped, while the checkbox surface still flips
- * and the command reports success (the #2140 silent-divergence class one
- * level deeper). Mirrors phase.cts's `editProgressHeadingSlice` scoping of
- * `## Progress` writes to that heading's own slice.
- *
- * Falls back to running `updateTableCell` against the whole `text` when no
- * `## Traceability` heading exists — matching the previous (unscoped)
- * behaviour for a REQUIREMENTS.md whose traceability table sits under some
- * other heading, or with no heading at all (never worse than before this fix).
- */
-function updateTraceabilityCell(text, match, column, newValue) {
-    const headingMatch = text.match(/^##[ \t]+Traceability(?:[ \t]+Status)?\b/im);
-    if (!headingMatch || headingMatch.index === undefined) {
-        return (0, markdown_table_cjs_1.updateTableCell)(text, match, column, newValue);
-    }
-    const headingOffset = headingMatch.index;
-    const before = text.slice(0, headingOffset);
-    const fromHeading = text.slice(headingOffset);
-    const nextHeadingOffset = fromHeading.search(/\n#{1,2}[ \t]/);
-    const scoped = nextHeadingOffset >= 0 ? fromHeading.slice(0, nextHeadingOffset) : fromHeading;
-    const after = nextHeadingOffset >= 0 ? fromHeading.slice(nextHeadingOffset) : '';
-    const result = (0, markdown_table_cjs_1.updateTableCell)(scoped, match, column, newValue);
-    if (!result.ok)
-        return result;
-    return { ok: true, value: before + result.value + after };
-}
 function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     if (!reqIdsRaw || reqIdsRaw.length === 0) {
         error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
@@ -186,7 +150,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         // Complete" gate is folded into the newValue callback so one
         // updateTableCell call both probes the current value and writes.
         let tableHit = false;
-        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const tableUpdate = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             // #2788: accept `Gaps Found` as a forward input too — `revert-phase` (the
             // documented gaps_found response) leaves a row stranded at Gaps Found with
             // no inverse; a genuinely-satisfied requirement must be able to reach
@@ -229,7 +193,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         // that genuinely exists. Probe via a no-op updateTableCell write (its own
         // tolerant scan) instead of findTableWithColumns (whole-table parse gate).
         let currentStatusCell = '';
-        const statusProbe = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const statusProbe = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             currentStatusCell = current;
             return current;
         });
@@ -433,7 +397,7 @@ function cmdRequirementsRevertPhase(cwd, reqIdsRaw, raw) {
         // "only flip Pending -> Complete" gate, in reverse).
         const rowMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === reqId.toLowerCase();
         let tableHit = false;
-        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const tableUpdate = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             if (/^complete$/i.test(current.trim())) {
                 tableHit = true;
                 return ' Gaps Found ';
@@ -524,6 +488,41 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     const phasesDir = planningPaths(cwd).phases;
     const today = clock_cjs_1.realClock.localToday();
     const milestoneName = options.name || version;
+    // #5706 (epic #3628): validate the caller-supplied release map BEFORE any
+    // read-for-decision or write below, so a bad map leaves the tree untouched
+    // (no archive directory, no MILESTONES.md or STATE.md change). An archived
+    // map is a recorded value: a differing map for an already-archived version is
+    // refused rather than silently overwritten; an identical one is left as is.
+    let releaseMap = null;
+    let releaseMapFile = null;
+    let releaseMapNeedsWrite = false;
+    if (typeof options.releaseMap === 'string') {
+        const loaded = (0, milestone_release_map_cjs_1.loadReleaseMapFile)(node_path_1.default.resolve(cwd, options.releaseMap));
+        if (!loaded.ok) {
+            error(`milestone complete: invalid --release-map — nothing has been changed.\n${loaded.errors.map((e) => `  - ${e}`).join('\n')}`);
+        }
+        else {
+            releaseMap = loaded.map;
+            releaseMapFile = (0, milestone_release_map_cjs_1.releaseMapArchivePath)(archiveDir, version);
+            const serialized = (0, milestone_release_map_cjs_1.serializeReleaseMapArchive)(version, releaseMap);
+            let existingText = null;
+            try {
+                existingText = node_fs_1.default.readFileSync(releaseMapFile, 'utf-8');
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT') {
+                    error(`milestone complete: ${node_path_1.default.basename(releaseMapFile)} already exists and cannot be read — nothing has been changed.`);
+                }
+            }
+            if (existingText !== null && existingText !== serialized) {
+                error(`milestone complete: ${node_path_1.default.basename(releaseMapFile)} already exists with a different release map; the archived map is a recorded value and is not overwritten — nothing has been changed.`);
+            }
+            releaseMapNeedsWrite = existingText === null;
+        }
+    }
+    const releaseMapReport = releaseMap && releaseMapFile
+        ? { path: node_path_1.default.relative(cwd, releaseMapFile).split(node_path_1.default.sep).join('/'), entries: releaseMap.length }
+        : null;
     // ADR-3408 §8.5 / #3469: "liberal but visible" — when the write-seam
     // composition's preservation stage restores a curated frontmatter value
     // over a disagreeing freshly-derived one, that divergence is surfaced
@@ -549,7 +548,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // `platformEnsureDir(archiveDir)` below — a refused run (scope not COMPLETE,
     // no --force) must be a true no-op on disk, and creating the archive
     // directory first left an empty directory behind even on refusal.
-    const isDirInMilestone = getMilestonePhaseFilter(cwd, version);
+    const isDirInMilestone = getMilestonePhaseFilter(cwd, version, undefined, undefined, phaseDirectoryOptions(cwd));
     if (isDirInMilestone.missingExplicitVersion) {
         error(`no phases found for milestone ${version} in ROADMAP.md`);
     }
@@ -574,6 +573,10 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             `entries, even though the ROADMAP has phase entries elsewhere), so phase scoping ` +
             `cannot be trusted for this destructive operation. Re-run with --force to override.`);
     }
+    // #2761/#4304: resolve once for every phase-directory consumer in this
+    // command. The matcher opts in only for bracket; the milestone enumerator
+    // retains the full resolved value it already accepted.
+    const phaseConvention = resolvePhaseIdConvention(cwd);
     // Guard: prevent marking complete when ROADMAP still lists phases that have
     // no directory on disk (disk_status: no_directory). This catches the case
     // where the active milestone was erroneously marked complete before phases
@@ -655,8 +658,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             // properly-scaffolded bracket phase reads as disk_status: 'no_directory'
             // — turning a real bracket project's own phases into false "ROADMAP
             // lists N unstarted phase(s)" failures on `milestone complete`.
-            const convention = resolvePhaseIdConvention(cwd);
-            const { regex: phasePattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.ANY_BRACKET, convention);
+            const directoryContext = phaseDirectoryOptions(cwd, undefined, scopedContent);
+            const { regex: phasePattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.ANY_BRACKET, phaseConvention, directoryContext);
             const noDirectoryPhases = [];
             let pm;
             const phaseDirEntries = (() => {
@@ -680,12 +683,14 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this local check already covered both 0 and 999; now delegates to the single canonical owner.
                 if (isSentinelPhaseId(phaseNum))
                     continue;
-                const normalized = normalizePhaseName(phaseNum);
+                const lookup = resolvePhaseDirectoryLookup(cwd, phaseNum, undefined, directoryContext);
                 // A phase has disk_status: 'no_directory' when no phase directory
                 // with a matching token exists on disk. Use the same matchPhaseDirs
                 // owner that roadmap.analyze uses to avoid false positives on decimal
-                // (2.1) and letter-suffix (12A) phase IDs. (#2528)
-                const hasDirectory = matchPhaseDirs(phaseDirEntries, normalized, convention).matches.length > 0;
+                // (2.1) and letter-suffix (12A) phase IDs. (#2528) Under #4304 the
+                // current checkout's bracket convention and migration-window legacy
+                // fallback are both owned by the shared lookup adapter.
+                const hasDirectory = matchPhaseDirsForLookup(phaseDirEntries, lookup, undefined, directoryContext).matches.length > 0;
                 if (!hasDirectory) {
                     noDirectoryPhases.push(phaseNum);
                 }
@@ -715,7 +720,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     let totalPlans = 0;
     let totalTasks = 0;
     const accomplishments = [];
-    // #2761 (round-11 BLOCKER): resolved ONCE, ambiently (no explicit `ws` —
+    // #2761: resolved ONCE above, ambiently (no explicit `ws` —
     // this function has none of its own and already resolves everything else
     // off `cwd` via planningPaths(cwd), matching the ambient-workstream
     // contract `resolvePhaseIdConvention`/`planningDir` share), and threaded
@@ -730,7 +735,6 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // the silent-inherit path without changing behavior for `null` /
     // `milestone-prefixed` projects, whose resolved convention is the same
     // value `undefined` would have lazily produced anyway.
-    const phaseConvention = resolvePhaseIdConvention(cwd);
     // #3597 (ADR-3180 Decision 2): SINGLE resolution of "which phase
     // directories belong to the current milestone" AND the SCOPE discriminator
     // that resolution came from — shared verbatim by the read-only stats loop
@@ -860,6 +864,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 phases_archive_skipped: phasesArchiveSkippedForScope,
                 phases_archive_skip_reason: phasesArchiveSkipReason,
                 quick: quickDirsToArchive,
+                ...(releaseMapReport ? { release_map: { target: releaseMapReport.path, entries: releaseMapReport.entries } } : {}),
             },
             would_update: {
                 milestones_md: node_path_1.default.relative(cwd, milestonesPath).split(node_path_1.default.sep).join('/'),
@@ -885,6 +890,10 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // archive directory behind. Reaching this point means the run is
     // committed to mutating.
     (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
+    // #5706: archive the validated release map by recorded value.
+    if (releaseMap && releaseMapFile && releaseMapNeedsWrite) {
+        (0, shell_command_projection_cjs_1.platformWriteSync)(releaseMapFile, (0, milestone_release_map_cjs_1.serializeReleaseMapArchive)(version, releaseMap));
+    }
     // Archive ROADMAP.md
     if (node_fs_1.default.existsSync(roadmapPath)) {
         const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
@@ -909,7 +918,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     }
     // Create/append MILESTONES.md entry
     const accomplishmentsList = accomplishments.map((a) => `- ${a}`).join('\n');
-    const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+    const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n${releaseMap ? `${(0, milestone_release_map_cjs_1.renderReleaseMapMarkdown)(releaseMap)}\n` : ''}---\n\n`;
     // #3685: mirror requirementsUpdated's diff-tracking contract — the result
     // below used to report `milestones_updated: true` hardcoded, never
     // consulting whether the MILESTONES.md write actually changed anything.
@@ -1166,6 +1175,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
         milestones_updated: milestonesUpdated,
         state_updated: stateUpdated,
         preservation_warnings: preservationWarnings,
+        ...(releaseMapReport ? { release_map: releaseMapReport } : {}),
     };
     output(result, raw);
     // #3227 (design doc §40 row 26 / "Not-corruption" rule): a refreshed