@deftai/directive-core 0.102.0 → 0.104.0

package/dist/scope/transition.js

@@ -1,18 +1,20 @@
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { SESSION_COMPLETED_AC_REMEDIATION, writeSessionCompletedMarker, } from "../check/session-completed-ac.js";
 import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemetry.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
+import { applyClauseDerivationToPlan, maybeEmitAcceptanceStampFromChange, } from "../intake/clause-derivation.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { evaluateCompletedPlanConsistency } from "../lifecycle/completed-consistency.js";
 import { evaluateLiteralAcceptanceFromPlan } from "../literal-acceptance/index.js";
 import { evaluateAcceptanceActivateGate } from "./acceptance-activate-gate.js";
-import { evaluateAcceptanceEvidenceGate, formatAcceptanceCompletionListing, } from "./acceptance-evidence.js";
+import { evaluateAcceptanceEvidenceGate, evaluateScopeCompleteAcceptanceWalk, formatAcceptanceCompletionListing, } from "./acceptance-evidence.js";
 import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
 import { atomicWriteBrief, formatBriefJson, readBriefForMutation } from "./brief-io.js";
 import { stampCompletionMetadata } from "./capacity-stamp.js";
 import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRANSITIONS, } from "./constants.js";
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
-import { classifyStoredDeliveryDisposition, evaluateDeliveryGate, stampDeliveryProvenance, } from "./delivery-evidence.js";
+import { classifyStoredDeliveryDisposition, evaluateDeliveryGate, resolveCompletionSessionId, stampDeliveryProvenance, } from "./delivery-evidence.js";
 import { evaluateEffortActivateGate } from "./effort-activate-gate.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
 import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
@@ -143,6 +145,19 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         }
     }
     const nowIso = utcNowIso(now);
+    // #3360: hand-authored briefs run #3323 clause derivation on activate/promote.
+    // #3355: stamp is state-observed (before vs after), not derivation-notice-bound.
+    const previousAcceptance = planObj.acceptance;
+    let derivationNotice = "";
+    if (act === "activate" || act === "promote") {
+        const derivation = applyClauseDerivationToPlan(planObj, {
+            projectRoot,
+            emitStamp: false,
+        });
+        if (derivation.applied) {
+            derivationNotice = derivation.notice;
+        }
+    }
     // #1581: fail closed before activating a scope that still has XL plan items.
     if (act === "activate") {
         const effortGate = evaluateEffortActivateGate(planObj);
@@ -170,7 +185,10 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             return { ok: false, message: gate.message };
         }
         if (gate.provenance !== null) {
-            stampDeliveryProvenance(planObj, gate.provenance);
+            const sessionId = resolveCompletionSessionId(projectRoot);
+            stampDeliveryProvenance(planObj, sessionId !== null
+                ? { ...gate.provenance, completedSessionId: sessionId }
+                : gate.provenance);
         }
     }
     // #3240: per-criterion typed evidence or human-origin disposition before auto-advance.
@@ -207,6 +225,19 @@ export function runTransition(action, filePath, now = new Date(), options = {})
                     ? `${acceptanceListing}\n${literalGate.message}`
                     : literalGate.message;
         }
+        // #3357: verify:ac walk is a hard precondition. Disposition does not skip it.
+        const acWalk = evaluateScopeCompleteAcceptanceWalk(planObj, { projectRoot });
+        if (!acWalk.ok) {
+            return {
+                ok: false,
+                message: acWalk.message,
+                acceptanceReports: acceptanceGate.reports,
+            };
+        }
+        if (acWalk.message.length > 0) {
+            acceptanceListing =
+                acceptanceListing.length > 0 ? `${acceptanceListing}\n${acWalk.message}` : acWalk.message;
+        }
     }
     planObj.status = targetStatus;
     planObj.updated = nowIso;
@@ -218,7 +249,9 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         advanceNonTerminalOwnItems(planObj.items, targetStatus);
     }
     if (act === "complete") {
-        stampCompletionMetadata(planObj, projectRoot, nowIso);
+        stampCompletionMetadata(planObj, projectRoot, nowIso, {
+            completedSessionId: resolveCompletionSessionId(projectRoot),
+        });
         // #3242 / epic #3237 Q4: after reconcile, completed lifecycle must match
         // plan.status=completed and terminal plan.items (compose with #3240).
         const consistency = evaluateCompletedPlanConsistency(planObj, {
@@ -249,6 +282,27 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             return { ok: false, message: writeResult.message };
         }
         crud.recordTrustedUpdate(destPath, formatted);
+        if (act === "complete") {
+            const sessionId = resolveCompletionSessionId(projectRoot);
+            if (sessionId !== null) {
+                try {
+                    writeSessionCompletedMarker(projectRoot, {
+                        path: destPath,
+                        sessionId,
+                        completedAt: nowIso,
+                    });
+                }
+                catch {
+                    try {
+                        unlinkSync(destPath);
+                    }
+                    catch {
+                        /* dest rollback after marker failure */
+                    }
+                    return { ok: false, message: SESSION_COMPLETED_AC_REMEDIATION };
+                }
+            }
+        }
         try {
             unlinkSync(resolvedPath);
         }
@@ -280,7 +334,11 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             };
         }
         syncSpecificationAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
+        if (act === "activate" || act === "promote") {
+            maybeEmitAcceptanceStampFromChange(projectRoot, previousAcceptance, planObj.acceptance);
+        }
         const moveMsg = `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})` +
+            (derivationNotice.length > 0 ? `\n${derivationNotice}` : "") +
             (acceptanceListing.length > 0 ? `\n${acceptanceListing}` : "");
         return {
             ok: true,
@@ -300,7 +358,11 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         /* best-effort telemetry persistence */
     }
     const actionLabel = STAY_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
+    if (act === "activate" || act === "promote") {
+        maybeEmitAcceptanceStampFromChange(projectRoot, previousAcceptance, planObj.acceptance);
+    }
     const stayMsg = `${actionLabel} ${basename}: stays in ${currentFolder}/ (status: ${targetStatus})` +
+        (derivationNotice.length > 0 ? `\n${derivationNotice}` : "") +
         (acceptanceListing.length > 0 ? `\n${acceptanceListing}` : "");
     return {
         ok: true,

package/dist/session/ceremony-dial-evidence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Consumer-environment evidence for ceremony-dial escalation (#3358).
+ *
+ * Session:start left `taskSize` and `modelTier` null unless CLI flags or
+ * provisional env/verb/file hints were set. Consumer runs then always
+ * declined with "insufficient evidence (size=- modelTier=-)".
+ *
+ * This module fills at least one input the consumer environment can supply:
+ *   1. stamped #3323 clause count on active/pending briefs (size proxy)
+ *   2. host-supplied model-tier env (`DEFT_HOST_MODEL_TIER` and aliases)
+ *   3. failing-gate count env (mid-session size proxy)
+ *
+ * ⊗ Change the rapid default or decline threshold when no evidence exists.
+ * Explicit CLI / session inputs still win at the merge site.
+ */
+import { type CeremonyDialInputs, type CeremonyModelTier, type CeremonyTaskSize } from "../policy/ceremony-dial.js";
+/** Host-supplied model-tier hint when `DEFT_CEREMONY_MODEL_TIER` is unset. */
+export declare const ENV_HOST_MODEL_TIER = "DEFT_HOST_MODEL_TIER";
+/** Mid-session failing-gate count the consumer/harness can supply. */
+export declare const ENV_FAILING_GATE_COUNT = "DEFT_FAILING_GATE_COUNT";
+export interface CeremonyDialConsumerEvidence {
+    readonly taskSize: CeremonyTaskSize | null;
+    readonly modelTier: CeremonyModelTier | null;
+    readonly clauseCount: number | null;
+    readonly failingGateCount: number | null;
+    readonly reasons: readonly string[];
+}
+export declare function taskSizeFromClauseCount(count: number): CeremonyTaskSize | null;
+export declare function taskSizeFromFailingGateCount(count: number): CeremonyTaskSize | null;
+/** Max stamped clause count across `xbrief/{active,pending}` (#3323). */
+export declare function readStampedClauseCount(projectRoot: string): {
+    readonly count: number;
+    readonly source: string;
+} | null;
+export declare function collectCeremonyDialConsumerEvidence(projectRoot: string, options?: {
+    readonly env?: NodeJS.ProcessEnv;
+}): CeremonyDialConsumerEvidence;
+/** Explicit non-null wins; consumer evidence fills only missing fields. */
+export declare function mergeCeremonyDialInputsWithConsumerEvidence(explicit: CeremonyDialInputs | undefined, evidence: CeremonyDialConsumerEvidence): CeremonyDialInputs;
+export declare function formatCeremonyDialEvidenceLine(evidence: CeremonyDialConsumerEvidence): string | null;
+export declare function ceremonyDialEvidenceToDict(evidence: CeremonyDialConsumerEvidence): Record<string, unknown>;
+//# sourceMappingURL=ceremony-dial-evidence.d.ts.map

package/dist/session/ceremony-dial-evidence.js

@@ -0,0 +1,194 @@
+/**
+ * Consumer-environment evidence for ceremony-dial escalation (#3358).
+ *
+ * Session:start left `taskSize` and `modelTier` null unless CLI flags or
+ * provisional env/verb/file hints were set. Consumer runs then always
+ * declined with "insufficient evidence (size=- modelTier=-)".
+ *
+ * This module fills at least one input the consumer environment can supply:
+ *   1. stamped #3323 clause count on active/pending briefs (size proxy)
+ *   2. host-supplied model-tier env (`DEFT_HOST_MODEL_TIER` and aliases)
+ *   3. failing-gate count env (mid-session size proxy)
+ *
+ * ⊗ Change the rapid default or decline threshold when no evidence exists.
+ * Explicit CLI / session inputs still win at the merge site.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ENV_CEREMONY_MODEL_HINT, ENV_CEREMONY_MODEL_TIER, normalizeCeremonyModelTier, } from "../policy/ceremony-dial.js";
+/** Host-supplied model-tier hint when `DEFT_CEREMONY_MODEL_TIER` is unset. */
+export const ENV_HOST_MODEL_TIER = "DEFT_HOST_MODEL_TIER";
+/** Mid-session failing-gate count the consumer/harness can supply. */
+export const ENV_FAILING_GATE_COUNT = "DEFT_FAILING_GATE_COUNT";
+const LIFECYCLE_DIRS = ["active", "pending"];
+export function taskSizeFromClauseCount(count) {
+    if (!Number.isFinite(count) || count <= 0)
+        return null;
+    if (count === 1)
+        return "S";
+    if (count <= 3)
+        return "M";
+    if (count <= 6)
+        return "L";
+    return "XL";
+}
+export function taskSizeFromFailingGateCount(count) {
+    if (!Number.isFinite(count) || count <= 0)
+        return null;
+    if (count <= 2)
+        return "M";
+    return "L";
+}
+function rankSize(size) {
+    switch (size) {
+        case "S":
+            return 0;
+        case "M":
+            return 1;
+        case "L":
+            return 2;
+        case "XL":
+            return 3;
+    }
+}
+function maxSize(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return rankSize(a) >= rankSize(b) ? a : b;
+}
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function clauseCountFromBrief(raw) {
+    const root = asRecord(raw);
+    const plan = asRecord(root?.plan);
+    const acceptance = asRecord(plan?.acceptance);
+    if (acceptance === null)
+        return null;
+    if (Array.isArray(acceptance.clauses) && acceptance.clauses.length > 0) {
+        return acceptance.clauses.length;
+    }
+    const stamped = acceptance.clause_count;
+    if (typeof stamped === "number" && Number.isFinite(stamped) && stamped > 0) {
+        return stamped;
+    }
+    return null;
+}
+function parseNonNegativeInt(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) {
+        return Math.trunc(raw);
+    }
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    const n = Number(trimmed);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    return Math.trunc(n);
+}
+/** Max stamped clause count across `xbrief/{active,pending}` (#3323). */
+export function readStampedClauseCount(projectRoot) {
+    let best = null;
+    for (const dir of LIFECYCLE_DIRS) {
+        const folder = join(projectRoot, "xbrief", dir);
+        if (!existsSync(folder))
+            continue;
+        let names = [];
+        try {
+            names = readdirSync(folder);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.endsWith(".xbrief.json") || name === "PROJECT-DEFINITION.xbrief.json") {
+                continue;
+            }
+            const path = join(folder, name);
+            try {
+                const parsed = JSON.parse(readFileSync(path, "utf8"));
+                const count = clauseCountFromBrief(parsed);
+                if (count === null)
+                    continue;
+                if (best === null || count > best.count) {
+                    best = { count, source: `xbrief/${dir}/${name}` };
+                }
+            }
+            catch {
+                // fail-open — a malformed brief is not an evidence source
+            }
+        }
+    }
+    return best;
+}
+export function collectCeremonyDialConsumerEvidence(projectRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const reasons = [];
+    const stamped = readStampedClauseCount(projectRoot);
+    const clauseCount = stamped?.count ?? null;
+    let taskSize = null;
+    if (stamped !== null) {
+        const fromClauses = taskSizeFromClauseCount(stamped.count);
+        if (fromClauses !== null) {
+            taskSize = fromClauses;
+            reasons.push(`taskSize=${fromClauses} from stamped clauseCount=${stamped.count} (${stamped.source})`);
+        }
+    }
+    const failingGateCount = parseNonNegativeInt(env[ENV_FAILING_GATE_COUNT]);
+    if (failingGateCount !== null) {
+        const fromGates = taskSizeFromFailingGateCount(failingGateCount);
+        if (fromGates !== null) {
+            const next = maxSize(taskSize, fromGates);
+            if (next !== taskSize) {
+                taskSize = next;
+                reasons.push(`taskSize=${next} from failingGateCount=${failingGateCount}`);
+            }
+            else if (taskSize === fromGates) {
+                reasons.push(`failingGateCount=${failingGateCount} (size already ${taskSize})`);
+            }
+        }
+    }
+    const modelTier = normalizeCeremonyModelTier(env[ENV_CEREMONY_MODEL_TIER]) ??
+        normalizeCeremonyModelTier(env[ENV_CEREMONY_MODEL_HINT]) ??
+        normalizeCeremonyModelTier(env[ENV_HOST_MODEL_TIER]);
+    if (modelTier !== null) {
+        reasons.push(`modelTier=${modelTier} from host env`);
+    }
+    return {
+        taskSize,
+        modelTier,
+        clauseCount,
+        failingGateCount,
+        reasons,
+    };
+}
+/** Explicit non-null wins; consumer evidence fills only missing fields. */
+export function mergeCeremonyDialInputsWithConsumerEvidence(explicit, evidence) {
+    return {
+        taskSize: explicit?.taskSize ?? evidence.taskSize ?? null,
+        modelTier: explicit?.modelTier ?? evidence.modelTier ?? null,
+        projectShape: explicit?.projectShape ?? null,
+    };
+}
+export function formatCeremonyDialEvidenceLine(evidence) {
+    if (evidence.reasons.length === 0)
+        return null;
+    return `[deft ceremony-dial] evidence: ${evidence.reasons.join("; ")}`;
+}
+export function ceremonyDialEvidenceToDict(evidence) {
+    return {
+        taskSize: evidence.taskSize,
+        modelTier: evidence.modelTier,
+        clauseCount: evidence.clauseCount,
+        failingGateCount: evidence.failingGateCount,
+        reasons: [...evidence.reasons],
+    };
+}
+//# sourceMappingURL=ceremony-dial-evidence.js.map

package/dist/session/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./ac-pass-banking.js";
 export * from "./active-cli.js";
+export * from "./ceremony-dial-evidence.js";
 export * from "./compact-ritual.js";
 export * from "./deposit-sha.js";
 export * from "./effort-budget.js";

package/dist/session/index.js

@@ -1,5 +1,6 @@
 export * from "./ac-pass-banking.js";
 export * from "./active-cli.js";
+export * from "./ceremony-dial-evidence.js";
 export * from "./compact-ritual.js";
 export * from "./deposit-sha.js";
 export * from "./effort-budget.js";

package/dist/session/session-start.js

@@ -23,6 +23,7 @@ import { runDefaultMode } from "../triage/welcome/default-mode.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { emitSessionValueReadback } from "../value/readback.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
+import { ceremonyDialEvidenceToDict, collectCeremonyDialConsumerEvidence, formatCeremonyDialEvidenceLine, mergeCeremonyDialInputsWithConsumerEvidence, } from "./ceremony-dial-evidence.js";
 import { effortBudgetToDict, maybeFormatEffortBudgetLines, resolveProductionHostEffortDescriptor, } from "./effort-budget.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
 import { runOrientationCompression, } from "./orientation-compression.js";
@@ -801,7 +802,16 @@ export function runSessionStart(projectRoot, options = {}) {
     // missing size/tier/shape from env/verb/files/deposit BEFORE resolve — never
     // block on plan-item effort (post-planning only). Cold incomplete size is
     // tier-conditional (#3263): mid/low → standard; frontier/unknown → rapid.
-    const { inputs: resolvedDialInputs, provisional: provisionalDial } = resolveSessionCeremonyDialInputs(projectRoot, options.ceremonyDialInputs, {
+    // #3358: fill at least one consumer-supplied input (stamped clause count,
+    // host-tier env, failing-gate count) so evaluation is not permanently
+    // size=- / modelTier=-. ⊗ Change rapid default when no evidence exists.
+    const consumerDialEvidence = collectCeremonyDialConsumerEvidence(projectRoot, {
+        env: options.env,
+    });
+    const dialInputsWithEvidence = options.ceremonyDial === undefined
+        ? mergeCeremonyDialInputsWithConsumerEvidence(options.ceremonyDialInputs, consumerDialEvidence)
+        : (options.ceremonyDialInputs ?? {});
+    const { inputs: resolvedDialInputs, provisional: provisionalDial } = resolveSessionCeremonyDialInputs(projectRoot, dialInputsWithEvidence, {
         ...options.ceremonyDialHints,
         env: options.env,
     });
@@ -850,6 +860,10 @@ export function runSessionStart(projectRoot, options = {}) {
     if (provisionalDial.reasons.length > 0 && options.ceremonyDial === undefined) {
         lines.push(`[deft ceremony-dial] provisional: ${provisionalDial.reasons.join("; ")}`);
     }
+    const evidenceLine = formatCeremonyDialEvidenceLine(consumerDialEvidence);
+    if (evidenceLine !== null && options.ceremonyDial === undefined) {
+        lines.push(evidenceLine);
+    }
     // Resolve USER.md via the shared first-hit-wins resolver so the alignment
     // step finds preferences automatically in mismatched / headless sandboxes
     // with zero manual DEFT_USER_PATH (#2271 / #2124). Never throws: an absent
@@ -1211,6 +1225,7 @@ export function runSessionStart(projectRoot, options = {}) {
             projectShape: provisionalDial.projectShape,
             reasons: [...provisionalDial.reasons],
         },
+        consumer_evidence: ceremonyDialEvidenceToDict(consumerDialEvidence),
     };
     const preflightDict = toolchainPreflightResult !== null ? toolchainPreflightToDict(toolchainPreflightResult) : null;
     const payload = {
@@ -1283,7 +1298,11 @@ export function runSessionStart(projectRoot, options = {}) {
                     }
                     : {}),
             });
-            emitter.emitKnownToolTurnDenominator();
+            // #3356: always emit a denominator when the destination is live so
+            // share = ritual_events / denominator is computable from the stream.
+            // Prefer DEFT_TOTAL_TOOL_TURNS, then DEFT_MAX_TURNS / host maxTurns,
+            // else this session:start CLI invocation (1).
+            emitter.emitSessionToolTurnDenominator(effortBudget.budget.maxTurns);
             // #3319: evaluate escalate-on-evidence only when #3274 is live. A pin
             // emits nothing so never-evaluated stays distinguishable from declined.
             if (!isCeremonyStartTierPinned(startTierProvenance)) {

package/dist/slice/existing.js

@@ -1,3 +1,4 @@
+import { ContainedWriteError } from "../fs/contained-write.js";
 import { call as scmCall } from "../scm/call.js";
 import { pyRepr } from "../scm/py-format.js";
 import { DEFAULT_ACTOR, DEFAULT_EXPECTED_CLOSE_SIGNAL, DEFAULT_ROLE, WAVE_FLAG_RE, } from "./constants.js";
@@ -278,7 +279,10 @@ export function runRecordExisting(args, waveMap, deps = {}) {
             if (authoritativeDup !== null && !args.force) {
                 return { kind: "duplicate", duplicate: authoritativeDup };
             }
-            const id = writeSliceUnlocked(record, { path: logPath });
+            const id = writeSliceUnlocked(record, {
+                path: logPath,
+                projectRoot: resolved.projectRoot,
+            });
             return { kind: "written", sliceId: id };
         });
         if (outcome.kind === "duplicate") {
@@ -301,6 +305,13 @@ export function runRecordExisting(args, waveMap, deps = {}) {
         if (err instanceof SliceRecordError) {
             return { exitCode: 1, stdout: "", stderr: `error: invalid record -- ${err.message}\n` };
         }
+        if (err instanceof ContainedWriteError) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `error: refused slices.jsonl write -- ${err.message}\n`,
+            };
+        }
         throw err;
     }
 }

package/dist/slice/record.d.ts

@@ -1,4 +1,4 @@
-import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { withAppendLock } from "./lock.js";
 export interface WriteSliceOptions {
     readonly umbrellaUrl: string;
@@ -14,13 +14,15 @@ export interface WriteSliceOptions {
 export interface RecordModuleDeps {
     readonly readFile?: typeof readFileSync;
     readonly exists?: typeof existsSync;
-    readonly append?: typeof appendFileSync;
-    readonly fsync?: typeof fsyncSync;
-    readonly open?: typeof openSync;
-    readonly close?: typeof closeSync;
     readonly mkdir?: typeof mkdirSync;
     readonly withLock?: typeof withAppendLock;
 }
+/**
+ * Containment root for slices.jsonl append (#3354 / #3288).
+ * Prefer `projectRoot` when the log is nested under it so out-of-tree dests refuse.
+ * Otherwise use the log parent (still refuses leaf symlink follow).
+ */
+export declare function containmentRootForSliceLog(logPath: string, projectRoot?: string): string;
 export declare function newSliceId(): string;
 /** Return the current UTC time in canonical ISO-8601 form with Z suffix (no fractional seconds). */
 export declare function nowIso(): string;
@@ -29,6 +31,7 @@ export declare function writeSliceUnlocked(record: Record<string, unknown>, opti
     path?: string;
     deps?: RecordModuleDeps;
     warn?: (message: string) => void;
+    projectRoot?: string;
 }): string;
 /** Validate and atomically append a cohort record to slices.jsonl. */
 export declare function writeSlice(umbrella: number, children: Iterable<Record<string, unknown>>, options: WriteSliceOptions, deps?: RecordModuleDeps): string;

package/dist/slice/record.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { resolveTriageCachePath } from "../triage/cache-path.js";
 import { pythonJsonStringify } from "./json.js";
 import { withAppendLock } from "./lock.js";
@@ -8,13 +9,20 @@ import { validateRecord } from "./validate.js";
 const defaultDeps = {
     readFile: readFileSync,
     exists: existsSync,
-    append: appendFileSync,
-    fsync: fsyncSync,
-    open: openSync,
-    close: closeSync,
     mkdir: mkdirSync,
     withLock: withAppendLock,
 };
+/**
+ * Containment root for slices.jsonl append (#3354 / #3288).
+ * Prefer `projectRoot` when the log is nested under it so out-of-tree dests refuse.
+ * Otherwise use the log parent (still refuses leaf symlink follow).
+ */
+export function containmentRootForSliceLog(logPath, projectRoot) {
+    if (projectRoot !== undefined) {
+        return resolve(projectRoot);
+    }
+    return resolve(dirname(logPath));
+}
 function resolvePath(path) {
     return path !== undefined ? resolve(path) : resolveTriageCachePath(process.cwd(), "slices.jsonl");
 }
@@ -64,14 +72,14 @@ export function writeSliceUnlocked(record, options = {}) {
         return resolvedId;
     }
     const line = `${pythonJsonStringify(record)}\n`;
-    deps.append(logPath, line, { encoding: "utf8" });
-    const fd = deps.open(logPath, "a");
-    try {
-        deps.fsync(fd);
-    }
-    finally {
-        deps.close(fd);
-    }
+    const root = containmentRootForSliceLog(logPath, options.projectRoot);
+    deps.mkdir(root, { recursive: true });
+    containedWrite({
+        root,
+        target: logPath,
+        data: line,
+        mode: "append",
+    });
     return resolvedId;
 }
 /** Validate and atomically append a cohort record to slices.jsonl. */

package/dist/telemetry-coverage/evaluate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * verify:telemetry-coverage — dead-surface detector (#3362).
+ *
+ * Two checks, one remediation that names the missing half:
+ *  1. Every RUN_SUMMARY_EVENT_KINDS member (and exported emitter method)
+ *     has a production caller outside the emitter module.
+ *  2. Every kind is enrolled, has a trial step, and appears in a run of
+ *     the shared fake-trial harness JSONL.
+ *
+ * Default is warn-only (exit 0). Pass --enforce to fail closed.
+ */
+import { type FakeTrialResult } from "./fake-trial.js";
+export interface TelemetryCoverageFinding {
+    readonly subject: string;
+    readonly missingCaller: boolean;
+    readonly missingFixture: boolean;
+    readonly remediation: string;
+}
+export interface TelemetryCoverageOptions {
+    readonly projectRoot: string;
+    readonly enforce?: boolean;
+    readonly scanRoots?: readonly string[];
+    readonly kinds?: readonly string[];
+    readonly enrolledKinds?: readonly string[];
+    /** Override trial-step kinds (tests). Default: DEFAULT_TRIAL_STEPS. */
+    readonly trialKinds?: readonly string[];
+    /** Skip running the fake trial (unit tests). Production default is to run it. */
+    readonly skipTrial?: boolean;
+    /** Injected trial result (tests). */
+    readonly trialResult?: Pick<FakeTrialResult, "presentKinds" | "stepOutcomes">;
+}
+export interface TelemetryCoverageResult {
+    readonly code: number;
+    readonly message: string;
+    readonly stream: "stdout" | "stderr";
+    readonly findings: readonly TelemetryCoverageFinding[];
+    readonly enforce: boolean;
+    readonly failOpen: boolean;
+}
+export declare function remediationFor(subject: string, missingCaller: boolean, missingFixture: boolean): string;
+export declare function evaluateTelemetryCoverage(options: TelemetryCoverageOptions): TelemetryCoverageResult;
+//# sourceMappingURL=evaluate.d.ts.map