@khoavu882/doflow 2.0.0-beta.4 → 2.0.0-beta.5

package/src/adapters/copy-tree.js

@@ -578,17 +578,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                             ();

package/src/adapters/gemini/hooks.js

@@ -14,6 +14,7 @@
 // if a third harness with the same shape is ever added.
 const fs = require('node:fs');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { verifyHookCommands } = require('../hook-commands.js');
 const { mergeHooks } = require('../../helper/settings-merge.js');
 
@@ -103,7 +104,39 @@ function classifyClaudeGuardrails(claudeHooks      = {})
  * exists but fails to parse is a hard error, not silently treated as empty (this path merges
  * into content DoFlow does not own — a malformed-file work-around here risks losing it).
  */
-function planGeminiHooks({ config, sourceFile, sourceHooksDir, settingsFile, destinationHooksDir: declaredHooksDir, trusted = false, fsImpl = fs }      = {})      {
+/** Every regular, non-JSON file in the shipped scripts directory: what deployGeminiHooks copies. */
+function shippedScripts(scriptsDir     , fsImpl      = fs)           {
+  if (!scriptsDir || !fsImpl.existsSync(scriptsDir)) return [];
+  return fsImpl.readdirSync(scriptsDir)
+    .filter((name        ) => !name.endsWith('.json') && fsImpl.statSync(path.join(scriptsDir, name)).isFile());
+}
+
+/** DoFlow's record of a deployed hook script: the sha256 of its bytes. */
+function scriptFingerprint(bytes     )         { return crypto.createHash('sha256').update(bytes).digest('hex'); }
+
+/** The scripts beside the config that differ from the shipped source (or are absent), by name, and
+ * those among them a ledger row says were edited since DoFlow wrote them. A script with no row
+ * (an install from before scripts were recorded) is DoFlow's to refresh: the config deploy always
+ * overwrote it. `rows` are this harness's script rows: { target, fingerprint }. */
+function planHookScripts({ commands, sourceHooksDir, destinationHooksDir, rows = [], force = false, fsImpl = fs }     ) {
+  const sources = new Map                (commands.checks.map((check     ) => [check.script, check.file]                    ));
+  for (const name of shippedScripts(sourceHooksDir, fsImpl)) if (!sources.has(name)) sources.set(name, path.join(sourceHooksDir, name));
+  const stale           = [];
+  const edited           = [];
+  for (const [name, source] of sources) {
+    const target = path.join(destinationHooksDir, name);
+    if (fsImpl.existsSync(target)) {
+      const current = fsImpl.readFileSync(target);
+      if (current.equals(fsImpl.readFileSync(source))) continue;
+      const row = rows.find((item     ) => path.resolve(item.target) === path.resolve(target));
+      if (row && row.fingerprint !== scriptFingerprint(current) && !force) edited.push(name);
+    }
+    stale.push(name);
+  }
+  return { names: [...sources.keys()], stale, edited };
+}
+
+function planGeminiHooks({ config, sourceFile, sourceHooksDir, settingsFile, destinationHooksDir: declaredHooksDir, trusted = false, scriptRows = [], force = false, fsImpl = fs }      = {})      {
   let desired = config;
   try {
     if (!desired && sourceFile) desired = JSON.parse(fsImpl.readFileSync(sourceFile, 'utf8'));
@@ -124,20 +157,26 @@ function planGeminiHooks({ config, sourceFile, sourceHooksDir, settingsFile, des
 
   const mergedHooks = existing.hooks ? mergeHooks(existing.hooks, desired.hooks) : desired.hooks;
   const merged = { ...existing, hooks: mergedHooks };
-  const changed = JSON.stringify(existing.hooks) !== JSON.stringify(mergedHooks);
+  const configChanged = JSON.stringify(existing.hooks) !== JSON.stringify(mergedHooks);
   // Preferred: the declared hooks directory (harnesses.json "paths".hooksDirectory); the derived
   // sibling-of-settings fallback stays for direct callers passing raw inputs, and resolves to the
   // same location.
   const destinationHooksDir = declaredHooksDir || path.join(path.dirname(settingsFile), 'hooks');
+  // The scripts are deployed with the hooks key but are not part of it: a script whose bytes differ
+  // from the source is redeployed even when the key is already right.
+  const scripts = planHookScripts({ commands, sourceHooksDir, destinationHooksDir, rows: scriptRows, force, fsImpl });
+  if (scripts.edited.length) {
+    return { ok: false, status: 'conflict', settingsFile, existing, changes: [], commands,
+      errors: scripts.edited.map((name        ) => `Gemini hook script '${name}' was modified outside DoFlow`) };
+  }
+  const scriptsOnly = !configChanged && scripts.stale.length > 0;
+  const changed = configChanged || scriptsOnly;
   // The scripts deployGeminiHooks copies beside settings.json, so a backup of this change holds them too.
-  const shipped = sourceHooksDir && fsImpl.existsSync(sourceHooksDir)
-    ? fsImpl.readdirSync(sourceHooksDir).filter((name        ) => !name.endsWith('.json') && fsImpl.statSync(path.join(sourceHooksDir, name)).isFile())
-    : [];
   const companionTargets = [...new Set([
     ...commands.checks.map((check     ) => path.join(destinationHooksDir, check.script)),
-    ...shipped.map((name        ) => path.join(destinationHooksDir, name)),
+    ...shippedScripts(sourceHooksDir, fsImpl).map((name        ) => path.join(destinationHooksDir, name)),
   ])].sort();
-  return { ok: true, status: changed ? 'change' : 'unchanged', settingsFile, existing, merged,
+  return { ok: true, status: changed ? 'change' : 'unchanged', settingsFile, existing, merged, scriptsOnly, scriptNames: scripts.names,
     changes: changed ? [{ type: fsImpl.existsSync(settingsFile) ? 'update' : 'create', file: settingsFile, key: 'hooks' }] : [],
     errors: [], commands, trust: commands.trust, scriptsDir: sourceHooksDir, destinationHooksDir, companionTargets };
 }
@@ -145,14 +184,16 @@ function planGeminiHooks({ config, sourceFile, sourceHooksDir, settingsFile, des
 function deployGeminiHooks(plan     , { dryRun = false, fsImpl = fs }                                     = {})      {
   if (!plan.ok) return { ...plan, applied: false };
   if (dryRun || plan.status === 'unchanged') return { ...plan, applied: false };
-  fsImpl.mkdirSync(path.dirname(plan.settingsFile), { recursive: true });
-  const content = `${JSON.stringify(plan.merged, null, 2)}\n`;
-  const temporary = path.join(path.dirname(plan.settingsFile), `.${path.basename(plan.settingsFile)}.${process.pid}.${Date.now()}.tmp`);
-  try {
-    fsImpl.writeFileSync(temporary, content, { flag: 'wx' });
-    fsImpl.renameSync(temporary, plan.settingsFile);
-  } finally {
-    if (fsImpl.existsSync(temporary)) fsImpl.unlinkSync(temporary);
+  if (!plan.scriptsOnly) {
+    fsImpl.mkdirSync(path.dirname(plan.settingsFile), { recursive: true });
+    const content = `${JSON.stringify(plan.merged, null, 2)}\n`;
+    const temporary = path.join(path.dirname(plan.settingsFile), `.${path.basename(plan.settingsFile)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+      fsImpl.writeFileSync(temporary, content, { flag: 'wx' });
+      fsImpl.renameSync(temporary, plan.settingsFile);
+    } finally {
+      if (fsImpl.existsSync(temporary)) fsImpl.unlinkSync(temporary);
+    }
   }
   const deployed = new Set        ();
   for (const check of plan.commands.checks) {
@@ -207,4 +248,4 @@ function deployRemoveGeminiHooks(plan     , { dryRun = false, fsImpl = fs }
   return { ...plan, applied: true };
 }
 
-module.exports = { SUPPORTED_EVENTS, validateHooksConfig, classifyClaudeGuardrails, verifyHookCommands, planGeminiHooks, deployGeminiHooks, planRemoveGeminiHooks, deployRemoveGeminiHooks };
+module.exports = { SUPPORTED_EVENTS, validateHooksConfig, classifyClaudeGuardrails, verifyHookCommands, planGeminiHooks, deployGeminiHooks, scriptFingerprint, shippedScripts, planRemoveGeminiHooks, deployRemoveGeminiHooks };

package/src/adapters/gemini/index.js

@@ -9,7 +9,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor, resolveTransform } = require('../copy-tree.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
-const { planGeminiHooks, deployGeminiHooks, planRemoveGeminiHooks, deployRemoveGeminiHooks } = require('./hooks.js');
+const { planGeminiHooks, deployGeminiHooks, planRemoveGeminiHooks, deployRemoveGeminiHooks, scriptFingerprint } = require('./hooks.js');
 
 const MARKER_START = '<!-- doflow:start -->';
 const MARKER_END = '<!-- doflow:end -->';
@@ -229,17 +229,32 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     return assets.find((asset     ) => asset.id === 'guidance.core')?.id ?? assets[0]?.id;
   }
 
+  /** This scope's ledger rows for the hook scripts deployed beside settings.json. */
+  function scriptRows(ledger     , scope     ) {
+    return (ledger?.resources || []).filter((row     ) => row?.harness === 'gemini' && row.kind === 'hooks-script' && (!row.scope || row.scope === scope));
+  }
+
   /** Plan the hooks pseudo-component's single change (or none), mirroring the {changes, conflicts}
    * shape planCopyTreeAssets already returns so plan() can fold it in the same way. The hook
    * scripts directory beside settings.json is declared (paths.hooksDirectory); the merge/remove
-   * planning itself lives in ./hooks.ts. */
-  function planHooksChange({ removing, found, context, assets, fsImpl }     ) {
+   * planning itself lives in ./hooks.ts. A removal also releases the rows of the hook scripts. */
+  function planHooksChange({ removing, found, context, assets, ledger, scope, fsImpl }     ) {
+    const component = planHooksComponentChange({ removing, found, context, assets, ledger, scope, fsImpl });
+    if (!removing) return component;
+    const releases = scriptRows(ledger, scope).map((row     ) => ({ assetId: row.assetId, target: row.target, operation: 'remove',
+      ownershipIdentity: row.ownershipIdentity, kind: row.kind, identity: row.identity, projection: row.projection,
+      retained: true, retainedFor: [] }));
+    return { ...component, changes: [...component.changes, ...releases] };
+  }
+
+  function planHooksComponentChange({ removing, found, context, assets, ledger, scope, fsImpl }     ) {
     if (found.settings.error) return { changes: [], conflicts: [] };
     const hooksPlan = removing
       ? planRemoveGeminiHooks({ settingsFile: found.paths.settings, fsImpl })
       : (context.geminiHooksSourceFile
         ? planGeminiHooks({ sourceFile: context.geminiHooksSourceFile, sourceHooksDir: context.geminiHooksSourceDir,
-          settingsFile: found.paths.settings, destinationHooksDir: found.paths.hooksDirectory, trusted: context.hooksTrusted, fsImpl })
+          settingsFile: found.paths.settings, destinationHooksDir: found.paths.hooksDirectory, trusted: context.hooksTrusted,
+          scriptRows: scriptRows(ledger, scope), force: context.force === true, fsImpl })
         : null);
     if (hooksPlan && !hooksPlan.ok) return { changes: [], conflicts: hooksPlan.errors || [] };
     if (hooksPlan?.status !== 'change') return { changes: [], conflicts: [] };
@@ -270,7 +285,7 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     const copyTree = planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl });
     changes.push(...copyTree.changes); conflicts.push(...copyTree.conflicts);
     if (found.settings.error) conflicts.push(found.settings.error);
-    const hooks = planHooksChange({ removing, found, context, assets, fsImpl });
+    const hooks = planHooksChange({ removing, found, context, assets, ledger, scope, fsImpl });
     changes.push(...hooks.changes); conflicts.push(...hooks.conflicts);
     return {
       changes, conflicts, prerequisites: [], notices: copyTree.notices,
@@ -331,6 +346,37 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     removeCopyTreeAssets(changes, { fsImpl });
   }
 
+  /** Whether the hooks pseudo-component is on disk as the source declares it, with the resource that
+   * records it when so. Null status when the run carries no hooks source or settings.json is unreadable. */
+  function verifyHooksComponent({ found, assets, context, fsImpl }     ) {
+    if (!context.geminiHooksSourceFile || found.settings.error) return { hooksStatus: null, resources: [], conflicts: [] };
+    const hooksPlan = planGeminiHooks({ sourceFile: context.geminiHooksSourceFile, sourceHooksDir: context.geminiHooksSourceDir,
+      settingsFile: found.paths.settings, destinationHooksDir: found.paths.hooksDirectory, trusted: context.hooksTrusted, fsImpl });
+    const hooksStatus = hooksPlan.ok && hooksPlan.status === 'unchanged' ? 'managed' : (hooksPlan.ok ? 'missing' : 'conflict');
+    const resources = hooksStatus === 'managed' ? [{ assetId: hooksAssetId(assets), target: hooksPlan.settingsFile, ownershipIdentity: 'gemini:hooks',
+      fingerprint: fingerprint(hooksPlan.merged.hooks), sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'gemini-hooks' } },
+    ...hooksPlan.scriptNames.map((identity        ) => {
+      const target = path.join(hooksPlan.destinationHooksDir, identity);
+      return { assetId: hooksAssetId(assets), target, ownershipIdentity: `gemini:hooks-script:${identity}`, kind: 'hooks-script', identity,
+        fingerprint: scriptFingerprint(fs.readFileSync(target)), sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'gemini-hooks' } };
+    })] : [];
+    return { hooksStatus, resources, conflicts: hooksPlan.ok ? [] : (hooksPlan.errors || []) };
+  }
+
+  /** The hook front doors (IC-037): the hooks pseudo-component alone. */
+  function planHookDoors({ scope, scopeRoot, assets = [], discovery, context = {}, ledger, fsImpl = fs }     ) {
+    const found = discovery || discover({ scope, scopeRoot, context, fsImpl });
+    const hooks = planHooksChange({ removing: false, found, context, assets, ledger, scope, fsImpl });
+    return { changes: hooks.changes, conflicts: [...(found.settings.error ? [found.settings.error] : []), ...hooks.conflicts], prerequisites: [], notices: [] };
+  }
+
+  function verifyHookDoors({ scope, scopeRoot, assets = [], context = {}, fsImpl = fs }     ) {
+    const found = discover({ scope, scopeRoot, context, fsImpl });
+    const hooks = verifyHooksComponent({ found, assets, context, fsImpl });
+    const conflicts = [...(found.settings.error ? [found.settings.error] : []), ...hooks.conflicts];
+    return { ok: conflicts.length === 0 && hooks.hooksStatus !== 'conflict', resources: hooks.resources, statuses: { hooks: hooks.hooksStatus }, conflicts };
+  }
+
   function verify({ scope, scopeRoot, assets = [], context = {}, fsImpl = fs }     ) {
     const found = discover({ scope, scopeRoot, context, fsImpl });
     const resources = [];
@@ -339,23 +385,16 @@ function createGeminiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] }
     }
     const copyTree = verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl });
     resources.push(...copyTree.resources);
-    let hooksStatus = null; const conflicts = [...(found.settings.error ? [found.settings.error] : []), ...copyTree.conflicts];
-    if (context.geminiHooksSourceFile && !found.settings.error) {
-      const hooksPlan = planGeminiHooks({ sourceFile: context.geminiHooksSourceFile, sourceHooksDir: context.geminiHooksSourceDir,
-        settingsFile: found.paths.settings, destinationHooksDir: found.paths.hooksDirectory, trusted: context.hooksTrusted, fsImpl });
-      hooksStatus = hooksPlan.ok && hooksPlan.status === 'unchanged' ? 'managed' : (hooksPlan.ok ? 'missing' : 'conflict');
-      if (!hooksPlan.ok) conflicts.push(...(hooksPlan.errors || []));
-      if (hooksStatus === 'managed') {
-        resources.push({ assetId: hooksAssetId(assets), target: hooksPlan.settingsFile, ownershipIdentity: 'gemini:hooks',
-          fingerprint: fingerprint(hooksPlan.merged.hooks), sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'gemini-hooks' } });
-      }
-    }
+    const hooks = verifyHooksComponent({ found, assets, context, fsImpl });
+    resources.push(...hooks.resources);
+    const hooksStatus = hooks.hooksStatus;
+    const conflicts = [...(found.settings.error ? [found.settings.error] : []), ...copyTree.conflicts, ...hooks.conflicts];
     return { ok: !found.settings.error && copyTree.conflicts.length === 0 && hooksStatus !== 'conflict', resources,
       statuses: { settings: found.settings.error ? 'invalid' : 'supported', extensions: 'different', policies: policyStatuses(context.policies), copyTree: copyTree.statuses, hooks: hooksStatus },
       conflicts };
   }
 
-  return { nativePaths, discover, render, plan, apply, remove, verify };
+  return { nativePaths, discover, render, plan, apply, remove, verify, planHookDoors, verifyHookDoors };
 }
 
 const singleton = createGeminiAdapter();
@@ -385,6 +424,6 @@ module.exports = {
   MARKER_START, MARKER_END,
   nativePaths: singleton.nativePaths, discover: singleton.discover, render: singleton.render,
   managedInstruction, plan: singleton.plan, apply: singleton.apply, remove: singleton.remove,
-  verify: singleton.verify, planGeminiHooks, hookTrustFor,
+  verify: singleton.verify, planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors, planGeminiHooks, hookTrustFor,
   createGeminiAdapter,
 };

package/src/adapters/kiro/index.js

@@ -258,6 +258,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 +310,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 +318,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/pi/hooks.js

@@ -0,0 +1,119 @@
+'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) => fsImpl.existsSync(path.join(dir, command)));
+  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

@@ -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,
@@ -27,9 +25,11 @@ 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 { 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 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 +43,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;
   }
@@ -191,15 +191,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 +243,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 +282,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 +298,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/cli/commands/install.js

@@ -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; }
 

package/src/cli/commands/update.js

@@ -51,7 +51,7 @@ function cmdUpdate(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: 'update',
       force: o.force, permissions: o.permissions === true, statusline: o.statusline === true });
     if (!lifecycleView.plan.safe) { assertSafeRegistryPlan(lifecycleView); return; }
     printMcpSelection(lifecycleView, selection.sources, { requested: o.mcp, prefix: o.dryRun ? '[DRY]' : '[INFO]' });