@pieai/pro-gov 0.3.3

package/assets/starter/docs/governance/doc-agent-rules.md

@@ -0,0 +1,71 @@
+---
+id: POLICY-DOC-AGENT-RULES
+title: Documentation Agent Rules
+type: policy
+status: stable
+canonical: true
+owner: project
+created: 2026-05-08
+last_reviewed: 2026-06-12
+domain: doc-governance
+tags:
+  - doc-gov
+  - agent-rules
+pinned: true
+related:
+  - POLICY-DOC-TYPES
+supersedes: []
+superseded_by: null
+---
+
+# Documentation Agent Rules
+
+This file belongs in `docs/governance/` because it governs how the documentation
+system itself behaves.
+
+Doc-gov governs `docs/**` by default. Do not move product prompts, generated
+media notes, source assets, runtime docs, or project-package Markdown into
+`docs/**` unless the project explicitly opts those files into governance.
+
+## Before Creating Docs
+
+Run:
+
+```bash
+pnpm doc-gov find <topic>
+```
+
+If a canonical document exists, update it instead of creating a parallel document.
+
+## Closed Document Types
+
+Use only:
+
+- `policy`
+- `decision`
+- `spec`
+- `plan`
+- `canon`
+- `reference`
+- `archive`
+
+## Status Machine
+
+Normal documents:
+
+```text
+draft -> active -> completed -> stable -> superseded -> archived
+```
+
+Decision documents:
+
+```text
+proposed -> accepted -> rejected | superseded
+```
+
+`completed` is for finished execution records or specs that should no longer appear in active folders.
+
+## Upstream Rule
+
+Do not locally invent doc-gov core changes. Propose core changes upstream in
+the Project Governance System upstream repository.

package/assets/starter/docs/governance/doc-types.md

@@ -0,0 +1,50 @@
+---
+id: POLICY-DOC-TYPES
+title: Document Types
+type: policy
+status: stable
+canonical: true
+owner: project
+created: 2026-05-08
+last_reviewed: 2026-05-08
+domain: doc-governance
+tags:
+  - doc-gov
+  - document-types
+pinned: true
+related:
+  - POLICY-DOC-AGENT-RULES
+supersedes: []
+superseded_by: null
+---
+
+# Document Types
+
+This file belongs in `docs/governance/` because it defines the document system's
+own cabinets and lifecycle.
+
+Allowed types:
+
+| Type | Default path |
+| --- | --- |
+| `policy` | `docs/policy/` for project policy; `docs/governance/` for doc-system policy |
+| `decision` | `docs/decisions/` |
+| `spec` | `docs/specs/active/` or `docs/specs/completed/` |
+| `plan` | `docs/plans/active/` or `docs/plans/completed/` |
+| `canon` | `docs/canon/` |
+| `reference` | `docs/reference/` |
+| `archive` | `docs/archive/` |
+
+Markdown outside `docs/**` is not a governed doc by default.
+
+Normal documents use:
+
+```text
+draft -> active -> completed -> stable -> superseded -> archived
+```
+
+Decision documents use:
+
+```text
+proposed -> accepted -> rejected | superseded
+```

package/assets/starter/docs/governance/ssot-v0.9.md

@@ -0,0 +1,166 @@
+---
+id: GOV-SSOT-V0-9
+title: SSOT Documentation Governance Rules v0.9
+type: policy
+status: stable
+canonical: true
+owner: human
+created: 2026-05-09
+last_reviewed: 2026-05-09
+domain: doc-governance
+tags:
+  - ssot
+  - doc-gov
+  - boundary
+pinned: true
+related:
+  - REF-DOC-GOVERNANCE-BOUNDARY
+supersedes: []
+superseded_by: null
+---
+
+# SSOT Documentation Governance Rules v0.9
+
+This rule defines how projects using Project Governance System handle
+**SSOT (Single Source of Truth)** for governed documentation.
+
+Use it whenever an AI agent creates, modifies, moves, deletes, archives, or
+cross-references project documents.
+
+Beginner version: every important fact should have one home. Other files can
+point to that home, but they should not become competing copies.
+
+## Governance Scope
+
+Project Governance System governs:
+
+- `AGENTS.md` and equivalent AI entry files.
+- Governed Markdown under `docs/**`.
+- Documentation governance rules, agent routing rules, templates, manifests,
+  plans, specs, decisions, references, canon, and archives that live under
+  `docs/**`.
+
+Project Governance System does **not** automatically govern every Markdown file
+or every asset in the repository.
+
+Markdown outside `docs/**` can be a product artifact, source asset, prompt,
+project package file, runtime note, generated media description, or local
+workbench record. Do not move those files into `docs/**` just because they are
+Markdown.
+
+Extra governed roots are allowed only when a project explicitly opts in.
+
+## 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.
+- **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 AI dump folders inside governed docs**: do not create ad-hoc `Temp/`,
+  `Drafts/`, `Opus/`, `Codex/`, or AI-name folders under `docs/**`.
+
+## Discovery Order
+
+Before changing docs, look for project-local guidance in this order:
+
+1. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or equivalent AI router.
+2. `docs/governance/boundary.md`.
+3. `docs/governance/ssot-v0.9.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.
+6. `docs/policy/`, `docs/governance/`, or equivalent project rules.
+7. Any project-specific doc tooling such as `doc-gov`, `mintlify`,
+   `docusaurus`, `vitepress`, or custom scripts.
+8. Runtime truth locations named by the project, such as config files, schemas,
+   manifests, source packages, product packages, or asset manifests.
+
+If the project uses `doc-gov`, follow it:
+
+```bash
+pnpm doc-gov find <topic>
+pnpm doc-gov check
+pnpm doc-gov scan --check
+```
+
+Do not invent a second structure when doc-gov already defines one.
+
+## Choosing The Truth Layer
+
+Use the project's own vocabulary when available. If none exists, this fallback
+works for governed docs:
+
+| Need | Usually belongs in |
+| --- | --- |
+| AI entry and startup routing | `AGENTS.md` plus host-specific forwarders |
+| Agents-routing rules | `docs/governance/agents-routing/` |
+| Doc-system rules, templates, and manifest | `docs/governance/` |
+| Project AI/development policy | `docs/policy/` |
+| Product or feature requirement | `docs/specs/` |
+| Step-by-step implementation work | `docs/plans/` |
+| Durable workspace/system truth | `docs/canon/` |
+| How-to guides, architecture maps, tool notes | `docs/reference/` |
+| Retired governed history | `docs/archive/` |
+| Runtime ids, values, generated asset paths | code/config/manifests, not Markdown body |
+| Product prompts, project-package canon, generated media notes | project package or workbench, not `docs/**` by default |
+
+If the project has different layers, use the project layers instead of this
+table.
+
+## Editing Rules
+
+When modifying documentation:
+
+1. Find the canonical source first.
+2. Decide whether the file is a governed doc or a 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
+   docs.
+7. Run the project's doc checks before claiming completion.
+
+## Moving Or Deleting Docs
+
+- If the content is still useful governed history, archive it under the
+  project-approved `docs/archive/**` path.
+- If the content is stale, misleading, and already superseded, deletion can be
+  better than hoarding.
+- Do not preserve obsolete drafts just to feel safe; excessive history increases
+  AI cognitive load.
+- If a file is moved, update indexes, manifests, and symlinks.
+- Do not move product artifacts into `docs/**` as a cleanup shortcut.
+
+## Completion Checklist
+
+Before reporting doc work complete:
+
+- [ ] I found the project documentation system.
+- [ ] I identified whether the changed file is governed documentation or a
+      product artifact.
+- [ ] I updated the canonical source, not a duplicate.
+- [ ] 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.
+
+## Common Mistakes
+
+| Mistake | Better move |
+| --- | --- |
+| Copying the same design rule into five docs | Keep one canonical doc, link from the others. |
+| 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. |
+| Creating a new folder because the current structure feels inconvenient | Use the governed structure or update governance first. |
+| Keeping outdated drafts forever | Archive only useful history; delete misleading noise. |

package/assets/starter/docs/governance/templates/adr.md

@@ -0,0 +1,24 @@
+---
+id: REPLACE-ME
+title: Replace Me
+type: decision
+status: proposed
+canonical: true
+owner: human
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: meta
+tags:
+  - replace-me
+pinned: false
+related: []
+---
+
+# REPLACE-ME: Replace Me
+
+## Context
+
+## Decision
+
+## Consequences
+

package/assets/starter/docs/governance/templates/archive.md

@@ -0,0 +1,23 @@
+---
+id: REPLACE-ME
+title: Replace Me
+type: archive
+status: archived
+canonical: false
+owner: human
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: archive
+tags:
+  - replace-me
+pinned: false
+related: []
+archive_reason: Replace me
+---
+
+# REPLACE-ME: Replace Me (archived)
+
+## Archived Reason
+
+## Historical Notes
+

package/assets/starter/docs/governance/templates/canon-entry.md

@@ -0,0 +1,24 @@
+---
+id: REPLACE-ME
+title: Replace Me
+type: canon
+status: draft
+canonical: false
+owner: human
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: canon
+tags:
+  - replace-me
+pinned: false
+related: []
+---
+
+# REPLACE-ME: Replace Me
+
+## Current Truth
+
+## Source / Provenance
+
+## Open Questions
+

package/assets/starter/docs/governance/templates/plan.md

@@ -0,0 +1,33 @@
+---
+id: REPLACE-ME
+title: Replace Me
+type: plan
+status: draft
+canonical: false
+owner: ai-assisted
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: meta
+tags:
+  - replace-me
+pinned: false
+related: []
+---
+
+# REPLACE-ME: Replace Me
+
+## Goal
+
+## Scope
+
+## Steps
+
+- [ ] Step 1
+
+## Acceptance
+
+- [ ] Verification completed
+
+## Closeout
+
+When complete, move this plan to `docs/plans/completed/` and set `status: completed`.

package/assets/starter/docs/governance/templates/policy.md

@@ -0,0 +1,24 @@
+---
+id: REPLACE-ME
+title: Replace Me
+type: policy
+status: draft
+canonical: false
+owner: human
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: policy
+tags:
+  - replace-me
+pinned: false
+related: []
+---
+
+# REPLACE-ME: Replace Me
+
+## Rule
+
+## Rationale
+
+## Examples
+

package/assets/starter/docs/governance/templates/reference.md

@@ -0,0 +1,24 @@
+---
+id: REPLACE-ME
+title: Replace Me
+type: reference
+status: draft
+canonical: false
+owner: human
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: reference
+tags:
+  - replace-me
+pinned: false
+related: []
+---
+
+# REPLACE-ME: Replace Me
+
+## Purpose
+
+## Details
+
+## Related Commands / Files
+

package/assets/starter/docs/governance/templates/spec.md

@@ -0,0 +1,24 @@
+---
+id: REPLACE-ME
+title: Replace Me
+type: spec
+status: draft
+canonical: false
+owner: human
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: meta
+tags:
+  - replace-me
+pinned: false
+related: []
+---
+
+# REPLACE-ME: Replace Me
+
+## Problem
+
+## Requirements
+
+## Acceptance
+

package/assets/starter/docs/plans/active/.gitkeep

@@ -0,0 +1 @@
+

package/assets/starter/docs/plans/completed/.gitkeep

@@ -0,0 +1 @@
+

package/assets/starter/docs/policy/best-practice-for-this-project.md

@@ -0,0 +1,35 @@
+---
+id: POLICY-PROJECT-BEST-PRACTICE
+title: Best Practice for This Project
+type: policy
+status: stable
+canonical: true
+owner: project
+created: 2026-05-08
+last_reviewed: 2026-05-08
+domain: project-policy
+tags:
+  - project-policy
+  - ai-development
+pinned: true
+related:
+  - POLICY-DOC-AGENT-RULES
+  - POLICY-DOC-TYPES
+supersedes: []
+superseded_by: null
+---
+
+# Best Practice for This Project
+
+This file is project-local.
+
+Put only project-specific rules here:
+
+- current project truth
+- runtime or canon truth hierarchy
+- local lane profile
+- verification commands
+- asset/provenance rules
+- current phase constraints
+
+Do not put cross-project doc-gov core rules here.

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

@@ -0,0 +1,51 @@
+---
+id: REF-DOCUMENTATION-MAP
+title: Documentation Map
+type: reference
+status: active
+canonical: true
+owner: human
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: meta
+tags:
+  - navigation
+pinned: false
+related: []
+---
+
+# Documentation Map
+
+This is a human and AI map of the governed document shelves. It is not the AI startup entrypoint; `AGENTS.md` is.
+
+## AI Startup Source
+
+Use `AGENTS.md` for startup reading. It should point agents to:
+
+- `docs/policy/*.md`
+- `docs/governance/boundary.md`
+- `docs/governance/ssot-v0.9.md`
+- `docs/governance/doc-agent-rules.md`
+- `docs/governance/doc-types.md`
+- `docs/governance/agents-routing/<selected-profile>-v0.9.md`
+- `docs/reference/execution/current-work.md`
+
+## Areas
+
+| Area | Purpose |
+| --- | --- |
+| `docs/policy/` | Project policy and AI development rules |
+| `docs/decisions/` | Durable decisions |
+| `docs/specs/active/` | Active requirements |
+| `docs/specs/completed/` | Completed specs |
+| `docs/plans/active/` | Active implementation plans |
+| `docs/plans/completed/` | Completed execution records |
+| `docs/canon/` | Durable project truth |
+| `docs/reference/` | Guides and references |
+| `docs/archive/` | Retired history |
+| `docs/governance/` | Governance core rules, SSOT, agents routing, doc types, templates, and manifest |
+
+Markdown outside `docs/**` is not governed by default. Product prompts, assets,
+project-package canon, generated media notes, and source-package files stay in
+their product/workbench structure unless this project explicitly opts them into
+doc-gov.

package/assets/starter/docs/reference/execution/current-work.md

@@ -0,0 +1,36 @@
+---
+id: REF-CURRENT-WORK
+title: Current Work
+type: reference
+status: active
+canonical: true
+owner: human
+created: YYYY-MM-DD
+last_reviewed: YYYY-MM-DD
+domain: meta
+tags:
+  - current-work
+  - navigation
+pinned: true
+related: []
+---
+
+# Current Work
+
+This file is the current project work index. It is not the agents-routing algorithm.
+
+## Current Focus
+
+- Current phase:
+- Current active plan:
+- Current active spec:
+- Current proof target:
+
+## Completed Proof History
+
+Completed plans and specs live in:
+
+- `docs/plans/completed/`
+- `docs/specs/completed/`
+
+Do not move completed work back into active. Create a new plan and link the completed record as provenance.

package/assets/starter/docs/specs/active/.gitkeep

@@ -0,0 +1 @@
+

package/assets/starter/docs/specs/completed/.gitkeep

@@ -0,0 +1 @@
+

package/assets/starter/lefthook.template.yml

@@ -0,0 +1,18 @@
+# lefthook.yml — Project Governance System standard doc-gov gate.
+# Copy to target project root as lefthook.yml, then run:
+#   pnpm exec lefthook install
+
+pre-commit:
+  parallel: false
+  commands:
+    01-doc-gov-router-check:
+      glob: "{AGENTS.md,CLAUDE.md,GEMINI.md,README.md,docs/**/*.{md,yml,yaml}}"
+      run: pnpm doc-gov router-check
+    02-doc-gov-check:
+      glob: "{docs/**/*.md,docs/governance/**/*.{md,yml,yaml},docs/policy/**/*.md,AGENTS.md,CLAUDE.md,GEMINI.md}"
+      run: pnpm doc-gov check && pnpm doc-gov scan --check && pnpm doc-gov links && pnpm doc-gov audit
+
+commit-msg:
+  commands:
+    doc-gov-commit-msg:
+      run: pnpm doc-gov verify-commit-msg "{1}"

package/cli-guide.md

@@ -0,0 +1,36 @@
+# pro-gov CLI Guide
+
+`pro-gov` is the project-level companion to `doc-gov`.
+
+Use it to inspect packaged Project Governance System assets, plan a starter
+installation, compare reusable governance files, and run package health checks.
+
+The validator remains `doc-gov`.
+
+## Commands
+
+```bash
+pro-gov assets list
+pro-gov init --profile engineering-runtime --dry-run
+pro-gov init --profile doc-only --dry-run
+pro-gov sync --check
+pro-gov doctor
+```
+
+`init` and `sync` are read-only in the first release. They report planned files,
+missing files, or changed files, but they do not overwrite target projects.
+
+## Typical Adoption Flow
+
+```bash
+pnpm add -D @pieai/pro-gov @pieai/doc-gov
+pnpm pro-gov assets list
+pnpm pro-gov init --profile engineering-runtime --dry-run
+pnpm pro-gov sync --check
+pnpm doc-gov migrate --profile engineering-runtime --check
+pnpm doc-gov doctor
+```
+
+Use `doc-only` instead of `engineering-runtime` for writing, research, IP, AI
+media, and asset-governance workspaces that do not need runtime engineering
+proof lanes.