@pieai/pro-gov 0.3.3 → 0.3.4

package/assets/integrations/ponytail.md

@@ -0,0 +1,109 @@
+# Ponytail Integration
+
+Ponytail is an external plugin that asks an AI to prefer the smallest solution
+that still works. Project Governance System does not vendor, rewrite, or require
+the Ponytail plugin.
+
+## The Beginner Version
+
+Think of an AI project as a building site:
+
+- PGS is the traffic desk and inspection station.
+- Superpowers is the construction process.
+- Ponytail is the cost and complexity adviser.
+
+The adviser can stop the team from buying unnecessary materials. The adviser
+cannot cancel the fire exit, the safety inspection, or a room the owner
+explicitly requested.
+
+## Safe Default
+
+Keep the global Ponytail mode `off`.
+
+`off` does not mean Ponytail is useless. It means Ponytail is available when a
+task needs a simplicity review without silently influencing every project and
+every answer.
+
+Do not describe `lite` as "almost off." In Ponytail 4.7.0, `lite` still injects
+the shared minimalism rules into the active AI context. Its mode-specific line
+is gentler than `full`, but the same AI still sees rules about fewer files,
+fewer abstractions, shorter diffs, and avoiding speculative work.
+
+## Mode Policy
+
+| Mode | Governed use |
+| --- | --- |
+| `off` | Recommended global default. Ponytail does not inject its active ruleset. |
+| `lite` | First mode to test in one isolated task or session. Complete the requested work, while surfacing a simpler option. |
+| `full` | Optional stress test after `lite`. Use only in an isolated task to see whether stronger minimalism harms scope or proof. |
+| `ultra` | Not part of the recommended PGS workflow. It is too aggressive for a default governed engineering lane. |
+
+Return to `off` after every comparison.
+
+## Comparison Protocol
+
+Use the same bounded, low-risk task in separate sessions or worktrees:
+
+```text
+baseline with off
+-> repeat with lite
+-> compare scope, proof, complexity, and clarity
+-> optionally repeat with full
+-> return global mode to off
+```
+
+Compare:
+
+- whether every requested requirement was delivered;
+- whether Superpowers brainstorming, planning, TDD, debugging, and verification
+  gates were preserved;
+- whether tests, security, accessibility, validation, and data-loss prevention
+  remained intact;
+- files, dependencies, abstractions, and lines changed;
+- whether the explanation and durable evidence stayed understandable;
+- token and time measurements only when the AI host exposes trustworthy data.
+
+A shorter answer or smaller diff is not automatically a better result.
+
+## Priority And Boundary
+
+Use this priority order:
+
+1. User instructions and project safety requirements.
+2. PGS routing, governance boundaries, and required evidence.
+3. Superpowers workflow gates.
+4. Ponytail complexity and cost advice.
+
+Ponytail may:
+
+- question speculative scope;
+- prefer the standard library or an already-installed dependency;
+- suggest fewer files, dependencies, and abstractions;
+- identify code or structure that can be removed safely.
+
+Ponytail may not:
+
+- remove an explicit requirement;
+- bypass PGS routing or document placement;
+- skip required brainstorming, plans, TDD, debugging, or verification;
+- weaken security, accessibility, trust-boundary validation, error handling, or
+  data-loss protection;
+- replace proof with "the code is shorter";
+- silently change the user's global Ponytail configuration.
+
+## Recommended Workflow
+
+```mermaid
+flowchart TD
+  A["Task arrives"] --> B["PGS selects the project lane"]
+  B --> C["Superpowers runs the required workflow"]
+  C --> D{"Would a simplicity review help?"}
+  D -- "no" --> E["Implement and verify normally"]
+  D -- "yes" --> F["Use Ponytail explicitly for this task"]
+  F --> G["Keep requirements and proof intact"]
+  G --> E
+```
+
+For normal engineering, Ponytail is a scoped adviser, not a second workflow
+engine and not a replacement for Superpowers.
+

package/assets/integrations/superpowers.md

@@ -2,6 +2,18 @@
 
 Superpowers is an external plugin/system. This repository does not vendor or rewrite it.
 
+## The Beginner Version
+
+Think of an AI project as a building site:
+
+- PGS is the traffic desk and inspection station.
+- Superpowers is the construction process.
+- Ponytail is an optional cost and complexity adviser.
+
+PGS chooses the lane. Superpowers makes sure the work follows the right
+engineering process. Ponytail may suggest a leaner implementation, but it
+cannot cancel the process or the final inspection.
+
 ## Boundary
 
 Superpowers owns engineering workflows such as:
@@ -20,6 +32,13 @@ Project Governance System owns:
 - current work index conventions
 - the governed location and boundary for externally sourced AI evidence rules
 
+Ponytail, when explicitly enabled for a task, may advise on:
+
+- speculative scope;
+- unnecessary dependencies;
+- avoidable files and abstractions;
+- simpler implementation choices.
+
 ## Rule
 
 Use Superpowers inside the selected project lane. Do not let Superpowers create a separate durable document tree unless the project explicitly adopts one.
@@ -33,6 +52,9 @@ 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 comes after those responsibilities are known. It may
+make the implementation leaner, but it must not remove explicit requirements or
+reduce how correctness is proven.
 
 ```mermaid
 flowchart TD
@@ -41,8 +63,11 @@ flowchart TD
   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
+  E --> G{"Would an explicit simplicity review help?"}
+  F --> H["Write durable outputs into doc-gov layers"]
+  G -- "yes" --> I["Use Ponytail without dropping workflow gates"]
+  G -- "no" --> H
+  I --> H
 ```
 
 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.
@@ -50,3 +75,6 @@ If Superpowers suggests a default location such as `docs/superpowers/**`, projec
 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.
+
+For Ponytail mode policy and the isolated comparison protocol, read
+`integrations/ponytail.md`.

package/assets/starter/.gemini/settings.json

@@ -0,0 +1,5 @@
+{
+  "context": {
+    "fileName": ["AGENTS.md"]
+  }
+}

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

@@ -5,7 +5,7 @@ on:
     paths:
       - "AGENTS.md"
       - "CLAUDE.md"
-      - "GEMINI.md"
+      - ".gemini/settings.json"
       - "README.md"
       - "docs/**"
       - "lefthook.yml"
@@ -18,7 +18,7 @@ on:
     paths:
       - "AGENTS.md"
       - "CLAUDE.md"
-      - "GEMINI.md"
+      - ".gemini/settings.json"
       - "README.md"
       - "docs/**"
       - "lefthook.yml"
@@ -34,6 +34,8 @@ jobs:
       - uses: actions/checkout@v4
 
       - uses: pnpm/action-setup@v4
+        with:
+          version: 10.26.0
 
       - uses: actions/setup-node@v4
         with:

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

@@ -79,5 +79,6 @@ 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.
+Host-specific adapters such as `CLAUDE.md` or `.gemini/settings.json` 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

@@ -74,5 +74,6 @@ 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.
+Host-specific adapters such as `CLAUDE.md` or `.gemini/settings.json` may adapt
+the route for a specific AI client, but they must not replace the project
+`AGENTS.md` route.

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

@@ -71,7 +71,7 @@ Extra governed roots are allowed only when a project explicitly opts in.
 
 Before changing docs, look for project-local guidance in this order:
 
-1. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or equivalent AI router.
+1. `AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, or equivalent AI router/config adapter.
 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.
@@ -100,7 +100,7 @@ works for governed docs:
 
 | Need | Usually belongs in |
 | --- | --- |
-| AI entry and startup routing | `AGENTS.md` plus host-specific forwarders |
+| AI entry and startup routing | `AGENTS.md` plus thin host-specific adapters such as `CLAUDE.md` and `.gemini/settings.json` |
 | Agents-routing rules | `docs/governance/agents-routing/` |
 | Doc-system rules, templates, and manifest | `docs/governance/` |
 | Project AI/development policy | `docs/policy/` |

package/assets/starter/lefthook.template.yml

@@ -6,10 +6,10 @@ pre-commit:
   parallel: false
   commands:
     01-doc-gov-router-check:
-      glob: "{AGENTS.md,CLAUDE.md,GEMINI.md,README.md,docs/**/*.{md,yml,yaml}}"
+      glob: "{AGENTS.md,CLAUDE.md,README.md,.gemini/settings.json,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}"
+      glob: "{docs/**/*.md,docs/governance/**/*.{md,yml,yaml},docs/policy/**/*.md,AGENTS.md,CLAUDE.md,.gemini/settings.json}"
       run: pnpm doc-gov check && pnpm doc-gov scan --check && pnpm doc-gov links && pnpm doc-gov audit
 
 commit-msg:

package/cli-guide.md

@@ -3,14 +3,21 @@
 `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.
+installation, compare reusable governance files, inspect local projects, and run
+package health checks.
 
 The validator remains `doc-gov`.
 
 ## Commands
 
+Public package-safe commands:
+
 ```bash
 pro-gov assets list
+pro-gov assets discover --target .
+pro-gov assets recommend --target .
+pro-gov lens inspect --target .
+pro-gov lens report --target . --out .pro-gov/lens-report.md
 pro-gov init --profile engineering-runtime --dry-run
 pro-gov init --profile doc-only --dry-run
 pro-gov sync --check
@@ -20,11 +27,28 @@ 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.
 
+Full upstream-checkout commands:
+
+```bash
+pro-gov assets list --json
+pro-gov assets plan --bundle base-governance --target . --out .pro-gov/asset-plan.json
+pro-gov assets apply --plan .pro-gov/asset-plan.json
+pro-gov assets check --target .
+pro-gov assets npx add <source> --plan
+pro-gov assets npx update --plan
+```
+
+These commands need the private `agent-assets/` registry in a full Project
+Governance System checkout. The public npm package excludes private and
+third-party skill bodies by design.
+
 ## Typical Adoption Flow
 
 ```bash
 pnpm add -D @pieai/pro-gov @pieai/doc-gov
 pnpm pro-gov assets list
+pnpm pro-gov assets discover --target .
+pnpm pro-gov assets recommend --target .
 pnpm pro-gov init --profile engineering-runtime --dry-run
 pnpm pro-gov sync --check
 pnpm doc-gov migrate --profile engineering-runtime --check