@pieai/pro-gov 0.3.12 → 0.3.13

package/README.md

@@ -148,6 +148,11 @@ engineering work. The default PGS pattern is a Compound Gate: run
 skipped. Full CE workflows such as `ce-plan`, `ce-work`, and `lfg` remain
 explicit user choices.
 
+PGS Learning Recall is the pre-work companion to that post-work gate. Before
+non-trivial implementation, debugging, release, architecture, or portfolio-sync
+work, run `pro-gov learn recall --query "<task summary>"` and read relevant
+`docs/solutions/**` or `CONCEPTS.md` hits before changing files.
+
 Engineering-runtime starters include cross-host Stop hooks for Codex,
 Claude Code, and Antigravity. Those hooks call `pro-gov host-hook` and require
 the final report to include either:

package/assets/docs/reference/adoption/adoption-playbook.md

@@ -211,6 +211,16 @@ Use Compound Engineering by default only as the post-work Compound Gate:
 `ce-compound` captures reusable lessons when they exist; otherwise the agent
 reports a skip reason. Full CE workflows require an explicit user request.
 
+Use PGS Learning Recall before non-trivial work:
+
+```bash
+pro-gov learn recall --query "<task summary>"
+```
+
+This reads the project's existing `docs/solutions/**` and `CONCEPTS.md` records
+so prior lessons can shape the work without making Compound Engineering the
+default execution workflow.
+
 The host-hook gate is deliberately small. It does not make Compound Engineering
 the main workflow. It only blocks a final completion report that looks like
 finished engineering work but does not say whether the Compound Gate ran or was

package/assets/docs/reference/adoption/recommended-agent-tooling.md

@@ -78,6 +78,15 @@ Superpowers completes verified work
 -> run ce-compound or report a skip reason
 ```
 
+PGS Learning Recall is the matching pre-work step:
+
+```bash
+pro-gov learn recall --query "<task summary>"
+```
+
+It searches `docs/solutions/**` and `CONCEPTS.md` so agents can reuse prior
+lessons without making Compound Engineering the default execution workflow.
+
 Do not make routine tasks choose between Superpowers and Compound Engineering as
 competing default engineering processes. Use CE's full `ce-plan`, `ce-work`, or
 `lfg` flow only when the user explicitly asks for it.
@@ -107,6 +116,7 @@ For an engineering/runtime project:
 ```text
 install PGS packages
 -> keep Superpowers available for engineering workflows
+-> run pro-gov learn recall before non-trivial work
 -> use Compound Engineering's ce-compound as the post-work learning tail
 -> install Ponytail but keep global mode off
 -> activate Ponytail only when a bounded simplicity review would help

package/assets/integrations/compound-engineering.md

@@ -11,6 +11,7 @@ Think of an AI project as a workshop:
 - Superpowers is the default cooking process for engineering work.
 - Compound Engineering's `ce-compound` is the recipe notebook written after a
   non-trivial dish is proven to work.
+- `pro-gov learn recall` is the recipe-card search before the next dish starts.
 - Ponytail is the cost and complexity adviser.
 
 The default path is one main process with one learning tail. Do not make every
@@ -25,12 +26,30 @@ capture loop by default, not as a second default execution engine.
 Use this order:
 
 1. PGS routes the task and selects the project lane.
-2. Superpowers handles the normal engineering workflow when that lane needs one.
-3. Ponytail may run as an explicit complexity review when useful.
-4. The agent must pass the Compound Gate before final reporting.
-5. Doc Gov validates governed documentation and ignores CE-owned external
+2. For non-trivial engineering work, run Learning Recall against the task
+   summary and read relevant prior lessons.
+3. Superpowers handles the normal engineering workflow when that lane needs one.
+4. Ponytail may run as an explicit complexity review when useful.
+5. The agent must pass the Compound Gate before final reporting.
+6. Doc Gov validates governed documentation and ignores CE-owned external
    artifacts.
 
+## Learning Recall
+
+CE writes the reusable lesson. PGS recalls it.
+
+Before non-trivial implementation, debugging, release, architecture, or
+portfolio-sync work, run:
+
+```bash
+pro-gov learn recall --query "<task summary>"
+```
+
+Read the relevant hits before changing files. A no-hit result is acceptable;
+do not scan every `docs/solutions/**` file by hand. The recall command is a
+small search surface over `docs/solutions/**` and `CONCEPTS.md`, not a second
+workflow engine, vector database, or CE replacement.
+
 ## Compound Gate
 
 Every completed non-trivial engineering task must pass the Compound Gate:

package/assets/integrations/superpowers.md

@@ -8,13 +8,15 @@ Think of an AI project as a building site:
 
 - PGS is the traffic desk and inspection station.
 - Superpowers is the construction process.
+- `pro-gov learn recall` is the pre-work lookup for reusable lessons.
 - Compound Engineering's `ce-compound` is the knowledge-capture tail.
 - Ponytail is an optional cost and complexity adviser.
 
 PGS chooses the lane. Superpowers makes sure the work follows the right
-engineering process. Compound Engineering records reusable lessons after
-verified work. Ponytail may suggest a leaner implementation, but it cannot
-cancel the process or the final inspection.
+engineering process. Learning Recall checks prior lessons before work starts.
+Compound Engineering records reusable lessons after verified work. Ponytail may
+suggest a leaner implementation, but it cannot cancel the process or the final
+inspection.
 
 ## Boundary
 
@@ -32,6 +34,7 @@ Project Governance System owns:
 - documentation lifecycle
 - agents routing
 - current work index conventions
+- pre-work learning recall through `pro-gov learn recall`
 - the governed location and boundary for externally sourced AI evidence rules
 
 Ponytail, when explicitly enabled for a task, may advise on:
@@ -59,17 +62,20 @@ Durable outputs should map back to the project's doc-gov layers:
 
 ## Execution Order
 
-Agents routing classifies first. Superpowers executes inside the selected lane.
-Optional Ponytail advice may run after those responsibilities are known. It may
-make the implementation leaner, but it must not remove explicit requirements or
-reduce how correctness is proven. The Compound Gate runs near the end, before
-final reporting, to decide whether verified work produced reusable learning.
+Agents routing classifies first. For non-trivial work, Learning Recall checks
+prior `docs/solutions/**` and `CONCEPTS.md` records before files change.
+Superpowers executes inside the selected lane. Optional Ponytail advice may run
+after those responsibilities are known. It may make the implementation leaner,
+but it must not remove explicit requirements or reduce how correctness is
+proven. The Compound Gate runs near the end, before final reporting, to decide
+whether verified work produced reusable learning.
 
 ```mermaid
 flowchart TD
   A["Task arrives"] --> B["Read project router and current work"]
   B --> C["Classify profile and lane"]
-  C --> D{"Does this lane need a Superpowers workflow?"}
+  C --> R["Run Learning Recall for non-trivial work"]
+  R --> D{"Does this lane need a Superpowers workflow?"}
   D -- "yes" --> E["Use the matching Superpowers skill"]
   D -- "no" --> F["Use the local non-Superpowers lane rules"]
   E --> G{"Would an explicit simplicity review help?"}

package/assets/profiles/engineering-runtime/profile.md

@@ -45,3 +45,8 @@ Stop hooks that call `pro-gov host-hook`. Use `pro-gov doctor --strict-hooks`
 after sync to confirm the exit gate is wired. The hook enforces the Compound
 Gate final-report marker; it does not replace verification, tests, or
 `ce-compound` itself.
+
+For non-trivial engineering work, run `pro-gov learn recall --query "<task
+summary>"` before changing files so existing `docs/solutions/**` and
+`CONCEPTS.md` lessons can shape the work without enabling a second default
+workflow.

package/assets/starter/AGENTS.template.md

@@ -18,6 +18,9 @@
    - `docs/governance/agents-routing/engineering-runtime-v0.9.md`, or
    - `docs/governance/agents-routing/doc-only-v0.9.md`
 7. `docs/reference/execution/current-work.md`
+8. Before non-trivial implementation, debugging, release, architecture, or
+   migration work, run `pro-gov learn recall --query "<task summary>"` and read
+   any relevant prior-learning hits before changing files.
 
 ## Governance
 
@@ -39,6 +42,7 @@
 - Point to the chosen agents-routing file from `docs/governance/agents-routing/`.
 - Engineering projects may use Superpowers, Directed Development, GStack, or other external workflows only inside the selected lane; do not copy upstream integration guides into the target project by default.
 - For engineering projects, Superpowers is the default engineering workflow. Compound Engineering is used by default only as the post-work Compound Gate through `ce-compound`; full CE workflows require an explicit user request.
+- For engineering projects, PGS Learning Recall is the pre-work companion to that post-work gate: recall existing lessons first, then do the work, then decide whether a new lesson should be compounded.
 - Engineering projects should have PGS Stop hooks wired for Codex, Claude Code, and Antigravity. Before final reporting after completed engineering work, report `Compound Gate: ran ce-compound -> <path>` or `Compound Gate: skipped -> <reason>`.
 - Doc-only projects should say that Superpowers TDD and Directed Development are not enabled by default.
 - External workflow systems such as Superpowers or GStack run inside the lane selected by this router. They must not replace this project router.

package/cli-guide.md

@@ -20,6 +20,7 @@ pro-gov portfolio check --config /path/to/portfolio.json
 pro-gov portfolio plan --config /path/to/portfolio.json --target web-app --json
 pro-gov portfolio assets-check --config /path/to/portfolio.json --json
 pro-gov portfolio doctor --config /path/to/portfolio.json --json
+pro-gov learn recall --query "release downstream sync" --target .
 pro-gov lens inspect --target .
 pro-gov lens report --target . --out .pro-gov/lens-report.md
 pro-gov lens audit init --target /path/to/project --out audits/project/2026-07-01
@@ -42,6 +43,13 @@ but checks project-local seeds such as `AGENTS.md`, project policy, and current
 work for presence only. It infers the installed profile when exactly one route
 exists; `--profile` resolves an empty or temporarily ambiguous target.
 
+`learn recall` is the pre-work companion to Compound Engineering's post-work
+`ce-compound` learning records. It searches `docs/solutions/**` and
+`CONCEPTS.md` in the target repository and returns the most relevant prior
+lessons for the current task. Use it before non-trivial implementation,
+debugging, release, architecture, or portfolio-sync work. It is read-only and
+does not require a full local PGS checkout.
+
 Full upstream-checkout commands:
 
 ```bash

package/dist/cli.js

@@ -2204,13 +2204,230 @@ function readFlag(args, flag) {
   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.");
+  }
+  return 0;
+}
+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 readFlagValue(args, index, flag) {
+  const value = args[index + 1];
+  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
 import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync6 } from "node:fs";
 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",
@@ -2230,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,
@@ -2257,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,
@@ -2290,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)) {
@@ -2555,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",
@@ -2573,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(),
@@ -2625,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))));
     }
   }
 }
@@ -2651,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);
@@ -2673,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);
@@ -2694,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);
@@ -2710,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 });
@@ -2726,7 +2943,7 @@ function runLensAudit(args) {
     }
     return result.ok ? 0 : 1;
   }
-  printUsage2();
+  printUsage3();
   return 1;
 }
 function parseLensOptions(args, subcommand2) {
@@ -2778,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>");
@@ -2787,16 +3004,16 @@ function printUsage2() {
 }
 
 // src/commands/portfolio.ts
-import { existsSync as existsSync20 } from "node:fs";
-import { join as join19 } 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 { 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,
@@ -2956,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,
@@ -3027,9 +3244,9 @@ function isRecord2(value) {
 
 // src/portfolio/doctor.ts
 import { spawnSync as spawnSync6 } from "node:child_process";
-import { existsSync as existsSync19, readFileSync as readFileSync16 } from "node:fs";
+import { existsSync as existsSync20, readFileSync as readFileSync17 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
-import { dirname as dirname11, join as join18 } from "node:path";
+import { dirname as dirname11, join as join19 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/host-tooling/inventory.ts
@@ -3120,13 +3337,13 @@ function isRecord3(value) {
 }
 
 // src/portfolio/asset-state.ts
-import { existsSync as existsSync18, lstatSync as lstatSync5, readFileSync as readFileSync15 } from "node:fs";
-import { join as join17 } from "node:path";
+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(join17(options.targetDir, ".pro-gov/assets.json"));
-  const currentLock = readJsonFile(join17(options.targetDir, ".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({
@@ -3149,7 +3366,7 @@ function comparePortfolioAssetState(options) {
   const expectedTargets = new Set((expectedLock?.assets ?? []).map((entry) => entry.targetPath));
   for (const entry of currentLock?.assets ?? []) {
     if (expectedTargets.has(entry.targetPath)) continue;
-    const targetAbsolutePath = join17(options.targetDir, entry.targetPath);
+    const targetAbsolutePath = join18(options.targetDir, entry.targetPath);
     if (!pathIsSymlink(targetAbsolutePath)) continue;
     issues.push({
       type: "orphaned-managed-symlink",
@@ -3171,9 +3388,9 @@ function readPlanDocument(plan, targetPath) {
   }
 }
 function readJsonFile(path) {
-  if (!existsSync18(path)) return void 0;
+  if (!existsSync19(path)) return void 0;
   try {
-    return JSON.parse(readFileSync15(path, "utf8"));
+    return JSON.parse(readFileSync16(path, "utf8"));
   } catch {
     return void 0;
   }
@@ -3222,11 +3439,11 @@ function inspectPortfolio(options) {
 function inspectTarget(options) {
   const { target } = options;
   const issues = [];
-  const packageJson = readJson2(join18(target.path, "package.json"));
+  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(join18(target.path, "node_modules", packageName, "package.json"));
+    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 };
@@ -3272,7 +3489,7 @@ function inspectTarget(options) {
       registry: options.registry,
       bundles: options.bundles,
       bundleIds: target.assetBundles ?? [],
-      host: "codex"
+      host: readTargetAssetHost(target.path) ?? "codex"
     });
     issues.push(...comparePortfolioAssetState({ targetDir: target.path, expectedPlan }).issues);
   } catch (error) {
@@ -3280,7 +3497,7 @@ function inspectTarget(options) {
       type: "asset-lock-drift",
       message: error instanceof Error ? error.message : String(error)
     });
-    if (!existsSync19(join18(target.path, ".pro-gov/assets.json"))) {
+    if (!existsSync20(join19(target.path, ".pro-gov/assets.json"))) {
       issues.push({ type: "bundle-drift", message: "Target asset manifest is missing." });
     }
   }
@@ -3294,9 +3511,16 @@ function inspectTarget(options) {
     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 = join18(target.path, "node_modules/@pieai/pro-gov/dist/cli.js");
-  const docGovCli = join18(target.path, "node_modules/@pieai/doc-gov/dist/cli.js");
+  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",
@@ -3307,7 +3531,7 @@ function runTargetChecks(target) {
     { name: "doc-gov scan --check", cli: docGovCli, args: ["scan", "--check"] }
   ];
   return commands.map((command2) => {
-    if (!existsSync19(command2.cli)) return { name: command2.name, status: null };
+    if (!existsSync20(command2.cli)) return { name: command2.name, status: null };
     const result = spawnSync6(process.execPath, [command2.cli, ...command2.args], {
       cwd: target.path,
       encoding: "utf8",
@@ -3348,16 +3572,16 @@ function getExpectedPackageVersions() {
 function findOwnPackageJson() {
   let current = dirname11(fileURLToPath3(import.meta.url));
   for (let depth = 0; depth < 5; depth += 1) {
-    const candidate = join18(current, "package.json");
-    if (existsSync19(candidate)) return candidate;
+    const candidate = join19(current, "package.json");
+    if (existsSync20(candidate)) return candidate;
     current = dirname11(current);
   }
   return "";
 }
 function readJson2(path) {
-  if (!path || !existsSync19(path)) return void 0;
+  if (!path || !existsSync20(path)) return void 0;
   try {
-    return JSON.parse(readFileSync16(path, "utf8"));
+    return JSON.parse(readFileSync17(path, "utf8"));
   } catch {
     return void 0;
   }
@@ -3379,14 +3603,14 @@ function runPortfolio(args) {
   if (subcommand2 === "plan") return runPortfolioPlan(rest);
   if (subcommand2 === "assets-check") return runPortfolioAssetsCheck(rest);
   if (subcommand2 === "doctor") return runPortfolioDoctor(rest);
-  printUsage3();
+  printUsage4();
   return 1;
 }
 function runPortfolioDoctor(args) {
   const options = parsePortfolioOptions(args);
   if (!options.ok) {
     console.error(options.error);
-    printUsage3();
+    printUsage4();
     return 1;
   }
   const loaded = loadPortfolioManifest(options.value.configPath);
@@ -3436,7 +3660,7 @@ function runPortfolioCheck(args) {
   const options = parsePortfolioOptions(args);
   if (!options.ok) {
     console.error(options.error);
-    printUsage3();
+    printUsage4();
     return 1;
   }
   const loaded = loadPortfolioManifest(options.value.configPath);
@@ -3468,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);
@@ -3542,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);
@@ -3658,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") {
@@ -3674,10 +3898,10 @@ function isHost2(value) {
   return value === "codex" || value === "claude-code" || value === "gemini-cli" || value === "antigravity";
 }
 function findPortfolioAgentAssetsDir(manifest) {
-  const agentAssetsDir = manifest?.executionEngine?.path ? join19(manifest.executionEngine.path, "agent-assets") : void 0;
-  return agentAssetsDir && existsSync20(join19(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]");
@@ -3686,8 +3910,8 @@ function printUsage3() {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync21, readFileSync as readFileSync17 } from "node:fs";
-import { join as join20 } 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.");
@@ -3714,16 +3938,16 @@ function runSync(args) {
   console.log("pro-gov sync check");
   console.log(`profile: ${profile}`);
   for (const file of planStarterFiles(profile)) {
-    const targetPath = join20(process.cwd(), file.targetPath);
-    if (!existsSync21(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 = readFileSync17(file.absoluteSourcePath, "utf8");
-    const target = readFileSync17(targetPath, "utf8");
+    const source = readFileSync18(file.absoluteSourcePath, "utf8");
+    const target = readFileSync18(targetPath, "utf8");
     if (source !== target) {
       console.log(`different: ${file.targetPath}`);
       differences += 1;
@@ -3738,7 +3962,7 @@ function runSync(args) {
 }
 function inferInstalledProfile(root) {
   const installed = ["engineering-runtime", "doc-only"].filter(
-    (profile) => existsSync21(join20(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;
 }
@@ -3762,6 +3986,7 @@ var COMMANDS = [
   "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>",
@@ -3780,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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pieai/pro-gov",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Project-level distribution kit for Project Governance System.",
   "keywords": [
     "ai-agents",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pieai/doc-gov": "^0.3.12"
+    "@pieai/doc-gov": "^0.3.13"
   },
   "devDependencies": {
     "@types/node": "24.13.2",