@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/adapters/gemini/hooks.js

@@ -0,0 +1,210 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Gemini hook planning. Unlike Codex (which owns a standalone hooks.json file), Gemini's hooks
+// live as a "hooks" key inside settings.json — a file DoFlow does not fully own (it commonly
+// pre-exists with unrelated content: mcpServers, ui, telemetry, model, etc.). planGeminiHooks
+// therefore returns a key-scoped merge plan, never a full-file replace.
+//
+// NOTE: validateHooksConfig below intentionally duplicates codex-hooks.js's shape-checking logic
+// (event -> array of {matcher, hooks:[{type,command,...}]} groups) rather than sharing it, since
+// unifying it would mean introducing a new shared module beyond this feature's planned scope
+// (agent-docs/doflow/013-codex-gemini-hooks-parity/plan.md's component list). Worth factoring out
+// 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.js');
+const { mergeHooks } = require('../../helper/settings-merge.js');
+
+const SUPPORTED_EVENTS = new Set([
+  'SessionStart', 'SessionEnd', 'BeforeAgent', 'AfterAgent', 'BeforeModel', 'AfterModel',
+  'BeforeToolSelection', 'BeforeTool', 'AfterTool', 'PreCompress', 'Notification',
+]);
+
+// Claude guardrail event -> Gemini event, only where a real Gemini event has matching semantics
+// (source: geminicli.com/docs/hooks/reference.md). UserPromptSubmit,
+// 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                         = {
+  SessionStart: 'SessionStart',
+  SessionEnd: 'SessionEnd',
+  PreToolUse: 'BeforeTool',
+  PostToolUse: 'AfterTool',
+  PreCompact: 'PreCompress',
+};
+
+function validationError(errors          , message        )       { errors.push(message); }
+
+function validateHooksConfig(config     )                                                      {
+  const errors           = [];
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return { ok: false, errors: ['Hook configuration must be an object'], events: [] };
+  }
+  if (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks)) {
+    return { ok: false, errors: ['Hook configuration requires a hooks object'], events: [] };
+  }
+  for (const [event, groups] of Object.entries(config.hooks)) {
+    if (!SUPPORTED_EVENTS.has(event)) {
+      validationError(errors, `Unsupported Gemini hook event '${event}'`);
+      continue;
+    }
+    if (!Array.isArray(groups) || groups.length === 0) {
+      validationError(errors, `Hook event '${event}' requires a non-empty array of matcher groups`);
+      continue;
+    }
+    groups.forEach((group     , groupIndex        ) => {
+      if (!group || typeof group !== 'object' || Array.isArray(group)) {
+        validationError(errors, `Hook event '${event}' group ${groupIndex} must be an object`);
+        return;
+      }
+      if (group.matcher !== undefined && typeof group.matcher !== 'string') {
+        validationError(errors, `Hook event '${event}' group ${groupIndex} matcher must be a string`);
+      }
+      if (!Array.isArray(group.hooks) || group.hooks.length === 0) {
+        validationError(errors, `Hook event '${event}' group ${groupIndex} requires a non-empty hooks array`);
+        return;
+      }
+      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;
+        }
+        if (handler.type !== 'command') validationError(errors, `${label} must have type 'command'`);
+        if (typeof handler.command !== 'string' || !handler.command.trim()) {
+          validationError(errors, `${label} requires a non-empty command string`);
+        }
+        if (handler.timeout !== undefined && typeof handler.timeout !== 'number') {
+          validationError(errors, `${label} timeout must be a number`);
+        }
+      });
+    });
+  }
+  return { ok: errors.length === 0, errors, events: Object.keys(config.hooks) };
+}
+
+/** Maps Claude guardrail intent, never fabricating a Gemini equivalent for unavailable events. */
+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 };
+    if (targetEvent) supported.push(item);
+    else unsupported.push({ ...item, reason: `Gemini has no equivalent lifecycle event for Claude's '${event}'` });
+  }
+  return { supported, unsupported };
+}
+
+/**
+ * Plan a key-scoped merge of a "hooks" config into an existing (or absent) settings.json, never
+ * touching any other key. Mirrors src/mcp.js's readJsonOrThrow discipline: a settings.json that
+ * 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 }      = {})      {
+  let desired = config;
+  try {
+    if (!desired && sourceFile) desired = JSON.parse(fsImpl.readFileSync(sourceFile, 'utf8'));
+  } 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     ) => !check.ok).map((check     ) => `${check.event}: ${check.reason}${check.script ? ` (${check.script})` : ''}`)];
+
+  let existing      = {};
+  if (fsImpl.existsSync(settingsFile)) {
+    try { existing = JSON.parse(fsImpl.readFileSync(settingsFile, 'utf8')); }
+    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);
+  // 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 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        ) => !name.endsWith('.json') && fsImpl.statSync(path.join(sourceHooksDir, name)).isFile())
+    : [];
+  const companionTargets = [...new Set([
+    ...commands.checks.map((check     ) => path.join(destinationHooksDir, check.script)),
+    ...shipped.map((name        ) => path.join(destinationHooksDir, name)),
+  ])].sort();
+  return { ok: true, status: changed ? 'change' : 'unchanged', settingsFile, existing, merged,
+    changes: changed ? [{ type: fsImpl.existsSync(settingsFile) ? 'update' : 'create', file: settingsFile, key: 'hooks' }] : [],
+    errors: [], commands, trust: commands.trust, scriptsDir: sourceHooksDir, destinationHooksDir, companionTargets };
+}
+
+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);
+  }
+  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 });
+    fsImpl.copyFileSync(check.file, target);
+    fsImpl.chmodSync(target, fsImpl.statSync(check.file).mode & 0o777);
+    deployed.add(check.script);
+  }
+  if (plan.scriptsDir && fsImpl.existsSync(plan.scriptsDir)) {
+    for (const name of fsImpl.readdirSync(plan.scriptsDir)) {
+      if (deployed.has(name) || name.endsWith('.json')) continue;
+      const source = path.join(plan.scriptsDir, name);
+      if (!fsImpl.statSync(source).isFile()) continue;
+      const target = path.join(plan.destinationHooksDir, name);
+      fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+      fsImpl.copyFileSync(source, target);
+      fsImpl.chmodSync(target, fsImpl.statSync(source).mode & 0o777);
+    }
+  }
+  return { ...plan, applied: true };
+}
+
+/**
+ * Plan stripping just the "hooks" key back out of settings.json — mirrors this codebase's
+ * existing GEMINI.md-instructions removal (structural presence check, not a ledger fingerprint
+ * 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 }                                          = {})      {
+  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     ) { 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     , { 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`;
+  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);
+  }
+  return { ...plan, applied: true };
+}
+
+module.exports = { SUPPORTED_EVENTS, validateHooksConfig, classifyClaudeGuardrails, verifyHookCommands, planGeminiHooks, deployGeminiHooks, planRemoveGeminiHooks, deployRemoveGeminiHooks };

package/src/adapters/gemini/index.js

@@ -0,0 +1,390 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Gemini CLI adapter.  Native settings are JSON and Gemini's extension installation is a host
+// workflow, so this adapter deliberately plans only safe instruction projection while exposing
+// 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.js');
+const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
+const { planGeminiHooks, deployGeminiHooks, planRemoveGeminiHooks, deployRemoveGeminiHooks } = require('./hooks.js');
+
+const MARKER_START = '<!-- doflow:start -->';
+const MARKER_END = '<!-- doflow:end -->';
+/**
+ * Residue (not a path fact): the one non-path native fact this harness still reads from its own
+ * fixture file — how extensions are installed ("native-host-workflow"), reported verbatim in plan
+ * surfaces. The file-name facts that used to live beside it (instructionFile, settingsFile) are now
+ * declared in core/registry/harnesses.json "paths" and resolve below like every other harness.
+ */
+const DEFAULTS_FILE = path.resolve(__dirname, '../../../core/harnesses/gemini/settings/adapter-defaults.json');
+const HARNESS = 'gemini';
+
+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     , rendered     ) {
+  if (existing === null) return { ok: true, operation: 'create', content: rendered };
+  const start = existing.indexOf(MARKER_START);
+  const end = existing.indexOf(MARKER_END);
+  if (start === -1 && end === -1) return { ok: false, conflict: 'GEMINI.md exists without a DoFlow managed section' };
+  if (start === -1 || end === -1 || end < start) return { ok: false, conflict: 'GEMINI.md has malformed DoFlow managed-section markers' };
+  const content = `${existing.slice(0, start)}${rendered}${existing.slice(end + MARKER_END.length).replace(/^\n?/, '')}`;
+  return { ok: true, operation: content === existing ? 'none' : 'merge', content };
+}
+
+/** Server names in one settings read, or null when the file is absent or unreadable. */
+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 : {});
+}
+
+/**
+ * The server names DoFlow can see for Gemini at a scope (`mcpConfigured`): the scope's settings, and
+ * at project scope the user's `~/.gemini/settings.json` too, since Gemini merges both. `null` while
+ * 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 }     ) {
+  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;
+  return { mcpConfigured, mcpComplete: false };
+}
+
+/**
+ * Native path facts live in core/registry/harnesses.json under this harness's "paths" section and
+ * resolve through the shared harness-paths resolver: project-scope config follows the Antigravity
+ * customization convention (.agents/) while user-scope config lives under ~/.gemini/config/.
+ * createGeminiAdapter({ declaredPaths }) is the injection point buildAdapterRegistry() uses;
+ * module-level exports delegate to a default-configured instance so direct callers keep their
+ * historical shape.
+ */
+function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } = {}) {
+  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 }     ) {
+    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.
+    const settings = readJson(paths.settings, { fsImpl });
+    const { mcpConfigured, mcpComplete } = configuredGeminiMcp({ scope, settings, homeDir: context.homeDir, fsImpl });
+    return { paths, instruction, settings, mcpOwned: [], mcpConfigured, mcpComplete };
+  }
+
+  function render({ content = '' }      = {}) {
+    const body = String(content).trimEnd();
+    return `${MARKER_START}\n${body}\n${MARKER_END}\n`;
+  }
+
+  /**
+   * Rewrite the pointer's guidance import so it resolves from wherever the instruction file
+   * actually lands. The shared pointer source carries one hardcoded `../`, which is correct only
+   * when the instruction file sits one level below the install root — true for Gemini's global
+   * scope (`.gemini/GEMINI.md`) and false for its project scope, where Gemini reads `GEMINI.md`
+   * from the workspace root itself. A static prefix cannot satisfy both, because the depth varies
+   * by scope rather than by harness, so it is computed here instead. Left unrewritten, the import
+   * pointed above the install root and the whole guidance chain silently failed to load.
+   *
+   * Logic residue: the relative prefix depends on the DISTANCE between two declared surfaces
+   * (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     , asset     ) {
+    if (asset.nativeDir && asset.nativeDir.startsWith('../')) {
+      const dest = path.join(paths.root, asset.nativeDir.slice(3));
+      const rel = path.relative(paths.root, dest);
+      if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        throw new Error(`gemini nativeDir escapes the scope root: ${asset.nativeDir}`);
+      }
+      return dest;
+    }
+    return copyTreeDestDir(paths.configDir, asset);
+  }
+
+  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('/');
+    if (!rel) return content;
+    // `./` is added explicitly for a same-directory descent: the bare form starts with the dot of
+    // `.doflow`, which reads as an extension rather than a path segment.
+    const prefix = rel.startsWith('../') ? rel : `./${rel}`;
+    return content.replace(/@\S*?(DOFLOW_CORE\.md)/g, `@${prefix}/$1`);
+  }
+
+  function instructionContent({ assets, context, paths, fsImpl = fs }     ) {
+    if (context.instructionContent !== undefined) return String(context.instructionContent);
+    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        = []) {
+    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 }     ) {
+    const paths = nativePaths({ scope, scopeRoot, homeDir: context.homeDir, fsImpl });
+    const changes = [];
+    const conflicts = [];
+    const treeResults = [];
+    const notices = [];
+    for (const asset of copyTreeAssets(assets)) {
+      const destDir = geminiDestDir(paths, asset);
+      const sourceDir = sourceDirFor(asset, context, fsImpl, 'Gemini');
+      const previousResources = ledgerFileResources(ledger?.resources, HARNESS, asset.id);
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, transform: asset.transform, keepModified: !removing,
+        // Was `force: context?.force`, ungated. Gemini was one of only two adapters forwarding force
+        // at all, so it looked like the reference implementation — but it handed force to the remove
+        // path too, where copy-tree deliberately stays strict: force heals drift on apply, and a
+        // hand-edited file is never deleted, forced or not (codex/index.ts states the rule in full).
+        // 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     ) => `${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     ) => `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,
+          ownershipIdentity: `doflow:gemini:copy-tree:${asset.id}:${change.relPath}`,
+          kind: 'copy-tree-file', identity: change.relPath,
+          afterFingerprint: change.fingerprint, fingerprint: change.fingerprint, sourceVersion: 'registry-v1',
+          transformName: asset.transform || null,
+          ...(change.kept ? { retained: true, retainedFor: [] } : {}),
+          projection: { renderer: 'copy-tree' },
+        });
+      }
+    }
+    return { changes, conflicts, notices: [...siblingReplacedNotices(treeResults), ...notices] };
+  }
+
+  function applyCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
+    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, fsImpl, transform: resolveTransform(transformName) }).applied;
+    }
+    return applied;
+  }
+
+  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 }     ) {
+    const paths = nativePaths({ scope, scopeRoot, homeDir: context.homeDir, fsImpl });
+    const statuses = [];
+    const resources = [];
+    const conflicts = [];
+    for (const asset of copyTreeAssets(assets)) {
+      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     ) => `${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}`,
+          kind: 'copy-tree-file', identity: resource.relPath,
+          fingerprint: resource.fingerprint, sourceVersion: 'registry-v1',
+          projection: { renderer: 'copy-tree' },
+        });
+      }
+      statuses.push({ assetId: asset.id, capability: asset.capability, status: result.ok ? 'managed' : 'conflict', target: destDir });
+    }
+    return { statuses, resources, conflicts };
+  }
+
+  // ---- shared adapter contract ----
+
+  // Hooks are a pseudo-component, not a registry-declared asset (like Codex's own hooks
+  // 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     ) {
+    return assets.find((asset     ) => asset.id === 'guidance.core')?.id ?? assets[0]?.id;
+  }
+
+  /** 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 }     ) {
+    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 })
+        : null);
+    if (hooksPlan && !hooksPlan.ok) return { changes: [], conflicts: hooksPlan.errors || [] };
+    if (hooksPlan?.status !== 'change') return { changes: [], conflicts: [] };
+    return { changes: [{ assetId: hooksAssetId(assets), target: hooksPlan.settingsFile, operation: removing ? 'remove' : (hooksPlan.changes[0]?.type ?? 'update'),
+      ownershipIdentity: 'gemini:hooks', nativeComponent: 'hooks', nativePlan: hooksPlan, projection: { renderer: 'gemini-hooks' },
+      companionTargets: removing ? [] : (hooksPlan.companionTargets ?? []) }], conflicts: [] };
+  }
+
+  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';
+    if (removing) {
+      // 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     ) => asset.id === 'guidance.core') && owns) {
+        changes.push({ assetId: 'guidance.core', target: found.paths.instruction, operation: 'remove', ownershipIdentity: 'gemini:instructions', projection: { renderer: 'gemini-instructions' } });
+      }
+    } else {
+      const content = instructionContent({ assets, context, paths: found.paths, fsImpl });
+      if (content !== null) {
+        const next = managedInstruction(found.instruction, render({ content }));
+        if (!next.ok) conflicts.push(next.conflict);
+        else if (next.operation !== 'none') changes.push({ assetId: 'guidance.core', target: found.paths.instruction, operation: next.operation, ownershipIdentity: 'gemini:instructions', afterFingerprint: fingerprint(next.content), content: next.content, projection: { renderer: 'gemini-instructions' } });
+      }
+    }
+    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 });
+    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     ) => item.id) },
+        extensions: { status: 'different', mode: found.paths.extensionMode, action: 'use Gemini CLI extension management' },
+        policies: policyStatuses(context.policies),
+      },
+    };
+  }
+
+  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 {
+      fsImpl.writeFileSync(temp, content, { encoding: 'utf8', flag: 'wx' });
+      fsImpl.renameSync(temp, file);
+    } finally {
+      if (fsImpl.existsSync(temp)) fsImpl.rmSync(temp, { force: true });
+    }
+  }
+  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     ) => 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
+    // rows as removals inside the apply batch; the lifecycle calls remove() only for `doflow remove`.
+    removeCopyTreeAssets(changes, { fsImpl });
+  }
+
+  /** 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     , { fsImpl = fs }      = {}) {
+    if (!fsImpl.existsSync(file)) return false;
+    const existing = fsImpl.readFileSync(file, 'utf8');
+    const start = existing.indexOf(MARKER_START);
+    if (start === -1) return false;
+    const end = existing.indexOf(MARKER_END, start + MARKER_START.length);
+    if (end === -1 || existing.indexOf(MARKER_START, end + MARKER_END.length) !== -1) {
+      throw new Error(`Refusing to remove malformed DoFlow markers in ${file}`);
+    }
+    let after = end + MARKER_END.length;
+    if (existing[after] === '\n') after += 1;
+    let next = existing.slice(0, start) + existing.slice(after);
+    if (next === '\n') next = '';
+    if (next === '') fsImpl.rmSync(file, { force: true });
+    else fsImpl.writeFileSync(file, next);
+    return true;
+  }
+  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     ) => change.nativeComponent === 'hooks');
+    if (hooksChange?.nativePlan) deployRemoveGeminiHooks(hooksChange.nativePlan, { fsImpl });
+    removeCopyTreeAssets(changes, { fsImpl });
+  }
+
+  function verify({ scope, scopeRoot, assets = [], context = {}, fsImpl = fs }     ) {
+    const found = discover({ scope, scopeRoot, context, fsImpl });
+    const resources = [];
+    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' } });
+      }
+    }
+    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 };
+}
+
+const singleton = createGeminiAdapter();
+
+/** Gemini's hooks trust, observed for a lifecycle target. Trust is not a static registry
+ * prerequisite the way Codex's `trusted-project`/`hook-review` are: Gemini fingerprints hook
+ * name/command and warns before running one that changed, so trust is computed live against the
+ * current hooks.json source and the harness's current settings.json. This is the adapter's own
+ * API for that observation (review A3 — lifecycle used to import planGeminiHooks and re-derive
+ * the plan itself, which put Gemini's hook semantics on the lifecycle side of the boundary).
+ * Read-only and side-effect free; returns the trust value or null when unobservable.
+ * @param {Object} target a lifecycle status target ({adapterInput, discovery})
+ * @returns {*} the plan's trust, or null
+ */
+function hookTrustFor(target     ) {
+  const context = target.adapterInput?.context || {};
+  const settingsFile = target.discovery?.paths?.settings;
+  if (!context.geminiHooksSourceFile || !settingsFile || target.discovery?.settings?.error) return null;
+  const plan = planGeminiHooks({
+    sourceFile: context.geminiHooksSourceFile, sourceHooksDir: context.geminiHooksSourceDir,
+    settingsFile, trusted: context.hooksTrusted,
+  });
+  return plan.ok ? (plan.trust ?? null) : null;
+}
+
+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,
+  createGeminiAdapter,
+};