@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/core/worker-evidence/codex/2026-10-24-cli-check.json

@@ -0,0 +1,126 @@
+{
+  "binary": "codex",
+  "checks": [
+    {
+      "argv": [
+        "exec",
+        "--help"
+      ],
+      "establishes": [
+        "runnableProbe",
+        "oneShot"
+      ],
+      "exit": 0,
+      "expect": [
+        "^Usage: codex exec \\[OPTIONS\\] \\[PROMPT\\]",
+        "instructions are read from stdin"
+      ],
+      "id": "exec-one-shot",
+      "matched": [
+        "Usage: codex exec [OPTIONS] [PROMPT]",
+        "          instructions are read from stdin. If stdin is piped and a prompt is also provided, stdin"
+      ],
+      "result": "pass"
+    },
+    {
+      "argv": [
+        "exec",
+        "--help"
+      ],
+      "establishes": [
+        "structuredOutput"
+      ],
+      "exit": 0,
+      "expect": [
+        "^\\s+--json$",
+        "Print events to stdout as JSONL",
+        "-o, --output-last-message"
+      ],
+      "id": "exec-json",
+      "matched": [
+        "      --json",
+        "          Print events to stdout as JSONL",
+        "  -o, --output-last-message <FILE>"
+      ],
+      "result": "pass"
+    },
+    {
+      "argv": [
+        "exec",
+        "--help"
+      ],
+      "establishes": [
+        "readOnly",
+        "isolatedEdit"
+      ],
+      "exit": 0,
+      "expect": [
+        "-s, --sandbox <SANDBOX_MODE>",
+        "read-only, workspace-write"
+      ],
+      "id": "exec-sandbox",
+      "matched": [
+        "  -s, --sandbox <SANDBOX_MODE>",
+        "          [possible values: read-only, workspace-write, danger-full-access]"
+      ],
+      "result": "pass"
+    },
+    {
+      "argv": [
+        "features",
+        "list",
+        "--disable",
+        "multi_agent",
+        "--disable",
+        "multi_agent_v2"
+      ],
+      "establishes": [
+        "spawnDenial"
+      ],
+      "exit": 0,
+      "expect": [
+        "^multi_agent\\s+\\S+\\s+false$",
+        "^multi_agent_v2\\s+\\S+\\s+false$"
+      ],
+      "id": "spawn-denial",
+      "matched": [
+        "multi_agent                              stable             false",
+        "multi_agent_v2                           stable             false"
+      ],
+      "result": "pass"
+    },
+    {
+      "argv": [
+        "exec",
+        "--help"
+      ],
+      "establishes": [
+        "model"
+      ],
+      "exit": 0,
+      "expect": [
+        "^\\s+-m, --model <MODEL>$"
+      ],
+      "id": "exec-model",
+      "matched": [
+        "  -m, --model <MODEL>"
+      ],
+      "result": "pass"
+    }
+  ],
+  "cliVersion": "codex-cli 0.164.0",
+  "establishes": [
+    "isolatedEdit",
+    "model",
+    "oneShot",
+    "readOnly",
+    "runnableProbe",
+    "spawnDenial",
+    "structuredOutput"
+  ],
+  "harness": "codex",
+  "kind": "cli-check",
+  "recordedAt": "2026-10-24T10:45:22.229Z",
+  "run": null,
+  "schema": "doflow-worker-evidence-v1"
+}

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.5",
+  "version": "2.0.1",
   "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 });
@@ -212,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 };
 }
@@ -279,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
@@ -297,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' },
       });
@@ -315,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;
@@ -330,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.
@@ -432,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];
@@ -447,7 +508,7 @@ function plan(options      = {}, impl      = {}) {
     conflicts,
     prerequisites: [],
     requiredNativeResources: changes,
-    notices: [...trees.notices, ...mcp.notices],
+    notices: [...instructions.notices, ...trees.notices, ...mcp.notices],
   };
 }
 
@@ -485,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
@@ -594,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 } : {}),
+      }));
     }
   }
 
@@ -619,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({
@@ -642,7 +719,7 @@ function verify(options      = {}, impl      = {}) {
   resources.push(...mcp.resources);
 
   // Hooks projection (project scope): the shims' bytes and the registered groups.
-  if (scope === 'project') {
+  if (scope === 'project' && context.hooksOff !== true) {
     const hooks = verifyHooks({ options, paths, context, fsImpl });
     statuses.push(...hooks.statuses);
     resources.push(...hooks.resources);