@khoavu882/doflow 2.0.0-beta.4 → 2.0.0-beta.5

package/core/registry/storage.json

@@ -92,6 +92,24 @@
         "src/runtime/task-state.js"
       ]
     },
+    {
+      "id": "task-delivery",
+      "root": "project-state",
+      "path": "delivery",
+      "entry": "record",
+      "match": "^[A-Za-z0-9][A-Za-z0-9._-]*\\.json$",
+      "rule": "work",
+      "bound": {
+        "finishedDays": 30
+      },
+      "protect": null,
+      "moments": [
+        "verb"
+      ],
+      "writers": [
+        "src/runtime/task-state.js"
+      ]
+    },
     {
       "id": "task-readiness",
       "root": "project-state",
@@ -162,7 +180,8 @@
         "verb"
       ],
       "writers": [
-        "src/runtime/retrieval-plan.js"
+        "src/runtime/task-state.js",
+        "src/runtime/retrieval-record.js"
       ]
     },
     {
@@ -989,6 +1008,10 @@
       "file": "core/shared/scripts/doflow/bash/sync-context.sh",
       "reason": "agent context file (AGENTS.md or CLAUDE.md) managed block, owned by the install ledger"
     },
+    {
+      "file": "core/harnesses/shared/hooks/bridge/bridge.sh",
+      "reason": "caller-named trace file, appended only when the caller sets DOFLOW_BRIDGE_TRACE"
+    },
     {
       "file": "src/adapters/claude/index.js",
       "reason": "harness configuration/projection owned by the install ledger"

package/core/shared/scripts/doflow/bin/doflow-run

@@ -13,8 +13,10 @@
 # PATH pointing at any of them.
 #
 # Usage: doflow-run <verb> [args...]
+#   enforcement --harness <id> --policy <id> [--profile <id>] [--json]
 #   Every verb accepts --json. Exit 0 = success, 1 = an actionable finding, 2 = usage or
-#   resolution error. Arguments, stdin and exit status pass through the dispatcher unmodified —
+#   resolution error, 3 = context-pack overflow. Arguments, stdin and exit status pass through the
+#   dispatcher unmodified —
 #   `sync-context` reads its block body from stdin, so anything that buffered or consumed it here
 #   would break that verb rather than merely inconvenience it.
 
@@ -112,13 +114,14 @@ capture_failure() {
 
 # After a verb ran: a status outside {0, 1, 2} is a crash worth recording (a signal, a runtime that
 # died), minus what is not DoFlow's fault (DEC-031): 127 (command not found), 130, 141 and 143
-# (interrupted, broken pipe, terminated) and the task-not-found status 3 of `task-brief`. A Node
-# crash exits 1 and is recorded by the CLI itself, so it is never counted twice.
+# (interrupted, broken pipe, terminated), task-not-found status 3 of `task-brief`, and overflow
+# status 3 of `context-pack`. A Node crash exits 1 and is recorded by the CLI itself, so it is
+# never counted twice.
 capture_exit_status() {
   local verb="${1:-}" status="${2:-0}"
   case "$status" in
     0|1|2|127|130|141|143) return 0 ;;
-    3) [ "$verb" = "task-brief" ] && return 0 ;;
+    3) case "$verb" in task-brief|context-pack) return 0 ;; esac ;;
   esac
   capture_failure "$verb" "exit-$status" "$status"
   return 0
@@ -358,7 +361,7 @@ Workflow and evidence:
   claim            record or update a claim and its support state
   readiness        evaluate readiness; return state and missing items
   context-pack     emit the compiled context pack for a stage
-  retrieval-plan   declare the needs a stage will resolve, then report every declared item
+  retrieval-plan   declare the needs a stage will resolve, attempt each need, then report every declared item
   outcome          record a task's terminal state with its basis, or show what was recorded
   scaffold         emit the code scaffold the active feature's artifacts imply
   decision         register, list or compact the active feature's decisions
@@ -379,6 +382,7 @@ Observability:
   discover         missed opportunities in recorded runs
   inventory        both scopes at once: shadowed assets, drift, unmanaged contenders
   capabilities     provider resolution
+  enforcement      verified lifecycle policy coverage
   doctor           installation and provider health
   storage          report stored data and its retention bounds
 EOF
@@ -478,7 +482,7 @@ shell_helper_for() {
 is_node_verb() {
   case "$1" in
     classify|workflow|route|evidence|claim|readiness|context-pack|retrieval-plan|outcome|scaffold|decision|followup|lifecycle|goal|failure|verify|recover|leak-scan|\
-trace|stats|indicators|discover|inventory|capabilities|doctor|orchestrate|research-request|task-attempt|retrieve|model-role|storage|brief-tools|advise) return 0 ;;
+trace|stats|indicators|discover|inventory|capabilities|enforcement|doctor|orchestrate|research-request|task-attempt|retrieve|model-role|storage|brief-tools|advise) return 0 ;;
     *) return 1 ;;
   esac
 }

package/core/shared/skills/do-design/SKILL.md

@@ -64,12 +64,12 @@ a `design.md` for it invents an artifact its workflow never reads.
    ```bash
    "$DOFLOW" context-pack --task-id "<task id>" --json
    ```
-   **Exit 1 means the pack came back empty.** This early in the chain that is ordinary rather than a
-   problem — a feature reaching design for the first time has nothing recorded against it yet, and
-   `do-brainstorm` may not have batched evidence at all. Treat it the same way step 3's precondition
-   treats a missing `requirement.md`: note the gap in this stage's report and fall through to
-   reading `requirement.md` directly, which this step always did. When the pack is non-empty, read
-   it alongside `requirement.md` for the user stories, FRs, and NFRs the design must serve.
+   **Exit 1 means the pack came back empty; exit 3 means overflow: the pack is complete, act on
+   `overflowAction.message` and report the gap.** Early in the chain an empty pack is ordinary — a
+   new feature has nothing recorded yet, and `do-brainstorm` may not have batched evidence. Treat
+   it like step 3's precondition treats missing `requirement.md`: note the gap in this stage's report
+   and fall through to reading `requirement.md` directly. When non-empty, read it alongside
+   `requirement.md` for the user stories, FRs, and NFRs the design must serve.
 
 5. **Design** — per `--type` (architecture/api/component/database), produce the system-shape
    decisions: a C4 System Context diagram (actors + external systems this feature touches) and,

package/core/shared/skills/do-execute-plan/SKILL.md

@@ -163,16 +163,17 @@ Branch on the returned `outcome` field, not the exit code.
      ```bash
      "$DOFLOW" context-pack --task-id "<task id>" --json
      ```
-     **Exit 1 means the pack came back empty.** Unlike design and plan, this call sits right at the
-     point a subagent is about to be handed the task and told to act — so proceeding as though
-     nothing happened is exactly the failure this feature exists to remove. An empty pack here can
-     still be legitimate: step 4 lets a task reach `READY` on `callerAsserted` inputs alone, which
-     link no evidence. Do not withhold dispatch on this alone — readiness already governs whether the
-     task may be worked. Instead, carry the empty result into the group's brief itself: state in the
-     dispatch, next to the task-brief output, that no prior evidence or claims were compiled for this
-     task, so the subagent works from the plan/design text `task-brief` already supplies without
-     assuming a grounding evidence base that isn't there. A non-empty pack is included in the brief
-     as the subagent's prior context, same handoff.
+     **Exit 1 means the pack came back empty; exit 3 means overflow: the pack is complete, act on
+     `overflowAction.message` and report the gap.**
+     This call sits right at subagent dispatch — proceeding as though nothing happened is the defect
+     this feature removes. An empty pack here can still be legitimate: step 4 lets a task reach
+     `READY` on `callerAsserted` inputs alone, which link no evidence. Do not withhold dispatch on
+     this alone — readiness already governs whether the task may be worked. Instead, carry the empty
+     result into the group's brief itself: state in the dispatch, next to the task-brief output, that
+     no prior evidence or claims were compiled for this task, so the subagent works from the
+     plan/design text `task-brief` already supplies without assuming a grounding evidence base that
+     isn't there. A non-empty pack is included in the brief as the subagent's prior context, same
+     handoff.
    - Claim each task before dispatch and finish it with evidence: `references/task_attempts.md`.
    - Dispatch tasks to appropriate specialist archetypes:
      - Architecture & Schema $\rightarrow$ `system-architect`

package/core/shared/skills/do-execute-plan/references/readiness_gate.md

@@ -153,3 +153,5 @@ checklist it is. Do not halt indefinitely on a persistent `NEEDS_EVIDENCE` — r
 actually established, state which requirements it covers, and say what remains. And do not write
 `READY` yourself. The gate did not say it, and saying it on the gate's behalf is precisely the
 failure this page exists to prevent.
+
+Record an absence with `--absence --need <intent>`; a positive item never states `--absence`.

package/core/shared/skills/do-implement/SKILL.md

@@ -111,8 +111,9 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      "$DOFLOW" context-pack --task-id "<task id>" --json
      ```
      This verb exits 1 on an empty pack by design — nothing recorded is not the same as nothing
-     needed — and that non-zero exit is never read as success. Because this call only runs after the
-     evidence check above already found something recorded for this task id, an exit 1 here means
+     needed — and that non-zero exit is never read as success; exit 3 means overflow: the pack is
+     complete, act on `overflowAction.message` and report the gap. Because this call only runs after
+     the evidence check above already found something recorded for this task id, an exit 1 here means
      the compiled pack still held nothing usable (evidence with no linked claims, most likely):
      treat that as a mismatch worth naming in step 6's report, not as license to proceed as though
      there were no prior context to look for. On a normal, non-empty pack, carry its evidence and

package/core/shared/skills/do-plan/SKILL.md

@@ -67,14 +67,13 @@ not have.
    ```bash
    "$DOFLOW" context-pack --task-id "<task id>" --json
    ```
-   **Exit 1 means the pack came back empty.** By this point `do-design` should already have batched
-   its own stage-boundary evidence and claims (its step 8), so an empty pack here carries more
-   weight than it does at design time: either that batch never ran, or this task id doesn't match
-   the one design used. Treat it as advisory rather than blocking — plan's hard gate is artifact
-   existence only — but say so plainly in this stage's report, and in `plan.md`'s own §3 "Research &
-   Decisions": a decision written straight from `requirement.md`/`design.md` prose, with no compiled
-   pack behind it, must not be recorded as if it traced to prior evidence it doesn't have. When the
-   pack is non-empty, read it alongside `requirement.md`, `design.md`, and the constitution.
+   **Exit 1 means the pack came back empty; exit 3 means overflow: the pack is complete, act on
+   `overflowAction.message` and report the gap.** By this point `do-design` should have batched
+   evidence and claims (step 8), so an empty pack carries weight: either the batch never ran or the
+   task id mismatched. Treat it as advisory rather than blocking — plan's hard gate is artifact
+   existence only — but note it in this stage's report and `plan.md` §3 "Research & Decisions": a
+   decision written straight from prose without a compiled pack must not claim prior evidence. When
+   non-empty, read it alongside `requirement.md`, `design.md`, and the constitution.
    **Also read `specs.md` when step 1's `has_specs` is true** — use that flag, never a filesystem
    check of your own, and read the `specs` path the resolver returned. `/do-design` moves the
    interface and data-model contracts out of `design.md` into `specs.md` §1 as numbered `IC-###`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khoavu882/doflow",
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0-beta.5",
   "description": "DoFlow config installer — npx CLI for the registry-driven multi-harness install/update/remove lifecycle",
   "keywords": [
     "claude-code",

package/src/adapters/antigravity/index.js

@@ -178,6 +178,8 @@ function createAntigravityAdapter({ declaredPaths = DEFAULT_DECLARED_PATHS }
     apply,
     remove,
     verify: (options     , impl = {}) => verify(options, { ...impl, nativePaths: nativePathsFor }),
+    planHookDoors: (options     , impl = {}) => planHookDoors(options, { ...impl, nativePaths: nativePathsFor }),
+    verifyHookDoors: (options     , impl = {}) => verifyHookDoors(options, { ...impl, nativePaths: nativePathsFor }),
   };
 }
 
@@ -449,6 +451,29 @@ function plan(options      = {}, impl      = {}) {
   };
 }
 
+/** The hook front doors (IC-037): the shims and the hooks.json groups that run them, planned and
+ * verified alone. Project scope only, and only when the harness selected the hooks asset. */
+function planHookDoors(options      = {}, impl      = {}) {
+  const fsImpl = impl.fsImpl || fs;
+  const context = options.context ?? {};
+  const scope = options.scope ?? 'project';
+  if (!(options.assets ?? []).some((asset     ) => asset.id === HOOKS_ASSET_ID)) return { changes: [], conflicts: [], prerequisites: [], notices: [] };
+  const paths = (impl.nativePaths ?? singleton.nativePaths)({ ...options, scope, homeDir: context.homeDir });
+  const doors = planHooks({ paths, scope, neutralResources: ledgerResources(options), removing: false, repoRoot: context.repoRoot, fsImpl });
+  return { changes: doors.changes, conflicts: doors.conflicts, prerequisites: [], notices: [] };
+}
+
+function verifyHookDoors(options      = {}, impl      = {}) {
+  const fsImpl = impl.fsImpl || fs;
+  const context = options.context ?? {};
+  const scope = options.scope ?? 'project';
+  if (scope !== 'project' || !(options.assets ?? []).some((asset     ) => asset.id === HOOKS_ASSET_ID)) return { ok: true, statuses: [], resources: [], conflicts: [] };
+  const paths = (impl.nativePaths ?? singleton.nativePaths)({ ...options, scope, homeDir: context.homeDir });
+  const doors = verifyHooks({ options, paths, context, fsImpl });
+  const conflicts = doors.statuses.filter((status     ) => status.status === 'conflict').map((status     ) => status.reason ?? status.identity);
+  return { ok: conflicts.length === 0, ...doors, conflicts };
+}
+
 function apply(options      = {}, impl      = {}) {
   const fsImpl = impl.fsImpl || fs;
   // apply()/verify() are reached through the lifecycle with the same scope inputs plan() saw, so
@@ -506,6 +531,60 @@ function remove(options      = {}, impl      = {}) {
   return apply(options, impl);
 }
 
+/** The hook shims' bytes and the registered groups (project scope), as statuses and resources. */
+function verifyHooks({ options, paths, context, fsImpl }     ) {
+  const statuses        = [];
+  const resources        = [];
+  const hooksTarget = paths.hooksJson;
+  const scriptTargets                      = {
+    'pre-implementation-gate.sh': paths.hookScript,
+    'stop-check.sh': paths.stopHookScript,
+  };
+  // Source-side residue: reads the shims from THIS checkout (the authored source of the
+  // projection, not an install destination — the destination is declared as the paths above).
+  const scriptSourceDir = path.join(path.resolve(registryRepoRoot(options)), 'core', 'harnesses', 'antigravity', 'hooks');
+  const removingOp = (context.operation ?? options.operation ?? '') === 'remove';
+  const fingerprints                      = {};
+  let scriptsOk = true;
+  let anyPresent = false;
+  for (const identity of HOOK_SCRIPTS) {
+    let sourceFp = null;
+    try { sourceFp = sha256File(fsImpl, path.join(scriptSourceDir, identity)); } catch { /* checkout without that shim */ }
+    fingerprints[identity] = sourceFp;
+    const target = scriptTargets[identity];
+    const current = fsImpl.existsSync(target) ? sha256File(fsImpl, target) : null;
+    if (current !== null) anyPresent = true;
+    if (current === null || current !== sourceFp) scriptsOk = false;
+  }
+  const doc = readJsonObject(hooksTarget, { fsImpl });
+  const gate = doc?.[HOOKS_GROUP];
+  const stop = doc?.[STOP_HOOKS_GROUP];
+  const gateOk = Boolean(gate?.PreToolUse?.[0]?.hooks?.[0]?.command)
+    && gate.PreToolUse[0].hooks[0].command === scriptTargets['pre-implementation-gate.sh']
+    && gate.PreToolUse[0].matcher === GATE_MATCHER;
+  // Stop registration is matcher-free: handlers sit directly under the event key.
+  const stopOk = Array.isArray(stop?.Stop) && stop.Stop.length > 0
+    && stop.Stop[0]?.command === scriptTargets['stop-check.sh'];
+  const groupsOk = gateOk && stopOk;
+  statuses.push({ assetId: HOOKS_ASSET_ID, capability: 'hooks', status:
+    removingOp ? (!anyPresent && !groupsOk ? 'absent' : 'retained')
+      : (scriptsOk && groupsOk ? 'managed' : (!anyPresent && !groupsOk ? 'absent' : 'missing')),
+    ownershipIdentity: `${HARNESS}:hooks:registration`, target: hooksTarget });
+  if (!removingOp && scriptsOk && groupsOk) {
+    resources.push({ assetId: HOOKS_ASSET_ID, target: hooksTarget,
+      ownershipIdentity: `${HARNESS}:hooks:registration`, kind: 'hooks-json',
+      fingerprint: fingerprint(JSON.stringify(doc)), sourceVersion: 'registry-v1',
+      projection: { renderer: 'antigravity-hooks' } });
+    for (const identity of HOOK_SCRIPTS) {
+      resources.push({ assetId: HOOKS_ASSET_ID, target: scriptTargets[identity],
+        ownershipIdentity: `${HARNESS}:copy-tree:${HOOKS_ASSET_ID}:${identity}`,
+        kind: 'copy-tree-file', identity, fingerprint: fingerprints[identity],
+        sourceVersion: 'registry-v1', projection: { renderer: 'antigravity-hooks' } });
+    }
+  }
+  return { statuses, resources };
+}
+
 function verify(options      = {}, impl      = {}) {
   const fsImpl = impl.fsImpl || fs;
   const context = options.context ?? {};
@@ -564,53 +643,9 @@ function verify(options      = {}, impl      = {}) {
 
   // Hooks projection (project scope): the shims' bytes and the registered groups.
   if (scope === 'project') {
-    const hooksTarget = paths.hooksJson;
-    const scriptTargets                      = {
-      'pre-implementation-gate.sh': paths.hookScript,
-      'stop-check.sh': paths.stopHookScript,
-    };
-    // Source-side residue: reads the shims from THIS checkout (the authored source of the
-    // projection, not an install destination — the destination is declared as the paths above).
-    const scriptSourceDir = path.join(path.resolve(registryRepoRoot(options)), 'core', 'harnesses', 'antigravity', 'hooks');
-    const removingOp = (context.operation ?? options.operation ?? '') === 'remove';
-    const fingerprints                      = {};
-    let scriptsOk = true;
-    let anyPresent = false;
-    for (const identity of HOOK_SCRIPTS) {
-      let sourceFp = null;
-      try { sourceFp = sha256File(fsImpl, path.join(scriptSourceDir, identity)); } catch { /* checkout without that shim */ }
-      fingerprints[identity] = sourceFp;
-      const target = scriptTargets[identity];
-      const current = fsImpl.existsSync(target) ? sha256File(fsImpl, target) : null;
-      if (current !== null) anyPresent = true;
-      if (current === null || current !== sourceFp) scriptsOk = false;
-    }
-    const doc = readJsonObject(hooksTarget, { fsImpl });
-    const gate = doc?.[HOOKS_GROUP];
-    const stop = doc?.[STOP_HOOKS_GROUP];
-    const gateOk = Boolean(gate?.PreToolUse?.[0]?.hooks?.[0]?.command)
-      && gate.PreToolUse[0].hooks[0].command === scriptTargets['pre-implementation-gate.sh']
-      && gate.PreToolUse[0].matcher === GATE_MATCHER;
-    // Stop registration is matcher-free: handlers sit directly under the event key.
-    const stopOk = Array.isArray(stop?.Stop) && stop.Stop.length > 0
-      && stop.Stop[0]?.command === scriptTargets['stop-check.sh'];
-    const groupsOk = gateOk && stopOk;
-    statuses.push({ assetId: HOOKS_ASSET_ID, capability: 'hooks', status:
-      removingOp ? (!anyPresent && !groupsOk ? 'absent' : 'retained')
-        : (scriptsOk && groupsOk ? 'managed' : (!anyPresent && !groupsOk ? 'absent' : 'missing')),
-      ownershipIdentity: `${HARNESS}:hooks:registration`, target: hooksTarget });
-    if (!removingOp && scriptsOk && groupsOk) {
-      resources.push({ assetId: HOOKS_ASSET_ID, target: hooksTarget,
-        ownershipIdentity: `${HARNESS}:hooks:registration`, kind: 'hooks-json',
-        fingerprint: fingerprint(JSON.stringify(doc)), sourceVersion: 'registry-v1',
-        projection: { renderer: 'antigravity-hooks' } });
-      for (const identity of HOOK_SCRIPTS) {
-        resources.push({ assetId: HOOKS_ASSET_ID, target: scriptTargets[identity],
-          ownershipIdentity: `${HARNESS}:copy-tree:${HOOKS_ASSET_ID}:${identity}`,
-          kind: 'copy-tree-file', identity, fingerprint: fingerprints[identity],
-          sourceVersion: 'registry-v1', projection: { renderer: 'antigravity-hooks' } });
-      }
-    }
+    const hooks = verifyHooks({ options, paths, context, fsImpl });
+    statuses.push(...hooks.statuses);
+    resources.push(...hooks.resources);
   }
 
   const conflicts = [...statuses.filter((s) => s.status === 'conflict').map((s) => s.reason ?? s.identity), ...mcp.conflicts];
@@ -627,5 +662,6 @@ function conflictsToStatuses(conflicts     , assetId     , statuses     ) {
 
 module.exports = {
   HARNESS, nativePaths: singleton.nativePaths, discover, render, plan, apply, remove, verify,
+  planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors,
   createAntigravityAdapter,
 };

package/src/adapters/claude/index.js

@@ -480,6 +480,19 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
     return { changes, conflicts, prerequisites: [], notices: [...copyTree.notices, ...mcpPlan.notices] };
   }
 
+  /** The hook front doors (IC-037): the one asset that holds the scripts the settings hooks run. */
+  function hookDoorAssets(assets     ) { return (assets || []).filter((asset     ) => asset.id === 'claude.hooks-scripts'); }
+
+  function planHookDoors({ assets, scope, scopeRoot, context = {}, ledger }     ) {
+    const doors = planCopyTreeAssets({ assets: hookDoorAssets(assets), scope, scopeRoot, context, ledger, removing: false });
+    return { changes: doors.changes, conflicts: doors.conflicts, prerequisites: [], notices: doors.notices };
+  }
+
+  function verifyHookDoors({ assets, scope, scopeRoot, context = {} }     ) {
+    const doors = verifyCopyTreeAssets({ assets: hookDoorAssets(assets), scope, scopeRoot, context });
+    return { ok: doors.conflicts.length === 0, statuses: doors.statuses, resources: doors.resources, conflicts: doors.conflicts };
+  }
+
   function apply({ changes, scope, scopeRoot, context = {} }     ) {
     for (const change of changes) {
       if (change.projection?.renderer !== INSTRUCTION_RENDERER) continue;
@@ -536,7 +549,7 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
     return { ok: conflicts.length === 0, statuses, resources, conflicts };
   }
 
-  return { nativePaths, discover, render, plan, apply, remove, verify };
+  return { nativePaths, discover, render, plan, apply, remove, verify, planHookDoors, verifyHookDoors };
 }
 
 const singleton = createClaudeAdapter();
@@ -544,5 +557,6 @@ const singleton = createClaudeAdapter();
 module.exports = {
   nativePaths: singleton.nativePaths, discover: singleton.discover, render: singleton.render,
   plan: singleton.plan, apply: singleton.apply, remove: singleton.remove, verify: singleton.verify,
+  planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors,
   createClaudeAdapter,
 };

package/src/adapters/codex/hooks.js

@@ -7,6 +7,7 @@
 // that are not executable.  Trust is reported as a prerequisite rather than being bypassed.
 const fs = require('node:fs');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { verifyHookCommands } = require('../hook-commands.js');
 const { mergeHooks } = require('../../helper/settings-merge.js');
 const { atomicWrite } = require('./config.js');
@@ -102,7 +103,32 @@ function destinationFor(context      = {})         {
   throw new Error('A hook destination or Codex scope is required');
 }
 
-function planCodexHooks({ config, sourceFile, sourceHooksDir, destinationContext = {}, trusted = false, fsImpl = fs }      = {})      {
+/** DoFlow's record of a deployed hook script, in the ledger's fingerprint form: sha256 of its bytes. */
+function scriptFingerprint(bytes     )         { return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`; }
+
+/** The scripts beside the config that differ from the shipped source (or are absent), by name, and
+ * those among them a ledger row says were edited since DoFlow wrote them. A script with no row
+ * (an install from before scripts were recorded) is DoFlow's to refresh: the config deploy always
+ * overwrote it. `rows` are this harness's script rows: { target, fingerprint }. */
+function planHookScripts({ commands, sourceHooksDir, destinationHooksDir, rows = [], force = false, fsImpl = fs }     ) {
+  const sources = new Map                (commands.checks.map((check     ) => [check.script, check.file]                    ));
+  for (const name of shippedHookScripts(sourceHooksDir, fsImpl)) if (!sources.has(name)) sources.set(name, path.join(sourceHooksDir, name));
+  const stale           = [];
+  const edited           = [];
+  for (const [name, source] of sources) {
+    const target = path.join(destinationHooksDir, name);
+    if (fsImpl.existsSync(target)) {
+      const current = fsImpl.readFileSync(target);
+      if (current.equals(fsImpl.readFileSync(source))) continue;
+      const row = rows.find((item     ) => path.resolve(item.target) === path.resolve(target));
+      if (row && row.fingerprint !== scriptFingerprint(current) && !force) edited.push(name);
+    }
+    stale.push(name);
+  }
+  return { names: [...sources.keys()], stale, edited };
+}
+
+function planCodexHooks({ config, sourceFile, sourceHooksDir, destinationContext = {}, trusted = false, scriptRows = [], force = false, fsImpl = fs }      = {})      {
   let desired = config;
   try {
     if (!desired && sourceFile) desired = JSON.parse(fsImpl.readFileSync(sourceFile, 'utf8'));
@@ -130,16 +156,25 @@ function planCodexHooks({ config, sourceFile, sourceHooksDir, destinationContext
   }
   const content = schema.ok && mergedDesired ? `${JSON.stringify(mergedDesired, null, 2)}\n` : null;
   if (errors.length) return { ok: false, status: 'invalid-request', destination, original, changes: [], errors, commands };
-  const changed = original !== content;
+  const configChanged = original !== content;
   const destinationHooksDir = destinationContext.paths?.hooksDirectory
     || destinationContext.hooksDir
     || path.join(path.dirname(destination), 'hooks');
+  // The scripts are deployed with the config but are not part of it: a script whose bytes differ
+  // from the source is redeployed even when the config is already right.
+  const scripts = planHookScripts({ commands, sourceHooksDir, destinationHooksDir, rows: scriptRows, force, fsImpl });
+  if (scripts.edited.length) {
+    return { ok: false, status: 'conflict', destination, original, changes: [], commands,
+      errors: scripts.edited.map((name        ) => `Codex hook script '${name}' was modified outside DoFlow`) };
+  }
+  const scriptsOnly = !configChanged && scripts.stale.length > 0;
+  const changed = configChanged || scriptsOnly;
   // The scripts deployCodexHooks copies beside hooks.json, so a backup of this change holds them too.
   const companionTargets = [...new Set([
     ...commands.checks.map((check     ) => path.join(destinationHooksDir, check.script)),
     ...shippedHookScripts(sourceHooksDir, fsImpl).map((name        ) => path.join(destinationHooksDir, name)),
   ])].sort();
-  return { ok: true, status: changed ? 'change' : 'unchanged', destination, original, content,
+  return { ok: true, status: changed ? 'change' : 'unchanged', destination, original, content, scriptsOnly, scriptNames: scripts.names,
     changes: changed ? [{ type: fsImpl.existsSync(destination) ? 'update' : 'create', file: destination, companionTargets }] : [],
     errors: [], commands, trust: commands.trust, scriptsDir: sourceHooksDir, destinationHooksDir };
 }
@@ -147,7 +182,7 @@ function planCodexHooks({ config, sourceFile, sourceHooksDir, destinationContext
 function deployCodexHooks(plan     , { dryRun = false, fsImpl = fs }                                     = {})      {
   if (!plan.ok) return { ...plan, applied: false };
   if (dryRun || plan.status === 'unchanged') return { ...plan, applied: false };
-  atomicWrite(plan.destination, plan.content, fsImpl);
+  if (!plan.scriptsOnly) atomicWrite(plan.destination, plan.content, fsImpl);
   const deployed = new Set        ();
   for (const check of plan.commands.checks) {
     const target = path.join(plan.destinationHooksDir, check.script);
@@ -200,4 +235,4 @@ function removeCodexHookScripts({ scriptsDir, destinationHooksDir }
   return { removed };
 }
 
-module.exports = { SUPPORTED_EVENTS, validateHooksConfig, classifyClaudeGuardrails, verifyHookCommands, planCodexHooks, deployCodexHooks, shippedHookScripts, removeCodexHookScripts };
+module.exports = { SUPPORTED_EVENTS, validateHooksConfig, classifyClaudeGuardrails, verifyHookCommands, planCodexHooks, deployCodexHooks, scriptFingerprint, shippedHookScripts, removeCodexHookScripts };

package/src/adapters/codex/index.js

@@ -12,7 +12,7 @@ const crypto = require('node:crypto');
 const { configPath, fingerprint: configFingerprint, parseToml, planCodexConfig, applyCodexConfig } = require('./config.js');
 const { renderServer, planCodexMcp, applyCodexMcp, ownedCodexMcpIds, userDefinedCodexMcpIds, serverTableText } = require('./mcp.js');
 const { agentDirectory, discoverCodexAgents, planCodexAgents, applyCodexAgents } = require('./agents.js');
-const { planCodexHooks, deployCodexHooks, removeCodexHookScripts } = require('./hooks.js');
+const { planCodexHooks, deployCodexHooks, removeCodexHookScripts, scriptFingerprint } = require('./hooks.js');
 const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices } = require('../copy-tree.js');
 const { mergeMarkedSection, removeMarkedSection, MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
 const { nativeMcpCatalog } = require('../../registry/index.js');
@@ -445,9 +445,16 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
   /** Codex hooks.json is only replaced when the file on disk still matches the ledger's last-known
    * fingerprint — a foreign edit (or a record the ledger never owned) downgrades an otherwise-clean
    * plan to a conflict rather than silently overwriting it. */
-  function planHooksComponent({ native, neutralResources, context, adopt = false }     ) {
+  /** This scope's ledger rows for the hook scripts deployed beside hooks.json. */
+  function scriptRows(neutralResources     , context     ) {
+    return (neutralResources || []).filter((resource     ) => resource?.harness === HARNESS && resource.kind === 'hooks-script'
+      && (!resource.scope || resource.scope === context.scope));
+  }
+
+  function planHooksComponent({ native, neutralResources, context, adopt = false, force = false }     ) {
     let hooks = planCodexHooks({ config: native.hooksConfig, sourceFile: native.hooksSourceFile,
-      sourceHooksDir: native.hooksSourceDir, trusted: native.hooksTrusted, destinationContext: context });
+      sourceHooksDir: native.hooksSourceDir, trusted: native.hooksTrusted, destinationContext: context,
+      scriptRows: scriptRows(neutralResources, context), force });
     const hooksFile = hooks.destination;
     if (hooks.ok && fs.existsSync(hooksFile)) {
       const [record] = nativeManagedResources(neutralResources, context, { kind: 'hooks-file', target: hooksFile });
@@ -457,7 +464,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       // conflict — that one is `--force`'s business, not adoption's.
       if (!record && !adopt) {
         hooks = { ...hooks, ok: false, status: 'conflict', changes: [], errors: ['Codex hooks.json exists but is not owned by the neutral ledger'] };
-      } else if (record && record.fingerprint !== current) {
+      } else if (record && record.fingerprint !== current && !force) {
         hooks = { ...hooks, ok: false, status: 'conflict', changes: [], errors: ['Codex hooks.json was modified outside DoFlow'] };
       }
     }
@@ -466,13 +473,22 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
 
   /** Agents/hooks share one removing-vs-planning fork: removal always owns both via the neutral
    * ledger's own records, regardless of what native input the caller provided this run. */
+  /** A removal drops the rows of the hook scripts too. The scripts themselves go by their bytes
+   * (removeCodexHookScripts), so each row is only released here. */
+  function withScriptReleases(plan     , neutralResources     , context     , extra     ) {
+    const releases = scriptRows(neutralResources, context).map((row     ) => ({ type: 'remove', assetId: row.assetId, identity: row.identity,
+      target: row.target, ownershipIdentity: row.ownershipIdentity, kind: row.kind, release: true }));
+    return { ...plan, ...extra, changes: [...plan.changes, ...releases],
+      status: plan.status === 'unchanged' && releases.length ? 'change' : plan.status };
+  }
+
   function planAgentsAndHooksComponents({ native, neutralResources, context, agentsDirectory, removing, options, adopt = false }     ) {
     if (removing) {
       return {
         agents: ownedRemovalPlan(neutralResources, context, 'custom-agent', agentsDirectory),
         // The scripts deployed beside hooks.json have no ledger rows; remove() matches them by bytes.
-        hooks: { ...ownedRemovalPlan(neutralResources, context, 'hooks-file'),
-          scriptsDir: native.hooksSourceDir, destinationHooksDir: context.paths.hooksDirectory },
+        hooks: withScriptReleases(ownedRemovalPlan(neutralResources, context, 'hooks-file'), neutralResources, context,
+          { scriptsDir: native.hooksSourceDir, destinationHooksDir: context.paths.hooksDirectory }),
       };
     }
     const components                      = {};
@@ -483,7 +499,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       components.agents = planCodexAgents({ ...context, managedResources, sourceDir: native.agentsSourceDir, sourceVersion: options.sourceVersion ?? options.context?.sourceVersion, adopt });
     }
     if (native.hooksSourceFile !== undefined || native.hooksConfig !== undefined) {
-      components.hooks = planHooksComponent({ native, neutralResources, context, adopt });
+      components.hooks = planHooksComponent({ native, neutralResources, context, adopt, force: options.context?.force === true });
     }
     return components;
   }
@@ -542,6 +558,25 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       notices: [...copyTree.notices, ...(components.mcp?.notices || [])] };
   }
 
+  /** The hook front doors (IC-037): hooks.json and the scripts deployed beside it, planned and
+   * verified alone. A conflict reaches the lifecycle through `components`, as in plan(). */
+  function planHookDoors(options     ) {
+    const native = projectedNativeOptions(options);
+    const hooks = native.hooksSourceFile === undefined && native.hooksConfig === undefined ? null
+      : planHooksComponent({ native, neutralResources: options.managedResources || options.ledger?.resources || [], context: nativeContext(options),
+        adopt: options.context?.adopt === true, force: options.context?.force === true });
+    const changes        = [];
+    if (hooks) addChanges(changes, assetIdFor(options, 'hooks'), hooks, 'hooks');
+    return { changes, components: hooks ? { hooks } : {}, prerequisites: [], notices: [] };
+  }
+
+  function verifyHookDoors(options      = {}) {
+    const hooks = verifyHooksResource({ native: projectedNativeOptions(options), context: nativeContext(options), options,
+      sourceVersion: options.sourceVersion ?? options.context?.sourceVersion, recoveryRef: options.recoveryRef });
+    return { ok: hooks.conflicts.length === 0 && hooks.statuses.every((status     ) => status.status !== 'missing' && status.status !== 'conflict'),
+      resources: hooks.resources, statuses: hooks.statuses, conflicts: hooks.conflicts };
+  }
+
   /** Apply only native plans emitted by this adapter. MCP is first because it and
    * config.toml share a file; config is then re-planned over the MCP result so it
    * cannot overwrite an adjacent MCP table. */
@@ -579,7 +614,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
   function remove({ changes = [], dryRun = false }      = {}) {
     const result = apply({ changes, dryRun });
     const direct = new Map();
-    for (const change of changes) if (change?.nativePlan?.directRemove) direct.set(change.target, change);
+    for (const change of changes) if (change?.nativePlan?.directRemove && !change.retained) direct.set(change.target, change);
     for (const change of direct.values()) {
       if (!fs.existsSync(change.target)) continue;
       const current = sha256(fs.readFileSync(change.target, 'utf8'));
@@ -651,6 +686,13 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     if (!hooks.ok) conflicts.push(...hooks.errors);
     if (status === 'managed') resources.push(lifecycleResource({ scope: options.scope, assetId: assetIdFor(options, 'hooks'), kind: 'hooks-file', identity: 'hooks.json',
       target: hooks.destination, fingerprint: sha256(fs.readFileSync(hooks.destination, 'utf8')), sourceVersion, recoveryRef, projection: { renderer: 'codex-hooks' } }));
+    if (status === 'managed') {
+      for (const name of hooks.scriptNames) {
+        resources.push(lifecycleResource({ scope: options.scope, assetId: assetIdFor(options, 'hooks'), kind: 'hooks-script', identity: name,
+          target: path.join(hooks.destinationHooksDir, name), fingerprint: scriptFingerprint(fs.readFileSync(path.join(hooks.destinationHooksDir, name))),
+          sourceVersion, recoveryRef, projection: { renderer: 'codex-hooks' } }));
+      }
+    }
     return { statuses, resources, conflicts };
   }
 
@@ -691,7 +733,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     return { ok: conflicts.length === 0 && statuses.every((status) => status.status !== 'missing' && status.status !== 'conflict'), resources, statuses, conflicts };
   }
 
-  return { normalizeContext, nativeContext, projectedNativeOptions, nativeManagedResources, ownershipIdentity, discover, render, plan, apply, remove, verify };
+  return { normalizeContext, nativeContext, projectedNativeOptions, nativeManagedResources, ownershipIdentity, discover, render, plan, apply, remove, verify, planHookDoors, verifyHookDoors };
 }
 
 const singleton = createCodexAdapter();
@@ -703,5 +745,6 @@ module.exports = {
   ownershipIdentity: singleton.ownershipIdentity,
   discover: singleton.discover, render: singleton.render, plan: singleton.plan, apply: singleton.apply,
   remove: singleton.remove, verify: singleton.verify,
+  planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors,
   createCodexAdapter,
 };