@geminix/gxpm 0.1.0

package/skills/gxpm-build/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: gxpm-build
+description: Compile and type-check verification. Use after implementing code changes, before committing, or when the build fails and root cause is unclear.
+---
+
+# gxpm-build
+
+## 入口条件
+
+在以下场景触发本 skill：
+
+- 每次代码变更后，需要确认编译和类型检查通过
+- 提交前，作为 `gxpm-verify` 的前置步骤之一
+- 构建失败且根因不明确时
+
+**Skill 边界**：本 skill 仅处理编译和类型检查层面的验证。测试失败请加载 `/gxpm-tdd`，代码风格或提交规范请加载 `/gxpm-hygiene`。
+
+在 gxpm 工作流中，`implement` 阶段每次完成一个垂直切片后都应运行构建验证。离开 `implement` 前，`local-verify` artifact 必须包含 `buildEvidence`。
+
+## 可操作流程
+
+按以下顺序执行构建验证：
+
+```bash
+# 1. Type check (fastest, catch type errors first)
+bun run check
+
+# 2. Build (confirm compilation produces valid output)
+bun run build
+```
+
+如果项目使用不同的构建系统，替换为等效命令。
+
+### 退出码约定
+
+| Exit Code | Meaning | Action |
+|-----------|---------|--------|
+| 0 | Success | Proceed |
+| non-0 | Failure | **Stop. Fix before continuing.** |
+
+### 构建失败归因
+
+遇到构建失败时，按症状定位根因并选择修复策略：
+
+| Symptom | Likely Cause | Fix Strategy |
+|---------|-------------|--------------|
+| Type error in changed file | Incorrect type usage or missing property | Fix the type, not the test |
+| Type error in unchanged file | Breaking change leaked to consumer | Update consumer or revert breaking change |
+| Syntax error | Typo, missing brace, invalid syntax | Fix syntax, re-run typecheck first |
+| Build output missing | Build script misconfigured or dependency missing | Check `package.json` scripts and `node_modules` |
+| Module resolution error | Import path wrong or alias unconfigured | Verify path mapping in `tsconfig.json` |
+
+## 红旗清单 / 反模式
+
+- **Never commit broken build.** A build failure means implementation is incomplete.
+- **Type errors are behavior errors.** Type checking is not optional polish — it is contract verification.
+- **Incremental compilable:** After every increment (even partial), the project must build successfully.
+- **One fix at a time:** If build fails, fix the root cause before running the build again. Do not guess-and-rerun.
+
+## 验证清单 / 出口条件
+
+构建通过的标准：
+
+- [ ] `bun run check` 返回 exit code 0
+- [ ] `bun run build` 返回 exit code 0
+- [ ] 如失败，已定位根因并完成单次修复（禁止猜测-重跑循环）
+
+`local-verify` artifact 中的 `buildEvidence` 必须包含：
+
+```json
+{
+  "buildEvidence": {
+    "commands": ["bun run check", "bun run build"],
+    "exitCodes": [0, 0],
+    "timestamp": "2026-05-08T08:30:00Z"
+  }
+}
+```

package/skills/gxpm-cleanup/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: gxpm-cleanup
+description: 多 issue worktree 合并前的代码清理与简化。在 cleanup 阶段识别跨 issue 重复、命名不一致、接口错位和死代码。
+status: stable
+---
+
+# gxpm-cleanup
+
+在 gxpm 的 `cleanup` 阶段对多 issue worktree 进行跨 issue 代码清理，确保进入 `ship` 前的代码是统一、简洁、无重复的。
+
+## 入口条件
+
+- issue 已进入 `cleanup` 阶段
+- worktree 中处理了 2+ 个 issue（单 issue 可跳过 cleanup）
+- 所有 issue 已完成 `self-review`
+
+## 可操作流程
+
+### 在 cleanup 阶段初始化报告
+
+```bash
+gxpm self-review cleanup <issue-id>
+```
+
+这会创建 `cleanup-report.json` artifact，包含：
+- `duplicatesExtracted` — 重复代码提取记录
+- `renamesUnified` — 命名统一记录
+- `interfacesAligned` — 接口对齐记录
+- `deadCodeRemoved` — 死代码删除记录
+- `testsDeduplicated` — 测试去重记录
+
+### 跳过 cleanup（单 issue worktree）
+
+```bash
+gxpm issue transition <issue-id> ship --skip-cleanup
+```
+
+单 issue worktree 可直接从 self-review 进入 ship，跳过 cleanup 阶段。
+
+**与 rigorLevel 的关系**：gxpm 的 `standard` 和 `lite` rigor 模式已自动跳过 cleanup 阶段（通过 `isCompressedSkip`），无需手动 `--skip-cleanup`。仅在 `full` 模式下需要显式跳过时才使用此 flag。
+
+### Cleanup 检查清单
+
+- [ ] 扫描 worktree 中所有 issue 的代码变更
+- [ ] 识别功能重复的模块/函数
+- [ ] 检查同一概念在不同 issue 中的命名一致性
+- [ ] 验证 issue 之间的接口格式是否对齐
+- [ ] 识别被后续 issue 替代的死代码
+- [ ] 检查测试覆盖是否有冗余
+- [ ] 记录所有发现到 cleanup-report
+
+## 红旗清单 / HARD-GATE
+
+- **发现功能完全重复的模块但未提取** → 必须 STOP，提取到共享位置
+- **跨 issue 接口不兼容且无迁移方案** → 必须 STOP，对齐接口后再推进
+- **死代码占比过高** → Important，需在 cleanup-report 中说明清理计划
+
+## 验证清单
+
+- [ ] cleanup-report.json 已创建并包含审计结果
+- [ ] 所有 blocking 级别问题已解决或获得豁免
+- [ ] 重复代码已提取或计划在后续迭代处理
+- [ ] 跨 issue 命名已统一或有明确的统一计划
+
+## 常见说辞表
+
+| 说辞 | 现实 | 正确做法 |
+|------|------|----------|
+| "这些重复是不同 issue 的职责，不应该提取" | 同一 worktree 的代码最终合并到同一 branch，重复就是债务 | 提取到共享位置，或明确说明为什么必须保持重复 |
+| "接口不对齐是设计决策，不是 bug" | 设计决策需要在代码层面有文档和兼容层 | 在 cleanup-report 中记录决策，必要时添加适配层 |
+| "cleanup 太费时间，直接 ship" | 跳过 cleanup 会让技术债务进入生产环境 | 至少记录发现的债务，在 ship notes 中说明还款计划 |
+
+## Read Next
+
+- `agents/cleanup-auditor/cleanup-auditor.md` — 审计角色详细定义
+- `skills/gxpm-refactor-safely/SKILL.md` — 安全重构指南

package/skills/gxpm-debug-issue/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: gxpm-debug-issue
+description: Systematic issue debugging using graph-powered code navigation. Use when user asks to trace a bug, investigate a specific error, or find the root cause of a failing test or exception.
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+## gxpm-debug-issue
+
+### 入口条件
+
+**Skill boundary:**
+- If the root cause is **completely unknown** and you need a systematic diagnosis loop, load `/gxpm-diagnose` first.
+- If you need to **understand code structure** without debugging a specific bug, load `/gxpm-explore-codebase` first.
+- If you are **refactoring**, load `/gxpm-refactor-safely` instead.
+
+Use GitNexus to systematically trace and debug issues when you have a **specific symptom**.
+
+### 可操作流程
+
+1. Run `list_repos` and read `gitnexus://repo/{name}/context` when an index exists.
+2. Use `query` to find execution flows related to the symptom.
+3. Use `context` on suspected symbols to inspect callers, callees, and participating processes.
+4. Run `detect_changes` to check if recent changes caused the issue.
+5. Use `impact` on suspected symbols or files to see what else is affected.
+
+> **Tips**
+> - Check both callers and callees to understand the full context.
+> - Look at affected flows to find the entry point that triggers the bug.
+> - Recent changes are the most common source of new issues.
+
+### 红旗清单 / 反模式
+
+- Start with the narrowest GitNexus query that matches the symptom, then expand.
+- Prefer `query` and `context` before raw `cypher`.
+
+### 验证清单 / 出口条件
+
+- Use `impact` on suspected symbols or files to see what else is affected.
+- Target: complete any review/debug/refactor task in ≤5 graph tool calls.

package/skills/gxpm-diagnose/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: diagnose
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Use when user says 'diagnose this', reports a hard bug, describes a performance regression, or asks why something fails.
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+# Diagnose
+
+A discipline for hard bugs where the root cause is **not yet known**.
+
+### 入口条件
+
+**Skill boundary:**
+- If you have a **specific symptom, stack trace, or error message** and need to trace its root cause through the codebase, load `/gxpm-debug-issue` first.
+- If you need to **understand code structure** without debugging a specific bug, load `/gxpm-explore-codebase` first.
+- If you are **refactoring** and discover a bug mid-refactor, switch to `/gxpm-diagnose` or `/gxpm-debug-issue` instead of continuing.
+
+- **触发时机**：Use when user says 'diagnose this', reports a hard bug, describes a performance regression, or asks why something fails.
+- **纪律**：Skip phases only when explicitly justified.
+
+### 可操作流程
+
+## Phase 2 — Reproduce
+
+Run the loop. Confirm:
+- [ ] The loop produces the failure mode the **user** described.
+- [ ] The failure is reproducible across multiple runs.
+- [ ] You have captured the exact symptom.
+
+## Phase 3 — Explore with the codebase
+
+Use available code intelligence tools (e.g., GitNexus MCP, grep, ReadFile) to accelerate understanding:
+
+1. **Semantic search** to find code related to the symptom.
+2. **Call-chain tracing** to follow `callers_of` / `callees_of` relationships.
+3. **Execution flow analysis** to see full paths through suspected areas.
+4. **Change detection** (`git diff`, `detect_changes`) to check if recent changes caused the issue.
+5. **Impact analysis** on suspected files to see what else is affected.
+
+**Token efficiency**: start with the narrowest context possible, then expand. Target ≤5 tool calls and ≤800 total output tokens for the exploration phase.
+
+## Phase 4 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear."
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly.
+
+## Phase 5 — Instrument
+
+Each probe must map to a specific prediction from Phase 4. **Change one variable at a time.**
+
+Tool preference:
+1. **Debugger / REPL inspection** if the env supports it.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep.
+
+**Perf branch.** For performance regressions: establish a baseline measurement first, then bisect. Measure first, fix second.
+
+## Phase 6 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site.
+
+**If no correct seam exists, that itself is the finding.** Flag this for the next `/architecture` run.
+
+## Phase 7 — Cleanup + post-mortem
+
+Required before declaring done:
+- [ ] Original repro no longer reproduces.
+- [ ] Regression test passes (or absence of seam is documented).
+- [ ] All `[DEBUG-...]` instrumentation removed.
+- [ ] Throwaway prototypes deleted.
+- [ ] The correct hypothesis is stated in the commit / PR message.
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change, hand off to `/architecture` with the specifics.
+
+
+### 红旗清单 / 反模式
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer).
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system that exercises the bug code path.
+7. **Property / fuzz loop.** Run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** Automate `git bisect run` if the bug appeared between two known states.
+9. **Differential loop.** Run old-version vs new-version and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive them with a structured loop.
+
+### Iterate on the loop itself
+
+- Can I make it faster? (Cache setup, skip unrelated init.)
+- Can I make the signal sharper? (Assert on the specific symptom.)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem.)
+
+### Non-deterministic bugs
+
+The goal is a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress. A 50%-flake bug is debuggable; 1% is not.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to the repro environment, (b) a captured artifact, or (c) permission to add temporary production instrumentation.
+
+**Do not proceed to Phase 2 until you have a loop you believe in.**
+
+
+### 验证清单 / 出口条件
+
+- 完成 ## Phase 2 — Reproduce
+
+Run the loop. Confirm:
+- [ ] The loop produces the failure mode the **user** described.
+- [ ] The failure is reproducible across multiple runs.
+- [ ] You have captured the exact symptom.
+
+## Phase 3 — Explore with the codebase
+
+Use available code intelligence tools (e.g., GitNexus MCP, grep, ReadFile) to accelerate understanding:
+
+1. **Semantic search** to find code related to the symptom.
+2. **Call-chain tracing** to follow `callers_of` / `callees_of` relationships.
+3. **Execution flow analysis** to see full paths through suspected areas.
+4. **Change detection** (`git diff`, `detect_changes`) to check if recent changes caused the issue.
+5. **Impact analysis** on suspected files to see what else is affected.
+
+**Token efficiency**: start with the narrowest context possible, then expand. Target ≤5 tool calls and ≤800 total output tokens for the exploration phase.
+
+## Phase 4 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear."
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly.
+
+## Phase 5 — Instrument
+
+Each probe must map to a specific prediction from Phase 4. **Change one variable at a time.**
+
+Tool preference:
+1. **Debugger / REPL inspection** if the env supports it.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep.
+
+**Perf branch.** For performance regressions: establish a baseline measurement first, then bisect. Measure first, fix second.
+
+## Phase 6 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site.
+
+**If no correct seam exists, that itself is the finding.** Flag this for the next `/architecture` run.
+
+## Phase 7 — Cleanup + post-mortem
+
+Required before declaring done:
+- [ ] Original repro no longer reproduces.
+- [ ] Regression test passes (or absence of seam is documented).
+- [ ] All `[DEBUG-...]` instrumentation removed.
+- [ ] Throwaway prototypes deleted.
+- [ ] The correct hypothesis is stated in the commit / PR message.
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change, hand off to `/architecture` with the specifics.
+ 中定义的全部阶段。
+- 按 ## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer).
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system that exercises the bug code path.
+7. **Property / fuzz loop.** Run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** Automate `git bisect run` if the bug appeared between two known states.
+9. **Differential loop.** Run old-version vs new-version and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive them with a structured loop.
+
+### Iterate on the loop itself
+
+- Can I make it faster? (Cache setup, skip unrelated init.)
+- Can I make the signal sharper? (Assert on the specific symptom.)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem.)
+
+### Non-deterministic bugs
+
+The goal is a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress. A 50%-flake bug is debuggable; 1% is not.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to the repro environment, (b) a captured artifact, or (c) permission to add temporary production instrumentation.
+
+**Do not proceed to Phase 2 until you have a loop you believe in.**
+ 的约束完成收敛。

package/skills/gxpm-diagnose/SKILL.md.tmpl

@@ -0,0 +1,31 @@
+---
+name: diagnose
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Use when user says 'diagnose this', reports a hard bug, describes a performance regression, or asks why something fails.
+---
+
+# Diagnose
+
+A discipline for hard bugs where the root cause is **not yet known**.
+
+### 入口条件
+
+**Skill boundary:**
+- If you have a **specific symptom, stack trace, or error message** and need to trace its root cause through the codebase, load `/gxpm-debug-issue` first.
+- If you need to **understand code structure** without debugging a specific bug, load `/gxpm-explore-codebase` first.
+- If you are **refactoring** and discover a bug mid-refactor, switch to `/gxpm-diagnose` or `/gxpm-debug-issue` instead of continuing.
+
+- **触发时机**：Use when user says 'diagnose this', reports a hard bug, describes a performance regression, or asks why something fails.
+- **纪律**：Skip phases only when explicitly justified.
+
+### 可操作流程
+
+{{REFERENCE:phases}}
+
+### 红旗清单 / 反模式
+
+{{REFERENCE:feedback-loop}}
+
+### 验证清单 / 出口条件
+
+- 完成 {{REFERENCE:phases}} 中定义的全部阶段。
+- 按 {{REFERENCE:feedback-loop}} 的约束完成收敛。

package/skills/gxpm-diagnose/references/feedback-loop.md

@@ -0,0 +1,34 @@
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer).
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system that exercises the bug code path.
+7. **Property / fuzz loop.** Run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** Automate `git bisect run` if the bug appeared between two known states.
+9. **Differential loop.** Run old-version vs new-version and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive them with a structured loop.
+
+### Iterate on the loop itself
+
+- Can I make it faster? (Cache setup, skip unrelated init.)
+- Can I make the signal sharper? (Assert on the specific symptom.)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem.)
+
+### Non-deterministic bugs
+
+The goal is a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress. A 50%-flake bug is debuggable; 1% is not.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to the repro environment, (b) a captured artifact, or (c) permission to add temporary production instrumentation.
+
+**Do not proceed to Phase 2 until you have a loop you believe in.**

package/skills/gxpm-diagnose/references/feedback-loops.md

@@ -0,0 +1,43 @@
+# Feedback Loop Construction Catalog
+
+Reference for Phase 1 of `/gxpm-diagnose`. Try these in roughly this order.
+
+## 1. Failing test
+At whatever seam reaches the bug — unit, integration, e2e.
+
+## 2. Curl / HTTP script
+Against a running dev server.
+
+## 3. CLI invocation
+With a fixture input, diffing stdout against a known-good snapshot.
+
+## 4. Headless browser script
+Playwright / Puppeteer — drives the UI, asserts on DOM/console/network.
+
+## 5. Replay a captured trace
+Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+
+## 6. Throwaway harness
+Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+
+## 7. Property / fuzz loop
+If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+
+## 8. Bisection harness
+If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+
+## 9. Differential loop
+Run the same input through old-version vs new-version (or two configs) and diff outputs.
+
+## 10. HITL bash script
+Last resort. If a human must click, drive _them_ with a structured loop so the feedback is still structured. Captured output feeds back to you.
+
+---
+
+## Loop quality checklist
+
+Once you have _a_ loop, iterate:
+
+- [ ] **Faster** — Cache setup, skip unrelated init, narrow the test scope.
+- [ ] **Sharper** — Assert on the specific symptom, not "didn't crash".
+- [ ] **More deterministic** — Pin time, seed RNG, isolate filesystem, freeze network.

package/skills/gxpm-diagnose/references/phases.md

@@ -0,0 +1,60 @@
+## Phase 2 — Reproduce
+
+Run the loop. Confirm:
+- [ ] The loop produces the failure mode the **user** described.
+- [ ] The failure is reproducible across multiple runs.
+- [ ] You have captured the exact symptom.
+
+## Phase 3 — Explore with the codebase
+
+Use available code intelligence tools (e.g., GitNexus MCP, grep, ReadFile) to accelerate understanding:
+
+1. **Semantic search** to find code related to the symptom.
+2. **Call-chain tracing** to follow `callers_of` / `callees_of` relationships.
+3. **Execution flow analysis** to see full paths through suspected areas.
+4. **Change detection** (`git diff`, `detect_changes`) to check if recent changes caused the issue.
+5. **Impact analysis** on suspected files to see what else is affected.
+
+**Token efficiency**: start with the narrowest context possible, then expand. Target ≤5 tool calls and ≤800 total output tokens for the exploration phase.
+
+## Phase 4 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear."
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly.
+
+## Phase 5 — Instrument
+
+Each probe must map to a specific prediction from Phase 4. **Change one variable at a time.**
+
+Tool preference:
+1. **Debugger / REPL inspection** if the env supports it.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep.
+
+**Perf branch.** For performance regressions: establish a baseline measurement first, then bisect. Measure first, fix second.
+
+## Phase 6 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site.
+
+**If no correct seam exists, that itself is the finding.** Flag this for the next `/architecture` run.
+
+## Phase 7 — Cleanup + post-mortem
+
+Required before declaring done:
+- [ ] Original repro no longer reproduces.
+- [ ] Regression test passes (or absence of seam is documented).
+- [ ] All `[DEBUG-...]` instrumentation removed.
+- [ ] Throwaway prototypes deleted.
+- [ ] The correct hypothesis is stated in the commit / PR message.
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change, hand off to `/architecture` with the specifics.

package/skills/gxpm-eval/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: gxpm-eval
+description: Skill quality evaluation harness for static analysis. Use when adding a new skill, modifying skill structure, auditing skill quality, or checking for governance compliance.
+---
+
+# gxpm-eval
+
+Lightweight static analysis for gxpm skills. Checks frontmatter completeness,
+trigger sections, description quality, and reference links.
+
+## 入口条件
+
+- After creating or modifying a skill
+- During `self-review` or `qa` phase before shipping skill changes
+- When `bun run check` reports skill doc drift
+
+## 可操作流程
+
+### 命令
+
+```bash
+gxpm-eval list                         # list all discoverable skills
+gxpm-eval run                          # eval all skills
+gxpm-eval run gxpm-diagnose            # eval one skill
+gxpm-eval run --json                   # machine-readable output
+```
+
+### 评分标准
+
+Each skill is scored on 9 dimensions. Pass threshold: ≥ 60%.
+
+#### Universal checks (all skill types)
+
+| Check | Points | Pass criteria |
+|-------|--------|---------------|
+| frontmatter | 10 | Has YAML `---` block |
+| name | 10 | `name:` field present and non-empty |
+| description | 10 | 20-300 characters **and** contains "Use when" trigger phrase |
+| triggers | 10 | Has `## When to trigger` or `## Commands` |
+| length | 10 | 10-1000 lines (warn if >100 without `references/`) |
+| references | 10 | Has `## Read Next` or `## References` |
+
+#### Type-specific checks
+
+| Check | Points | Pass criteria |
+|-------|--------|---------------|
+| **Discipline** skills | 10 | Has `## Red Flags` AND `## Rationalization Table` AND explicit negation (`**No exceptions:**`) |
+| **Pattern** skills | 10 | Has `## Recognition criteria` AND `## When NOT to apply` AND `## Counter-examples` |
+| **Reference** skills | 10 | Has concrete command examples with expected output |
+
+A skill missing its type-specific structures loses the full 10 points for that dimension.
+
+### 集成到 CI
+
+Add to `gxpm-check` or CI:
+
+```bash
+bun run scripts/eval.ts run --json
+```
+
+## 红旗清单 / 反模式
+
+- 不要依赖 gxpm-eval 做 LLM 输出质量评分 — 它只做静态结构分析
+- 不要假设结构通过 = 内容正确 — eval 不验证 skill 内容的正确性
+- 不要在未通过 ≥ 60% 阈值时将 skill 标记为就绪
+
+## 验证清单 / 出口条件
+
+- [ ] 所有 discoverable skills 已列入评估结果
+- [ ] 每个 skill 在 9 个维度上的得分已计算
+- [ ] 总分达到 ≥ 60% 阈值
+- [ ] type-specific checks 已按 skill 类型正确匹配
+- [ ] `bun run scripts/eval.ts run --json` 输出可被下游 CI 消费
+
+## Read Next
+
+- `docs/governance/skill-authoring.md`
+- Main `/gxpm` skill for skill toolchain overview