@deftai/directive-core 0.87.0 → 0.89.0

package/dist/session/session-start-hook.d.ts

@@ -1,9 +1,12 @@
+import { detectNoDeftDirective } from "../policy/no-deft-directive.js";
 import { writeSentinel } from "./ritual-sentinel.js";
 export interface SessionStartHookOptions {
     readonly resolveVersionFn?: () => string;
     readonly detectBranchFn?: (projectRoot: string) => string | null;
     readonly detectLatestActiveVbriefFn?: (projectRoot: string) => string | null;
     readonly writeSentinelFn?: typeof writeSentinel;
+    /** Test seam for #2926 opt-out detection. */
+    readonly detectNoDeftDirectiveFn?: typeof detectNoDeftDirective;
 }
 /** Write ``.deft/last-session.json`` from current git state (#1269). */
 export declare function runSessionStartHookWrite(projectRoot: string, options?: SessionStartHookOptions): {

package/dist/session/session-start-hook.js

@@ -1,8 +1,23 @@
 import { resolveVersion } from "../doctor/paths.js";
+import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, } from "../policy/no-deft-directive.js";
 import { detectBranch } from "./git.js";
 import { detectLatestActiveVbrief, writeSentinel } from "./ritual-sentinel.js";
 /** Write ``.deft/last-session.json`` from current git state (#1269). */
 export function runSessionStartHookWrite(projectRoot, options = {}) {
+    const detectOptOut = options.detectNoDeftDirectiveFn ?? detectNoDeftDirective;
+    // #2926: root opt-out wins — host SessionStart must not write ritual bookkeeping.
+    const optOut = detectOptOut(projectRoot);
+    if (optOut.present) {
+        const lines = [NO_DEFT_DIRECTIVE_DISABLED_MESSAGE];
+        if (optOut.inconsistent) {
+            lines.push(NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE);
+        }
+        return {
+            code: optOut.inconsistent ? 1 : 0,
+            stdout: `${lines.join("\n")}\n`,
+            stderr: optOut.inconsistent ? `${NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE}\n` : "",
+        };
+    }
     const detectBranchFn = options.detectBranchFn ?? detectBranch;
     const detectVbriefFn = options.detectLatestActiveVbriefFn ?? detectLatestActiveVbrief;
     const resolveVersionFn = options.resolveVersionFn ?? resolveVersion;

package/dist/session/session-start.js

@@ -4,6 +4,8 @@ import { emitSessionEvalReadback } from "../eval/readback.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { disclosureLine } from "../policy/disclosure.js";
+import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
+import { humanMergeDisclosureLine, resolveHumanMergePolicy, } from "../policy/require-human-merge.js";
 import { resolvePolicy } from "../policy/resolve.js";
 import { maybeFormatProductSignalConsentPrompt } from "../product-signal/consent-prompt.js";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
@@ -233,6 +235,35 @@ export function runSessionStart(projectRoot, options = {}) {
     const deferrals = options.deferrals ?? {};
     const runGit = options.runGit ?? defaultGitRunner;
     const environment = (options.probeEnvironment ?? detectEnvironmentContext)();
+    // #2926: official root opt-out wins locally — skip Directive session ritual.
+    // disabled = skip ritual (exit 0 clean / 1 inconsistent). ready stays false so
+    // automation does not treat opt-out as "session fully initialized for work".
+    const optOut = detectNoDeftDirective(projectRoot);
+    if (optOut.present) {
+        const lines = [NO_DEFT_DIRECTIVE_DISABLED_MESSAGE];
+        if (optOut.inconsistent) {
+            lines.push(NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE);
+        }
+        const code = optOut.inconsistent ? 1 : 0;
+        return {
+            code,
+            payload: {
+                ready: false,
+                exit_code: code,
+                disabled: true,
+                disabled_via: NO_DEFT_DIRECTIVE_FLAG_NAME,
+                inconsistent: optOut.inconsistent,
+                inconsistent_policy: optOut.inconsistent
+                    ? NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY
+                    : undefined,
+                deposit_present: optOut.depositPresent,
+                posture,
+                environment: environmentContextToDict(environment),
+                message: NO_DEFT_DIRECTIVE_DISABLED_MESSAGE,
+            },
+            lines,
+        };
+    }
     if (posture === READ_ONLY_POSTURE) {
         return runReadOnlySessionStart(projectRoot, options, instant, environment);
     }
@@ -289,6 +320,12 @@ export function runSessionStart(projectRoot, options = {}) {
             exitCode: ok ? 0 : 2,
         });
         lines.push(message);
+        // Human merge gate disclosure (#1193) — surface when ON (or env bypass active).
+        const humanMerge = resolveHumanMergePolicy(projectRoot);
+        const humanMergeLine = humanMergeDisclosureLine(humanMerge);
+        if (humanMergeLine !== null) {
+            lines.push(humanMergeLine);
+        }
         const branchSync = defaultBranchSync(projectRoot, runGit);
         if (branchSync.warning) {
             lines.push(branchSync.warning);

package/dist/staleness-tickler/state.js

@@ -1,5 +1,6 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { resolveTriageCachePath } from "../triage/cache-path.js";
 export const STATE_RELATIVE_PATH = join("xbrief", ".triage-cache", "staleness-tickler-state.json");
 const STATE_FILE_NAME = "staleness-tickler-state.json";
@@ -15,10 +16,29 @@ function defaultReadText(path) {
     }
 }
 function defaultWriteText(path, content) {
-    mkdirSync(dirname(path), { recursive: true });
-    const temporary = `${path}.${process.pid}.tmp`;
-    writeFileSync(temporary, content, "utf8");
-    renameSync(temporary, path);
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmpBase = `${basename(path)}.${process.pid}.tmp`;
+    const temporary = join(dir, tmpBase);
+    try {
+        // #2980 wave D: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(dir),
+            target: tmpBase,
+            data: content,
+            mode: "create",
+        });
+        renameSync(temporary, path);
+    }
+    catch (err) {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
 }
 export function parseStalenessTicklerState(text) {
     if (text === null) {

package/dist/swarm/launch.js

@@ -1,5 +1,6 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, isAbsolute, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { inferGithubAuthMode } from "../intake/github-auth-modes.js";
 import { getPlatformCapabilities } from "../intake/platform-capabilities.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, stripArtifactSuffix, } from "../layout/resolve.js";
@@ -581,7 +582,16 @@ export function swarmLaunch(args) {
     const rendered = `${JSON.stringify(manifest, null, 2)}\n`;
     if (args.output !== undefined && args.output !== null) {
         try {
-            writeFileSync(args.output, rendered, "utf8");
+            // #2980 wave D: product write sink routes through containedWrite.
+            const abs = resolve(args.output);
+            const dir = dirname(abs);
+            mkdirSync(dir, { recursive: true });
+            containedWrite({
+                root: dir,
+                target: basename(abs),
+                data: rendered,
+                mode: "replace",
+            });
         }
         catch (exc) {
             return {

package/dist/swarm/routing.js

@@ -14,8 +14,9 @@
  * explicit default.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 /**
  * The fixed worker-role vocabulary (reused from #1531). No separate tier
@@ -234,7 +235,12 @@ export function writeModelDecision(projectRoot, path, provider, role, decision)
         decidedAt: decision.decidedAt ?? new Date().toISOString(),
     };
     file[provider] = block;
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+    // #2980 wave D: product write sink routes through containedWrite.
+    containedWrite({
+        root: resolve(projectRoot),
+        target: path,
+        data: `${JSON.stringify(file, null, 2)}\n`,
+        mode: "replace",
+    });
 }
 //# sourceMappingURL=routing.js.map

package/dist/task-surface/index.js

@@ -1,8 +1,9 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { LEGACY_VBRIEF_VERSION } from "@deftai/directive-types";
-import { assertProjectionContained, assertWriteTargetSafe, ProjectionContainmentError, } from "../fs/projection-containment.js";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
+import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 const UNRELEASED_RE = /## \[Unreleased\][ \t]*\n([\s\S]*?)(?=\n## \[|$)/;
 const CHANGE_NAME_RE = /^[\w][\w-]*$/;
 const COMMIT_TYPES = "feat|fix|docs|chore|refactor|test|style|perf|ci|build|revert";
@@ -14,7 +15,7 @@ function projectionTarget(projectDir, ...relSegments) {
     return target;
 }
 function containmentExitCode(io, err) {
-    if (err instanceof ProjectionContainmentError) {
+    if (err instanceof ProjectionContainmentError || err instanceof ContainedWriteError) {
         io.writeErr(`FAIL: ${err.message}\n`);
         return 2;
     }
@@ -93,10 +94,19 @@ export function runChangeInit(projectRoot, name, io) {
         mkdirSync(specsDir, { recursive: true });
         const proposalPath = join(base, "proposal.xbrief.json");
         const tasksPath = join(base, "tasks.xbrief.json");
-        assertWriteTargetSafe(projectAbs, proposalPath);
-        assertWriteTargetSafe(projectAbs, tasksPath);
-        writeFileSync(proposalPath, `${JSON.stringify(proposalTemplate(trimmed), null, 2)}\n`, "utf8");
-        writeFileSync(tasksPath, `${JSON.stringify(tasksTemplate(trimmed), null, 2)}\n`, "utf8");
+        // #2980 wave D: product write sinks route through containedWrite.
+        containedWrite({
+            root: projectAbs,
+            target: proposalPath,
+            data: `${JSON.stringify(proposalTemplate(trimmed), null, 2)}\n`,
+            mode: "create",
+        });
+        containedWrite({
+            root: projectAbs,
+            target: tasksPath,
+            data: `${JSON.stringify(tasksTemplate(trimmed), null, 2)}\n`,
+            mode: "create",
+        });
         io.writeOut(`OK: Created change proposal at ${base}/\n`);
         for (const file of ["proposal.xbrief.json", "tasks.xbrief.json", "specs/"]) {
             io.writeOut(`  - ${file}\n`);
@@ -150,8 +160,13 @@ export function runInstallUninstall(projectRoot, io) {
     const next = filtered.join("");
     if (next !== original) {
         try {
-            assertWriteTargetSafe(resolve(projectRoot), path);
-            writeFileSync(path, next, "utf8");
+            // #2980 wave D: product write sink routes through containedWrite.
+            containedWrite({
+                root: resolve(projectRoot),
+                target: path,
+                data: next,
+                mode: "replace",
+            });
             io.writeOut("Removed deft entry from AGENTS.md\n");
         }
         catch (err) {

package/dist/triage/bootstrap/gitignore.js

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, relative } from "node:path";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../../fs/projection-containment.js";
 import { MIGRATED_ARTIFACT_DIR, resolveLifecycleLayout } from "../../layout/resolve.js";
 import { resolveCandidatesLogPath, resolveTriageCachePath, TRIAGE_CACHE_DIR_NAME, triageCacheRelPath, } from "../cache-path.js";
@@ -197,7 +198,14 @@ function ensureGitignoreLine(projectRoot, gitignorePath, line, stepName, createI
             return stepOutcome(stepName, false, `.gitignore not present after the prior gitignore step; ${line} not written -- re-run bootstrap to retry`, { created: false, appended: false, skipped: "no-gitignore" }, "prior gitignore step did not create .gitignore");
         }
         try {
-            writeFileSync(gitignorePath, `${line}\n`, { encoding: "utf8" });
+            // #2980 wave D: product write sink routes through containedWrite.
+            const root = resolve(projectRoot);
+            containedWrite({
+                root,
+                target: gitignorePath,
+                data: `${line}\n`,
+                mode: "create",
+            });
         }
         catch (exc) {
             return stepOutcome(stepName, false, "could not create .gitignore", {}, String(exc));
@@ -232,7 +240,13 @@ function ensureGitignoreLine(projectRoot, gitignorePath, line, stepName, createI
     const suffix = existing.endsWith("\n") || existing === "" ? "" : "\n";
     const newContent = `${existing + suffix + rationaleBlock + line}\n`;
     try {
-        writeFileSync(gitignorePath, newContent, { encoding: "utf8" });
+        // #2980 wave D: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(projectRoot),
+            target: gitignorePath,
+            data: newContent,
+            mode: "replace",
+        });
     }
     catch (exc) {
         return stepOutcome(stepName, false, "could not write .gitignore", {}, String(exc));
@@ -303,7 +317,13 @@ function ensureGitignoreSelectiveEntries(projectRoot, stepName, entries) {
         : `${EVAL_ENTRIES_RATIONALE}${missing.join("\n")}\n`;
     const newContent = existing + suffix + appendedBlock;
     try {
-        writeFileSync(gitignorePath, newContent, { encoding: "utf8" });
+        // #2980 wave D: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(projectRoot),
+            target: gitignorePath,
+            data: newContent,
+            mode: "replace",
+        });
     }
     catch (exc) {
         return stepOutcome(stepName, false, "could not write .gitignore", { gitignore_appended_lines: 0 }, String(exc));
@@ -341,7 +361,13 @@ function ensureGitattributesMergeUnion(projectRoot, stepName, glob, ruleLine) {
         const suffix = existing.endsWith("\n") || existing === "" ? "" : "\n";
         const newContent = `${existing + suffix + GITATTRIBUTES_EVAL_RATIONALE + ruleLine}\n`;
         try {
-            writeFileSync(gitattributesPath, newContent, { encoding: "utf8" });
+            // #2980 wave D: product write sink routes through containedWrite.
+            containedWrite({
+                root: resolve(projectRoot),
+                target: gitattributesPath,
+                data: newContent,
+                mode: "replace",
+            });
         }
         catch (exc) {
             return stepOutcome(stepName, false, "could not write .gitattributes", { gitattributes_appended: false }, String(exc));
@@ -353,7 +379,13 @@ function ensureGitattributesMergeUnion(projectRoot, stepName, glob, ruleLine) {
     }
     const newContent = `${GITATTRIBUTES_EVAL_RATIONALE + ruleLine}\n`;
     try {
-        writeFileSync(gitattributesPath, newContent, { encoding: "utf8" });
+        // #2980 wave D: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(projectRoot),
+            target: gitattributesPath,
+            data: newContent,
+            mode: "create",
+        });
     }
     catch (exc) {
         return stepOutcome(stepName, false, "could not create .gitattributes", { gitattributes_appended: false }, String(exc));
@@ -382,8 +414,13 @@ function ensureEvalReadme(options) {
         // create below
     }
     try {
-        mkdirSync(dirname(readmePath), { recursive: true });
-        writeFileSync(readmePath, generateTriageCacheReadmeBody(projectRoot), { encoding: "utf8" });
+        // #2980 wave D: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(projectRoot),
+            target: readmePath,
+            data: generateTriageCacheReadmeBody(projectRoot),
+            mode: "create",
+        });
     }
     catch (exc) {
         return stepOutcome(stepName, false, `could not create ${readmePath}`, { readme_created: false }, String(exc));
@@ -474,7 +511,13 @@ export function stepSeedCandidatesLog(projectRoot) {
         // create below
     }
     try {
-        writeFileSync(auditPath, "", { encoding: "utf8" });
+        // #2980 wave D: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(projectRoot),
+            target: auditPath,
+            data: "",
+            mode: "create",
+        });
     }
     catch (exc) {
         return stepOutcome("seed_candidates_log", false, `could not seed ${auditPath}`, {}, String(exc));

package/dist/triage/cache-path.js

@@ -4,8 +4,9 @@
  * Triage append-only logs and scratch dirs live under `.triage-cache/` so the
  * `.eval/` namespace can be reclaimed for version-eval results (#1703 Tier 2).
  */
-import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { join, relative } from "node:path";
+import { existsSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertProjectionContained } from "../fs/projection-containment.js";
 import { MIGRATED_ARTIFACT_DIR, resolveEvalDir, resolveLifecycleLayout, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { generateTriageCacheReadmeBody } from "./bootstrap/gitignore.js";
@@ -99,7 +100,13 @@ export function migrateLegacyTriageCacheFromEval(projectRoot) {
                 removedLegacyFiles.push(name);
             }
             else {
-                writeFileSync(targetPath, generateTriageCacheReadmeBody(projectRoot), "utf8");
+                // #2980 wave D: product write sink routes through containedWrite.
+                containedWrite({
+                    root: resolve(projectRoot),
+                    target: targetPath,
+                    data: generateTriageCacheReadmeBody(projectRoot),
+                    mode: "create",
+                });
                 unlinkSync(legacyPath);
                 regeneratedFiles.push(name);
             }

package/dist/triage/welcome/summary.js

@@ -1,5 +1,6 @@
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { readPlanPolicy } from "../../policy/plan-extensions.js";
 import { countVbriefWip, resolveWipCap } from "../../policy/wip.js";
@@ -296,8 +297,14 @@ export function appendHistory(historyPath, result, line) {
         reconcilable: result.reconcilable,
     };
     try {
-        mkdirSync(join(historyPath, ".."), { recursive: true });
-        appendFileSync(historyPath, `${JSON.stringify(record)}\n`, "utf8");
+        // #2980 wave D: product write sink routes through containedWrite.
+        const dir = dirname(historyPath);
+        containedWrite({
+            root: resolve(dir),
+            target: basename(historyPath),
+            data: `${JSON.stringify(record)}\n`,
+            mode: "append",
+        });
     }
     catch {
         // observability only

package/dist/triage/welcome/writers.js

@@ -1,6 +1,6 @@
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { assertProjectionContained } from "../../fs/projection-containment.js";
+import { containedWrite } from "../../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
 import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
@@ -12,22 +12,51 @@ function utcIso() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
 export function appendAuditEntry(projectRoot, entry) {
-    const logPath = join(resolve(projectRoot), AUDIT_LOG_REL_PATH);
-    assertProjectionContained(projectRoot, logPath);
-    mkdirSync(dirname(logPath), { recursive: true });
-    const line = `${utcIso()} ${entry}\n`;
+    const root = resolve(projectRoot);
+    const logPath = join(root, AUDIT_LOG_REL_PATH);
+    // #2980 wave D: product write sink routes through containedWrite.
+    mkdirSync(root, { recursive: true });
     if (!existsSync(logPath)) {
-        writeFileSync(logPath, "# meta/policy-changes.log -- audit trail for PROJECT-DEFINITION plan.policy.* mutations (#746 / #1143)\n", "utf8");
+        containedWrite({
+            root,
+            target: AUDIT_LOG_REL_PATH,
+            data: "# meta/policy-changes.log -- audit trail for PROJECT-DEFINITION plan.policy.* mutations (#746 / #1143)\n",
+            mode: "create",
+        });
     }
-    appendFileSync(logPath, line, "utf8");
+    containedWrite({
+        root,
+        target: AUDIT_LOG_REL_PATH,
+        data: `${utcIso()} ${entry}\n`,
+        mode: "append",
+    });
     return logPath;
 }
-function atomicWrite(path, data) {
-    mkdirSync(dirname(path), { recursive: true });
+function atomicWrite(_projectRoot, path, data) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
     const payload = `${JSON.stringify(data, null, 2)}\n`;
-    const tmp = join(dirname(path), `.${Date.now()}.tmp`);
-    writeFileSync(tmp, payload, "utf8");
-    renameSync(tmp, path);
+    const tmpName = `.${Date.now()}.tmp`;
+    const tmp = join(dir, tmpName);
+    try {
+        // #2980 wave D: temp payload write uses containedWrite under the parent dir.
+        containedWrite({
+            root: resolve(dir),
+            target: tmpName,
+            data: payload,
+            mode: "create",
+        });
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
 }
 export function writeTriageScope(projectRoot, rules, options = { presetLabel: "custom" }) {
     // Serialise read-modify-write + audit append under the shared lock (#1260).
@@ -54,7 +83,7 @@ export function writeTriageScope(projectRoot, rules, options = { presetLabel: "c
         const policyRec = policy;
         const previous = policyRec.triageScope;
         policyRec.triageScope = rules;
-        atomicWrite(path, data);
+        atomicWrite(projectRoot, path, data);
         const changed = JSON.stringify(previous) !== JSON.stringify(rules);
         const actor = options.actor ?? WELCOME_AUDIT_TAG;
         const auditEntry = [
@@ -101,14 +130,14 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         }
         if (previous !== undefined && wipCap === DEFAULT_WIP_CAP) {
             delete policyRec.wipCap;
-            atomicWrite(path, data);
+            atomicWrite(projectRoot, path, data);
             const auditEntry = `actor=${actor} field=plan.policy.wipCap action=cleared-to-default value=${wipCap} ` +
                 `previous=${JSON.stringify(previous)} changed=true`;
             appendAuditEntry(projectRoot, auditEntry);
             return [true, auditEntry];
         }
         policyRec.wipCap = wipCap;
-        atomicWrite(path, data);
+        atomicWrite(projectRoot, path, data);
         const changed = previous !== wipCap;
         const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
             `changed=${changed ? "true" : "false"}`;

package/dist/validate-content/validate-links.js

@@ -10,6 +10,11 @@ const EXCLUDE_DIRS = new Set([
     "dist",
     ".planning",
     "specs",
+    // Swarm / agent worktrees are not framework content; walking them
+    // during release Step 5 / task check is pure wall-clock waste (#2953, #1656).
+    ".deft-scratch",
+    // Legacy swarm worktree root name (pre-.deft-scratch layout).
+    "swarm-worktrees",
 ]);
 function shouldSkipPath(parts) {
     if (parts.some((p) => EXCLUDE_DIRS.has(p)))

package/dist/value/readback.js

@@ -1,8 +1,9 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { ALL_ATTRIBUTION_EVENT_NAMES } from "../events/attribution-constants.js";
-import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
+import { ProjectionContainmentError } from "../fs/projection-containment.js";
 import { DEFAULT_EVENT_LOG, readEvents } from "../lifecycle/events.js";
 import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
@@ -230,12 +231,16 @@ function appendReadbackHistory(projectRoot, eventId, line, options = {}) {
         line,
     };
     try {
-        assertWriteTargetSafe(projectRoot, path);
-        mkdirSync(join(path, ".."), { recursive: true });
-        appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+        // #2980 wave D: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(projectRoot),
+            target: path,
+            data: `${JSON.stringify(record)}\n`,
+            mode: "append",
+        });
     }
     catch (err) {
-        if (err instanceof ProjectionContainmentError) {
+        if (err instanceof ProjectionContainmentError || err instanceof ContainedWriteError) {
             throw err;
         }
         // observability only

package/dist/vbrief-activate/activate.js

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
-import { basename, dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { utcNowIso } from "../scope/vbrief-json.js";
 import { pythonJsonPretty } from "../vbrief-build/json.js";
 import { ACTIVE_FOLDER, ELIGIBLE_STATUSES_FOR_FLIP, formatEligibleStatusList, SOURCE_FOLDERS, TARGET_STATUS, } from "./constants.js";
@@ -150,15 +151,22 @@ export function activate(vbriefPath, options = {}) {
                 "collision manually before re-running `task vbrief:activate`.",
         };
     }
+    const tmpBase = `${fileName}.tmp`;
     const tmp = `${dest}.tmp`;
     try {
-        writeFileSync(tmp, pythonJsonPretty(payload), "utf8");
+        // #2980 wave D: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(activeDir),
+            target: tmpBase,
+            data: pythonJsonPretty(payload),
+            mode: "create",
+        });
         renameSync(tmp, dest);
     }
     catch (err) {
         const e = err;
         try {
-            unlinkSync(tmp);
+            rmSync(tmp, { force: true });
         }
         catch {
             /* best-effort cleanup */

package/dist/vbrief-build/project-definition-io.js

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { pythonJsonPretty } from "./json.js";
 import { ProjectDefinitionIOError } from "./types.js";
@@ -105,12 +106,19 @@ export function loadProjectDefinitionForMutation(projectRoot) {
 }
 /** Atomically write ``data`` to ``path`` as pretty-printed JSON. */
 export function atomicWriteProjectDefinition(path, data) {
-    mkdirSync(dirname(path), { recursive: true });
+    // #2980 wave C: product write sink routes through containedWrite (temp under parent).
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
     const payload = pythonJsonPretty(data).replace(/\n$/, "");
-    const tmp = join(dirname(path), `${path.split(/[/\\]/).pop()}.${randomBytes(4).toString("hex")}.tmp`);
+    const body = payload.endsWith("\n") ? payload : `${payload}\n`;
+    const tmpName = `${basename(path)}.${randomBytes(4).toString("hex")}.tmp`;
+    const tmp = join(dir, tmpName);
     try {
-        writeFileSync(tmp, payload.endsWith("\n") ? payload : `${payload}\n`, {
-            encoding: "utf8",
+        containedWrite({
+            root: resolve(dir),
+            target: tmpName,
+            data: body,
+            mode: "create",
         });
         renameSync(tmp, path);
     }