@deftai/directive-core 0.78.0 → 0.79.1

package/dist/cache/empty-populate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * empty-populate.ts -- auto-fetch GitHub when the triage cache is empty (#2575).
+ *
+ * Empty/missing cache is the one case where a live list beats a false-empty
+ * "what's next?" answer. Non-empty caches keep the 24h freshness gate unchanged.
+ */
+import type { FetchAllReportImpl } from "./fetch.js";
+export interface EmptyPopulateResult {
+    readonly skipped: boolean;
+    readonly skipReason: string | null;
+    readonly repo: string | null;
+    readonly populated: boolean;
+    readonly succeeded: number | null;
+    readonly message: string;
+}
+export interface EmptyPopulateOptions {
+    readonly repo?: string | null;
+    readonly cacheRoot?: string;
+    readonly source?: string;
+    readonly inferRepoFn?: (cwd: string) => string | null;
+    readonly fetchFn?: (options: {
+        source: string;
+        repo: string;
+        cacheRoot: string;
+        force: boolean;
+    }) => FetchAllReportImpl;
+    readonly seedFn?: (projectRoot: string) => {
+        ok: boolean;
+    };
+    readonly backfillFn?: (projectRoot: string, repo: string | null) => {
+        ok: boolean;
+    };
+}
+/** True when `.deft-cache/github-issue/` has zero cached issue entries. */
+export declare function isTriageCacheEmpty(projectRoot: string, cacheRoot?: string): boolean;
+/**
+ * When the triage cache is empty, mirror `triage:bootstrap` populate steps:
+ * fetch-all from GitHub, seed the candidates log, backfill lifecycle accepts.
+ * Never auto-accepts new issues beyond existing xBRIEF backfill.
+ */
+export declare function maybeAutoPopulateEmptyCache(projectRoot: string, options?: EmptyPopulateOptions): EmptyPopulateResult;
+/** Idempotent hydrate hook for triage read paths (#2575). */
+export declare function ensureTriageCacheHydrated(projectRoot: string, options?: EmptyPopulateOptions): EmptyPopulateResult;
+//# sourceMappingURL=empty-populate.d.ts.map

package/dist/cache/empty-populate.js

@@ -0,0 +1,117 @@
+/**
+ * empty-populate.ts -- auto-fetch GitHub when the triage cache is empty (#2575).
+ *
+ * Empty/missing cache is the one case where a live list beats a false-empty
+ * "what's next?" answer. Non-empty caches keep the 24h freshness gate unchanged.
+ */
+import { join, resolve } from "node:path";
+import { stepSeedCandidatesLog } from "../triage/bootstrap/gitignore.js";
+import { inferRepoFromGit, stepBackfillAuditLog } from "../triage/bootstrap/index.js";
+import { ENV_TRIAGE_REPO } from "../triage/queue/constants.js";
+import { CACHE_DIR_NAME, CACHE_SOURCE, iterCachedIssues } from "../triage/summary/index.js";
+import { cacheFetchAll } from "./fetch.js";
+/** True when `.deft-cache/github-issue/` has zero cached issue entries. */
+export function isTriageCacheEmpty(projectRoot, cacheRoot) {
+    const root = resolve(projectRoot);
+    const resolvedCacheRoot = cacheRoot ?? join(root, CACHE_DIR_NAME);
+    return iterCachedIssues(resolvedCacheRoot).length === 0;
+}
+/**
+ * When the triage cache is empty, mirror `triage:bootstrap` populate steps:
+ * fetch-all from GitHub, seed the candidates log, backfill lifecycle accepts.
+ * Never auto-accepts new issues beyond existing xBRIEF backfill.
+ */
+export function maybeAutoPopulateEmptyCache(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const source = options.source ?? CACHE_SOURCE;
+    const cacheRoot = options.cacheRoot ?? join(root, CACHE_DIR_NAME);
+    if (!isTriageCacheEmpty(root, cacheRoot)) {
+        return {
+            skipped: true,
+            skipReason: "cache-non-empty",
+            repo: null,
+            populated: false,
+            succeeded: null,
+            message: "cache already populated",
+        };
+    }
+    const infer = options.inferRepoFn ?? inferRepoFromGit;
+    const envRepo = (process.env[ENV_TRIAGE_REPO] ?? "").trim();
+    const repo = options.repo ?? (envRepo.length > 0 ? envRepo : null) ?? infer(root);
+    if (repo === null) {
+        return {
+            skipped: true,
+            skipReason: "repo-not-resolved",
+            repo: null,
+            populated: false,
+            succeeded: null,
+            message: "could not infer repo for empty-cache auto-populate",
+        };
+    }
+    const fetch = options.fetchFn ?? cacheFetchAll;
+    let report;
+    try {
+        report = fetch({ source, repo, cacheRoot, force: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            skipped: true,
+            skipReason: "fetch-failed",
+            repo,
+            populated: false,
+            succeeded: null,
+            message,
+        };
+    }
+    const seed = options.seedFn ?? stepSeedCandidatesLog;
+    const seedOutcome = seed(root);
+    if (!seedOutcome.ok) {
+        return {
+            skipped: true,
+            skipReason: "seed-failed",
+            repo,
+            populated: false,
+            succeeded: report.issuesWritten,
+            message: "candidates log seed failed after fetch-all",
+        };
+    }
+    const backfill = options.backfillFn ?? stepBackfillAuditLog;
+    try {
+        const backfillOutcome = backfill(root, repo);
+        if (!backfillOutcome.ok) {
+            return {
+                skipped: true,
+                skipReason: "backfill-failed",
+                repo,
+                populated: false,
+                succeeded: report.issuesWritten,
+                message: "audit log backfill failed after fetch-all",
+            };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            skipped: true,
+            skipReason: "backfill-failed",
+            repo,
+            populated: false,
+            succeeded: report.issuesWritten,
+            message,
+        };
+    }
+    return {
+        skipped: false,
+        skipReason: null,
+        repo,
+        populated: true,
+        succeeded: report.issuesWritten,
+        message: `auto-populated empty triage cache from GitHub (${repo})`,
+    };
+}
+/** Idempotent hydrate hook for triage read paths (#2575). */
+export function ensureTriageCacheHydrated(projectRoot, options = {}) {
+    return maybeAutoPopulateEmptyCache(projectRoot, options);
+}
+//# sourceMappingURL=empty-populate.js.map

package/dist/cache/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./constants.js";
+export * from "./empty-populate.js";
 export * from "./errors.js";
 export * from "./fetch.js";
 export * from "./io.js";

package/dist/cache/index.js

@@ -1,4 +1,5 @@
 export * from "./constants.js";
+export * from "./empty-populate.js";
 export * from "./errors.js";
 export * from "./fetch.js";
 export * from "./io.js";

package/dist/check-updates/index.d.ts

@@ -2,10 +2,20 @@
 export declare const REMOTE_PROBE_DEFAULT_TIMEOUT = 5;
 /** Baked-in canonical upstream (#1320). Never probe consumer origin. */
 export declare const DEFT_UPSTREAM_URL = "https://github.com/deftai/directive.git";
+/** SSH form of the canonical upstream — allowlisted alongside HTTPS (#2601). */
+export declare const DEFT_UPSTREAM_SSH_URL = "git@github.com:deftai/directive.git";
 /** Reject git ls-remote targets that could be parsed as options (#CodeQL). */
 export declare function isSafeGitLsRemoteTarget(url: string): boolean;
 /** Return a trimmed upstream URL safe for `git ls-remote`, or null when rejected. */
 export declare function sanitizeGitLsRemoteTarget(url: string): string | null;
+/** Extract hostname from an https or git@ upstream URL. */
+export declare function extractUpstreamHostname(url: string): string | null;
+/** Reject localhost, link-local, and RFC1918 targets for blind SSRF hardening (#2601). */
+export declare function isPrivateOrLinkLocalUpstreamHost(hostname: string): boolean;
+/** True when a sanitized upstream URL is on the canonical allowlist (#2601). */
+export declare function isAllowlistedSafeUpstreamUrl(safeUrl: string): boolean;
+/** True when a manifest-controlled upstream URL is safe to probe (#2601). */
+export declare function isAllowlistedUpstreamUrl(url: string): boolean;
 export type RemoteProbeStatus = "ok" | "behind" | "skipped" | "no-upstream" | "no-tags" | "error";
 export interface RemoteProbeResult {
     readonly status: RemoteProbeStatus;

package/dist/check-updates/index.js

@@ -7,6 +7,9 @@ import { resolveVersion } from "../doctor/paths.js";
 export const REMOTE_PROBE_DEFAULT_TIMEOUT = 5.0;
 /** Baked-in canonical upstream (#1320). Never probe consumer origin. */
 export const DEFT_UPSTREAM_URL = "https://github.com/deftai/directive.git";
+/** SSH form of the canonical upstream — allowlisted alongside HTTPS (#2601). */
+export const DEFT_UPSTREAM_SSH_URL = "git@github.com:deftai/directive.git";
+const ALLOWED_UPSTREAM_URLS = new Set([DEFT_UPSTREAM_URL, DEFT_UPSTREAM_SSH_URL]);
 const MANIFEST_UPSTREAM_URL_KEYS = [
     "source_url",
     "url",
@@ -32,6 +35,83 @@ export function sanitizeGitLsRemoteTarget(url) {
     }
     return null;
 }
+/** Extract hostname from an https or git@ upstream URL. */
+export function extractUpstreamHostname(url) {
+    const trimmed = url.trim();
+    const httpsMatch = /^https?:\/\/([^/:?#]+)/i.exec(trimmed);
+    if (httpsMatch?.[1]) {
+        return httpsMatch[1].toLowerCase();
+    }
+    const sshMatch = /^git@([^:/]+):/i.exec(trimmed);
+    if (sshMatch?.[1]) {
+        return sshMatch[1].toLowerCase();
+    }
+    return null;
+}
+function parseIpv4Octets(hostname) {
+    const parts = hostname.split(".");
+    if (parts.length !== 4) {
+        return null;
+    }
+    const octets = [];
+    for (const part of parts) {
+        if (!/^\d+$/.test(part)) {
+            return null;
+        }
+        const value = Number(part);
+        if (value > 255) {
+            return null;
+        }
+        octets.push(value);
+    }
+    return octets;
+}
+/** Reject localhost, link-local, and RFC1918 targets for blind SSRF hardening (#2601). */
+export function isPrivateOrLinkLocalUpstreamHost(hostname) {
+    const host = hostname.trim().toLowerCase();
+    if (host.length === 0) {
+        return true;
+    }
+    if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) {
+        return true;
+    }
+    if (host === "::1" || host === "[::1]") {
+        return true;
+    }
+    const octets = parseIpv4Octets(host);
+    if (octets !== null) {
+        const [a, b] = octets;
+        if (a === 127)
+            return true;
+        if (a === 10)
+            return true;
+        if (a === 172 && b !== undefined && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 0)
+            return true;
+    }
+    return false;
+}
+/** True when a sanitized upstream URL is on the canonical allowlist (#2601). */
+export function isAllowlistedSafeUpstreamUrl(safeUrl) {
+    if (!ALLOWED_UPSTREAM_URLS.has(safeUrl)) {
+        return false;
+    }
+    const hostname = extractUpstreamHostname(safeUrl);
+    if (hostname === null || isPrivateOrLinkLocalUpstreamHost(hostname)) {
+        return false;
+    }
+    return true;
+}
+/** True when a manifest-controlled upstream URL is safe to probe (#2601). */
+export function isAllowlistedUpstreamUrl(url) {
+    const safe = sanitizeGitLsRemoteTarget(url);
+    return safe !== null && isAllowlistedSafeUpstreamUrl(safe);
+}
 function normalizePrereleaseForSort(pre) {
     const dot = pre.indexOf(".");
     if (dot <= 0) {
@@ -134,7 +214,7 @@ export function resolveUpstreamUrl(projectRoot) {
             const value = manifest[key];
             if (typeof value === "string" && value.trim()) {
                 const safe = sanitizeGitLsRemoteTarget(value);
-                if (safe) {
+                if (safe && isAllowlistedSafeUpstreamUrl(safe)) {
                     return safe;
                 }
             }

package/dist/doctor/main.js

@@ -349,7 +349,18 @@ export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, add
     try {
         const result = (seams.evaluateAgentHooks ?? evaluateAgentHooks)(projectRoot);
         if (result.code === 0) {
-            sink.success(`${checkName}: healthy`);
+            const message = `${checkName}: registered and structurally valid; ` +
+                "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+            sink.success(message);
+            addFinding({
+                severity: "skip",
+                message,
+                check: checkName,
+                status: "registered",
+                registrations: result.registrations,
+                trust_status: "not-verifiable",
+                trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+            });
             return;
         }
         const message = `${checkName}: ${result.message.replace(/\s+/g, " ").trim()}`;
@@ -358,7 +369,7 @@ export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, add
             severity: "warning",
             message,
             check: checkName,
-            status: result.code === 2 ? "unavailable" : "non-functional",
+            status: result.code === 2 ? "unavailable" : "incomplete",
             registrations: result.registrations,
             suggestion: "deft update",
         });

package/dist/doctor/payload-staleness.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { detectCanonicalVendoredManifest, isNpmManaged } from "../init-deposit/migrate.js";
+import { isPublishable } from "../release/version.js";
 import { CANONICAL_UPGRADE_COMMAND, NPM_PACKAGE_NAME, upgradeCommandFor, VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND, } from "./constants.js";
 import { locateManifest, parseInstallManifest } from "./manifest.js";
 import { readTextSafe, resolveDefaultFrameworkRoot } from "./paths.js";
@@ -203,7 +204,12 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
         });
         return;
     }
-    const installedCandidate = (tag || ref).trim().replace(/^refs\/tags\//, "");
+    const normalizedRef = ref.trim().replace(/^refs\/tags\//, "");
+    const normalizedTag = tag.trim().replace(/^refs\/tags\//, "");
+    // Branch pins (ref not a publishable tag) must not fall through to npm via a stale tag (#2538).
+    const installedCandidate = isPublishable(normalizedRef)
+        ? normalizedTag || normalizedRef
+        : normalizedRef;
     const applicability = evaluateReleaseAvailability(installedCandidate, null);
     if (applicability.status === "not-applicable") {
         if (remoteSha && installedSha === remoteSha) {

package/dist/hooks/dispatcher.d.ts

@@ -1,12 +1,12 @@
 import { type VerifyResult } from "../session/verify-session-ritual.js";
 import { type ActiveScopeInspection } from "./scope.js";
 export { DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool } from "./tools.js";
-export declare const HOOK_HOSTS: readonly ["claude", "grok", "cursor"];
+export declare const HOOK_HOSTS: readonly ["claude", "grok", "cursor", "codex"];
 export type HookHost = (typeof HOOK_HOSTS)[number];
 export declare const HOOK_EVENTS: readonly ["session.start", "tool.before"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 export type HookVerdict = "allow" | "deny";
-export type HookDecisionCode = "session-start" | "session-start-degraded" | "not-direct-write" | "invalid-input" | "ritual-not-ready" | "scope-not-ready" | "write-ready";
+export type HookDecisionCode = "session-start" | "session-start-degraded" | "not-direct-write" | "invalid-input" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready" | "write-ready";
 export interface HookDecision {
     readonly verdict: HookVerdict;
     readonly code: HookDecisionCode;
@@ -33,6 +33,18 @@ export interface HookPolicySeams {
     };
 }
 export declare function hookToolName(payload: unknown): string | null;
+/**
+ * Best-effort write-target path from host PreToolUse payloads (#2625).
+ * Hosts disagree on nesting (`tool_input.file_path` vs top-level `path`).
+ */
+export declare function hookWriteTargetPath(payload: unknown): string | null;
+/** POSIX-ish project-relative path for lifecycle matching. */
+export declare function toProjectRelativePosix(projectRoot: string, targetPath: string): string;
+/**
+ * Proposing a scope under xbrief/proposed/ (or legacy vbrief/proposed/) is
+ * planning, not implementation dispatch — exempt from the active-scope gate (#2625).
+ */
+export declare function isProposedLifecycleWrite(projectRoot: string, targetPath: string | null): boolean;
 export declare function projectRootFromHookPayload(payload: unknown, fallback: string): string;
 export declare function isHookHost(value: string): value is HookHost;
 export declare function isHookEvent(value: string): value is HookEvent;

package/dist/hooks/dispatcher.js

@@ -1,10 +1,11 @@
-import { resolve } from "node:path";
+import { relative, resolve, sep } from "node:path";
+import { hasArtifactSuffix } from "../layout/resolve.js";
 import { runSessionStartHookWrite } from "../session/session-start-hook.js";
 import { inspectSessionRitual } from "../session/verify-session-ritual.js";
 import { inspectActiveScope } from "./scope.js";
 import { isDirectWriteTool } from "./tools.js";
 export { DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool } from "./tools.js";
-export const HOOK_HOSTS = ["claude", "grok", "cursor"];
+export const HOOK_HOSTS = ["claude", "grok", "cursor", "codex"];
 export const HOOK_EVENTS = ["session.start", "tool.before"];
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
@@ -24,6 +25,39 @@ export function hookToolName(payload) {
         return null;
     return firstString(input.tool_name, input.toolName, input.tool);
 }
+/**
+ * Best-effort write-target path from host PreToolUse payloads (#2625).
+ * Hosts disagree on nesting (`tool_input.file_path` vs top-level `path`).
+ */
+export function hookWriteTargetPath(payload) {
+    const input = record(payload);
+    if (input === null)
+        return null;
+    const toolInput = record(input.tool_input) ?? record(input.toolInput) ?? record(input.input);
+    return firstString(toolInput?.file_path, toolInput?.filePath, toolInput?.path, input.file_path, input.filePath, input.path);
+}
+/** POSIX-ish project-relative path for lifecycle matching. */
+export function toProjectRelativePosix(projectRoot, targetPath) {
+    const abs = resolve(projectRoot, targetPath);
+    const rel = relative(resolve(projectRoot), abs);
+    return rel.split(sep).join("/");
+}
+/**
+ * Proposing a scope under xbrief/proposed/ (or legacy vbrief/proposed/) is
+ * planning, not implementation dispatch — exempt from the active-scope gate (#2625).
+ */
+export function isProposedLifecycleWrite(projectRoot, targetPath) {
+    if (targetPath === null || targetPath.trim().length === 0)
+        return false;
+    const posix = toProjectRelativePosix(projectRoot, targetPath);
+    // resolve()+relative() collapses mid-path `..`; only outside-root `..` remains.
+    if (posix.startsWith(".."))
+        return false;
+    const base = posix.includes("/") ? posix.slice(posix.lastIndexOf("/") + 1) : posix;
+    if (!hasArtifactSuffix(base))
+        return false;
+    return posix.startsWith("xbrief/proposed/") || posix.startsWith("vbrief/proposed/");
+}
 export function projectRootFromHookPayload(payload, fallback) {
     const input = record(payload);
     if (input === null)
@@ -124,6 +158,20 @@ export function decideHook(input, seams = {}) {
             "Recovery: run `deft session:start`, then " +
             "`deft verify:session-ritual -- --tier=gated`.");
     }
+    const writeTarget = hookWriteTargetPath(input.payload);
+    if (isProposedLifecycleWrite(projectRoot, writeTarget)) {
+        return {
+            verdict: "allow",
+            code: "write-propose-ready",
+            event: input.event,
+            host: input.host,
+            toolName,
+            projectRoot,
+            message: `Directive write gate allowed ${toolName} for a proposed lifecycle xBRIEF ` +
+                "(planning write; active scope not required).",
+            scopePath: null,
+        };
+    }
     let scope;
     try {
         scope = (seams.inspectScope ?? inspectActiveScope)(projectRoot);
@@ -132,8 +180,15 @@ export function decideHook(input, seams = {}) {
         scope = { ready: false, path: null, message: String(cause) };
     }
     if (!scope.ready) {
-        return deny(input, "scope-not-ready", toolName, `Directive denied ${toolName}: ${scope.message} ` +
-            "Recovery: run `deft scope:activate -- <path>` for the approved xBRIEF.");
+        const relTarget = writeTarget !== null ? toProjectRelativePosix(projectRoot, writeTarget) : null;
+        const proposedPathHint = relTarget !== null &&
+            (relTarget.startsWith("xbrief/proposed/") || relTarget.startsWith("vbrief/proposed/"))
+            ? " For a new proposal under xbrief/proposed/, include a lifecycle artifact " +
+                "filename (*.xbrief.json) in the Write/Edit payload so the gate can exempt " +
+                "planning writes (#2625)."
+            : " Recovery: run `deft scope:activate -- <path>` for the approved xBRIEF, " +
+                "or Write a new proposal to xbrief/proposed/*.xbrief.json (planning exemption).";
+        return deny(input, "scope-not-ready", toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
     }
     return {
         verdict: "allow",
@@ -150,22 +205,24 @@ export function decideHook(input, seams = {}) {
 export function renderHostDecision(host, decision) {
     if (decision.verdict === "allow")
         return "";
-    if (host === "claude") {
-        return JSON.stringify({
-            hookSpecificOutput: {
-                hookEventName: "PreToolUse",
-                permissionDecision: "deny",
-                permissionDecisionReason: decision.message,
-            },
-        });
-    }
-    if (host === "grok") {
-        return JSON.stringify({ decision: "deny", reason: decision.message });
+    switch (host) {
+        case "claude":
+        case "codex":
+            return JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: decision.message,
+                },
+            });
+        case "grok":
+            return JSON.stringify({ decision: "deny", reason: decision.message });
+        case "cursor":
+            return JSON.stringify({
+                permission: "deny",
+                user_message: decision.message,
+                agent_message: decision.message,
+            });
     }
-    return JSON.stringify({
-        permission: "deny",
-        user_message: decision.message,
-        agent_message: decision.message,
-    });
 }
 //# sourceMappingURL=dispatcher.js.map

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

@@ -2,7 +2,7 @@ import type { HookHost } from "../hooks/dispatcher.js";
 import type { InitDepositIo } from "./constants.js";
 export declare const DIRECT_WRITE_HOOK_MATCHER: string;
 export declare const DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
-export declare const AGENT_HOOK_PATHS: readonly [".claude/settings.json", ".grok/hooks/deft.json", ".cursor/hooks.json"];
+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 interface AgentHookInspection {

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

@@ -8,6 +8,7 @@ export const AGENT_HOOK_PATHS = [
     ".claude/settings.json",
     ".grok/hooks/deft.json",
     ".cursor/hooks.json",
+    ".codex/hooks.json",
 ];
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
@@ -125,6 +126,10 @@ export function writeAgentHookDeposit(projectRoot, io = { printf: () => undefine
             merge: (config, path) => mergeNestedConfig(config, path, "grok"),
         },
         { path: AGENT_HOOK_PATHS[2], merge: mergeCursorConfig },
+        {
+            path: AGENT_HOOK_PATHS[3],
+            merge: (config, path) => mergeNestedConfig(config, path, "codex"),
+        },
     ];
     const prepared = definitions.map((definition) => {
         const absolute = join(projectRoot, definition.path);
@@ -187,6 +192,11 @@ export function inspectAgentHookDeposit(projectRoot) {
             valid: (config) => hasNestedRegistration(config, "grok"),
         },
         { host: "cursor", path: AGENT_HOOK_PATHS[2], valid: hasCursorRegistration },
+        {
+            host: "codex",
+            path: AGENT_HOOK_PATHS[3],
+            valid: (config) => hasNestedRegistration(config, "codex"),
+        },
     ];
     return definitions.map((definition) => {
         const absolute = join(projectRoot, definition.path);

package/dist/init-deposit/hygiene.js

@@ -24,6 +24,7 @@ export function installerManagedMatchers() {
         { exact: ".claude/settings.json" },
         { exact: ".grok/hooks/deft.json" },
         { exact: ".cursor/hooks.json" },
+        { exact: ".codex/hooks.json" },
         { exact: ".gitattributes" },
         { exact: ".gitignore" },
         { exact: "greptile.json" },

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

@@ -18,6 +18,7 @@ import { ensureInitGitignoreLines, reconstituteDepositFromContent } from "./giti
 import { depositStagePaths, printCommitGuidance } from "./hygiene.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
+import { ensurePrettierIgnoreLines } from "./prettierignore.js";
 import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeAgentsSkills, writeConsumerGitHooks, writeConsumerVbrief, writeInstallManifest, } from "./scaffold.js";
 export function parseInitArgv(canonicalArgv, userArgv = []) {
     const args = [...canonicalArgv, ...userArgv];
@@ -137,6 +138,7 @@ export async function runInitDeposit(args, io, seams = {}) {
     await reconstituteDepositFromContent(contentRoot, deftDir, copyContent);
     await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
     ensureInitGitignoreLines(projectDir, io);
+    ensurePrettierIgnoreLines(projectDir, io);
     const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
     const version = readContentVersion(contentRoot, seams.readPackageVersion ?? readCorePackageVersion);
     const manifestFields = {

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

@@ -0,0 +1,21 @@
+/**
+ * Consumer `.prettierignore` upkeep for install and npm-managed update (#2534).
+ *
+ * Managed `.deft/core/` is outside the consumer Prettier format gate. Official
+ * install and `directive update` heal the ignore entry idempotently without
+ * reformatting the vendored deposit.
+ *
+ * Refs #2534, #670.
+ */
+import type { InitDepositIo } from "./constants.js";
+/** Directory ignore entry for the hybrid deposit. */
+export declare const PRETTIERIGNORE_DEFT_CORE_LINE = ".deft/core/";
+export interface EnsurePrettierIgnoreResult {
+    readonly changed: boolean;
+}
+/**
+ * Ensure the consumer `.prettierignore` excludes managed `.deft/core/` from
+ * Prettier. Idempotent; preserves consumer preamble.
+ */
+export declare function ensurePrettierIgnoreLines(projectDir: string, io: InitDepositIo): EnsurePrettierIgnoreResult;
+//# sourceMappingURL=prettierignore.d.ts.map