@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/markdown-table.cjs

@@ -23,6 +23,7 @@ exports.findTableBySchema = findTableBySchema;
 exports.findTableWithColumns = findTableWithColumns;
 exports.escapeCell = escapeCell;
 exports.appendQuickTaskRow = appendQuickTaskRow;
+exports.migrateQuickTasksTable = migrateQuickTasksTable;
 exports.resetQuickTaskRows = resetQuickTaskRows;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ─── Schema registry ──────────────────────────────────────────────────────────
@@ -657,6 +658,54 @@ function escapeCell(value) {
  * Raw Text Matching").
  */
 exports.QUICK_TASKS_SECTION_ABSENT = 'no Quick Tasks Completed section';
+/**
+ * #3860: heading predicate for STATE.md's Quick Tasks Completed section(s).
+ * The heading is a section LABEL, not data — milestone-scoped files
+ * legitimately carry suffixed headings (`### Quick Tasks Completed (v1.1+)`
+ * beside an archived `(v1.0)`), so the match is prefix-anchored with a word
+ * boundary, never exact: `Quick Tasks Completedness` must NOT match. Hoisted
+ * beside QUICK_TASKS_SECTION_ABSENT so `appendQuickTaskRow` and
+ * `resetQuickTaskRows` cannot drift apart again.
+ */
+const isQuickTasksHeading = (h) => /^quick tasks completed\b/i.test(h.text.trim());
+/**
+ * #3860: among ALL heading-matching sections, pick the first whose body is a
+ * table with a recognized Quick Tasks schema — a legacy/unparseable table
+ * first in document order no longer shadows a usable one further down. When
+ * NO section is usable, return the FIRST match so the caller's downstream
+ * error describes the real problem (unparseable/legacy table) instead of a
+ * false QUICK_TASKS_SECTION_ABSENT.
+ *
+ * Bounding: `collectSections` ends a candidate's body only at the NEXT
+ * matching heading — far too wide for splicing (it would swallow an
+ * intervening `## Deferred Items` table into the Quick Tasks body, and
+ * `appendQuickTaskRow`'s last-table-line scan would then splice the new row
+ * into that WRONG table). Each candidate is therefore re-collected through
+ * `collectSection` with an offset-precise predicate, whose default
+ * level-bounded stop (next heading of the same or higher level) is exactly
+ * the semantics the pre-#3860 single-section lookup had.
+ *
+ * Convention: "first" is document order — the newest-on-top layout the issue
+ * itself demonstrates (`(v1.1+)` above an archived `(v1.0)`). When several
+ * suffixed sections all carry recognized schemas, this layer has no signal
+ * for which milestone is active, so document order is the pinned tie-break.
+ */
+function selectQuickTasksSection(stateContent) {
+    const candidates = (0, markdown_sectionizer_cjs_1.collectSections)(stateContent, isQuickTasksHeading);
+    if (candidates.length === 0)
+        return null;
+    const boundedOf = (cand) => (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => h.offset === cand.heading.offset);
+    const firstBounded = boundedOf(candidates[0]);
+    for (const cand of candidates) {
+        const bounded = boundedOf(cand);
+        if (!bounded)
+            continue;
+        const parsed = parseMarkdownTable(bounded.body);
+        if (parsed.ok && matchTableSchema(parsed.value.columns)?.id === 'QuickTasks')
+            return bounded;
+    }
+    return firstBounded;
+}
 /**
  * Append one row to STATE.md's "Quick Tasks Completed" table.
  *
@@ -677,7 +726,7 @@ exports.QUICK_TASKS_SECTION_ABSENT = 'no Quick Tasks Completed section';
  * rows), preserving any surrounding blank lines/trailing content in the section.
  */
 function appendQuickTaskRow(stateContent, fields) {
-    const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
+    const section = selectQuickTasksSection(stateContent);
     if (!section) {
         return { ok: false, reason: exports.QUICK_TASKS_SECTION_ABSENT };
     }
@@ -697,7 +746,7 @@ function appendQuickTaskRow(stateContent, fields) {
     const rowNumber = parsed.value.rows.length + 1;
     const cellFor = (col) => {
         switch (col) {
-            case '#': return escapeCell(String(rowNumber));
+            case '#': return escapeCell(fields.quickId ?? String(rowNumber));
             case 'Description': return escapeCell(fields.description);
             case 'Date': return escapeCell(fields.date);
             case 'Commit': return escapeCell(fields.commit);
@@ -728,6 +777,128 @@ function appendQuickTaskRow(stateContent, fields) {
     const content = (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody);
     return { ok: true, value: { content, row, variant: match.label } };
 }
+// ─── migrateQuickTasksTable (#3730 option b) ───────────────────────────────
+/**
+ * Column-name → canonical-cell mapping for migrating a legacy Quick Tasks table
+ * (#3730). Name-based, case-insensitive; every column NOT in this map lands in
+ * the Description bucket (joined with ' · ' in original column order, unknown
+ * names kept as `name: value`) so no historical datum is dropped.
+ */
+const QUICK_TASKS_COLUMN_ALIASES = {
+    '#': '#', id: '#',
+    date: 'Date', when: 'Date',
+    commit: 'Commit', sha: 'Commit',
+    status: 'Status',
+    directory: 'Directory', artifacts: 'Directory', path: 'Directory', dir: 'Directory',
+    description: 'Description', task: 'Description', summary: 'Description',
+    slug: 'Description', scope: 'Description', title: 'Description',
+};
+/**
+ * Migrate STATE.md's "Quick Tasks Completed" table onto the canonical
+ * `with-status` schema (#3730, maintainer decision 2026-09-02: option b).
+ *
+ * The pre-registry prose template licensed arbitrary column shapes GSD itself
+ * emitted, and `appendQuickTaskRow` fails loud on every one of them — leaving a
+ * project permanently unappendable. This is the supported repair path: the
+ * `gsd-tools quick-tasks-migrate` subcommand, plus an automatic check on the
+ * first `quick`/`fast` run (the workflow calls this before appending), which is
+ * a silent no-op when the section is absent, the table is already canonical, or
+ * the user never runs quick at all.
+ *
+ * Same section-selection, parse, and fail-loud posture as `appendQuickTaskRow`
+ * (ADR-2143 §7 upheld — append still rejects; this REPAIRS). Returns
+ * `{ok:true, value:{content, migrated:false}}` for the no-op cases so callers
+ * can stay silent, and `{migrated:true, from, rows}` when a rewrite happened so
+ * the CLI can report exactly what moved.
+ */
+function migrateQuickTasksTable(stateContent) {
+    const section = selectQuickTasksSection(stateContent);
+    if (!section) {
+        return { ok: true, value: { content: stateContent, migrated: false } };
+    }
+    const parsed = parseMarkdownTable(section.body);
+    if (!parsed.ok) {
+        return { ok: false, reason: `quick-tasks table: ${parsed.reason}` };
+    }
+    const match = matchTableSchema(parsed.value.columns);
+    if (match && match.id === 'QuickTasks') {
+        return { ok: true, value: { content: stateContent, migrated: false } };
+    }
+    const canonical = exports.TABLE_SCHEMAS.QuickTasks.find((v) => v.label === 'with-status').columns;
+    // Map each legacy column to its canonical target; unmapped names keep their
+    // identity so the Description bucket can render them losslessly.
+    const targets = parsed.value.columns.map((c) => QUICK_TASKS_COLUMN_ALIASES[c.trim().toLowerCase()] ?? null);
+    const rows = parsed.value.rows.map((row, rowIdx) => {
+        const bucket = {
+            '#': '', Description: '', Date: '', Commit: '', Status: '', Directory: '',
+        };
+        const descriptionParts = [];
+        // parseMarkdownTable hands back name-keyed records (rows[i][columnName]).
+        parsed.value.columns.forEach((col, i) => {
+            const raw = (row[col] ?? '').trim();
+            const target = targets[i];
+            if (target === 'Description') {
+                if (raw)
+                    descriptionParts.push(raw);
+            }
+            else if (target) {
+                // Collision-safe (#3730 review): two legacy columns aliasing the same
+                // canonical target must not silently overwrite — the displaced value
+                // joins the Description bucket under its own name, same convention as
+                // an unknown column, so no historical datum is dropped.
+                if (raw && bucket[target]) {
+                    descriptionParts.push(`${col.trim()}: ${raw}`);
+                }
+                else if (raw) {
+                    bucket[target] = raw;
+                }
+            }
+            else if (raw) {
+                descriptionParts.push(`${col.trim()}: ${raw}`);
+            }
+        });
+        bucket['#'] = bucket['#'] || String(rowIdx + 1);
+        bucket.Description = descriptionParts.join(' · ');
+        bucket.Date = bucket.Date || '—';
+        bucket.Commit = bucket.Commit || '—';
+        bucket.Status = bucket.Status || '—';
+        bucket.Directory = bucket.Directory || '—';
+        return `| ${canonical.map((c) => escapeCell(bucket[c])).join(' | ')} |`;
+    });
+    const eol = /\r\n/.test(section.body) ? '\r\n' : '\n';
+    const lines = section.body.split(/\r?\n/);
+    // CONTIGUOUS-run bound (#3730 review), mirroring resetQuickTaskRows: the
+    // section body may carry a SECOND table (a `#### Notes` subsection or a
+    // trailing table after a blank line) that parseMarkdownTable never read —
+    // scanning for the last pipe line anywhere in the body would splice the
+    // rewrite across it and silently destroy it. Only the first CONTIGUOUS run
+    // of pipe lines — the table that was parsed — is replaced.
+    const firstTableLineIdx = lines.findIndex((l) => l.trim().startsWith('|'));
+    let lastTableLineIdx = firstTableLineIdx;
+    while (lastTableLineIdx + 1 < lines.length && lines[lastTableLineIdx + 1].trim().startsWith('|')) {
+        lastTableLineIdx++;
+    }
+    const header = `| ${canonical.join(' | ')} |`;
+    // Widths match workflows/quick.md's canonical template byte-for-byte
+    // (#3730 review): its delimiter is max(3, len+2) per column.
+    const delimiter = `| ${canonical.map((c) => '-'.repeat(Math.max(3, c.length + 2))).join(' | ')} |`;
+    const newBody = [
+        ...lines.slice(0, firstTableLineIdx),
+        header,
+        delimiter,
+        ...rows,
+        ...lines.slice(lastTableLineIdx + 1),
+    ].join(eol);
+    return {
+        ok: true,
+        value: {
+            content: (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody),
+            migrated: true,
+            from: parsed.value.columns,
+            rows: rows.length,
+        },
+    };
+}
 // ─── resetQuickTaskRows (#2142) ────────────────────────────────────────────
 /**
  * Clear every DATA row from STATE.md's "Quick Tasks Completed" table, leaving
@@ -736,7 +907,7 @@ function appendQuickTaskRow(stateContent, fields) {
  * directories out from under the table (see `src/milestone.cts`'s
  * `archiveQuickTaskDirectories` / `cmdMilestoneComplete` wiring).
  *
- * Mirrors `appendQuickTaskRow`'s exact contract (same `collectSection` ->
+ * Mirrors `appendQuickTaskRow`'s exact contract (same `selectQuickTasksSection` ->
  * `parseMarkdownTable` -> `matchTableSchema` pipeline, same fail-loud posture,
  * same EOL-detect-before-split handling) rather than inventing a second one:
  *   - no "Quick Tasks Completed" heading -> `{ok:false, reason:
@@ -758,7 +929,7 @@ function resetQuickTaskRows(stateContent) {
     if (typeof stateContent !== 'string' || stateContent.trim() === '') {
         return { ok: false, reason: 'empty or non-string input' };
     }
-    const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
+    const section = selectQuickTasksSection(stateContent);
     if (!section) {
         return { ok: false, reason: exports.QUICK_TASKS_SECTION_ABSENT };
     }

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

@@ -31,8 +31,14 @@ const { resolveQuickTaskSummaryFile } = auditMod;
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitMod = require("./cli-exit.cjs");
+const { ExitError } = cliExitMod;
+// 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
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId } = phaseIdMod;
+const { normalizePhaseName, matchPhaseDirs, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, isSentinelPhaseDir } = phaseIdMod;
 const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
@@ -49,7 +55,7 @@ const { scanPhasePlans } = planScanMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { listMilestonePhaseDirs } = phaseLocatorMod;
-const { planningPaths } = planningWorkspace;
+const { planningPaths, resolvePhaseIdConvention } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 // ADR-3408 §8.3 / #3469: `writeStateMd` gets sync and NO preservation — the
 // same #3374-shaped exposure the milestone-complete write used to carry (a
@@ -477,7 +483,7 @@ function applyQuickTasksReset(content) {
 }
 function cmdMilestoneComplete(cwd, version, options, raw) {
     if (!version) {
-        error('version required for milestone complete (e.g., v1.0)');
+        error('version required for milestone complete (e.g., v1.0) — and --confirm to mutate');
     }
     // #2288 security: `version` is a CLI positional that is interpolated into
     // multiple filesystem sinks below — `path.join(archiveDir, `${version}-ROADMAP.md`)`,
@@ -488,6 +494,23 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     if (!ARCHIVE_VERSION_LABEL_RE.test(version)) {
         error(`milestone complete: version "${version}" is invalid — a milestone version label may contain only letters, digits, '.', '-' and '_', and must not contain path separators or "..".`);
     }
+    // #3726: confirmation gate — refuse before ANY read of the tree beyond the
+    // arg checks above, so an unconfirmed invocation is a guaranteed no-op on
+    // disk. The threat model is the NEVER_VALID_FLAGS one (gsd-tools.cjs): a
+    // caller supplies a token it believes is inert and a destructive operation
+    // proceeds unchecked — here the caller-side belief was that the `query`
+    // meta-prefix implies a read, and `query milestone.complete <v>` archived
+    // the milestone with no confirmation. The prefix is an intentional
+    // invocation-compatibility mechanism, not a permission boundary, so the
+    // gate lives on the destructive command itself and covers every invocation
+    // path. --dry-run needs no confirmation (it mutates nothing and is the
+    // recommended first step); --force does NOT imply it (see
+    // MilestoneCompleteOptions.confirm).
+    if (!options.dryRun && !options.confirm) {
+        error(`milestone complete is irreversible: it archives ROADMAP.md and REQUIREMENTS.md, MOVES every phase ` +
+            `directory for ${version} into .planning/milestones/, and rewrites STATE.md. ` +
+            `Nothing has been changed. Re-run with --confirm to proceed, or --dry-run to preview exactly what would move.`);
+    }
     const roadmapPath = planningPaths(cwd).roadmap;
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
@@ -660,6 +683,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             }
         }
         catch (e) {
+            // ADR-3889: error() now throws ExitError (carries no message) instead
+            // of calling process.exit() directly, so it can no longer be detected
+            // by sniffing e.message — an ExitError from our own guard above must be
+            // re-thrown UNCONDITIONALLY, before any message inspection, or the
+            // guard silently stops blocking milestone completion.
+            if (e instanceof ExitError)
+                throw e;
             // If the error came from our guard, re-throw it; otherwise skip silently.
             const message = e instanceof Error ? e.message : String(e);
             if (message && message.startsWith('Cannot mark milestone complete:'))
@@ -672,6 +702,22 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     let totalPlans = 0;
     let totalTasks = 0;
     const accomplishments = [];
+    // #2761 (round-11 BLOCKER): resolved ONCE, ambiently (no explicit `ws` —
+    // this function has none of its own and already resolves everything else
+    // off `cwd` via planningPaths(cwd), matching the ambient-workstream
+    // contract `resolvePhaseIdConvention`/`planningDir` share), and threaded
+    // into the single `listMilestonePhaseDirs` call directly below. Left
+    // unthreaded, `phaseIdConvention` stays `undefined` and
+    // `getMilestonePhaseFilter` silently resolves it FROM CONFIG itself —
+    // which is exactly the behavior the changeset originally (and wrongly)
+    // claimed this PR does not reach: on a bracket-convention project that
+    // lazily-resolved convention changes `milestonePhaseDirs`/
+    // `milestonePhaseScope` below, and this function goes on to ARCHIVE
+    // (rename/move) whatever that set names. Resolving explicitly here removes
+    // the silent-inherit path without changing behavior for `null` /
+    // `milestone-prefixed` projects, whose resolved convention is the same
+    // value `undefined` would have lazily produced anyway.
+    const phaseConvention = resolvePhaseIdConvention(cwd);
     // #3597 (ADR-3180 Decision 2): SINGLE resolution of "which phase
     // directories belong to the current milestone" AND the SCOPE discriminator
     // that resolution came from — shared verbatim by the read-only stats loop
@@ -685,7 +731,11 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // disk, same as before #3597. Only the destructive archive pass (and its
     // --dry-run preview) refuses to act on a non-COMPLETE (non-answer) scope;
     // see the guard built from `milestonePhaseScope` further down.
-    const { value: milestonePhaseDirs, scope: milestonePhaseScope } = listMilestonePhaseDirs(phasesDir, { cwd, versionOverride: version });
+    const { value: milestonePhaseDirs, scope: milestonePhaseScope } = listMilestonePhaseDirs(phasesDir, {
+        cwd,
+        versionOverride: version,
+        phaseIdConvention: phaseConvention,
+    });
     try {
         for (const dir of milestonePhaseDirs) {
             phaseCount++;
@@ -838,6 +888,12 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // Create/append MILESTONES.md entry
     const accomplishmentsList = accomplishments.map((a) => `- ${a}`).join('\n');
     const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+    // #3685: mirror requirementsUpdated's diff-tracking contract — the result
+    // below used to report `milestones_updated: true` hardcoded, never
+    // consulting whether the MILESTONES.md write actually changed anything.
+    // Captured before the write branches below so the after-comparison reports
+    // a real content diff instead of an assumed one.
+    const milestonesBefore = node_fs_1.default.existsSync(milestonesPath) ? node_fs_1.default.readFileSync(milestonesPath, 'utf-8') : null;
     if (node_fs_1.default.existsSync(milestonesPath)) {
         const existing = node_fs_1.default.readFileSync(milestonesPath, 'utf-8');
         if (!existing.trim()) {
@@ -867,6 +923,10 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     else {
         (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
     }
+    // #3685: real content diff, not the hardcoded `true` this used to report —
+    // see the `milestonesBefore` capture above.
+    const milestonesAfter = node_fs_1.default.existsSync(milestonesPath) ? node_fs_1.default.readFileSync(milestonesPath, 'utf-8') : null;
+    const milestonesUpdated = milestonesAfter !== milestonesBefore;
     // #2142 BLOCKER 2 (review): opt-in quick-task archival. This call MUST sit
     // immediately adjacent to the STATE.md write block directly below it, with
     // NO unguarded IO in between (unlike the ROADMAP/REQUIREMENTS/audit/
@@ -906,6 +966,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // taken). `resync: true` mirrors `cmdPhaseComplete`'s posture (progress
     // recomputed from disk; only the preserve-when-unchanged deltas apply) —
     // milestone completion is the same kind of lifecycle transition.
+    // #3685: mirror requirementsUpdated's diff-tracking contract — this used to
+    // report `state_updated: fs.existsSync(statePath)`, true even on a no-op
+    // transaction. Declared here beside `stateUpdated`'s sibling flags and
+    // defaulted to `false` so the "STATE.md absent" case keeps today's answer
+    // (existsSync also returns false there) reached via a real content
+    // comparison instead.
+    let stateUpdated = false;
     if (node_fs_1.default.existsSync(statePath)) {
         withStateLock(statePath, () => {
             const originalStateContent = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
@@ -976,6 +1043,24 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 divergedFields,
             });
             (0, shell_command_projection_cjs_1.platformWriteSync)(statePath, finalContent);
+            // #3685 / #3691: compare NORMALIZED bytes, not the pre-normalize
+            // `finalContent` string, against the pre-normalize `originalStateContent`
+            // read above. `platformWriteSync` runs Markdown normalization (blank-line
+            // insertion around headings/fences/lists) before persisting — the
+            // transition core (`transitionCore`'s `## Current Position` section
+            // reset) regenerates that section fresh on every call, including on a
+            // genuine no-op re-run, and its raw un-normalized output differs from
+            // the already-normalized on-disk original even though the write
+            // converges to byte-identical content. Comparing pre-normalize strings
+            // (mirroring cmdPhaseComplete's shape verbatim) was verified live to
+            // report `true` on three consecutive byte-identical writes.
+            // `contentChangedAfterNormalize` runs BOTH sides through the exact same
+            // normalizer `platformWriteSync` used to persist (no extra disk I/O,
+            // and immune by construction to this ordering artifact) — this used to
+            // re-read the file to get the same answer; #3691 hoisted that seam so
+            // this site, `updateRoadmapAfterPhaseRemoval`, and `cmdPhaseComplete`'s
+            // roadmap/state/requirements flags all agree by construction.
+            stateUpdated = (0, shell_command_projection_cjs_1.contentChangedAfterNormalize)(statePath, originalStateContent, finalContent);
             for (const field of divergedFields) {
                 preservationWarnings.push({ field, reason: 'preserved-over-disagreeing-derived' });
             }
@@ -1053,11 +1138,27 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             phases_archive_skip_reason: phasesArchiveSkipReason,
             quick: !!quickArchiveResult && quickArchiveResult.archived > 0,
         },
-        milestones_updated: true,
-        state_updated: node_fs_1.default.existsSync(statePath),
+        // #3685: mirror requirementsUpdated's diff-tracking contract — both flags
+        // now report a real before/after content diff instead of the previous
+        // hardcoded `true` (milestones_updated) / bare fs.existsSync (state_updated).
+        milestones_updated: milestonesUpdated,
+        state_updated: stateUpdated,
         preservation_warnings: preservationWarnings,
     };
     output(result, raw);
+    // #3227 (design doc §40 row 26 / "Not-corruption" rule): a refreshed
+    // state.json `updated_at` must always mean something on disk actually
+    // moved. This site is unconditional because every reachable path either
+    // exits via `error()` (process.exit — refusals like a truncated milestone
+    // window, an unstarted phase, or an invalid version never reach here) or
+    // returns early on `--dry-run` (before any mutation, see the `dry_run:
+    // true` branch above) — the only way execution reaches this line is after
+    // the unconditional MILESTONES.md `platformWriteSync` a few lines above,
+    // which always runs (new file, empty file, or append) once the run is
+    // committed to mutating. Best-effort — cannot throw, cannot change this
+    // command's exit code or output. publishStateContract resolves the
+    // workstream planning root itself via planningPaths.
+    publishStateContract(cwd);
 }
 function cmdPhasesClear(cwd, raw, args) {
     const phasesDir = planningPaths(cwd).phases;
@@ -1100,7 +1201,11 @@ function cmdPhasesClear(cwd, raw, args) {
         // divergence meant a `0-*` directory `roadmap analyze` preserves as a
         // sentinel was DELETED here. Routed through the canonical predicate so
         // every reader of "is this a sentinel phase" agrees by construction.
-        const dirs = entries.filter((e) => e.isDirectory() && !isSentinelPhaseId(e.name));
+        // #3639: the DIR-AWARE recognizer — the convention-less id predicate
+        // never saw bracket sentinel dirs (GSD.999-07-icebox), so they were
+        // counted for deletion here while the disk guards (post-#3639) preserve
+        // them; the destructive path must not be the one blind reader left.
+        const dirs = entries.filter((e) => e.isDirectory() && !isSentinelPhaseDir(e.name));
         if (dirs.length > 0 && !confirm) {
             error(`phases clear would delete ${dirs.length} phase director${dirs.length === 1 ? 'y' : 'ies'}. ` +
                 `Pass --confirm to proceed.`);