@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

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);

package/src/adapters/claude/index.js

@@ -183,6 +183,24 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
   function settingsContent(fileName     , raw     , scope     ) {
     return fileName === 'settings.json' && scope !== 'global' ? raw.split(GLOBAL_HOOK_PREFIX).join(PROJECT_HOOK_PREFIX) : raw;
   }
+  /** Hook tiers (maint-hooks): with Claude outside `hooks.harnesses` the managed settings carry no
+   * `hooks` block. Returns the managed text to write and the hooks it left out, which a merge strips
+   * from the live file so an earlier install's entries do not stay behind. */
+  function tieredSettings(fileName     , raw     , context     ) {
+    if (fileName !== 'settings.json' || context?.hooksOff !== true) return { raw, droppedHooks: null };
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch { return { raw, droppedHooks: null }; }
+    if (!parsed || parsed.hooks === undefined) return { raw, droppedHooks: null };
+    const { hooks, ...rest } = parsed;
+    return { raw: serializeSettings(rest), droppedHooks: hooks };
+  }
+  /** The live settings without DoFlow's own entries of `hooks`; every other key is left alone. */
+  function withoutManagedHooks(current     , hooks     ) {
+    if (!hooks || !current || typeof current !== 'object' || current.hooks === undefined) return current;
+    const { hooks: liveHooks, ...rest } = current;
+    const stripped = stripManagedSettings({ hooks: liveHooks, _: true }, { hooks });
+    return stripped?.hooks ? { ...rest, hooks: stripped.hooks } : rest;
+  }
   function settingsLedgerResources(ledger     , assetId     ) {
     const byFile = new Map();
     for (const resource of ledger?.resources || []) {
@@ -242,7 +260,8 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
     for (const fileName of SETTINGS_FILES) {
       const sourceAbs = path.join(sourceDir, fileName);
       if (!fs.existsSync(sourceAbs)) continue;
-      let managedRaw = settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope);
+      const tiered = tieredSettings(fileName, settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope), context);
+      let managedRaw = tiered.raw;
       if (fileName === 'settings.json' && context.statusline && !removing) {
         // --statusline: point Claude Code's statusLine key at the projected script. It rides the
         // same managed settings write as everything else this asset owns — one serialization, one
@@ -267,7 +286,7 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
         const currentRaw = fs.readFileSync(target, 'utf8');
         let merged;
         try {
-          merged = mergeSettings(JSON.parse(currentRaw), JSON.parse(managedRaw));
+          merged = mergeSettings(withoutManagedHooks(JSON.parse(currentRaw), tiered.droppedHooks), JSON.parse(managedRaw));
         } catch {
           conflicts.push(`${fileName} is not valid JSON and cannot be merged`);
           continue;
@@ -358,7 +377,8 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
     for (const fileName of SETTINGS_FILES) {
       const sourceAbs = path.join(sourceDir, fileName);
       if (!fs.existsSync(sourceAbs)) continue;
-      const fingerprint = sha256(settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope));
+      const sourceText = tieredSettings(fileName, settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope), context).raw;
+      const fingerprint = sha256(sourceText);
       const target = settingsTarget(fileName, paths);
       // 'absent' (not 'missing') matches the same convention the instructions asset already uses
       // for "no file here" — 'missing' is reserved by the lifecycle layer's removal reconciliation
@@ -373,7 +393,7 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
       let managed;
       try {
         current = JSON.parse(fs.readFileSync(target, 'utf8'));
-        managed = JSON.parse(settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope));
+        managed = JSON.parse(sourceText);
       } catch {
         conflicts.push(`${fileName} is not valid JSON`);
         statuses.push({ assetId: asset.id, capability: 'settings', status: 'conflict', target });

package/src/adapters/codex/agents.js

@@ -9,18 +9,12 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { atomicWrite } = require('./config.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
 
 const AGENT_DIRECTORY = 'agents';
 const AGENT_KIND = 'custom-agent';
 const REQUIRED_FIELDS = ['name', 'description', 'developer_instructions'];
-const READ_ONLY_ROLES = new Set([
-  'backend-architect', 'deep-research-agent', 'devops-architect', 'frontend-architect',
-  'quality-engineer', 'requirements-analyst', 'root-cause-analyst', 'security-engineer',
-  'system-architect', 'technical-writer',
-]);
-const IMPLEMENTATION_ROLES = new Set([
-  'performance-engineer', 'pm-agent', 'python-expert', 'refactoring-expert',
-]);
+const SPEC_DIRECTORY = path.join(REPO_ROOT, 'core', 'shared', 'agent-specs');
 const ALLOWED_FIELDS = new Set([...REQUIRED_FIELDS, 'sandbox_mode']);
 
 function fingerprint(content        )         {
@@ -85,7 +79,21 @@ function parseAgentToml(source     , { fileName }                        = {})
   return values;
 }
 
-function validateAgentContract(source     , { fileName }                        = {})      {
+/** `access` of every shared agent spec by name (118 IC-002). A TOML whose name has no spec is the
+ * user's own agent and is not tied to any access. */
+function specAccess(specDir         = SPEC_DIRECTORY, fsImpl      = fs)                      {
+  const access = new Map                ();
+  if (!fsImpl.existsSync(specDir)) return access;
+  for (const entry of fsImpl.readdirSync(specDir)) {
+    if (!entry.endsWith('.md')) continue;
+    const frontmatter = fsImpl.readFileSync(path.join(specDir, entry), 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const value = frontmatter?.[1].match(/^access:\s*(\S+)\s*$/m)?.[1];
+    if (value) access.set(entry.slice(0, -'.md'.length), value);
+  }
+  return access;
+}
+
+function validateAgentContract(source     , { fileName, access = specAccess() }                                                      = {})      {
   const agent = parseAgentToml(source, { fileName });
   for (const field of REQUIRED_FIELDS) {
     if (typeof agent[field] !== 'string' || !agent[field].trim()) throw new Error(`Agent is missing required '${field}'`);
@@ -97,11 +105,12 @@ function validateAgentContract(source     , { fileName }
   if (agent.sandbox_mode !== undefined && !['read-only', 'workspace-write', 'danger-full-access'].includes(agent.sandbox_mode)) {
     throw new Error(`Agent '${agent.name}' has an unsupported sandbox_mode`);
   }
-  if (READ_ONLY_ROLES.has(agent.name) && agent.sandbox_mode !== 'read-only') {
-    throw new Error(`Analysis role '${agent.name}' must use sandbox_mode = "read-only"`);
+  const specAccessValue = access.get(agent.name);
+  if (specAccessValue === 'read-only' && agent.sandbox_mode !== 'read-only') {
+    throw new Error(`Agent '${agent.name}' has access: read-only and must use sandbox_mode = "read-only"`);
   }
-  if (IMPLEMENTATION_ROLES.has(agent.name) && agent.sandbox_mode !== undefined) {
-    throw new Error(`Implementation role '${agent.name}' must inherit its parent sandbox`);
+  if (specAccessValue === 'write' && agent.sandbox_mode !== undefined) {
+    throw new Error(`Agent '${agent.name}' has access: write and must inherit its parent sandbox`);
   }
   return Object.freeze({ ...agent, fileName: filenameFor(agent.name) });
 }
@@ -134,12 +143,13 @@ function discoverCodexAgents(sourceDir     , fsImpl      = fs)        {
   const directory = path.resolve(sourceDir);
   if (!fsImpl.existsSync(directory)) throw new Error(`Codex agent source directory does not exist: ${sourceDir}`);
   const agents        = [];
+  const access = specAccess();
   for (const entry of fsImpl.readdirSync(directory, { withFileTypes: true }).sort((a     , b     ) => a.name.localeCompare(b.name))) {
     if (!entry.name.endsWith('.toml')) continue;
     if (!entry.isFile()) throw new Error(`Codex agent source '${entry.name}' must be a regular file`);
     const name = expectedName(entry.name);
     const source = fsImpl.readFileSync(path.join(directory, entry.name), 'utf8');
-    agents.push({ ...validateAgentContract(source, { fileName: entry.name }), name, source, fingerprint: fingerprint(source) });
+    agents.push({ ...validateAgentContract(source, { fileName: entry.name, access }), name, source, fingerprint: fingerprint(source) });
   }
   if (!agents.length) throw new Error(`No Codex agent TOML contracts found in ${sourceDir}`);
   return agents;
@@ -202,7 +212,7 @@ function reconcileCodexAgents(options     )      {
 }
 
 module.exports = {
-  AGENT_DIRECTORY, AGENT_KIND, READ_ONLY_ROLES, IMPLEMENTATION_ROLES, fingerprint,
+  AGENT_DIRECTORY, AGENT_KIND, fingerprint, specAccess,
   parseAgentToml, validateAgentContract, agentDirectory, destinationFor, discoverCodexAgents,
   planCodexAgents, applyCodexAgents, reconcileCodexAgents,
 };

package/src/adapters/codex/index.js

@@ -13,8 +13,9 @@ const { configPath, fingerprint: configFingerprint, parseToml, planCodexConfig,
 const { renderServer, planCodexMcp, applyCodexMcp, ownedCodexMcpIds, userDefinedCodexMcpIds, serverTableText } = require('./mcp.js');
 const { agentDirectory, discoverCodexAgents, planCodexAgents, applyCodexAgents } = require('./agents.js');
 const { planCodexHooks, deployCodexHooks, removeCodexHookScripts, scriptFingerprint } = require('./hooks.js');
-const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices } = require('../copy-tree.js');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, resolveTransform } = require('../copy-tree.js');
 const { mergeMarkedSection, removeMarkedSection, MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
+const { renderGuidancePointer } = require('../guidance-pointer.js');
 const { nativeMcpCatalog } = require('../../registry/index.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 
@@ -275,6 +276,26 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
   }
   function sha256Text(text     ) { return crypto.createHash('sha256').update(text).digest('hex'); }
 
+  function instructionBody(content     ) {
+    if (typeof content !== 'string') return null;
+    const start = content.indexOf(MARKER_START);
+    if (start === -1) return null;
+    const bodyStart = start + MARKER_START.length;
+    const end = content.indexOf(MARKER_END, bodyStart);
+    if (end === -1 || content.indexOf(MARKER_START, end + MARKER_END.length) !== -1) return null;
+    let from = bodyStart;
+    if (content[from] === '\n') from += 1;
+    let to = end;
+    if (to > from && content[to - 1] === '\n') to -= 1;
+    return content.slice(from, to);
+  }
+
+  function renderedInstructionContent(asset     , context     , repoRoot     ) {
+    const source = sourceDirFor(asset, repoRoot);
+    const content = fs.readFileSync(source, 'utf8');
+    return renderGuidancePointer(content, { scope: context.scope, scopeRoot: context.paths.root }).replace(/\s+$/, '');
+  }
+
   function planInstructionsAsset({ assets, context, removing, repoRoot, claimedElsewhere = () => false }     ) {
     const asset = instructionsAsset(assets);
     const changes        = [];
@@ -298,18 +319,19 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       return { changes, conflicts };
     }
     const source = sourceDirFor(asset, repoRoot);
-    if (!mergeMarkedSection(source, target, { dryRun: true }).changed) return { changes, conflicts };
-    const content = fs.readFileSync(source, 'utf8').replace(/\s+$/, '');
+    const content = renderedInstructionContent(asset, context, repoRoot);
+    const merged = mergeMarkedSection(source, target, { dryRun: true, content });
+    if (!merged.changed) return { changes, conflicts };
     changes.push({ assetId: asset.id, target, source, operation: fs.existsSync(target) ? 'update' : 'create',
       ownershipIdentity: 'doflow:codex:instructions:managed-section', kind: 'instructions-section', identity: 'AGENTS.md',
-      afterFingerprint: sha256Text(content), sourceVersion: 'registry-v1', projection: { renderer: 'codex-agents' } });
+      afterFingerprint: sha256Text(content), renderedContent: content, sourceVersion: 'registry-v1', projection: { renderer: 'codex-agents' } });
     return { changes, conflicts };
   }
 
   function applyInstructionsAsset(changes     ) {
     for (const change of changes) {
       if (change.projection?.renderer !== 'codex-agents' || change.operation === 'remove') continue;
-      mergeMarkedSection(change.source, change.target);
+      mergeMarkedSection(change.source, change.target, { content: change.renderedContent });
     }
   }
 
@@ -325,11 +347,14 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     if (!asset) return { statuses, resources };
     const target = instructionsPath(context);
     const existing = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
-    const managed = existing !== null && existing.includes(MARKER_START) && existing.includes(MARKER_END);
-    statuses.push({ assetId: asset.id, capability: asset.capability, status: managed ? 'managed' : 'absent', target });
+    const expected = renderedInstructionContent(asset, context, repoRoot);
+    const actual = instructionBody(existing);
+    const hasMarkers = existing !== null && existing.includes(MARKER_START) && existing.includes(MARKER_END);
+    const managed = actual !== null && actual === expected;
+    statuses.push({ assetId: asset.id, capability: asset.capability, status: managed ? 'managed' : (hasMarkers ? 'missing' : 'absent'), target });
     if (managed) {
       resources.push({ assetId: asset.id, target, ownershipIdentity: 'doflow:codex:instructions:managed-section',
-        kind: 'instructions-section', identity: 'AGENTS.md', fingerprint: sha256Text(existing), sourceVersion: 'registry-v1',
+        kind: 'instructions-section', identity: 'AGENTS.md', fingerprint: sha256Text(expected), sourceVersion: 'registry-v1',
         projection: { renderer: 'codex-agents' } });
     }
     return { statuses, resources };
@@ -344,7 +369,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
       const destDir = copyTreeDestDir(codexConfigDir(context), asset);
       const sourceDir = sourceDirFor(asset, repoRoot);
       const previousResources = ledgerFileResources(neutralResources, HARNESS, asset.id);
-      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(neutralResources, HARNESS), operation: removing ? 'remove' : 'apply', layout: asset.layout, keepModified: !removing,
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(neutralResources, HARNESS), operation: removing ? 'remove' : 'apply', layout: asset.layout, transform: asset.transform, keepModified: !removing,
         // `force` is the CLI's --force reaching the one conflict class a plan can actually
         // downgrade: a ledger-owned destination whose bytes were edited underneath us. With force,
         // that is drift to heal rather than a refusal — exactly what `doflow reconcile` (always
@@ -362,6 +387,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
           ownershipIdentity: `doflow:codex:copy-tree:${asset.id}:${change.relPath}`,
           kind: 'copy-tree-file', identity: change.relPath,
           afterFingerprint: change.fingerprint, fingerprint: change.fingerprint, sourceVersion: sourceVersion ?? 'unknown',
+          transformName: asset.transform || null,
           ...(change.kept ? { retained: true, retainedFor: [] } : {}),
           projection: { renderer: 'copy-tree' },
         });
@@ -371,9 +397,18 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
   }
 
   function applyCopyTreeAssets(changes     ) {
-    const treeChanges = changes.filter((change     ) => change.projection?.renderer === 'copy-tree' && change.operation !== 'remove')
-      .map((change     ) => ({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint }));
-    return applyTree({ changes: treeChanges }).applied;
+    let applied = 0;
+    const grouped = new Map();
+    for (const change of changes) {
+      if (change.projection?.renderer !== 'copy-tree' || change.operation === 'remove') continue;
+      const key = change.transformName || null;
+      if (!grouped.has(key)) grouped.set(key, []);
+      grouped.get(key).push({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint });
+    }
+    for (const [transformName, treeChanges] of grouped) {
+      applied += applyTree({ changes: treeChanges, transform: resolveTransform(transformName) }).applied;
+    }
+    return applied;
   }
 
   function removeCopyTreeAssets(changes     ) {
@@ -389,7 +424,7 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     for (const asset of copyTreeAssets(assets)) {
       const destDir = copyTreeDestDir(codexConfigDir(context), asset);
       const sourceDir = sourceDirFor(asset, repoRoot);
-      const result = verifyTree({ sourceDir, destDir, layout: asset.layout, plannedWrites });
+      const result = verifyTree({ sourceDir, destDir, layout: asset.layout, transform: asset.transform, plannedWrites });
       conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({