@opengsd/gsd-core 1.18.0 → 1.20.0

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

@@ -30,7 +30,7 @@ const modelProfiles = require("./model-profiles.cjs");
 const { VALID_PROFILES, getAgentToModelMapForProfile, formatAgentToModelMapAsTable } = modelProfiles;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configSchema = require("./config-schema.cjs");
-const { VALID_CONFIG_KEYS, isValidConfigKey, getCapabilityConfigSchema } = configSchema;
+const { VALID_CONFIG_KEYS, DYNAMIC_KEY_PATTERNS, isValidConfigKey, getCapabilityConfigSchema } = configSchema;
 const secrets_cjs_1 = require("./secrets.cjs");
 const review_reviewer_selection_cjs_1 = require("./review-reviewer-selection.cjs");
 const configuration_cjs_1 = require("./configuration.cjs");
@@ -66,6 +66,8 @@ const SHIP_PR_BODY_TEMPLATE_TOKENS = new Set([
     'padded_phase',
 ]);
 const SHIP_PR_BODY_SOURCE_RE = /^(ROADMAP|PLAN|SUMMARY|VERIFICATION|STATE|REQUIREMENTS|CONTEXT)\.md\s+##\s+[^\r\n#][^\r\n]*$/;
+/** Allowed values of `git.repo_tagging` (#5706): `single` is the default. */
+const VALID_REPO_TAGGING_MODES = Object.freeze(['single', 'per_repo']);
 // ADR-612 PR-5: configuration accepts every convention the runtime can read.
 // Keep this distinct from roadmap-upgrade's supported target set: sequential
 // is valid project configuration but is not a migration destination.
@@ -87,6 +89,9 @@ const SCHEMA_DEFAULTS = {
     'planner.stall_detect_interval_minutes': 5,
     'planner.stall_threshold_minutes': 10,
     'git.create_tag': true,
+    // #5706 (epic #3628): per-repository milestone tagging mode. `single` is
+    // exactly the pre-existing behavior; `per_repo` is opt-in.
+    'git.repo_tagging': 'single',
     // #1689: per-plan agent_hint executor routing — default-on. A no-op for plans
     // without an agent_hint field, so existing dispatch is byte-identical.
     'workflow.agent_hint_routing': true,
@@ -191,6 +196,18 @@ function validateKnownConfigKeyPath(keyPath) {
         error(`Unknown config key: ${keyPath}. Did you mean ${suggested}?`, ERROR_REASON.CONFIG_INVALID_KEY);
     }
 }
+/**
+ * The key gate `config-set` and `config-new-project` share (#5268): a known
+ * misspelling gets its suggestion, and anything else outside the schema is
+ * refused with the valid-key list. One function, so the two verbs cannot
+ * disagree about which keys they accept or about the error text.
+ */
+function assertKnownConfigKey(cwd, kp) {
+    validateKnownConfigKeyPath(kp);
+    if (!isValidConfigKey(kp, cwd)) {
+        error(`Unknown config key: "${kp}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}, agent_skills.<agent-type>, features.<feature_name>, phase_commit_docs.<phase-id>`, ERROR_REASON.CONFIG_INVALID_KEY);
+    }
+}
 /**
  * Is `value` an acceptable `git.protected_branches` list (#3552)?
  *
@@ -271,9 +288,11 @@ function validateShipPrBodySections(value) {
         }
     });
 }
-// ─── Core config operations ───────────────────────────────────────────────────
 /**
- * Build a fully-materialized config object for a new project.
+ * Plan a fully-materialized config object for a new project. Writes nothing:
+ * the user defaults rewrite comes back as data, for the caller to persist once
+ * it has decided to write at all (#5268: a `--dry-run` never does, and a
+ * refused build never gets that far).
  *
  * Merges (increasing priority):
  *   1. Hardcoded defaults — every key that loadConfig() resolves, plus mode/granularity
@@ -284,11 +303,10 @@ function validateShipPrBodySections(value) {
  * Uses the canonical `git` namespace for branching keys (consistent with VALID_CONFIG_KEYS
  * and the settings workflow). loadConfig() handles both flat and nested formats, so this
  * is backward-compatible with existing projects that have flat keys.
- *
- * Returns a plain object — does NOT write any files.
  */
-function buildNewProjectConfig(userChoices) {
+function planNewProjectConfig(userChoices) {
     const choices = userChoices || {};
+    let defaultsRewrite = null;
     // #4976: the GSD-owned store resolves exactly as the config loader resolves
     // it (`GSD_HOME || homedir()`), so the defaults.json seeding this project is
     // the one the loader and its #3532 shadow warning read in the same run.
@@ -319,10 +337,9 @@ function buildNewProjectConfig(userChoices) {
                 const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' };
                 userDefaults['granularity'] = depthToGranularity[userDefaults['depth']] || userDefaults['depth'];
                 delete userDefaults['depth'];
-                try {
-                    (0, shell_command_projection_cjs_1.platformWriteSync)(globalDefaultsPath, JSON.stringify(userDefaults, null, 2));
-                }
-                catch { /* intentionally empty */ }
+                // The migrated value is used for this build whether or not the
+                // rewrite is ever persisted.
+                defaultsRewrite = { path: globalDefaultsPath, contents: JSON.stringify(userDefaults, null, 2) };
             }
         }
     }
@@ -344,6 +361,7 @@ function buildNewProjectConfig(userChoices) {
         git: {
             branching_strategy: CONFIG_DEFAULTS.branching_strategy,
             create_tag: true,
+            repo_tagging: 'single',
             phase_branch_template: CONFIG_DEFAULTS.phase_branch_template,
             milestone_branch_template: CONFIG_DEFAULTS.milestone_branch_template,
             quick_branch_template: CONFIG_DEFAULTS.quick_branch_template,
@@ -444,7 +462,134 @@ function buildNewProjectConfig(userChoices) {
         },
     };
     validateShipPrBodySections(config['ship']['pr_body_sections']);
-    return config;
+    return { config, defaultsRewrite };
+}
+/** Persist a plan's user defaults rewrite, best-effort as it always was. */
+function persistDefaultsRewrite(plan) {
+    if (plan.defaultsRewrite === null)
+        return;
+    try {
+        (0, shell_command_projection_cjs_1.platformWriteSync)(plan.defaultsRewrite.path, plan.defaultsRewrite.contents);
+    }
+    catch { /* intentionally empty */ }
+}
+/**
+ * Build a new project's config and persist the user defaults rewrite its plan
+ * carries. For callers that write the config unconditionally; one that may not
+ * (a `--dry-run`) plans with `planNewProjectConfig` and persists only on write.
+ */
+function buildNewProjectConfig(userChoices) {
+    const plan = planNewProjectConfig(userChoices);
+    persistDefaultsRewrite(plan);
+    return plan.config;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Does any schema key live under `keyPath`? True for a section (`workflow`),
+ * for the top level of a dynamic key family (`agent_skills`, whose keys are
+ * `agent_skills.<agent-type>`), and for the settings that are also parents
+ * (`review.max_prompt_tokens_per_reviewer` and its per-reviewer keys;
+ * `agent_tools`, a setting whose entries are the `agent_tools.<selector>`
+ * family).
+ */
+function hasChildConfigKeys(cwd, keyPath) {
+    const childPrefix = `${keyPath}.`;
+    for (const known of VALID_CONFIG_KEYS) {
+        if (known.startsWith(childPrefix))
+            return true;
+    }
+    if (DYNAMIC_KEY_PATTERNS.some((family) => family['topLevel'] === keyPath))
+        return true;
+    return Object.keys(getCapabilityConfigSchema(cwd)).some((known) => known.startsWith(childPrefix));
+}
+/**
+ * Is `keyPath` a section a choice may nest settings under? The same test as
+ * `hasChildConfigKeys`. A dynamic family's deeper levels
+ * (`model_profile_overrides.<runtime>`) are not recognised; an empty object
+ * there is refused as an unknown key, and it would set nothing anyway.
+ */
+function isConfigSection(cwd, keyPath) {
+    return hasChildConfigKeys(cwd, keyPath);
+}
+/**
+ * Hold `config-new-project` choices to the rules `config-set` applies (#5268).
+ *
+ * Choices arrive nested (`{"workflow":{"research":true}}`) while the schema
+ * and `config-set` address dotted leaf paths (`workflow.research`), so the
+ * walk descends through section objects and checks each leaf under its dotted
+ * path: the key through `assertKnownConfigKey`, the value through
+ * `validateConfigValue`. An object whose own path is a settable key with
+ * nothing under it (`model_overrides.<agent>`) is a leaf, as it is for
+ * `config-set`.
+ *
+ * Returns the checked choices as a new object and leaves `choices` as given:
+ * each value is the one `config-set` would persist (a normalizing rule's
+ * result where one applies). An empty object is a section with nothing set:
+ * refused as an unknown key unless its name is a real section, and left out
+ * of the result either way.
+ */
+function validateNewProjectChoices(cwd, choices, prefix = '') {
+    const checked = {};
+    for (const key of Object.keys(choices)) {
+        const kp = prefix ? `${prefix}.${key}` : key;
+        // An empty key names no setting. Refused here because an empty section
+        // name would otherwise be walked as if its contents sat one level up.
+        if (key === '')
+            assertKnownConfigKey(cwd, kp);
+        // A key is one path segment. A dot inside it spells a deeper path, which
+        // would pass the key gate while the merge wrote it as one literal key no
+        // reader resolves. The exception is a dot inside an id: one dynamic key
+        // family admits both the path cut at the dot and the whole path, so the
+        // dot is part of what that family calls a single key (`phase_commit_docs`
+        // is a map keyed by phase id, and "2.1" is a phase id).
+        const dot = key.indexOf('.');
+        if (dot !== -1) {
+            const head = prefix ? `${prefix}.${key.slice(0, dot)}` : key.slice(0, dot);
+            const dotIsInsideAnId = prefix !== '' && DYNAMIC_KEY_PATTERNS.some((family) => family.test(head) && family.test(kp));
+            if (!dotIsInsideAnId) {
+                error(`Invalid choice key "${key}" for config-new-project. Nest it instead of using a dotted key, e.g. {"workflow":{"research":true}}.`, ERROR_REASON.CONFIG_INVALID_KEY);
+            }
+        }
+        const value = choices[key];
+        if (isPlainObject(value) && (!isValidConfigKey(kp, cwd) || hasChildConfigKeys(cwd, kp))) {
+            // A non-empty section has its name checked through its leaves. An empty
+            // one has no leaves, so its name is checked here: config-set refuses
+            // `bogus '{}'` as an unknown key, and so does this.
+            if (Object.keys(value).length === 0 && !isValidConfigKey(kp, cwd) && !isConfigSection(cwd, kp)) {
+                assertKnownConfigKey(cwd, kp);
+            }
+            const section = validateNewProjectChoices(cwd, value, kp);
+            // Empty as given, or emptied by null choices: it sets nothing.
+            if (Object.keys(section).length > 0)
+                checked[key] = section;
+            continue;
+        }
+        // A section given a value that is not an object. config-set would call
+        // the name unknown, which misdescribes a real section; say what is wrong.
+        if (!isValidConfigKey(kp, cwd) && isConfigSection(cwd, kp)) {
+            error(`Invalid choice "${kp}" for config-new-project: it is a section, so its value must be an object of settings, e.g. {"workflow":{"research":true}}.`, ERROR_REASON.CONFIG_INVALID_KEY);
+        }
+        assertKnownConfigKey(cwd, kp);
+        // `config-set <key> null` clears the key: it skips the typed rules and
+        // leaves the key to its default. A null choice is the same request, so it
+        // skips them too and is left unchosen, where it used to be written as a
+        // literal null that config-set can never store.
+        const checkedValue = value === null
+            ? null
+            : validateConfigValue(cwd, kp, value, typeof value === 'string' ? value : JSON.stringify(value));
+        // config-set's setter refuses these segments after the key and value
+        // rules have run (`_setNestedValue`); same refusal, same place in the order.
+        // It also runs before the assignment below, so no such key reaches `checked`.
+        if (kp.split('.').some((segment) => segment === '__proto__' || segment === 'prototype' || segment === 'constructor')) {
+            error('Invalid config key (prototype pollution guard): ' + kp, ERROR_REASON.CONFIG_PARSE_FAILED);
+        }
+        if (value === null)
+            continue;
+        checked[key] = checkedValue;
+    }
+    return checked;
 }
 /**
  * Command: create a fully-materialized .planning/config.json for a new project.
@@ -453,25 +598,54 @@ function buildNewProjectConfig(userChoices) {
  * configured during /gsd:new-project). All remaining keys are filled from
  * hardcoded defaults and optional $GSD_HOME/.gsd/defaults.json.
  *
- * Idempotent: if config.json already exists, returns { created: false }.
+ * Choices are validated with `config-set`'s key and value rules before
+ * anything is written (#5268). With `dryRun`, prints the config that would be
+ * created and writes nothing.
+ *
+ * Idempotent: if config.json already exists, returns { created: false } once
+ * the choices have been checked; a refused choice is refused either way.
  */
-function cmdConfigNewProject(cwd, choicesJson, raw) {
+function cmdConfigNewProject(cwd, choicesJson, raw, options = {}) {
+    const dryRun = options.dryRun === true;
     const planningBase = planningDir(cwd);
     const configPath = node_path_1.default.join(planningBase, 'config.json');
-    // Idempotent: don't overwrite existing config
-    if (node_fs_1.default.existsSync(configPath)) {
-        output({ created: false, reason: 'already_exists' }, raw, 'exists');
-        return;
-    }
     // Parse user choices
     let userChoices = {};
     if (choicesJson && choicesJson.trim() !== '') {
+        let parsedChoices;
         try {
-            userChoices = JSON.parse(choicesJson);
+            parsedChoices = JSON.parse(choicesJson);
         }
         catch (err) {
             error('Invalid JSON for config-new-project: ' + err.message);
         }
+        // #5268: an array or a string parses as JSON and was then spread into the
+        // config as index keys.
+        if (!isPlainObject(parsedChoices)) {
+            error('Invalid choices for config-new-project: expected a JSON object of config keys.', ERROR_REASON.USAGE);
+        }
+        userChoices = parsedChoices;
+    }
+    // #5268: refuse what config-set refuses, before the first write — and
+    // before the existing-config check, so a refused choice is reported
+    // whether or not the project already has a config.
+    const checkedChoices = validateNewProjectChoices(cwd, userChoices);
+    // Idempotent: don't overwrite existing config
+    if (node_fs_1.default.existsSync(configPath)) {
+        output({ created: false, reason: 'already_exists' }, raw, 'exists');
+        return;
+    }
+    const plan = planNewProjectConfig(checkedChoices);
+    const config = plan.config;
+    if (dryRun) {
+        // The preview is CLI output, so secret keys are masked exactly as
+        // config-set and config-get mask them. See lib/secrets.cjs.
+        const preview = { ...config };
+        for (const key of Object.keys(preview)) {
+            preview[key] = (0, secrets_cjs_1.maskIfSecret)(key, preview[key]);
+        }
+        output({ dry_run: true, would_create: true, path: '.planning/config.json', config: preview }, raw, 'would create (dry run)');
+        return;
     }
     // Ensure .planning directory exists
     try {
@@ -480,14 +654,16 @@ function cmdConfigNewProject(cwd, choicesJson, raw) {
     catch (err) {
         error('Failed to create .planning directory: ' + err.message);
     }
-    const config = buildNewProjectConfig(userChoices);
     try {
         (0, shell_command_projection_cjs_1.platformWriteSync)(configPath, JSON.stringify(config, null, 2));
-        output({ created: true, path: '.planning/config.json' }, raw, 'created');
     }
     catch (err) {
         error('Failed to write config.json: ' + err.message);
     }
+    // The user defaults rewrite follows the config it was planned for: a
+    // creation that fails before here leaves the defaults file as it was.
+    persistDefaultsRewrite(plan);
+    output({ created: true, path: '.planning/config.json' }, raw, 'created');
 }
 /**
  * Ensures the config file exists (creates it if needed).
@@ -772,10 +948,7 @@ function cmdConfigSet(cwd, keyPath, value, raw, options = {}) {
     // TypeScript doesn't always infer never-return narrowing through error(), so we assert.
     const kp = keyPath;
     const val = value;
-    validateKnownConfigKeyPath(kp);
-    if (!isValidConfigKey(kp, cwd)) {
-        error(`Unknown config key: "${kp}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}, agent_skills.<agent-type>, features.<feature_name>, phase_commit_docs.<phase-id>`, ERROR_REASON.CONFIG_INVALID_KEY);
-    }
+    assertKnownConfigKey(cwd, kp);
     // Parse value (handle booleans, numbers, and JSON arrays/objects)
     let parsedValue = val;
     if (val === 'true')
@@ -832,6 +1005,60 @@ function cmdConfigSet(cwd, keyPath, value, raw, options = {}) {
     if (kp === 'project_code') {
         parsedValue = val;
     }
+    parsedValue = validateConfigValue(cwd, kp, parsedValue, val);
+    if (dryRun) {
+        const preview = previewConfigValue(cwd, kp, parsedValue);
+        if ((0, secrets_cjs_1.isSecretKey)(kp)) {
+            const masked = (0, secrets_cjs_1.maskSecret)(parsedValue);
+            const maskedPrev = preview.previousValue === undefined
+                ? undefined
+                : (0, secrets_cjs_1.maskSecret)(preview.previousValue);
+            output({ dry_run: true, would_update: true, key: kp, value: masked, previousValue: maskedPrev, masked: true }, raw, `${kp}=${masked} (dry run)`);
+            return;
+        }
+        output({ dry_run: true, would_update: true, key: kp, value: parsedValue, previousValue: preview.previousValue }, raw, `${kp}=${String(parsedValue)} (dry run)`);
+        return;
+    }
+    const setConfigValueResult = setConfigValue(cwd, kp, parsedValue);
+    // Mask secrets in both JSON and text output. The plaintext is written
+    // to config.json (that's where secrets live on disk); the CLI output
+    // must never echo it. See lib/secrets.cjs.
+    if ((0, secrets_cjs_1.isSecretKey)(kp)) {
+        // parsedValue is unknown at this point; maskSecret accepts MaskableValue
+        const masked = (0, secrets_cjs_1.maskSecret)(parsedValue);
+        const maskedPrev = setConfigValueResult.previousValue === undefined
+            ? undefined
+            : (0, secrets_cjs_1.maskSecret)(setConfigValueResult.previousValue);
+        const maskedResult = {
+            ...setConfigValueResult,
+            value: masked,
+            previousValue: maskedPrev,
+            masked: true,
+        };
+        output(maskedResult, raw, `${kp}=${masked}`);
+        return;
+    }
+    output(setConfigValueResult, raw, `${kp}=${String(parsedValue)}`);
+}
+/**
+ * The per-key VALUE rules, shared by `config-set` and `config-new-project`
+ * (#5268). They were inline in `cmdConfigSet`, so `config-new-project` had no
+ * way to apply them and wrote values `config-set` refuses for the same key.
+ *
+ * `parsedValue` is the typed value about to be persisted and `val` its text
+ * form, used only in error messages. Returns the value to persist for `kp`:
+ * the input itself, or its normalized form where a rule normalizes
+ * (`review.default_reviewers`). A value the key does not accept has no value
+ * to persist, so it is refused through `error()` instead.
+ */
+function validateConfigValue(cwd, kp, parsedValue, val) {
+    // #1581: project_code is an identifier, and config-set stores it as the text
+    // typed. Through config-set this never fires; it holds a JSON choice (#5268)
+    // to the type config-set stores, rather than writing a number readers cast
+    // to string.
+    if (kp === 'project_code' && typeof parsedValue !== 'string') {
+        error(`Invalid project_code '${val}'. Must be a string identifier, e.g. "PROJ".`);
+    }
     const VALID_CONTEXT_VALUES = ['dev', 'research', 'review'];
     if (kp === 'context')
         assertEnumValue(parsedValue, val, VALID_CONTEXT_VALUES, 'context value');
@@ -912,6 +1139,9 @@ function cmdConfigSet(cwd, keyPath, value, raw, options = {}) {
             error(`Invalid git.create_tag '${val}'. Must be a boolean (true or false).`);
         }
     }
+    // #5706 (epic #3628): per-repository milestone tagging mode, enum only.
+    if (kp === 'git.repo_tagging')
+        assertEnumValue(parsedValue, val, VALID_REPO_TAGGING_MODES, 'git.repo_tagging');
     if (kp === 'git.protected_branches') {
         if (!isValidProtectedBranches(parsedValue)) {
             error(`Invalid git.protected_branches '${val}'. Must be a non-empty array of non-empty branch names.`);
@@ -1076,39 +1306,7 @@ function cmdConfigSet(cwd, keyPath, value, raw, options = {}) {
             }
         }
     }
-    if (dryRun) {
-        const preview = previewConfigValue(cwd, kp, parsedValue);
-        if ((0, secrets_cjs_1.isSecretKey)(kp)) {
-            const masked = (0, secrets_cjs_1.maskSecret)(parsedValue);
-            const maskedPrev = preview.previousValue === undefined
-                ? undefined
-                : (0, secrets_cjs_1.maskSecret)(preview.previousValue);
-            output({ dry_run: true, would_update: true, key: kp, value: masked, previousValue: maskedPrev, masked: true }, raw, `${kp}=${masked} (dry run)`);
-            return;
-        }
-        output({ dry_run: true, would_update: true, key: kp, value: parsedValue, previousValue: preview.previousValue }, raw, `${kp}=${String(parsedValue)} (dry run)`);
-        return;
-    }
-    const setConfigValueResult = setConfigValue(cwd, kp, parsedValue);
-    // Mask secrets in both JSON and text output. The plaintext is written
-    // to config.json (that's where secrets live on disk); the CLI output
-    // must never echo it. See lib/secrets.cjs.
-    if ((0, secrets_cjs_1.isSecretKey)(kp)) {
-        // parsedValue is unknown at this point; maskSecret accepts MaskableValue
-        const masked = (0, secrets_cjs_1.maskSecret)(parsedValue);
-        const maskedPrev = setConfigValueResult.previousValue === undefined
-            ? undefined
-            : (0, secrets_cjs_1.maskSecret)(setConfigValueResult.previousValue);
-        const maskedResult = {
-            ...setConfigValueResult,
-            value: masked,
-            previousValue: maskedPrev,
-            masked: true,
-        };
-        output(maskedResult, raw, `${kp}=${masked}`);
-        return;
-    }
-    output(setConfigValueResult, raw, `${kp}=${String(parsedValue)}`);
+    return parsedValue;
 }
 function cmdConfigGet(cwd, keyPath, raw, defaultValue) {
     const configPath = node_path_1.default.join(planningDir(cwd), 'config.json');

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

@@ -40,6 +40,9 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // frontmatter-fence.cjs is a leaf module (no imports), so this adds no cycle.
 const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
+// pattern.cjs is a leaf module (escapeRegex only), so this adds no cycle.
+const pattern_cjs_1 = require("./pattern.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -521,6 +524,45 @@ function findOrphanSummaries(planFiles, summaryFiles) {
     }
     return summaryFiles.filter((s) => !claimed.has(s));
 }
+/**
+ * #5542: does `summaryFile` pair with ANY of `planFiles`, by the same
+ * `summaryCandidates` rule the counts use? The ROADMAP plan-checkbox writers
+ * tick a row only for a summary that does — never by id prefix, which let a
+ * leftover `47-1` summary survive because a live `47-10` plan starts with `47-1`.
+ */
+function summaryPairsWithAnyPlan(planFiles, summaryFile) {
+    return planFiles.some((plan) => countMatchedSummaries([plan], [summaryFile]) > 0);
+}
+/**
+ * #5542: lookahead that ends a plan id inside a ROADMAP checkbox row, so `47-1`
+ * never matches the start of `47-10-PLAN.md`. The id ends at `.md` or at any
+ * character that is not a word character or a `.`/`-` followed by a digit: a
+ * dotted sub-id (`01-01.1`) or a longer numeric id (`05-01-02`) is a distinct
+ * plan, not a continuation of `01-01`/`05-01`, while sentence punctuation
+ * (`01-01. Setup`) and a slug (`05-01-scaffold`) still end the id.
+ */
+const PLAN_ID_ROW_BOUNDARY_SOURCE = '(?=\\.md|(?!\\w|[.-]\\d))';
+/**
+ * #5542: the checkbox-row regex for one plan id. By default it matches an
+ * UNCHECKED row (the tick target); `anyState` matches either box state, for
+ * presence detection; `anchored` pins the row to a line start (the
+ * `phase complete` bullet flip). Capture group 1 is the opening `- [`, group 2
+ * the rest after the box, so a caller ticks with `$1x$2`.
+ */
+function planRowPattern(planId, opts = {}) {
+    const box = opts.anyState ? '[x ]' : ' ';
+    const lead = opts.anchored ? '^(\\s*-\\s*\\[)' : '(-\\s*\\[)';
+    return new RegExp(`${lead}${box}(\\]\\s*(?:\\*\\*)?${(0, pattern_cjs_1.escapeRegex)(planId)}${PLAN_ID_ROW_BOUNDARY_SOURCE}(?:\\*\\*)?)`, 'i');
+}
+/**
+ * Tick the first line-anchored unchecked row for `planId` in `text` (the
+ * `phase complete` / `roadmap update-plan-progress` bullet flip): a bullet
+ * mutation through `updateBullet`, so never a fenced line or mid-line match.
+ */
+function tickAnchoredPlanRow(text, planId) {
+    const row = planRowPattern(planId, { anchored: true });
+    return (0, markdown_sectionizer_cjs_1.updateBullet)(text, (_bulletText, rawLine) => row.test(rawLine), (rawLine) => rawLine.replace(row, '$1x$2'));
+}
 module.exports = {
     toPosixPath,
     normalizeLineEndings,
@@ -536,4 +578,7 @@ module.exports = {
     countMatchedSummaries,
     findUnsummarizedPlans,
     findOrphanSummaries,
+    summaryPairsWithAnyPlan,
+    planRowPattern,
+    tickAnchoredPlanRow,
 };

package/gsd-core/bin/lib/decision-coverage-support.cjs

@@ -20,12 +20,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACKER_RESOLVE_BUDGET_MS = void 0;
 exports.decisionMentioned = decisionMentioned;
 exports.phaseDirProblem = phaseDirProblem;
 exports.loadPlanContents = loadPlanContents;
 exports.loadSummaryContents = loadSummaryContents;
 exports.loadDecisionExtraction = loadDecisionExtraction;
 exports.extractPlanDesignatedSections = extractPlanDesignatedSections;
+exports.resolveTrackerBodies = resolveTrackerBodies;
 exports.buildPlanMessage = buildPlanMessage;
 exports.buildVerifyMessage = buildVerifyMessage;
 exports.phaseCommitMessages = phaseCommitMessages;
@@ -46,6 +48,12 @@ const { scanPhasePlans } = planScanMod;
 // 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 planDocumentMod = require("./plan-document.cjs");
+const { parsePlanDocument } = planDocumentMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const taskContentResolutionMod = require("./task-content-resolution.cjs");
+const { resolveTaskContent, splitTrackerId, loadResolverCapabilities, isResolverFailure, contentTexts, } = taskContentResolutionMod;
 // ─── Decision matching ────────────────────────────────────────────────────────
 function normalizePhrase(text) {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -189,6 +197,72 @@ function extractPlanDesignatedSections(planContent) {
     parts.push((0, markdown_sectionizer_cjs_1.extractXmlTagBodies)(cleaned));
     return parts.join('\n\n');
 }
+/** Aggregate wall-clock budget for all resolver spawns in one gate run; registry load and each spawn's timeout are inside it (spawn timeouts are clamped to the remainder), so this is the true bound for resolver work. */
+exports.TRACKER_RESOLVE_BUDGET_MS = 120_000;
+const unreadable = (reason, span) => ({ kind: 'unreadable', reason, span });
+/**
+ * Extra scannable text per plan (same index) from tracker-resolved task content; '' for plans without `tracker-id=`.
+ * `missingResolver` names the first tracker id with no installed resolver: coverage is monotone (a mention anywhere counts), so
+ * that can only cause a false "uncovered" — callers go `unreadable` only when a decision would otherwise be uncovered.
+ */
+function resolveTrackerBodies(projectDir, planContents, deps = {}) {
+    let missingResolver = null;
+    let capabilities = null;
+    const seen = new Map();
+    const resolveFn = deps.resolveTaskContentFn ?? resolveTaskContent;
+    const bodies = [];
+    const now = deps.now ?? (() => performance.now());
+    const startedAt = now();
+    for (const raw of planContents) {
+        const content = stripCommentsAndFences(raw);
+        if (!/\btracker-id\s*=/i.test(content)) {
+            bodies.push('');
+            continue;
+        }
+        const parts = [];
+        for (const task of parsePlanDocument(content).tasks) {
+            const trackerId = task.trackerId;
+            if (trackerId === null)
+                continue;
+            const cached = seen.get(trackerId);
+            if (cached) {
+                parts.push(...cached);
+                continue;
+            }
+            if (capabilities === null) {
+                try {
+                    capabilities = (deps.loadCapabilities ?? loadResolverCapabilities)(projectDir);
+                }
+                catch (err) {
+                    return unreadable(`capability registry unreadable: ${err instanceof Error ? err.message : String(err)}`, trackerId);
+                }
+            }
+            // Floor: spawnSync rejects a fractional timeout, and a 0 timeout means unbounded, so a sub-ms remainder is a rejection.
+            const remainingMs = Math.floor(exports.TRACKER_RESOLVE_BUDGET_MS - (now() - startedAt));
+            if (remainingMs <= 0) {
+                return unreadable(`tracker resolution exceeded the ${exports.TRACKER_RESOLVE_BUDGET_MS} ms aggregate budget`, trackerId);
+            }
+            try {
+                const result = resolveFn({ trackerId, capabilities, timeoutOverrideMs: remainingMs });
+                if (result.kind === 'no-resolver') {
+                    missingResolver ??= { span: trackerId, reason: `no task-content resolver installed for tracker prefix "${splitTrackerId(trackerId)?.prefix}"` };
+                }
+                // Per field: an unclosed fence in one field must not swallow the rest.
+                const texts = result.kind === 'resolved' ? contentTexts(result.content).map(stripCommentsAndFences) : [];
+                seen.set(trackerId, texts);
+                parts.push(...texts);
+            }
+            catch (err) {
+                if (isResolverFailure(err)) {
+                    return unreadable(`tracker task content unresolved: ${err.message}`, trackerId);
+                }
+                throw err;
+            }
+        }
+        bodies.push(parts.join('\n'));
+    }
+    return (0, gate_evidence_cjs_1.evidenceFound)({ bodies, missingResolver });
+}
 function buildPlanMessage(uncovered) {
     if (uncovered.length === 0)
         return 'All trackable CONTEXT.md decisions are covered by plans.';

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

@@ -851,6 +851,17 @@ function frontmatterListEntries(content, key) {
  * no closed, parseable frontmatter mapping or the key is not an own key of it.
  */
 function rawFrontmatterField(content, key) {
+    const mapping = rawFrontmatterMapping(content);
+    if (!mapping || !Object.prototype.hasOwnProperty.call(mapping, key))
+        return null;
+    return { value: mapping[key] };
+}
+/**
+ * The top-level frontmatter mapping VERBATIM, off `rawFrontmatterField`'s guarded parse path.
+ * Null when the document has no closed, parseable frontmatter mapping — so a caller can tell
+ * "parsed, without that key" (#4998 review) from "no usable frontmatter".
+ */
+function rawFrontmatterMapping(content) {
     const found = frontmatterRegion(content);
     if (!found || !found.terminated)
         return null;
@@ -867,9 +878,7 @@ function rawFrontmatterField(content, key) {
     }
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return null;
-    if (!Object.prototype.hasOwnProperty.call(raw, key))
-        return null;
-    return { value: raw[key] };
+    return raw;
 }
 /**
  * Escape a string for emission inside a YAML double-quoted scalar (#1779). ADR-3473 §8.1
@@ -940,6 +949,14 @@ function scalarNeedsDoubleQuoting(s) {
     // round-trip.
     if (/[\uD800-\uDFFF]/.test(s))
         return true;
+    // #4998: U+2028/U+2029 are not YAML line breaks, so a bare one round-trips
+    // through js-yaml, but every line-anchored reader of a planning document
+    // (`^key:\s*(.+)` with the `m` flag) ends the line there and reads only the
+    // part before it. (A value holding `:` was already quoted by the callers, so
+    // no key could be forged this way.) The quoted path escapes them (`\L`,
+    // `\P`), which no such reader splits on.
+    if (/[\u2028\u2029]/.test(s))
+        return true;
     return false;
 }
 /**
@@ -1806,6 +1823,7 @@ module.exports = {
     // parse path — the decision-coverage gates read `must_haves`/`truths`/`objective` and the
     // SUMMARY `files_modified` list through it instead of a hand-rolled `^key:` scan / regex.
     rawFrontmatterField,
+    rawFrontmatterMapping,
     // #5139: one key's block as unparsed text, for a citation scan that must survive frontmatter
     // the YAML parser refuses.
     frontmatterKeyBlockText,

package/gsd-core/bin/lib/gate-api-coverage-verify-pre.cjs

@@ -39,7 +39,7 @@ const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
+const { phaseDirectoryOptions, findPhaseInternal } = phaseLocatorMod;
 const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapModule = require("./roadmap.cjs");
@@ -171,7 +171,7 @@ function evaluateApiCoverageVerifyPre(input) {
     let resolvedDir = null;
     let phaseNumber = '';
     if (token) {
-        const found = findPhaseInternal(projectDir, token);
+        const found = findPhaseInternal(projectDir, token, undefined, phaseDirectoryOptions(projectDir));
         if (found && found.directory) {
             // findPhaseInternal's `directory` is relative to the project root; anchor it to `projectDir`
             // (not the process cwd) so the gate reads the same files in-process as it does from the CLI.