@opengsd/gsd-core 1.5.0-rc.2 → 1.5.0-rc.4

package/gsd-core/bin/lib/plan-drift-guard.cjs

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * ADR-22 Drift-Guard Decision Module
+ *
+ * Implements the authority ladder and severity classification table from
+ * ADR-22 (docs/adr/0022-source-grounding-drift-guard.md).
+ *
+ * Design constraints:
+ *   - Pure module: no I/O, no require() calls, no side effects.
+ *   - All inputs are validated; unknown values throw a TypeError.
+ *   - Consumed by the `gsd-tools drift-guard` CLI seam and by tests.
+ *
+ * Authority ladder (rung values determine MISSING severity):
+ *   grep=0  intel=1  treesitter=2  lsp=3  scip=4
+ *
+ * Hard-block threshold: rung >= 3 (lsp, scip) — these adapters can prove
+ * absence, so MISSING is a definite error (severity HIGH, hardBlock true).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTHORITY_RUNGS = void 0;
+exports.getEffectiveAuthority = getEffectiveAuthority;
+exports.classifyDriftSeverity = classifyDriftSeverity;
+/**
+ * Frozen map from authority name to its rung number.
+ *
+ * Rung determines whether a MISSING symbol triggers a hard block:
+ * rung >= 3 (lsp, scip) → hard block; rung < 3 → acknowledgement only.
+ */
+exports.AUTHORITY_RUNGS = Object.freeze({
+    grep: 0,
+    intel: 1,
+    treesitter: 2,
+    lsp: 3,
+    scip: 4,
+});
+/** Rung at which MISSING transitions to hard-block (inclusive). */
+const HARD_BLOCK_RUNG_THRESHOLD = 3;
+const VALID_AUTHORITIES = new Set(Object.keys(exports.AUTHORITY_RUNGS));
+const VALID_STATUSES = new Set(['VERIFIED', 'MISSING', 'AMBIGUOUS', 'UNCHECKABLE']);
+/**
+ * Validate and return an authority value, normalising undefined to 'grep'.
+ *
+ * Throws TypeError for any non-null unknown string value so callers surface
+ * configuration errors at call time rather than silently defaulting.
+ *
+ * @param value - raw authority string from config or CLI arg
+ * @returns a validated Authority value
+ */
+function validateAuthority(value) {
+    if (value === undefined || value === null || value === '') {
+        return 'grep';
+    }
+    if (!VALID_AUTHORITIES.has(value)) {
+        throw new TypeError(`Unknown authority: ${JSON.stringify(value)}. ` +
+            `Valid values: ${[...VALID_AUTHORITIES].join(', ')}`);
+    }
+    return value;
+}
+/**
+ * Return the effective authority after applying the ADR-22 auto-upgrade rule.
+ *
+ * Auto-upgrade rule: if the configured authority is 'grep' AND intel is
+ * enabled (`intelEnabled === true`), upgrade to 'intel'. All other authority
+ * values are returned unchanged regardless of intelEnabled.
+ *
+ * @param authority   - configured authority (undefined → 'grep')
+ * @param intelEnabled - whether the intel capability is active in this project
+ * @returns the effective Authority after upgrade
+ * @throws TypeError if authority is not one of the five valid values
+ */
+function getEffectiveAuthority(authority, intelEnabled) {
+    const validated = validateAuthority(authority);
+    if (validated === 'grep' && intelEnabled === true) {
+        return 'intel';
+    }
+    return validated;
+}
+/**
+ * Classify a symbol verification result into a drift severity and hard-block flag.
+ *
+ * ADR-22 decision table:
+ *
+ * | Status       | Authority rung | severity               | hardBlock |
+ * |------------- |--------------- |----------------------- |---------- |
+ * | VERIFIED     | any            | 'none'                 | false     |
+ * | MISSING      | rung >= 3      | 'HIGH'                 | true      |
+ * | MISSING      | rung 0-2       | 'needs-acknowledgement'| false     |
+ * | AMBIGUOUS    | any            | 'MEDIUM'               | false     |
+ * | UNCHECKABLE  | any            | 'INFO'                 | false     |
+ *
+ * @param opts.status    - verdict from the source-grounding adapter
+ * @param opts.authority - the effective authority adapter used
+ * @returns { severity, hardBlock }
+ * @throws TypeError for unknown status or authority values
+ */
+function classifyDriftSeverity({ status, authority, }) {
+    if (!VALID_STATUSES.has(status)) {
+        throw new TypeError(`Unknown status: ${JSON.stringify(status)}. ` +
+            `Valid values: ${[...VALID_STATUSES].join(', ')}`);
+    }
+    // authority validation (also catches unknown values)
+    const validatedAuthority = validateAuthority(authority);
+    const rung = exports.AUTHORITY_RUNGS[validatedAuthority];
+    switch (status) {
+        case 'VERIFIED':
+            return { severity: 'none', hardBlock: false };
+        case 'MISSING':
+            if (rung >= HARD_BLOCK_RUNG_THRESHOLD) {
+                return { severity: 'HIGH', hardBlock: true };
+            }
+            return { severity: 'needs-acknowledgement', hardBlock: false };
+        case 'AMBIGUOUS':
+            return { severity: 'MEDIUM', hardBlock: false };
+        case 'UNCHECKABLE':
+            return { severity: 'INFO', hardBlock: false };
+    }
+}

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

@@ -30,10 +30,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VALID_STATUS = void 0;
+exports.PROHIBITION_VALIDATORS = exports.VALID_STATUS = void 0;
 exports.validateRequirement = validateRequirement;
 exports.validateResolution = validateResolution;
 exports.analyzeCoverage = analyzeCoverage;
+exports.validateProhibitionResolution = validateProhibitionResolution;
+exports.projectProhibitions = projectProhibitions;
+exports.dispositionForProhibition = dispositionForProhibition;
 exports.runProbeCli = runProbeCli;
 const node_fs_1 = __importDefault(require("node:fs"));
 /** The LOCKED set of valid lifecycle statuses (the re-cut: no covered/backstop). */
@@ -203,6 +206,119 @@ function analyzeCoverage(items, resolutions = [], validators) {
     }
     return { items: merged, coverage: { applicable, resolved, unresolved, byVerification } };
 }
+/**
+ * The prohibition adapter's injected runtime validators (ADR-550 #5). There is no closed
+ * category taxonomy (recall is open-vocabulary values/safety/ethics prose), so `categories`
+ * is intentionally empty — `analyzeCoverage` is not the prohibition entry point and the
+ * round-trip schema layer does not gate on category. The verification tiers are
+ * `test | judgment` (ADR-550 D7a); both require only a present `resolution`/`reason` per their
+ * lifecycle (a resolved prohibition's checkable content is the `statement`, validated by the
+ * schema layer, not a `resolution` string), so `requiredFieldsByVerification` is the minimal
+ * fail-closed set: a dismissed item still needs its reason (enforced by `validateResolution`).
+ */
+exports.PROHIBITION_VALIDATORS = {
+    categories: [],
+    verification: ['test', 'judgment'],
+    // A resolved prohibition's checkable content is the `statement` (schema-layer validated), NOT a
+    // `resolution` string — the canonical fixtures and the reference doc's worked examples all carry
+    // `resolution: null`. So the per-tier required set is empty: `resolved` still requires a present
+    // verification tier (enforced in validateResolution) and `dismissed` still requires a reason
+    // (enforced unconditionally), but neither tier requires a `resolution`. This matches the corpus
+    // the docs-fixtures parity test pins; the validators.test.cjs regression keeps them aligned.
+    requiredFieldsByVerification: { test: [], judgment: [] },
+};
+/** Validate a prohibition resolution against the prohibition verification vocabulary. */
+function validateProhibitionResolution(resolution) {
+    return validateResolution(resolution, exports.PROHIBITION_VALIDATORS);
+}
+/**
+ * Deterministically project resolved prohibition items into the `must_haves.prohibitions:`
+ * list shape (the SPEC<->plan projection; ADR-550 Decision 5c). This is a FUNCTION the parity
+ * assertion round-trips, never a prompt: the same input always yields the same output, and the
+ * output is the exact re-readable block shape `parseMustHavesBlock(content, 'prohibitions')`
+ * returns — `{ statement, status, verification }` plus `reason` only when present (a dismissed
+ * item's audit trail). `resolution`/`requirement_id`/`category` are recall-stage bookkeeping
+ * and are intentionally NOT projected into the plan block (which is keyed on the must-NOT
+ * statement, not the source requirement). A non-array input projects to `[]` (fail-soft on the
+ * empty/zero-prohibition case), never a throw.
+ */
+function projectProhibitions(items) {
+    if (!Array.isArray(items))
+        return [];
+    const out = [];
+    for (const item of items) {
+        if (item == null || typeof item !== 'object')
+            continue;
+        const p = item;
+        const statement = typeof p.statement === 'string' ? p.statement : '';
+        const entry = {
+            statement,
+            status: typeof p.status === 'string' ? p.status : 'unresolved',
+        };
+        if (p.verification != null)
+            entry.verification = String(p.verification);
+        if (p.reason != null && String(p.reason).trim())
+            entry.reason = String(p.reason);
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Deterministic verify-time disposition for a single prohibition — the FAIL-CLOSED default
+ * (ADR-550 Decision 5d, the safety half of the 2026-06-12 "B-with-guard" maintainer decision).
+ *
+ * This is the cheap safety guarantee: a well-formed prohibition that reaches verify-phase with NO
+ * wired enforcement evidence can NEVER be a silent pass. It is `{ status: 'unverified', flagged:
+ * true }` — never `green` — exactly like an unresolved judgment item. The HEAVY half (a real
+ * fail-first negative-test enforcement mechanism that, given evidence, would flip a test-tier item
+ * to green) is OUT of #644 scope and defers to a follow-up PR: #644's corpus is entirely
+ * judgment-tier, so wiring a contrived test-tier consumer here would be the delete-bad-tests /
+ * gold-plating failure mode. Until that follow-up lands, ANY prohibition without enforcement
+ * evidence — test- or judgment-tier — disposes as flagged-unverified.
+ *
+ * The function is pure: same input always yields the same disposition (no LLM judgment, ADR-550
+ * D5). The LLM-judge soft-gate for judgment-tier items is a verify-phase PROSE concern (the
+ * verifier records a non-authoritative verdict + the unverified-prohibition flag); this helper
+ * only owns the deterministic fail-closed default that the plan-01-01 CI safety assertion pins.
+ */
+function dispositionForProhibition(prohibition, context = {}) {
+    const p = (prohibition ?? {});
+    const tier = p.verification === 'test' || p.verification === 'judgment' ? p.verification : null;
+    const evidence = Array.isArray(context.enforcementEvidence) ? context.enforcementEvidence : [];
+    const hasEnforcement = evidence.length > 0;
+    // FAIL CLOSED: no wired enforcement evidence -> flagged unverified, never green. This holds for
+    // every tier today (the real enforcement mechanism that could flip a test-tier item to green is
+    // deferred to a follow-up PR). The guard the safety assertion proves: an unwired item can never
+    // be silently skipped.
+    if (!hasEnforcement) {
+        return {
+            status: 'unverified',
+            flagged: true,
+            tier,
+            reason: tier === 'test'
+                ? 'test-tier prohibition has no wired enforcement evidence — flagged unverified (fail-closed; real negative-test enforcement deferred to a follow-up PR, ADR-550 D5d)'
+                : 'prohibition has no enforcement evidence — flagged unverified (fail-closed; never a silent pass, ADR-550 D5d)',
+        };
+    }
+    // D4 GUARD: a judgment-tier (or unknown-tier) prohibition is NEVER a silent green from this
+    // deterministic helper — it always routes to human/LLM judgment review (ADR-550 D4; verify-phase.md).
+    // Only a test-tier item with wired enforcement evidence may go green, and even that is the deferred
+    // heavy half until the real negative-test enforcement mechanism lands (no #644 caller passes evidence).
+    if (tier === 'test') {
+        return {
+            status: 'green',
+            flagged: false,
+            tier,
+            reason: 'test-tier prohibition has wired enforcement evidence',
+        };
+    }
+    return {
+        status: 'unverified',
+        flagged: true,
+        tier,
+        reason: 'judgment-tier prohibition routes to judgment review — never a silent green (ADR-550 D4)',
+    };
+}
 /**
  * Read the requirements file (and optional resolutions file), run the adapter's `analyze`,
  * and write the report as pretty JSON + newline. With no requirements path, writes the usage

package/gsd-core/bin/lib/profile-output.cjs

@@ -653,7 +653,21 @@ function cmdWriteProfile(cwd, options, raw) {
     }
     let outputPath = options.output;
     if (!outputPath) {
-        outputPath = node_path_1.default.join(node_os_1.default.homedir(), '.claude', 'gsd-core', 'USER-PROFILE.md');
+        // #1114: resolve the ACTIVE runtime's config home so the profile is written
+        // where the runtime's own workflows look for it. Previously this hardcoded the
+        // Claude home, so a Codex run wrote the profile under the Claude config dir
+        // while Codex advisor-mode (installed under the Codex home) checked the Codex
+        // dir and never found it. Mirrors cmdGenerateDevPreferences' runtime resolution.
+        let effectiveRuntime = 'claude';
+        try {
+            const config = loadConfig(cwd);
+            effectiveRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime'], 'claude') || 'claude';
+        }
+        catch {
+            effectiveRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], 'claude') || 'claude';
+        }
+        // path.join (not a string literal) keeps the cline-install leaked-path lint quiet.
+        outputPath = node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)(effectiveRuntime), 'gsd-core', 'USER-PROFILE.md');
     }
     else if (!node_path_1.default.isAbsolute(outputPath)) {
         outputPath = node_path_1.default.join(cwd, outputPath);
@@ -911,8 +925,10 @@ function cmdGenerateClaudeProfile(cwd, options, raw) {
         targetPath = node_path_1.default.isAbsolute(options.output) ? options.output : node_path_1.default.join(cwd, options.output);
     }
     else {
-        // Read claude_md_path from config, default to ./CLAUDE.md
-        let configClaudeMdPath = './CLAUDE.md';
+        // Read claude_md_path from config; #1098 default is ./.claude/CLAUDE.md
+        // (kept consistent with cmdGenerateClaudeMd so the profile section and the
+        // managed sections land in the same file on a config-less project).
+        let configClaudeMdPath = './.claude/CLAUDE.md';
         try {
             const config = loadConfig(cwd);
             if (config['claude_md_path'])
@@ -986,7 +1002,12 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
         }
     }
     let assemblyConfig = {};
-    let configClaudeMdPath = './CLAUDE.md';
+    // #1098: default the Claude-family instruction file to the project-scoped
+    // `.claude/CLAUDE.md` (a valid auto-loaded memory location) rather than a
+    // repo-root `CLAUDE.md`, so generated GSD content does not land next to — or
+    // pollute — a hand-crafted repo-root CLAUDE.md. An explicit `claude_md_path`
+    // config value or `--output` still wins.
+    let configClaudeMdPath = './.claude/CLAUDE.md';
     try {
         const config = loadConfig(cwd);
         if (config['claude_md_path'])
@@ -1037,6 +1058,26 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
         (0, shell_command_projection_cjs_1.platformEnsureDir)(node_path_1.default.dirname(outputPath));
         (0, shell_command_projection_cjs_1.platformWriteSync)(outputPath, existingContent);
     }
+    else if (!/<!-- GSD:[a-z]+-start/.test(existingContent) && !options.force) {
+        // #1098: the target instruction file already exists and contains NO GSD
+        // section markers — it is a hand-crafted CLAUDE.md/AGENTS.md, not a
+        // GSD-managed one. Do NOT clobber it with generated project documentation
+        // (broad project detail belongs in PROJECT.md / REQUIREMENTS.md, which GSD
+        // already owns). Leave the file untouched and report a skip; `--force`
+        // overwrites intentionally.
+        output({
+            claude_md_path: outputPath,
+            action: 'skipped',
+            reason: 'existing instruction file has no GSD markers (hand-crafted); not overwriting. Pass --force to overwrite.',
+            sections_generated: [],
+            sections_fallback: [],
+            sections_skipped: MANAGED_SECTIONS,
+            sections_total: MANAGED_SECTIONS.length,
+            profile_status: 'skipped',
+            message: `Left existing ${node_path_1.default.basename(outputPath)} untouched (no GSD markers found). Broad project context lives in PROJECT.md / REQUIREMENTS.md; pass --force to overwrite this file with GSD-managed sections.`,
+        }, raw, undefined);
+        return;
+    }
     else {
         action = 'updated';
         let fileContent = existingContent;

package/gsd-core/bin/lib/profile-pipeline-command-router.cjs

@@ -0,0 +1,138 @@
+'use strict';
+/**
+ * Profile-pipeline command router — CLI dispatcher for gsd-tools profiling commands.
+ *
+ * ADR-857 phase 6 / ADR-959: profile-pipeline capability command cutover.
+ * Extracted from hardcoded case arms in gsd-tools.cjs (lines 1324-1410).
+ * Dispatch path: default → dispatchCapabilityCommand →
+ *   require(profile-pipeline-command-router.cjs) → route<X>.
+ *
+ * Router signature: { args, cwd, raw, error } — identical to existing routers.
+ * Test seams: _pipeline / _output inject mock modules; _core injects mock core.
+ *
+ * Async note: cmdExtractMessages and cmdProfileSample are async functions.
+ * dispatchCapabilityCommand (gsd-tools.cjs:366-371) explicitly errors if a
+ * router returns a Promise. Therefore these router functions call the async
+ * function WITHOUT await and WITHOUT returning the Promise. The async functions
+ * end with output() or process.exit() so the process terminates correctly once
+ * the event loop drains. Unhandled rejections are caught by the .catch() wrapper
+ * to surface errors via the error() callback.
+ */
+const { ERROR_REASON } = require('./io.cjs');
+
+// ─── Pipeline phase commands ───────────────────────────────────────────────────
+
+function routeScanSessions({ args, cwd, raw, error, _pipeline }) {
+  void cwd; void error;
+  const p = _pipeline ?? require('./profile-pipeline.cjs');
+  const pathIdx = args.indexOf('--path');
+  const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
+  const verboseFlag = args.includes('--verbose');
+  const jsonFlag = args.includes('--json');
+  // cmdScanSessions is synchronous — call directly.
+  p.cmdScanSessions(sessionsPath, { verbose: verboseFlag, json: jsonFlag }, raw);
+}
+
+function routeExtractMessages({ args, cwd, raw, error, _pipeline }) {
+  const p = _pipeline ?? require('./profile-pipeline.cjs');
+  const sessionIdx = args.indexOf('--session');
+  const sessionId = sessionIdx !== -1 ? args[sessionIdx + 1] : null;
+  const limitIdx = args.indexOf('--limit');
+  const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : null;
+  const pathIdx = args.indexOf('--path');
+  const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
+  // args[0] = 'extract-messages' (family name), args[1] = project positional
+  const projectArg = args[1];
+  if (!projectArg || projectArg.startsWith('--')) {
+    error('Usage: gsd-tools extract-messages <project> [--session <id>] [--limit N] [--path <dir>]\nRun scan-sessions first to see available projects.', ERROR_REASON.USAGE);
+    return;
+  }
+  // cmdExtractMessages is async — do NOT return the Promise.
+  // The function ends with output() or process.exit(); the event loop will drain.
+  void cwd;
+  p.cmdExtractMessages(projectArg, { sessionId, limit }, raw, sessionsPath)
+    .catch(e => { error(e && e.message ? e.message : String(e)); });
+}
+
+function routeProfileSample({ args, cwd, raw, error, _pipeline }) {
+  void cwd; void error;
+  const p = _pipeline ?? require('./profile-pipeline.cjs');
+  const pathIdx = args.indexOf('--path');
+  const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
+  const limitIdx = args.indexOf('--limit');
+  const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : 150;
+  const maxPerIdx = args.indexOf('--max-per-project');
+  const maxPerProject = maxPerIdx !== -1 ? parseInt(args[maxPerIdx + 1], 10) : null;
+  const maxCharsIdx = args.indexOf('--max-chars');
+  const maxChars = maxCharsIdx !== -1 ? parseInt(args[maxCharsIdx + 1], 10) : 500;
+  // cmdProfileSample is async — do NOT return the Promise.
+  p.cmdProfileSample(sessionsPath, { limit, maxPerProject, maxChars }, raw)
+    .catch(e => { error(e && e.message ? e.message : String(e)); });
+}
+
+// ─── Output phase commands ─────────────────────────────────────────────────────
+
+function routeWriteProfile({ args, cwd, raw, error, _output }) {
+  const o = _output ?? require('./profile-output.cjs');
+  const inputIdx = args.indexOf('--input');
+  const inputPath = inputIdx !== -1 ? args[inputIdx + 1] : null;
+  if (!inputPath) {
+    error('--input <analysis-json-path> is required', ERROR_REASON.USAGE);
+    return;
+  }
+  const outputIdx = args.indexOf('--output');
+  const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+  o.cmdWriteProfile(cwd, { input: inputPath, output: outputPath }, raw);
+}
+
+function routeProfileQuestionnaire({ args, cwd, raw, error, _output }) {
+  void cwd; void error;
+  const o = _output ?? require('./profile-output.cjs');
+  const answersIdx = args.indexOf('--answers');
+  const answers = answersIdx !== -1 ? args[answersIdx + 1] : null;
+  o.cmdProfileQuestionnaire({ answers }, raw);
+}
+
+function routeGenerateDevPreferences({ args, cwd, raw, error, _output }) {
+  void error;
+  const o = _output ?? require('./profile-output.cjs');
+  const analysisIdx = args.indexOf('--analysis');
+  const analysisPath = analysisIdx !== -1 ? args[analysisIdx + 1] : null;
+  const outputIdx = args.indexOf('--output');
+  const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+  const stackIdx = args.indexOf('--stack');
+  const stack = stackIdx !== -1 ? args[stackIdx + 1] : null;
+  o.cmdGenerateDevPreferences(cwd, { analysis: analysisPath, output: outputPath, stack }, raw);
+}
+
+function routeGenerateClaudeProfile({ args, cwd, raw, error, _output }) {
+  void error;
+  const o = _output ?? require('./profile-output.cjs');
+  const analysisIdx = args.indexOf('--analysis');
+  const analysisPath = analysisIdx !== -1 ? args[analysisIdx + 1] : null;
+  const outputIdx = args.indexOf('--output');
+  const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+  const globalFlag = args.includes('--global');
+  o.cmdGenerateClaudeProfile(cwd, { analysis: analysisPath, output: outputPath, global: globalFlag }, raw);
+}
+
+function routeGenerateClaudeMd({ args, cwd, raw, error, _output }) {
+  void error;
+  const o = _output ?? require('./profile-output.cjs');
+  const outputIdx = args.indexOf('--output');
+  const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+  const autoFlag = args.includes('--auto');
+  const forceFlag = args.includes('--force');
+  o.cmdGenerateClaudeMd(cwd, { output: outputPath, auto: autoFlag, force: forceFlag }, raw);
+}
+
+module.exports = {
+  routeScanSessions,
+  routeExtractMessages,
+  routeProfileSample,
+  routeWriteProfile,
+  routeProfileQuestionnaire,
+  routeGenerateDevPreferences,
+  routeGenerateClaudeProfile,
+  routeGenerateClaudeMd,
+};

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

@@ -319,8 +319,17 @@ function stripFencedLines(text) {
 /**
  * Returns a filter function that checks whether a phase directory belongs
  * to the current milestone based on ROADMAP.md phase headings.
+ *
+ * @param cwd - Project working directory.
+ * @param versionOverride - Optional version string to scope the phase filter
+ *   to a specific milestone (e.g. 'v1.2').
+ * @param phaseIdConvention - The resolved `phase_id_convention` config value.
+ *   When `'milestone-prefixed'`, a deprecation warning is emitted for
+ *   free-form ROADMAPs that lack versioned milestone headings. When absent or
+ *   any other value, the warning is suppressed — legacy/default projects must
+ *   never see spurious warnings.
  */
-function getMilestonePhaseFilter(cwd, versionOverride) {
+function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
     const milestonePhaseNums = new Set();
     let missingExplicitVersion = false;
     try {
@@ -331,9 +340,10 @@ function getMilestonePhaseFilter(cwd, versionOverride) {
         let roadmap = extractCurrentMilestone(roadmapContent, cwd);
         const hasVersionedMilestonesGlobal = /^#{1,3}\s+.*v\d+\.\d+/mi.test(roadmapContent);
         const hasPhaseHeadings = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+[\w]/i.test(roadmapContent);
-        if (!hasVersionedMilestonesGlobal && hasPhaseHeadings) {
+        if (!hasVersionedMilestonesGlobal && hasPhaseHeadings && phaseIdConvention === 'milestone-prefixed') {
             console.warn('[gsd] Deprecated: free-form ROADMAP.md detected (no versioned milestone headings). ' +
-                'Set phase_id_convention in config.json to suppress this warning.');
+                'The project has phase_id_convention set to "milestone-prefixed" in config.json but the ' +
+                'ROADMAP does not use versioned milestone headings. Run `gsd-tools roadmap upgrade --convention milestone-prefixed` to migrate (dry-run by default).');
         }
         if (versionOverride) {
             const escapedVersion = escapeRegex(versionOverride);

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

@@ -11,6 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const core = require("./core.cjs");
 const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseMarkdownRegexSourceExact, output, error, findPhaseInternal, phaseTokenMatches } = core;
@@ -386,7 +387,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     }
     const isComplete = summaryCount >= planCount;
     const status = isComplete ? 'Complete' : summaryCount > 0 ? 'In Progress' : 'Planned';
-    const today = new Date().toISOString().split('T')[0];
+    const today = clock_cjs_1.realClock.today();
     if (!node_fs_1.default.existsSync(roadmapPath)) {
         output({ updated: false, reason: 'ROADMAP.md not found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
         return;
@@ -397,25 +398,37 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         const phasePattern = phaseMarkdownRegexSource(phaseNum);
         // Progress table row: update Plans/Status/Date columns (handles 4 or 5 column tables)
         const tableRowPattern = new RegExp(`^(\\|\\s*${phasePattern}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, 'im');
-        const dateField = isComplete ? ` ${today} ` : '  ';
         roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
             const cells = fullRow.split('|').slice(1, -1); // drop leading/trailing empty from split
+            const dateShape = /^\d{4}-\d{2}-\d{2}$/;
             if (cells.length === 5) {
                 // 5-col: Phase | Milestone | Plans | Status | Completed
                 cells[2] = ` ${summaryCount}/${planCount} `;
                 cells[3] = ` ${status.padEnd(11)}`;
-                cells[4] = dateField;
+                // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
+                const existingDate5 = cells[4].trim();
+                cells[4] = isComplete
+                    ? (dateShape.test(existingDate5) ? cells[4] : ` ${today} `)
+                    : '  ';
             }
             else if (cells.length === 4) {
                 // 4-col: Phase | Plans | Status | Completed
                 cells[1] = ` ${summaryCount}/${planCount} `;
                 cells[2] = ` ${status.padEnd(11)}`;
-                cells[3] = dateField;
+                // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
+                const existingDate4 = cells[3].trim();
+                cells[3] = isComplete
+                    ? (dateShape.test(existingDate4) ? cells[3] : ` ${today} `)
+                    : '  ';
             }
             return '|' + cells.join('|') + '|';
         });
-        // Update plan count in phase detail section
-        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`, 'i');
+        // Update plan count in phase detail section.
+        // Three recognised forms (all tolerated; canonical template uses the first):
+        //   `**Plans**: N plans`  — bold word + outer colon (gsd-core/templates/roadmap.md)
+        //   `**Plans:** N plans`  — bold "Plans:" (colon inside bold)
+        //   `Plans: N plans`      — plain text header
+        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)[^\\n]+`, 'i');
         const planCountText = isComplete
             ? `${summaryCount}/${planCount} plans complete`
             : `${summaryCount}/${planCount} plans executed`;
@@ -434,6 +447,80 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
             roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
         }
+        // Compute the active (post-</details>) region offset ONCE.  Both the
+        // missing-plan DETECTION and the row INSERTION must use the same active
+        // region string so that a plan row that exists only in an archived <details>
+        // block is not counted as "already present" in the active milestone section.
+        // (Finding 1 code-review: detection was previously running against the full
+        //  roadmapContent, causing archived rows to suppress active-section inserts.)
+        const lastDetailsClose = roadmapContent.lastIndexOf('</details>');
+        const activeRegion = lastDetailsClose === -1
+            ? roadmapContent
+            : roadmapContent.slice(lastDetailsClose + '</details>'.length);
+        // Compute which plan files are MISSING a checkbox row in the ACTIVE region.
+        // This handles three cases:
+        //   (a) Fresh template — no rows at all: all plans are missing.
+        //   (b) Partial gap — some rows exist, others don't: only the absent ones.
+        //   (c) All rows present — nothing to insert (idempotent).
+        //
+        // Detection is scoped to the active region so a plan that appears in an
+        // archived <details> block is still correctly detected as missing from the
+        // active milestone section.
+        const missingPlans = phaseInfo.plans.filter((planFile) => {
+            const planEscaped = escapeRegex(planFile);
+            return !new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${planEscaped}`, 'i').test(activeRegion);
+        });
+        if (missingPlans.length > 0) {
+            // Insert missing plan checklist rows (#1163).  We prefer to anchor to the
+            // bare `Plans:` checklist header (canonical template form) and fall back to
+            // the bold `**Plans**:`/`**Plans:**` summary line only when no bare header
+            // is present.  Using two separate patterns avoids the lazy-quantifier trap
+            // where a single alternation would stop at the first matching alternative
+            // (the bold summary) before reaching the checklist header.
+            //
+            // Canonical template (gsd-core/templates/roadmap.md) uses BOTH lines:
+            //   **Plans**: N plans   ← summary (colon outside bold)
+            //   Plans:               ← checklist header (PREFERRED insertion anchor)
+            // Rows must land after `Plans:`, not between the summary and the header.
+            //
+            // Pattern A: anchor to bare `Plans:` header (preferred).
+            // Pattern B: fallback to bold summary when no bare header exists.
+            const insertRowsPatternA = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
+            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
+            const sortedMissing = [...missingPlans].sort();
+            const newRows = sortedMissing.map(p => `- [ ] ${p}`).join('\n');
+            const inserter = (match) => `${match}\n${newRows}`;
+            // Scope insertion to the active (post-</details>) milestone region to
+            // prevent duplicate phase headings in archived sections from receiving rows.
+            // replaceInCurrentMilestone only accepts a string replacement, so we
+            // perform the scoped replace manually here (same strategy as that helper).
+            // Note: lastDetailsClose was computed above (shared with detection).
+            const scopedReplace = (src, pat) => src.replace(pat, inserter);
+            let withRows;
+            if (lastDetailsClose === -1) {
+                // activeRegion === roadmapContent when there are no </details> blocks.
+                const regionA = scopedReplace(activeRegion, insertRowsPatternA);
+                withRows = regionA !== activeRegion ? regionA : scopedReplace(activeRegion, insertRowsPatternB);
+            }
+            else {
+                const beforeDetails = roadmapContent.slice(0, lastDetailsClose + '</details>'.length);
+                const regionA = scopedReplace(activeRegion, insertRowsPatternA);
+                const afterWithRows = regionA !== activeRegion ? regionA : scopedReplace(activeRegion, insertRowsPatternB);
+                withRows = beforeDetails + afterWithRows;
+            }
+            if (withRows !== roadmapContent) {
+                roadmapContent = withRows;
+                // Mark any newly-inserted rows that already have summaries as complete
+                for (const summaryFile of phaseInfo.summaries) {
+                    const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+                    if (!planId)
+                        continue;
+                    const planEscaped = escapeRegex(planId);
+                    const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
+                    roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
+                }
+            }
+        }
         (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, roadmapContent);
     });
     output({
@@ -620,7 +707,10 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
             }
         }
         const newListBlock = annotatedLines.join('\n') + '\n';
-        const newPhaseSection = phaseSection.replace(plansBlockMatch[0], plansHeader + newListBlock);
+        // #1103: when `(?:^|\n)` consumed a leading `\n` (mid-string match), re-emit it
+        // so the line preceding the Plans: header is not fused onto it.
+        const leadingNewline = plansBlockMatch[0].startsWith('\n') ? '\n' : '';
+        const newPhaseSection = phaseSection.replace(plansBlockMatch[0], leadingNewline + plansHeader + newListBlock);
         const nextContent = content.slice(0, phaseStart) + newPhaseSection + content.slice(phaseEnd);
         if (nextContent === content)
             return;