@pieai/pro-gov 0.3.11 → 0.3.13

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
 
@@ -139,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

@@ -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.
@@ -207,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
@@ -125,4 +135,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/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

@@ -18,6 +18,9 @@ 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 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
@@ -40,12 +43,21 @@ 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
 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 +84,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