@opengsd/gsd-core 1.10.0 → 1.11.0

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

@@ -23,21 +23,41 @@ const clock_cjs_1 = require("./clock.cjs");
 const state_transition_cjs_1 = require("./state-transition.cjs");
 const write_set_cjs_1 = require("./write-set.cjs");
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
+const security_cjs_1 = require("./security.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- audit.cjs is an export= CommonJS module
+const auditMod = require("./audit.cjs");
+const { resolveQuickTaskSummaryFile } = auditMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex, normalizePhaseName, phaseTokenMatches, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
+const { normalizePhaseName, matchPhaseDirs, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId } = phaseIdMod;
+const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { getMilestonePhaseFilter, extractCurrentMilestone, getMilestoneInfo } = roadmapParserMod;
+const { getMilestonePhaseFilter, extractCurrentMilestone, getMilestoneInfo, sliceMilestoneWindow, } = roadmapParserMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtilsMod = require("./core-utils.cjs");
-const { extractOneLinerFromBody } = coreUtilsMod;
+const { extractOneLinerFromBody, countMatchedSummaries } = coreUtilsMod;
+// 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;
+// 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 { extractFrontmatter } = frontmatterMod;
-const { writeStateMd } = stateMod;
+// ADR-3408 §8.3 / #3469: `writeStateMd` gets sync and NO preservation — the
+// same #3374-shaped exposure the milestone-complete write used to carry (a
+// stale body value silently clobbering fresher frontmatter, with no
+// divergence signal). Routed through the single write-seam composition
+// (`syncAndPreserveStateMd`) instead, under `withStateLock` — see
+// `cmdMilestoneComplete`'s own STATE.md-update block for the full rationale.
+const { syncAndPreserveStateMd, withStateLock, readModifyWriteStateMd } = stateMod;
 // #2288 security: a milestone version label becomes a filesystem directory
 // component (`milestones/<label>-phases/`) into which phase directories are
 // MOVED. Any label used as a path segment must be a safe version token —
@@ -131,7 +151,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     // table_unmatched; this only adds the structured ADR-2143 shape on top).
     const writeSet = [];
     for (const reqId of reqIds) {
-        const reqEscaped = escapeRegex(reqId);
+        const reqEscaped = (0, pattern_cjs_1.escapeRegex)(reqId);
         // Surface 1 — the checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
         // Use replace() + compare to avoid the test()+replace() global regex
         // lastIndex bug where test() advances state and replace() misses matches.
@@ -298,17 +318,20 @@ function cmdRequirementsReadyIds(cwd, args, raw) {
         return;
     }
     const planAbsPath = node_path_1.default.resolve(cwd, planPathArg);
-    const phaseDir = node_path_1.default.dirname(planAbsPath);
-    const currentBasename = node_path_1.default.basename(planAbsPath);
-    let siblingPlanFiles = [];
-    try {
-        siblingPlanFiles = node_fs_1.default
-            .readdirSync(phaseDir)
-            .filter((f) => f.endsWith('-PLAN.md') && f !== currentBasename);
-    }
-    catch {
-        siblingPlanFiles = [];
-    }
+    // #3183: `planPathArg` may point at a root plan (`<phaseDir>/<n>-PLAN.md`)
+    // or a nested plan (`<phaseDir>/plans/PLAN-<n>.md`, #3139 layout) —
+    // scanPhasePlans always operates on the PHASE dir, so a nested plan needs
+    // one extra `dirname` to reach it, and its planFiles-relative identity
+    // carries the `plans/` prefix scanPhasePlans itself applies.
+    const isNestedPlanPath = node_path_1.default.basename(node_path_1.default.dirname(planAbsPath)) === 'plans';
+    const phaseDir = isNestedPlanPath ? node_path_1.default.dirname(node_path_1.default.dirname(planAbsPath)) : node_path_1.default.dirname(planAbsPath);
+    const currentRelative = isNestedPlanPath ? `plans/${node_path_1.default.basename(planAbsPath)}` : node_path_1.default.basename(planAbsPath);
+    // #3183: canonical plan/summary sets (root+nested, superseded-excluded)
+    // from the single owner, rather than a root-only hand-rolled readdirSync
+    // filter — a superseded sibling that still declares reqId with no SUMMARY
+    // used to block the ID forever (false-block); it is now excluded upstream.
+    const phaseScan = scanPhasePlans(phaseDir);
+    const siblingPlanFiles = phaseScan.planFiles.filter((f) => f !== currentRelative);
     const parseFrontmatterReqIds = (content, sourcePath) => {
         const fm = extractFrontmatter(content, sourcePath);
         const fmReq = fm.requirements;
@@ -341,9 +364,11 @@ function cmdRequirementsReadyIds(cwd, args, raw) {
             if (!siblingDeclaresId)
                 continue;
             // Sibling declares the SAME ID — it must have finished (produced a
-            // SUMMARY) before this ID is ready to mark Complete.
-            const siblingSummaryPath = siblingPath.replace(/-PLAN\.md$/, '-SUMMARY.md');
-            if (!node_fs_1.default.existsSync(siblingSummaryPath)) {
+            // SUMMARY) before this ID is ready to mark Complete. Canonical pairing
+            // via countMatchedSummaries (root+nested, all three naming forms)
+            // instead of a bespoke -PLAN.md→-SUMMARY.md regex swap.
+            const siblingHasSummary = countMatchedSummaries([siblingFile], phaseScan.summaryFiles) > 0;
+            if (!siblingHasSummary) {
                 blockedBySibling = true;
                 break;
             }
@@ -388,7 +413,7 @@ function cmdRequirementsRevertPhase(cwd, reqIdsRaw, raw) {
     const reverted = [];
     const unchanged = [];
     for (const reqId of reqIds) {
-        const reqEscaped = escapeRegex(reqId);
+        const reqEscaped = (0, pattern_cjs_1.escapeRegex)(reqId);
         let idReverted = false;
         // Surface 1 — checkbox: - [x] **REQ-ID** -> - [ ] **REQ-ID**
         const checkboxPattern = new RegExp(`(-\\s*\\[)x(\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
@@ -424,6 +449,32 @@ function cmdRequirementsRevertPhase(cwd, reqIdsRaw, raw) {
     }
     output({ reverted, unchanged, total: reqIds.length }, raw, `${reverted.length}/${reqIds.length} requirement(s) reverted from Complete`);
 }
+/**
+ * #2142 (code-review FIX 4): the single owned "should the Quick Tasks
+ * Completed table be reset, and is a reset failure worth a warning" decision
+ * — shared by `cmdMilestoneComplete` (which folds this into its own
+ * `withStateLock` transform, since it already holds that lock for the
+ * closure-transition write happening in the same block) and `cmdQuickArchive`
+ * (which routes through `readModifyWriteStateMd`'s own transform instead, per
+ * the lock-reentrancy note on that function). Only the WRITE mechanics
+ * differ between the two callers — the decision itself ("skip a
+ * `QUICK_TASKS_SECTION_ABSENT` result silently; surface any other failure")
+ * was previously duplicated verbatim at both call sites.
+ *
+ * Never throws: a reset failure degrades to returning `content` unchanged
+ * with a non-null `warning`, mirroring both callers' pre-existing
+ * "liberal but visible" posture.
+ */
+function applyQuickTasksReset(content) {
+    const resetResult = (0, markdown_table_cjs_1.resetQuickTaskRows)(content);
+    if (resetResult.ok) {
+        return { content: resetResult.value.content, warning: null };
+    }
+    if (resetResult.reason !== markdown_table_cjs_1.QUICK_TASKS_SECTION_ABSENT) {
+        return { content, warning: { field: 'quick_tasks_table', reason: resetResult.reason } };
+    }
+    return { content, warning: null };
+}
 function cmdMilestoneComplete(cwd, version, options, raw) {
     if (!version) {
         error('version required for milestone complete (e.g., v1.0)');
@@ -450,17 +501,56 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     const phasesDir = planningPaths(cwd).phases;
     const today = clock_cjs_1.realClock.localToday();
     const milestoneName = options.name || version;
-    // Ensure archive directory exists (skipped in dry-run — no mutations)
-    if (!options.dryRun) {
-        (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
-    }
+    // ADR-3408 §8.5 / #3469: "liberal but visible" — when the write-seam
+    // composition's preservation stage restores a curated frontmatter value
+    // over a disagreeing freshly-derived one, that divergence is surfaced
+    // here rather than silently absorbed (the direct answer to #3374's
+    // `warnings: []`). Structured (field + reason), not prose, so a caller can
+    // assert on the value rather than regex a rendered message.
+    //
+    // Named `preservation_warnings`, NOT `warnings`: `cmdPhaseComplete` already
+    // exposes a sibling field called `warnings` typed as prose `string[]`. Reusing
+    // that name here for a structured `{field, reason}[]` shape would be the
+    // "Generative Fix Divergence" anti-pattern — two sibling state commands
+    // sharing one field name with different element types. `warnings` stays
+    // one meaning (prose) repo-wide; this is a distinct, machine-assertable
+    // signal for ADR-3408 §8.5's "preservation is visible" rule. Check
+    // `preservation_warnings.length` rather than a companion `has_warnings`
+    // flag — that flag existed only to mirror `cmdPhaseComplete`'s channel,
+    // which this field intentionally does not claim to be.
+    const preservationWarnings = [];
     // Scope stats and accomplishments to only the phases belonging to the
     // current milestone's ROADMAP.  Uses the shared filter from roadmap-parser.cjs
     // (same logic used by cmdPhasesList and other callers).
+    // #3184 review finding: this scope computation + refusal MUST run BEFORE
+    // `platformEnsureDir(archiveDir)` below — a refused run (scope not COMPLETE,
+    // no --force) must be a true no-op on disk, and creating the archive
+    // directory first left an empty directory behind even on refusal.
     const isDirInMilestone = getMilestonePhaseFilter(cwd, version);
     if (isDirInMilestone.missingExplicitVersion) {
         error(`no phases found for milestone ${version} in ROADMAP.md`);
     }
+    // #3184/#3166: `milestone complete` is the ONE-WAY-DOOR consumer of the
+    // milestone window (ROADMAP/REQUIREMENTS archived, phase directories
+    // MOVED). #3166 is specifically the TRUNCATED case: the milestone's
+    // heading IS found but its section closes before the phase region, and the
+    // phase filter degrades to pass-all (see getMilestonePhaseFilter above) —
+    // silently archiving every phase directory on disk. UNREADABLE (no
+    // ROADMAP.md at all) and UNSCOPED (no section for this version) are
+    // pre-existing, legitimately-handled states — `missingExplicitVersion`
+    // above already errors where that matters, and a missing ROADMAP.md has
+    // its own documented graceful path — so only TRUNCATED is refused here.
+    // The read-path consumers keep the pass-all degrade for every scope
+    // (ADR-3180 Decision 3's Rejected section: deny-all there would trade one
+    // silent wrong answer for another); this write path refuses on TRUNCATED
+    // alone, positioned before `platformEnsureDir` so a refusal stays a no-op
+    // on disk.
+    if (isDirInMilestone.scope === SCOPE.TRUNCATED && !options.force) {
+        error(`Cannot mark milestone complete: the ROADMAP window for "${version}" is truncated ` +
+            `(the milestone heading was found but its section ends before reaching any phase ` +
+            `entries, even though the ROADMAP has phase entries elsewhere), so phase scoping ` +
+            `cannot be trusted for this destructive operation. Re-run with --force to override.`);
+    }
     // Guard: prevent marking complete when ROADMAP still lists phases that have
     // no directory on disk (disk_status: no_directory). This catches the case
     // where the active milestone was erroneously marked complete before phases
@@ -514,7 +604,21 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                     `running the unstarted-phase guard against the ROADMAP scoped for "${version}" anyway.\n`);
             }
             const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-            const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
+            // #3184/#2946: scope the unstarted-phase guard to the same `version`
+            // window `getMilestonePhaseFilter` used above, NOT to
+            // extractCurrentMilestone's own STATE.md-derived window — those two
+            // can disagree (that disagreement is exactly what the WARNING above
+            // detects), and scoping this guard to the wrong window under-detects
+            // unstarted phases on the destructive completion path. Calls the same
+            // sliceMilestoneWindow owner getMilestonePhaseFilter's versionOverride
+            // branch calls (a prior pass here re-composed locate+select+section-end
+            // locally, which review caught as a second, disagreeing derivation of
+            // the same window — ADR-3180 Decision 4(c)); falls back to
+            // extractCurrentMilestone's whole-document result only for the
+            // free-form (no versioned milestones anywhere) shape, where both
+            // windows converge to the same value regardless of which version drove
+            // the lookup.
+            const scopedContent = sliceMilestoneWindow(roadmapContent, version) ?? extractCurrentMilestone(roadmapContent, cwd);
             // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
             const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
             const noDirectoryPhases = [];
@@ -537,15 +641,15 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 // milestone completion. Mirrors the engine-wide sentinel convention
                 // (phase-id getMilestoneFromPhaseId, roadmap-command-router SENTINELS,
                 // the #1445 /^999/ progress filters). (#1580)
-                const major = parseInt(phaseNum, 10);
-                if (major === 0 || major === 999)
+                // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this local check already covered both 0 and 999; now delegates to the single canonical owner.
+                if (isSentinelPhaseId(phaseNum))
                     continue;
                 const normalized = normalizePhaseName(phaseNum);
                 // A phase has disk_status: 'no_directory' when no phase directory
-                // with a matching token exists on disk. Use the same phaseTokenMatches
-                // helper that roadmap.analyze uses to avoid false positives on decimal
-                // (2.1) and letter-suffix (12A) phase IDs.
-                const hasDirectory = phaseDirEntries.some((d) => phaseTokenMatches(d, normalized));
+                // with a matching token exists on disk. Use the same matchPhaseDirs
+                // owner that roadmap.analyze uses to avoid false positives on decimal
+                // (2.1) and letter-suffix (12A) phase IDs. (#2528)
+                const hasDirectory = matchPhaseDirs(phaseDirEntries, normalized).matches.length > 0;
                 if (!hasDirectory) {
                     noDirectoryPhases.push(phaseNum);
                 }
@@ -568,20 +672,29 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     let totalPlans = 0;
     let totalTasks = 0;
     const accomplishments = [];
+    // #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
+    // immediately below, the --dry-run preview, and the real archive pass, so
+    // none of the three can ever disagree. `listMilestonePhaseDirs` never
+    // throws (its own doc comment), so this is safe to call unguarded ahead of
+    // the try/catch that scopes the stats roll-up below.
+    //
+    // The stats loop's own ENUMERATION behavior is intentionally left
+    // unaffected by a non-COMPLETE scope — it reports what is actually on
+    // 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 });
     try {
-        const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-        const dirs = entries
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name)
-            .sort();
-        for (const dir of dirs) {
-            if (!isDirInMilestone(dir))
-                continue;
+        for (const dir of milestonePhaseDirs) {
             phaseCount++;
-            const phaseFiles = node_fs_1.default.readdirSync(node_path_1.default.join(phasesDir, dir));
-            const plans = phaseFiles.filter((f) => f.endsWith('-PLAN.md') || f === 'PLAN.md');
-            const summaries = phaseFiles.filter((f) => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
-            totalPlans += plans.length;
+            // #3183: canonical plan/summary sets (root+nested, superseded-excluded)
+            // from the single owner, rather than a root-only hand-rolled readdirSync
+            // filter.
+            const phaseScan = scanPhasePlans(node_path_1.default.join(phasesDir, dir));
+            const summaries = phaseScan.summaryFiles;
+            totalPlans += phaseScan.planCount;
             // Extract one-liners from summaries
             for (const s of summaries) {
                 try {
@@ -621,21 +734,49 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
          * were created). Degrades stats to phaseCount/totalPlans/totalTasks=0,
          * accomplishments=[] rather than crash `milestone complete`. */
     }
+    // #3597 (ADR-3180 Decision 2): `SCOPE.UNREADABLE` is the ONE classification
+    // where `getMilestonePhaseFilter` throws (no workstream ROADMAP of its
+    // own), leaves `milestonePhaseNums` empty, and the window degrades to a
+    // pass-all fallback — that fallback is what silently WIDENS the archive
+    // set past the single-derivation guarantee this block exists to protect
+    // (confirmed empirically: a workstream with phase dirs but no workstream
+    // ROADMAP.md reports UNREADABLE and used to enumerate every directory on
+    // disk). `SCOPE.TRUNCATED` already refuses the WHOLE command above.
+    // `SCOPE.UNSCOPED` is a DIFFERENT, pre-existing classification — e.g. a
+    // root project with no milestone asserted in STATE.md — whose
+    // `listMilestonePhaseDirs` resolution is a real (non-degraded) answer, and
+    // its rollover archive behavior predates this branch and must not change.
+    // The guard therefore refuses ONLY on UNREADABLE, not on "not COMPLETE" —
+    // widening to every non-COMPLETE scope was itself a regression (a root
+    // project with no active workstream resolves UNSCOPED, and refusing to
+    // archive there broke the ordinary `milestone complete` -> `phases clear`
+    // rollover). Computed once here from the single
+    // `milestonePhaseDirs`/`milestonePhaseScope` resolution above, so the
+    // --dry-run preview below and the real archive pass further down can never
+    // disagree about whether (or what) to archive.
+    const phasesArchiveSkippedForScope = options.archivePhases !== false && milestonePhaseScope === SCOPE.UNREADABLE;
+    const phasesArchiveSkipReason = phasesArchiveSkippedForScope
+        ? `milestone window scope is "${milestonePhaseScope}" — refusing to archive phase directories until the window can be resolved (ADR-3180)`
+        : null;
     // #2118: --dry-run preview — compute what WOULD happen without mutating.
     // The stats above are read-only; all mutations start at the archive section below.
     if (options.dryRun) {
         const phaseDirsToArchive = [];
-        if (options.archivePhases !== false) {
-            try {
-                const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-                for (const e of entries) {
-                    if (e.isDirectory() && isDirInMilestone(e.name)) {
-                        phaseDirsToArchive.push(e.name);
-                    }
-                }
-            }
-            catch { /* phasesDir missing — nothing to archive */ }
+        if (options.archivePhases !== false && !phasesArchiveSkippedForScope) {
+            // #3185 (ADR-3180 Decision 1) / #3597: same single routed derivation as
+            // the stats loop above — the dry-run preview must list exactly what
+            // the real archive pass below would move, including refusing to list
+            // anything when the window scope is not COMPLETE.
+            phaseDirsToArchive.push(...milestonePhaseDirs);
         }
+        // #2142 MAJOR 5 (review): dry-run preview of quick-task archival —
+        // read-only, routed through the SAME `listQuickTaskDirsForArchive`
+        // selection `archiveQuickTaskDirectories` uses for real (directory
+        // entries only, `requireSafePath`-guarded, sorted) so this preview can
+        // never disagree with what a real run actually archives. Absent
+        // --archive-quick this stays `[]` and nothing on disk is touched either
+        // way (dry-run always returns before any mutation below).
+        const quickDirsToArchive = options.archiveQuick ? listQuickTaskDirsForArchive(cwd) : [];
         const dryRunResult = {
             dry_run: true,
             version,
@@ -653,6 +794,9 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                     ? { source: node_path_1.default.relative(cwd, node_path_1.default.join(planningBase, `${version}-MILESTONE-AUDIT.md`)).split(node_path_1.default.sep).join('/'), target: node_path_1.default.relative(cwd, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)).split(node_path_1.default.sep).join('/') }
                     : null,
                 phases: phaseDirsToArchive,
+                phases_archive_skipped: phasesArchiveSkippedForScope,
+                phases_archive_skip_reason: phasesArchiveSkipReason,
+                quick: quickDirsToArchive,
             },
             would_update: {
                 milestones_md: node_path_1.default.relative(cwd, milestonesPath).split(node_path_1.default.sep).join('/'),
@@ -662,6 +806,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
         output(dryRunResult, raw);
         return;
     }
+    // Ensure archive directory exists. Deliberately placed AFTER the dry-run
+    // early return and every refusal/guard above (missingExplicitVersion, the
+    // scope refusal, the unstarted-phase guard) — #3184 review finding: this
+    // used to run before those checks, so a refused run still left an empty
+    // archive directory behind. Reaching this point means the run is
+    // committed to mutating.
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
     // Archive ROADMAP.md
     if (node_fs_1.default.existsSync(roadmapPath)) {
         const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
@@ -695,7 +846,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
         }
         else {
             // Insert after the header line(s) for reverse chronological order (newest first)
-            const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+            // #3415: empirically verified linear-time up to 5MB adversarial input (worst-case
+            // no-newline-at-all forcing full [^\r\n]* backtrack: 0.11ms@10KB -> 6.9ms@5MB).
+            // Non-global, `^`-anchored (no /m) so this is a single match attempt at position 0
+            // only — never rescanned at every offset — with no nested repeated group, so it
+            // cannot exhibit the #2128-class catastrophic backtracking.
+            // eslint-disable-next-line local/no-unbounded-quantifier -- single ^-anchored non-global attempt at pos 0, measured linear to 5MB, no nested quantifier
+            const headerMatch = existing.match(/^(#{1,3}\s+[^\r\n]*\r?\n(?:\r?\n)?)/);
             if (headerMatch) {
                 const header = headerMatch[1];
                 const rest = existing.slice(header.length);
@@ -710,26 +867,140 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     else {
         (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
     }
+    // #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/
+    // MILESTONES.md writes above, none of which are wrapped in a try/catch).
+    // If the move ran earlier — e.g. right after `platformEnsureDir(archiveDir)`
+    // — and any one of those unguarded writes then threw, the quick-task
+    // directories would already be gone from `.planning/quick/` while the
+    // STATE.md Quick Tasks table reset (which lives inside `withStateLock`
+    // immediately below) would never be reached. That is precisely the
+    // STATE-vs-disk drift #2142 exists to eliminate: a table still describing
+    // directories that no longer exist. Keeping the move and the reset
+    // adjacent — separated only by this comment, never by IO that can throw —
+    // means either both happen or (if the move itself throws) neither does.
+    // `archiveQuick` is opt-in (default OFF); absent the flag this is `null`
+    // and every downstream read of it degrades to "no quick archival happened".
+    const quickArchiveResult = options.archiveQuick
+        ? archiveQuickTaskDirectories(cwd, version)
+        : null;
     // Update STATE.md — keep frontmatter/body semantically aligned after closure.
     // ADR-1769 Phase 5: dispatches to the STATE.md Transition Module. The closure
     // write (Status, Last Activity, Last Activity Description, Current Position
     // reset, Operator Next Steps reset) is the pure `milestoneCompleteCore` in
     // src/state-transition.cts, backed by the field-classification table. The
     // runtime-specific next-milestone slash command is resolved here and injected
-    // via the intent so the core stays pure. writeStateMd still owns the lock and
-    // the steady-state syncStateFrontmatter post-sync.
+    // via the intent so the core stays pure.
+    //
+    // ADR-3408 §8.3 / #3469: this used to write via `writeStateMd`, which gets
+    // sync and NO preservation — the identical shape #3374 reported for
+    // `phase.complete` (a stale body value silently clobbering fresher
+    // frontmatter). Routed through the single write-seam composition
+    // (`syncAndPreserveStateMd`) instead, under the same lock discipline
+    // `cmdPhaseComplete`'s atomic-commit adapter already uses: `withStateLock`
+    // wraps read + transform + sync + preserve + write so the read this
+    // transaction bases its transform on cannot be raced by a concurrent
+    // writer (closing a pre-existing TOCTOU gap `writeStateMd`'s own internal
+    // lock never covered, since the read used to happen before any lock was
+    // 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.
     if (node_fs_1.default.existsSync(statePath)) {
-        const result = (0, state_transition_cjs_1.transitionCore)(node_fs_1.default.readFileSync(statePath, 'utf-8'), {
-            kind: 'milestoneComplete',
-            version,
-            nextMilestoneCommand: (0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd)),
-        }, { clock: clock_cjs_1.realClock, sourcePath: statePath });
-        writeStateMd(statePath, result.content, cwd);
+        withStateLock(statePath, () => {
+            const originalStateContent = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
+            const result = (0, state_transition_cjs_1.transitionCore)(originalStateContent, {
+                kind: 'milestoneComplete',
+                version,
+                nextMilestoneCommand: (0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd)),
+            }, { clock: clock_cjs_1.realClock, sourcePath: statePath });
+            const divergedFields = [];
+            // #2111 (found by #3471 review): `milestoneCompleteCore` never declares
+            // `current_phase`/`current_phase_name` among the fields it touches — but
+            // its ## Current Position reset REWRITES the `Phase:` prose line to a
+            // closure message ("Milestone vX.Y complete"), which is not a number.
+            // That is an unavoidable side effect of the wholesale section reset
+            // `resetSectionVerbatim` performs, not an intent to change the phase.
+            // Downstream, `current_phase`/`current_phase_name` are
+            // `preserve-when-unchanged` rows: the #1230 delta heuristic sees the
+            // body source go from a real value to unparseable and — correctly, per
+            // ADR-3408 §8.5 Row 2 — lets the derived (empty) value win, discarding
+            // the curated phase entirely. §8.5 Row 2 governs a genuine mid-write
+            // body edit (e.g. `state.patch` deleting the Phase line); milestone
+            // closure is a different shape — the transition never intended to
+            // touch these fields at all. Re-assert them via `authoritativeFm` (the
+            // same #2736 intent-first mechanism `beginPhaseCore`/`completePhaseCore`
+            // already use to freeze a field the transition resolved out-of-band),
+            // so the closure-message side effect cannot clobber the last real
+            // phase. Scoped to non-empty strings only, mirroring #2736's own guard.
+            const authoritativeFm = {};
+            const preFm = extractFrontmatter(originalStateContent, statePath);
+            const preCurrentPhase = preFm['current_phase'];
+            const preCurrentPhaseName = preFm['current_phase_name'];
+            if (typeof preCurrentPhase === 'string' && preCurrentPhase.trim().length > 0) {
+                authoritativeFm['current_phase'] = preCurrentPhase;
+            }
+            if (typeof preCurrentPhaseName === 'string' && preCurrentPhaseName.trim().length > 0) {
+                authoritativeFm['current_phase_name'] = preCurrentPhaseName;
+            }
+            // #2142: fold the Quick Tasks table reset into this SAME
+            // `withStateLock` transform — no second lock acquisition, no second
+            // `syncAndPreserveStateMd`/`platformWriteSync` pass. Only applied when
+            // quick archival actually MOVED something (never when the flag was
+            // absent, and never for a mere dry-run preview, which never reaches
+            // here at all). A refused reset degrades to leaving the content
+            // untouched and never fails milestone completion, but the two refusal
+            // shapes are NOT equally noteworthy (design doc §40, behavior table
+            // row 5): an ABSENT "Quick Tasks Completed" section is the normal,
+            // common case — the section is created lazily by
+            // `gsd-core/workflows/quick.md` Step 7b, not by
+            // `gsd-core/templates/state.md`, so most projects simply don't have
+            // one — and is silently skipped (compared via the shared
+            // `QUICK_TASKS_SECTION_ABSENT` sentinel, never by matching on the
+            // free-form reason string). A section that EXISTS but couldn't be
+            // reset (unparseable table, or columns matching neither registered
+            // QuickTasks variant) is a genuine anomaly and IS surfaced via
+            // `preservationWarnings`, the same "liberal but visible" posture the
+            // rest of this block already uses for a disagreeing derived STATE.md
+            // value.
+            let quickTasksResetContent = result.content;
+            if (quickArchiveResult && quickArchiveResult.archived > 0) {
+                const { content: resetContent, warning } = applyQuickTasksReset(quickTasksResetContent);
+                quickTasksResetContent = resetContent;
+                if (warning)
+                    preservationWarnings.push(warning);
+            }
+            const finalContent = syncAndPreserveStateMd(originalStateContent, quickTasksResetContent, statePath, cwd, {
+                resync: true,
+                authoritativeFm: Object.keys(authoritativeFm).length > 0 ? authoritativeFm : undefined,
+                divergedFields,
+            });
+            (0, shell_command_projection_cjs_1.platformWriteSync)(statePath, finalContent);
+            for (const field of divergedFields) {
+                preservationWarnings.push({ field, reason: 'preserved-over-disagreeing-derived' });
+            }
+            // The authoritativeFm re-assert above (unlike a delta-based restore) is
+            // invisible to `divergedFields` — #2736's re-assert runs after that
+            // diff — so surface it explicitly here for "liberal but visible".
+            for (const field of Object.keys(authoritativeFm)) {
+                if (!divergedFields.includes(field)) {
+                    preservationWarnings.push({ field, reason: 'preserved-over-disagreeing-derived' });
+                }
+            }
+        });
     }
     // Archive phase directories if requested
     let phasesArchived = false;
     // #1871: archive phase dirs by default on milestone complete (opt out via --no-archive-phases).
-    if (options.archivePhases !== false) {
+    // #3597: `phasesArchiveSkippedForScope` (computed once, above, from the SAME
+    // `milestonePhaseDirs`/`milestonePhaseScope` resolution the --dry-run preview
+    // consumed) refuses this destructive rename loop entirely when the window
+    // scope is UNREADABLE — the one scope whose resolution degrades to a
+    // pass-all fallback (ADR-3180). UNSCOPED/TRUNCATED are real, pre-existing
+    // answers and archive exactly as they did before this branch.
+    // `phasesArchived` stays false and the refusal is surfaced on `result` below;
+    // nothing on disk moves, and `phaseArchiveDir` is never even created.
+    if (options.archivePhases !== false && !phasesArchiveSkippedForScope) {
         // #2245 audit (was ERROR-HIDING): retryRenameSync moves one phase dir at a
         // time — a mid-loop failure (e.g. the Nth rename) used to leave
         // `phasesArchived` at its `false` default even though the first N-1 dirs
@@ -741,11 +1012,12 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
         try {
             const phaseArchiveDir = node_path_1.default.join(archiveDir, `${version}-phases`);
             (0, shell_command_projection_cjs_1.platformEnsureDir)(phaseArchiveDir);
-            const phaseEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-            const phaseDirNames = phaseEntries.filter((e) => e.isDirectory()).map((e) => e.name);
-            for (const dir of phaseDirNames) {
-                if (!isDirInMilestone(dir))
-                    continue;
+            // #3185 (ADR-3180 Decision 1) / #3597: same single routed derivation as
+            // the stats loop and the --dry-run preview above — only the CURRENT
+            // milestone's phase directories move, never a sentinel or an
+            // out-of-window directory left for a later milestone, and never a
+            // pass-all degrade from a non-COMPLETE scope (refused above).
+            for (const dir of milestonePhaseDirs) {
                 (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, dir), node_path_1.default.join(phaseArchiveDir, dir));
                 archivedCount++;
             }
@@ -772,9 +1044,18 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             requirements: node_fs_1.default.existsSync(node_path_1.default.join(archiveDir, `${version}-REQUIREMENTS.md`)),
             audit: node_fs_1.default.existsSync(node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
             phases: phasesArchived,
+            // #3597: machine-readable refusal signal — distinguishes "nothing to
+            // archive because the milestone genuinely has no phase directories"
+            // (phases: false, phases_archive_skipped: false) from "refused to
+            // archive because the milestone window scope was not COMPLETE"
+            // (phases: false, phases_archive_skipped: true, with a reason).
+            phases_archive_skipped: phasesArchiveSkippedForScope,
+            phases_archive_skip_reason: phasesArchiveSkipReason,
+            quick: !!quickArchiveResult && quickArchiveResult.archived > 0,
         },
         milestones_updated: true,
         state_updated: node_fs_1.default.existsSync(statePath),
+        preservation_warnings: preservationWarnings,
     };
     output(result, raw);
 }
@@ -813,7 +1094,13 @@ function cmdPhasesClear(cwd, raw, args) {
     let cleared = 0;
     if (node_fs_1.default.existsSync(phasesDir)) {
         const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-        const dirs = entries.filter((e) => e.isDirectory() && !/^999(?:\.|$)/.test(e.name));
+        // #3185 (ADR-3180 Decision 1): this carried the FIFTH copy of the
+        // sentinel rule and its THIRD regex variant — `/^999(?:\.|$)/` — which
+        // excluded 999 but NOT 0. Because this is the DESTRUCTIVE path, that
+        // 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));
         if (dirs.length > 0 && !confirm) {
             error(`phases clear would delete ${dirs.length} phase director${dirs.length === 1 ? 'y' : 'ies'}. ` +
                 `Pass --confirm to proceed.`);
@@ -897,7 +1184,13 @@ function archivePhaseDirectories(cwd, phasesDir, dirs, archiveVersionOverride =
     let archiveVersion = safeOverride;
     if (!archiveVersion) {
         try {
-            const liveVersion = getMilestoneInfo(cwd).version ?? null;
+            // #3216 (ADR-3180 §7.2 Decision): getMilestoneInfo's version becomes a
+            // DIRECTORY NAME below — only a COMPLETE scope's identity is trustworthy
+            // enough to act on destructively. On any other scope, treat the version
+            // as unavailable so control falls through to the dated-label fallback,
+            // same as an unreadable ROADMAP/STATE.
+            const info = getMilestoneInfo(cwd);
+            const liveVersion = info.scope === SCOPE.COMPLETE ? (info.value?.version ?? null) : null;
             // Defense in depth (#2288 security): getMilestoneInfo reads STATE.md's
             // `milestone:` field, which is unvalidated file content. Only accept it
             // as a path component if it is a safe version label; a crafted value
@@ -928,10 +1221,401 @@ function archivePhaseDirectories(cwd, phasesDir, dirs, archiveVersionOverride =
     }
     return { archiveDir: archivePhasesDir, archived };
 }
+/**
+ * #2142 BLOCKER 1 (review): escape one directory-name span for insertion as
+ * markdown LINK TEXT (`[...]`) — a directory name containing a literal `|`,
+ * `[` or `]` must not be able to break the enclosing markdown. `mkdirSync`
+ * accepts an embedded newline in a directory name on POSIX (and `isDirectory()`
+ * still reports true for it), so an unescaped newline would let attacker-
+ * controlled content — including a markdown HEADING — land verbatim in the
+ * generated README.md, an indirect prompt-injection vector for any agent
+ * workflow step that later reads that file. Mirrors `escapeCell`'s exact
+ * convention (markdown-table.cts `escapeCell`): collapse `\r?\n+` to a single
+ * space FIRST (so a newline can never re-enter the output as a line break),
+ * THEN escape the escape char itself (before the rest, so a literal backslash
+ * in the name is never mistaken for part of an escape sequence this function
+ * introduces), THEN the markdown-syntax characters.
+ */
+function escapeMarkdownLinkText(text) {
+    return text
+        .replace(/\r?\n+/g, ' ')
+        .replace(/\\/g, '\\\\')
+        .replace(/\|/g, '\\|')
+        .replace(/\[/g, '\\[')
+        .replace(/\]/g, '\\]');
+}
+/**
+ * #2142 BLOCKER 1 (review): encode one path span for insertion as a markdown
+ * link DESTINATION (`(...)`) — `relSummary` is built from a directory name
+ * that may legally contain a space, a `(`/`)`, or a control character
+ * (including an embedded newline) on POSIX. Per CommonMark, an unbracketed
+ * link destination terminates at the first ASCII space/control character and
+ * requires parens to be balanced or escaped — any of those would truncate or
+ * corrupt the link, or let attacker-controlled content spill out of the
+ * `(...)` span into the surrounding markdown (the same indirect
+ * prompt-injection vector `escapeMarkdownLinkText` guards the link TEXT
+ * against). Percent-encodes just the unsafe set (space, `(`, `)`, and C0
+ * control chars incl. `\r`/`\n`, plus DEL) rather than switching to the
+ * angle-bracket `<...>` destination form — percent-encoding is reversible (a
+ * markdown viewer resolving the link still reaches the right file) and does
+ * not introduce a new pair of syntax characters (`<`/`>`) that would in turn
+ * need their own escaping.
+ */
+function encodeMarkdownLinkTarget(target) {
+    return target.replace(/[\x00-\x1f\x7f ()]/g, (ch) => `%${ch.charCodeAt(0).toString(16).padStart(2, '0').toUpperCase()}`);
+}
+/**
+ * #2142 (code-review FIX 2): PURE builder — scans `archiveQuickDir` and
+ * resolves each entry's summary link, but performs NO IO beyond the read
+ * scan itself; never writes. Split out of the former `writeQuickArchiveReadme`
+ * so tests can assert on the returned structured IR (`entries`) instead of
+ * substring-matching rendered markdown (CONTRIBUTING.md "Prohibited: Raw Text
+ * Matching on Test Outputs" — a generated archive index is a "Rendered file",
+ * which requires a pure builder returning IR, not the `.md`-IS-the-runtime-
+ * artifact exemption).
+ *
+ * (re)generates an index of every quick-task directory PHYSICALLY PRESENT in
+ * the archive, built by scanning the ARCHIVE directory on disk. Deliberately
+ * NOT built from STATE.md's Quick Tasks table (the issue evidenced that table
+ * drifting — 53 rows against 49 dirs, ~22 rows pointing at absent dirs, 18
+ * dirs missing from the table — the filesystem is the only source of truth)
+ * and NOT from the pre-move source list either, so a RE-RUN's index includes
+ * entries a PRIOR run already archived, not just this run's (design row 11).
+ *
+ * Each entry's summary link is resolved via `resolveQuickTaskSummaryFile`
+ * (audit.cts) — the SAME rule `scanQuickTasks` uses to read a task's record
+ * — imported rather than re-derived, so the read and write paths can never
+ * disagree about which file is a task's summary. A task WITHOUT a summary is
+ * still listed, just without a link — never omitted (an omission would
+ * under-report the index, which is worse than an unlinked entry).
+ *
+ * Entries are sorted for deterministic output. A directory name containing
+ * `|`, `[`, `]` or an embedded newline is neutralized via
+ * `escapeMarkdownLinkText` (link TEXT) so it cannot break the generated
+ * markdown or inject a heading — applied here, at build time, so `entries`
+ * itself already carries the injection-safe name (the regression test
+ * asserts on THIS, not on rendered output). The destination is separately
+ * encoded via `encodeMarkdownLinkTarget` (link TARGET) at RENDER time, so a
+ * space/paren/control char in the name cannot truncate or corrupt the
+ * `(...)` span. The summary path is normalized to POSIX
+ * (`.split(path.sep).join('/')`) so the link is stable across platforms.
+ *
+ * Throws when `archiveQuickDir` is unreadable — the caller (`writeQuickArchiveReadme`)
+ * is the best-effort boundary, not this builder.
+ */
+function buildQuickArchiveIndex(archiveQuickDir) {
+    const dirEntries = node_fs_1.default.readdirSync(archiveQuickDir, { withFileTypes: true });
+    const dirNames = dirEntries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    const entries = dirNames.map((dirName) => {
+        const taskDir = node_path_1.default.join(archiveQuickDir, dirName);
+        const summaryPath = resolveQuickTaskSummaryFile(taskDir, dirName);
+        const escapedName = escapeMarkdownLinkText(dirName);
+        if (summaryPath) {
+            const relSummary = node_path_1.default.relative(archiveQuickDir, summaryPath).split(node_path_1.default.sep).join('/');
+            return { name: escapedName, summary: relSummary };
+        }
+        // No summary file — list the directory, but never link into it (there
+        // is nothing to point at). See indexListsTaskWithoutSummaryWithoutLink.
+        return { name: escapedName, summary: null };
+    });
+    return {
+        entries,
+        render() {
+            const lines = ['# Archived Quick Tasks', ''];
+            for (const entry of entries) {
+                if (entry.summary !== null) {
+                    lines.push(`- [${entry.name}](${encodeMarkdownLinkTarget(entry.summary)})`);
+                }
+                else {
+                    lines.push(`- ${entry.name}`);
+                }
+            }
+            lines.push('');
+            return lines.join('\n');
+        },
+    };
+}
+/**
+ * #2142: thin writer — calls `buildQuickArchiveIndex` and writes its
+ * `render()` output to `<archiveQuickDir>/README.md`. No-ops (writes
+ * nothing) when `archiveQuickDir` is unreadable — this is a best-effort
+ * index, not a gate on milestone completion. #2142 MAJOR 4 (review): the
+ * whole body is wrapped in a try/catch so a failure of the WRITE itself
+ * (read-only archive dir, full disk, or a quick-task directory literally
+ * named `README.md` colliding with the file being written) degrades the same
+ * way — this function genuinely cannot throw, matching its own
+ * "best-effort, not a gate" contract; the directories are already safely
+ * archived by the time this runs.
+ */
+function writeQuickArchiveReadme(archiveQuickDir) {
+    try {
+        const index = buildQuickArchiveIndex(archiveQuickDir);
+        (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(archiveQuickDir, 'README.md'), index.render());
+    }
+    catch {
+        /* best-effort (#2142 MAJOR 4): a read-only archive dir, a full disk, or a
+         * quick-task directory literally named `README.md` colliding with the
+         * file this function writes must never crash `milestone complete` —
+         * the quick-task directories are already safely archived on disk by the
+         * time this index-generation step runs. */
+    }
+}
+/**
+ * #2142 MAJOR 5 (review): the single owned selection rule for "which
+ * directories under `.planning/quick/` would/will move" — directory entries
+ * only (symlinks are excluded here, per the MAJOR 3 note above), each
+ * additionally guarded with `requireSafePath` (the same guard
+ * `scanQuickTasks`/`archiveQuickTaskDirectories` use), sorted for
+ * deterministic output. Extracted so `cmdMilestoneComplete`'s dry-run
+ * preview, `cmdQuickArchive`'s dry-run preview, and the REAL selection inside
+ * `archiveQuickTaskDirectories` all call this ONE function instead of each
+ * re-deriving the rule — the "Generative Fix Divergence" anti-pattern this
+ * repo explicitly guards against (a prior version of this code had the rule
+ * written three times, and only the real-run copy applied `requireSafePath`,
+ * so a dry-run preview could list a directory the real run would silently
+ * skip).
+ */
+function listQuickTaskDirsForArchive(cwd) {
+    const planningBase = planningPaths(cwd).planning;
+    const quickDir = planningPaths(cwd).quick;
+    let sourceEntries;
+    try {
+        sourceEntries = node_fs_1.default.readdirSync(quickDir, { withFileTypes: true });
+    }
+    catch {
+        // .planning/quick absent or unreadable — nothing to select.
+        return [];
+    }
+    const names = [];
+    for (const entry of sourceEntries) {
+        if (!entry.isDirectory())
+            continue; // excludes symlinks too — see MAJOR 3 note above
+        try {
+            (0, security_cjs_1.requireSafePath)(node_path_1.default.join(quickDir, entry.name), planningBase, 'quick task dir', { allowAbsolute: true });
+        }
+        catch {
+            continue; // symlink/escape attempt — never a candidate, in preview OR real run
+        }
+        names.push(entry.name);
+    }
+    return names.sort();
+}
+/**
+ * #2142: move each DIRECTORY entry under `.planning/quick/` into
+ * `milestones/<version>-quick/` (collision-safe), then (re)write that
+ * archive directory's README.md index. Sibling of `archivePhaseDirectories`
+ * — extracted rather than inlined into `cmdMilestoneComplete` (already
+ * cyclomatic 61) — mirroring its collision-safe destination-suffix loop,
+ * `retryRenameSync`, and `platformEnsureDir` usage.
+ *
+ * `version` is ALREADY validated by `ARCHIVE_VERSION_LABEL_RE` at
+ * `cmdMilestoneComplete`'s entry — this helper does not re-validate it, and
+ * must only ever be called after that guard has run.
+ *
+ * #2142 MAJOR 3 (review): a symlink under `.planning/quick/` — even one that
+ * targets a directory — is excluded by the `dirEntries` filter below
+ * (`fs.Dirent.isDirectory()` returns FALSE for a symlink, regardless of what
+ * it points at), so it is never a candidate `entry` in the first place and
+ * `requireSafePath` below never runs against it. `requireSafePath` is
+ * retained here as defense-in-depth for the NON-symlink path (a real
+ * directory entry whose resolved path still needs re-validating against
+ * `planningBase`) — the SAME guard `scanQuickTasks` (audit.cts) uses — so an
+ * entry that fails it is skipped, never archived, never counted. See the
+ * symlink regression tests in tests/milestone-archive.test.cjs
+ * (`symlinkEscapeIsNeverArchivedByMilestoneComplete` /
+ * `symlinkEscapeIsNeverArchivedByQuickArchive`) for a fixture proving neither
+ * the symlink nor its external target is ever moved or altered — added
+ * specifically so a future change to this filter cannot silently reopen the
+ * escape with nothing to catch it.
+ *
+ * No-op (returns `{archived: 0, entries: []}`, creates NOTHING on disk) when
+ * `.planning/quick/` does not exist or contains zero DIRECTORY entries — a
+ * stray file with no sibling directory is neither an empty-dir case nor an
+ * archive case.
+ *
+ * A mid-loop rename failure (or a failure to create the archive directory
+ * itself) does not crash `milestone complete` — it degrades to whatever
+ * `archived`/`entries` had already accumulated before the failure, mirroring
+ * the `archivedCount` finally-pattern `cmdMilestoneComplete`'s own phase
+ * archival uses a few hundred lines above (so a partial archive reports the
+ * TRUE count, never a false `0`/`false`).
+ */
+function archiveQuickTaskDirectories(cwd, version) {
+    const planningBase = planningPaths(cwd).planning;
+    const quickDir = planningPaths(cwd).quick;
+    const archiveQuickDir = node_path_1.default.join(planningBase, 'milestones', `${version}-quick`);
+    // #2142 MAJOR 5 (review): dirNames is the SAME selection
+    // `listQuickTaskDirsForArchive` hands to both dry-run previews — this is
+    // the real run, so it cannot disagree with what a preview reported.
+    const dirNames = listQuickTaskDirsForArchive(cwd);
+    if (dirNames.length === 0) {
+        // Boundary 0 (#2142): zero (safe) directory entries (empty dir, only
+        // stray files, or every entry excluded by the selection rule) must not
+        // create the archive directory. Also covers `.planning/quick/` being
+        // absent/unreadable — `listQuickTaskDirsForArchive` degrades to `[]`.
+        return { archiveDir: archiveQuickDir, archived: 0, entries: [] };
+    }
+    let archived = 0;
+    const entries = [];
+    try {
+        (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveQuickDir);
+        for (const name of dirNames) {
+            const src = node_path_1.default.join(quickDir, name);
+            let safeSrc;
+            try {
+                // Re-validated here (not just trusted from the selection above) as
+                // TOCTOU defense-in-depth: `listQuickTaskDirsForArchive` and this
+                // rename are two separate filesystem observations, and an entry
+                // that was a safe real directory at selection time could in theory
+                // be swapped for a symlink before this loop reaches it.
+                safeSrc = (0, security_cjs_1.requireSafePath)(src, planningBase, 'quick task dir', { allowAbsolute: true });
+            }
+            catch {
+                continue; // symlink/escape attempt — skip, not archived
+            }
+            // Collision-safe: if a same-named archive entry exists (re-run), suffix it.
+            let dest = node_path_1.default.join(archiveQuickDir, name);
+            let destName = name;
+            let n = 1;
+            while (node_fs_1.default.existsSync(dest)) {
+                destName = `${name}.${n++}`;
+                dest = node_path_1.default.join(archiveQuickDir, destName);
+            }
+            (0, shell_command_projection_cjs_1.retryRenameSync)(safeSrc, dest);
+            archived++;
+            entries.push(destName);
+        }
+    }
+    catch {
+        /* best-effort: platformEnsureDir failed, or the rename loop failed
+         * partway — `archived`/`entries` above already reflect exactly what
+         * succeeded before the failure (accumulated incrementally, never lost
+         * with the swallowed exception — mirrors the archivedCount pattern at
+         * cmdMilestoneComplete's phase-archival block). */
+    }
+    // Regenerate the README from whatever is ACTUALLY on disk now — covers
+    // both a clean full archive and a degraded partial one, and (on a re-run)
+    // includes entries a PRIOR run already archived. Skipped only when the
+    // archive directory itself was never created (ensureDir failed above).
+    if (node_fs_1.default.existsSync(archiveQuickDir)) {
+        writeQuickArchiveReadme(archiveQuickDir);
+    }
+    return { archiveDir: archiveQuickDir, archived, entries };
+}
+/**
+ * #2142 escalation: `milestone.archive-quick` (CLI: `milestone archive-quick`,
+ * renamed from the original `quick.archive` per code-review FIX 1 — folded
+ * under the existing `milestone` namespace rather than adding a new top-level
+ * command) — the narrow archival helper the issue's own "Scope of changes"
+ * anticipated ("a `quick.archive`-style routine"), for callers (chiefly
+ * `gsd-core/workflows/cleanup.md`) that need to sweep
+ * `.planning/quick/*` WITHOUT the full `milestone complete` close-out.
+ *
+ * `milestone complete --archive-quick` cannot be reused for this: it
+ * hard-errors via `missingExplicitVersion` for an already-completed
+ * milestone (no `### Phase N:` headings left in its ROADMAP window),
+ * re-archives ROADMAP.md over the very snapshot cleanup depends on, and
+ * appends a duplicate MILESTONES.md entry on every re-run.
+ *
+ * This command performs ONLY the two things `archiveQuickTaskDirectories`
+ * already does (move `.planning/quick/*` dirs into
+ * `milestones/<version>-quick/` + (re)write that archive's README index —
+ * the SAME helper `cmdMilestoneComplete` calls, so the two entry points can
+ * never diverge on step 1) plus a Quick Tasks Completed table reset. It
+ * NEVER touches ROADMAP.md, REQUIREMENTS.md, or MILESTONES.md, and runs
+ * NEITHER the unstarted-phase guard NOR the milestone-window/TRUNCATED
+ * refusal — those remain `milestone complete`'s alone.
+ *
+ * #2142 MAJOR 6 (review): the STATE.md write now routes through
+ * `readModifyWriteStateMd` — the same owned read-transform-write composition
+ * `gsd-tools.cjs`'s `quick-tasks-append` handler uses (ADR-3408 §8.3 / #3469:
+ * "the single owned composition ... so the composition cannot diverge"). A
+ * prior version of this function called `platformWriteSync` directly with
+ * the reset result, bypassing `syncAndPreserveStateMd` entirely — the exact
+ * bypass shape that ADR closed. Per `src/state.cts:3289-3330`,
+ * `readModifyWriteStateMd` ALREADY acquires its own exclusive lock
+ * (`acquireStateLock`/`releaseStateLock`, a real `O_CREAT|O_EXCL` file lock,
+ * not reentrant) across its own read -> transform -> write cycle — so, unlike
+ * `cmdMilestoneComplete` (which folds the table reset into its own
+ * pre-existing `withStateLock` transform because it ALSO needs that lock for
+ * the closure-transition write happening in the same block), this function
+ * must NOT wrap the call in its own `withStateLock`: doing so would acquire
+ * the same lock file twice in the same process, and the second acquire would
+ * spin against a lock this same call already holds until it times out.
+ */
+function cmdQuickArchive(cwd, version, options, raw) {
+    if (!version) {
+        error('version required for milestone.archive-quick (e.g., v1.0)');
+    }
+    // #2288-class security: `version` becomes a filesystem directory component
+    // (`milestones/<version>-quick/`) that directories are MOVED into — same
+    // guard + wording shape `cmdMilestoneComplete` uses for its own version arg.
+    if (!ARCHIVE_VERSION_LABEL_RE.test(version)) {
+        error(`milestone.archive-quick: version "${version}" is invalid — a milestone version label may contain only letters, digits, '.', '-' and '_', and must not contain path separators or "..".`);
+    }
+    const statePath = planningPaths(cwd).state;
+    const planningBase = planningPaths(cwd).planning;
+    const toPosixRel = (p) => node_path_1.default.relative(cwd, p).split(node_path_1.default.sep).join('/');
+    // --dry-run: preview only, mutates nothing. #2142 MAJOR 5 (review): routed
+    // through the SAME `listQuickTaskDirsForArchive` selection
+    // `cmdMilestoneComplete`'s own dry-run preview and the real
+    // `archiveQuickTaskDirectories` both use, so all three can never disagree.
+    if (options.dryRun) {
+        const quickDirsToArchive = listQuickTaskDirsForArchive(cwd);
+        output({
+            dry_run: true,
+            version,
+            would_archive: quickDirsToArchive,
+            archive_dir: toPosixRel(node_path_1.default.join(planningBase, 'milestones', `${version}-quick`)),
+        }, raw);
+        return;
+    }
+    const quickArchiveResult = archiveQuickTaskDirectories(cwd, version);
+    const warnings = [];
+    let stateUpdated = false;
+    // Same silent/surfaced rule `cmdMilestoneComplete` applies: only attempt
+    // the reset when something actually moved, and treat the
+    // QUICK_TASKS_SECTION_ABSENT sentinel as a silent no-op (the section is
+    // created lazily by quick.md Step 7b and absent from templates/state.md,
+    // so absence is the common case, not an anomaly). Any other reset failure
+    // is surfaced via `warnings`, never thrown.
+    //
+    // #2142 MAJOR 6 (review): routed through `readModifyWriteStateMd` (see the
+    // docstring above) instead of a bare `platformWriteSync` — the transform
+    // returns the ORIGINAL content unchanged whenever the reset did not apply
+    // (sentinel-absent or a genuine failure), so `readModifyWriteStateMd`'s own
+    // no-op guard (#948, state.cts:3304) skips the write and its `false`
+    // return accurately reports "nothing was written" — the same "state_updated
+    // must report accurately" contract the prior direct-write version upheld.
+    if (quickArchiveResult.archived > 0 && node_fs_1.default.existsSync(statePath)) {
+        let resetWarning = null;
+        stateUpdated = readModifyWriteStateMd(statePath, (content) => {
+            const { content: nextContent, warning } = applyQuickTasksReset(content);
+            resetWarning = warning;
+            return nextContent;
+        }, cwd);
+        if (resetWarning) {
+            warnings.push(resetWarning);
+        }
+    }
+    output({
+        version,
+        archived: quickArchiveResult.archived,
+        entries: quickArchiveResult.entries,
+        archive_dir: toPosixRel(quickArchiveResult.archiveDir),
+        state_updated: stateUpdated,
+        warnings,
+    }, raw, `${quickArchiveResult.archived} quick task director${quickArchiveResult.archived === 1 ? 'y' : 'ies'} archived`);
+}
 module.exports = {
     cmdRequirementsMarkComplete,
     cmdRequirementsReadyIds,
     cmdRequirementsRevertPhase,
     cmdMilestoneComplete,
     cmdPhasesClear,
+    cmdQuickArchive,
+    buildQuickArchiveIndex,
 };