@deftai/directive-core 0.69.0 → 0.71.0

package/dist/policy/value-feedback.js

@@ -0,0 +1,284 @@
+import { readFileSync } from "node:fs";
+import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
+import { appendAuditLog, loadProjectDefinition, projectDefinitionPath } from "./resolve.js";
+/** Canonical registered policy field name (matches other FIELD_* dotted paths). */
+export const FIELD_VALUE_FEEDBACK = "plan.policy.valueFeedback";
+/** Short alias accepted by `policy:show --field=valueFeedback` (#1709). */
+export const FIELD_VALUE_FEEDBACK_CLI_ALIAS = "valueFeedback";
+export const DEFAULT_VALUE_FEEDBACK_ENABLED = false;
+/** Sub-flag defaults applied when the master flag is enabled (#1709 tiered-cost decision). */
+export const VALUE_FEEDBACK_SUBFLAG_DEFAULTS_WHEN_ENABLED = {
+    emitEvents: true,
+    sessionLine: true,
+    upstreamPrompt: false,
+};
+export const VALUE_FEEDBACK_CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost disclosure -- enabling value feedback opts into " +
+    "attributed awareness surfaces that may consume session context and nudge budget.\n" +
+    "  \u2022 Local emit-only ledger writes to the gitignored `.deft-cache/events.jsonl` " +
+    "(no network by default).\n" +
+    "  \u2022 A budgeted session one-liner may appear when concrete attributed value exists.\n" +
+    "  \u2022 Upstream gap-escalation prompts stay OFF unless you explicitly enable " +
+    "`upstreamPrompt` (GitHub attention + token cost).\n" +
+    "  \u2022 Inspect current state: `task policy:show --field=valueFeedback`.\n" +
+    "  \u2022 Reversible: set `enabled: false` under the typed policy block in PROJECT-DEFINITION.\n" +
+    "  \u2022 Changes are recorded to meta/policy-changes.log for auditability.";
+function defaultResolved(source, error = null) {
+    return {
+        enabled: DEFAULT_VALUE_FEEDBACK_ENABLED,
+        emitEvents: false,
+        sessionLine: false,
+        upstreamPrompt: false,
+        source,
+        error,
+    };
+}
+function readSubFlag(block, key, masterEnabled) {
+    if (!masterEnabled) {
+        return false;
+    }
+    if (key in block && typeof block[key] === "boolean") {
+        return block[key];
+    }
+    return VALUE_FEEDBACK_SUBFLAG_DEFAULTS_WHEN_ENABLED[key];
+}
+/** Validate a `plan.policy.valueFeedback` payload. */
+export function validateValueFeedback(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [`${FIELD_VALUE_FEEDBACK} must be an object; got ${typeof value}`];
+    }
+    const rec = value;
+    const errors = [];
+    for (const key of ["enabled", "emitEvents", "sessionLine", "upstreamPrompt"]) {
+        if (key in rec && typeof rec[key] !== "boolean") {
+            errors.push(`${FIELD_VALUE_FEEDBACK}.${key} must be a boolean`);
+        }
+    }
+    return errors;
+}
+function resolveFromPolicyBlock(raw) {
+    const errors = validateValueFeedback(raw);
+    if (errors.length > 0) {
+        return defaultResolved("default-on-error", errors[0] ?? "invalid valueFeedback block");
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return defaultResolved("default");
+    }
+    const block = raw;
+    const enabled = typeof block.enabled === "boolean" ? block.enabled : DEFAULT_VALUE_FEEDBACK_ENABLED;
+    if (!enabled) {
+        return {
+            enabled: false,
+            emitEvents: false,
+            sessionLine: false,
+            upstreamPrompt: false,
+            source: "typed",
+            error: null,
+        };
+    }
+    return {
+        enabled: true,
+        emitEvents: readSubFlag(block, "emitEvents", true),
+        sessionLine: readSubFlag(block, "sessionLine", true),
+        upstreamPrompt: readSubFlag(block, "upstreamPrompt", true),
+        source: "typed",
+        error: null,
+    };
+}
+/** Resolve `plan.policy.valueFeedback` from PROJECT-DEFINITION (#1709). */
+export function resolveValueFeedback(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return defaultResolved("default-on-error", err);
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("valueFeedback" in policyBlock)) {
+        return defaultResolved("default");
+    }
+    return resolveFromPolicyBlock(policyBlock.valueFeedback);
+}
+/** Master gate: when `enabled` is false, every downstream path is rejected. */
+export function isValueFeedbackPathAllowed(path, policy) {
+    if (!policy.enabled) {
+        return false;
+    }
+    return policy[path];
+}
+/** Resolved per-path gate booleans for policy:show and enable status output. */
+export function valueFeedbackPathGates(policy) {
+    return {
+        emitEvents: isValueFeedbackPathAllowed("emitEvents", policy),
+        sessionLine: isValueFeedbackPathAllowed("sessionLine", policy),
+        upstreamPrompt: isValueFeedbackPathAllowed("upstreamPrompt", policy),
+    };
+}
+/** Human-readable status line for CLI enable/show surfaces. */
+export function formatValueFeedbackStatusLine(policy) {
+    const gates = valueFeedbackPathGates(policy);
+    return (`[deft policy] valueFeedback enabled=${String(policy.enabled)} ` +
+        `emitEvents=${String(policy.emitEvents)} (path=${String(gates.emitEvents)}) ` +
+        `sessionLine=${String(policy.sessionLine)} (path=${String(gates.sessionLine)}) ` +
+        `upstreamPrompt=${String(policy.upstreamPrompt)} (path=${String(gates.upstreamPrompt)}).`);
+}
+function defaultInspectorConfig() {
+    const defaults = defaultResolved("default");
+    return {
+        enabled: defaults.enabled,
+        emitEvents: defaults.emitEvents,
+        sessionLine: defaults.sessionLine,
+        upstreamPrompt: defaults.upstreamPrompt,
+    };
+}
+function buildDefaultInspectorField() {
+    return {
+        name: FIELD_VALUE_FEEDBACK,
+        current: defaultInspectorConfig(),
+        default: {
+            enabled: DEFAULT_VALUE_FEEDBACK_ENABLED,
+            emitEvents: false,
+            sessionLine: false,
+            upstreamPrompt: false,
+        },
+        source: "default",
+    };
+}
+/** Inspector row for `policy:show --field=valueFeedback`. */
+export function inspectValueFeedback(data) {
+    if (data === null) {
+        return buildDefaultInspectorField();
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("valueFeedback" in policyBlock)) {
+        return buildDefaultInspectorField();
+    }
+    const resolved = resolveFromPolicyBlock(policyBlock.valueFeedback);
+    return {
+        name: FIELD_VALUE_FEEDBACK,
+        current: {
+            enabled: resolved.enabled,
+            emitEvents: resolved.emitEvents,
+            sessionLine: resolved.sessionLine,
+            upstreamPrompt: resolved.upstreamPrompt,
+        },
+        default: {
+            enabled: DEFAULT_VALUE_FEEDBACK_ENABLED,
+            emitEvents: false,
+            sessionLine: false,
+            upstreamPrompt: false,
+        },
+        source: resolved.source,
+    };
+}
+/** Persist `valueFeedback.enabled=true` after capability-cost disclosure (#1709). */
+export function enableValueFeedback(projectRoot, options) {
+    if (!options.confirm) {
+        return {
+            exitCode: 1,
+            stdout: `${VALUE_FEEDBACK_CAPABILITY_COST_DISCLOSURE}\n\n` +
+                "Re-run with --confirm to apply: task policy:enable-value-feedback -- --confirm\n",
+            changed: false,
+        };
+    }
+    const path = projectDefinitionPath(projectRoot);
+    try {
+        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
+            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+            }
+            const data = parsed;
+            if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
+                if (data.plan === undefined) {
+                    data.plan = {};
+                }
+                else {
+                    throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+                }
+            }
+            const plan = data.plan;
+            migrateLegacyPolicyKey(plan);
+            const existingPolicy = plan[PLAN_POLICY_KEY];
+            if (typeof existingPolicy !== "object" ||
+                existingPolicy === null ||
+                Array.isArray(existingPolicy)) {
+                if (existingPolicy === undefined) {
+                    plan[PLAN_POLICY_KEY] = {};
+                }
+                else {
+                    throw new Error("plan.policy is not an object");
+                }
+            }
+            const policyBlock = plan[PLAN_POLICY_KEY];
+            const previous = policyBlock.valueFeedback;
+            const prevObj = typeof previous === "object" && previous !== null && !Array.isArray(previous)
+                ? previous
+                : {};
+            const sub = options.subFlags ?? {};
+            const readPersistedSubFlag = (key) => {
+                if (key in sub && typeof sub[key] === "boolean") {
+                    return sub[key];
+                }
+                if (key in prevObj && typeof prevObj[key] === "boolean") {
+                    return prevObj[key];
+                }
+                return VALUE_FEEDBACK_SUBFLAG_DEFAULTS_WHEN_ENABLED[key];
+            };
+            const nextBlock = {
+                enabled: true,
+                emitEvents: readPersistedSubFlag("emitEvents"),
+                sessionLine: readPersistedSubFlag("sessionLine"),
+                upstreamPrompt: readPersistedSubFlag("upstreamPrompt"),
+            };
+            const previousNormalized = resolveFromPolicyBlock(previous);
+            const changedFlag = previousNormalized.enabled !== nextBlock.enabled ||
+                previousNormalized.emitEvents !== nextBlock.emitEvents ||
+                previousNormalized.sessionLine !== nextBlock.sessionLine ||
+                previousNormalized.upstreamPrompt !== nextBlock.upstreamPrompt;
+            policyBlock.valueFeedback = nextBlock;
+            if (changedFlag) {
+                atomicWriteProjectDefinition(path, data);
+            }
+            const actor = options.actor ?? "task policy:enable-value-feedback";
+            const note = options.note ?? "";
+            const parts = [
+                `actor=${actor}`,
+                "valueFeedback.enabled=true",
+                `emitEvents=${String(nextBlock.emitEvents)}`,
+                `sessionLine=${String(nextBlock.sessionLine)}`,
+                `upstreamPrompt=${String(nextBlock.upstreamPrompt)}`,
+                `previous=${JSON.stringify(previous ?? null)}`,
+            ];
+            if (note) {
+                parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
+            }
+            appendAuditLog(projectRoot, parts.join(" "));
+            return { changed: changedFlag };
+        });
+        const resolved = resolveValueFeedback(projectRoot);
+        const lines = [
+            `\u2713 ${FIELD_VALUE_FEEDBACK}.enabled=true (value-feedback ON).`,
+            changed
+                ? "  audit: meta/policy-changes.log updated."
+                : "  no-op: value already matched (audit entry still appended for trail).",
+            formatValueFeedbackStatusLine(resolved),
+        ];
+        return { exitCode: 0, stdout: `${lines.join("\n")}\n`, changed };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("PROJECT-DEFINITION not found")) {
+            return { exitCode: 2, stdout: `\u274c ${message}\n`, changed: false };
+        }
+        return { exitCode: 2, stdout: `\u274c Config error: ${message}\n`, changed: false };
+    }
+}
+//# sourceMappingURL=value-feedback.js.map

package/dist/policy/wip.d.ts

@@ -1,5 +1,5 @@
-/** Framework default WIP cap (#1124 / umbrella #1119). */
-export declare const DEFAULT_WIP_CAP = 10;
+/** Framework default WIP cap (#2319; raised from 10 per #1124 / umbrella #1119). */
+export declare const DEFAULT_WIP_CAP = 20;
 /** vBRIEF lifecycle folders that count toward the WIP set. */
 export declare const WIP_LIFECYCLE_DIRS: readonly ["pending", "active"];
 export type WipCapSource = "typed" | "default" | "default-on-error";

package/dist/policy/wip.js

@@ -3,8 +3,8 @@ import { join } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { readPlanPolicy } from "./plan-extensions.js";
 import { loadProjectDefinition } from "./resolve.js";
-/** Framework default WIP cap (#1124 / umbrella #1119). */
-export const DEFAULT_WIP_CAP = 10;
+/** Framework default WIP cap (#2319; raised from 10 per #1124 / umbrella #1119). */
+export const DEFAULT_WIP_CAP = 20;
 /** vBRIEF lifecycle folders that count toward the WIP set. */
 export const WIP_LIFECYCLE_DIRS = ["pending", "active"];
 function pythonTypeName(value) {

package/dist/preflight-cache/evaluate.js

@@ -14,15 +14,16 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 import { probeCacheDrift } from "../cache/fetch.js";
-import { resolveEvalPath, resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { latestDecisionForIssue as auditLatestDecisionForIssue } from "../triage/actions/candidates-log.js";
+import { resolveCandidatesLogPath } from "../triage/cache-path.js";
 // ---------------------------------------------------------------------------
 // Public constants (mirror preflight_cache.py)
 // ---------------------------------------------------------------------------
 export const CACHE_DIR_NAME = ".deft-cache";
 export const DEFAULT_SOURCE = "github-issue";
-export const CANDIDATES_RELPATH = join("vbrief", ".eval", "candidates.jsonl");
+export const CANDIDATES_RELPATH = join("vbrief", ".triage-cache", "candidates.jsonl");
 export const DEFAULT_MAX_AGE_HOURS = 24;
 export const ENV_MAX_AGE_HOURS = "DEFT_CACHE_MAX_AGE_HOURS";
 export const ENV_TRIAGE_REPO = "DEFT_TRIAGE_REPO";
@@ -335,7 +336,7 @@ export function evaluate(projectRoot, options = {}) {
         DEFAULT_MAX_AGE_HOURS;
     const cacheRoot = join(projectRoot, CACHE_DIR_NAME);
     // Layout-aware (#2109 part 2a): resolve under xbrief/.eval when migrated.
-    const candidatesPath = resolveEvalPath(projectRoot, "candidates.jsonl");
+    const candidatesPath = resolveCandidatesLogPath(projectRoot);
     // Step 1: Resolve repo slug
     const resolvedRepo = resolveRepo(projectRoot, cacheRoot, source, options.repo ?? null);
     // Step 2: Check cache dir exists

package/dist/scope/audit-log.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { resolveEvalPath } from "../layout/resolve.js";
+import { resolveTriageCachePath } from "../triage/cache-path.js";
 import { utcNowIso } from "./vbrief-json.js";
 export class ScopeAuditLogError extends Error {
     constructor(message) {
@@ -94,8 +94,8 @@ export function newDecisionId() {
     return randomUUID();
 }
 export function canonicalLogPath(projectRoot) {
-    // Layout-aware (#2109 part 2a): xbrief/.eval when migrated, else vbrief/.eval.
-    return resolveEvalPath(resolve(projectRoot), "scope-lifecycle.jsonl");
+    // Layout-aware (#1703): triage working-set under `.triage-cache/`.
+    return resolveTriageCachePath(resolve(projectRoot), "scope-lifecycle.jsonl");
 }
 function withAppendLock(logPath, fn) {
     const lockPath = `${logPath}.lock`;

package/dist/scope/transition.js

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemetry.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
 import { stampCompletionMetadata } from "./capacity-stamp.js";
@@ -78,14 +79,24 @@ export function runTransition(action, filePath, now = new Date()) {
     const nowIso = utcNowIso(now);
     planObj.status = targetStatus;
     planObj.updated = nowIso;
+    const vbriefRoot = dirname(dirname(resolvedPath));
+    const projectRoot = dirname(vbriefRoot);
     if (act === "complete") {
-        const vbriefRoot = dirname(dirname(resolvedPath));
-        const projectRoot = dirname(vbriefRoot);
         stampCompletionMetadata(planObj, projectRoot, nowIso);
     }
-    writeFileSync(resolvedPath, formatVbriefJson(data), "utf8");
+    const formatted = formatVbriefJson(data);
+    const crud = new InstrumentedVbriefCrud({ now: () => now });
+    const writeResult = crud.update(resolvedPath, formatted, { trustedWrite: true });
+    if (!writeResult.ok) {
+        return { ok: false, message: writeResult.error ?? `CRUD update failed for ${resolvedPath}` };
+    }
+    try {
+        persistCrudMetrics(projectRoot, crud.getMetrics());
+    }
+    catch {
+        /* best-effort telemetry persistence */
+    }
     if (targetFolder !== null) {
-        const vbriefRoot = dirname(dirname(resolvedPath));
         const destDir = join(vbriefRoot, targetFolder);
         mkdirSync(destDir, { recursive: true });
         const destPath = join(destDir, basename);

package/dist/session/session-start.js

@@ -1,10 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
+import { emitSessionEvalReadback } from "../eval/readback.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
 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 { defaultGitRunner, gitHead, worktreePath } from "./git.js";
 import { newRitualStatePayload, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
@@ -289,6 +291,24 @@ export function runSessionStart(projectRoot, options = {}) {
     if (!runningInsideDeftRepo(projectRoot) && shouldEmitMigrateNudge(projectRoot)) {
         lines.push(MIGRATE_COMPLETION_NUDGE);
     }
+    try {
+        emitSessionValueReadback(projectRoot, {
+            output: (line) => lines.push(line),
+            writeHistory: options.writeHistory !== false,
+        });
+    }
+    catch {
+        // observability only — session start must not abort on transient readback I/O
+    }
+    try {
+        emitSessionEvalReadback(projectRoot, {
+            output: (line) => lines.push(line),
+            writeHistory: options.writeHistory !== false,
+        });
+    }
+    catch {
+        // observability only — session start must not abort on transient eval readback I/O
+    }
     const payload = newRitualStatePayload({
         sessionId: (options.newSessionId ?? randomUUID)(),
         gitHead: gitHeadValue,

package/dist/slice/record.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { resolveEvalPath } from "../layout/resolve.js";
+import { resolveTriageCachePath } from "../triage/cache-path.js";
 import { pythonJsonStringify } from "./json.js";
 import { withAppendLock } from "./lock.js";
 import { validateRecord } from "./validate.js";
@@ -16,7 +16,7 @@ const defaultDeps = {
     withLock: withAppendLock,
 };
 function resolvePath(path) {
-    return path !== undefined ? resolve(path) : resolveEvalPath(process.cwd(), "slices.jsonl");
+    return path !== undefined ? resolve(path) : resolveTriageCachePath(process.cwd(), "slices.jsonl");
 }
 export function newSliceId() {
     return randomUUID();
@@ -134,6 +134,6 @@ export function findByUmbrella(umbrella, options = {}) {
     return readAll(options).filter((record) => record.umbrella === umbrella);
 }
 export function slicesPath(projectRoot) {
-    return resolveEvalPath(projectRoot, "slices.jsonl");
+    return resolveTriageCachePath(projectRoot, "slices.jsonl");
 }
 //# sourceMappingURL=record.js.map

package/dist/swarm/routing.js

@@ -186,7 +186,9 @@ export function resolveDispatchProvider(environ = process.env) {
  * Keys that would mutate the prototype chain rather than set an own property
  * if used as a computed object key. Rejected for provider/role names so a
  * malicious routing input cannot pollute `Object.prototype` (CodeQL
- * js/prototype-polluting-assignment).
+ * js/prototype-polluting-assignment). This validation guard produces the
+ * caller-facing error; the null-prototype write targets in
+ * `writeModelDecision` are the structural backstop CodeQL recognizes.
  */
 const FORBIDDEN_ROUTING_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 function assertSafeRoutingKey(kind, key) {
@@ -203,9 +205,14 @@ export function writeModelDecision(path, provider, role, decision) {
     assertSafeRoutingKey("provider", provider);
     assertSafeRoutingKey("role", role);
     const { data } = loadRoutingFile(path);
-    const file = data ?? {};
+    // Null-prototype write targets so a computed provider/role key can only ever
+    // set an own property and can never reach `Object.prototype`, even if the
+    // validation guard above regresses. CodeQL's js/prototype-polluting-assignment
+    // barrier does not track the interprocedural `assertSafeRoutingKey` guard, so
+    // this structural sink is what closes alert #52.
+    const file = Object.assign(Object.create(null), data ?? {});
     const existing = providerBlockOf(file, provider);
-    const block = existing ?? {};
+    const block = Object.assign(Object.create(null), existing ?? {});
     block[role] = {
         model: decision.model,
         mode: decision.mode ??

package/dist/triage/actions/candidates-log.d.ts

@@ -1,8 +1,8 @@
+import { resolveCandidatesLogPath } from "../cache-path.js";
 import type { AuditEntry, CandidatesLog } from "./types.js";
-/** Display/back-compat constant; resolution flows through resolveEvalPath (#2109). */
-export declare const AUDIT_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
-/** Layout-aware candidates audit-log path (xbrief when migrated, else vbrief). */
-export declare function resolveCandidatesLogPath(projectRoot: string): string;
+/** Display/back-compat constant; resolution flows through resolveTriageCachePath (#1703). */
+export declare const AUDIT_LOG_REL_PATH = "vbrief/.triage-cache/candidates.jsonl";
+export { resolveCandidatesLogPath };
 /** Read every well-formed audit-log row in insertion order (#1698 shared reader). */
 export declare function readAuditLog(logPath: string, repo?: string | null): AuditEntry[];
 /** Return every entry for ``(repo, issue_number)`` in insertion order. */

package/dist/triage/actions/candidates-log.js

@@ -1,14 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { resolveEvalPath } from "../../layout/resolve.js";
+import { resolveCandidatesLogPath, TRIAGE_CANDIDATES_LOG_REL_PATH } from "../cache-path.js";
 import { CandidatesLogError } from "./errors.js";
-/** Display/back-compat constant; resolution flows through resolveEvalPath (#2109). */
-export const AUDIT_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
-/** Layout-aware candidates audit-log path (xbrief when migrated, else vbrief). */
-export function resolveCandidatesLogPath(projectRoot) {
-    return resolveEvalPath(projectRoot, "candidates.jsonl");
-}
+/** Display/back-compat constant; resolution flows through resolveTriageCachePath (#1703). */
+export const AUDIT_LOG_REL_PATH = TRIAGE_CANDIDATES_LOG_REL_PATH;
+export { resolveCandidatesLogPath };
 const VALID_DECISIONS = new Set([
     "accept",
     "reject",

package/dist/triage/bootstrap/gitignore.d.ts

@@ -1,16 +1,20 @@
 import type { StepOutcome } from "./types.js";
 export declare const GITIGNORE_LINE = ".deft-cache/";
 export declare const GITIGNORE_DEFT_RUNTIME_SENTINELS: readonly string[];
+/** Legacy static vbrief paths kept for tests referencing the pre-#1703 constant shape. */
 export declare const GITIGNORE_EVAL_ENTRIES: readonly string[];
-export declare const GITATTRIBUTES_EVAL_RULE = "vbrief/.eval/*.jsonl  merge=union";
+/** Layout-aware gitignore lines for triage working-set files (#1703). */
+export declare function gitignoreTriageCacheEntries(projectRoot: string): readonly string[];
+export declare function gitattributesTriageCacheGlob(projectRoot: string): string;
+export declare const GITATTRIBUTES_EVAL_RULE = "vbrief/.triage-cache/*.jsonl  merge=union";
 export declare const FORBIDDEN_BLANKET_EVAL_LINES: readonly string[];
-export declare const EVAL_README_BODY = "# `vbrief/.eval/` -- triage + slicing evaluation artefacts\n\nThis directory holds the append-only JSON-lines logs that the triage and\nslicing skills emit. The framework governs which files in here are tracked\nby git versus gitignored using a **hybrid policy** (#1144, child of #1119).\n\n## Tracking policy\n\n| File | Tracked? | Why |\n| --- | --- | --- |\n| `slices.jsonl` | Yes -- **committed** | Team-shared cohort records produced by slicing skills (D13 / #1132). New operators joining the team need to see prior cohort outputs to detect orphans and avoid re-slicing the same scope. |\n| `candidates.jsonl` | No -- **gitignored** | Operator-private triage decisions (#845 Story 2). Each operator's local accept / defer / reject stream is per-machine state; sharing it would conflate operators' timing + identity across the team. Re-derive on a fresh clone via `task triage:bootstrap`. |\n| `summary-history.jsonl` | No -- **gitignored** | Operator-private observability for `task triage:summary` output time-series. Not load-bearing for any decision. |\n| `scope-lifecycle.jsonl` | No -- **gitignored** | Operator-private scope-lifecycle audit decisions (D1 / #1121). Each demote (`task scope:demote`) appends one entry including a `demote_meta` block (`was_promoted`, `original_promotion_decision_id`, `days_in_pending`, `demote_reason`, `demoted_from`). Per-operator stream; sharing would conflate operators' demote timing across the team. Lightweight metrics over this log are tracked separately at #1180. |\n| `decompositions/` | No -- **gitignored** | Temporary story-decomposition proposal drafts. These JSON drafts are local scratch artifacts, not vBRIEFs; generated child story vBRIEFs are created by `task scope:decompose` in lifecycle folders, defaulting to `vbrief/pending/`. |\n| `doctor-state.json` | No -- **gitignored** | Per-machine `task doctor` throttle state (last exit code + timestamps) persisted to gate the 24h/4h re-probe window (#1308 / #1464). Local to each clone; never committed. |\n\nThe gitignore lines live in the repo-root `.gitignore` (`vbrief/.eval/candidates.jsonl`,\n`vbrief/.eval/summary-history.jsonl`, `vbrief/.eval/scope-lifecycle.jsonl`,\n`vbrief/.eval/decompositions/`, and `vbrief/.eval/doctor-state.json`). All paths\nnot listed above remain committed by default.\n\n## Fresh-clone regeneration\n\nOn a fresh clone (or any machine that has never run triage), `candidates.jsonl`\nis absent. Regenerate it with:\n\n```\ntask triage:bootstrap\n```\n\nThe bootstrap path detects the missing file, runs the auto-classifier, and\nwrites a fresh `vbrief/.eval/candidates.jsonl`. It does NOT touch the tracked\n`slices.jsonl`; cohort records remain a team-shared resource.\n\n## `merge=union` policy for `*.jsonl`\n\nThe repo-root `.gitattributes` declares:\n\n```\nvbrief/.eval/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on\nauto-merge, so two branches that each appended a different record to the\nsame JSON-lines file rebase cleanly without operator surgery. Two things\noperators should know:\n\n- **Concatenation, not set-union.** When two branches append DIFFERENT\n  records to the file, the merge driver concatenates both sides' lines\n  -- there is no smart deduplication of \"semantically similar\" records.\n  (Identical line-for-line appends collapse because git's three-way\n  merge sees them as the same change, but distinct records always\n  survive verbatim, even if a downstream reader would consider them\n  redundant.) The append-only writers in `scripts/candidates_log.py`\n  mint a fresh `decision_id` per call, so genuinely duplicate records\n  are not the expected case, but downstream readers MUST tolerate\n  multiple records describing the same logical decision.\n- **Single-operator scope only.** This is the foundational rebase\n  ergonomic for the single-operator case (operator A rebases their\n  feature branch onto a master that grew while they were AFK).\n  Multi-operator merge-conflict resolution is explicitly out of scope per\n  #1119 R4 (tracked separately as M1-M4 in #1183).\n\n## See also\n\n- Current Shape comment on #1144 for the canonical decisions (the source\n  of truth this README documents).\n- `.gitignore` -- selective gitignore entries for the operator-private\n  files.\n- `.gitattributes` -- the `merge=union` rule.\n- `scripts/candidates_log.py` -- the writer for `candidates.jsonl`.\n";
+export declare const EVAL_README_BODY = "# `vbrief/.triage-cache/` -- triage working-set artefacts\n\nThis directory holds the append-only JSON-lines logs that the triage and\nslicing skills emit. The framework governs which files in here are tracked\nby git versus gitignored using a **hybrid policy** (#1144, child of #1119).\n\n## Tracking policy\n\n| File | Tracked? | Why |\n| --- | --- | --- |\n| `slices.jsonl` | Yes -- **committed** | Team-shared cohort records produced by slicing skills (D13 / #1132). New operators joining the team need to see prior cohort outputs to detect orphans and avoid re-slicing the same scope. |\n| `candidates.jsonl` | No -- **gitignored** | Operator-private triage decisions (#845 Story 2). Each operator's local accept / defer / reject stream is per-machine state; sharing it would conflate operators' timing + identity across the team. Re-derive on a fresh clone via `task triage:bootstrap`. |\n| `summary-history.jsonl` | No -- **gitignored** | Operator-private observability for `task triage:summary` output time-series. Not load-bearing for any decision. |\n| `scope-lifecycle.jsonl` | No -- **gitignored** | Operator-private scope-lifecycle audit decisions (D1 / #1121). Each demote (`task scope:demote`) appends one entry including a `demote_meta` block (`was_promoted`, `original_promotion_decision_id`, `days_in_pending`, `demote_reason`, `demoted_from`). Per-operator stream; sharing would conflate operators' demote timing across the team. Lightweight metrics over this log are tracked separately at #1180. |\n| `decompositions/` | No -- **gitignored** | Temporary story-decomposition proposal drafts. These JSON drafts are local scratch artifacts, not vBRIEFs; generated child story vBRIEFs are created by `task scope:decompose` in lifecycle folders, defaulting to `vbrief/pending/`. |\n| `doctor-state.json` | No -- **gitignored** | Per-machine `task doctor` throttle state (last exit code + timestamps) persisted to gate the 24h/4h re-probe window (#1308 / #1464). Local to each clone; never committed. |\n\nThe gitignore lines live in the repo-root `.gitignore` (`vbrief/.triage-cache/candidates.jsonl`,\n`vbrief/.triage-cache/summary-history.jsonl`, `vbrief/.triage-cache/scope-lifecycle.jsonl`,\n`vbrief/.triage-cache/decompositions/`, and `vbrief/.triage-cache/doctor-state.json`). All paths\nnot listed above remain committed by default.\n\n## Fresh-clone regeneration\n\nOn a fresh clone (or any machine that has never run triage), `candidates.jsonl`\nis absent. Regenerate it with:\n\n```\ntask triage:bootstrap\n```\n\nThe bootstrap path detects the missing file, runs the auto-classifier, and\nwrites a fresh `vbrief/.triage-cache/candidates.jsonl`. It does NOT touch the tracked\n`slices.jsonl`; cohort records remain a team-shared resource.\n\n## `merge=union` policy for `*.jsonl`\n\nThe repo-root `.gitattributes` declares:\n\n```\nvbrief/.triage-cache/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on\nauto-merge, so two branches that each appended a different record to the\nsame JSON-lines file rebase cleanly without operator surgery. Two things\noperators should know:\n\n- **Concatenation, not set-union.** When two branches append DIFFERENT\n  records to the file, the merge driver concatenates both sides' lines\n  -- there is no smart deduplication of \"semantically similar\" records.\n  (Identical line-for-line appends collapse because git's three-way\n  merge sees them as the same change, but distinct records always\n  survive verbatim, even if a downstream reader would consider them\n  redundant.) The append-only writers in `scripts/candidates_log.py`\n  mint a fresh `decision_id` per call, so genuinely duplicate records\n  are not the expected case, but downstream readers MUST tolerate\n  multiple records describing the same logical decision.\n- **Single-operator scope only.** This is the foundational rebase\n  ergonomic for the single-operator case (operator A rebases their\n  feature branch onto a master that grew while they were AFK).\n  Multi-operator merge-conflict resolution is explicitly out of scope per\n  #1119 R4 (tracked separately as M1-M4 in #1183).\n\n## See also\n\n- Current Shape comment on #1144 for the canonical decisions (the source\n  of truth this README documents).\n- `.gitignore` -- selective gitignore entries for the operator-private\n  files.\n- `.gitattributes` -- the `merge=union` rule.\n- `scripts/candidates_log.py` -- the writer for `candidates.jsonl`.\n";
 /** Strip an inline `# ...` comment from a gitignore line. */
 export declare function stripGitignoreInlineComment(line: string): string;
 /** Append `.deft-cache/` to `.gitignore` when absent. */
 export declare function stepEnsureGitignoreEntry(projectRoot: string): StepOutcome;
 /** Ensure the #1144 hybrid policy is encoded in the repo (idempotent). */
 export declare function stepEnsureGitignoreEvalEntries(projectRoot: string): StepOutcome;
-/** Ensure `vbrief/.eval/candidates.jsonl` exists (#1240 option A). */
+/** Ensure `vbrief/.triage-cache/candidates.jsonl` exists (#1240 option A). */
 export declare function stepSeedCandidatesLog(projectRoot: string): StepOutcome;
 //# sourceMappingURL=gitignore.d.ts.map