@geminix/gxpm 0.1.0

package/docs/README.md

@@ -0,0 +1,57 @@
+# gxpm 文档体系
+
+本文档目录采用结构化分类模式，确保工程决策、最佳实践和平台规范可跨会话恢复。
+
+## 目录结构
+
+```
+docs/
+├── README.md                          # 本文件：文档体系导航
+├── brainstorms/                       # 需求文档与问题探索
+│   ├── README.md
+│   └── *-requirements.md
+├── plans/                             # 实现计划与技术方案
+│   ├── README.md
+│   └── *-plan.md
+├── solutions/                         # 最佳实践、恢复手册、决策记录
+│   ├── README.md
+│   └── *.md（含 frontmatter）
+├── specs/                             # Host 平台规范镜像
+│   ├── README.md
+│   └── claude.md / codex.md / cursor.md
+├── architecture/                      # 架构设计文档（存量）
+├── governance/                        # 治理契约与规范（存量）
+├── research/                          # 上游研究与调研（存量）
+├── roadmap/                           # 产品路线图（存量）
+├── migrations/                        # 迁移指南（存量）
+├── agents/                            # Agent 相关文档（存量）
+├── GXPM_VERIFY.md                     # 验证清单
+└── INSTALL_FOR_AGENTS.md              # 代理安装指南
+```
+
+## 快速导航
+
+| 场景 | 目标目录 |
+|------|----------|
+| 新功能需求探索 | `docs/brainstorms/` |
+| 制定实现计划 | `docs/plans/` |
+| 记录故障恢复步骤 | `docs/solutions/` |
+| 查看 host 平台约束 | `docs/specs/` |
+| 理解系统设计 | `docs/architecture/` |
+| 查阅开发规范 | `docs/governance/` |
+
+## 新会话恢复上下文
+
+1. 读取 `AGENTS.md`（项目根目录）— 代理契约
+2. 读取 `CONTEXT.md`（项目根目录）— 共享术语表
+3. 按需查阅 `docs/solutions/` — 工程决策与恢复手册
+4. 按需查阅 `docs/specs/<host>.md` — 当前 host 平台规范
+5. 运行 `./bin/gxpm issue list` — 查看当前 issue 状态
+
+## 维护约定
+
+- **solutions/** 文档必须包含 YAML frontmatter（title, category, date, severity, component, tags）
+- **brainstorms/** 采用 `*-requirements.md` 命名
+- **plans/** 采用 `*-plan.md` 命名
+- 每次重大决策后同步更新 solutions/
+- 每次 host 适配变更后同步更新 specs/

package/docs/adr/adr-005-multi-platform-skill-converter.md

@@ -0,0 +1,72 @@
+# ADR-005: 多平台插件转换/分发基础设施
+
+## 状态
+
+Accepted — 最小可行实现已完成（GXPM-80）。
+
+## 背景
+
+gxpm 当前通过 `scripts/gen-skill-docs.ts` 和 `scripts/install-skill.ts` 将 skill 从源格式（`.tmpl` 模板 + 静态 `.md`）分发到目标宿主（Codex CLI、Claude Code、Cursor）。
+
+现有管道的问题：
+1. **Ad-hoc 转换**：`gen-skill-docs.ts` 使用简单的字符串替换（`replaceAll`）渲染模板，没有正式的解析层。
+2. **平台差异硬编码**：frontmatter 过滤、env var 注入、preamble 生成等逻辑散落在 `gen-skill-docs.ts` 和 `install-skill.ts` 中。
+3. **无托管区块**：生成的 SKILL.md 是完整覆盖的，用户无法在生成内容之间插入自定义内容而不被下次生成覆盖。
+4. **扩展成本高**：新增宿主平台需要同时修改 `gen-skill-docs.ts` 和 `install-skill.ts`。
+
+## 决策
+
+引入 **parser → converter → target-writer** 三层转换架构，作为 gxpm skill 分发的正式基础设施。
+
+### 源格式（Canonical Source）
+
+- **模板文件**（`.tmpl`）：保留现有字符串占位符体系（`{{PREAMBLE}}`、`{{ARTIFACT_READ_COMMANDS}}` 等），因为它们在 skill 作者侧直观且有效。
+- **静态文件**（`.md`）：走新的 AST 管道，支持 frontmatter 过滤、 preamble 注入和 managed-artifacts。
+
+### 三层架构
+
+| 层级 | 职责 | 对应模块 |
+|------|------|----------|
+| Parser | 将 Markdown 解析为 `SkillDocument` AST（frontmatter + sections + managed blocks） | `core/converters/parser.ts` |
+| Converter | 根据 `HostConfig` 转换 AST（过滤 frontmatter、注入 preamble、调整结构） | `core/converters/converter.ts` |
+| TargetWriter | 将 AST 序列化为目标平台字符串，支持 managed-artifacts 合并 | `core/converters/writer.ts` |
+
+### 平台优先级
+
+1. **Codex CLI**（已有，保持兼容）
+2. **Claude Code**（已有，通过新管道增强静态文件支持）
+3. **Cursor**（后续 issue 跟进）
+
+### Managed Artifacts
+
+采用 HTML 注释标记：
+
+```markdown
+<!-- BEGIN MANAGED:section-id -->
+... generated content ...
+<!-- END MANAGED:section-id -->
+```
+
+重新生成时，Writer 会保留旧文件中的非托管内容，只替换匹配的托管区块。当前最小实现中，Writer 以生成内容为准，未来可扩展为严格合并模式。
+
+## 替代方案
+
+| 方案 | 优点 | 缺点 | 结论 |
+|------|------|------|------|
+| A. 保持现有字符串替换 | 零改动，风险低 | 无法支持 managed-artifacts，扩展性差 | 拒绝 |
+| B. 引入完整 Markdown AST（如 remark） | 解析精确 | 引入外部依赖，overkill for skill 文档 | 拒绝 |
+| C. **轻量自定义 parser + converter** | 零外部依赖，足够精确，可控 | 需要维护 parser | **采纳** |
+| D. 每个平台独立维护 skill 副本 | 平台完全自由 | 违背 "一次编写，多平台分发" 目标 | 拒绝 |
+
+## 影响
+
+- `scripts/gen-skill-docs.ts`：静态文件路径切换为新管道；`.tmpl` 路径保持字符串替换以保证向后兼容。
+- `scripts/install-skill.ts`：静态文件安装使用新管道；`.tmpl` 继续委托 `gen-skill-docs.ts`。
+- 新增 `core/contracts/converter.ts` 类型定义和 `core/converters/` 实现目录。
+- 现有测试（`test/gen-skill-docs.test.ts`）继续通过，无回归。
+
+## 后续工作
+
+- GXPM-XX：将 `.tmpl` 模板体系逐步迁移到新 AST 管道，统一字符串替换和 AST 转换。
+- GXPM-XX：为 Cursor 宿主实现专门的 `HostConverter` 扩展。
+- GXPM-XX：严格合并模式（`mergeManagedBlocksStrict`），保留用户在生成文件中的非托管自定义内容。

package/docs/agents/domain.md

@@ -0,0 +1,30 @@
+# Domain Docs Layout
+
+> Defines where domain documentation lives and how skills consume it.
+
+## Layout
+
+This repo uses a **single-context** layout:
+
+```
+/
+├── CONTEXT.md              # shared language / glossary
+├── docs/adr/               # architecture decision records
+│   ├── 0001-example-decision.md
+│   └── ...
+└── skills/                 # agent skills
+    └── ...
+```
+
+## Consumer Rules
+
+- `/grill` reads and writes `CONTEXT.md` during alignment sessions.
+- `/architecture` reads `CONTEXT.md` for domain vocabulary and `docs/adr/` for past decisions.
+- `/diagnose` and `/tdd` read `CONTEXT.md` to name tests and interfaces consistently.
+- Skills must not read implementation details into `CONTEXT.md` — only terms meaningful to domain experts.
+
+## Creating docs lazily
+
+- Create `CONTEXT.md` when the first domain term is resolved.
+- Create `docs/adr/` when the first ADR is needed.
+- Do not create empty scaffolding.

package/docs/agents/issue-tracker.md

@@ -0,0 +1,30 @@
+# Issue Tracker Configuration
+
+> Generated by gxpm setup. Edit directly when switching issue trackers.
+
+## Current Issue Tracker
+
+**Linear** — issues are tracked in Linear and synced to local `.gxpm/issues/` state.
+
+Linear serves as the **collaboration front door** (human-readable, shareable, threaded discussion). The local `.gxpm/issues/<id>/` directory is the **execution source of truth** (machine-readable state, artifacts, phase history).
+
+## Workflow
+
+1. External issues arrive via Linear.
+2. `gxpm issue create <linear-id>` creates local state for the issue.
+3. All phase transitions, artifact writes, and evidence captures happen locally.
+4. Linear remains the human collaboration layer; `.gxpm/` remains the agent execution layer.
+
+## Alternative Trackers
+
+If migrating away from Linear, the supported alternatives are:
+
+- **GitHub Issues** — uses `gh issue create` / `gh issue list` / `gh issue view`
+- **GitLab Issues** — uses `glab` CLI
+- **Local markdown** — issues live as files under `.gxpm/issues/` (good for solo projects)
+
+## Consumer Rules
+
+- Skills like `/triage`, `/planning`, and `/gxpm` read from and write to the local `.gxpm/` state.
+- Linear sync is one-directional for execution state: local state does not push back to Linear automatically.
+- When a Linear issue is referenced, prefer the local `.gxpm/issues/<id>/` state over fetching from Linear API.

package/docs/agents/triage-labels.md

@@ -0,0 +1,32 @@
+# Triage Label Vocabulary
+
+> Maps canonical triage roles to actual label strings in the issue tracker.
+> Edit when your issue tracker uses different label names.
+
+## Canonical Roles
+
+| Canonical role | Default label string | Meaning |
+|----------------|---------------------|---------|
+| `needs-triage` | `needs-triage` | Maintainer needs to evaluate |
+| `needs-info` | `needs-info` | Waiting on reporter for more information |
+| `ready-for-agent` | `ready-for-agent` | Fully specified, AFK-ready (agent can pick up with no human context) |
+| `ready-for-human` | `ready-for-human` | Needs human implementation |
+| `wontfix` | `wontfix` | Will not be actioned |
+
+## Category Roles
+
+| Canonical role | Default label string | Meaning |
+|----------------|---------------------|---------|
+| `bug` | `bug` | Something is broken |
+| `enhancement` | `enhancement` | New feature or improvement |
+
+## Usage
+
+- Every triaged issue should carry exactly one category role and one state role.
+- If state roles conflict, flag it and ask the maintainer before doing anything else.
+- The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
+
+## gxpm Integration
+
+- The `acceptance-contract` artifact includes a `triageRole` field that maps to these canonical names.
+- `gxpm issue list --type` filters by classification but does not alter phase gates.

package/docs/architecture/gxpm-architecture-diagram.md

@@ -0,0 +1,265 @@
+# gxpm 架构图
+
+> 基于 `gxpm-replacement-architecture.md` 和 `gxpm-v0-contract.md` 绘制
+
+---
+
+## 1. 顶层公式
+
+```text
+gxpm = State Graph + Capability Runtime + Evidence Store + Policy Engine + Skill Surface
+```
+
+---
+
+## 2. 整体架构图 (Mermaid)
+
+```mermaid
+flowchart TB
+    subgraph User["👤 用户 / Agent"]
+        CLI["gxpm CLI\n/gxpm triage | plan | dispatch | verify | qa | land | ship ..."]
+    end
+
+    subgraph SkillSurface["🎤 Skill Surface"]
+        CMD_Triage["gxpm triage"]
+        CMD_Plan["gxpm plan"]
+        CMD_Dispatch["gxpm dispatch"]
+        CMD_Implement["gxpm implement"]
+        CMD_Verify["gxpm verify"]
+        CMD_QA["gxpm qa"]
+        CMD_Land["gxpm land"]
+        CMD_Ship["gxpm ship"]
+        CMD_Review["gxpm review"]
+        CMD_Investigate["gxpm investigate"]
+        CMD_Learn["gxpm learn"]
+    end
+
+    subgraph Core["🔧 gxpm Core (统一控制面)"]
+        direction TB
+
+        subgraph StateGraph["📊 State Graph"]
+            Issue["Issue 状态机"]
+            Phase["Phase 阶段\ntriage → plan → dispatch → implement → local-verify → ac-check → self-review → ship → pr-check → verify → qa → land"]
+            Transition["Transition Gate\n(严格顺序 + artifact 校验)"]
+            Graph["Graph.json\n(依赖图 / 阻塞关系)"]
+        end
+
+        subgraph PolicyEngine["⚖️ Policy Engine"]
+            Gate["Gate 判定\n(能进入下一阶段吗?)"]
+            AC["Acceptance Criterion\n(哪些需要 browser evidence?)"]
+            Risk["Risk Profile\n(fast / standard / high-risk / regression)"]
+            Confirm["不可逆操作确认\n(land/merge/deploy)"]
+        end
+
+        subgraph CapabilityRuntime["🚀 Capability Runtime"]
+            IssueRT["issueRuntime\n(Linear/GitHub sync)"]
+            ExecRT["executionRuntime\n(worktree / dispatch / verify)"]
+            ReviewRT["reviewRuntime\n(diff / specialist / adversarial)"]
+            BrowserRT["browserRuntime\n(QA / screenshot / console)"]
+            ReleaseRT["releaseRuntime\n(PR / version / changelog)"]
+            MemoryRT["memoryRuntime\n(timeline / learn / resume)"]
+            SkillRT["skillRuntime\n(discovery / routing / template)"]
+        end
+
+        subgraph EvidenceStore["📁 Evidence Store"]
+            State["state.json"]
+            Artifacts["artifacts/*.json\n(acceptance-contract, dispatch-handoff,\nlocal-verify, qa-findings, land-findings...)"]
+            Evidence["evidence/\n(screenshots, console.jsonl,\nnetwork.jsonl, commands.jsonl)"]
+            Memory["memory/\n(resume-packet.json, checkpoints/)"]
+            Runs["runs/\n(run-ledger, 审计日志)"]
+        end
+    end
+
+    subgraph External["🌐 外部系统"]
+        Linear["Linear (Issue Provider)"]
+        GitHub["GitHub (PR / Code)"]
+        Browser["Browser / QA 环境"]
+    end
+
+    subgraph Hosts["💻 Host Adapters"]
+        Codex["Codex CLI"]
+        Claude["Claude Code"]
+        OpenClaw["OpenClaw / 其他"]
+    end
+
+    subgraph Codebase["📂 代码库"]
+        Worktree["git worktree\n(隔离开发)"]
+        Source["源代码"]
+    end
+
+    %% === 连接关系 ===
+    User --> CLI
+    CLI --> SkillSurface
+
+    SkillSurface --> StateGraph
+    SkillSurface --> CapabilityRuntime
+
+    StateGraph <-- "读写 state / graph" --> EvidenceStore
+    CapabilityRuntime <-- "写入 evidence / artifacts" --> EvidenceStore
+    CapabilityRuntime --> PolicyEngine
+    PolicyEngine --> StateGraph
+
+    IssueRT --> Linear
+    ReleaseRT --> GitHub
+    BrowserRT --> Browser
+    ExecRT --> Worktree
+
+    Hosts --> CLI
+    Codebase --> ExecRT
+```
+
+---
+
+## 3. 核心数据流
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as 用户 / Agent
+    participant SS as Skill Surface
+    participant SG as State Graph
+    participant PE as Policy Engine
+    participant CR as Capability Runtime
+    participant ES as Evidence Store
+    participant EX as 外部系统 (Linear/GitHub)
+
+    U->>SS: gxpm triage init GXPM-001
+    SS->>SG: 读取当前 phase (triage)
+    SG->>PE: 请求 gate 判定
+    PE-->>SG: 允许 (当前 phase = triage)
+    SS->>CR: 调用 issueRuntime + planning
+    CR->>EX: 从 Linear 读取 issue 详情
+    CR->>ES: 写入 artifact: acceptance-contract.json
+    CR-->>SS: 返回 triage 结果
+    SS->>SG: 推进 phase: triage → plan
+    SG->>ES: 更新 state.json + events.jsonl
+    SS-->>U: 完成 triage
+
+    U->>SS: gxpm plan init GXPM-001
+    SS->>SG: 读取 phase (plan)
+    SG->>PE: gate 判定 (需 acceptance-contract)
+    PE->>ES: 检查 artifacts/acceptance-contract.json
+    ES-->>PE: 存在 ✓
+    PE-->>SG: 允许
+    SS->>CR: 调用 planning capability
+    CR->>ES: 写入 artifact: implementation-plan.json
+    SS->>SG: 推进 phase: plan → dispatch
+    SG->>ES: 更新 state
+    SS-->>U: 完成 plan
+
+    Note over U,EX: ... 各阶段以此类推 ...
+
+    U->>SS: gxpm qa land GXPM-001
+    SS->>SG: 读取 phase (qa)
+    SG->>PE: gate 判定 (需 qa-findings, land-findings)
+    PE->>ES: 检查所有前置 artifacts
+    ES-->>PE: 全部存在 ✓
+    PE->>PE: 判定是否涉及不可逆操作
+    PE-->>U: 请求用户确认
+    U-->>PE: 确认
+    PE-->>SG: 允许
+    SS->>CR: 调用 releaseRuntime
+    CR->>EX: GitHub merge PR
+    SS->>SG: 推进 phase: qa → land
+    SG->>ES: 最终 state 更新
+    SS-->>U: land 完成
+```
+
+---
+
+## 4. V0 本地目录结构 (Evidence Store 实体)
+
+```text
+.gxpm/
+└── issues/<issue-id>/
+    ├── state.json              ← 状态机真值
+    ├── graph.json              ← 依赖/阻塞关系
+    ├── events.jsonl            ← 阶段转换审计日志
+    ├── artifacts/
+    │   ├── index.json
+    │   ├── acceptance-contract.json
+    │   ├── implementation-plan.json
+    │   ├── dispatch-handoff.json
+    │   ├── local-verify.json
+    │   ├── acceptance-check.json
+    │   ├── self-review.json
+    │   ├── ship-readiness.json
+    │   ├── pr-check.json
+    │   ├── verify-findings.json
+    │   ├── qa-findings.json
+    │   └── land-findings.json
+    ├── reports/                ← (未来) Markdown 渲染视图
+    ├── 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
+```
+
+---
+
+## 5. 真值优先级金字塔
+
+```text
+        ┌─────────────────┐
+        │  phase JSON     │  ← 最高真值
+        │  artifacts      │
+        ├─────────────────┤
+        │   state.json    │
+        ├─────────────────┤
+        │ resume-packet   │
+        ├─────────────────┤
+        │ rendered md     │
+        │ reports         │
+        ├─────────────────┤
+        │ Linear comments │
+        │ PR body         │
+        │ chat history    │  ← 最低真值
+        └─────────────────┘
+```
+
+---
+
+## 6. 与上游项目的关系
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                        gxpm (二代产品)                       │
+│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
+│  │  State Graph │  │ Capability   │  │   Evidence Store    │ │
+│  │  (统一状态机)│  │ Runtime      │  │   (统一证据层)       │ │
+│  └─────────────┘  │ (统一能力)   │  └─────────────────────┘ │
+│                   └──────────────┘                          │
+│                           ▲                                 │
+│         ┌─────────────────┴─────────────────┐               │
+│         ▼                                   ▼               │
+│   ┌─────────────┐                   ┌─────────────┐         │
+│   │    PMC      │  ── 吸收/迁移 ──▶ │  gxpm Core  │         │
+│   │(phase gate, │                   │ (native)    │         │
+│   │ checkpoint) │                   │             │         │
+│   └─────────────┘                   └─────────────┘         │
+│   ┌─────────────┐                   ┌─────────────┐         │
+│   │   gstack    │  ── 吸收/迁移 ──▶ │  gxpm Core  │         │
+│   │(browser QA, │                   │ (native)    │         │
+│   │ review,ship)│                   │             │         │
+│   └─────────────┘                   └─────────────┘         │
+│                                                             │
+│   原则：PMC/gstack 是上游研究对象与能力来源，不是长期运行时依赖   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+*生成时间: 2026-05-02*
+*来源文档: `docs/architecture/gxpm-replacement-architecture.md`, `docs/architecture/gxpm-v0-contract.md`*

package/docs/architecture/gxpm-current-architecture.md

@@ -0,0 +1,175 @@
+# gxpm 当前系统架构图（v0）
+
+> 绘制日期：2026-05-02
+> 目的：可视化当前 gxpm 的组件关系与数据流，作为重构规划的基线
+
+---
+
+## 1. 系统分层架构图
+
+```mermaid
+graph TB
+    subgraph "External Systems"
+        LINEAR["Linear<br/>Issue Tracker"]
+        GITNEXUS["GitNexus<br/>MCP Server"]
+        GIT["Git Repository"]
+    end
+
+    subgraph "Host Layer"
+        CODEX["Codex CLI<br/>OpenAI"]
+        CLAUDE["Claude Code<br/>Anthropic"]
+    end
+
+    subgraph "Skill Layer"
+        direction TB
+        SKILL_GXPM["skills/gxpm/<br/>SKILL.md.tmpl"]
+        SKILL_GEN["scripts/<br/>gen-skill-docs.ts"]
+        SKILL_OUT["skills/gxpm/<br/>SKILL.md<br/>(generated)"]
+        SKILL_INST["scripts/<br/>install-skill.ts"]
+        SKILL_DEV["scripts/<br/>dev-skill.ts"]
+        SKILL_ORPHAN[".claude/skills/<br/>*.md<br/>(4 orphans)"]
+    end
+
+    subgraph "Hook Layer"
+        GIT_HOOKS[".githooks/<br/>pre-commit, commit-msg,<br/>pre-push, post-merge"]
+        CODEX_HOOKS[".codex/hooks/<br/>SessionStart,<br/>UserPromptSubmit"]
+    end
+
+    subgraph "CLI Layer (bin/)"
+        CLI_MAIN["gxpm<br/>main CLI"]
+        CLI_INIT["gxpm-init<br/>install skill + hooks"]
+        CLI_INV["gxpm-investigate<br/>browser evidence"]
+        CLI_CFG["gxpm-config<br/>config mgmt"]
+        CLI_OTHERS["gxpm-update-check<br/>gxpm-global-discover<br/>gxpm-uninstall"]
+    end
+
+    subgraph "Core Runtime (core/)"
+        direction TB
+
+        subgraph "Issue & State"
+            ISSUES["issues.ts<br/>CRUD"]
+            STATE["state.ts<br/>state machine"]
+            SESSION["session.ts<br/>ownership"]
+            CHECKPOINT["checkpoint.ts<br/>handoff"]
+            RUNS["runs.ts<br/>execution ledger"]
+        end
+
+        subgraph "Phase Engine"
+            PHASE_GATES["phase-gates.ts<br/>gate definitions"]
+            PHASE_ART["phase-artifact.ts<br/>artifact mapping"]
+            TRIAGE["triage.ts"]
+            PLAN["plan.ts"]
+            DISPATCH["dispatch.ts"]
+            IMPLEMENT["implement.ts"]
+            AC_CHECK["ac-check.ts"]
+            SELF_REVIEW["self-review.ts"]
+            SHIP["ship.ts"]
+            PR_CHECK["pr-check.ts"]
+            VERIFY["verify.ts"]
+            QA["qa.ts"]
+            LAND["land.ts"]
+            GATE["gate.ts<br/>enforcement"]
+        end
+
+        subgraph "Workspace & Orchestration"
+            WORKSPACE["workspace-runtime.ts"]
+            ORCH["orchestrator.ts<br/>tick dispatch"]
+            READINESS["issue-readiness.ts"]
+        end
+
+        subgraph "Artifact & Evidence"
+            ARTIFACTS["artifacts.ts"]
+            EVIDENCE["evidence.ts"]
+        end
+
+        subgraph "Knowledge & Wiki"
+            WIKI["wiki.ts"]
+            WIKI_NATIVE["wiki-native.ts<br/>first-party"]
+        end
+
+        subgraph "Config & Capabilities"
+            CONFIG["config.ts<br/>resolution chain"]
+            CAPS["capabilities.ts<br/>registry"]
+            PROBE["command-probe.ts"]
+            PLAN_LINT["plan-lint.ts"]
+        end
+    end
+
+    subgraph "Storage Layer (.gxpm/)"
+        ISSUE_STATE[".gxpm/issues/<id>/<br/>state + artifacts"]
+        LOCAL_RUN[".gxpm/local/<br/>workspaces + runs"]
+        WIKI_STORE[".gxpm/wiki/<br/>native index + content"]
+        CONFIG_STORE[".gxpm/config.json"]
+    end
+
+    %% Host → Skill
+    CODEX --> |"loads"| SKILL_OUT
+    CLAUDE --> |"loads"| SKILL_ORPHAN
+
+    %% Skill generation flow
+    SKILL_GXPM --> |"renderTemplate<br/>PHASE_GATE_RULES"| SKILL_GEN
+    SKILL_GEN --> SKILL_OUT
+    SKILL_OUT --> |"copy to host"| SKILL_INST
+    SKILL_INST --> |"installs to"| CODEX
+    SKILL_DEV --> |"watch"| SKILL_GXPM
+
+    %% CLI → Core
+    CLI_MAIN --> ISSUES
+    CLI_MAIN --> STATE
+    CLI_MAIN --> ARTIFACTS
+    CLI_MAIN --> GATE
+    CLI_MAIN --> WIKI
+    CLI_MAIN --> CONFIG
+    CLI_INIT --> SKILL_INST
+    CLI_INIT --> GIT_HOOKS
+    CLI_INIT --> CODEX_HOOKS
+    CLI_INV --> EVIDENCE
+
+    %% Core → Storage
+    ISSUES --> ISSUE_STATE
+    STATE --> ISSUE_STATE
+    ARTIFACTS --> ISSUE_STATE
+    RUNS --> LOCAL_RUN
+    WORKSPACE --> LOCAL_RUN
+    WIKI_NATIVE --> WIKI_STORE
+    CONFIG --> CONFIG_STORE
+
+    %% Core → External
+    ISSUES -.-> |"sync"| LINEAR
+    QODER_MOD -.-> |"optional link"| QODER
+    ORCH -.-> |"dispatch"| CODEX
+
+    %% Hooks → Core
+    GIT_HOOKS --> |"calls"| GATE
+    CODEX_HOOKS --> |"inject context"| STATE
+
+    %% Code-intelligence skills now use GitNexus (external tool)
+    SKILL_ORPHAN -.-> |"uses MCP"| GITNEXUS
+```
+
+---
+
+## 2. 关键观察
+
+### 2.1 Skill 层是"单点 + 孤儿"结构
+
+- **主 skill**：`skills/gxpm/SKILL.md.tmpl` → `SKILL.md`（673 行，所有能力塞在一起）
+- **代码智能 skill**：`skills/gxpm-*`（GitNexus 驱动，随项目维护；旧 Claude-only 图谱 skill 已归档）
+- **生成管道**：`discoverTemplates()` 虽支持递归发现，但 `install-skill.ts` 和 `dev-skill.ts` 硬编码只处理 `skills/gxpm/SKILL.md.tmpl`
+
+### 2.2 Core 是按 Phase 组织的，但 Skill 是平铺的
+
+- Core 有清晰的 phase 文件：`triage.ts`, `plan.ts`, `dispatch.ts` ... `land.ts`
+- 但 Skill 把所有 phase 的指引塞进一个文件，导致 progressive disclosure 失效
+
+### 2.3 Host 适配层只处理安装路径，不处理 skill 内容分发
+
+- `hosts/codex.ts` 定义了 `globalRoot: ".codex/skills/gxpm"`
+- `hosts/claude.ts` 定义了 `globalRoot: ".claude/skills/gxpm"`
+- GitNexus code-intelligence skill 已收敛到 `skills/gxpm-*`，不再依赖 Claude-only 的旧图谱路径
+
+### 2.4 外部系统集成是"可选依赖"模式
+
+- Linear：协作前门，同步 issue，但不替代本地 state
+- GitNexus：MCP 工具，Agent 默认代码智能层，用于代码导航、调试、重构影响面和 review
+- gxpm wiki：可选人类文档层，用于 onboarding、phase/CLI/governance 导览；不替代 GitNexus