@deftai/directive-core 0.88.0 → 0.90.0

package/dist/tool-events/summarize.js

@@ -0,0 +1,93 @@
+/**
+ * Aggregate tool-event classifications into counts, anomalies, and status lines (#2967).
+ * Pure: no I/O.
+ */
+import { classifyToolEvent } from "./classify.js";
+import { TOOL_EVENT_BUCKETS, } from "./types.js";
+export function emptyBucketCounts() {
+    return {
+        explore: 0,
+        commit: 0,
+        verify: 0,
+        coordinate: 0,
+        unknown: 0,
+    };
+}
+/** Count classified buckets for a sequence of tool events. */
+export function countToolEventBuckets(events) {
+    const counts = {
+        explore: 0,
+        commit: 0,
+        verify: 0,
+        coordinate: 0,
+        unknown: 0,
+    };
+    for (const event of events) {
+        const { bucket } = classifyToolEvent(event);
+        counts[bucket] += 1;
+    }
+    return counts;
+}
+/**
+ * Detect operator-facing anomalies from bucket counts.
+ *
+ * Rules (conservative — only fire when the mix is clearly wrong):
+ * - commit-without-explore: commit > 0 and explore === 0
+ * - verify-skipped: commit > 0 and verify === 0 (ship without gates)
+ * - explore-only: explore > 0, commit === 0, verify === 0, and total >= 3
+ *   (thrash / stuck-reading signal; small explore-only sessions stay quiet)
+ */
+export function detectToolEventAnomalies(counts) {
+    const anomalies = [];
+    const total = counts.explore + counts.commit + counts.verify + counts.coordinate + counts.unknown;
+    if (counts.commit > 0 && counts.explore === 0) {
+        anomalies.push({
+            code: "commit-without-explore",
+            message: `commit-without-explore: ${counts.commit} commit event(s) with 0 explore`,
+        });
+    }
+    if (counts.commit > 0 && counts.verify === 0) {
+        anomalies.push({
+            code: "verify-skipped",
+            message: `verify-skipped: ${counts.commit} commit event(s) with 0 verify`,
+        });
+    }
+    if (counts.explore > 0 && counts.commit === 0 && counts.verify === 0 && total >= 3) {
+        anomalies.push({
+            code: "explore-only",
+            message: `explore-only: ${counts.explore} explore event(s) with 0 commit and 0 verify (possible thrash)`,
+        });
+    }
+    return anomalies;
+}
+/**
+ * Compact status line for swarm monitor / review-cycle batch brief.
+ * Example: `tools: explore=3 commit=2 verify=1 coordinate=0 unknown=0`
+ */
+export function formatToolEventStatusLine(counts) {
+    const parts = TOOL_EVENT_BUCKETS.map((b) => `${b}=${counts[b]}`);
+    return `tools: ${parts.join(" ")}`;
+}
+/**
+ * One-line anomaly suffix for status surfaces.
+ * Empty string when no anomalies.
+ */
+export function formatToolEventAnomalyLine(anomalies) {
+    if (anomalies.length === 0)
+        return "";
+    return `anomalies: ${anomalies.map((a) => a.code).join(",")}`;
+}
+/**
+ * Full summary for a tool-event sequence — counts, anomalies, status line.
+ * When anomalies exist, statusLine appends `| anomalies: …`.
+ */
+export function summarizeToolEvents(events) {
+    const counts = countToolEventBuckets(events);
+    const anomalies = detectToolEventAnomalies(counts);
+    const total = counts.explore + counts.commit + counts.verify + counts.coordinate + counts.unknown;
+    const base = formatToolEventStatusLine(counts);
+    const anomalyLine = formatToolEventAnomalyLine(anomalies);
+    const statusLine = anomalyLine.length > 0 ? `${base} | ${anomalyLine}` : base;
+    return { total, counts, anomalies, statusLine };
+}
+//# sourceMappingURL=summarize.js.map

package/dist/tool-events/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool-event taxonomy types for explore/commit/verify classification (#2967).
+ * Pure types only — no I/O.
+ */
+/** Deterministic activity buckets for swarm/review operator skim. */
+export type ToolEventBucket = "explore" | "commit" | "verify" | "coordinate" | "unknown";
+/** All buckets in stable report order (unknown last). */
+export declare const TOOL_EVENT_BUCKETS: readonly ToolEventBucket[];
+/**
+ * Minimal tool-event input. Prefer tool name + coarse args; never require
+ * full host payloads. Shell tools should pass `command` when known.
+ */
+export interface ToolEventInput {
+    /** Host tool name (e.g. `Read`, `Shell`, `Write`, `Task`). */
+    readonly name: string;
+    /**
+     * Coarse args bag — common keys: `command`, `cmd`, `path`, `file_path`,
+     * `query`, `pattern`. Values may be strings or other JSON-ish primitives.
+     */
+    readonly args?: Readonly<Record<string, unknown>> | null;
+    /**
+     * Explicit shell/command string when not nested under `args`.
+     * Wins over `args.command` / `args.cmd` when both are set.
+     */
+    readonly command?: string | null;
+}
+/** Result of classifying one tool event. */
+export interface ClassifyToolEventResult {
+    readonly bucket: ToolEventBucket;
+    /** Stable machine-oriented reason code for tests and debug. */
+    readonly reason: string;
+}
+/** Per-bucket event counts (always includes every bucket key). */
+export type ToolEventBucketCounts = Readonly<Record<ToolEventBucket, number>>;
+/**
+ * Operator-facing anomaly codes derived from a sequence of classified events.
+ * Detection is conservative: only fire when the mix is clearly wrong.
+ */
+export type ToolEventAnomalyCode = "commit-without-explore" | "verify-skipped" | "explore-only";
+export interface ToolEventAnomaly {
+    readonly code: ToolEventAnomalyCode;
+    readonly message: string;
+}
+/** Aggregate summary for monitor status lines and batch briefs. */
+export interface ToolEventSummary {
+    readonly total: number;
+    readonly counts: ToolEventBucketCounts;
+    readonly anomalies: readonly ToolEventAnomaly[];
+    /** Compact one-liner: `tools: explore=3 commit=2 verify=1 coordinate=0 unknown=0`. */
+    readonly statusLine: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tool-events/types.js

@@ -0,0 +1,13 @@
+/**
+ * Tool-event taxonomy types for explore/commit/verify classification (#2967).
+ * Pure types only — no I/O.
+ */
+/** All buckets in stable report order (unknown last). */
+export const TOOL_EVENT_BUCKETS = [
+    "explore",
+    "commit",
+    "verify",
+    "coordinate",
+    "unknown",
+];
+//# sourceMappingURL=types.js.map

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);
     }

package/dist/verify-source/contained-writes.d.ts

@@ -0,0 +1,59 @@
+/**
+ * contained-writes.ts — inventory gate for raw product write sinks (#2951).
+ *
+ * Scans TypeScript under packages/core/src (and optional roots) for raw write
+ * call patterns (`writeFileSync`, `appendFileSync`, `fs.writeFile`, etc.)
+ * outside an allowlist. Default remains **fail-open** (advisory exit 0) while
+ * mass migration continues; pass `--enforce` to fail closed (Phase 2+).
+ *
+ * Allowlist is the residual set of modules not yet migrated onto containedWrite.
+ * Phase 2 removed cache/io + lifecycle/events after sink migration.
+ *
+ * Exit codes:
+ *   0 — clean OR fail-open with findings (default)
+ *   1 — findings under `--enforce` (fail-closed)
+ *   2 — config error (project root missing)
+ *
+ * Refs #2951, #2980 (e2e/parity harness exclusions).
+ */
+/** Patterns that indicate a raw filesystem write sink in product code. */
+export declare const RAW_WRITE_PATTERNS: readonly RegExp[];
+/**
+ * Relative path prefixes (posix-style) allowed to use raw write sinks.
+ * Shrink as sinks migrate onto containedWrite (#2951 Phase 2+).
+ */
+export declare const CONTAINED_WRITES_ALLOWLIST: readonly string[];
+/**
+ * Non-product harness path markers excluded from the product inventory (#2980).
+ * Prefer exclusion over permanent CONTAINED_WRITES_ALLOWLIST entries for e2e/parity noise.
+ * Paths are matched as posix substrings after `toPosix` (always `/` separators).
+ */
+export declare const NON_PRODUCT_HARNESS_PATH_MARKERS: readonly string[];
+export interface ContainedWriteFinding {
+    readonly path: string;
+    readonly line: number;
+    readonly match: string;
+}
+export interface ContainedWritesOptions {
+    readonly projectRoot: string;
+    /** When true, exit 1 if any non-allowlisted raw write is found. Default false (fail-open). */
+    readonly enforce?: boolean;
+    /** Extra relative path prefixes to allow. */
+    readonly extraAllowlist?: readonly string[];
+    /** Roots to scan relative to projectRoot. Default packages/core/src. */
+    readonly scanRoots?: readonly string[];
+}
+export interface ContainedWritesResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: "stdout" | "stderr";
+    readonly findings: readonly ContainedWriteFinding[];
+    readonly enforce: boolean;
+    readonly failOpen: boolean;
+}
+/**
+ * Inventory raw write sinks under scan roots; fail-open by default (#2951).
+ * Pass `enforce: true` / `--enforce` to fail closed on findings (Phase 2 path).
+ */
+export declare function evaluateContainedWrites(options: ContainedWritesOptions): ContainedWritesResult;
+//# sourceMappingURL=contained-writes.d.ts.map