@pieai/pro-gov 0.3.17 → 0.4.1

package/README.md

@@ -53,6 +53,7 @@ pro-gov init --profile engineering-runtime --dry-run
 pro-gov init --profile engineering-runtime --apply
 pro-gov init --profile doc-only --dry-run
 pro-gov sync --check --profile engineering-runtime
+pro-gov sync --apply-host-hooks --profile engineering-runtime
 pro-gov doctor
 ```
 
@@ -72,6 +73,7 @@ What these commands do:
 | `init --dry-run` | Shows starter/profile files that would be needed. | No |
 | `init --apply` | Installs one profile into a fresh target; refuses the whole operation if any target file exists. Optional CI and Lefthook references are not installed. | Yes |
 | `sync --check` | Strictly compares shared core files and checks only the presence of project-local seed files. | No |
+| `sync --apply-host-hooks` | Merges current PGS Compound Gate entries into engineering-runtime host configs while preserving consumer-owned keys and hooks. | Only the three host config files |
 | `doctor` | Checks required packaged assets and whether `doc-gov` is available. | No |
 
 ## Full Checkout Commands
@@ -154,8 +156,13 @@ work, run `pro-gov learn recall --query "<task summary>"` and read relevant
 `docs/solutions/**` or `CONCEPTS.md` hits before changing files.
 
 Engineering-runtime starters include cross-host Stop hooks for Codex,
-Claude Code, and Antigravity. Those hooks call `pro-gov host-hook` and require
-the final report to include either:
+Claude Code, and Antigravity. Those hooks call `pro-gov host-hook`. The starter
+default is `--compound-gate-mode off`: wiring is present, but the hook does not
+interrupt the main session. Use `--compound-gate-mode lite` for a short
+exit-door reminder, or `--compound-gate-mode strict` for the older blocking
+gate.
+
+When enabled, the hook expects the final report to include either:
 
 ```text
 Compound Gate: ran ce-compound -> <path>

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-02
+last_reviewed: 2026-07-11
 domain: adoption
 tags:
   - adoption
@@ -79,7 +79,8 @@ Current package-based method:
   merge local truth deliberately instead of asking PGS to overwrite it
 - run `pro-gov sync --check --profile <profile>` to compare shared core files;
   project-local router, policy, documentation map, and current-work files are
-  checked for presence rather than byte equality
+  checked for presence rather than byte equality; host configs are compared by
+  PGS-owned entries rather than whole-file equality
 - run `pro-gov assets discover --target <path>` and
   `pro-gov assets recommend --target <path>` to collect local project signals
   and suggested agent-asset bundles without changing the project
@@ -98,6 +99,9 @@ Current package-based method:
   - `.codex/hooks.json`
   - `.claude/settings.json`
   - `.agents/hooks.json`
+- prefer `pro-gov sync --apply-host-hooks --profile engineering-runtime` for
+  that merge; it preserves consumer `PreToolUse`, other events, other top-level
+  keys, and non-PGS Stop/SubagentStop entries
 - run `doc-gov doctor` after wiring guardrails to verify they are actually
   connected
 - run `pro-gov doctor --strict-hooks` after wiring host hooks to prove the
@@ -112,6 +116,7 @@ pnpm pro-gov init --profile engineering-runtime --dry-run
 pnpm pro-gov init --profile engineering-runtime --apply
 pnpm doc-gov scan
 pnpm pro-gov sync --check --profile engineering-runtime
+pnpm pro-gov sync --apply-host-hooks --profile engineering-runtime
 ```
 
 Use `--apply` only for a fresh target. Existing projects normally already own
@@ -225,9 +230,11 @@ so prior lessons can shape the work without making Compound Engineering the
 default execution workflow.
 
 The host-hook gate is deliberately small. It does not make Compound Engineering
-the main workflow. It only blocks a final completion report that looks like
-finished engineering work but does not say whether the Compound Gate ran or was
-skipped:
+the main workflow. Starter hooks default to `--compound-gate-mode off`, so they
+prove the wiring without interrupting the main session. Switch a target to
+`--compound-gate-mode lite` for a short reminder, or `--compound-gate-mode
+strict` when a project intentionally wants the old blocking exit gate. In
+`lite` or `strict`, the hook checks whether a completion report says one of:
 
 ```text
 Compound Gate: ran ce-compound -> <path>
@@ -310,8 +317,9 @@ engineering runtime profile.
 
 `pro-gov doctor --strict-hooks` is a wiring check, not a live host simulation.
 It proves the project has hook files that call `pro-gov host-hook`; PGS package
-tests prove the expected Stop/SubagentStop behavior for the supported host
-schemas. After installing or changing hooks, validate from a fresh AI session.
+tests prove the expected Stop/SubagentStop behavior for `off`, `lite`, and
+`strict` modes across the supported host schemas. After installing or changing
+hooks, validate from a fresh AI session.
 For Antigravity, a real invocation writes diagnostics under
 `.git/pro-gov-hook-debug/` because the starter hook command sets
 `PGS_HOST_HOOK_DEBUG=1`. Absence of a diagnostic file after a fresh

package/assets/docs/reference/adoption/agent-workflow-methodology-comparison.md

@@ -0,0 +1,331 @@
+---
+id: REF-AGENT-WORKFLOW-METHODOLOGY-COMPARISON
+title: Agent Workflow Methodology Comparison
+type: reference
+status: active
+canonical: true
+owner: project
+created: 2026-07-06
+last_reviewed: 2026-07-06
+domain: adoption
+tags:
+  - agent-workflows
+  - superpowers
+  - compound-engineering
+  - mattpocock-skills
+  - wayfinder
+pinned: false
+related:
+  - REF-PUBLIC-RELEASE-CHECKLIST
+  - REF-DOWNSTREAM-PROJECT-REGISTRY
+---
+
+# Agent Workflow Methodology Comparison
+
+本文比较 4 套 AI agent 工作方法，观察时间点是 2026-07-06：
+
+1. **Superpowers**
+2. **Compound Engineering**
+3. **Matt Pocock skills 主流程**
+4. **Matt Pocock Wayfinder**
+
+小学生版本：这 4 套东西都不是“更聪明的魔法咒语”。它们更像 4 个不同的帮手。
+
+- Superpowers 像工地施工队长。
+- Compound Engineering 像厨师的复盘菜谱本。
+- Matt 主流程像采访员、产品经理、拆票员三个人排队帮你。
+- Wayfinder 像走进大雾森林前的画地图的人。
+
+## 版本和证据
+
+这是一个时间点快照，不是永久真理。Wayfinder 现在变化尤其快。
+
+| 系统 | 本次观察到的版本或来源 | 证据 |
+| --- | --- | --- |
+| PGS | 本地 package 版本 `0.4.0` | `package.json`，2026-07-06 检查 |
+| Superpowers | 本机 Codex 插件 `6.1.1` | 本地 `.codex/plugins/cache/superpowers-dev/superpowers/6.1.1`；上游项目：[obra/superpowers](https://github.com/obra/superpowers) |
+| Compound Engineering | 本机插件 `3.18.0` | 本地 `.codex/plugins/cache/compound-engineering-plugin/compound-engineering/3.18.0`；上游项目：[EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) |
+| Matt Pocock skills | PGS 本地 lock 记录 GitHub 来源和 hash，不记录 semver | 上游项目：[mattpocock/skills](https://github.com/mattpocock/skills)；Skill Vault 在 2026-07-05 显示 `1.0.31`、commit `66f92b6` |
+| Wayfinder | 属于 `mattpocock/skills`，2026-07-06 仍在 `skills/in-progress/wayfinder` | 上游文件：[Wayfinder SKILL.md](https://github.com/mattpocock/skills/blob/main/skills/in-progress/wayfinder/SKILL.md)；GitHub Actions 显示 Wayfinder 已连续多次发布到 Release #46 |
+
+重要提醒：PGS 本地 `wayfinder` 已在 2026-07-07 通过 `pro-gov assets npx update --skill wayfinder --plan` 更新到包含 **"Plan, don't do"** 和 destination 说明的新版。Wayfinder 仍处在高流动期，后续如果继续升级，需要重新复查这篇文档。
+
+## 一句话结论
+
+PGS 最稳的组合是：
+
+- **Superpowers** 继续当默认工程流程负责人。
+- **Compound Engineering** 继续当默认复利记录和经验沉淀工具。
+- **Matt 主流程** 用在“想法还模糊，需要问清楚、写 PRD、拆 issue”的时候。
+- **Wayfinder** 只用在“大到一个 session 装不下、前路还在雾里”的任务上。
+
+Wayfinder 暂时不应该自动启动。它很有潜力，但现在更像侦察兵，不像自动驾驶车。要用它，最好满足 4 个条件：用户明确叫它、目的地说清楚、issue tracker 支持它的地图/子票规则、关键节点有人类确认。
+
+## 两个贯穿例子
+
+为了更好懂，下面一直用两个例子：
+
+- **小安要开发一个 App。** 可能只是一个习惯打卡小工具，也可能是一个很大的 EMS 管理系统。
+- **小宁要写一本小说。** 可能只是一本短篇推理，也可能是一个多卷本奇幻系列。
+
+## Superpowers：工地施工队长
+
+Superpowers 像工地施工队长。施工队长不会一上来就让人搬砖。他会先问：要建什么？图纸在哪里？怎么验收？有没有安全检查？
+
+小安做 App 时，Superpowers 会帮：
+
+- 问清楚这个功能到底要解决什么问题。
+- 写计划。
+- 尽量用 TDD，先写测试再实现。
+- 完工前检查测试、review、分支状态。
+
+小宁写小说时，Superpowers 也能帮一点，比如安排写作计划。但它脑子里更多是“软件工程施工”。如果小宁只是想探索人物和情绪，Superpowers 可能显得有点硬。
+
+最适合：工程实现、调 bug、测试验证、分支收尾。
+
+PGS 判断：Superpowers 继续做默认工程流程负责人。PGS 已在 [integrations/superpowers.md](../../../integrations/superpowers.md) 里这样定位。
+
+## Compound Engineering：厨师的复盘菜谱本
+
+Compound Engineering 像厨师的菜谱本。厨师这次做菜发现“火候应该小一点”“这个酱汁可以提前一天做”，就记下来。下次做同类菜，就不用重新踩坑。
+
+小安做 App 时，CE 会帮：
+
+- 修完一个难部署 bug 后，把可复用经验记下来。
+- 下次遇到类似问题，AI 可以先读以前的经验。
+- CE 也有计划、review、debug 等完整流程，但 PGS 默认不让它接管整条开发线。
+
+小宁写小说时，CE 可以记录写作经验，比如“多卷本小说需要先做时间线表”。但如果只是自由创作，完整 CE 流程可能也会显得太工程化。
+
+最适合：把一次工作变成下一次工作的优势。
+
+PGS 判断：默认只用 **Compound Gate** 做经验沉淀。完整 CE 流程必须用户明确要求。见 [integrations/compound-engineering.md](../../../integrations/compound-engineering.md)。
+
+## Matt 主流程：采访员 + 产品经理 + 拆票员
+
+Matt 主流程像 3 个人接力：
+
+1. 采访员先不停追问，把模糊想法问清楚。
+2. 产品经理把答案整理成 PRD。
+3. 拆票员把 PRD 切成一个个能独立完成的小 issue。
+
+小安做 App 时：
+
+- `/grill-with-docs` 像采访员，边问边更新项目上下文。
+- `/to-prd` 像产品经理，把讨论整理成 PRD。
+- `/to-issues` 像拆票员，把 PRD 拆成竖切 issue。
+- `/implement` 像工程执行员，拿一个 issue 做 TDD、review、commit。
+
+小宁写小说时：
+
+- `/grill-me` 可以问清楚题材、主角、冲突、结尾。
+- `/to-prd` 可以变成故事圣经或写作 brief。
+- `/to-issues` 可以变成章节卡、设定任务、资料研究任务。
+- 但它的形状还是偏“产品开发”，所以对纯文学创作可能有点像用项目管理工具写诗。
+
+最适合：把模糊需求变成可保存、可拆分、可执行的东西。
+
+PGS 判断：Matt skills 可以完整安装、原样使用，但它产生的原生产物不应该被 PGS 乱改。PGS 不应该为了 Doc Gov 给它的产物硬加 frontmatter。正确做法是：Matt 产物保留原味；只有当人明确决定“这个东西要升级为 PGS 治理真相”时，才另建或更新 PGS 文档。见 [integrations/mattpocock-skills.md](../../../integrations/mattpocock-skills.md)。
+
+## Wayfinder：大雾森林里的画地图的人
+
+Wayfinder 像你站在一片大雾森林前。你知道森林另一边可能有城堡，但不知道路在哪里，也不知道哪些桥断了。这时最聪明的事不是冲进去盖房子，而是先画地图。
+
+小安做一个小习惯 App：
+
+- 不建议用 Wayfinder。太重了。Matt 主流程或 Superpowers 就够。
+
+小安做一个大型 EMS 系统：
+
+- Wayfinder 可以创建一个 map issue。
+- 然后创建子票，比如“决定权限模型”“研究 EMS 审计要求”“原型验证派单时间线 UI”“追问升级规则”。
+- 每个 session 只解决一个票，把答案记回地图。
+
+小宁写短篇推理：
+
+- 一般不需要 Wayfinder。
+
+小宁写多卷奇幻系列：
+
+- Wayfinder 很可能有用。它可以画出“魔法规则是否影响经济”“第二卷由谁推动主线”“结局前必须先决定哪些世界观问题”等地图。
+- 每张票解决一个大问题。
+
+最适合：很大、很模糊、一个 session 装不下、下一步不清楚的工作。
+
+PGS 判断：Wayfinder 只能显式调用。用户说 `/wayfinder`，或者清楚表达“我要为一个大而不清楚的任务画地图”，再用。
+
+## 总对比表
+
+| 维度 | Superpowers | Compound Engineering | Matt 主流程 | Wayfinder |
+| --- | --- | --- | --- | --- |
+| 小学生比喻 | 施工队长 | 复盘菜谱本 | 采访员 + 产品经理 + 拆票员 | 大雾地图师 |
+| 主要工作 | 把代码小心做出来 | 让下一次工作更容易 | 把想法变成 PRD / issue / code | 在未知里找到路线 |
+| 最适合规模 | 小到大的工程任务 | 重复出现的工程经验 | 中等复杂产品/功能 | 超大、模糊、多 session |
+| 主要产物 | 计划、测试、review、分支收尾 | `docs/solutions/**` 等经验文档 | `CONTEXT.md`、ADR、PRD、issue | 一个 map issue + 多个 child ticket |
+| 如何启动 | skill routing / session startup | 显式 CE skill 或 PGS Compound Gate | 通常显式 slash command | 显式 `/wayfinder` |
+| 人类角色 | 批准计划和关键选择 | 判断什么值得沉淀 | 回答采访、批准 issue 颗粒度 | 批准目的地、地图、下一步 |
+| 自主程度 | 中等 | PGS 默认低；完整 CE 时较高 | 中等 | 如果不设边界会偏高 |
+| 停止条件 | 测试、review、分支完成 | 学习记录完成或跳过 | PRD / issue / implementation 完成 | 路线清楚，没有更多必须先决定的问题 |
+| 最大优点 | 工程纪律强 | 真正复利 | 需求澄清和竖切很强 | 不假装大雾已经清楚 |
+| 最大风险 | 小任务可能仪式太重 | 用多了会变流程负担 | 可能偏重、偏线性 | 可能造太多票，或选错下一步 |
+| PGS 默认态度 | 默认工程负责人 | 默认复利尾巴 | 可选工具箱 | 显式侦察兵 |
+
+## 外部证据和评论
+
+### Wayfinder
+
+一手来源：Wayfinder 自己说，它处理的是“一个 session 太大、路还在雾里”的工作。它会在 issue tracker 上建共享地图，然后一个 ticket 一个 ticket 解决，直到目的地路线清楚。最新版上游还明确说默认是 **Plan, don't do**：默认产出决策，不产出最终交付物，除非 map Notes 明确允许执行。来源：[Wayfinder SKILL.md](https://github.com/mattpocock/skills/blob/main/skills/in-progress/wayfinder/SKILL.md)。
+
+GitHub Actions 显示 Wayfinder 近期更新非常密集，包括 destination/purpose、deferred section、native blocking、assignment claiming、plan big work 等。来源：[mattpocock/skills Actions](https://github.com/mattpocock/skills/actions)。
+
+GitHub issue #450 报告了一个真实风险：Wayfinder 在 work-through-map 时没有充分追问资源冲突，导致一个部署任务影响了另一个已存在服务。来源：[Issue #450](https://github.com/mattpocock/skills/issues/450)。
+
+用户提供的 2026-07-06 X 截图也显示两面性：有人觉得 Wayfinder 很震撼，但也观察到它可能继续执行错误的下一张票；Matt 回复说这不应该发生，听起来像 bug。这个证据说明：它很有潜力，但还不能当稳定自动驾驶。
+
+PGS 解释：Wayfinder 是侦察兵，不是总司令。
+
+### Matt 主流程
+
+一手来源：Matt README 说这些 skills 是小而可组合、可改造、用于真实工程，不是 vibe coding。它把 `/grill-with-docs`、`CONTEXT.md`、`/to-prd`、`/to-issues`、`/tdd`、`/code-review` 组合成一个流程。来源：[mattpocock/skills](https://github.com/mattpocock/skills)。
+
+公开 `to-issues` 指南说，它会把 PRD 拆成可独立抓取的竖切 issue，并让用户批准颗粒度和依赖。来源：[AI Hero to-issues guide](https://www.aihero.dev/skills-to-issues)。
+
+外部评论是“有用但可能重”。有 Reddit 用户说 Matt 风格的 GitHub issues / TDD / audit loop 质量好，但也担心每个小 issue 都耗时较多。来源：[Reddit discussion](https://www.reddit.com/r/PiCodingAgent/comments/1t2tm5c/am_i_overengineering_matt_pococks_ai_coding/)。
+
+另一个公开写法认为，这套流程适合触达多个模块的 feature/refactor，但不能替代人的判断。来源：[Danny Shmueli writeup](https://dannyshmueli.com/2026/04/29/Matt-Pocock-Skills-Hermes-Subagents-Feature-Work/)。
+
+PGS 解释：Matt 主流程适合“把话问明白、把需求切小”。但不要为了治理洁癖去改它原生输出。
+
+### Superpowers
+
+一手来源：Superpowers 自称是基于 composable skills 和启动指令的软件开发方法论，覆盖 brainstorming、worktree、planning、subagent execution、TDD、debugging、review、verification。来源：[obra/superpowers](https://github.com/obra/superpowers)。
+
+Superpowers 6 发布说明称，它在作者测试中更快、更省 token，并支持或改进了多个 coding agent，包括 Codex。来源：[Superpowers 6 announcement](https://blog.fsck.com/2026/06/15/Superpowers-6/)。
+
+社区评论也分两面。有些用户喜欢它前半段：澄清假设、写 spec、识别风险、做计划。也有人认为它对小任务会太重，甚至更耗用量。来源：[Reddit ClaudeCode thread](https://www.reddit.com/r/ClaudeCode/comments/1uk7dzk/fable_5_and_superpowers_plugin/) 和 [Reddit Codex thread](https://www.reddit.com/r/codex/comments/1sp7di6/have_any_of_you_guys_been_using_the_superpower/)。
+
+PGS 解释：Superpowers 仍然是最适合当默认工程负责人的，因为它端到端纪律强。但 PGS 需要保留轻量路径，小事不要被拖进大仪式。
+
+### Compound Engineering
+
+一手来源：CE 插件强调“每一次工程工作都应该让下一次更容易”，提供 `/ce-brainstorm`、`/ce-plan`、`/ce-code-review`、`/ce-compound` 等技能。来源：[EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin)。
+
+Every 的 Compound Engineering 指南强调 safety nets、agent-native environment、parallel work、plan as artifact。来源：[Compound Engineering guide](https://every.to/guides/compound-engineering)。
+
+Will Larson 的评论认为它是一个便宜、有用、值得试的实验，同时也提醒有些实践未来可能会被 agent harness 吸收。来源：[Lethain review](https://lethain.com/everyinc-compound-engineering/)。
+
+PGS 解释：CE 最珍贵的是“把经验留下来”。但如果 CE 和 Superpowers 同时想当整个流程的老板，AI 就像同时听两个教练喊口令，会乱。PGS 因此让 Superpowers 默认负责施工，让 CE 默认负责复盘。
+
+## 用 Loopy 外骨骼检查
+
+`loopy` 技能说，一个好 loop 应该有 6 步：观察、选择、行动、验证、记录、重复或停止。它还要求有明确终点，比如成功、阻塞、需要批准、用尽、停滞。
+
+把 4 套方法放进去看：
+
+| 系统 | 观察 | 选择 | 行动 | 验证 | 记录 | 停止 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Superpowers | 强：会问、会读代码 | 强：会写计划 | 强：会实现 | 强：测试/review | 中：计划和 review 记录 | 强，但要真的跑验证 |
+| CE | 中：读任务上下文 | 中：CE plan/review | 中：可执行但 PGS 默认不用 | 中：review/check | 强：复利文档 | capture 很清楚，完整流程较重 |
+| Matt 主流程 | 强：grilling/docs | 强：PRD/issues | 强：implement | 强：TDD/code review | 强：context/ADR/PRD/issues | 中：依赖 smart context hygiene |
+| Wayfinder | 强：map/fog/tickets | 如果 frontier 对，就强 | 默认低：应该 plan，不应该 do | 中：依赖 ticket resolution 质量 | 强：map 和 resolution comments | 需要特别小心：一 session 一票 |
+
+Loopy 角度的 PGS 结论：Wayfinder 最大问题不是“不聪明”，而是“权限和刹车”。地图必须写清楚什么时候问人、什么时候停、什么时候绝对不执行。
+
+## 五轮真实评估迭代
+
+### 第 1 轮：先看 PGS 边界
+
+问题：PGS 能不能引入 Wayfinder，而不让 4 套方法互相打架？
+
+判断：可以，但每套方法要分工清楚。
+
+- Superpowers 负责默认工程施工。
+- CE 负责默认经验复利。
+- Matt 主流程负责需求澄清、PRD、issue 拆分。
+- Wayfinder 负责大雾任务的地图。
+
+我否掉的方案：让 Wayfinder 自动替代 Matt 旧流程。这太激进，像把整个施工队换成一张地图。
+
+### 第 2 轮：看 Wayfinder 上游原意
+
+问题：Wayfinder 自己到底说它是什么？
+
+判断：它不是更强的 `/implement`。它更像“路线发现”和“决策地图”。上游最新版还明确写了默认 plan，不默认 do。
+
+这改变了推荐：Wayfinder 不应该直接拿来替代实现流程。
+
+### 第 3 轮：看外部评论是不是只有夸
+
+问题：大家是在无脑夸，还是有真实问题？
+
+判断：两者都有。
+
+- 夸：有人觉得它能做以前不敢交给 AI 的大规划。
+- 风险：GitHub issue #450 和用户截图都说明，它可能在下一步选择或冲突追问上出错。
+
+这让 PGS 不应该过早自动化采用。
+
+### 第 4 轮：用 Loopy 查循环质量
+
+问题：4 套方法哪个循环最完整？
+
+判断：
+
+- Superpowers 和 Matt 主流程的“构建循环”更成熟。
+- CE 的“记录/复利循环”最强。
+- Wayfinder 的“观察/记录”很强，但“谁决定下一步”和“什么时候停止”需要额外护栏。
+
+结论：Wayfinder 必须一 session 一票，chart map 后要人工确认，默认只做决策，不做执行。
+
+### 第 5 轮：看 PGS 最小采用方式
+
+问题：最小、稳妥、有价值的采用方式是什么？
+
+判断：先写边界文档，不急着改运行规则。
+
+如果后续要真正 operationalize Wayfinder，需要：
+
+1. 保持 Matt skill pack 更新到包含最新版 Wayfinder 文案的版本。
+2. 保持 PGS 中央 `docs/agents/issue-tracker.md` 有 Wayfinding operations。
+3. 保持 Matt 原生产物不被 PGS 修改。
+4. Doc Gov 继续忽略 Matt 原生产物，除非人工提升为治理文档。
+5. 本地主控 AI 保留最终 merge / commit / push 权限。
+
+## PGS 推荐路由
+
+| 场景 | 推荐用什么 |
+| --- | --- |
+| 小而明确的代码修复 | Superpowers，必要时直接 TDD |
+| 难 bug | Superpowers systematic debugging；有复用经验再 CE capture |
+| 现有 repo 里的模糊功能想法 | Matt `/grill-with-docs`，然后可能 `/to-prd`、`/to-issues` |
+| 已经有 PRD，需要拆票 | Matt `/to-issues` |
+| 单个 issue 要实现 | Matt `/implement` 或 Superpowers 实现流程，看用户怎么叫 |
+| 巨大、模糊、多 session 的任务 | Wayfinder |
+| 工作结束后有可复用经验 | CE `/ce-compound` 或 PGS fallback capture |
+| 小说、课程、非代码创作 | Matt grilling 或 Wayfinder；不要默认套 Superpowers 工程仪式 |
+
+## 采用 Wayfinder 的护栏
+
+如果 PGS 以后真正启用 Wayfinder，请保留这些护栏：
+
+1. **只能显式启动。** 用户说 `/wayfinder`，或清楚要求“给大任务画地图”。
+2. **必须说清目的地。** 没有目的地的地图，只是一堆便利贴。
+3. **一个 session 只解决一张票。** 这样不会跑飞，也保护上下文。
+4. **默认只计划，不执行。** 除非 map Notes 明确写这个 effort 包含执行。
+5. **第一次 chart map 后要人工确认。** 不要一口气造几十张票然后自动往下冲。
+6. **Matt 原生产物保持原味。** 不要为了 PGS Doc Gov 给 map tickets、PRD、scratch、context docs 硬加 frontmatter。
+7. **要升级为 PGS 真相时，另行提升。** 也就是新建或更新受治理的 PGS 文档，而不是改原生产物。
+8. **issue tracker 必须保留规则。** PGS 中央的 `docs/agents/issue-tracker.md` 必须包含 Wayfinding operations；正式跑之前先检查它还在。
+
+## 最终建议
+
+PGS 应该支持 Wayfinder，但不要把它封王。
+
+最好的搭配是：
+
+- **Superpowers**：平时工程施工。
+- **Matt 主流程**：把模糊想法问清楚、写成 PRD、拆成 issue。
+- **Wayfinder**：遇到巨大迷雾任务时先画地图。
+- **CE**：工作结束后把可复用经验存下来。
+
+用小孩能懂的话说：Superpowers 帮你盖树屋，Matt 主流程问清楚你想要什么树屋，Wayfinder 在你连哪棵树能爬都不知道时先画森林地图，CE 把“梯子怎么做更结实”记进小本本，下次少摔一次。

package/assets/integrations/directed-development.md

@@ -4,6 +4,11 @@ Directed Development is an optional workflow for mixed, cross-domain, interdepen
 
 It is not the default for every task.
 
+It is not a Superpowers startup adapter and not a second engineering plugin. It
+is a small PGS routing rule for cases where product work must be split into
+ordered dependency-aware Blocks before the selected lane uses its normal
+workflow. Superpowers still owns the engineering process inside that lane.
+
 ## Boundary
 
 Directed Development may define:
@@ -16,6 +21,7 @@ Directed Development may define:
 Directed Development must not define:
 
 - artifact locations
+- Superpowers skill invocation rules
 - project document paths
 - project lane names
 - runtime truth
@@ -25,6 +31,10 @@ Those remain owned by the project and doc-gov.
 Agents routing decides whether this workflow applies. Directed Development does
 not replace the project router.
 
+BDD-style scenarios are allowed only as acceptance language for a DD Block. They
+do not turn Directed Development into a default BDD ceremony and do not replace
+Superpowers TDD, debugging, or verification workflows.
+
 ## Trigger
 
 Use Directed Development only when all are true:

package/assets/integrations/mattpocock-skills.md

@@ -0,0 +1,143 @@
+# mattpocock/skills Integration
+
+mattpocock/skills is an external npx skill pack. This repository may install
+the pack unchanged, but it does not vendor, rewrite, or fork the skill bodies.
+
+## The Beginner Version
+
+Think of the project as a workshop:
+
+- PGS is the traffic desk and filing cabinet.
+- Superpowers is the default construction process for engineering work.
+- mattpocock/skills is a set of sharp workshop tools for grilling ideas,
+  modeling domain language, turning decisions into PRDs/issues, and running
+  specific implementation flows.
+- Compound Engineering is the verified-learning notebook written after the work.
+
+Installing a box of tools does not mean every tool runs by itself. PGS decides
+the lane first. Superpowers remains the default engineering workflow. Matt
+skills may add useful artifacts and focused flows when their trigger fits.
+
+## Default Rule
+
+For PGS-governed engineering/runtime projects, mattpocock/skills is optional
+capability inside the selected lane. It is not the default workflow owner.
+
+Use this order:
+
+1. PGS routes the task and selects the project lane.
+2. For non-trivial engineering work, run Learning Recall.
+3. Superpowers owns the normal engineering workflow when that lane needs one.
+4. Matt skills may run when the user explicitly invokes a Matt flow or when an
+   active Matt flow calls one of its helper skills.
+5. The Compound Gate still runs before final reporting.
+
+Do not make routine work choose between Superpowers and Matt. The useful split
+is simpler:
+
+- Superpowers owns default engineering discipline.
+- Matt owns demand shaping, domain modeling, PRD/issues generation, triage, and
+  explicitly requested Matt implementation flows.
+- CE owns post-work reusable learning.
+
+## Trigger Boundary
+
+User-invoked Matt skills, such as `/grill-with-docs`, `/to-prd`,
+`/to-issues`, `/implement`, `/triage`, and `/ask-matt`, require an explicit
+user request or an already active Matt flow that named them.
+
+Model-invoked Matt helper skills, such as `domain-modeling`, `tdd`,
+`code-review`, `research`, and `prototype`, may run only when they support the
+current selected lane and do not replace the current workflow owner.
+
+If a Matt helper and a Superpowers skill both fit, keep the current workflow
+owner unless the user explicitly switches. For example:
+
+- normal feature implementation -> Superpowers remains the default;
+- user says `/implement issue 123` -> Matt `/implement` owns that flow;
+- user says "grill this idea and make docs" -> Matt `/grill-with-docs` owns
+  that shaping flow;
+- user says "use CE full workflow" -> CE owns the explicitly requested flow.
+
+## PGS Central Setup
+
+The PGS central repository uses these Matt setup choices:
+
+| Setup item | PGS central value |
+| --- | --- |
+| Issue tracker | GitHub Issues for `PieAIStudio/ProjectGovernanceSystem` |
+| External PRs as request surface | No by default |
+| Triage labels | Default Matt labels: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix` |
+| Domain docs layout | Single-context: root `CONTEXT.md` and `docs/adr/**` when Matt creates them |
+
+The setup files live under `docs/agents/**`. They are Matt-owned external
+configuration files, not PGS canonical product truth.
+
+## Matt-Owned Artifacts
+
+The following outputs are Matt-owned external artifacts:
+
+| Path or surface | Owner | Rule |
+| --- | --- | --- |
+| `CONTEXT.md` | Matt | Domain glossary/context. Helpful input, not a replacement for `docs/canon/**`. |
+| `CONTEXT-MAP.md` | Matt | Multi-context map when a project opts into that layout. |
+| `docs/agents/**` | Matt | Per-repo Matt setup: issue tracker, triage labels, domain docs. |
+| `docs/adr/**` | Matt | Matt-generated ADRs. Promote manually to `docs/decisions/**` if they become PGS-governed decisions. |
+| `.scratch/**` | Matt | Local issue tracker or temporary work surface. Keep project-specific. |
+| GitHub/GitLab issues | Matt/project | PRDs, issue breakdowns, triage state. They are work-tracking artifacts, not doc-gov records by themselves. |
+
+Doc Gov must ignore `docs/agents/**` and `docs/adr/**` as external artifacts.
+When a Matt artifact becomes durable PGS truth, promote it into the normal
+governed layer:
+
+- decisions -> `docs/decisions/**`
+- specs -> `docs/specs/**`
+- plans -> `docs/plans/**`
+- canon -> `docs/canon/**`
+- references -> `docs/reference/**`
+
+Do not try to make one file satisfy both Matt's native artifact contract and a
+PGS governed document contract.
+
+## Downstream Install Rule
+
+Install or update Matt skills in downstream repositories through the PGS asset
+workflow. Do not run `npx skills add mattpocock/skills` inside every downstream
+project as an unmanaged one-off.
+
+The central intake flow is:
+
+```bash
+pro-gov assets npx add mattpocock/skills --plan --root agent-assets/skills/npx-skills
+```
+
+Review the plan, then install into the PGS central npx skill root. Downstream
+projects receive managed symlinks through the private PGS asset bundle
+`mattpocock-skills` and project-local Matt setup files according to their
+selected profile and host support.
+
+## Verification
+
+Central verification:
+
+```bash
+node packages/doc-gov/dist/cli.js router-check
+node packages/doc-gov/dist/cli.js check
+node packages/doc-gov/dist/cli.js scan --check
+git diff --check
+```
+
+Matt install verification:
+
+```bash
+test -f agent-assets/skills/npx-skills/skills-lock.json
+find agent-assets/skills/npx-skills/.agents/skills -maxdepth 2 -name SKILL.md
+```
+
+Downstream verification must prove:
+
+- the target's project router points to its selected profile;
+- Matt skills are linked from the managed PGS asset source;
+- `docs/agents/**` exists when Matt engineering skills are enabled;
+- Doc Gov ignores Matt-owned external artifacts;
+- Superpowers, Matt, and CE each keep their documented ownership.

package/assets/integrations/superpowers.md

@@ -29,6 +29,13 @@ Superpowers owns engineering workflows such as:
 - verification before completion
 - worktree usage
 
+Superpowers 6.x for Codex is skill-routed, not hook-driven. The plugin manifest
+does not need a SessionStart hook for PGS to make use of it. The startup
+behavior comes from the `using-superpowers` skill description, which tells the
+host to check relevant skills at the start of a conversation and before acting.
+Do not add a PGS hook just to force Superpowers startup unless a future
+Superpowers release explicitly requires one.
+
 Project Governance System owns:
 
 - documentation lifecycle

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

@@ -11,6 +11,7 @@ required:
 optional:
   compound_engineering: integrations/compound-engineering.md
   directed_development: integrations/directed-development.md
+  mattpocock_skills: integrations/mattpocock-skills.md
   superpowers: integrations/superpowers.md
 project_local_required:
   - docs/policy/best-practice-for-this-project.md

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

@@ -12,6 +12,7 @@ Use for code-heavy projects: apps, games, runtimes, services, browser products,
 - `integrations/superpowers.md`
 - `integrations/compound-engineering.md`
 - `integrations/directed-development.md`
+- `integrations/mattpocock-skills.md`
 - starter `docs/governance/` and `docs/policy/` templates
 
 ## Requires Project-Local Rules
@@ -31,6 +32,7 @@ Each project must define:
 - game/app-specific lane wording
 - Superpowers plugin body
 - Compound Engineering plugin body
+- mattpocock/skills body
 
 ## Automation Boundary
 
@@ -42,9 +44,10 @@ content under the target project's ownership.
 
 Engineering-runtime starters also include Codex, Claude Code, and Antigravity
 Stop hooks that call `pro-gov host-hook`. Use `pro-gov doctor --strict-hooks`
-after sync to confirm the exit gate is wired. The hook enforces the Compound
-Gate final-report marker; it does not replace verification, tests, or
-`ce-compound` itself.
+after sync to confirm the host configs are wired. The starter default is
+`--compound-gate-mode off`, so the hook does not interrupt the main session
+unless the project explicitly switches to `lite` or `strict`. Even when enabled,
+the hook does not replace verification, tests, or `ce-compound` itself.
 
 For non-trivial engineering work, run `pro-gov learn recall --query "<task
 summary>"` before changing files so existing `docs/solutions/**` and

package/assets/starter/.agents/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then PGS_HOST_HOOK_DEBUG=1 ./node_modules/.bin/pro-gov host-hook --host antigravity --event Stop; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; PGS_HOST_HOOK_DEBUG=1 pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host antigravity --event Stop; else PGS_HOST_HOOK_DEBUG=1 npx --no-install @pieai/pro-gov host-hook --host antigravity --event Stop; fi",
+            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then PGS_HOST_HOOK_DEBUG=1 ./node_modules/.bin/pro-gov host-hook --host antigravity --event Stop --compound-gate-mode off; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; PGS_HOST_HOOK_DEBUG=1 pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host antigravity --event Stop --compound-gate-mode off; else PGS_HOST_HOOK_DEBUG=1 npx --no-install @pieai/pro-gov host-hook --host antigravity --event Stop --compound-gate-mode off; fi",
             "timeout": 30
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then PGS_HOST_HOOK_DEBUG=1 ./node_modules/.bin/pro-gov host-hook --host antigravity --event SubagentStop; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; PGS_HOST_HOOK_DEBUG=1 pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host antigravity --event SubagentStop; else PGS_HOST_HOOK_DEBUG=1 npx --no-install @pieai/pro-gov host-hook --host antigravity --event SubagentStop; fi",
+            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then PGS_HOST_HOOK_DEBUG=1 ./node_modules/.bin/pro-gov host-hook --host antigravity --event SubagentStop --compound-gate-mode off; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; PGS_HOST_HOOK_DEBUG=1 pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host antigravity --event SubagentStop --compound-gate-mode off; else PGS_HOST_HOOK_DEBUG=1 npx --no-install @pieai/pro-gov host-hook --host antigravity --event SubagentStop --compound-gate-mode off; fi",
             "timeout": 30
           }
         ]

package/assets/starter/.claude/settings.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host claude-code --event Stop; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host claude-code --event Stop; else npx --no-install @pieai/pro-gov host-hook --host claude-code --event Stop; fi",
+            "command": "cd \"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host claude-code --event Stop --compound-gate-mode off; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host claude-code --event Stop --compound-gate-mode off; else npx --no-install @pieai/pro-gov host-hook --host claude-code --event Stop --compound-gate-mode off; fi",
             "timeout": 30
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host claude-code --event SubagentStop; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host claude-code --event SubagentStop; else npx --no-install @pieai/pro-gov host-hook --host claude-code --event SubagentStop; fi",
+            "command": "cd \"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host claude-code --event SubagentStop --compound-gate-mode off; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host claude-code --event SubagentStop --compound-gate-mode off; else npx --no-install @pieai/pro-gov host-hook --host claude-code --event SubagentStop --compound-gate-mode off; fi",
             "timeout": 30
           }
         ]

package/assets/starter/.codex/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host codex --event Stop; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host codex --event Stop; else npx --no-install @pieai/pro-gov host-hook --host codex --event Stop; fi",
+            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host codex --event Stop --compound-gate-mode off; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host codex --event Stop --compound-gate-mode off; else npx --no-install @pieai/pro-gov host-hook --host codex --event Stop --compound-gate-mode off; fi",
             "timeout": 30,
             "statusMessage": "Checking PGS Compound Gate"
           }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host codex --event SubagentStop; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host codex --event SubagentStop; else npx --no-install @pieai/pro-gov host-hook --host codex --event SubagentStop; fi",
+            "command": "cd \"$(git rev-parse --show-toplevel)\" && if [ -x ./node_modules/.bin/pro-gov ]; then ./node_modules/.bin/pro-gov host-hook --host codex --event SubagentStop --compound-gate-mode off; elif [ -f packages/pro-gov/src/cli.ts ] && { command -v corepack >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; }; then pgs_pnpm() { if command -v corepack >/dev/null 2>&1; then corepack pnpm \"$@\"; else pnpm \"$@\"; fi; }; pgs_pnpm --silent --filter @pieai/pro-gov dev host-hook --host codex --event SubagentStop --compound-gate-mode off; else npx --no-install @pieai/pro-gov host-hook --host codex --event SubagentStop --compound-gate-mode off; fi",
             "timeout": 30,
             "statusMessage": "Checking PGS subagent Compound Gate"
           }

package/assets/starter/AGENTS.template.md

@@ -43,7 +43,7 @@
 - Engineering projects may use Superpowers, Directed Development, GStack, or other external workflows only inside the selected lane; do not copy upstream integration guides into the target project by default.
 - For engineering projects, Superpowers is the default engineering workflow. Compound Engineering is used by default only as the post-work Compound Gate through `ce-compound`; full CE workflows require an explicit user request.
 - For engineering projects, PGS Learning Recall is the pre-work companion to that post-work gate: recall existing lessons first, then do the work, then decide whether a new lesson should be compounded.
-- Engineering projects should have PGS Stop hooks wired for Codex, Claude Code, and Antigravity. Before final reporting after completed engineering work, report `Compound Gate: ran ce-compound -> <path>`, `Compound Gate: ran fallback capture -> <path>`, or `Compound Gate: skipped -> <reason>`.
+- Engineering projects should have PGS Stop hooks wired for Codex, Claude Code, and Antigravity. Starter hooks default to `--compound-gate-mode off`; opt into `lite` or `strict` only when this project wants runtime exit-gate reminders. Before final reporting after completed engineering work, report `Compound Gate: ran ce-compound -> <path>`, `Compound Gate: ran fallback capture -> <path>`, or `Compound Gate: skipped -> <reason>`.
 - Use fallback capture only when the current host cannot load Compound Engineering; run `pro-gov learn capture --title "<learning title>" --summary "<reusable lesson>"` so Learning Recall can find the lesson later.
 - 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.

package/cli-guide.md

@@ -26,10 +26,12 @@ pro-gov lens inspect --target .
 pro-gov lens report --target . --out .pro-gov/lens-report.md
 pro-gov lens audit init --target /path/to/project --out audits/project/2026-07-01
 pro-gov lens audit check --dir audits/project/2026-07-01
+pro-gov host-hook --host codex --event Stop --compound-gate-mode off|lite|strict
 pro-gov init --profile engineering-runtime --dry-run
 pro-gov init --profile engineering-runtime --apply
 pro-gov init --profile doc-only --dry-run
 pro-gov sync --check [--profile engineering-runtime|doc-only]
+pro-gov sync --apply-host-hooks --profile engineering-runtime
 pro-gov doctor
 ```
 
@@ -41,8 +43,14 @@ Actions references stay packaged but are not installed by default.
 
 `sync --check` is read-only. It compares shared governance core files strictly,
 but checks project-local seeds such as `AGENTS.md`, project policy, and current
-work for presence only. It infers the installed profile when exactly one route
-exists; `--profile` resolves an empty or temporarily ambiguous target.
+work for presence only. Host configs are compared by PGS-owned entries, so
+consumer hooks do not create false drift. It infers the installed profile when
+exactly one route exists; `--profile` resolves an empty or temporarily ambiguous target.
+
+`sync --apply-host-hooks` is the bounded write path for engineering-runtime
+host configs. It updates only PGS Compound Gate entries and preserves consumer
+`PreToolUse`, other events, other top-level keys, and non-PGS entries inside
+Stop/SubagentStop arrays. All three files are parsed before any write.
 
 `learn recall` is the pre-work companion to Compound Engineering's post-work
 `ce-compound` learning records. It searches `docs/solutions/**` and
@@ -69,6 +77,12 @@ Then report:
 Compound Gate: ran fallback capture -> docs/solutions/<category>/<file>.md
 ```
 
+`host-hook` is the cross-host Compound Gate adapter for Codex, Claude Code, and
+Antigravity. `--compound-gate-mode off` is the default and does not interrupt
+the main session. `lite` emits a short continuation prompt when completed
+engineering work lacks a Compound Gate marker. `strict` emits the fuller legacy
+prompt. The same value can be supplied through `PGS_COMPOUND_GATE_MODE`.
+
 Full upstream-checkout commands:
 
 ```bash
@@ -146,6 +160,7 @@ pnpm pro-gov init --profile engineering-runtime --dry-run
 pnpm pro-gov init --profile engineering-runtime --apply
 pnpm doc-gov scan
 pnpm pro-gov sync --check --profile engineering-runtime
+pnpm pro-gov sync --apply-host-hooks --profile engineering-runtime
 pnpm doc-gov migrate --profile engineering-runtime --check
 pnpm doc-gov doctor
 ```

package/dist/cli.js

@@ -1763,8 +1763,19 @@ var compoundGateInstruction = [
   "If there is no reusable learning, report:",
   "Compound Gate: skipped -> <reason>"
 ].join("\n");
+var liteCompoundGateInstruction = [
+  "Pass the PGS Compound Gate before final reporting.",
+  "Report one line:",
+  "Compound Gate: ran ce-compound -> <path>",
+  "Compound Gate: ran fallback capture -> <path>",
+  "Compound Gate: skipped -> <reason>"
+].join("\n");
 var maxTranscriptBytes = 2 * 1024 * 1024;
 function evaluateHostHook(request) {
+  const mode = request.compoundGateMode ?? "off";
+  if (mode === "off") {
+    return { action: "allow" };
+  }
   if (request.event !== "Stop" && request.event !== "SubagentStop") {
     return { action: "allow" };
   }
@@ -1781,7 +1792,10 @@ function evaluateHostHook(request) {
   if (!looksLikeCompletedEngineeringWork(input.lastAssistantMessage)) {
     return { action: "allow" };
   }
-  return { action: "continue", reason: compoundGateInstruction };
+  return { action: "continue", reason: compoundGateInstructionForMode(mode) };
+}
+function compoundGateInstructionForMode(mode) {
+  return mode === "lite" ? liteCompoundGateInstruction : compoundGateInstruction;
 }
 function formatHostHookOutput(host, event, decision) {
   if (decision.action === "allow") {
@@ -1953,6 +1967,9 @@ function isHostHookHost(value) {
 function isHostHookEvent(value) {
   return value === "PostToolUse" || value === "PreToolUse" || value === "Stop" || value === "SubagentStop" || value === "UserPromptSubmit";
 }
+function isCompoundGateMode(value) {
+  return value === "off" || value === "lite" || value === "strict";
+}
 
 // src/commands/host-hook.ts
 var defaultStdinTimeoutMs = 750;
@@ -1960,6 +1977,7 @@ var maxDebugRawInputBytes = 256 * 1024;
 async function runHostHook(args) {
   const host = readOption(args, "--host");
   const event = readOption(args, "--event");
+  const compoundGateMode = readCompoundGateMode(args);
   if (!isHostHookHost(host)) {
     console.error("Expected --host <codex|claude-code|antigravity>");
     return 1;
@@ -1970,9 +1988,10 @@ async function runHostHook(args) {
   }
   const rawInput = await readStdinText(defaultStdinTimeoutMs);
   const input = parseStdinJson(rawInput);
-  const decision = evaluateHostHook({ host, event, input });
+  const decision = evaluateHostHook({ compoundGateMode, host, event, input });
   const output = formatHostHookOutput(host, event, decision);
   writeDebugLogIfRequested(args, {
+    compoundGateMode,
     decision,
     event,
     host,
@@ -1984,6 +2003,11 @@ async function runHostHook(args) {
 `);
   return 0;
 }
+function readCompoundGateMode(args) {
+  const value = readOption(args, "--compound-gate-mode") ?? process.env.PGS_COMPOUND_GATE_MODE ?? "off";
+  if (isCompoundGateMode(value)) return value;
+  return "off";
+}
 function readOption(args, name) {
   const index = args.indexOf(name);
   if (index < 0) return void 0;
@@ -2041,6 +2065,7 @@ function writeDebugLogIfRequested(args, record) {
         {
           schemaVersion: 1,
           cwd: process.cwd(),
+          compoundGateMode: record.compoundGateMode,
           event: record.event,
           host: record.host,
           nodeVersion: process.version,
@@ -2127,9 +2152,12 @@ function classifyOwnership(targetPath) {
 function isOtherProfileRouting(targetPath, profile) {
   return targetPath.startsWith("docs/governance/agents-routing/") && targetPath !== `docs/governance/agents-routing/${profile}-v0.9.md`;
 }
-function isEngineeringOnlyGuardrail(targetPath) {
+function isHostHookTargetPath(targetPath) {
   return targetPath === ".codex/hooks.json" || targetPath === ".claude/settings.json" || targetPath === ".agents/hooks.json";
 }
+function isEngineeringOnlyGuardrail(targetPath) {
+  return isHostHookTargetPath(targetPath);
+}
 function starterTargetPath(sourcePath) {
   if (sourcePath === "starter/AGENTS.template.md") return "AGENTS.md";
   if (sourcePath === "starter/CLAUDE.template.md") return "CLAUDE.md";
@@ -4089,11 +4117,69 @@ function printUsage4() {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync23, readFileSync as readFileSync18 } from "node:fs";
-import { join as join22 } from "node:path";
+import { existsSync as existsSync23, mkdirSync as mkdirSync9, readFileSync as readFileSync18, writeFileSync as writeFileSync8 } from "node:fs";
+import { dirname as dirname12, join as join22 } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+
+// src/host-hooks/config-merge.ts
+var MANAGED_EVENTS = ["Stop", "SubagentStop"];
+function mergeHostHookConfig(targetPath, current, template) {
+  const currentRecord = asRecord(current);
+  const templateRecord = asRecord(template);
+  if (targetPath === ".agents/hooks.json") {
+    return {
+      ...currentRecord,
+      "pgs-compound-gate": templateRecord["pgs-compound-gate"]
+    };
+  }
+  const host = targetPath === ".codex/hooks.json" ? "codex" : "claude-code";
+  const currentHooks = asRecord(currentRecord.hooks);
+  const templateHooks = asRecord(templateRecord.hooks);
+  const mergedHooks = { ...currentHooks };
+  for (const event of MANAGED_EVENTS) {
+    const currentEntries = asArray(currentHooks[event]);
+    const templateEntries = asArray(templateHooks[event]);
+    mergedHooks[event] = replaceManagedEntries(currentEntries, templateEntries, host, event);
+  }
+  return {
+    ...currentRecord,
+    hooks: mergedHooks
+  };
+}
+function replaceManagedEntries(currentEntries, templateEntries, host, event) {
+  const result = [];
+  let insertedTemplate = false;
+  for (const entry of currentEntries) {
+    if (isManagedEntry(entry, host, event)) {
+      if (!insertedTemplate) {
+        result.push(...templateEntries);
+        insertedTemplate = true;
+      }
+      continue;
+    }
+    result.push(entry);
+  }
+  if (!insertedTemplate) result.push(...templateEntries);
+  return result;
+}
+function isManagedEntry(entry, host, event) {
+  const serialized = JSON.stringify(entry);
+  return serialized.includes("pro-gov host-hook") && serialized.includes(`--host ${host}`) && serialized.includes(`--event ${event}`);
+}
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value;
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+// src/commands/sync.ts
 function runSync(args) {
-  if (!args.includes("--check")) {
-    console.error("pro-gov sync is read-only and requires --check.");
+  const check = args.includes("--check");
+  const applyHostHooks = args.includes("--apply-host-hooks");
+  if (check === applyHostHooks) {
+    console.error("pro-gov sync requires exactly one of --check or --apply-host-hooks.");
     return 1;
   }
   const requestedProfile = readFlag2(args, "--profile");
@@ -4113,6 +4199,7 @@ function runSync(args) {
     );
     return 1;
   }
+  if (applyHostHooks) return applyHostHookConfigs(profile);
   let differences = 0;
   console.log("pro-gov sync check");
   console.log(`profile: ${profile}`);
@@ -4127,7 +4214,7 @@ function runSync(args) {
     if (file.ownership === "project-local-seed") continue;
     const source = readFileSync18(file.absoluteSourcePath, "utf8");
     const target = readFileSync18(targetPath, "utf8");
-    if (source !== target) {
+    if (!matchesExpectedContent(file.targetPath, source, target)) {
       console.log(`different: ${file.targetPath}`);
       differences += 1;
     }
@@ -4139,6 +4226,48 @@ function runSync(args) {
   console.log("sync check passed: starter files match packaged assets.");
   return 0;
 }
+function applyHostHookConfigs(profile) {
+  if (profile !== "engineering-runtime") {
+    console.error("Host hooks are installed only for the engineering-runtime profile.");
+    return 1;
+  }
+  const root = process.cwd();
+  const updates = [];
+  try {
+    for (const file of planStarterFiles(profile)) {
+      if (!isHostHookTargetPath(file.targetPath)) continue;
+      const path = join22(root, file.targetPath);
+      const template = JSON.parse(readFileSync18(file.absoluteSourcePath, "utf8"));
+      const targetExists = existsSync23(path);
+      const current = targetExists ? JSON.parse(readFileSync18(path, "utf8")) : {};
+      const merged = mergeHostHookConfig(file.targetPath, current, template);
+      if (targetExists && isDeepStrictEqual(current, merged)) continue;
+      updates.push({ path, content: `${JSON.stringify(merged, null, 2)}
+` });
+    }
+  } catch (error) {
+    console.error(`Cannot merge host hook configuration: ${errorMessage(error)}`);
+    console.error("No host hook files were written.");
+    return 1;
+  }
+  for (const update of updates) {
+    mkdirSync9(dirname12(update.path), { recursive: true });
+    writeFileSync8(update.path, update.content);
+  }
+  console.log(`host hooks applied: ${updates.length}`);
+  console.log("Project-owned host config keys and non-PGS hook entries were preserved.");
+  return 0;
+}
+function matchesExpectedContent(targetPath, source, target) {
+  if (!isHostHookTargetPath(targetPath)) return source === target;
+  try {
+    const current = JSON.parse(target);
+    const template = JSON.parse(source);
+    return isDeepStrictEqual(current, mergeHostHookConfig(targetPath, current, template));
+  } catch {
+    return false;
+  }
+}
 function inferInstalledProfile(root) {
   const installed = ["engineering-runtime", "doc-only"].filter(
     (profile) => existsSync23(join22(root, `docs/governance/agents-routing/${profile}-v0.9.md`))
@@ -4150,6 +4279,9 @@ function readFlag2(args, flag) {
   const value = index >= 0 ? args[index + 1] : void 0;
   return value && !value.startsWith("--") ? value : void 0;
 }
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 
 // src/cli.ts
 var COMMANDS = [
@@ -4172,9 +4304,9 @@ var COMMANDS = [
   "lens report --target <path> --out <path>",
   "lens audit init --target <path> --out <path>",
   "lens audit check --dir <path> [--json]",
-  "host-hook --host <codex|claude-code|antigravity> --event <Stop|SubagentStop|...>",
+  "host-hook --host <codex|claude-code|antigravity> --event <Stop|SubagentStop|...> [--compound-gate-mode off|lite|strict]",
   "init --profile <engineering-runtime|doc-only> <--dry-run|--apply>",
-  "sync --check [--profile <engineering-runtime|doc-only>]",
+  "sync <--check|--apply-host-hooks> [--profile <engineering-runtime|doc-only>]",
   "doctor"
 ];
 var [command, subcommand] = process.argv.slice(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pieai/pro-gov",
-  "version": "0.3.17",
+  "version": "0.4.1",
   "description": "Project-level distribution kit for Project Governance System.",
   "keywords": [
     "ai-agents",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pieai/doc-gov": "^0.3.17"
+    "@pieai/doc-gov": "^0.4.1"
   },
   "devDependencies": {
     "@types/node": "24.13.2",