@pieai/pro-gov 0.3.9 → 0.3.11

package/README.md

@@ -149,8 +149,20 @@ Compound Gate: skipped -> <reason>
 ```
 
 Use `pro-gov doctor --strict-hooks` after syncing an engineering project to
-verify that the host configs are wired. Open a fresh AI session after installing
-or changing hooks; old sessions may not reload host configuration.
+verify that the host configs are wired. This is a wiring check: it proves the
+project calls `pro-gov host-hook` for Codex, Claude Code, and Antigravity. The
+host behavior contract is covered by PGS package tests against recorded
+per-host Stop/SubagentStop fixtures. Open a fresh AI session after installing or
+changing hooks; old sessions may not reload host configuration.
+
+Antigravity hook commands enable `PGS_HOST_HOOK_DEBUG=1` by default in PGS
+starters. The hook writes local diagnostics to `.git/pro-gov-hook-debug/` when
+it is actually invoked, including the input summary, decision, and output JSON.
+This directory lives inside Git's private metadata so it does not dirty the
+worktree. If an Antigravity test does not create a diagnostic file, inspect
+whether the host loaded `.agents/hooks.json` before changing PGS policy.
+`.pro-gov/assets.json` is only an asset-install manifest; its `host` field does
+not control runtime hook dispatch.
 
 Ponytail can be installed as an optional complexity adviser. Keep its global mode
 `off`; test `lite` in one isolated task before considering a stronger mode.

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

@@ -6,7 +6,7 @@ status: stable
 canonical: true
 owner: human
 created: 2026-05-06
-last_reviewed: 2026-06-15
+last_reviewed: 2026-07-02
 domain: adoption
 tags:
   - adoption
@@ -92,8 +92,17 @@ Current package-based method:
 - copy `starter/lefthook.template.yml` to `lefthook.yml` and
   `starter/.github/workflows/docs-check.yml` to `.github/workflows/docs-check.yml`
   when the target project is ready for standard guardrails
+- for an `engineering-runtime` target, install the three host-hook starter files
+  or merge their Stop/SubagentStop entries into the target's existing host
+  config:
+  - `.codex/hooks.json`
+  - `.claude/settings.json`
+  - `.agents/hooks.json`
 - run `doc-gov doctor` after wiring guardrails to verify they are actually
   connected
+- run `pro-gov doctor --strict-hooks` after wiring host hooks to prove the
+  target has the expected host-hook configuration for Codex, Claude Code, and
+  Antigravity
 - treat the npm package as the CLI source and the local `docs/governance/`
   files as the project's checked-in governance contract
 
@@ -198,6 +207,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.
 
+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
+skipped:
+
+```text
+Compound Gate: ran ce-compound -> <path>
+Compound Gate: skipped -> <reason>
+```
+
 ### Doc-Only
 
 Add:
@@ -257,6 +276,7 @@ For the v0.9 structural migration, use
 Minimum:
 
 ```bash
+pnpm pro-gov doctor --strict-hooks
 pnpm doc-gov check
 pnpm doc-gov router-check
 pnpm doc-gov scan --check
@@ -266,6 +286,21 @@ pnpm doc-gov doctor
 git diff --check
 ```
 
+Use `pro-gov doctor --strict-hooks` for engineering-runtime projects. Doc-only
+projects may omit strict host hooks unless they intentionally adopt the
+engineering runtime profile.
+
+`pro-gov doctor --strict-hooks` is a wiring check, not a live host simulation.
+It proves the project has hook files that call `pro-gov host-hook`; PGS package
+tests prove the expected Stop/SubagentStop behavior for the supported host
+schemas. After installing or changing hooks, validate from a fresh AI session.
+For Antigravity, a real invocation writes diagnostics under
+`.git/pro-gov-hook-debug/` because the starter hook command sets
+`PGS_HOST_HOOK_DEBUG=1`. Absence of a diagnostic file after a fresh
+Antigravity session usually means the host did not load or run
+`.agents/hooks.json`. The `.pro-gov/assets.json` `host` field records asset
+placement only; it does not control runtime hook dispatch.
+
 Engineering projects should also run their local verification ladder.
 
 ## Example: Migrating A Runtime Product

package/assets/starter/.agents/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host antigravity --event Stop; elif [ -f packages/pro-gov/src/cli.ts ] && command -v pnpm >/dev/null 2>&1; then pnpm --silent --filter @pieai/pro-gov dev host-hook --host antigravity --event Stop; else npx --no-install @pieai/pro-gov host-hook --host antigravity --event Stop; fi",
+            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then PGS_HOST_HOOK_DEBUG=1 ./node_modules/.bin/pro-gov host-hook --host antigravity --event Stop; elif [ -f packages/pro-gov/src/cli.ts ] && command -v pnpm >/dev/null 2>&1; then PGS_HOST_HOOK_DEBUG=1 pnpm --silent --filter @pieai/pro-gov dev host-hook --host antigravity --event Stop; else PGS_HOST_HOOK_DEBUG=1 npx --no-install @pieai/pro-gov host-hook --host antigravity --event Stop; fi",
             "timeout": 30
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host antigravity --event SubagentStop; elif [ -f packages/pro-gov/src/cli.ts ] && command -v pnpm >/dev/null 2>&1; then pnpm --silent --filter @pieai/pro-gov dev host-hook --host antigravity --event SubagentStop; else npx --no-install @pieai/pro-gov host-hook --host antigravity --event SubagentStop; fi",
+            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then PGS_HOST_HOOK_DEBUG=1 ./node_modules/.bin/pro-gov host-hook --host antigravity --event SubagentStop; elif [ -f packages/pro-gov/src/cli.ts ] && command -v pnpm >/dev/null 2>&1; then PGS_HOST_HOOK_DEBUG=1 pnpm --silent --filter @pieai/pro-gov dev host-hook --host antigravity --event SubagentStop; else PGS_HOST_HOOK_DEBUG=1 npx --no-install @pieai/pro-gov host-hook --host antigravity --event SubagentStop; fi",
             "timeout": 30
           }
         ]

package/dist/cli.js

@@ -1628,6 +1628,9 @@ function checkStrictHostHooks(root) {
     if (!content.includes("pro-gov host-hook") || !content.includes(`--host ${entry.host}`)) {
       issues.push(`host-hooks: ${entry.path} does not call pro-gov host-hook for ${entry.host}`);
     }
+    if (entry.host === "antigravity" && !content.includes("PGS_HOST_HOOK_DEBUG=1")) {
+      issues.push(`host-hooks: ${entry.path} does not enable PGS_HOST_HOOK_DEBUG=1 for Antigravity diagnostics`);
+    }
   }
   return issues;
 }
@@ -1636,15 +1639,23 @@ function isEngineeringRuntimeProject(root) {
 }
 
 // src/commands/host-hook.ts
-import { readFileSync as readFileSync9 } from "node:fs";
+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";
 
 // src/host-hooks/host-hook-runner.ts
+import { closeSync, openSync, readFileSync as readFileSync9, readSync, statSync as statSync3 } from "node:fs";
 var gateMarkerPattern = /Compound Gate:\s*(ran ce-compound|skipped)\s*->/i;
 var completionSignalPatterns = [
   /\b(done|completed|implemented|fixed|verified|validated|shipped|pushed|committed)\b/i,
   /\b(tests?|typecheck|build|lint|doctor|pack)\b.*\b(pass|passed|green|succeed|succeeded|ok)\b/i,
   /\b(changed|updated|modified|created|deleted|refactored)\b.*\b(files?|docs?|tests?|hooks?|configs?)\b/i,
-  /完成|已完成|修好了|实现了|验证通过|测试通过|已经提交|已经推送|提交并推送/
+  /已完成|完成了|修好了|实现了|验证通过|测试通过|已经提交|已经推送|提交并推送|已提交|已推送/
+];
+var negativeCompletionSignalPatterns = [
+  /\b(not done|not completed|not implemented|not fixed|did not complete|didn't complete|have not completed|haven't completed)\b/i,
+  /没有完成|未完成|还没完成|没有改动|未改动|没有修改|未修改/
 ];
 var compoundGateInstruction = [
   "Before final reporting, pass the PGS Compound Gate.",
@@ -1653,6 +1664,7 @@ var compoundGateInstruction = [
   "If there is no reusable learning, report:",
   "Compound Gate: skipped -> <reason>"
 ].join("\n");
+var maxTranscriptBytes = 2 * 1024 * 1024;
 function evaluateHostHook(request) {
   if (request.event !== "Stop" && request.event !== "SubagentStop") {
     return { action: "allow" };
@@ -1694,7 +1706,7 @@ function formatHostHookOutput(host, event, decision) {
   }
   if (host === "claude" || host === "claude-code") {
     if (event === "Stop" || event === "SubagentStop") {
-      return { ok: false, reason: decision.reason };
+      return { decision: "block", reason: decision.reason };
     }
     if (decision.action === "block") {
       return {
@@ -1723,11 +1735,14 @@ function normalizeStopInput(input) {
     return { lastAssistantMessage: void 0, stopHookActive: false };
   }
   return {
-    lastAssistantMessage: findString(input, ["last_assistant_message", "lastAssistantMessage", "message", "text"]),
+    lastAssistantMessage: findString(input, ["last_assistant_message", "lastAssistantMessage", "message", "text"]) ?? findLastAssistantMessageFromTranscript(findString(input, ["agent_transcript_path", "agentTranscriptPath"])) ?? findLastAssistantMessageFromTranscript(findString(input, ["transcript_path", "transcriptPath"])),
     stopHookActive: findBoolean(input, ["stop_hook_active", "stopHookActive"]) ?? false
   };
 }
 function looksLikeCompletedEngineeringWork(message) {
+  if (negativeCompletionSignalPatterns.some((pattern) => pattern.test(message))) {
+    return false;
+  }
   return completionSignalPatterns.some((pattern) => pattern.test(message));
 }
 function findString(input, keys) {
@@ -1748,6 +1763,86 @@ function findBoolean(input, keys) {
   }
   return void 0;
 }
+function findLastAssistantMessageFromTranscript(path) {
+  if (!path || path.startsWith("~/")) {
+    return void 0;
+  }
+  let content;
+  try {
+    content = readTranscriptTail(path);
+  } catch {
+    return void 0;
+  }
+  const lines = content.split(/\r?\n/);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index]?.trim();
+    if (!line) {
+      continue;
+    }
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const message = extractAssistantText(record);
+    if (message) {
+      return message;
+    }
+  }
+  return void 0;
+}
+function readTranscriptTail(path) {
+  const size = statSync3(path).size;
+  if (size <= maxTranscriptBytes) {
+    return readFileSync9(path, "utf8");
+  }
+  const fd = openSync(path, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(maxTranscriptBytes);
+    readSync(fd, buffer, 0, maxTranscriptBytes, size - maxTranscriptBytes);
+    return buffer.toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+function extractAssistantText(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const nested = value.message;
+  const role = findString(value, ["role", "type"]);
+  if (isRecord(nested)) {
+    const nestedRole = findString(nested, ["role", "type"]);
+    if (nestedRole === "assistant") {
+      return extractTextContent(nested.content);
+    }
+  }
+  if (role === "assistant") {
+    return extractTextContent(value.content) ?? extractTextContent(value.text);
+  }
+  return void 0;
+}
+function extractTextContent(value) {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value;
+  }
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const parts = [];
+  for (const item of value) {
+    if (typeof item === "string") {
+      parts.push(item);
+      continue;
+    }
+    if (isRecord(item) && typeof item.text === "string") {
+      parts.push(item.text);
+    }
+  }
+  const text = parts.join("\n").trim();
+  return text.length > 0 ? text : void 0;
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1761,7 +1856,9 @@ function isHostHookEvent(value) {
 }
 
 // src/commands/host-hook.ts
-function runHostHook(args) {
+var defaultStdinTimeoutMs = 750;
+var maxDebugRawInputBytes = 256 * 1024;
+async function runHostHook(args) {
   const host = readOption(args, "--host");
   const event = readOption(args, "--event");
   if (!isHostHookHost(host)) {
@@ -1772,9 +1869,18 @@ function runHostHook(args) {
     console.error("Expected --event <Stop|SubagentStop|PreToolUse|PostToolUse|UserPromptSubmit>");
     return 1;
   }
-  const input = readStdinJson();
+  const rawInput = await readStdinText(defaultStdinTimeoutMs);
+  const input = parseStdinJson(rawInput);
   const decision = evaluateHostHook({ host, event, input });
   const output = formatHostHookOutput(host, event, decision);
+  writeDebugLogIfRequested(args, {
+    decision,
+    event,
+    host,
+    input,
+    output,
+    rawInput
+  });
   console.log(`${JSON.stringify(output)}
 `);
   return 0;
@@ -1784,8 +1890,7 @@ function readOption(args, name) {
   if (index < 0) return void 0;
   return args[index + 1];
 }
-function readStdinJson() {
-  const raw = readFileSync9(0, "utf8").trim();
+function parseStdinJson(raw) {
   if (!raw) return {};
   try {
     return JSON.parse(raw);
@@ -1793,10 +1898,106 @@ function readStdinJson() {
     return {};
   }
 }
+function readStdinText(timeoutMs) {
+  if (process.stdin.isTTY) {
+    return Promise.resolve("");
+  }
+  process.stdin.setEncoding("utf8");
+  return new Promise((resolveText) => {
+    let settled = false;
+    let content = "";
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      process.stdin.off("data", onData);
+      process.stdin.off("end", settle);
+      process.stdin.off("error", settle);
+      process.stdin.pause();
+      resolveText(content.trim());
+    };
+    const onData = (chunk) => {
+      content += chunk.toString();
+    };
+    const timer = setTimeout(settle, timeoutMs);
+    timer.unref();
+    process.stdin.on("data", onData);
+    process.stdin.on("end", settle);
+    process.stdin.on("error", settle);
+    process.stdin.resume();
+  });
+}
+function writeDebugLogIfRequested(args, record) {
+  const explicitPath = readOption(args, "--debug-log");
+  const enabled = explicitPath !== void 0 || process.env.PGS_HOST_HOOK_DEBUG === "1";
+  if (!enabled) return;
+  const debugDir = explicitPath && explicitPath.trim().length > 0 ? explicitPath : defaultDebugDir();
+  try {
+    mkdirSync4(debugDir, { recursive: true });
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const fileName = `${timestamp}-${process.pid}-${record.host}-${record.event}.json`;
+    writeFileSync3(
+      join13(debugDir, fileName),
+      `${JSON.stringify(
+        {
+          schemaVersion: 1,
+          cwd: process.cwd(),
+          event: record.event,
+          host: record.host,
+          nodeVersion: process.version,
+          packageVersion: readPackageVersion(),
+          rawInput: truncateDebugRawInput(record.rawInput),
+          input: record.input,
+          decision: record.decision,
+          output: record.output
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+  } catch {
+  }
+}
+function defaultDebugDir() {
+  const gitPath = spawnSync3("git", ["rev-parse", "--git-path", "pro-gov-hook-debug"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  const value = gitPath.status === 0 ? gitPath.stdout.trim() : "";
+  if (value) {
+    return resolve2(process.cwd(), value);
+  }
+  return join13(tmpdir2(), "pro-gov-hook-debug", basename3(process.cwd()));
+}
+function readPackageVersion() {
+  const packageJsonPath = resolvePackageJsonPath();
+  if (!packageJsonPath) return void 0;
+  try {
+    const parsed = JSON.parse(readFileSync10(packageJsonPath, "utf8"));
+    return typeof parsed.version === "string" ? parsed.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolvePackageJsonPath() {
+  const candidates = [
+    resolve2(process.cwd(), "packages/pro-gov/package.json"),
+    resolve2(process.cwd(), "node_modules/@pieai/pro-gov/package.json")
+  ];
+  return candidates.find((candidate) => existsSync13(candidate));
+}
+function truncateDebugRawInput(value) {
+  const buffer = Buffer.from(value);
+  if (buffer.byteLength <= maxDebugRawInputBytes) return value;
+  return `${buffer.subarray(0, maxDebugRawInputBytes).toString("utf8")}
+[truncated]`;
+}
 
 // src/commands/init.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync4, readFileSync as readFileSync10, writeFileSync as writeFileSync3 } from "node:fs";
-import { basename as basename3, dirname as dirname7, join as join13 } from "node:path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync4 } from "node:fs";
+import { basename as basename4, dirname as dirname7, join as join14 } from "node:path";
 
 // src/commands/shared.ts
 function planStarterFiles(profile) {
@@ -1868,7 +2069,7 @@ function runInit(args) {
 }
 function applyStarterFiles(files, profile) {
   const root = process.cwd();
-  const conflicts = files.filter((file) => existsSync13(join13(root, file.targetPath)));
+  const conflicts = files.filter((file) => existsSync14(join14(root, file.targetPath)));
   if (conflicts.length > 0) {
     console.error("pro-gov init is refusing to overwrite existing project files:");
     for (const file of conflicts) console.error(`  ${file.targetPath}`);
@@ -1876,11 +2077,11 @@ function applyStarterFiles(files, profile) {
     return 1;
   }
   for (const file of files) {
-    const targetPath = join13(root, file.targetPath);
-    mkdirSync4(dirname7(targetPath), { recursive: true });
-    const source = readFileSync10(file.absoluteSourcePath);
-    const content = file.targetPath === "AGENTS.md" ? renderAgentsTemplate(source.toString("utf8"), basename3(root), profile) : source;
-    writeFileSync3(targetPath, content);
+    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}`);
@@ -1908,12 +2109,12 @@ function readFlag(args, flag) {
 }
 
 // src/commands/lens.ts
-import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync5 } from "node:fs";
+import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync6 } from "node:fs";
 import { dirname as dirname9 } from "node:path";
 
 // src/lens/audit.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync4 } from "node:fs";
-import { basename as basename4, dirname as dirname8, join as join14 } from "node:path";
+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";
 var REQUIRED_ARTIFACTS = [
   "manifest.md",
   "raw/project-lens/architecture-lens.md",
@@ -1933,20 +2134,20 @@ function createProjectLensAuditPackage(targetDir, auditDir) {
     version: 1,
     target: {
       path: targetDir,
-      name: basename4(targetDir) || "target"
+      name: basename5(targetDir) || "target"
     },
     requiredArtifacts: [...REQUIRED_ARTIFACTS]
   };
-  mkdirSync5(auditDir, { recursive: true });
-  writeJson(join14(auditDir, "audit.contract.json"), contract);
+  mkdirSync6(auditDir, { recursive: true });
+  writeJson(join15(auditDir, "audit.contract.json"), contract);
   for (const artifactPath of REQUIRED_ARTIFACTS) {
-    writeTemplate(join14(auditDir, artifactPath), renderArtifactTemplate(artifactPath, contract));
+    writeTemplate(join15(auditDir, artifactPath), renderArtifactTemplate(artifactPath, contract));
   }
   return contract;
 }
 function checkProjectLensAuditPackage(auditDir, options = {}) {
-  const contractPath = join14(auditDir, "audit.contract.json");
-  if (!existsSync14(contractPath)) {
+  const contractPath = join15(auditDir, "audit.contract.json");
+  if (!existsSync15(contractPath)) {
     return {
       ok: false,
       auditDir,
@@ -1960,7 +2161,7 @@ function checkProjectLensAuditPackage(auditDir, options = {}) {
   }
   let contract;
   try {
-    contract = JSON.parse(readFileSync11(contractPath, "utf8"));
+    contract = JSON.parse(readFileSync12(contractPath, "utf8"));
   } catch (error) {
     return {
       ok: false,
@@ -1993,12 +2194,12 @@ function checkProjectLensAuditPackage(auditDir, options = {}) {
     }
   }
   for (const artifactPath of REQUIRED_ARTIFACTS) {
-    const absolutePath = join14(auditDir, artifactPath);
-    if (!existsSync14(absolutePath)) {
+    const absolutePath = join15(auditDir, artifactPath);
+    if (!existsSync15(absolutePath)) {
       issues.push({ type: "missing-required-artifact", path: artifactPath });
       continue;
     }
-    const content = readFileSync11(absolutePath, "utf8");
+    const content = readFileSync12(absolutePath, "utf8");
     if (isPendingArtifact(content)) {
       issues.push({ type: "artifact-not-complete", path: artifactPath });
     } else if (hasTemplateBody(content)) {
@@ -2014,13 +2215,13 @@ function checkProjectLensAuditPackage(auditDir, options = {}) {
   };
 }
 function writeJson(path, value) {
-  mkdirSync5(dirname8(path), { recursive: true });
-  writeFileSync4(path, `${JSON.stringify(value, null, 2)}
+  mkdirSync6(dirname8(path), { recursive: true });
+  writeFileSync5(path, `${JSON.stringify(value, null, 2)}
 `);
 }
 function writeTemplate(path, content) {
-  mkdirSync5(dirname8(path), { recursive: true });
-  writeFileSync4(path, content);
+  mkdirSync6(dirname8(path), { recursive: true });
+  writeFileSync5(path, content);
 }
 function renderArtifactTemplate(artifactPath, contract) {
   const title = artifactPath.replace(/\.md$/, "").split("/").map((part) => part.replaceAll("-", " ")).join(" / ");
@@ -2257,9 +2458,9 @@ function bulletList(values) {
 }
 
 // src/lens/scan.ts
-import { spawnSync as spawnSync3 } from "node:child_process";
-import { existsSync as existsSync15, readdirSync as readdirSync6, readFileSync as readFileSync12, statSync as statSync3 } from "node:fs";
-import { join as join15, relative as relative5 } from "node:path";
+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";
 var ignoredDirectories = /* @__PURE__ */ new Set([
   ".git",
   ".next",
@@ -2276,24 +2477,24 @@ function scanProjectLensTarget(targetDir, options = {}) {
   return {
     targetDir,
     aiEntryFiles: ["AGENTS.md", "CLAUDE.md"].filter(
-      (file) => existsSync15(join15(targetDir, file))
+      (file) => existsSync16(join16(targetDir, file))
     ),
     aiConfigFiles: [],
     packageJson,
     docs: {
-      hasDocsDirectory: existsSync15(join15(targetDir, "docs")),
+      hasDocsDirectory: existsSync16(join16(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: statSync3(join15(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(join16(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 = join15(targetDir, "package.json");
-  if (!existsSync15(packageJsonPath)) return void 0;
+  const packageJsonPath = join16(targetDir, "package.json");
+  if (!existsSync16(packageJsonPath)) return void 0;
   try {
-    const packageJson = JSON.parse(readFileSync12(packageJsonPath, "utf8"));
+    const packageJson = JSON.parse(readFileSync13(packageJsonPath, "utf8"));
     return {
       scripts: Object.keys(packageJson.scripts ?? {}).sort(),
       dependencies: Object.keys(packageJson.dependencies ?? {}).sort(),
@@ -2316,7 +2517,7 @@ function readGitState(targetDir) {
   };
 }
 function runGit(targetDir, args) {
-  const result = spawnSync3("git", ["-C", targetDir, ...args], {
+  const result = spawnSync4("git", ["-C", targetDir, ...args], {
     encoding: "utf8"
   });
   if (result.status !== 0) return { ok: false };
@@ -2328,13 +2529,13 @@ function listProjectFiles(targetDir) {
   return files.sort();
 }
 function collectFiles2(rootDir, currentDir, files) {
-  if (!existsSync15(currentDir)) return;
+  if (!existsSync16(currentDir)) return;
   for (const entry of readdirSync6(currentDir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
       if (ignoredDirectories.has(entry.name)) continue;
-      collectFiles2(rootDir, join15(currentDir, entry.name), files);
+      collectFiles2(rootDir, join16(currentDir, entry.name), files);
     } else if (entry.isFile()) {
-      files.push(toUnixPath4(relative5(rootDir, join15(currentDir, entry.name))));
+      files.push(toUnixPath4(relative5(rootDir, join16(currentDir, entry.name))));
     }
   }
 }
@@ -2386,8 +2587,8 @@ function runLensReport(args) {
   }
   const report = scanProjectLensTarget(options.value.targetDir);
   const markdown = renderProjectLensMarkdownReport(report);
-  mkdirSync6(dirname9(options.value.outPath), { recursive: true });
-  writeFileSync5(options.value.outPath, markdown);
+  mkdirSync7(dirname9(options.value.outPath), { recursive: true });
+  writeFileSync6(options.value.outPath, markdown);
   console.log(`report: ${options.value.outPath}`);
   return 0;
 }
@@ -2490,16 +2691,16 @@ function printUsage2() {
 }
 
 // src/commands/portfolio.ts
-import { existsSync as existsSync17 } from "node:fs";
-import { join as join16 } from "node:path";
+import { existsSync as existsSync18 } from "node:fs";
+import { join as join17 } from "node:path";
 
 // src/portfolio/manifest.ts
-import { existsSync as existsSync16, readFileSync as readFileSync13 } from "node:fs";
-import { dirname as dirname10, isAbsolute as isAbsolute3, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync17, readFileSync as readFileSync14 } from "node:fs";
+import { dirname as dirname10, isAbsolute as isAbsolute3, resolve as resolve3 } from "node:path";
 function loadPortfolioManifest(configPath) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync13(configPath, "utf8"));
+    parsed = JSON.parse(readFileSync14(configPath, "utf8"));
   } catch (error) {
     return {
       configPath,
@@ -2511,7 +2712,7 @@ function loadPortfolioManifest(configPath) {
       ]
     };
   }
-  const normalized = resolveManifestPaths(parsed, dirname10(resolve2(configPath)));
+  const normalized = resolveManifestPaths(parsed, dirname10(resolve3(configPath)));
   const issues = validatePortfolioManifest(normalized);
   return {
     configPath,
@@ -2525,7 +2726,7 @@ function resolveManifestPaths(value, configDir) {
     if (!isRecord2(endpoint) || typeof endpoint.path !== "string" || isAbsolute3(endpoint.path)) {
       return endpoint;
     }
-    return { ...endpoint, path: resolve2(configDir, endpoint.path) };
+    return { ...endpoint, path: resolve3(configDir, endpoint.path) };
   };
   return {
     ...value,
@@ -2653,7 +2854,7 @@ function validateEndpoint(value, field, issues) {
     });
     return;
   }
-  if (!existsSync16(value.path)) {
+  if (!existsSync17(value.path)) {
     issues.push({
       type: "missing-path",
       id: typeof value.id === "string" ? value.id : void 0,
@@ -2928,8 +3129,8 @@ function isHost2(value) {
   return value === "codex" || value === "claude-code" || value === "gemini-cli" || value === "antigravity";
 }
 function findPortfolioAgentAssetsDir(manifest) {
-  const agentAssetsDir = manifest?.executionEngine?.path ? join16(manifest.executionEngine.path, "agent-assets") : void 0;
-  return agentAssetsDir && existsSync17(join16(agentAssetsDir, "registry.json")) ? agentAssetsDir : void 0;
+  const agentAssetsDir = manifest?.executionEngine?.path ? join17(manifest.executionEngine.path, "agent-assets") : void 0;
+  return agentAssetsDir && existsSync18(join17(agentAssetsDir, "registry.json")) ? agentAssetsDir : void 0;
 }
 function printUsage3() {
   console.error("Usage:");
@@ -2939,8 +3140,8 @@ function printUsage3() {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync18, readFileSync as readFileSync14 } from "node:fs";
-import { join as join17 } from "node:path";
+import { existsSync as existsSync19, readFileSync as readFileSync15 } from "node:fs";
+import { join as join18 } from "node:path";
 function runSync(args) {
   if (!args.includes("--check")) {
     console.error("pro-gov sync is read-only and requires --check.");
@@ -2967,16 +3168,16 @@ function runSync(args) {
   console.log("pro-gov sync check");
   console.log(`profile: ${profile}`);
   for (const file of planStarterFiles(profile)) {
-    const targetPath = join17(process.cwd(), file.targetPath);
-    if (!existsSync18(targetPath)) {
+    const targetPath = join18(process.cwd(), file.targetPath);
+    if (!existsSync19(targetPath)) {
       if (file.ownership === "optional-guardrail") continue;
       console.log(`missing: ${file.targetPath}`);
       differences += 1;
       continue;
     }
     if (file.ownership === "project-local-seed") continue;
-    const source = readFileSync14(file.absoluteSourcePath, "utf8");
-    const target = readFileSync14(targetPath, "utf8");
+    const source = readFileSync15(file.absoluteSourcePath, "utf8");
+    const target = readFileSync15(targetPath, "utf8");
     if (source !== target) {
       console.log(`different: ${file.targetPath}`);
       differences += 1;
@@ -2991,7 +3192,7 @@ function runSync(args) {
 }
 function inferInstalledProfile(root) {
   const installed = ["engineering-runtime", "doc-only"].filter(
-    (profile) => existsSync18(join17(root, `docs/governance/agents-routing/${profile}-v0.9.md`))
+    (profile) => existsSync19(join18(root, `docs/governance/agents-routing/${profile}-v0.9.md`))
   );
   return installed.length === 1 ? installed[0] : void 0;
 }
@@ -3025,27 +3226,22 @@ var COMMANDS = [
   "doctor"
 ];
 var [command, subcommand] = process.argv.slice(2);
-if (!command || command === "--help" || command === "-h") {
-  printHelp();
-  process.exitCode = command ? 0 : 1;
-} else if (command === "assets") {
-  process.exitCode = runAssets(process.argv.slice(3));
-} else if (command === "lens") {
-  process.exitCode = runLens(process.argv.slice(3));
-} else if (command === "portfolio") {
-  process.exitCode = runPortfolio(process.argv.slice(3));
-} else if (command === "host-hook") {
-  process.exitCode = runHostHook(process.argv.slice(3));
-} else if (command === "init") {
-  process.exitCode = runInit(process.argv.slice(3));
-} else if (command === "sync") {
-  process.exitCode = runSync(process.argv.slice(3));
-} else if (command === "doctor") {
-  process.exitCode = runDoctor(process.argv.slice(3));
-} else {
+process.exitCode = await main();
+async function main() {
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return command ? 0 : 1;
+  }
+  if (command === "assets") return runAssets(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));
+  if (command === "init") return runInit(process.argv.slice(3));
+  if (command === "sync") return runSync(process.argv.slice(3));
+  if (command === "doctor") return runDoctor(process.argv.slice(3));
   console.error(`Unknown command: ${[command, subcommand].filter(Boolean).join(" ")}`);
   printHelp();
-  process.exitCode = 1;
+  return 1;
 }
 function printHelp() {
   console.log("pro-gov \u2014 project-level distribution kit for Project Governance System");

package/package.json

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