@opengsd/gsd-core 1.5.0 → 1.6.0-rc.1

package/gsd-core/bin/lib/project-root.cjs

@@ -1,11 +1,12 @@
 "use strict";
 /**
  * Project-Root Resolution Module — resolves a project root from a starting
- * directory by walking the ancestor chain and applying four heuristics:
+ * directory by walking the ancestor chain and applying five heuristics:
  *   (0) own .planning/ guard (#1362)
  *   (1) parent .planning/config.json sub_repos
  *   (2) legacy multiRepo: true + ancestor .git
  *   (3) .git heuristic with parent .planning/
+ *   (4) nearest ancestor .planning/ (#1414, Resolution Provenance P1)
  * Bounded by FIND_PROJECT_ROOT_MAX_DEPTH ancestors. Sync I/O.
  *
  * ADR-457 build-at-publish: the hand-written bin/lib/project-root.cjs
@@ -17,6 +18,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findProjectRoot = findProjectRoot;
+exports.consentProjectRoot = consentProjectRoot;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -107,13 +109,98 @@ function findProjectRoot(startDir) {
             }
             if (matched)
                 return parent;
-            // Heuristic: parent has .planning/ and we're inside a git repo.
+            // Heuristic (3): parent has .planning/ and we're inside a git repo.
+            // Before returning, check if any further ancestor has sub_repos that explicitly
+            // claims our startDir — explicit sub_repos config takes precedence over the
+            // implicit .git signal. (#1422)
             if (isInsideGitRepo(parent)) {
+                // Lookahead: walk ancestors above `parent` to find a sub_repos claim.
+                let ancestor = node_path_1.default.dirname(parent);
+                let ancestorDepth = 0;
+                while (ancestor !== fsRoot && ancestor !== home && ancestorDepth < FIND_PROJECT_ROOT_MAX_DEPTH) {
+                    const ancestorPlanning = ancestor + node_path_1.default.sep + '.planning';
+                    try {
+                        if (node_fs_1.default.existsSync(ancestorPlanning) && node_fs_1.default.statSync(ancestorPlanning).isDirectory()) {
+                            const ancestorConfig = ancestor + node_path_1.default.sep + '.planning' + node_path_1.default.sep + 'config.json';
+                            const rawA = node_fs_1.default.readFileSync(ancestorConfig, 'utf-8');
+                            const cfgA = JSON.parse(rawA);
+                            const subReposValueA = cfgA['sub_repos'] ??
+                                (cfgA['planning'] && typeof cfgA['planning'] === 'object'
+                                    ? cfgA['planning']['sub_repos']
+                                    : undefined);
+                            const subReposA = Array.isArray(subReposValueA) ? subReposValueA : [];
+                            if (subReposA.length > 0) {
+                                const relPathA = node_path_1.default.relative(ancestor, resolvedStart);
+                                const topSegmentA = relPathA.split(node_path_1.default.sep)[0];
+                                if (subReposA.includes(topSegmentA)) {
+                                    return ancestor;
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // ignore — config missing or unparseable, keep walking
+                    }
+                    const nextAncestor = node_path_1.default.dirname(ancestor);
+                    if (nextAncestor === ancestor)
+                        break;
+                    ancestor = nextAncestor;
+                    ancestorDepth += 1;
+                }
                 return parent;
             }
         }
         dir = parent;
         depth += 1;
     }
+    // Heuristic (4): nearest ancestor .planning/ — last resort before fallback.
+    // Runs only after heuristics (1)–(3) have been exhausted without a match,
+    // ensuring sub_repos / multiRepo / .git-based resolution always wins when
+    // applicable. Walks upward again within the same FIND_PROJECT_ROOT_MAX_DEPTH
+    // bound; returns the nearest ancestor directory that contains a .planning/
+    // subdirectory so config resolves correctly when invoked from a plain
+    // descendant of a single-repo project. (#1414)
+    let dir2 = resolvedStart;
+    let depth2 = 0;
+    while (dir2 !== fsRoot && depth2 < FIND_PROJECT_ROOT_MAX_DEPTH) {
+        const parent2 = node_path_1.default.dirname(dir2);
+        if (parent2 === dir2)
+            break;
+        try {
+            const candidatePlanning = parent2 + node_path_1.default.sep + '.planning';
+            if (node_fs_1.default.existsSync(candidatePlanning) && node_fs_1.default.statSync(candidatePlanning).isDirectory()) {
+                return parent2;
+            }
+        }
+        catch {
+            // ignore fs errors and continue walking
+        }
+        if (parent2 === home)
+            break;
+        dir2 = parent2;
+        depth2 += 1;
+    }
     return startDir;
 }
+/**
+ * #1459 (IC-01 / CB-4): THE single canonical derivation of the PROJECT ROOT used to bind/lookup a
+ * project-scope consent record. Install (the CLI/lifecycle RECORD site), the loader (the LOOKUP
+ * site), and `trust revoke` (CB-4) MUST all derive the consent root through this one helper so the
+ * recorded key always matches the looked-up key — otherwise installing from a SUBDIR records consent
+ * at `realpath(subdir)` while the loader looks it up at `realpath(findProjectRoot)` and the freshly
+ * installed cap is immediately INACTIVE (install-then-inactive).
+ *
+ * The rule: `realpath(findProjectRoot(cwd))` (findProjectRoot is total — it returns `cwd` itself when
+ * no project root is found, so there is no null branch), falling back to `path.resolve(cwd)` when the
+ * resolved root cannot be realpath'd (e.g. it does not exist yet). The consent store realpaths
+ * whatever it is given, so passing the SAME logical root from every site is what guarantees the match.
+ */
+function consentProjectRoot(cwd) {
+    const root = findProjectRoot(cwd);
+    try {
+        return node_fs_1.default.realpathSync(root);
+    }
+    catch {
+        return node_path_1.default.resolve(root);
+    }
+}

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

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Resolution Convention — canonical shape for config-interpreting read verbs.
+ *
+ * Extracted as the anchor for ADR-1411 P3 (Resolution Provenance, #1416).
+ * Exports the `Resolution<T>` envelope used when a verb reads and interprets
+ * configuration (e.g. agent-skills). Not used by mutation verbs (see
+ * capability-writer's `SetCapabilityStateResult` for the mutation shape) or
+ * plain read verbs (see capability-state's `ResolveCapabilityRuntimeStateResult`).
+ *
+ * This is a pure types+builder leaf — no other src/ imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeResolution = makeResolution;
+// ─── Builder ──────────────────────────────────────────────────────────────────
+/**
+ * Construct a `Resolution<T>` envelope from a value and its provenance fields.
+ */
+function makeResolution(value, opts) {
+    return {
+        value,
+        configured: opts.configured,
+        reason: opts.reason,
+        warnings: opts.warnings,
+    };
+}

package/gsd-core/bin/lib/roadmap-parser.cjs

@@ -27,6 +27,7 @@ const { escapeRegex, phaseMarkdownRegexSource } = phaseIdModule;
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspace;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ─── Roadmap milestone scoping ───────────────────────────────────────────────
 /**
  * Strip shipped milestone content wrapped in <details> blocks.
@@ -97,34 +98,25 @@ function extractCurrentMilestone(content, cwd) {
     const sectionStart = selected.index;
     const computeSectionEnd = (headingText, headingStart) => {
         const level = (headingText.match(/^(#{1,3})\s/) ?? ['', '#'])[1].length;
-        const rest = content.slice(headingStart + headingText.length);
-        const stopPattern = new RegExp(`^#{1,${level}}\\s+(?!Phase\\s+\\S)(?:.*v\\d+\\.\\d+|✅|📋|🚧)`, 'i');
-        let end = content.length;
-        let fc = null;
-        let fl = 0;
-        let off = 0;
-        for (const line of rest.split('\n')) {
-            const fm = line.match(/^\s{0,3}((?:`{3,}|~{3,}))(.*)/);
-            if (fm) {
-                const ch = fm[1][0];
-                const ln = fm[1].length;
-                const trailing = fm[2] || '';
-                if (!fc) {
-                    fc = ch;
-                    fl = ln;
-                }
-                else if (ch === fc && ln >= fl && /^\s*$/.test(trailing)) {
-                    fc = null;
-                    fl = 0;
-                }
-            }
-            else if (!fc && stopPattern.test(line)) {
-                end = headingStart + headingText.length + off;
-                break;
-            }
-            off += line.length + 1;
+        const afterHeading = headingStart + headingText.length;
+        // Use tokenizeHeadings (fence-aware, offsets into original content) to find
+        // the next stop boundary without re-implementing fence detection. T4 seam migration.
+        const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
+        for (const h of headings) {
+            if (h.offset <= headingStart)
+                continue;
+            if (h.offset < afterHeading)
+                continue;
+            if (h.level > level)
+                continue;
+            // Mirrors old stopPattern: level-bounded, not a Phase heading, milestone marker
+            if (/^Phase\s+\S/i.test(h.text))
+                continue;
+            if (!/v\d+\.\d+|✅|📋|🚧/i.test(h.text))
+                continue;
+            return h.offset;
         }
-        return end;
+        return content.length;
     };
     const sectionEnd = computeSectionEnd(selected[0], sectionStart);
     const anyMilestonePattern = /^#{1,3}\s+(?!Phase\s+\S)(?:.*v\d+\.\d+|✅|📋|🚧)/im;
@@ -278,47 +270,6 @@ function getMilestoneInfo(cwd) {
         return { version: 'v1.0', name: 'milestone' };
     }
 }
-// ─── Fence-aware text helper ──────────────────────────────────────────────────
-/**
- * Return a copy of `text` with every line that lies inside a fenced code block
- * replaced by an empty string, using the same fence semantics as
- * `computeSectionEnd` (backtick/tilde, ≥3 chars, indent ≤3 spaces, toggle;
- * an unclosed fence treats remaining content as fenced).
- */
-function stripFencedLines(text) {
-    let fenceChar = null;
-    let fenceLen = 0;
-    const lines = text.split('\n');
-    const result = [];
-    for (const line of lines) {
-        const fm = line.match(/^\s{0,3}((?:`{3,}|~{3,}))(.*)/);
-        if (fm) {
-            const ch = fm[1][0];
-            const ln = fm[1].length;
-            const trailing = fm[2] || '';
-            if (!fenceChar) {
-                fenceChar = ch;
-                fenceLen = ln;
-                // The fence-open line itself is not a content line — blank it.
-                result.push('');
-            }
-            else if (ch === fenceChar && ln >= fenceLen && /^\s*$/.test(trailing)) {
-                fenceChar = null;
-                fenceLen = 0;
-                // The fence-close line — blank it.
-                result.push('');
-            }
-            else {
-                // A fence marker that doesn't close the current fence (different char or shorter) — keep treating as fenced content.
-                result.push(fenceChar ? '' : line);
-            }
-        }
-        else {
-            result.push(fenceChar ? '' : line);
-        }
-    }
-    return result.join('\n');
-}
 /**
  * Returns a filter function that checks whether a phase directory belongs
  * to the current milestone based on ROADMAP.md phase headings.
@@ -374,42 +325,37 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
             else {
                 const sectionStart = sectionMatch.index;
                 const headingLevel = (sectionMatch[1].match(/^(#{1,3})\s/) ?? ['', '#'])[1].length;
-                const restContent = roadmapContent.slice(sectionStart + sectionMatch[0].length);
-                const nextMilestonePattern = new RegExp(`^#{1,${headingLevel}}\\s+(?!Phase\\s+\\S)(?:.*v\\d+\\.\\d+|✅|📋|🚧)`, 'i');
+                const afterHeading = sectionStart + sectionMatch[0].length;
+                // Use tokenizeHeadings (fence-aware, offsets into original content) to find
+                // the next milestone-boundary heading. T4 seam migration.
+                const allHeadings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(roadmapContent);
                 let sectionEnd = roadmapContent.length;
-                let fenceChar = null;
-                let fenceLen = 0;
-                let charOffset = 0;
-                for (const line of restContent.split('\n')) {
-                    const fenceMatch = line.match(/^\s{0,3}((?:`{3,}|~{3,}))(.*)/);
-                    if (fenceMatch) {
-                        const char = fenceMatch[1][0];
-                        const len = fenceMatch[1].length;
-                        const trailing = fenceMatch[2] || '';
-                        if (!fenceChar) {
-                            fenceChar = char;
-                            fenceLen = len;
-                        }
-                        else if (char === fenceChar && len >= fenceLen && /^\s*$/.test(trailing)) {
-                            fenceChar = null;
-                            fenceLen = 0;
-                        }
-                    }
-                    else if (!fenceChar && nextMilestonePattern.test(line)) {
-                        sectionEnd = sectionStart + sectionMatch[0].length + charOffset;
-                        break;
-                    }
-                    charOffset += line.length + 1;
+                for (const h of allHeadings) {
+                    if (h.offset < afterHeading)
+                        continue;
+                    if (h.level > headingLevel)
+                        continue;
+                    if (/^Phase\s+\S/i.test(h.text))
+                        continue;
+                    if (!/v\d+\.\d+|✅|📋|🚧/i.test(h.text))
+                        continue;
+                    sectionEnd = h.offset;
+                    break;
                 }
                 const currentSection = roadmapContent.slice(sectionStart, sectionEnd);
                 roadmap = currentSection;
             }
         }
-        const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
-        const roadmapUnfenced = stripFencedLines(roadmap);
-        let m;
-        while ((m = phasePattern.exec(roadmapUnfenced)) !== null) {
-            milestonePhaseNums.add(m[1]);
+        // Use tokenizeHeadings (fence-aware) instead of stripFencedLines + regex.
+        // T4 seam migration: phase headings inside fences are excluded automatically.
+        const phaseHeadingPattern = /^(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/i;
+        for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(roadmap)) {
+            if (h.level < 2 || h.level > 4)
+                continue;
+            const pm = phaseHeadingPattern.exec(h.text);
+            // Exclude 999.x backlog phases from milestone phase set. Mirrors init.cts filter.
+            if (pm && !/^999\b/.test(pm[1]))
+                milestonePhaseNums.add(pm[1]);
         }
     }
     catch { /* intentionally empty */ }

package/gsd-core/bin/lib/runtime-homes.cjs

@@ -36,6 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveConfigHomeFromDescriptor = resolveConfigHomeFromDescriptor;
 exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
+exports.detectAntigravityDirAmbiguity = detectAntigravityDirAmbiguity;
 exports.resolveKimiGlobalDir = resolveKimiGlobalDir;
 exports.getGlobalConfigDir = getGlobalConfigDir;
 exports.resolveSkillsBaseFromDescriptor = resolveSkillsBaseFromDescriptor;
@@ -97,7 +98,20 @@ function resolveConfigHomeFromDescriptor(configHome, opts = {}) {
             }
             const base = node_path_1.default.join(home, configHome.parent);
             if (configHome.probe && configHome.probe.length > 0) {
-                // probe each candidate under base; return first that exists
+                // Pass 1 (marker-priority): when probeExists is declared, prefer the
+                // candidate GSD actually owns (its `<candidate>/<probeExists>` exists).
+                // This disambiguates an active-but-shadowing sibling dir (e.g. the
+                // Antigravity-IDE `~/.gemini/antigravity` dir) from the dir GSD was
+                // installed into, instead of blindly taking the first dir that exists.
+                if (configHome.probeExists) {
+                    for (const candidate of configHome.probe) {
+                        const resolved = node_path_1.default.join(base, candidate);
+                        if (existsSyncFn(node_path_1.default.join(resolved, configHome.probeExists))) {
+                            return resolved;
+                        }
+                    }
+                }
+                // Pass 2 (legacy bare-existence): first candidate dir that exists.
                 for (const candidate of configHome.probe) {
                     const resolved = node_path_1.default.join(base, candidate);
                     if (existsSyncFn(resolved))
@@ -171,8 +185,46 @@ function resolveAntigravityGlobalDir(opts = {}) {
         parent: '.gemini',
         env: ['ANTIGRAVITY_CONFIG_DIR'],
         probe: ['antigravity', 'antigravity-ide', 'antigravity-cli'],
+        // Prefer the candidate GSD installed into (carries gsd-core/VERSION) over
+        // a bare-existing sibling. Without this, a CLI user (antigravity-cli) who
+        // also has the IDE's ~/.gemini/antigravity dir is shadowed to the legacy
+        // dir because it is probed first. See #213/#217. The posix-slash literal
+        // matches capabilities/antigravity/capability.json; both normalize via
+        // path.join at the check site, so Windows backslash handling is covered.
+        probeExists: 'gsd-core/VERSION',
     }, { env, home, existsSync: existsSyncFn });
 }
+/**
+ * Detect whether the Antigravity config-dir resolution is ambiguous — i.e. more
+ * than one of ~/.gemini/{antigravity,antigravity-ide,antigravity-cli} exists, so
+ * a user upgrading from a pre-#217 install may have had GSD written into the
+ * wrong sibling dir (the legacy/IDE dir shadowing an active CLI dir).
+ *
+ * This is a pure, side-effect-free probe intended for the installer and
+ * /gsd-update to surface operator guidance (set ANTIGRAVITY_CONFIG_DIR or move
+ * gsd-core/ into the intended dir). The migration framework cannot relocate an
+ * install across sibling config dirs (it is bounded to a single configDir and
+ * has no cross-dir move primitive — see installer-migrations 004), so existing
+ * misinstalls are corrected by re-detection + operator guidance, not an
+ * automatic move.
+ */
+function detectAntigravityDirAmbiguity(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? node_os_1.default.homedir();
+    const existsSyncFn = opts.existsSync ?? node_fs_1.default.existsSync;
+    const marker = node_path_1.default.join('gsd-core', 'VERSION');
+    const base = node_path_1.default.join(home, '.gemini');
+    const candidates = ['antigravity', 'antigravity-ide', 'antigravity-cli'].map((c) => node_path_1.default.join(base, c));
+    const presentDirs = candidates.filter((dir) => existsSyncFn(dir));
+    const gsdMarkedDirs = candidates.filter((dir) => existsSyncFn(node_path_1.default.join(dir, marker)));
+    return {
+        ambiguous: presentDirs.length > 1,
+        resolved: resolveAntigravityGlobalDir({ env, home, existsSync: existsSyncFn }),
+        presentDirs,
+        gsdMarkedDirs,
+        envOverridden: Boolean(env['ANTIGRAVITY_CONFIG_DIR']),
+    };
+}
 /**
  * Resolve Kimi's generic user root using Kimi CLI's documented first-existing
  * generic skills directory policy:

package/gsd-core/bin/lib/semver-compare.cjs

@@ -14,6 +14,7 @@ exports.toNumericTuple = toNumericTuple;
 exports.compareSemverCore = compareSemverCore;
 exports.isSemverNewer = isSemverNewer;
 exports.isStableTripletSemver = isStableTripletSemver;
+exports.semverSatisfies = semverSatisfies;
 function toNumericTuple(input) {
     const cleaned = String(input == null ? '' : input).trim().replace(/^v/, '');
     const base = cleaned.replace(/[-+].*$/, '');
@@ -40,3 +41,129 @@ function isSemverNewer(a, b) {
 function isStableTripletSemver(v) {
     return /^\d+\.\d+\.\d+$/.test(String(v || '').replace(/^v/, ''));
 }
+function compareTuples(a, b) {
+    if (a[0] !== b[0])
+        return a[0] > b[0] ? 1 : -1;
+    if (a[1] !== b[1])
+        return a[1] > b[1] ? 1 : -1;
+    if (a[2] !== b[2])
+        return a[2] > b[2] ? 1 : -1;
+    return 0;
+}
+// Parse a version-ish token into a tuple + how many leading numeric parts were
+// specified (0 = bare wildcard "*"/"x", 1 = "1", 2 = "1.2", 3 = "1.2.3").
+// Returns null if the token is not a parseable partial/full version.
+function parseVersionToken(token) {
+    const clean = token.trim().replace(/^v/, '').replace(/[-+].*$/, '');
+    if (clean === '' || clean === '*' || clean === 'x' || clean === 'X')
+        return { tuple: [0, 0, 0], specified: 0 };
+    const parts = clean.split('.');
+    if (parts.length > 3)
+        return null;
+    const nums = [];
+    let sawWildcard = false;
+    for (const p of parts) {
+        if (p === 'x' || p === 'X' || p === '*') {
+            sawWildcard = true;
+            continue;
+        }
+        // A concrete segment after a wildcard ("1.x.2", "1.*.2") is malformed → fail closed.
+        if (sawWildcard)
+            return null;
+        if (!/^\d+$/.test(p))
+            return null;
+        nums.push(Number.parseInt(p, 10));
+    }
+    if (nums.length === 0)
+        return { tuple: [0, 0, 0], specified: 0 };
+    return { tuple: [nums[0] || 0, nums[1] || 0, nums[2] || 0], specified: nums.length };
+}
+// Expand a single comparator into primitive (op, tuple) constraints, or null if
+// unparseable (→ fail closed).
+function expandComparator(c) {
+    const trimmed = c.trim();
+    if (trimmed === '' || trimmed === '*' || trimmed === 'x' || trimmed === 'X')
+        return [{ op: '>=', t: [0, 0, 0] }];
+    const m = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(trimmed);
+    if (!m)
+        return null;
+    const op = m[1] || '';
+    const pv = parseVersionToken(m[2]);
+    if (!pv)
+        return null;
+    const { tuple, specified } = pv;
+    const [maj, min, pat] = tuple;
+    if (op === '^') {
+        let upper;
+        if (maj > 0)
+            upper = [maj + 1, 0, 0];
+        else if (min > 0)
+            upper = [0, min + 1, 0];
+        else
+            upper = [0, 0, pat + 1];
+        return [{ op: '>=', t: tuple }, { op: '<', t: upper }];
+    }
+    if (op === '~') {
+        const upper = specified >= 2 ? [maj, min + 1, 0] : [maj + 1, 0, 0];
+        return [{ op: '>=', t: tuple }, { op: '<', t: upper }];
+    }
+    if (op === '' || op === '=') {
+        if (specified === 0)
+            return [{ op: '>=', t: [0, 0, 0] }]; // "*" → any
+        if (specified === 3)
+            return [{ op: '=', t: tuple }];
+        const upper = specified === 1 ? [maj + 1, 0, 0] : [maj, min + 1, 0];
+        return [{ op: '>=', t: tuple }, { op: '<', t: upper }];
+    }
+    // >= <= > < with an explicit version
+    if (specified === 0)
+        return null; // e.g. ">=*" is meaningless → fail closed
+    return [{ op: op, t: tuple }];
+}
+function satisfiesPrimitive(v, prim) {
+    const cmp = compareTuples(v, prim.t);
+    switch (prim.op) {
+        case '>=': return cmp >= 0;
+        case '<=': return cmp <= 0;
+        case '>': return cmp > 0;
+        case '<': return cmp < 0;
+        case '=': return cmp === 0;
+        default: return false;
+    }
+}
+// One whitespace-separated comparator set (ANDed). Fail closed if any comparator
+// is unparseable.
+function satisfiesSet(v, set) {
+    const trimmed = set.trim();
+    if (trimmed === '')
+        return false;
+    const comparators = trimmed.split(/\s+/).filter(Boolean);
+    if (comparators.length === 0)
+        return false;
+    for (const c of comparators) {
+        const prims = expandComparator(c);
+        if (prims === null)
+            return false; // unparseable → fail closed
+        for (const prim of prims) {
+            if (!satisfiesPrimitive(v, prim))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Does `version` satisfy the semver `range`? OR-composed across `||`, AND-composed
+ * across whitespace. Fail-closed: an empty range, or any comparator this minimal
+ * implementation cannot parse, returns false. Comparison is on the numeric
+ * major.minor.patch core (prerelease tags are stripped, per `toNumericTuple`).
+ */
+function semverSatisfies(version, range) {
+    const r = String(range == null ? '' : range).trim();
+    if (r === '')
+        return false;
+    const v = toNumericTuple(version);
+    const orSets = r.split('||').map((s) => s.trim()).filter((s) => s.length > 0);
+    if (orSets.length === 0)
+        return false;
+    return orSets.some((set) => satisfiesSet(v, set));
+}

package/gsd-core/bin/lib/state-document.cjs

@@ -153,8 +153,10 @@ function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
         return false;
     const existing = existingProgress;
     const derived = derivedProgress;
-    return (existingProgressExceedsDerived(existing, derived, 'total_phases') ||
-        existingProgressExceedsDerived(existing, derived, 'completed_phases') ||
+    // total_phases is intentionally excluded from the ratchet: it must always
+    // take the freshly derived value so it can correct downward (#1446).
+    // Only completed_phases, total_plans, and completed_plans keep ratchet behaviour.
+    return (existingProgressExceedsDerived(existing, derived, 'completed_phases') ||
         existingProgressExceedsDerived(existing, derived, 'total_plans') ||
         existingProgressExceedsDerived(existing, derived, 'completed_plans'));
 }