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

package/src/adapters/hook-commands.ts

@@ -0,0 +1,60 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Shared hook-command verification — the one piece of codex/hooks.ts and gemini/hooks.ts that
+// proved byte-identical on inspection (unlike SUPPORTED_EVENTS, validateHooksConfig, and
+// classifyClaudeGuardrails, which encode genuine per-harness differences and stay in each
+// adapter). verifyHookCommands and the two private helpers it calls, commandScriptNames and
+// hookHandlers, check that a hook config's command handlers resolve to a real, executable script
+// in the harness's own hooks directory — that check does not vary by harness, so it lives once.
+const fs = require('node:fs');
+const path = require('node:path');
+
+function commandScriptNames(command: string): string[] {
+  // 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 }))));
+}
+
+// On `trusted`: both harnesses gate hook execution behind their own trust prompt — Codex through
+// its config, Gemini by fingerprinting a hook's name and command and warning before running one
+// that changed (geminicli.com/docs/hooks/). DoFlow verifies neither gate live; doing so would need
+// a running CLI session. It reports trust as a prerequisite whose shape it observed, not one it
+// bypassed or assumed satisfied. That reading is identical for both harnesses, which is part of
+// why this function is shared.
+// Windows carries no executable permission bits — statSync().mode always reports 0666/0444 and
+// chmodSync can only toggle the read-only flag — so the POSIX "not executable" failure mode
+// cannot exist there. Requiring the bit would refuse every hooks install on win32 (the scripts
+// are invoked through an explicit `bash <script>` command string, which needs no +x), so the
+// 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[] = [];
+  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);
+    if (names.length === 0) {
+      checks.push({ event, command: handler.command, ok: false, reason: 'Command does not identify a hook script', requiresTrust: true, trusted });
+      continue;
+    }
+    for (const name of names) {
+      const file = scriptsDir ? path.join(scriptsDir, name) : null;
+      const exists = Boolean(file && fsImpl.existsSync(file));
+      const executable = exists && (!EXEC_BITS_EXIST || Boolean(fsImpl.statSync(file).mode & 0o111));
+      checks.push({ event, command: handler.command, script: name, file, exists, executable,
+        ok: exists && executable, reason: !exists ? 'Hook script is missing' : (!executable ? 'Hook script is not executable' : null),
+        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' } };
+}
+
+module.exports = { commandScriptNames, hookHandlers, verifyHookCommands };

package/src/adapters/index.ts

@@ -0,0 +1,106 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Harness adapters own native formats and paths. This module intentionally only
+// validates and resolves that boundary; it never reads or writes harness files.
+const { resolveRegistrySource } = require('./resolve-source.ts');
+
+const ADAPTER_METHODS = Object.freeze(['discover', 'render', 'plan', 'apply', 'remove', 'verify']);
+
+/** Per-adapter native-projection normalizers. Each lives in its adapter's own directory (review
+ * A3: the Codex shape used to be inlined here, putting per-harness knowledge on the shared side of
+ * the boundary); this module only dispatches by adapter name. An adapter gaining a
+ * nativeProjection declaration registers its normalizer here. */
+const NATIVE_PROJECTION_NORMALIZERS: Record<string, () => any> = Object.freeze({
+  codex: () => require('./codex/native-projection.ts').normalizeNativeProjection,
+});
+
+/** Dispatch a harness's nativeProjection declaration to its adapter's own normalizer. */
+function nativeProjectionFor(registry: any, harness: any, mcp: any, context: any) {
+  if (!harness.nativeProjection) return {};
+  const load = NATIVE_PROJECTION_NORMALIZERS[harness.adapter];
+  if (!load) {
+    throw new Error(`No native projection normalizer is registered for '${harness.adapter}'. `
+      + `Registered: ${Object.keys(NATIVE_PROJECTION_NORMALIZERS).join(', ')}`);
+  }
+  return load()(registry, harness, mcp, context);
+}
+
+/**
+ * Convert validated registry declarations into the only generic payload an
+ * adapter receives. Native serializers may add adapter-specific fields, but
+ * cannot infer applicability from a missing projection.
+ */
+function projectAdapterInput({ registry, harness, scope, scopeRoot, assets = [], mcp = [], mcpAdoptable = [], policies = [], context = {} }: any) {
+  if (!registry || !harness) throw new Error('registry and harness are required for adapter projection');
+  const projectAsset = (asset: any) => {
+    const projection = asset?.projection?.[harness.id];
+    if (!projection || typeof projection.renderer !== 'string' || typeof projection.capability !== 'string') {
+      throw new Error(`Asset '${asset?.id ?? '?'}' lacks a projection for '${harness.id}'`);
+    }
+    const capability = harness.capabilities?.[projection.capability];
+    if (!capability || capability.status === 'unavailable') {
+      throw new Error(`Asset '${asset.id}' cannot project unavailable '${harness.id}' capability '${projection.capability}'`);
+    }
+    return Object.freeze({
+      id: asset.id, kind: asset.kind, source: asset.source, ownership: asset.ownership,
+      renderer: projection.renderer, capability: projection.capability,
+      capabilityStatus: capability.status, nativeTarget: harness.nativeTargets?.[projection.capability] ?? null,
+      nativeDir: asset.nativeDir?.[harness.id] ?? null,
+      // Optional destination shape for copy-tree assets. Null for every projection that mirrors
+      // source paths, which is all of them except Antigravity's directory-per-agent requirement.
+      layout: projection.layout ?? null,
+      transform: projection.transform ?? null,
+      prerequisites: [...(capability.prerequisites || [])],
+    });
+  };
+  if (mcp.length && (!harness.capabilities?.mcp || harness.capabilities.mcp.status === 'unavailable')) {
+    throw new Error(`Selected MCP servers cannot project to unavailable '${harness.id}' MCP capability`);
+  }
+  const projection = nativeProjectionFor(registry, harness, mcp, context);
+  return Object.freeze({
+    harness, scope, scopeRoot, context,
+    assets: Object.freeze(assets.map(projectAsset)),
+    mcp: Object.freeze(mcp.map((server: any) => Object.freeze({ ...server }))),
+    // Servers whose existing entries the adapter may take as its own while it holds no MCP row.
+    mcpAdoptable: Object.freeze(mcpAdoptable.map((server: any) => Object.freeze({ ...server }))),
+    policies: Object.freeze(policies.map((policy: any) => Object.freeze({ ...policy }))),
+    nativeTargets: Object.freeze({ ...harness.nativeTargets }),
+    projection: Object.freeze({ ...projection }),
+  });
+}
+
+function assertAdapter(adapter: any, name = 'adapter') {
+  if (!adapter || typeof adapter !== 'object') throw new Error(`${name} must be an object`);
+  for (const method of ADAPTER_METHODS) {
+    if (typeof adapter[method] !== 'function') throw new Error(`${name} must implement ${method}()`);
+  }
+  return adapter;
+}
+
+function createAdapterRegistry(adapters = {}) {
+  const entries = adapters instanceof Map ? [...adapters.entries()] : Object.entries(adapters);
+  const resolved = new Map();
+  for (const [name, adapter] of entries) {
+    if (typeof name !== 'string' || !name.trim()) throw new Error('Adapter names must be non-empty strings');
+    resolved.set(name, assertAdapter(adapter, `Adapter '${name}'`));
+  }
+  return Object.freeze({
+    names: () => [...resolved.keys()],
+    has: (name: any) => resolved.has(name),
+    get(name: any) {
+      const adapter = resolved.get(name);
+      if (!adapter) throw new Error(`No registered adapter '${name}'`);
+      return adapter;
+    },
+  });
+}
+
+function resolveAdapter(adapterRegistry: any, harness: any) {
+  if (!adapterRegistry || typeof adapterRegistry.get !== 'function') throw new Error('adapterRegistry must expose get(name)');
+  if (!harness || typeof harness.adapter !== 'string') throw new Error('Harness must declare an adapter');
+  return adapterRegistry.get(harness.adapter);
+}
+
+module.exports = { ADAPTER_METHODS, assertAdapter, createAdapterRegistry, resolveAdapter, resolveRegistrySource, nativeProjectionFor, projectAdapterInput };

package/src/adapters/kiro/index.ts

@@ -0,0 +1,310 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Kiro adapter.
+//
+// Kiro's native root is symmetric across scopes — `.kiro/` (project) / `~/.kiro/` (global) is the
+// one directory that holds everything Kiro reads: steering, agents, hooks, and settings/mcp.json
+// (see src/targets.js's toolDirs() for the same convention this adapter's own nativePaths()
+// mirrors). Unlike every other harness in this codebase, Kiro receives DoFlow's *full* guidance
+// tree as steering files rather than a single marker-wrapped pointer file plus a separately-copied
+// tree (design.md §4's "research decision D3"): there is no single-file instruction surface here
+// at all, so — unlike src/adapters/gemini or src/adapters/opencode — this adapter never renders a
+// marker-wrapped instruction file.
+//
+// Evidence: https://kiro.dev/docs/steering/, https://kiro.dev/docs/mcp/configuration/,
+// https://kiro.dev/docs/hooks/
+const fs = require('node:fs');
+const path = require('node:path');
+const { planTree, applyTree, removeTree, verifyTree, resolveTransform, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, sourceDirFor } = require('../copy-tree.ts');
+const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.ts');
+const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.ts');
+
+const HARNESS = 'kiro';
+const MCP_CONTAINER = 'mcpServers';
+const MCP_RENDERER = 'kiro-mcp';
+// Releases up to 1.18.0 recorded one `kiro:mcp:<id>` row per server (and never a row for the old
+// `kiro:mcp:registration` change); they are read as owned rows until a run replaces them.
+const LEGACY_MCP_PREFIX = `${HARNESS}:mcp:`;
+const LEGACY_MCP_REGISTRATION = `${HARNESS}:mcp:registration`;
+
+/**
+ * Native path facts live in core/registry/harnesses.json under this harness's "paths" section and
+ * resolve through the shared harness-paths resolver; `.kiro` (project) / `~/.kiro` (global) is the
+ * whole native root and every other path here is a fixed subpath under it.
+ * createKiroAdapter({ declaredPaths }) is the injection point buildAdapterRegistry() uses;
+ * module-level exports delegate to a default-configured instance so direct callers keep their
+ * historical shape.
+ */
+function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } = {}) {
+  // Parity note: Kiro's historical nativePaths() derived even its user-scope root from scopeRoot
+  // (the CLI passes $HOME there for -g installs), never from a separate homeDir argument — so the
+  // resolver is fed no homeDir and "root" keeps resolving exactly as before.
+  function nativePaths({ scope, scopeRoot }: any = {}) {
+    return resolveHarnessPaths(declaredPaths, { scope, scopeRoot });
+  }
+
+  /** Discovery keeps the MCP files as plan read them (`mcpSnapshot`), which verify compares against,
+   * and reports the servers DoFlow owns in Kiro's mcp.json now (`mcpOwned`). */
+  function discover({ scope, scopeRoot, mcp = [], mcpAdoptable = [], ledger, fsImpl = fs }: any) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const entries = mcpEntriesInput({ paths, mcp, mcpAdoptable, ledger });
+    const mcpSnapshot = readMcpFiles({ file: entries.file, ownRows: entries.ownRows, container: MCP_CONTAINER, fsImpl });
+    const read = mcpSnapshot[entries.file];
+    // `null` while the file is absent, unreadable or has no server map; every name in it otherwise, whoever wrote it.
+    const mcpConfigured = read?.ok && read.servers ? Object.keys(read.servers).sort() : null;
+    return { paths, mcpSnapshot, mcpOwned: ownedMcpIds({ ...entries, files: mcpSnapshot }), mcpConfigured };
+  }
+
+  /**
+   * Kiro has no single-file, marker-managed instruction surface for this adapter to render into —
+   * the guidance tree is projected file-for-file by the copy-tree engine below, once as steering
+   * (guidance.context-layer) and once into the shared `.doflow/guidance` (kiro.guidance-tree). Every
+   * asset routed to 'kiro' in core/registry/assets.json uses `renderer: copy-tree` or
+   * `kiro-agents`, so nothing reaches this function. It is kept as a pure passthrough only to
+   * satisfy the six-function adapter contract every harness must implement identically.
+   */
+  function render({ content = '' }: any = {}) {
+    return String(content);
+  }
+
+  // ---- copy-tree assets (steering tree, agents) ----
+
+  /**
+   * Kiro has a dedicated skills system (https://kiro.dev/docs/skills/): a folder containing
+   * `SKILL.md` with YAML frontmatter, optionally alongside scripts/references/assets — the same open
+   * Agent Skills standard DoFlow already authors, scanned from `.kiro/skills/` (workspace) and
+   * `~/.kiro/skills/` (global). `skills.doflow` therefore materialises like every other harness's
+   * skills tree, no exclusion needed.
+   *
+   * `agents.shared` is included alongside the generic `copy-tree` renderer even though its own
+   * projection declares `renderer: 'kiro-agents'` — a distinct name chosen so the registry can tell
+   * the two apart. Both materialise through the same engine, but `kiro-agents` declares the
+   * `kiro-agent-json` layout and `kiro-agents` transform: kiro-cli discovers agents as
+   * `.kiro/agents/<name>.json`, so each shared `<name>.md` spec is rendered, not mirrored.
+   */
+  function kiroTreeAssets(assets: any) {
+    return [...copyTreeAssets(assets), ...(assets || []).filter((asset: any) => asset.renderer === 'kiro-agents')];
+  }
+
+  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl = fs }: any) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const changes = [];
+    const conflicts = [];
+    const treeResults = [];
+    const notices = [];
+    for (const asset of kiroTreeAssets(assets)) {
+      const destDir = copyTreeDestDir(paths.configDir, asset);
+      const sourceDir = sourceDirFor(asset, context, fsImpl, 'Kiro');
+      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,
+        // Forwarded so the CLI's --force reaches planTree's conflict check; omitting it let
+        // planTree's own `force = false` default stand in silently. Gated on `!removing` for the
+        // reason codex/index.ts states in full: force heals drift on apply, but a hand-edited file
+        // is never deleted on removal, forced or not.
+        force: !removing && context?.force === true, });
+      treeResults.push(result);
+      conflicts.push(...result.conflicts.map((reason: any) => `${asset.id}: ${reason}`));
+      // A hand-edited file at a path DoFlow no longer writes 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`));
+      for (const change of result.changes) {
+        changes.push({
+          assetId: asset.id, target: change.target, source: change.source, operation: change.operation,
+          ownershipIdentity: `doflow:${HARNESS}: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: asset.renderer },
+        });
+      }
+    }
+    return { changes, conflicts, notices: [...siblingReplacedNotices(treeResults), ...notices] };
+  }
+
+  function applyCopyTreeAssets(changes: any, { fsImpl = fs }: any = {}) {
+    let applied = 0;
+    const grouped = new Map();
+    for (const change of changes) {
+      if (change.kind !== 'copy-tree-file' || 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: any, { fsImpl = fs }: any = {}) {
+    const treeChanges = changes.filter((change: any) => change.kind === 'copy-tree-file' && change.operation === 'remove' && !change.retained)
+      .map((change: any) => ({ 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) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const statuses = [];
+    const resources = [];
+    const conflicts = [];
+    for (const asset of kiroTreeAssets(assets)) {
+      const destDir = copyTreeDestDir(paths.configDir, asset);
+      const sourceDir = sourceDirFor(asset, context, fsImpl, 'Kiro');
+      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}`));
+      for (const resource of result.resources) {
+        resources.push({
+          assetId: asset.id, target: resource.target, ownershipIdentity: `doflow:${HARNESS}:copy-tree:${asset.id}:${resource.relPath}`,
+          kind: 'copy-tree-file', identity: resource.relPath,
+          fingerprint: resource.fingerprint, sourceVersion: 'registry-v1',
+          projection: { renderer: asset.renderer },
+        });
+      }
+      statuses.push({ assetId: asset.id, capability: asset.capability, status: result.ok ? 'managed' : 'conflict', target: destDir });
+    }
+    return { statuses, resources, conflicts };
+  }
+
+  // ---- MCP (.kiro/settings/mcp.json) ----
+
+  /**
+   * Shape one registry MCP server declaration into Kiro's own per-server schema (confirmed against
+   * kiro.dev/docs/mcp/configuration/): a local (stdio) server carries `command`/`args`/`env`/
+   * `disabled`/`autoApprove`/`disabledTools`; a remote server carries `url`/`headers` instead. The
+   * registry (core/registry/mcp.json) only ever declares stdio servers today, so only the fields it
+   * actually carries are emitted — this never invents a field the registry doesn't supply.
+   */
+  function buildServerEntry(server: any) {
+    if (server.url) return { url: server.url, ...(server.headers ? { headers: server.headers } : {}) };
+    return { command: server.command, ...(server.args?.length ? { args: server.args } : {}) };
+  }
+
+  function ownershipIdentity(id: any) { return `doflow:${HARNESS}:mcp-server:${id}`; }
+
+  function mcpOwnRows(ledger: any) {
+    return (ledger?.resources || []).filter((row: any) => row.harness === HARNESS).flatMap((row: any) => {
+      if (row.kind === 'mcp-server') {
+        return [{ identity: row.identity, target: row.target, fingerprint: row.fingerprint ?? null, ownershipIdentity: row.ownershipIdentity, legacy: false }];
+      }
+      const legacyIdentity = row.ownershipIdentity;
+      if (typeof legacyIdentity !== 'string' || !legacyIdentity.startsWith(LEGACY_MCP_PREFIX) || legacyIdentity === LEGACY_MCP_REGISTRATION) return [];
+      return [{ identity: legacyIdentity.slice(LEGACY_MCP_PREFIX.length), target: row.target, fingerprint: row.fingerprint ?? null, ownershipIdentity: legacyIdentity, legacy: true }];
+    });
+  }
+
+  /** Everything the shared entry-ownership rules (../mcp-entries.ts) need from this adapter. */
+  function mcpEntriesInput({ paths, mcp = [], mcpAdoptable = [], ledger, assets = [] }: any) {
+    const rendered = (servers: any) => servers.map((server: any) => ({ id: server.id, entry: buildServerEntry(server) }));
+    return {
+      file: paths.mcp, selected: rendered(mcp), adoptable: rendered(mcpAdoptable),
+      ownRows: mcpOwnRows(ledger),
+      foreignRows: (ledger?.resources || []).filter((row: any) => row.kind === 'mcp-server' && row.harness !== HARNESS)
+        .map((row: any) => ({ harness: row.harness, identity: row.identity, target: row.target })),
+      identityFor: ownershipIdentity, assetId: pseudoAssetId(assets), renderer: MCP_RENDERER, label: 'Kiro MCP',
+    };
+  }
+
+  /** Kiro has no hooks or mcp asset of its own in core/registry/assets.json (mcp servers come from
+   * core/registry/mcp.json, not an asset), so an MCP entry change piggybacks on an asset id
+   * this harness actually receives — the same "pseudo-component" technique
+   * src/adapters/gemini/index.ts#hooksAssetId already uses for its own settings-only component. */
+  function pseudoAssetId(assets: any) {
+    return assets.find((asset: any) => asset.id === 'guidance.context-layer')?.id ?? assets[0]?.id;
+  }
+
+  // ---- shared adapter contract ----
+
+  /**
+   * `.kiro/hooks/` is now a real, populated native surface: `kiro.hooks-scripts`
+   * (core/registry/assets.json) is a copy-tree asset like skills/agents, so `kiroTreeAssets()` above
+   * already plans/applies/removes it alongside them. This function only reports the
+   * declarative capability surface — same unconditional shape `plan()` already uses for
+   * instructions/skills/agents — not whether that asset happens to be present in a given call's
+   * `assets` array; per-file installed status for the hooks tree itself is reported through
+   * `copyTree.statuses`/`copyTree.resources`, exactly like it is for skills and agents.
+   */
+  function hooksSurface(paths: any) {
+    return { status: 'supported', target: paths.hooks };
+  }
+
+  function plan({ scope, scopeRoot, assets = [], mcp = [], mcpAdoptable = [], discovery, context = {}, ledger, fsImpl = fs }: any) {
+    const found = discovery || discover({ scope, scopeRoot, mcp, mcpAdoptable, ledger, fsImpl });
+    const changes = [];
+    const conflicts = [];
+    const removing = context.operation === 'remove';
+
+    const copyTree = planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl });
+    changes.push(...copyTree.changes);
+    conflicts.push(...copyTree.conflicts);
+
+    const mcpPlan = planMcpEntries({
+      ...mcpEntriesInput({ paths: found.paths, mcp, mcpAdoptable, ledger, assets }), files: found.mcpSnapshot, removing,
+    });
+    changes.push(...mcpPlan.changes);
+    conflicts.push(...mcpPlan.conflicts);
+
+    return {
+      changes, conflicts, prerequisites: [], notices: [...copyTree.notices, ...mcpPlan.notices],
+      surfaces: {
+        instructions: { status: 'supported', target: found.paths.steering },
+        skills: { status: 'supported', target: found.paths.skills },
+        agents: { status: 'supported', target: found.paths.agents },
+        hooks: hooksSurface(found.paths),
+        mcp: { status: found.mcpSnapshot[found.paths.mcp].ok ? 'supported' : 'blocked', target: found.paths.mcp, selected: mcp.map((item: any) => item.id) },
+      },
+    };
+  }
+
+  function apply({ changes = [], fsImpl = fs }: any) {
+    writeMcpEntries(changes, { container: MCP_CONTAINER, fsImpl });
+    applyCopyTreeAssets(changes, { fsImpl });
+    // An update that no longer ships a copy-tree file carries its rows as removals inside the
+    // apply batch; the lifecycle calls remove() only for `doflow remove`.
+    removeCopyTreeAssets(changes, { fsImpl });
+  }
+
+  function remove({ changes = [], fsImpl = fs }: any) {
+    writeMcpEntries(changes, { container: MCP_CONTAINER, fsImpl });
+    removeCopyTreeAssets(changes, { fsImpl });
+  }
+
+  function verify({ scope, scopeRoot, assets = [], mcp = [], mcpAdoptable = [], discovery, ledger, operation, context = {}, fsImpl = fs }: any) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const resources = [];
+    const conflicts = [];
+
+    const copyTree = verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl });
+    resources.push(...copyTree.resources);
+    conflicts.push(...copyTree.conflicts);
+
+    const entries = mcpEntriesInput({ paths, mcp, mcpAdoptable, ledger, assets });
+    const files = readMcpFiles({ file: entries.file, ownRows: entries.ownRows, container: MCP_CONTAINER, fsImpl });
+    const mcpResult = verifyMcpEntries({
+      ...entries, files, snapshot: discovery?.mcpSnapshot ?? files,
+      removing: (operation ?? context.operation) === 'remove', harness: HARNESS, sourceVersion: context.sourceVersion ?? 'unknown',
+    });
+    resources.push(...mcpResult.resources);
+    conflicts.push(...mcpResult.conflicts);
+
+    return {
+      ok: conflicts.length === 0,
+      resources,
+      statuses: { copyTree: copyTree.statuses, mcp: mcpResult.statuses, hooks: hooksSurface(paths) },
+      conflicts,
+    };
+  }
+
+  return { nativePaths, discover, render, plan, apply, remove, verify, buildServerEntry };
+}
+
+const singleton = createKiroAdapter();
+
+module.exports = {
+  nativePaths: singleton.nativePaths, discover: singleton.discover, render: singleton.render,
+  plan: singleton.plan, apply: singleton.apply, remove: singleton.remove, verify: singleton.verify,
+  buildServerEntry: singleton.buildServerEntry,
+  createKiroAdapter,
+};