@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/adapters/claude/index.js

@@ -29,6 +29,12 @@ const SETTINGS_RENDERER = 'claude-settings';
  *    its install destination is declared (paths.statuslineScript).
  */
 const SETTINGS_FILES = ['settings.json', 'keybindings.json'];
+/** Hook entries an earlier DoFlow wrote into settings.json and no longer ships. The update prunes their
+ * scripts, so a merge strips these entries from the live file (and a remove does too) instead of leaving a
+ * hook that points at a missing script. Written in the global form; `retiredHooks` rewrites the prefix for project scope. */
+const RETIRED_SETTINGS_HOOKS = {
+  PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: `${GLOBAL_HOOK_PREFIX}pre-bash-guard.sh` }] }],
+};
 
 function sha256(value     ) {
   return crypto.createHash('sha256').update(value).digest('hex');
@@ -183,6 +189,36 @@ 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 };
+  }
+  function retiredHooks(scope     ) {
+    const raw = JSON.stringify(RETIRED_SETTINGS_HOOKS);
+    return JSON.parse(scope === 'global' ? raw : raw.split(GLOBAL_HOOK_PREFIX).join(PROJECT_HOOK_PREFIX));
+  }
+  /** The managed settings text with the retired hook entries added, so a remove strips them as well. */
+  function withRetiredHooks(raw     , scope     ) {
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch { return raw; }
+    const hooks = { ...(parsed.hooks || {}) };
+    for (const [event, entries] of Object.entries     (retiredHooks(scope))) hooks[event] = [...(hooks[event] || []), ...entries];
+    return JSON.stringify({ ...parsed, 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 || []) {
@@ -228,7 +264,9 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
         // entries, so a drifted file is safe to process rather than a reason to refuse.
         changes.push({ assetId: asset.id, target, operation: 'remove', ownershipIdentity: `doflow:claude:settings:${fileName}`,
           ...settingsChangeExtras(fileName), fingerprint: prev.fingerprint,
-          managed: settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope),
+          managed: fileName === 'settings.json'
+            ? withRetiredHooks(settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope), scope)
+            : settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope),
           projection: { renderer: SETTINGS_RENDERER } });
       }
       if (previous.get(statuslineScriptName)) {
@@ -242,7 +280,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 +306,8 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
         const currentRaw = fs.readFileSync(target, 'utf8');
         let merged;
         try {
-          merged = mergeSettings(JSON.parse(currentRaw), JSON.parse(managedRaw));
+          const live = fileName === 'settings.json' ? withoutManagedHooks(JSON.parse(currentRaw), retiredHooks(scope)) : JSON.parse(currentRaw);
+          merged = mergeSettings(withoutManagedHooks(live, tiered.droppedHooks), JSON.parse(managedRaw));
         } catch {
           conflicts.push(`${fileName} is not valid JSON and cannot be merged`);
           continue;
@@ -358,7 +398,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 +414,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/hooks.js

@@ -17,6 +17,41 @@ const SUPPORTED_EVENTS = new Set([
   'UserPromptSubmit', 'SubagentStop', 'Stop', 'SessionStart', 'SubagentStart', 'SessionEnd',
 ]);
 
+// An earlier DoFlow wired a pre-bash-guard front door into hooks.json and deployed its script. Both
+// are gone from the shipped source; a merge drops the entry from the live file so an updated install
+// does not keep a hook that runs a script nothing refreshes, and the script goes with it. Only the
+// exact command DoFlow shipped is dropped: a user's own hook that happens to name a script of the same
+// file name stays.
+const RETIRED_HOOK_SCRIPT = 'pre-bash-guard.sh';
+const RETIRED_HOOK_COMMAND = 'bash "$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f "$root/.codex/hooks/pre-bash-guard.sh" ] && printf \'%s/.codex/hooks/pre-bash-guard.sh\' "$root" || printf \'%s/hooks/pre-bash-guard.sh\' "${CODEX_HOME:-$HOME/.codex}")"';
+
+function withoutRetiredHooks(hooks     )      {
+  const result                      = {};
+  for (const [event, groups] of Object.entries     (hooks || {})) {
+    if (!Array.isArray(groups)) { result[event] = groups; continue; }
+    const kept = groups.map((group     ) => (Array.isArray(group?.hooks)
+      ? { ...group, hooks: group.hooks.filter((handler     ) => handler?.command !== RETIRED_HOOK_COMMAND) }
+      : group)).filter((group     ) => !Array.isArray(group?.hooks) || group.hooks.length > 0);
+    if (kept.length) result[event] = kept;
+  }
+  return result;
+}
+
+/** Whether the retired front door is still on disk as DoFlow's own (it names the bridge call it was written with). */
+function ownsRetiredHookScript(destinationHooksDir        , fsImpl      = fs)          {
+  const target = path.join(destinationHooksDir, RETIRED_HOOK_SCRIPT);
+  try {
+    return fsImpl.lstatSync(target).isFile() && fsImpl.readFileSync(target, 'utf8').includes('doflow_bridge codex PreToolUse pre-bash-guard');
+  } catch { return false; }
+}
+
+/** Delete the retired front door when it is still DoFlow's own. */
+function removeRetiredHookScript(destinationHooksDir        , fsImpl      = fs, dryRun = false)         {
+  if (!ownsRetiredHookScript(destinationHooksDir, fsImpl)) return 0;
+  if (!dryRun) { try { fsImpl.unlinkSync(path.join(destinationHooksDir, RETIRED_HOOK_SCRIPT)); } catch { return 0; } }
+  return 1;
+}
+
 function validationError(errors          , message        )       { errors.push(message); }
 
 function validateHooksConfig(config     )                                                      {
@@ -148,7 +183,7 @@ function planCodexHooks({ config, sourceFile, sourceHooksDir, destinationContext
     try {
       const existing = JSON.parse(original);
       if (existing?.hooks && desired?.hooks) {
-        mergedDesired = { ...existing, ...desired, hooks: mergeHooks(existing.hooks, desired.hooks) };
+        mergedDesired = { ...existing, ...desired, hooks: mergeHooks(withoutRetiredHooks(existing.hooks), desired.hooks) };
       }
     } catch {
       // malformed existing will be flagged or left for schema validation
@@ -167,7 +202,7 @@ function planCodexHooks({ config, sourceFile, sourceHooksDir, destinationContext
     return { ok: false, status: 'conflict', destination, original, changes: [], commands,
       errors: scripts.edited.map((name        ) => `Codex hook script '${name}' was modified outside DoFlow`) };
   }
-  const scriptsOnly = !configChanged && scripts.stale.length > 0;
+  const scriptsOnly = !configChanged && (scripts.stale.length > 0 || ownsRetiredHookScript(destinationHooksDir, fsImpl));
   const changed = configChanged || scriptsOnly;
   // The scripts deployCodexHooks copies beside hooks.json, so a backup of this change holds them too.
   const companionTargets = [...new Set([
@@ -204,6 +239,7 @@ function deployCodexHooks(plan     , { dryRun = false, fsImpl = fs }
     fsImpl.copyFileSync(source, target);
     fsImpl.chmodSync(target, fsImpl.statSync(source).mode & 0o777);
   }
+  removeRetiredHookScript(plan.destinationHooksDir, fsImpl);
   return { ...plan, applied: true };
 }
 
@@ -220,7 +256,7 @@ function shippedHookScripts(scriptsDir     , fsImpl      = fs)           {
  * user edited or added stays. The directory goes only once it is empty. */
 function removeCodexHookScripts({ scriptsDir, destinationHooksDir }                                                        = {}, { dryRun = false, fsImpl = fs }                                     = {})                      {
   if (!destinationHooksDir || !fsImpl.existsSync(destinationHooksDir)) return { removed: 0 };
-  let removed = 0;
+  let removed = removeRetiredHookScript(destinationHooksDir, fsImpl, dryRun);
   for (const name of shippedHookScripts(scriptsDir, fsImpl)) {
     const target = path.join(destinationHooksDir, name);
     // lstat, not stat: a symlink (even to a file with the shipped bytes) is not DoFlow's copy.

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({
@@ -468,9 +503,22 @@ function createCodexAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
         hooks = { ...hooks, ok: false, status: 'conflict', changes: [], errors: ['Codex hooks.json was modified outside DoFlow'] };
       }
     }
+    if (hooks.ok) hooks = withStaleScriptReleases(hooks, scriptRows(neutralResources, context));
     return hooks;
   }
 
+  /** A script row for a name the source no longer ships (a retired front door) is released with the
+   * plan, so the ledger does not keep a row for a file the update deletes. The script itself goes by
+   * its bytes (deployCodexHooks), so this only drops the row. */
+  function withStaleScriptReleases(hooks     , rows       ) {
+    const shipped = new Set(hooks.scriptNames);
+    const releases = rows.filter((row     ) => !shipped.has(row.identity)).map((row     ) => ({ type: 'remove', assetId: row.assetId, identity: row.identity,
+      target: row.target, ownershipIdentity: row.ownershipIdentity, kind: row.kind, release: true }));
+    if (!releases.length) return hooks;
+    return { ...hooks, changes: [...hooks.changes, ...releases],
+      ...(hooks.status === 'unchanged' ? { status: 'change', scriptsOnly: true } : {}) };
+  }
+
   /** Agents/hooks share one removing-vs-planning fork: removal always owns both via the neutral
    * ledger's own records, regardless of what native input the caller provided this run. */
   /** A removal drops the rows of the hook scripts too. The scripts themselves go by their bytes

package/src/adapters/codex/native-projection.js

@@ -19,11 +19,15 @@ function normalizeNativeProjection(registry     , harness     , mcp       , cont
   if (!override || typeof override !== 'object' || Array.isArray(override)) throw new Error(`Projection override for '${harness.id}' must be an object`);
   const trusted = override.hooks?.trusted;
   if (trusted !== undefined && typeof trusted !== 'boolean') throw new Error(`Projection override '${harness.id}.hooks.trusted' must be boolean`);
+  // Hook tiers (maint-hooks): Codex outside `hooks.harnesses` gets no hooks.json, no hook scripts and no
+  // `features.hooks` entry; the lifecycle removes what an earlier install wrote through the remove path.
+  const hooksOff = harness.capabilities?.hooks?.tiered === true;
+  const configResources = (declaration.config?.resources || []).filter((resource     ) => !(hooksOff && resource.identity === 'features.hooks'));
   return Object.freeze({
-    configResources: Object.freeze((declaration.config?.resources || []).map((resource     ) => Object.freeze({ ...resource }))),
+    configResources: Object.freeze(configResources.map((resource     ) => Object.freeze({ ...resource }))),
     mcp: Object.freeze({ catalog: Object.freeze(mcp.map((server     ) => Object.freeze({ ...server }))), selected: Object.freeze(mcp.map((server     ) => server.id)) }),
     agents: Object.freeze({ sourceDir: resolveRegistrySource(registry, declaration.agents?.source, `${harness.id} agents`) }),
-    hooks: Object.freeze({
+    hooks: hooksOff ? Object.freeze({}) : Object.freeze({
       sourceFile: resolveRegistrySource(registry, declaration.hooks?.configSource, `${harness.id} hooks config`),
       sourceHooksDir: resolveRegistrySource(registry, declaration.hooks?.scriptsSource, `${harness.id} hooks scripts`),
       trusted: trusted ?? declaration.hooks?.trusted,

package/src/adapters/copilot/index.js

@@ -5,28 +5,37 @@
 // GitHub Copilot CLI adapter.
 //
 // Copilot has no single native root the way Claude's `.claude` is one — instructions, skills,
-// agents, and MCP each live under a different path, split further by scope. Skills and agents are
-// both trees materialised via the shared copy-tree engine in ../copy-tree.ts; the single instruction
-// pointer is a marker-merged section in a shared file, the same shape opencode/pi/gemini already use;
-// MCP servers are entries of one JSON map that DoFlow owns one at a time through ../mcp-entries.ts,
-// never touching an entry it does not own.
+// agents, and MCP each live under a different path, split further by scope. Skills, agents and the
+// core guidance rules are trees materialised via the shared copy-tree engine in ../copy-tree.ts; the
+// single instruction pointer is a marker-merged section in a shared file, the same shape
+// opencode/pi already use; MCP servers are entries of one JSON map that DoFlow owns one at a
+// time through ../mcp-entries.ts, never touching an entry it does not own.
 //
 // Native paths (see design.md §4's harness-native-surfaces table):
-//   instructions -> <projectRoot>/.github/copilot-instructions.md (project only — Copilot documents
-//                   no global instructions file, so global scope installs nothing for this asset)
+//   instructions -> <projectRoot>/.github/copilot-instructions.md, the pointer to .doflow/guidance
+//                   (project only — Copilot CLI also reads a user-level ~/.copilot/copilot-instructions.md,
+//                   but this adapter does not project a pointer there, so global scope writes none)
+//   rules        -> <projectRoot>/.github/instructions/ (project) / ~/.copilot/instructions/ (global):
+//                   the core set (DOFLOW_CORE.md and the files it imports) as `*.instructions.md`
+//                   with an `applyTo: '**'` header, under instructions/rules/ for the rule files;
+//                   the full guidance tree stays in .doflow/guidance
 //   skills       -> ~/.agents/skills (global) / <projectRoot>/.agents/skills (project)
 //   agents       -> ~/.copilot/agents (global) / <projectRoot>/.github/agents (project)
 //   mcp          -> ~/.copilot/mcp-config.json (global) / <projectRoot>/.mcp.json (project)
+//   hooks        -> <projectRoot>/.github/hooks (project) / ~/.copilot/hooks (global): doflow.json plus the
+//                   doflow-*.sh front doors; the shared bridge tree lands in <root>/.doflow/shared/hooks
 //
 // Evidence: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot,
 // https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills,
 // https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli,
-// https://docs.github.com/en/copilot/reference/custom-agents-configuration
+// https://docs.github.com/en/copilot/reference/custom-agents-configuration,
+// https://docs.github.com/en/copilot/reference/hooks-reference
 const fs = require('node:fs');
 const path = require('node:path');
 
 const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
 const { planTree, applyTree, removeTree, verifyTree, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor, resolveTransform } = require('../copy-tree.js');
+const { renderGuidancePointer } = require('../guidance-pointer.js');
 const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 
@@ -49,18 +58,31 @@ const LEGACY_MCP_REGISTRATION = `${HARNESS}:mcp:registration`;
  *     list per https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills.
  *   - `agentsConfigDir` is genuinely asymmetric: `~/.copilot` globally, `.github` at project scope,
  *     because that is where Copilot's own custom-agents documentation places each.
- *   - `instruction` is project-only: Copilot documents no global instructions file, so no user-scope
- *     rule is declared and it resolves to null rather than inventing a path with no reader.
+ *   - `instruction` is project-only: Copilot CLI reads a user-level ~/.copilot/copilot-instructions.md,
+ *     but this adapter does not project a pointer there, so no user-scope rule is declared and it
+ *     resolves to null.
  * createCopilotAdapter({ declaredPaths }) is the injection point buildAdapterRegistry() uses;
  * module-level exports delegate to a default-configured instance so direct callers keep their
  * historical shape.
  */
-function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } = {}) {
+function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env = process.env }      = {}) {
   // Parity note: Copilot's historical nativePaths() derived even its user-scope root from scopeRoot
   // (the CLI passes $HOME there for -g installs), never from a separate homeDir argument — so the
   // resolver is fed no homeDir and "root" keeps resolving exactly as before.
   function nativePaths({ scope, scopeRoot }      = {}) {
-    return resolveHarnessPaths(declaredPaths, { scope, scopeRoot });
+    const paths = resolveHarnessPaths(declaredPaths, { scope, scopeRoot });
+    // Copilot CLI loads user hooks from $COPILOT_HOME/hooks when COPILOT_HOME is set (hooks reference,
+    // "Hook locations"), and DoFlow's generated commands read it too. The path schema has no
+    // environment base (src/helper/harness-paths.js), so the override stays here, as Pi's agent dir
+    // does; skills, agents, instructions and MCP keep their declared locations.
+    if ((scope === 'user' || scope === 'global') && copilotHomeOverride()) paths.hooksConfigDir = copilotHomeOverride();
+    return paths;
+  }
+
+  /** $COPILOT_HOME when it is an absolute path, else null (a relative value would move with the cwd). */
+  function copilotHomeOverride() {
+    const home = typeof env.COPILOT_HOME === 'string' ? env.COPILOT_HOME.trim() : '';
+    return path.isAbsolute(home) ? path.resolve(home) : null;
   }
 
   /** Discovery keeps the MCP files as plan read them (`mcpSnapshot`), which verify compares against,
@@ -81,7 +103,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   }
 
   /** Replace only the span between DoFlow's markers. A copilot-instructions.md that exists with no
-   * DoFlow section is refused rather than appended to — the same policy opencode/pi/gemini apply to
+   * DoFlow section is refused rather than appended to — the same policy opencode/pi apply to
    * their own shared instruction files, and for the same reason: where DoFlow's content belongs in a
    * file it doesn't fully own is a decision for the file's owner, not a guess for the installer. Add
    * an empty marker pair to opt in. */
@@ -108,9 +130,9 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   }
 
   /** Plan the single instructions change (or none). Global scope always yields no change and no
-   * conflict — Copilot documents no global instructions file, so there is nothing to skip *to*,
-   * mirroring how other adapters skip a capability with no native equivalent for a given scope. */
-  function planInstructionsChange({ assets, found, context, removing, fsImpl }     ) {
+   * conflict — the user-level ~/.copilot/copilot-instructions.md is not projected, so there is no
+   * global target, the same way other adapters skip a capability they do not project at a scope. */
+  function planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, fsImpl }     ) {
     if (!found.paths.instruction) return { changes: [], conflicts: [] };
     // The marker-managed instruction file is one specific asset: exclude tree-projected rule
     // assets (copilot-rule-instructions), whose `source` is a directory, not a file.
@@ -118,7 +140,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     if (!guidance) return { changes: [], conflicts: [] };
     const outcome = removing
       ? { ok: true, operation: 'remove', content: strippedInstruction(found.instruction) }
-      : managedInstruction(found.instruction, render({ content: fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8') }));
+      : managedInstruction(found.instruction, render({ content: renderGuidancePointer(fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8'), { scope, scopeRoot }) }));
     if (!outcome.ok) return { changes: [], conflicts: [outcome.conflict] };
     if (outcome.operation === 'none' || outcome.content === null) return { changes: [], conflicts: [] };
     return {
@@ -138,7 +160,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
    * (https://docs.github.com/en/copilot/reference/custom-agents-configuration) requires the
    * `.agent.md` extension, while `core/shared/agent-specs/*.md` — already `name`/`description`
    * YAML-frontmatter files, the same shape `.agent.md` expects — carries a plain `.md` extension.
-   * This is the same class of shape mismatch Gemini/Antigravity's `dir-per-file:agent.md` layout in
+   * This is the same class of shape mismatch Antigravity's `dir-per-file:agent.md` layout in
    * copy-tree.ts already solves for a directory-per-agent requirement; here the mismatch is only the
    * extension, so a flat rename is enough and no directory restructuring is needed. Declared as a
    * function (rather than a name registered in copy-tree.ts's LAYOUTS) because it is specific to this
@@ -160,7 +182,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
       const destDir = copyTreeDestDir(destRoot, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Copilot');
       const previousResources = ledgerFileResources(ledger?.resources, HARNESS, asset.id);
-      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: layout || asset.layout, transform: asset.transform, keepModified: !removing,
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: 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
@@ -214,7 +236,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     for (const asset of treeAssetsFor(assets, renderer)) {
       const destDir = copyTreeDestDir(destRoot, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Copilot');
-      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: layout || asset.layout, transform: asset.transform, plannedWrites: context?.plannedWrites });
+      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: layout || asset.layout, transform: asset.transform, select: asset.select, plannedWrites: context?.plannedWrites });
       conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({
@@ -268,7 +290,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   /** Copilot's MCP entry changes have no asset of their own in core/registry/assets.json (they are a
    * registration side-effect of the selected MCP servers, not a projected asset), so they piggyback
    * on a real asset id already routed to this harness — the same "pseudo-component" technique
-   * src/adapters/gemini/index.js#hooksAssetId and src/adapters/kiro/index.js#pseudoAssetId use. The
+   * src/adapters/kiro/index.js#pseudoAssetId uses. The
    * lifecycle layer validates every change's assetId against the harness's actual asset list, so an
    * invented id like a literal 'copilot.mcp' string is rejected as unknown. */
   function pseudoAssetId(assets     ) {
@@ -283,7 +305,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     const conflicts = [];
     const removing = context.operation === 'remove';
 
-    const instructions = planInstructionsChange({ assets, found, context, removing, fsImpl });
+    const instructions = planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, fsImpl });
     changes.push(...instructions.changes);
     conflicts.push(...instructions.conflicts);
 
@@ -299,13 +321,21 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     changes.push(...rules.changes);
     conflicts.push(...rules.conflicts);
 
+    // Hooks: DoFlow's own .github/hooks/doflow.json and doflow-*.sh front doors (renderer
+    // copilot-hooks, a flat tree beside any hook files the user keeps there), and the shared bridge
+    // tree under ../.doflow, which hooks.shared projects through the plain copy-tree renderer above.
+    // Outside `hooks.harnesses` the registry marks the capability unavailable and selects neither.
+    const hooks = planTreeAssets({ assets, renderer: 'copilot-hooks', scopeRoot, destRoot: found.paths.hooksConfigDir, layout: null, context, ledger, removing, fsImpl });
+    changes.push(...hooks.changes);
+    conflicts.push(...hooks.conflicts);
+
     const mcpPlan = planMcpEntries({
       ...mcpEntriesInput({ paths: found.paths, mcp, mcpAdoptable, ledger, assets }), files: found.mcpSnapshot, removing,
     });
     changes.push(...legacyRegistrationReleases(ledger), ...mcpPlan.changes);
     conflicts.push(...mcpPlan.conflicts);
 
-    return { changes, conflicts, notices: [...skills.notices, ...agents.notices, ...rules.notices, ...mcpPlan.notices], paths: found.paths };
+    return { changes, conflicts, notices: [...skills.notices, ...agents.notices, ...rules.notices, ...hooks.notices, ...mcpPlan.notices], paths: found.paths };
   }
 
   function writeChange(change     , fsImpl     ) {
@@ -380,6 +410,11 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     statuses.push(...rules.statuses);
     conflicts.push(...rules.conflicts);
 
+    const hooks = verifyTreeAssets({ assets, renderer: 'copilot-hooks', destRoot: found.paths.hooksConfigDir, layout: null, context, fsImpl });
+    resources.push(...hooks.resources);
+    statuses.push(...hooks.statuses);
+    conflicts.push(...hooks.conflicts);
+
     const mcpResult = verifyMcpEntries({
       ...mcpEntriesInput({ paths: found.paths, mcp, mcpAdoptable, ledger, assets }), files: found.mcpSnapshot,
       snapshot: discovery?.mcpSnapshot ?? found.mcpSnapshot, removing: (operation ?? context.operation) === 'remove',