@deftai/directive-core 0.70.0 → 0.71.1

package/dist/events/attribution-ledger.js

@@ -0,0 +1,61 @@
+import { resolve } from "node:path";
+import { DEFAULT_EVENT_LOG, emit } from "../lifecycle/events.js";
+import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
+import { ATTRIBUTION_EVENT_NAMES } from "./attribution-constants.js";
+export { ALL_ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_REQUIRED_PAYLOAD, } from "./attribution-constants.js";
+function resolveLedgerLogPath(projectRoot, logPath) {
+    if (logPath !== undefined && logPath !== null) {
+        return resolve(logPath);
+    }
+    return resolve(projectRoot, DEFAULT_EVENT_LOG);
+}
+function signalClassForEvent(name) {
+    const prefix = name.split(":")[0];
+    if (prefix === "value" || prefix === "bypass" || prefix === "adoption" || prefix === "friction") {
+        return prefix;
+    }
+    throw new Error(`attribution event '${name}' has unknown signal-class prefix`);
+}
+/**
+ * Append an attribution ledger entry when valueFeedback emitEvents is allowed.
+ * Returns null when gated OFF (no disk write).
+ */
+export function emitAttributionSignal(name, payload, options) {
+    try {
+        const policy = options.policyOverride ?? resolveValueFeedback(options.projectRoot);
+        if (!isValueFeedbackPathAllowed("emitEvents", policy)) {
+            return null;
+        }
+        const signalClass = signalClassForEvent(name);
+        const logPath = resolveLedgerLogPath(options.projectRoot, options.logPath);
+        return emit(name, {
+            signal_class: signalClass,
+            ...payload,
+        }, { logPath });
+    }
+    catch {
+        // Telemetry is best-effort; any failure must not interrupt gate callers (#1709).
+        return null;
+    }
+}
+/** Record a detection-bound gate catch (value class). */
+export function recordGateCatch(projectRoot, source, detail, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.valueGateCatch, { source, detail }, { projectRoot, ...options });
+}
+/** Record a WIP-cap protect refusal (value class). */
+export function recordWipCapProtect(projectRoot, count, cap, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.valueWipCapProtect, { source: "verify:wip-cap", count, cap }, { projectRoot, ...options });
+}
+/** Record a bypass/off-flow signal. */
+export function recordBypassSignal(projectRoot, source, detail, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.bypassOffFlow, { source, detail }, { projectRoot, ...options });
+}
+/** Record an adoption/unused-capability signal. */
+export function recordAdoptionSignal(projectRoot, capability, detail, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.adoptionUnusedCapability, { source: "adoption-registry", capability, detail }, { projectRoot, ...options });
+}
+/** Record a friction/directive-gap signal. */
+export function recordFrictionSignal(projectRoot, source, detail, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.frictionDirectiveGap, { source, detail }, { projectRoot, ...options });
+}
+//# sourceMappingURL=attribution-ledger.js.map

package/dist/index.d.ts

@@ -15,6 +15,11 @@ export * as capacity from "./capacity/index.js";
 export * as codebase from "./codebase/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
+export * as evalCrud from "./eval/crud-telemetry.js";
+export * as evalHealth from "./eval/health.js";
+export * as evalReport from "./eval/report.js";
+export * as evalRun from "./eval/run.js";
+export * as events from "./events/attribution-ledger.js";
 export * from "./forward-coverage/evaluate.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";

package/dist/index.js

@@ -15,6 +15,11 @@ export * as capacity from "./capacity/index.js";
 export * as codebase from "./codebase/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
+export * as evalCrud from "./eval/crud-telemetry.js";
+export * as evalHealth from "./eval/health.js";
+export * as evalReport from "./eval/report.js";
+export * as evalRun from "./eval/run.js";
+export * as events from "./events/attribution-ledger.js";
 export * from "./forward-coverage/evaluate.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";

package/dist/init-deposit/gitignore.js

@@ -26,11 +26,21 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/ritual-state.json",
     ".deft/last-session.json",
     ".deft/routing.local.json",
-    "vbrief/.eval/candidates.jsonl",
-    "vbrief/.eval/summary-history.jsonl",
-    "vbrief/.eval/scope-lifecycle.jsonl",
-    "vbrief/.eval/decompositions/",
-    "vbrief/.eval/doctor-state.json",
+    "vbrief/.triage-cache/candidates.jsonl",
+    "vbrief/.triage-cache/summary-history.jsonl",
+    "vbrief/.triage-cache/scope-lifecycle.jsonl",
+    "vbrief/.triage-cache/decompositions/",
+    "vbrief/.triage-cache/doctor-state.json",
+    // Symmetric `xbrief/` layout entries (#2348). On the migrated `xbrief/` tree
+    // the engine writes operator-private triage-cache files to
+    // `xbrief/.triage-cache/`; without these the paths are trackable, violating
+    // the #1144 hybrid policy. Both layouts are emitted (harmless extra lines on
+    // the layout not in use) to match the both-layout `.eval/` treatment.
+    "xbrief/.triage-cache/candidates.jsonl",
+    "xbrief/.triage-cache/summary-history.jsonl",
+    "xbrief/.triage-cache/scope-lifecycle.jsonl",
+    "xbrief/.triage-cache/decompositions/",
+    "xbrief/.triage-cache/doctor-state.json",
     "vbrief/*.lock",
     ".deft/core.bak-*/",
     ".deft/*.bak-*",

package/dist/intake/candidates-log.d.ts

@@ -1,4 +1,3 @@
-export declare const DEFAULT_LOG_PATH: string;
 export declare class CandidatesLogError extends Error {
     constructor(message: string);
 }

package/dist/intake/candidates-log.js

@@ -2,7 +2,10 @@ import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { pyRepr } from "../scm/py-format.js";
-export const DEFAULT_LOG_PATH = resolve(import.meta.dirname, "..", "..", "..", "..", "vbrief", ".eval", "candidates.jsonl");
+import { resolveCandidatesLogPath } from "../triage/cache-path.js";
+function defaultLogPath() {
+    return resolveCandidatesLogPath(process.cwd());
+}
 const VALID_DECISIONS = new Set([
     "accept",
     "reject",
@@ -105,7 +108,7 @@ function validateEntry(entry) {
     }
 }
 function resolvePath(path) {
-    return path !== undefined && path !== null ? resolve(path) : DEFAULT_LOG_PATH;
+    return path !== undefined && path !== null ? resolve(path) : defaultLogPath();
 }
 function acquireAppendLock(logPath) {
     while (threadLocked) {

package/dist/intake/issue-ingest.d.ts

@@ -44,6 +44,14 @@ export interface FetchIssueOptions {
     readonly cacheRoot?: string | null;
     readonly scmCall?: ScmCallFn;
 }
+/**
+ * Strip the `# #<number>: <title>` header that `renderContent` prepends when it
+ * materializes an issue's `content.md` at cache-put (#2314). The header is the
+ * only shape difference between the cache-read body and the live/raw-body path;
+ * removing it makes an ingested xBRIEF's `Overview` identical whether the source
+ * was a cache hit or a live fetch. A missing/older-shape header is left intact.
+ */
+export declare function stripRenderedIssueHeader(content: string, number: number): string;
 export declare function fetchFromCache(repo: string, number: number, options?: FetchIssueOptions): Record<string, unknown> | null;
 export declare function fetchIssueComments(repo: string, number: number, options?: FetchIssueOptions): IssueComment[];
 export declare function attachIssueCommentThread(issue: Record<string, unknown>, comments: readonly IssueComment[]): Record<string, unknown>;

package/dist/intake/issue-ingest.js

@@ -386,6 +386,20 @@ export function targetFilename(number, title, artifactSuffix = LEGACY_ARTIFACT_S
     const slug = slugify(title) || `issue-${number}`;
     return `${TODAY}-${number}-${slug}${artifactSuffix}`;
 }
+/**
+ * Strip the `# #<number>: <title>` header that `renderContent` prepends when it
+ * materializes an issue's `content.md` at cache-put (#2314). The header is the
+ * only shape difference between the cache-read body and the live/raw-body path;
+ * removing it makes an ingested xBRIEF's `Overview` identical whether the source
+ * was a cache hit or a live fetch. A missing/older-shape header is left intact.
+ */
+export function stripRenderedIssueHeader(content, number) {
+    if (!Number.isFinite(number)) {
+        return content;
+    }
+    const header = new RegExp(`^# #${number}:[^\\n]*\\n\\n`);
+    return content.replace(header, "");
+}
 export function fetchFromCache(repo, number, options = {}) {
     const key = `${repo}/${number}`;
     try {
@@ -405,7 +419,11 @@ export function fetchFromCache(repo, number, options = {}) {
         // buildIssueVbrief.
         if (result.contentPath !== null) {
             try {
-                issue.body = readFileSync(result.contentPath, "utf8");
+                // #2314: content.md is `renderContent`-prefixed with a `# #<n>: <title>`
+                // header at cache-put. Strip that header so the cache-read Overview
+                // matches the live/raw-body path (which has no header), keeping the
+                // durable xBRIEF identical for a cache hit vs a live fetch.
+                issue.body = stripRenderedIssueHeader(readFileSync(result.contentPath, "utf8"), Number(issue.number));
             }
             catch {
                 // fall back to the raw body (re-scanned downstream)

package/dist/intake/reconcile-issues.js

@@ -6,6 +6,7 @@ import { call } from "../scm/call.js";
 import { updateDecomposedChildBackReferences } from "../scope/decomposed-refs.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
+import { LEGACY_INFO_ROOT_KEY, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
 export const LIFECYCLE_FOLDERS = [
     "proposed",
     "pending",
@@ -633,8 +634,14 @@ export function applyLifecycleFixes(vbriefDir, report, projectRoot = null) {
         const terminalStatus = destFolder === "cancelled" ? "cancelled" : "completed";
         plan.status = terminalStatus;
         const stamp = utcNowIso();
-        const info = (data.vBRIEFInfo ?? {});
-        data.vBRIEFInfo = info;
+        // Stamp `updated` into whichever info envelope the file already uses (#2346).
+        // Canonical v0.8 briefs use `xBRIEFInfo`; stamping `vBRIEFInfo` unconditionally
+        // appended a stray, version-less `vBRIEFInfo` block that then failed
+        // `vbrief:validate` ('vBRIEFInfo.version' must be one of ..., got 'undefined').
+        // Legacy briefs (or files without either envelope) keep the `vBRIEFInfo` key.
+        const infoKey = MIGRATED_INFO_ROOT_KEY in data ? MIGRATED_INFO_ROOT_KEY : LEGACY_INFO_ROOT_KEY;
+        const info = (data[infoKey] ?? {});
+        data[infoKey] = info;
         info.updated = stamp;
         plan.updated = stamp;
         propagateItemStatus(plan.items, terminalStatus, stamp);

package/dist/layout/resolve.d.ts

@@ -51,9 +51,9 @@ export declare function resolveLifecycleRoot(projectRoot: string): string;
  * (e.g. `<root>/<xbrief|vbrief>/active`). Layout-aware (#2109 part 2a).
  */
 export declare function resolveLifecycleFolder(projectRoot: string, folder: string): string;
-/** Absolute path to the resolved lifecycle `.eval` cache directory (#2109 part 2a). */
+/** Absolute path to the layout-aware `.eval/` directory for version-eval results (#1703). */
 export declare function resolveEvalDir(projectRoot: string): string;
-/** Absolute path to a file or subpath under the resolved `.eval` cache directory. */
+/** Absolute path under `.eval/` for version-eval artefacts (not triage working-set). */
 export declare function resolveEvalPath(projectRoot: string, ...segments: string[]): string;
 /** Absolute path to the resolved lifecycle `.audit` directory (#2109 part 2a). */
 export declare function resolveAuditDir(projectRoot: string): string;

package/dist/layout/resolve.js

@@ -101,11 +101,11 @@ export function resolveLifecycleRoot(projectRoot) {
 export function resolveLifecycleFolder(projectRoot, folder) {
     return join(resolveLifecycleRoot(projectRoot), folder);
 }
-/** Absolute path to the resolved lifecycle `.eval` cache directory (#2109 part 2a). */
+/** Absolute path to the layout-aware `.eval/` directory for version-eval results (#1703). */
 export function resolveEvalDir(projectRoot) {
     return join(resolveLifecycleRoot(projectRoot), ".eval");
 }
-/** Absolute path to a file or subpath under the resolved `.eval` cache directory. */
+/** Absolute path under `.eval/` for version-eval artefacts (not triage working-set). */
 export function resolveEvalPath(projectRoot, ...segments) {
     return join(resolveEvalDir(projectRoot), ...segments);
 }

package/dist/lifecycle/events.js

@@ -3,10 +3,12 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { contentRoot } from "../content-root.js";
+import { ATTRIBUTION_REQUIRED_PAYLOAD } from "../events/attribution-constants.js";
 /** Default event log location (project-local). */
 export const DEFAULT_EVENT_LOG = join(".deft-cache", "events.jsonl");
 const BEHAVIORAL_CATEGORY = "behavioral";
 const REQUIRED_BEHAVIORAL_PAYLOAD = {
+    ...ATTRIBUTION_REQUIRED_PAYLOAD,
     "session:interrupted": ["session_id", "reason"],
     "session:resumed": ["session_id", "interrupted_id"],
     "plan:approved": ["plan_ref", "approver"],

package/dist/orchestration/subagent-monitor.js

@@ -379,8 +379,8 @@ export function cmdSubagentMonitor(argv, cwd = process.cwd()) {
         process.stderr.write(`Error: ${args.error}\n`);
         return EXIT_EXTERNAL_ERROR;
     }
-    if (args.thresholdMinutes <= 0) {
-        process.stderr.write(`Error: --threshold-minutes must be positive, got ${args.thresholdMinutes}\n`);
+    if (Number.isNaN(args.thresholdMinutes) || args.thresholdMinutes <= 0) {
+        process.stderr.write(`Error: --threshold-minutes must be a positive number, got ${args.thresholdMinutes}\n`);
         return EXIT_EXTERNAL_ERROR;
     }
     const scratchEntries = args.scratchDirs.length > 0

package/dist/policy/index.d.ts

@@ -5,6 +5,7 @@ export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
 export * from "./resolve.js";
+export * from "./value-feedback.js";
 export * from "./wip.js";
 export declare const FIELD_ALLOW_DIRECT_COMMITS = "plan.policy.allowDirectCommitsToMaster";
 export declare const FIELD_WIP_CAP = "plan.policy.wipCap";
@@ -29,7 +30,7 @@ export interface PolicyField {
 }
 /** Walk registered inspectors and return one row per field (#1148). */
 export declare function inspectAllPolicies(projectRoot: string): PolicyField[];
-/** Look up a single registered field by canonical dotted-path name. */
+/** Look up a single registered field by canonical dotted-path name (or CLI alias). */
 export declare function inspectOnePolicy(name: string, projectRoot: string): PolicyField | null;
 /** Return canonical names of every registered typed-policy field. */
 export declare function registeredPolicyNames(): string[];

package/dist/policy/index.js

@@ -1,5 +1,6 @@
 import { readPlanPolicy } from "./plan-extensions.js";
 import { coerceLegacyNarrative, LEGACY_NARRATIVE_KEY, loadProjectDefinition } from "./resolve.js";
+import { FIELD_VALUE_FEEDBACK, FIELD_VALUE_FEEDBACK_CLI_ALIAS, inspectValueFeedback, } from "./value-feedback.js";
 import { DEFAULT_WIP_CAP } from "./wip.js";
 export * from "./agents-md-advisory.js";
 export * from "./autonomy.js";
@@ -8,6 +9,7 @@ export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
 export * from "./resolve.js";
+export * from "./value-feedback.js";
 export * from "./wip.js";
 export const FIELD_ALLOW_DIRECT_COMMITS = "plan.policy.allowDirectCommitsToMaster";
 export const FIELD_WIP_CAP = "plan.policy.wipCap";
@@ -213,6 +215,15 @@ function inspectSwarmSubagentBackend(data) {
         source: "default-on-error",
     };
 }
+function inspectValueFeedbackField(data) {
+    const field = inspectValueFeedback(data);
+    return {
+        name: field.name,
+        current: field.current,
+        default: field.default,
+        source: field.source,
+    };
+}
 const REGISTERED_POLICIES = [
     inspectAllowDirectCommits,
     inspectWipCap,
@@ -225,16 +236,18 @@ const REGISTERED_POLICIES = [
         emptyIsTyped: true,
     }),
     inspectSwarmSubagentBackend,
+    inspectValueFeedbackField,
 ];
 /** Walk registered inspectors and return one row per field (#1148). */
 export function inspectAllPolicies(projectRoot) {
     const [data] = loadProjectDefinition(projectRoot);
     return REGISTERED_POLICIES.map((inspect) => inspect(data));
 }
-/** Look up a single registered field by canonical dotted-path name. */
+/** Look up a single registered field by canonical dotted-path name (or CLI alias). */
 export function inspectOnePolicy(name, projectRoot) {
+    const normalized = name === FIELD_VALUE_FEEDBACK_CLI_ALIAS ? FIELD_VALUE_FEEDBACK : name;
     for (const field of inspectAllPolicies(projectRoot)) {
-        if (field.name === name)
+        if (field.name === normalized)
             return field;
     }
     return null;

package/dist/policy/value-feedback.d.ts

@@ -0,0 +1,56 @@
+/** Canonical registered policy field name (matches other FIELD_* dotted paths). */
+export declare const FIELD_VALUE_FEEDBACK = "plan.policy.valueFeedback";
+/** Short alias accepted by `policy:show --field=valueFeedback` (#1709). */
+export declare const FIELD_VALUE_FEEDBACK_CLI_ALIAS = "valueFeedback";
+export declare const DEFAULT_VALUE_FEEDBACK_ENABLED = false;
+/** Sub-flag defaults applied when the master flag is enabled (#1709 tiered-cost decision). */
+export declare const VALUE_FEEDBACK_SUBFLAG_DEFAULTS_WHEN_ENABLED: {
+    readonly emitEvents: true;
+    readonly sessionLine: true;
+    readonly upstreamPrompt: false;
+};
+export type ValueFeedbackSubFlag = keyof typeof VALUE_FEEDBACK_SUBFLAG_DEFAULTS_WHEN_ENABLED;
+export interface ValueFeedbackConfig {
+    readonly enabled: boolean;
+    readonly emitEvents: boolean;
+    readonly sessionLine: boolean;
+    readonly upstreamPrompt: boolean;
+}
+export type ValueFeedbackSource = "typed" | "default" | "default-on-error";
+export interface ValueFeedbackResolved extends ValueFeedbackConfig {
+    readonly source: ValueFeedbackSource;
+    readonly error: string | null;
+}
+export declare const VALUE_FEEDBACK_CAPABILITY_COST_DISCLOSURE: string;
+/** Validate a `plan.policy.valueFeedback` payload. */
+export declare function validateValueFeedback(value: unknown): string[];
+/** Resolve `plan.policy.valueFeedback` from PROJECT-DEFINITION (#1709). */
+export declare function resolveValueFeedback(projectRoot: string): ValueFeedbackResolved;
+/** Master gate: when `enabled` is false, every downstream path is rejected. */
+export declare function isValueFeedbackPathAllowed(path: ValueFeedbackSubFlag, policy: ValueFeedbackResolved): boolean;
+/** Resolved per-path gate booleans for policy:show and enable status output. */
+export declare function valueFeedbackPathGates(policy: ValueFeedbackResolved): Record<ValueFeedbackSubFlag, boolean>;
+/** Human-readable status line for CLI enable/show surfaces. */
+export declare function formatValueFeedbackStatusLine(policy: ValueFeedbackResolved): string;
+export interface ValueFeedbackPolicyField {
+    readonly name: typeof FIELD_VALUE_FEEDBACK;
+    readonly current: ValueFeedbackConfig;
+    readonly default: ValueFeedbackConfig;
+    readonly source: string;
+}
+/** Inspector row for `policy:show --field=valueFeedback`. */
+export declare function inspectValueFeedback(data: Record<string, unknown> | null): ValueFeedbackPolicyField;
+export interface EnableValueFeedbackOptions {
+    readonly confirm: boolean;
+    readonly actor?: string;
+    readonly note?: string;
+    readonly subFlags?: Partial<Record<ValueFeedbackSubFlag, boolean>>;
+}
+export interface EnableValueFeedbackResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly stdout: string;
+    readonly changed: boolean;
+}
+/** Persist `valueFeedback.enabled=true` after capability-cost disclosure (#1709). */
+export declare function enableValueFeedback(projectRoot: string, options: EnableValueFeedbackOptions): EnableValueFeedbackResult;
+//# sourceMappingURL=value-feedback.d.ts.map