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

package/src/adapters/opencode/{index.ts → index.js}

@@ -16,15 +16,15 @@
 // https://opencode.ai/docs/rules
 const fs = require('node:fs');
 const path = require('node:path');
-const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor, resolveTransform } = require('../copy-tree.ts');
-const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.ts');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor, resolveTransform } = require('../copy-tree.js');
+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.
-const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.ts');
-const { destructiveCommandGlobs } = require('../../helper/guardrails.ts');
-const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.ts');
+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 HARNESS = 'opencode';
 /**
@@ -48,7 +48,7 @@ const MCP_RENDERER = 'opencode-mcp';
  * historical shape.
  */
 function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } = {}) {
-  function nativePaths({ scope, scopeRoot, homeDir }: any) {
+  function nativePaths({ scope, scopeRoot, homeDir }     ) {
     return resolveHarnessPaths(declaredPaths, { scope, scopeRoot, homeDir });
   }
 
@@ -57,20 +57,20 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
    * `opencode.json` are read from the repo root, but the skills tree is namespaced under
    * `.opencode/` per design.md's native-surfaces table. Global scope has no such split —
    * `~/.config/opencode` already IS the skills root. Declared as `treeRoot` in harnesses.json. */
-  function copyTreeConfigDir(paths: any) {
+  function copyTreeConfigDir(paths     ) {
     return paths.treeRoot;
   }
 
   /** Agents live under `.opencode/agents/` at project scope and `~/.config/opencode/agents/`
    * globally — a different root from the skills tree in both scopes, so they get their own
    * destination resolution rather than reusing copyTreeConfigDir. Declared as `agentsDirectory`. */
-  function agentsDestDir(paths: any) {
+  function agentsDestDir(paths     ) {
     return paths.agentsDirectory;
   }
 
   /** Discovery keeps opencode.json as plan read it (`mcpSnapshot`), which verify compares against,
    * and reports the servers DoFlow owns in its `mcp` object now (`mcpOwned`). */
-  function discover({ scope, scopeRoot, mcp = [], mcpAdoptable = [], ledger, context = {}, fsImpl = fs }: any) {
+  function discover({ scope, scopeRoot, mcp = [], mcpAdoptable = [], ledger, context = {}, fsImpl = fs }     ) {
     const paths = nativePaths({ scope, scopeRoot, homeDir: context.homeDir });
     const instruction = fsImpl.existsSync(paths.instruction) ? fsImpl.readFileSync(paths.instruction, 'utf8') : null;
     const entries = mcpEntriesInput({ paths, mcp, mcpAdoptable, ledger });
@@ -81,7 +81,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     return { paths, instruction, config: readJson(paths.config, { fsImpl }), mcpSnapshot, mcpOwned: ownedMcpIds({ ...entries, files: mcpSnapshot }), mcpConfigured };
   }
 
-  function render({ content = '' }: any = {}) {
+  function render({ content = '' }      = {}) {
     return `${MARKER_START}\n${String(content).trimEnd()}\n${MARKER_END}\n`;
   }
 
@@ -90,17 +90,17 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
    * every config it discovers — replacing would silently drop a user's own entries. Skills are
    * deliberately absent here: they are a materialised directory now, discovered natively, not a
    * registered path. The `mcp` object is left to the entry changes. */
-  function mergeConfig(existing: any) {
+  function mergeConfig(existing     ) {
     const next = { ...(existing || {}) };
-    const union = (current: any, add: any) => [...new Set([...(Array.isArray(current) ? current : []), ...add])];
+    const union = (current     , add     ) => [...new Set([...(Array.isArray(current) ? current : []), ...add])];
     next.instructions = union(next.instructions, [INSTRUCTION_FILE]);
     return next;
   }
 
   /** Remove only what mergeConfig added, leaving every user key and every unrelated array entry. */
-  function unmergeConfig(existing: any) {
+  function unmergeConfig(existing     ) {
     const next = { ...(existing || {}) };
-    const without = (current: any, drop: any) => (Array.isArray(current) ? current.filter((v) => !drop.includes(v)) : []);
+    const without = (current     , drop     ) => (Array.isArray(current) ? current.filter((v) => !drop.includes(v)) : []);
     next.instructions = without(next.instructions, [INSTRUCTION_FILE]);
     if (!next.instructions.length) delete next.instructions;
     return next;
@@ -116,12 +116,12 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
    * comment-free glob we can re-derive) are touched; a user's own bash rules survive untouched.
    * Entries are namespaced by value, not by key, so ownership is decided by re-deriving the list
    * from the single authored source rather than by trusting whatever happens to be present. */
-  function guardrailBashRules(context: any) {
+  function guardrailBashRules(context     ) {
     const globs = destructiveCommandGlobs({ repoRoot: context.repoRoot });
-    return Object.fromEntries(globs.map((glob: any) => [glob, 'deny']));
+    return Object.fromEntries(globs.map((glob     ) => [glob, 'deny']));
   }
 
-  function mergeGuardrails(existing: any, context: any) {
+  function mergeGuardrails(existing     , context     ) {
     const next = { ...(existing || {}) };
     const bash = { ...guardrailBashRules(context), ...((next.permission?.bash ?? {})) };
     // Keep user rules, but make sure ours win for identical globs (they are the stricter value).
@@ -129,7 +129,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     return next;
   }
 
-  function stripGuardrails(existing: any, context: any) {
+  function stripGuardrails(existing     , context     ) {
     if (!existing?.permission?.bash) return existing;
     const ours = new Set(Object.keys(guardrailBashRules(context)));
     const bash = Object.fromEntries(Object.entries(existing.permission.bash).filter(([glob]) => !ours.has(glob)));
@@ -141,7 +141,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     return rest;
   }
 
-  function managedInstruction(existing: any, rendered: any) {
+  function managedInstruction(existing     , rendered     ) {
     if (existing === null) return { ok: true, operation: 'create', content: rendered };
     const start = existing.indexOf(MARKER_START);
     const end = existing.indexOf(MARKER_END);
@@ -153,7 +153,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
 
   /** Strip DoFlow's span, leaving the rest of a shared AGENTS.md intact. Returns null when there is
    * nothing to do, so remove() can skip the write entirely. */
-  function strippedInstruction(existing: any) {
+  function strippedInstruction(existing     ) {
     if (typeof existing !== 'string') return null;
     const start = existing.indexOf(MARKER_START);
     const end = existing.indexOf(MARKER_END);
@@ -168,11 +168,11 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   /** `agents.shared` projects onto OpenCode through its own renderer name (its frontmatter is
    * transformed into OpenCode's markdown-agent vocabulary) but materialises with exactly the same
    * engine and change records as every other copy-tree asset. */
-  function opencodeTreeAssets(assets: any) {
-    return [...copyTreeAssets(assets), ...(assets || []).filter((asset: any) => asset.renderer === 'opencode-agents')];
+  function opencodeTreeAssets(assets     ) {
+    return [...copyTreeAssets(assets), ...(assets || []).filter((asset     ) => asset.renderer === 'opencode-agents')];
   }
 
-  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl = fs }: any) {
+  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl = fs }     ) {
     const paths = nativePaths({ scope, scopeRoot, homeDir: context.homeDir });
     const treeConfigDir = copyTreeConfigDir(paths);
     const changes = [];
@@ -190,10 +190,10 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
         // is never deleted on removal, forced or not.
         force: !removing && context?.force === true, });
       treeResults.push(result);
-      conflicts.push(...result.conflicts.map((reason: any) => `${asset.id}: ${reason}`));
+      conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       // A hand-edited file at a path DoFlow no longer writes is the user's: it stays, only its
       // ownership row is released.
-      notices.push(...result.kept.map((item: any) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
+      notices.push(...result.kept.map((item     ) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
       for (const change of result.changes) {
         changes.push({
           assetId: asset.id, target: change.target, source: change.source, operation: change.operation,
@@ -209,7 +209,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     return { changes, conflicts, notices: [...siblingReplacedNotices(treeResults), ...notices] };
   }
 
-  function applyCopyTreeAssets(changes: any, { fsImpl = fs }: any = {}) {
+  function applyCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
     let applied = 0;
     const grouped = new Map();
     for (const change of changes) {
@@ -224,13 +224,13 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     return applied;
   }
 
-  function removeCopyTreeAssets(changes: any, { fsImpl = fs }: any = {}) {
-    const treeChanges = changes.filter((change: any) => change.kind === 'copy-tree-file' && change.operation === 'remove' && !change.retained)
-      .map((change: any) => ({ relPath: change.identity, target: change.target, operation: 'remove', fingerprint: change.fingerprint, pruneGuard: change.pruneGuard }));
+  function removeCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
+    const treeChanges = changes.filter((change     ) => change.kind === 'copy-tree-file' && change.operation === 'remove' && !change.retained)
+      .map((change     ) => ({ relPath: change.identity, target: change.target, operation: 'remove', fingerprint: change.fingerprint, pruneGuard: change.pruneGuard }));
     return removeTree({ changes: treeChanges, fsImpl }).removed;
   }
 
-  function verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl = fs }: any) {
+  function verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl = fs }     ) {
     const paths = nativePaths({ scope, scopeRoot, homeDir: context.homeDir });
     const treeConfigDir = copyTreeConfigDir(paths);
     const statuses = [];
@@ -240,7 +240,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
       const destDir = asset.renderer === 'opencode-agents' ? agentsDestDir(paths) : sharedTreeDestDir(paths.root, asset.nativeDir) ?? copyTreeDestDir(treeConfigDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'OpenCode');
       const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: asset.transform, plannedWrites: context?.plannedWrites });
-      conflicts.push(...result.conflicts.map((reason: any) => `${asset.id}: ${reason}`));
+      conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({
           assetId: asset.id, target: resource.target, ownershipIdentity: `doflow:${HARNESS}:copy-tree:${asset.id}:${resource.relPath}`,
@@ -259,45 +259,45 @@ 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.ts#hooksAssetId and src/adapters/kiro/index.ts#pseudoAssetId use. The
+   * src/adapters/gemini/index.js#hooksAssetId and src/adapters/kiro/index.js#pseudoAssetId use. 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: any) {
-    return assets.find((asset: any) => asset.capability === 'instructions')?.id ?? assets[0]?.id;
+  function pseudoAssetId(assets     ) {
+    return assets.find((asset     ) => asset.capability === 'instructions')?.id ?? assets[0]?.id;
   }
 
   // ---- MCP entries (opencode.json `mcp`) ----
 
   /** OpenCode's own server shape: a local server whose command and arguments form one array. */
-  function buildServerEntry(server: any) {
+  function buildServerEntry(server     ) {
     return { type: 'local', command: [server.command, ...(server.args || [])], enabled: true };
   }
 
-  function ownershipIdentity(id: any) { return `doflow:${HARNESS}:mcp-server:${id}`; }
+  function ownershipIdentity(id     ) { return `doflow:${HARNESS}:mcp-server:${id}`; }
 
   /** Everything the shared entry-ownership rules (../mcp-entries.ts) need from this adapter. */
-  function mcpEntriesInput({ paths, mcp = [], mcpAdoptable = [], ledger, assets = [] }: any) {
-    const rendered = (servers: any) => servers.map((server: any) => ({ id: server.id, entry: buildServerEntry(server) }));
-    const rows = (ledger?.resources || []).filter((row: any) => row.kind === 'mcp-server');
+  function mcpEntriesInput({ paths, mcp = [], mcpAdoptable = [], ledger, assets = [] }     ) {
+    const rendered = (servers     ) => servers.map((server     ) => ({ id: server.id, entry: buildServerEntry(server) }));
+    const rows = (ledger?.resources || []).filter((row     ) => row.kind === 'mcp-server');
     return {
       file: paths.config, selected: rendered(mcp), adoptable: rendered(mcpAdoptable),
-      ownRows: rows.filter((row: any) => row.harness === HARNESS).map((row: any) => ({
+      ownRows: rows.filter((row     ) => row.harness === HARNESS).map((row     ) => ({
         identity: row.identity, target: row.target, fingerprint: row.fingerprint ?? null, ownershipIdentity: row.ownershipIdentity, legacy: false,
       })),
-      foreignRows: rows.filter((row: any) => row.harness !== HARNESS).map((row: any) => ({ harness: row.harness, identity: row.identity, target: row.target })),
+      foreignRows: rows.filter((row     ) => row.harness !== HARNESS).map((row     ) => ({ harness: row.harness, identity: row.identity, target: row.target })),
       identityFor: ownershipIdentity, assetId: pseudoAssetId(assets), renderer: MCP_RENDERER, label: 'OpenCode MCP',
     };
   }
 
   /** opencode.json cannot be edited safely while removing: its registration row is released with
    * the entry rows, so the removal completes and leaves the file as it is. */
-  function releasedConfigRow({ assets, paths, ledger }: any) {
-    const owned = (ledger?.resources || []).some((row: any) => row.harness === HARNESS && row.ownershipIdentity === `${HARNESS}:config:registration` && row.target === paths.config);
+  function releasedConfigRow({ assets, paths, ledger }     ) {
+    const owned = (ledger?.resources || []).some((row     ) => row.harness === HARNESS && row.ownershipIdentity === `${HARNESS}:config:registration` && row.target === paths.config);
     return owned ? [{ assetId: pseudoAssetId(assets), target: paths.config, operation: 'remove', release: true,
       ownershipIdentity: `${HARNESS}:config:registration`, harness: HARNESS, projection: { renderer: 'opencode-config' } }] : [];
   }
 
-  function plan({ scope, scopeRoot, assets = [], mcp = [], mcpAdoptable = [], discovery, context = {}, ledger, fsImpl = fs }: any) {
+  function plan({ scope, scopeRoot, assets = [], mcp = [], mcpAdoptable = [], discovery, context = {}, ledger, fsImpl = fs }     ) {
     const found = discovery || discover({ scope, scopeRoot, mcp, mcpAdoptable, ledger, context, fsImpl });
     const changes = [];
     const conflicts = [];
@@ -306,7 +306,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     // below, under a fixed reason that never quotes the file.
     const configReadable = found.mcpSnapshot[found.paths.config].ok;
 
-    const guidance = assets.find((asset: any) => asset.capability === 'instructions');
+    const guidance = assets.find((asset     ) => asset.capability === 'instructions');
     if (guidance) {
       const rendered = render({ content: fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8') });
       const outcome = removing
@@ -333,7 +333,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
           // Tagged 'remove' during a remove operation (rather than always 'update'/'create') so this
           // adapter's own apply()/remove() dispatch — which routes strictly on `operation` — writes
           // the unmerged file during removal instead of silently skipping it (the same fix
-          // src/adapters/copilot/index.ts's analogous mcp-merge change already carries).
+          // src/adapters/copilot/index.js's analogous mcp-merge change already carries).
           operation: removing ? 'remove' : (found.config.exists ? 'update' : 'create'), content: `${JSON.stringify(next, null, 2)}\n`,
           ownershipIdentity: `${HARNESS}:config:registration`, fingerprint: fingerprint(next),
           harness: HARNESS, projection: { renderer: 'opencode-config' } });
@@ -355,14 +355,14 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     return { changes, conflicts, notices: [...copyTree.notices, ...mcpPlan.notices], paths: found.paths };
   }
 
-  function writeChange(change: any, fsImpl: any) {
+  function writeChange(change     , fsImpl     ) {
     fsImpl.mkdirSync(path.dirname(change.target), { recursive: true });
     fsImpl.writeFileSync(change.target, change.content, 'utf8');
   }
 
   // The config change is written first; the entry changes then go to a fresh read of the same file,
   // so they apply on top of it.
-  function apply({ changes = [], fsImpl = fs }: any) {
+  function apply({ changes = [], fsImpl = fs }     ) {
     let applied = 0;
     for (const change of changes) {
       if (change.operation === 'remove') continue;
@@ -378,7 +378,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     return { applied };
   }
 
-  function remove({ changes = [], fsImpl = fs }: any) {
+  function remove({ changes = [], fsImpl = fs }     ) {
     let removed = 0;
     for (const change of changes) {
       if (change.operation !== 'remove') continue;
@@ -392,13 +392,13 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
     return { removed };
   }
 
-  function verify({ scope, scopeRoot, assets = [], mcp = [], mcpAdoptable = [], discovery, ledger, operation, context = {}, fsImpl = fs }: any) {
+  function verify({ scope, scopeRoot, assets = [], mcp = [], mcpAdoptable = [], discovery, ledger, operation, context = {}, fsImpl = fs }     ) {
     const found = discover({ scope, scopeRoot, mcp, mcpAdoptable, ledger, context, fsImpl });
     const removing = (operation ?? context.operation) === 'remove';
     const statuses = [];
     const resources = [];
     const conflicts = [];
-    const instructionsAssetId = assets.find((asset: any) => asset.capability === 'instructions')?.id ?? pseudoAssetId(assets);
+    const instructionsAssetId = assets.find((asset     ) => asset.capability === 'instructions')?.id ?? pseudoAssetId(assets);
 
     const hasSection = typeof found.instruction === 'string'
       && found.instruction.includes(MARKER_START) && found.instruction.includes(MARKER_END);
@@ -445,7 +445,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
 
     const copyTree = verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl });
     resources.push(...copyTree.resources);
-    statuses.push(...copyTree.statuses.map((status: any) => ({ harness: HARNESS, ...status })));
+    statuses.push(...copyTree.statuses.map((status     ) => ({ harness: HARNESS, ...status })));
     conflicts.push(...copyTree.conflicts);
 
     return { ok: conflicts.length === 0 && !statuses.some((s) => s.status === 'invalid' || s.status === 'conflict'), resources, statuses, conflicts };

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