@pieai/pro-gov 0.5.4 → 0.6.0

package/assets/profiles/doc-only/manifest.yml

@@ -6,7 +6,7 @@ required:
   ai_in_the_loop:
     target: docs/policy/shared-rules/ai-in-the-loop.md
     source: external shared-rule SSOT
-  agents_routing: docs/governance/agents-routing/doc-only-v1.0.md
+  agents_routing: docs/governance/agents-routing/doc-only-v1.1.md
   current_work: docs/reference/execution/current-work.md
 project_local_required:
   - docs/policy/best-practice-for-this-project.md

package/assets/profiles/doc-only/profile.md

@@ -6,9 +6,9 @@ Use for non-runtime projects: IP development, AI media production, research vaul
 
 - `packages/doc-gov`
 - `packages/pro-gov`
-- `docs/governance/ssot-v1.0.md`
+- `docs/governance/ssot-v1.1.md`
 - external AI-in-the-Loop policy linked by target projects under `docs/policy/shared-rules/ai-in-the-loop.md`
-- `docs/governance/agents-routing/doc-only-v1.0.md`
+- `docs/governance/agents-routing/doc-only-v1.1.md`
 - starter `docs/governance/` and `docs/policy/` templates
 
 ## Does Not Include By Default

package/assets/profiles/engineering-runtime/manifest.yml

@@ -6,7 +6,7 @@ required:
   ai_in_the_loop:
     target: docs/policy/shared-rules/ai-in-the-loop.md
     source: external shared-rule SSOT
-  agents_routing: docs/governance/agents-routing/engineering-runtime-v1.0.md
+  agents_routing: docs/governance/agents-routing/engineering-runtime-v1.1.md
   current_work: docs/reference/execution/current-work.md
 optional:
   mattpocock_skills: integrations/mattpocock-skills.md

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

@@ -6,9 +6,9 @@ Use for code-heavy projects: apps, games, runtimes, services, browser products,
 
 - `packages/doc-gov`
 - `packages/pro-gov`
-- `docs/governance/ssot-v1.0.md`
+- `docs/governance/ssot-v1.1.md`
 - external AI-in-the-Loop policy linked by target projects under `docs/policy/shared-rules/ai-in-the-loop.md`
-- `docs/governance/agents-routing/engineering-runtime-v1.0.md`
+- `docs/governance/agents-routing/engineering-runtime-v1.1.md`
 - `integrations/mattpocock-skills.md`
 - starter `docs/governance/` and `docs/policy/` templates
 

package/assets/starter/.agents/skills/.gitkeep

@@ -0,0 +1 @@
+

package/assets/starter/AGENTS.template.md

@@ -2,11 +2,15 @@
 
 ## PGS Router Block
 
-<!-- PGS-ROUTER:BEGIN v1.0 -->
+<!-- PGS-ROUTER:BEGIN v1.1 -->
 
 ## Boundary
 
 - PGS governs this `AGENTS.md` entry and governed Markdown under `docs/**`.
+- `AGENTS.md` is the canonical project router; `CLAUDE.md` must be the exact
+  relative symlink `AGENTS.md`.
+- `.agents/skills/` is the canonical project skill root; `.claude/skills`
+  must be the exact relative symlink `../.agents/skills`.
 - Product artifacts outside `docs/**` are not governed docs unless this project explicitly opts them in.
 - `README.md` is the human-facing introduction; read it only for positioning,
   public explanation, or README work.
@@ -19,7 +23,7 @@
 ## Documentation Tasks
 
 When the task creates, edits, moves, deletes, or governs documentation, read
-`docs/governance/boundary.md`, `docs/governance/ssot-v1.0.md`,
+`docs/governance/boundary.md`, `docs/governance/ssot-v1.1.md`,
 `docs/governance/doc-agent-rules.md`, `docs/governance/doc-types.md`, the
 selected agents routing file, and all Markdown under `docs/policy/**/*.md`.
 That policy set includes subdirectories and symlinked shared-rule files; keep

package/assets/starter/docs/governance/agents-routing/{doc-only-v1.0.md → doc-only-v1.1.md}

@@ -1,12 +1,12 @@
 ---
-id: GOV-AGENTS-ROUTING-DOC-ONLY-V1-0
-title: Doc-Only Agents Routing v1.0
+id: GOV-AGENTS-ROUTING-DOC-ONLY-V1-1
+title: Doc-Only Agents Routing v1.1
 type: policy
 status: stable
 canonical: true
 owner: human
-created: 2026-05-09
-last_reviewed: 2026-07-12
+created: 2026-07-13
+last_reviewed: 2026-07-13
 domain: agents-routing
 tags:
   - agents-routing
@@ -14,13 +14,13 @@ tags:
   - workflow
 pinned: true
 related:
-  - GOV-SSOT-V1-0
+  - GOV-SSOT-V1-1
   - REF-DOC-GOVERNANCE-BOUNDARY
 supersedes: []
 superseded_by: null
 ---
 
-# Doc-Only Agents Routing v1.0
+# Doc-Only Agents Routing v1.1
 
 Shared routing algorithm for non-runtime projects such as AI media, IP development, research, and asset governance workspaces.
 
@@ -74,7 +74,7 @@ written as Markdown. Governed docs record decisions, plans, references, policies
 and workspace truth. Product artifacts stay in the project package or workbench
 unless the project explicitly opts them into doc-gov.
 
-## Host Adapter Boundary
+## Host Compatibility Boundary
 
-Host-specific adapters such as `CLAUDE.md` may adapt the route for a specific AI
-client, but they must not replace the project `AGENTS.md` route.
+Follow the Project AI Host SSOT in `docs/governance/ssot-v1.1.md`. Host-specific
+runtime settings must not create a second project router or skill tree.

package/assets/starter/docs/governance/agents-routing/{engineering-runtime-v1.0.md → engineering-runtime-v1.1.md}

@@ -1,12 +1,12 @@
 ---
-id: GOV-AGENTS-ROUTING-ENGINEERING-RUNTIME-V1-0
-title: Engineering Runtime Agents Routing v1.0
+id: GOV-AGENTS-ROUTING-ENGINEERING-RUNTIME-V1-1
+title: Engineering Runtime Agents Routing v1.1
 type: policy
 status: stable
 canonical: true
 owner: human
-created: 2026-05-09
-last_reviewed: 2026-05-09
+created: 2026-07-13
+last_reviewed: 2026-07-13
 domain: agents-routing
 tags:
   - agents-routing
@@ -14,13 +14,13 @@ tags:
   - workflow
 pinned: true
 related:
-  - GOV-SSOT-V1-0
+  - GOV-SSOT-V1-1
   - REF-DOC-GOVERNANCE-BOUNDARY
 supersedes: []
 superseded_by: null
 ---
 
-# Engineering Runtime Agents Routing v1.0
+# Engineering Runtime Agents Routing v1.1
 
 Shared routing algorithm for app, game, runtime, and code-heavy projects.
 
@@ -54,7 +54,7 @@ Typical lanes:
 
 But the shared router must not define project-specific lanes.
 
-## Host Adapter Boundary
+## Host Compatibility Boundary
 
-Host-specific adapters such as `CLAUDE.md` may adapt the route for a specific AI
-client, but they must not replace the project `AGENTS.md` route.
+Follow the Project AI Host SSOT in `docs/governance/ssot-v1.1.md`. Host-specific
+runtime settings must not create a second project router or skill tree.

package/assets/starter/docs/governance/boundary.md

@@ -53,7 +53,7 @@ project-specific AI development habits live.
 | --- | --- |
 | AI startup entry | `AGENTS.md` |
 | Agent routing algorithm | `docs/governance/agents-routing/` |
-| Governed SSOT rules | `docs/governance/ssot-v1.0.md` |
+| Governed SSOT rules | `docs/governance/ssot-v1.1.md` |
 | Project AI development practices | `docs/policy/best-practice-for-this-project.md` |
 | Current work index | `docs/reference/execution/current-work.md` |
 | Product or world truth | `docs/canon/` |
@@ -69,8 +69,9 @@ System rules go here. Project-specific rules go to `docs/policy/`.
 
 ## Governed Scope
 
-By default, doc-gov governs Markdown under `docs/**` and AI entry files such as
-`AGENTS.md`.
+By default, doc-gov governs Markdown under `docs/**` and the project AI entry
+contract. `AGENTS.md` is the canonical project router; compatibility entry and
+skill roots must follow `docs/governance/ssot-v1.1.md`.
 
 It does not govern every Markdown file in the repository. Markdown under
 product packages, workbenches, prompt libraries, source folders, or asset

package/assets/starter/docs/governance/{ssot-v1.0.md → ssot-v1.1.md}

@@ -1,17 +1,18 @@
 ---
-id: GOV-SSOT-V1-0
-title: SSOT Documentation Governance Rules v1.0
+id: GOV-SSOT-V1-1
+title: SSOT Documentation Governance Rules v1.1
 type: policy
 status: stable
 canonical: true
 owner: human
-created: 2026-05-09
-last_reviewed: 2026-05-09
+created: 2026-07-13
+last_reviewed: 2026-07-13
 domain: doc-governance
 tags:
   - ssot
   - doc-gov
   - boundary
+  - ai-hosts
 pinned: true
 related:
   - REF-DOC-GOVERNANCE-BOUNDARY
@@ -19,29 +20,32 @@ supersedes: []
 superseded_by: null
 ---
 
-# SSOT Documentation Governance Rules v1.0
+# SSOT Documentation Governance Rules v1.1
 
 This rule defines how projects using Project Governance System handle
-**SSOT (Single Source of Truth)** for governed documentation.
+**SSOT (Single Source of Truth)** for governed documentation and project-level
+AI-host entry and skill discovery.
 
 Use it whenever an AI agent creates, modifies, moves, deletes, archives, or
-cross-references project documents.
+cross-references project documents, routers, or project skill roots.
 
-Beginner version: every important fact should have one home. Other files can
-point to that home, but they should not become competing copies.
+Beginner version: every important fact should have one home. Other files and
+host compatibility paths may point to that home, but they must not become
+competing copies.
 
 ## Governance Scope
 
 Project Governance System governs:
 
-- `AGENTS.md` and equivalent AI entry files.
+- `AGENTS.md` and compatible project AI entry paths.
+- `.agents/skills/` as the canonical project skill root and compatible
+  project skill discovery paths.
 - Governed Markdown under `docs/**`.
 - Documentation governance rules, agent routing rules, templates, manifests,
-  plans, specs, references, canon, and archives that live under
-  `docs/**`.
+  plans, specs, references, canon, and archives that live under `docs/**`.
 
-Project Governance System does **not** automatically govern every Markdown file
-or every asset in the repository.
+Project Governance System does **not** automatically govern every Markdown file,
+host-native runtime setting, user-level skill installation, or project asset.
 
 Markdown outside `docs/**` can be a product artifact, source asset, prompt,
 project package file, runtime note, generated media description, or local
@@ -62,20 +66,60 @@ Gov schema:
 PGS plans remain under `docs/plans/active/**` and
 `docs/plans/completed/**`.
 
+## Project AI Host SSOT
+
+Every governed project uses these project-level truth surfaces:
+
+| Concern | Canonical path | Compatibility contract |
+| --- | --- | --- |
+| Project AI router | `AGENTS.md` | `CLAUDE.md` is the exact relative symlink `AGENTS.md` |
+| Project skills | `.agents/skills/` | `.claude/skills` is the exact relative symlink `../.agents/skills` |
+
+The compatibility paths are structural contracts, not alternate content
+locations:
+
+- `CLAUDE.md` must be a symbolic link whose raw link target is exactly
+  `AGENTS.md`.
+- `.claude/skills` must be a symbolic link whose raw link target is exactly
+  `../.agents/skills`.
+- `.agents/skills/` must still exist in a clean checkout. Track managed skill
+  entries or a `.gitkeep`; if the directory is otherwise ignored, explicitly
+  unignore that placeholder.
+- A copied file, copied directory, absolute link, differently spelled relative
+  link, wrong target, or dangling link is not compliant even when it currently
+  resolves to similar content.
+- Check the link object and raw target with `lstat` and `readlink`; resolving
+  the final path alone is insufficient.
+- Host-specific runtime settings may remain in native host configuration files,
+  but they must not introduce a second project router or project skill tree.
+
+This exact-relative rule applies only to the two compatibility links above.
+Individual entries under `.agents/skills/<skill>` may be directories or valid
+absolute or relative symlinks. Skill managers may choose absolute per-skill
+links when that is the correct installation model.
+
+User-level skill roots are a separate configuration scope. A user may maintain
+one canonical `~/.agents/skills/` tree and link a compatible host root to it,
+but project governance must not hard-code a user's home directory or inspect it
+as part of a portable project router contract.
+
 ## Core Behavior
 
 - **Discover before editing**: first identify the project's actual documentation
   system and current entrypoints.
 - **One truth surface**: each durable fact should have one canonical source;
   other files should summarize and link.
+- **One project router and skill tree**: host compatibility paths point to the
+  canonical project surfaces instead of duplicating them.
 - **Runtime beats Markdown**: when runtime code/config is the real product truth,
   docs must point to it instead of duplicating it.
 - **Product artifacts stay in their product package**: prompts, generated media,
   asset manifests, project-package canon, and source materials should stay in
   the project's own production/workbench structure unless the project explicitly
   makes them governed docs.
-- **No parallel systems**: do not keep old and new documentation structures alive
-  unless the project explicitly says it is in a migration window.
+- **No parallel systems**: do not keep old and new documentation, router, or
+  skill structures alive unless the project explicitly says it is in a
+  migration window.
 - **No AI dump folders inside governed docs**: do not create ad-hoc `Temp/`,
   `Drafts/`, `Opus/`, `Codex/`, or AI-name folders under `docs/**`.
 
@@ -83,9 +127,9 @@ PGS plans remain under `docs/plans/active/**` and
 
 Before changing docs, look for project-local guidance in this order:
 
-1. `AGENTS.md`, `CLAUDE.md`, or equivalent AI router/config adapter.
+1. `AGENTS.md`, reached directly or through a compliant compatibility link.
 2. `docs/governance/boundary.md`.
-3. `docs/governance/ssot-v1.0.md`.
+3. `docs/governance/ssot-v1.1.md`.
 4. `docs/governance/agents-routing/` and the project's selected agents-routing file.
 5. `docs/reference/documentation-map.md`, root `README.md` for human-facing
    orientation, or another project-defined documentation index.
@@ -112,7 +156,8 @@ works for governed docs:
 
 | Need | Usually belongs in |
 | --- | --- |
-| AI entry and startup routing | `AGENTS.md` plus thin host-specific adapters such as `CLAUDE.md` |
+| AI entry and startup routing | `AGENTS.md`, reached through exact host compatibility links when required |
+| Project skill discovery | `.agents/skills/`, reached through exact host compatibility links when required |
 | Agents-routing rules | `docs/governance/agents-routing/` |
 | Doc-system rules, templates, and manifest | `docs/governance/` |
 | Project AI/development policy | `docs/policy/` |
@@ -131,16 +176,19 @@ table.
 
 ## Editing Rules
 
-When modifying documentation:
+When modifying documentation or project AI-host compatibility:
 
 1. Find the canonical source first.
-2. Decide whether the file is a governed doc or a product artifact.
+2. Decide whether the file is a governed doc, compatibility link, or product
+   artifact.
 3. Edit only the canonical source for the durable fact.
-4. Update navigation links if names or paths change.
-5. Replace duplicated content with a one-line summary plus link.
-6. If code/runtime behavior changed, update the runtime truth first, then align
+4. Preserve exact compatibility link targets instead of editing through a
+   duplicate host-specific body.
+5. Update navigation links if names or paths change.
+6. Replace duplicated content with a one-line summary plus link.
+7. If code/runtime behavior changed, update the runtime truth first, then align
    docs.
-7. Run the project's doc checks before claiming completion.
+8. Run the project's checks before claiming completion.
 
 ## Moving Or Deleting Docs
 
@@ -152,27 +200,34 @@ When modifying documentation:
   AI cognitive load.
 - If a file is moved, update indexes, manifests, and symlinks.
 - Do not move product artifacts into `docs/**` as a cleanup shortcut.
+- Before replacing an incompatible skill directory, preserve any unique skills
+  by moving them into the canonical `.agents/skills/` tree.
 
 ## Completion Checklist
 
-Before reporting doc work complete:
+Before reporting doc or host-compatibility work complete:
 
 - [ ] I found the project documentation system.
-- [ ] I identified whether the changed file is governed documentation or a
-      product artifact.
+- [ ] I identified whether the changed path is canonical, compatible, governed
+      documentation, or a product artifact.
 - [ ] I updated the canonical source, not a duplicate.
+- [ ] `CLAUDE.md` and `.claude/skills` use their exact relative link targets.
+- [ ] I did not rewrite valid per-skill links merely because they are absolute.
 - [ ] I did not create ungoverned temp/draft/AI-name folders under `docs/**`.
 - [ ] I updated links/navigation after moves or renames.
 - [ ] I kept runtime data in runtime/config files, not Markdown copies.
 - [ ] I kept product prompts/assets in the product package unless explicitly
       governed.
-- [ ] I ran the project's doc validation command when available.
+- [ ] I ran the project's validation commands when available.
 
 ## Common Mistakes
 
 | Mistake | Better move |
 | --- | --- |
 | Copying the same design rule into five docs | Keep one canonical doc, link from the others. |
+| Keeping a separate `CLAUDE.md` body | Link `CLAUDE.md` exactly to `AGENTS.md`. |
+| Copying skills into `.claude/skills/` | Keep skills in `.agents/skills/` and link the compatible root. |
+| Rewriting every absolute per-skill link | Leave valid per-skill installation links alone; the exact-relative rule is for compatibility roots. |
 | Treating old migration sources as current truth | Archive or delete them after migration. |
 | Letting Markdown override runtime config | Runtime/config wins; docs explain intent. |
 | Moving every `.md` file into `docs/**` | Govern discussion records; keep product artifacts in their product package. |

package/assets/starter/docs/reference/documentation-map.md

@@ -24,10 +24,10 @@ Use `AGENTS.md` for startup reading. It should point agents to:
 
 - `docs/policy/*.md`
 - `docs/governance/boundary.md`
-- `docs/governance/ssot-v1.0.md`
+- `docs/governance/ssot-v1.1.md`
 - `docs/governance/doc-agent-rules.md`
 - `docs/governance/doc-types.md`
-- `docs/governance/agents-routing/<selected-profile>-v1.0.md`
+- `docs/governance/agents-routing/<selected-profile>-v1.1.md`
 - `docs/reference/execution/current-work.md`
 
 ## Areas

package/cli-guide.md

@@ -92,10 +92,14 @@ auto|manual` only as a migration override when deliberately moving an existing
 target.
 
 `portfolio ai-health` performs a read-only structural inventory of the control
-plane, execution engine, and registered targets, then writes a fixed local HTML
-dashboard plus JSON evidence to the explicit `--out` directory. It records MCP
-server names and environment filenames, but never reads or emits secret values,
-environment values, MCP commands, arguments, or MCP environment maps.
+plane, execution engine, registered targets, user/project AI-host configuration,
+and machine-level specialist checks explicitly declared in the private manifest
+(currently DevSpace). It then writes a fixed local HTML dashboard plus JSON
+evidence to the explicit `--out` directory. Specialist checks retain derived
+health states only; credentials, URLs, and raw process environments are never
+written. The inventory records MCP server names and environment filenames, but
+never reads or emits secret values, environment values, MCP commands, arguments,
+or MCP environment maps.
 
 Portfolio manifests are external configuration files owned by a user or
 organization. PGS provides the format and commands; it does not publish a real