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

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

@@ -12,6 +12,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 shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
@@ -144,6 +145,110 @@ function cmdListTodos(cwd, area, raw) {
     const result = { count, todos };
     output(result, raw, count.toString());
 }
+/**
+ * List captured seeds from .planning/seeds/SEED-*.md for browsing/audit (#441).
+ *
+ * Unlike audit.scanSeeds (which returns only *unimplemented* seeds for the
+ * milestone surface), this lists seeds of every status with the richer fields a
+ * human audit needs (scope, trigger, planted date). An optional case-insensitive
+ * status filter narrows the set. Seed content is user-controlled, so every
+ * displayed field is passed through sanitizeForDisplay and each file path is
+ * validated with requireSafePath before reading. Read-only — never mutates.
+ */
+/**
+ * Derive the canonical `{ seed_id, slug }` from a seed filename stem and the
+ * frontmatter `id:` value. Pure (no I/O) so it can be property-tested directly.
+ *
+ * seed_id: frontmatter `id:` when it matches `SEED-NNN`, else the numeric prefix
+ * of the filename (`SEED-NNN-…`), else the whole stem. slug: the descriptive
+ * remainder after `SEED-NNN-`, else the stem with a leading `SEED-` stripped.
+ * `rawFmId` is `unknown` because frontmatter values are not guaranteed strings.
+ */
+function deriveSeedIdentity(stem, rawFmId) {
+    const fmId = typeof rawFmId === 'string' ? rawFmId.trim() : '';
+    let seedId;
+    if (/^SEED-\d+$/i.test(fmId)) {
+        seedId = fmId;
+    }
+    else {
+        const numMatch = stem.match(/^(SEED-\d+)/i);
+        seedId = numMatch ? numMatch[1] : stem;
+    }
+    const slugMatch = stem.match(/^SEED-\d+-(.+)$/i);
+    const slug = slugMatch ? slugMatch[1] : stem.replace(/^SEED-/i, '');
+    return { seed_id: seedId, slug };
+}
+function cmdListSeeds(cwd, statusFilter, raw) {
+    const planDir = planningDir(cwd);
+    const seedsDir = node_path_1.default.join(planDir, 'seeds');
+    const wantStatus = statusFilter ? statusFilter.trim().toLowerCase() : null;
+    const seeds = [];
+    const summary = {};
+    // Frontmatter values are not guaranteed to be scalars: extractFrontmatter
+    // yields {} for a bare `key:` line and an array for `key: [a, b]`. Coerce every
+    // read to a string so one malformed seed cannot crash the whole audit list
+    // (`.toLowerCase()` on a non-string throws) or leak a raw object/array into the
+    // JSON contract. Mirrors the existing `typeof fm.id === 'string'` guard below.
+    const fmStr = (v) => (typeof v === 'string' ? v : '');
+    let files;
+    try {
+        files = node_fs_1.default.readdirSync(seedsDir, { withFileTypes: true });
+    }
+    catch {
+        // No seeds dir (or unreadable) — an empty, non-error result. The seed dir is
+        // created lazily by the first plant-seed, so absence is the normal zero case.
+        output({ count: 0, seeds: [], summary: {} }, raw, '0');
+        return;
+    }
+    for (const entry of files) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.startsWith('SEED-') || !entry.name.endsWith('.md'))
+            continue;
+        let safeFilePath;
+        try {
+            safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(seedsDir, entry.name), planDir, 'seed file', { allowAbsolute: true });
+        }
+        catch {
+            continue;
+        }
+        const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+        if (content === null)
+            continue;
+        const fm = extractFrontmatter(content);
+        const status = (fmStr(fm.status) || 'dormant').toLowerCase().trim() || 'dormant';
+        // Match on the raw lowercased status (both sides already normalized);
+        // sanitizeForDisplay is for output, not comparison.
+        if (wantStatus && status !== wantStatus)
+            continue;
+        // Canonical seed id is `SEED-NNN` (frontmatter `id:`, e.g. SEED-001). Fall
+        // back to the numeric prefix of the filename, then to the whole stem. The
+        // descriptive remainder of the filename (`SEED-NNN-<slug>.md`) is the slug.
+        const stem = node_path_1.default.basename(entry.name, '.md');
+        const { seed_id: seedId, slug } = deriveSeedIdentity(stem, fm.id);
+        let title = (0, security_cjs_1.sanitizeForDisplay)(fmStr(fm.title).slice(0, 100));
+        if (!title) {
+            const headingMatch = content.match(/^#\s*(.+)$/m);
+            if (headingMatch)
+                title = (0, security_cjs_1.sanitizeForDisplay)(headingMatch[1].trim().slice(0, 100));
+        }
+        const safeStatus = (0, security_cjs_1.sanitizeForDisplay)(status);
+        summary[safeStatus] = (summary[safeStatus] || 0) + 1;
+        seeds.push({
+            seed_id: (0, security_cjs_1.sanitizeForDisplay)(seedId),
+            slug: (0, security_cjs_1.sanitizeForDisplay)(slug),
+            status: safeStatus,
+            scope: (0, security_cjs_1.sanitizeForDisplay)(fmStr(fm.scope) || 'unknown'),
+            trigger_when: (0, security_cjs_1.sanitizeForDisplay)(fmStr(fm.trigger_when)),
+            planted: (0, security_cjs_1.sanitizeForDisplay)(fmStr(fm.planted)),
+            title,
+            path: toPosixPath(node_path_1.default.relative(cwd, safeFilePath)),
+        });
+    }
+    // Stable order: by seed_id so output is deterministic across filesystems.
+    seeds.sort((a, b) => a.seed_id.localeCompare(b.seed_id));
+    output({ count: seeds.length, seeds, summary }, raw, seeds.length.toString());
+}
 function cmdVerifyPathExists(cwd, targetPath, raw) {
     if (!targetPath) {
         error('path required for verification');
@@ -629,6 +734,145 @@ function cmdCommitToSubrepo(cwd, message, files, raw) {
     };
     output(result, raw, Object.entries(repos).map(([r, v]) => `${r}:${v.hash || 'skip'}`).join(' '));
 }
+/**
+ * Prepare a sub-repo for a companion PR branch.
+ *
+ * Detects uncommitted changes, creates a new branch, stages every changed
+ * file explicitly (never git add -A per universal-anti-patterns.md:44), commits,
+ * and pushes with --set-upstream. Returns a structured result the workflow uses
+ * to call `gh pr create`.
+ *
+ * On a stage/commit failure (nothing committed yet), the branch is deleted and
+ * the caller is returned to the original HEAD so the repo is left clean. On a
+ * push failure, the commit already exists — the branch is left in place instead
+ * so the user's work is not lost; the error includes a retry instruction.
+ */
+function cmdPrSubrepo(cwd, repo, branch, commitMessage, raw) {
+    if (!repo) {
+        error('--repo required');
+    }
+    if (!branch) {
+        error('--branch required');
+    }
+    if (!commitMessage || commitMessage.startsWith('--')) {
+        error('commit message required');
+    }
+    if (branch.startsWith('-')) {
+        error(`Branch name must not start with '-': ${branch}`);
+    }
+    // 0. Security: validate repo path is contained within the workspace root.
+    //    Uses security.cjs validatePath (symlink-safe realpathSync + startsWith guard)
+    //    to reject ../escape, absolute paths, and symlink traversal.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
+    const { validatePath } = require('./security.cjs');
+    const pathCheck = validatePath(repo, cwd);
+    if (!pathCheck.safe) {
+        error(`Sub-repo path is unsafe: ${pathCheck.error}`);
+    }
+    const repoCwd = pathCheck.resolved;
+    if (!node_fs_1.default.existsSync(repoCwd)) {
+        error(`Sub-repo not found: ${repoCwd}`);
+    }
+    // 1. Collect changed files via porcelain status — explicit, never git add -A.
+    //    ?? (untracked) lines are excluded — only stage tracked modifications.
+    const statusResult = (0, shell_command_projection_cjs_1.execGit)(['-c', 'core.quotePath=false', 'status', '--porcelain'], { cwd: repoCwd });
+    if (statusResult.exitCode !== 0) {
+        error(`git status failed in ${repo}: ${statusResult.stderr}`);
+    }
+    // Parse porcelain output into two lists:
+    //   changedFiles — all affected paths (old + new for renames) → goes into result.files
+    //   filesToStage — paths to pass to git add (rename old-paths are already staged by
+    //                  the rename op and no longer exist in the worktree; only add new paths)
+    const changedFiles = [];
+    const filesToStage = [];
+    for (const line of statusResult.stdout.split('\n').filter(Boolean).filter(l => !l.startsWith('??'))) {
+        // execGit trims the entire stdout string, which may strip the leading X-status
+        // space from the first output line. Normalize before slicing.
+        const normalized = line.trimStart();
+        const file = normalized.slice(2).trim();
+        const arrowIdx = file.indexOf(' -> ');
+        if (arrowIdx !== -1) {
+            const oldPath = file.slice(0, arrowIdx).trim();
+            const newPath = file.slice(arrowIdx + 4).trim();
+            changedFiles.push(oldPath, newPath);
+            filesToStage.push(newPath); // old path already staged; worktree no longer has it
+        }
+        else {
+            changedFiles.push(file);
+            filesToStage.push(file);
+        }
+    }
+    if (changedFiles.length === 0) {
+        output({ ok: true, repo, branch, committed: false, reason: 'nothing_to_commit', files: [] }, raw, 'nothing_to_commit');
+        return;
+    }
+    // 2. Guard: refuse if branch already exists — checkout -b is non-idempotent
+    const branchCheck = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--verify', branch], { cwd: repoCwd });
+    if (branchCheck.exitCode === 0) {
+        error(`Branch already exists in ${repo}: ${branch}. Delete it first or choose a unique name.`);
+    }
+    // Capture current HEAD before switching so rollback can return explicitly.
+    // git checkout - fails on a fresh single-branch repo with no prior HEAD.
+    const prevBranchResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoCwd });
+    const prevBranchName = prevBranchResult.exitCode === 0 ? prevBranchResult.stdout.trim() : null;
+    // 3. Create branch
+    const checkoutResult = (0, shell_command_projection_cjs_1.execGit)(['checkout', '-b', branch], { cwd: repoCwd });
+    if (checkoutResult.exitCode !== 0) {
+        error(`Failed to create branch ${branch} in ${repo}: ${checkoutResult.stderr}`);
+    }
+    // Helper: rollback the created branch and return to the previous HEAD.
+    const rollback = () => {
+        if (prevBranchName) {
+            (0, shell_command_projection_cjs_1.execGit)(['checkout', prevBranchName], { cwd: repoCwd });
+        }
+        (0, shell_command_projection_cjs_1.execGit)(['branch', '-D', branch], { cwd: repoCwd });
+    };
+    // 4. Stage explicit files (never git add -A per universal-anti-patterns.md:44)
+    for (const file of filesToStage) {
+        const addResult = (0, shell_command_projection_cjs_1.execGit)(['add', '--', file], { cwd: repoCwd });
+        if (addResult.exitCode !== 0) {
+            rollback();
+            error(`Failed to stage ${file} in ${repo}: ${addResult.stderr}`);
+        }
+    }
+    // 5. Commit
+    const commitResult = (0, shell_command_projection_cjs_1.execGit)(['commit', '-m', commitMessage], { cwd: repoCwd });
+    if (commitResult.exitCode !== 0) {
+        rollback();
+        error(`Failed to commit in ${repo}: ${commitResult.stderr}`);
+    }
+    // 6. Capture commit hash
+    const hashResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--short', 'HEAD'], { cwd: repoCwd });
+    const commitHash = hashResult.exitCode === 0 ? hashResult.stdout.trim() : null;
+    // 7. Capture remote URL and derive GitHub owner/repo slug for gh pr create
+    const remoteResult = (0, shell_command_projection_cjs_1.execGit)(['remote', 'get-url', 'origin'], { cwd: repoCwd });
+    const remoteUrl = remoteResult.exitCode === 0 ? remoteResult.stdout.trim() : null;
+    let remoteSlug = null;
+    if (remoteUrl) {
+        const m = remoteUrl.match(/github\.com[:/](.+?)(?:\.git)?$/);
+        remoteSlug = m ? m[1] : null;
+    }
+    // 8. Push with --set-upstream so gh pr create can find the branch.
+    //    Network operation — use a longer timeout than the default 10 s.
+    //    Do NOT rollback on push failure — the commit already exists on the local branch.
+    //    Deleting the branch here would destroy the only ref holding the user's work.
+    //    Leave the branch in place so the user can retry the push.
+    const pushResult = (0, shell_command_projection_cjs_1.execGit)(['push', '--set-upstream', 'origin', branch], { cwd: repoCwd, timeout: 60_000 });
+    if (pushResult.exitCode !== 0) {
+        error(`Failed to push ${branch} in ${repo}: ${pushResult.stderr}\nBranch ${branch} was created locally — retry with: git -C ${repo} push --set-upstream origin ${branch}`);
+    }
+    const result = {
+        ok: true,
+        repo,
+        branch,
+        committed: true,
+        files: changedFiles,
+        commit_hash: commitHash,
+        remote_url: remoteUrl,
+        remote_slug: remoteSlug,
+    };
+    output(result, raw, `${repo}@${commitHash ?? 'unknown'}`);
+}
 function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
     if (!summaryPath) {
         error('summary-path required for summary-extract');
@@ -1224,6 +1468,8 @@ module.exports = {
     cmdGenerateSlug,
     cmdCurrentTimestamp,
     cmdListTodos,
+    cmdListSeeds,
+    deriveSeedIdentity,
     cmdVerifyPathExists,
     cmdHistoryDigest,
     cmdResolveModel,
@@ -1232,6 +1478,7 @@ module.exports = {
     cmdEffortSync,
     cmdCommit,
     cmdCommitToSubrepo,
+    cmdPrSubrepo,
     cmdSummaryExtract,
     cmdWebsearch,
     cmdProgressRender,

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

@@ -135,6 +135,12 @@ function _deepMergeConfig(base, overlay) {
         return overlay;
     const result = { ...base };
     for (const key of Object.keys(overlay)) {
+        // Prototype-pollution guard — mirrors the four sibling guards in this file
+        // (lines ~315/319/331/341/549). Without it a workstream/root config.json with
+        // {"__proto__": {...}} pollutes this merged object's prototype chain and can
+        // spoof unset config flags. (Per-object pollution, not global Object.prototype.)
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            continue;
         if (overlay[key] !== null && typeof overlay[key] === 'object' && !Array.isArray(overlay[key])) {
             result[key] = _deepMergeConfig((base[key] ?? {}), overlay[key]);
         }

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

@@ -210,6 +210,7 @@ function buildNewProjectConfig(userChoices) {
             ui_safety_gate: true,
             ai_integration_phase: true,
             human_verify_mode: 'end-of-phase',
+            context_guard_mode: 'warn',
             text_mode: false,
             research_before_questions: false,
             discuss_mode: 'discuss',
@@ -556,6 +557,11 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
     if (kp === 'workflow.human_verify_mode' && !VALID_HUMAN_VERIFY_MODES.includes(String(parsedValue))) {
         error(`Invalid workflow.human_verify_mode '${val}'. Valid values: ${VALID_HUMAN_VERIFY_MODES.join(', ')}`);
     }
+    // Context exhaustion guard mode (#1452)
+    const VALID_CONTEXT_GUARD_MODES = ['auto', 'warn', 'off'];
+    if (kp === 'workflow.context_guard_mode' && !VALID_CONTEXT_GUARD_MODES.includes(String(parsedValue))) {
+        error(`Invalid workflow.context_guard_mode '${val}'. Valid values: ${VALID_CONTEXT_GUARD_MODES.join(', ')}`);
+    }
     // Context position enum validation (#2937)
     const VALID_CONTEXT_POSITIONS = ['front', 'end'];
     if (kp === 'statusline.context_position' && !VALID_CONTEXT_POSITIONS.includes(String(parsedValue))) {

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

@@ -56,10 +56,14 @@ function extractFrontmatter(content) {
     const frontmatter = {};
     // Match frontmatter only at byte 0 — a `---` block later in the document
     // body (YAML examples, horizontal rules) must never be treated as frontmatter.
-    const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
-    if (!match)
+    const headerEnd = content.startsWith('---\r\n') ? 5 : content.startsWith('---\n') ? 4 : -1;
+    if (headerEnd === -1)
         return frontmatter;
-    const yaml = match[1];
+    const closingLineStart = content.indexOf('\n---', headerEnd);
+    if (closingLineStart === -1)
+        return frontmatter;
+    const yamlEnd = content[closingLineStart - 1] === '\r' ? closingLineStart - 1 : closingLineStart;
+    const yaml = content.slice(headerEnd, yamlEnd);
     const lines = yaml.split(/\r?\n/);
     const stack = [{ obj: frontmatter, key: null, indent: -1 }];
     for (const line of lines) {

package/gsd-core/bin/lib/phase-id.cjs

@@ -14,10 +14,24 @@
 function escapeRegex(value) {
     return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+// project_code values start with an uppercase letter (e.g. PROJ, APP_CODE);
+// leading underscores are not valid project codes per .planning/config.json.
+const PROJECT_CODE_PREFIX_STRIP_RE = /^[A-Z][A-Z0-9_]*-(?=\d)/;
+const PROJECT_CODE_PREFIX_STRIP_RE_I = /^[A-Z][A-Z0-9_]*-(?=\d)/i;
+const PROJECT_CODE_PREFIX_CAPTURE_RE_I = /^([A-Z][A-Z0-9_]*)-(\d.*)/i;
+const OPTIONAL_PROJECT_CODE_PREFIX_SOURCE = '(?:[A-Z][A-Z0-9_]*-)?';
+function stripProjectCodePrefix(value, caseInsensitive = true) {
+    const input = String(value);
+    const re = caseInsensitive ? PROJECT_CODE_PREFIX_STRIP_RE_I : PROJECT_CODE_PREFIX_STRIP_RE;
+    return input.replace(re, '');
+}
+function hasProjectCodePrefix(value) {
+    return PROJECT_CODE_PREFIX_STRIP_RE_I.test(String(value));
+}
 function normalizePhaseName(phase) {
     const str = String(phase);
     // Strip optional project_code prefix (e.g., 'CK-01' → '01')
-    const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/, '');
+    const stripped = stripProjectCodePrefix(str, false);
     // Milestone-prefixed phase IDs: M-NN or M-N-N (deep decomposition).
     const milestoneMatch = stripped.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
     if (milestoneMatch) {
@@ -39,8 +53,7 @@ function normalizePhaseName(phase) {
     return str;
 }
 function getMilestoneFromPhaseId(phaseId) {
-    const str = String(phaseId);
-    const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const stripped = stripProjectCodePrefix(phaseId);
     const m = stripped.match(/^0*(\d+)-\d/);
     if (!m)
         return null;
@@ -50,8 +63,7 @@ function getMilestoneFromPhaseId(phaseId) {
     return `v${major}.0`;
 }
 function getPhaseDirFromPhaseId(phaseId, phaseName, projectCode) {
-    const str = String(phaseId);
-    const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const stripped = stripProjectCodePrefix(phaseId);
     const m = stripped.match(/^0*(\d+)-(0*(\d+(?:-\d+)*))$/);
     if (!m)
         return null;
@@ -70,7 +82,7 @@ function getPhaseDirFromPhaseId(phaseId, phaseName, projectCode) {
  * prose regardless of zero-padding on either side.
  */
 function phaseMarkdownRegexSource(phaseNum) {
-    const stripped = String(phaseNum).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const stripped = stripProjectCodePrefix(phaseNum);
     // Milestone-prefixed IDs: M-NN or M-N-N (deep).
     const milestoneSegments = stripped.match(/^(\d+)((?:-\d+)*)([A-Z]?(?:\.\d+)*)$/i);
     if (milestoneSegments && milestoneSegments[2]) {
@@ -99,14 +111,14 @@ function phaseMarkdownRegexSource(phaseNum) {
  */
 function phaseMarkdownRegexSourceExact(phaseNum) {
     const raw = String(phaseNum);
-    if (!/^[A-Z]{1,6}-(?=\d)/i.test(raw))
+    if (!hasProjectCodePrefix(raw))
         return null;
     return escapeRegex(raw);
 }
 function comparePhaseNum(a, b) {
     // Strip optional project_code prefix before comparing
-    const sa = String(a).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
-    const sb = String(b).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const sa = stripProjectCodePrefix(a);
+    const sb = stripProjectCodePrefix(b);
     const milestoneA = sa.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
     const milestoneB = sb.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
     if (milestoneA && milestoneB) {
@@ -162,7 +174,7 @@ function comparePhaseNum(a, b) {
  * Extract the phase token from a directory name.
  */
 function extractPhaseToken(dirName) {
-    const codePrefixMatch = dirName.match(/^([A-Z]{1,6})-(\d.*)/i);
+    const codePrefixMatch = dirName.match(PROJECT_CODE_PREFIX_CAPTURE_RE_I);
     let prefix = '';
     let rest = dirName;
     if (codePrefixMatch) {
@@ -192,7 +204,7 @@ function phaseTokenMatches(dirName, normalized) {
     const token = extractPhaseToken(dirName);
     if (token.toUpperCase() === normalized.toUpperCase())
         return true;
-    const stripped = dirName.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const stripped = stripProjectCodePrefix(dirName);
     if (stripped !== dirName) {
         const strippedToken = extractPhaseToken(stripped);
         if (strippedToken.toUpperCase() === normalized.toUpperCase())
@@ -202,6 +214,8 @@ function phaseTokenMatches(dirName, normalized) {
 }
 module.exports = {
     escapeRegex,
+    OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
+    stripProjectCodePrefix,
     normalizePhaseName,
     getMilestoneFromPhaseId,
     getPhaseDirFromPhaseId,

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

@@ -32,7 +32,7 @@ const coreUtilsMod = require("./core-utils.cjs");
 const { toPosixPath, generateSlugInternal, readSubdirectories } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, phaseTokenMatches } = phaseIdMod;
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, phaseTokenMatches, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal, getArchivedPhaseDirs } = phaseLocatorMod;
@@ -167,7 +167,7 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
             const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
             const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
             baseExists = dirs.some((d) => phaseTokenMatches(d, normalized));
-            const dirPattern = new RegExp(`^(?:[A-Z]{1,6}-)?${escapeRegex(normalized)}\\.(\\d+)`);
+            const dirPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${escapeRegex(normalized)}\\.(\\d+)`);
             for (const dir of dirs) {
                 const match = dir.match(dirPattern);
                 if (match)
@@ -310,7 +310,7 @@ function cmdFindPhase(cwd, phase, raw) {
             const match = dirs.find((d) => phaseTokenMatches(d, normalized));
             if (!match)
                 continue;
-            const dirMatch = match.match(/^(?:[A-Z]{1,6}-)(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i) ||
+            const dirMatch = match.match(new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+[A-Z]?(?:\\.\\d+)*)-?(.*)`, 'i')) ||
                 match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i);
             const phaseNumber = dirMatch ? dirMatch[1] : normalized;
             const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
@@ -756,7 +756,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         try {
             const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
             const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-            const decimalPattern = new RegExp(`^(?:[A-Z]{1,6}-)?${escapeRegex(normalizedBase)}\\.(\\d+)`);
+            const decimalPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${escapeRegex(normalizedBase)}\\.(\\d+)`);
             for (const dir of dirs) {
                 const dm = dir.match(decimalPattern);
                 if (dm)

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

@@ -288,6 +288,13 @@ function projectProhibitions(items) {
             if (typeof p.check_violation_fixture === 'string' && p.check_violation_fixture.trim() !== '') {
                 entry.check_violation_fixture = String(p.check_violation_fixture);
             }
+            // `check_clean_fixture` (#1346) rides BOTH kinds — the KNOWN-CLEAN control subject the prover
+            // requires to stay GREEN (content-dependence proof). Emit ONLY a non-empty fixture (blank ->
+            // absent so no control runs; the documented residual remains). Like the violation fixture it is
+            // meaningless without the descriptor, so it lives inside this well-formed-descriptor branch.
+            if (typeof p.check_clean_fixture === 'string' && p.check_clean_fixture.trim() !== '') {
+                entry.check_clean_fixture = String(p.check_clean_fixture);
+            }
         }
         out.push(entry);
     }

package/gsd-core/bin/lib/prohibition-enforcement.cjs

@@ -79,8 +79,9 @@ const probe_core_cjs_1 = require("./probe-core.cjs");
  *   - `null`/`undefined`/non-object input -> `null`.
  *   - `check_kind` ABSENT -> `null` (no descriptor -> producer locates nothing -> fail-closed).
  *   - `check_kind` present -> `{ kind: check_kind, target: check_target }`, adding `rule: check_rule`
- *     ONLY when `check_rule` is a non-empty string, and `violationFixture: check_violation_fixture`
- *     ONLY when that scalar is a non-empty string (#1346 — composes #1278 locate with #1279 proof).
+ *     ONLY when `check_rule` is a non-empty string, `violationFixture: check_violation_fixture`
+ *     ONLY when that scalar is a non-empty string (composes #1278 locate with #1279 proof), and
+ *     `cleanFixture: check_clean_fixture` ONLY when that scalar is non-empty (#1346 causation control).
  *   - `failFirst` is NEVER sourced from the projection — it stays a verify-time caller attestation
  *     (#1279 machine-proves it; out of scope here). The returned descriptor carries no `failFirst`.
  *   - The adapter does NOT strictly validate kind/target/rule: it faithfully reconstructs whatever
@@ -118,6 +119,13 @@ function descriptorFromProjection(projected) {
     const fixture = scalar(projected.check_violation_fixture);
     if (fixture.trim().length > 0)
         descriptor.violationFixture = fixture;
+    // `cleanFixture` (#1346) rides BOTH kinds — reconstruct it from `check_clean_fixture` so the
+    // causation control runs end-to-end: when present the prover also requires the check to stay GREEN
+    // against this known-clean subject (proving the violation RED is content-dependent). Absent/blank ->
+    // no control (the documented residual remains; backward-compatible with the #1314 compose path).
+    const clean = scalar(projected.check_clean_fixture);
+    if (clean.trim().length > 0)
+        descriptor.cleanFixture = clean;
     return descriptor;
 }
 /** node --test argv. Forces the TAP reporter so the summary counts are parseable + version-stable;
@@ -360,6 +368,31 @@ const CHECK_MAX_BUFFER = 16 * 1024 * 1024;
 function posTimeout(timeoutMs, def) {
     return typeof timeoutMs === 'number' && timeoutMs > 0 ? timeoutMs : def;
 }
+/**
+ * Spawn the negative `node --test` against a single subject (set via the `GSD_PROHIB_SUBJECT`
+ * convention, #1279) and return its TAP output. Reuses the bounded-subprocess machinery
+ * (`process.execPath`, arg arrays → no shell, `childEnv`, bounded `timeout`/`maxBuffer`) and NEVER
+ * throws — a RED run exits non-zero, so the partial TAP (with the `# fail` summary) is recovered from
+ * the thrown error's `stdout`. The prover calls this once per subject: the KNOWN-BAD violation fixture
+ * (expect RED) and, for the #1346 causation control, the KNOWN-CLEAN control subject (expect GREEN).
+ */
+function runNodeTestWithSubject(check, cwd, subject, timeoutMs) {
+    try {
+        return (0, node_child_process_1.execFileSync)(process.execPath, buildNodeTestArgs(check), {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            env: { ...childEnv(), GSD_PROHIB_SUBJECT: subject },
+            timeout: posTimeout(timeoutMs, NODE_TEST_TIMEOUT_MS),
+            maxBuffer: CHECK_MAX_BUFFER,
+        });
+    }
+    catch (e) {
+        const stdout = e && typeof e === 'object' && 'stdout' in e ? e.stdout : '';
+        return typeof stdout === 'string' ? stdout : '';
+    }
+}
 function defaultRunCheck(check, cwd, timeoutMs) {
     try {
         if (check.kind === 'node-test') {
@@ -482,36 +515,36 @@ function defaultProveFailFirst(check, cwd, timeoutMs) {
             // a setup crash, not from the prohibition firing. Requiring the fixture to exist before spawning
             // closes the realistic typo/stale-path case (#1279 review, Major 1).
             //
-            // KNOWN RESIDUAL (documented, fail-open direction, tracked follow-up #1346): existence is
-            // necessary but not sufficient — a deliberately deceptive negative test that reds merely BECAUSE
-            // `GSD_PROHIB_SUBJECT` is set (rather than because the subject's CONTENT violates the must-NOT)
-            // is still accepted. Proving "the red was CAUSED BY the violation" cannot be done generically for
-            // an arbitrary author-supplied test, so it is recorded as a constraint, not silently implied-solved.
+            // CAUSATION (#1346): existence + a non-vacuous red is necessary but not sufficient — a deceptive
+            // negative test that reds merely BECAUSE `GSD_PROHIB_SUBJECT` is set (rather than because the
+            // subject's CONTENT violates the must-NOT) would otherwise be accepted. The OPTIONAL `cleanFixture`
+            // control below proves content-dependence when supplied (red on bad AND green on clean). When NO
+            // clean fixture is authored the control cannot run, so the residual remains a documented constraint
+            // for that case (an author opts into the stronger proof by supplying a known-clean control subject).
             // Resolve the fixture against `cwd` (NOT the verify process's cwd): the spawned test reads
             // `GSD_PROHIB_SUBJECT` and resolves a relative subject against `cwd`, so the existence check must
             // use the SAME base or it could pass here yet ENOENT in the child (re-opening the fail-open hole).
             if (!fixture || !node_fs_1.default.existsSync(node_path_1.default.resolve(cwd, fixture)))
                 return { provenFailFirst: false };
-            let out = '';
-            try {
-                out = (0, node_child_process_1.execFileSync)(process.execPath, buildNodeTestArgs(check), {
-                    cwd,
-                    encoding: 'utf-8',
-                    stdio: ['ignore', 'pipe', 'pipe'],
-                    windowsHide: true,
-                    // CONVENTION (#1279): the negative test reads its subject-under-test from this env var.
-                    env: { ...childEnv(), GSD_PROHIB_SUBJECT: fixture },
-                    timeout: posTimeout(timeoutMs, NODE_TEST_TIMEOUT_MS),
-                    maxBuffer: CHECK_MAX_BUFFER,
-                });
-            }
-            catch (e) {
-                // A negative test that goes RED exits non-zero; the partial TAP (with the `# fail` summary)
-                // is on stdout. Parse what we have: a real failure here is the PROOF the test is fail-first.
-                const stdout = e && typeof e === 'object' && 'stdout' in e ? e.stdout : '';
-                out = typeof stdout === 'string' ? stdout : '';
+            // Run the negative test against the KNOWN-BAD subject and require a NON-VACUOUS red.
+            const redOut = runNodeTestWithSubject(check, cwd, fixture, timeoutMs);
+            if (!isNonVacuousNodeTestRed(redOut, check.target))
+                return { provenFailFirst: false, method: 'violation-fixture' };
+            // #1346 CAUSATION CONTROL (optional): if a clean control subject is supplied, run the SAME test
+            // against it and require it to stay GREEN. This proves the red above was caused by the subject's
+            // CONTENT — a deceptive test that reds merely because GSD_PROHIB_SUBJECT is SET reds here too →
+            // not content-dependent → not proven. Absent → no control (documented residual; backward-compat).
+            const clean = check.cleanFixture;
+            if (clean) {
+                // A supplied-but-missing/typo'd control path can't run the control → fail-closed, symmetric
+                // with the violation-fixture existence guard (resolve against the SAME `cwd` as the child).
+                if (!node_fs_1.default.existsSync(node_path_1.default.resolve(cwd, clean)))
+                    return { provenFailFirst: false, method: 'violation-fixture' };
+                const cleanOut = runNodeTestWithSubject(check, cwd, clean, timeoutMs);
+                if (!isNonVacuousNodeTestPass(cleanOut, check.target))
+                    return { provenFailFirst: false, method: 'violation-fixture' };
             }
-            return { provenFailFirst: isNonVacuousNodeTestRed(out, check.target), method: 'violation-fixture' };
+            return { provenFailFirst: true, method: 'violation-fixture' };
         }
         // Unknown kind — defensive; the LOCATE guard already rejects it.
         return { provenFailFirst: false };

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

@@ -150,10 +150,23 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
             },
             'upgrade': () => {
                 const dryRun = !args.includes('--apply');
-                const convention = args.find((_a, i) => args[i - 1] === '--convention') || 'milestone-prefixed';
+                // Parse `--convention <value>` and `--convention=<value>`. When the flag is
+                // absent entirely, default to the only supported convention; when present
+                // with a missing/unsupported value, fall through to the rejection below
+                // (fail-closed — never silently run a migration the user did not request).
+                let convention = 'milestone-prefixed';
+                const conventionFlagIdx = args.findIndex((a) => a === '--convention' || a.startsWith('--convention='));
+                if (conventionFlagIdx !== -1) {
+                    const token = args[conventionFlagIdx];
+                    convention = token.includes('=')
+                        ? token.slice(token.indexOf('=') + 1)
+                        : (args[conventionFlagIdx + 1] ?? '');
+                }
                 if (convention !== 'milestone-prefixed') {
-                    process.stderr.write('Only --convention milestone-prefixed is supported\n');
-                    process.exit(1);
+                    // No-throw hub contract (ADR-0012): a hub-dispatched handler must not call
+                    // process.exit. Throw instead — the hub converts this to HandlerFailure and
+                    // the adapter routes it through the injected error() boundary.
+                    throw new Error('Only --convention milestone-prefixed is supported');
                 }
                 const plan = roadmapUpgrade.computeMigrationPlan(cwd);
                 roadmapUpgrade.applyMigration(cwd, plan, { dryRun });