@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/core/worker-evidence/codex/checks.json

@@ -0,0 +1,38 @@
+{
+  "schema": "doflow-worker-checks-v1",
+  "harness": "codex",
+  "binary": "codex",
+  "version": { "argv": ["--version"], "expect": "^codex-cli \\d+\\.\\d+\\.\\d+" },
+  "checks": [
+    {
+      "id": "exec-one-shot",
+      "argv": ["exec", "--help"],
+      "expect": ["^Usage: codex exec \\[OPTIONS\\] \\[PROMPT\\]", "instructions are read from stdin"],
+      "establishes": ["runnableProbe", "oneShot"]
+    },
+    {
+      "id": "exec-json",
+      "argv": ["exec", "--help"],
+      "expect": ["^\\s+--json$", "Print events to stdout as JSONL", "-o, --output-last-message"],
+      "establishes": ["structuredOutput"]
+    },
+    {
+      "id": "exec-sandbox",
+      "argv": ["exec", "--help"],
+      "expect": ["-s, --sandbox <SANDBOX_MODE>", "read-only, workspace-write"],
+      "establishes": ["readOnly", "isolatedEdit"]
+    },
+    {
+      "id": "spawn-denial",
+      "argv": ["features", "list", "--disable", "multi_agent", "--disable", "multi_agent_v2"],
+      "expect": ["^multi_agent\\s+\\S+\\s+false$", "^multi_agent_v2\\s+\\S+\\s+false$"],
+      "establishes": ["spawnDenial"]
+    },
+    {
+      "id": "exec-model",
+      "argv": ["exec", "--help"],
+      "expect": ["^\\s+-m, --model <MODEL>$"],
+      "establishes": ["model"]
+    }
+  ]
+}

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@khoavu882/doflow",
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0",
   "description": "DoFlow config installer — npx CLI for the registry-driven multi-harness install/update/remove lifecycle",
   "keywords": [
     "claude-code",
     "codex",
-    "gemini",
     "opencode",
     "ai-coding-agent",
     "skills",
@@ -26,16 +25,21 @@
     "doflow": "bin/doflow.js"
   },
   "engines": {
-    "node": "^22.18.0 || >=24.3.0"
+    "node": ">=24.22.1"
   },
   "scripts": {
-    "test": "node --test \"test/**/*.test.js\"",
+    "test": "node --test \"test/**/*.test.js\" \"test/**/*.test.ts\"",
+    "test:fast": "node test/helper/fast-tier.ts",
     "typecheck": "npx -y -p typescript@5.7.2 tsc -p tsconfig.json",
     "build:package": "node src/release/build-package.js .pack",
-    "bench": "node bench/runner.js",
+    "bench": "node bench/runner.ts",
     "drift": "node scripts/check-format-drift.js",
+    "emission-rules": "node src/runtime/context/emission-rules.js --check",
     "release-notes": "node src/release/changelog-section.js",
-    "version": "node src/release/sync-plugin-versions.js && git add core/.codex-plugin/plugin.json core/.claude-plugin/plugin.json core/.plugin/plugin.json"
+    "docs:blocks": "node src/release/docs-blocks.js --check",
+    "release:preflight": "node src/release/preflight.js",
+    "release:rehearse": "node src/release/rehearse.js",
+    "version": "node src/release/sync-plugin-versions.js && git add core/.codex-plugin/plugin.json core/.claude-plugin/plugin.json core/.plugin/plugin.json core/registry/packages/doflow/doflow-package.json core/registry/contribution-points.json"
   },
   "files": [
     "bin/",

package/src/adapters/antigravity/index.js

@@ -4,9 +4,11 @@
 
 // Antigravity CLI adapter (#8). Scope follows the surfaces verified against Antigravity's own
 // docs (antigravity.google/docs/cli/*):
-//   instructions — marker-managed section in PROJECT AGENTS.md only. Global memory is
-//     ~/.gemini/GEMINI.md, shared with the Gemini CLI harness; two adapters writing one file with
-//     one marker pair would fight, so global instructions are reported, never written.
+//   instructions — marker-managed section in project AGENTS.md and global ~/.gemini/GEMINI.md (left
+//     alone while another live harness declares it); a retired harness's span there is taken over in
+//     one write (row 127 IC-007), a person-edited file kept until --force. See instructionTarget.
+//   rules        — the core set (DOFLOW_CORE.md and the files it imports), flat, in project .agents/rules
+//     only; the full guidance tree stays in .doflow/guidance.
 //   skills       — folder-form copy-tree into project .agents/skills or user ~/.gemini/config/skills.
 //   agents       — copy-tree into project .agents/agents or user ~/.gemini/config/agents.
 //   mcp          — entries of the mcpServers object in .agents/mcp_config.json (workspace) or
@@ -20,9 +22,10 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
-const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor } = require('../copy-tree.js');
+const { MARKER_START, MARKER_END, removeMarkedSection } = require('../../helper/marker-merge.js');
+const { planTree, applyTree, removeTree, verifyTree, resolveTransform, copyTreeAssets, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor } = require('../copy-tree.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
+const { renderGuidancePointer } = require('../guidance-pointer.js');
 const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
 
 const HARNESS = 'antigravity';
@@ -136,8 +139,8 @@ function sha256File(fsImpl     , file     ) {
 
 /** Native paths per scope, resolved from the declaration in core/registry/harnesses.json
  * ("paths"): project customization lives at <root>/.agents, global config at ~/.gemini/config
- * (the shared-customization root); instructions and skills are project-only surfaces, so no user
- * rule is declared for them and they resolve to null there. */
+ * (the shared-customization root); instructions are AGENTS.md in the project and ~/.gemini/GEMINI.md
+ * globally; the hook surfaces are project-only, so no user rule is declared and they resolve to null. */
 function resolveNativePaths(declaredPaths     , { scope, scopeRoot, homeDir }      = {}) {
   if (scope !== 'project' && scope !== 'global') throw new Error(`Unsupported Antigravity scope '${scope}'`);
   const resolved = resolveHarnessPaths(declaredPaths, { scope, scopeRoot, homeDir });
@@ -178,6 +181,8 @@ function createAntigravityAdapter({ declaredPaths = DEFAULT_DECLARED_PATHS }
     apply,
     remove,
     verify: (options     , impl = {}) => verify(options, { ...impl, nativePaths: nativePathsFor }),
+    planHookDoors: (options     , impl = {}) => planHookDoors(options, { ...impl, nativePaths: nativePathsFor }),
+    verifyHookDoors: (options     , impl = {}) => verifyHookDoors(options, { ...impl, nativePaths: nativePathsFor }),
   };
 }
 
@@ -210,16 +215,25 @@ function render({ content = '' }      = {}) {
   return `${MARKER_START}\n${String(content).trimEnd()}\n${MARKER_END}\n`;
 }
 
-function managedInstruction(existing     , rendered     ) {
+const INSTRUCTIONS_IDENTITY = `doflow:${HARNESS}:instructions:managed-section`;
+/** The short start marker the retired harness wrote into ~/.gemini/GEMINI.md (row 127). It is read
+ * only in a file this adapter is taking over, never written: the span it opens is replaced with ours. */
+const PREDECESSOR_MARKER_START = '<!-- doflow:start -->';
+
+/** The file's content with `rendered` as its DoFlow span: created, appended to a file with none, or
+ * replacing the span in place. `predecessor` also accepts the retired harness's start marker, for a
+ * file being taken over. `name` is the file's name in the conflict. */
+function managedInstruction(existing     , rendered     , { name = 'AGENTS.md', predecessor = false }      = {}) {
   if (existing === null) return { ok: true, operation: 'create', content: rendered };
-  const start = existing.indexOf(MARKER_START);
+  let start = existing.indexOf(MARKER_START);
+  if (start === -1 && predecessor) start = existing.indexOf(PREDECESSOR_MARKER_START);
   const end = existing.indexOf(MARKER_END);
   if (start === -1 && end === -1) {
     const separator = existing === '' || existing.endsWith('\n') ? '\n' : '\n\n';
     const content = `${existing}${separator}${rendered}`;
     return { ok: true, operation: 'merge', content };
   }
-  if (start === -1 || end === -1 || end < start) return { ok: false, conflict: 'AGENTS.md has malformed DoFlow managed-section markers' };
+  if (start === -1 || end === -1 || end < start) return { ok: false, conflict: `${name} 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 };
 }
@@ -277,7 +291,7 @@ function planTrees({ assets, paths, scope, neutralResources, removing, repoRoot,
   for (const { asset, destDir } of targets) {
     const sourceDir = sourceDirFor(asset, { repoRoot }, fsImpl, HARNESS);
     const previousResources = ledgerFileResources(neutralResources, HARNESS, asset.id);
-    const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(neutralResources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, keepModified: !removing,
+    const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(neutralResources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, transform: asset.transform, select: asset.select, 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
@@ -295,6 +309,7 @@ function planTrees({ assets, paths, scope, neutralResources, removing, repoRoot,
         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: 'copy-tree' },
       });
@@ -313,7 +328,8 @@ function runTreeChanges(changes     , mode     ) {
     .filter((c     ) => c.projection?.renderer === 'copy-tree' || c.kind === 'copy-tree-file')
     .map((c     ) => ({ relPath: c.identity ?? c.relPath, target: c.target,
       source: c._text ? undefined : c.source, operation: c.operation,
-      fingerprint: c.fingerprint, pruneGuard: c.pruneGuard, ...(c._text ? { _text: c._text } : {}) }));
+      fingerprint: c.fingerprint, pruneGuard: c.pruneGuard, transformName: c.transformName || null,
+      ...(c._text ? { _text: c._text } : {}) }));
   // Content-managed tree files (hook scripts): write rendered text with +x, not a byte copy.
   for (const t of treeChanges) {
     if (t._text === undefined) continue;
@@ -328,58 +344,100 @@ function runTreeChanges(changes     , mode     ) {
       const plain = treeChanges.filter((t     ) => t._text === undefined);
       const writes = plain.filter((c     ) => c.operation !== 'remove');
       const removals = plain.filter((c     ) => c.operation === 'remove');
-      const applied = writes.length ? applyTree({ changes: writes }).applied : 0;
+      // A projection that declares a transform (the rules' always_on header) is re-derived from the
+      // source at write time, so each change is applied under its own transform.
+      const byTransform = new Map                      ();
+      for (const change of writes) byTransform.set(change.transformName, [...(byTransform.get(change.transformName) || []), change]);
+      let applied = 0;
+      for (const [transformName, group] of byTransform) {
+        applied += applyTree({ changes: group, transform: transformName ? resolveTransform(transformName) : undefined }).applied;
+      }
       const removed = removals.length ? removeTree({ changes: removals }).removed : 0;
       return { applied, removed };
     })(),
   };
-  const writes = treeChanges.filter((c     ) => c.operation !== 'remove');
-  const removals = treeChanges.filter((c     ) => c.operation === 'remove');
-  const applied = writes.length ? applyTree({ changes: writes }).applied : 0;
-  const removed = removals.length ? removeTree({ changes: removals }).removed : 0;
-  return { applied, removed };
 }
 
 // ---- instructions component ----
 
-function planInstructions({ paths, assets, removing, repoRoot, fsImpl = fs }     ) {
-  if (scopeOf(paths) !== 'project') return { changes: [], conflicts: [] };
-  void repoRoot;
+/** The instruction file this run manages, or null: project AGENTS.md as ever; the global GEMINI.md
+ * only when the pointer asset is selected and no other live harness in `registry` declares that same
+ * file (until the harness that owned it retires, its adapter keeps it and this one stays out). */
+function instructionTarget({ paths, assets, registry }     ) {
+  if (!paths.instruction) return null;
+  if (scopeOf(paths) === 'project') return paths.instruction;
+  if (!(assets ?? []).some((asset     ) => asset.id === POINTER_ASSET_ID)) return null;
+  const declaredBy = (harness     ) => {
+    if (harness?.id === HARNESS || !harness?.paths?.instruction) return false;
+    try { return resolveHarnessPaths({ instruction: harness.paths.instruction }, { scope: 'global', scopeRoot: paths.root, homeDir: paths.root }).instruction === paths.instruction; } catch { return false; }
+  };
+  return (registry?.harnesses ?? []).some(declaredBy) ? null : paths.instruction;
+}
+
+/** How this run stands to a section it took over (IC-007): the lifecycle's handover verdict for the
+ * file, this harness's own row on it, and whether a person-edited file stays as it is (`retained`:
+ * edited before the handover, or kept since, and no --force). `predecessor` lets the retired
+ * harness's span count as the section to replace; `keptRow` is a row recorded as kept. A handover
+ * file whose DoFlow span already is this harness's render was written by DoFlow itself (a run that
+ * threw after that write and before its ledger write), so it does not count as edited. */
+function instructionState({ target, context, resources, paths, fsImpl = fs }     ) {
+  const handover = (context.handovers ?? []).find((item     ) => item.target === target) ?? null;
+  const ownRow = (resources ?? []).find((row     ) => row.harness === HARNESS && row.target === target && row.ownershipIdentity === INSTRUCTIONS_IDENTITY) ?? null;
+  const ownWrite = () => {
+    const rendered = renderedInstruction(paths, fsImpl);
+    if (rendered === null || !fsImpl.existsSync(target)) return false;
+    const outcome = managedInstruction(fsImpl.readFileSync(target, 'utf8'), rendered);
+    return outcome.ok && outcome.operation === 'none';
+  };
+  const edited = (handover?.edited === true && !ownWrite()) || ownRow?.retainedEdit === true;
+  return { predecessor: Boolean(handover) || ownRow?.retainedEdit === true, retained: edited && context.force !== true,
+    keptRow: ownRow?.retainedEdit === true };
+}
+
+function instructionsChange(target     , fields     ) {
+  return { assetId: POINTER_ASSET_ID, target, ownershipIdentity: INSTRUCTIONS_IDENTITY,
+    kind: 'instructions-section', identity: path.basename(target), projection: { renderer: 'antigravity-instructions' }, ...fields };
+}
+
+function planInstructions({ paths, target, removing, state, fsImpl = fs }     ) {
+  const none = { changes: [], conflicts: [], notices: [] };
+  if (!target) return none;
   if (removing) {
     // Removal must strip the section DoFlow owns while leaving foreign bytes untouched — same
     // contract as the other AGENTS-style adapters.
-    if (!fsImpl.existsSync(paths.instruction)) return { changes: [], conflicts: [] };
-    const text = fsImpl.readFileSync(paths.instruction, 'utf8');
-    if (!text.includes(MARKER_START)) return { changes: [], conflicts: [] };
-    return {
-      changes: [{
-        assetId: POINTER_ASSET_ID, target: paths.instruction, operation: 'remove',
-        ownershipIdentity: `doflow:${HARNESS}:instructions:managed-section`,
-        kind: 'instructions-section', identity: 'AGENTS.md',
-        projection: { renderer: 'antigravity-instructions' },
-      }],
-      conflicts: [],
-    };
+    if (!fsImpl.existsSync(target)) return none;
+    const text = fsImpl.readFileSync(target, 'utf8');
+    // A kept edited file with no span left still carries this harness's row: the remove change
+    // releases the row, and apply finds no span to strip, so the person's file is not touched.
+    if (!text.includes(MARKER_START) && !state.keptRow) return none;
+    return { ...none, changes: [instructionsChange(target, { operation: 'remove' })] };
   }
-  const sourceText = pointerBody(fsImpl);
-  if (!sourceText) return { changes: [], conflicts: [] };
-  const existing = fsImpl.existsSync(paths.instruction) ? fsImpl.readFileSync(paths.instruction, 'utf8') : null;
-  const outcome = managedInstruction(existing, render({ content: sourceText }));
-  if (!outcome.ok) return { changes: [], conflicts: [outcome.conflict] };
-  if (outcome.operation === 'none') return { changes: [], conflicts: [] };
+  if (state.retained) {
+    const shown = scopeOf(paths) === 'global' ? `~/${path.relative(paths.root, target)}` : path.relative(paths.root, target);
+    return { ...none, notices: [`kept ${shown}: changed before handover; --force replaces the DoFlow section`] };
+  }
+  const rendered = renderedInstruction(paths, fsImpl);
+  if (rendered === null) return none;
+  const existing = fsImpl.existsSync(target) ? fsImpl.readFileSync(target, 'utf8') : null;
+  const outcome = managedInstruction(existing, rendered, { name: path.basename(target), predecessor: state.predecessor });
+  if (!outcome.ok) return { ...none, conflicts: [outcome.conflict] };
+  if (outcome.operation === 'none') return none;
   return {
-    changes: [{
-      assetId: POINTER_ASSET_ID, target: paths.instruction, operation: existing === null ? 'create' : 'update',
-      ownershipIdentity: `doflow:${HARNESS}:instructions:managed-section`,
-      kind: 'instructions-section', identity: 'AGENTS.md',
+    ...none,
+    changes: [instructionsChange(target, {
+      operation: existing === null ? 'create' : 'update',
       afterFingerprint: fingerprint(outcome.content), sourceVersion: 'registry-v1',
-      projection: { renderer: 'antigravity-instructions' },
       _content: outcome.content,
-    }],
-    conflicts: [],
+    })],
   };
 }
 
+/** This scope's DoFlow section: the shared pointer rendered for the scope, inside the markers. */
+function renderedInstruction(paths     , fsImpl     ) {
+  const sourceText = pointerBody(fsImpl);
+  return sourceText ? render({ content: renderGuidancePointer(sourceText, { scope: scopeOf(paths), scopeRoot: paths.root }) }) : null;
+}
+
 function pointerBody(fsImpl     ) {
   // The shared pointer prose ships once; read it through the same repo-relative anchor the other
   // AGENTS-style adapters use.
@@ -430,13 +488,18 @@ function plan(options      = {}, impl      = {}) {
   const selectedServers = Array.isArray(options.mcp) ? options.mcp : [];
   const discovery = options.discovery ?? discover(options, impl);
 
-  const instructions = planInstructions({ paths, assets: options.assets, removing, repoRoot: context.repoRoot, fsImpl });
+  const instructionFile = instructionTarget({ paths, assets: options.assets, registry: options.registry });
+  const instructions = planInstructions({ paths, target: instructionFile, removing, fsImpl,
+    state: instructionState({ target: instructionFile, context, resources: neutralResources, paths, fsImpl }) });
   const trees = planTrees({ assets: options.assets, paths, scope, neutralResources, removing, repoRoot: context.repoRoot, force: context.force === true, fsImpl });
   const mcp = planMcpEntries({
     ...mcpEntriesInput({ paths, mcp: selectedServers, mcpAdoptable: options.mcpAdoptable, resources: neutralResources }),
     files: discovery.mcpSnapshot, removing,
   });
-  const hooksPlan = planHooks({ paths, scope, neutralResources, removing, repoRoot: context.repoRoot, fsImpl });
+  // Hook tiers (maint-hooks): outside `hooks.harnesses` this plan carries no hook change; the lifecycle
+  // plans the removal of what an earlier run wrote, from the ledger, against the full registry.
+  const hooksPlan = context.hooksOff === true && !removing ? { changes: [], conflicts: [] }
+    : planHooks({ paths, scope, neutralResources, removing, repoRoot: context.repoRoot, fsImpl });
 
   const changes = [...instructions.changes, ...trees.changes, ...mcp.changes, ...hooksPlan.changes];
   const conflicts = [...instructions.conflicts, ...trees.conflicts, ...mcp.conflicts, ...hooksPlan.conflicts];
@@ -445,10 +508,33 @@ function plan(options      = {}, impl      = {}) {
     conflicts,
     prerequisites: [],
     requiredNativeResources: changes,
-    notices: [...trees.notices, ...mcp.notices],
+    notices: [...instructions.notices, ...trees.notices, ...mcp.notices],
   };
 }
 
+/** The hook front doors (IC-037): the shims and the hooks.json groups that run them, planned and
+ * verified alone. Project scope only, and only when the harness selected the hooks asset. */
+function planHookDoors(options      = {}, impl      = {}) {
+  const fsImpl = impl.fsImpl || fs;
+  const context = options.context ?? {};
+  const scope = options.scope ?? 'project';
+  if (!(options.assets ?? []).some((asset     ) => asset.id === HOOKS_ASSET_ID)) return { changes: [], conflicts: [], prerequisites: [], notices: [] };
+  const paths = (impl.nativePaths ?? singleton.nativePaths)({ ...options, scope, homeDir: context.homeDir });
+  const doors = planHooks({ paths, scope, neutralResources: ledgerResources(options), removing: false, repoRoot: context.repoRoot, fsImpl });
+  return { changes: doors.changes, conflicts: doors.conflicts, prerequisites: [], notices: [] };
+}
+
+function verifyHookDoors(options      = {}, impl      = {}) {
+  const fsImpl = impl.fsImpl || fs;
+  const context = options.context ?? {};
+  const scope = options.scope ?? 'project';
+  if (scope !== 'project' || !(options.assets ?? []).some((asset     ) => asset.id === HOOKS_ASSET_ID)) return { ok: true, statuses: [], resources: [], conflicts: [] };
+  const paths = (impl.nativePaths ?? singleton.nativePaths)({ ...options, scope, homeDir: context.homeDir });
+  const doors = verifyHooks({ options, paths, context, fsImpl });
+  const conflicts = doors.statuses.filter((status     ) => status.status === 'conflict').map((status     ) => status.reason ?? status.identity);
+  return { ok: conflicts.length === 0, ...doors, conflicts };
+}
+
 function apply(options      = {}, impl      = {}) {
   const fsImpl = impl.fsImpl || fs;
   // apply()/verify() are reached through the lifecycle with the same scope inputs plan() saw, so
@@ -460,14 +546,26 @@ function apply(options      = {}, impl      = {}) {
 
   for (const change of changes.filter((c     ) => c.projection?.renderer === 'antigravity-instructions')) {
     if (change.operation === 'remove') {
-      // pi precedent: strip only the managed span; the file survives even when nothing remains.
       if (!fsImpl.existsSync(change.target)) continue;
+      // The global file is the person's: the span goes with the one newline put before it, so their
+      // bytes come back exactly (and a file that held only the span goes with it). A kept file taken
+      // over from the retired harness may still hold that harness's span, under its short marker.
+      if ((options.scope ?? 'project') === 'global') { removeMarkedSection(change.target, { startMarkers: [MARKER_START, PREDECESSOR_MARKER_START] }); continue; }
+      // pi precedent: strip only the managed span; the file survives even when nothing remains.
       const next = strippedInstruction(fsImpl.readFileSync(change.target, 'utf8'));
       if (next !== null) fsImpl.writeFileSync(change.target, next, 'utf8');
       continue;
     }
+    // One rename onto the file: no reader, and no failure, ever sees it without its DoFlow span.
     fsImpl.mkdirSync(path.dirname(change.target), { recursive: true });
-    fsImpl.writeFileSync(change.target, change._content ?? render({ content: '' }), 'utf8');
+    const tmp = `${change.target}.${process.pid}.tmp`;
+    try {
+      fsImpl.writeFileSync(tmp, change._content ?? render({ content: '' }), 'utf8');
+      fsImpl.renameSync(tmp, change.target);
+    } catch (error) {
+      fsImpl.rmSync(tmp, { force: true });
+      throw error;
+    }
   }
   for (const change of changes.filter((c     ) => c.projection?.renderer === 'antigravity-hooks')) {
     if (change.kind === 'copy-tree-file') continue;          // handled by runTreeChanges below
@@ -506,6 +604,60 @@ function remove(options      = {}, impl      = {}) {
   return apply(options, impl);
 }
 
+/** The hook shims' bytes and the registered groups (project scope), as statuses and resources. */
+function verifyHooks({ options, paths, context, fsImpl }     ) {
+  const statuses        = [];
+  const resources        = [];
+  const hooksTarget = paths.hooksJson;
+  const scriptTargets                      = {
+    'pre-implementation-gate.sh': paths.hookScript,
+    'stop-check.sh': paths.stopHookScript,
+  };
+  // Source-side residue: reads the shims from THIS checkout (the authored source of the
+  // projection, not an install destination — the destination is declared as the paths above).
+  const scriptSourceDir = path.join(path.resolve(registryRepoRoot(options)), 'core', 'harnesses', 'antigravity', 'hooks');
+  const removingOp = (context.operation ?? options.operation ?? '') === 'remove';
+  const fingerprints                      = {};
+  let scriptsOk = true;
+  let anyPresent = false;
+  for (const identity of HOOK_SCRIPTS) {
+    let sourceFp = null;
+    try { sourceFp = sha256File(fsImpl, path.join(scriptSourceDir, identity)); } catch { /* checkout without that shim */ }
+    fingerprints[identity] = sourceFp;
+    const target = scriptTargets[identity];
+    const current = fsImpl.existsSync(target) ? sha256File(fsImpl, target) : null;
+    if (current !== null) anyPresent = true;
+    if (current === null || current !== sourceFp) scriptsOk = false;
+  }
+  const doc = readJsonObject(hooksTarget, { fsImpl });
+  const gate = doc?.[HOOKS_GROUP];
+  const stop = doc?.[STOP_HOOKS_GROUP];
+  const gateOk = Boolean(gate?.PreToolUse?.[0]?.hooks?.[0]?.command)
+    && gate.PreToolUse[0].hooks[0].command === scriptTargets['pre-implementation-gate.sh']
+    && gate.PreToolUse[0].matcher === GATE_MATCHER;
+  // Stop registration is matcher-free: handlers sit directly under the event key.
+  const stopOk = Array.isArray(stop?.Stop) && stop.Stop.length > 0
+    && stop.Stop[0]?.command === scriptTargets['stop-check.sh'];
+  const groupsOk = gateOk && stopOk;
+  statuses.push({ assetId: HOOKS_ASSET_ID, capability: 'hooks', status:
+    removingOp ? (!anyPresent && !groupsOk ? 'absent' : 'retained')
+      : (scriptsOk && groupsOk ? 'managed' : (!anyPresent && !groupsOk ? 'absent' : 'missing')),
+    ownershipIdentity: `${HARNESS}:hooks:registration`, target: hooksTarget });
+  if (!removingOp && scriptsOk && groupsOk) {
+    resources.push({ assetId: HOOKS_ASSET_ID, target: hooksTarget,
+      ownershipIdentity: `${HARNESS}:hooks:registration`, kind: 'hooks-json',
+      fingerprint: fingerprint(JSON.stringify(doc)), sourceVersion: 'registry-v1',
+      projection: { renderer: 'antigravity-hooks' } });
+    for (const identity of HOOK_SCRIPTS) {
+      resources.push({ assetId: HOOKS_ASSET_ID, target: scriptTargets[identity],
+        ownershipIdentity: `${HARNESS}:copy-tree:${HOOKS_ASSET_ID}:${identity}`,
+        kind: 'copy-tree-file', identity, fingerprint: fingerprints[identity],
+        sourceVersion: 'registry-v1', projection: { renderer: 'antigravity-hooks' } });
+    }
+  }
+  return { statuses, resources };
+}
+
 function verify(options      = {}, impl      = {}) {
   const fsImpl = impl.fsImpl || fs;
   const context = options.context ?? {};
@@ -515,24 +667,28 @@ function verify(options      = {}, impl      = {}) {
   const statuses = [];
   const resources = [];
 
-  const instruction = paths.instruction && fsImpl.existsSync(paths.instruction)
-    ? fsImpl.readFileSync(paths.instruction, 'utf8') : null;
-  const managed = instruction !== null && instruction.includes(MARKER_START) && instruction.includes(MARKER_END);
-  if (paths.instruction) {
+  const instructionFile = instructionTarget({ paths, assets: options.assets, registry: options.registry });
+  const state = instructionState({ target: instructionFile, context, resources: ledgerResources(options), paths, fsImpl });
+  const instruction = instructionFile && fsImpl.existsSync(instructionFile)
+    ? fsImpl.readFileSync(instructionFile, 'utf8') : null;
+  const managed = instruction !== null && instruction.includes(MARKER_END)
+    && (instruction.includes(MARKER_START) || (state.predecessor && instruction.includes(PREDECESSOR_MARKER_START)));
+  // A kept, person-edited file (IC-007) is owned as it is now, markers or not: an edit can drop the
+  // span, and without its row the next run would see no owner and append the section unasked.
+  const kept = !removing && state.retained && instruction !== null;
+  if (instructionFile) {
     // Removal verification asks "did our section go away?"; install/update asks "is it managed?".
     statuses.push({
       assetId: POINTER_ASSET_ID, capability: 'instructions',
-      status: removing ? (managed ? 'retained' : 'absent') : (managed ? 'managed' : 'missing'),
-      target: paths.instruction,
+      status: removing ? (managed ? 'retained' : 'absent') : (managed ? 'managed' : (kept ? 'retained' : 'missing')),
+      target: instructionFile,
     });
-    if (managed && !removing) {
-      resources.push({
-        assetId: POINTER_ASSET_ID, target: paths.instruction,
-        ownershipIdentity: `doflow:${HARNESS}:instructions:managed-section`,
-        kind: 'instructions-section', identity: 'AGENTS.md',
+    if (!removing && (managed || kept)) {
+      // Recorded with the file as it is now; a kept one is flagged so later runs keep it until --force.
+      resources.push(instructionsChange(instructionFile, {
         fingerprint: fingerprint(instruction), sourceVersion: 'registry-v1',
-        projection: { renderer: 'antigravity-instructions' },
-      });
+        ...(state.retained ? { retainedEdit: true } : {}),
+      }));
     }
   }
 
@@ -540,7 +696,7 @@ function verify(options      = {}, impl      = {}) {
     const destDir = treeDestFor(asset, paths, scope);
     if (!destDir) continue;
     const sourceDir = sourceDirFor(asset, { repoRoot: context.repoRoot }, fsImpl, HARNESS);
-    const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, plannedWrites: context.plannedWrites });
+    const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: asset.transform, select: asset.select, plannedWrites: context.plannedWrites });
     conflictsToStatuses(result.conflicts, asset.id, statuses);
     for (const resource of result.resources) {
       resources.push({
@@ -563,54 +719,10 @@ function verify(options      = {}, impl      = {}) {
   resources.push(...mcp.resources);
 
   // Hooks projection (project scope): the shims' bytes and the registered groups.
-  if (scope === 'project') {
-    const hooksTarget = paths.hooksJson;
-    const scriptTargets                      = {
-      'pre-implementation-gate.sh': paths.hookScript,
-      'stop-check.sh': paths.stopHookScript,
-    };
-    // Source-side residue: reads the shims from THIS checkout (the authored source of the
-    // projection, not an install destination — the destination is declared as the paths above).
-    const scriptSourceDir = path.join(path.resolve(registryRepoRoot(options)), 'core', 'harnesses', 'antigravity', 'hooks');
-    const removingOp = (context.operation ?? options.operation ?? '') === 'remove';
-    const fingerprints                      = {};
-    let scriptsOk = true;
-    let anyPresent = false;
-    for (const identity of HOOK_SCRIPTS) {
-      let sourceFp = null;
-      try { sourceFp = sha256File(fsImpl, path.join(scriptSourceDir, identity)); } catch { /* checkout without that shim */ }
-      fingerprints[identity] = sourceFp;
-      const target = scriptTargets[identity];
-      const current = fsImpl.existsSync(target) ? sha256File(fsImpl, target) : null;
-      if (current !== null) anyPresent = true;
-      if (current === null || current !== sourceFp) scriptsOk = false;
-    }
-    const doc = readJsonObject(hooksTarget, { fsImpl });
-    const gate = doc?.[HOOKS_GROUP];
-    const stop = doc?.[STOP_HOOKS_GROUP];
-    const gateOk = Boolean(gate?.PreToolUse?.[0]?.hooks?.[0]?.command)
-      && gate.PreToolUse[0].hooks[0].command === scriptTargets['pre-implementation-gate.sh']
-      && gate.PreToolUse[0].matcher === GATE_MATCHER;
-    // Stop registration is matcher-free: handlers sit directly under the event key.
-    const stopOk = Array.isArray(stop?.Stop) && stop.Stop.length > 0
-      && stop.Stop[0]?.command === scriptTargets['stop-check.sh'];
-    const groupsOk = gateOk && stopOk;
-    statuses.push({ assetId: HOOKS_ASSET_ID, capability: 'hooks', status:
-      removingOp ? (!anyPresent && !groupsOk ? 'absent' : 'retained')
-        : (scriptsOk && groupsOk ? 'managed' : (!anyPresent && !groupsOk ? 'absent' : 'missing')),
-      ownershipIdentity: `${HARNESS}:hooks:registration`, target: hooksTarget });
-    if (!removingOp && scriptsOk && groupsOk) {
-      resources.push({ assetId: HOOKS_ASSET_ID, target: hooksTarget,
-        ownershipIdentity: `${HARNESS}:hooks:registration`, kind: 'hooks-json',
-        fingerprint: fingerprint(JSON.stringify(doc)), sourceVersion: 'registry-v1',
-        projection: { renderer: 'antigravity-hooks' } });
-      for (const identity of HOOK_SCRIPTS) {
-        resources.push({ assetId: HOOKS_ASSET_ID, target: scriptTargets[identity],
-          ownershipIdentity: `${HARNESS}:copy-tree:${HOOKS_ASSET_ID}:${identity}`,
-          kind: 'copy-tree-file', identity, fingerprint: fingerprints[identity],
-          sourceVersion: 'registry-v1', projection: { renderer: 'antigravity-hooks' } });
-      }
-    }
+  if (scope === 'project' && context.hooksOff !== true) {
+    const hooks = verifyHooks({ options, paths, context, fsImpl });
+    statuses.push(...hooks.statuses);
+    resources.push(...hooks.resources);
   }
 
   const conflicts = [...statuses.filter((s) => s.status === 'conflict').map((s) => s.reason ?? s.identity), ...mcp.conflicts];
@@ -627,5 +739,6 @@ function conflictsToStatuses(conflicts     , assetId     , statuses     ) {
 
 module.exports = {
   HARNESS, nativePaths: singleton.nativePaths, discover, render, plan, apply, remove, verify,
+  planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors,
   createAntigravityAdapter,
 };