@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -21,24 +21,34 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- io.cjs is an export= CommonJS module
 const ioMod = require("./io.cjs");
-const { output, error, ERROR_REASON } = ioMod;
+const { output, error, ERROR_REASON, formatDiagnosticToken } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateContract = require("./state-contract.cjs");
+const { publishStateContract } = stateContract;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
 const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- core-utils.cjs is an export= CommonJS module
 const coreUtilsMod = require("./core-utils.cjs");
-const { toPosixPath, generateSlugInternal, readSubdirectories, findUnsummarizedPlans } = coreUtilsMod;
+// #2528: `extractCanonicalPlanId` used to exist here as a byte-identical second
+// copy, and this PR had to patch BOTH with the same rewind rule — the exact
+// generative-fix divergence CLAUDE.md warns about. Collapsed onto core-utils'
+// copy, which was already the leaf owner, so there is no second surface left to
+// drift and no parity test needed to police one.
+const { toPosixPath, generateSlugInternal, readSubdirectories, extractCanonicalPlanId, findUnsummarizedPlans, normalizeLineEndings, } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, phaseTokenMatches, isSentinelPhaseId, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, } = phaseIdMod;
+const { normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, matchPhaseDirs, isSentinelPhaseId, scopeToPhase, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, } = phaseIdMod;
+const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal, getArchivedPhaseDirs } = phaseLocatorMod;
+const { findPhaseInternal, getArchivedPhaseDirs, listMilestonePhaseDirs } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- roadmap-parser.cjs is an export= CommonJS module
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { stripShippedMilestones, extractCurrentMilestone, getMilestonePhaseFilter, currentMilestoneRawRanges, withPhaseSection } = roadmapParserMod;
+const { stripShippedMilestones, extractCurrentMilestone, currentMilestoneRawRanges, withPhaseSection, findMilestoneScopeHeadingLines } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
@@ -64,12 +74,15 @@ const verifyMod = require("./verify.cjs");
 const { readVerificationStatus } = verificationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-dependency-graph.cjs is an export= CommonJS module
 const planDependencyGraphMod = require("./plan-dependency-graph.cjs");
-const { computeHaltPropagation, buildSummaryFileIndex, isSummaryFileHalted } = planDependencyGraphMod;
-const { planningDir, withPlanningLock, listAvailableWorkstreams, getActiveWorkstream } = planningWorkspace;
+const { computeHaltPropagation, buildSummaryFileIndex, isSummaryFileHalted, isSummaryFileBlocked } = planDependencyGraphMod;
+const { planningDir, withPlanningLock, listAvailableWorkstreams, peekActiveWorkstream, diagnoseUnresolvedActiveWorkstream, describeUnresolvedWorkstreamReason, } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- milestone-lock.cjs is an export= CommonJS module
+const milestoneLockMod = require("./milestone-lock.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planDocumentMod = require("./plan-document.cjs");
+const { parsePlanDocument, planIdFromFile } = planDocumentMod;
 const { extractFrontmatter } = frontmatterMod;
-const { readModifyWriteStateMd, stateExtractField, stateReplaceField, syncStateFrontmatter, withStateLock, updatePerformanceMetricsSection, } = stateMod;
-// #2893 — strict canonical filter: `{padded_phase}-{NN}-PLAN.md` or `PLAN.md`.
-const isCanonicalPlanFile = (f) => f.endsWith('-PLAN.md') || f === 'PLAN.md';
+const { readModifyWriteStateMd, stateExtractField, stateReplaceField, syncAndPreserveStateMd, withStateLock, updatePerformanceMetricsSection, } = stateMod;
 // Any .md file with PLAN anywhere in the basename — diagnostic net
 const PLAN_OUTLINE_RE = /-PLAN-OUTLINE\.md$/i;
 const PLAN_PRE_BOUNCE_RE = /-PLAN.*\.pre-bounce\.md$/i;
@@ -138,27 +151,6 @@ function describeNonCanonicalPlans(dirFiles, matchedFiles) {
         `. Rename to the canonical form (e.g. "01-01-PLAN.md") so the executor can detect them. ` +
         `See agents/gsd-planner.md write_phase_prompt step for the full contract.`);
 }
-function extractCanonicalPlanId(filename) {
-    const base = filename
-        .replace(/-PLAN\.md$/i, '')
-        .replace(/-SUMMARY\.md$/i, '')
-        .replace(/\.md$/i, '');
-    const parts = base.split('-').filter(Boolean);
-    // #2043: a phase/plan token component is either a zero-padded number (≥2 digits)
-    // or a single-digit-plus-letter id ("3A"); a *bare* single digit is a slug word,
-    // so "46-6-rs-…" is not paired into a "46-6" id while "3A-01" stays intact.
-    const tokenRe = /^(?:\d{2,}[A-Z]?|\d[A-Z])(?:\.\d+)*$/i;
-    // #2232: the PAIRED plan component is a zero-padded continuation segment
-    // (exactly 2 digits), so a ≥3-digit slug word (a year) is not paired into a
-    // bogus "14-2026" id. The leading phase component keeps tokenRe's unbounded
-    // \d{2,} — phase numbers ≥100 are legitimate; only continuations are capped.
-    const planTokenRe = new RegExp(`^(?:${phaseIdMod.PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?|\\d[A-Z])(?:\\.\\d+)*$`, 'i');
-    const phaseIdx = parts.findIndex((p) => tokenRe.test(p));
-    if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && planTokenRe.test(parts[phaseIdx + 1])) {
-        return `${parts[phaseIdx]}-${parts[phaseIdx + 1]}`;
-    }
-    return base;
-}
 function cmdPhasesList(cwd, options, raw) {
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
     const { type, phase, includeArchived } = options;
@@ -172,24 +164,56 @@ function cmdPhasesList(cwd, options, raw) {
         return;
     }
     try {
-        const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-        let dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-        if (includeArchived) {
-            const archived = getArchivedPhaseDirs(cwd);
-            for (const a of archived) {
-                dirs.push(`${a.name} [${a.milestone}]`);
-            }
-        }
-        dirs.sort((a, b) => comparePhaseNum(a, b));
+        // #3185 (ADR-3180 Decision 1): only the ENUMERATION routes through the
+        // single owner. The two other modes below ask genuinely DIFFERENT
+        // questions and are exempt by documented reason, never by a file
+        // allowlist (ADR-3180 Decision 4a):
+        //
+        //   --phase <n>        locating ONE phase by token is phase LOCATION, a
+        //                      question src/phase-locator.cts already owns via
+        //                      findPhaseInternal/searchPhaseInDir. Scoping it to
+        //                      the current milestone would make an out-of-window
+        //                      phase report "Phase not found".
+        //   --include-archived archived directories are BY DEFINITION from other
+        //                      milestones; filtering them through the CURRENT
+        //                      milestone window would return nothing at all.
+        //
+        // Generalizing #3183's rule ("a diagnostic about file NAMING wants the
+        // physical set; only a question about outstanding WORK wants the live
+        // set"): a LOOKUP wants the physical set; only "which phases belong to
+        // this milestone" wants the scoped set.
+        const archivedLabels = includeArchived
+            ? getArchivedPhaseDirs(cwd).map((a) => `${a.name} [${a.milestone}]`)
+            : [];
+        let dirs;
+        // #3185 (ADR-3180 Decision 2): the enumeration's scope, so a consumer
+        // can tell a genuinely-empty milestone from one it could not scope. Only
+        // the ENUMERATION path scopes anything; the LOOKUP path below has no
+        // enumeration to report a scope for.
+        let phaseScope = null;
         if (phase) {
+            // LOOKUP (b): search the physical set, plus archived when asked.
+            const lookupPool = [...readSubdirectories(phasesDir, true), ...archivedLabels];
             const normalized = normalizePhaseName(phase);
-            const match = dirs.find((d) => phaseTokenMatches(d, normalized));
+            // The pool is #3185's (physical set + archived); the matcher is this
+            // PR's. `dirs` is deliberately not read here: on this base it is not
+            // assigned until the branch below picks a match.
+            const { matches } = matchPhaseDirs(lookupPool, normalized);
+            const match = matches[0];
             if (!match) {
                 output({ files: [], count: 0, phase_dir: null, error: 'Phase not found' }, raw, '');
                 return;
             }
             dirs = [match];
         }
+        else {
+            // ENUMERATION (a): milestone-scoped and sentinel-filtered, plus
+            // archived when asked (c).
+            const enumerated = listMilestonePhaseDirs(phasesDir, { cwd });
+            phaseScope = enumerated.scope;
+            dirs = [...enumerated.value, ...archivedLabels];
+            dirs.sort((a, b) => comparePhaseNum(a, b));
+        }
         if (type) {
             const files = [];
             const warnings = [];
@@ -198,13 +222,31 @@ function cmdPhasesList(cwd, options, raw) {
                 const dirFiles = node_fs_1.default.readdirSync(dirPath);
                 let filtered;
                 if (type === 'plans') {
-                    filtered = dirFiles.filter(isCanonicalPlanFile);
+                    // #3183: this is a "what plan files physically exist" query (this
+                    // IS the file-listing command), not a live-completion question, so
+                    // it uses the single owner's allPlanFiles (root+nested, INCLUDING
+                    // status: superseded) rather than a root-only readdirSync filter
+                    // that also missed nested plans.
+                    //
+                    // #2893 (regression fix): `allPlanFiles` also carries
+                    // `isRootPlanFile`'s loose `/PLAN/i` fallback (deliberately
+                    // permissive for live-plan COUNTING elsewhere — see
+                    // plan-count-single-owner.test.cjs). That fallback silently
+                    // recognized a non-canonically-named file (e.g.
+                    // `01-PLAN-01-foundation.md`) as "matched", which defeated this
+                    // command's #2893 naming-convention diagnostic entirely (no
+                    // warning, file listed as if valid). Intersect with the STRICT
+                    // `isCanonicalPlanFile` predicate so this diagnostic — and the
+                    // `files` list this command actually returns — only ever
+                    // recognizes the canonical root/nested forms, exactly like the
+                    // pre-#3183 behavior this feature was built and tested against.
+                    filtered = scanPhasePlans(dirPath).allPlanFiles.filter(isCanonicalPlanFile);
                     const w = describeNonCanonicalPlans(dirFiles, filtered);
                     if (w)
                         warnings.push(`${dir}: ${w}`);
                 }
                 else if (type === 'summaries') {
-                    filtered = dirFiles.filter((f) => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+                    filtered = scanPhasePlans(dirPath).summaryFiles;
                 }
                 else {
                     filtered = dirFiles;
@@ -215,13 +257,18 @@ function cmdPhasesList(cwd, options, raw) {
                 files,
                 count: files.length,
                 phase_dir: phase ? dirs[0].replace(/^\d+(?:\.\d+)*-?/, '') : null,
+                // #3185 (ADR-3180 Decision 2): the enumeration's scope, so a consumer
+                // can tell a genuinely-empty milestone from one it could not scope.
+                phase_scope: phaseScope,
             };
             if (warnings.length)
                 result['warning'] = warnings.join(' | ');
             output(result, raw, files.join('\n'));
             return;
         }
-        output({ directories: dirs, count: dirs.length }, raw, dirs.join('\n'));
+        // #3185 (ADR-3180 Decision 2): the enumeration's scope, so a consumer
+        // can tell a genuinely-empty milestone from one it could not scope.
+        output({ directories: dirs, count: dirs.length, phase_scope: phaseScope }, raw, dirs.join('\n'));
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
@@ -237,8 +284,8 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
         if (node_fs_1.default.existsSync(phasesDir)) {
             const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
             const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-            baseExists = dirs.some((d) => phaseTokenMatches(d, normalized));
-            const dirPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${escapeRegex(normalized)}\\.(\\d+)`);
+            baseExists = matchPhaseDirs(dirs, normalized).matches.length > 0;
+            const dirPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${(0, pattern_cjs_1.escapeRegex)(normalized)}\\.(\\d+)`);
             for (const dir of dirs) {
                 const match = dir.match(dirPattern);
                 if (match)
@@ -351,6 +398,13 @@ function cmdFindPhase(cwd, phase, raw) {
         phase_name: null,
         plans: [],
         summaries: [],
+        // #3218: scalar counts alongside the arrays above. Left `null` (not `0`)
+        // when the phase can't be resolved at all — a fabricated `0` here would
+        // read identically to "phase exists with zero plans", which is a real,
+        // distinct answer (see the `status: superseded` case below).
+        plan_count: null,
+        summary_count: null,
+        plan_count_all: null,
         searched_directories: [],
     };
     const searchDirs = [];
@@ -381,7 +435,10 @@ function cmdFindPhase(cwd, phase, raw) {
             // #2237: fail loud when multiple directories match the same bare phase
             // number — prevents cross-project file writes when unrelated projects
             // share a .planning/phases/ tree.
-            const matches = dirs.filter((d) => phaseTokenMatches(d, normalized));
+            // #2528: selection delegates to the canonical two-pass matcher (exact
+            // token match, then the bare-integer leading-digit-run fallback) shared
+            // with the locator and the phase-plan-index scan.
+            const { matches } = matchPhaseDirs(dirs, normalized);
             if (matches.length === 0)
                 continue;
             if (matches.length > 1) {
@@ -398,9 +455,29 @@ function cmdFindPhase(cwd, phase, raw) {
             const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
             const phaseDir = node_path_1.default.join(searchDir, match);
             const phaseFiles = node_fs_1.default.readdirSync(phaseDir);
-            const plans = phaseFiles.filter(isCanonicalPlanFile).sort();
-            const summaries = phaseFiles.filter((f) => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').sort();
-            const planNamingWarning = describeNonCanonicalPlans(phaseFiles, plans);
+            // #3183: canonical, live (superseded-excluded) plan/summary sets
+            // (root+nested) from the single owner, rather than a root-only
+            // isCanonicalPlanFile filter + hand-rolled summary filter.
+            //
+            // #2893 (regression fix): both `plans` and the naming-diagnostic
+            // "matched" set are further intersected with the STRICT
+            // `isCanonicalPlanFile` predicate — scanPhasePlans's own
+            // planFiles/allPlanFiles carry `isRootPlanFile`'s loose `/PLAN/i`
+            // fallback (deliberately permissive for live-plan COUNTING elsewhere),
+            // which silently recognized a non-canonically-named file (e.g.
+            // `01-PLAN-01-foundation.md`) as a valid plan here and defeated this
+            // command's #2893 naming-convention diagnostic (no warning, offender
+            // listed in `plans` as if valid).
+            const phaseScan = scanPhasePlans(phaseDir);
+            const plans = phaseScan.planFiles.filter(isCanonicalPlanFile).sort();
+            const summaries = phaseScan.summaryFiles.slice().sort();
+            // describeNonCanonicalPlans is a NAMING-CONVENTION diagnostic, unrelated
+            // to supersession — compare against allPlanFiles (every plan-shaped file
+            // the owner recognizes, canonical or not) rather than the live-only
+            // `plans`, so a superseded-but-canonically-named plan is not misreported
+            // as a naming violation.
+            const canonicalAllPlanFiles = phaseScan.allPlanFiles.filter(isCanonicalPlanFile);
+            const planNamingWarning = describeNonCanonicalPlans(phaseFiles, canonicalAllPlanFiles);
             const result = {
                 found: true,
                 directory: toPosixPath(node_path_1.default.join(node_path_1.default.relative(cwd, planBase), node_path_1.default.relative(planBase, searchDir), match)),
@@ -408,6 +485,20 @@ function cmdFindPhase(cwd, phase, raw) {
                 phase_name: phaseName,
                 plans,
                 summaries,
+                // #3218: scalar counts additive alongside `plans[]`/`summaries[]`,
+                // which stay unchanged for existing consumers. Naming mirrors
+                // `roadmap.analyze`'s `plan_count`/`summary_count` (live, i.e.
+                // status:superseded EXCLUDED — same set as `plans`/`summaries`
+                // above) so the two surfaces read alike. `plan_count_all` is the
+                // PHYSICAL count — every canonically-named plan file on disk,
+                // status:superseded INCLUDED, same set `planNamingWarning` above
+                // diffs against (`canonicalAllPlanFiles`). The `_all` suffix
+                // deliberately echoes `scanPhasePlans`'s own `allPlanFiles` field so
+                // a reader can trace the name back to its source rather than guess
+                // which of two similarly-named integers is the filtered one.
+                plan_count: plans.length,
+                summary_count: summaries.length,
+                plan_count_all: canonicalAllPlanFiles.length,
             };
             if (planNamingWarning)
                 result['warning'] = planNamingWarning;
@@ -420,23 +511,73 @@ function cmdFindPhase(cwd, phase, raw) {
     }
     output(notFound, raw, '');
 }
-function extractObjective(content) {
-    const m = content.match(/<objective>\s*\n?\s*(.+)/);
-    return m ? m[1].trim() : null;
-}
 /**
  * Resolve a raw `depends_on` token to the `RawPlan.id` it refers to
- * (case-folded exact match, falling back to canonical-id matching). Returns
+ * (case-folded exact match, falling back to canonical-id matching, falling
+ * back to the in-phase short-form plan number — #3897 rung 4). Returns
  * `null` when the token does not resolve to any plan in this phase (a typo
  * or a cross-phase reference) — every call site treats that as "ignore this
  * edge", never a throw. Shared by `computeDependencyLevels`'s DAG-edge
- * resolution, the `depends_on` display mapping, and (#2830) the
- * halt-propagation node resolution, so the three can never disagree about
- * which token resolves to which plan.
+ * resolution and (#2830) the halt-propagation node resolution, so the two can
+ * never disagree about which token resolves to which plan. NOT used by the
+ * `depends_on` display mapping (#3785/N3) — that stays a passthrough by
+ * design; see the comment at its call site.
+ *
+ * `shortFormToId` (#3897 rung 4, ADR-3473 §8.9) is the third tier, consulted
+ * only when neither `planMap` nor `canonicalToId` resolves the token. It is
+ * optional so any caller that has not been threaded through yet (there are
+ * none left in this file) degrades to the pre-#3897 two-tier behavior rather
+ * than throwing on a missing argument.
  */
-function resolveDependencyId(dep, planMap, canonicalToId) {
+function resolveDependencyId(dep, planMap, canonicalToId, shortFormToId) {
     const lower = dep.toLowerCase();
-    return planMap.has(lower) ? planMap.get(lower).id : (canonicalToId.get(lower) ?? null);
+    if (planMap.has(lower))
+        return planMap.get(lower).id;
+    if (canonicalToId.has(lower))
+        return canonicalToId.get(lower);
+    return shortFormToId?.get(lower) ?? null;
+}
+// #3897 rung 4 (ADR-3473 §8.9) — builds the third depends_on resolution tier:
+// a map from an in-phase BARE PLAN NUMBER (e.g. "01") to the plan id whose
+// canonical id ends with that number. Recovered from the retired SDK lineage
+// (sdk/src/query/phase.ts at 11918dcc3^) with ONE deliberate narrowing: the
+// lost implementation indexed ANY trailing dash-segment of a canonical id,
+// with no constraint that the segment be a plan NUMBER — so a phase
+// containing both `09-FIX-auth-PLAN.md` and `09-GAP-auth-PLAN.md` (canonical
+// id `09-FIX-auth`, trailing segment "auth") would silently bind
+// `depends_on: ["auth"]` to whichever sorted first, fabricating a
+// wave-affecting DAG edge with ZERO warning — a mis-resolved edge, which is
+// worse than a dropped one (found in isolated correctness review, #3897).
+// `docs/reference/plan-md.md` already documents this tier as resolving "the
+// bare plan number", so requiring `/^\d+$/` on the trailing segment is a
+// strict narrowing onto the tier's OWN documented contract, not a behavior
+// change for any legitimate input. Do NOT restore the unconstrained
+// lastDash-slice "to match the recovered original" — the original was wrong
+// here; this rung deliberately departs from it in this one respect, and only
+// this one. Everything else — the `lastDash` bound, first-write-wins,
+// lowercasing — is kept exactly as recovered:
+//   - first write wins, deterministic because rawPlans is passed in sorted
+//     plan-file order (D4/T44) and this loop iterates in that same order;
+//   - a canonical id with no dash (`lastDash === -1` or `lastDash === 0`,
+//     e.g. "24" or "-01") or a trailing dash (`lastDash === canonical.length
+//     - 1`, e.g. "09-") is never indexed (D5).
+// Exported so callers can build this map once and so tests assert against
+// this REAL implementation rather than a hand-rolled copy that could
+// silently disagree with it after a future change here (CLAUDE.md's
+// generative-fix-divergence rule).
+function buildShortFormToId(rawPlans) {
+    const shortFormToId = new Map();
+    for (const p of rawPlans) {
+        const canonical = extractCanonicalPlanId(p.id);
+        const lastDash = canonical.lastIndexOf('-');
+        if (lastDash > 0 && lastDash < canonical.length - 1) {
+            const shortForm = canonical.slice(lastDash + 1).toLowerCase();
+            if (/^\d+$/.test(shortForm) && !shortFormToId.has(shortForm)) {
+                shortFormToId.set(shortForm, p.id);
+            }
+        }
+    }
+    return shortFormToId;
 }
 // O(V + E). Assigns each in-phase plan its longest-path topological level over the
 // in-phase dependsOn DAG (Kahn's algorithm). Returns { level: Map<id,number>, visited: number,
@@ -444,19 +585,32 @@ function resolveDependencyId(dep, planMap, canonicalToId) {
 // the exact dequeue order this pass already produces — a valid topological order — passed to
 // computeHaltPropagation as `precomputedOrder` so halt propagation does not re-run Kahn's
 // algorithm a second time over the same graph.
-function computeDependencyLevels(rawPlans, planMap, canonicalToId) {
+//
+// `shortFormToId` (#3897 rung 4, optional — see resolveDependencyId) is threaded through so a
+// bare in-phase plan-number token (`depends_on: ["01"]`) resolves as a real DAG edge instead of
+// being dropped and silently collapsing the dependent plan to wave 1 (D3).
+function computeDependencyLevels(rawPlans, planMap, canonicalToId, shortFormToId) {
     const level = new Map();
     const inDeg = new Map();
     const adj = new Map();
+    // #3427 / ADR-3473 §8.5: a depends_on token that resolves via NONE of the
+    // three tiers (planMap, canonicalToId, shortFormToId) is a dropped edge.
+    // Naming it here (rather than silently `continue`-ing past it) lets
+    // cmdPhasePlanIndex surface the token's own warning instead of
+    // manufacturing a wave-mismatch verdict from the resulting damaged graph
+    // (#3427).
+    const unresolved = [];
     for (const p of rawPlans) {
         if (!inDeg.has(p.id))
             inDeg.set(p.id, 0);
         if (!adj.has(p.id))
             adj.set(p.id, []);
         for (const dep of p.dependsOn) {
-            const resolvedDep = resolveDependencyId(dep, planMap, canonicalToId);
-            if (!resolvedDep)
+            const resolvedDep = resolveDependencyId(dep, planMap, canonicalToId, shortFormToId);
+            if (!resolvedDep) {
+                unresolved.push({ plan: p.id, token: String(dep) });
                 continue;
+            }
             if (!adj.has(resolvedDep))
                 adj.set(resolvedDep, []);
             adj.get(resolvedDep).push(p.id);
@@ -489,7 +643,7 @@ function computeDependencyLevels(rawPlans, planMap, canonicalToId) {
             }
         }
     }
-    return { level, visited, order: queue };
+    return { level, visited, order: queue, unresolved };
 }
 function cmdPhasePlanIndex(cwd, phase, raw) {
     if (!phase) {
@@ -499,74 +653,109 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     const normalized = normalizePhaseName(phase);
     let phaseDir = null;
     let phaseDirName = null;
+    let ambiguousMatches = null;
     try {
         const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
         const dirs = entries
             .filter((e) => e.isDirectory())
             .map((e) => e.name)
             .sort((a, b) => comparePhaseNum(a, b));
-        const match = dirs.find((d) => phaseTokenMatches(d, normalized));
-        if (match) {
-            phaseDir = node_path_1.default.join(phasesDir, match);
-            phaseDirName = match;
+        // #2528: selection delegates to the canonical two-pass matcher shared with
+        // the locator and the find-phase scan (this site previously first-matched
+        // with `.find()` and had no multi-match guard — the #2237 fail-loud rule
+        // now applies here too, so the three resolution paths cannot disagree).
+        const { matches } = matchPhaseDirs(dirs, normalized);
+        if (matches.length > 1) {
+            ambiguousMatches = matches;
+        }
+        else if (matches.length === 1) {
+            phaseDir = node_path_1.default.join(phasesDir, matches[0]);
+            phaseDirName = matches[0];
         }
     }
     catch {
         // phases dir doesn't exist
     }
+    if (ambiguousMatches) {
+        output({
+            phase: normalized,
+            error: `Phase ${normalized} is ambiguous: ${ambiguousMatches.length} directories match (${ambiguousMatches.map((m) => `"${m}"`).join(', ')}).`,
+            ambiguous_matches: ambiguousMatches,
+            plans: [], waves: {}, incomplete: [], has_checkpoints: false,
+        }, raw);
+        return;
+    }
     if (!phaseDir) {
         output({ phase: normalized, error: 'Phase not found', plans: [], waves: {}, incomplete: [], runnable: [], has_checkpoints: false }, raw);
         return;
     }
     void phaseDirName; // used only to set phaseDir above
+    // phaseFiles stays root-only readdirSync — it feeds only
+    // describeNonCanonicalPlans's near-miss naming diagnostic below, which is
+    // advisory text, not a counted/scheduled file set.
     const phaseFiles = node_fs_1.default.readdirSync(phaseDir);
-    const planFiles = phaseFiles.filter(isCanonicalPlanFile).sort();
-    const summaryFiles = phaseFiles.filter((f) => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
-    const planNamingWarning = describeNonCanonicalPlans(phaseFiles, planFiles);
-    const completedPlanIds = new Set(summaryFiles.flatMap((s) => {
-        const exact = s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
-        const canonical = extractCanonicalPlanId(s);
-        return canonical === exact ? [exact] : [exact, canonical];
-    }));
+    // #3183 (highest-severity site, ADR-3180 Decision 2): canonical LIVE
+    // plan/summary sets (root+nested, status: superseded EXCLUDED) from the
+    // single owner. This fixes two real bugs in the wave/dependency index this
+    // function builds: (1) a superseded plan used to still get scheduled into
+    // an execution wave, and (2) a phase using the #3139 nested `plans/`
+    // layout used to report ZERO plans (root-only readdirSync, no `plans/`
+    // join).
+    // #2893 (regression fix): intersected with the STRICT `isCanonicalPlanFile`
+    // predicate — scanPhasePlans's own planFiles/allPlanFiles carry
+    // `isRootPlanFile`'s loose `/PLAN/i` fallback (deliberately permissive for
+    // live-plan COUNTING elsewhere), which silently scheduled a
+    // non-canonically-named file (e.g. `01-PLAN-01-foundation.md`) into a wave
+    // here and defeated this command's #2893 naming-convention diagnostic (no
+    // warning). Restores the pre-#3183, tested behavior: only canonical
+    // root/nested filenames are ever counted or scheduled by this command.
+    const phaseScan = scanPhasePlans(phaseDir);
+    const planFiles = phaseScan.planFiles.filter(isCanonicalPlanFile).sort();
+    const summaryFiles = phaseScan.summaryFiles;
+    // describeNonCanonicalPlans is a NAMING-CONVENTION diagnostic, unrelated to
+    // supersession — compare against allPlanFiles (every plan-shaped file the
+    // owner recognizes, canonical or not) rather than the live-only planFiles,
+    // so a superseded-but-canonically-named plan is not misreported as a
+    // naming violation.
+    const planNamingWarning = describeNonCanonicalPlans(phaseFiles, phaseScan.allPlanFiles.filter(isCanonicalPlanFile));
+    // #3183: completion pairing via the canonical findUnsummarizedPlans
+    // (shares its `summaryCandidates` matching rule with countMatchedSummaries,
+    // and is layout-agnostic — it pairs a nested `plans/PLAN-01.md` with
+    // `plans/SUMMARY-01.md` correctly) instead of a bespoke ID-Set built from
+    // extractCanonicalPlanId, which only ever handled the root-canonical
+    // `-PLAN.md`/`-SUMMARY.md` naming form.
+    //
+    // #3345: the summary list is filtered through the SAME shared predicate
+    // scanPhasePlans filters its countable set with
+    // (plan-dependency-graph.cjs's isSummaryFileBlocked), so a SUMMARY declaring
+    // `status: blocked` reads as NO completion record here — has_summary false,
+    // the plan lands in `incomplete` — exactly matching the count side. Fail-open
+    // on a SUMMARY with no status key / unreadable file (filename fallback);
+    // `status: halted` stays summarized (#2830 designed stop). summaryFileByPlanId
+    // below still indexes EVERY summary on disk because the halted lookup is a
+    // file resolution for reading status, not a completion pairing.
+    const countableSummaryFiles = summaryFiles.filter((f) => !isSummaryFileBlocked(node_path_1.default.join(phaseDir, f)));
+    const unsummarizedPlanFiles = new Set(findUnsummarizedPlans(planFiles, countableSummaryFiles));
     // #2830: reverse lookup from a completed plan's id (exact or canonical) to
     // the actual summary filename, so a plan's own SUMMARY frontmatter can be
     // read for its `status`. Shared builder (also used by phase-locator.cts's
     // searchPhaseInDir) so the two can never disagree about which summary
-    // belongs to which plan.
+    // belongs to which plan. This is a FILE resolution for reading halted
+    // status, not a completion-count pairing rule, so it is unaffected by the
+    // #3183 pairing migration above.
     const summaryFileByPlanId = buildSummaryFileIndex(summaryFiles, extractCanonicalPlanId);
     // ── Pass 1: parse each plan file ─────────────────────────────────────────
     const rawPlans = [];
     for (const planFile of planFiles) {
-        const planId = planFile.replace('-PLAN.md', '').replace('PLAN.md', '');
+        const planId = planIdFromFile(planFile);
         const planPath = node_path_1.default.join(phaseDir, planFile);
         const content = node_fs_1.default.readFileSync(planPath, 'utf-8');
-        // Pass planPath so a truncated PLAN.md names the file in the #1882 diagnostic.
-        const fm = extractFrontmatter(content, planPath);
-        const xmlTasks = content.match(/<task[\s>]/gi) || [];
-        const mdTasks = content.match(/##\s*Task\s*\d+/gi) || [];
-        const taskCount = xmlTasks.length || mdTasks.length;
-        const parsedWave = parseInt(fm['wave'], 10);
-        const declaredWave = Number.isNaN(parsedWave) ? null : parsedWave;
-        let dependsOn = [];
-        const fmDeps = fm['depends_on'];
-        if (Array.isArray(fmDeps)) {
-            dependsOn = fmDeps.map(String);
-        }
-        else if (typeof fmDeps === 'string' && fmDeps.trim() !== '') {
-            dependsOn = [fmDeps];
-        }
-        let autonomous = true;
-        if (fm['autonomous'] !== undefined) {
-            // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue comparison
-            autonomous = fm['autonomous'] === 'true' || String(fm['autonomous']) === 'true';
-        }
-        let filesModified = [];
-        const fmFiles = fm['files_modified'] || fm['files-modified'];
-        if (fmFiles) {
-            // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
-            filesModified = Array.isArray(fmFiles) ? fmFiles.map(String) : [String(fmFiles)];
-        }
-        const hasSummary = completedPlanIds.has(planId) || completedPlanIds.has(extractCanonicalPlanId(planFile));
+        // #2790: plan-body parsing is owned by the shared Plan Document Module, so
+        // this command and the read-only `planning.inspect` query cannot drift on
+        // what a plan document says. planPath is still passed so a truncated
+        // PLAN.md names the file in the #1882 diagnostic.
+        const planDoc = parsePlanDocument(content, planPath);
+        const hasSummary = !unsummarizedPlanFiles.has(planFile);
         // #2830: a plan can have a SUMMARY (hasSummary=true) and still be halted —
         // a designed stop still writes a completion record, just one whose status
         // says "halted" rather than "complete". Only look up the summary file
@@ -577,12 +766,14 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
             : false;
         rawPlans.push({
             id: planId,
-            declaredWave,
-            dependsOn,
-            autonomous,
-            objective: extractObjective(content) || fm['objective'] || null,
-            filesModified,
-            taskCount,
+            declaredWave: planDoc.declaredWave,
+            dependsOn: planDoc.dependsOn,
+            autonomous: planDoc.autonomous,
+            objective: planDoc.objective,
+            filesModified: planDoc.filesModified,
+            filesDeleted: planDoc.filesDeleted,
+            agentHint: planDoc.agentHint,
+            taskCount: planDoc.taskCount,
             hasSummary,
             halted,
         });
@@ -600,7 +791,15 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     }
     const planMap = new Map(rawPlans.map((p) => [p.id.toLowerCase(), p]));
     const canonicalToId = new Map(rawPlans.map((p) => [extractCanonicalPlanId(p.id).toLowerCase(), p.id]));
-    const { level, visited, order } = computeDependencyLevels(rawPlans, planMap, canonicalToId);
+    // #3897 rung 4 (ADR-3473 §8.9) — the third depends_on resolution tier.
+    // Resolves a bare in-phase plan-number short form (e.g. "01") to its owning
+    // plan id. In-phase only by construction (T49): the map is built from THIS
+    // phase's rawPlans alone, so a short form colliding with a different
+    // phase's plan can never be a candidate. See {@link buildShortFormToId}'s
+    // own comment for the numeric-only narrowing this rung applies on top of
+    // the recovered SDK-lineage algorithm.
+    const shortFormToId = buildShortFormToId(rawPlans);
+    const { level, visited, order, unresolved } = computeDependencyLevels(rawPlans, planMap, canonicalToId, shortFormToId);
     if (visited < rawPlans.length) {
         const cycleNodes = rawPlans.filter((p) => !level.has(p.id)).map((p) => p.id);
         error(`depends_on cycle detected in phase ${normalized} — cycle involves: ${cycleNodes.join(', ')}`);
@@ -614,7 +813,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     const haltNodes = rawPlans.map((p) => ({
         id: p.id,
         resolvedDependsOn: p.dependsOn
-            .map((dep) => resolveDependencyId(String(dep), planMap, canonicalToId))
+            .map((dep) => resolveDependencyId(String(dep), planMap, canonicalToId, shortFormToId))
             .filter((id) => id !== null),
         halted: p.halted,
     }));
@@ -628,6 +827,17 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     const runnable = [];
     let hasCheckpoints = false;
     const warnings = [];
+    // #3427 / ADR-3473 §8.5: name every dropped depends_on edge (plan AND
+    // token) rather than letting it silently collapse the plan to a DAG root.
+    // A plan with at least one unresolved token gets ITS OWN warning here and
+    // the wave-mismatch verdict below is suppressed for that plan ONLY — a
+    // plan with no dropped edges and a genuinely wrong `wave:` still warns
+    // (N3, D6, T25).
+    const plansWithUnresolvedTokens = new Set();
+    for (const { plan, token } of unresolved) {
+        plansWithUnresolvedTokens.add(plan);
+        warnings.push(`Plan ${plan}: depends_on token ${formatDiagnosticToken(token)} does not resolve to any plan in this phase — edge dropped, wave placement for this plan may be unreliable`);
+    }
     for (const rawPlan of rawPlans) {
         if (!rawPlan.autonomous) {
             hasCheckpoints = true;
@@ -644,7 +854,15 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         }
         const computedWave = (level.get(rawPlan.id) ?? 0) + levelOffset;
         const effectiveWave = computedWave;
-        if (rawPlan.declaredWave !== null && rawPlan.declaredWave !== computedWave) {
+        // #3427 (D5/N3): suppress the wave-mismatch verdict for a plan that has
+        // at least one unresolved depends_on token — its own dropped-edge
+        // warning above already explains the degraded wave placement, so the
+        // mismatch here would blame the author for a DAG the tool itself
+        // couldn't build. A plan with NO unresolved tokens still gets a genuine
+        // mismatch reported (N3, T25) — the suppression is per-plan, never blanket.
+        if (rawPlan.declaredWave !== null &&
+            rawPlan.declaredWave !== computedWave &&
+            !plansWithUnresolvedTokens.has(rawPlan.id)) {
             warnings.push(`Plan ${rawPlan.id}: declared wave: ${rawPlan.declaredWave} but depends_on DAG places it in wave ${computedWave}`);
         }
         const plan = {
@@ -664,6 +882,8 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
             autonomous: rawPlan.autonomous,
             objective: rawPlan.objective,
             files_modified: rawPlan.filesModified,
+            files_deleted: rawPlan.filesDeleted,
+            agent_hint: rawPlan.agentHint,
             task_count: rawPlan.taskCount,
             has_summary: rawPlan.hasSummary,
             // #2830: additive fields — halted is this plan's OWN status; blocked_by
@@ -716,10 +936,123 @@ function describeGoalShapedTitle(description) {
     return (`description looks goal-shaped, not title-shaped (${reasons}). It was written verbatim ` +
         `as the phase title; consider a short title with the detail moved to **Goal:**.`);
 }
+/**
+ * #3163: compute the byte offset in `rawContent` where a new `### Phase N:`
+ * entry should be inserted — at the end of the active phase list, scoped to the
+ * CURRENT MILESTONE so the entry can never land before a trailing `---` in
+ * shipped/history/backlog material (the file's last `---` on a long roadmap
+ * sits deep in archive). When no current milestone can be resolved (no
+ * STATE.md `milestone:` and no in-progress `🚧`/`🔄` marker), fall back to the
+ * legacy whole-file lastIndexOf('\n---') so simple no-milestone roadmaps keep
+ * their existing behavior.
+ */
+function phaseEntryInsertOffset(rawContent, cwd) {
+    const ranges = currentMilestoneRawRanges(rawContent, cwd);
+    if (!ranges) {
+        const legacy = rawContent.lastIndexOf('\n---');
+        return legacy > 0 ? legacy : rawContent.length;
+    }
+    const window = rawContent.slice(ranges.primary.start, ranges.primary.end);
+    const lastSeparator = window.lastIndexOf('\n---');
+    return lastSeparator > 0 ? ranges.primary.start + lastSeparator : ranges.primary.end;
+}
+/**
+ * #3262 (write-time milestone-scope guard): the phase-creation and
+ * phase-insertion entry templates interpolate the caller's `description`
+ * verbatim into `### Phase N: ${description}`. A description embedding a
+ * level 1-3 heading that carries a milestone marker (version token,
+ * ✅/📋/🚧/🔄, or the word "Milestone") would splice a heading that TERMINATES
+ * the current milestone window (`computeMilestoneSectionEnd`) and silently
+ * drops every later phase out of the derived milestone phase set. Reject
+ * before any write or phase-directory creation — the fail-loud sibling of
+ * the edit-phase workflow's depends_on gate. The predicate itself
+ * (`findMilestoneScopeHeadingLines`) is fence-aware and Phase-heading-exempt,
+ * so ordinary descriptions and the phase's own numbered heading never trip it.
+ */
+function assertDescriptionPreservesMilestoneScope(description, command) {
+    const offending = findMilestoneScopeHeadingLines(description);
+    if (offending.length === 0)
+        return;
+    error(`${command}: description contains a milestone-scoping heading line — writing it to ROADMAP.md would terminate ` +
+        `the current milestone window and silently drop later phases out of the milestone scope. ` +
+        `Offending line(s): ${offending.map((line) => JSON.stringify(line)).join(', ')}. ` +
+        `Rewrite the line so it is not a level 1-3 "#" heading carrying a milestone marker ` +
+        `(a vN.N version token, a ✅/📋/🚧/🔄 marker, or the word "Milestone").`);
+}
+/**
+ * #3849 — widen "used phase numbers" beyond this checkout. Every sibling git
+ * worktree carries its own `.planning/` on its own branch, so a phase minted
+ * there is invisible to the cwd-scoped sources (headers, bullets, on-disk
+ * dirs). Scan each sibling's phase-directory names (cheap — dir names alone
+ * caught the real incident) and its WHOLE ROADMAP.md headers (a row can exist
+ * before any directory does; milestone-scoping is wrong here because a number
+ * used under any milestone on another branch is still taken).
+ *
+ * Widen, never refuse: a missing `.planning/`, an unreadable sibling, a
+ * non-git cwd, or an unavailable git binary each leave `used` untouched —
+ * allocation then behaves exactly as it did before this horizon existed.
+ * Sentinels reuse the canonical `isSentinelPhaseId`; the dir pattern is the
+ * same one the on-disk scan uses, so decimal sub-phases (`411.1-foo`) are
+ * correctly not integers.
+ */
+function collectSiblingWorktreePhaseNums(cwd, used) {
+    let porcelain;
+    try {
+        porcelain = (0, node_child_process_1.execFileSync)('git', ['worktree', 'list', '--porcelain'], {
+            cwd,
+            encoding: 'utf-8',
+            // Same subprocess band as the other git call sites (smart-entry, check-command-router):
+            // inside the 5-30s git window, hidden console window on Windows, bounded buffer.
+            timeout: 10_000,
+            windowsHide: true,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+    }
+    catch {
+        return; // not a git repo / git unavailable — unchanged behavior
+    }
+    const dirNumPattern = /^(?:[A-Z][A-Z0-9]*-)?(\d+)-/;
+    // Same header shape the allocators scan locally (#1729 tag tolerance).
+    const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
+    for (const line of porcelain.split('\n')) {
+        if (!line.startsWith('worktree '))
+            continue;
+        const wt = line.slice('worktree '.length).trim();
+        if (!wt || node_path_1.default.resolve(wt) === node_path_1.default.resolve(cwd))
+            continue;
+        try {
+            for (const entry of node_fs_1.default.readdirSync(node_path_1.default.join(wt, '.planning', 'phases'))) {
+                const match = entry.match(dirNumPattern);
+                if (!match)
+                    continue;
+                const num = parseInt(match[1], 10);
+                if (!isSentinelPhaseId(num))
+                    used.add(num);
+            }
+        }
+        catch {
+            /* worktree has no .planning — normal, contributes nothing */
+        }
+        try {
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(wt, '.planning', 'ROADMAP.md'), 'utf-8');
+            let m;
+            headerPattern.lastIndex = 0;
+            while ((m = headerPattern.exec(content)) !== null) {
+                const num = parseInt(m[1], 10);
+                if (!isSentinelPhaseId(num))
+                    used.add(num);
+            }
+        }
+        catch {
+            /* no roadmap in that worktree — normal, contributes nothing */
+        }
+    }
+}
 function cmdPhaseAdd(cwd, description, raw, customId) {
     if (!description) {
         error('description required for phase add');
     }
+    assertDescriptionPreservesMilestoneScope(description, 'phase add');
     const config = loadConfig(cwd);
     const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
     if (!node_fs_1.default.existsSync(roadmapPath)) {
@@ -755,12 +1088,14 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
             let m;
             while ((m = headerPattern.exec(content)) !== null) {
                 const num = parseInt(m[1], 10);
-                if (num !== 999)
+                // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+                if (!isSentinelPhaseId(num))
                     usedPhaseNums.add(num);
             }
             while ((m = bulletPattern.exec(content)) !== null) {
                 const num = parseInt(m[1], 10);
-                if (num !== 999)
+                // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+                if (!isSentinelPhaseId(num))
                     usedPhaseNums.add(num);
             }
             // 3) On-disk phase directories (e.g. phases/11-foo/ with no header yet)
@@ -772,7 +1107,8 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
                     if (!match)
                         continue;
                     const num = parseInt(match[1], 10);
-                    if (num !== 999)
+                    // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+                    if (!isSentinelPhaseId(num))
                         usedPhaseNums.add(num);
                 }
             }
@@ -780,6 +1116,9 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
             // section headers, roadmap bullets, AND on-disk dirs above is what prevents the
             // #1229 collision (a bullet-only Phase N is now counted), so max+1 cannot reuse
             // an existing number.
+            // 4) Sibling git worktrees (#3849) — same max+1, wider horizon: a number
+            // taken on another branch is still taken.
+            collectSiblingWorktreePhaseNums(cwd, usedPhaseNums);
             const maxUsed = usedPhaseNums.size > 0 ? Math.max(...usedPhaseNums) : 0;
             _newPhaseId = maxUsed + 1;
             const paddedNum = String(_newPhaseId).padStart(2, '0');
@@ -792,14 +1131,8 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
             ? ''
             : `\n**Depends on:** Phase ${typeof _newPhaseId === 'number' ? _newPhaseId - 1 : 'TBD'}`;
         const phaseEntry = `\n### Phase ${_newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${_newPhaseId} to break down)\n`;
-        let updatedContent;
-        const lastSeparator = rawContent.lastIndexOf('\n---');
-        if (lastSeparator > 0) {
-            updatedContent = rawContent.slice(0, lastSeparator) + phaseEntry + rawContent.slice(lastSeparator);
-        }
-        else {
-            updatedContent = rawContent + phaseEntry;
-        }
+        const insertAt = phaseEntryInsertOffset(rawContent, cwd);
+        const updatedContent = rawContent.slice(0, insertAt) + phaseEntry + rawContent.slice(insertAt);
         (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, updatedContent);
         return { newPhaseId: _newPhaseId, dirName: _dirName };
     });
@@ -815,11 +1148,29 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
     if (titleWarning)
         result['warning'] = titleWarning;
     output(result, raw, result['padded']);
+    // #3227 (design doc §40 row 26 / "Not-corruption" rule): every
+    // `publishStateContract` call site in this file is audited so a refreshed
+    // state.json `updated_at` always means something on disk actually moved —
+    // a stale-but-refreshed timestamp is worse than no refresh, because it
+    // reads as fresh to a downstream watcher. This site is unconditional
+    // because every reachable path either exits via `error()` (process.exit,
+    // never reaches here) or falls through to the unconditional
+    // `platformEnsureDir`/`platformWriteSync` pair above that always creates
+    // the phase directory and rewrites ROADMAP.md — there is no code path that
+    // reaches this line without having just written to disk. Best-effort —
+    // cannot throw, cannot change this command's exit code or output.
+    publishStateContract(cwd);
 }
 function cmdPhaseAddBatch(cwd, descriptions, raw) {
     if (!Array.isArray(descriptions) || descriptions.length === 0) {
         error('descriptions array required for phase add-batch');
     }
+    // #3262: validate every description BEFORE the lock — the batch is
+    // all-or-nothing, so one offending description must reject the whole batch
+    // with no ROADMAP write and no phase directories created.
+    for (const description of descriptions) {
+        assertDescriptionPreservesMilestoneScope(description, 'phase add-batch');
+    }
     const config = loadConfig(cwd);
     const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
     if (!node_fs_1.default.existsSync(roadmapPath)) {
@@ -832,12 +1183,24 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
         const content = extractCurrentMilestone(rawContent, cwd);
         let maxPhase = 0;
         if (config.phase_naming !== 'custom') {
+            // Same three cwd-scoped sources as cmdPhaseAdd (#1229): headers, roadmap
+            // bullets, on-disk dirs. The bullet scan was missing here — a bullet-only
+            // `Phase N` row was invisible to batch allocation (#3849 secondary).
             // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
             const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
+            const bulletPattern = /^[ \t]*-[ \t]*\[[^\]]{0,200}\][ \t]*\*{0,2}Phase[ \t]+(\d+)(?=[:.\s*]|$)/gim;
             let m;
             while ((m = phasePattern.exec(content)) !== null) {
                 const num = parseInt(m[1], 10);
-                if (num === 999)
+                // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+                if (isSentinelPhaseId(num))
+                    continue;
+                if (num > maxPhase)
+                    maxPhase = num;
+            }
+            while ((m = bulletPattern.exec(content)) !== null) {
+                const num = parseInt(m[1], 10);
+                if (isSentinelPhaseId(num))
                     continue;
                 if (num > maxPhase)
                     maxPhase = num;
@@ -850,12 +1213,20 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
                     if (!match)
                         continue;
                     const num = parseInt(match[1], 10);
-                    if (num === 999)
+                    // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+                    if (isSentinelPhaseId(num))
                         continue;
                     if (num > maxPhase)
                         maxPhase = num;
                 }
             }
+            // 4) Sibling git worktrees (#3849) — same max+1, wider horizon.
+            const siblingNums = new Set();
+            collectSiblingWorktreePhaseNums(cwd, siblingNums);
+            for (const num of siblingNums) {
+                if (num > maxPhase)
+                    maxPhase = num;
+            }
         }
         const added = [];
         for (const description of descriptions) {
@@ -878,11 +1249,8 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
                 ? ''
                 : `\n**Depends on:** Phase ${typeof newPhaseId === 'number' ? newPhaseId - 1 : 'TBD'}`;
             const phaseEntry = `\n### Phase ${newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${newPhaseId} to break down)\n`;
-            const lastSeparator = rawContent.lastIndexOf('\n---');
-            rawContent =
-                lastSeparator > 0
-                    ? rawContent.slice(0, lastSeparator) + phaseEntry + rawContent.slice(lastSeparator)
-                    : rawContent + phaseEntry;
+            const insertAt = phaseEntryInsertOffset(rawContent, cwd);
+            rawContent = rawContent.slice(0, insertAt) + phaseEntry + rawContent.slice(insertAt);
             added.push({
                 phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId),
                 padded: typeof newPhaseId === 'number' ? String(newPhaseId).padStart(2, '0') : String(newPhaseId),
@@ -896,11 +1264,17 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
         return added;
     });
     output({ phases: results, count: results.length }, raw);
+    // #3227: unconditional here because `platformWriteSync(roadmapPath, rawContent)`
+    // above always rewrites ROADMAP.md for every description in the batch before
+    // this line is reached; the only refusal path is the `error('ROADMAP.md not
+    // found')` above, which terminates the process and never reaches here.
+    publishStateContract(cwd);
 }
 function cmdPhaseInsert(cwd, afterPhase, description, raw) {
     if (!afterPhase || !description) {
         error('after-phase and description required for phase insert');
     }
+    assertDescriptionPreservesMilestoneScope(description, 'phase insert');
     const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
     if (!node_fs_1.default.existsSync(roadmapPath)) {
         error('ROADMAP.md not found');
@@ -949,7 +1323,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
                 error(`Failed to scan phase directories for existing decimal phases: ${msg}`);
             }
             const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-            const decimalPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${escapeRegex(normalizedBase)}\\.(\\d+)`);
+            const decimalPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${(0, pattern_cjs_1.escapeRegex)(normalizedBase)}\\.(\\d+)`);
             for (const dir of dirs) {
                 const dm = dir.match(decimalPattern);
                 if (dm)
@@ -977,15 +1351,30 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
             const phaseLabel = useBold
                 ? `**Phase ${_decimalPhase}: ${description}**`
                 : `Phase ${_decimalPhase}: ${description}`;
+            // #3413 review fix: bulletEntry stays hardcoded '\n'. The on-disk EOL
+            // is decided at write time by platformWriteSync's normalizeContent /
+            // _normalizeMd (shell-command-projection.cts), which unconditionally
+            // converts \r\n -> \n for any .md target — so whatever terminator is
+            // used here in memory is erased before the file is ever written, and
+            // templating it via detectEol(rawContent) was inert dead code. '\n'
+            // matches what platformWriteSync enforces anyway.
             const bulletEntry = `\n- [ ] ${phaseLabel}`;
-            const targetBulletPattern = new RegExp(`(-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
+            // #3413: was `[^\n]*`, which on CRLF content swallows the line's
+            // trailing \r into the match, shifting bulletLineEnd to land BETWEEN
+            // the \r and \n of the original CRLF pair — a pure splice-POSITION
+            // bug on the not-yet-write-normalized CRLF read (independent of the
+            // final on-disk EOL, which platformWriteSync always forces to LF for
+            // .md targets regardless). Widening to [^\r\n]* stops the match at the
+            // true line-content boundary so bulletLineEnd lands cleanly before the
+            // terminator.
+            const targetBulletPattern = new RegExp(`(-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\r\\n]*)`, 'i');
             const bulletMatchResult = rawContent.match(targetBulletPattern);
             if (!bulletMatchResult) {
                 error(`Could not find Phase ${afterPhase} bullet line`);
             }
             const bulletLineEnd = rawContent.indexOf(bulletMatchResult[0]) + bulletMatchResult[0].length;
             const afterBullet = rawContent.slice(bulletLineEnd);
-            const nextBulletMatch = afterBullet.match(/\n-\s*\[[ x]\]\s*(?:\*\*)?Phase\s+\d/i);
+            const nextBulletMatch = afterBullet.match(/\r?\n-\s*\[[ x]\]\s*(?:\*\*)?Phase\s+\d/i);
             let insertIdx;
             if (nextBulletMatch) {
                 insertIdx = bulletLineEnd + nextBulletMatch.index;
@@ -1005,7 +1394,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
             }
             const headerIdx = rawContent.indexOf(headerMatch[0]);
             const afterHeader = rawContent.slice(headerIdx + headerMatch[0].length);
-            const nextPhaseMatch = afterHeader.match(/\n#{2,4}\s+Phase\s+\d[\d.]*/i);
+            const nextPhaseMatch = afterHeader.match(/\r?\n#{2,4}\s+Phase\s+\d[\d.]*/i);
             let insertIdx;
             if (nextPhaseMatch) {
                 insertIdx = headerIdx + headerMatch[0].length + nextPhaseMatch.index;
@@ -1027,6 +1416,11 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         directory: toPosixPath(node_path_1.default.join(node_path_1.default.relative(cwd, planningDir(cwd)), 'phases', dirName)),
     };
     output(result, raw, decimalPhase);
+    // #3227: unconditional here because `platformWriteSync(roadmapPath, updatedContent)`
+    // above always rewrites ROADMAP.md with the inserted phase before this line is
+    // reached; every refusal along the way (bad args, missing ROADMAP.md, unresolved
+    // target bullet/header) exits via `error()`, which terminates the process.
+    publishStateContract(cwd);
 }
 function renameDecimalPhases(phasesDir, baseInt, removedDecimal) {
     const renamedDirs = [];
@@ -1059,9 +1453,33 @@ function renameDecimalPhases(phasesDir, baseInt, removedDecimal) {
     }
     return { renamedDirs, renamedFiles };
 }
+/**
+ * Find a free name to move an occupying file aside to, on collision, so the
+ * intended rename can proceed without destroying either file. Appends the
+ * literal `.orphaned` suffix to the whole existing filename (never `.md`,
+ * so no phase-directory scan predicate — all of which filter on
+ * `.endsWith('.md')` / `.endsWith('-VERIFICATION.md')` etc — can ever pick
+ * the displaced file back up as any phase's artifact). Falls back to a
+ * numeric discriminator (`.orphaned.2`, `.orphaned.3`, ...) if `.orphaned`
+ * itself is taken, bounded at 100 attempts so a pathological directory
+ * cannot loop forever; returns null if no free name is found within that
+ * bound, letting the caller fall back to skip-and-report.
+ */
+function findOrphanedDisplacementName(dir, fileName) {
+    const base = `${fileName}.orphaned`;
+    if (!node_fs_1.default.existsSync(node_path_1.default.join(dir, base)))
+        return base;
+    for (let n = 2; n <= 100; n++) {
+        const candidate = `${base}.${n}`;
+        if (!node_fs_1.default.existsSync(node_path_1.default.join(dir, candidate)))
+            return candidate;
+    }
+    return null;
+}
 function renameIntegerPhases(phasesDir, removedInt) {
     const renamedDirs = [];
     const renamedFiles = [];
+    const renamedFileCollisions = [];
     const dirs = readSubdirectories(phasesDir, true);
     const toRename = dirs
         .map((dir) => {
@@ -1069,7 +1487,8 @@ function renameIntegerPhases(phasesDir, removedInt) {
         if (!m)
             return null;
         const dirInt = parseInt(m[1], 10);
-        return dirInt > removedInt && dirInt !== 999
+        // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+        return dirInt > removedInt && !isSentinelPhaseId(dirInt)
             ? {
                 dir,
                 oldInt: dirInt,
@@ -1090,21 +1509,77 @@ function renameIntegerPhases(phasesDir, removedInt) {
         const oldPrefix = `${oldPadded}${letterSuffix}${decimalSuffix}`;
         const newPrefix = `${newPadded}${letterSuffix}${decimalSuffix}`;
         const newDirName = `${newPrefix}-${item.slug}`;
+        // WARNING-3 (#3511 review): the directory match above accepts an
+        // UNPADDED leading number (`\d+`), so a supported rename can pair a
+        // 2-padded dir with an unpadded-numbered artifact — dir `9-slug` holding
+        // `9-VERIFICATION.md`. Renaming files by `f.startsWith(oldPrefix)` alone
+        // (oldPrefix always 2-padded) misses that file: it becomes desynced from
+        // its now-renamed directory and the phase reads `missing`. Try the
+        // UNPADDED old-prefix form as a fallback so such an artifact renames
+        // alongside its directory. A trailing-digit boundary check keeps the
+        // unpadded form from over-matching a DIFFERENT phase's file (unpadded
+        // prefix "1" must not match "10-…").
+        const oldPrefixUnpadded = `${item.oldInt}${letterSuffix}${decimalSuffix}`;
         (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, item.dir), node_path_1.default.join(phasesDir, newDirName));
         renamedDirs.push({ from: item.dir, to: newDirName });
         for (const f of node_fs_1.default.readdirSync(node_path_1.default.join(phasesDir, newDirName))) {
+            let matchedPrefix = null;
             if (f.startsWith(oldPrefix)) {
-                const newFileName = newPrefix + f.slice(oldPrefix.length);
-                (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, newDirName, f), node_path_1.default.join(phasesDir, newDirName, newFileName));
+                matchedPrefix = oldPrefix;
+            }
+            else if (oldPrefixUnpadded !== oldPrefix &&
+                f.startsWith(oldPrefixUnpadded) &&
+                // Token-boundary check: the character immediately after the unpadded
+                // prefix must be a separator (`-`, `.`) or end-of-name, not any
+                // non-digit. A bare `!/^\d/` test (prior form) let a LETTER through
+                // too, so unpadded prefix "2" wrongly matched "2FA-notes.md" (a
+                // wholly unrelated file whose name merely starts with the digit).
+                (f.length === oldPrefixUnpadded.length || /^[-.]/.test(f.slice(oldPrefixUnpadded.length)))) {
+                matchedPrefix = oldPrefixUnpadded;
+            }
+            if (matchedPrefix) {
+                const newFileName = newPrefix + f.slice(matchedPrefix.length);
+                const destPath = node_path_1.default.join(phasesDir, newDirName, newFileName);
+                // Collision guard: the padded and unpadded prefix forms can both
+                // resolve to the SAME destination (e.g. `09-VERIFICATION.md` and
+                // `9-VERIFICATION.md` in one directory both target
+                // `08-VERIFICATION.md`), and a stray cross-phase file can already sit
+                // at the destination name (e.g. a leftover `08-VERIFICATION.md`
+                // belonging to a DIFFERENT phase, inside phase 9's directory).
+                // Renaming blindly over an existing target silently destroys
+                // whichever file loses; skipping the rename instead lets the stray
+                // outrank the phase's own renamed artifact once it lands at the
+                // canonical name. Neither is acceptable: move the OCCUPYING file
+                // aside first (never overwrite, never skip the real rename), then
+                // complete the intended rename so the phase's own artifact takes the
+                // canonical name. This also handles a target that was already
+                // claimed by an EARLIER file in this same pass, since that earlier
+                // rename already created it on disk.
+                if (node_fs_1.default.existsSync(destPath)) {
+                    const displacedName = findOrphanedDisplacementName(node_path_1.default.join(phasesDir, newDirName), newFileName);
+                    if (displacedName === null) {
+                        // No free displacement name within the bounded search — fall
+                        // back to skip-and-report rather than looping or overwriting.
+                        renamedFileCollisions.push({ from: f, to: newFileName, displaced_to: null });
+                        continue;
+                    }
+                    (0, shell_command_projection_cjs_1.retryRenameSync)(destPath, node_path_1.default.join(phasesDir, newDirName, displacedName));
+                    (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, newDirName, f), destPath);
+                    renamedFiles.push({ from: f, to: newFileName });
+                    renamedFileCollisions.push({ from: f, to: newFileName, displaced_to: displacedName });
+                    continue;
+                }
+                (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, newDirName, f), destPath);
                 renamedFiles.push({ from: f, to: newFileName });
             }
         }
     }
-    return { renamedDirs, renamedFiles };
+    return { renamedDirs, renamedFiles, renamedFileCollisions };
 }
 function decrementRoadmapPhaseNumber(raw, removedInt) {
     const num = parseInt(raw, 10);
-    if (!Number.isInteger(num) || num <= removedInt || num === 999)
+    // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+    if (!Number.isInteger(num) || num <= removedInt || isSentinelPhaseId(num))
         return raw;
     return String(num - 1);
 }
@@ -1113,13 +1588,15 @@ function decrementRoadmapPhaseToken(raw, removedInt) {
     if (!match)
         return raw;
     const num = parseInt(match[1], 10);
-    if (!Number.isInteger(num) || num <= removedInt || num === 999)
+    // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+    if (!Number.isInteger(num) || num <= removedInt || isSentinelPhaseId(num))
         return raw;
     return `${num - 1}${match[2] || ''}`;
 }
 function decrementRoadmapPaddedPhaseNumber(raw, removedInt) {
     const num = parseInt(raw, 10);
-    if (!Number.isInteger(num) || num <= removedInt || num === 999)
+    // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+    if (!Number.isInteger(num) || num <= removedInt || isSentinelPhaseId(num))
         return raw;
     return String(num - 1).padStart(raw.length, '0');
 }
@@ -1157,10 +1634,26 @@ function findDataRowLine(sectionText, dataRowIndex) {
     }
     return null;
 }
+// #3685: mirror requirementsUpdated's diff-tracking contract — the caller
+// (cmdPhaseRemove) used to report `roadmap_updated: true` unconditionally,
+// hardcoded regardless of whether this transform actually changed
+// ROADMAP.md's content. Returning a real before/after comparison here lets
+// the caller report accurately, the same fix #3685 applied to
+// `cmdPhaseComplete` and #2640/#2974 already applied to this same function's
+// sibling `stateUpdated` flag a few lines below in `cmdPhaseRemove`.
 function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, removedInt, cwd) {
-    withPlanningLock(cwd, () => {
-        let content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-        const escaped = escapeRegex(targetPhase);
+    return withPlanningLock(cwd, () => {
+        const originalContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        let content = originalContent;
+        const escaped = (0, pattern_cjs_1.escapeRegex)(targetPhase);
+        // #3572: ROADMAP headings and rows carry the normalized (zero-padded) form
+        // of a decimal id — `phase insert 1` writes `### Phase 01.1:` while the
+        // user's remove query is usually unpadded (`1.1`) — and integer headings
+        // legitimately appear both padded (`02`) and unpadded (`2`). A `0*` prefix
+        // makes the token padding-insensitive in both directions without widening
+        // to other ids: the token stays anchored between `Phase\s+`/line-start and
+        // `:`/whitespace/end, so `0*2` still never matches `Phase 12:`.
+        const padTolerant = `0*${escaped}`;
         // SECTION-DELETION (not a section-body edit) — removes the phase's ENTIRE
         // detail section INCLUDING its own heading line. Migrated onto deleteSection
         // (ADR-2143 §4 / markdown-sectionizer T7): it locates the target heading via
@@ -1172,9 +1665,9 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
         // such heading to stop at, so the lazy `[\s\S]*?` scan ran to EOF and swept
         // away everything after it — including a trailing `## Progress` heading and
         // its tracking table.
-        const phaseHeadingRe = new RegExp(`^Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
+        const phaseHeadingRe = new RegExp(`^Phase\\s+${padTolerant}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
         content = (0, markdown_sectionizer_cjs_1.deleteSection)(content, (h) => h.level >= 2 && h.level <= 4 && phaseHeadingRe.test(h.text));
-        content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*`, 'gi'), '');
+        content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${padTolerant}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*`, 'gi'), '');
         // ROW-DELETION (not a cell update) — removes the WHOLE Progress-table row
         // for a removed phase via deleteTableRow (ADR-2143 §7 row-removal sibling
         // of updateTableCell). Scoped to the `## Progress` section — mirroring
@@ -1201,7 +1694,7 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
             const matchRemovedProgressRow = (row) => {
                 const firstCellRaw = (Object.values(row)[0] ?? '').trim();
                 if (isDecimal) {
-                    return new RegExp(`^${escaped}\\.?(?:\\s|$)`, 'i').test(firstCellRaw);
+                    return new RegExp(`^${padTolerant}\\.?(?:\\s|$)`, 'i').test(firstCellRaw);
                 }
                 const leadingMatch = firstCellRaw.match(/^0*(\d+)(\.\d+)?/);
                 if (!leadingMatch || leadingMatch[2])
@@ -1216,7 +1709,7 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
         if (!isDecimal) {
             // #1729: fold an optional pre-colon ( ) tag into the suffix capture so it
             // is re-emitted verbatim — a tagged later phase still gets renumbered.
-            content = content.replace(/(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)((?:\s*\([^)\n]{0,200}\))?\s*:)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
+            content = content.replace(/(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)((?:\s*\([^)\r\n]{0,200}\))?\s*:)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
             content = content.replace(/(-\s*\[[ x]\]\s*.*?Phase\s+)(\d+)(\s*:|\s+)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseNumber(num, removedInt)}${suffix}`);
             // ORDINAL-RENUMBER — CELL EDIT (not row-deletion) — migrated onto
             // updateTableCell (ADR-2143 §7, sibling of the deleteTableRow scoping
@@ -1278,7 +1771,8 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
                         if (!m)
                             return false;
                         const num = parseInt(m[1], 10);
-                        if (!Number.isInteger(num) || num <= removedInt || num === 999)
+                        // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+                        if (!Number.isInteger(num) || num <= removedInt || isSentinelPhaseId(num))
                             return false;
                         processedOrdinalRows.add(index);
                         matchedRowIndex = index;
@@ -1291,7 +1785,7 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
                         const newContent = `${decremented}${m[2]}${current.slice(m[0].length)}`;
                         const targetLine = matchedRowIndex === null ? null : findDataRowLine(ordinalSection, matchedRowIndex);
                         const padMatch = targetLine
-                            ? new RegExp(`^[ \\t]*\\|(\\s*)${escapeRegex((0, markdown_table_cjs_1.escapeCell)(current))}(\\s*)\\|`).exec(targetLine)
+                            ? new RegExp(`^[ \\t]*\\|(\\s*)${(0, pattern_cjs_1.escapeRegex)((0, markdown_table_cjs_1.escapeCell)(current))}(\\s*)\\|`).exec(targetLine)
                             : null;
                         const leadPad = padMatch ? padMatch[1] : ' ';
                         const trailPad = padMatch ? padMatch[2] : ' ';
@@ -1308,8 +1802,43 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
             content = content.replace(/(Depends on:\*\*\s*Phase\s+)(\d+(?:\.\d+)?)\b/gi, (_match, prefix, num) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}`);
         }
         (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, content);
+        // #3685 / #3691: compare NORMALIZED bytes (what platformWriteSync actually
+        // persists), not the raw pre-normalize `content` string, against the raw
+        // pre-mutation `originalContent` read above — a raw `!==` here reports a
+        // false `true` whenever this transform's regenerated output takes a
+        // different-but-equivalent shape than the already-normalized on-disk
+        // original (same normalization-order artifact #3685 fixed at
+        // cmdMilestoneComplete; see contentChangedAfterNormalize's own doc).
+        return (0, shell_command_projection_cjs_1.contentChangedAfterNormalize)(roadmapPath, originalContent, content);
     });
 }
+/**
+ * #3572: insert `fieldLine` at the start of STATE.md's BODY — immediately after
+ * the leading frontmatter block's closing `---` fence — so a body field never
+ * lands before the opening fence. The former whole-content prepend
+ * (`field + content`) put the line ABOVE the opening `---`, and
+ * syncStateFrontmatter then treated the scrambled fence structure as TWO
+ * frontmatter blocks, rebuilding a derived one on top of the original
+ * (milestone_name from a ROADMAP heading, total_phases counting the removed
+ * phase, a stray 'Total Phases: 0' between fences). A file with no leading
+ * frontmatter is all body: the field goes to content start, preserving the
+ * former behavior for that shape.
+ */
+function insertStateBodyFieldAtTop(content, fieldLine) {
+    // Split AND join on bare '\n' so CRLF line endings stay attached to their
+    // own lines — each '\r' remains the tail of the line it terminated, where
+    // the trimmed fence compare still matches it. (#3572 review: splitting on
+    // '\n' but re-joining on a detected '\r\n' doubled every carriage return.)
+    const lines = content.split('\n');
+    if ((lines[0] ?? '').trim() === '---') {
+        const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+        if (closeIdx !== -1) {
+            lines.splice(closeIdx + 1, 0, '', fieldLine);
+            return lines.join('\n');
+        }
+    }
+    return fieldLine + '\n' + content;
+}
 function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     if (!targetPhase)
         error('phase number required for phase remove');
@@ -1321,24 +1850,55 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     const isDecimal = targetPhase.includes('.');
     const force = options.force || false;
     const subdirs = readSubdirectories(phasesDir, true);
-    const targetDir = subdirs.find((d) => phaseTokenMatches(d, normalized)) || null;
+    // #2237/#2528: every other resolution path refuses to choose between multiple
+    // directories claiming one phase number. This one is the DESTRUCTIVE path, so
+    // taking `matches[0]` silently is strictly worse than anywhere else: it turns
+    // "resolve nothing" into "delete one of two candidates, unrecoverably, and
+    // renumber every phase after it". Refuse before any file is touched.
+    const { matches: phaseDirMatches } = matchPhaseDirs(subdirs, normalized);
+    if (phaseDirMatches.length > 1) {
+        output({
+            removed: null,
+            error: `Phase ${normalized} is ambiguous: ${phaseDirMatches.length} directories match `
+                + `(${phaseDirMatches.map((m) => `"${m}"`).join(', ')}). Refusing to remove any of them. `
+                + 'Set a distinct project_code in .planning/config.json, or pass the full directory name.',
+            ambiguous_matches: phaseDirMatches,
+            directory_deleted: null,
+            renamed_directories: [],
+            renamed_files: [],
+            roadmap_updated: false,
+            state_updated: false,
+        }, raw);
+        return;
+    }
+    const targetDir = phaseDirMatches[0] || null;
     if (targetDir && !force) {
-        const files = node_fs_1.default.readdirSync(node_path_1.default.join(phasesDir, targetDir));
-        const summaries = files.filter((f) => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
-        if (summaries.length > 0) {
-            error(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`);
+        // #3183: canonical summary set (root+nested) from the single owner —
+        // a root-only readdirSync filter left nested (#3139 layout) summaries
+        // invisible, letting a phase with completed nested work be deleted
+        // without --force.
+        const summaryCount = scanPhasePlans(node_path_1.default.join(phasesDir, targetDir)).summaryFiles.length;
+        if (summaryCount > 0) {
+            error(`Phase ${targetPhase} has ${summaryCount} executed plan(s). Use --force to remove anyway.`);
         }
     }
     if (targetDir)
         node_fs_1.default.rmSync(node_path_1.default.join(phasesDir, targetDir), { recursive: true, force: true });
     let renamedDirs = [];
     let renamedFiles = [];
+    let renamedFileCollisions = [];
     try {
-        const renamed = isDecimal
-            ? renameDecimalPhases(phasesDir, parseInt(normalized.split('.')[0], 10), parseInt(normalized.split('.')[1], 10))
-            : renameIntegerPhases(phasesDir, parseInt(normalized, 10));
-        renamedDirs = renamed.renamedDirs;
-        renamedFiles = renamed.renamedFiles;
+        if (isDecimal) {
+            const renamed = renameDecimalPhases(phasesDir, parseInt(normalized.split('.')[0], 10), parseInt(normalized.split('.')[1], 10));
+            renamedDirs = renamed.renamedDirs;
+            renamedFiles = renamed.renamedFiles;
+        }
+        else {
+            const renamed = renameIntegerPhases(phasesDir, parseInt(normalized, 10));
+            renamedDirs = renamed.renamedDirs;
+            renamedFiles = renamed.renamedFiles;
+            renamedFileCollisions = renamed.renamedFileCollisions;
+        }
     }
     catch (e) {
         // #2245 audit (was ERROR-HIDING): renameDecimalPhases/renameIntegerPhases
@@ -1353,7 +1913,7 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
         const msg = e instanceof Error ? e.message : String(e);
         error(`Failed to renumber phase directories after removing phase ${targetPhase}: ${msg}`);
     }
-    updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, parseInt(normalized, 10), cwd);
+    const roadmapUpdated = updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, parseInt(normalized, 10), cwd);
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
     let stateUpdated = false;
     if (node_fs_1.default.existsSync(statePath)) {
@@ -1367,13 +1927,15 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
             let modified = stateContent;
             const totalRaw = stateExtractField(modified, 'Total Phases');
             if (totalRaw) {
+                // #3572 review: clamp at 0 — a stale 'Total Phases: 0' (e.g. written by
+                // an earlier remove whose dir-count was 0) must not decrement to -1 on
+                // the next removal.
                 modified =
-                    stateReplaceField(modified, 'Total Phases', String(parseInt(totalRaw, 10) - 1)) ||
-                        modified;
+                    stateReplaceField(modified, 'Total Phases', String(Math.max(0, parseInt(totalRaw, 10) - 1))) || modified;
             }
             const ofMatch = modified.match(/(\bof\s+)(\d+)(\s*(?:\(|phases?))/i);
             if (ofMatch) {
-                modified = modified.replace(/(\bof\s+)(\d+)(\s*(?:\(|phases?))/i, `$1${parseInt(ofMatch[2], 10) - 1}$3`);
+                modified = modified.replace(/(\bof\s+)(\d+)(\s*(?:\(|phases?))/i, `$1${Math.max(0, parseInt(ofMatch[2], 10) - 1)}$3`);
             }
             // #2640: if neither body field was found, the transform is a no-op.
             // readModifyWriteStateMd's no-op guard (#948) would then skip the
@@ -1386,16 +1948,33 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
             if (targetDir && modified === stateContent) {
                 // subdirs was read before the deletion; excluding the removed target
                 // gives the remaining count. Renumbering changes names but not count.
-                const remainingPhases = subdirs.filter((d) => phaseTokenMatches(d, normalized) === false).length;
+                //
+                // #2528: exclude the directory that was ACTUALLY deleted, by identity,
+                // rather than re-deriving "which dir was the target" from the query.
+                // The two are not the same predicate here: `targetDir` comes from
+                // `matchPhaseDirs`, whose bare-integer fallback resolves digit-leading
+                // dirs (`05-80-20-cleanup` for query `5`) that `phaseTokenMatches`
+                // reports as non-matching — so a token re-derivation would count the
+                // just-deleted directory as still present and write a `Total Phases`
+                // one too high. Identity is also what the comment above already
+                // claims this filter does, and the block is gated on targetDir.
+                // (#3572 note: this body field counts DIRECTORIES on disk; the
+                // frontmatter progress.* block is rebuilt by syncStateFrontmatter
+                // from the post-removal ROADMAP — the two counts legitimately differ
+                // when phases exist in ROADMAP without directories.)
+                const remainingPhases = Math.max(0, subdirs.filter((d) => d !== targetDir).length);
                 if (totalRaw) {
                     modified =
                         stateReplaceField(modified, 'Total Phases', String(remainingPhases)) || modified;
                 }
                 else {
-                    // No 'Total Phases:' field in the body — append one so the no-op
-                    // guard sees a diff. syncStateFrontmatter will then rebuild the
-                    // frontmatter progress.* block from the real disk/ROADMAP count.
-                    modified = `Total Phases: ${remainingPhases}\n` + modified;
+                    // No 'Total Phases:' field in the body — insert one at the start of
+                    // the BODY so the no-op guard sees a diff. #3572: the former
+                    // whole-content prepend landed the line BEFORE the opening '---'
+                    // fence and corrupted STATE.md into two frontmatter blocks.
+                    // syncStateFrontmatter will still rebuild the frontmatter
+                    // progress.* block from the real disk/ROADMAP count.
+                    modified = insertStateBodyFieldAtTop(modified, `Total Phases: ${remainingPhases}`);
                 }
             }
             return modified;
@@ -1406,10 +1985,28 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
         directory_deleted: targetDir,
         renamed_directories: renamedDirs,
         renamed_files: renamedFiles,
-        roadmap_updated: true,
+        renamed_file_collisions: renamedFileCollisions,
+        // #3685: mirror requirementsUpdated's diff-tracking contract — true only
+        // when updateRoadmapAfterPhaseRemoval's content diff detected a real
+        // change, not hardcoded regardless of whether ROADMAP.md's content
+        // actually changed.
+        roadmap_updated: roadmapUpdated,
         state_updated: stateUpdated,
     }, raw);
+    // #3227: unconditional here because `updateRoadmapAfterPhaseRemoval` above
+    // always rewrites ROADMAP.md before this line is reached; every refusal path
+    // (bad target, missing ROADMAP.md, --force-required, renumber failure) exits
+    // via `error()`, and the ambiguous-match case exits via an earlier `return`
+    // before any file is touched.
+    publishStateContract(cwd);
 }
+/**
+ * #3227: returns the count of writes actually applied (entries whose
+ * `before` differed from `after` and were therefore written to disk) — the
+ * caller (`cmdPhaseComplete`) uses this as its publish-gate signal, since a
+ * re-run against an already-completed phase can produce a `writes[]` array
+ * where every entry is byte-identical to what's already on disk.
+ */
 function writePlanningFileSet(writes) {
     const applied = [];
     try {
@@ -1439,6 +2036,7 @@ function writePlanningFileSet(writes) {
         }
         throw err;
     }
+    return applied.length;
 }
 function phaseDisplayNameFromRoadmap(roadmapContent, phaseNum) {
     if (!roadmapContent || !phaseNum)
@@ -1467,11 +2065,27 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     // init.progress got (resolution: GSD_WORKSTREAM env > stored active pointer; an
     // explicit --ws sets GSD_WORKSTREAM upstream and satisfies the check).
     const availableWorkstreams = listAvailableWorkstreams(cwd);
-    const resolvedWorkstream = process.env['GSD_WORKSTREAM'] || getActiveWorkstream(cwd);
+    // #3579 root-cause fix: this is a check, not a consuming read — use the
+    // non-mutating peek so an unresolvable pointer isn't self-healed (cleared)
+    // here and then found "absent" by diagnoseUnresolvedActiveWorkstream below,
+    // which would misreport a present-but-bad marker as no marker at all.
+    const resolvedWorkstream = process.env['GSD_WORKSTREAM'] || peekActiveWorkstream(cwd);
     if (availableWorkstreams.length > 0 && !resolvedWorkstream) {
+        // #3579: getActiveWorkstream now inherits a pointer-less session's read
+        // from the shared .planning/active-workstream marker, so reaching this
+        // branch with a marker actually present means the marker EXISTED but
+        // didn't resolve (invalid name, or its workstream dir is gone) — a
+        // materially different situation from "nothing was ever set" and one
+        // that deserves its own diagnostic instead of the generic message below.
+        const diagnosis = diagnoseUnresolvedActiveWorkstream(cwd);
+        if (diagnosis.present) {
+            error(`phase.complete requires a workstream in workstream mode — the active-workstream marker names '${diagnosis.value}', but it did not resolve: ${describeUnresolvedWorkstreamReason(diagnosis.reason)}. Root STATE.md/ROADMAP.md (likely stale) would be written otherwise. ` +
+                `Pass --ws <name> or run ${(0, runtime_slash_cjs_1.formatGsdSlash)('workstream set', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} to point it at an existing workstream. ` +
+                `Available workstreams: ${availableWorkstreams.join(', ')}`, ERROR_REASON.WORKSTREAM_MODE_MARKER_UNRESOLVED, { marker_value: diagnosis.value, marker_reason: diagnosis.reason });
+        }
         error(`phase.complete requires a workstream in workstream mode — no active workstream is set, so root STATE.md/ROADMAP.md (likely stale) would be written. ` +
             `Pass --ws <name> or run ${(0, runtime_slash_cjs_1.formatGsdSlash)('workstream set', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} first. ` +
-            `Available workstreams: ${availableWorkstreams.join(', ')}`);
+            `Available workstreams: ${availableWorkstreams.join(', ')}`, ERROR_REASON.WORKSTREAM_MODE_NONE_ACTIVE);
     }
     const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
@@ -1489,7 +2103,25 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         ? phaseInfo['summaries'].length
         : 0;
     let requirementsUpdated = false;
+    // #3685: mirror requirementsUpdated's diff-tracking contract at the
+    // writes.push({filePath, before, after}) sites below, rather than
+    // reporting via fs.existsSync (which is true whenever the file merely
+    // exists, not when the transaction actually wrote a change).
+    let roadmapUpdated = false;
+    let stateUpdated = false;
     const warnings = [];
+    // ADR-3408 §8.5 / D2 (#3374): "liberal but visible" — when the write-seam
+    // composition's preservation stage restores a curated frontmatter value
+    // over a disagreeing derived one, that divergence is surfaced here rather
+    // than silently absorbed. Structured (field + reason), not prose, so a
+    // caller can assert on the value rather than regex a rendered message.
+    // Named `preservation_warnings`, NOT `warnings`: `warnings` above is
+    // already a prose `string[]` on this exact command — reusing it for a
+    // structured `{field, reason}[]` shape would be the "Generative Fix
+    // Divergence" anti-pattern (two sibling fields, same name, different
+    // element types). Mirrors `cmdMilestoneComplete`'s identical field
+    // (milestone.cts).
+    const preservationWarnings = [];
     // #3057 B3: mirrors `verification_stale_check_indeterminate` on init.cts /
     // roadmap.cts / uat-predicate.cts's outputs — set on the non-blocking path
     // below (inside withPlanningLock) alongside the warnings[] entry, so a
@@ -1564,7 +2196,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     }
     try {
         const phaseFiles = node_fs_1.default.readdirSync(phaseFullDir);
-        for (const file of phaseFiles.filter((f) => f.includes('-UAT') && f.endsWith('.md'))) {
+        // #3511: scope this advisory pre-scan to THIS phase's own token so a
+        // stray, cross-phase, or ad-hoc file cannot name a warning against a
+        // phase it does not belong to.
+        const phaseFullDirBaseName = node_path_1.default.basename(phaseFullDir);
+        for (const file of scopeToPhase(phaseFiles.filter((f) => f.includes('-UAT') && f.endsWith('.md')), phaseFullDirBaseName)) {
             const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, file), 'utf-8');
             if (/result: pending/.test(content))
                 warnings.push(`${file}: has pending tests`);
@@ -1575,9 +2211,14 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             if (/status: diagnosed/.test(content))
                 warnings.push(`${file}: has diagnosed gaps`);
         }
-        for (const file of phaseFiles.filter((f) => f.includes('-VERIFICATION') && f.endsWith('.md'))) {
+        for (const file of scopeToPhase(phaseFiles.filter((f) => f.includes('-VERIFICATION') && f.endsWith('.md')), phaseFullDirBaseName)) {
             const verificationFilePath = node_path_1.default.join(phaseFullDir, file);
-            const content = node_fs_1.default.readFileSync(verificationFilePath, 'utf-8');
+            // #3707-CR follow-up MINOR: normalize line endings at this read boundary
+            // (same fix as src/verification.cts's readVerificationStatus) so a
+            // lone-CR VERIFICATION.md's `---\r...\r---` frontmatter fence still
+            // matches extractFrontmatter's byte-0 check instead of silently
+            // dropping the human_needed/gaps_found advisory warning below.
+            const content = normalizeLineEndings(node_fs_1.default.readFileSync(verificationFilePath, 'utf-8'));
             // #1159 (Defect A): read ONLY the frontmatter `status` key to avoid false positives
             // from historical metadata in the file body (e.g. `previous_status: gaps_found`).
             // A full-text regex like /status: gaps_found/ matches the substring inside
@@ -1639,7 +2280,33 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     let nextPhaseNum = null;
     let nextPhaseName = null;
     let isLastPhase = true;
+    // #3311: typed conflict descriptor surfaced on the result JSON alongside the
+    // warnings[] entry below (same parity pattern as
+    // verification_stale_check_indeterminate).
+    let milestoneConflict = null;
+    // #3227: set inside `runPhaseCompleteTransaction` below from
+    // `writePlanningFileSet`'s applied-count return — the transaction always
+    // RUNS (verification passed, the lock was taken, `writes[]` was built),
+    // but a re-run against a phase whose ROADMAP/STATE bytes already reflect
+    // completion produces a `writes[]` where every entry is byte-identical to
+    // disk, so `writePlanningFileSet` applies none of them. That must not
+    // still refresh state.json's `updated_at` (design doc §40 row 26).
+    let anyPlanningWrite = false;
     const verificationBlocked = withPlanningLock(cwd, () => {
+        // #3311: completing a phase while a live milestone claim (phase + session)
+        // holds a DIFFERENT phase means two sessions are working two phases against
+        // the single Current Position slot. Warn via the established warnings[]
+        // channel (rendered by execute-phase.md's "If has_warnings is true" step)
+        // rather than blocking — the claim may simply be stale-but-live.
+        milestoneConflict = milestoneLockMod.checkMilestoneConflictForPhase(cwd, phaseNum);
+        if (milestoneConflict) {
+            const holder = milestoneConflict.locked_session ?? 'an unknown (headless) session';
+            const actor = milestoneConflict.session ?? 'an unknown (headless) session';
+            warnings.push(`milestone lock conflict (#3311): ${holder} holds the milestone claim for phase ` +
+                `${milestoneConflict.locked_phase}, but ${actor} is completing phase ${phaseNum} — ` +
+                `STATE.md's Current Position is a single slot; verify it before trusting it`);
+            milestoneLockMod.warnMilestoneConflict(milestoneConflict, `phase.complete ${phaseNum}`);
+        }
         // #2617: pass the project's runtime so the blocked-completion error below
         // suggests the command surface this runtime actually installs
         // ($gsd-… on Codex) rather than a hard-coded Claude-style string.
@@ -1786,7 +2453,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
                             if (!planId)
                                 continue;
-                            const planEscaped = escapeRegex(planId);
+                            const planEscaped = (0, pattern_cjs_1.escapeRegex)(planId);
                             const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
                             b = b.replace(planCheckboxPattern, '$1x$2');
                         }
@@ -1816,6 +2483,12 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     before: originalRoadmapContent,
                     after: roadmapContent,
                 });
+                // #3685 / #3691: normalize both sides before comparing — see
+                // contentChangedAfterNormalize's doc (shell-command-projection.cts).
+                // A raw `!==` here false-positives whenever this phase-complete
+                // roadmap mutation regenerates a section in a different-but-
+                // equivalent raw shape than the already-normalized on-disk original.
+                roadmapUpdated = (0, shell_command_projection_cjs_1.contentChangedAfterNormalize)(roadmapPath, originalRoadmapContent, roadmapContent);
                 const reqPath = node_path_1.default.join(planningDir(cwd), 'REQUIREMENTS.md');
                 if (node_fs_1.default.existsSync(reqPath)) {
                     const phaseEsc = phaseMarkdownRegexSource(phaseNum);
@@ -1862,7 +2535,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             .filter(Boolean)
                             .filter((r) => REQ_ID_SHAPE_RE.test(r));
                         for (const reqId of citedReqIds) {
-                            const reqEscaped = escapeRegex(reqId);
+                            const reqEscaped = (0, pattern_cjs_1.escapeRegex)(reqId);
                             // Surface 1 — the checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**.
                             // #2945: the flip is CONDITIONAL (porting #2788 defect-2's rollback from
                             // cmdRequirementsMarkComplete). Capture the pre-flip content; if a
@@ -2069,7 +2742,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     // row actually matched is registered — not a ghost — regardless of
                     // which section (deferred or not) it lives under.
                     const reqIsRegisteredAnywhere = (id) => {
-                        const reqEscaped = escapeRegex(id);
+                        const reqEscaped = (0, pattern_cjs_1.escapeRegex)(id);
                         // Surface 1 — checkbox, EITHER state (`[ ]` or `[x]`), case-
                         // insensitive: existence check, not the write's space-only match.
                         if (new RegExp(`-\\s*\\[[ xX]\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent)) {
@@ -2102,27 +2775,67 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     // diff-tracking pattern used for the ROADMAP write above. A phase
                     // whose citations match nothing (ghost REQ-IDs only) must report
                     // `false`, not a bare "the file was present" `true`.
-                    requirementsUpdated = reqContent !== originalReqContent;
+                    // #3685 / #3691: normalize both sides before comparing — same
+                    // false-positive shape as the sibling roadmapUpdated/stateUpdated
+                    // flags in this same transaction; all three must agree by
+                    // construction (see contentChangedAfterNormalize's doc).
+                    requirementsUpdated = (0, shell_command_projection_cjs_1.contentChangedAfterNormalize)(reqPath, originalReqContent, reqContent);
                 }
             }
+            // #3701 — the ROADMAP decides WHICH phase is next; the disk decides only HOW it
+            // is spelled. Both scans select the numerically lowest phase above N.
+            //
+            // Both scans below are unchanged in what they match; what changed is that
+            // the roadmap is no longer gated behind "the disk found nothing". It used
+            // to be (`if (isLastPhase && roadmapContent !== null)`), which made a wrong
+            // disk answer uncorrectable: phase directories are created lazily, but
+            // `phase insert` scaffolds an inserted phase's directory immediately, so an
+            // inserted decimal is routinely the ONLY directory above N and outranked
+            // every phase preceding it in the roadmap. Observed: roadmap `1, 2, 02.1,
+            // 3` with directories for 01 and 02.1 only reported `next_phase: "02.1"`
+            // after completing 1 — and PERSISTED it to STATE.md — while
+            // `roadmap.analyze` correctly said `2`.
+            //
+            // #3581 fixed exactly this at `init.progress` and named the rule: "the
+            // frontier is ROADMAP ORDER, not artifact presence". This call site was not
+            // in that change's scope.
+            //
+            // Why the disk scan survives, rather than being replaced:
+            //   1. It is the only resolver when there is no ROADMAP.md, or when its
+            //      phase rows do not parse.
+            //   2. When both agree, it carries the SPELLING the output has always used
+            //      — the zero-padded directory token and the on-disk slug (`02`/`beta`),
+            //      where the roadmap would give `2` and a slugified title. Promoting the
+            //      roadmap without this would silently change the reported value on
+            //      every aligned project, which is the majority case.
+            let diskNextNum = null;
+            let diskNextName = null;
+            let roadmapNextNum = null;
+            let roadmapNextName = null;
             try {
-                const isDirInMilestone = getMilestonePhaseFilter(cwd);
-                const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-                const dirs = entries
-                    .filter((e) => e.isDirectory())
-                    .map((e) => e.name)
-                    .filter(isDirInMilestone)
-                    .sort((a, b) => comparePhaseNum(a, b));
+                // #3185 (ADR-3180 Decision 1): "which phase directories belong to
+                // the CURRENT milestone" — routed through the canonical owner
+                // instead of a hand-rolled readdirSync + isDirInMilestone filter
+                // (which also never excluded sentinels on its own, unlike the
+                // owner; the per-directory isSentinelPhaseId check below stays as a
+                // defensive second check against the REGEX-EXTRACTED token, which
+                // is not necessarily identical to the raw directory name).
+                const dirs = listMilestonePhaseDirs(phasesDir, { cwd }).value;
                 for (const dir of dirs) {
                     const dm = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})-?(.*)`, 'i'));
                     if (dm) {
-                        if (/^999(?:\.|$)/.test(dm[1]))
+                        // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+                        if (isSentinelPhaseId(dm[1]))
                             continue;
-                        if (comparePhaseNum(dm[1], phaseNum) > 0) {
-                            nextPhaseNum = dm[1];
-                            nextPhaseName = dm[2] || null;
-                            isLastPhase = false;
-                            break;
+                        // Numeric MINIMUM above N, not "first encountered". `listMilestonePhaseDirs`
+                        // does sort by `comparePhaseNum`, so a `break` on the first hit happens to be
+                        // correct today — but that makes this scan's correctness depend on an
+                        // upstream sort nothing here states. Selecting the minimum explicitly costs
+                        // one comparison and removes the hidden coupling.
+                        if (comparePhaseNum(dm[1], phaseNum) > 0
+                            && (diskNextNum === null || comparePhaseNum(dm[1], diskNextNum) < 0)) {
+                            diskNextNum = dm[1];
+                            diskNextName = dm[2] || null;
                         }
                     }
                 }
@@ -2136,7 +2849,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                  * derives the same information independently from ROADMAP.md content
                  * — not a silent data-loss path. */
             }
-            if (isLastPhase && roadmapContent !== null) {
+            if (roadmapContent !== null) {
                 try {
                     const roadmapForPhases = extractCurrentMilestone(roadmapContent, cwd);
                     // #1591: match BOTH heading-style phases (`### Phase N:`) AND
@@ -2158,20 +2871,32 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     let pm;
                     while ((pm = phasePattern.exec(roadmapForPhases)) !== null) {
                         // #2786: skip sentinel phase ids (999.x backlog, 0.x drafts) — stage 1
-                        // already skips 999 dirs on disk; stage 2's heading scan must not
-                        // advance into backlog headings. Mirrors the /^999(?:\.|$)/ guard
-                        // stage 1 uses at line 2536, but via isSentinelPhaseId for both ranges.
+                        // already skips sentinel dirs on disk via isSentinelPhaseId (#3185);
+                        // stage 2's heading scan must not advance into backlog headings either.
                         if (isSentinelPhaseId(pm[1]))
                             continue;
-                        if (comparePhaseNum(pm[1], phaseNum) > 0) {
-                            nextPhaseNum = pm[1];
-                            nextPhaseName = pm[2]
+                        // #3701 review: the numeric MINIMUM above N, not the first row above N in
+                        // DOCUMENT order. This scan walks raw roadmap text, and one global regex
+                        // sweeps both the `## Phases` checklist and the `## Phase Details`
+                        // headings, so "first match" is a statement about where a line sits in the
+                        // file — not about which phase comes next.
+                        //
+                        // It mattered only once this scan started deciding the answer. Before, it
+                        // ran solely when the disk scan found nothing; now it outranks the disk, so
+                        // a roadmap listing rows out of numeric sequence (`1, 3, 2`) reported
+                        // `next_phase: 3` and PERSISTED it, skipping Phase 2 — on an input the
+                        // pre-#3701 code got right, because the disk scan is numerically sorted.
+                        // Phase NUMBERS define sequence here, exactly as `comparePhaseNum` does for
+                        // the disk scan and for #2028's lowest-outstanding override; the roadmap
+                        // defines which phases EXIST and which milestone they belong to.
+                        if (comparePhaseNum(pm[1], phaseNum) > 0
+                            && (roadmapNextNum === null || comparePhaseNum(pm[1], roadmapNextNum) < 0)) {
+                            roadmapNextNum = pm[1];
+                            roadmapNextName = pm[2]
                                 .replace(/\(INSERTED\)/i, '')
                                 .trim()
                                 .toLowerCase()
                                 .replace(/\s+/g, '-');
-                            isLastPhase = false;
-                            break;
                         }
                     }
                 }
@@ -2182,6 +2907,25 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                      * regardless and provides a further, independent override. */
                 }
             }
+            // Resolve. The roadmap wins on identity; the disk wins on spelling when it
+            // is talking about the same phase.
+            if (roadmapNextNum !== null) {
+                // Same comparator both scans already use to order phases, so "the disk
+                // and the roadmap mean the same phase" cannot drift from "N is above the
+                // one just completed". `02` and `2` compare equal, which is the whole
+                // point — they are the same phase spelled two ways.
+                const diskAgrees = diskNextNum !== null && comparePhaseNum(diskNextNum, roadmapNextNum) === 0;
+                nextPhaseNum = diskAgrees ? diskNextNum : roadmapNextNum;
+                nextPhaseName = diskAgrees ? diskNextName : roadmapNextName;
+                isLastPhase = false;
+            }
+            else if (diskNextNum !== null) {
+                // No usable roadmap (absent, unreadable, or no parseable phase rows) —
+                // the disk is all there is. Unchanged from the pre-#3701 behaviour.
+                nextPhaseNum = diskNextNum;
+                nextPhaseName = diskNextName;
+                isLastPhase = false;
+            }
             // #2028: don't stamp "All phases complete" when a LOWER-numbered phase is
             // still outstanding. The two blocks above only clear isLastPhase when a
             // HIGHER-numbered phase exists, so completing the numerically-highest phase
@@ -2196,7 +2940,17 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             // pattern mirrors the sibling phasePattern's anchoring (only whitespace/bold
             // between the box and "Phase", a required `:`) so unrelated checklist lines
             // that merely mention "Phase N" don't match.
-            if (isLastPhase && roadmapContent !== null) {
+            // #3350: this stage answers a DIFFERENT question than stages 1-2 ("what is
+            // the next actionable phase?" vs "is this the last phase?"), so it must not
+            // be gated on their answer. Gating on isLastPhase let a merely-positionally
+            // next higher heading (stage 2) permanently mask a genuinely-outstanding
+            // lower phase — stage 2 cleared isLastPhase and this scan never ran. The
+            // scan already refuses anything not strictly lower than the completed phase
+            // (plus sentinels, #2949), so running it unconditionally cannot manufacture
+            // a wrong answer: when no lower phase is outstanding it finds nothing and
+            // stages 1-2's pick stands unchanged; in the masking case isLastPhase is
+            // already false, so the last-phase signal has no reachable regression.
+            if (roadmapContent !== null) {
                 try {
                     const milestoneScope = extractCurrentMilestone(roadmapContent, cwd);
                     const cbPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*(?:\\*\\*|__)?\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n*]+)`, 'gi');
@@ -2243,11 +2997,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 // to the STATE.md Transition Module. The ~90-line inline RMW callback
                 // that lived here is the pure `completePhaseCore` in
                 // src/state-transition.cts, backed by the field-classification table.
-                // `updatePerformanceMetricsSection` + `syncStateFrontmatter` stay in
-                // this adapter: they are section-table / disk-scan concerns, not
-                // classified fields, and `syncStateFrontmatter` is the post-sync this
-                // transaction needs (it does NOT go through readModifyWriteStateMd
-                // because STATE.md is committed atomically with ROADMAP/REQUIREMENTS).
+                // `updatePerformanceMetricsSection` stays in this adapter: it is a
+                // section-table / disk-scan concern, not a classified field. The
+                // sync + post-sync preservation this transaction needs runs via the
+                // single write-seam composition, `syncAndPreserveStateMd` (it does
+                // NOT go through readModifyWriteStateMd because STATE.md is
+                // committed atomically with ROADMAP/REQUIREMENTS, ADR-3408 §8.3 /
+                // #3374 / #3469).
                 const nextPhaseDisplayName = phaseDisplayNameFromRoadmap(roadmapContent, nextPhaseNum) ??
                     phaseDisplayNameFromSlug(nextPhaseName);
                 const completeResult = (0, state_transition_cjs_1.transitionCore)(stateContent, {
@@ -2269,10 +3025,64 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 // the intent; pass it as authoritative so the sync's prose
                 // re-derivation cannot rewrite current_phase_name to the name's own
                 // parenthetical (`Closer-ruling measurement (D1a)` → `D1a`).
-                stateContent = syncStateFrontmatter(stateContent, cwd, nextPhaseDisplayName ? { current_phase_name: nextPhaseDisplayName } : undefined);
+                // #3350: PAIR the override. When STATE.md's body carries no Current
+                // Phase / Phase field to re-derive from (narrative prose), the #905
+                // preserve guard in syncStateFrontmatter keeps the OLD frontmatter
+                // current_phase while the authoritative current_phase_name advances —
+                // leaving the two fields describing different phases. Pin BOTH to the
+                // resolved next phase in that case. When the body DOES carry the field
+                // (completePhaseCore just rewrote it), stay name-only so the body's
+                // richer `N of T (name)` derived shape survives the sync.
+                const fmBody = frontmatterMod.stripFrontmatter(stateContent);
+                const bodyHasPhaseField = stateExtractField(fmBody, 'Current Phase') != null ||
+                    stateExtractField(fmBody, 'Phase') != null;
+                const authoritativeFm = nextPhaseDisplayName
+                    ? bodyHasPhaseField || !nextPhaseNum
+                        ? { current_phase_name: nextPhaseDisplayName }
+                        : {
+                            current_phase: String(nextPhaseNum),
+                            current_phase_name: nextPhaseDisplayName,
+                        }
+                    : undefined;
+                // ADR-3408 §8.3 / #3469: this deliberately bypasses
+                // readModifyWriteStateMd (STATE.md is committed atomically with
+                // ROADMAP/REQUIREMENTS), so it calls the single write-seam
+                // composition (`syncAndPreserveStateMd`) directly instead of
+                // assembling `syncStateFrontmatter` + `applyPostSyncPreservation`
+                // itself — a call site re-assembling the pair, even with every step
+                // calling an owner, is the exact re-derivation §8.3 forbids by name
+                // (Phase 2 found this shape live here). The composition runs
+                // snapshots from the on-disk pre-image (originalStateContent) and
+                // the transformed content, table-driven applyStatePreservation, then
+                // the #2736 authoritative re-assert (which restores the #3350
+                // pairing override the preserve-always restore may have reverted).
+                // resync=true is the lifecycle-transition posture (progress
+                // recomputed from disk; only the preserve-when-unchanged deltas
+                // apply). Fields the transition legitimately rewrote (Status, Phase,
+                // Stopped At via completePhaseCore's #3374 continuity line) have
+                // changed body sources, so their deltas do not fire.
+                // ADR-3408 §8.5 / D2 (#3374): thread `divergedFields` through so this
+                // command reports what it preserved, following `cmdMilestoneComplete`'s
+                // shape (milestone.cts) — the same composition, the same out-param,
+                // the same visibility contract.
+                const divergedFields = [];
+                stateContent = syncAndPreserveStateMd(originalStateContent, stateContent, statePath, cwd, {
+                    resync: true,
+                    authoritativeFm,
+                    divergedFields,
+                });
+                for (const field of divergedFields) {
+                    preservationWarnings.push({ field, reason: 'preserved-over-disagreeing-derived' });
+                }
                 writes.push({ filePath: statePath, before: originalStateContent, after: stateContent });
+                // #3685 / #3691: normalize both sides before comparing (same
+                // transitionCore-regenerated-section artifact cmdMilestoneComplete
+                // hit — see contentChangedAfterNormalize's doc). Reported "not
+                // exposed" by a previous agent; the reviewer disproved that by
+                // inspection and this branch closes it.
+                stateUpdated = (0, shell_command_projection_cjs_1.contentChangedAfterNormalize)(statePath, originalStateContent, stateContent);
             }
-            writePlanningFileSet(writes);
+            anyPlanningWrite = writePlanningFileSet(writes) > 0;
         };
         if (node_fs_1.default.existsSync(statePath)) {
             withStateLock(statePath, runPhaseCompleteTransaction);
@@ -2280,6 +3090,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         else {
             runPhaseCompleteTransaction();
         }
+        // #3311: a successful completion of the CLAIMED phase releases the
+        // milestone claim — regardless of which session completes it (an
+        // orchestrator cleaning up after a dead session must not be blocked by the
+        // dead session's own claim). No-ops when the claim names another phase.
+        milestoneLockMod.releaseMilestonePhase(cwd, phaseNum);
         return null;
     });
     if (verificationBlocked) {
@@ -2325,15 +3140,23 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         next_phase_name: nextPhaseName,
         is_last_phase: isLastPhase,
         date: today,
-        roadmap_updated: node_fs_1.default.existsSync(roadmapPath),
-        state_updated: node_fs_1.default.existsSync(statePath),
+        roadmap_updated: roadmapUpdated,
+        state_updated: stateUpdated,
         requirements_updated: requirementsUpdated,
         auto_pruned: autoPruned,
         warnings,
         has_warnings: warnings.length > 0,
         verification_stale_check_indeterminate: staleCheckIndeterminate,
+        milestone_conflict: milestoneConflict,
+        preservation_warnings: preservationWarnings,
     };
     output(result, raw);
+    // #3227: gate on `anyPlanningWrite` (whether `writePlanningFileSet`
+    // actually wrote anything), not on reaching this line — reaching here only
+    // means verification passed and the transaction ran, not that ROADMAP.md
+    // or STATE.md bytes changed (see the `anyPlanningWrite` declaration above).
+    if (anyPlanningWrite)
+        publishStateContract(cwd);
 }
 function cmdPhaseUatPassed(cwd, phaseNum, raw, opts = {}) {
     if (!phaseNum) {
@@ -2353,7 +3176,7 @@ function cmdPhaseUatPassed(cwd, phaseNum, raw, opts = {}) {
 // paths without re-discovering the phase directory themselves.
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
 const planScanMod = require("./plan-scan.cjs");
-const { scanPhasePlans } = planScanMod;
+const { scanPhasePlans, isCanonicalPlanFile } = planScanMod;
 function cmdPhaseListPlans(cwd, phaseNum, raw) {
     if (!phaseNum) {
         error('phase number required for phase list-plans');
@@ -2390,4 +3213,5 @@ module.exports = {
     cmdPhaseUatPassed,
     cmdPhaseListPlans,
     computeDependencyLevels,
+    buildShortFormToId,
 };