@pieai/pro-gov 0.3.10 → 0.3.12

package/README.md

@@ -45,6 +45,8 @@ pro-gov assets discover --target .
 pro-gov assets recommend --target .
 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 lens inspect --target .
 pro-gov lens report --target . --out .pro-gov/lens-report.md
 pro-gov init --profile engineering-runtime --dry-run
@@ -63,6 +65,8 @@ What these commands do:
 | `assets recommend` | Suggests relevant asset bundles with reasons. | No |
 | `portfolio check` | Validates an external portfolio manifest owned by the user or organization. | No |
 | `portfolio plan` | Builds dry-run asset plans for manifest targets, using packaged public assets unless a full checkout is supplied. | No |
+| `portfolio assets-check` | Checks the integrity of each target's current managed asset lock and symlinks. | No |
+| `portfolio doctor` | Runs the offline fleet gate: package, target CLI, bundle, asset, symlink, Git-state evidence, and optional host-tooling checks. | No |
 | `lens inspect` | Produces ProjectLens-style local evidence. | No |
 | `lens report` | Writes the requested report file. | Only the explicit output |
 | `init --dry-run` | Shows starter/profile files that would be needed. | No |
@@ -98,7 +102,10 @@ User-scoped skills, such as a personal loop library, are not installed into
 project targets; link them once under the user's skill roots instead.
 
 The plan is the safety gate. `apply` may update managed targets described by the
-plan; it must not overwrite an unrelated unmanaged file.
+plan; it must not overwrite an unrelated unmanaged file. When an asset leaves a
+bundle, a plan may remove its old symlink only when the previous lock proves
+ownership and both plan-time and apply-time checks confirm that the path is
+still the same managed symlink.
 
 These checkout-only workflows depend on a maintainer-local `agent-assets/`
 registry when local-only assets are being used. The public repository and npm
@@ -111,7 +118,7 @@ the private-source and public-copy hashes recorded during promotion.
 - `pro-gov` distributes starter, profile, integration, and adoption assets.
 - `pro-gov assets discover|recommend` provides read-only project evidence and
   deterministic recommendations.
-- `pro-gov portfolio check|plan` reads an external portfolio manifest. Real
+- `pro-gov portfolio check|plan|assets-check|doctor` reads an external portfolio manifest. Real
   downstream project lists belong in the user's control repository, not in this
   public package. The manifest does not require a private headquarters repo:
   npm users can omit `controlPlane` and `executionEngine`, and PGS will use the
@@ -127,6 +134,8 @@ the private-source and public-copy hashes recorded during promotion.
   use `--dry-run` and a deliberate migration so local truth is never overwritten.
 - Superpowers, Compound Engineering, and Ponytail are external tools, not
   bundled runtime dependencies.
+- Optional `hostTooling` entries let `portfolio doctor` verify required Codex or
+  Claude Code plugins. PGS does not install or upgrade those plugins.
 
 ## Recommended Companion Tools
 
@@ -155,6 +164,15 @@ 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.
 Ponytail must not remove requested scope, tests, safety, accessibility, or proof.

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

@@ -153,6 +153,10 @@ Managed symlinks are relative by default. A target project's normal
 public package to know a maintainer's private registry. Maintainers can add
 `--strict-registry`, or run `pro-gov portfolio assets-check --config
 /path/to/portfolio.json`, when they need central private-registry validation.
+Use `pro-gov portfolio doctor --config /path/to/portfolio.json` as the final
+offline fleet gate when package versions, target-local routers and hooks,
+declared bundles, locks, managed symlinks, and optional host plugins all need to
+be checked together. The command reports dirty Git state but does not edit it.
 
 When a maintainer promotes a private asset into `public-agent-assets/`, the
 public registry must record the private-source hash and the public-copy hash.
@@ -294,6 +298,12 @@ engineering runtime profile.
 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.
 

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

@@ -125,4 +125,7 @@ install PGS packages
 
 PGS does not automatically install, enable, update, or remove these external
 plugins in another person's AI host. It documents the recommended boundary and
-lets each project or user adopt tools deliberately.
+lets each project or user adopt tools deliberately. A user-owned portfolio may
+declare required Codex or Claude Code plugin ids in `hostTooling`; `portfolio
+doctor` then verifies installed/enabled state and reports observed versions.
+The host's native plugin manager remains the installation and update authority.

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/cli-guide.md

@@ -18,6 +18,8 @@ pro-gov assets discover --target .
 pro-gov assets recommend --target .
 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 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
@@ -46,6 +48,8 @@ Full upstream-checkout commands:
 pro-gov assets list --json
 pro-gov portfolio check --config /path/to/control-repo/.pro-gov/portfolio.json --json
 pro-gov portfolio plan --config /path/to/control-repo/.pro-gov/portfolio.json --target web-app --json
+pro-gov portfolio assets-check --config /path/to/control-repo/.pro-gov/portfolio.json --json
+pro-gov portfolio doctor --config /path/to/control-repo/.pro-gov/portfolio.json --json
 pro-gov assets plan --bundle base-governance --target . --out .pro-gov/asset-plan.json
 pro-gov assets plan --bundle project-lens --target /path/to/project --host codex --placement manual --out /tmp/project-lens-plan.json
 pro-gov assets apply --plan .pro-gov/asset-plan.json
@@ -72,6 +76,27 @@ public assets packaged with `@pieai/pro-gov`. Add `executionEngine.path` only
 when a full local checkout should provide a private asset registry for strict
 maintainer checks.
 
+`portfolio assets-check` verifies that the currently recorded lock and managed
+links are healthy. `portfolio doctor` additionally compares each target with the
+current portfolio `assetBundles`, registry hashes, package versions, target-local
+router/hook checks, and optional `hostTooling` requirements. The doctor is
+offline and read-only by default. A dirty product worktree is reported as
+evidence but is not itself a governance failure.
+
+Third-party update discovery is deliberately separate and low frequency:
+
+```bash
+pro-gov assets npx update --plan
+codex plugin marketplace upgrade
+codex plugin list --json
+claude plugin update <plugin>
+claude plugin list --json
+```
+
+The native tools own fetching and installation. PGS reviews resulting asset
+changes, regenerates plans, and verifies the fleet; it does not implement a
+second plugin marketplace or silently accept upstream changes.
+
 `lens audit init` creates a raw-first audit package for Project Lens plus
 Ponytail reviews. For a "read-only project audit", the target repository remains
 read-only, but the audit package is still the required output record. `lens