@deftai/directive-core 0.105.0 → 0.106.0

package/dist/triage/welcome/writers.js

@@ -4,6 +4,7 @@ import { containedWrite } from "../../fs/contained-write.js";
 import { assertWriteTargetSafe } from "../../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_ONBOARDING_KEY, PLAN_POLICY_KEY, } from "../../policy/plan-extensions.js";
+import { stampChangedToken } from "../../policy/resolve.js";
 import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 import { AUDIT_LOG_REL_PATH, DEFAULT_RELIEF_AGE_DAYS, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WELCOME_AUDIT_TAG, } from "./constants.js";
 function projectDefinitionPath(projectRoot) {
@@ -12,9 +13,13 @@ function projectDefinitionPath(projectRoot) {
 function utcIso() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
-export function appendAuditEntry(projectRoot, entry) {
+export function appendAuditEntry(projectRoot, entry, changed = true) {
     const root = resolve(projectRoot);
     const logPath = join(root, AUDIT_LOG_REL_PATH);
+    const stamped = stampChangedToken(entry, changed);
+    if (!changed) {
+        return logPath;
+    }
     // #2980 wave D: product write sink routes through containedWrite.
     mkdirSync(root, { recursive: true });
     if (!existsSync(logPath)) {
@@ -28,7 +33,7 @@ export function appendAuditEntry(projectRoot, entry) {
     containedWrite({
         root,
         target: AUDIT_LOG_REL_PATH,
-        data: `${utcIso()} ${entry}\n`,
+        data: `${utcIso()} ${stamped}\n`,
         mode: "append",
     });
     return logPath;
@@ -102,7 +107,7 @@ export function writeTriageScope(projectRoot, rules, options = { presetLabel: "c
             `rule_count=${rules.length}`,
             `changed=${changed ? "true" : "false"}`,
         ].join(" ");
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }
@@ -153,7 +158,7 @@ export function writeWipCapDecision(projectRoot, options = {}) {
             `acceptedDefault=${acceptedDefault ? "true" : "false"}`,
             `changed=${changed ? "true" : "false"}`,
         ].join(" ");
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }
@@ -220,7 +225,7 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         const changed = previous !== wipCap;
         const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
             `changed=${changed ? "true" : "false"}`;
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }

package/dist/value/readback.d.ts

@@ -1,5 +1,6 @@
 import { type BehavioralEventRecord } from "../lifecycle/events.js";
 import { type ValueFeedbackResolved } from "../policy/value-feedback.js";
+import { type CeremonyCostRollup } from "../session/process-cost.js";
 /** Repeat-suppression window for the budgeted session readback (#1709 / #1279 parity). */
 export declare const VALUE_READBACK_SUPPRESSION_HOURS = 4;
 export declare const VALUE_READBACK_HISTORY_REL: string;
@@ -24,6 +25,8 @@ export interface ValueShowResult {
     readonly empty: boolean;
     readonly text: string;
     readonly trend: ValueShowTrend | null;
+    /** Composed #3508 ceremony-cost rollup (CLI process time, not turn clock). */
+    readonly ceremonyCost: CeremonyCostRollup | null;
 }
 export interface SessionReadbackResult {
     readonly line: string | null;
@@ -64,7 +67,7 @@ export declare function computeValueShowTrend(projectRoot: string, options?: {
     now?: Date;
 }): ValueShowTrend;
 export declare function formatValueShowReport(trend: ValueShowTrend): string;
-/** Pull-based value:show CLI core (#1709). */
+/** Pull-based value:show CLI core (#1709) with composed ceremony-cost reader (#3508). */
 export declare function runValueShow(options: {
     projectRoot?: string | null;
     window?: string;

package/dist/value/readback.js

@@ -8,6 +8,7 @@ import { DEFAULT_EVENT_LOG, readEvents } from "../lifecycle/events.js";
 import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
+import { computeCeremonyCostRollup, formatCeremonyCostReport, PROCESS_COST_EVENT_NAMES, } from "../session/process-cost.js";
 import { MAX_LINE_CHARS } from "../triage/welcome/constants.js";
 import { probeAdoptionAtWorkBoundary } from "./adoption-emit.js";
 import { probeFrictionAtWorkBoundary } from "./friction-emit.js";
@@ -391,7 +392,36 @@ export function formatValueShowReport(trend) {
     ];
     return `${lines.join("\n")}\n`;
 }
-/** Pull-based value:show CLI core (#1709). */
+function attachCeremonyCost(result, ceremonyCost, format) {
+    if (format === "json") {
+        const payload = result.trend !== null
+            ? {
+                ...result.trend,
+                ceremonyCost,
+                process_cost_events: PROCESS_COST_EVENT_NAMES,
+                gated: result.gated,
+                attribution_gated: result.gated,
+            }
+            : {
+                ceremonyCost,
+                process_cost_events: PROCESS_COST_EVENT_NAMES,
+                gated: result.gated,
+                attribution_gated: result.gated,
+                empty: result.empty,
+            };
+        return {
+            ...result,
+            ceremonyCost,
+            text: `${JSON.stringify(payload, null, 2)}\n`,
+        };
+    }
+    return {
+        ...result,
+        ceremonyCost,
+        text: `${result.text}${formatCeremonyCostReport(ceremonyCost)}`,
+    };
+}
+/** Pull-based value:show CLI core (#1709) with composed ceremony-cost reader (#3508). */
 export function runValueShow(options) {
     const rootRaw = resolveProjectRoot(options.projectRoot ?? undefined);
     if (rootRaw === null) {
@@ -401,30 +431,39 @@ export function runValueShow(options) {
             empty: true,
             text: "Error: could not resolve project root.\n",
             trend: null,
+            ceremonyCost: null,
         };
     }
     const root = resolve(rootRaw);
+    const windowMs = parseWindowMs(options.window);
+    const ceremonyCost = computeCeremonyCostRollup({
+        projectRoot: root,
+        logPath: options.logPath,
+        windowMs,
+        now: options.now,
+        windowLabel: formatWindowLabel(windowMs),
+    });
     if (maintainerReadbackDisabled(root)) {
-        return {
+        return attachCeremonyCost({
             exitCode: 0,
-            gated: true,
+            gated: false,
             empty: true,
-            text: "[value] Skipped: maintainer framework repo (set DEFT_VALUE_SELF_DOGFOOD=1 to dogfood).\n",
+            text: "[value] Attribution skipped: maintainer framework repo " +
+                "(set DEFT_VALUE_SELF_DOGFOOD=1 to dogfood).\n",
             trend: null,
-        };
+        }, ceremonyCost, options.format);
     }
     const policy = options.policyOverride ?? resolveValueFeedback(root);
     if (!policy.enabled) {
-        return {
+        return attachCeremonyCost({
             exitCode: 1,
             gated: true,
             empty: true,
             text: "[value] Blocked: plan.policy.valueFeedback is OFF. " +
                 `Enable with \`${policyColonInvocation("enable-value-feedback", " -- --confirm")}\`.\n`,
             trend: null,
-        };
+        }, ceremonyCost, options.format);
     }
-    const windowMs = parseWindowMs(options.window);
     const trend = computeValueShowTrend(root, {
         windowMs,
         logPath: options.logPath,
@@ -432,21 +471,21 @@ export function runValueShow(options) {
     });
     const empty = trend.total === 0;
     if (options.format === "json") {
-        return {
+        return attachCeremonyCost({
             exitCode: 0,
             gated: false,
             empty,
             text: `${JSON.stringify(trend, null, 2)}\n`,
             trend,
-        };
+        }, ceremonyCost, "json");
     }
-    return {
+    return attachCeremonyCost({
         exitCode: 0,
         gated: false,
         empty,
         text: formatValueShowReport(trend),
         trend,
-    };
+    }, ceremonyCost, "text");
 }
 export function parseValueShowArgs(argv) {
     const out = {};

package/dist/vbrief-validate/schema.d.ts

@@ -1,4 +1,8 @@
 export type JsonObject = Record<string, unknown>;
+export declare function resolveInfoBlock(data: JsonObject): {
+    key: "vBRIEFInfo" | "xBRIEFInfo";
+    info: JsonObject;
+} | null;
 /** Validate vBRIEF/xBRIEF structural requirements (v0.6 + v0.8 additive). */
 export declare function validateVbriefSchema(data: JsonObject, filepath: string): string[];
 /** Normalize a narrative key for D3 comparison. */

package/dist/vbrief-validate/schema.js

@@ -22,7 +22,7 @@ function validatePlanRefs(planRefs, path, errors) {
         }
     }
 }
-function resolveInfoBlock(data) {
+export function resolveInfoBlock(data) {
     for (const key of VALID_INFO_ROOT_KEYS) {
         if (!(key in data)) {
             continue;

package/dist/verify-env/agent-hook-readiness.d.ts

@@ -5,10 +5,10 @@ import { type AgentHookHealthResult } from "./agent-hooks.js";
 import { type AgentHookLiveProbeResult, type AgentHookLiveProbeSeams } from "./agent-hooks-live-probe.js";
 import type { OutputStream } from "./verify-hooks-installed.js";
 export type AgentHookReadinessRegistration = "registered" | "disabled" | "missing" | "drifted" | "not-applicable";
-export type AgentHookReadinessFunctionality = "functional" | "non-functional" | "unavailable" | "not-run" | "disabled" | "not-applicable";
+export type AgentHookReadinessFunctionality = "functional" | "non-functional" | "unavailable" | "timed-out" | "not-run" | "disabled" | "not-applicable";
 export type AgentHookReadinessTrust = "manual-review-required" | "not-applicable" | "disabled";
 export type AgentHookReadinessInterception = "not-directly-verified" | "not-applicable" | "disabled";
-export type AgentHookReadinessLiveStatus = "functional" | "non-functional" | "unavailable" | "not-run" | "disabled" | "skipped";
+export type AgentHookReadinessLiveStatus = "functional" | "non-functional" | "unavailable" | "timed-out" | "not-run" | "disabled" | "skipped";
 export interface AgentHookReadinessHostResult {
     readonly host: HookHost;
     readonly registration: AgentHookReadinessRegistration;

package/dist/verify-env/agent-hook-readiness.js

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { resolveFrameworkRootForProject } from "../doctor/paths.js";
-import { loadHostHooksPolicyFromProject } from "../policy/host-hooks.js";
+import { loadHostHooksPolicyFromProject, UNUSED_HOST_HOOKS_RECOVERY, } from "../policy/host-hooks.js";
 import { evaluateAgentHooks } from "./agent-hooks.js";
 import { probeAgentHooksLive, } from "./agent-hooks-live-probe.js";
 /** Stable CLI JSON projection; keep the four readiness dimensions orthogonal. */
@@ -114,31 +114,35 @@ export function evaluateAgentHookReadiness(projectRoot, options = {}) {
                 ? "functional"
                 : liveStatus === "unavailable"
                     ? "unavailable"
-                    : liveStatus === "non-functional"
-                        ? "non-functional"
-                        : "not-run",
+                    : liveStatus === "timed-out"
+                        ? "timed-out"
+                        : liveStatus === "non-functional"
+                            ? "non-functional"
+                            : "not-run",
         };
     });
     const allDisabled = enabledHosts.length === 0;
+    const timeoutOnly = liveProbe.cases.length > 0 && liveProbe.cases.every((entry) => entry.issue === "timed-out");
     const liveStatus = allDisabled
         ? "disabled"
         : liveProbe.code === 0
             ? "functional"
             : liveProbe.code === 2
                 ? "unavailable"
-                : "non-functional";
+                : timeoutOnly
+                    ? "timed-out"
+                    : "non-functional";
     const trustReview = policy.codex
         ? "\n  Codex trust: manual-review-required. Open `/hooks` and approve the exact project hook commands. " +
             "The live probe validates the shim and codec, not host interception."
         : "";
+    const unusedHostRecovery = liveProbe.code === 0 || timeoutOnly ? "" : `\n  ${UNUSED_HOST_HOOKS_RECOVERY}`;
     return {
         code: liveProbe.code,
         message: `${liveProbe.code === 0 ? "✓" : "❌"} deft agent hook readiness: ${liveProbe.message}\n` +
             renderHosts(evaluatedHosts) +
             trustReview +
-            (liveProbe.code === 0
-                ? ""
-                : "\n  If an affected host is unused, inspect `deft policy:show --field=hostHooks`, set `plan.policy.hostHooks.<host> = false`, and run `deft update`."),
+            unusedHostRecovery,
         stream: liveProbe.code === 0 ? "stdout" : "stderr",
         skipped: false,
         liveStatus,

package/dist/verify-env/agent-hooks-live-probe.d.ts

@@ -1,5 +1,9 @@
 import { type HookEvent, type HookHost } from "../hooks/dispatcher.js";
 export declare const LIVE_PROBE_CASE_TIMEOUT_MS = 1500;
+/** Extra attempts after a timeout. One retry keeps 4×2×1.5s×2 = 24s under Cursor 30s (#3570). */
+export declare const LIVE_PROBE_CASE_RETRY_COUNT = 1;
+export declare const LIVE_PROBE_TIMEOUT_RECOVERY = "Recovery: retry the gated ritual when load is lower. Do not reinstall @deftai/directive or disable hostHooks for a timeout.";
+export declare const LIVE_PROBE_BROKEN_RECOVERY = "Recovery: reinstall @deftai/directive and run `deft update`.";
 export type AgentHookLiveProbeIssue = "hook-command-missing" | "spawn-failed" | "timed-out" | "empty-stdout" | "unparseable-json" | "missing-allow" | "missing-deny";
 export interface AgentHookLiveProbeCase {
     readonly host: HookHost;
@@ -8,7 +12,7 @@ export interface AgentHookLiveProbeCase {
     readonly issue: AgentHookLiveProbeIssue;
     readonly detail: string;
 }
-export type AgentHookLiveProbeHostStatus = "functional" | "non-functional" | "unavailable";
+export type AgentHookLiveProbeHostStatus = "functional" | "non-functional" | "unavailable" | "timed-out";
 export interface AgentHookLiveProbeHostResult {
     readonly host: HookHost;
     readonly status: AgentHookLiveProbeHostStatus;

package/dist/verify-env/agent-hooks-live-probe.js

@@ -6,6 +6,10 @@ import { DEFT_HOOK_COMMAND_MARKER } from "../init-deposit/agent-hooks.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { quoteWin32CommandForShell, resolveCommandOnPath, shouldUseShellForCommand, } from "./command-spawn.js";
 export const LIVE_PROBE_CASE_TIMEOUT_MS = 1_500;
+/** Extra attempts after a timeout. One retry keeps 4×2×1.5s×2 = 24s under Cursor 30s (#3570). */
+export const LIVE_PROBE_CASE_RETRY_COUNT = 1;
+export const LIVE_PROBE_TIMEOUT_RECOVERY = "Recovery: retry the gated ritual when load is lower. Do not reinstall @deftai/directive or disable hostHooks for a timeout.";
+export const LIVE_PROBE_BROKEN_RECOVERY = "Recovery: reinstall @deftai/directive and run `deft update`.";
 const LIVE_PROBE_EVENT = "tool.before";
 function elapsedMs(started) {
     return Math.max(0, Math.round(performance.now() - started));
@@ -122,21 +126,38 @@ function validateFixtureOutput(host, fixture, stdout) {
         ? { ok: true }
         : { ok: false, issue: "missing-deny", detail: `expected ${host} deny envelope` };
 }
+function liveProbeRecovery(cases) {
+    if (cases.length > 0 && cases.every((entry) => entry.issue === "timed-out")) {
+        return LIVE_PROBE_TIMEOUT_RECOVERY;
+    }
+    return LIVE_PROBE_BROKEN_RECOVERY;
+}
+function hostStatusFromFailure(hostFailure) {
+    if (hostFailure === null)
+        return "functional";
+    if (hostFailure.issue === "timed-out")
+        return "timed-out";
+    return "non-functional";
+}
 function runFixtureProbe(command, host, projectRoot, fixture, spawnHook) {
-    const spawned = spawnHook({
+    const input = {
         command,
         args: ["--host", host, "--event", LIVE_PROBE_EVENT, "--project-root", projectRoot],
         stdin: fixture === "allow" ? allowFixture(projectRoot) : denyFixture(projectRoot),
         cwd: projectRoot,
         env: fixture === "allow" ? process.env : denyProbeEnv(),
-    });
+    };
+    let spawned = spawnHook(input);
+    for (let retry = 0; retry < LIVE_PROBE_CASE_RETRY_COUNT && spawned.timedOut === true; retry += 1) {
+        spawned = spawnHook(input);
+    }
     if (spawned.timedOut === true) {
         return {
             host,
             event: LIVE_PROBE_EVENT,
             fixture,
             issue: "timed-out",
-            detail: `hook command exceeded ${LIVE_PROBE_CASE_TIMEOUT_MS}ms`,
+            detail: `hook command exceeded ${LIVE_PROBE_CASE_TIMEOUT_MS}ms after ${LIVE_PROBE_CASE_RETRY_COUNT + 1} attempts`,
         };
     }
     if (spawned.status !== 0) {
@@ -204,7 +225,7 @@ export function probeAgentHooksLive(projectRoot, seams = {}) {
                 break;
             }
         }
-        hostResults.push({ host, status: hostFailure === null ? "functional" : "non-functional" });
+        hostResults.push({ host, status: hostStatusFromFailure(hostFailure) });
     }
     if (failures.length === 0) {
         return {
@@ -220,7 +241,7 @@ export function probeAgentHooksLive(projectRoot, seams = {}) {
         .join("; ");
     return {
         code: 1,
-        message: `deft agent hooks live probe FAILED: ${summary}. Recovery: reinstall @deftai/directive and run \`deft update\`.`,
+        message: `deft agent hooks live probe FAILED: ${summary}. ${liveProbeRecovery(failures)}`,
         cases: failures,
         hosts: hostResults,
         durationMs: elapsedMs(started),

package/dist/verify-env/agent-hooks.js

@@ -1,7 +1,7 @@
 import { statSync } from "node:fs";
 import { resolve } from "node:path";
 import { inspectAgentHookDeposit } from "../init-deposit/agent-hooks.js";
-import { loadHostHooksPolicyFromProject } from "../policy/host-hooks.js";
+import { loadHostHooksPolicyFromProject, UNUSED_HOST_HOOKS_RECOVERY, } from "../policy/host-hooks.js";
 function isDirectory(path) {
     try {
         return statSync(path).isDirectory();
@@ -30,9 +30,8 @@ export function evaluateAgentHooks(projectRoot, hostHooksPolicy = loadHostHooksP
                 unhealthy
                     .map((entry) => `  - ${entry.host}: ${entry.status} at ${entry.path} — ${entry.detail}`)
                     .join("\n") +
-                "\n  Recovery: run `deft update` (or `directive init`) to refresh project hooks." +
-                " If a failed host is intentionally unused, inspect `deft policy:show --field=hostHooks`, " +
-                "set `plan.policy.hostHooks.<host> = false`, and run `deft update` again.",
+                "\n  Recovery: run `deft update` (or `directive init`) to refresh project hooks. " +
+                UNUSED_HOST_HOOKS_RECOVERY,
             stream: "stderr",
             registrations,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.105.0",
+  "version": "0.106.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -283,6 +283,10 @@
       "types": "./dist/lifecycle/index.d.ts",
       "default": "./dist/lifecycle/index.js"
     },
+    "./lifecycle-visible": {
+      "types": "./dist/lifecycle-visible/index.d.ts",
+      "default": "./dist/lifecycle-visible/index.js"
+    },
     "./literal-acceptance": {
       "types": "./dist/literal-acceptance/index.d.ts",
       "default": "./dist/literal-acceptance/index.js"
@@ -382,8 +386,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.105.0",
-    "@deftai/directive-types": "^0.105.0",
+    "@deftai/directive-content": "^0.106.0",
+    "@deftai/directive-types": "^0.106.0",
     "archiver": "^8.0.0"
   },
   "scripts": {