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

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -510,13 +510,49 @@ function normalizeContent(filePath, content, opts = {}) {
     }
     return { content: normalized, encoding };
 }
+// Rename errnos that are transient on Windows: a concurrent reader (or an AV
+// scanner / indexer) holding the target open makes renameSync fail briefly.
+// Same idiom as capability-ledger.cts / capability-consent.cts.
+const RENAME_RETRY_ERRNOS = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_MAX_ATTEMPTS = 3;
+const RENAME_RETRY_BACKOFF_MS = 50;
+/** Synchronous best-effort backoff sleep (Atomics.wait — same idiom as io.cts). */
+let _renameSleepBuf = null;
+function renameBackoff() {
+    if (_renameSleepBuf === null)
+        _renameSleepBuf = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(_renameSleepBuf, 0, 0, RENAME_RETRY_BACKOFF_MS);
+}
+/**
+ * Atomic publish with bounded retry on transient Windows lock errnos.
+ * Returns null on success, or the final error if every attempt failed.
+ */
+function atomicRenameWithRetry(tmpPath, filePath) {
+    let renameErr = null;
+    for (let attempt = 1; attempt <= RENAME_MAX_ATTEMPTS; attempt++) {
+        try {
+            node_fs_1.default.renameSync(tmpPath, filePath);
+            return null;
+        }
+        catch (err) {
+            renameErr = err;
+            if (attempt < RENAME_MAX_ATTEMPTS && RENAME_RETRY_ERRNOS.has(renameErr.code ?? '')) {
+                renameBackoff();
+                continue;
+            }
+            break;
+        }
+    }
+    return renameErr;
+}
 function platformWriteSync(filePath, content, opts = {}) {
     const { content: normalized, encoding } = normalizeContent(filePath, content, opts);
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
     const tmpPath = filePath + '.tmp.' + process.pid;
+    // Step 1: write the sibling tmp file. If THIS fails, nothing was published, so a
+    // direct fallback write cannot truncate a concurrent reader of an existing file.
     try {
         node_fs_1.default.writeFileSync(tmpPath, normalized, encoding);
-        node_fs_1.default.renameSync(tmpPath, filePath);
     }
     catch {
         try {
@@ -524,7 +560,25 @@ function platformWriteSync(filePath, content, opts = {}) {
         }
         catch { /* already gone */ }
         node_fs_1.default.writeFileSync(filePath, normalized, encoding);
+        return;
+    }
+    // Step 2: atomic publish, retrying transient Windows locks.
+    const renameErr = atomicRenameWithRetry(tmpPath, filePath);
+    if (renameErr === null)
+        return;
+    try {
+        node_fs_1.default.unlinkSync(tmpPath);
+    }
+    catch { /* already gone */ }
+    if (RENAME_RETRY_ERRNOS.has(renameErr.code ?? '')) {
+        // A live reader still holds the target open after every retry. A non-atomic
+        // direct write here would truncate that reader (the exact corruption this seam
+        // exists to prevent), so surface the error instead of falling back.
+        throw renameErr;
     }
+    // Atomic publish is genuinely impossible here (e.g. EXDEV cross-device move):
+    // fall back to a direct write to preserve write availability.
+    node_fs_1.default.writeFileSync(filePath, normalized, encoding);
 }
 function platformReadSync(filePath, opts = {}) {
     const encoding = opts.encoding ?? 'utf-8';

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

@@ -33,7 +33,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const node_os_1 = __importDefault(require("node:os"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
@@ -41,7 +40,9 @@ const { readActiveProfile, resolveProfile, loadSkillsManifest, } = installProfil
 const clusters_cjs_1 = require("./clusters.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
-const { findInstallSourceRoot, getInstallExports } = runtimeArtifactLayout;
+const { findInstallSourceRoot } = runtimeArtifactLayout;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
 const SURFACE_FILE_NAME = '.gsd-surface.json';
 /**
  * Read the surface state from a runtime config directory.
@@ -265,26 +266,18 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry)
     const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap, registry);
     // Mirror installRuntimeArtifacts: skills kinds get per-runtime path rewrites
     // so SKILL.md bodies reference the install target (pathPrefix), not the
-    // converter's default ~/.claude paths (#813). Computed lazily so command-only
-    // runtimes do not trigger the install.js require.
-    let pathPrefix = null;
+    // converter's default ~/.claude paths (#813). Delegated to the conversion
+    // module's deep seam (ADR-1508 / #1511 Phase 2) — no attribution resolver
+    // needed here (proven: Co-Authored-By never appears in staged content; see
+    // brief PROVEN KEY FACT). No getInstallExports() call required.
     for (const kind of layout.kinds) {
         const staged = kind.stage(resolved);
         if (kind.kind === 'skills') {
-            const installExports = getInstallExports();
-            if (pathPrefix === null) {
-                const scope = layout.scope ?? 'global';
-                const resolvedTarget = node_path_1.default.resolve(layout.configDir).replace(/\\/g, '/');
-                const homeDir = node_os_1.default.homedir().replace(/\\/g, '/');
-                pathPrefix = installExports.computePathPrefix({
-                    isGlobal: scope === 'global',
-                    isOpencode: layout.runtime === 'opencode',
-                    isWindowsHost: process.platform === 'win32',
-                    resolvedTarget,
-                    homeDir,
-                });
-            }
-            installExports.applyRuntimeContentRewritesInPlace(staged, layout.runtime, pathPrefix);
+            runtimeArtifactConversion.rewriteStagedSkillBodies(staged, {
+                runtime: layout.runtime,
+                configDir: layout.configDir,
+                scope: layout.scope ?? 'global',
+            });
         }
         const dest = node_path_1.default.join(layout.configDir, kind.destSubpath);
         _syncGsdDir(staged, dest, kind, skillManifest);

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

@@ -37,14 +37,17 @@ exports.canonicalPlanStem = canonicalPlanStem;
 exports.phaseVariants = phaseVariants;
 exports.buildRoadmapPhaseVariants = buildRoadmapPhaseVariants;
 exports.buildNotStartedPhaseVariants = buildNotStartedPhaseVariants;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE } = phaseIdMod;
 // ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
 // Matches legacy numeric dirs (01-setup), milestone-prefixed dirs (02-01-setup),
 // deep dirs (02-04-01-deep), and project-code-prefixed variants (GSD-02-01-setup).
-exports.phaseDirNameRe = /^(?:[A-Z]{1,6}-)?\d{2,}(?:-\d+)*(?:\.\d+)*-[\w-]+$/i;
+exports.phaseDirNameRe = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}\\d{2,}(?:-\\d+)*(?:\\.\\d+)*-[\\w-]+$`, 'i');
 // Extracts the full phase token from a directory name, including milestone-prefixed
 // multi-segment tokens like "02-01" from "02-01-setup" or "GSD-02-01-setup".
 // Greedily captures all leading all-digit segments before the first letter-start segment.
-exports.PHASE_TOKEN_FROM_DIR_RE = /^(?:[A-Z]{1,6}-)?(\d+(?:-\d+)*[A-Z]?(?:\.\d+)*)(?:-[a-z]|$)/i;
+exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+(?:-\\d+)*[A-Z]?(?:\\.\\d+)*)(?:-[a-z]|$)`, 'i');
 exports.MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
 // ── Issue #26: I001 canonicalization ────────────────────────────────────────
 function canonicalPlanStem(stem) {

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

@@ -1887,8 +1887,17 @@ function cmdVerifyCodebaseDrift(cwd, raw) {
             else if (status === 'D')
                 deleted.push(file);
         }
-        const config = loadConfig(cwd);
-        const wf = config?.workflow;
+        // loadConfig() returns a flattened object — there is no nested `workflow`
+        // key. Read the raw config.json directly to access workflow-scoped keys,
+        // matching the pattern used in check-command-router.cts:readWorkflowConfig.
+        let wf;
+        try {
+            const rawCfg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'config.json'), 'utf-8'));
+            wf = rawCfg['workflow'];
+        }
+        catch {
+            wf = undefined;
+        }
         const threshold = Number.isInteger(wf?.drift_threshold) && wf?.drift_threshold >= 1
             ? wf?.drift_threshold
             : 3;

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -693,6 +693,206 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
         process.exitCode = 1;
     }
 }
+/**
+ * Pure planner for the per-agent wave-manifest append.
+ *
+ * Validates the candidate entry at write time using the SAME rules the
+ * cleanup-wave reader enforces (via `normalizeCleanupManifestEntry`), so an
+ * entry that `record-agent` accepts is guaranteed to survive
+ * `normalizeCleanupManifest` on read — a field that would be silently dropped
+ * at cleanup time fails loudly here instead.
+ *
+ * `agent_id` is treated write-strict (required) even though the reader is
+ * lenient (nullable): the whole point of this verb is to catch an
+ * under-populated entry at write time, and an entry whose author cannot be
+ * identified defeats that. A duplicate `(worktree_path, branch)` is also
+ * rejected loudly — the reader dedups on that key, so a re-record would be
+ * silently dropped (the failure mode this verb exists to eliminate). The
+ * on-disk shape stays the existing 4-field entry (`agent_id`, `worktree_path`,
+ * `branch`, `expected_base`) — no schema change; the reader re-derives
+ * `allowed_bases`.
+ */
+function planWorktreeRecordAgent(manifestRaw, fields) {
+    // 1. Write-strict required-field check (loud, with which flag is missing).
+    //    Trim first so a whitespace-only value ("   ") is rejected here rather
+    //    than deferred to a guaranteed `git worktree remove` failure at cleanup.
+    const agentId = (fields.agentId || '').trim();
+    const worktreePath = (fields.worktreePath || '').trim();
+    const branch = (fields.branch || '').trim();
+    const base = (fields.base || '').trim();
+    const missing = [];
+    if (!agentId)
+        missing.push('--agent-id');
+    if (!worktreePath)
+        missing.push('--path');
+    if (!branch)
+        missing.push('--branch');
+    if (!base)
+        missing.push('--base');
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            reason: 'missing_field',
+            hint: `record-agent requires ${missing.join(', ')}. Re-run with all of --agent-id, --path, --branch, --base set to non-empty (non-whitespace) values.`,
+            entry: null,
+            manifest: null,
+        };
+    }
+    // 2. Shared validation: run the candidate through the reader's normalizer.
+    //    If it returns null the reader would drop this entry on read — reject now.
+    const candidate = {
+        agent_id: agentId,
+        worktree_path: worktreePath,
+        branch,
+        expected_base: base,
+    };
+    const entry = normalizeCleanupManifestEntry(candidate);
+    if (!entry) {
+        return {
+            ok: false,
+            reason: 'invalid_entry',
+            hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ^worktree-agent-[A-Za-z0-9._/-]+$ (got branch="${branch}"). Fix the field and re-run.`,
+            entry: null,
+            manifest: null,
+        };
+    }
+    // 3. Parse the existing manifest. The init shell ({orchestrator_root, worktrees: []})
+    //    is written inline by the orchestrator before any agent spawns; a missing or
+    //    malformed manifest is a loud failure here, not a silent under-populated write.
+    let parsed;
+    try {
+        parsed = JSON.parse(manifestRaw);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'invalid_manifest_json',
+            hint: 'Manifest is not valid JSON. The orchestrator must initialize it as {"orchestrator_root": "...", "worktrees": []} before recording agents.',
+            entry: null,
+            manifest: null,
+        };
+    }
+    // Accept the canonical {worktrees: []} shell or a bare top-level array (both
+    // are read by normalizeCleanupManifest); preserve any other top-level keys.
+    let worktrees;
+    let writeBack;
+    if (Array.isArray(parsed)) {
+        worktrees = parsed;
+        writeBack = worktrees;
+    }
+    else if (parsed && typeof parsed === 'object') {
+        const container = parsed;
+        if (container.worktrees === undefined)
+            container.worktrees = [];
+        if (!Array.isArray(container.worktrees)) {
+            return {
+                ok: false,
+                reason: 'manifest_shape_invalid',
+                hint: 'Manifest "worktrees" must be an array. Re-initialize as {"orchestrator_root": "...", "worktrees": []}.',
+                entry: null,
+                manifest: null,
+            };
+        }
+        worktrees = container.worktrees;
+        writeBack = container;
+    }
+    else {
+        return {
+            ok: false,
+            reason: 'manifest_shape_invalid',
+            hint: 'Manifest must be a JSON object {"worktrees": []} or a top-level array.',
+            entry: null,
+            manifest: null,
+        };
+    }
+    // 4. Reject a duplicate (worktree_path, branch). The reader dedups on this
+    //    exact key, but only over entries that NORMALIZE successfully — so an
+    //    existing malformed same-key entry (which the reader would drop) must NOT
+    //    block recording a valid one. Run each existing entry through the reader's
+    //    own normalizer and compare only the entries the reader would keep; this
+    //    matches its dedup behavior exactly. A real duplicate signals an upstream
+    //    double-spawn — surface it loudly instead of silently dropping it.
+    const dupKey = `${entry.worktree_path}\0${entry.branch}`;
+    const isDuplicate = worktrees.some((existing) => {
+        const normalized = normalizeCleanupManifestEntry(existing);
+        return normalized !== null && `${normalized.worktree_path}\0${normalized.branch}` === dupKey;
+    });
+    if (isDuplicate) {
+        return {
+            ok: false,
+            reason: 'duplicate_entry',
+            hint: `The manifest already records worktree_path="${entry.worktree_path}" branch="${entry.branch}". The cleanup reader dedups on (worktree_path, branch), so re-recording would be silently dropped — this usually signals an upstream double-spawn. Investigate rather than re-record.`,
+            entry: null,
+            manifest: null,
+        };
+    }
+    // 5. Append the minimal 4-field entry, matching the existing on-disk format.
+    const recorded = {
+        agent_id: entry.agent_id,
+        worktree_path: entry.worktree_path,
+        branch: entry.branch,
+        expected_base: entry.expected_base,
+    };
+    worktrees.push(recorded);
+    return {
+        ok: true,
+        reason: 'ok',
+        entry: recorded,
+        manifest: `${JSON.stringify(writeBack, null, 2)}\n`,
+    };
+}
+/**
+ * CLI command: append a validated per-agent entry to a wave cleanup manifest.
+ *
+ * Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha>
+ *
+ * Fails loudly (non-zero exit + recovery hint on stderr) when a field is
+ * missing/garbled or the manifest is absent/malformed, rather than appending an
+ * under-populated entry that the cleanup reader would silently drop.
+ */
+function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
+    const flag = (name) => {
+        const i = args.indexOf(name);
+        return i >= 0 && i + 1 < args.length ? args[i + 1] : '';
+    };
+    const write = deps.write || ((s) => process.stdout.write(s));
+    const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
+    const manifestPath = flag('--manifest');
+    if (!manifestPath) {
+        writeErr('Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha>\n');
+        process.exitCode = 2;
+        return { ok: false, reason: 'usage', entry: null };
+    }
+    const resolved = node_path_1.default.resolve(cwd, manifestPath);
+    const readFile = deps.readFile || ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
+    let manifestRaw;
+    try {
+        manifestRaw = readFile(resolved);
+    }
+    catch (err) {
+        const hint = `Manifest not found or unreadable at ${manifestPath}. The orchestrator must initialize it ({"orchestrator_root": "...", "worktrees": []}) before recording agents.`;
+        writeErr(`[gsd] worktree.record-agent: manifest_read_failed — ${hint}\n`);
+        write(`${JSON.stringify({ ok: false, reason: 'manifest_read_failed', hint, error: err.message }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: 'manifest_read_failed', hint, entry: null };
+    }
+    const plan = planWorktreeRecordAgent(manifestRaw, {
+        agentId: flag('--agent-id'),
+        worktreePath: flag('--path'),
+        branch: flag('--branch'),
+        base: flag('--base'),
+    });
+    if (!plan.ok || plan.manifest === null) {
+        writeErr(`[gsd] worktree.record-agent: ${plan.reason} — ${plan.hint || ''}\n`);
+        write(`${JSON.stringify({ ok: false, reason: plan.reason, hint: plan.hint }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: plan.reason, hint: plan.hint, entry: null };
+    }
+    const writeFile = deps.writeFile || ((p, content) => node_fs_1.default.writeFileSync(p, content, 'utf8'));
+    writeFile(resolved, plan.manifest);
+    write(`${JSON.stringify({ ok: true, reason: 'ok', entry: plan.entry, manifest_path: resolved }, null, 2)}\n`);
+    return { ok: true, reason: 'ok', entry: plan.entry, manifest_path: resolved };
+}
 /**
  * Reap orphaned linked worktrees whose lock owner process is dead, whose
  * branch tip is fully merged into the default branch, and whose lock file
@@ -978,6 +1178,8 @@ module.exports = {
     planWorktreeWaveCleanup,
     executeWorktreeWaveCleanupPlan,
     cmdWorktreeCleanupWave,
+    planWorktreeRecordAgent,
+    cmdWorktreeRecordAgent,
     reapOrphanWorktrees,
     cmdWorktreeReapOrphans,
     resolveWorktreeRoot,

package/gsd-core/bin/shared/config-defaults.manifest.json

@@ -53,7 +53,8 @@
     "post_planning_gaps": true,
     "security_enforcement": true,
     "security_asvs_level": 1,
-    "security_block_on": "high"
+    "security_block_on": "high",
+    "context_guard_mode": "warn"
   },
   "planning": {
     "commit_docs": true,

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -56,6 +56,7 @@
     "workflow.test_command",
     "workflow.build_command",
     "workflow.mvp_mode",
+    "workflow.context_guard_mode",
     "executor.stall_detect_interval_minutes",
     "executor.stall_threshold_minutes",
     "workflow.inline_plan_threshold",

package/gsd-core/references/context-budget.md

@@ -29,14 +29,14 @@ Every workflow that spawns agents or reads significant content must follow these
 
 ## Context Degradation Tiers
 
-Monitor context usage and adjust behavior accordingly:
-
-| Tier | Usage | Behavior |
-|------|-------|----------|
-| PEAK | 0-30% | Full operations. Read bodies, spawn multiple agents, inline results. |
-| GOOD | 30-50% | Normal operations. Prefer frontmatter reads, delegate aggressively. |
-| DEGRADING | 50-70% | Economize. Frontmatter-only reads, minimal inlining, warn user about budget. |
-| POOR | 70%+ | Emergency mode. Checkpoint progress immediately. No new reads unless critical. |
+Monitor context usage and adjust behavior accordingly. The `workflow.context_guard_mode` config key (values: `auto`, `warn`, `off`; default `warn`) controls how `execute-phase.md` responds when the guard fires at a wave boundary.
+
+| Tier | Usage | Behavior | Trigger Action (execute-phase) |
+|------|-------|----------|-------------------------------|
+| PEAK | 0-30% | Full operations. Read bodies, spawn multiple agents, inline results. | None |
+| GOOD | 30-50% | Normal operations. Prefer frontmatter reads, delegate aggressively. | None |
+| DEGRADING | 50-70% | Economize. Frontmatter-only reads, minimal inlining, warn user about budget. | Emit warning, continue |
+| POOR | 70%+ | Emergency mode. Checkpoint progress immediately. No new reads unless critical. | `warn`: emit warning + recommend `/gsd:pause-work`. `auto`: invoke pause-work before next wave. `off`: proceed anyway. |
 
 ## Context Degradation Warning Signs
 

package/gsd-core/references/execute-phase-context-guard.md

@@ -0,0 +1,16 @@
+0. **Context exhaustion guard — `context_guard` (BEFORE spawning, #1452):**
+
+   Before spawning any agents for this wave, self-assess context pressure using the
+   degradation signals in `references/context-budget.md`. Signs of POOR tier (70%+):
+   increasing vagueness, skipped steps, silent partial completion.
+
+   Read `workflow.context_guard_mode` from `.planning/config.json` (default `warn`).
+
+   | Tier | `warn` (default) | `auto` | `off` |
+   |------|-----------------|--------|-------|
+   | PEAK / GOOD | No output | No output | No output |
+   | DEGRADING (50-70%) | Emit: "⚠ Context pressure DEGRADING — switching to frontmatter-only reads for remaining waves." Continue. | Same as warn | Skip |
+   | POOR (70%+) | Emit: "🛑 Context pressure POOR — risk of context exhaustion. Run `/gsd:pause-work` to checkpoint before this wave, then resume in a fresh session." Continue (user decides). | Invoke `/gsd:pause-work` immediately and halt. Do NOT spawn wave agents. | Skip |
+
+   The guard is heuristic — no programmatic context-percentage API exists. Use your
+   assessment of degradation signals, not a fixed token count.

package/gsd-core/references/planning-config.md

@@ -267,6 +267,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.test_command` | string\|null | `null` | Any shell command | Regression/test gate command run by verify-phase, execute-phase, audit-fix, and post-merge-gate. Unset → GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). |
 | `workflow.build_command` | string\|null | `null` | Any shell command | Build gate command run by the post-merge gate. Unset → build step auto-detected/skipped. |
 | `workflow.mvp_mode` | boolean | `false` | `true`, `false` | Persist the MVP-mode flag in config so every phase defaults to MVP framing without requiring `--mvp` on the CLI. Resolved via the chain: `--mvp` CLI flag → ROADMAP.md `**Mode:** mvp` field → this config value → `false`. When `true`, the planner, executor, verifier, and discovery surfaces (progress, stats, graphify) all treat the phase as an MVP vertical slice (UI → API → DB) of one user-visible capability. |
+| `workflow.context_guard_mode` | string | `"warn"` | `"auto"`, `"warn"`, `"off"` | Context exhaustion guard mode for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using degradation signals from `context-budget.md`. `"warn"` (default): emit a warning and recommend `/gsd:pause-work` when POOR tier is detected. `"auto"`: automatically invoke `/gsd:pause-work` before the next wave when POOR tier is detected. `"off"`: disable the guard. The guard is heuristic — no programmatic context-% API exists. |
 | `workflow.plan_chunked` | boolean | `false` | `true`, `false` | Enable chunked planning mode. When `true`, the plan-phase orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3–5 min each). Each plan is committed individually for crash resilience. Particularly useful on Windows where long-lived Tasks may hang on stdio. Also activated by the `--chunked` flag. |
 | `workflow.code_review_command` | string\|null | `null` | Any shell command | External code-review command integrated into `/gsd:ship`. The diff is piped to the command via stdin; the command must output JSON with a `verdict` field (`"APPROVED"` or `"REVISE"`). Non-zero exit or `"REVISE"` verdict blocks the ship workflow. When unset, the built-in review flow runs. Example: `my-review-tool --review`. |
 | `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |

package/gsd-core/references/prohibition-probe.md

@@ -157,7 +157,7 @@ A `resolved`/`test`-tier prohibition MAY carry an **optional `check` descriptor*
 the wired mechanical check, so verify-phase locates it deterministically instead of inventing
 `{kind, target, rule}` each run. The descriptor is captured at spec-phase (soft / optional —
 the author wires it when the negative test or lint rule already exists) and is represented as
-**four flat scalar keys** on the `must_haves.prohibitions` item — never a nested `check: {}`
+**five flat scalar keys** on the `must_haves.prohibitions` item — never a nested `check: {}`
 object:
 
 - `check_kind` — `node-test` | `lint-rule` (which producer mechanism runs the check).
@@ -165,16 +165,19 @@ object:
 - `check_rule` — the `ruleId` to filter on, **lint-rule only** (absent for `node-test`).
 - `check_violation_fixture` — path to a KNOWN-BAD subject the #1279 prover runs the check against to
   machine-prove fail-first (rides BOTH kinds; for `node-test` it is injected via `GSD_PROHIB_SUBJECT`).
+- `check_clean_fixture` — **optional** path to a KNOWN-CLEAN control subject (#1346). When present the
+  node-test prover also runs the check against it and requires GREEN, proving the violation's RED is
+  caused by the subject's *content* (not merely by `GSD_PROHIB_SUBJECT` being set). Absent → no control.
 
 The flat-scalar shape is load-bearing: the shared `parseMustHavesBlock` is a flat parser and a
 nested object would flatten/mangle the round-trip (ADR-550 2026-06-15 addendum; #644 "no parser
 rewrite" precedent). `projectProhibitions` emits these keys **only for a well-formed descriptor**
 (valid `check_kind` + non-empty `check_target`; `check_rule` only on the lint-rule path;
-`check_violation_fixture` only when non-empty), and verify-phase reads them back via
-`descriptorFromProjection` into the `CheckDescriptor` handed to `check prohibition-enforcement`. This
-closes **both** the locate (#1278) and the machine-proof-fixture (#1346) halves with **zero manual
-descriptor authoring**: a prohibition authored with all four scalars greens end-to-end through the
-projection alone.
+`check_violation_fixture` and `check_clean_fixture` only when non-empty), and verify-phase reads them
+back via `descriptorFromProjection` into the `CheckDescriptor` handed to `check prohibition-enforcement`.
+This closes the locate (#1278), the machine-proof-fixture (#1279), and the causation-control (#1346)
+halves with **zero manual descriptor authoring**: a prohibition authored with the scalars greens
+end-to-end through the projection alone.
 
 **Fail-closed + backward-compat.** A partial descriptor (`lint-rule` missing `check_rule`), an
 unknown `check_kind`, an **absent** descriptor, OR a descriptor with **no `check_violation_fixture`**
@@ -182,8 +185,11 @@ falls through to the producer's fail-closed paths (`located: false`, or located-
 never a silent green. A prohibition with no descriptor parses and disposes byte-identically to today.
 `failFirst` is **not** sourced from the descriptor and is **demoted** (machine-proven fail-first
 DELIVERED in #1279 — no path greens on attestation alone, FF-08); the `dispositionForProhibition`
-policy is unchanged. Residual (tracked **#1346**): the node-test proof confirms the fixture exists and
-the check goes RED, but cannot generically prove the red was *caused by* the subject's content.
+policy is unchanged. Causation (**#1346**): the node-test proof confirms the fixture exists and the
+check goes RED; supplying `check_clean_fixture` adds an opt-in control that *also* requires GREEN on a
+known-clean subject, proving the red is content-caused. With no clean fixture the control cannot run,
+so that one residual case (a deceptive test reding merely because the env var is set) stays a
+documented constraint — an author opts into the stronger proof by wiring a clean control subject.
 
 ## Output schema
 
@@ -191,7 +197,7 @@ The probe emits, per kept prohibition, an item of the form:
 
 ```
 { requirement_id, category, status, verification, resolution, reason, statement,
-  check_kind?, check_target?, check_rule? }
+  check_kind?, check_target?, check_rule?, check_violation_fixture?, check_clean_fixture? }
 ```
 
 where `statement` is the must-NOT sentence and `category` is the values/safety/ethics class