@pieai/pro-gov 0.5.3 → 0.6.0

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-07-11
+last_reviewed: 2026-07-13
 domain: adoption
 tags:
   - adoption
@@ -16,6 +16,7 @@ pinned: false
 related:
   - POLICY-SYNC-STRATEGY
   - REF-PROJECT-RELATIONSHIP
+  - REF-MIGRATION-V1-1
 ---
 
 # Adoption Playbook
@@ -55,6 +56,7 @@ If unsure, pick `doc-only` first. Add engineering agents routing only when the p
 Before moving anything, list:
 
 - current project router files (`AGENTS.md`, `CLAUDE.md`, etc.)
+- current project skill roots (`.agents/skills/`, `.claude/skills/`, etc.)
 - current docs index files
 - current active plans/specs
 - current canon/reference/archive locations
@@ -95,6 +97,8 @@ Current package-based method:
   connected
 - treat the npm package as the CLI source and the local `docs/governance/`
   files as the project's checked-in governance contract
+- keep `AGENTS.md` and `.agents/skills/` canonical; host compatibility paths
+  must use the exact relative symlinks defined by the v1.1 SSOT contract
 
 ```bash
 pnpm add -D @pieai/pro-gov @pieai/doc-gov
@@ -167,10 +171,10 @@ Required concepts:
 
 - `docs/reference/documentation-map.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/governance/templates/*.md`
 - `docs/policy/best-practice-for-this-project.md`
 - `docs/reference/execution/current-work.md`
@@ -180,7 +184,9 @@ Required concepts:
 - `docs/specs/completed/`
 - `docs/archive/`
 - `AGENTS.md` as the project router
-- `CLAUDE.md` as a thin adapter that forwards to `AGENTS.md`
+- `CLAUDE.md -> AGENTS.md` as the exact relative compatibility symlink
+- `.agents/skills/` as the canonical project skill root
+- `.claude/skills -> ../.agents/skills` as the exact relative compatibility symlink
 
 ## Step 5: Apply The Profile
 
@@ -188,7 +194,7 @@ Required concepts:
 
 Add:
 
-- `docs/governance/agents-routing/engineering-runtime-v1.0.md`
+- `docs/governance/agents-routing/engineering-runtime-v1.1.md`
 - engineering lane summary in `AGENTS.md`
 - detailed lane profile in `docs/policy/best-practice-for-this-project.md`
 
@@ -216,8 +222,8 @@ ceremony is required.
 
 Add:
 
-- `docs/governance/agents-routing/doc-only-v1.0.md`
-- `docs/governance/ssot-v1.0.md`
+- `docs/governance/agents-routing/doc-only-v1.1.md`
+- `docs/governance/ssot-v1.1.md`
 - AI-in-the-Loop rules linked from the project's external shared-rule source
 - canon/provenance/archive rules in `docs/policy/best-practice-for-this-project.md`
 
@@ -257,8 +263,10 @@ Prompts, generated media notes, project-package canon, source assets, and
 workbench files stay in their product package unless the project explicitly opts
 them into doc-gov.
 
-For the v1.0 structural migration, use
-`docs/reference/adoption/migration-v1.0.md` as the checklist.
+For the current host-SSOT migration, use
+`docs/reference/adoption/migration-v1.1.md` as the checklist. The v1.0 checklist
+remains historical guidance for projects that have not yet completed the
+decision and learning-surface migration.
 
 ## Step 8: Validate
 

package/assets/docs/reference/adoption/migration-v1.1.md

@@ -0,0 +1,164 @@
+---
+id: REF-MIGRATION-V1-1
+title: Project Governance System v1.1 Migration Checklist
+type: reference
+status: stable
+canonical: true
+owner: human
+created: 2026-07-13
+last_reviewed: 2026-07-13
+domain: adoption
+tags:
+  - migration
+  - v1.1
+  - ai-hosts
+  - skills
+  - symlinks
+pinned: false
+related:
+  - POLICY-VERSIONING
+  - REF-ADOPTION-PLAYBOOK
+  - GOV-SSOT-V1-1
+  - GOV-AGENTS-ROUTING-ENGINEERING-RUNTIME-V1-1
+  - GOV-AGENTS-ROUTING-DOC-ONLY-V1-1
+---
+
+# v1.1 Migration Checklist
+
+Use this checklist when upgrading a v1.0 project. v1.1 removes duplicate
+project router and skill surfaces across AI hosts. It does not change the
+project's product truth, host-native runtime settings, or the installation
+model of individual skills.
+
+## Target Contract
+
+A migrated project has exactly these project-level truth surfaces:
+
+| Concern | Canonical path | Exact compatibility link |
+| --- | --- | --- |
+| Project AI router | `AGENTS.md` | `CLAUDE.md -> AGENTS.md` |
+| Project skills | `.agents/skills/` | `.claude/skills -> ../.agents/skills` |
+
+The target text shown after each arrow is the raw symbolic-link target. An
+absolute link or a differently spelled relative link is not the v1.1 contract,
+even when it resolves to the same destination on one machine.
+
+The exact-relative requirement applies to these compatibility roots only.
+Entries under `.agents/skills/<skill>` may remain directories or valid
+absolute or relative symlinks.
+
+## Preflight Inventory
+
+Before replacing anything:
+
+1. Confirm that `AGENTS.md` is the intended project router.
+2. Inspect `CLAUDE.md` with `lstat` or `readlink`; do not assume a path is a
+   link because its content resembles `AGENTS.md`.
+3. Inventory both `.agents/skills/` and `.claude/skills/`.
+4. Identify any Claude-only skill that does not already exist under
+   `.agents/skills/`.
+5. Check Git status and preserve unrelated work.
+6. If the project uses managed asset locks, identify which links are
+   PGS-managed before changing them.
+
+Do not delete a copied skill directory until every unique skill has a reviewed
+canonical destination.
+
+## Project Router Migration
+
+1. Merge any still-valid project guidance from an independent `CLAUDE.md` into
+   the canonical `AGENTS.md`. Remove duplicated or host-specific wording that
+   does not belong in the shared project router.
+2. Replace `CLAUDE.md` with a symbolic link whose raw target is exactly
+   `AGENTS.md`.
+3. Update the router marker to:
+   `<!-- PGS-ROUTER:BEGIN v1.1 -->`.
+4. Update startup references to:
+   - `docs/governance/ssot-v1.1.md`
+   - `docs/governance/agents-routing/<selected-profile>-v1.1.md`
+5. Remove the v1.0 SSOT and selected routing file from the downstream project
+   after v1.1 is installed. Do not keep two current contracts.
+
+Host-native settings such as `.claude/settings.json`, `.codex/config.toml`,
+or project MCP configuration remain separate. They may configure host behavior,
+but they must not become alternate project routers.
+
+## Project Skill Migration
+
+1. Create or confirm the canonical `.agents/skills/` directory.
+   Ensure it survives a clean checkout by tracking managed entries or
+   `.agents/skills/.gitkeep`. If the root is otherwise ignored, keep the
+   directory and placeholder explicitly unignored.
+2. Move or deliberately reinstall every unique project skill into that
+   canonical tree.
+3. Leave valid per-skill absolute or relative symlinks unchanged unless their
+   source is stale or broken.
+4. Replace `.claude/skills` with a symbolic link whose raw target is exactly
+   `../.agents/skills`.
+5. Confirm that every expected skill remains discoverable through both roots.
+
+Do not run a bulk relative-link rewrite inside `.agents/skills/`. The
+compatibility-root contract and the per-skill installation model are different
+layers.
+
+## User-Level Skill Scope
+
+User-level skills are not part of the portable project router contract. When a
+user chooses the same SSOT pattern, keep `~/.agents/skills/` canonical and use
+one compatible host-root link such as
+`~/.claude/skills -> ../.agents/skills`.
+
+Do not commit a user's home path into a project. User-level migration and
+validation belong to the user's skill manager or portfolio health tooling, not
+to a target repository's `doc-gov router-check`.
+
+## Governance File Migration
+
+Install only the current starter contract:
+
+- `docs/governance/ssot-v1.1.md`
+- `docs/governance/agents-routing/engineering-runtime-v1.1.md`, or
+- `docs/governance/agents-routing/doc-only-v1.1.md`
+
+The central PGS repository retains v1.0 documents as superseded history.
+Downstream starter assets and current router checks must not mix v1.0 and v1.1.
+
+## Verification
+
+First inspect the raw links:
+
+```bash
+test -L CLAUDE.md
+test "$(readlink CLAUDE.md)" = "AGENTS.md"
+test -d .agents/skills
+test -L .claude/skills
+test "$(readlink .claude/skills)" = "../.agents/skills"
+```
+
+Then run the governance and project checks:
+
+```bash
+pnpm pro-gov sync --check --profile <engineering-runtime|doc-only>
+pnpm pro-gov lens inspect --target .
+pnpm doc-gov check
+pnpm doc-gov router-check
+pnpm doc-gov scan
+pnpm doc-gov scan --check
+pnpm doc-gov links
+pnpm doc-gov doctor
+git diff --check
+```
+
+Run the target project's normal typecheck, lint, tests, build, and visual checks
+when the migration is part of an engineering repository upgrade.
+
+## Completion Evidence
+
+Record:
+
+- the raw target and resolved destination of both compatibility links;
+- any unique skill moved into the canonical tree;
+- the selected v1.1 routing profile;
+- governance check results;
+- project verification results;
+- any deliberate exception that remains outside the portable project contract.