@geminix/gxpm 0.1.0

package/docs/architecture/gxpm-v0-contract.md

@@ -0,0 +1,311 @@
+# gxpm V0 合同
+
+## 北极星
+
+gxpm 是替代 PMC 和 gstack 的二代代理项目管理控制面。它把 Linear issue、阶段状态、执行代理、验证证据、浏览器 QA、评审、发布收口、上下文恢复和自学习整合到同一个原生系统里。
+
+## 非目标
+
+- 不做 PMC/gstack 的薄封装。
+- 不保留“PMC 管项目、gstack 管工程流”的长期双轨。
+- 不把历史 skill 目录直接 vendoring 成 gxpm。
+- 不在 V0 一次性实现全部替代能力；V0 要形成最小可运行替代闭环。
+
+## 核心对象
+
+### Project
+
+一个 gxpm 管理的代码项目或产品项目。Project 需要声明：
+
+- issue provider：默认 Linear。
+- state root：默认 `.gxpm/issues/<issue-id>/`。
+- artifact root：默认同 state root。
+- capability bindings：不同阶段调用哪些 gxpm 原生能力。
+
+### Issue
+
+Issue 是状态机实例。Issue 的本地真值必须在文件系统中存在，Linear 只是前门和同步面。
+
+V0 已实现的本地目录：
+
+```text
+.gxpm/issues/<issue-id>/
+  state.json
+  graph.json
+  events.jsonl
+  artifacts/
+    index.json
+    acceptance-check.json
+    acceptance-contract.json
+    autopilot-grant.json
+    dispatch-handoff.json
+    implementation-plan.json
+    issue-intake.json
+    land-findings.json
+    local-verify.json
+    pr-check.json
+    qa-findings.json
+    self-review.json
+    ship-readiness.json
+    triage-report.json
+    verify-findings.json
+  reports/
+  evidence/
+    command-logs/
+    browser-snapshots/
+    browser-screenshots/
+    browser-console/
+    browser-errors/
+    investigations/
+    review/
+    release/
+    screenshots/
+  memory/
+    resume-packet.json
+    checkpoints/
+      20260427-044500-handoff.md
+  runs/
+    run-20260428123000-1a2b3c4d.json
+```
+
+V0 已支持 JSON artifact store。当前 artifact type：
+
+- `issue-intake`
+- `triage-report`
+- `autopilot-grant`
+- `acceptance-contract`
+- `implementation-plan`
+- `dispatch-handoff`
+- `behavior-spec`
+- `wiki-context`
+- `local-verify`
+- `acceptance-check`
+- `self-review`
+- `review-report`
+- `cleanup-report`
+- `ship-readiness`
+- `ship-audit-report`
+- `pr-check`
+- `verify-findings`
+- `qa-findings`
+- `land-findings`
+- `feedback-description`
+
+V0 只写 JSON artifact，不渲染 markdown report。
+
+### Autopilot Grant
+
+Autopilot Grant 是 issue-local 的自动驾驶授权 artifact：`artifacts/autopilot-grant.json`。它不是新的 phase，也不绕过 phase gate；它只把用户对“无需逐步确认”的授权、profile、允许动作、hard stop 和生命周期状态持久化，让 hook 与 agent 在后续回合可恢复同一授权边界。
+
+V0 profile 只有 `full-delivery`：授权代理在同一 issue 内自主完成 triage、plan、dispatch、implement、local verification、review、PR、merge/land 和 cleanup。hard stop 包括用户显式停止、需要密钥/付费外部 API、生产数据或破坏性数据迁移、不可恢复冲突或验证失败、以及策略/权限边界。
+
+### Evidence Store
+
+V0 的 issue-local evidence 统一由 `core/evidence.ts` 分配路径和写入。调用方必须提供 issue id、evidence kind、安全文件名、媒体类型和 payload；helper 负责复用 `core/state.ts` 的 issue id 校验、确认 issue state 存在、创建目标 evidence 子目录，并阻止文件名穿越 issue 目录。
+
+当前 evidence kind 覆盖 command logs、browser snapshots/screenshots/console/errors、investigations、review 和 release。`screenshots` 保留给已有 `gxpm-investigate` 证据路径以维持兼容；新的 browser runtime 证据优先使用更具体的 `browser-*` kind。
+
+Evidence Store 只管理 issue-local files，不替代 phase artifact store；阶段结论仍写入 `artifacts/*.json`，原始截图、console、review 或命令日志写入 `evidence/`。
+
+### Resume Packet / Checkpoint
+
+V0 的上下文恢复入口是 issue-local memory，而不是聊天历史或 gstack runtime：
+
+- `gxpm issue checkpoint <issue-id> --title <title> --stdin`：读取 JSON payload，写入 append-only markdown checkpoint，并更新 `memory/resume-packet.json`。
+- `gxpm issue resume <issue-id>`：读取 `resume-packet.json`，打印 phase、checkpoint path、summary、remaining work 和 notes，供新对话恢复上下文。
+
+checkpoint payload 至少包含 `summary`，可选 `decisions`、`remainingWork`、`notes`、`filesModified`、`status`、`sessionDurationSeconds`。`memory/resume-packet.json` 是恢复流程的机器可读入口，markdown checkpoint 是人类可读交接文档。
+
+### Run Ledger / Workspace Runtime
+
+V0 的执行运行时先提供可审计原语，不启动长驻 daemon：
+
+- run ledger 保存在 `.gxpm/issues/<issue-id>/runs/`，每条 run 记录包含 `runId`、`attempt`、`status`、`sessionId`、`workspacePath`、失败原因和事件序列。
+- workspace runtime 负责把 issue 映射到安全的 per-issue workspace 路径，默认根目录来自 `workspace.root`（默认 `.gxpm/local/workspaces`），并提供 plan / ensure / cleanup 三个动作。
+- orchestrator dry-run tick 只读本地 `.gxpm` issue state，报告哪些 issue 可派发、哪些被 phase/artifact 阻塞；它不 claim、不启动 agent、不写 phase state。
+
+这些运行时原语属于 Capability Runtime 的 execution 层，但不改变 phase 顺序，也不替代 phase artifact gate。
+
+### Phase
+
+V0 phase 集合：
+
+- `triage`
+- `plan`
+- `dispatch`
+- `specify`
+- `implement`
+- `local-verify`
+- `ac-check`
+- `self-review`
+- `cleanup`
+- `ship`
+- `pr-check`
+- `verify`
+- `qa`
+- `land`
+
+V0 可以导入 PMC/gstack 的语义，但最终 phase 是 gxpm 原生状态，不以 `.omc` 或 `.gstack` 作为长期真值。
+
+V0 phase transition 采用严格顺序：只能从当前 phase 进入列表中的下一个 phase。
+
+`triage -> plan` 额外要求存在 `acceptance-contract` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm triage init <issue-id>`。
+
+`plan -> dispatch` 额外要求存在 `implementation-plan` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm plan init <issue-id>`。
+
+`dispatch -> specify` 额外要求存在 `dispatch-handoff` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm dispatch init <issue-id>`。
+
+`specify -> implement` 额外要求存在 `behavior-spec` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm specify init <issue-id>`。
+
+`implement -> local-verify` 额外要求存在 `local-verify` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm implement verify <issue-id>`。
+
+`local-verify -> ac-check` 额外要求存在 `acceptance-check` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm local-verify ac-check <issue-id>`。
+
+`ac-check -> self-review` 额外要求存在 `self-review` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm ac-check self-review <issue-id>`。
+
+`self-review -> cleanup` 额外要求存在 `cleanup-report` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm self-review cleanup <issue-id>`。
+
+`cleanup -> ship` 额外要求存在 `ship-readiness` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm cleanup ship <issue-id>`。
+
+`ship -> pr-check` 额外要求存在 `pr-check` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm ship pr-check <issue-id>`。
+
+`pr-check -> verify` 额外要求存在 `verify-findings` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm pr-check verify <issue-id>`。
+
+`verify -> qa` 额外要求存在 `qa-findings` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm verify qa <issue-id>`。
+
+`qa -> land` 额外要求存在 `land-findings` artifact。缺失时 transition 必须失败，并提示先运行 `gxpm qa land <issue-id>`。
+
+## Source of Truth
+
+真值优先级：
+
+1. phase JSON artifacts
+2. `state.json`
+3. `resume-packet.json`
+4. rendered markdown reports
+5. Linear comments / PR body / chat history
+
+任何恢复流程都必须先读本地 phase/state，而不是从聊天上下文猜。
+
+## Ability Adapter
+
+gxpm 用 capability runtime 统一所有能力。V0 可以先用 adapter 接入现有能力，但 adapter 是迁移脚手架，不是最终产品边界：
+
+- `issueRuntime`：Linear read/write/sync 与 issue graph。
+- `executionRuntime`：worker dispatch、worktree、task claim、local verification。
+- `reviewRuntime`：代码评审、specialist review、adversarial review。
+- `browserRuntime`：浏览器 QA、截图、console/network evidence。
+- `releaseRuntime`：PR、版本、changelog、merge/deploy handoff。
+- `memoryRuntime`：timeline、learn、context restore。
+- `skillRuntime`：skill discovery、routing、preamble、模板生成。
+
+每个 runtime/capability 必须声明：
+
+- input contract
+- output artifact
+- failure mode
+- idempotency rule
+- 是否允许 mutation
+
+V0 的 first-party capability contract 由 `core/capabilities.ts` 维护，并可通过只读命令 `gxpm capability list` / `gxpm capability show <capability-id>` 检查。registry 只描述合同和证据要求，不负责动态加载、执行插件或绕过 phase/artifact gate。
+
+`verification.issue-evidence-store` 是 V0 的共享 evidence 写入能力。它只能在目标 issue 的 `evidence/` 目录内创建或覆盖文件，不能隐式推进 phase、写 phase artifact、claim issue 或调用外部 provider。
+
+## 与 PMC 的关系
+
+PMC 是 gxpm 的上游能力来源和迁移对象，不是长期依赖。
+
+gxpm 应吸收 PMC 的优秀部分：
+
+- phase gating
+- checkpoint
+- Linear team key/source discipline
+- acceptance/local-verify/verify/qa artifact contracts
+- execution continuity
+
+gxpm 应替换 PMC 的不足：
+
+- QA 只停留在合同层。
+- skill routing 与能力发现不够系统。
+- 对 review/ship/design/devex/security/canary 的能力聚合不完整。
+
+## 与 gstack 的关系
+
+gstack 是 gxpm 的上游能力来源和迁移对象，不是长期依赖。
+
+gxpm 应吸收 gstack 的优秀部分：
+
+- preamble/config/session/timeline/learn 模式。
+- template-generated skill docs。
+- browser daemon 的设计原则。
+- `/review`、`/qa`、`/investigate`、`/ship` 的证据和循环机制。
+- team install 与 host abstraction 的思路。
+
+gxpm 应替换 gstack 的不足：
+
+- Claude-only 假设。
+- 自动 ship/PR 的所有语义。
+- 对项目目录写入 vendored gstack 的模式。
+
+## V0 Stop Rules
+
+V0 阶段如果出现以下情况，应停止并生成 report，而不是继续推进：
+
+- 无法确定 issue/state 的真实阶段。
+- Linear 与本地 state 冲突且无法安全补偿。
+- adapter 的 mutation 行为不明确。
+- QA/browser evidence 无法获得，但 acceptance 依赖浏览器行为。
+- land/merge 需要不可逆操作但用户尚未确认。
+
+## 成功信号
+
+- 新会话可以只靠 `.gxpm/issues/<issue-id>/state.json` 和 artifacts 恢复。
+- 每个 phase 都有明确的 required output。
+- 每个能力都有 gxpm 原生 contract。
+- 失败时能降级为本地报告，而不是把状态写坏。
+- 一个 issue 可以在 gxpm 内完成从 intake 到 QA/land 的最小闭环，不必同时加载 PMC 和 gstack。
+
+## V0 本地命令
+
+```bash
+gxpm issue create <issue-id>
+gxpm issue status <issue-id>
+gxpm issue transition <issue-id> <phase>
+gxpm issue checkpoint <issue-id> --title "handoff" --stdin
+gxpm issue resume <issue-id>
+gxpm issue ready
+gxpm issue claim <issue-id>
+gxpm issue release <issue-id>
+gxpm issue reconcile-claim <issue-id>
+gxpm capability list
+gxpm capability show <capability-id>
+gxpm run start <issue-id> [--claim]
+gxpm run list <issue-id>
+gxpm run status <issue-id> <run-id>
+gxpm run event <issue-id> <run-id> --type <event>
+gxpm workspace plan <issue-id>
+gxpm workspace ensure <issue-id>
+gxpm workspace cleanup <issue-id>
+gxpm orchestrator tick --dry-run
+gxpm autopilot start <issue-id>|--auto-id
+gxpm autopilot status <issue-id>
+gxpm autopilot list
+gxpm autopilot stop <issue-id>
+gxpm artifact list <issue-id>
+gxpm artifact read <issue-id> <type>
+gxpm triage init <issue-id>
+gxpm plan init <issue-id>
+gxpm dispatch init <issue-id>
+gxpm specify init <issue-id>
+gxpm implement verify <issue-id>
+gxpm local-verify ac-check <issue-id>
+gxpm ac-check self-review <issue-id>
+gxpm self-review cleanup <issue-id>
+gxpm cleanup ship <issue-id>
+gxpm ship pr-check <issue-id>
+gxpm pr-check verify <issue-id>
+gxpm verify qa <issue-id>
+gxpm qa land <issue-id>
+```
+
+`gxpm issue create` 默认进入 `triage`。`gxpm issue transition` 不支持跳 phase 或 force。`gxpm triage init` 会生成 draft `acceptance-contract`，用于解锁 `triage -> plan`。`gxpm plan init` 会生成 draft `implementation-plan`，用于解锁 `plan -> dispatch`。`gxpm dispatch init` 会生成 draft `dispatch-handoff`，用于解锁 `dispatch -> specify`。`gxpm specify init` 会生成 draft `behavior-spec`，用于解锁 `specify -> implement`。`gxpm implement verify` 会生成 draft `local-verify`，用于解锁 `implement -> local-verify`。`gxpm local-verify ac-check` 会生成 draft `acceptance-check`，用于解锁 `local-verify -> ac-check`。`gxpm ac-check self-review` 会生成 draft `self-review`，用于解锁 `ac-check -> self-review`。`gxpm self-review cleanup` 会生成 draft `cleanup-report`，用于解锁 `self-review -> cleanup`。`gxpm cleanup ship` 会生成 draft `ship-readiness`，用于解锁 `cleanup -> ship`。`gxpm ship pr-check` 会生成 draft `pr-check`，用于解锁 `ship -> pr-check`。`gxpm pr-check verify` 会生成 draft `verify-findings`，用于解锁 `pr-check -> verify`。`gxpm verify qa` 会生成 draft `qa-findings`，用于解锁 `verify -> qa`。`gxpm qa land` 会生成 draft `land-findings`，用于解锁 `qa -> land`。

package/docs/architecture/layered-workflow-boundaries.md

@@ -0,0 +1,193 @@
+# Layered Workflow Boundaries
+
+日期：2026-05-10
+
+## 目的
+
+本文件把 `ZeroZ-lab/unified-skills` 的完整工程实践，转译为 gxpm 的长期分层合同。
+
+它回答五个边界问题：
+
+- Command 负责什么？
+- Agent 负责什么？
+- Skill 负责什么？
+- Artifact 负责什么？
+- Hook / Validate 负责什么？
+
+gxpm 的目标不是复制 unified-skills 的目录，而是吸收它的分层原则：入口清晰、职责单一、证据可追溯、运行前后都有守卫。
+
+## 上游研究证据
+
+研究对象：
+
+- 本地路径：`/Users/x/Desktop/Project/github/unified-skills`
+- 上游仓库：`https://github.com/ZeroZ-lab/unified-skills`
+- 研究时 HEAD：`f4e6dde`
+
+关键工程实践：
+
+- `CANON.md` 定义不可破坏的系统规则，约束 command、agent、skill、hook 的协作方式。
+- `commands/*.md` 把用户意图收敛为可执行流程，例如 `refine`、`plan`、`build`、`review`、`ship`。
+- `agents/*.md` 把执行者拆成明确责任视角，例如 spec compliance auditor、code quality auditor、task planner、software engineer。
+- `skills-index.json` 和 `load-manifest.json` 把 skill 变成可发现、可加载、可校验的能力目录。
+- `hooks/*.sh` 与 `hooks/hooks.json` 在 SessionStart、UserPromptSubmit、工具使用前后注入运行守卫。
+- `validate` 把目录、索引、manifest、hook 和命名约定变成可重复执行的检查。
+
+这套实践的核心不是文件格式，而是分层闭环：
+
+```text
+Command 选择流程
+Agent 承担责任视角
+Skill 提供可加载方法
+Artifact 保存事实和证据
+Hook / Validate 阻止边界漂移
+```
+
+## gxpm 分层定义
+
+### Command
+
+Command 是用户和 agent 进入 state graph 的入口。
+
+在 gxpm 中，Command 由 CLI 和 phase gate 表达：
+
+- `scripts/gxpm.ts`
+- `scripts/phase-artifact-commands.ts`
+- `core/phase-gates.ts`
+
+Command 只回答：
+
+- 当前 phase 允许什么动作？
+- 需要哪个输入 artifact？
+- 会生成哪个输出 artifact？
+- 是否可以 transition？
+
+Command 不应该承载长期业务真值。业务真值必须写入 `.gxpm/issues/<id>/`。
+
+### Agent
+
+Agent 是责任视角，不是人格模板。
+
+在 gxpm 中，Agent 当前主要体现在 phase 责任里：
+
+- triage owner 澄清范围和验收合同。
+- planner owner 输出实现计划和验证策略。
+- implementer owner 修改代码并记录 local verification。
+- reviewer owner 检查 acceptance、self-review、ship readiness。
+- QA owner 记录 browser/runtime 证据。
+- land owner 记录 merge plan 和 release risks。
+
+GXPM-120 的研究结论是：Agent 层还没有成为第一类 registry。短期先通过 capability contract 覆盖每个 phase gate，长期再设计 Agent Runtime，把 role、input、output、stop rule 和 handoff 做成可查询契约。
+
+### Skill
+
+Skill 是 host 发现和加载 gxpm 方法的表面，不是真值层。
+
+在 gxpm 中，Skill Surface 包括：
+
+- `skills/gxpm/SKILL.md.tmpl`
+- `scripts/gen-skill-docs.ts`
+- 生成后的 host-facing `SKILL.md`
+- host config 和 skill naming checks
+
+Skill 可以解释如何运行 gxpm，但不能替代：
+
+- state graph
+- artifact store
+- capability registry
+- phase gate rules
+
+因此修改 skill 时必须改模板和生成器，不把生成物当真值手修。
+
+### Artifact
+
+Artifact 是 phase 结论、验收状态和可恢复事实。
+
+在 gxpm 中，Artifact 的位置是：
+
+```text
+.gxpm/issues/<issue-id>/artifacts/*.json
+```
+
+Artifact 必须承载：
+
+- 当前 phase 的输入摘要
+- 输出结论
+- 验收状态
+- 风险和失败模式
+- 后续 phase 可恢复的最小事实
+
+原始证据不应该塞进 artifact。截图、console、命令输出、review 原文和调查过程属于 `evidence/`，artifact 只引用它们并总结结论。
+
+### Hook / Validate
+
+Hook 和 Validate 是防漂移层。
+
+在 gxpm 中，对应能力包括：
+
+- git hooks 和 `gxpm gate`
+- `bun run check`
+- `scripts/scaffold-check.ts`
+- `scripts/governance-check.ts`
+- `core/artifact-validator.ts`
+- phase gate tests
+
+Hook / Validate 不应该替 agent 做业务判断；它们只负责阻止明显违反合同的状态进入仓库。
+
+## 四个缺口
+
+### 1. Agent 层不是第一类对象
+
+问题：gxpm 有 phase 和 capability，但没有像 unified-skills `agents/*.md` 那样可查询的责任视角目录。
+
+本次落地：先把每个 phase gate artifact 映射到 capability contract，确保执行责任至少有清楚的输入、输出、证据、失败模式和 mutation policy。
+
+后续方向：新增 Agent Runtime 或 agent registry，把 reviewer、QA、implementer、planner 等责任视角显式建模。
+
+### 2. Capability Registry 没覆盖所有 phase gate artifact
+
+问题：部分 gate artifact 只存在于 phase initializer 和 tests 中，没有 capability contract。这样 agent 不知道某个 artifact 对应的能力边界。
+
+本次落地：`core/capabilities.ts` 补齐 gate artifact 覆盖，并用测试证明所有 `PHASE_GATE_RULES.requiredArtifact` 都能被 capability 输出。
+
+### 3. Artifact Validator 仍停留在旧 artifact 名称
+
+问题：validator 还在校验早期 `spec`、`plan`、`tasks`，而 gxpm 当前 artifact 已经演化为 `acceptance-contract`、`implementation-plan`、`dispatch-handoff` 等。
+
+本次落地：`core/artifact-validator.ts` 改为基于 `ARTIFACT_TYPES` 的 gxpm artifact schema，并让 CLI artifact write 使用统一 validator。
+
+### 4. Validate 层没有检查分层边界漂移
+
+问题：`bun run check` 主要验证 host config、governance、version、skill naming，不能发现 phase gate、capability output、artifact validator 三者不一致。
+
+本次落地：`scripts/scaffold-check.ts` 增加 layered workflow contract check，检查：
+
+- 每个 phase gate artifact 都有 capability output。
+- 每个 artifact type 都被 artifact validator 覆盖。
+- capability output 不引用未知 artifact。
+
+## 边界矩阵
+
+| Layer | gxpm 真值 | 允许写入 | 不允许承担 |
+| --- | --- | --- | --- |
+| Command | `core/phase-gates.ts`、CLI command handlers | phase transition、artifact initialization | 长期业务事实 |
+| Agent | phase owner / future agent registry | handoff、review、QA、land 责任结论 | 绕过 phase gate |
+| Skill | `*.tmpl`、生成器、host config | host-facing guidance | state truth、artifact truth |
+| Artifact | `.gxpm/issues/<id>/artifacts/*.json` | phase 结论、验收状态、风险 | 原始日志和截图 |
+| Hook / Validate | `gxpm gate`、`bun run check`、scaffold checks | 阻止合同漂移 | 替代人工判断或业务验收 |
+
+## 非目标
+
+- 不引入 unified-skills 运行时依赖。
+- 不把 gxpm 写成 unified-skills、PMC 或 gstack 的兼容壳。
+- 不在本次实现完整 Agent Runtime。
+- 不把所有 evidence schema 一次性收紧；本次只校准 phase gate artifact 的结构边界。
+
+## 设计原则
+
+1. Command 只路由，不沉淀事实。
+2. Agent 是责任，不是聊天人格。
+3. Skill 是入口，不是真值。
+4. Artifact 是恢复和验收的最小事实。
+5. Hook / Validate 是防漂移，不替代判断。
+6. 每个 capability 必须声明输入、输出、证据、失败模式和 mutation policy。

package/docs/architecture/preset-system.md

@@ -0,0 +1,126 @@
+# Preset System Architecture
+
+> Override > Preset > Core three-layer resolution for gxpm templates and skills.
+
+## Overview
+
+The preset system allows projects to customize gxpm-generated artifacts (skills, templates, commands) without forking the core repository. It implements a subset of Spec Kit's four-layer extensibility stack:
+
+| Layer | Path | Priority | Purpose |
+|-------|------|----------|---------|
+| Override | `.gxpm/overrides/` | Highest | One-off local adjustments (full replacement) |
+| Preset | `.gxpm/presets/<id>/` | Middle | Shareable, stackable template/command overrides |
+| Core | `skills/`, `templates/` | Lowest | Built-in defaults |
+
+Extension and hooks are deferred to future iterations (MVP: Override + Preset + Core only).
+
+## Directory Layout
+
+```
+.gxpm/
+├── overrides/              # Override layer (mirrors project root structure)
+│   └── skills/
+│       └── gxpm/
+│           └── SKILL.md    # Full replacement of generated skill
+├── presets/
+│   ├── .registry           # Active preset IDs (JSON)
+│   ├── default/
+│   │   ├── manifest.json   # Preset manifest
+│   │   └── skill.md        # Source file for replace rule
+│   └── team-alpha/
+│       ├── manifest.json
+│       └── header.md
+```
+
+## Registry Format
+
+`.gxpm/presets/.registry`:
+
+```json
+{
+  "active": ["team-alpha", "default"]
+}
+```
+
+- `active` is ordered by priority (first = highest).
+- Presets not in `active` are loaded but not applied.
+
+## Manifest Schema
+
+`manifest.json`:
+
+```json
+{
+  "id": "default",
+  "name": "Default Preset",
+  "version": "1.0.0",
+  "description": "Optional description",
+  "extends": ["base-preset"],
+  "rules": [
+    {
+      "target": "skills/gxpm/SKILL.md",
+      "strategy": "replace",
+      "source": "skill.md"
+    },
+    {
+      "target": "skills/*/SKILL.md",
+      "strategy": "append",
+      "source": "notice.md"
+    }
+  ]
+}
+```
+
+### Fields
+
+- `id` — unique preset identifier (matches directory name)
+- `name` — human-readable name
+- `version` — semver string
+- `description` — optional description
+- `extends` — IDs of lower-priority presets to inherit (not yet implemented in MVP)
+- `rules` — composition rules
+
+### Rule Fields
+
+- `target` — file path relative to project root; supports `*` wildcard
+- `strategy` — `replace` | `prepend` | `append` | `wrap`
+- `source` — file path relative to preset directory
+- `anchor` — optional marker for positioning (prepend/append/wrap)
+
+## Composition Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `replace` | Full replacement with source content |
+| `prepend` | Insert source before target (or before `anchor`) |
+| `append` | Insert source after target (or after `anchor`) |
+| `wrap` | Wrap target with source (or replace `anchor` with source) |
+
+## Integration with gen:skill-docs
+
+`scripts/gen-skill-docs.ts` integrates `PresetResolver` after template rendering:
+
+1. Render `.tmpl` → base content
+2. Call `PresetResolver.resolve(outputPath, baseContent)`
+3. Write resolved content to disk
+
+This means presets can override:
+- Template variables (by replacing the entire generated file)
+- Specific sections (by append/prepend/wrap with anchors)
+- Static skills (by targeting their output path)
+
+## CLI Commands
+
+```bash
+gxpm preset list              # List all presets and active status
+gxpm preset add <id>          # Activate a preset
+gxpm preset remove <id>       # Deactivate a preset
+gxpm preset show <id>         # Show preset manifest and rules
+gxpm preset init <id>         # Create a new preset directory
+```
+
+## Backward Compatibility
+
+- No `.gxpm/presets/` directory → `PresetResolver` returns core content unchanged
+- No `.gxpm/overrides/` directory → override layer is skipped
+- Existing `gen:skill-docs` behavior is preserved when no presets are active

package/docs/architecture/scaffold-northstar.md

@@ -0,0 +1,23 @@
+# gxpm 脚手架北极星
+
+gxpm 把 gstack 当作脚手架北极星，而不是运行时依赖。需要保留的是它的产品化形态：
+
+- 用模板定义可安装的 agent-facing surface。
+- 用 host adapter 显式描述每个代理运行时。
+- 用生成器从模板产出可检查的 skill 文档。
+- 用本地检查在生成产物漂移时 fail fast。
+- 用 CLI 入口把项目做成可安装、可升级、可团队化的产品。
+
+## V0 合同
+
+初始脚手架刻意保持小而完整：
+
+- `hosts/` 把 Codex 和 Claude Code 注册成一等 host adapter。
+- `scripts/discover-skills.ts` 发现 `SKILL.md.tmpl`，同时跳过生成目录、隐藏目录和构建产物。
+- `scripts/gen-skill-docs.ts` 用 host-aware preamble 渲染模板。
+- `scripts/gxpm-check.ts` 校验 host 合同和生成文档。
+- `bin/` 暴露稳定命令名，为后续 install/update/team-init 流程留入口。
+- `docs/governance/` 把开发规范拆成渐进加载的执行合同。
+
+这会先给 gxpm 建立产品脊柱，再继续生长 PM state graph。下一层可以补 `.gxpm`
+状态、capability 执行、browser evidence 和 Linear sync，而不需要重写安装面。