@deftai/directive-runtime 0.128.0 → 0.129.1

package/UPGRADING.md

@@ -79,7 +79,7 @@ npm install -g --allow-scripts=<pkg,...> <package>
 
 ### Framework monorepo contributors
 
-Install source of truth for this repo is **pnpm** (`packageManager` field; CI uses `pnpm install --frozen-lockfile`). Install-script builds are gated by `pnpm-workspace.yaml` **`allowBuilds`** (currently `esbuild: true`). Do **not** treat `npm approve-scripts` under the pnpm virtual store as monorepo SoT.
+Install source of truth for this repo is **pnpm** (`packageManager` field; CI uses `pnpm install --frozen-lockfile`). Install-script builds are gated by `pnpm-workspace.yaml` **`allowBuilds`** (currently `esbuild: true` where needed). **`allowBuilds` is PM-owned**: Directive install/upgrade uses the package manager for `package.json` / lockfile pin ops and does **not** hand-edit `allowBuilds`. If pnpm fails with `ERR_PNPM_IGNORED_BUILDS`, recover with `pnpm approve-builds` or set a real `true`/`false` under `allowBuilds` — do **not** commit pnpm's interactive placeholder text. Pin/add paths already pass `--ignore-scripts` so ordinary consumer upgrades should not need a runtime `allowBuilds` entry. Do **not** treat `npm approve-scripts` under the pnpm virtual store as monorepo SoT.
 
 ### Git / remote package sources and publish
 
@@ -456,7 +456,7 @@ import schema from "@deftai/directive-types/schemas/xbrief-core-0.8.schema.json"
 
 **Supported public API:** `@deftai/directive-types` and its published schema subpaths only. **`@deftai/directive-core` is published for npm dependency resolution but is not a supported library surface** — use the `deft` / `directive` CLI for behavior.
 
-**Schema source of truth:** `content/vbrief/schemas/vbrief-core.schema.json` in the directive repo. The types package mirrors it to `packages/types/schemas/` at build time; `deft` install also deposits schemas under project-root `xbrief/schemas/`. When in doubt, treat the directive repo canonical file as authoritative and refresh mirrors with `deft update` (install) or `@deftai/directive-types` (npm).
+**Schema source of truth (OVPR):** the pinned runtime ships schemas under `node_modules/@deftai/directive-runtime/vbrief/schemas/` (current write schema: `xbrief-core-0.8.schema.json`). The types package publishes the same artifacts as `@deftai/directive-types/schemas/…`. Framework source authors at `content/vbrief/schemas/`. Install does **not** deposit project-root `xbrief/schemas/`. Refresh via `directive upgrade` (pin) or `@deftai/directive-types` (npm).
 
 ### `deft migrate` vs pre-v0.20 document-model migration
 

package/dist/contract-entry.js

@@ -61,6 +61,8 @@ export async function handleContractEntrypoint(argv) {
             operation: operation,
             from,
             root,
+            // Explicit pre-write operator force only (#5837); self-complete never forces.
+            forceGitHooks: hasFlag(argv, "--force-githooks"),
         });
         process.stdout.write(`${JSON.stringify(result)}\n`);
         if (result.conflicts.length > 0)

package/dist/doctor-diagnose.d.ts

@@ -8,6 +8,11 @@ export { DEFT_DOCTOR_HOOK_DIAGNOSTIC };
 export declare const GIT_PRECONDITION_RECOVERY_GUIDANCE = "git init, then directive install --repair";
 /** Readiness detail when wiring-ready is withheld solely because there is no .git. */
 export declare const GIT_PRECONDITION_READINESS_DETAIL = "incomplete install \u2014 wiring-ready withheld until git init (hooksPath not activatable)";
+/**
+ * #5798 — wiring-only residual (pin/install/readiness already ok).
+ * Names Taskfile/probe surface; owned wiring damage → repair, never npm i -g hammer.
+ */
+export declare const WIRING_RECOVERY_GUIDANCE = "inspect Taskfile.yml / Directive wiring targets (or probe); for owned wiring damage: directive install --repair";
 /** Patterns that must never appear as doctor remedies (AC12.5–12.7 / AC9.11). */
 export declare const FORBIDDEN_DOCTOR_REMEDY_PATTERNS: readonly RegExp[];
 export interface DoctorSurface {
@@ -34,11 +39,11 @@ export interface DoctorDiagnosis {
     readonly failClosed: boolean;
     readonly dataStatus: DataStatusValue;
     /**
-     * Install/wiring recovery guidance, or F-010 git-precondition recovery.
-     * Null when healthy or schema-only.
+     * Install-class (AC9.7), wiring-only (#5798 WIRING_RECOVERY_GUIDANCE), or
+     * F-010 git-precondition recovery. Null when healthy or schema-only.
      */
     readonly remedy: string | null;
-    /** Schema/data migration remedy; never `install --repair`. */
+    /** Schema/data migration remedy; never the AC9.7 global-install hammer. */
     readonly schemaRemedy: "directive upgrade" | null;
     /**
      * F-010: set when pin/lock/installed/GENERATION/wiring are ok but readiness is

package/dist/doctor-diagnose.js

@@ -16,6 +16,11 @@ export { DEFT_DOCTOR_HOOK_DIAGNOSTIC };
 export const GIT_PRECONDITION_RECOVERY_GUIDANCE = "git init, then directive install --repair";
 /** Readiness detail when wiring-ready is withheld solely because there is no .git. */
 export const GIT_PRECONDITION_READINESS_DETAIL = "incomplete install — wiring-ready withheld until git init (hooksPath not activatable)";
+/**
+ * #5798 — wiring-only residual (pin/install/readiness already ok).
+ * Names Taskfile/probe surface; owned wiring damage → repair, never npm i -g hammer.
+ */
+export const WIRING_RECOVERY_GUIDANCE = "inspect Taskfile.yml / Directive wiring targets (or probe); for owned wiring damage: directive install --repair";
 /** Patterns that must never appear as doctor remedies (AC12.5–12.7 / AC9.11). */
 export const FORBIDDEN_DOCTOR_REMEDY_PATTERNS = [
     /\balign-pin\b/i,
@@ -208,13 +213,26 @@ function chooseRemedy(sync, dataStatus, projectRoot) {
     if (isNoGitReadinessGap(sync, projectRoot)) {
         return { remedy: GIT_PRECONDITION_RECOVERY_GUIDANCE, schemaRemedy: null };
     }
-    const installBroken = sync.failClosed || !sync.inSync || !sync.predicates.installed.ok || !sync.predicates.pin.ok;
-    // AC12.7: never dual-prescribe upgrade + repair. Install/wiring recovery wins
-    // when both faults are present; schema-only behind → upgrade alone.
-    if (installBroken) {
+    const p = sync.predicates;
+    // Install-class faults only — do NOT fold wiring-only into AC9.7 via !inSync (#5798).
+    const pinInstallBroken = sync.failClosed || !p.pin.ok || !p.installed.ok || !p.lockfile.ok || !p.generation.ok;
+    // Missing readiness (with .git) stays install/repair guidance (acceptance / F-010 peer).
+    const readinessBroken = !p.readiness.ok;
+    const wiringBroken = !p.wiring.ok;
+    const schemaBehind = dataStatus === "migration_needed" || dataStatus === "diagnosis_failed";
+    // AC12.7: AC9.7 global install + schema upgrade must not co-prescribe for install-class red.
+    if (pinInstallBroken || readinessBroken) {
         return { remedy: INSTALLATION_RECOVERY_GUIDANCE, schemaRemedy: null };
     }
-    if (dataStatus === "migration_needed" || dataStatus === "diagnosis_failed") {
+    // Wiring-only (good pin/install/readiness): failure-shaped map — Taskfile/probe, not npm i -g.
+    if (wiringBroken) {
+        return {
+            remedy: WIRING_RECOVERY_GUIDANCE,
+            // Distinct surfaces may list both (#5798 multi-surface); not the AC9.7+upgrade dual ban.
+            schemaRemedy: schemaBehind ? "directive upgrade" : null,
+        };
+    }
+    if (schemaBehind) {
         return { remedy: null, schemaRemedy: "directive upgrade" };
     }
     return { remedy: null, schemaRemedy: null };

package/dist/hook-dispatch.js

@@ -239,7 +239,8 @@ export function run(argv, seams = {}) {
     }
     // Wave 2d / AC8.6: registered hooks self-complete when readiness is missing/stale.
     // Suppressed when DEFT_DOCTOR_HOOK_DIAGNOSTIC is set (AC9.10).
-    maybeSelfCompleteSetup(projectRoot, { fromHook: true });
+    // #5885: thread seams.writeErr so preserved tracked hooks disclose on stderr.
+    maybeSelfCompleteSetup(projectRoot, { fromHook: true, writeErr });
     const environ = mergeHookDispatchEnviron(payload);
     let decision = decideHook({
         host: args.host,

package/dist/self-complete.d.ts

@@ -5,6 +5,8 @@ import { type SetupResult } from "./setup.js";
  * Doctor sets this before spawning committed hook probes.
  */
 export declare const DEFT_DOCTOR_HOOK_DIAGNOSTIC = "DEFT_DOCTOR_HOOK_DIAGNOSTIC";
+/** Test-only: clear the process once-guard for preserved disclosure. */
+export declare function resetSelfCompletePreservedDisclosureForTests(): void;
 export type SelfCompleteSkipReason = "fast-path" | "doctor-diagnostic" | "ineligible" | "not-configured" | "fail-closed" | "no-version";
 export interface SelfCompleteResult {
     readonly ran: boolean;
@@ -24,5 +26,7 @@ export declare function maybeSelfCompleteSetup(projectRoot: string, options?: {
     readonly environ?: NodeJS.ProcessEnv;
     /** Hooks are always eligible unless doctor-diagnostic. */
     readonly fromHook?: boolean;
+    /** Stderr sink for preserved tracked-hook disclosure (#5885); never stdout. */
+    readonly writeErr?: (text: string) => void;
 }): SelfCompleteResult;
 //# sourceMappingURL=self-complete.d.ts.map

package/dist/self-complete.js

@@ -23,6 +23,22 @@ import { runSetup } from "./setup.js";
  * Doctor sets this before spawning committed hook probes.
  */
 export const DEFT_DOCTOR_HOOK_DIAGNOSTIC = DOCTOR_DIAGNOSTIC_ENV;
+/** Process once-guard for preserved-hook stderr lines (#5885). */
+const emittedPreservedLines = new Set();
+/** Test-only: clear the process once-guard for preserved disclosure. */
+export function resetSelfCompletePreservedDisclosureForTests() {
+    emittedPreservedLines.clear();
+}
+function disclosePreservedHooks(preserved, writeErr) {
+    if (preserved === undefined || preserved.length === 0)
+        return;
+    for (const line of preserved) {
+        if (emittedPreservedLines.has(line))
+            continue;
+        emittedPreservedLines.add(line);
+        writeErr(`${line}\n`);
+    }
+}
 /** Installation-management and help heads that never trigger self-complete. */
 const INELIGIBLE_HEADS = new Set([
     "install",
@@ -76,6 +92,7 @@ function readOwnRuntimeVersion() {
  */
 export function maybeSelfCompleteSetup(projectRoot, options = {}) {
     const environ = options.environ ?? process.env;
+    const writeErr = options.writeErr ?? ((text) => process.stderr.write(text));
     if (isDoctorDiagnosticEnv(environ)) {
         return { ran: false, skipReason: "doctor-diagnostic", setup: null };
     }
@@ -113,6 +130,7 @@ export function maybeSelfCompleteSetup(projectRoot, options = {}) {
         from: version,
         root: projectRoot,
     });
+    disclosePreservedHooks(setup.preserved, writeErr);
     return { ran: true, skipReason: null, setup };
 }
 //# sourceMappingURL=self-complete.js.map

package/dist/setup-wiring.d.ts

@@ -84,10 +84,28 @@ export declare function ensureHostHooks(projectRoot: string, hostHooksPolicy?: H
 export declare const PRE_PUSH_BOUND_PRE_PR_MARKER = "deft:pre-pr-bound-push-v1";
 /** AC8.6 / AC2.5 / F-008 — disclosed when hooks files exist but core.hooksPath cannot activate. */
 export declare const GIT_HOOKS_INACTIVE_NO_GIT = "Git hooks inactive until git init + eligible repair/self-complete (core.hooksPath not set)";
-export declare function ensureGitHooks(projectRoot: string): {
+/**
+ * True when `rel` is tracked by git in `projectRoot` (#5837). Any git failure
+ * (no repo, no git binary) reads as untracked, which keeps the replace path lawful.
+ */
+export declare function isGitTrackedPath(projectRoot: string, rel: string): boolean;
+/** Disclosure for a tracked divergent managed hook kept in place (#5837). */
+export declare function formatTrackedHookPreserved(rel: string): string;
+export interface EnsureGitHooksOptions {
+    /** Explicit pre-write operator force: replace tracked divergent managed hooks (#5837). */
+    readonly forceTrackedReplace?: boolean;
+    /**
+     * Test-only: override the next body for named relative hook paths so fixtures
+     * can reach refuse-to-downgrade under forceTrackedReplace (#5885 / #5804).
+     */
+    readonly testOnlyNextBodyByRel?: Readonly<Record<string, string>>;
+}
+export declare function ensureGitHooks(projectRoot: string, options?: EnsureGitHooksOptions): {
     created: string[];
     modified: string[];
     conflicts: string[];
+    /** Tracked divergent managed hooks kept in place; a non-failure outcome (#5837). */
+    preserved: string[];
     /** True only when core.hooksPath is relative .githooks (AC9.9). */
     hooksPathActive: boolean;
     /** Human disclosure when hooks are not live; null when active. */

package/dist/setup-wiring.js

@@ -8,6 +8,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { containedChmod, containedRemove, containedWrite, } from "../vendor/directive-core/dist/fs/contained-write.js";
 import { DIRECT_WRITE_HOOK_MATCHER, KILL_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../vendor/directive-core/dist/hooks/tools.js";
+import { GROK_PRETOOLUSE_WRAPPER_COMMAND, GROK_PRETOOLUSE_WRAPPER_REL_PATH, grokPretooluseWrapperScriptSource, isGrokWrapperCommand, } from "../vendor/directive-core/dist/init-deposit/agent-hooks.js";
 import { INSTALLATION_RECOVERY_GUIDANCE, RUNTIME_PACKAGE_PATH_PREFIX, } from "../vendor/directive-core/dist/install-health/constants.js";
 import { MANAGED_SECTION_CLOSE, MANAGED_SECTION_OPEN_PREFIX, } from "../vendor/directive-core/dist/install-health/index.js";
 import { applyAgentsRefresh } from "../vendor/directive-core/dist/platform/agents-md.js";
@@ -428,6 +429,7 @@ function rewriteCommandsInValue(value) {
 }
 function isManagedHookCommand(command) {
     return (command.includes(HOOK_BIN_COMMAND) ||
+        isGrokWrapperCommand(command) ||
         /(^|[\s"`'])deft-hook([\s"`']|$)/.test(command) ||
         command.includes("deft hook:dispatch"));
 }
@@ -436,26 +438,49 @@ function object(value) {
         ? value
         : null;
 }
-function nestedManagedGroup(value) {
+function isManagedNestedHookCommand(command, host) {
+    if (host === "grok" && isGrokWrapperCommand(command))
+        return true;
+    return isManagedHookCommand(command) && command.includes(`--host ${host}`);
+}
+/**
+ * Drop managed commands inside a nested group; keep custom hooks and group fields.
+ * Returns null when the group is empty after filtering (or was fully managed).
+ * Non-group entries pass through unchanged.
+ */
+function filterManagedCommandsInNestedGroup(value, host, options = {}) {
     const group = object(value);
     if (group === null || !Array.isArray(group.hooks))
-        return false;
-    return group.hooks.some((h) => {
+        return value;
+    const keptHooks = group.hooks.filter((h) => {
         const hook = object(h);
-        return typeof hook?.command === "string" && isManagedHookCommand(hook.command);
+        if (typeof hook?.command !== "string")
+            return true;
+        if (options.hostAgnostic)
+            return !isManagedHookCommand(hook.command);
+        return !isManagedNestedHookCommand(hook.command, host);
     });
+    if (keptHooks.length === 0)
+        return null;
+    return { ...group, hooks: keptHooks };
 }
 function cursorManagedEntry(value) {
     const entry = object(value);
     return typeof entry?.command === "string" && isManagedHookCommand(entry.command);
 }
+function nestedToolCommand(host, event) {
+    // Grok PreToolUse deposits the outer-deny wrapper (#5807 / #5656 / #5715).
+    if (host === "grok" && event === "tool.before")
+        return GROK_PRETOOLUSE_WRAPPER_COMMAND;
+    return hookCommand(host, event);
+}
 function nestedGroup(host, event, matcher) {
     return {
         ...(event === "tool.before" && matcher !== undefined ? { matcher } : {}),
         hooks: [
             {
                 type: "command",
-                command: hookCommand(host, event),
+                command: nestedToolCommand(host, event),
                 timeout: event === "tool.before" ? 30 : 5,
             },
         ],
@@ -478,17 +503,9 @@ function stripNestedManaged(existing, host) {
         if (!(key in hooks))
             continue;
         const filtered = Array.isArray(hooks[key])
-            ? hooks[key].filter((e) => {
-                const group = object(e);
-                if (group === null || !Array.isArray(group.hooks))
-                    return true;
-                return !group.hooks.some((h) => {
-                    const hook = object(h);
-                    return (typeof hook?.command === "string" &&
-                        isManagedHookCommand(hook.command) &&
-                        hook.command.includes(`--host ${host}`));
-                });
-            })
+            ? hooks[key]
+                .map((e) => filterManagedCommandsInNestedGroup(e, host))
+                .filter((e) => e !== null)
             : [];
         if (filtered.length > 0)
             nextHooks[key] = filtered;
@@ -525,13 +542,21 @@ function stripCursorManaged(existing) {
     }
     return { ...existing, version: 1, hooks: nextHooks };
 }
+function keepCustomNestedGroups(entries, host) {
+    return entries
+        .map((e) => filterManagedCommandsInNestedGroup(e, host, {
+        // Merge clears any managed identity (incl. Grok wrapper) before redeposit.
+        hostAgnostic: true,
+    }))
+        .filter((e) => e !== null);
+}
 function mergeNestedHost(existing, host, options) {
     const hooks = object(existing.hooks) ?? {};
     const session = Array.isArray(hooks.SessionStart)
-        ? hooks.SessionStart.filter((e) => !nestedManagedGroup(e))
+        ? keepCustomNestedGroups(hooks.SessionStart, host)
         : [];
     const preTool = Array.isArray(hooks.PreToolUse)
-        ? hooks.PreToolUse.filter((e) => !nestedManagedGroup(e))
+        ? keepCustomNestedGroups(hooks.PreToolUse, host)
         : [];
     const nextHooks = {
         ...hooks,
@@ -543,10 +568,10 @@ function mergeNestedHost(existing, host, options) {
     };
     if (options.compact) {
         const preCompact = Array.isArray(hooks.PreCompact)
-            ? hooks.PreCompact.filter((e) => !nestedManagedGroup(e))
+            ? keepCustomNestedGroups(hooks.PreCompact, host)
             : [];
         const postCompact = Array.isArray(hooks.PostCompact)
-            ? hooks.PostCompact.filter((e) => !nestedManagedGroup(e))
+            ? keepCustomNestedGroups(hooks.PostCompact, host)
             : [];
         nextHooks.PreCompact = [...preCompact, nestedGroup(host, "session.compact")];
         nextHooks.PostCompact = [...postCompact, nestedGroup(host, "session.compact")];
@@ -665,6 +690,38 @@ export function ensureHostHooks(projectRoot, hostHooksPolicy = loadHostHooksPoli
         else
             modified.push(spec.rel);
     }
+    // #5807: rewrite/redeposit Grok outer-deny wrapper so leftover deft-hook deny
+    // bodies cannot sit beside a healthy PreToolUse registration.
+    const grokEnabled = isHostHookDepositEnabled("grok", hostHooksPolicy);
+    const wrapperRel = GROK_PRETOOLUSE_WRAPPER_REL_PATH;
+    if (grokEnabled) {
+        const wrapperBody = grokPretooluseWrapperScriptSource();
+        const wrapperPrior = readText(join(projectRoot, wrapperRel));
+        if (wrapperPrior !== wrapperBody) {
+            writeContained(projectRoot, wrapperRel, wrapperBody);
+            if (wrapperPrior === null)
+                created.push(wrapperRel);
+            else
+                modified.push(wrapperRel);
+        }
+        if (existsSync(join(projectRoot, wrapperRel))) {
+            try {
+                containedChmod({ root: projectRoot, target: wrapperRel, mode: 0o755 });
+            }
+            catch {
+                /* best-effort on platforms without chmod */
+            }
+        }
+    }
+    else if (existsSync(join(projectRoot, wrapperRel))) {
+        try {
+            containedRemove({ root: projectRoot, target: wrapperRel });
+            modified.push(wrapperRel);
+        }
+        catch {
+            /* best-effort strip */
+        }
+    }
     return { created, modified };
 }
 const GITHOOK_HELPER = `#!/usr/bin/env sh
@@ -740,22 +797,51 @@ function isOurGitHookBody(rel, body) {
 const EXECUTABLE_GITHOOKS = new Set([".githooks/pre-commit", ".githooks/pre-push"]);
 /** AC8.6 / AC2.5 / F-008 — disclosed when hooks files exist but core.hooksPath cannot activate. */
 export const GIT_HOOKS_INACTIVE_NO_GIT = "Git hooks inactive until git init + eligible repair/self-complete (core.hooksPath not set)";
-export function ensureGitHooks(projectRoot) {
+/**
+ * True when `rel` is tracked by git in `projectRoot` (#5837). Any git failure
+ * (no repo, no git binary) reads as untracked, which keeps the replace path lawful.
+ */
+export function isGitTrackedPath(projectRoot, rel) {
+    try {
+        execFileSync("git", ["-C", projectRoot, "ls-files", "--error-unmatch", "--", rel], {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Disclosure for a tracked divergent managed hook kept in place (#5837). */
+export function formatTrackedHookPreserved(rel) {
+    return `${rel}: tracked managed hook differs from the template; kept (not a failure). Review and pass --force-githooks to setup to replace it (#5837)`;
+}
+export function ensureGitHooks(projectRoot, options = {}) {
     const created = [];
     const modified = [];
     const conflicts = [];
+    const preserved = [];
+    const force = options.forceTrackedReplace === true;
     const files = [
         { rel: ".githooks/_directive-run.sh", body: GITHOOK_HELPER },
         { rel: ".githooks/pre-commit", body: PRE_COMMIT },
         { rel: ".githooks/pre-push", body: PRE_PUSH },
     ];
     for (const file of files) {
-        const next = file.body.endsWith("\n") ? file.body : `${file.body}\n`;
+        const override = options.testOnlyNextBodyByRel?.[file.rel];
+        const rawNext = override ?? file.body;
+        const next = rawNext.endsWith("\n") ? rawNext : `${rawNext}\n`;
         const prior = readText(join(projectRoot, file.rel));
         if (prior !== null && prior !== next && !isOurGitHookBody(file.rel, prior)) {
             conflicts.push(`${file.rel}: existing hook is not Directive-managed; refusing to overwrite (chain or remove manually)`);
             continue;
         }
+        // Tracked divergent preserve (#5837): never overwrite a committed hook body,
+        // even a Directive-managed one, unless the operator forced the replace.
+        if (prior !== null && prior !== next && !force && isGitTrackedPath(projectRoot, file.rel)) {
+            preserved.push(formatTrackedHookPreserved(file.rel));
+            continue;
+        }
         // Refuse-to-downgrade: marker-aware installer will not replace a newer enrolled
         // pre-push arm with an older body that lacks the monotonic marker (#5804).
         if (file.rel === ".githooks/pre-push" &&
@@ -802,7 +888,10 @@ export function ensureGitHooks(projectRoot) {
             catch {
                 stillReferenced = true;
             }
-            if (!stillReferenced) {
+            if (!stillReferenced && !force && isGitTrackedPath(projectRoot, legacyHelperRel)) {
+                preserved.push(formatTrackedHookPreserved(legacyHelperRel));
+            }
+            else if (!stillReferenced) {
                 try {
                     const rem = containedRemove({ root: projectRoot, target: legacyHelperRel });
                     if (rem.removed)
@@ -847,7 +936,7 @@ export function ensureGitHooks(projectRoot) {
             inactiveDisclosure = `Git hooks inactive: core.hooksPath is '${current}' (not .githooks)`;
         }
     }
-    return { created, modified, conflicts, hooksPathActive, inactiveDisclosure };
+    return { created, modified, conflicts, preserved, hooksPathActive, inactiveDisclosure };
 }
 const MINIMAL_TASKFILE = `version: '3'
 

package/dist/setup.d.ts

@@ -11,6 +11,8 @@ export interface SetupResult {
     readonly modified: string[];
     readonly removed: string[];
     readonly conflicts: string[];
+    /** Tracked divergent managed hooks kept in place; non-failure, present only when non-empty (#5837). */
+    readonly preserved?: string[];
     readonly message: string;
 }
 /**
@@ -22,6 +24,8 @@ export declare function runSetup(options: {
     readonly operation: SetupOperation;
     readonly from: string;
     readonly root: string;
+    /** Explicit pre-write operator force to replace tracked divergent managed hooks (#5837). */
+    readonly forceGitHooks?: boolean;
 }): SetupResult;
 export declare function setupChangeCount(result: SetupResult): number;
 //# sourceMappingURL=setup.d.ts.map

package/dist/setup.js

@@ -9,14 +9,20 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ContainedWriteError, containedRemove, containedWrite, } from "../vendor/directive-core/dist/fs/contained-write.js";
+import { defaultTrackedNames, isTrackedDeletePath, stageFrameworkPaths, } from "../vendor/directive-core/dist/init-deposit/hygiene.js";
+import { seedMinimalProjectDefinition } from "../vendor/directive-core/dist/init-deposit/init-deposit.js";
 import { buildOwnershipRecord, fingerprintContent, ownershipRecordsEqual, readEvidenceGenerationNumber, readOwnershipRecord, writeOwnershipRecord, } from "../vendor/directive-core/dist/install-health/index.js";
 import { assertInventoryCompleteness } from "./installer-output-inventory.js";
 import { CURRENT_DATA_SCHEMA_VERSION, DATA_SCHEMA_MARKER_REL } from "./migrate.js";
 import { isConvertStrategyFrom, runStrategy } from "./removal-steps/index.js";
 import { ensureAgentsManagedSection, ensureGitHooks, ensureHostHooks, ensureOpenClawIntegrations, ensureSkillPointers, ensureSlashCommands, ensureTaskfileInclude, listSkillPointerPaths, listVerifiedManagedSlashCommandPaths, RUNTIME_PREFIX, } from "./setup-wiring.js";
 const SEED_PLACEHOLDER_REL = "xbrief/.directive-seed-placeholder";
+const PD_REL = "xbrief/PROJECT-DEFINITION.xbrief.json";
 const GEN_REL = ".deft/GENERATION.json";
 const WIRING_READY_DIR_REL = ".deft/directive";
+const XBRIEF_LIFECYCLE_DIRS = ["proposed", "pending", "active", "completed", "cancelled"];
+const XBRIEF_LIFECYCLE_GITKEEP = "# Keeps this xbrief/ lifecycle directory present in version control so the\n" +
+    "# deft-directive-setup pre-cutover guard does not fire on a fresh install (#4666).\n";
 function readOwnRuntimeVersion() {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
@@ -144,6 +150,59 @@ function createSeedPlaceholder(projectRoot) {
     writeContained(projectRoot, SEED_PLACEHOLDER_REL, "# Directive initial seed placeholder (install only; repair must not create this).\n");
     return SEED_PLACEHOLDER_REL;
 }
+/** Install-only: five xbrief lifecycle dirs + .gitkeeps (#4666 / AC8.4). */
+function ensureXbriefLifecycleGitkeeps(projectRoot) {
+    const created = [];
+    for (const sub of XBRIEF_LIFECYCLE_DIRS) {
+        const rel = relPosix("xbrief", sub, ".gitkeep");
+        if (existsSync(join(projectRoot, rel)))
+            continue;
+        writeContained(projectRoot, rel, XBRIEF_LIFECYCLE_GITKEEP);
+        created.push(rel);
+    }
+    return created;
+}
+/**
+ * Stage this-run setup writes after install/upgrade (#4666).
+ * Always includes PD + lifecycle gitkeeps when present (fix the 0.126 hole).
+ * Does not `git add` every existing managed matcher path — that would stage
+ * unrelated dirty peers (package.json / custom .githooks/*). Keeps exact
+ * this-run paths (no skill/command parent compaction) so sibling untracked
+ * skills stay unstaged. This-run removals may be missing on disk so tracked
+ * deletions can reach `git add`; untracked missing paths are skipped so one
+ * unmatched pathspec cannot fail the whole staging batch (#5883 P1 / #3394).
+ */
+function stageSetupManagedPaths(projectRoot, thisRunPaths) {
+    const present = [];
+    const missingAllow = [];
+    const seen = new Set();
+    const add = (rel, opts = {}) => {
+        const normalized = rel.replace(/\\/g, "/");
+        if (!normalized || seen.has(normalized))
+            return;
+        const onDisk = existsSync(join(projectRoot, normalized));
+        if (!onDisk && !opts.allowMissing)
+            return;
+        seen.add(normalized);
+        if (onDisk)
+            present.push(normalized);
+        else
+            missingAllow.push(normalized);
+    };
+    for (const rel of thisRunPaths) {
+        add(rel, { allowMissing: true });
+    }
+    add(PD_REL);
+    for (const sub of XBRIEF_LIFECYCLE_DIRS) {
+        add(relPosix("xbrief", sub, ".gitkeep"));
+    }
+    const tracked = new Set(defaultTrackedNames(projectRoot, missingAllow));
+    const stagePaths = [
+        ...present,
+        ...missingAllow.filter((path) => isTrackedDeletePath(path, tracked)),
+    ];
+    stageFrameworkPaths(projectRoot, stagePaths);
+}
 /** Shared host settings / Taskfile: only Directive entries are owned (structured-entry). */
 const STRUCTURED_ENTRY_RELS = [
     { path: ".claude/settings.json", entryKey: "hooks" },
@@ -207,7 +266,9 @@ function buildOwnershipArtifacts(projectRoot) {
         });
     }
     const seedAbs = join(projectRoot, SEED_PLACEHOLDER_REL);
-    if (existsSync(seedAbs)) {
+    const pdAbs = join(projectRoot, PD_REL);
+    const hasLifecycle = XBRIEF_LIFECYCLE_DIRS.some((sub) => existsSync(join(projectRoot, "xbrief", sub, ".gitkeep")));
+    if (existsSync(seedAbs) || existsSync(pdAbs) || hasLifecycle) {
         artifacts.push({
             path: "xbrief",
             kind: "retained",
@@ -223,6 +284,8 @@ function buildOwnershipArtifacts(projectRoot) {
  */
 export function runSetup(options) {
     const { operation, from, root } = options;
+    let preserved = [];
+    const withPreserved = () => (preserved.length > 0 ? { preserved } : {});
     const created = [];
     const modified = [];
     const removed = [];
@@ -297,7 +360,8 @@ export function runSetup(options) {
         const hooks = ensureHostHooks(root);
         created.push(...hooks.created);
         modified.push(...hooks.modified);
-        const githooks = ensureGitHooks(root);
+        const githooks = ensureGitHooks(root, { forceTrackedReplace: options.forceGitHooks === true });
+        preserved = githooks.preserved;
         created.push(...githooks.created);
         modified.push(...githooks.modified);
         conflicts.push(...githooks.conflicts);
@@ -309,10 +373,15 @@ export function runSetup(options) {
         // Seeds only on first-time install (AC8.4); repair/upgrade never create them.
         // AC6.2: leave data-schema current for empty/seeded install. Repair may write a
         // missing marker (not a migration); upgrade still migrates when data is behind.
+        // #4666: greenfield retain — PD + lifecycle dirs (not placeholder-only); no schemas.
         if (operation === "install" && conflicts.length === 0) {
             const seed = createSeedPlaceholder(root);
             if (seed !== null)
                 created.push(seed);
+            created.push(...ensureXbriefLifecycleGitkeeps(root));
+            if (seedMinimalProjectDefinition(root, { printf: () => undefined })) {
+                created.push(PD_REL);
+            }
         }
         if ((operation === "install" || operation === "repair") &&
             conflicts.length === 0 &&
@@ -335,6 +404,12 @@ export function runSetup(options) {
             created.push(GEN_REL);
         else if (!unchanged || legacyConversion || convertViaRemovals)
             modified.push(GEN_REL);
+        // #4666: stage this-run managed peers including PD + lifecycle after install/upgrade.
+        // Still no auto-commit. Repair does not stage (seeds are install-only; upgrade stages
+        // existing PD/lifecycle with refreshed wiring).
+        if (conflicts.length === 0 && (operation === "install" || operation === "upgrade")) {
+            stageSetupManagedPaths(root, [...created, ...modified, ...removed]);
+        }
         if (conflicts.length > 0) {
             // Never publish readiness after conflict; invalidate any existing marker (AC8.6).
             invalidateReadinessMarkers(root, removed);
@@ -350,6 +425,7 @@ export function runSetup(options) {
                 modified,
                 removed,
                 conflicts,
+                ...withPreserved(),
                 message: "setup completed with conflicts",
             };
         }
@@ -371,6 +447,7 @@ export function runSetup(options) {
                 modified,
                 removed,
                 conflicts,
+                ...withPreserved(),
                 message: `setup ${operation} completed for ${runtimeVersion} (${RUNTIME_PREFIX}); ${disclosure}`,
             };
         }
@@ -388,6 +465,7 @@ export function runSetup(options) {
             modified,
             removed,
             conflicts,
+            ...withPreserved(),
             message: `setup ${operation} completed for ${runtimeVersion} (${RUNTIME_PREFIX})`,
         };
     }