@deftai/directive-core 0.94.0 → 0.95.0

package/dist/handoff-evidence/validate.js

@@ -0,0 +1,423 @@
+/**
+ * Deterministic handoff-evidence validator (#3120).
+ *
+ * status pass is forbidden when any remote artifact is claimed unless
+ * proof_status is bound and same-turn probe snippets cover each claim.
+ * Invented-done (false remote artifacts under pass) ranks stricter than
+ * empty-done (pass with no completion substance).
+ */
+const PROOF_STATUSES = new Set(["bound", "unbound", "n/a-no-remote-claim"]);
+const AXIS_STATES = new Set(["done", "in_progress", "not_started", "blocked", "n/a"]);
+const STATUS_VALUES = new Set(["pass", "fail", "blocked", "partial"]);
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isPresentClaim(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    return true;
+}
+/** Commands that look like same-turn forge/git/gate tool invocations. */
+const TOOLISH_CMD_RE = /^(?:gh\b|git\b|task\b|deft\b|directive\b|pnpm\b|npm\b|npx\b|curl\b|python\b|node\b)/i;
+function probePresent(probe) {
+    if (!probe)
+        return false;
+    if (!isNonEmptyString(probe.command) || !isNonEmptyString(probe.snippet))
+        return false;
+    // Reject freeform narration commands ("I checked" / "x") — require tool-like invocation.
+    if (!TOOLISH_CMD_RE.test(probe.command.trim()))
+        return false;
+    // Trivial snippet that is only the claim itself is not a probe payload.
+    if (probe.snippet.trim().length < 8)
+        return false;
+    return true;
+}
+/** Escape untrusted claim text before interpolating into RegExp constructors. */
+function escapeRe(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Token-boundary match: needle must appear not as a substring of a longer
+ * alphanumeric identifier (PR 12 ⊄ 3120; score 5 ⊄ elapsed=15s).
+ */
+function hasToken(snippet, needle) {
+    if (!needle)
+        return false;
+    try {
+        return new RegExp(`(^|[^A-Za-z0-9_])${escapeRe(needle)}([^A-Za-z0-9_]|$)`, "i").test(snippet);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when the probe's raw snippet actually mentions the claimed remote value
+ * with token-level binding (not incidental substring collisions).
+ * Never throws on malformed claims — returns false instead.
+ *
+ * Scope: textual shape binding only. Live probe execution/provenance is agent
+ * process responsibility (preamble probe-then-fill); this library does not
+ * re-run forge/git commands.
+ */
+export function probeBindsClaim(claim, evidence, probe) {
+    try {
+        if (!probePresent(probe) || !probe)
+            return false;
+        const snippet = probe.snippet;
+        switch (claim) {
+            case "pr_url": {
+                const url = String(evidence.pr_url ?? "").trim();
+                if (!url)
+                    return false;
+                // Exact claimed URL present in probe output.
+                if (snippet.toLowerCase().includes(url.toLowerCase()))
+                    return true;
+                // GitHub HTML or API form must preserve owner/repo + number identity.
+                const html = url.match(/github\.com\/([^/]+)\/([^/]+)\/pulls?\/(\d+)/i);
+                if (html) {
+                    const owner = html[1] ?? "";
+                    const repo = html[2] ?? "";
+                    const num = html[3] ?? "";
+                    const o = escapeRe(owner);
+                    const r = escapeRe(repo);
+                    const n = escapeRe(num);
+                    return (new RegExp(`${o}\\/${r}\\/pulls?\\/${n}(?:[^0-9]|$)`, "i").test(snippet) ||
+                        new RegExp(`repos\\/${o}\\/${r}\\/pulls\\/${n}(?:[^0-9]|$)`, "i").test(snippet));
+                }
+                // Non-GitHub URL: require the full URL string; no number-only fallback.
+                return false;
+            }
+            case "pr_number": {
+                const num = String(evidence.pr_number ?? "").trim();
+                if (!num || !/^\d+$/.test(num))
+                    return false;
+                const n = escapeRe(num);
+                return (new RegExp(`(?:number["'\\s:=]+|#|pulls?\\/)${n}(?:[^0-9]|$)`, "i").test(snippet) ||
+                    hasToken(snippet, num));
+            }
+            case "commit_sha":
+            case "head_sha": {
+                const sha = String(claim === "commit_sha" ? (evidence.commit_sha ?? "") : (evidence.head_sha ?? ""))
+                    .trim()
+                    .toLowerCase();
+                if (sha.length < 7 || !/^[0-9a-f]+$/i.test(sha))
+                    return false;
+                const prefix = sha.slice(0, 7);
+                return (hasToken(snippet, sha) ||
+                    new RegExp(`(^|[^0-9a-f])${prefix}(?![0-9a-f])`, "i").test(snippet));
+            }
+            case "ci_status": {
+                const ci = String(evidence.ci_status ?? "")
+                    .trim()
+                    .toLowerCase();
+                if (!ci)
+                    return false;
+                const greenFamily = [
+                    "green",
+                    "pass",
+                    "passed",
+                    "success",
+                    "successful",
+                    "ok",
+                    "clean",
+                ];
+                const redFamily = [
+                    "fail",
+                    "failed",
+                    "failure",
+                    "failing",
+                    "error",
+                    "errored",
+                    "cancelled",
+                    "canceled",
+                ];
+                if (greenFamily.includes(ci)) {
+                    const hasGreen = /"state"\s*:\s*"(success|successful|ok|clean|pass(?:ed)?)"/i.test(snippet) ||
+                        greenFamily.some((tok) => hasToken(snippet, tok));
+                    const hasRed = /"state"\s*:\s*"(failure|failed|error|cancelled|canceled)"/i.test(snippet) ||
+                        redFamily.some((tok) => hasToken(snippet, tok));
+                    // Mixed success+failure in one snippet is not a clean green bind.
+                    return hasGreen && !hasRed;
+                }
+                if (redFamily.includes(ci)) {
+                    return (/"state"\s*:\s*"(failure|failed|error|cancelled|canceled)"/i.test(snippet) ||
+                        hasToken(snippet, ci));
+                }
+                return hasToken(snippet, ci);
+            }
+            case "review_score": {
+                const score = String(evidence.review_score ?? "").trim();
+                if (!score || !/^\d+(\.\d+)?$/.test(score))
+                    return false;
+                const s = escapeRe(score);
+                // Labeled fields only — bare hasToken would bind p0=5 to review_score 5.
+                return new RegExp(`(?:confidence(?:\\s*score)?|score|rating)\\s*[:=]?\\s*${s}(?:\\s*\\/\\s*5)?(?:[^0-9]|$)`, "i").test(snippet);
+            }
+            default:
+                return false;
+        }
+    }
+    catch {
+        // Malformed claims must fail closed as unbound, never throw.
+        return false;
+    }
+}
+/** Detect which remote claim keys are present on the evidence object. */
+export function detectRemoteClaims(evidence) {
+    const claims = [];
+    if (isPresentClaim(evidence.pr_url))
+        claims.push("pr_url");
+    if (isPresentClaim(evidence.pr_number))
+        claims.push("pr_number");
+    if (isPresentClaim(evidence.commit_sha))
+        claims.push("commit_sha");
+    if (isPresentClaim(evidence.head_sha))
+        claims.push("head_sha");
+    if (isPresentClaim(evidence.ci_status)) {
+        const ci = String(evidence.ci_status).trim();
+        // Neutral tokens are not remote claims; green-family and other explicit
+        // forge outcomes (failing, cancelled, …) are claims that need probes.
+        if (!/^(unknown|pending|n\/a|none|skipped)$/i.test(ci)) {
+            claims.push("ci_status");
+        }
+    }
+    if (isPresentClaim(evidence.review_score))
+        claims.push("review_score");
+    return claims;
+}
+/** Map a remote claim key to the probe slot that must bind it. */
+function probeKeyForClaim(claim) {
+    if (claim === "pr_url" || claim === "pr_number")
+        return "pr";
+    if (claim === "commit_sha" || claim === "head_sha")
+        return "sha";
+    if (claim === "ci_status")
+        return "ci";
+    return "review";
+}
+function unboundClaimKeys(evidence, claims) {
+    const unbound = [];
+    for (const claim of claims) {
+        const slot = probeKeyForClaim(claim);
+        const probe = evidence.probes?.[slot];
+        if (!probeBindsClaim(claim, evidence, probe)) {
+            unbound.push(claim);
+        }
+    }
+    // Cross-claim consistency: PR + SHA must co-appear so unrelated forge artifacts
+    // cannot be stitched into one "bound" pass (Greptile residual on #3120).
+    try {
+        const claimSet = new Set(claims);
+        const hasPr = claimSet.has("pr_url") || claimSet.has("pr_number");
+        const shaClaim = claimSet.has("head_sha")
+            ? "head_sha"
+            : claimSet.has("commit_sha")
+                ? "commit_sha"
+                : null;
+        const rawSha = shaClaim
+            ? String(shaClaim === "head_sha" ? (evidence.head_sha ?? "") : (evidence.commit_sha ?? ""))
+                .trim()
+                .toLowerCase()
+            : "";
+        // Only hex SHAs participate in co-binding; malformed SHA fails closed as unbound.
+        const hexOk = /^[0-9a-f]{7,}$/i.test(rawSha);
+        if (shaClaim && !hexOk) {
+            if (!unbound.includes(shaClaim))
+                unbound.push(shaClaim);
+        }
+        const prefix = hexOk ? rawSha.slice(0, 7) : "";
+        if (hasPr && shaClaim && prefix) {
+            const prSnippet = evidence.probes?.pr?.snippet ?? "";
+            if (!new RegExp(`(^|[^0-9a-f])${prefix}`, "i").test(prSnippet)) {
+                if (!unbound.includes(shaClaim))
+                    unbound.push(shaClaim);
+                if (!unbound.includes("pr_number") && claimSet.has("pr_number")) {
+                    unbound.push("pr_number");
+                }
+                if (!unbound.includes("pr_url") && claimSet.has("pr_url")) {
+                    unbound.push("pr_url");
+                }
+            }
+        }
+        if (claimSet.has("ci_status") && shaClaim && prefix) {
+            const ciCmd = evidence.probes?.ci?.command ?? "";
+            const ciSnippet = evidence.probes?.ci?.snippet ?? "";
+            const joined = `${ciCmd}\n${ciSnippet}`;
+            if (!new RegExp(`(^|[^0-9a-f])${prefix}`, "i").test(joined)) {
+                if (!unbound.includes("ci_status"))
+                    unbound.push("ci_status");
+            }
+        }
+    }
+    catch {
+        // Fail closed on any unexpected error during consistency checks.
+        for (const claim of claims) {
+            if (!unbound.includes(claim))
+                unbound.push(claim);
+        }
+    }
+    return unbound;
+}
+function isPassStatus(status) {
+    return status.trim().toLowerCase() === "pass";
+}
+/** Collect shape errors for unsupported status / proof_status / axis enums. */
+function enumShapeReasons(evidence) {
+    const reasons = [];
+    const status = evidence.status.toString().trim().toLowerCase();
+    if (!STATUS_VALUES.has(status)) {
+        reasons.push(`status must be one of pass|fail|blocked|partial (got ${evidence.status})`);
+    }
+    if (evidence.proof_status !== undefined && evidence.proof_status !== null) {
+        const proof = evidence.proof_status.toString().trim().toLowerCase();
+        if (proof.length > 0 && !PROOF_STATUSES.has(proof)) {
+            reasons.push(`proof_status must be bound|unbound|n/a-no-remote-claim (got ${evidence.proof_status})`);
+        }
+    }
+    for (const [name, axis] of [
+        ["work", evidence.work],
+        ["ship", evidence.ship],
+        ["gate", evidence.gate],
+    ]) {
+        const state = axis?.state;
+        if (state === undefined || state === null)
+            continue;
+        const s = state.toString().trim().toLowerCase();
+        if (s.length > 0 && !AXIS_STATES.has(s)) {
+            reasons.push(`${name}.state must be done|in_progress|not_started|blocked|n/a (got ${state})`);
+        }
+    }
+    return reasons;
+}
+function isEmptyDone(evidence) {
+    // Pass claimed but no work/ship/gate substance and no remote claims —
+    // the empty completion shape (stricter handling still prefers invented-done
+    // when remote claims are present without binding).
+    const work = evidence.work?.state?.toString().trim().toLowerCase();
+    const ship = evidence.ship?.state?.toString().trim().toLowerCase();
+    const gate = evidence.gate?.state?.toString().trim().toLowerCase();
+    const axesEmpty = (!work || work === "n/a" || work === "not_started") &&
+        (!ship || ship === "n/a" || ship === "not_started") &&
+        (!gate || gate === "n/a" || gate === "not_started");
+    return axesEmpty;
+}
+/**
+ * Validate handoff evidence against the #3120 bound-proof contract.
+ *
+ * Ranking when invalid under status pass:
+ * 1. invented-done — remote claims present without bound proof
+ * 2. empty-done — pass with no completion substance and no remote claims
+ * 3. unbound-remote-claim — non-pass status but still has unbound remote claims
+ * 4. shape-error — malformed proof_status / inconsistent n/a
+ */
+export function validateHandoffEvidence(evidence) {
+    if (!evidence || typeof evidence !== "object") {
+        return {
+            ok: false,
+            failClass: "shape-error",
+            reasons: ["evidence must be a non-null object"],
+            hasRemoteClaims: false,
+            unboundClaims: [],
+        };
+    }
+    if (!isNonEmptyString(evidence.status)) {
+        return {
+            ok: false,
+            failClass: "shape-error",
+            reasons: ["status is required"],
+            hasRemoteClaims: false,
+            unboundClaims: [],
+        };
+    }
+    const claims = detectRemoteClaims(evidence);
+    const hasRemoteClaims = claims.length > 0;
+    const unbound = unboundClaimKeys(evidence, claims);
+    const proof = (evidence.proof_status ?? "").toString().trim().toLowerCase();
+    const reasons = [...enumShapeReasons(evidence)];
+    const pass = isPassStatus(evidence.status);
+    // proof_status consistency
+    if (hasRemoteClaims && proof === "n/a-no-remote-claim") {
+        reasons.push("proof_status is n/a-no-remote-claim but remote claims are present (" +
+            claims.join(", ") +
+            ")");
+    }
+    if (!hasRemoteClaims && proof === "bound") {
+        reasons.push("proof_status is bound but no remote claims are present");
+    }
+    // Core rule: pass + remote claims requires bound + probes
+    if (hasRemoteClaims) {
+        if (proof !== "bound") {
+            reasons.push(`remote claims present (${claims.join(", ")}) require proof_status=bound` +
+                (proof ? ` (got ${proof})` : " (missing)"));
+        }
+        if (unbound.length > 0) {
+            reasons.push(`missing same-turn probes for: ${unbound.join(", ")} ` +
+                "(probe-then-fill: copy IDs from probe JSON/text, never recollection)");
+        }
+    }
+    else if (pass && (!proof || proof === "unbound")) {
+        // No remote claims under pass: n/a-no-remote-claim is the legal proof_status.
+        // unbound without remote claims is a soft shape issue under pass.
+        if (proof === "unbound") {
+            reasons.push("proof_status=unbound with no remote claims; use n/a-no-remote-claim under pass");
+        }
+    }
+    // Rank fail class
+    let failClass = "none";
+    let ok = reasons.length === 0;
+    if (pass && hasRemoteClaims && (proof !== "bound" || unbound.length > 0)) {
+        // Invented-done: complete-looking remote artifacts under pass without binding.
+        failClass = "invented-done";
+        ok = false;
+        if (!reasons.some((r) => r.includes("invented-done"))) {
+            reasons.unshift("invented-done: status pass with remote PR/SHA/CI/review claims " +
+                "without bound same-turn probes (stricter than empty-done)");
+        }
+    }
+    else if (pass && !hasRemoteClaims && isEmptyDone(evidence)) {
+        failClass = "empty-done";
+        ok = false;
+        reasons.unshift("empty-done: status pass with no work/ship/gate substance and no remote claims");
+    }
+    else if (!pass && hasRemoteClaims && (proof !== "bound" || unbound.length > 0)) {
+        failClass = "unbound-remote-claim";
+        ok = false;
+    }
+    else if (reasons.length > 0) {
+        failClass = "shape-error";
+        ok = false;
+    }
+    // Legal partial: work done + ship not_started without PR fields → ok when not pass-with-remote
+    if (ok &&
+        evidence.status === "partial" &&
+        !hasRemoteClaims &&
+        (evidence.ship?.state === "not_started" || !evidence.ship?.state)) {
+        return {
+            ok: true,
+            failClass: "none",
+            reasons: [],
+            hasRemoteClaims: false,
+            unboundClaims: [],
+        };
+    }
+    return {
+        ok,
+        failClass,
+        reasons,
+        hasRemoteClaims,
+        unboundClaims: unbound,
+    };
+}
+/**
+ * Convenience: true when status may legally be pass for this evidence.
+ * Equivalent to validateHandoffEvidence(...).ok under a pass status intent.
+ */
+export function canClaimPass(evidence) {
+    const candidate = { ...evidence, status: "pass" };
+    return validateHandoffEvidence(candidate).ok;
+}
+//# sourceMappingURL=validate.js.map

package/dist/hooks/dispatcher.d.ts

@@ -54,6 +54,9 @@ export interface HookDispatchInput {
     readonly environ?: NodeJS.ProcessEnv;
 }
 export interface HookPolicySeams {
+    /** Active mutation-boundary verifier. Defaults to gated verification. */
+    readonly verifyRitual?: (projectRoot: string) => VerifyResult;
+    /** @deprecated Compatibility seam for existing tests and callers. */
     readonly inspectRitual?: (projectRoot: string) => VerifyResult;
     readonly inspectScope?: (projectRoot: string) => ActiveScopeInspection;
     readonly sessionStart?: (projectRoot: string) => {

package/dist/hooks/dispatcher.js

@@ -11,7 +11,7 @@ import { detectBranch } from "../session/git.js";
 import { emitSessionRitualBlockedProcessCost } from "../session/process-cost.js";
 import { markRitualStaleAfterCompact } from "../session/ritual-sentinel.js";
 import { runSessionStartHookWrite } from "../session/session-start-hook.js";
-import { formatRitualRecoveryInstruction, inspectSessionRitual, } from "../session/verify-session-ritual.js";
+import { formatRitualRecoveryInstruction, verifySessionRitual, } from "../session/verify-session-ritual.js";
 import { hookMcpArgsText, hookShellCommand, hookToolName, hookWriteTargetPath, missingToolNameMessage, record, } from "./classify/index.js";
 import { isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
 import { inspectActiveScope } from "./scope.js";
@@ -524,8 +524,17 @@ function inspectMutationGates(input, toolName, seams, options) {
     }
     let ritual;
     try {
-        ritual = (seams.inspectRitual ??
-            ((root) => inspectSessionRitual(root, { tier: "gated", posture: "mutation" })))(projectRoot);
+        // Mutation dispatch is a live gated boundary: active verification reruns
+        // non-cacheable agent-hook readiness instead of trusting persisted success.
+        // Its allow fixture is non-write and its deny fixture is read-only, so the
+        // installed-shim probe cannot recurse into this mutation path.
+        ritual = (seams.verifyRitual ??
+            seams.inspectRitual ??
+            ((root) => verifySessionRitual(root, {
+                tier: "gated",
+                posture: "mutation",
+                bypass: false,
+            })))(projectRoot);
     }
     catch (cause) {
         // #2994: best-effort local process-cost; never changes deny verdict.

package/dist/index.d.ts

@@ -24,8 +24,10 @@ 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 freshness from "./freshness/index.js";
 export { ContainedWriteError, ContainedWriteErrorCode, type ContainedWriteInput, type ContainedWriteMode, type ContainedWriteResult, containedWrite, resolveContainedTarget, } from "./fs/contained-write.js";
 export { assertDestinationNotSymlink, assertDirectoryNotSymlink, assertProjectionContained, assertWriteTargetSafe, PROJECTION_CONTAINMENT_REFUSED_EXIT_CODE, ProjectionContainmentError, walkDirectoryRejectSymlinks, } from "./fs/projection-containment.js";
+export * as handoffEvidence from "./handoff-evidence/index.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";

package/dist/index.js

@@ -24,9 +24,11 @@ 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 freshness from "./freshness/index.js";
 // #2951 Phase 1: contained-write API for product sinks.
 export { ContainedWriteError, ContainedWriteErrorCode, containedWrite, resolveContainedTarget, } from "./fs/contained-write.js";
 export { assertDestinationNotSymlink, assertDirectoryNotSymlink, assertProjectionContained, assertWriteTargetSafe, PROJECTION_CONTAINMENT_REFUSED_EXIT_CODE, ProjectionContainmentError, walkDirectoryRejectSymlinks, } from "./fs/projection-containment.js";
+export * as handoffEvidence from "./handoff-evidence/index.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";

package/dist/init-deposit/agent-hooks.d.ts

@@ -6,7 +6,7 @@ export declare const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export declare const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
 export declare const AGENT_HOOK_PATHS: readonly [".claude/settings.json", ".grok/hooks/deft.json", ".cursor/hooks.json", ".codex/hooks.json"];
 export type AgentHookPath = (typeof AGENT_HOOK_PATHS)[number];
-export type AgentHookRegistrationStatus = "healthy" | "missing" | "drifted";
+export type AgentHookRegistrationStatus = "healthy" | "disabled" | "missing" | "drifted";
 /** Whether the host receives a compact/resume hook deposit (#2113). */
 export type AgentHookCompactSupport = "deposited" | "unsupported";
 export interface AgentHookInspection {

package/dist/init-deposit/agent-hooks.js

@@ -312,7 +312,10 @@ function hasNestedRegistration(config, host, options = {}) {
     const sessionCommand = command(host, "session.start");
     const toolCommand = command(host, "tool.before");
     const compactCommand = command(host, "session.compact");
-    const base = session.some((entry) => nestedCommands(entry).includes(sessionCommand)) &&
+    const base = session.some((entry) => {
+        const group = object(entry);
+        return group?.matcher === undefined && nestedCommands(entry).includes(sessionCommand);
+    }) &&
         preTool.some((entry) => {
             const group = object(entry);
             return (group?.matcher === DIRECT_WRITE_HOOK_MATCHER && nestedCommands(entry).includes(toolCommand));
@@ -409,7 +412,7 @@ export function inspectAgentHookDeposit(projectRoot, hostHooksPolicy = loadHostH
             return {
                 host: definition.host,
                 path: definition.path,
-                status: "healthy",
+                status: "disabled",
                 compactSupport: definition.compactSupport,
                 detail: `plan.policy.hostHooks.${definition.host} is false — Directive hook deposit is skipped for this host.`,
             };

package/dist/init-deposit/init-deposit.d.ts

@@ -5,6 +5,7 @@
  * scaffold, skills/githooks/#1430 neutralization, and Taskfile wiring.
  * Refs #1942, #11, #1430.
  */
+import { type AgentHookReadinessResult } from "../verify-env/agent-hook-readiness.js";
 import { type LegacyLayoutDetection } from "./legacy-detect.js";
 import { type InitDepositIo, writeConsumerGitHooks } from "./scaffold.js";
 export interface InitDepositArgs {
@@ -28,11 +29,16 @@ export interface InitDepositSeams {
     nowIso?: () => string;
     gitHooks?: Parameters<typeof writeConsumerGitHooks>[3];
     detectLegacy?: (projectDir: string) => LegacyLayoutDetection;
+    evaluateAgentHookReadiness?: (projectRoot: string) => AgentHookReadinessResult;
 }
 export declare function parseInitArgv(canonicalArgv: readonly string[], userArgv?: readonly string[]): InitDepositArgs;
 export declare function userConfigDir(): string;
 export declare function createUserConfigDir(io: InitDepositIo): string;
-export declare function buildInstallSummaryJson(result: InitDepositResult, options: InitDepositArgs): Record<string, unknown>;
+export declare function buildInstallSummaryJson(input: {
+    result: InitDepositResult;
+    options: InitDepositArgs;
+    readiness: AgentHookReadinessResult | undefined;
+}): Record<string, unknown>;
 export declare function printNextSteps(result: InitDepositResult, io: InitDepositIo): void;
 /**
  * Ensure a minimal render-ready PROJECT-DEFINITION exists after lifecycle dirs

package/dist/init-deposit/init-deposit.js

@@ -13,8 +13,10 @@ import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { stampLiveGeneration } from "../freshness/generation.js";
 import { renderProjectDefinition } from "../render/project-render.js";
 import { depositOpenClawL2ProductCommands } from "../slash/openclaw-deposit.js";
+import { agentHookReadinessJson, evaluateAgentHookReadiness, evaluateAgentHookReadinessSafely, } from "../verify-env/agent-hook-readiness.js";
 import { removeStaleMigratedFrameworkNarrative } from "../xbrief-migrate/migrate-project.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
 import { ensureInitGitignoreLines, reconstituteDepositFromContent } from "./gitignore.js";
@@ -81,9 +83,12 @@ function readContentVersion(contentRoot, readVersion = readCorePackageVersion) {
     }
     return readVersion();
 }
-export function buildInstallSummaryJson(result, options) {
+export function buildInstallSummaryJson(input) {
+    const { result, options, readiness } = input;
     return {
-        success: true,
+        success: readiness ? readiness.code === 0 : true,
+        deposit_completed: true,
+        ...(readiness ? { agent_hook_readiness: agentHookReadinessJson(readiness) } : {}),
         action: "install",
         version: readCorePackageVersion(),
         project_dir: result.projectDir,
@@ -210,6 +215,14 @@ export async function runInitDeposit(args, io, seams = {}) {
         includeTaskfile: taskfileWired,
     });
     printCommitGuidance(io, stagePaths, staged);
+    // #3117: stamp live generation only after required init projections succeed.
+    // Stamping earlier would advance authority for a failed/partial init (Greptile).
+    stampLiveGeneration(projectDir, {
+        contentVersion: version,
+        stampedBy: "directive-init",
+        increment: true,
+        nowIso: nowIso(),
+    });
     return {
         projectDir,
         deftDir,
@@ -234,14 +247,21 @@ export async function runInitDepositCli(options) {
     };
     try {
         const result = await runInitDeposit(options, io, options.seams);
+        const readiness = evaluateAgentHookReadinessSafely(result.projectDir, options.seams?.evaluateAgentHookReadiness ?? evaluateAgentHookReadiness);
         if (options.jsonOut) {
-            options.writeOut(`${JSON.stringify(buildInstallSummaryJson(result, options), null, 2)}\n`);
+            options.writeOut(`${JSON.stringify(buildInstallSummaryJson({ result, options, readiness }), null, 2)}\n`);
             printNextSteps(result, { printf: options.writeErr });
         }
         else {
             printNextSteps(result, io);
         }
-        return 0;
+        const readinessOut = options.jsonOut
+            ? options.writeErr
+            : readiness.stream === "stderr"
+                ? options.writeErr
+                : options.writeOut;
+        readinessOut(`\n${readiness.message}\n`);
+        return readiness.code;
     }
     catch (cause) {
         if (cause instanceof LegacyLayoutRefusedError) {

package/dist/init-deposit/refresh.d.ts

@@ -9,6 +9,7 @@
  */
 import type { ResolutionFacts, ResolutionPlan } from "@deftai/directive-types";
 import { type ClassifySeams, type EngineInstallRunner, type EngineResolution, type LadderFacts, type ReprojectRunner } from "../resolution/index.js";
+import { type AgentHookReadinessResult } from "../verify-env/agent-hook-readiness.js";
 import { type GitLsFiles } from "./gitignore.js";
 import { type InitDepositArgs } from "./init-deposit.js";
 import { type LegacyLayoutDetection } from "./legacy-detect.js";
@@ -49,6 +50,8 @@ export interface RefreshDepositSeams {
     gitHooks?: GitHooksSeams;
     /** #2822: optional seam for trusted-org policy force-on migration. */
     runOrgForceOn?: (projectRoot: string) => void;
+    /** Post-deposit functional readiness gate (#3100). */
+    evaluateAgentHookReadiness?: (projectRoot: string) => AgentHookReadinessResult;
 }
 /**
  * The four states `directive update` classifies an EXISTING install into BEFORE
@@ -123,7 +126,12 @@ export interface RefreshSideEffects {
 export declare function frameworkRefreshSideEffects(projectDir: string, options?: FrameworkRefreshSideEffectsOptions): RefreshSideEffects;
 export declare function printRefreshSideEffects(io: InitDepositIo, effects: RefreshSideEffects): void;
 export declare function buildVersionSkewNotice(engineVersion: string, contentVersion: string, previousDepositVersion: string | null): string | null;
-export declare function buildUpdateSummaryJson(result: RefreshDepositResult, options: RefreshDepositArgs, updateState?: UpdateState): Record<string, unknown>;
+export declare function buildUpdateSummaryJson(input: {
+    result: RefreshDepositResult;
+    options: RefreshDepositArgs;
+    updateState: UpdateState | undefined;
+    readiness: AgentHookReadinessResult | undefined;
+}): Record<string, unknown>;
 export declare function printUpdateComplete(result: RefreshDepositResult, io: InitDepositIo, updateState?: UpdateState): void;
 export declare function runRefreshDeposit(args: RefreshDepositArgs, io: InitDepositIo, seams?: RefreshDepositSeams): Promise<RefreshDepositResult>;
 export interface RunRefreshDepositCliOptions extends RefreshDepositArgs {