@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.5

package/gsd-core/bin/lib/capability-validator.cjs

@@ -709,7 +709,7 @@ const VALID_HOOK_EVENTS = new Set(['claude', 'gemini']);
 // DISTINCT from hookEvents (managed-hook dialect): extensionEvents describes the
 // plugin-owned event subset imperative hosts expose (opencode / pi); 'none' = the
 // host exposes no extension surface (engine owns the bus, e.g. VS Code).
-const VALID_EXTENSION_EVENTS = new Set(['opencode', 'pi', 'none']);
+const VALID_EXTENSION_EVENTS = new Set(['opencode', 'pi', 'hermes', 'none']);
 const VALID_SANDBOX_TIERS = new Set(['none', 'codex-agent-sandbox']);
 const VALID_ARTIFACT_KIND_NAMES = new Set(['commands', 'agents', 'skills', 'kimi-agents']);
 const VALID_ARTIFACT_NESTINGS = new Set(['flat', 'nested']);

package/gsd-core/bin/lib/capability-writer.cjs

@@ -77,8 +77,17 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
     const before = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
     const resolvedConfigDir = before.runtimeConfigDir;
     // ── Load registry ─────────────────────────────────────────────────────────
+    // Issue #2045 (DEFECT 2): validate against the COMPOSED overlay-aware registry
+    // (first-party ∪ accepted overlays), mirroring capability-state.cts:547-551.
+    // The frozen capability-registry.cjs only knows first-party ids, so a third-
+    // party cap failed the membership check below → "unknown capability" even
+    // though resolveCapabilityRuntimeState (the `before` snapshot, line 150) already
+    // knew about it. loadRegistry is non-throwing and first-party-wins, so a
+    // malformed overlay is skipped (never crashes the writer); a truly-unknown id
+    // is STILL rejected because it is absent from the composed capabilities map.
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const registry = require('./capability-registry.cjs');
+    const { loadRegistry } = require('./capability-loader.cjs');
+    const registry = loadRegistry({ includeInstalled: true, cwd, gsdHome: process.env['GSD_HOME'] });
     const capabilitiesMap = (registry['capabilities'] && typeof registry['capabilities'] === 'object' && !Array.isArray(registry['capabilities'])
         ? registry['capabilities']
         : {});

package/gsd-core/bin/lib/check-command-router.cjs

@@ -37,6 +37,9 @@ const prohibition_enforcement_cjs_1 = require("./prohibition-enforcement.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const gatePredicateEval = require("./gate-predicate-evaluator.cjs");
 const { evaluatePredicate } = gatePredicateEval;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const apiCoverageMod = require("./api-coverage.cjs");
+const { detectApiIntegration, validateCoverageMatrix } = apiCoverageMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function normalizePhrase(text) {
@@ -131,10 +134,13 @@ function loadPlanContents(phaseDir) {
     }
 }
 const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
-const XML_DECISION_TAGS_RE = /<(?:objective|tasks?|action)(?:\s[^>]*)?>([\s\S]*?)<\/(?:objective|tasks?|action)>/gi;
+const XML_DECISION_TAGS_RE = /<(?:objective|tasks?|action)(?:\s[^>]{0,1000})?>((?:(?!<(?:objective|tasks?|action)[\s>])[\s\S])*?)<\/(?:objective|tasks?|action)>/gi;
 function stripCommentsAndFences(text) {
     // HTML-comment stripping stays caller-side (the seam does not strip HTML comments).
-    const htmlStripped = text.replace(/<!--[\s\S]*?-->/g, ' ');
+    // Stop-at-next-open body (ReDoS-safe, #2128); an UNCLOSED `<!--` does not match,
+    // so downstream tags are preserved (unlike a `(?:-->|$)` fallback, which would
+    // wipe to EOF and fail-close the decision-coverage gate).
+    const htmlStripped = text.replace(/<!--(?:(?!<!--)[\s\S])*?-->/g, ' ');
     // Fenced-code stripping: delegate to the canonical CommonMark-correct seam.
     // replaces the prior independent regex copy (```` ``` ``` ````  + `~~~ ~~~`).
     return (0, markdown_sectionizer_cjs_1.stripFencedCode)(htmlStripped).text;
@@ -876,6 +882,233 @@ function cmdCheckPredicate(projectDir, args, raw) {
     }
     output(result, raw, undefined);
 }
+// ─── api-coverage-verify-pre ──────────────────────────────────────────────────
+/**
+ * api-coverage.verify-pre: BLOCKING seal-time gate for the ai-integration
+ * capability (#1562). Enforces "Full API Coverage by Default — Opt Out, Never
+ * Opt In." A phase that integrates an external API/SDK/service may not seal
+ * until a COVERAGE.md matrix enumerates the surface and every non-integrated
+ * capability is an explicit, reasoned opt-out.
+ *
+ * Contract (two touch points composed into one check):
+ *   1. If COVERAGE.md exists in the phase dir → validate it (acceptance #2).
+ *      Block on any validation error (empty matrix, OPT-OUT without reason,
+ *      duplicate/empty capability).
+ *   2. If COVERAGE.md is absent → run detectApiIntegration over the phase scope
+ *      (PLAN.md body, then ROADMAP phase section as fallback). If a strong
+ *      external-API-integration signal is detected → BLOCK ("integration
+ *      detected without coverage matrix"). If no signal → PASS (treat as a
+ *      non-API phase; acceptance #4 — low false positives).
+ *
+ * The detector is the FALLBACK for the "nobody decided / forgot the matrix"
+ * case; the primary path is the plan:pre contribution prompting COVERAGE.md.
+ *
+ * Args: check api-coverage.verify-pre <phase-dir>
+ * Emits the uniform gate contract: { block, passed, message, ...details }.
+ */
+function cmdApiCoverageVerifyPre(projectDir, args, raw) {
+    const phaseArg = typeof args[2] === 'string' ? args[2] : '';
+    if (!phaseArg) {
+        error('api-coverage.verify-pre requires a phase argument: check api-coverage.verify-pre <phase-dir-or-token>', ERROR_REASON.SDK_MISSING_ARG);
+        return;
+    }
+    const pDir = planningDir(projectDir);
+    const phasesRoot = node_path_1.default.join(pDir, 'phases');
+    // SECURITY (path traversal): the phase argument is taken ONLY as a phase
+    // token — its basename — and resolved by findPhaseInternal strictly under
+    // .planning/phases/ (or a milestone archive). The raw arg is never used as a
+    // path, so `..`, absolute paths, and arbitrary directories cannot reach a
+    // file read. Mirrors cmdVerifySchemaDrift's token-match approach.
+    let token = phaseArg.replace(/\\/g, '/').split('/').filter(Boolean).pop() || '';
+    // A token like ".." or "." carries no phase identity → unresolvable.
+    if (token === '.' || token === '..')
+        token = '';
+    // Not a GSD project (no phases tree at all) → fail-open: nothing to gate.
+    if (!node_fs_1.default.existsSync(phasesRoot)) {
+        output({
+            block: false,
+            passed: true,
+            coverage_present: false,
+            detected: false,
+            message: 'api-coverage: no .planning/phases directory; gate skipped (not a GSD project layout)',
+        }, raw, undefined);
+        return;
+    }
+    // Resolve the phase dir under the contained phases root.
+    let resolvedDir = null;
+    let phaseNumber = '';
+    if (token) {
+        const found = findPhaseInternal(projectDir, token);
+        if (found && found.directory) {
+            resolvedDir = found.directory;
+            phaseNumber = found.phase_number || '';
+        }
+    }
+    if (!resolvedDir) {
+        // The phases tree EXISTS but THIS phase could not be resolved. For a
+        // BLOCKING gate, fail-closed: a missing phase dir must not silently bypass
+        // the coverage requirement. (Distinguished from "no .planning at all"
+        // above, which is a genuine non-GSD-project → pass.)
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            phase_lookup_failed: true,
+            message: `api-coverage: could not resolve phase "${phaseArg}" under .planning/phases/. ` +
+                'Resolve the phase directory (or produce COVERAGE.md) before sealing.',
+        }, raw, undefined);
+        return;
+    }
+    // Defense-in-depth: the resolved dir must be inside the phases root (or a
+    // milestone archive under .planning/milestones).
+    const milestonesRoot = node_path_1.default.join(pDir, 'milestones');
+    if (!isInsideRoot(resolvedDir, phasesRoot) && !isInsideRoot(resolvedDir, milestonesRoot)) {
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            message: 'api-coverage: resolved phase dir escapes .planning/ — refusing to evaluate',
+        }, raw, undefined);
+        return;
+    }
+    // (1) locate COVERAGE.md — prefer the exact name, then a single *-COVERAGE.md.
+    let coverageFile = '';
+    let suffixed = [];
+    try {
+        const entries = node_fs_1.default.readdirSync(resolvedDir, { withFileTypes: true });
+        const files = entries.filter((e) => e.isFile()).map((e) => e.name);
+        const exact = files.find((f) => /^COVERAGE\.md$/i.test(f));
+        if (exact) {
+            coverageFile = exact;
+        }
+        else {
+            suffixed = files.filter((f) => /-COVERAGE\.md$/i.test(f)).sort();
+            if (suffixed.length === 1)
+                coverageFile = suffixed[0];
+        }
+    }
+    catch {
+        // readdir failure → treat as no matrix readable; fall through to detection.
+    }
+    if (coverageFile) {
+        let matrixText;
+        try {
+            matrixText = node_fs_1.default.readFileSync(node_path_1.default.join(resolvedDir, coverageFile), 'utf8');
+        }
+        catch {
+            // COVERAGE.md exists but is unreadable (EACCES/EIO/encoding). Fail-closed
+            // with a useful message rather than a raw throw.
+            output({
+                block: true,
+                passed: false,
+                coverage_present: true,
+                message: `api-coverage: COVERAGE.md exists but is unreadable — fix file permissions/encoding before sealing`,
+            }, raw, undefined);
+            return;
+        }
+        const v = validateCoverageMatrix(matrixText);
+        if (v.valid) {
+            output({
+                block: false,
+                passed: true,
+                coverage_present: true,
+                matrix: coverageFile,
+                counts: v.counts,
+                message: `api-coverage: matrix present (${v.counts.surface} capabilities, ${v.counts.optout} opt-out)`,
+            }, raw, undefined);
+            return;
+        }
+        // Fixed-template message (no raw cell content echoed into the LLM-facing
+        // message). The structured `errors` array is safe (row-indexed, no cell
+        // values) and travels as data for tooling that wants detail.
+        output({
+            block: true,
+            passed: false,
+            coverage_present: true,
+            matrix: coverageFile,
+            error_count: v.errors.length,
+            errors: v.errors,
+            message: `api-coverage: COVERAGE.md has ${v.errors.length} problem(s) — fix the matrix (every capability INTEGRATE or OPT-OUT with a reason) before sealing`,
+        }, raw, undefined);
+        return;
+    }
+    if (suffixed.length > 1) {
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            message: `api-coverage: multiple *-COVERAGE.md files found (${suffixed.length}) — consolidate into one COVERAGE.md before sealing`,
+        }, raw, undefined);
+        return;
+    }
+    // (2) no matrix — detect whether this phase integrates an external API.
+    const scopeText = readPhaseScope(projectDir, resolvedDir, phaseNumber);
+    const detection = detectApiIntegration(scopeText);
+    if (detection.detected) {
+        // Surface only verb/noun (typed, bounded) — NOT raw prose snippets — so the
+        // gate output cannot relay injected PLAN.md instructions to the orchestrator.
+        const signals = detection.signals.map((s) => ({ verb: s.verb, noun: s.noun }));
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: true,
+            signals,
+            message: 'api-coverage: external-API integration detected without a coverage matrix. ' +
+                'Produce COVERAGE.md enumerating the API surface (every capability INTEGRATE or ' +
+                'OPT-OUT with a reason) before sealing. Full coverage is the default.',
+        }, raw, undefined);
+        return;
+    }
+    output({
+        block: false,
+        passed: true,
+        coverage_present: false,
+        detected: false,
+        message: 'api-coverage: no external-API integration detected; coverage matrix not required',
+    }, raw, undefined);
+}
+/**
+ * Read the phase-scope text used for API-integration detection. Uses the
+ * resolved plan files (PLAN.md bodies — the planner's own words about what the
+ * phase does) and, as a fallback, ONLY THIS PHASE'S ROADMAP section (not the
+ * whole roadmap, which would cross-contaminate sibling phases). Strips nothing
+ * here — detectApiIntegration strips fenced code itself.
+ */
+function readPhaseScope(projectDir, phaseDir, phaseNumber) {
+    const chunks = [];
+    try {
+        const entries = node_fs_1.default.readdirSync(phaseDir, { withFileTypes: true });
+        const plans = entries
+            .filter((e) => e.isFile() && /-PLAN\.md$/i.test(e.name))
+            .map((e) => e.name)
+            .sort();
+        for (const p of plans) {
+            chunks.push(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, p), 'utf8'));
+        }
+    }
+    catch {
+        // ignore — fall through to roadmap
+    }
+    if (chunks.join('').trim().length > 0)
+        return chunks.join('\n\n');
+    // Fallback: ONLY this phase's ROADMAP section (not the whole file, which
+    // would pollute detection with sibling-phase prose). Best-effort; absence or
+    // an unresolvable section is non-fatal (detector returns not-detected).
+    if (phaseNumber) {
+        try {
+            const section = getRoadmapPhaseWithFallback(projectDir, phaseNumber);
+            if (section)
+                return section;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return '';
+}
 function routeCheckCommand({ args, cwd, raw }) {
     // Normalize dots to hyphens in the subcommand so both forms are accepted.
     // This makes `check.query = "ui.plan-gate"` (dotted form in capability.json gates)
@@ -905,6 +1138,12 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdGapAnalysisPlanPost(cwd, args, raw);
         return;
     }
+    if (subcommand === 'api-coverage-verify-pre') {
+        // ai-integration capability blocking gate at verify:pre (#1562). Dot-to-
+        // hyphen normalization means query "api-coverage.verify-pre" routes here.
+        cmdApiCoverageVerifyPre(cwd, args, raw);
+        return;
+    }
     if (subcommand === 'tdd-review-checkpoint') {
         cmdTddReviewCheckpoint(cwd, args, raw);
         return;
@@ -945,7 +1184,7 @@ function routeCheckCommand({ args, cwd, raw }) {
         (0, prohibition_enforcement_cjs_1.routeProhibitionEnforcement)(args, raw);
         return;
     }
-    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, predicate, prohibition-enforcement, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    error('Unknown check subcommand. Available: api-coverage-verify-pre, auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, predicate, prohibition-enforcement, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
 }
 module.exports = {
     routeCheckCommand,

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

@@ -471,9 +471,11 @@ function cmdEffortSync(cwd, raw, opts) {
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
     const { getGlobalConfigDir } = require('./runtime-homes.cjs');
     // Use install-time resolvers: they merge ~/.gsd/defaults.json with project config,
-    // matching the exact logic used when agents were originally installed.
+    // matching the exact logic used when agents were originally installed. #2071: these
+    // live in the shipped sibling install-effort-resolver.cjs (extracted from the
+    // package-root bin/install.js, which the installer never copies into a runtime home).
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
-    const { readGsdEffectiveEffortConfig, resolveInstallTimeEffort } = require('../../../bin/install.js');
+    const { readGsdEffectiveEffortConfig, resolveInstallTimeEffort } = require('./install-effort-resolver.cjs');
     const effortCfg = readGsdEffectiveEffortConfig(cwd);
     const agentsDir = node_path_1.default.join(opts.configDir || getGlobalConfigDir(runtime), 'agents');
     if (!node_fs_1.default.existsSync(agentsDir)) {
@@ -1157,7 +1159,7 @@ function cmdTodoMatchPhase(cwd, phase, raw) {
                 const planContent = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(phaseDir, pf));
                 if (planContent === null)
                     continue;
-                const fmFiles = planContent.match(/files_modified:\s*\[([^\]]*)\]/);
+                const fmFiles = planContent.match(/files_modified:\s*\[([^\]]{0,8000})\]/);
                 if (fmFiles) {
                     phasePlans.push(...fmFiles[1].split(',').map(s => s.trim().replace(/['"]/g, '')).filter(Boolean));
                 }
@@ -1302,8 +1304,8 @@ function cmdStats(cwd, format, raw) {
         const roadmapContent = extractCurrentMilestone(roadmapRaw, cwd);
         // Matches both plain numeric (Phase 1:) and milestone-prefixed (Phase 2-01:) headings.
         // Also tolerates optional [bracket-token] scope prefix on phase headings.
-        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-        const headingPattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
+        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const headingPattern = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:\s*([^\n]+)/gi;
         let match;
         while ((match = headingPattern.exec(roadmapContent)) !== null) {
             const key = normalizePhaseName(match[1]);

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

@@ -104,6 +104,7 @@ const CONFIG_DEFAULTS = {
     verifier: _getNestedConfigDefault('workflow', 'verifier'),
     nyquist_validation: _getNestedConfigDefault('workflow', 'nyquist_validation'),
     ai_integration_phase: _getNestedConfigDefault('workflow', 'ai_integration_phase'),
+    api_coverage_gate: _getNestedConfigDefault('workflow', 'api_coverage_gate'),
     parallelization: _getConfigDefault('parallelization'),
     brave_search: _getConfigDefault('brave_search'),
     firecrawl: _getConfigDefault('firecrawl'),

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

@@ -209,6 +209,7 @@ function buildNewProjectConfig(userChoices) {
             ui_phase: true,
             ui_safety_gate: true,
             ai_integration_phase: true,
+            api_coverage_gate: true,
             human_verify_mode: 'end-of-phase',
             context_guard_mode: 'warn',
             text_mode: false,
@@ -408,6 +409,81 @@ function _setNestedValue(config, keyPath, parsedValue) {
     current[lastKey] = parsedValue;
     return previousValue;
 }
+/**
+ * Deletes a value from the config object, allowing nested values via dot
+ * notation (e.g., "review.models.gemini"). Mirrors `_setNestedValue`'s
+ * prototype-pollution guard on every path segment (including intermediates).
+ *
+ * Unlike `_setNestedValue`, this NEVER creates missing intermediate objects —
+ * if any segment along the path is missing (or not a plain, non-array
+ * object), the key doesn't exist and we return early without mutating
+ * `config` at all.
+ *
+ * Does not prune now-empty parent objects after deletion (matches the
+ * conservative, structure-preserving behaviour callers expect from a bare
+ * unset).
+ *
+ * Returns { previousValue, existed } — existed is false when the leaf key
+ * (or an intermediate segment) was never present.
+ * Calls error() (process.exit(1)) on prototype-pollution attempts.
+ */
+function _unsetNestedValue(config, keyPath) {
+    const keys = keyPath.split('.');
+    let current = config;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (key === '__proto__' || key === 'prototype' || key === 'constructor') {
+            error('Invalid config key (prototype pollution guard): ' + keyPath, ERROR_REASON.CONFIG_PARSE_FAILED);
+        }
+        const existingChild = current[key];
+        if (existingChild === undefined || existingChild === null || typeof existingChild !== 'object' || Array.isArray(existingChild)) {
+            // Path doesn't exist — nothing to unset, and we must not create it.
+            return { previousValue: undefined, existed: false };
+        }
+        current = existingChild;
+    }
+    const lastKey = keys[keys.length - 1];
+    if (lastKey === '__proto__' || lastKey === 'prototype' || lastKey === 'constructor') {
+        error('Invalid config key (prototype pollution guard): ' + keyPath, ERROR_REASON.CONFIG_PARSE_FAILED);
+    }
+    const existed = Object.prototype.hasOwnProperty.call(current, lastKey);
+    const previousValue = current[lastKey];
+    if (existed) {
+        delete current[lastKey];
+    }
+    return { previousValue, existed };
+}
+/**
+ * Deletes a key from the config file, allowing nested values via dot
+ * notation. Mirrors `setConfigValue`'s load/lock/write cycle.
+ *
+ * Does not call `output()`, so can be used as one step in a command without triggering `exit(0)` in
+ * the happy path. But note that `error()` will still `exit(1)` out of the process.
+ */
+function unsetConfigValue(cwd, keyPath) {
+    const configPath = node_path_1.default.join(planningDir(cwd), 'config.json');
+    return withPlanningLock(cwd, () => {
+        // Load existing config or start with empty object
+        let config = {};
+        try {
+            if (node_fs_1.default.existsSync(configPath)) {
+                config = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+            }
+        }
+        catch (err) {
+            error('Failed to read config.json: ' + err.message, ERROR_REASON.CONFIG_PARSE_FAILED);
+        }
+        const { previousValue, existed } = _unsetNestedValue(config, keyPath);
+        // Write back
+        try {
+            (0, shell_command_projection_cjs_1.platformWriteSync)(configPath, JSON.stringify(config, null, 2));
+            return { updated: existed, unset: true, key: keyPath, value: null, previousValue };
+        }
+        catch (err) {
+            error('Failed to write config.json: ' + err.message);
+        }
+    });
+}
 /**
  * Sets a value in the config file, allowing nested values via dot notation (e.g.,
  * "workflow.research").
@@ -531,6 +607,8 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
         parsedValue = true;
     else if (val === 'false')
         parsedValue = false;
+    else if (val === 'null')
+        parsedValue = null;
     // #1581: Number.isFinite (not !isNaN) so 'Infinity'/'-Infinity' are NOT
     // coerced to non-finite numbers that JSON.stringify later renders as `null`
     // (disk=null while the CLI echoed 'Infinity'). They fall through to the
@@ -544,6 +622,24 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
         }
         catch { /* keep as string */ }
     }
+    // #2046: a bare `null` unsets (deletes) the key — the documented "Clear" action.
+    // Short-circuits before every typed per-key validator so clearing a typed key
+    // (enum/boolean/number) removes it rather than being rejected. Deleting (not
+    // persisting JSON null) is the correct "clear": a persisted null is still a
+    // present, truthy-adjacent value that consumers must special-case — worst for
+    // secret keys where a leftover value can be passed as a real credential.
+    if (parsedValue === null) {
+        const unsetResult = unsetConfigValue(cwd, kp);
+        if ((0, secrets_cjs_1.isSecretKey)(kp)) {
+            const maskedPrev = unsetResult.previousValue === undefined
+                ? undefined
+                : (0, secrets_cjs_1.maskSecret)(unsetResult.previousValue);
+            output({ ...unsetResult, value: null, previousValue: maskedPrev, masked: true }, raw, `${kp} unset`);
+            return;
+        }
+        output(unsetResult, raw, `${kp} unset`);
+        return;
+    }
     // #1581: project_code is an identifier string — never number-coerce it. A
     // leading-zero code like '007' must persist verbatim (not collapse to 7).
     if (kp === 'project_code') {

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

@@ -176,7 +176,10 @@ function timeAgo(date) {
 function extractCanonicalPlanId(filename) {
     const base = filename.replace(/-PLAN\.md$/i, '').replace(/-SUMMARY\.md$/i, '').replace(/\.md$/i, '');
     const parts = base.split('-').filter(Boolean);
-    const tokenRe = /^\d+[A-Z]?(?:\.\d+)*$/i;
+    // #2043: a phase/plan token component is either a zero-padded number (≥2 digits)
+    // or a single-digit-plus-letter id ("3A"); a *bare* single digit is a slug word,
+    // so "46-6-rs-…" is not paired into a "46-6" id while "3A-01" stays intact.
+    const tokenRe = /^(?:\d{2,}[A-Z]?|\d[A-Z])(?:\.\d+)*$/i;
     const phaseIdx = parts.findIndex(p => tokenRe.test(p));
     if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && tokenRe.test(parts[phaseIdx + 1])) {
         return `${parts[phaseIdx]}-${parts[phaseIdx + 1]}`;