@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/adapters/hook-commands.js

@@ -2,10 +2,9 @@
 
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
-// Shared hook-command verification — the one piece of codex/hooks.ts and gemini/hooks.ts that
-// proved byte-identical on inspection (unlike SUPPORTED_EVENTS, validateHooksConfig, and
-// classifyClaudeGuardrails, which encode genuine per-harness differences and stay in each
-// adapter). verifyHookCommands and the two private helpers it calls, commandScriptNames and
+// Hook-command verification, kept apart from codex/hooks.ts because it does not depend on the
+// harness (unlike SUPPORTED_EVENTS, validateHooksConfig, and classifyClaudeGuardrails, which
+// encode genuine per-harness differences and stay in each adapter). verifyHookCommands and the two private helpers it calls, commandScriptNames and
 // hookHandlers, check that a hook config's command handlers resolve to a real, executable script
 // in the harness's own hooks directory — that check does not vary by harness, so it lives once.
 const fs = require('node:fs');
@@ -23,12 +22,9 @@ function hookHandlers(config     )                                    {
       (Array.isArray(group?.hooks) ? group.hooks : []).map((handler     ) => ({ event, handler }))));
 }
 
-// On `trusted`: both harnesses gate hook execution behind their own trust prompt — Codex through
-// its config, Gemini by fingerprinting a hook's name and command and warning before running one
-// that changed (geminicli.com/docs/hooks/). DoFlow verifies neither gate live; doing so would need
-// a running CLI session. It reports trust as a prerequisite whose shape it observed, not one it
-// bypassed or assumed satisfied. That reading is identical for both harnesses, which is part of
-// why this function is shared.
+// On `trusted`: Codex gates hook execution behind its own trust prompt, through its config.
+// DoFlow does not verify that gate live; doing so would need a running CLI session. It reports
+// trust as a prerequisite whose shape it observed, not one it bypassed or assumed satisfied.
 // Windows carries no executable permission bits — statSync().mode always reports 0666/0444 and
 // chmodSync can only toggle the read-only flag — so the POSIX "not executable" failure mode
 // cannot exist there. Requiring the bit would refuse every hooks install on win32 (the scripts

package/src/adapters/index.js

@@ -52,6 +52,7 @@ function projectAdapterInput({ registry, harness, scope, scopeRoot, assets = [],
       // source paths, which is all of them except Antigravity's directory-per-agent requirement.
       layout: projection.layout ?? null,
       transform: projection.transform ?? null,
+      select: projection.select ?? null,
       prerequisites: [...(capability.prerequisites || [])],
     });
   };

package/src/adapters/kiro/index.js

@@ -7,11 +7,13 @@
 // Kiro's native root is symmetric across scopes — `.kiro/` (project) / `~/.kiro/` (global) is the
 // one directory that holds everything Kiro reads: steering, agents, hooks, and settings/mcp.json
 // (see src/targets.js's toolDirs() for the same convention this adapter's own nativePaths()
-// mirrors). Unlike every other harness in this codebase, Kiro receives DoFlow's *full* guidance
-// tree as steering files rather than a single marker-wrapped pointer file plus a separately-copied
-// tree (design.md §4's "research decision D3"): there is no single-file instruction surface here
-// at all, so — unlike src/adapters/gemini or src/adapters/opencode — this adapter never renders a
-// marker-wrapped instruction file.
+// mirrors). Unlike every other harness in this codebase, Kiro receives DoFlow's guidance as
+// steering files rather than a single marker-wrapped pointer file plus a separately-copied tree
+// (design.md §4's "research decision D3"): there is no single-file instruction surface here at all,
+// so — unlike src/adapters/opencode — this adapter never renders a
+// marker-wrapped instruction file. Steering holds the core set only (DOFLOW_CORE.md and the files it
+// imports, selected by the `guidance-manifest` select); the full guidance tree remains under
+// `.doflow/guidance` through kiro.guidance-tree, where `retrieve` and the runtime read it.
 //
 // Evidence: https://kiro.dev/docs/steering/, https://kiro.dev/docs/mcp/configuration/,
 // https://kiro.dev/docs/hooks/
@@ -37,6 +39,15 @@ const LEGACY_MCP_REGISTRATION = `${HARNESS}:mcp:registration`;
  * module-level exports delegate to a default-configured instance so direct callers keep their
  * historical shape.
  */
+/** Hook tiers (maint-hooks): with Kiro outside `hooks.harnesses` (`context.hooksOff`) its agents carry no
+ * `hooks`, so they never name a hook script DoFlow did not install. */
+const CONTENT_ONLY_TRANSFORMS                                   = Object.freeze({ 'kiro-agents': 'kiro-agents-content' });
+function transformFor(asset     , context     )                {
+  if (context?.hooksOff !== true) return asset.transform || null;
+  if (asset.id === 'kiro.doflow-agent') return 'kiro-agent-content';
+  return CONTENT_ONLY_TRANSFORMS[asset.transform] ?? (asset.transform || null);
+}
+
 function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } = {}) {
   // Parity note: Kiro'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
@@ -59,8 +70,8 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
 
   /**
    * Kiro has no single-file, marker-managed instruction surface for this adapter to render into —
-   * the guidance tree is projected file-for-file by the copy-tree engine below, once as steering
-   * (guidance.context-layer) and once into the shared `.doflow/guidance` (kiro.guidance-tree). Every
+   * guidance is projected file-for-file by the copy-tree engine below, the core set as steering
+   * (guidance.context-layer) and the whole tree into the shared `.doflow/guidance` (kiro.guidance-tree). Every
    * asset routed to 'kiro' in core/registry/assets.json uses `renderer: copy-tree` or
    * `kiro-agents`, so nothing reaches this function. It is kept as a pure passthrough only to
    * satisfy the six-function adapter contract every harness must implement identically.
@@ -98,7 +109,7 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
       const destDir = copyTreeDestDir(paths.configDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Kiro');
       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: asset.layout, transform: asset.transform, keepModified: !removing,
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, transform: transformFor(asset, context), 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
@@ -115,7 +126,7 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
           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,
+          transformName: transformFor(asset, context),
           ...(change.kept ? { retained: true, retainedFor: [] } : {}),
           projection: { renderer: asset.renderer },
         });
@@ -153,7 +164,7 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
     for (const asset of kiroTreeAssets(assets)) {
       const destDir = copyTreeDestDir(paths.configDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Kiro');
-      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: asset.transform, plannedWrites: context?.plannedWrites });
+      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: transformFor(asset, context), select: asset.select, plannedWrites: context?.plannedWrites });
       conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({
@@ -209,8 +220,8 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
 
   /** Kiro has no hooks or mcp asset of its own in core/registry/assets.json (mcp servers come from
    * core/registry/mcp.json, not an asset), so an MCP entry change piggybacks on an asset id
-   * this harness actually receives — the same "pseudo-component" technique
-   * src/adapters/gemini/index.js#hooksAssetId already uses for its own settings-only component. */
+   * this harness actually receives — the same "pseudo-component" technique the opencode and
+   * copilot adapters use for their settings-only changes. */
   function pseudoAssetId(assets     ) {
     return assets.find((asset     ) => asset.id === 'guidance.context-layer')?.id ?? assets[0]?.id;
   }
@@ -258,6 +269,19 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
     };
   }
 
+  /** The hook front doors (IC-037): the scripts and the agent that wires them. */
+  function hookDoorAssets(assets     ) { return (assets || []).filter((asset     ) => asset.id === 'kiro.hooks-scripts' || asset.id === 'kiro.doflow-agent'); }
+
+  function planHookDoors({ scope, scopeRoot, assets = [], context = {}, ledger, fsImpl = fs }     ) {
+    const doors = planCopyTreeAssets({ assets: hookDoorAssets(assets), scope, scopeRoot, context, ledger, removing: false, fsImpl });
+    return { changes: doors.changes, conflicts: doors.conflicts, prerequisites: [], notices: doors.notices };
+  }
+
+  function verifyHookDoors({ scope, scopeRoot, assets = [], context = {}, fsImpl = fs }     ) {
+    const doors = verifyCopyTreeAssets({ assets: hookDoorAssets(assets), scope, scopeRoot, context, fsImpl });
+    return { ok: doors.conflicts.length === 0, statuses: doors.statuses, resources: doors.resources, conflicts: doors.conflicts };
+  }
+
   function apply({ changes = [], fsImpl = fs }     ) {
     writeMcpEntries(changes, { container: MCP_CONTAINER, fsImpl });
     applyCopyTreeAssets(changes, { fsImpl });
@@ -297,7 +321,7 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
     };
   }
 
-  return { nativePaths, discover, render, plan, apply, remove, verify, buildServerEntry };
+  return { nativePaths, discover, render, plan, apply, remove, verify, planHookDoors, verifyHookDoors, buildServerEntry };
 }
 
 const singleton = createKiroAdapter();
@@ -305,6 +329,7 @@ const singleton = createKiroAdapter();
 module.exports = {
   nativePaths: singleton.nativePaths, discover: singleton.discover, render: singleton.render,
   plan: singleton.plan, apply: singleton.apply, remove: singleton.remove, verify: singleton.verify,
+  planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors,
   buildServerEntry: singleton.buildServerEntry,
   createKiroAdapter,
 };

package/src/adapters/opencode/index.js

@@ -4,7 +4,7 @@
 
 // OpenCode adapter.
 //
-// OpenCode gets its own copy of DoFlow's skills tree, the same as Claude, Codex, and Gemini: it
+// OpenCode gets its own copy of DoFlow's skills tree, the same as Claude and Codex: it
 // natively discovers skills under `.opencode/skills/` (project) and `~/.config/opencode/skills/`
 // (global) without any settings entry, so the shared copy-tree engine in ../copy-tree.ts
 // materialises `skills.doflow` there directly. What remains registration, rather than
@@ -20,11 +20,11 @@ const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDes
 const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
 
 // Only the marker constants: marker-merge.js reads and writes files itself, which cannot be used
-// from plan(), whose contract is to compute changes without touching disk. The gemini adapter
-// solves this the same way, with a pure managedInstruction() over strings.
+// from plan(), whose contract is to compute changes without touching disk.
 const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
 const { destructiveCommandGlobs } = require('../../helper/guardrails.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
+const { renderGuidancePointer } = require('../guidance-pointer.js');
 
 const HARNESS = 'opencode';
 /**
@@ -107,9 +107,8 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   }
 
   /** Replace only the span between DoFlow's markers, leaving everything else byte-identical.
-   * An AGENTS.md that exists without a DoFlow section is refused rather than appended to — the same
-   * policy the gemini adapter applies to GEMINI.md, and for the same reason: AGENTS.md is a shared,
-   * cross-tool file, so where DoFlow's content belongs inside it is a decision for its owner, not a
+   * An AGENTS.md that exists without a DoFlow section is refused rather than appended to:
+   * AGENTS.md is a shared, cross-tool file, so where DoFlow's content belongs inside it is a decision for its owner, not a
    * guess for the installer. Add an empty marker pair to opt in. */
   /** Opt-in (--permissions) guardrail projection: DoFlow's destructive-command blocklist lands as
    * deny rules under permission.bash. Only keys this feature owns (each carries a matching
@@ -259,7 +258,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   /** OpenCode's settings-merge change has no asset of its own in core/registry/assets.json (it's a
    * registration side-effect of the instructions/mcp assets, not a projected asset), so it piggybacks
    * 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 the literal string 'opencode.config' is rejected as unknown. */
   function pseudoAssetId(assets     ) {
@@ -308,7 +307,8 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
 
     const guidance = assets.find((asset     ) => asset.capability === 'instructions');
     if (guidance) {
-      const rendered = render({ content: fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8') });
+      const pointer = renderGuidancePointer(fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8'), { scope, scopeRoot });
+      const rendered = render({ content: pointer });
       const outcome = removing
         ? { ok: true, operation: 'remove', content: strippedInstruction(found.instruction) }
         : managedInstruction(found.instruction, rendered);

package/src/adapters/pi/hooks.js

@@ -0,0 +1,120 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { fingerprint } = require('../copy-tree.js');
+
+const ASSET_ID = 'pi.guard-extension';
+const EXTENSION_NAME = 'doflow-guard.js';
+const OWNERSHIP = 'pi:guard-extension';
+const TEMPLATE = 'core/harnesses/pi/extensions/doflow-guard.js';
+const BRIDGE_SUFFIX = ['.doflow', 'shared', 'hooks', 'bridge', 'bridge.sh'];
+
+function userAgentDir(scopeRoot     , env     ) {
+  const override = env?.PI_CODING_AGENT_DIR;
+  return typeof override === 'string' && override.trim() ? path.resolve(override.trim()) : path.join(scopeRoot, '.pi', 'agent');
+}
+
+function targetPath(scopeRoot     , env     , scope      = 'user') {
+  return scope === 'project'
+    ? path.join(scopeRoot, '.pi', 'extensions', EXTENSION_NAME)
+    : path.join(userAgentDir(scopeRoot, env), 'extensions', EXTENSION_NAME);
+}
+
+function renderExtension({ repoRoot, scopeRoot, target, fsImpl = fs }     ) {
+  const templatePath = path.join(repoRoot, TEMPLATE);
+  const template = fsImpl.readFileSync(templatePath, 'utf8');
+  const bridgePath = path.join(scopeRoot, ...BRIDGE_SUFFIX);
+  const relative = path.relative(path.dirname(target), bridgePath).split(path.sep).join('/');
+  const rendered = template.replace("const BRIDGE = new URL('../../shared/hooks/bridge/bridge.sh', import.meta.url);",
+    `const BRIDGE = new URL(${JSON.stringify(relative)}, import.meta.url);`);
+  if (rendered === template) throw new Error('Pi extension bridge path template was not found');
+  return rendered;
+}
+
+function planPiHooks({ scope, scopeRoot, assets = [], ledger, context = {}, adopt = false, env = process.env, fsImpl = fs }     ) {
+  if (scope !== 'user' && scope !== 'global' && scope !== 'project') return { changes: [], conflicts: [], notices: [] };
+  const asset = assets.find((row     ) => row.id === ASSET_ID);
+  if (!asset) return { changes: [], conflicts: [], notices: [] };
+  const computedTarget = targetPath(scopeRoot, env, scope);
+  const removing = context.operation === 'remove';
+  const ownedRows = (ledger?.resources || []).filter((row     ) => row.harness === 'pi' && row.assetId === ASSET_ID
+    && row.ownershipIdentity === OWNERSHIP);
+  const exactOwned = ownedRows.find((row     ) => row.target === computedTarget);
+  const owned = exactOwned || (removing && ownedRows.length === 1 ? ownedRows[0] : undefined);
+  const target = removing && owned ? owned.target : computedTarget;
+  const exists = fsImpl.existsSync(target);
+  const notices           = [];
+  if (removing) {
+    if (!owned) return { changes: [], conflicts: [], notices };
+    if (!exists) return { changes: [{ assetId: ASSET_ID, target, operation: 'remove', release: true,
+      ownershipIdentity: OWNERSHIP, harness: 'pi', projection: { renderer: 'pi-guard-extension' } }], conflicts: [], notices };
+    const current = fsImpl.readFileSync(target, 'utf8');
+    if (fingerprint(current) !== owned.fingerprint) {
+      notices.push(`kept hand-edited ${target}; DoFlow no longer manages it`);
+      return { changes: [{ assetId: ASSET_ID, target, operation: 'remove', release: true,
+        ownershipIdentity: OWNERSHIP, harness: 'pi', projection: { renderer: 'pi-guard-extension' } }], conflicts: [], notices };
+    }
+    return { changes: [{ assetId: ASSET_ID, target, operation: 'remove', content: null,
+      ownershipIdentity: OWNERSHIP, harness: 'pi', projection: { renderer: 'pi-guard-extension' } }], conflicts: [], notices };
+  }
+
+  const content = renderExtension({ repoRoot: context.repoRoot, scopeRoot, target, fsImpl });
+  if (!exists) return { changes: [{ assetId: ASSET_ID, target, operation: 'create', content,
+    ownershipIdentity: OWNERSHIP, harness: 'pi', fingerprint: fingerprint(content),
+    projection: { renderer: 'pi-guard-extension' } }], conflicts: [], notices };
+  if (!owned && !adopt) {
+    return { changes: [], conflicts: [`Pi extension already exists and is not owned by DoFlow: ${target}`], notices };
+  }
+  const current = fsImpl.readFileSync(target, 'utf8');
+  if (owned && fingerprint(current) !== owned.fingerprint) {
+    return { changes: [], conflicts: [`Pi extension was modified outside DoFlow: ${target}`], notices };
+  }
+  if (current === content) return { changes: [], conflicts: [], notices };
+  return { changes: [{ assetId: ASSET_ID, target, operation: 'update', content,
+    ownershipIdentity: OWNERSHIP, harness: 'pi', fingerprint: fingerprint(content),
+    projection: { renderer: 'pi-guard-extension' } }], conflicts: [], notices };
+}
+
+function verifyPiHooks({ scope, scopeRoot, assets = [], ledger, context = {}, adopt = false, env = process.env, fsImpl = fs, pathEnv = process.env.PATH }     ) {
+  if (scope !== 'user' && scope !== 'global' && scope !== 'project') return { statuses: [], resources: [], conflicts: [] };
+  const asset = assets.find((row     ) => row.id === ASSET_ID);
+  if (!asset) return { statuses: [], resources: [], conflicts: [] };
+  const target = targetPath(scopeRoot, env, scope);
+  const owned = (ledger?.resources || []).find((row     ) => row.harness === 'pi' && row.assetId === ASSET_ID
+    && row.ownershipIdentity === OWNERSHIP && row.target === target);
+  const bridgePath = path.join(scopeRoot, ...BRIDGE_SUFFIX);
+  const present = fsImpl.existsSync(target);
+  const content = present ? fsImpl.readFileSync(target, 'utf8') : null;
+  const actualFingerprint = content === null ? null : fingerprint(content);
+  const fingerprintMatches = !!owned && actualFingerprint === owned.fingerprint;
+  const plannedWrite = (context?.plannedWrites || []).includes(target);
+  const bridgeMatches = !!content && content.includes(JSON.stringify(path.relative(path.dirname(target), bridgePath).split(path.sep).join('/')));
+  const commandOnPath = (command        ) => String(pathEnv || '').split(path.delimiter)
+    .some((dir) => [command, ...(process.platform === 'win32' ? ['.exe', '.cmd', '.bat'].map((ext) => command + ext) : [])]
+      .some((name) => fsImpl.existsSync(path.join(dir, name))));
+  const status = present && !owned && !plannedWrite && !adopt ? 'conflict'
+    : (present && (fingerprintMatches || plannedWrite) && bridgeMatches && commandOnPath('bash') && commandOnPath('jq') ? 'managed' : 'absent');
+  const resources = status === 'managed' ? [{ assetId: ASSET_ID, target, ownershipIdentity: OWNERSHIP,
+    fingerprint: actualFingerprint, sourceVersion: context.sourceVersion ?? 'unknown',
+    projection: { renderer: 'pi-guard-extension' } }] : [];
+  const statuses = [{ harness: 'pi', assetId: ASSET_ID, capability: 'hooks', status, target,
+    ownershipIdentity: OWNERSHIP, fingerprint: actualFingerprint, fingerprintMatches,
+    bridgePath, bridgeExists: fsImpl.existsSync(bridgePath), bash: commandOnPath('bash'), jq: commandOnPath('jq'),
+    prerequisites: scope === 'project' ? ['project-trust'] : [], piCodingAgentDir: typeof env?.PI_CODING_AGENT_DIR === 'string' && env.PI_CODING_AGENT_DIR.trim() ? env.PI_CODING_AGENT_DIR.trim() : null }];
+  const conflicts = status === 'conflict' ? [`Pi extension is not owned by DoFlow: ${target}`] : [];
+  return { statuses, resources, conflicts };
+}
+
+function removePiHooks(changes       , { fsImpl = fs }      = {}) {
+  let removed = 0;
+  for (const change of changes) {
+    if (change.projection?.renderer !== 'pi-guard-extension' || change.operation !== 'remove' || change.release) continue;
+    if (fsImpl.existsSync(change.target)) { fsImpl.unlinkSync(change.target); removed += 1; }
+  }
+  return removed;
+}
+
+module.exports = { ASSET_ID, EXTENSION_NAME, OWNERSHIP, userAgentDir, targetPath, renderExtension, planPiHooks, verifyPiHooks, removePiHooks };

package/src/adapters/pi/index.js

@@ -3,7 +3,7 @@
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
 // Pi adapter — a marker-merged instruction file plus copy-tree materialisation, the same shape
-// Claude/Codex/Gemini already use for their own skills trees.
+// Claude/Codex already use for their own skills trees.
 //
 // Skills materialise into Pi's own directories (`~/.pi/agent/skills` global, `.pi/skills` project)
 // via the shared copy-tree engine, rather than pointing Pi's settings.json at DoFlow's already
@@ -13,9 +13,7 @@
 //
 // MCP servers are merged per server into Pi's mcp.json (.pi/mcp.json project; ~/.pi/agent/mcp.json
 // or $PI_CODING_AGENT_DIR/mcp.json user) by ./mcp.ts; Pi reads it through its built-in MCP from
-// 0.99.0. Hooks are absent — Pi lifecycle handlers are TypeScript modules registered via pi.on(),
-// executing with full system permissions, which is a different trust model from the shell scripts
-// DoFlow ships.
+// 0.99.0. The user- and project-scope lifecycle extension is ledger-owned and resolves its shared bridge at install time.
 //
 // Evidence: https://pi.dev/docs/latest/settings, https://pi.dev/docs/latest/skills,
 // https://pi.dev/docs/latest/quickstart, https://pi.dev/docs/latest/extensions,
@@ -24,12 +22,15 @@ 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, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor } = require('../copy-tree.js');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor, resolveTransform } = require('../copy-tree.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 const { mcpRows, discoverPiMcp, ownedPiMcpIds, planPiMcp, applyPiMcp, verifyPiMcp } = require('./mcp.js');
+const { planPiHooks, verifyPiHooks, removePiHooks } = require('./hooks.js');
+const { renderGuidancePointer } = require('../guidance-pointer.js');
 
 const HARNESS = 'pi';
-const AGENT_DIR_NOTICE = 'PI_CODING_AGENT_DIR is set: Pi reads its whole agent dir from it, but DoFlow moves only mcp.json there; skills and AGENTS.md stay in ~/.pi/agent.';
+const AGENT_DIR_MCP_NOTICE = 'PI_CODING_AGENT_DIR is set: Pi reads its whole agent dir from it, but DoFlow moves only mcp.json there; skills and AGENTS.md stay in ~/.pi/agent.';
+const AGENT_DIR_NOTICE = 'PI_CODING_AGENT_DIR is set: Pi reads its whole agent dir from it, and DoFlow moves mcp.json and the guard extension there; skills and AGENTS.md stay in ~/.pi/agent.';
 
 // Native path facts live in core/registry/harnesses.json under this harness's "paths" section and
 // resolve through the shared harness-paths resolver; nothing below hardcodes them.
@@ -43,8 +44,8 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
   function nativePaths({ scope, scopeRoot }      = {}) {
     const paths = resolveHarnessPaths(declaredPaths, { scope, scopeRoot });
     // Pi's user-scope mcp.json follows $PI_CODING_AGENT_DIR when set. It is not declared in the
-    // registry because the path schema has no environment base (src/helper/harness-paths.js); only
-    // mcp moves, skills and AGENTS.md keep their declared locations.
+    // registry because the path schema has no environment base (src/helper/harness-paths.js); the
+    // guard extension follows it too, while skills and AGENTS.md keep their declared locations.
     if ((scope === 'user' || scope === 'global') && agentDirOverride()) paths.mcp = path.join(path.resolve(agentDirOverride()), 'mcp.json');
     return paths;
   }
@@ -105,7 +106,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
       const destDir = sharedTreeDestDir(paths.root, asset.nativeDir) ?? copyTreeDestDir(paths.configDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Pi');
       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: asset.layout, keepModified: !removing,
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, transform: asset.transform, 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
@@ -123,6 +124,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
           kind: 'copy-tree-file', identity: change.relPath,
           afterFingerprint: change.fingerprint, fingerprint: change.fingerprint, sourceVersion: 'registry-v1',
           ...(change.kept ? { retained: true, retainedFor: [] } : {}),
+          transformName: asset.transform || null,
           projection: { renderer: 'copy-tree' },
         });
       }
@@ -132,8 +134,12 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
 
   function applyCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
     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, fsImpl }).applied;
+      .map((change     ) => ({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint, transformName: change.transformName || null }));
+    const grouped = new Map                      ();
+    for (const change of treeChanges) grouped.set(change.transformName, [...(grouped.get(change.transformName) || []), change]);
+    let applied = 0;
+    for (const [transformName, group] of grouped) applied += applyTree({ changes: group, fsImpl, transform: resolveTransform(transformName) }).applied;
+    return applied;
   }
 
   function removeCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
@@ -150,7 +156,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     for (const asset of copyTreeAssets(assets)) {
       const destDir = sharedTreeDestDir(paths.root, asset.nativeDir) ?? copyTreeDestDir(paths.configDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Pi');
-      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, plannedWrites: context?.plannedWrites });
+      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: asset.transform, plannedWrites: context?.plannedWrites });
       conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({
@@ -175,7 +181,8 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
 
     const guidance = assets.find((asset     ) => asset.capability === 'instructions');
     if (guidance) {
-      const rendered = render({ content: fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8') });
+      const pointer = renderGuidancePointer(fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8'), { scope, scopeRoot });
+      const rendered = render({ content: pointer });
       const outcome = removing
         ? { ok: true, operation: 'remove', content: strippedInstruction(found.instruction) }
         : managedInstruction(found.instruction, rendered);
@@ -191,15 +198,32 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     changes.push(...copyTree.changes);
     conflicts.push(...copyTree.conflicts);
 
+    const piHooks = planPiHooks({ scope, scopeRoot, assets, ledger, context, adopt: context?.adopt === true, env, fsImpl });
+    changes.push(...piHooks.changes);
+    conflicts.push(...piHooks.conflicts);
+
     const piMcp = planPiMcp({ selected: mcp, rows: mcpRows(ledger), file: found.paths.mcp, scope, removing, snapshot: found.mcp, assets });
     changes.push(...piMcp.changes);
     conflicts.push(...piMcp.conflicts);
 
-    const notices = [...copyTree.notices, ...piMcp.notices];
-    if (!removing && scope !== 'project' && agentDirOverride()) notices.push(AGENT_DIR_NOTICE);
+    const notices = [...copyTree.notices, ...piMcp.notices, ...piHooks.notices];
+    if (!removing && scope !== 'project' && agentDirOverride()) {
+      notices.push(assets.some((asset     ) => asset.id === 'pi.guard-extension') ? AGENT_DIR_NOTICE : AGENT_DIR_MCP_NOTICE);
+    }
     return { changes, conflicts, notices, paths: found.paths };
   }
 
+  /** The hook front door (IC-037): the guard extension. */
+  function planHookDoors({ scope, scopeRoot, assets = [], context = {}, ledger, fsImpl = fs }     ) {
+    const door = planPiHooks({ scope, scopeRoot, assets, ledger, context, adopt: context?.adopt === true, env, fsImpl });
+    return { changes: door.changes, conflicts: door.conflicts, notices: door.notices };
+  }
+
+  function verifyHookDoors({ scope, scopeRoot, assets = [], ledger, context = {}, fsImpl = fs }     ) {
+    const door = verifyPiHooks({ scope, scopeRoot, assets, ledger, context, adopt: context?.adopt === true, env, fsImpl });
+    return { ok: door.conflicts.length === 0 && !door.statuses.some((s     ) => s.status === 'invalid' || s.status === 'conflict'), ...door };
+  }
+
   function writeChange(change     , fsImpl     ) {
     fsImpl.mkdirSync(path.dirname(change.target), { recursive: true });
     fsImpl.writeFileSync(change.target, change.content, 'utf8');
@@ -226,10 +250,12 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     let removed = applyPiMcp(changes.filter(isPiMcp), { fsImpl }).applied;
     for (const change of changes) {
       if (change.operation !== 'remove' || change.projection?.renderer === 'copy-tree' || isPiMcp(change)) continue;
+      if (change.projection?.renderer === 'pi-guard-extension') continue;
       if (change.content === null) continue;
       writeChange(change, fsImpl);
       removed += 1;
     }
+    removed += removePiHooks(changes, { fsImpl });
     removed += removeCopyTreeAssets(changes, { fsImpl });
     return { removed };
   }
@@ -263,10 +289,15 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     resources.push(...piMcp.resources);
     conflicts.push(...piMcp.conflicts);
 
+    const piHooks = verifyPiHooks({ scope, scopeRoot, assets, ledger, context, adopt: context?.adopt === true, env, fsImpl });
+    statuses.push(...piHooks.statuses);
+    resources.push(...piHooks.resources);
+    conflicts.push(...piHooks.conflicts);
+
     return { ok: conflicts.length === 0 && !statuses.some((s) => s.status === 'invalid' || s.status === 'conflict'), resources, statuses, conflicts };
   }
 
-  return { nativePaths, discover, render, plan, apply, remove, verify };
+  return { nativePaths, discover, render, plan, apply, remove, verify, planHookDoors, verifyHookDoors };
 }
 
 const singleton = createPiAdapter();
@@ -274,6 +305,7 @@ const singleton = createPiAdapter();
 module.exports = {
   HARNESS, nativePaths: singleton.nativePaths, discover: singleton.discover, render: singleton.render,
   plan: singleton.plan, apply: singleton.apply, remove: singleton.remove, verify: singleton.verify,
+  planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors,
   managedInstruction: (singleton       ).managedInstruction, strippedInstruction: (singleton       ).strippedInstruction,
   createPiAdapter,
 };

package/src/adapters/resolve-source.js

@@ -2,12 +2,36 @@
 
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
+const fs = require('node:fs');
 const path = require('node:path');
 
 /** Resolve a registry-declared source path against the repo root, refusing escapes. Shared by the
  * common projection module and by per-adapter native-projection normalizers, which is why it lives
- * in its own module rather than in index.js — a normalizer importing index.js would be a cycle. */
-function resolveRegistrySource(registry     , source     , label        )         {
+ * in its own module rather than in index.js — a normalizer importing index.js would be a cycle.
+ * `sourceRoot` checks containment against that root using real paths, as required by IC-017.
+ * When omitted, the existing lexical repository-root check is preserved. */
+function resolveRegistrySource(registry     , source     , label        , sourceRoot         )         {
+  if (sourceRoot !== undefined) {
+    if (typeof sourceRoot !== 'string' || !sourceRoot) {
+      throw new Error(`Registry ${label} sourceRoot must be a non-empty string`);
+    }
+    if (typeof source !== 'string' || !source) throw new Error(`Registry ${label} source is required`);
+    let realRoot        ;
+    let realSource        ;
+    try {
+      realRoot = fs.realpathSync(path.resolve(sourceRoot));
+      realSource = fs.realpathSync(path.resolve(sourceRoot, source));
+    } catch (error     ) {
+      if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+        throw new Error(`Registry ${label} source is missing under source root: ${source}`);
+      }
+      throw error;
+    }
+    if (!realSource.startsWith(`${realRoot}${path.sep}`)) {
+      throw new Error(`Registry ${label} source escapes source root: ${source}`);
+    }
+    return realSource;
+  }
   if (typeof registry.repoRoot !== 'string' || !registry.repoRoot) throw new Error(`Registry repoRoot is required for ${label}`);
   if (typeof source !== 'string' || !source) throw new Error(`Registry ${label} source is required`);
   const root = path.resolve(registry.repoRoot);

package/src/cli/commands/install.js

@@ -20,7 +20,7 @@ const { loadRegistry } = require('../../registry/index.js');
 const { storageAfterInstall } = require('../../runtime/storage/upkeep.js');
 const { applyLifecycle, applyMcpIndex, recordMcpOwnership } = require('../../lifecycle/index.js');
 const {
-  codexScope, registryLifecycleView, printRegistryLifecycle, printPlanNotices, assertSafeRegistryPlan,
+  codexScope, registryLifecycleView, printRegistryLifecycle, printRetiredPlans, printPlanNotices, assertSafeRegistryPlan,
   lockDocument, recordLock,
 } = require('../../lifecycle/view.js');
 const {
@@ -55,7 +55,7 @@ function cmdInstall(o     )       {
     // One lifecycle view across every requested target — computed unconditionally (not only under
     // --dry-run) so its safety gate and its plan are the exact same object the real apply below uses.
     const lifecycleView = registryLifecycleView({ registry, repoRoot: REPO_ROOT, scope, dirs, targets,
-      mcpSelections: selection.selections, mcpAdoptable: selection.adoptable, retainedMcpIds: selection.retainedMcpIds,
+      mcpSelections: selection.selections, mcpAdoptable: selection.adoptable, retainedMcpIds: selection.retainedMcpIds, operation: 'install',
       force: o.force, adopt: o.adopt === true, permissions: o.permissions === true, statusline: o.statusline === true });
     if (!lifecycleView.plan.safe) { assertSafeRegistryPlan(lifecycleView); return; }
 
@@ -120,6 +120,7 @@ function cmdInstall(o     )       {
         const owned = result.ledger.resources.filter((resource     ) => resource.harness === target.harness).length;
         console.log(`[INFO] ${target.harness}: lifecycle verified (${owned} owned resource(s))`);
       }
+      printRetiredPlans(lifecycleView);
       ledgerAfter = result.ledger;
     } else {
       // MCP_INDEX.md is generated, not a tracked resource, so it never appears in plan.changes and