@deftai/directive-core 0.107.0 → 0.108.0

package/dist/session/toolchain-preflight.js

@@ -9,20 +9,24 @@
  * remedy without embedding env values.
  */
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { allGatesCliDispatchable, GLOBAL_CLI_REMEDY, isCliNativeGate, } from "../check/cli-native-gates.js";
 import { isFrameworkRepoRoot, isFrameworkSourceContext } from "../check/context.js";
 import { CONSUMER_CHECK_GATES, checkGateId, FRAMEWORK_CHECK_GATES, } from "../check/gate-lists.js";
 import { defaultWhich } from "../doctor/which.js";
+import { packageManagerSourceLabel, resolveProjectPackageManager, } from "../resolution/package-manager.js";
+/** Maintainer toolchain remains pnpm-based. Consumer tools are selected dynamically. */
 export const TOOLCHAIN_PREFLIGHT_TOOLS = ["task", "pnpm", "node", "git"];
 const REMEDY = {
     task: "Install go-task: https://taskfile.dev/installation/ (e.g. winget install Task.Task / brew install go-task)",
+    npm: "Install or repair Node 20+ (npm is bundled), then re-run the consumer check",
     pnpm: "Enable pnpm via corepack: corepack enable && corepack prepare pnpm@latest --activate",
-    node: "Install Node 20+ (see .nvmrc); then corepack enable",
+    node: "Install Node 20+ (see .nvmrc)",
     git: "Install Git: https://git-scm.com/downloads",
 };
 const CAUSE = {
     task: "go-task binary not found on PATH",
+    npm: "npm binary not found on PATH",
     pnpm: "pnpm binary not found on PATH",
     node: "node binary not found on PATH",
     git: "git binary not found on PATH",
@@ -32,20 +36,29 @@ const CAUSE = {
  * When task/node is missing, the orchestrator skips *all* scheduled gates
  * (dynamic from gate-lists), not this static list — avoids hardcode drift.
  */
-export const PNPM_DEPENDENT_GATE_IDS = [
+export const PACKAGE_MANAGER_DEPENDENT_GATE_IDS = [
     "toolchain:check",
     "toolchain:check-consumer",
     "ts:check-lane",
 ];
+/** @deprecated use PACKAGE_MANAGER_DEPENDENT_GATE_IDS. */
+export const PNPM_DEPENDENT_GATE_IDS = PACKAGE_MANAGER_DEPENDENT_GATE_IDS;
 /** Sentinel skip id meaning "every gate in the active check composition". */
 export const SKIP_ALL_GATES = "*";
-function probeTool(tool, which) {
+function probeTool(tool, which, packageManager) {
     const present = which(tool) !== null;
+    let remedy = REMEDY[tool];
+    if (tool === "node" && packageManager === "npm") {
+        remedy = "Install or repair Node 20+ (npm is bundled), then re-run the consumer check";
+    }
+    else if (tool === "node" && packageManager === "pnpm") {
+        remedy = "Install Node 20+ (see .nvmrc); then enable pnpm with Corepack";
+    }
     return {
         tool,
         present,
         cause: present ? null : CAUSE[tool],
-        remedy: present ? null : REMEDY[tool],
+        remedy: present ? null : remedy,
     };
 }
 function probeCliDist(frameworkRoot, which, exists) {
@@ -78,7 +91,8 @@ function formatFindingLine(finding) {
     }
     if (finding.impact === "none") {
         const cause = finding.cause ?? "absent";
-        return `[deft preflight] ${finding.tool}: absent (impact: none) — ${cause}`;
+        const remedy = finding.remedy === null ? "" : `; remedy: ${finding.remedy}`;
+        return `[deft preflight] ${finding.tool}: absent (impact: none) — ${cause}${remedy}`;
     }
     const cause = finding.cause ?? "missing";
     const remedy = finding.remedy ?? "install the tool";
@@ -90,14 +104,17 @@ function inferConsumerDeposit(options) {
     const project = options.projectRoot;
     if (project === undefined)
         return false;
-    // Same-path roots are framework-source only when the tree is the source repo.
-    if (isFrameworkRepoRoot(project))
-        return false;
     const framework = options.frameworkRoot ?? project;
+    // session:start passes equal roots for both framework source and a consumer
+    // deposit. Equal roots identify maintainer mode only when the tree has the
+    // framework-source markers; otherwise this is the production consumer shape.
+    if (resolve(framework) === resolve(project)) {
+        return !isFrameworkRepoRoot(project);
+    }
     return !isFrameworkSourceContext(framework, project);
 }
 /**
- * Run done-gate toolchain preflight. Pure probe — never installs or builds.
+ * Run done-gate toolchain preflight. Read-only probe — never installs or builds.
  */
 export function runToolchainPreflight(options = {}) {
     const which = options.which ?? defaultWhich;
@@ -106,16 +123,44 @@ export function runToolchainPreflight(options = {}) {
     const composed = options.composedGates ?? (consumerDeposit ? CONSUMER_CHECK_GATES : FRAMEWORK_CHECK_GATES);
     const allCli = allGatesCliDispatchable(composed);
     const findings = [];
-    for (const tool of TOOLCHAIN_PREFLIGHT_TOOLS) {
-        findings.push(probeTool(tool, which));
+    let packageManager = "pnpm";
+    let packageManagerSource = "maintainer";
+    let packageManagerSelectionFailed = false;
+    let selectedTools = TOOLCHAIN_PREFLIGHT_TOOLS;
+    if (consumerDeposit) {
+        const resolution = resolveProjectPackageManager({
+            projectRoot: options.projectRoot,
+            env: options.env,
+        });
+        if (resolution.ok) {
+            packageManager = resolution.packageManager;
+            packageManagerSource = resolution.source;
+            selectedTools = ["task", packageManager, "node", "git"];
+        }
+        else {
+            packageManager = null;
+            packageManagerSource = null;
+            packageManagerSelectionFailed = true;
+            selectedTools = ["task", "node", "git"];
+            findings.push({
+                tool: "package_manager",
+                present: false,
+                cause: resolution.message,
+                remedy: "Set package.json#packageManager (or DEFT_PACKAGE_MANAGER) to a supported npm or pnpm value",
+            });
+        }
+    }
+    for (const tool of selectedTools) {
+        findings.push(probeTool(tool, which, packageManager));
     }
     if (options.probeCliDist !== false) {
         findings.push(probeCliDist(options.frameworkRoot ?? options.projectRoot, which, exists));
     }
     const cliPresent = findings.some((f) => f.tool === "cli_dist" && f.present);
     const taskMissing = findings.some((f) => f.tool === "task" && !f.present);
-    const pnpmMissing = findings.some((f) => f.tool === "pnpm" && !f.present);
     const nodeMissing = findings.some((f) => f.tool === "node" && !f.present);
+    const packageManagerMissing = packageManagerSelectionFailed ||
+        (packageManager !== null && findings.some((f) => f.tool === packageManager && !f.present));
     // #3335: in a deposit whose composed gates are all CLI-dispatchable, a
     // missing task binary is impact none — no install-go-task remedy.
     if (taskMissing && allCli) {
@@ -132,10 +177,30 @@ export function runToolchainPreflight(options = {}) {
             };
         }
     }
+    // Keep finding impact aligned with the skip calculation. Git is advisory in
+    // this preflight, and a local CLI dist matters only when task is absent and
+    // every composed gate must dispatch through the CLI.
+    for (let index = 0; index < findings.length; index += 1) {
+        const finding = findings[index];
+        if (finding === undefined || finding.present)
+            continue;
+        if (finding.tool === "git") {
+            findings[index] = { ...finding, impact: "none" };
+        }
+        else if (finding.tool === "cli_dist") {
+            findings[index] = {
+                ...finding,
+                impact: taskMissing && allCli && !cliPresent ? "degraded" : "none",
+            };
+        }
+    }
     const missingCritical = findings.filter((f) => {
         if (f.present || f.impact === "none")
             return false;
-        return f.tool === "task" || f.tool === "pnpm" || f.tool === "node";
+        return (f.tool === "task" ||
+            f.tool === "node" ||
+            f.tool === "package_manager" ||
+            f.tool === packageManager);
     });
     const skip = new Set();
     if (nodeMissing) {
@@ -156,8 +221,8 @@ export function runToolchainPreflight(options = {}) {
     else if (taskMissing && allCli && !cliPresent) {
         skip.add(SKIP_ALL_GATES);
     }
-    else if (pnpmMissing) {
-        for (const id of PNPM_DEPENDENT_GATE_IDS) {
+    else if (packageManagerMissing) {
+        for (const id of PACKAGE_MANAGER_DEPENDENT_GATE_IDS) {
             skip.add(id);
         }
     }
@@ -166,6 +231,12 @@ export function runToolchainPreflight(options = {}) {
     const status = ok ? "ok" : "degraded";
     const lines = [];
     lines.push(`[deft preflight] toolchain status: ${status}`);
+    if (consumerDeposit &&
+        packageManager !== null &&
+        packageManagerSource !== null &&
+        packageManagerSource !== "maintainer") {
+        lines.push(`[deft preflight] package manager: ${packageManager} (${packageManagerSourceLabel(packageManagerSource)})`);
+    }
     for (const finding of findings) {
         if (!finding.present) {
             lines.push(formatFindingLine(finding));
@@ -173,8 +244,8 @@ export function runToolchainPreflight(options = {}) {
     }
     if (ok) {
         lines.push(taskMissing && allCli
-            ? "[deft preflight] done-gate toolchain ready (CLI dispatch; go-task not required) (#3335)"
-            : "[deft preflight] done-gate toolchain ready (task, pnpm, node)");
+            ? `[deft preflight] done-gate toolchain ready (CLI dispatch; go-task not required; package manager: ${packageManager}) (#3335)`
+            : `[deft preflight] done-gate toolchain ready (task, ${packageManager}, node)`);
     }
     else {
         lines.push("[deft preflight] degraded mode: directive check will skip toolchain-dependent gates " +
@@ -190,6 +261,8 @@ export function runToolchainPreflight(options = {}) {
         findings,
         lines,
         skipGateIds: [...skip].sort(),
+        packageManager,
+        packageManagerSource,
     };
 }
 /** Serialize preflight for run-summary / ritual-state (no env values). */
@@ -198,6 +271,8 @@ export function toolchainPreflightToDict(result) {
         status: result.status,
         ok: result.ok,
         degraded: result.degraded,
+        package_manager: result.packageManager ?? null,
+        package_manager_source: result.packageManagerSource ?? null,
         findings: result.findings.map((f) => ({
             tool: f.tool,
             present: f.present,

package/dist/session/verify-session-ritual.d.ts

@@ -41,6 +41,11 @@ export interface VerifyResult {
      * `rearm` when age/compact stale on an otherwise valid bind; `cold` otherwise.
      */
     readonly recoveryTier?: SessionCeremonyTier | null;
+    /**
+     * Internal owner from the exact ritual state evaluated for this verdict.
+     * Absent until worktree/HEAD binding succeeds; never projected by emitVerifyJson.
+     */
+    readonly boundSessionId?: string;
 }
 export type RitualRunner = (command: readonly string[], projectRoot: string) => {
     code: number;
@@ -107,6 +112,12 @@ export interface InspectSessionRitualOptions {
     readonly posture?: DirectivePosture;
     readonly envPosture?: string | undefined;
     readonly handoffText?: string | null;
+    /**
+     * Required gated steps for this surface. Defaults to all {@link GATED_STEPS}.
+     * Write dispatch passes {@link WRITE_GATED_REQUIRED_STEPS} so a no-write
+     * inspect reports the same readiness its verifying counterpart would (#3738).
+     */
+    readonly requiredGatedSteps?: readonly GatedStepName[];
 }
 /**
  * Read-only ritual-state inspection for host hooks.

package/dist/session/verify-session-ritual.js

@@ -136,7 +136,37 @@ function shouldRearmDriftProbe(payload, projectRoot, detect) {
         return false;
     return detect(projectRoot).inPlay;
 }
-function runGatedStep(projectRoot, payload, stepName, runner, now, detect = detectWorkSelection) {
+/**
+ * Persist a payload derived from `expected` only while the record on disk is
+ * still the one this verification read (#3769).
+ *
+ * A lease transfer mid-verification can re-arm the tree under a new owner. The
+ * losing session is denied by the occupancy recheck, but without this
+ * compare-and-swap its in-flight write would already have replaced the new
+ * owner record. Serializing ritual writes outright is the separate
+ * ritual-state locking item, deliberately out of scope.
+ *
+ * Returns null on success, or the reason the write was refused.
+ */
+function writeRitualStateIfStillOwned(projectRoot, payload, expected) {
+    const [current] = readRitualState(projectRoot);
+    if (current === null) {
+        return "session ritual state was removed while this verification was running";
+    }
+    if (current.sessionId !== expected.sessionId ||
+        current.startedAt.getTime() !== expected.startedAt.getTime()) {
+        return (`session ritual state was re-armed by ${current.sessionId ?? "<unbound>"} while this ` +
+            "verification was running; refusing to overwrite the current owner record");
+    }
+    try {
+        writeRitualState(projectRoot, payload);
+    }
+    catch (exc) {
+        return String(exc);
+    }
+    return null;
+}
+function runGatedStep(projectRoot, payload, stepName, runner, now, expected, detect = detectWorkSelection) {
     const command = resolveGatedEntrypointCommand(stepName, projectRoot, detect);
     const { code, stdout, stderr } = runner(command, projectRoot);
     const message = stdout.trim() || stderr.trim() || `${command[0]} exited ${code}`;
@@ -152,11 +182,9 @@ function runGatedStep(projectRoot, payload, stepName, runner, now, detect = dete
     if (stepName === "cache_fresh") {
         applyCacheFreshDriftProbeField(payload, command);
     }
-    try {
-        writeRitualState(projectRoot, payload);
-    }
-    catch (exc) {
-        return `could not write session ritual state after ${stepName}: ${String(exc)}`;
+    const refusal = writeRitualStateIfStillOwned(projectRoot, payload, expected);
+    if (refusal !== null) {
+        return `could not write session ritual state after ${stepName}: ${refusal}`;
     }
     return null;
 }
@@ -199,14 +227,11 @@ function evaluateLoadedState(projectRoot, state, input) {
             return { code: 1, message: headDriftRecoveryMessage(), recoveryTier: "cold" };
         }
         if (input.rebindForwardHead) {
-            const payload = { ...state.raw, git_head: currentHead };
-            try {
-                writeRitualState(projectRoot, payload);
-            }
-            catch (exc) {
+            const refusal = writeRitualStateIfStillOwned(projectRoot, { ...state.raw, git_head: currentHead }, { sessionId: state.sessionId, startedAt: state.startedAt });
+            if (refusal !== null) {
                 return {
                     code: 2,
-                    message: `could not rebind session ritual git HEAD: ${String(exc)}`,
+                    message: `could not rebind session ritual git HEAD: ${refusal}`,
                     recoveryTier: "cold",
                 };
             }
@@ -218,6 +243,7 @@ function evaluateLoadedState(projectRoot, state, input) {
             code: 2,
             message: staleness.error ?? "session ritual staleness policy is invalid",
             recoveryTier: "cold",
+            boundSessionId: state.sessionId,
         };
     }
     const maxAgeMs = staleness.hours * 60 * 60 * 1000;
@@ -232,6 +258,7 @@ function evaluateLoadedState(projectRoot, state, input) {
             message: `session ritual state is stale (older than ${staleness.hours}h).${compactNote} ` +
                 `Run \`${rearmCmd}\` to re-arm (or \`${coldCmd}\` for a full cold ceremony).`,
             recoveryTier: "rearm",
+            boundSessionId: state.sessionId,
         };
     }
     for (const stepName of QUICK_STEPS) {
@@ -241,6 +268,7 @@ function evaluateLoadedState(projectRoot, state, input) {
                 code: 1,
                 message: failedStepMessage("quick", stepName, step),
                 recoveryTier: "cold",
+                boundSessionId: state.sessionId,
             };
         }
     }
@@ -249,10 +277,14 @@ function evaluateLoadedState(projectRoot, state, input) {
         for (const stepName of requiredGated) {
             const step = state.gatedSteps[stepName];
             if (!stepPasses(step)) {
+                const recoveryTier = "cold";
                 return {
                     code: 1,
-                    message: failedStepMessage("gated", stepName, step),
-                    recoveryTier: "cold",
+                    message: failedStepMessage("gated", stepName, step) +
+                        " " +
+                        formatRitualRecoveryInstruction(recoveryTier),
+                    recoveryTier,
+                    boundSessionId: state.sessionId,
                 };
             }
         }
@@ -261,6 +293,7 @@ function evaluateLoadedState(projectRoot, state, input) {
         code: 0,
         message: `OK session ritual ${input.tier} tier is fresh.`,
         recoveryTier: null,
+        boundSessionId: state.sessionId,
     };
 }
 /**
@@ -335,6 +368,7 @@ export function inspectSessionRitual(projectRoot, options = {}) {
         now: options.now ?? new Date(),
         runGit: options.runGit,
         rebindForwardHead: false,
+        requiredGatedSteps: options.requiredGatedSteps,
     });
     return {
         code: evaluated.code,
@@ -346,6 +380,7 @@ export function inspectSessionRitual(projectRoot, options = {}) {
         posture,
         ritualStateRequired,
         recoveryTier: evaluated.recoveryTier,
+        ...(evaluated.boundSessionId === undefined ? {} : { boundSessionId: evaluated.boundSessionId }),
     };
 }
 export function verifySessionRitual(projectRoot, options = {}) {
@@ -440,6 +475,9 @@ export function verifySessionRitual(projectRoot, options = {}) {
                 posture,
                 ritualStateRequired,
                 recoveryTier: precheck.recoveryTier,
+                ...(precheck.boundSessionId === undefined
+                    ? {}
+                    : { boundSessionId: precheck.boundSessionId }),
             };
         }
         const reloadedAfterPrecheck = readRitualState(projectRoot);
@@ -458,6 +496,9 @@ export function verifySessionRitual(projectRoot, options = {}) {
             };
         }
         const payload = { ...state.raw };
+        // Identity of the record this verification is amending; a mid-flight lease
+        // transfer must not let these writes land on a newer owner (#3769).
+        const ownerAtVerify = { sessionId: state.sessionId, startedAt: state.startedAt };
         const gated = { ...payload.gated_steps };
         payload.gated_steps = gated;
         const runCmd = options.runner ?? defaultRitualRunner;
@@ -477,7 +518,7 @@ export function verifySessionRitual(projectRoot, options = {}) {
             if (stepName !== "agent_hooks" && stepPasses(step) && !forced.has(stepName) && !rearmDrift) {
                 continue;
             }
-            const writeError = runGatedStep(projectRoot, payload, stepName, runCmd, instant, detect);
+            const writeError = runGatedStep(projectRoot, payload, stepName, runCmd, instant, ownerAtVerify, detect);
             if (writeError !== null) {
                 return {
                     code: 2,
@@ -556,6 +597,9 @@ export function verifySessionRitual(projectRoot, options = {}) {
             posture,
             ritualStateRequired,
             recoveryTier: evaluated.recoveryTier,
+            ...(evaluated.boundSessionId === undefined
+                ? {}
+                : { boundSessionId: evaluated.boundSessionId }),
         };
     }
     return {
@@ -568,6 +612,7 @@ export function verifySessionRitual(projectRoot, options = {}) {
         posture,
         ritualStateRequired,
         recoveryTier: evaluated.recoveryTier,
+        ...(evaluated.boundSessionId === undefined ? {} : { boundSessionId: evaluated.boundSessionId }),
     };
 }
 export function emitVerifyJson(result) {

package/dist/slice/constants.d.ts

@@ -10,7 +10,7 @@ export declare const REQUIRED_FIELDS: readonly ["slice_id", "umbrella", "umbrell
 export declare const OPTIONAL_FIELDS: readonly ["notes"];
 export declare const ALLOWED_FIELDS: Set<"actor" | "slice_id" | "umbrella" | "umbrella_url" | "sliced_at" | "children" | "expected_close_signal" | "notes">;
 export declare const CHILD_REQUIRED_FIELDS: readonly ["n", "url", "wave", "role"];
-export declare const CHILD_ALLOWED_FIELDS: Set<"n" | "url" | "wave" | "role">;
+export declare const CHILD_ALLOWED_FIELDS: Set<"n" | "role" | "url" | "wave">;
 export declare const UUID_RE: RegExp;
 export declare const ISO8601_RE: RegExp;
 export declare const WAVE_FLAG_RE: RegExp;

package/dist/spec-authority/constants.d.ts

@@ -4,10 +4,18 @@ export declare const GENERATED_SPEC_SOURCE_SPEC = "<!-- Source of truth: vbrief/
 export declare const GENERATED_SPEC_SOURCE_SPEC_XBRIEF = "<!-- Source of truth: xbrief/specification.xbrief.json -->";
 export declare const GENERATED_SPEC_SOURCE_PD = "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json -->";
 export declare const GENERATED_SPEC_SOURCE_PD_XBRIEF = "<!-- Source of truth: xbrief/PROJECT-DEFINITION.xbrief.json -->";
-/** True when markdown carries a generated-spec source marker for either layout. */
-export declare function contentHasGeneratedSpecSource(content: string): boolean;
+/** Return decoded non-PROJECT-DEFINITION source markers from generated markdown. */
+export declare function generatedSpecSourcePaths(content: string): string[];
+/** True when markdown names the expected generated-spec source artifact. */
+export declare function contentHasGeneratedSpecSource(content: string, expectedSourcePath: string): boolean;
 /** True when markdown carries a generated greenfield PD source marker for either layout. */
 export declare function contentHasGeneratedPdSource(content: string): boolean;
+/** Format a source path for a generated artifact banner. */
+export declare function generatedSourcePath(sourcePath: string): string;
+/** Build a canonical four-line generated-artifact banner from the actual source path. */
+export declare function buildGeneratedArtifactBanner(generator: string, purpose: string, sourcePath: string): string;
+/** Build the greenfield project export banner for the resolved PROJECT-DEFINITION path. */
+export declare function buildExportSpecPdBanner(projectDefPath: string): string;
 export declare const EXPORT_SPEC_PD_BANNER: string;
 /** Narratives excluded from stakeholder SPEC/PRD exports (#2013 Wave 0 §5). */
 export declare const STAKEHOLDER_EXCLUDED_NARRATIVE_KEYS: Set<string>;

package/dist/spec-authority/constants.js

@@ -1,22 +1,67 @@
+import { basename, dirname, normalize, sep } from "node:path";
 /** Generated-spec banner tokens (lockstep with Python ``_precutover.py``). */
 export const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
 export const GENERATED_SPEC_SOURCE_SPEC = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
 export const GENERATED_SPEC_SOURCE_SPEC_XBRIEF = "<!-- Source of truth: xbrief/specification.xbrief.json -->";
 export const GENERATED_SPEC_SOURCE_PD = "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json -->";
 export const GENERATED_SPEC_SOURCE_PD_XBRIEF = "<!-- Source of truth: xbrief/PROJECT-DEFINITION.xbrief.json -->";
-/** True when markdown carries a generated-spec source marker for either layout. */
-export function contentHasGeneratedSpecSource(content) {
-    return (content.includes(GENERATED_SPEC_SOURCE_SPEC) ||
-        content.includes(GENERATED_SPEC_SOURCE_SPEC_XBRIEF));
+const GENERATED_SOURCE_MARKER = /^<!-- Source of truth: (.+?) -->\r?$/gm;
+const PROJECT_DEFINITION_SOURCE = /(?:^|\/)PROJECT-DEFINITION\.(?:vbrief|xbrief)\.json$/i;
+/** Return decoded non-PROJECT-DEFINITION source markers from generated markdown. */
+export function generatedSpecSourcePaths(content) {
+    const sources = [];
+    for (const match of content.matchAll(GENERATED_SOURCE_MARKER)) {
+        let source;
+        try {
+            source = match[1] ? decodeURI(match[1]) : undefined;
+        }
+        catch {
+            // A generated source path is URI-encoded by the banner writer. Reject
+            // malformed escapes instead of guessing at a filesystem path.
+        }
+        if (source && !PROJECT_DEFINITION_SOURCE.test(source))
+            sources.push(source);
+    }
+    return sources;
+}
+/** True when markdown names the expected generated-spec source artifact. */
+export function contentHasGeneratedSpecSource(content, expectedSourcePath) {
+    const expected = generatedSourcePath(expectedSourcePath);
+    return generatedSpecSourcePaths(content).includes(expected);
 }
 /** True when markdown carries a generated greenfield PD source marker for either layout. */
 export function contentHasGeneratedPdSource(content) {
     return (content.includes(GENERATED_SPEC_SOURCE_PD) || content.includes(GENERATED_SPEC_SOURCE_PD_XBRIEF));
 }
-export const EXPORT_SPEC_PD_BANNER = "<!-- AUTO-GENERATED by task project:export-spec -- DO NOT EDIT MANUALLY -->\n" +
-    `${GENERATED_SPEC_PURPOSE}\n` +
-    `${GENERATED_SPEC_SOURCE_PD}\n` +
-    "<!-- Regenerate with: task project:export-spec -->\n";
+/** Format a source path for a generated artifact banner. */
+export function generatedSourcePath(sourcePath) {
+    const parent = basename(dirname(sourcePath));
+    if (parent === "xbrief" || parent === "vbrief") {
+        return `${parent}/${basename(sourcePath)}`;
+    }
+    return normalize(sourcePath).split(sep).join("/");
+}
+function generatedBannerValue(value) {
+    return value.replace(/\r\n?|\n/g, " ").replaceAll("-->", "--&gt;");
+}
+/** Build a canonical four-line generated-artifact banner from the actual source path. */
+export function buildGeneratedArtifactBanner(generator, purpose, sourcePath) {
+    const safeGenerator = generatedBannerValue(generator);
+    const safePurpose = generatedBannerValue(purpose);
+    // Source paths must be reversible so an explicit --spec artifact can be
+    // bound back to the resolved authority. URI encoding keeps CR/LF and an
+    // embedded comment closer on one safe line without losing path identity.
+    const safeSourcePath = encodeURI(generatedSourcePath(sourcePath));
+    return (`<!-- AUTO-GENERATED by ${safeGenerator} -- DO NOT EDIT MANUALLY -->\n` +
+        `<!-- Purpose: ${safePurpose} -->\n` +
+        `<!-- Source of truth: ${safeSourcePath} -->\n` +
+        `<!-- Regenerate with: ${safeGenerator} -->\n`);
+}
+/** Build the greenfield project export banner for the resolved PROJECT-DEFINITION path. */
+export function buildExportSpecPdBanner(projectDefPath) {
+    return buildGeneratedArtifactBanner("task project:export-spec", "rendered specification", projectDefPath);
+}
+export const EXPORT_SPEC_PD_BANNER = buildExportSpecPdBanner("xbrief/PROJECT-DEFINITION.xbrief.json");
 /** Narratives excluded from stakeholder SPEC/PRD exports (#2013 Wave 0 §5). */
 export const STAKEHOLDER_EXCLUDED_NARRATIVE_KEYS = new Set([
     "projectconfig",

package/dist/spec-authority/resolver.d.ts

@@ -5,10 +5,13 @@ export interface ResolvedSpecAuthority {
     readonly vbriefDir: string;
     readonly projectDefPath: string;
     readonly specPath: string | null;
+    readonly sourcePath: string;
     readonly banner: string;
 }
 export declare function resolveSpecAuthority(projectRoot: string): ResolvedSpecAuthority | null;
 export declare function readSpecMarkdown(projectRoot: string): string;
+/** True when the markdown source marker resolves to the project's specification authority. */
+export declare function contentHasResolvedSpecSource(projectRoot: string, content: string): boolean;
 export declare function isFullSpecState(projectRoot: string): boolean;
 export declare function isGreenfieldSpecExport(projectRoot: string): boolean;
 export declare function isCurrentGeneratedSpecification(projectRoot: string): boolean;

package/dist/spec-authority/resolver.js

@@ -1,8 +1,8 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, } from "../layout/resolve.js";
-import { SPEC_RENDER_BANNER } from "../render/constants.js";
-import { contentHasGeneratedPdSource, contentHasGeneratedSpecSource, EXPORT_SPEC_PD_BANNER, GENERATED_SPEC_PURPOSE, } from "./constants.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, resolveSpecArtifactPath, } from "../layout/resolve.js";
+import { buildExportSpecPdBanner, buildGeneratedArtifactBanner, contentHasGeneratedPdSource, contentHasGeneratedSpecSource, GENERATED_SPEC_PURPOSE, generatedSpecSourcePaths, } from "./constants.js";
 export function resolveSpecAuthority(projectRoot) {
     const root = projectRoot;
     let layout;
@@ -20,13 +20,17 @@ export function resolveSpecAuthority(projectRoot) {
     const specPath = join(vbriefDir, `specification${layout.artifactSuffix}`);
     const hasSpec = existsSync(specPath);
     const kind = hasSpec ? "full-spec" : "greenfield";
-    const banner = kind === "full-spec" ? SPEC_RENDER_BANNER : EXPORT_SPEC_PD_BANNER;
+    const sourcePath = hasSpec ? specPath : projectDefPath;
+    const banner = hasSpec
+        ? buildGeneratedArtifactBanner("task spec:render", "rendered specification", sourcePath)
+        : buildExportSpecPdBanner(sourcePath);
     return {
         kind,
         projectRoot: root,
         vbriefDir,
         projectDefPath,
         specPath: hasSpec ? specPath : null,
+        sourcePath,
         banner,
     };
 }
@@ -39,12 +43,56 @@ export function readSpecMarkdown(projectRoot) {
         return "";
     }
 }
+function sourcePathFromMarker(projectRoot, source) {
+    return isAbsolute(source) ? source : resolve(projectRoot, source);
+}
+function contentMatchesResolvedSpecSource(projectRoot, content, resolvedSourcePath) {
+    if (contentHasGeneratedSpecSource(content, resolvedSourcePath))
+        return true;
+    let resolvedSource;
+    try {
+        resolvedSource = JSON.parse(readFileSync(resolvedSourcePath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    for (const source of generatedSpecSourcePaths(content)) {
+        try {
+            const candidate = sourcePathFromMarker(projectRoot, source);
+            if (!statSync(candidate).isFile())
+                continue;
+            // Explicit --spec paths remain valid aliases only when they identify the
+            // same JSON authority as the layout-resolved specification artifact.
+            if (isDeepStrictEqual(JSON.parse(readFileSync(candidate, "utf8")), resolvedSource)) {
+                return true;
+            }
+        }
+        catch {
+            // Missing or unreadable explicit source markers are not resolved authority.
+        }
+    }
+    return false;
+}
+/** True when the markdown source marker resolves to the project's specification authority. */
+export function contentHasResolvedSpecSource(projectRoot, content) {
+    let resolvedSourcePath;
+    try {
+        resolvedSourcePath = resolveSpecArtifactPath(projectRoot);
+    }
+    catch {
+        return false;
+    }
+    if (!existsSync(resolvedSourcePath))
+        return false;
+    return contentMatchesResolvedSpecSource(projectRoot, content, resolvedSourcePath);
+}
 export function isFullSpecState(projectRoot) {
     const authority = resolveSpecAuthority(projectRoot);
     if (authority?.kind !== "full-spec")
         return false;
     const specMd = readSpecMarkdown(projectRoot);
-    return specMd.includes(GENERATED_SPEC_PURPOSE) && contentHasGeneratedSpecSource(specMd);
+    return (specMd.includes(GENERATED_SPEC_PURPOSE) &&
+        contentMatchesResolvedSpecSource(projectRoot, specMd, authority.sourcePath));
 }
 export function isGreenfieldSpecExport(projectRoot) {
     const authority = resolveSpecAuthority(projectRoot);

package/dist/subprocess/max-buffer.d.ts

@@ -15,4 +15,18 @@
  * so an overflow is never silent again.
  */
 export declare const SUBPROCESS_MAX_BUFFER: number;
+/**
+ * Reason text for a failed capture, so an overflow is never blank (#1867 / #3903).
+ *
+ * A spawn-level failure (ENOBUFS past the ceiling, timeout kill, missing
+ * binary) reports no exit status and empty stderr, whether it arrives as a
+ * `spawnSync` result or as a thrown `execFileSync` error. Only then does the
+ * error message stand in for stderr: a process that exited with a status and
+ * chose to say nothing keeps its empty stderr.
+ */
+export declare function resolveCaptureFailureStderr(capture: {
+    readonly captured: string;
+    readonly status: number | null | undefined;
+    readonly message: string | undefined;
+}): string;
 //# sourceMappingURL=max-buffer.d.ts.map