@pieai/pro-gov 0.3.3

package/assets/docs/reference/adoption/site-publication-brief.md

@@ -0,0 +1,86 @@
+---
+id: REF-SITE-PUBLICATION-BRIEF
+title: Website Publication Brief
+type: reference
+status: stable
+canonical: true
+owner: human
+created: 2026-06-04
+last_reviewed: 2026-06-13
+domain: adoption
+tags:
+  - website
+  - public
+  - handoff
+pinned: false
+related:
+  - REF-PUBLIC-RELEASE-CHECKLIST
+  - REF-PROJECT-RELATIONSHIP
+---
+
+# Website Publication Brief
+
+Use this when asking the PieAI Studio website project to add Project Governance
+System as a public project page.
+
+## Public Positioning
+
+Project Governance System is an AI-native governance layer for projects that
+work with AI agents over time.
+
+Beginner-friendly description:
+
+> Git remembers code history. AGENTS.md tells an AI how to enter a project.
+> Superpowers gives engineering workflows. Project Governance System is the
+> librarian and traffic desk: it decides where durable AI-created documents
+> belong, which ones are current truth, which route a task should take, and
+> when old documents should retire.
+
+## What To Emphasize
+
+- It keeps AI-generated specs, plans, decisions, references, and routing rules
+  from becoming unmanaged clutter.
+- It separates central governance rules from project-local truth.
+- It has two practical profiles: engineering-runtime and doc-only.
+- It provides `doc-gov` commands for schema checks, manifest freshness, link
+  checks, router integrity, health checks, and read-only migration checks.
+- It provides `pro-gov` commands for packaged starter/profile assets,
+  read-only init planning, read-only sync checks, and package health checks.
+- It is designed to work with external workflow systems instead of replacing
+  them.
+
+## Do Not Overclaim
+
+- Do not say it replaces Git.
+- Do not say it replaces Superpowers.
+- Do not say it automatically migrates every project.
+- Do not imply product prompts, generated media, or runtime assets must move
+  under `docs/**`.
+
+## Suggested Website Prompt
+
+```text
+Read <local ProjectGovernanceSystem checkout path> as the source project.
+
+Add Project Governance System to <local PieAIStudio-Site path> as a
+public project surface. Follow the existing project-page pattern, homepage card
+pattern, translations, and sitemap conventions in that website repository.
+
+Use the central repo's README.md, packages/doc-gov/README.md,
+packages/pro-gov/README.md, docs/reference/adoption/public-release-checklist.md,
+and docs/reference/adoption/site-publication-brief.md as source material.
+
+Position it for normal readers as an AI-era documentation governance system:
+the librarian and traffic desk for AI-created project documents. Explain what
+problem it solves, why it matters, how doc-gov checks work, and how it fits next
+to Git, AGENTS.md, Superpowers, pro-gov starter/profile distribution, and
+project-local product truth.
+
+Keep the copy confident but accurate. Do not claim automatic migration or
+full replacement of existing workflow tools. npm publication is live, so include
+the package install commands for @pieai/doc-gov and @pieai/pro-gov, and link the
+npm packages plus the GitHub repository.
+
+After implementation, run the site's normal quality/typecheck/build checks and
+verify the new public route plus sitemap entry.
+```

package/assets/integrations/directed-development.md

@@ -0,0 +1,36 @@
+# Directed Development Integration
+
+Directed Development is an optional workflow for mixed, cross-domain, interdependent product work.
+
+It is not the default for every task.
+
+## Boundary
+
+Directed Development may define:
+
+- ordered DD Blocks
+- dependencies between Blocks
+- BDD-style acceptance scenarios
+- verification gates
+
+Directed Development must not define:
+
+- artifact locations
+- project document paths
+- project lane names
+- runtime truth
+
+Those remain owned by the project and doc-gov.
+
+Agents routing decides whether this workflow applies. Directed Development does
+not replace the project router.
+
+## Trigger
+
+Use Directed Development only when all are true:
+
+- the task is product work
+- it crosses local lanes or shared contracts
+- sequencing risk makes a flat plan unsafe
+
+Doc-only projects do not use Directed Development unless explicitly opted in.

package/assets/integrations/superpowers.md

@@ -0,0 +1,52 @@
+# Superpowers Integration
+
+Superpowers is an external plugin/system. This repository does not vendor or rewrite it.
+
+## Boundary
+
+Superpowers owns engineering workflows such as:
+
+- brainstorming
+- writing plans
+- TDD
+- debugging
+- verification before completion
+- worktree usage
+
+Project Governance System owns:
+
+- documentation lifecycle
+- agents routing
+- current work index conventions
+- the governed location and boundary for externally sourced AI evidence rules
+
+## Rule
+
+Use Superpowers inside the selected project lane. Do not let Superpowers create a separate durable document tree unless the project explicitly adopts one.
+
+Durable outputs should map back to the project's doc-gov layers:
+
+- specs -> `docs/specs/**`
+- plans -> `docs/plans/**`
+- durable references -> `docs/reference/**`
+
+## Execution Order
+
+Agents routing classifies first. Superpowers executes inside the selected lane.
+
+```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?"}
+  D -- "yes" --> E["Use the matching Superpowers skill"]
+  D -- "no" --> F["Use the local non-Superpowers lane rules"]
+  E --> G["Write durable outputs into doc-gov layers"]
+  F --> G
+```
+
+If Superpowers suggests a default location such as `docs/superpowers/**`, project instructions may override that location. The durable project record should still land in the governed doc-gov layer unless the project has explicitly adopted a separate Superpowers document tree.
+
+Host-specific files such as `CLAUDE.md` may include Superpowers skill routing
+text. That text is an adapter. It must not replace the project `AGENTS.md`
+router or run before the Project Governance System routing block.

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

@@ -0,0 +1,21 @@
+profile: doc-only
+required:
+  doc_gov: true
+  pro_gov: true
+  ssot: true
+  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-v0.9.md
+  current_work: docs/reference/execution/current-work.md
+optional:
+  directed_development: false
+  superpowers: false
+project_local_required:
+  - docs/policy/best-practice-for-this-project.md
+  - canon/provenance/approval boundaries
+  - archive/delete policy
+not_included:
+  - engineering-runtime agents routing
+  - behavior-critical code lanes
+  - Superpowers TDD workflow

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

@@ -0,0 +1,37 @@
+# Doc-Only Profile
+
+Use for non-runtime projects: IP development, AI media production, research vaults, writing systems, asset governance, and strategy libraries.
+
+## Includes
+
+- `packages/doc-gov`
+- `packages/pro-gov`
+- `docs/governance/ssot-v0.9.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-v0.9.md`
+- starter `docs/governance/` and `docs/policy/` templates
+
+## Does Not Include By Default
+
+- engineering-runtime agents routing
+- Directed Development
+- Superpowers TDD
+- behavior-critical code lanes
+
+## Requires Project-Local Rules
+
+Each project must define:
+
+- canon layers
+- asset/provenance rules
+- approval boundaries
+- archive/delete policy
+- current work index (required, kept lightweight when there is no active execution lane)
+
+## Automation Boundary
+
+This profile is a human/AI adoption contract. `doc-gov` validates the resulting
+project shape. `pro-gov` packages reusable starter/profile assets and exposes
+read-only init/sync checks, but it does not overwrite project-local files in
+the first release. Use `starter/`, this profile, and `manifest.yml` as the
+reference checklist.

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

@@ -0,0 +1,22 @@
+profile: engineering-runtime
+required:
+  doc_gov: true
+  pro_gov: true
+  ssot: true
+  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-v0.9.md
+  current_work: docs/reference/execution/current-work.md
+optional:
+  directed_development: integrations/directed-development.md
+  superpowers: integrations/superpowers.md
+project_local_required:
+  - docs/policy/best-practice-for-this-project.md
+  - AGENTS.md lane summary
+  - verification command ladder
+  - current runtime truth hierarchy
+not_included:
+  - product canon
+  - project-specific runtime rules
+  - Superpowers plugin body

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

@@ -0,0 +1,39 @@
+# Engineering Runtime Profile
+
+Use for code-heavy projects: apps, games, runtimes, services, browser products, Electron apps, and multiplayer prototypes.
+
+## Includes
+
+- `packages/doc-gov`
+- `packages/pro-gov`
+- `docs/governance/ssot-v0.9.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-v0.9.md`
+- `integrations/superpowers.md`
+- `integrations/directed-development.md`
+- starter `docs/governance/` and `docs/policy/` templates
+
+## Requires Project-Local Rules
+
+Each project must define:
+
+- current runtime truth hierarchy
+- lane profile
+- behavior-critical paths
+- verification command ladder
+- current work index
+
+## Does Not Include
+
+- product canon
+- stack-specific rules
+- game/app-specific lane wording
+- Superpowers plugin body
+
+## Automation Boundary
+
+This profile is a human/AI adoption contract. `doc-gov` validates the resulting
+project shape. `pro-gov` packages reusable starter/profile assets and exposes
+read-only init/sync checks, but it does not overwrite project-local files in
+the first release. Use `starter/`, this profile, and `manifest.yml` as the
+reference checklist.

package/assets/starter/.github/workflows/docs-check.yml

@@ -0,0 +1,59 @@
+name: docs-check
+
+on:
+  pull_request:
+    paths:
+      - "AGENTS.md"
+      - "CLAUDE.md"
+      - "GEMINI.md"
+      - "README.md"
+      - "docs/**"
+      - "lefthook.yml"
+      - ".github/workflows/docs-check.yml"
+      - "package.json"
+      - "pnpm-lock.yaml"
+  push:
+    branches:
+      - main
+    paths:
+      - "AGENTS.md"
+      - "CLAUDE.md"
+      - "GEMINI.md"
+      - "README.md"
+      - "docs/**"
+      - "lefthook.yml"
+      - ".github/workflows/docs-check.yml"
+      - "package.json"
+      - "pnpm-lock.yaml"
+
+jobs:
+  doc-gov:
+    name: doc-gov
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Validate router and entry files
+        run: pnpm doc-gov router-check
+
+      - name: Validate governed docs
+        run: pnpm doc-gov check
+
+      - name: Validate manifest freshness
+        run: pnpm doc-gov scan --check
+
+      - name: Validate links
+        run: pnpm doc-gov links
+
+      - name: Audit docs
+        run: pnpm doc-gov audit

package/assets/starter/AGENTS.template.md

@@ -0,0 +1,48 @@
+# PROJECT_NAME AI Router
+
+## PGS Router Block
+
+<!-- PGS-ROUTER:BEGIN v0.9 -->
+
+## Startup Reading
+
+`README.md` is the human-facing project introduction. Do not use it as the default AI startup path unless the task is about project positioning, public explanation, or the README itself.
+
+1. All Markdown files under `docs/policy/**/*.md`, including files in
+   subdirectories and symlinked shared-rule files.
+2. `docs/governance/boundary.md`
+3. `docs/governance/ssot-v0.9.md`
+4. `docs/governance/doc-agent-rules.md`
+5. `docs/governance/doc-types.md`
+6. The selected agents routing file:
+   - `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`
+
+## Governance
+
+- Use doc-gov for governed Markdown.
+- Governed Markdown lives under `docs/**` by default.
+- Product artifacts outside `docs/**` are not governed docs unless this project explicitly opts them in.
+- Before creating docs: `pnpm doc-gov find <topic>`.
+- Before claiming doc work complete:
+  - `pnpm doc-gov router-check`
+  - `pnpm doc-gov check`
+  - `pnpm doc-gov scan --check`
+  - `pnpm doc-gov links`
+  - `pnpm doc-gov audit`
+  - `pnpm doc-gov doctor`
+
+## Routing
+
+- Name this project's adopted profile: `engineering-runtime` or `doc-only`.
+- 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 `integrations/` into the target project by default.
+- 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.
+
+<!-- PGS-ROUTER:END -->
+
+## Upstream Rule
+
+Do not locally invent doc-gov core changes such as new document statuses, frontmatter schema, lifecycle rules, shared agents-routing rules, or external shared-rule placement contracts. If such a change seems necessary, propose it upstream in the Project Governance System upstream repository first.

package/assets/starter/CLAUDE.template.md

@@ -0,0 +1,6 @@
+# Claude Adapter
+
+Read `AGENTS.md` first and follow it as the project router.
+
+Claude-specific workflow guidance may add tool usage details, but it must not
+replace or run before the Project Governance System router block in `AGENTS.md`.

package/assets/starter/docs/archive/.gitkeep

@@ -0,0 +1 @@
+

package/assets/starter/docs/canon/.gitkeep

@@ -0,0 +1 @@
+

package/assets/starter/docs/decisions/.gitkeep

@@ -0,0 +1 @@
+

package/assets/starter/docs/governance/agents-routing/doc-only-v0.9.md

@@ -0,0 +1,83 @@
+---
+id: GOV-AGENTS-ROUTING-DOC-ONLY-V0-9
+title: Doc-Only Agents Routing v0.9
+type: policy
+status: stable
+canonical: true
+owner: human
+created: 2026-05-09
+last_reviewed: 2026-05-09
+domain: agents-routing
+tags:
+  - agents-routing
+  - doc-only
+  - workflow
+pinned: true
+related:
+  - GOV-SSOT-V0-9
+  - REF-DOC-GOVERNANCE-BOUNDARY
+supersedes: []
+superseded_by: null
+---
+
+# Doc-Only Agents Routing v0.9
+
+Shared routing algorithm for non-runtime projects such as AI media, IP development, research, and asset governance workspaces.
+
+This route does not use Superpowers TDD or Directed Development by default.
+
+## Core Flow
+
+```mermaid
+flowchart TD
+  A["Task arrives"] --> B["Read project router and current work"]
+  B --> C{"What is being changed?"}
+  C --> D["canon / durable truth"]
+  C --> E["asset / provenance"]
+  C --> F["reference / operating guide"]
+  C --> G["archive / cleanup"]
+  C --> H["review / synthesis"]
+  D --> I["Update canonical doc"]
+  E --> J["Preserve source and approval trail"]
+  F --> K["Update reusable guide"]
+  G --> L["Archive or delete stale material"]
+  H --> M["Write summary and evidence"]
+  I --> N["Run doc-gov checks"]
+  J --> N
+  K --> N
+  L --> N
+  M --> N
+```
+
+## Rules
+
+- Do not ask whether the task needs TDD unless the project has actual runtime code.
+- Do not trigger Directed Development unless the project explicitly opts in.
+- Prefer SSOT, provenance, and approval clarity over engineering ceremonies.
+- Use AI-in-the-Loop for evidence: inspect source, change one thing, verify the target document or asset path.
+
+## Typical Lanes
+
+- canon truth
+- asset intake and promotion
+- production/reference guide
+- archive and cleanup
+- research synthesis
+
+The local project decides exact lane names.
+
+## Product Artifact Boundary
+
+Doc-only projects often produce Markdown, prompts, images, scripts, bibles,
+reference packs, and asset manifests as product artifacts.
+
+Those artifacts do not become governed `docs/**` files just because they are
+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.
+
+## External Workflow Boundary
+
+This route runs before external workflow systems such as Superpowers or GStack.
+Host-specific files such as `CLAUDE.md` or `GEMINI.md` may adapt the route for a
+specific AI client, but they must not replace the project `AGENTS.md` route.

package/assets/starter/docs/governance/agents-routing/engineering-runtime-v0.9.md

@@ -0,0 +1,78 @@
+---
+id: GOV-AGENTS-ROUTING-ENGINEERING-RUNTIME-V0-9
+title: Engineering Runtime Agents Routing v0.9
+type: policy
+status: stable
+canonical: true
+owner: human
+created: 2026-05-09
+last_reviewed: 2026-05-09
+domain: agents-routing
+tags:
+  - agents-routing
+  - engineering-runtime
+  - workflow
+pinned: true
+related:
+  - GOV-SSOT-V0-9
+  - REF-DOC-GOVERNANCE-BOUNDARY
+supersedes: []
+superseded_by: null
+---
+
+# Engineering Runtime Agents Routing v0.9
+
+Shared routing algorithm for app, game, runtime, and code-heavy projects.
+
+This file decides **how to choose a workflow**, not what the project is currently building. Current work belongs in the project's `docs/reference/execution/current-work.md` or equivalent.
+
+## Core Flow
+
+```mermaid
+flowchart TD
+  A["Task arrives"] --> B["Read project router and current work"]
+  B --> C["Classify with local lane profile"]
+  C --> D{"Mixed / cross-domain / interdependent product work?"}
+  D -- "yes" --> E["Use Directed Development to split ordered DD Blocks"]
+  E --> C
+  D -- "no" --> F["Enter local lane"]
+  F --> G["Use matching Superpowers workflow if applicable"]
+  G --> H["Use AI-in-the-Loop evidence cycle"]
+  H --> I["Record evidence in doc-gov"]
+```
+
+## Keep It Small
+
+Use this router only to pick depth and workflow. Do not use it as a project roadmap.
+
+## DD Trigger
+
+Use Directed Development only when all are true:
+
+- the task is product work
+- it crosses local lanes or shared contracts
+- sequencing risk makes a flat plan unsafe
+
+Do not trigger DD for broad mechanical edits, renames, formatting, or ordinary docs migration.
+
+## Project-Local Lane Profile
+
+Every engineering project must define its own lane profile in `AGENTS.md` or `docs/policy/best-practice-for-this-project.md`.
+
+Typical lanes:
+
+- visual / UX / game-feel
+- content / config / canon
+- behavior-critical code
+- pure refactor
+
+But the shared router must not define project-specific lanes.
+
+## External Workflow Boundary
+
+This route runs before external workflow systems such as Superpowers or GStack.
+Those systems may provide skills, reviews, browser workflows, or shipping gates,
+but they execute **inside** the lane selected by this route.
+
+Host-specific files such as `CLAUDE.md` or `GEMINI.md` may adapt the route for a
+specific AI client, but they must not replace the project `AGENTS.md` route.

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

@@ -0,0 +1,76 @@
+---
+id: REF-DOC-GOVERNANCE-BOUNDARY
+title: Documentation Governance Boundary
+type: reference
+status: stable
+canonical: true
+owner: project
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: doc-governance
+tags:
+  - doc-gov
+  - boundary
+pinned: true
+related:
+  - POLICY-DOC-AGENT-RULES
+  - POLICY-DOC-TYPES
+supersedes: []
+superseded_by: null
+---
+
+# Project Governance Boundary
+
+Use this folder for the Project Governance System's own rules.
+
+Beginner version: `docs/governance/` is the filing-cabinet manual and traffic
+desk. It explains how governed documents work, how agents choose a workflow,
+and what the system does not govern.
+
+It is not where project product truth, source assets, generated media, or
+project-specific AI development habits live.
+
+## Put Here
+
+- Document types and lifecycle rules.
+- SSOT rules for governed docs.
+- Agents-routing rules.
+- Documentation agent behavior rules.
+- Document templates.
+- The generated doc manifest.
+
+## Do Not Put Here
+
+- Project-specific AI development practices.
+- Product canon, runtime truth, or content truth.
+- Product prompts, generated media notes, or project-package workbench files.
+- Current project plans or active specs.
+- Superpowers plugin content.
+
+## Put Those Elsewhere
+
+| Need | Put it in |
+| --- | --- |
+| AI startup entry | `AGENTS.md` |
+| Agent routing algorithm | `docs/governance/agents-routing/` |
+| Governed SSOT rules | `docs/governance/ssot-v0.9.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/` |
+| Active implementation work | `docs/plans/active/` |
+| Completed proof records | `docs/plans/completed/` |
+| Product artifacts outside governed docs | Project package, workbench, assets, runtime config, or source tree |
+
+When unsure, ask this question: is this rule about how the document system works,
+how agents should route work, or about how this particular project works?
+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`.
+
+It does not govern every Markdown file in the repository. Markdown under
+product packages, workbenches, prompt libraries, source folders, or asset
+folders can be product artifacts. Keep those files where the product package
+expects them unless a project explicitly opts them into doc-gov.