@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/adapters/claude/index.js

@@ -183,6 +183,24 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
   function settingsContent(fileName     , raw     , scope     ) {
     return fileName === 'settings.json' && scope !== 'global' ? raw.split(GLOBAL_HOOK_PREFIX).join(PROJECT_HOOK_PREFIX) : raw;
   }
+  /** Hook tiers (maint-hooks): with Claude outside `hooks.harnesses` the managed settings carry no
+   * `hooks` block. Returns the managed text to write and the hooks it left out, which a merge strips
+   * from the live file so an earlier install's entries do not stay behind. */
+  function tieredSettings(fileName     , raw     , context     ) {
+    if (fileName !== 'settings.json' || context?.hooksOff !== true) return { raw, droppedHooks: null };
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch { return { raw, droppedHooks: null }; }
+    if (!parsed || parsed.hooks === undefined) return { raw, droppedHooks: null };
+    const { hooks, ...rest } = parsed;
+    return { raw: serializeSettings(rest), droppedHooks: hooks };
+  }
+  /** The live settings without DoFlow's own entries of `hooks`; every other key is left alone. */
+  function withoutManagedHooks(current     , hooks     ) {
+    if (!hooks || !current || typeof current !== 'object' || current.hooks === undefined) return current;
+    const { hooks: liveHooks, ...rest } = current;
+    const stripped = stripManagedSettings({ hooks: liveHooks, _: true }, { hooks });
+    return stripped?.hooks ? { ...rest, hooks: stripped.hooks } : rest;
+  }
   function settingsLedgerResources(ledger     , assetId     ) {
     const byFile = new Map();
     for (const resource of ledger?.resources || []) {
@@ -242,7 +260,8 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
     for (const fileName of SETTINGS_FILES) {
       const sourceAbs = path.join(sourceDir, fileName);
       if (!fs.existsSync(sourceAbs)) continue;
-      let managedRaw = settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope);
+      const tiered = tieredSettings(fileName, settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope), context);
+      let managedRaw = tiered.raw;
       if (fileName === 'settings.json' && context.statusline && !removing) {
         // --statusline: point Claude Code's statusLine key at the projected script. It rides the
         // same managed settings write as everything else this asset owns — one serialization, one
@@ -267,7 +286,7 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
         const currentRaw = fs.readFileSync(target, 'utf8');
         let merged;
         try {
-          merged = mergeSettings(JSON.parse(currentRaw), JSON.parse(managedRaw));
+          merged = mergeSettings(withoutManagedHooks(JSON.parse(currentRaw), tiered.droppedHooks), JSON.parse(managedRaw));
         } catch {
           conflicts.push(`${fileName} is not valid JSON and cannot be merged`);
           continue;
@@ -358,7 +377,8 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
     for (const fileName of SETTINGS_FILES) {
       const sourceAbs = path.join(sourceDir, fileName);
       if (!fs.existsSync(sourceAbs)) continue;
-      const fingerprint = sha256(settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope));
+      const sourceText = tieredSettings(fileName, settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope), context).raw;
+      const fingerprint = sha256(sourceText);
       const target = settingsTarget(fileName, paths);
       // 'absent' (not 'missing') matches the same convention the instructions asset already uses
       // for "no file here" — 'missing' is reserved by the lifecycle layer's removal reconciliation
@@ -373,7 +393,7 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
       let managed;
       try {
         current = JSON.parse(fs.readFileSync(target, 'utf8'));
-        managed = JSON.parse(settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope));
+        managed = JSON.parse(sourceText);
       } catch {
         conflicts.push(`${fileName} is not valid JSON`);
         statuses.push({ assetId: asset.id, capability: 'settings', status: 'conflict', target });
@@ -480,6 +500,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 +569,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 +577,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/agents.js

@@ -9,18 +9,12 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { atomicWrite } = require('./config.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
 
 const AGENT_DIRECTORY = 'agents';
 const AGENT_KIND = 'custom-agent';
 const REQUIRED_FIELDS = ['name', 'description', 'developer_instructions'];
-const READ_ONLY_ROLES = new Set([
-  'backend-architect', 'deep-research-agent', 'devops-architect', 'frontend-architect',
-  'quality-engineer', 'requirements-analyst', 'root-cause-analyst', 'security-engineer',
-  'system-architect', 'technical-writer',
-]);
-const IMPLEMENTATION_ROLES = new Set([
-  'performance-engineer', 'pm-agent', 'python-expert', 'refactoring-expert',
-]);
+const SPEC_DIRECTORY = path.join(REPO_ROOT, 'core', 'shared', 'agent-specs');
 const ALLOWED_FIELDS = new Set([...REQUIRED_FIELDS, 'sandbox_mode']);
 
 function fingerprint(content        )         {
@@ -85,7 +79,21 @@ function parseAgentToml(source     , { fileName }                        = {})
   return values;
 }
 
-function validateAgentContract(source     , { fileName }                        = {})      {
+/** `access` of every shared agent spec by name (118 IC-002). A TOML whose name has no spec is the
+ * user's own agent and is not tied to any access. */
+function specAccess(specDir         = SPEC_DIRECTORY, fsImpl      = fs)                      {
+  const access = new Map                ();
+  if (!fsImpl.existsSync(specDir)) return access;
+  for (const entry of fsImpl.readdirSync(specDir)) {
+    if (!entry.endsWith('.md')) continue;
+    const frontmatter = fsImpl.readFileSync(path.join(specDir, entry), 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const value = frontmatter?.[1].match(/^access:\s*(\S+)\s*$/m)?.[1];
+    if (value) access.set(entry.slice(0, -'.md'.length), value);
+  }
+  return access;
+}
+
+function validateAgentContract(source     , { fileName, access = specAccess() }                                                      = {})      {
   const agent = parseAgentToml(source, { fileName });
   for (const field of REQUIRED_FIELDS) {
     if (typeof agent[field] !== 'string' || !agent[field].trim()) throw new Error(`Agent is missing required '${field}'`);
@@ -97,11 +105,12 @@ function validateAgentContract(source     , { fileName }
   if (agent.sandbox_mode !== undefined && !['read-only', 'workspace-write', 'danger-full-access'].includes(agent.sandbox_mode)) {
     throw new Error(`Agent '${agent.name}' has an unsupported sandbox_mode`);
   }
-  if (READ_ONLY_ROLES.has(agent.name) && agent.sandbox_mode !== 'read-only') {
-    throw new Error(`Analysis role '${agent.name}' must use sandbox_mode = "read-only"`);
+  const specAccessValue = access.get(agent.name);
+  if (specAccessValue === 'read-only' && agent.sandbox_mode !== 'read-only') {
+    throw new Error(`Agent '${agent.name}' has access: read-only and must use sandbox_mode = "read-only"`);
   }
-  if (IMPLEMENTATION_ROLES.has(agent.name) && agent.sandbox_mode !== undefined) {
-    throw new Error(`Implementation role '${agent.name}' must inherit its parent sandbox`);
+  if (specAccessValue === 'write' && agent.sandbox_mode !== undefined) {
+    throw new Error(`Agent '${agent.name}' has access: write and must inherit its parent sandbox`);
   }
   return Object.freeze({ ...agent, fileName: filenameFor(agent.name) });
 }
@@ -134,12 +143,13 @@ function discoverCodexAgents(sourceDir     , fsImpl      = fs)        {
   const directory = path.resolve(sourceDir);
   if (!fsImpl.existsSync(directory)) throw new Error(`Codex agent source directory does not exist: ${sourceDir}`);
   const agents        = [];
+  const access = specAccess();
   for (const entry of fsImpl.readdirSync(directory, { withFileTypes: true }).sort((a     , b     ) => a.name.localeCompare(b.name))) {
     if (!entry.name.endsWith('.toml')) continue;
     if (!entry.isFile()) throw new Error(`Codex agent source '${entry.name}' must be a regular file`);
     const name = expectedName(entry.name);
     const source = fsImpl.readFileSync(path.join(directory, entry.name), 'utf8');
-    agents.push({ ...validateAgentContract(source, { fileName: entry.name }), name, source, fingerprint: fingerprint(source) });
+    agents.push({ ...validateAgentContract(source, { fileName: entry.name, access }), name, source, fingerprint: fingerprint(source) });
   }
   if (!agents.length) throw new Error(`No Codex agent TOML contracts found in ${sourceDir}`);
   return agents;
@@ -202,7 +212,7 @@ function reconcileCodexAgents(options     )      {
 }
 
 module.exports = {
-  AGENT_DIRECTORY, AGENT_KIND, READ_ONLY_ROLES, IMPLEMENTATION_ROLES, fingerprint,
+  AGENT_DIRECTORY, AGENT_KIND, fingerprint, specAccess,
   parseAgentToml, validateAgentContract, agentDirectory, destinationFor, discoverCodexAgents,
   planCodexAgents, applyCodexAgents, reconcileCodexAgents,
 };

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,9 +12,10 @@ 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 { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices } = require('../copy-tree.js');
+const { planCodexHooks, deployCodexHooks, removeCodexHookScripts, scriptFingerprint } = require('./hooks.js');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, resolveTransform } = require('../copy-tree.js');
 const { mergeMarkedSection, removeMarkedSection, MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
+const { renderGuidancePointer } = require('../guidance-pointer.js');
 const { nativeMcpCatalog } = require('../../registry/index.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 
@@ -275,6 +276,26 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
   }
   function sha256Text(text     ) { return crypto.createHash('sha256').update(text).digest('hex'); }
 
+  function instructionBody(content     ) {
+    if (typeof content !== 'string') return null;
+    const start = content.indexOf(MARKER_START);
+    if (start === -1) return null;
+    const bodyStart = start + MARKER_START.length;
+    const end = content.indexOf(MARKER_END, bodyStart);
+    if (end === -1 || content.indexOf(MARKER_START, end + MARKER_END.length) !== -1) return null;
+    let from = bodyStart;
+    if (content[from] === '\n') from += 1;
+    let to = end;
+    if (to > from && content[to - 1] === '\n') to -= 1;
+    return content.slice(from, to);
+  }
+
+  function renderedInstructionContent(asset     , context     , repoRoot     ) {
+    const source = sourceDirFor(asset, repoRoot);
+    const content = fs.readFileSync(source, 'utf8');
+    return renderGuidancePointer(content, { scope: context.scope, scopeRoot: context.paths.root }).replace(/\s+$/, '');
+  }
+
   function planInstructionsAsset({ assets, context, removing, repoRoot, claimedElsewhere = () => false }     ) {
     const asset = instructionsAsset(assets);
     const changes        = [];
@@ -298,18 +319,19 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       return { changes, conflicts };
     }
     const source = sourceDirFor(asset, repoRoot);
-    if (!mergeMarkedSection(source, target, { dryRun: true }).changed) return { changes, conflicts };
-    const content = fs.readFileSync(source, 'utf8').replace(/\s+$/, '');
+    const content = renderedInstructionContent(asset, context, repoRoot);
+    const merged = mergeMarkedSection(source, target, { dryRun: true, content });
+    if (!merged.changed) return { changes, conflicts };
     changes.push({ assetId: asset.id, target, source, operation: fs.existsSync(target) ? 'update' : 'create',
       ownershipIdentity: 'doflow:codex:instructions:managed-section', kind: 'instructions-section', identity: 'AGENTS.md',
-      afterFingerprint: sha256Text(content), sourceVersion: 'registry-v1', projection: { renderer: 'codex-agents' } });
+      afterFingerprint: sha256Text(content), renderedContent: content, sourceVersion: 'registry-v1', projection: { renderer: 'codex-agents' } });
     return { changes, conflicts };
   }
 
   function applyInstructionsAsset(changes     ) {
     for (const change of changes) {
       if (change.projection?.renderer !== 'codex-agents' || change.operation === 'remove') continue;
-      mergeMarkedSection(change.source, change.target);
+      mergeMarkedSection(change.source, change.target, { content: change.renderedContent });
     }
   }
 
@@ -325,11 +347,14 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     if (!asset) return { statuses, resources };
     const target = instructionsPath(context);
     const existing = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
-    const managed = existing !== null && existing.includes(MARKER_START) && existing.includes(MARKER_END);
-    statuses.push({ assetId: asset.id, capability: asset.capability, status: managed ? 'managed' : 'absent', target });
+    const expected = renderedInstructionContent(asset, context, repoRoot);
+    const actual = instructionBody(existing);
+    const hasMarkers = existing !== null && existing.includes(MARKER_START) && existing.includes(MARKER_END);
+    const managed = actual !== null && actual === expected;
+    statuses.push({ assetId: asset.id, capability: asset.capability, status: managed ? 'managed' : (hasMarkers ? 'missing' : 'absent'), target });
     if (managed) {
       resources.push({ assetId: asset.id, target, ownershipIdentity: 'doflow:codex:instructions:managed-section',
-        kind: 'instructions-section', identity: 'AGENTS.md', fingerprint: sha256Text(existing), sourceVersion: 'registry-v1',
+        kind: 'instructions-section', identity: 'AGENTS.md', fingerprint: sha256Text(expected), sourceVersion: 'registry-v1',
         projection: { renderer: 'codex-agents' } });
     }
     return { statuses, resources };
@@ -344,7 +369,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       const destDir = copyTreeDestDir(codexConfigDir(context), asset);
       const sourceDir = sourceDirFor(asset, repoRoot);
       const previousResources = ledgerFileResources(neutralResources, HARNESS, asset.id);
-      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(neutralResources, HARNESS), operation: removing ? 'remove' : 'apply', layout: asset.layout, keepModified: !removing,
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(neutralResources, HARNESS), operation: removing ? 'remove' : 'apply', layout: asset.layout, transform: asset.transform, keepModified: !removing,
         // `force` is the CLI's --force reaching the one conflict class a plan can actually
         // downgrade: a ledger-owned destination whose bytes were edited underneath us. With force,
         // that is drift to heal rather than a refusal — exactly what `doflow reconcile` (always
@@ -362,6 +387,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
           ownershipIdentity: `doflow:codex:copy-tree:${asset.id}:${change.relPath}`,
           kind: 'copy-tree-file', identity: change.relPath,
           afterFingerprint: change.fingerprint, fingerprint: change.fingerprint, sourceVersion: sourceVersion ?? 'unknown',
+          transformName: asset.transform || null,
           ...(change.kept ? { retained: true, retainedFor: [] } : {}),
           projection: { renderer: 'copy-tree' },
         });
@@ -371,9 +397,18 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
   }
 
   function applyCopyTreeAssets(changes     ) {
-    const treeChanges = changes.filter((change     ) => change.projection?.renderer === 'copy-tree' && change.operation !== 'remove')
-      .map((change     ) => ({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint }));
-    return applyTree({ changes: treeChanges }).applied;
+    let applied = 0;
+    const grouped = new Map();
+    for (const change of changes) {
+      if (change.projection?.renderer !== 'copy-tree' || change.operation === 'remove') continue;
+      const key = change.transformName || null;
+      if (!grouped.has(key)) grouped.set(key, []);
+      grouped.get(key).push({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint });
+    }
+    for (const [transformName, treeChanges] of grouped) {
+      applied += applyTree({ changes: treeChanges, transform: resolveTransform(transformName) }).applied;
+    }
+    return applied;
   }
 
   function removeCopyTreeAssets(changes     ) {
@@ -389,7 +424,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     for (const asset of copyTreeAssets(assets)) {
       const destDir = copyTreeDestDir(codexConfigDir(context), asset);
       const sourceDir = sourceDirFor(asset, repoRoot);
-      const result = verifyTree({ sourceDir, destDir, layout: asset.layout, plannedWrites });
+      const result = verifyTree({ sourceDir, destDir, layout: asset.layout, transform: asset.transform, plannedWrites });
       conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({
@@ -445,9 +480,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 +499,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 +508,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 +534,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 +593,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 +649,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 +721,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 +768,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 +780,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,
 };

package/src/adapters/codex/native-projection.js

@@ -19,11 +19,15 @@ function normalizeNativeProjection(registry     , harness     , mcp       , cont
   if (!override || typeof override !== 'object' || Array.isArray(override)) throw new Error(`Projection override for '${harness.id}' must be an object`);
   const trusted = override.hooks?.trusted;
   if (trusted !== undefined && typeof trusted !== 'boolean') throw new Error(`Projection override '${harness.id}.hooks.trusted' must be boolean`);
+  // Hook tiers (maint-hooks): Codex outside `hooks.harnesses` gets no hooks.json, no hook scripts and no
+  // `features.hooks` entry; the lifecycle removes what an earlier install wrote through the remove path.
+  const hooksOff = harness.capabilities?.hooks?.tiered === true;
+  const configResources = (declaration.config?.resources || []).filter((resource     ) => !(hooksOff && resource.identity === 'features.hooks'));
   return Object.freeze({
-    configResources: Object.freeze((declaration.config?.resources || []).map((resource     ) => Object.freeze({ ...resource }))),
+    configResources: Object.freeze(configResources.map((resource     ) => Object.freeze({ ...resource }))),
     mcp: Object.freeze({ catalog: Object.freeze(mcp.map((server     ) => Object.freeze({ ...server }))), selected: Object.freeze(mcp.map((server     ) => server.id)) }),
     agents: Object.freeze({ sourceDir: resolveRegistrySource(registry, declaration.agents?.source, `${harness.id} agents`) }),
-    hooks: Object.freeze({
+    hooks: hooksOff ? Object.freeze({}) : Object.freeze({
       sourceFile: resolveRegistrySource(registry, declaration.hooks?.configSource, `${harness.id} hooks config`),
       sourceHooksDir: resolveRegistrySource(registry, declaration.hooks?.scriptsSource, `${harness.id} hooks scripts`),
       trusted: trusted ?? declaration.hooks?.trusted,