@pieai/pro-gov 0.3.11 → 0.3.13

package/dist/cli.js

@@ -79,7 +79,14 @@ function createNpxSkillsMaintenancePlan(options) {
   cpSync(options.npxRoot, tempRoot, { recursive: true, dereference: false });
   const command2 = buildNpxCommand(options);
   const runner = options.runner ?? defaultRunner;
-  const result = runner({ command: command2, cwd: tempRoot });
+  const timeoutMs = options.timeoutMs ?? 3e5;
+  const result = runner({ command: command2, cwd: tempRoot, timeoutMs });
+  if (result.timedOut) {
+    throw new Error(`npx skills ${options.operation} timed out after ${timeoutMs}ms`);
+  }
+  if (result.status === null && result.signal) {
+    throw new Error(`npx skills ${options.operation} terminated by ${result.signal}`);
+  }
   if (result.status !== 0) {
     throw new Error(`npx skills ${options.operation} failed with exit code ${result.status}`);
   }
@@ -128,12 +135,18 @@ function buildNpxCommand(options) {
   if (options.skill) command2.push(options.skill);
   return command2;
 }
-function defaultRunner({ command: command2, cwd }) {
-  const result = spawnSync(command2[0] ?? "npx", command2.slice(1), { cwd, encoding: "utf8" });
+function defaultRunner({ command: command2, cwd, timeoutMs }) {
+  const result = spawnSync(command2[0] ?? "npx", command2.slice(1), {
+    cwd,
+    encoding: "utf8",
+    timeout: timeoutMs
+  });
   return {
     status: result.status,
     stdout: result.stdout,
-    stderr: result.stderr
+    stderr: result.stderr,
+    signal: result.signal,
+    timedOut: result.error?.code === "ETIMEDOUT"
   };
 }
 function snapshotFiles(root) {
@@ -536,8 +549,229 @@ function resolveSafePath(root, sourcePath) {
 }
 
 // src/asset-targets/apply.ts
-import { existsSync as existsSync7, lstatSync as lstatSync2, mkdirSync as mkdirSync2, realpathSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname as dirname3, join as join7, relative as relative4, resolve } from "node:path";
+import {
+  existsSync as existsSync8,
+  lstatSync as lstatSync3,
+  mkdirSync as mkdirSync2,
+  readlinkSync as readlinkSync2,
+  realpathSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { dirname as dirname4, join as join8, relative as relative4, resolve as resolve2 } from "node:path";
+
+// src/asset-targets/install-plan.ts
+import { existsSync as existsSync7, lstatSync as lstatSync2, readFileSync as readFileSync4, readlinkSync } from "node:fs";
+import { basename, dirname as dirname3, join as join7, resolve } from "node:path";
+function createAssetInstallPlan(options) {
+  const placement = options.placement ?? "registry";
+  const assetsById = new Map(options.registry.assets.map((asset) => [asset.id, asset]));
+  const bundlesById = new Map(options.bundles.map((bundle) => [bundle.id, bundle]));
+  const assetIds = resolveBundleAssetIds(options.bundleIds, bundlesById);
+  const assets = assetIds.map((assetId) => {
+    const asset = assetsById.get(assetId);
+    if (!asset) throw new Error(`Unknown asset id in bundle: ${assetId}`);
+    if (asset.kind === "skill" && !asset.hosts.includes(options.host)) {
+      throw new Error(`Asset ${assetId} does not support host ${options.host}`);
+    }
+    return asset;
+  });
+  const lockEntries = createAgentAssetLockEntries(options.registry, options.agentAssetsDir, assetIds);
+  const managedEntries = readManagedEntries(options.targetDir);
+  const managedTargets = new Set(managedEntries.map((entry) => entry.targetPath));
+  const assetActions = assets.map(
+    (asset) => createAssetAction(asset, options.agentAssetsDir, options.targetDir, options.host, placement, managedTargets)
+  );
+  const manifest = {
+    schemaVersion: 1,
+    host: options.host,
+    placement,
+    bundleIds: [...options.bundleIds],
+    assetIds
+  };
+  const lockfile = {
+    schemaVersion: 1,
+    host: options.host,
+    placement,
+    bundleIds: [...options.bundleIds],
+    assets: lockEntries.map((entry) => {
+      const action = assetActions.find((candidate) => "assetId" in candidate && candidate.assetId === entry.id);
+      return {
+        ...entry,
+        targetPath: action && "targetPath" in action ? action.targetPath : ""
+      };
+    })
+  };
+  const writeActions = [
+    {
+      type: "write-file",
+      targetPath: ".pro-gov/assets.json",
+      content: `${JSON.stringify(manifest, null, 2)}
+`
+    },
+    {
+      type: "write-file",
+      targetPath: ".pro-gov/assets.lock.json",
+      content: `${JSON.stringify(lockfile, null, 2)}
+`
+    }
+  ];
+  const expectedTargetPaths = new Set(
+    assetActions.filter((action) => "assetId" in action).map((action) => action.targetPath)
+  );
+  const removalActions = createRemovalActions(
+    options.targetDir,
+    options.agentAssetsDir,
+    managedEntries,
+    expectedTargetPaths
+  );
+  return {
+    schemaVersion: 1,
+    dryRun: true,
+    targetDir: options.targetDir,
+    host: options.host,
+    placement,
+    bundleIds: [...options.bundleIds],
+    assetIds,
+    actions: [
+      ...createDirectoryActions([...assetActions, ...writeActions]),
+      ...removalActions,
+      ...assetActions,
+      ...writeActions
+    ]
+  };
+}
+function resolveBundleAssetIds(bundleIds, bundlesById) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const bundleId of bundleIds) {
+    const bundle = bundlesById.get(bundleId);
+    if (!bundle) throw new Error(`Unknown bundle id: ${bundleId}`);
+    for (const assetId of bundle.assets) {
+      ids.add(assetId);
+    }
+  }
+  return [...ids].sort();
+}
+function createAssetAction(asset, agentAssetsDir, targetDir, host, placement, managedTargets) {
+  if (asset.kind === "skill" && asset.defaultScope === "user") {
+    throw new Error(
+      `User-scoped asset ${asset.id} must be linked at the user level, not installed into a project target.`
+    );
+  }
+  const sourcePath = join7(agentAssetsDir, asset.sourcePath);
+  const targetPath = resolveHostTargetPath(asset, host, placement);
+  const targetAbsolutePath = join7(targetDir, targetPath);
+  const targetExists = pathExistsEvenIfDanglingSymlink2(targetAbsolutePath);
+  if (targetExists) {
+    const stats = lstatSync2(targetAbsolutePath);
+    if (stats.isSymbolicLink() && managedTargets.has(targetPath)) {
+      return {
+        type: "update-symlink",
+        assetId: asset.id,
+        sourcePath,
+        targetPath
+      };
+    }
+    throw new Error(`Refusing to overwrite unmanaged target: ${targetPath}`);
+  }
+  return {
+    type: "symlink",
+    assetId: asset.id,
+    sourcePath,
+    targetPath
+  };
+}
+function resolveHostTargetPath(asset, host, placement) {
+  if (asset.kind === "skill") {
+    const effectivePlacement = resolveSkillPlacement(asset, placement);
+    if (host === "claude-code") {
+      if (placement === "manual") {
+        throw new Error("Manual skill placement is only supported for .agents hosts");
+      }
+      return `.claude/skills/${basename(asset.sourcePath)}`;
+    }
+    if (effectivePlacement === "manual") {
+      return `.agents/manual-skills/${basename(asset.sourcePath)}`;
+    }
+    return `.agents/skills/${basename(asset.sourcePath)}`;
+  }
+  if (asset.kind === "rule") {
+    return `.pro-gov/agent-assets/rules/${basename(asset.sourcePath)}`;
+  }
+  return `.pro-gov/agent-assets/commands/${basename(asset.sourcePath)}`;
+}
+function resolveSkillPlacement(asset, placement) {
+  if (placement !== "registry") return placement;
+  return asset.defaultPlacement ?? "auto";
+}
+function createDirectoryActions(actions) {
+  const directories = /* @__PURE__ */ new Set();
+  for (const action of actions) {
+    if (action.type === "create-dir") continue;
+    const directory = dirname3(action.targetPath);
+    if (directory !== ".") directories.add(directory);
+  }
+  return [...directories].sort().map((targetPath) => ({ type: "create-dir", targetPath }));
+}
+function readManagedEntries(targetDir) {
+  const lockfilePath = join7(targetDir, ".pro-gov/assets.lock.json");
+  if (!existsSync7(lockfilePath)) return [];
+  try {
+    const lockfile = JSON.parse(readFileSync4(lockfilePath, "utf8"));
+    return (lockfile.assets ?? []).filter(
+      (entry) => typeof entry.id === "string" && typeof entry.sourcePath === "string" && typeof entry.targetPath === "string"
+    );
+  } catch {
+    return [];
+  }
+}
+function createRemovalActions(targetDir, agentAssetsDir, managedEntries, expectedTargetPaths) {
+  const actions = [];
+  for (const entry of managedEntries) {
+    if (expectedTargetPaths.has(entry.targetPath)) continue;
+    if (!isManagedAssetTargetPath(entry.targetPath)) {
+      throw new Error(`Refusing to remove managed asset outside supported roots: ${entry.targetPath}`);
+    }
+    const targetAbsolutePath = join7(targetDir, entry.targetPath);
+    if (!pathExistsEvenIfDanglingSymlink2(targetAbsolutePath)) continue;
+    const stats = lstatSync2(targetAbsolutePath);
+    if (!stats.isSymbolicLink()) {
+      throw new Error(`Refusing to remove path that is no longer a managed symlink: ${entry.targetPath}`);
+    }
+    const expectedSourcePath = join7(agentAssetsDir, entry.sourcePath);
+    const actualSourcePath = resolve(dirname3(targetAbsolutePath), readlinkSync(targetAbsolutePath));
+    if (actualSourcePath !== resolve(expectedSourcePath)) {
+      throw new Error(`Refusing to remove managed symlink with changed target: ${entry.targetPath}`);
+    }
+    actions.push({
+      type: "remove-symlink",
+      assetId: entry.id,
+      expectedSourcePath,
+      targetPath: entry.targetPath
+    });
+  }
+  return actions.sort((a, b) => a.targetPath.localeCompare(b.targetPath));
+}
+function isManagedAssetTargetPath(path) {
+  return [
+    ".agents/skills/",
+    ".agents/manual-skills/",
+    ".claude/skills/",
+    ".pro-gov/agent-assets/rules/",
+    ".pro-gov/agent-assets/commands/"
+  ].some((prefix) => path.startsWith(prefix));
+}
+function pathExistsEvenIfDanglingSymlink2(path) {
+  try {
+    lstatSync2(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/asset-targets/apply.ts
 function applyAssetInstallPlan(plan) {
   const appliedActions = [];
   for (const action of plan.actions) {
@@ -547,52 +781,71 @@ function applyAssetInstallPlan(plan) {
   return { appliedActions };
 }
 function applyAction(targetDir, action) {
-  const targetAbsolutePath = join7(targetDir, action.targetPath);
+  const targetAbsolutePath = join8(targetDir, action.targetPath);
+  if (action.type === "remove-symlink") {
+    removeManagedSymlink(targetAbsolutePath, action);
+    return;
+  }
   if (action.type === "create-dir") {
     mkdirSync2(targetAbsolutePath, { recursive: true });
     return;
   }
   if (action.type === "write-file") {
-    mkdirSync2(dirname3(targetAbsolutePath), { recursive: true });
+    mkdirSync2(dirname4(targetAbsolutePath), { recursive: true });
     writeFileSync(targetAbsolutePath, action.content);
     return;
   }
-  mkdirSync2(dirname3(targetAbsolutePath), { recursive: true });
-  const sourceAbsolutePath = resolve(action.sourcePath);
-  const symlinkTarget = relative4(realpathSync(dirname3(targetAbsolutePath)), realpathSync(sourceAbsolutePath)) || ".";
+  mkdirSync2(dirname4(targetAbsolutePath), { recursive: true });
+  const sourceAbsolutePath = resolve2(action.sourcePath);
+  const symlinkTarget = relative4(realpathSync(dirname4(targetAbsolutePath)), realpathSync(sourceAbsolutePath)) || ".";
   if (action.type === "symlink") {
-    if (pathExistsEvenIfDanglingSymlink2(targetAbsolutePath)) {
+    if (pathExistsEvenIfDanglingSymlink3(targetAbsolutePath)) {
       throw new Error(`Refusing to overwrite unmanaged target: ${action.targetPath}`);
     }
     symlinkSync(symlinkTarget, targetAbsolutePath);
     return;
   }
-  if (!pathExistsEvenIfDanglingSymlink2(targetAbsolutePath)) {
+  if (!pathExistsEvenIfDanglingSymlink3(targetAbsolutePath)) {
     symlinkSync(symlinkTarget, targetAbsolutePath);
     return;
   }
-  const stats = lstatSync2(targetAbsolutePath);
+  const stats = lstatSync3(targetAbsolutePath);
   if (!stats.isSymbolicLink()) {
     throw new Error(`Refusing to overwrite unmanaged target: ${action.targetPath}`);
   }
   unlinkSync(targetAbsolutePath);
   symlinkSync(symlinkTarget, targetAbsolutePath);
 }
-function pathExistsEvenIfDanglingSymlink2(path) {
+function removeManagedSymlink(targetAbsolutePath, action) {
+  if (!isManagedAssetTargetPath(action.targetPath)) {
+    throw new Error(`Refusing to remove managed asset outside supported roots: ${action.targetPath}`);
+  }
+  if (!pathExistsEvenIfDanglingSymlink3(targetAbsolutePath)) return;
+  const stats = lstatSync3(targetAbsolutePath);
+  if (!stats.isSymbolicLink()) {
+    throw new Error(`Refusing to remove path that is no longer a managed symlink: ${action.targetPath}`);
+  }
+  const actualSourcePath = resolve2(dirname4(targetAbsolutePath), readlinkSync2(targetAbsolutePath));
+  if (actualSourcePath !== resolve2(action.expectedSourcePath)) {
+    throw new Error(`Refusing to remove managed symlink with changed target: ${action.targetPath}`);
+  }
+  unlinkSync(targetAbsolutePath);
+}
+function pathExistsEvenIfDanglingSymlink3(path) {
   try {
-    lstatSync2(path);
+    lstatSync3(path);
     return true;
   } catch {
-    return existsSync7(path);
+    return existsSync8(path);
   }
 }
 
 // src/asset-targets/check.ts
-import { existsSync as existsSync8, lstatSync as lstatSync3, readFileSync as readFileSync4 } from "node:fs";
-import { basename, join as join8 } from "node:path";
+import { existsSync as existsSync9, lstatSync as lstatSync4, readFileSync as readFileSync5 } from "node:fs";
+import { basename as basename2, join as join9 } from "node:path";
 function checkInstalledAssets(options) {
-  const lockfilePath = join8(options.targetDir, ".pro-gov/assets.lock.json");
-  if (!existsSync8(lockfilePath)) {
+  const lockfilePath = join9(options.targetDir, ".pro-gov/assets.lock.json");
+  if (!existsSync9(lockfilePath)) {
     return {
       targetDir: options.targetDir,
       issues: [
@@ -604,12 +857,12 @@ function checkInstalledAssets(options) {
     };
   }
   const registryById = new Map(options.registry.assets.map((asset) => [asset.id, asset]));
-  const lockfile = JSON.parse(readFileSync4(lockfilePath, "utf8"));
+  const lockfile = JSON.parse(readFileSync5(lockfilePath, "utf8"));
   const issues = [];
   const strictRegistry = options.strictRegistry ?? false;
   for (const entry of lockfile.assets ?? []) {
     const asset = registryById.get(entry.id);
-    const targetAbsolutePath = join8(options.targetDir, entry.targetPath);
+    const targetAbsolutePath = join9(options.targetDir, entry.targetPath);
     if (!asset && strictRegistry) {
       issues.push({
         type: "unknown-asset",
@@ -636,7 +889,7 @@ function checkInstalledAssets(options) {
         issues.push(placementDriftIssue);
       }
     }
-    if (!pathExistsEvenIfDanglingSymlink3(targetAbsolutePath)) {
+    if (!pathExistsEvenIfDanglingSymlink4(targetAbsolutePath)) {
       issues.push({
         type: "missing-target",
         id: entry.id,
@@ -645,7 +898,7 @@ function checkInstalledAssets(options) {
       });
       continue;
     }
-    const targetStats = lstatSync3(targetAbsolutePath);
+    const targetStats = lstatSync4(targetAbsolutePath);
     if (!targetStats.isSymbolicLink()) {
       issues.push({
         type: "unmanaged-conflict",
@@ -655,7 +908,7 @@ function checkInstalledAssets(options) {
       });
       continue;
     }
-    if (!existsSync8(targetAbsolutePath)) {
+    if (!existsSync9(targetAbsolutePath)) {
       issues.push({
         type: "dangling-symlink",
         id: entry.id,
@@ -675,8 +928,8 @@ function checkInstalledAssets(options) {
       });
     }
     if (!asset || !strictRegistry) continue;
-    const sourceAbsolutePath = join8(options.agentAssetsDir, asset.sourcePath);
-    if (!existsSync8(sourceAbsolutePath)) {
+    const sourceAbsolutePath = join9(options.agentAssetsDir, asset.sourcePath);
+    if (!existsSync9(sourceAbsolutePath)) {
       issues.push({
         type: "missing-source",
         id: entry.id,
@@ -714,10 +967,10 @@ function checkDuplicateSkillPlacements(targetDir, registry) {
   const issues = [];
   for (const asset of registry.assets) {
     if (asset.kind !== "skill") continue;
-    const skillName = basename(asset.sourcePath);
+    const skillName = basename2(asset.sourcePath);
     const autoPath = `.agents/skills/${skillName}`;
     const manualPath = `.agents/manual-skills/${skillName}`;
-    if (pathExistsEvenIfDanglingSymlink3(join8(targetDir, autoPath)) && pathExistsEvenIfDanglingSymlink3(join8(targetDir, manualPath))) {
+    if (pathExistsEvenIfDanglingSymlink4(join9(targetDir, autoPath)) && pathExistsEvenIfDanglingSymlink4(join9(targetDir, manualPath))) {
       issues.push({
         type: "duplicate-skill-placement",
         id: asset.id,
@@ -757,7 +1010,7 @@ function expectedSkillTargetPrefixes(host) {
   return void 0;
 }
 function expectedRegistrySkillTargetPath(host, sourcePath, placement) {
-  const skillName = basename(sourcePath);
+  const skillName = basename2(sourcePath);
   if (host === "claude-code") {
     return placement === "manual" ? void 0 : `.claude/skills/${skillName}`;
   }
@@ -766,163 +1019,6 @@ function expectedRegistrySkillTargetPath(host, sourcePath, placement) {
   }
   return void 0;
 }
-function pathExistsEvenIfDanglingSymlink3(path) {
-  try {
-    lstatSync3(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// src/asset-targets/install-plan.ts
-import { existsSync as existsSync9, lstatSync as lstatSync4, readFileSync as readFileSync5 } from "node:fs";
-import { basename as basename2, dirname as dirname4, join as join9 } from "node:path";
-function createAssetInstallPlan(options) {
-  const placement = options.placement ?? "registry";
-  const assetsById = new Map(options.registry.assets.map((asset) => [asset.id, asset]));
-  const bundlesById = new Map(options.bundles.map((bundle) => [bundle.id, bundle]));
-  const assetIds = resolveBundleAssetIds(options.bundleIds, bundlesById);
-  const assets = assetIds.map((assetId) => {
-    const asset = assetsById.get(assetId);
-    if (!asset) throw new Error(`Unknown asset id in bundle: ${assetId}`);
-    if (asset.kind === "skill" && !asset.hosts.includes(options.host)) {
-      throw new Error(`Asset ${assetId} does not support host ${options.host}`);
-    }
-    return asset;
-  });
-  const lockEntries = createAgentAssetLockEntries(options.registry, options.agentAssetsDir, assetIds);
-  const managedTargets = readManagedTargets(options.targetDir);
-  const assetActions = assets.map(
-    (asset) => createAssetAction(asset, options.agentAssetsDir, options.targetDir, options.host, placement, managedTargets)
-  );
-  const manifest = {
-    schemaVersion: 1,
-    host: options.host,
-    placement,
-    bundleIds: [...options.bundleIds],
-    assetIds
-  };
-  const lockfile = {
-    schemaVersion: 1,
-    host: options.host,
-    placement,
-    bundleIds: [...options.bundleIds],
-    assets: lockEntries.map((entry) => {
-      const action = assetActions.find((candidate) => "assetId" in candidate && candidate.assetId === entry.id);
-      return {
-        ...entry,
-        targetPath: action && "targetPath" in action ? action.targetPath : ""
-      };
-    })
-  };
-  const writeActions = [
-    {
-      type: "write-file",
-      targetPath: ".pro-gov/assets.json",
-      content: `${JSON.stringify(manifest, null, 2)}
-`
-    },
-    {
-      type: "write-file",
-      targetPath: ".pro-gov/assets.lock.json",
-      content: `${JSON.stringify(lockfile, null, 2)}
-`
-    }
-  ];
-  return {
-    schemaVersion: 1,
-    dryRun: true,
-    targetDir: options.targetDir,
-    host: options.host,
-    placement,
-    bundleIds: [...options.bundleIds],
-    assetIds,
-    actions: [...createDirectoryActions([...assetActions, ...writeActions]), ...assetActions, ...writeActions]
-  };
-}
-function resolveBundleAssetIds(bundleIds, bundlesById) {
-  const ids = /* @__PURE__ */ new Set();
-  for (const bundleId of bundleIds) {
-    const bundle = bundlesById.get(bundleId);
-    if (!bundle) throw new Error(`Unknown bundle id: ${bundleId}`);
-    for (const assetId of bundle.assets) {
-      ids.add(assetId);
-    }
-  }
-  return [...ids].sort();
-}
-function createAssetAction(asset, agentAssetsDir, targetDir, host, placement, managedTargets) {
-  if (asset.kind === "skill" && asset.defaultScope === "user") {
-    throw new Error(
-      `User-scoped asset ${asset.id} must be linked at the user level, not installed into a project target.`
-    );
-  }
-  const sourcePath = join9(agentAssetsDir, asset.sourcePath);
-  const targetPath = resolveHostTargetPath(asset, host, placement);
-  const targetAbsolutePath = join9(targetDir, targetPath);
-  const targetExists = pathExistsEvenIfDanglingSymlink4(targetAbsolutePath);
-  if (targetExists) {
-    const stats = lstatSync4(targetAbsolutePath);
-    if (stats.isSymbolicLink() && managedTargets.has(targetPath)) {
-      return {
-        type: "update-symlink",
-        assetId: asset.id,
-        sourcePath,
-        targetPath
-      };
-    }
-    throw new Error(`Refusing to overwrite unmanaged target: ${targetPath}`);
-  }
-  return {
-    type: "symlink",
-    assetId: asset.id,
-    sourcePath,
-    targetPath
-  };
-}
-function resolveHostTargetPath(asset, host, placement) {
-  if (asset.kind === "skill") {
-    const effectivePlacement = resolveSkillPlacement(asset, placement);
-    if (host === "claude-code") {
-      if (placement === "manual") {
-        throw new Error("Manual skill placement is only supported for .agents hosts");
-      }
-      return `.claude/skills/${basename2(asset.sourcePath)}`;
-    }
-    if (effectivePlacement === "manual") {
-      return `.agents/manual-skills/${basename2(asset.sourcePath)}`;
-    }
-    return `.agents/skills/${basename2(asset.sourcePath)}`;
-  }
-  if (asset.kind === "rule") {
-    return `.pro-gov/agent-assets/rules/${basename2(asset.sourcePath)}`;
-  }
-  return `.pro-gov/agent-assets/commands/${basename2(asset.sourcePath)}`;
-}
-function resolveSkillPlacement(asset, placement) {
-  if (placement !== "registry") return placement;
-  return asset.defaultPlacement ?? "auto";
-}
-function createDirectoryActions(actions) {
-  const directories = /* @__PURE__ */ new Set();
-  for (const action of actions) {
-    if (action.type === "create-dir") continue;
-    const directory = dirname4(action.targetPath);
-    if (directory !== ".") directories.add(directory);
-  }
-  return [...directories].sort().map((targetPath) => ({ type: "create-dir", targetPath }));
-}
-function readManagedTargets(targetDir) {
-  const lockfilePath = join9(targetDir, ".pro-gov/assets.lock.json");
-  if (!existsSync9(lockfilePath)) return /* @__PURE__ */ new Set();
-  try {
-    const lockfile = JSON.parse(readFileSync5(lockfilePath, "utf8"));
-    return new Set((lockfile.assets ?? []).map((asset) => asset.targetPath).filter(Boolean));
-  } catch {
-    return /* @__PURE__ */ new Set();
-  }
-}
 function pathExistsEvenIfDanglingSymlink4(path) {
   try {
     lstatSync4(path);
@@ -1642,7 +1738,7 @@ function isEngineeringRuntimeProject(root) {
 import { spawnSync as spawnSync3 } from "node:child_process";
 import { existsSync as existsSync13, mkdirSync as mkdirSync4, readFileSync as readFileSync10, writeFileSync as writeFileSync3 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
-import { basename as basename3, join as join13, resolve as resolve2 } from "node:path";
+import { basename as basename3, join as join13, resolve as resolve3 } from "node:path";
 
 // src/host-hooks/host-hook-runner.ts
 import { closeSync, openSync, readFileSync as readFileSync9, readSync, statSync as statSync3 } from "node:fs";
@@ -1967,7 +2063,7 @@ function defaultDebugDir() {
   });
   const value = gitPath.status === 0 ? gitPath.stdout.trim() : "";
   if (value) {
-    return resolve2(process.cwd(), value);
+    return resolve3(process.cwd(), value);
   }
   return join13(tmpdir2(), "pro-gov-hook-debug", basename3(process.cwd()));
 }
@@ -1983,8 +2079,8 @@ function readPackageVersion() {
 }
 function resolvePackageJsonPath() {
   const candidates = [
-    resolve2(process.cwd(), "packages/pro-gov/package.json"),
-    resolve2(process.cwd(), "node_modules/@pieai/pro-gov/package.json")
+    resolve3(process.cwd(), "packages/pro-gov/package.json"),
+    resolve3(process.cwd(), "node_modules/@pieai/pro-gov/package.json")
   ];
   return candidates.find((candidate) => existsSync13(candidate));
 }
@@ -2076,36 +2172,253 @@ function applyStarterFiles(files, profile) {
     console.error("No files were written. Use --dry-run and migrate existing files deliberately.");
     return 1;
   }
-  for (const file of files) {
-    const targetPath = join14(root, file.targetPath);
-    mkdirSync5(dirname7(targetPath), { recursive: true });
-    const source = readFileSync11(file.absoluteSourcePath);
-    const content = file.targetPath === "AGENTS.md" ? renderAgentsTemplate(source.toString("utf8"), basename4(root), profile) : source;
-    writeFileSync4(targetPath, content);
+  for (const file of files) {
+    const targetPath = join14(root, file.targetPath);
+    mkdirSync5(dirname7(targetPath), { recursive: true });
+    const source = readFileSync11(file.absoluteSourcePath);
+    const content = file.targetPath === "AGENTS.md" ? renderAgentsTemplate(source.toString("utf8"), basename4(root), profile) : source;
+    writeFileSync4(targetPath, content);
+  }
+  console.log("pro-gov init APPLIED");
+  console.log(`profile: ${profile}`);
+  console.log(`created-files: ${files.length}`);
+  console.log("Existing project files were not overwritten.");
+  console.log("Next: customize project-local policy/current-work, run doc-gov scan, then run doc-gov doctor.");
+  return 0;
+}
+function renderAgentsTemplate(template, projectName, profile) {
+  const selectedRoute = `docs/governance/agents-routing/${profile}-v0.9.md`;
+  return template.replace("# PROJECT_NAME AI Router", `# ${projectName} AI Router`).replace(
+    /6\. The selected agents routing file:\n   - `docs\/governance\/agents-routing\/engineering-runtime-v0\.9\.md`, or\n   - `docs\/governance\/agents-routing\/doc-only-v0\.9\.md`/,
+    `6. The selected agents routing file: \`${selectedRoute}\``
+  ).replace(
+    "- Name this project's adopted profile: `engineering-runtime` or `doc-only`.",
+    `- This project adopts the \`${profile}\` profile.`
+  );
+}
+function readFlag(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) return null;
+  return value;
+}
+
+// src/learning/recall.ts
+import { existsSync as existsSync15, readdirSync as readdirSync6, readFileSync as readFileSync12 } from "node:fs";
+import { basename as basename5, join as join15, relative as relative5 } from "node:path";
+function recallLearnings(root, options) {
+  const query = options.query.trim();
+  const terms = tokenize(query);
+  const limit = Math.max(1, options.limit ?? 5);
+  if (terms.length === 0) {
+    return { query, hits: [] };
+  }
+  const records = loadLearningRecords(root);
+  const hits = records.map((record) => {
+    const score = scoreRecord(record, terms);
+    return {
+      relativePath: record.relativePath,
+      title: record.title,
+      score,
+      summary: summarizeRecord(record, terms)
+    };
+  }).filter((hit) => hit.score > 0).sort((a, b) => b.score - a.score || a.relativePath.localeCompare(b.relativePath)).slice(0, limit);
+  return { query, hits };
+}
+function loadLearningRecords(root) {
+  const records = [];
+  const solutionsDir = join15(root, "docs/solutions");
+  if (existsSync15(solutionsDir)) {
+    for (const path of listMarkdownFiles(solutionsDir)) {
+      records.push(readLearningRecord(root, path));
+    }
+  }
+  const conceptsPath = join15(root, "CONCEPTS.md");
+  if (existsSync15(conceptsPath)) {
+    records.push(readLearningRecord(root, conceptsPath));
+  }
+  return records;
+}
+function listMarkdownFiles(dir) {
+  const files = [];
+  for (const entry of readdirSync6(dir, { withFileTypes: true })) {
+    const absolutePath = join15(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listMarkdownFiles(absolutePath));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(absolutePath);
+    }
+  }
+  return files.sort();
+}
+function readLearningRecord(root, absolutePath) {
+  const content = readFileSync12(absolutePath, "utf8");
+  const parsed = splitFrontmatter(content);
+  const body = parsed.body;
+  return {
+    relativePath: normalizePath(relative5(root, absolutePath)),
+    title: findTitle(parsed.frontmatter, body) ?? titleFromPath(absolutePath),
+    metadata: parsed.frontmatter,
+    body
+  };
+}
+function splitFrontmatter(content) {
+  if (!content.startsWith("---\n")) {
+    return { frontmatter: "", body: content };
+  }
+  const end = content.indexOf("\n---", 4);
+  if (end === -1) {
+    return { frontmatter: "", body: content };
+  }
+  return {
+    frontmatter: content.slice(4, end).trim(),
+    body: content.slice(end + "\n---".length).trim()
+  };
+}
+function findTitle(frontmatter, body) {
+  const titleLine = frontmatter.split(/\r?\n/).find((line) => line.trim().toLowerCase().startsWith("title:"));
+  if (titleLine) {
+    return titleLine.slice(titleLine.indexOf(":") + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  const heading = body.split(/\r?\n/).find((line) => line.startsWith("# "));
+  return heading ? heading.slice(2).trim() : void 0;
+}
+function titleFromPath(path) {
+  return basename5(path, ".md").split(/[-_]/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function scoreRecord(record, terms) {
+  const title = record.title.toLowerCase();
+  const metadata = record.metadata.toLowerCase();
+  const path = record.relativePath.toLowerCase();
+  const body = record.body.toLowerCase();
+  let score = 0;
+  for (const term of terms) {
+    if (title.includes(term)) score += 6;
+    if (metadata.includes(term)) score += 4;
+    if (path.includes(term)) score += 2;
+    if (body.includes(term)) score += 1;
+  }
+  return score;
+}
+function summarizeRecord(record, terms) {
+  const lines = record.body.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  const best = lines.map((line, index) => ({
+    line,
+    index,
+    score: countTermMatches(line, terms) + (line.startsWith("#") ? 0.5 : 0)
+  })).filter((candidate) => candidate.score > 0).sort((a, b) => b.score - a.score || a.index - b.index)[0];
+  if (!best) {
+    return truncate(cleanMarkdownLine(lines[0] ?? record.title), 180);
+  }
+  const cleaned = cleanMarkdownLine(best.line);
+  if (!best.line.startsWith("#")) {
+    return truncate(cleaned, 180);
+  }
+  const nextLine = lines.slice(best.index + 1).find((line) => !line.startsWith("#"));
+  return truncate([cleaned, nextLine].filter(Boolean).join(" - "), 180);
+}
+function tokenize(input) {
+  return [...new Set(input.toLowerCase().match(/[a-z0-9\u4e00-\u9fff]+/g) ?? [])].filter((term) => term.length > 1);
+}
+function truncate(input, maxLength) {
+  return input.length <= maxLength ? input : `${input.slice(0, maxLength - 1)}\u2026`;
+}
+function normalizePath(path) {
+  return path.split("\\").join("/");
+}
+function countTermMatches(input, terms) {
+  const lower = input.toLowerCase();
+  return terms.filter((term) => lower.includes(term)).length;
+}
+function cleanMarkdownLine(input) {
+  return input.replace(/^#+\s*/, "").trim();
+}
+
+// src/commands/learn.ts
+function runLearn(args) {
+  const [subcommand2, ...rest] = args;
+  if (subcommand2 === "recall") return runLearnRecall(rest);
+  printUsage2();
+  return 1;
+}
+function runLearnRecall(args) {
+  const options = parseRecallOptions(args);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage2();
+    return 1;
+  }
+  const result = recallLearnings(options.value.targetDir, {
+    query: options.value.query,
+    limit: options.value.limit
+  });
+  if (options.value.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  console.log(`Learning Recall: ${result.hits.length} hit${result.hits.length === 1 ? "" : "s"}`);
+  for (const hit of result.hits) {
+    console.log(`${hit.relativePath}	${hit.score}	${hit.title}`);
+    if (hit.summary) console.log(`  ${hit.summary}`);
+  }
+  if (result.hits.length === 0) {
+    console.log("No relevant learning records found.");
   }
-  console.log("pro-gov init APPLIED");
-  console.log(`profile: ${profile}`);
-  console.log(`created-files: ${files.length}`);
-  console.log("Existing project files were not overwritten.");
-  console.log("Next: customize project-local policy/current-work, run doc-gov scan, then run doc-gov doctor.");
   return 0;
 }
-function renderAgentsTemplate(template, projectName, profile) {
-  const selectedRoute = `docs/governance/agents-routing/${profile}-v0.9.md`;
-  return template.replace("# PROJECT_NAME AI Router", `# ${projectName} AI Router`).replace(
-    /6\. The selected agents routing file:\n   - `docs\/governance\/agents-routing\/engineering-runtime-v0\.9\.md`, or\n   - `docs\/governance\/agents-routing\/doc-only-v0\.9\.md`/,
-    `6. The selected agents routing file: \`${selectedRoute}\``
-  ).replace(
-    "- Name this project's adopted profile: `engineering-runtime` or `doc-only`.",
-    `- This project adopts the \`${profile}\` profile.`
-  );
+function parseRecallOptions(args) {
+  let targetDir = process.cwd();
+  let query = "";
+  let limit = 5;
+  let json = false;
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--target") {
+      const value = readFlagValue(args, index, "--target");
+      if (!value.ok) return value;
+      targetDir = value.value;
+      index += 1;
+    } else if (arg === "--query") {
+      const value = readFlagValue(args, index, "--query");
+      if (!value.ok) return value;
+      query = value.value;
+      index += 1;
+    } else if (arg === "--limit") {
+      const parsed = readFlagValue(args, index, "--limit");
+      if (!parsed.ok) return parsed;
+      const value = Number.parseInt(parsed.value, 10);
+      if (!Number.isFinite(value) || value < 1) return { ok: false, error: "--limit must be a positive integer" };
+      limit = value;
+      index += 1;
+    } else if (arg === "--json") {
+      json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      return { ok: false, error: "Usage requested" };
+    } else if (arg.startsWith("--")) {
+      return { ok: false, error: `Unknown option: ${arg}` };
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (!query && positional.length > 0) {
+    query = positional.join(" ");
+  }
+  if (!query.trim()) {
+    return { ok: false, error: "Missing required --query <text>" };
+  }
+  return { ok: true, value: { targetDir, query, limit, json } };
 }
-function readFlag(args, flag) {
-  const index = args.indexOf(flag);
-  if (index === -1) return null;
+function readFlagValue(args, index, flag) {
   const value = args[index + 1];
-  if (!value || value.startsWith("--")) return null;
-  return value;
+  if (!value || value.startsWith("--")) {
+    return { ok: false, error: `Missing value for ${flag}` };
+  }
+  return { ok: true, value };
+}
+function printUsage2() {
+  console.error("Usage: pro-gov learn recall --query <text> [--target <path>] [--limit <n>] [--json]");
 }
 
 // src/commands/lens.ts
@@ -2113,8 +2426,8 @@ import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync6 } from "node:f
 import { dirname as dirname9 } from "node:path";
 
 // src/lens/audit.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync6, readFileSync as readFileSync12, writeFileSync as writeFileSync5 } from "node:fs";
-import { basename as basename5, dirname as dirname8, join as join15 } from "node:path";
+import { existsSync as existsSync16, mkdirSync as mkdirSync6, readFileSync as readFileSync13, writeFileSync as writeFileSync5 } from "node:fs";
+import { basename as basename6, dirname as dirname8, join as join16 } from "node:path";
 var REQUIRED_ARTIFACTS = [
   "manifest.md",
   "raw/project-lens/architecture-lens.md",
@@ -2134,20 +2447,20 @@ function createProjectLensAuditPackage(targetDir, auditDir) {
     version: 1,
     target: {
       path: targetDir,
-      name: basename5(targetDir) || "target"
+      name: basename6(targetDir) || "target"
     },
     requiredArtifacts: [...REQUIRED_ARTIFACTS]
   };
   mkdirSync6(auditDir, { recursive: true });
-  writeJson(join15(auditDir, "audit.contract.json"), contract);
+  writeJson(join16(auditDir, "audit.contract.json"), contract);
   for (const artifactPath of REQUIRED_ARTIFACTS) {
-    writeTemplate(join15(auditDir, artifactPath), renderArtifactTemplate(artifactPath, contract));
+    writeTemplate(join16(auditDir, artifactPath), renderArtifactTemplate(artifactPath, contract));
   }
   return contract;
 }
 function checkProjectLensAuditPackage(auditDir, options = {}) {
-  const contractPath = join15(auditDir, "audit.contract.json");
-  if (!existsSync15(contractPath)) {
+  const contractPath = join16(auditDir, "audit.contract.json");
+  if (!existsSync16(contractPath)) {
     return {
       ok: false,
       auditDir,
@@ -2161,7 +2474,7 @@ function checkProjectLensAuditPackage(auditDir, options = {}) {
   }
   let contract;
   try {
-    contract = JSON.parse(readFileSync12(contractPath, "utf8"));
+    contract = JSON.parse(readFileSync13(contractPath, "utf8"));
   } catch (error) {
     return {
       ok: false,
@@ -2194,12 +2507,12 @@ function checkProjectLensAuditPackage(auditDir, options = {}) {
     }
   }
   for (const artifactPath of REQUIRED_ARTIFACTS) {
-    const absolutePath = join15(auditDir, artifactPath);
-    if (!existsSync15(absolutePath)) {
+    const absolutePath = join16(auditDir, artifactPath);
+    if (!existsSync16(absolutePath)) {
       issues.push({ type: "missing-required-artifact", path: artifactPath });
       continue;
     }
-    const content = readFileSync12(absolutePath, "utf8");
+    const content = readFileSync13(absolutePath, "utf8");
     if (isPendingArtifact(content)) {
       issues.push({ type: "artifact-not-complete", path: artifactPath });
     } else if (hasTemplateBody(content)) {
@@ -2459,8 +2772,8 @@ function bulletList(values) {
 
 // src/lens/scan.ts
 import { spawnSync as spawnSync4 } from "node:child_process";
-import { existsSync as existsSync16, readdirSync as readdirSync6, readFileSync as readFileSync13, statSync as statSync4 } from "node:fs";
-import { join as join16, relative as relative5 } from "node:path";
+import { existsSync as existsSync17, readdirSync as readdirSync7, readFileSync as readFileSync14, statSync as statSync4 } from "node:fs";
+import { join as join17, relative as relative6 } from "node:path";
 var ignoredDirectories = /* @__PURE__ */ new Set([
   ".git",
   ".next",
@@ -2477,24 +2790,24 @@ function scanProjectLensTarget(targetDir, options = {}) {
   return {
     targetDir,
     aiEntryFiles: ["AGENTS.md", "CLAUDE.md"].filter(
-      (file) => existsSync16(join16(targetDir, file))
+      (file) => existsSync17(join17(targetDir, file))
     ),
     aiConfigFiles: [],
     packageJson,
     docs: {
-      hasDocsDirectory: existsSync16(join16(targetDir, "docs")),
+      hasDocsDirectory: existsSync17(join17(targetDir, "docs")),
       markdownFileCount: markdownFiles.length,
       governanceFiles: markdownFiles.filter((file) => file.startsWith("docs/governance/") || file.startsWith("docs/policy/")).sort()
     },
     git: readGitState(targetDir),
-    largeFiles: files.map((file) => ({ path: file, bytes: statSync4(join16(targetDir, file)).size })).filter((file) => file.bytes >= largeFileBytes).sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path)).slice(0, 25)
+    largeFiles: files.map((file) => ({ path: file, bytes: statSync4(join17(targetDir, file)).size })).filter((file) => file.bytes >= largeFileBytes).sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path)).slice(0, 25)
   };
 }
 function readPackageJson(targetDir) {
-  const packageJsonPath = join16(targetDir, "package.json");
-  if (!existsSync16(packageJsonPath)) return void 0;
+  const packageJsonPath = join17(targetDir, "package.json");
+  if (!existsSync17(packageJsonPath)) return void 0;
   try {
-    const packageJson = JSON.parse(readFileSync13(packageJsonPath, "utf8"));
+    const packageJson = JSON.parse(readFileSync14(packageJsonPath, "utf8"));
     return {
       scripts: Object.keys(packageJson.scripts ?? {}).sort(),
       dependencies: Object.keys(packageJson.dependencies ?? {}).sort(),
@@ -2529,13 +2842,13 @@ function listProjectFiles(targetDir) {
   return files.sort();
 }
 function collectFiles2(rootDir, currentDir, files) {
-  if (!existsSync16(currentDir)) return;
-  for (const entry of readdirSync6(currentDir, { withFileTypes: true })) {
+  if (!existsSync17(currentDir)) return;
+  for (const entry of readdirSync7(currentDir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
       if (ignoredDirectories.has(entry.name)) continue;
-      collectFiles2(rootDir, join16(currentDir, entry.name), files);
+      collectFiles2(rootDir, join17(currentDir, entry.name), files);
     } else if (entry.isFile()) {
-      files.push(toUnixPath4(relative5(rootDir, join16(currentDir, entry.name))));
+      files.push(toUnixPath4(relative6(rootDir, join17(currentDir, entry.name))));
     }
   }
 }
@@ -2555,14 +2868,14 @@ function runLens(args) {
   if (subcommand2 === "audit") {
     return runLensAudit(rest);
   }
-  printUsage2();
+  printUsage3();
   return 1;
 }
 function runLensInspect(args, subcommand2) {
   const options = parseLensOptions(args, subcommand2);
   if (!options.ok) {
     console.error(options.error);
-    printUsage2();
+    printUsage3();
     return 1;
   }
   const report = scanProjectLensTarget(options.value.targetDir);
@@ -2577,12 +2890,12 @@ function runLensReport(args) {
   const options = parseLensOptions(args, "report");
   if (!options.ok) {
     console.error(options.error);
-    printUsage2();
+    printUsage3();
     return 1;
   }
   if (!options.value.outPath) {
     console.error("Expected --out <path>");
-    printUsage2();
+    printUsage3();
     return 1;
   }
   const report = scanProjectLensTarget(options.value.targetDir);
@@ -2598,12 +2911,12 @@ function runLensAudit(args) {
     const options = parseLensOptions(rest, "audit init");
     if (!options.ok) {
       console.error(options.error);
-      printUsage2();
+      printUsage3();
       return 1;
     }
     if (!options.value.outPath) {
       console.error("Expected --out <path>");
-      printUsage2();
+      printUsage3();
       return 1;
     }
     createProjectLensAuditPackage(options.value.targetDir, options.value.outPath);
@@ -2614,12 +2927,12 @@ function runLensAudit(args) {
     const options = parseLensOptions(rest, "audit check");
     if (!options.ok) {
       console.error(options.error);
-      printUsage2();
+      printUsage3();
       return 1;
     }
     if (!options.value.auditDir) {
       console.error("Expected --dir <path>");
-      printUsage2();
+      printUsage3();
       return 1;
     }
     const result = checkProjectLensAuditPackage(options.value.auditDir, { mode: options.value.auditMode });
@@ -2630,7 +2943,7 @@ function runLensAudit(args) {
     }
     return result.ok ? 0 : 1;
   }
-  printUsage2();
+  printUsage3();
   return 1;
 }
 function parseLensOptions(args, subcommand2) {
@@ -2682,7 +2995,7 @@ function parseLensOptions(args, subcommand2) {
   }
   return { ok: true, value: options };
 }
-function printUsage2() {
+function printUsage3() {
   console.error("Usage: pro-gov lens scan [--target <path>] [--json]");
   console.error("Usage: pro-gov lens inspect [--target <path>] [--format text|json]");
   console.error("Usage: pro-gov lens report --target <path> --out <path>");
@@ -2691,16 +3004,16 @@ function printUsage2() {
 }
 
 // src/commands/portfolio.ts
-import { existsSync as existsSync18 } from "node:fs";
-import { join as join17 } from "node:path";
+import { existsSync as existsSync21 } from "node:fs";
+import { join as join20 } from "node:path";
 
 // src/portfolio/manifest.ts
-import { existsSync as existsSync17, readFileSync as readFileSync14 } from "node:fs";
-import { dirname as dirname10, isAbsolute as isAbsolute3, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync18, readFileSync as readFileSync15 } from "node:fs";
+import { dirname as dirname10, isAbsolute as isAbsolute3, resolve as resolve4 } from "node:path";
 function loadPortfolioManifest(configPath) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync14(configPath, "utf8"));
+    parsed = JSON.parse(readFileSync15(configPath, "utf8"));
   } catch (error) {
     return {
       configPath,
@@ -2712,7 +3025,7 @@ function loadPortfolioManifest(configPath) {
       ]
     };
   }
-  const normalized = resolveManifestPaths(parsed, dirname10(resolve3(configPath)));
+  const normalized = resolveManifestPaths(parsed, dirname10(resolve4(configPath)));
   const issues = validatePortfolioManifest(normalized);
   return {
     configPath,
@@ -2726,7 +3039,7 @@ function resolveManifestPaths(value, configDir) {
     if (!isRecord2(endpoint) || typeof endpoint.path !== "string" || isAbsolute3(endpoint.path)) {
       return endpoint;
     }
-    return { ...endpoint, path: resolve3(configDir, endpoint.path) };
+    return { ...endpoint, path: resolve4(configDir, endpoint.path) };
   };
   return {
     ...value,
@@ -2760,9 +3073,15 @@ function validatePortfolioManifest(value) {
       message: "Portfolio manifest portfolioId must be a non-empty string."
     });
   }
-  validateAllowedFields(value, "root", ["schemaVersion", "portfolioId", "controlPlane", "executionEngine", "targets"], issues);
+  validateAllowedFields(
+    value,
+    "root",
+    ["schemaVersion", "portfolioId", "controlPlane", "executionEngine", "hostTooling", "targets"],
+    issues
+  );
   validateEndpoint(value.controlPlane, "controlPlane", issues);
   validateEndpoint(value.executionEngine, "executionEngine", issues);
+  validateHostTooling(value.hostTooling, issues);
   if (!Array.isArray(value.targets)) {
     issues.push({
       type: "invalid-field",
@@ -2854,7 +3173,7 @@ function validateEndpoint(value, field, issues) {
     });
     return;
   }
-  if (!existsSync17(value.path)) {
+  if (!existsSync18(value.path)) {
     issues.push({
       type: "missing-path",
       id: typeof value.id === "string" ? value.id : void 0,
@@ -2874,24 +3193,474 @@ function validateOptionalStringArray(value, id, field, issues) {
     });
   }
 }
+function validateHostTooling(value, issues) {
+  if (value === void 0) return;
+  if (!Array.isArray(value)) {
+    issues.push({
+      type: "invalid-field",
+      field: "hostTooling",
+      message: "Portfolio hostTooling must be an array."
+    });
+    return;
+  }
+  const seenHosts = /* @__PURE__ */ new Set();
+  for (const entry of value) {
+    if (!isRecord2(entry)) {
+      issues.push({
+        type: "invalid-field",
+        field: "hostTooling",
+        message: "Portfolio hostTooling entry must be an object."
+      });
+      continue;
+    }
+    validateAllowedFields(entry, "hostTooling", ["host", "plugins"], issues);
+    if (entry.host !== "codex" && entry.host !== "claude-code") {
+      issues.push({
+        type: "invalid-field",
+        field: "hostTooling.host",
+        message: "Portfolio hostTooling host must be codex or claude-code."
+      });
+    } else if (seenHosts.has(entry.host)) {
+      issues.push({
+        type: "invalid-field",
+        field: "hostTooling",
+        message: `Duplicate portfolio hostTooling entry: ${entry.host}`
+      });
+    } else {
+      seenHosts.add(entry.host);
+    }
+    if (!Array.isArray(entry.plugins) || !entry.plugins.every((plugin) => typeof plugin === "string" && plugin.length > 0)) {
+      issues.push({
+        type: "invalid-field",
+        field: "hostTooling.plugins",
+        message: "Portfolio hostTooling plugins must be an array of non-empty strings."
+      });
+    }
+  }
+}
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// src/portfolio/doctor.ts
+import { spawnSync as spawnSync6 } from "node:child_process";
+import { existsSync as existsSync20, readFileSync as readFileSync17 } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import { dirname as dirname11, join as join19 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+
+// src/host-tooling/inventory.ts
+import { spawnSync as spawnSync5 } from "node:child_process";
+function inspectHostTooling(requirements, runner = defaultRunner2) {
+  const hosts = [];
+  const issues = [];
+  for (const requirement of requirements) {
+    const command2 = requirement.host === "codex" ? ["codex", "plugin", "list", "--json"] : ["claude", "plugin", "list", "--json"];
+    const result = runner({ host: requirement.host, command: command2 });
+    if (result.status !== 0) {
+      issues.push({
+        type: "host-tooling-command-failed",
+        host: requirement.host,
+        message: `Unable to inspect ${requirement.host} plugins: ${result.stderr || `exit ${result.status}`}`
+      });
+      hosts.push({ host: requirement.host, plugins: [] });
+      continue;
+    }
+    let plugins;
+    try {
+      plugins = parseHostPlugins(requirement.host, JSON.parse(result.stdout));
+    } catch (error) {
+      issues.push({
+        type: "host-tooling-command-failed",
+        host: requirement.host,
+        message: `Unable to parse ${requirement.host} plugin inventory: ${error instanceof Error ? error.message : String(error)}`
+      });
+      hosts.push({ host: requirement.host, plugins: [] });
+      continue;
+    }
+    const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
+    hosts.push({
+      host: requirement.host,
+      plugins: requirement.plugins.flatMap((pluginId) => {
+        const plugin = byId.get(pluginId);
+        return plugin ? [plugin] : [];
+      })
+    });
+    for (const pluginId of requirement.plugins) {
+      const plugin = byId.get(pluginId);
+      if (!plugin) {
+        issues.push({
+          type: "host-tooling-missing",
+          host: requirement.host,
+          pluginId,
+          message: `Required ${requirement.host} plugin is missing: ${pluginId}`
+        });
+      } else if (!plugin.enabled) {
+        issues.push({
+          type: "host-tooling-disabled",
+          host: requirement.host,
+          pluginId,
+          message: `Required ${requirement.host} plugin is disabled: ${pluginId}`
+        });
+      }
+    }
+  }
+  return { hosts, issues };
+}
+function parseHostPlugins(host, value) {
+  const entries = host === "codex" ? isRecord3(value) && Array.isArray(value.installed) ? value.installed : void 0 : Array.isArray(value) ? value : void 0;
+  if (!entries) throw new Error("expected a plugin array");
+  return entries.flatMap((entry) => {
+    if (!isRecord3(entry)) return [];
+    const id = host === "codex" ? entry.pluginId : entry.id;
+    if (typeof id !== "string") return [];
+    return [{
+      id,
+      version: typeof entry.version === "string" ? entry.version : void 0,
+      enabled: entry.enabled === true
+    }];
+  });
+}
+function defaultRunner2({ command: command2 }) {
+  const result = spawnSync5(command2[0] ?? "", command2.slice(1), {
+    encoding: "utf8",
+    timeout: 1e4
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr || result.error?.message || ""
+  };
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/portfolio/asset-state.ts
+import { existsSync as existsSync19, lstatSync as lstatSync5, readFileSync as readFileSync16 } from "node:fs";
+import { join as join18 } from "node:path";
+function comparePortfolioAssetState(options) {
+  const expectedManifest = readPlanDocument(options.expectedPlan, ".pro-gov/assets.json");
+  const expectedLock = readPlanDocument(options.expectedPlan, ".pro-gov/assets.lock.json");
+  const currentManifest = readJsonFile(join18(options.targetDir, ".pro-gov/assets.json"));
+  const currentLock = readJsonFile(join18(options.targetDir, ".pro-gov/assets.lock.json"));
+  const issues = [];
+  if (!sameStrings(currentManifest?.bundleIds, expectedManifest?.bundleIds)) {
+    issues.push({
+      type: "bundle-drift",
+      message: "Target asset bundles do not match the portfolio manifest."
+    });
+  }
+  if (!sameStrings(currentManifest?.assetIds, expectedManifest?.assetIds)) {
+    issues.push({
+      type: "asset-set-drift",
+      message: "Target asset ids do not match the current bundle definitions."
+    });
+  }
+  if (!sameLock(currentLock, expectedLock)) {
+    issues.push({
+      type: "asset-lock-drift",
+      message: "Target asset lock does not match the current registry, placement, and content hashes."
+    });
+  }
+  const expectedTargets = new Set((expectedLock?.assets ?? []).map((entry) => entry.targetPath));
+  for (const entry of currentLock?.assets ?? []) {
+    if (expectedTargets.has(entry.targetPath)) continue;
+    const targetAbsolutePath = join18(options.targetDir, entry.targetPath);
+    if (!pathIsSymlink(targetAbsolutePath)) continue;
+    issues.push({
+      type: "orphaned-managed-symlink",
+      targetPath: entry.targetPath,
+      message: `Previously managed symlink is absent from the expected bundle state: ${entry.targetPath}`
+    });
+  }
+  return { issues };
+}
+function readPlanDocument(plan, targetPath) {
+  const action = plan.actions.find(
+    (candidate) => candidate.type === "write-file" && candidate.targetPath === targetPath
+  );
+  if (!action || action.type !== "write-file") return void 0;
+  try {
+    return JSON.parse(action.content);
+  } catch {
+    return void 0;
+  }
+}
+function readJsonFile(path) {
+  if (!existsSync19(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync16(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function sameStrings(left, right) {
+  return JSON.stringify([...left ?? []].sort()) === JSON.stringify([...right ?? []].sort());
+}
+function sameLock(left, right) {
+  return JSON.stringify(normalizeLock(left)) === JSON.stringify(normalizeLock(right));
+}
+function normalizeLock(lock) {
+  return {
+    host: lock?.host,
+    placement: lock?.placement,
+    bundleIds: [...lock?.bundleIds ?? []].sort(),
+    assets: [...lock?.assets ?? []].sort((a, b) => a.id.localeCompare(b.id))
+  };
+}
+function pathIsSymlink(path) {
+  try {
+    return lstatSync5(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+// src/portfolio/doctor.ts
+function inspectPortfolio(options) {
+  const expectedPackageVersions = getExpectedPackageVersions();
+  const hostTooling = inspectHostTooling(options.manifest.hostTooling ?? []);
+  const targets = options.targets.map((target) => inspectTarget({
+    target,
+    agentAssetsDir: options.agentAssetsDir,
+    registry: options.registry,
+    bundles: options.bundles,
+    expectedPackageVersions
+  }));
+  return {
+    ok: hostTooling.issues.length === 0 && targets.every((target) => target.issues.length === 0),
+    portfolioId: options.manifest.portfolioId,
+    expectedPackageVersions,
+    hostTooling,
+    targets
+  };
+}
+function inspectTarget(options) {
+  const { target } = options;
+  const issues = [];
+  const packageJson = readJson2(join19(target.path, "package.json"));
+  const packages = {};
+  for (const packageName of ["@pieai/pro-gov", "@pieai/doc-gov"]) {
+    const declared = packageJson?.devDependencies?.[packageName] ?? packageJson?.dependencies?.[packageName];
+    const installedPackage = readJson2(join19(target.path, "node_modules", packageName, "package.json"));
+    const installed = installedPackage?.version;
+    const expected = options.expectedPackageVersions[packageName];
+    packages[packageName] = { declared, installed, expected };
+    if (!declared) {
+      issues.push({
+        type: "package-declaration-missing",
+        packageName,
+        message: `Target does not declare ${packageName}.`
+      });
+    }
+    if (!installed || expected && installed !== expected) {
+      issues.push({
+        type: "package-version-drift",
+        packageName,
+        message: `Target ${packageName} installed version is ${installed ?? "missing"}; expected ${expected ?? "unknown"}.`
+      });
+    }
+  }
+  const checks = runTargetChecks(target);
+  for (const check of checks) {
+    if (check.status === 0) continue;
+    issues.push({
+      type: "target-check-failed",
+      check: check.name,
+      message: `Target check failed: ${check.name} (${check.status ?? "unavailable"}).`
+    });
+  }
+  const assetCheck = checkInstalledAssets({
+    targetDir: target.path,
+    agentAssetsDir: options.agentAssetsDir,
+    registry: options.registry,
+    strictRegistry: true
+  });
+  issues.push(...assetCheck.issues.map((issue) => ({
+    type: issue.type,
+    targetPath: issue.targetPath,
+    message: issue.message
+  })));
+  try {
+    const expectedPlan = createAssetInstallPlan({
+      targetDir: target.path,
+      agentAssetsDir: options.agentAssetsDir,
+      registry: options.registry,
+      bundles: options.bundles,
+      bundleIds: target.assetBundles ?? [],
+      host: readTargetAssetHost(target.path) ?? "codex"
+    });
+    issues.push(...comparePortfolioAssetState({ targetDir: target.path, expectedPlan }).issues);
+  } catch (error) {
+    issues.push({
+      type: "asset-lock-drift",
+      message: error instanceof Error ? error.message : String(error)
+    });
+    if (!existsSync20(join19(target.path, ".pro-gov/assets.json"))) {
+      issues.push({ type: "bundle-drift", message: "Target asset manifest is missing." });
+    }
+  }
+  return {
+    id: target.id,
+    path: target.path,
+    profile: target.profile,
+    packages,
+    git: inspectGit(target.path),
+    checks,
+    issues: deduplicateIssues(issues)
+  };
+}
+function readTargetAssetHost(targetDir) {
+  const lockfile = readJson2(join19(targetDir, ".pro-gov/assets.lock.json"));
+  return isAssetRegistryHost(lockfile?.host) ? lockfile.host : void 0;
+}
+function isAssetRegistryHost(value) {
+  return value === "codex" || value === "claude-code" || value === "gemini-cli" || value === "antigravity";
+}
+function runTargetChecks(target) {
+  const proGovCli = join19(target.path, "node_modules/@pieai/pro-gov/dist/cli.js");
+  const docGovCli = join19(target.path, "node_modules/@pieai/doc-gov/dist/cli.js");
+  const commands = [
+    {
+      name: "pro-gov doctor",
+      cli: proGovCli,
+      args: target.profile === "engineering-runtime" ? ["doctor", "--strict-hooks"] : ["doctor"]
+    },
+    { name: "doc-gov router-check", cli: docGovCli, args: ["router-check"] },
+    { name: "doc-gov scan --check", cli: docGovCli, args: ["scan", "--check"] }
+  ];
+  return commands.map((command2) => {
+    if (!existsSync20(command2.cli)) return { name: command2.name, status: null };
+    const result = spawnSync6(process.execPath, [command2.cli, ...command2.args], {
+      cwd: target.path,
+      encoding: "utf8",
+      timeout: 3e4
+    });
+    return { name: command2.name, status: result.status };
+  });
+}
+function inspectGit(path) {
+  const inside = spawnSync6("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd: path,
+    encoding: "utf8"
+  });
+  if (inside.status !== 0) return { isRepository: false, dirty: false };
+  const status = spawnSync6("git", ["status", "--porcelain"], { cwd: path, encoding: "utf8" });
+  const branch = spawnSync6("git", ["branch", "--show-current"], { cwd: path, encoding: "utf8" });
+  return {
+    isRepository: true,
+    dirty: status.stdout.trim().length > 0,
+    branch: branch.stdout.trim() || void 0
+  };
+}
+function getExpectedPackageVersions() {
+  const proGovPackage = readJson2(findOwnPackageJson());
+  let docGovVersion;
+  try {
+    const require2 = createRequire2(import.meta.url);
+    const docGovPackage = readJson2(require2.resolve("@pieai/doc-gov/package.json"));
+    docGovVersion = docGovPackage?.version;
+  } catch {
+    docGovVersion = void 0;
+  }
+  return {
+    "@pieai/pro-gov": proGovPackage?.version,
+    "@pieai/doc-gov": docGovVersion
+  };
+}
+function findOwnPackageJson() {
+  let current = dirname11(fileURLToPath3(import.meta.url));
+  for (let depth = 0; depth < 5; depth += 1) {
+    const candidate = join19(current, "package.json");
+    if (existsSync20(candidate)) return candidate;
+    current = dirname11(current);
+  }
+  return "";
+}
+function readJson2(path) {
+  if (!path || !existsSync20(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync17(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function deduplicateIssues(issues) {
+  const seen = /* @__PURE__ */ new Set();
+  return issues.filter((issue) => {
+    const key = `${issue.type}\0${issue.packageName ?? ""}\0${issue.targetPath ?? ""}\0${issue.check ?? ""}\0${issue.message}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
 // src/commands/portfolio.ts
 function runPortfolio(args) {
   const [subcommand2, ...rest] = args;
   if (subcommand2 === "check") return runPortfolioCheck(rest);
   if (subcommand2 === "plan") return runPortfolioPlan(rest);
   if (subcommand2 === "assets-check") return runPortfolioAssetsCheck(rest);
-  printUsage3();
+  if (subcommand2 === "doctor") return runPortfolioDoctor(rest);
+  printUsage4();
   return 1;
 }
+function runPortfolioDoctor(args) {
+  const options = parsePortfolioOptions(args);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage4();
+    return 1;
+  }
+  const loaded = loadPortfolioManifest(options.value.configPath);
+  if (loaded.issues.length > 0 || !loaded.manifest) {
+    if (options.value.json) {
+      console.log(JSON.stringify({ ok: false, configPath: loaded.configPath, issues: loaded.issues, targets: [] }, null, 2));
+    } else {
+      for (const issue of loaded.issues) console.error(`${issue.type}: ${issue.message}`);
+    }
+    return 1;
+  }
+  const targets = getDefaultPortfolioTargets(loaded.manifest).filter(
+    (target) => !options.value.targetId || options.value.targetId === "all" || target.id === options.value.targetId
+  );
+  if (targets.length === 0) {
+    console.error(`Unknown portfolio target: ${options.value.targetId}`);
+    return 1;
+  }
+  const loadedAssets = loadAgentAssetRegistry({
+    agentAssetsDir: findPortfolioAgentAssetsDir(loaded.manifest)
+  });
+  if (loadedAssets.issues.length > 0) {
+    for (const issue of loadedAssets.issues) console.error(`${issue.type}: ${issue.message}`);
+    return 1;
+  }
+  const result = inspectPortfolio({
+    manifest: loaded.manifest,
+    targets,
+    agentAssetsDir: loadedAssets.agentAssetsDir,
+    registry: loadedAssets.registry,
+    bundles: loadAgentAssetBundles(loadedAssets.agentAssetsDir)
+  });
+  const output = { configPath: loaded.configPath, ...result };
+  if (options.value.json) {
+    console.log(JSON.stringify(output, null, 2));
+  } else if (result.ok) {
+    console.log(`portfolio doctor passed (${targets.length} targets)`);
+  } else {
+    for (const issue of result.hostTooling.issues) console.log(`${issue.host}	${issue.type}: ${issue.message}`);
+    for (const target of result.targets) {
+      for (const issue of target.issues) console.log(`${target.id}	${issue.type}: ${issue.message}`);
+    }
+  }
+  return result.ok ? 0 : 1;
+}
 function runPortfolioCheck(args) {
   const options = parsePortfolioOptions(args);
   if (!options.ok) {
     console.error(options.error);
-    printUsage3();
+    printUsage4();
     return 1;
   }
   const loaded = loadPortfolioManifest(options.value.configPath);
@@ -2923,7 +3692,7 @@ function runPortfolioPlan(args) {
   const options = parsePortfolioOptions(args);
   if (!options.ok) {
     console.error(options.error);
-    printUsage3();
+    printUsage4();
     return 1;
   }
   const loaded = loadPortfolioManifest(options.value.configPath);
@@ -2997,7 +3766,7 @@ function runPortfolioAssetsCheck(args) {
   const options = parsePortfolioOptions(args);
   if (!options.ok) {
     console.error(options.error);
-    printUsage3();
+    printUsage4();
     return 1;
   }
   const loaded = loadPortfolioManifest(options.value.configPath);
@@ -3113,7 +3882,7 @@ function parsePortfolioOptions(args) {
       index += 1;
     } else if (arg === "--host") {
       const host = args[index + 1];
-      if (!isHost2(host)) return { ok: false, error: "Expected --host codex|claude-code" };
+      if (!isHost2(host)) return { ok: false, error: "Expected --host codex|claude-code|gemini-cli|antigravity" };
       options.host = host;
       index += 1;
     } else if (arg === "--json") {
@@ -3129,19 +3898,20 @@ function isHost2(value) {
   return value === "codex" || value === "claude-code" || value === "gemini-cli" || value === "antigravity";
 }
 function findPortfolioAgentAssetsDir(manifest) {
-  const agentAssetsDir = manifest?.executionEngine?.path ? join17(manifest.executionEngine.path, "agent-assets") : void 0;
-  return agentAssetsDir && existsSync18(join17(agentAssetsDir, "registry.json")) ? agentAssetsDir : void 0;
+  const agentAssetsDir = manifest?.executionEngine?.path ? join20(manifest.executionEngine.path, "agent-assets") : void 0;
+  return agentAssetsDir && existsSync21(join20(agentAssetsDir, "registry.json")) ? agentAssetsDir : void 0;
 }
-function printUsage3() {
+function printUsage4() {
   console.error("Usage:");
   console.error("  pro-gov portfolio check --config <path> [--json]");
   console.error("  pro-gov portfolio plan --config <path> [--target <id|all>] [--host codex|claude-code|gemini-cli|antigravity] [--json]");
   console.error("  pro-gov portfolio assets-check --config <path> [--target <id|all>] [--json]");
+  console.error("  pro-gov portfolio doctor --config <path> [--target <id|all>] [--json]");
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync19, readFileSync as readFileSync15 } from "node:fs";
-import { join as join18 } from "node:path";
+import { existsSync as existsSync22, readFileSync as readFileSync18 } from "node:fs";
+import { join as join21 } from "node:path";
 function runSync(args) {
   if (!args.includes("--check")) {
     console.error("pro-gov sync is read-only and requires --check.");
@@ -3168,16 +3938,16 @@ function runSync(args) {
   console.log("pro-gov sync check");
   console.log(`profile: ${profile}`);
   for (const file of planStarterFiles(profile)) {
-    const targetPath = join18(process.cwd(), file.targetPath);
-    if (!existsSync19(targetPath)) {
+    const targetPath = join21(process.cwd(), file.targetPath);
+    if (!existsSync22(targetPath)) {
       if (file.ownership === "optional-guardrail") continue;
       console.log(`missing: ${file.targetPath}`);
       differences += 1;
       continue;
     }
     if (file.ownership === "project-local-seed") continue;
-    const source = readFileSync15(file.absoluteSourcePath, "utf8");
-    const target = readFileSync15(targetPath, "utf8");
+    const source = readFileSync18(file.absoluteSourcePath, "utf8");
+    const target = readFileSync18(targetPath, "utf8");
     if (source !== target) {
       console.log(`different: ${file.targetPath}`);
       differences += 1;
@@ -3192,7 +3962,7 @@ function runSync(args) {
 }
 function inferInstalledProfile(root) {
   const installed = ["engineering-runtime", "doc-only"].filter(
-    (profile) => existsSync19(join18(root, `docs/governance/agents-routing/${profile}-v0.9.md`))
+    (profile) => existsSync22(join21(root, `docs/governance/agents-routing/${profile}-v0.9.md`))
   );
   return installed.length === 1 ? installed[0] : void 0;
 }
@@ -3215,6 +3985,8 @@ var COMMANDS = [
   "portfolio check --config <path> [--json]",
   "portfolio plan --config <path> [--target <id|all>] [--json]",
   "portfolio assets-check --config <path> [--target <id|all>] [--json]",
+  "portfolio doctor --config <path> [--target <id|all>] [--json]",
+  "learn recall --query <text> [--target <path>] [--limit <n>] [--json]",
   "lens scan [--target <path>] [--json]",
   "lens inspect [--target <path>] [--format text|json]",
   "lens report --target <path> --out <path>",
@@ -3233,6 +4005,7 @@ async function main() {
     return command ? 0 : 1;
   }
   if (command === "assets") return runAssets(process.argv.slice(3));
+  if (command === "learn") return runLearn(process.argv.slice(3));
   if (command === "lens") return runLens(process.argv.slice(3));
   if (command === "portfolio") return runPortfolio(process.argv.slice(3));
   if (command === "host-hook") return runHostHook(process.argv.slice(3));