@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/adapters/copy-tree.js

@@ -5,12 +5,14 @@
 // Shared copy-tree engine — the generic "own a tree of files" implementation every asset
 // declaring `renderer: "copy-tree"` in core/registry/assets.json needs. Codex's adapter already
 // proved this per-file fingerprint/conflict model for agents and hooks (ownedRemovalPlan,
-// nativeManagedResources); this module generalizes it so Claude, Gemini, and Codex's own
+// nativeManagedResources); this module generalizes it so every adapter's
 // tree-shaped assets (skills, rules, agent-specs, templates, scripts, modes, references) share
-// one implementation instead of three adapter-specific copies.
+// one implementation instead of adapter-specific copies.
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { guidanceManifest } = require('./guidance-manifest.js');
+const { REPO_ROOT } = require('../helper/repo-root.js');
 
 function sha256(buf     )         {
   return crypto.createHash('sha256').update(buf).digest('hex');
@@ -39,7 +41,7 @@ const LAYOUTS                                                = {
     const ext = path.extname(sourceRel);
     return path.join(sourceRel.slice(0, sourceRel.length - ext.length), `agent${ext || '.md'}`);
   },
-  /** `RULE_01_SAFETY.md` -> `RULE_01_SAFETY.instructions.md` — GitHub's path-specific
+  /** `RULES.md` -> `RULES.instructions.md` — GitHub's path-specific
    * instructions are discovered by their `.instructions.md` suffix. */
   'instructions-md': (sourceRel        ) => {
     const ext = path.extname(sourceRel);
@@ -59,6 +61,8 @@ const LAYOUTS                                                = {
     const ext = path.extname(sourceRel);
     return `${sourceRel.slice(0, sourceRel.length - ext.length)}.json`;
   },
+  /** `rules/RULES.md` -> `RULES.md` for flat rule directories. */
+  flat: (sourceRel        ) => path.basename(sourceRel),
 };
 
 /** Resolve a declared layout name to its mapper. Unknown names fail loudly rather than silently
@@ -70,6 +74,25 @@ function resolveLayout(name     )                                {
   return layout;
 }
 
+/** Source-file selectors for projections that intentionally materialize only part of a tree. */
+const SELECTORS                                                                  = {
+  // A dangling import that is not generated would install a core set missing a file the entry file
+  // names, silently; the selector fails instead (MCP_INDEX.md is generated and exempt) (107-B C-4).
+  'guidance-manifest': (sourceDir        , fsImpl     ) => {
+    const { files, dangling } = guidanceManifest(sourceDir, fsImpl);
+    if (dangling.length) throw new Error(`guidance-manifest: DOFLOW_CORE.md imports files that do not exist under ${sourceDir}: ${dangling.join(', ')}`);
+    return new Set(files);
+  },
+};
+
+/** Resolve a declared selector name, or return null when a projection mirrors the whole tree. */
+function resolveSelect(name     )                                                           {
+  if (name == null) return null;
+  const selector = SELECTORS[name];
+  if (!selector) throw new Error(`Unknown copy-tree select '${name}' (known: ${Object.keys(SELECTORS).join(', ')})`);
+  return selector;
+}
+
 /** Destination content transforms. Where a harness reads a supported but different file FORMAT
  * than the shared source authors (Copilot's path-specific instructions require an `applyTo`
  * frontmatter header; OpenCode's markdown agents want their own frontmatter vocabulary), the
@@ -87,10 +110,32 @@ const TRANSFORMS                                                           = {
     void sourceRel;
     return Buffer.from(`---\napplyTo: '**'\n---\n\n${stripFrontmatter(content.toString('utf8'))}`);
   },
-  /** Shared agent spec frontmatter -> only the keys Gemini CLI's subagent schema accepts */
-  'gemini-agents': (sourceRel        , content     ) => {
+  /** `<rule>.md` -> the same body under Antigravity's `trigger: always_on` front-matter. Antigravity
+   * silently discards a `.agents/rules/*.md` file without valid front-matter, so the shared core
+   * files (which carry none) are loaded only through this header (107-B review C-2). */
+  'antigravity-always-on-rules': (sourceRel        , content     ) => {
+    void sourceRel;
+    return Buffer.from(`---\ntrigger: always_on\n---\n\n${stripFrontmatter(content.toString('utf8'))}`);
+  },
+  /** Shared agent spec -> the same file without `access`, plus Claude's read-only limit keys (118 IC-005) */
+  'claude-agents': (sourceRel        , content     ) => {
     void sourceRel;
-    return Buffer.from(filterGeminiAgentFrontmatter(content.toString('utf8')));
+    return Buffer.from(applyAgentLimits(content.toString('utf8'), 'claude'));
+  },
+  /** Shared agent spec -> the same file without `access`; Codex's limit is `unenforced` (the TOML carries it), so no keys are added */
+  'codex-agents': (sourceRel        , content     ) => {
+    void sourceRel;
+    return Buffer.from(applyAgentLimits(content.toString('utf8'), 'codex'));
+  },
+  /** Shared agent spec -> the same file without `access`, plus Copilot's read-only limit keys (118 IC-005) */
+  'copilot-agents': (sourceRel        , content     ) => {
+    void sourceRel;
+    return Buffer.from(applyAgentLimits(content.toString('utf8'), 'copilot'));
+  },
+  /** Shared agent spec -> the same file without `access`; Antigravity's limit is `unenforced`, so no keys are added */
+  'antigravity-agents': (sourceRel        , content     ) => {
+    void sourceRel;
+    return Buffer.from(applyAgentLimits(content.toString('utf8'), 'antigravity'));
   },
   /** Shared agent spec frontmatter -> OpenCode's markdown-agent vocabulary */
   'opencode-agents': (sourceRel        , content     ) => {
@@ -102,8 +147,80 @@ const TRANSFORMS                                                           = {
     void sourceRel;
     return Buffer.from(renderKiroAgent(content.toString('utf8')));
   },
+  /** Hook tiers (maint-hooks): the same Kiro agent with no `hooks`, for Kiro outside `hooks.harnesses`. */
+  'kiro-agents-content': (sourceRel        , content     ) => {
+    void sourceRel;
+    return Buffer.from(renderKiroAgent(content.toString('utf8'), { hooks: false }));
+  },
+  /** Hook tiers: an authored Kiro agent JSON (core/harnesses/kiro/agents) without its `hooks` key. */
+  'kiro-agent-content': (sourceRel        , content     ) => {
+    if (!sourceRel.endsWith('.json')) return content;
+    const agent = JSON.parse(content.toString('utf8'));
+    delete agent.hooks;
+    return Buffer.from(`${JSON.stringify(agent, null, 2)}\n`);
+  },
 };
 
+/** Row 131: core/registry/contracts.json, read once. Its `agentSkillsSpec` holds the Agent Skills
+ * spec keys; each contract's `skillFields` the keys that harness documents. */
+const SKILL_CONTRACTS = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'core', 'registry', 'contracts.json'), 'utf8'));
+
+/** One `skill-frontmatter-<harness>` transform per contract that lists skillFields: a SKILL.md keeps
+ * the spec keys and that harness's skillFields at the top level, and every other top-level key moves
+ * under `metadata` as a quoted string. Files other than SKILL.md pass through unchanged. */
+for (const contract of SKILL_CONTRACTS.contracts.filter((entry     ) => Array.isArray(entry.skillFields))) {
+  const allowed = new Set        ([...SKILL_CONTRACTS.agentSkillsSpec.skillFields, ...contract.skillFields]);
+  TRANSFORMS[`skill-frontmatter-${contract.harness}`] = (sourceRel        , content     ) => (
+    path.basename(sourceRel) === 'SKILL.md' ? Buffer.from(portableSkillFrontmatter(content.toString('utf8'), allowed, sourceRel)) : content);
+}
+
+/** A one-line YAML scalar's value. Single-quoted: `''` is one quote. Double-quoted: JSON's escapes
+ * (`\"`, `\\`, `\n`, `\t`, `\uXXXX`, ...), which YAML reads the same way; any other escape throws
+ * rather than be guessed. Anything else is plain and taken as written. */
+function yamlScalar(value        , key        , file        )         {
+  const single = value.match(/^'((?:[^']|'')*)'$/);
+  if (single) return single[1].replace(/''/g, "'");
+  if (!/^"(?:[^"\\]|\\.)*"$/.test(value)) return value;
+  try { return JSON.parse(value); } catch {
+    throw new Error(`${file}: '${key}' has a double-quoted value with an escape this projector does not decode`);
+  }
+}
+
+/** Move every top-level frontmatter key outside `allowed` under `metadata:`. A moved value is
+ * written as a JSON string (valid YAML), a plain scalar's continuation lines joined with a space; a
+ * nested map or a block scalar (`|`, `>`) is not handled, so it throws rather than guess, and so does a
+ * flow-style `metadata` (`{...}` on the key's line), which block entries cannot be appended to without a
+ * YAML parser. `file` names the source in each error. */
+function portableSkillFrontmatter(text        , allowed             , file = 'SKILL.md')         {
+  const match = text.match(/^---\n([\s\S]*?\n)---(?=\n|$)/);
+  if (!match) return text;
+  const entries                                                            = [];
+  for (const line of match[1].replace(/\n$/, '').split('\n')) {
+    // A top-level key, bare or quoted (`"key":`, `'key':`); `prefix` is the length up to its colon.
+    const found = line.match(/^(?:"((?:[^"\\]|\\.)+)"|'((?:[^']|'')+)'|([A-Za-z][A-Za-z0-9_-]*))[ \t]*:/);
+    const key = found ? (found[1]?.replace(/\\(.)/g, '$1') ?? found[2]?.replace(/''/g, "'") ?? found[3]) : null;
+    if (key || !entries.length) entries.push({ key, prefix: found ? found[0].length : 0, lines: [line] });
+    else entries[entries.length - 1].lines.push(line);
+  }
+  const metadataEntry = entries.find((entry) => entry.key === 'metadata');
+  if (metadataEntry && /^[ \t]*[^\s#]/.test(metadataEntry.lines[0].slice(metadataEntry.prefix))) {
+    throw new Error(`${file}: flow-style metadata cannot take moved keys; write metadata as a block map`);
+  }
+  const moved = entries.filter((entry) => entry.key && entry.key !== 'metadata' && !allowed.has(entry.key));
+  if (!moved.length) return text;
+  const metadata = moved.map(({ key, prefix, lines }) => {
+    const head = lines[0].slice(prefix).trim();
+    if (!head || /^[|>][-+0-9]*$/.test(head)) throw new Error(`${file}: '${key}' has no scalar value to move under metadata`);
+    const value = [head, ...lines.slice(1).map((part) => part.trim())].join(' ').trim();
+    return `  ${/^[A-Za-z][A-Za-z0-9_-]*$/.test(key          ) ? key : JSON.stringify(key)}: ${JSON.stringify(yamlScalar(value, key          , file))}`;
+  });
+  const kept = entries.filter((entry) => !moved.includes(entry));
+  const existing = kept.find((entry) => entry.key === 'metadata');
+  if (existing) existing.lines.push(...metadata);
+  else kept.push({ key: 'metadata', prefix: 9, lines: ['metadata:', ...metadata] });
+  return `---\n${kept.flatMap((entry) => entry.lines).join('\n')}\n${text.slice(match[0].length - 3)}`;
+}
+
 function resolveTransform(name     )                                                    {
   if (!name) return null;
   const transform = TRANSFORMS[name];
@@ -130,23 +247,113 @@ function renderClaudeOutputStyle(sourceRel        , content     )         {
   return ['---', `name: DoFlow: ${base}`, `description: ${JSON.stringify(description)}`, 'keep-coding-instructions: true', '---', '', text.replace(/\n*$/, ''), ''].join('\n');
 }
 
-/** The frontmatter keys Gemini CLI documents for a custom subagent (https://geminicli.com/docs/core/subagents, accessed 2026-10-06).
- * Its agent schema is strict, so a spec key outside this list (DoFlow's `effort`) would be rejected. */
-const GEMINI_AGENT_KEYS = new Set(['name', 'description', 'kind', 'tools', 'mcpServers', 'model', 'temperature', 'max_turns', 'timeout_mins']);
+/** One harness's `agentLimits` block from core/registry/harnesses.json, read once. */
+let harnessAgentLimits               = null;
+function agentLimitsOf(harnessId        )      {
+  if (!harnessAgentLimits) {
+    harnessAgentLimits = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'core', 'registry', 'harnesses.json'), 'utf8')).harnesses;
+  }
+  const harness = (harnessAgentLimits         ).find((item     ) => item.id === harnessId);
+  if (!harness) throw new Error(`agentLimits: unknown harness '${harnessId}'`);
+  return harness.agentLimits || {};
+}
+
+/** The `apply` keys a harness writes into the file of a `read-only` agent spec (118 IC-003), read from
+ * `agentLimits.readOnly`. `null` when the harness's limit is `unenforced`: nothing is written, and the
+ * registry says why. */
+function readOnlyApply(harnessId        )                             {
+  const entry = agentLimitsOf(harnessId).readOnly;
+  return entry?.status === 'native' ? entry.apply : null;
+}
+
+/** The MCP servers DoFlow's registry names, read once and sorted: every `core/registry/mcp.json`
+ * server (the ones an install writes) and every capability provider's `mcp.server` in
+ * capabilities.json (semble, graphify). All are retrieval servers, so a read-only agent keeps them. */
+let registryMcpServers                  = null;
+function approvedMcpServers()           {
+  if (!registryMcpServers) {
+    const read = (file        ) => JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'core', 'registry', file), 'utf8'));
+    const providers = Object.values(read('capabilities.json').capabilities || {}).flatMap((capability     ) => capability.providers || []);
+    registryMcpServers = [...new Set        ([
+      ...read('mcp.json').servers.map((server     ) => server.id),
+      ...providers.map((provider     ) => provider.mcp?.server).filter(Boolean),
+    ])].sort();
+  }
+  return registryMcpServers            ;
+}
+
+/** One category's tools on a harness: the `map` entry, or for `mcp` the selector of each approved server. */
+function categoryTools(entry     , category        )           {
+  return category === 'mcp' ? approvedMcpServers().map((server) => entry.mcpSelector.replace('{server}', server)) : entry.map[category];
+}
+
+/** The categories of a spec's `tool-scope` value (`read, shell, web`), or null when it declares none. */
+function scopeCategories(value                    )                  {
+  if (value === undefined) return null;
+  return value.split(',').map((item        ) => item.trim()).filter(Boolean);
+}
+
+/** The keys a harness writes for a declared tool scope (row 135), from `agentLimits.toolScope`: the
+ * category tools as a comma string or a list, or a closed permission object (`"*": deny`, then an
+ * allow per declared tool). `null` when the spec declares no scope or the harness cannot express one
+ * (`unenforced`): then nothing is written, never a broader scope. */
+function toolScopeApply(harnessId        , scope                 )                             {
+  if (!scope) return null;
+  const entry = agentLimitsOf(harnessId).toolScope;
+  if (entry?.status !== 'native') return null;
+  for (const category of scope) {
+    if (category !== 'mcp' && !Object.hasOwn(entry.map, category)) throw new Error(`tool-scope: unknown category '${category}' for harness '${harnessId}'`);
+  }
+  const tools = scope.flatMap((category) => categoryTools(entry, category));
+  if (entry.form === 'closed') return { [entry.field]: { '*': 'deny', ...Object.fromEntries(tools.map((tool        ) => [tool, 'allow'])) } };
+  return { [entry.field]: entry.form === 'comma' ? tools.join(', ') : tools };
+}
+
+/** The keys an agent file gains: the scope keys, then the read-only keys. Where both write one key the
+ * narrower wins: two lists keep only the tools both name, plus the approved MCP selectors (retrieval
+ * servers a read-only agent keeps); two permission objects keep every `deny`. */
+function agentLimitKeys(harnessId        , { readOnly, scope }                                               )                             {
+  const scoped = toolScopeApply(harnessId, scope);
+  const limits = readOnly ? readOnlyApply(harnessId) : null;
+  if (!scoped || !limits) return scoped || limits;
+  const merged                      = { ...scoped };
+  for (const [key, value] of Object.entries(limits)) {
+    const have = merged[key];
+    if (have === undefined) merged[key] = value;
+    else if (Array.isArray(have) && Array.isArray(value)) {
+      const mcp = scope?.includes('mcp') ? categoryTools(agentLimitsOf(harnessId).toolScope, 'mcp') : [];
+      merged[key] = have.filter((tool        ) => value.includes(tool) || mcp.includes(tool));
+    }
+    else if (have && value && typeof have === 'object' && typeof value === 'object') merged[key] = { ...have, ...value };
+    else throw new Error(`agentLimits: harness '${harnessId}' writes '${key}' from both the tool scope and the read-only limit`);
+  }
+  return merged;
+}
 
-/** Keep only Gemini's documented top-level frontmatter keys, with their indented continuation
- * lines, in source order. The body after the closing `---` passes through byte for byte, and a
- * file without frontmatter is returned unchanged. */
-function filterGeminiAgentFrontmatter(text        )         {
+/** One frontmatter key as YAML lines: a scalar inline, an array as a flow sequence, an object as an
+ * indented block. A key that is not a plain name (`*`, `context7_*`) is double-quoted. */
+function yamlLines(key        , value     , indent         = '')           {
+  const name = /^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key);
+  if (Array.isArray(value)) return [`${indent}${name}: ${JSON.stringify(value)}`];
+  if (value && typeof value === 'object') {
+    return [`${indent}${name}:`, ...Object.entries(value).flatMap(([k, v]) => yamlLines(k, v, `${indent}  `))];
+  }
+  return [`${indent}${name}: ${value}`];
+}
+
+/** Rewrite a shared agent spec's frontmatter for one harness: `access` and `tool-scope` are never projected under
+ * those names; the spec gains the harness's keys for its tool scope and, when `read-only`, its `apply` keys. Body and every other
+ * key pass through byte for byte; a file without frontmatter is returned unchanged. */
+function applyAgentLimits(text        , harnessId        )         {
   const match = text.match(/^---\r?\n([\s\S]*?\r?\n)---(?=\r?\n|$)/);
   if (!match) return text;
-  let keep = false;
-  const kept = match[1].split(/(?<=\n)/).filter((line        ) => {
-    const key = line.match(/^([A-Za-z][A-Za-z0-9_-]*):/);
-    if (key) keep = GEMINI_AGENT_KEYS.has(key[1]);
-    return keep;
-  });
-  return `${text.slice(0, text.indexOf('\n') + 1)}${kept.join('')}${text.slice(match[0].length - 3)}`;
+  const lines = match[1].split(/(?<=\n)/);
+  const readOnly = lines.some((line        ) => /^access:\s*read-only\s*$/.test(line));
+  const scopeLine = lines.find((line        ) => /^tool-scope:/.test(line));
+  const apply = agentLimitKeys(harnessId, { readOnly, scope: scopeCategories(scopeLine?.replace(/^tool-scope:/, '')) });
+  const added = apply ? Object.entries(apply).flatMap(([key, value]) => yamlLines(key, value)).map((line        ) => `${line}\n`) : [];
+  const kept = lines.filter((line        ) => !/^(access|tool-scope):/.test(line));
+  return `${text.slice(0, text.indexOf('\n') + 1)}${kept.join('')}${added.join('')}${text.slice(match[0].length - 3)}`;
 }
 
 /** The command a Kiro hook runs for one front-door script: the project copy when the git root
@@ -177,8 +384,9 @@ function kiroPreToolUseHooks()        {
 }
 
 /** Map one core/shared agent-spec file onto a kiro-cli custom agent. Spec keys other than
- * name/description (model: inherit, effort) are dropped: Kiro inherits the session model. */
-function renderKiroAgent(text        )         {
+ * name/description (model: inherit, effort) are dropped: Kiro inherits the session model. `access` is
+ * never projected; the spec's tool scope (narrowed by `apply.tools` when `read-only`) replaces `tools: ["*"]`. */
+function renderKiroAgent(text        , { hooks = true }                      = {})         {
   const fm                         = {};
   let body = text;
   if (text.startsWith('---')) {
@@ -191,17 +399,16 @@ function renderKiroAgent(text        )         {
       body = text.slice(end + 4).replace(/^\n+/, '');
     }
   }
+  const limits = agentLimitKeys('kiro', { readOnly: fm.access === 'read-only', scope: scopeCategories(fm['tool-scope']) });
   const agent = {
     name: fm.name || '', description: fm.description || '',
     prompt: `${body.replace(/\s+$/, '')}\n`,
-    tools: ['*'],
-    hooks: kiroPreToolUseHooks(),
+    tools: limits?.tools ?? ['*'],
+    ...(hooks ? { hooks: kiroPreToolUseHooks() } : {}),
   };
   return `${JSON.stringify(agent, null, 2)}\n`;
 }
 
-const OPENCODE_READONLY_AGENTS = new Set(['spec-analyst', 'system-architect', 'quality-guardian', 'research-writer']);
-
 /** Map one core/shared agent-spec file onto OpenCode's documented markdown-agent frontmatter
  * (description / mode / permission; model omitted because OpenCode has no 'inherit'). Unknown
  * spec keys (tools, effort) are dropped rather than passed through, so OpenCode never sees
@@ -222,9 +429,8 @@ function renderOpencodeAgent(text        )         {
   const lines = ['---'];
   if (fm.description) lines.push(`description: ${JSON.stringify(fm.description)}`);
   lines.push('mode: subagent');
-  if (OPENCODE_READONLY_AGENTS.has(fm.name)) {
-    lines.push('permission:', '  edit: deny', '  bash: deny');
-  }
+  const limits = agentLimitKeys('opencode', { readOnly: fm.access === 'read-only', scope: scopeCategories(fm['tool-scope']) });
+  if (limits) lines.push(...Object.entries(limits).flatMap(([key, value]) => yamlLines(key, value)));
   lines.push('---', '', body.replace(/\n*$/, ''), '');
   return lines.join('\n');
 }
@@ -233,11 +439,15 @@ function renderOpencodeAgent(text        )         {
  * the destination tree beyond checking existence. `relPath` is destination-relative and doubles as
  * the ledger identity, so a layout change relocates the recorded resource too — planTree's
  * relocation handling then removes the old path rather than orphaning it. */
-function discoverTree({ sourceDir, destDir, fsImpl = fs, layout, transform }     )                   {
+function discoverTree({ sourceDir, destDir, fsImpl = fs, layout, transform, select }     )                   {
   if (!fsImpl.existsSync(sourceDir)) throw new Error(`copy-tree source is missing: ${sourceDir}`);
   const mapRel = typeof layout === 'function' ? layout : resolveLayout(layout);
   const mapContent = typeof transform === 'function' ? transform : resolveTransform(transform);
-  const files = walkRelFiles(sourceDir, fsImpl).map((sourceRel) => {
+  const selected = resolveSelect(select)?.(sourceDir, fsImpl);
+  const files = walkRelFiles(sourceDir, fsImpl).filter((sourceRel) => {
+    if (!selected) return true;
+    return selected.has(sourceRel.split(path.sep).join('/'));
+  }).map((sourceRel) => {
     const relPath = mapRel(sourceRel);
     const sourceAbs = path.join(sourceDir, sourceRel);
     const destAbs = path.join(destDir, relPath);
@@ -247,6 +457,27 @@ function discoverTree({ sourceDir, destDir, fsImpl = fs, layout, transform }
   return { files };
 }
 
+/** Selected files that map to one destination cannot both be installed safely. */
+function selectedDestinationCollisions(files       , sourceDir        , destDir        )                                                     {
+  const sourcesByDestination = new Map               ();
+  for (const file of files) {
+    const key = path.resolve(file.destAbs);
+    const sources = sourcesByDestination.get(key) || [];
+    sources.push(file);
+    sourcesByDestination.set(key, sources);
+  }
+
+  const destinations = new Set        ();
+  const conflicts           = [];
+  for (const [destination, sources] of sourcesByDestination) {
+    if (sources.length < 2) continue;
+    destinations.add(destination);
+    const names = sources.map((file) => path.relative(sourceDir, file.sourceAbs).split(path.sep).join('/'));
+    conflicts.push(`selected files ${names.map((name) => `'${name}'`).join(' and ')} map to the same destination '${path.relative(destDir, destination).split(path.sep).join('/')}'`);
+  }
+  return { destinations, conflicts };
+}
+
 /** A file's identity on disk (device + inode), or null when the path does not resolve to one. */
 function fileId(file        , fsImpl     )                {
   try {
@@ -292,7 +523,7 @@ function sameFileIndex(paths          , fsImpl      = fs)
  * `siblingReplaced` lists the harnesses whose recorded bytes this plan replaces: the file matches
  * neither the source nor this harness's own record, only a sibling's (forced or not).
  */
-function planTree({ sourceDir, destDir, previousResources = [], operation = 'apply', fsImpl = fs, layout, transform, force = false, keepModified = false, siblingFingerprints = new Map() }     )      {
+function planTree({ sourceDir, destDir, previousResources = [], operation = 'apply', fsImpl = fs, layout, transform, select, force = false, keepModified = false, siblingFingerprints = new Map() }     )      {
   const prevByPath = new Map             (previousResources.map((resource     ) => [resource.relPath, resource]));
   const changes        = [];
   const conflicts           = [];
@@ -307,7 +538,7 @@ function planTree({ sourceDir, destDir, previousResources = [], operation = 'app
   const sourceFingerprint = (destAbs        )                     => {
     if (sourceByDest === undefined) {
       sourceByDest = sourceDir && fsImpl.existsSync(sourceDir)
-        ? new Map                (discoverTree({ sourceDir, destDir, fsImpl, layout, transform }).files.map((file)                   => [file.destAbs, file.fingerprint]))
+        ? new Map                (discoverTree({ sourceDir, destDir, fsImpl, layout, transform, select }).files.map((file)                   => [file.destAbs, file.fingerprint]))
         : new Map();
     }
     return sourceByDest.get(destAbs);
@@ -335,7 +566,7 @@ function planTree({ sourceDir, destDir, previousResources = [], operation = 'app
     // Untampered on removal means the same two signals the apply path below already accepts: the
     // bytes this harness last recorded, or the bytes the current source would write. The second
     // one matters because a destination tree can be claimed by several harnesses (scripts.doflow
-    // is one `<project>/.doflow/scripts` for claude, codex and gemini), so a sibling's update
+    // is one `<project>/.doflow/scripts` for claude, codex and others), so a sibling's update
     // legitimately rewrites files this harness's rows still describe — the same "a sibling
     // changed bytes my row still describes" case the apply path had to be taught, arriving here
     // as an un-releasable claim instead of a refused install. A hand edit matches neither and is
@@ -366,10 +597,18 @@ function planTree({ sourceDir, destDir, previousResources = [], operation = 'app
     return { changes, conflicts, kept, siblingReplaced: [] };
   }
 
-  const { files } = discoverTree({ sourceDir, destDir, fsImpl, layout, transform });
+  const { files } = discoverTree({ sourceDir, destDir, fsImpl, layout, transform, select });
+  const collisions = select == null
+    ? { destinations: new Set        (), conflicts: [] }
+    : selectedDestinationCollisions(files, sourceDir, destDir);
+  conflicts.push(...collisions.conflicts);
   producedSameFile = sameFileIndex(files.map((file) => file.destAbs), fsImpl);
   const satisfiedAtSameLocation = new Set();
   for (const file of files) {
+    if (collisions.destinations.has(path.resolve(file.destAbs))) {
+      satisfiedAtSameLocation.add(file.relPath);
+      continue;
+    }
     const prev = prevByPath.get(file.relPath);
     // prev.target === undefined means "location unknown" (pre-this-fix ledger data, or a
     // caller-constructed previousResources entry) — treat as same-location, matching pre-fix
@@ -442,16 +681,18 @@ function applyTree({ changes = [], fsImpl = fs, transform }     )
 /** Why a removal the runtime prune planned may no longer run, or null when it still may: the
  * prune's plan-time proof (src/lifecycle/index.js pruneRetiredRuntimeFiles) re-run right before the
  * unlink, so a directory swapped for a symlink, or a file linked to a shipped one, after the plan was
- * made is not deleted through. `guard` is `{ root, source }`: the tree and the source it projects.
+ * made is not deleted through. `guard` is `{ root, source, scope }`: the tree, the source it projects
+ * and the scope root the tree must resolve inside (a tree linked out of its scope is refused).
  * One walk of the source and one stat per shipped path per tree per call, cached in `cache`. */
 function pruneGuardRefusal(change     , cache                  , fsImpl     )                {
-  const { root, source } = change.pruneGuard;
-  const key = `${root}\0${source}`;
+  const { root, source, scope } = change.pruneGuard;
+  const key = `${root}\0${source}\0${scope ?? ''}`;
   if (!cache.has(key)) {
     const produced = fsImpl.existsSync(source) ? discoverTree({ sourceDir: source, destDir: root, fsImpl }).files.map((file     ) => file.destAbs) : [];
-    cache.set(key, { realRoot: fsImpl.realpathSync(root), sameFile: sameFileIndex(produced, fsImpl) });
+    cache.set(key, { realRoot: fsImpl.realpathSync(root), realScope: scope ? fsImpl.realpathSync(scope) : null, sameFile: sameFileIndex(produced, fsImpl) });
   }
-  const { realRoot, sameFile } = cache.get(key);
+  const { realRoot, realScope, sameFile } = cache.get(key);
+  if (realScope && !realRoot.startsWith(`${realScope}${path.sep}`)) return `${root} resolves outside the scope root ${scope}`;
   if (!fsImpl.realpathSync(change.target).startsWith(`${realRoot}${path.sep}`)) return `it resolves outside ${root}`;
   const shipped = sameFile(change.target);
   return shipped ? `it is the same file as ${shipped}, which this version ships` : null;
@@ -500,12 +741,17 @@ function pruneEmptyAncestors(startDir        , { fsImpl = fs }
  * `plannedWrites` lists the destinations the run being verified wrote. An absent source file is
  * not reported in general, because a user may delete one, but an absent file this run wrote means
  * the run lost it (a case-only rename once deleted the file it had just written) and is a conflict. */
-function verifyTree({ sourceDir, destDir, fsImpl = fs, layout, transform, plannedWrites = [] }     )                                                         {
-  const { files } = discoverTree({ sourceDir, destDir, fsImpl, layout, transform });
+function verifyTree({ sourceDir, destDir, fsImpl = fs, layout, transform, select, plannedWrites = [] }     )                                                         {
+  const { files } = discoverTree({ sourceDir, destDir, fsImpl, layout, transform, select });
   const written = new Set(plannedWrites);
   const resources        = [];
   const conflicts           = [];
+  const collisions = select == null
+    ? { destinations: new Set        (), conflicts: [] }
+    : selectedDestinationCollisions(files, sourceDir, destDir);
+  conflicts.push(...collisions.conflicts);
   for (const file of files) {
+    if (collisions.destinations.has(path.resolve(file.destAbs))) continue;
     if (!file.exists) {
       if (written.has(file.destAbs)) conflicts.push(`${file.relPath} was written by this run but is missing`);
       continue;
@@ -517,7 +763,7 @@ function verifyTree({ sourceDir, destDir, fsImpl = fs, layout, transform, planne
   return { ok: conflicts.length === 0, resources, conflicts };
 }
 
-// ---- per-adapter copy-tree glue, shared so codex/claude/gemini don't each carry their own copy ----
+// ---- per-adapter copy-tree glue, shared so each adapter doesn't carry its own copy ----
 
 /** Filter a harness's asset list down to the ones this engine handles. */
 function copyTreeAssets(assets     )        {
@@ -578,17 +824,17 @@ function sharedTreeDestDir(rootDir        , nativeDir     )                {
   return dest;
 }
 
-/** The assets that project a tree several harnesses claim at one scope root: the runtime tree, and
- * the guidance tree. A harness whose
+/** The assets that project a tree several harnesses claim at one scope root: the runtime, guidance,
+ * and shared hooks trees. A harness whose
  * install predates its own rows for a shared tree (Pi gained guidance rows in v1.15.0) can only
  * recognise the bytes a sibling recorded. */
 const SHARED_TREE_ASSETS = new Set([
   'scripts.doflow', 'runtime.cli', 'runtime.lib', 'runtime.registry',
-  'guidance.context-layer', 'kiro.guidance-tree',
+  'guidance.context-layer', 'kiro.guidance-tree', 'hooks.shared',
 ]);
 
 /** For each shared-tree target, the fingerprints other harnesses recorded and which harness
- * recorded each, so an update accepts a runtime or guidance tree a sibling wrote (several harnesses
+ * recorded each, so an update accepts a runtime, guidance, or shared hooks tree a sibling wrote (several harnesses
  * claim one `.doflow` file) while bytes no such row recorded are still refused as a hand edit. */
 function ledgerSiblingFingerprints(resources     , harness        )                                   {
   const byTarget = new Map                             ();
@@ -617,4 +863,4 @@ function ledgerFileResources(resources     , harness        , assetId        )
     .map((resource     ) => ({ relPath: resource.identity, fingerprint: resource.fingerprint, target: resource.target }));
 }
 
-module.exports = { kiroHook, kiroHookCommand, kiroPreToolUseHooks, walkRelFiles, discoverTree, sameFileIndex, planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, resolveLayout, LAYOUTS, resolveTransform, TRANSFORMS, fingerprint, pruneEmptyAncestors, readJson, sourceDirFor };
+module.exports = { readOnlyApply, toolScopeApply, approvedMcpServers, agentLimitKeys, kiroHook, kiroHookCommand, kiroPreToolUseHooks, walkRelFiles, discoverTree, sameFileIndex, planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, resolveLayout, LAYOUTS, resolveSelect, SELECTORS, resolveTransform, TRANSFORMS, portableSkillFrontmatter, fingerprint, pruneEmptyAncestors, readJson, sourceDirFor };

package/src/adapters/guidance-manifest.js

@@ -0,0 +1,71 @@
+'use strict';
+
+// The shared, harness-neutral core set: the breadth-first @-import walk rooted at DOFLOW_CORE.md.
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Generated per install, excluded by name rather than forgotten.
+//
+// MCP_INDEX.md and everything it imports under guidance/mcp/ are written at install time from the
+// MCP servers the user actually selected. Their size is a property of the machine, not of
+// DoFlow-authored content, and it differs between two correct installs — so the import walk stops
+// at MCP_INDEX.md and does not descend into its @mcp/* imports.
+const GENERATED_EXCLUSIONS = new Map                ([
+  ['MCP_INDEX.md', 'generated per install from the servers actually selected; size varies per machine'],
+]);
+
+function importsIn(text        )           {
+  return [...text.matchAll(/^@(\S+)$/gm)].map(([, target]) => target);
+}
+
+/** The first path segment of `rel` (relative to `root`) that is a symlink, or null. */
+function symlinkedSegment(root        , rel        , fsImpl     )                {
+  if (typeof fsImpl.lstatSync !== 'function') return null;
+  let current = root;
+  for (const segment of rel.split('/')) {
+    current = path.join(current, segment);
+    if (fsImpl.lstatSync(current).isSymbolicLink()) return path.relative(root, current).split(path.sep).join('/');
+  }
+  return null;
+}
+
+function guidanceManifest(root        , fsImpl      = fs)                                                               {
+  const rootFile = 'DOFLOW_CORE.md';
+  if (!fsImpl.existsSync(path.join(root, rootFile))) {
+    throw new Error(`guidanceManifest root is missing ${rootFile}: ${root}`);
+  }
+
+  const files           = [];
+  const generated           = [];
+  const dangling           = [];
+  const seen = new Set        ();
+  const queue = [rootFile];
+
+  while (queue.length) {
+    const rel = path.posix.normalize(queue.shift() .replace(/\\/g, '/'));
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    if (GENERATED_EXCLUSIONS.has(rel)) { generated.push(rel); continue; }
+
+    // The core set is a closed set of files under the guidance root. An import that leaves it,
+    // or that is (or sits under) a symlink, is not something the copy-tree engine installs, so it
+    // is refused here rather than reported as part of a set that is never written (107-B review C-4).
+    if (rel === '..' || rel.startsWith('../') || path.posix.isAbsolute(rel)) {
+      throw new Error(`guidanceManifest: ${rel} escapes the guidance root: ${root}`);
+    }
+    const full = path.join(root, ...rel.split('/'));
+    if (!fsImpl.existsSync(full)) { dangling.push(rel); continue; }
+    const linked = symlinkedSegment(root, rel, fsImpl);
+    if (linked) throw new Error(`guidanceManifest: ${rel} is or sits under a symlink (${linked}); the copy-tree engine does not install symlinks: ${root}`);
+    const text = fsImpl.readFileSync(full, 'utf8');
+    files.push(rel);
+    for (const target of importsIn(text)) {
+      if (path.posix.isAbsolute(target)) throw new Error(`guidanceManifest: ${rel} imports the absolute path ${target}: ${root}`);
+      queue.push(path.posix.normalize(path.posix.join(path.posix.dirname(rel), target)));
+    }
+  }
+
+  return { files, generated, dangling };
+}
+
+module.exports = { GENERATED_EXCLUSIONS, guidanceManifest };

package/src/adapters/guidance-pointer.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const path = require('node:path');
+
+const GUIDANCE_TOKEN = '{{GUIDANCE}}';
+
+function renderGuidancePointer(content        , { scope, scopeRoot }                                      )         {
+  if (scope !== 'global' && scope !== 'project') throw new Error(`Unknown guidance pointer scope '${scope}'`);
+  if (typeof content !== 'string') throw new TypeError('Guidance pointer content must be a string');
+
+  const guidancePath = scope === 'global'
+    ? path.resolve(scopeRoot, '.doflow', 'guidance').replace(/\\/g, '/')
+    : '.doflow/guidance';
+  const rendered = content.split(GUIDANCE_TOKEN).join(guidancePath);
+  if (rendered.includes(GUIDANCE_TOKEN)) throw new Error('Guidance pointer contains an unresolved token');
+  return rendered;
+}
+
+module.exports = { renderGuidancePointer };