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

package/src/adapters/gemini/{hooks.ts → hooks.js}

@@ -14,8 +14,9 @@
 // if a third harness with the same shape is ever added.
 const fs = require('node:fs');
 const path = require('node:path');
-const { verifyHookCommands } = require('../hook-commands.ts');
-const { mergeHooks } = require('../../helper/settings-merge.ts');
+const crypto = require('node:crypto');
+const { verifyHookCommands } = require('../hook-commands.js');
+const { mergeHooks } = require('../../helper/settings-merge.js');
 
 const SUPPORTED_EVENTS = new Set([
   'SessionStart', 'SessionEnd', 'BeforeAgent', 'AfterAgent', 'BeforeModel', 'AfterModel',
@@ -27,7 +28,7 @@ const SUPPORTED_EVENTS = new Set([
 // Stop, SubagentStart/Stop, and ConfigChange have no correct Gemini equivalent and are
 // intentionally omitted rather than approximated onto BeforeAgent/AfterAgent (design.md §7/§8 —
 // no false parity).
-const CLAUDE_TO_GEMINI_EVENT: Record<string, string> = {
+const CLAUDE_TO_GEMINI_EVENT                         = {
   SessionStart: 'SessionStart',
   SessionEnd: 'SessionEnd',
   PreToolUse: 'BeforeTool',
@@ -35,10 +36,10 @@ const CLAUDE_TO_GEMINI_EVENT: Record<string, string> = {
   PreCompact: 'PreCompress',
 };
 
-function validationError(errors: string[], message: string): void { errors.push(message); }
+function validationError(errors          , message        )       { errors.push(message); }
 
-function validateHooksConfig(config: any): { ok: boolean, errors: string[], events: string[] } {
-  const errors: string[] = [];
+function validateHooksConfig(config     )                                                      {
+  const errors           = [];
   if (!config || typeof config !== 'object' || Array.isArray(config)) {
     return { ok: false, errors: ['Hook configuration must be an object'], events: [] };
   }
@@ -54,7 +55,7 @@ function validateHooksConfig(config: any): { ok: boolean, errors: string[], even
       validationError(errors, `Hook event '${event}' requires a non-empty array of matcher groups`);
       continue;
     }
-    groups.forEach((group: any, groupIndex: number) => {
+    groups.forEach((group     , groupIndex        ) => {
       if (!group || typeof group !== 'object' || Array.isArray(group)) {
         validationError(errors, `Hook event '${event}' group ${groupIndex} must be an object`);
         return;
@@ -66,7 +67,7 @@ function validateHooksConfig(config: any): { ok: boolean, errors: string[], even
         validationError(errors, `Hook event '${event}' group ${groupIndex} requires a non-empty hooks array`);
         return;
       }
-      group.hooks.forEach((handler: any, handlerIndex: number) => {
+      group.hooks.forEach((handler     , handlerIndex        ) => {
         const label = `Hook event '${event}' group ${groupIndex} handler ${handlerIndex}`;
         if (!handler || typeof handler !== 'object' || Array.isArray(handler)) {
           validationError(errors, `${label} must be an object`); return;
@@ -85,9 +86,9 @@ function validateHooksConfig(config: any): { ok: boolean, errors: string[], even
 }
 
 /** Maps Claude guardrail intent, never fabricating a Gemini equivalent for unavailable events. */
-function classifyClaudeGuardrails(claudeHooks: any = {}): { supported: any[], unsupported: any[] } {
-  const supported: any[] = [];
-  const unsupported: any[] = [];
+function classifyClaudeGuardrails(claudeHooks      = {})                                           {
+  const supported        = [];
+  const unsupported        = [];
   for (const [event, groups] of Object.entries(claudeHooks || {})) {
     const targetEvent = CLAUDE_TO_GEMINI_EVENT[event] || null;
     const item = { sourceEvent: event, targetEvent, groups: Array.isArray(groups) ? groups.length : 0 };
@@ -103,58 +104,98 @@ function classifyClaudeGuardrails(claudeHooks: any = {}): { supported: any[], un
  * exists but fails to parse is a hard error, not silently treated as empty (this path merges
  * into content DoFlow does not own — a malformed-file work-around here risks losing it).
  */
-function planGeminiHooks({ config, sourceFile, sourceHooksDir, settingsFile, destinationHooksDir: declaredHooksDir, trusted = false, fsImpl = fs }: any = {}): any {
+/** Every regular, non-JSON file in the shipped scripts directory: what deployGeminiHooks copies. */
+function shippedScripts(scriptsDir     , fsImpl      = fs)           {
+  if (!scriptsDir || !fsImpl.existsSync(scriptsDir)) return [];
+  return fsImpl.readdirSync(scriptsDir)
+    .filter((name        ) => !name.endsWith('.json') && fsImpl.statSync(path.join(scriptsDir, name)).isFile());
+}
+
+/** DoFlow's record of a deployed hook script: the sha256 of its bytes. */
+function scriptFingerprint(bytes     )         { return 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 shippedScripts(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 planGeminiHooks({ config, sourceFile, sourceHooksDir, settingsFile, destinationHooksDir: declaredHooksDir, trusted = false, scriptRows = [], force = false, fsImpl = fs }      = {})      {
   let desired = config;
   try {
     if (!desired && sourceFile) desired = JSON.parse(fsImpl.readFileSync(sourceFile, 'utf8'));
-  } catch (error: any) {
+  } catch (error     ) {
     return { ok: false, status: 'malformed', changes: [], errors: [`Could not parse ${sourceFile}: ${error.message}`] };
   }
   if (!settingsFile) return { ok: false, status: 'invalid-request', changes: [], errors: ['settingsFile is required'] };
   const schema = validateHooksConfig(desired);
   const commands = verifyHookCommands(desired || {}, { scriptsDir: sourceHooksDir, trusted, fsImpl });
-  const errors = [...schema.errors, ...commands.checks.filter((check: any) => !check.ok).map((check: any) => `${check.event}: ${check.reason}${check.script ? ` (${check.script})` : ''}`)];
+  const errors = [...schema.errors, ...commands.checks.filter((check     ) => !check.ok).map((check     ) => `${check.event}: ${check.reason}${check.script ? ` (${check.script})` : ''}`)];
 
-  let existing: any = {};
+  let existing      = {};
   if (fsImpl.existsSync(settingsFile)) {
     try { existing = JSON.parse(fsImpl.readFileSync(settingsFile, 'utf8')); }
-    catch (error: any) { return { ok: false, status: 'malformed', changes: [], errors: [`Refusing to touch malformed ${settingsFile}: ${error.message}`] }; }
+    catch (error     ) { return { ok: false, status: 'malformed', changes: [], errors: [`Refusing to touch malformed ${settingsFile}: ${error.message}`] }; }
   }
   if (errors.length) return { ok: false, status: 'invalid-request', settingsFile, existing, changes: [], errors, commands };
 
   const mergedHooks = existing.hooks ? mergeHooks(existing.hooks, desired.hooks) : desired.hooks;
   const merged = { ...existing, hooks: mergedHooks };
-  const changed = JSON.stringify(existing.hooks) !== JSON.stringify(mergedHooks);
+  const configChanged = JSON.stringify(existing.hooks) !== JSON.stringify(mergedHooks);
   // Preferred: the declared hooks directory (harnesses.json "paths".hooksDirectory); the derived
   // sibling-of-settings fallback stays for direct callers passing raw inputs, and resolves to the
   // same location.
   const destinationHooksDir = declaredHooksDir || path.join(path.dirname(settingsFile), 'hooks');
+  // The scripts are deployed with the hooks key but are not part of it: a script whose bytes differ
+  // from the source is redeployed even when the key is already right.
+  const scripts = planHookScripts({ commands, sourceHooksDir, destinationHooksDir, rows: scriptRows, force, fsImpl });
+  if (scripts.edited.length) {
+    return { ok: false, status: 'conflict', settingsFile, existing, changes: [], commands,
+      errors: scripts.edited.map((name        ) => `Gemini hook script '${name}' was modified outside DoFlow`) };
+  }
+  const scriptsOnly = !configChanged && scripts.stale.length > 0;
+  const changed = configChanged || scriptsOnly;
   // The scripts deployGeminiHooks copies beside settings.json, so a backup of this change holds them too.
-  const shipped = sourceHooksDir && fsImpl.existsSync(sourceHooksDir)
-    ? fsImpl.readdirSync(sourceHooksDir).filter((name: string) => !name.endsWith('.json') && fsImpl.statSync(path.join(sourceHooksDir, name)).isFile())
-    : [];
   const companionTargets = [...new Set([
-    ...commands.checks.map((check: any) => path.join(destinationHooksDir, check.script)),
-    ...shipped.map((name: string) => path.join(destinationHooksDir, name)),
+    ...commands.checks.map((check     ) => path.join(destinationHooksDir, check.script)),
+    ...shippedScripts(sourceHooksDir, fsImpl).map((name        ) => path.join(destinationHooksDir, name)),
   ])].sort();
-  return { ok: true, status: changed ? 'change' : 'unchanged', settingsFile, existing, merged,
+  return { ok: true, status: changed ? 'change' : 'unchanged', settingsFile, existing, merged, scriptsOnly, scriptNames: scripts.names,
     changes: changed ? [{ type: fsImpl.existsSync(settingsFile) ? 'update' : 'create', file: settingsFile, key: 'hooks' }] : [],
     errors: [], commands, trust: commands.trust, scriptsDir: sourceHooksDir, destinationHooksDir, companionTargets };
 }
 
-function deployGeminiHooks(plan: any, { dryRun = false, fsImpl = fs }: { dryRun?: boolean, fsImpl?: any } = {}): any {
+function deployGeminiHooks(plan     , { dryRun = false, fsImpl = fs }                                     = {})      {
   if (!plan.ok) return { ...plan, applied: false };
   if (dryRun || plan.status === 'unchanged') return { ...plan, applied: false };
-  fsImpl.mkdirSync(path.dirname(plan.settingsFile), { recursive: true });
-  const content = `${JSON.stringify(plan.merged, null, 2)}\n`;
-  const temporary = path.join(path.dirname(plan.settingsFile), `.${path.basename(plan.settingsFile)}.${process.pid}.${Date.now()}.tmp`);
-  try {
-    fsImpl.writeFileSync(temporary, content, { flag: 'wx' });
-    fsImpl.renameSync(temporary, plan.settingsFile);
-  } finally {
-    if (fsImpl.existsSync(temporary)) fsImpl.unlinkSync(temporary);
+  if (!plan.scriptsOnly) {
+    fsImpl.mkdirSync(path.dirname(plan.settingsFile), { recursive: true });
+    const content = `${JSON.stringify(plan.merged, null, 2)}\n`;
+    const temporary = path.join(path.dirname(plan.settingsFile), `.${path.basename(plan.settingsFile)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+      fsImpl.writeFileSync(temporary, content, { flag: 'wx' });
+      fsImpl.renameSync(temporary, plan.settingsFile);
+    } finally {
+      if (fsImpl.existsSync(temporary)) fsImpl.unlinkSync(temporary);
+    }
   }
-  const deployed = new Set<string>();
+  const deployed = new Set        ();
   for (const check of plan.commands.checks) {
     const target = path.join(plan.destinationHooksDir, check.script);
     fsImpl.mkdirSync(path.dirname(target), { recursive: true });
@@ -182,18 +223,18 @@ function deployGeminiHooks(plan: any, { dryRun = false, fsImpl = fs }: { dryRun?
  * cross-check): if the key isn't present, there's nothing to do; otherwise propose removing only
  * that key, leaving every other key in the shared file untouched (FR-002).
  */
-function planRemoveGeminiHooks({ settingsFile, fsImpl = fs }: { settingsFile?: string, fsImpl?: any } = {}): any {
+function planRemoveGeminiHooks({ settingsFile, fsImpl = fs }                                          = {})      {
   if (!settingsFile) return { ok: false, status: 'invalid-request', changes: [], errors: ['settingsFile is required'] };
   if (!fsImpl.existsSync(settingsFile)) return { ok: true, status: 'unchanged', settingsFile, changes: [] };
   let existing;
   try { existing = JSON.parse(fsImpl.readFileSync(settingsFile, 'utf8')); }
-  catch (error: any) { return { ok: false, status: 'malformed', changes: [], errors: [`Could not parse ${settingsFile}: ${error.message}`] }; }
+  catch (error     ) { return { ok: false, status: 'malformed', changes: [], errors: [`Could not parse ${settingsFile}: ${error.message}`] }; }
   if (existing.hooks === undefined) return { ok: true, status: 'unchanged', settingsFile, changes: [] };
   const { hooks: _dropped, ...merged } = existing;
   return { ok: true, status: 'change', settingsFile, merged, changes: [{ type: 'update', file: settingsFile, key: 'hooks', operation: 'remove' }] };
 }
 
-function deployRemoveGeminiHooks(plan: any, { dryRun = false, fsImpl = fs }: { dryRun?: boolean, fsImpl?: any } = {}): any {
+function deployRemoveGeminiHooks(plan     , { dryRun = false, fsImpl = fs }                                     = {})      {
   if (!plan.ok || plan.status !== 'change' || dryRun) return { ...plan, applied: false };
   fsImpl.mkdirSync(path.dirname(plan.settingsFile), { recursive: true });
   const content = `${JSON.stringify(plan.merged, null, 2)}\n`;
@@ -207,4 +248,4 @@ function deployRemoveGeminiHooks(plan: any, { dryRun = false, fsImpl = fs }: { d
   return { ...plan, applied: true };
 }
 
-module.exports = { SUPPORTED_EVENTS, validateHooksConfig, classifyClaudeGuardrails, verifyHookCommands, planGeminiHooks, deployGeminiHooks, planRemoveGeminiHooks, deployRemoveGeminiHooks };
+module.exports = { SUPPORTED_EVENTS, validateHooksConfig, classifyClaudeGuardrails, verifyHookCommands, planGeminiHooks, deployGeminiHooks, scriptFingerprint, shippedScripts, planRemoveGeminiHooks, deployRemoveGeminiHooks };

package/src/adapters/gemini/{index.ts → index.js}

@@ -7,9 +7,9 @@
 // settings/MCP/extensions as first-class native-surface results for the lifecycle UI.
 const fs = require('node:fs');
 const path = require('node:path');
-const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor, resolveTransform } = require('../copy-tree.ts');
-const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.ts');
-const { planGeminiHooks, deployGeminiHooks, planRemoveGeminiHooks, deployRemoveGeminiHooks } = require('./hooks.ts');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor, resolveTransform } = require('../copy-tree.js');
+const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
+const { planGeminiHooks, deployGeminiHooks, planRemoveGeminiHooks, deployRemoveGeminiHooks, scriptFingerprint } = require('./hooks.js');
 
 const MARKER_START = '<!-- doflow:start -->';
 const MARKER_END = '<!-- doflow:end -->';
@@ -22,12 +22,12 @@ const MARKER_END = '<!-- doflow:end -->';
 const DEFAULTS_FILE = path.resolve(__dirname, '../../../core/harnesses/gemini/settings/adapter-defaults.json');
 const HARNESS = 'gemini';
 
-function defaults({ fsImpl = fs }: any = {}) { return JSON.parse(fsImpl.readFileSync(DEFAULTS_FILE, 'utf8')); }
+function defaults({ fsImpl = fs }      = {}) { return JSON.parse(fsImpl.readFileSync(DEFAULTS_FILE, 'utf8')); }
 
 /** Pure string helper (no path facts): replace only the span between DoFlow's markers in an
  * existing GEMINI.md body. An existing file with no DoFlow section is refused rather than appended
  * to — GEMINI.md is shared with the user and other tools. */
-function managedInstruction(existing: any, rendered: any) {
+function managedInstruction(existing     , rendered     ) {
   if (existing === null) return { ok: true, operation: 'create', content: rendered };
   const start = existing.indexOf(MARKER_START);
   const end = existing.indexOf(MARKER_END);
@@ -38,7 +38,7 @@ function managedInstruction(existing: any, rendered: any) {
 }
 
 /** Server names in one settings read, or null when the file is absent or unreadable. */
-function settingsServerNames(read: any) {
+function settingsServerNames(read     ) {
   if (!read.exists || read.error || !read.value || typeof read.value !== 'object') return null;
   const servers = read.value.mcpServers;
   return Object.keys(servers && typeof servers === 'object' ? servers : {});
@@ -50,7 +50,7 @@ function settingsServerNames(read: any) {
  * neither can be read. Gemini also merges system settings and extension servers, which DoFlow does
  * not read, so the view is never complete (`mcpComplete: false`) and absence is never proof.
  */
-function configuredGeminiMcp({ scope, settings, homeDir, fsImpl }: any) {
+function configuredGeminiMcp({ scope, settings, homeDir, fsImpl }     ) {
   const own = settingsServerNames(settings);
   const user = scope === 'project' && homeDir ? settingsServerNames(readJson(path.join(homeDir, '.gemini', 'settings.json'), { fsImpl })) : null;
   const mcpConfigured = own || user ? [...new Set([...(own || []), ...(user || [])])].sort() : null;
@@ -66,13 +66,13 @@ function configuredGeminiMcp({ scope, settings, homeDir, fsImpl }: any) {
  * historical shape.
  */
 function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } = {}) {
-  function nativePaths({ scope, scopeRoot, homeDir, fsImpl = fs }: any) {
+  function nativePaths({ scope, scopeRoot, homeDir, fsImpl = fs }     ) {
     const resolved = resolveHarnessPaths(declaredPaths, { scope, scopeRoot, homeDir });
     // Non-path native fact carried alongside the resolved surfaces (see DEFAULTS_FILE residue note).
     return { ...resolved, extensionMode: defaults({ fsImpl }).extensionInstall };
   }
 
-  function discover({ scope, scopeRoot, context = {}, fsImpl = fs }: any) {
+  function discover({ scope, scopeRoot, context = {}, fsImpl = fs }     ) {
     const paths = nativePaths({ scope, scopeRoot, homeDir: context.homeDir, fsImpl });
     const instruction = fsImpl.existsSync(paths.instruction) ? fsImpl.readFileSync(paths.instruction, 'utf8') : null;
     // Gemini takes no servers from DoFlow's MCP catalog.
@@ -81,7 +81,7 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     return { paths, instruction, settings, mcpOwned: [], mcpConfigured, mcpComplete };
   }
 
-  function render({ content = '' }: any = {}) {
+  function render({ content = '' }      = {}) {
     const body = String(content).trimEnd();
     return `${MARKER_START}\n${body}\n${MARKER_END}\n`;
   }
@@ -99,7 +99,7 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
    * (instruction vs. the guidance tree), not on any single declared path — expressible only by
    * joining and diffing, which is computation, not declaration.
    */
-  function geminiDestDir(paths: any, asset: any) {
+  function geminiDestDir(paths     , asset     ) {
     if (asset.nativeDir && asset.nativeDir.startsWith('../')) {
       const dest = path.join(paths.root, asset.nativeDir.slice(3));
       const rel = path.relative(paths.root, dest);
@@ -111,8 +111,8 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     return copyTreeDestDir(paths.configDir, asset);
   }
 
-  function rewriteGuidanceImport(content: any, assets: any, paths: any) {
-    const guidance = assets.find((item: any) => item.id === 'guidance.context-layer');
+  function rewriteGuidanceImport(content     , assets     , paths     ) {
+    const guidance = assets.find((item     ) => item.id === 'guidance.context-layer');
     if (!guidance?.nativeDir || !paths?.instruction || !paths?.configDir) return content;
     const guidanceDir = geminiDestDir(paths, guidance);
     const rel = path.relative(path.dirname(paths.instruction), guidanceDir).split(path.sep).join('/');
@@ -123,22 +123,22 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     return content.replace(/@\S*?(DOFLOW_CORE\.md)/g, `@${prefix}/$1`);
   }
 
-  function instructionContent({ assets, context, paths, fsImpl = fs }: any) {
+  function instructionContent({ assets, context, paths, fsImpl = fs }     ) {
     if (context.instructionContent !== undefined) return String(context.instructionContent);
-    const asset = assets.find((item: any) => item.id === 'guidance.core');
+    const asset = assets.find((item     ) => item.id === 'guidance.core');
     if (!asset || !context.repoRoot) return null;
     const source = path.resolve(context.repoRoot, asset.source);
     if (!fsImpl.existsSync(source)) return null;
     return rewriteGuidanceImport(fsImpl.readFileSync(source, 'utf8'), assets, paths);
   }
 
-  function policyStatuses(policies: any[] = []) {
-    return policies.map((policy: any) => ({ id: policy.id, status: 'unavailable', fallback: 'guidance', reason: 'Gemini policy automation is not rendered by this adapter' }));
+  function policyStatuses(policies        = []) {
+    return policies.map((policy     ) => ({ id: policy.id, status: 'unavailable', fallback: 'guidance', reason: 'Gemini policy automation is not rendered by this adapter' }));
   }
 
   // ---- copy-tree assets (rules, skills, agents, modes, references) ----
 
-  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl = fs }: any) {
+  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl = fs }     ) {
     const paths = nativePaths({ scope, scopeRoot, homeDir: context.homeDir, fsImpl });
     const changes = [];
     const conflicts = [];
@@ -156,10 +156,10 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
         // Found by the guard written for the six adapters that forwarded nothing.
         force: !removing && context?.force === true });
       treeResults.push(result);
-      conflicts.push(...result.conflicts.map((reason: any) => `${asset.id}: ${reason}`));
+      conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       // A hand-edited file at a path DoFlow no longer writes (the agents folder layout) is the
       // user's: it stays, only its ownership row is released.
-      notices.push(...result.kept.map((item: any) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
+      notices.push(...result.kept.map((item     ) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
       for (const change of result.changes) {
         changes.push({
           assetId: asset.id, target: change.target, source: change.source, operation: change.operation,
@@ -175,7 +175,7 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     return { changes, conflicts, notices: [...siblingReplacedNotices(treeResults), ...notices] };
   }
 
-  function applyCopyTreeAssets(changes: any, { fsImpl = fs }: any = {}) {
+  function applyCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
     let applied = 0;
     const grouped = new Map();
     for (const change of changes) {
@@ -190,13 +190,13 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     return applied;
   }
 
-  function removeCopyTreeAssets(changes: any, { fsImpl = fs }: any = {}) {
-    const treeChanges = changes.filter((change: any) => change.projection?.renderer === 'copy-tree' && change.operation === 'remove' && !change.retained)
-      .map((change: any) => ({ relPath: change.identity, target: change.target, operation: 'remove', fingerprint: change.fingerprint, pruneGuard: change.pruneGuard }));
+  function removeCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
+    const treeChanges = changes.filter((change     ) => change.projection?.renderer === 'copy-tree' && change.operation === 'remove' && !change.retained)
+      .map((change     ) => ({ relPath: change.identity, target: change.target, operation: 'remove', fingerprint: change.fingerprint, pruneGuard: change.pruneGuard }));
     return removeTree({ changes: treeChanges, fsImpl }).removed;
   }
 
-  function verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl = fs }: any) {
+  function verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl = fs }     ) {
     const paths = nativePaths({ scope, scopeRoot, homeDir: context.homeDir, fsImpl });
     const statuses = [];
     const resources = [];
@@ -205,7 +205,7 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       const destDir = geminiDestDir(paths, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Gemini');
       const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: asset.transform, plannedWrites: context?.plannedWrites });
-      conflicts.push(...result.conflicts.map((reason: any) => `${asset.id}: ${reason}`));
+      conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({
           assetId: asset.id, target: resource.target, ownershipIdentity: `doflow:gemini:copy-tree:${asset.id}:${resource.relPath}`,
@@ -225,21 +225,36 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
   // integration) — the lifecycle layer's normalizeChange() requires every change's assetId to
   // match a real registered asset, so this piggybacks on guidance.core's id the same way Codex's
   // assetIdFor(options, 'hooks') does, rather than inventing an unregistered 'hooks' id.
-  function hooksAssetId(assets: any) {
-    return assets.find((asset: any) => asset.id === 'guidance.core')?.id ?? assets[0]?.id;
+  function hooksAssetId(assets     ) {
+    return assets.find((asset     ) => asset.id === 'guidance.core')?.id ?? assets[0]?.id;
+  }
+
+  /** This scope's ledger rows for the hook scripts deployed beside settings.json. */
+  function scriptRows(ledger     , scope     ) {
+    return (ledger?.resources || []).filter((row     ) => row?.harness === 'gemini' && row.kind === 'hooks-script' && (!row.scope || row.scope === scope));
   }
 
   /** Plan the hooks pseudo-component's single change (or none), mirroring the {changes, conflicts}
    * shape planCopyTreeAssets already returns so plan() can fold it in the same way. The hook
    * scripts directory beside settings.json is declared (paths.hooksDirectory); the merge/remove
-   * planning itself lives in ./hooks.ts. */
-  function planHooksChange({ removing, found, context, assets, fsImpl }: any) {
+   * planning itself lives in ./hooks.ts. A removal also releases the rows of the hook scripts. */
+  function planHooksChange({ removing, found, context, assets, ledger, scope, fsImpl }     ) {
+    const component = planHooksComponentChange({ removing, found, context, assets, ledger, scope, fsImpl });
+    if (!removing) return component;
+    const releases = scriptRows(ledger, scope).map((row     ) => ({ assetId: row.assetId, target: row.target, operation: 'remove',
+      ownershipIdentity: row.ownershipIdentity, kind: row.kind, identity: row.identity, projection: row.projection,
+      retained: true, retainedFor: [] }));
+    return { ...component, changes: [...component.changes, ...releases] };
+  }
+
+  function planHooksComponentChange({ removing, found, context, assets, ledger, scope, fsImpl }     ) {
     if (found.settings.error) return { changes: [], conflicts: [] };
     const hooksPlan = removing
       ? planRemoveGeminiHooks({ settingsFile: found.paths.settings, fsImpl })
       : (context.geminiHooksSourceFile
         ? planGeminiHooks({ sourceFile: context.geminiHooksSourceFile, sourceHooksDir: context.geminiHooksSourceDir,
-          settingsFile: found.paths.settings, destinationHooksDir: found.paths.hooksDirectory, trusted: context.hooksTrusted, fsImpl })
+          settingsFile: found.paths.settings, destinationHooksDir: found.paths.hooksDirectory, trusted: context.hooksTrusted,
+          scriptRows: scriptRows(ledger, scope), force: context.force === true, fsImpl })
         : null);
     if (hooksPlan && !hooksPlan.ok) return { changes: [], conflicts: hooksPlan.errors || [] };
     if (hooksPlan?.status !== 'change') return { changes: [], conflicts: [] };
@@ -248,7 +263,7 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       companionTargets: removing ? [] : (hooksPlan.companionTargets ?? []) }], conflicts: [] };
   }
 
-  function plan({ scope, scopeRoot, assets = [], mcp = [], discovery, context = {}, ledger, fsImpl = fs }: any) {
+  function plan({ scope, scopeRoot, assets = [], mcp = [], discovery, context = {}, ledger, fsImpl = fs }     ) {
     const found = discovery || discover({ scope, scopeRoot, context, fsImpl });
     const changes = []; const conflicts = [];
     const removing = context.operation === 'remove';
@@ -256,7 +271,7 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       // Removal only ever targets a section this adapter itself owns — a foreign or absent
       // GEMINI.md yields no change, never a forced deletion of user content.
       const owns = found.instruction !== null && found.instruction.includes(MARKER_START) && found.instruction.includes(MARKER_END);
-      if (assets.some((asset: any) => asset.id === 'guidance.core') && owns) {
+      if (assets.some((asset     ) => asset.id === 'guidance.core') && owns) {
         changes.push({ assetId: 'guidance.core', target: found.paths.instruction, operation: 'remove', ownershipIdentity: 'gemini:instructions', projection: { renderer: 'gemini-instructions' } });
       }
     } else {
@@ -270,21 +285,21 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     const copyTree = planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl });
     changes.push(...copyTree.changes); conflicts.push(...copyTree.conflicts);
     if (found.settings.error) conflicts.push(found.settings.error);
-    const hooks = planHooksChange({ removing, found, context, assets, fsImpl });
+    const hooks = planHooksChange({ removing, found, context, assets, ledger, scope, fsImpl });
     changes.push(...hooks.changes); conflicts.push(...hooks.conflicts);
     return {
       changes, conflicts, prerequisites: [], notices: copyTree.notices,
       surfaces: {
         instructions: { status: 'supported', target: found.paths.instruction },
         settings: { status: found.settings.error ? 'invalid' : 'supported', target: found.paths.settings },
-        mcp: { status: found.settings.error ? 'blocked' : 'supported', target: found.paths.settings, selected: mcp.map((item: any) => item.id) },
+        mcp: { status: found.settings.error ? 'blocked' : 'supported', target: found.paths.settings, selected: mcp.map((item     ) => item.id) },
         extensions: { status: 'different', mode: found.paths.extensionMode, action: 'use Gemini CLI extension management' },
         policies: policyStatuses(context.policies),
       },
     };
   }
 
-  function atomicWrite(file: any, content: any, { fsImpl = fs }: any = {}) {
+  function atomicWrite(file     , content     , { fsImpl = fs }      = {}) {
     fsImpl.mkdirSync(path.dirname(file), { recursive: true });
     const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
     try {
@@ -294,9 +309,9 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       if (fsImpl.existsSync(temp)) fsImpl.rmSync(temp, { force: true });
     }
   }
-  function apply({ changes = [], fsImpl = fs }: any) {
+  function apply({ changes = [], fsImpl = fs }     ) {
     for (const change of changes) if (change.content !== undefined) atomicWrite(change.target, change.content, { fsImpl });
-    const hooksChange = changes.find((change: any) => change.nativeComponent === 'hooks');
+    const hooksChange = changes.find((change     ) => change.nativeComponent === 'hooks');
     if (hooksChange?.nativePlan) deployGeminiHooks(hooksChange.nativePlan, { fsImpl });
     applyCopyTreeAssets(changes, { fsImpl });
     // An update that relocates an asset (the agents folder layout -> flat files) carries the old
@@ -307,7 +322,7 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
   /** Strip only the DoFlow-managed span, exactly like the Claude adapter's removeManagedSection —
    * a file with user content before/after the managed section must keep that content. Only delete
    * the file outright once nothing but the managed section (and its separator) remains. */
-  function removeManagedSection(file: any, { fsImpl = fs }: any = {}) {
+  function removeManagedSection(file     , { fsImpl = fs }      = {}) {
     if (!fsImpl.existsSync(file)) return false;
     const existing = fsImpl.readFileSync(file, 'utf8');
     const start = existing.indexOf(MARKER_START);
@@ -324,38 +339,62 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     else fsImpl.writeFileSync(file, next);
     return true;
   }
-  function remove({ changes = [], fsImpl = fs }: any) {
+  function remove({ changes = [], fsImpl = fs }     ) {
     for (const change of changes) if (change.target && change.projection?.renderer === 'gemini-instructions') removeManagedSection(change.target, { fsImpl });
-    const hooksChange = changes.find((change: any) => change.nativeComponent === 'hooks');
+    const hooksChange = changes.find((change     ) => change.nativeComponent === 'hooks');
     if (hooksChange?.nativePlan) deployRemoveGeminiHooks(hooksChange.nativePlan, { fsImpl });
     removeCopyTreeAssets(changes, { fsImpl });
   }
 
-  function verify({ scope, scopeRoot, assets = [], context = {}, fsImpl = fs }: any) {
+  /** Whether the hooks pseudo-component is on disk as the source declares it, with the resource that
+   * records it when so. Null status when the run carries no hooks source or settings.json is unreadable. */
+  function verifyHooksComponent({ found, assets, context, fsImpl }     ) {
+    if (!context.geminiHooksSourceFile || found.settings.error) return { hooksStatus: null, resources: [], conflicts: [] };
+    const hooksPlan = planGeminiHooks({ sourceFile: context.geminiHooksSourceFile, sourceHooksDir: context.geminiHooksSourceDir,
+      settingsFile: found.paths.settings, destinationHooksDir: found.paths.hooksDirectory, trusted: context.hooksTrusted, fsImpl });
+    const hooksStatus = hooksPlan.ok && hooksPlan.status === 'unchanged' ? 'managed' : (hooksPlan.ok ? 'missing' : 'conflict');
+    const resources = hooksStatus === 'managed' ? [{ assetId: hooksAssetId(assets), target: hooksPlan.settingsFile, ownershipIdentity: 'gemini:hooks',
+      fingerprint: fingerprint(hooksPlan.merged.hooks), sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'gemini-hooks' } },
+    ...hooksPlan.scriptNames.map((identity        ) => {
+      const target = path.join(hooksPlan.destinationHooksDir, identity);
+      return { assetId: hooksAssetId(assets), target, ownershipIdentity: `gemini:hooks-script:${identity}`, kind: 'hooks-script', identity,
+        fingerprint: scriptFingerprint(fs.readFileSync(target)), sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'gemini-hooks' } };
+    })] : [];
+    return { hooksStatus, resources, conflicts: hooksPlan.ok ? [] : (hooksPlan.errors || []) };
+  }
+
+  /** The hook front doors (IC-037): the hooks pseudo-component alone. */
+  function planHookDoors({ scope, scopeRoot, assets = [], discovery, context = {}, ledger, fsImpl = fs }     ) {
+    const found = discovery || discover({ scope, scopeRoot, context, fsImpl });
+    const hooks = planHooksChange({ removing: false, found, context, assets, ledger, scope, fsImpl });
+    return { changes: hooks.changes, conflicts: [...(found.settings.error ? [found.settings.error] : []), ...hooks.conflicts], prerequisites: [], notices: [] };
+  }
+
+  function verifyHookDoors({ scope, scopeRoot, assets = [], context = {}, fsImpl = fs }     ) {
+    const found = discover({ scope, scopeRoot, context, fsImpl });
+    const hooks = verifyHooksComponent({ found, assets, context, fsImpl });
+    const conflicts = [...(found.settings.error ? [found.settings.error] : []), ...hooks.conflicts];
+    return { ok: conflicts.length === 0 && hooks.hooksStatus !== 'conflict', resources: hooks.resources, statuses: { hooks: hooks.hooksStatus }, conflicts };
+  }
+
+  function verify({ scope, scopeRoot, assets = [], context = {}, fsImpl = fs }     ) {
     const found = discover({ scope, scopeRoot, context, fsImpl });
     const resources = [];
-    if (assets.some((asset: any) => asset.id === 'guidance.core') && found.instruction?.includes(MARKER_START) && found.instruction.includes(MARKER_END)) {
+    if (assets.some((asset     ) => asset.id === 'guidance.core') && found.instruction?.includes(MARKER_START) && found.instruction.includes(MARKER_END)) {
       resources.push({ assetId: 'guidance.core', target: found.paths.instruction, ownershipIdentity: 'gemini:instructions', fingerprint: fingerprint(found.instruction), sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'gemini-instructions' } });
     }
     const copyTree = verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl });
     resources.push(...copyTree.resources);
-    let hooksStatus = null; const conflicts = [...(found.settings.error ? [found.settings.error] : []), ...copyTree.conflicts];
-    if (context.geminiHooksSourceFile && !found.settings.error) {
-      const hooksPlan = planGeminiHooks({ sourceFile: context.geminiHooksSourceFile, sourceHooksDir: context.geminiHooksSourceDir,
-        settingsFile: found.paths.settings, destinationHooksDir: found.paths.hooksDirectory, trusted: context.hooksTrusted, fsImpl });
-      hooksStatus = hooksPlan.ok && hooksPlan.status === 'unchanged' ? 'managed' : (hooksPlan.ok ? 'missing' : 'conflict');
-      if (!hooksPlan.ok) conflicts.push(...(hooksPlan.errors || []));
-      if (hooksStatus === 'managed') {
-        resources.push({ assetId: hooksAssetId(assets), target: hooksPlan.settingsFile, ownershipIdentity: 'gemini:hooks',
-          fingerprint: fingerprint(hooksPlan.merged.hooks), sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'gemini-hooks' } });
-      }
-    }
+    const hooks = verifyHooksComponent({ found, assets, context, fsImpl });
+    resources.push(...hooks.resources);
+    const hooksStatus = hooks.hooksStatus;
+    const conflicts = [...(found.settings.error ? [found.settings.error] : []), ...copyTree.conflicts, ...hooks.conflicts];
     return { ok: !found.settings.error && copyTree.conflicts.length === 0 && hooksStatus !== 'conflict', resources,
       statuses: { settings: found.settings.error ? 'invalid' : 'supported', extensions: 'different', policies: policyStatuses(context.policies), copyTree: copyTree.statuses, hooks: hooksStatus },
       conflicts };
   }
 
-  return { nativePaths, discover, render, plan, apply, remove, verify };
+  return { nativePaths, discover, render, plan, apply, remove, verify, planHookDoors, verifyHookDoors };
 }
 
 const singleton = createGeminiAdapter();
@@ -370,7 +409,7 @@ const singleton = createGeminiAdapter();
  * @param {Object} target a lifecycle status target ({adapterInput, discovery})
  * @returns {*} the plan's trust, or null
  */
-function hookTrustFor(target: any) {
+function hookTrustFor(target     ) {
   const context = target.adapterInput?.context || {};
   const settingsFile = target.discovery?.paths?.settings;
   if (!context.geminiHooksSourceFile || !settingsFile || target.discovery?.settings?.error) return null;
@@ -385,6 +424,6 @@ module.exports = {
   MARKER_START, MARKER_END,
   nativePaths: singleton.nativePaths, discover: singleton.discover, render: singleton.render,
   managedInstruction, plan: singleton.plan, apply: singleton.apply, remove: singleton.remove,
-  verify: singleton.verify, planGeminiHooks, hookTrustFor,
+  verify: singleton.verify, planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors, planGeminiHooks, hookTrustFor,
   createGeminiAdapter,
 };

package/src/adapters/{hook-commands.ts → hook-commands.js}

@@ -11,16 +11,16 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-function commandScriptNames(command: string): string[] {
+function commandScriptNames(command        )           {
   // DoFlow's wrappers are shell scripts selected from a project or CODEX_HOME hooks directory.
   // Extracting the basename works for both literal and command-substitution based paths.
   return [...new Set((command.match(/[A-Za-z0-9][A-Za-z0-9_-]*\.sh\b/g) || []))];
 }
 
-function hookHandlers(config: any): { event: string, handler: any }[] {
-  return Object.entries(config.hooks || {}).flatMap(([event, groups]: [string, any]) =>
-    (Array.isArray(groups) ? groups : []).flatMap((group: any) =>
-      (Array.isArray(group?.hooks) ? group.hooks : []).map((handler: any) => ({ event, handler }))));
+function hookHandlers(config     )                                    {
+  return Object.entries(config.hooks || {}).flatMap(([event, groups]               ) =>
+    (Array.isArray(groups) ? groups : []).flatMap((group     ) =>
+      (Array.isArray(group?.hooks) ? group.hooks : []).map((handler     ) => ({ event, handler }))));
 }
 
 // On `trusted`: both harnesses gate hook execution behind their own trust prompt — Codex through
@@ -36,8 +36,8 @@ function hookHandlers(config: any): { event: string, handler: any }[] {
 // exec-bit half of the check is POSIX-only; existence is checked everywhere.
 const EXEC_BITS_EXIST = process.platform !== 'win32';
 
-function verifyHookCommands(config: any, { scriptsDir, trusted = false, fsImpl = fs }: { scriptsDir?: string, trusted?: boolean, fsImpl?: any } = {}): any {
-  const checks: any[] = [];
+function verifyHookCommands(config     , { scriptsDir, trusted = false, fsImpl = fs }                                                           = {})      {
+  const checks        = [];
   for (const { event, handler } of hookHandlers(config)) {
     if (!handler || handler.type !== 'command' || typeof handler.command !== 'string' || !handler.command.trim()) continue;
     const names = commandScriptNames(handler.command);
@@ -54,7 +54,7 @@ function verifyHookCommands(config: any, { scriptsDir, trusted = false, fsImpl =
         requiresTrust: true, trusted });
     }
   }
-  return { ok: checks.every((check: any) => check.ok), checks, trust: { required: checks.length > 0, trusted: Boolean(trusted), status: trusted ? 'trusted' : 'review-required' } };
+  return { ok: checks.every((check     ) => check.ok), checks, trust: { required: checks.length > 0, trusted: Boolean(trusted), status: trusted ? 'trusted' : 'review-required' } };
 }
 
 module.exports = { commandScriptNames, hookHandlers, verifyHookCommands };