@deftai/directive-core 0.94.0 → 0.96.0

package/dist/scope/promote-from-issue.js

@@ -0,0 +1,367 @@
+/**
+ * scope:promote --from-issue reciprocity gate (#1136 / D18).
+ *
+ * Gates promote of a proposed scope on the latest triage-cache decision for
+ * the issue, locates the proposed artifact via provenance scan, and runs the
+ * shared promotePath path (WIP rules unchanged).
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { provenanceIssueNumber, scanProvenanceRefs } from "../intake/issue-ingest.js";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { createCandidatesLog, resolveAuditLogPath } from "../triage/actions/candidates-log.js";
+import { resolveRepo } from "../triage/queue/repo.js";
+import { resolveProjectRoot } from "./project-context.js";
+import { promotePath } from "./promote-path.js";
+/** Collapse CR/LF in operator-facing messages (SLizard CWE-116). */
+function sanitizeMsg(value) {
+    return value.replace(/\r?\n/g, " ");
+}
+/** True when brief references or Origin point at owner/name issue N. */
+function briefMatchesIssueAndRepo(data, issueNumber, repo) {
+    if (provenanceIssueNumber(data) !== issueNumber) {
+        // Also accept plan.references github-issue URIs without Origin text.
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            return false;
+        }
+        const refs = plan.references;
+        if (!Array.isArray(refs)) {
+            return false;
+        }
+        let hit = false;
+        for (const ref of refs) {
+            if (typeof ref !== "object" || ref === null || Array.isArray(ref))
+                continue;
+            const uri = String(ref.uri ?? "");
+            if (uri.includes(`/issues/${issueNumber}`)) {
+                hit = true;
+                if (repo === null ||
+                    uri.includes(`github.com/${repo}/`) ||
+                    uri.includes(`${repo}/issues/`)) {
+                    return true;
+                }
+            }
+        }
+        return hit && repo === null;
+    }
+    if (repo === null) {
+        return true;
+    }
+    const plan = data.plan;
+    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+        const refs = plan.references;
+        if (Array.isArray(refs)) {
+            for (const ref of refs) {
+                if (typeof ref !== "object" || ref === null || Array.isArray(ref))
+                    continue;
+                const uri = String(ref.uri ?? "");
+                if (uri.includes(`/issues/${issueNumber}`) &&
+                    (uri.includes(`github.com/${repo}/`) || uri.includes(`${repo}/issues/`))) {
+                    return true;
+                }
+            }
+        }
+        const narratives = plan.narratives;
+        if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
+            const origin = String(narratives.Origin ?? "");
+            if (origin.includes(`github.com/${repo}/issues/${issueNumber}`)) {
+                return true;
+            }
+        }
+    }
+    // Provenance matched issue number but no repo-scoped URI — refuse when repo known.
+    return false;
+}
+/**
+ * Locate lifecycle artifacts whose provenance owns ``issueNumber`` (optionally repo-scoped).
+ */
+export function findLifecycleArtifactsForIssue(projectRoot, issueNumber, options = {}) {
+    const folder = options.folder ?? "proposed";
+    const repo = options.repo ?? null;
+    const root = resolve(projectRoot);
+    let lifecycleRoot;
+    try {
+        lifecycleRoot = resolveLifecycleRoot(root);
+    }
+    catch {
+        return [];
+    }
+    const byIssue = scanProvenanceRefs(lifecycleRoot);
+    const rels = (byIssue.get(issueNumber) ?? []).filter((rel) => {
+        const f = rel.split(/[/\\]/)[0];
+        return f === folder;
+    });
+    const candidates = rels.map((rel) => join(lifecycleRoot, rel));
+    // Always also scan the folder for Origin-only scaffolds.
+    const folderDir = join(lifecycleRoot, folder);
+    if (existsSync(folderDir)) {
+        for (const name of readdirSync(folderDir).filter((f) => hasArtifactSuffix(f))) {
+            candidates.push(join(folderDir, name));
+        }
+    }
+    const out = [];
+    for (const abs of uniqueExisting(candidates)) {
+        try {
+            const data = JSON.parse(readFileSync(abs, "utf8"));
+            if (briefMatchesIssueAndRepo(data, issueNumber, repo)) {
+                out.push(abs);
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return uniqueExisting(out);
+}
+/** Locate proposed/ artifacts for issue N (repo-scoped when provided). */
+export function findProposedArtifactsForIssue(projectRoot, issueNumber, repo = null) {
+    return findLifecycleArtifactsForIssue(projectRoot, issueNumber, { folder: "proposed", repo });
+}
+function uniqueExisting(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const p of paths) {
+        const key = resolve(p);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (existsSync(key)) {
+            out.push(key);
+        }
+    }
+    return out.sort();
+}
+function resolveLatestDecision(options, projectRoot, repo) {
+    if (options.latestDecision !== undefined) {
+        return options.latestDecision;
+    }
+    const log = createCandidatesLog(projectRoot);
+    const path = options.candidatesLogPath ?? resolveAuditLogPath(projectRoot);
+    return log.latestDecision(options.issueNumber, repo, { path });
+}
+/**
+ * Promote the proposed scope for an issue, gated on triage-cache latestDecision.
+ */
+export function promoteFromIssue(options) {
+    const warnings = [];
+    const projectRoot = resolveProjectRoot(options.projectRoot);
+    if (projectRoot === null) {
+        return {
+            ok: false,
+            message: "Cannot determine project root. Pass --project-root PATH, set $DEFT_PROJECT_ROOT, or run from inside a directory tree that contains vbrief/ or .git/ (#535).",
+            exitCode: 2,
+            warnings,
+            repo: null,
+            matchedPaths: [],
+            cacheStateAtPromote: null,
+            cacheDecisionId: null,
+        };
+    }
+    const repo = resolveRepo(options.repo, projectRoot);
+    if (repo === null) {
+        return {
+            ok: false,
+            message: "scope:promote --from-issue requires --repo OWNER/NAME (or $DEFT_TRIAGE_REPO / git remote origin).",
+            exitCode: 2,
+            warnings,
+            repo: null,
+            matchedPaths: [],
+            cacheStateAtPromote: null,
+            cacheDecisionId: null,
+        };
+    }
+    const repoSafe = sanitizeMsg(repo);
+    const n = options.issueNumber;
+    if (!Number.isInteger(n) || n < 1) {
+        return {
+            ok: false,
+            message: `Invalid --from-issue value: ${String(options.issueNumber)} (expected positive integer).`,
+            exitCode: 2,
+            warnings,
+            repo,
+            matchedPaths: [],
+            cacheStateAtPromote: null,
+            cacheDecisionId: null,
+        };
+    }
+    const latest = resolveLatestDecision(options, projectRoot, repo);
+    const cacheState = latest?.decision ?? null;
+    const cacheDecisionId = latest?.decision_id ?? null;
+    const forceNoCache = options.forceNoCache === true;
+    if (!forceNoCache) {
+        if (latest === null) {
+            if (options.strict === true) {
+                return {
+                    ok: false,
+                    message: `No triage-cache decision for #${n} (${repoSafe}). ` +
+                        `Accept first: task triage:accept -- --issue ${n} --repo ${repoSafe} ` +
+                        `(or omit --strict to soft-warn and proceed; --force-no-cache skips the gate).`,
+                    exitCode: 1,
+                    warnings,
+                    repo,
+                    matchedPaths: [],
+                    cacheStateAtPromote: null,
+                    cacheDecisionId: null,
+                };
+            }
+            warnings.push(`[scope:promote --from-issue] no triage-cache decision for #${n} (${repoSafe}); proceeding (soft warn). Use --strict to fail.`);
+        }
+        else if (latest.decision !== "accept") {
+            return {
+                ok: false,
+                message: `Refusing promote for #${n} (${repoSafe}): latest triage decision is '${sanitizeMsg(latest.decision)}' ` +
+                    `(decision_id=${latest.decision_id}). ` +
+                    `Accept first: task triage:accept -- --issue ${n} --repo ${repoSafe} ` +
+                    `or override with --force-no-cache.`,
+                exitCode: 1,
+                warnings,
+                repo,
+                matchedPaths: [],
+                cacheStateAtPromote: cacheState,
+                cacheDecisionId,
+            };
+        }
+    }
+    else {
+        warnings.push(`[scope:promote --from-issue] --force-no-cache: skipped reciprocity gate for #${n} ` +
+            `(cache decision was ${cacheState === null ? "absent" : `'${sanitizeMsg(cacheState)}'`}).`);
+    }
+    // Already in pending/ for this issue → idempotent success (auto-promote re-entry).
+    const alreadyPending = findLifecycleArtifactsForIssue(projectRoot, n, {
+        folder: "pending",
+        repo,
+    });
+    if (alreadyPending.length === 1 && options.explicitPath === undefined) {
+        warnings.push(`[scope:promote --from-issue] #${n} already pending (${sanitizeMsg(alreadyPending[0] ?? "")}); no-op.`);
+        return {
+            ok: true,
+            message: `No-op: issue #${n} already has pending scope ${alreadyPending[0]}`,
+            exitCode: 0,
+            warnings,
+            repo,
+            matchedPaths: alreadyPending,
+            cacheStateAtPromote: cacheState,
+            cacheDecisionId: forceNoCache && cacheState !== "accept" ? null : cacheDecisionId,
+            destPath: alreadyPending[0],
+        };
+    }
+    let matched = findProposedArtifactsForIssue(projectRoot, n, repo);
+    if (options.explicitPath !== undefined && options.explicitPath.trim().length > 0) {
+        const raw = options.explicitPath.trim();
+        const explicit = isAbsolute(raw) ? resolve(raw) : resolve(projectRoot, raw);
+        if (!existsSync(explicit)) {
+            return {
+                ok: false,
+                message: `Explicit path not found: ${sanitizeMsg(explicit)}`,
+                exitCode: 2,
+                warnings,
+                repo,
+                matchedPaths: matched,
+                cacheStateAtPromote: cacheState,
+                cacheDecisionId,
+            };
+        }
+        // Never accept an unrelated path — must match issue provenance (and repo).
+        try {
+            const data = JSON.parse(readFileSync(explicit, "utf8"));
+            if (!briefMatchesIssueAndRepo(data, n, repo)) {
+                return {
+                    ok: false,
+                    message: `Explicit path is not a provenance match for #${n} (${repoSafe}): ${sanitizeMsg(explicit)}.`,
+                    exitCode: 2,
+                    warnings,
+                    repo,
+                    matchedPaths: matched,
+                    cacheStateAtPromote: cacheState,
+                    cacheDecisionId,
+                };
+            }
+        }
+        catch (err) {
+            return {
+                ok: false,
+                message: `Explicit path is not readable JSON: ${sanitizeMsg(explicit)} (${String(err)})`,
+                exitCode: 2,
+                warnings,
+                repo,
+                matchedPaths: matched,
+                cacheStateAtPromote: cacheState,
+                cacheDecisionId,
+            };
+        }
+        if (matched.length > 0) {
+            const hit = matched.find((p) => resolve(p) === explicit);
+            if (hit === undefined) {
+                return {
+                    ok: false,
+                    message: `Explicit path is not among proposed matches for #${n}: ${sanitizeMsg(explicit)}. ` +
+                        `Matched: ${matched.map(sanitizeMsg).join(", ")}`,
+                    exitCode: 2,
+                    warnings,
+                    repo,
+                    matchedPaths: matched,
+                    cacheStateAtPromote: cacheState,
+                    cacheDecisionId,
+                };
+            }
+            matched = [hit];
+        }
+        else {
+            matched = [explicit];
+        }
+    }
+    if (matched.length === 0) {
+        return {
+            ok: false,
+            message: `No proposed/ scope artifact found for issue #${n} (${repoSafe}). ` +
+                `Ingest first (task triage:accept -- --issue ${n} --repo ${repoSafe}) ` +
+                `or pass an explicit path: task scope:promote -- <path>.`,
+            exitCode: 1,
+            warnings,
+            repo,
+            matchedPaths: [],
+            cacheStateAtPromote: cacheState,
+            cacheDecisionId,
+        };
+    }
+    if (matched.length > 1) {
+        const list = matched.map((p) => `  - ${sanitizeMsg(p)}`).join("\n");
+        return {
+            ok: false,
+            message: `Multiple proposed/ artifacts match issue #${n}; refuse to guess.\n${list}\n` +
+                `Promote one path explicitly: task scope:promote -- <path> ` +
+                `or re-run with --path <one-of-the-above>.`,
+            exitCode: 1,
+            warnings,
+            repo,
+            matchedPaths: matched,
+            cacheStateAtPromote: cacheState,
+            cacheDecisionId,
+        };
+    }
+    const filePath = matched[0];
+    const promoteResult = promotePath(filePath, {
+        projectRoot,
+        force: options.force,
+        actor: options.actor,
+        now: options.now,
+        fromIssue: n,
+        cacheDecisionId: forceNoCache && cacheState !== "accept" ? null : cacheDecisionId,
+        cacheStateAtPromote: cacheState,
+        forceNoCache,
+        requireAudit: true,
+    });
+    warnings.push(`[scope:promote --from-issue] cache decision for #${n} was ` +
+        `${cacheState === null ? "absent" : `'${sanitizeMsg(cacheState)}'`}` +
+        (promoteResult.ok ? " (proceeded)" : " (promote failed)"));
+    return {
+        ...promoteResult,
+        warnings,
+        repo,
+        matchedPaths: matched,
+        cacheStateAtPromote: cacheState,
+        cacheDecisionId: forceNoCache && cacheState !== "accept" ? null : cacheDecisionId,
+    };
+}
+//# sourceMappingURL=promote-from-issue.js.map

package/dist/scope/promote-path.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared single-path promote (proposed/ → pending/) with optional triage audit linkage (#1136).
+ */
+export interface PromotePathOptions {
+    readonly projectRoot?: string;
+    /** WIP-cap override (--force). */
+    readonly force?: boolean;
+    readonly actor?: string;
+    readonly now?: Date;
+    /** Issue number that triggered this promote (from-issue / auto-promote). */
+    readonly fromIssue?: number;
+    /** Accept (or other) decision_id from candidates.jsonl, when known. */
+    readonly cacheDecisionId?: string | null;
+    /** Latest cache decision string at promote time (accept / defer / null). */
+    readonly cacheStateAtPromote?: string | null;
+    /** True when reciprocity gate was skipped via --force-no-cache. */
+    readonly forceNoCache?: boolean;
+    /** Write promote audit entry even without from-issue linkage (default: only when linkage present). */
+    readonly alwaysAudit?: boolean;
+    /**
+     * When true, audit append failure is a hard error (from-issue / auto-promote
+     * require from_issue + cache fields). Default false for plain path promote.
+     */
+    readonly requireAudit?: boolean;
+}
+export interface PromotePathResult {
+    readonly ok: boolean;
+    readonly message: string;
+    readonly exitCode: number;
+    readonly destPath?: string;
+    readonly auditEntry?: Record<string, unknown> | null;
+    readonly wipCapOverride?: boolean;
+}
+/**
+ * Promote a single proposed-scope path to pending/, enforcing WIP and
+ * optionally recording from_issue / cache_decision_id on the scope audit log.
+ */
+export declare function promotePath(filePath: string, options?: PromotePathOptions): PromotePathResult;
+//# sourceMappingURL=promote-path.d.ts.map

package/dist/scope/promote-path.js

@@ -0,0 +1,105 @@
+/**
+ * Shared single-path promote (proposed/ → pending/) with optional triage audit linkage (#1136).
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
+import { resolveProjectRoot } from "./project-context.js";
+import { recordWipCapOverride, runTransition } from "./transition.js";
+import { utcNowIso } from "./vbrief-json.js";
+import { canonicalRelpath } from "./vbrief-ref.js";
+import { checkWipCap, formatWipCapRefusal } from "./wip-cap-check.js";
+/**
+ * Promote a single proposed-scope path to pending/, enforcing WIP and
+ * optionally recording from_issue / cache_decision_id on the scope audit log.
+ */
+export function promotePath(filePath, options = {}) {
+    const root = resolveProjectRoot(options.projectRoot);
+    if (root === null) {
+        return {
+            ok: false,
+            message: "Cannot determine project root. Pass --project-root PATH, set $DEFT_PROJECT_ROOT, or run from inside a directory tree that contains vbrief/ or .git/ (#535).",
+            exitCode: 2,
+        };
+    }
+    const resolved = resolve(filePath);
+    if (!existsSync(resolved)) {
+        return { ok: false, message: `File not found: ${resolved}`, exitCode: 2 };
+    }
+    const capCheck = checkWipCap(root, options.force === true);
+    if (!capCheck.allowed) {
+        return {
+            ok: false,
+            message: formatWipCapRefusal(capCheck),
+            exitCode: 1,
+        };
+    }
+    const now = options.now ?? new Date();
+    const result = runTransition("promote", resolved, now);
+    if (!result.ok) {
+        return { ok: false, message: result.message, exitCode: 1 };
+    }
+    const basename = resolved.split(/[/\\]/).pop() ?? "";
+    // Destination after promote is sibling pending/ under the same lifecycle root.
+    const lifecycleRoot = dirname(dirname(resolved));
+    const destPath = join(lifecycleRoot, "pending", basename);
+    let auditEntry = null;
+    const shouldAudit = options.alwaysAudit === true ||
+        options.fromIssue !== undefined ||
+        options.forceNoCache === true ||
+        options.cacheDecisionId !== undefined ||
+        options.cacheStateAtPromote !== undefined;
+    if (shouldAudit) {
+        try {
+            const entry = {
+                decision_id: newDecisionId(),
+                timestamp: utcNowIso(now),
+                action: "promote",
+                vbrief_path: canonicalRelpath(destPath, root),
+                from_status: "proposed",
+                to_status: "pending",
+                actor: options.actor ?? "operator",
+            };
+            if (options.fromIssue !== undefined) {
+                entry.from_issue = options.fromIssue;
+            }
+            if (options.cacheDecisionId !== undefined) {
+                entry.cache_decision_id = options.cacheDecisionId;
+            }
+            if (options.cacheStateAtPromote !== undefined) {
+                entry.cache_state_at_promote = options.cacheStateAtPromote;
+            }
+            if (options.forceNoCache === true) {
+                entry.force_no_cache = true;
+            }
+            append(entry, canonicalLogPath(root));
+            auditEntry = entry;
+        }
+        catch (err) {
+            if (options.requireAudit === true) {
+                return {
+                    ok: false,
+                    message: `Promoted ${basename} to pending/ but required scope audit failed: ${String(err)}. ` +
+                        `Artifact is in pending/; re-run promote will no-op once audit is writable.`,
+                    exitCode: 1,
+                    destPath,
+                    auditEntry: null,
+                    wipCapOverride: capCheck.forceOverride,
+                };
+            }
+            /* best-effort audit for plain path promote */
+        }
+    }
+    if (capCheck.forceOverride) {
+        recordWipCapOverride(destPath, root, capCheck, now);
+    }
+    return {
+        ok: true,
+        message: result.message,
+        exitCode: 0,
+        destPath,
+        auditEntry,
+        wipCapOverride: capCheck.forceOverride,
+    };
+}
+//# sourceMappingURL=promote-path.js.map

package/dist/session/ritual-entrypoint.d.ts

@@ -1,6 +1,10 @@
+import { type AgentHookReadinessResult } from "../verify-env/agent-hook-readiness.js";
 export declare const ENTRYPOINT_TIMEOUT_SECONDS = 300;
 export declare const ENTRYPOINT_TIMEOUT_EXIT_CODE = 124;
 export type RitualEntrypointFn = (argv: readonly string[]) => number;
+export interface DefaultRitualRunnerSeams {
+    readonly evaluateAgentHookReadiness?: (projectRoot: string) => AgentHookReadinessResult;
+}
 /** Run an in-process ritual entrypoint with stdout/stderr capture. */
 export declare function callMain(mainFn: RitualEntrypointFn, argv: readonly string[], _options?: {
     label?: string;
@@ -11,8 +15,8 @@ export declare function callMain(mainFn: RitualEntrypointFn, argv: readonly stri
 };
 /** CLI-shaped cache-fresh entrypoint (mirrors scripts/preflight_cache.py main). */
 export declare function runCacheFreshMain(argv: readonly string[]): number;
-/** Default gated-tier runner: in-process doctor + cache-fresh (mirrors verify_session_ritual.py). */
-export declare function defaultRitualRunner(command: readonly string[], projectRoot: string): {
+/** Default gated-tier runner: in-process hook readiness, doctor, and cache freshness. */
+export declare function defaultRitualRunner(command: readonly string[], projectRoot: string, seams?: DefaultRitualRunnerSeams): {
     code: number;
     stdout: string;
     stderr: string;

package/dist/session/ritual-entrypoint.js

@@ -1,5 +1,6 @@
 import { cmdDoctor } from "../doctor/main.js";
 import { evaluate } from "../preflight-cache/evaluate.js";
+import { evaluateAgentHookReadinessSafely, } from "../verify-env/agent-hook-readiness.js";
 export const ENTRYPOINT_TIMEOUT_SECONDS = 300;
 export const ENTRYPOINT_TIMEOUT_EXIT_CODE = 124;
 /** Run an in-process ritual entrypoint with stdout/stderr capture. */
@@ -66,9 +67,21 @@ export function runCacheFreshMain(argv) {
     }
     return result.code;
 }
-/** Default gated-tier runner: in-process doctor + cache-fresh (mirrors verify_session_ritual.py). */
-export function defaultRitualRunner(command, projectRoot) {
+/** Default gated-tier runner: in-process hook readiness, doctor, and cache freshness. */
+export function defaultRitualRunner(command, projectRoot, seams = {}) {
     const [verb, ...rest] = command;
+    if (verb === "verify:hooks-installed") {
+        const evaluateReadiness = seams.evaluateAgentHookReadiness
+            ? (root) => evaluateAgentHookReadinessSafely(root, seams.evaluateAgentHookReadiness)
+            : evaluateAgentHookReadinessSafely;
+        const result = evaluateReadiness(projectRoot);
+        const output = `${result.message}\n`;
+        return {
+            code: result.code,
+            stdout: result.stream === "stdout" ? output : "",
+            stderr: result.stream === "stderr" ? output : "",
+        };
+    }
     if (verb === "doctor") {
         return callMain((argv) => cmdDoctor(argv), ["--project-root", projectRoot, ...rest]);
     }

package/dist/session/session-ready.js

@@ -90,12 +90,20 @@ export function runSessionReady(projectRoot, options = {}) {
     const env = options.env ?? process.env;
     const lines = [];
     const steps = [];
-    const inspect = options.inspectRitual ?? ((root, opts) => inspectSessionRitual(root, opts));
-    const verify = options.verifyRitual ?? ((root, opts) => verifySessionRitual(root, opts));
-    const start = options.runStart ?? ((root, opts) => runSessionStart(root, opts));
+    const inspect = options.inspectRitual ?? inspectSessionRitual;
+    const verify = options.verifyRitual ?? verifySessionRitual;
+    const start = options.runStart ?? runSessionStart;
     const fetchAll = options.fetchAll ?? cacheFetchAll;
     const inferRepo = options.inferRepo ?? ((root) => inferSessionReadyRepo(root, env));
-    // --- Fast path: already green for PreToolUse gated inspect ---
+    const verifyOpts = {
+        tier: "gated",
+        posture: "mutation",
+        now,
+        runGit: options.runGit,
+        runner: options.runner,
+        forceGatedSteps: ["agent_hooks"],
+    };
+    // --- Fast path: inspect is green, but refresh functional hook readiness before returning. ---
     const gatedInspect = inspect(projectRoot, {
         tier: "gated",
         posture: "mutation",
@@ -103,6 +111,22 @@ export function runSessionReady(projectRoot, options = {}) {
         runGit: options.runGit,
     });
     if (gatedInspect.code === 0) {
+        steps.push("verify:session-ritual:gated");
+        const refreshed = verify(projectRoot, verifyOpts);
+        if (!isGatedVerifyActuallyReady(refreshed)) {
+            const message = refreshed.code === 0 && refreshed.bypassed
+                ? bypassedReadyFailure(refreshed)
+                : `${refreshed.message}\n  Remaining blocker after session:ready. Fix the step above, then re-run \`${readyCommand()}\`.`;
+            lines.push(message);
+            return {
+                code: refreshed.code === 0 ? 1 : refreshed.code,
+                message,
+                path: SESSION_READY_FAILED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
         const message = "OK session ready (gated ritual already fresh).";
         lines.push(message);
         return {
@@ -138,7 +162,7 @@ export function runSessionReady(projectRoot, options = {}) {
                 `session:start failed (exit ${startResult.code}). Recovery: run \`${readyCommand()}\` again after fixing the blocker.`;
             lines.push(message);
             return {
-                code: startResult.code === 0 ? 1 : startResult.code,
+                code: startResult.code,
                 message,
                 path: SESSION_READY_FAILED,
                 lines,
@@ -149,13 +173,6 @@ export function runSessionReady(projectRoot, options = {}) {
     }
     // --- Gated verify (lazy doctor + cache_fresh) ---
     steps.push("verify:session-ritual:gated");
-    const verifyOpts = {
-        tier: "gated",
-        posture: "mutation",
-        now,
-        runGit: options.runGit,
-        runner: options.runner,
-    };
     let verifyResult = verify(projectRoot, verifyOpts);
     if (isGatedVerifyActuallyReady(verifyResult)) {
         const message = "OK session ready (gated ritual verified).";
@@ -222,7 +239,7 @@ export function runSessionReady(projectRoot, options = {}) {
             };
         }
         steps.push("verify:session-ritual:gated:retry");
-        verifyResult = verify(projectRoot, verifyOpts);
+        verifyResult = verify(projectRoot, { ...verifyOpts, forceGatedSteps: [] });
         if (isGatedVerifyActuallyReady(verifyResult)) {
             const message = "OK session ready (recovered via cache refresh).";
             lines.push(message);
@@ -253,7 +270,7 @@ export function runSessionReady(projectRoot, options = {}) {
         `  Remaining blocker after session:ready. Fix the step above, then re-run \`${readyCommand()}\`.`;
     lines.push(message);
     return {
-        code: verifyResult.code === 0 ? 1 : verifyResult.code,
+        code: verifyResult.code,
         message,
         path: SESSION_READY_FAILED,
         lines,

package/dist/session/session-start.d.ts

@@ -16,7 +16,8 @@ export type SessionCeremonyTier = (typeof SESSION_CEREMONY_TIERS)[number];
 export declare const COLD_CEREMONY_TIER: SessionCeremonyTier;
 export declare const REARM_CEREMONY_TIER: SessionCeremonyTier;
 export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome"];
-export declare const GATED_STEPS: readonly ["doctor", "cache_fresh"];
+export declare const GATED_STEPS: readonly ["agent_hooks", "doctor", "cache_fresh"];
+export type GatedStepName = (typeof GATED_STEPS)[number];
 /** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
 export declare const ENV_SESSION_START_NETWORK = "DEFT_SESSION_START_NETWORK";
 /** Human-readable skip notice when optional network is off the hot path (#2991). */