@geminix/gxpm 0.1.0

package/AGENTS.md

@@ -0,0 +1,148 @@
+# gxpm Agent Contract
+
+## Role
+
+gxpm 是面向完全替代 `pmc` 和 `gstack` 的第二代代理项目管理产品。PMC 和 gstack 是上游研究对象与能力来源，不是 gxpm 的长期运行依赖。
+
+<!-- BEGIN USER-SPECIFIED -->
+**核心定位：AI Agent 工作制度架构 + 工作流 + 状态机的可执行产品。**
+
+形态：**基于文档驱动的制度套件 + CLI 运行时。**
+
+gxpm 不是 PMC 的兼容壳，也不是 gstack 的插件集合。所有设计都要服务于独立产品闭环：统一 state graph、capability runtime、browser evidence、review/ship governance 和 agent execution loop。
+
+**架构哲学 —— 四维分工：**
+
+| 维度 | 职责 | gxpm 体现 |
+|---|---|---|
+| **commit** | 阶段切分 | git worktree 隔离 + phase transition，物理与逻辑双重边界 |
+| **Agent** | 角色分工 | triage/plan/implement/review/QA/land owner，责任视角而非人格模板 |
+| **skill** | 能力注入 | `skills/*/SKILL.md` 可发现、可加载、可校验的方法目录 |
+| **证据/事实** | 持久存储 | `artifacts/*.json` + `evidence/` + `state.json`，本地文件系统为唯一真值 |
+
+**五层架构：**
+
+```
+L1: 制度文档层 — CANON.md / AGENTS.md / CONTEXT.md / docs/governance/*.md
+L2: 角色与技能层 — agents/*.md / skills/*/SKILL.md / templates/*.tmpl
+L3: 工作流编排层 — workflows/*.yml / core/phase-gates.ts / PHASE_GATE_RULES
+L4: 状态机执行层 — core/state.ts / core/capabilities.ts / CLI commands
+L5: 证据与恢复层 — .gxpm/issues/<id>/{state,artifacts,evidence,memory}/
+```
+
+**核心原则：**
+
+1. 文档即制度，制度可执行 —— 治理规则以文本存在，被 CLI 解析、被模板生成、被 hook 校验。
+2. 本地 state 永远比外部系统更权威 —— `state.json` 比 Linear comment、PR body、聊天上下文更权威。
+3. 所有 transition 都必须可审计、可重放、可恢复 —— 事件 append-only 写入 `events.jsonl`。
+4. Command 只路由，Agent 只担责，Skill 只注入，Artifact 只存真值 —— 分层边界不可漂移。
+
+**Phase 顺序（14 阶段，按 `rigorLevel` 压缩）：**
+
+完整：`triage → plan → dispatch → specify → implement → local-verify → ac-check → self-review → cleanup → ship → pr-check → verify → qa → land`
+
+- `lite`（spike/meta）：7 阶段，跳过 dispatch, local-verify, ac-check, cleanup, pr-check, verify, qa
+- `standard`（默认）：9 阶段，跳过 local-verify, ac-check, cleanup, pr-check, verify
+- `full`：14 阶段，不跳过
+
+底层阶段不变，transition 允许跨阶段跳跃；跳过阶段仍记入 `phaseHistory` 保持审计链。
+
+- **specify**：BDD 行为规约阶段。产出 `behavior-spec.json` artifact + 空测试 stub；必须由用户通过 `gxpm specify confirm <id>` 显式确认后才能进入 implement。Owner：`specifier`。Skill：`gxpm-specifier`。规则：`docs/governance/gherkin-style.md`。
+- 进入 `implement` 之前，phase-gate 校验 `behavior-spec.confirmedAt` 非空；老 issue（在 `SPECIFY_PHASE_CUTOFF = 2026-05-14T00:00:00Z` 前已进入 implement）可豁免。
+<!-- END USER-SPECIFIED -->
+
+## 全局纪律
+
+**所有 Agent 在所有阶段都必须遵守 `CANON.md` 中的行为宪法。** 本文档不再重复那些纪律，只保留项目级入口信息。
+
+## Truth Sources
+
+1. 用户本轮明确指令。
+2. `CANON.md` — 全局行为宪法
+3. `CONTEXT.md` — 共享语言/术语表
+4. `README.md` — 产品定位与架构哲学（本文档的简化版）
+5. `docs/architecture/gxpm-replacement-architecture.md`
+6. `docs/architecture/gxpm-v0-contract.md`
+7. `docs/architecture/layered-workflow-boundaries.md`
+8. `docs/architecture/scaffold-northstar.md`
+9. `docs/governance/development-contract.md`
+10. `docs/governance/template-authoring.md`
+11. `docs/governance/host-adapter.md`
+12. `docs/governance/skill-authoring.md`
+13. `docs/governance/gherkin-style.md`（specify 阶段强制规则）
+14. `docs/research/pmc-gstack-skill-study.md`
+
+如果来源冲突，先指出冲突和建议的最小安全路径。
+
+## Reference Projects（工程实践优先参考）
+
+以下项目作为 gxpm 工程实践与 skill 设计的参考借鉴对象，本地路径如下：
+
+### 行为规范参考框架
+
+- **ZeroZ-lab/unified-skills** — AI Agent 工作制度架构的完整参考实现  
+  路径：`/Users/x/Desktop/Project/github/unified-skills`
+
+  gxpm 的分层边界设计（Command / Agent / Skill / Artifact / Hook）直接继承并转译自 unified-skills 的四层分离制度。以下实践应作为 gxpm 的长期行为约束参考：
+
+  | unified-skills 实践 | gxpm 对应层 | 借鉴状态 |
+  |---|---|---|
+  | CANON.md 10 条行为宪法 | `CANON.md` | ✅ 已吸收 |
+  | Command 阶段协议（12 命令） | CLI phase commands + `core/phase-gates.ts` | ✅ 已转译为状态机 |
+  | Agent 角色责任边界（24 角色） | `agents/*.md` + future Agent Runtime | 🟡 结构存在，Runtime 待建 |
+  | Skill 能力注入（53 技能） | `skills/*/SKILL.md` | ✅ 已吸收模式 |
+  | `./validate` 治理检查 | `bun run check` + `scripts/scaffold-check.ts` | ✅ 已吸收 |
+  | Hooks 安全护栏（SessionStart / careful / freeze） | `core/hook-engine.ts` + `.githooks/` | ✅ 已转译 |
+  | 文档产物链（`docs/features/YYYYMMDD-<name>/`） | `.gxpm/issues/<id>/artifacts/` + `reports/` | ✅ 已转译为 JSON artifact |
+  | artifact_type 路由（software / document / article / deck / visual） | `issueType`（feature / meta / spike） | 🟡 可扩展 |
+  | Agent Army 并行审查模式 | future Agent Runtime | 🔴 待实现 |
+
+  **关键约束**：unified-skills 是 gxpm 的**上游行为规范来源**，不是运行时依赖。gxpm 吸收其分层原则和纪律设计，但用 state graph + capability runtime + evidence store 重新实现为可执行产品。
+
+### 其他工程参考
+
+- **obra/superpowers** — 代理能力编排与权限管理参考  
+  路径：`/Users/x/Desktop/Project/github/superpowers`
+- **garrytan/gstack** — 全栈 Agent 工具链与部署实践参考  
+  路径：`/Users/x/Desktop/Project/github/gstack`
+- **affaan-m/everything-claude-code** — Claude Code 扩展生态与 skill 模式参考  
+  路径：`/Users/x/Desktop/Project/github/everything-claude-code`
+- **Yeachan-Heo/oh-my-codex** — Codex CLI 工作流与 hook 设计参考  
+  路径：`/Users/x/Desktop/Project/github/oh-my-codex`
+- **mattpocock/skills** — Skill 结构与类型驱动开发实践参考  
+  路径：`/Users/x/Desktop/Project/github/mattpocock-skills`
+
+## gxpm Config
+
+- worktree.enforcement: required
+- worktree.default: ask
+
+如需禁用 worktree，改为 `forbidden`。任何 `.gxpm/config.json` 中显式设置都会覆盖本段。
+
+## Commands
+
+```bash
+bun test
+bun run gen:skill-docs
+bun run check
+```
+
+## Progressive Docs
+
+- 全局纪律：`CANON.md`
+- 产品定位与架构哲学：`README.md`
+- 开发、验证、提交：`docs/governance/development-contract.md`
+- skill 模板写法：`docs/governance/template-authoring.md`
+- host adapter 扩展：`docs/governance/host-adapter.md`
+- 产品架构：`docs/architecture/`
+- 上游研究：`docs/research/`
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **gxpm** (6575 symbols, 10872 relationships, 300 execution flows). Use GitNexus MCP tools (`query`, `context`, `impact`, `detect_changes`) to understand code, assess impact, and navigate safely. If index is stale, run `npx gitnexus analyze` first.
+
+**Always Do:** run `impact` before editing any symbol; run `detect_changes` before committing; warn on HIGH/CRITICAL risk. **Never Do:** edit without impact analysis; ignore HIGH/CRITICAL risk; rename with find-and-replace; commit without `detect_changes`.
+
+Resources: `gitnexus://repo/gxpm/context` (overview), `/clusters` (functional areas), `/processes` (execution flows), `/process/{name}` (step-by-step trace). Skill files: `gitnexus-exploring`, `gitnexus-impact-analysis`, `gitnexus-debugging`, `gitnexus-refactoring`, `gitnexus-guide`, `gitnexus-cli` under `.claude/skills/gitnexus/`.
+<!-- gitnexus:end -->

package/CANON.md

@@ -0,0 +1,53 @@
+# gxpm 行为宪法
+
+> CANON.md 是 gxpm 的最高行为合同。它不描述某个具体技能怎么做，而是规定所有 Agent 在所有阶段都必须遵守的纪律。
+
+## 1. 真值优先
+
+先读本仓库真值和相关上游 skill/source，再改文件。来源冲突时，先指出冲突和建议的最小安全路径。
+
+## 2. Issue 驱动
+
+任何非平凡代码改动开始前，确认有对应 GXPM-N issue 处于正确阶段；否则先 `gxpm issue create --auto-id` 并走完 triage → plan → dispatch。
+
+## 3. Phase 不可臆测
+
+不从聊天记忆推断 phase 或完成状态。不确定下一步时，统一查 `gxpm issue next <id>`，不要自己拼 CLI。
+
+## 4. Artifact 先决
+
+Phase 推进前先写完 artifact，再 `gxpm issue transition`。不要直接编辑 `.gxpm/issues/<id>/*.json`，统一通过 `gxpm artifact write` / `gxpm artifact edit`。
+
+## 5. 设计落盘
+
+方案、取舍、替代选项必须写到对应 artifact（triage-report / implementation-plan / ADR 等），不能只留在聊天里。下一个会话只读 `.gxpm/issues/<id>/` 也能恢复上下文是底线。
+
+## 6. 生成物纪律
+
+编辑 skill 时改 `*.tmpl`，再运行 `bun run gen:skill-docs`。生成物冲突只能通过模板和生成器解决，再重新生成。不手改生成产物当真值。
+
+## 7. Worktree 隔离
+
+进入 implement 前 `git status -sb` 检查未追踪文件；如有 3+ 个来源不明文件，默认走独立 worktree 隔离。`git worktree add` 之后必须 `cd` 进新 worktree 才能动代码。
+
+## 8. 证据可复核
+
+browser/QA/review/ship 相关结论必须落到可复核证据。汇报包含路径、命令和验证证据。
+
+## 9. 安全门控
+
+destructive cleanup、发布、合并、远端写操作前必须确认。不把 gxpm 写成 PMC/gstack wrapper，不引入 PMC/gstack 运行时依赖。不做 yes-machine。
+
+## 10. 失败归因
+
+不声称历史失败与本次无关，除非有 base/main 对照证据或仓库已有记录证明该失败是基线噪声。
+
+## 约束层级
+
+```text
+CANON.md
+  ├─ 约束 Command：阶段不能跳过必要门控
+  ├─ 约束 Agent：角色不能越权自证通过
+  ├─ 约束 Skill：技能只能增加纪律，不能放松宪法
+  └─ 约束 Artifact：产物必须留下可审计证据
+```

package/CLAUDE.md

@@ -0,0 +1,60 @@
+# gxpm Claude Bootstrap
+
+本文件只承担 Claude Code 的薄启动层。共享执行合同以 `AGENTS.md` 为准。
+
+## Load Order
+
+1. 先读 `AGENTS.md`。
+2. 涉及开发规范时读 `docs/governance/development-contract.md`。
+3. 涉及 skill 文档或 prompt 模板时读 `docs/governance/template-authoring.md`。
+4. 涉及 Codex/Claude/未来 host 输出时读 `docs/governance/host-adapter.md`。
+
+## Claude-Specific Notes
+
+- 不要把 `/pm` 当 gxpm 的最终入口；PMC 只作为上游参考。
+- 不要把 `/qa`、`/review`、`/ship` 的 gstack 实现直接 vendoring 到 gxpm；先抽象为 gxpm capability。
+- 如果本地 `.claude/` 未来被脚手架生成或 symlink 到工作区，先确认 live install 风险，再改模板或生成器。
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **gxpm** (6575 symbols, 10872 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/gxpm/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/gxpm/clusters` | All functional areas |
+| `gitnexus://repo/gxpm/processes` | All execution flows |
+| `gitnexus://repo/gxpm/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

package/CONTEXT.md

@@ -0,0 +1,49 @@
+# gxpm Shared Language (CONTEXT.md)
+
+> This file is the single source of truth for domain terminology used across the gxpm project.
+> Update it inline during `/grill` sessions when terms are resolved or sharpened.
+
+## Language
+
+**Issue tracker**:
+The tool that hosts a repo's issues — GitHub Issues, Linear, a local `.gxpm/issues/` markdown convention, or similar.
+_Avoid_: backlog manager, backlog backend, issue host
+
+**Issue**:
+A single tracked unit of work inside an **Issue tracker** — a bug, task, PRD, or slice produced by `/planning`.
+_Avoid_: ticket (use only when quoting external systems that call them tickets)
+
+**Triage role**:
+A canonical state-machine label applied to an **Issue** during triage (e.g. `needs-triage`, `ready-for-agent`). Each role maps to a real label string in the **Issue tracker** via `docs/agents/triage-labels.md`.
+
+**Phase**:
+A canonical stage in the gxpm delivery pipeline: `triage` → `plan` → `dispatch` → `implement` → `local-verify` → `ac-check` → `self-review` → `ship` → `pr-check` → `verify` → `qa` → `land`.
+
+**Artifact**:
+A machine-readable JSON document persisted under `.gxpm/issues/<id>/artifacts/`. Each phase transition requires a specific artifact type as gate evidence.
+
+**Autopilot Grant**:
+A persisted `autopilot-grant` artifact that records the user's explicit authorization for an agent to complete a gxpm workflow autonomously within a named profile, including allowed actions, hard stops, and lifecycle status.
+
+**Worktree**:
+A git worktree used to isolate feature branch development from the canonical main checkout.
+
+**Claim**:
+A soft-state lock indicating which session is currently executing an issue. Not a write lock — ownership records the latest writing session for hook warnings.
+
+**Skill**:
+A reusable agent capability loaded by the host (Codex/Claude). Each skill is a self-contained directory with a `SKILL.md` file. gxpm skills live under `skills/` and are installed to the host's skill directory.
+
+## Relationships
+
+- An **Issue tracker** holds many **Issues**
+- An **Issue** carries one **Triage role** at a time
+- An **Issue** progresses through one **Phase** at a time
+- A **Phase** transition requires one **Artifact**
+- An **Autopilot Grant** may authorize autonomous execution for one **Issue**
+- A **Session** may **Claim** one **Issue** at a time
+
+## Flagged ambiguities
+
+- "backlog" was previously used to mean both the *tool* hosting issues and the *body of work* inside it — resolved: the tool is the **Issue tracker**; "backlog" is no longer used as a domain term.
+- "backlog backend" / "backlog manager" — resolved: collapsed into **Issue tracker**.

package/DEBUG.md

@@ -0,0 +1,59 @@
+# GXPM-111 Test Baseline Debug Notes
+
+## Observations
+
+- `bun test test/install-skill.test.ts --timeout 30000` reproduces a hard failure at `test/install-skill.test.ts:77`.
+- The failing assertion expects `gxpm-explore-codebase/scripts/summarize-communities.ts` to be installed.
+- `rg --files skills | rg '/scripts/'` returns no skill script files in the current repository.
+- `scripts/discover-skills.ts` only reports `scripts/` files that physically exist beside a skill.
+- `core/state.ts` and `core/artifacts.ts` fire-and-forget `maybeSyncIssue()` after issue creation, phase transitions, artifact writes, and archive changes.
+- `core/issue-sync.ts` resolves sync config through `getConfigValue()`, whose precedence is env -> repo config -> global config. That means ordinary temp-root tests can inherit live Linear sync from the shell or global gxpm config.
+- Prior baseline checks showed `issue-list` becomes stable when sync is explicitly disabled, while dedicated `issue-sync.test.ts` passes with repo-local fake Linear config.
+
+## Hypotheses
+
+### H1: Ordinary tests inherit live sync configuration from env/global config (ROOT HYPOTHESIS)
+
+- Supports: issue-heavy tests create many local issues, and issue creation triggers `maybeSyncIssue()` asynchronously.
+- Supports: `getConfigValue()` reads env/global config even when a test passes an isolated temp root.
+- Supports: disabling sync made `issue-list` stable, while repo-local fake sync tests still pass.
+- Conflicts: none found.
+- Test: add test-runtime sync isolation so only repo-local `.gxpm/config.json` can enable sync under `NODE_ENV=test`, then rerun `issue-list` and `issue-sync`.
+
+### H2: issue-list itself has inefficient list/archive logic
+
+- Supports: failures concentrate in tests that create many issues.
+- Conflicts: the same tests stabilize when sync is disabled, pointing outside list logic.
+- Test: rerun `issue-list` after sync isolation without changing list code.
+
+### H3: install-skill implementation dropped script copying
+
+- Supports: failing test is about script installation.
+- Conflicts: `discoverScripts()` and `installSkill()` still copy discovered script files; the repository simply has no `skills/**/scripts/*` assets.
+- Test: change the stale real-repo expectation and keep script discovery covered by fixture-based tests.
+
+## Experiments
+
+- Reproduced `install-skill.test.ts` failure on the stale hard-coded script path.
+- Inspected `discover-skills.ts` and `install-skill.ts`; script install behavior is data-driven and only copies existing files.
+- Inspected `issue-sync.ts`, `state.ts`, and `artifacts.ts`; temp-root issue operations can trigger external sync through inherited config.
+- After test-runtime sync isolation, `bun test test/issue-list.test.ts --timeout 30000` passed 23 tests in 6.70s.
+- After replacing the stale real-repo script assertion with fixture coverage, `bun test test/install-skill.test.ts --timeout 30000` passed 7 tests.
+- After adding env/global sync isolation coverage, `bun test test/issue-sync.test.ts --timeout 30000` passed 12 tests.
+
+## Root Cause
+
+The baseline combines two existing drifts: ordinary tests can accidentally inherit live sync configuration despite using temp roots, and `install-skill.test.ts` still expects a skill script file that no longer exists in this repository.
+
+## Fix Plan
+
+- Isolate sync config during `NODE_ENV=test` so env/global sync cannot activate ordinary temp-root tests; allow repo-local sync config for dedicated fake Linear tests.
+- Restore environment cleanup in sync tests for all sync-related env vars.
+- Replace the stale script expectation in `install-skill.test.ts` with a current contract: references install from the repo, and missing script assets are not invented.
+- Verify with focused tests, full `bun test --timeout 30000`, `bun run check`, and `git diff --check`.
+
+## Fix
+
+- `core/issue-sync.ts` now resolves sync values through a test-aware helper. In `NODE_ENV=test`, unless `GXPM_TEST_ALLOW_LIVE_SYNC=1` is set, only repo-local `.gxpm/config.json` can enable sync.
+- `test/issue-sync.test.ts` now restores sync-related env vars and verifies env/global sync config is ignored during tests.
+- `test/install-skill.test.ts` now keeps repository reference installation coverage and uses a temp fixture to prove script assets are copied when a skill actually owns them.

package/ISSUE_CONTEXT.md

@@ -0,0 +1,25 @@
+# ISSUE_CONTEXT — GXPM-138
+
+> 这是 gxpm 自动生成的上下文恢复文件。
+> 如果 AI 代理忘记了当前正在处理的 issue，请阅读此文件。
+
+- **Issue ID**: `GXPM-138`
+- **当前阶段**: `implement`
+- **分支**: `gxpm-GXPM-138`
+- **工作目录**: `/Users/x/Desktop/Project/gxpm/.gxpm/worktrees/gxpm-GXPM-138`
+- **更新时间**: 2026-05-20T01:09:27.405Z
+
+## 快速恢复
+
+如果你忘记了当前 issue，运行以下命令恢复上下文：
+
+```bash
+gxpm issue context --auto
+```
+
+## 下一步
+
+下一阶段: `local-verify`
+
+---
+*此文件由 gxpm 自动生成，请勿手动编辑。*

package/README.md

@@ -0,0 +1,143 @@
+# gxpm
+
+> **AI Agent 工作制度架构 + 工作流 + 状态机的可执行产品**
+>
+> 形态：基于文档驱动的制度套件 + CLI 运行时
+
+gxpm 是给 AI Agent 建立的一套**"公司制操作系统"**：以 Markdown/JSON 文档承载治理规则与角色契约，以 CLI 运行时解析执行这些规则，驱动 Agent 在严格状态机中按 phase 交付，最终以 commit 切分阶段边界，以 skill 注入专业能力，将所有证据与事实持久化到本地文件系统，实现可审计、可中断、可恢复的全自动 issue 交付闭环。
+
+它面向完全替代 PMC 和 gstack，会系统吸收两者已验证有效的能力，然后重构成统一的原生产品：
+
+- 从 PMC 继承 Linear-first 项目管理、issue phase、状态门禁、交付产物和可恢复执行。
+- 从 gstack 继承技能框架、浏览器 runtime、QA/review/ship/investigate 流水线、上下文恢复、自学习和团队化安装。
+- 在 gxpm 中重新定义统一的 state graph、capability runtime、agent execution loop、browser evidence layer 和 release governance。
+
+它不是 PMC 的兼容壳，也不是 gstack 的插件集合。所有设计都服务于**独立产品闭环**。
+
+---
+
+## 架构哲学
+
+### 四维分工
+
+| 维度 | 职责 | 在 gxpm 中的体现 |
+|---|---|---|
+| **commit** | 阶段切分 | git worktree 隔离 + phase transition，物理与逻辑双重边界 |
+| **Agent** | 角色分工 | triage/plan/implement/review/QA/land owner，责任视角而非人格模板 |
+| **skill** | 能力注入 | `skills/*/SKILL.md` 可发现、可加载、可校验的方法目录 |
+| **证据/事实** | 持久存储 | `artifacts/*.json` + `evidence/` + `state.json`，本地文件系统为唯一真值 |
+
+### 五层架构
+
+```
+L1: 制度文档层 (Document Governance)
+    CANON.md / AGENTS.md / CONTEXT.md / docs/governance/*.md
+    ── 定义不可破坏的规则、术语、开发合同、架构决策
+
+L2: 角色与技能层 (Agent & Skill Surface)
+    agents/*.md / skills/*/SKILL.md / templates/*.tmpl
+    ── Agent 是责任视角，Skill 是可加载能力，均通过文档声明契约
+
+L3: 工作流编排层 (Workflow Orchestration)
+    workflows/*.yml / core/phase-gates.ts / PHASE_GATE_RULES
+    ── 12-phase pipeline，每步有输入 artifact、输出 artifact、gate 规则
+
+L4: 状态机执行层 (State Machine Runtime)
+    core/state.ts / core/capabilities.ts / CLI commands
+    ── 强制执行 transition 顺序，检查 worktree/artifact gate，写事件日志
+
+L5: 证据与恢复层 (Evidence & Recovery Store)
+    .gxpm/issues/<id>/{state,artifacts,evidence,memory}/
+    ── 文件系统为唯一真值，支持新会话零上下文恢复
+```
+
+### 核心原则
+
+1. **文档即制度，制度可执行** —— 治理规则以文本形式存在，被 CLI 解析、被模板引擎生成、被 hook 校验、被 Agent 加载。
+2. **本地 state 永远比外部系统更权威** —— phase JSON artifact 比 markdown report 更权威；`state.json` 比 Linear comment、PR body、聊天上下文更权威。
+3. **所有 transition 都必须可审计、可重放、可恢复** —— 事件 append-only 写入 `events.jsonl`，`graph.json` 记录完整 transition 历史。
+4. **Command 只路由，Agent 只担责，Skill 只注入，Artifact 只存真值** —— 分层边界不可漂移。
+
+---
+
+## 初始化产物
+
+- `AGENTS.md`：本仓库代理规则。
+- `CANON.md`：全局行为宪法。
+- `CONTEXT.md`：共享语言与领域术语表。
+- `package.json`：Bun/TypeScript 脚手架入口。
+- `hosts/`：Codex 与 Claude Code 的 host adapter 注册。
+- `scripts/`：skill 模板发现、生成和脚手架检查。
+- `bin/`：未来安装/升级/检查命令的稳定入口。
+- `docs/governance/`：代理开发规范、模板写法和 host adapter 治理。
+- `docs/research/pmc-gstack-skill-study.md`：PMC 与 gstack 的调查结论。
+- `docs/architecture/gxpm-replacement-architecture.md`：替代型二代架构。
+- `docs/architecture/gxpm-v0-contract.md`：gxpm V0 合同与边界。
+- `docs/architecture/layered-workflow-boundaries.md`：分层工作流边界。
+- `docs/architecture/scaffold-northstar.md`：借鉴 gstack 的脚手架北极星。
+- `docs/roadmap/initial-roadmap.md`：初始路线图。
+- `skills/gxpm/SKILL.md.tmpl`：gxpm skill 模板真值。
+- `skills/gxpm/SKILL.md`：由模板生成的 gxpm skill 入口。
+
+---
+
+## 快速开始
+
+```bash
+git clone https://github.com/laozhong86/gxpm.git ~/gxpm && cd ~/gxpm
+bun install && bun link
+
+cd /path/to/your/project
+gxpm init                      # 初始化项目（hooks + skills + config）
+gxpm doctor --json             # 健康检查
+gxpm verify                    # 端到端验证
+```
+
+Agent 自举协议见 `docs/INSTALL_FOR_AGENTS.md`。
+
+---
+
+## 本地命令
+
+```bash
+bun test
+bun run gen:skill-docs
+bun run check
+
+gxpm issue create --auto-id
+gxpm issue status <id>
+gxpm doctor --fix
+gxpm upgrade
+gxpm verify
+
+bin/gxpm workspace plan local-demo
+bin/gxpm run list local-demo
+bin/gxpm orchestrator tick --dry-run
+bin/gxpm artifact list local-demo
+bin/gxpm artifact read local-demo acceptance-contract
+```
+
+完整 phase gate 命令由 `skills/gxpm/SKILL.md` 生成，真值来自 `core/phase-gates.ts`。
+
+---
+
+## 行为规范参考框架
+
+gxpm 的分层架构设计直接继承并转译自 [ZeroZ-lab/unified-skills](https://github.com/ZeroZ-lab/unified-skills) 的四层分离制度：
+
+| 层 | unified-skills | gxpm |
+|---|---|---|
+| 宪法 | CANON.md（10 条行为宪法） | CANON.md（10 条行为宪法） |
+| 阶段协议 | 12 个 Command（/refine /plan /build /review /ship） | 12-phase state machine + CLI commands |
+| 角色责任 | 24 个 Agent（7 核心 + 17 审查/侦察） | `agents/*.md` + future Agent Runtime |
+| 能力注入 | 53 个 Skill（SKILL.md） | `skills/*/SKILL.md`（host-facing） |
+| 产物链 | `docs/features/YYYYMMDD-<name>/` | `.gxpm/issues/<id>/artifacts/*.json` |
+| 治理检查 | `./validate` | `bun run check` + `scripts/scaffold-check.ts` |
+
+unified-skills 是 gxpm 的**上游行为规范来源**，不是运行时依赖。gxpm 吸收其分层原则和纪律设计，但用 state graph + capability runtime + evidence store 重新实现为可执行产品。
+
+本地参考路径：`/Users/x/Desktop/Project/github/unified-skills`
+
+## 当前边界
+
+当前已具备脚手架、host adapter、生成检查、`.gxpm` state graph、phase artifact gate、checkpoint/resume、原生 wiki init/update/query/context/eval，以及第一批 execution runtime 原语：run ledger、workspace runtime 和只读 orchestrator dry-run。下一步应继续把 PMC/gstack 能力拆成 gxpm 原生模块，并围绕 V0 最小替代闭环补齐真实 agent run、browser evidence 和 release governance。

package/VERSION

@@ -0,0 +1 @@
+0.1.0.0

package/agents/cleanup-auditor/cleanup-auditor.md

@@ -0,0 +1,56 @@
+---
+name: cleanup-auditor
+description: 跨 issue 代码清理审计。负责在 cleanup 阶段审查多 issue worktree 合并后的代码质量，识别重复、命名不一致、接口错位和死代码。
+role: quality
+---
+
+# Agent: Cleanup Auditor
+
+## 负责
+- 扫描同一 worktree 下多个 issue 的代码变更，识别重复逻辑
+- 检查跨 issue 的命名一致性（函数、类型、变量）
+- 验证 issue 之间的接口是否对齐（输入/输出格式、错误处理）
+- 识别被后续 issue 替代但未删除的死代码
+- 检查测试覆盖是否有冗余（同一边界条件被多个 issue 测试）
+
+## 不负责
+- 单 issue 内部的代码质量（Code Quality Reviewer 的职责）
+- 安全漏洞扫描（Security Reviewer 的职责）
+- 性能优化（Performance Auditor 的职责）
+- 实际执行重构（只识别问题，不修改代码）
+
+## 输入
+- 当前 worktree 中所有 issue 的代码变更 diff
+- 各 issue 的 implementation-plan 和 behavior-spec
+- 现有代码库的术语表（CONTEXT.md）
+- cleanup-report artifact（初始为空，由本角色填充）
+
+## 输出
+- `cleanup-report` artifact 中的审计发现
+- 每条 finding 包含：category（duplicate/rename/interface/dead-code/test-dedup）、location、rationale、recommendation
+
+## 审查维度
+
+| 维度 | 检查点 |
+|------|--------|
+| 重复代码 | 两个+ issue 是否引入了功能相同的函数/模块 |
+| 命名一致性 | 同一概念在不同 issue 中是否使用不同名称 |
+| 接口对齐 | Issue A 的输出是否是 Issue B 期望的输入格式 |
+| 死代码 | 某个 issue 的实现是否被后续 issue 完全替代 |
+| 测试冗余 | 多个 issue 的测试是否覆盖了相同的边界条件 |
+
+## 红旗清单 / HARD-GATE
+
+- **同一 worktree 中存在功能完全重复的模块（未提取）** → Blocking
+- **跨 issue 的接口格式不兼容且无转换层** → Blocking
+- **死代码占比 > 10%** → Important
+- **同一概念有 3+ 种不同命名** → Important
+- **测试冗余导致 CI 时间增加 > 20%** → Important
+
+## 验证清单
+
+- [ ] 所有 issue 的变更范围已扫描
+- [ ] 重复代码已标记并推荐提取位置
+- [ ] 命名不一致已列出统一建议
+- [ ] 接口错位已说明影响范围和修复方案
+- [ ] 死代码已列出删除理由

package/agents/grill-master.md

@@ -0,0 +1,26 @@
+---
+name: grill-master
+description: 压力测试计划与假设。负责在交付前暴露计划中的盲区、矛盾和不一致。
+---
+
+# Agent: Grill Master
+
+## 负责
+- 对照领域模型质疑计划中的每个决策
+- 精炼术语，确保上下文中的词汇一致
+- 内联更新 `CONTEXT.md` 和 ADR 作为决策结晶
+- 在 triage 和 plan 阶段暴露盲区
+
+## 不负责
+- 替用户做最终决定（只暴露问题，不裁决）
+- 直接执行实现（Implementer 的职责）
+- 定义工作流状态机（Command 的职责）
+
+## 调用 Skill
+- `gxpm-grill` — 压力测试方法论与流程
+- `gxpm-architecture` — 架构深度分析（需要时）
+
+## 输出
+- 澄清后的 scope 和 acceptance criteria
+- 更新后的 `CONTEXT.md`（术语和决策）
+- ADR（架构决策记录）

package/agents/implementer.md

@@ -0,0 +1,32 @@
+---
+name: implementer
+description: 增量实现与四维自审。负责将已批准的计划转化为可验证的代码变更。
+---
+
+# Agent: Implementer
+
+## 负责
+- 按已批准的 `implementation-plan` 和 `dispatch-handoff` 执行增量实现
+- 编写测试并验证实现（编译、类型检查、功能测试）
+- 执行四维自审：Completeness / Quality / Discipline / Testing
+- 遇到阻塞时及时升级（BLOCKED / NEEDS_CONTEXT），不猜测
+- 遵循现有代码模式和架构约束
+
+## 不负责
+- 定义整个工作流状态机（Command 的职责）
+- 修改 CANON 纪律（CANON 是上层合同）
+- 把方法论复制到自己内部（方法论应在 Skill）
+- 无计划指导时自行拆分文件或重构范围外代码
+
+## 调用 Skill
+- `gxpm-implementer` — 实现方法论与报告格式
+- `gxpm-build` — 编译与类型检查验证
+- `gxpm-verify` — 本地验证管道执行
+- `gxpm-hygiene` — 提交卫生与原子提交纪律
+- `gxpm-debug-issue` — 调试与根因分析（失败时）
+- `gxpm-refactor-safely` — 安全重构（需要时）
+
+## 输出
+- 代码变更（feature branch 上的 commit）
+- 自审报告（DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT）
+- 测试证据与验证结果