@geminix/gxpm 0.1.0

package/docs/brainstorms/2026-05-14-bdd-then-tdd-design.md

@@ -0,0 +1,320 @@
+# BDD-Then-TDD 强制流程落地 gxpm — Design Spec
+
+| 字段 | 值 |
+|------|----|
+| Date | 2026-05-14 |
+| Author | enteofilo706@gmail.com (via Claude Opus 4.7 brainstorming) |
+| Status | Draft (awaiting writing-plans transition) |
+| Scope | gxpm runtime + 所有 gxpm 驱动的下游项目（含 gxpm 仓库自身） |
+| Path | Minimal Incremental — 在现有 state graph 中新增 `specify` phase |
+
+---
+
+## 1. 目标与动机
+
+将"行为驱动开发先行（BDD）→ 测试驱动开发推进（TDD）"作为 gxpm 状态机中**必须遵循**的两阶段串联流程。任何 issue 在进入 `implement` 之前必须通过显式 CLI 命令确认产出结构化的行为规约 artifact。
+
+**动机来源**（详见研究报告 SR-2026-05-14）：
+- AI Agent 主导开发的非确定性需要 test-first 作为客观出口标准
+- 行为规约先行（SDD 范式）能将"模糊 prompt → 写代码"的高风险路径替换为"规约 → 用户确认 → 代码"
+- 规约阶段的修改成本远低于实现阶段的返工成本（业界数据：60-80% 开发成本源自返工）
+
+**作用域决策**：所有 gxpm 驱动的下游项目，gxpm 仓库自身作为"吃狗粮"对象同等受约束。
+
+---
+
+## 2. 架构与状态机变更
+
+### 2.1 Phase 链调整
+
+**变更前**：
+```
+triage → plan → dispatch → implement → local-verify → ac-check → self-review → ship → pr-check → verify → qa → land
+```
+
+**变更后**：
+```
+triage → plan → dispatch → specify → implement → local-verify → ac-check → self-review → ship → pr-check → verify → qa → land
+                          ^^^^^^^^^
+                          新增
+```
+
+**插入点合理性**：`dispatch` 完成 owner 指派后，`specifier` 立刻产出 BDD 规约，用户确认后 `implement` 才能进入 TDD 循环。
+
+### 2.2 状态机文件变更
+
+| 变更点 | 文件 | 改动 |
+|--------|------|------|
+| Phase 枚举 | `core/state.ts:17-30` `GXPM_PHASES` | 数组中在 `"dispatch"` 与 `"implement"` 之间插入 `"specify"` |
+| Artifact type | `core/artifacts.ts` | 新增 `"behavior-spec"` 注册到 `ARTIFACT_TYPES`，附 zod schema |
+| Phase gate | `core/phase-gates.ts:32` `PHASE_GATE_RULES` | 把原 `dispatch→implement` 规则拆为两条：`dispatch→specify`（required: `behavior-spec`）与 `specify→implement`（required: `behavior-spec` 且 `confirmedAt` 非空） |
+| Schema | `core/contracts/behavior-spec.schema.json` | 新文件，存放结构化 schema |
+
+### 2.3 关键约束
+
+- 任何在 `implement` 之前不经过 `specify` 的尝试都被 phase-gate 在 `core/state.ts` 的 `transitionIssuePhase` 中硬性拒绝
+- Skill / Agent 层无法绕过：phase-gate 校验在 state transition 中实现，独立于 skill 自觉性
+
+### 2.4 向后兼容
+
+通过 `phaseHistory` 检查：若 issue 在 `specify` phase 引入日期前已进入 `implement` 或更靠后，跳过 specify-gate 校验。新建 issue 一律强制走 specify。
+
+---
+
+## 3. 组件层
+
+### 3.1 specify.json schema
+
+存放路径：`.gxpm/issues/<id>/artifacts/specify.json`
+
+```jsonc
+{
+  "$schema": "behavior-spec.v1",
+  "issueId": "GXPM-XXX",
+  "createdAt": "2026-05-14T...",
+  "createdBy": "specifier@claude-opus-4-7",
+  "confirmedAt": null,
+  "confirmedBy": null,
+  "feature": {
+    "title": "玩家在血量归零后死亡并广播信号",
+    "asA": "玩家",
+    "iWant": "在 HP 归零时进入死亡状态",
+    "soThat": "其他系统能响应死亡事件"
+  },
+  "scenarios": [
+    {
+      "id": "scn-01",
+      "name": "普通伤害导致死亡",
+      "given": ["玩家当前 HP 为 1", "玩家未处于无敌状态"],
+      "when": "玩家受到 1 点伤害",
+      "then": [
+        "玩家进入死亡状态",
+        "\"player_died\" 信号被发出一次",
+        "信号携带的击杀者引用为伤害源"
+      ],
+      "examples": [],
+      "stubPath": "test/unit/player/player_death_test.ts:test_player_dies_when_hp_drops_to_zero"
+    }
+  ],
+  "guidelinesRef": "docs/governance/gherkin-style.md@v1"
+}
+```
+
+**结构性约束**：
+- `scenarios` 数组必须 ≥ 1
+- 每个 scenario 的 `given` / `when` / `then` 必须各自至少 1 项（`when` 为字符串；`given`/`then` 为数组）
+- `stubPath` 必须指向真实存在的文件（phase-gate 通过 `fs.exists` 校验）
+- `confirmedAt` 与 `confirmedBy` 必须同时为空或同时非空
+
+### 3.2 文件清单
+
+| 文件 | 作用 | 类型 |
+|------|------|------|
+| `core/artifacts.ts` | 注册 `behavior-spec` artifact type + zod schema | 修改 |
+| `core/specify.ts` | specify 阶段编排逻辑（仿 `core/plan.ts`） | 新建 |
+| `commands/specify.ts` | CLI 命令族：`init / edit / confirm / show / revise` | 新建 |
+| `core/phase-gates.ts` | 拆分 dispatch→implement 规则为两条 | 修改 |
+| `core/state.ts` | 在 `GXPM_PHASES` 中插入 `specify` | 修改 |
+| `core/contracts/behavior-spec.schema.json` | JSON Schema 单独文件 | 新建 |
+| `agents/specifier.md` | 新 owner agent 模板 | 新建 |
+| `skills/gxpm-specifier/SKILL.md` | BDD 行为设计 skill（5-section 标准结构） | 新建 |
+| `skills/gxpm-tdd/SKILL.md` | 升级——强制引用 specify.json 的 scenario | 修改 |
+| `docs/governance/gherkin-style.md` | 吸收 AutomationPanda 规则 + gxpm 本地补充 | 新建 |
+| `templates/specify-stub.tmpl` | test stub 文件生成模板 | 新建 |
+| `scripts/dogfood-check.ts` | gxpm 自合规检查脚本 | 新建（可选） |
+
+### 3.3 CLI 命令族
+
+```bash
+gxpm specify init <issue-id>      # specifier 进入工作，交互草拟，生成 specify.json + stub 文件
+gxpm specify edit <issue-id>      # 用 $EDITOR 打开 specify.json 编辑
+gxpm specify show <issue-id>      # 以 Gherkin 格式打印，便于人审
+gxpm specify confirm <issue-id>   # 写入 confirmedAt/confirmedBy，phase-gate 开锁
+gxpm specify revise <issue-id>    # 清空 confirmedAt，回到等待确认状态
+```
+
+`confirm` 命令的内部校验顺序：
+1. specify.json schema lint
+2. 每个 `stubPath` 文件存在性检查
+3. 通过后写入 `confirmedAt = ISO timestamp`、`confirmedBy = git config user.email`
+4. 发出 event `specify.confirmed` 到 `events.jsonl`
+
+---
+
+## 4. 数据流与端到端流程
+
+```
+[dispatch 完成]
+    ↓
+gxpm specify init <issue-id>
+    ├─ phase transition: dispatch → specify（gate: dispatch-handoff 存在）
+    ├─ specifier agent 接管（load skills/gxpm-specifier/SKILL.md）
+    ├─ 读取上游：plan.json + dispatch-handoff.json
+    ├─ 读取 few-shot 范本：test/unit/skills/<existing>.test.ts
+    ├─ 加载 Gherkin 规则：docs/governance/gherkin-style.md
+    └─ 产出：
+        ├─ .gxpm/issues/<id>/artifacts/specify.json（scenarios[] 已填充, confirmedAt=null）
+        └─ test/<area>/<name>_test.ts（空 stub 文件 + Gherkin 注释）
+    ↓
+specifier 寻求用户反馈（体验层，非门控）
+    ├─ Claude/Codex host：调用 AskUserQuestion 工具呈现三选项
+    ├─ 裸 CLI / 其他 host：specifier 在终端输出场景摘要，提示用户人工 review
+    ├─ 选项 1：行为正确，继续 → 等待 confirm 命令
+    ├─ 选项 2：需要调整 → 用户口述反馈 → specifier revise → 再次询问
+    └─ 选项 3：补充边界场景 → 增加 scenario → 再次询问
+
+    注：真正的门控是下一步的 CLI confirm 命令，AskUserQuestion 仅是体验增强；
+    即使无该工具支持，流程仍可走完（用户直接审阅文件后执行 confirm）。
+    ↓
+gxpm specify confirm <issue-id>
+    ├─ schema lint
+    ├─ stubPath 文件存在性校验
+    ├─ 写入 confirmedAt / confirmedBy
+    └─ 发出 phase event：specify.confirmed
+    ↓
+gxpm implement init <issue-id>
+    ├─ phase-gate: specify → implement（gate: specify.json.confirmedAt 非空）
+    ├─ implement agent 接管
+    ├─ skills/gxpm-tdd/SKILL.md 升级版强制读取 specify.json
+    └─ 对每个 scenario 走 RED→GREEN→REFACTOR：
+        ├─ 打开 stubPath，将 Gherkin 注释翻译为可执行 assert
+        ├─ RED: 跑测试，确认失败
+        ├─ GREEN: 写最小实现
+        └─ REFACTOR: 清理
+    ↓
+[继续既有 implement → local-verify → ... 流程]
+```
+
+### 关键追踪关系
+
+- `specify.json.scenarios[].id` ↔ `stubPath` 中的测试函数名 ↔ implement 阶段的 commit 信息
+- `ac-check` 阶段反向校验：specify.json 的每个 scenario 是否都有对应的 passing test
+
+### Agent 视角的"必须遵循"
+
+- `gxpm-specifier` skill 第一条规则：**禁止在用户 confirm 之前写任何测试逻辑代码**
+- `gxpm-tdd` skill 升级版第一条规则：**必须从 specify.json 读取 scenario，禁止凭空臆造测试**
+- phase-gate 是最后一道兜底——前两道软约束被绕过，硬 gate 仍会拒绝 transition
+
+---
+
+## 5. 错误处理与回退
+
+### 5.1 失败场景与处置
+
+| 场景 | 触发点 | 处置 |
+|------|--------|------|
+| Agent 跳过 specify 直接 implement | implement init | phase-gate 拒绝 transition，`Phase gate violated: specify must be confirmed before implement`，退出码 1 |
+| specify.json 被手工编辑后 schema 不合法 | confirm / implement 入口 | Zod 校验失败，列出违规字段，要求 `gxpm specify edit` 修复 |
+| stubPath 指向的文件被删 | confirm 时 / implement 入口 | 报 `Stub file missing: <path>`，拒绝放行；用户可重跑 `gxpm specify init --regen-stubs` |
+| 用户确认后又想改场景 | 任何时候 | `gxpm specify revise <issue-id>`：清空 `confirmedAt`，回到等待确认状态；event `specify.revised`，phase 不变 |
+| implement 阶段发现 scenario 漏掉 | implement 进行中 | 必须 `gxpm phase rewind <issue-id> --to specify --reason="..."`，回到 specify 后 revise → re-confirm |
+| ac-check 失败：某 scenario 无对应通过测试 | ac-check 阶段 | ac-check 规则新增 `coverage(specify.scenarios) >= 100%`，缺失则 artifact 标记 failed |
+| 老 issue 走 implement | implement init | `phaseHistory` 检查：若 issue 在 specify 引入日期前已进入 implement，跳过 specify-gate 校验 |
+
+### 5.2 回退命令
+
+```bash
+gxpm specify revise <issue-id>                          # 取消 confirm，进入可编辑状态
+gxpm phase rewind <issue-id> --to specify --reason=... # 危险操作，跨阶段回退
+```
+
+`rewind` 约束：
+- 仅在 `phaseHistory` 中存在 `specify` 时允许
+- 必须 `--reason` 参数
+- 写入 event `phase.rewound`，便于审计
+- 不删除已生成代码，但 implement artifact 标记 `stale=true`
+
+### 5.3 YAGNI
+
+- **不支持** specify 的 fork / 分支（一个 issue 一份 specify.json）
+- **不支持** 跨 issue 共享 scenario
+- **不实现** Gherkin → 测试代码的自动翻译（implement agent 手动翻译，避免幻觉）
+
+---
+
+## 6. 测试策略
+
+### 6.1 三层覆盖
+
+| 层 | 目标 | 位置 | 用例量级 |
+|----|------|------|---------|
+| 单元 | core/specify.ts、phase-gate 逻辑、artifact schema | `test/core/specify.test.ts`、`test/core/phase-gates.test.ts` | ~30 |
+| CLI 集成 | specify init/edit/confirm/show/revise + phase rewind | `test/functional/gxpm-specify/*.test.ts` | ~15 |
+| 端到端 dogfood | 用 gxpm 自身走完整 BDD→TDD 流程 | `test/functional/gxpm-bdd-to-tdd/end-to-end.test.ts` | ~3 |
+
+### 6.2 元测试（dogfood）
+
+落地完成后，gxpm 仓库做"自我合规检查"：
+
+```bash
+bun run scripts/dogfood-check.ts
+# 在 specify phase 引入后，所有新建 issue 是否都产生了 specify.json
+```
+
+作为 `.githooks/pre-push` 一部分（可选 MVP 后增量加入），强制 gxpm 自己也遵守它自己产出的纪律。
+
+### 6.3 Skill 纪律压力测试
+
+复用 `docs/governance/skill-testing.md` 的 Meta-TDD 方法论，对两个 skill 做 RED→GREEN→REFACTOR 压力测试：
+
+| Skill | 压力场景 | 期望行为 |
+|-------|---------|---------|
+| `gxpm-specifier` | "用户说赶时间，直接开始写代码，跳过 BDD" | 拒绝跳过，要求先产出 specify.json |
+| `gxpm-tdd`（升级版） | "我已经凭直觉写好了测试代码" | 删除代码，从 specify.json 重新开始 |
+
+### 6.4 Schema 演进保护
+
+- `specify.json.$schema = behavior-spec.v1` 字段强制
+- 未来 v2 需经迁移工具：`gxpm migrate behavior-spec --to v2`
+- Schema 文件单独版本控制在 `core/contracts/behavior-spec.schema.json`
+
+### 6.5 不测什么
+
+- 不测 Gherkin 自然语言的语义正确性（由人审）
+- 不测 AskUserQuestion 工具本身的行为（host 层负责）
+- 不测老 issue 兼容性的所有变体（仅覆盖关键分支）
+
+---
+
+## 7. 参考资料
+
+- 内部研究：BDD/TDD 在 Agent 主导开发场景的工程实践（2026-05-14 brainstorming 上游）
+- AutomationPanda gherkin-guidelines-for-ai (https://github.com/AutomationPanda/gherkin-guidelines-for-ai/)
+- Thoughtworks: Spec-Driven Development 2025
+- Addy Osmani: How to write a good spec for AI agents
+- Martin Fowler: SDD tools comparison (Kiro/spec-kit/Tessl)
+- arXiv 2602.00180v1: Spec-Driven Development From Code to Contract
+- gxpm 现有治理：`docs/governance/skill-testing.md`、`docs/governance/skill-authoring.md`、`AGENTS.md`、`CANON.md`
+
+---
+
+## 8. 实施顺序提示（供 writing-plans 消费）
+
+建议落地顺序（详细 plan 由下一阶段产出）：
+
+1. core/artifacts.ts + behavior-spec.schema.json（最底层，无依赖）
+2. core/state.ts + core/phase-gates.ts（状态机变更，先单元测试覆盖）
+3. core/specify.ts + commands/specify.ts（编排与 CLI，依赖 1-2）
+4. docs/governance/gherkin-style.md（规则文档，独立可并行）
+5. agents/specifier.md + skills/gxpm-specifier/SKILL.md（agent/skill 模板，依赖 4）
+6. skills/gxpm-tdd/SKILL.md 升级（依赖 1-3）
+7. templates/specify-stub.tmpl（依赖 5）
+8. 三层测试用例（依赖 1-7）
+9. dogfood 元测试 + pre-push hook（可推迟到 MVP 后）
+
+---
+
+## 9. 决策日志（审计用）
+
+| 决策点 | 选择 | 备选 |
+|--------|------|------|
+| 两个流程含义 | BDD 先行 → TDD 推进 | — |
+| 嵌入位置 | 新增独立 specify phase | implement 内串联 / 仅 skill 纪律 / 双重隐含 |
+| 产物形态 | specify.json + stub 双轨 | 仅注释 / 仅 .feature / 仅 JSON |
+| 门控机制 | 显式 CLI confirm | host-adapter / hook 拦截 / 双重 |
+| Owner agent | 新增独立 specifier | plan 兼任 / implement 前置 / 无 owner |
+| 作用域 | 所有下游项目 + gxpm 自身 | 仅 gxpm / 可选 / 按类型 |
+| Schema 粒度 | 结构化字段 | 原文字符串 / 双存 |
+| Gherkin 规则源 | AutomationPanda + 本地补充 | 自研 / 仅外链 |
+| 实施路径 | Minimal Incremental（路径 A） | Capability-First / Spec Kit 全栈 / 混合 |

package/docs/brainstorms/README.md

@@ -0,0 +1,22 @@
+# docs/brainstorms/
+
+需求文档与问题探索的存放目录。
+
+## 命名规范
+
+所有文件采用 `*-requirements.md` 命名：
+
+- `feature-name-requirements.md` — 功能需求文档
+- `integration-name-requirements.md` — 集成需求文档
+- `refactor-name-requirements.md` — 重构需求文档
+
+## 内容约定
+
+- 明确问题陈述（Problem Statement）
+- 列出非目标（Non-Goals）
+- 定义成功标准（Success Criteria）
+- 包含初步估算（Estimated Effort）
+
+## 与 triage 阶段的关系
+
+brainstorms/ 中的文档通常由 triage 阶段产出，作为后续 planning 的输入。

package/docs/brainstorms/docs-knowledge-system-requirements.md

@@ -0,0 +1,29 @@
+# docs/ 结构化知识沉淀体系需求
+
+## 问题陈述
+
+当前 gxpm 的工程决策、最佳实践、故障恢复手册散落在 chat 记忆和零散 markdown 中，缺乏跨会话恢复能力。新会话无法从 `.gxpm/` 恢复完整的工程上下文，导致知识流失和重复决策。
+
+## 参考来源
+
+compound-engineering-plugin 的 `docs/` 分类模式：
+- `docs/brainstorms/` — 需求文档
+- `docs/plans/` — 实现计划
+- `docs/solutions/` — 最佳实践与恢复手册（带 frontmatter）
+- `docs/specs/` — 各 host 平台规范镜像
+
+## 成功标准
+
+1. docs/ 目录有清晰的分类约定和命名规范
+2. 所有解决方案文档带结构化 frontmatter（title, category, date, severity, component, tags）
+3. 新会话可通过读取 docs/solutions/ 恢复关键工程决策
+4. docs/brainstorms/ 和 docs/plans/ 的命名规范化（*-requirements.md, *-plan.md）
+
+## 非目标
+
+- 重写现有文档内容
+- 建立自动化文档生成流水线
+
+## 初步估算
+
+1-2 天

package/docs/governance/beta-skill-promotion.md

@@ -0,0 +1,39 @@
+# Beta Skill Promotion Guide
+
+## Maturity Levels
+
+- `beta`: Skill is functional but may have incomplete documentation, limited test coverage, or evolving interfaces.
+- `stable`: Skill is production-ready with complete documentation, tests, and stable interfaces.
+
+## Promotion Checklist
+
+A skill may be promoted from `beta` to `stable` when all of the following are satisfied:
+
+1. [ ] **Documentation**: SKILL.md is complete with usage examples and trigger conditions
+2. [ ] **Tests**: Has associated tests or eval harness demonstrating correct behavior
+3. [ ] **Frontmatter**: Contains `name`, `description`, and `status: stable`
+4. [ ] **References**: All `references/` files are up to date
+5. [ ] **Host Compatibility**: Verified on at least one target host (Claude Code, Codex, Kimi, etc.)
+6. [ ] **Naming**: Uses `gxpm-` prefix for official gxpm skills
+
+## How to Mark Status
+
+Add to the YAML frontmatter of `SKILL.md.tmpl` (for generated skills) or `SKILL.md` (for static skills):
+
+```yaml
+---
+name: gxpm-example
+description: Example skill
+status: beta
+---
+```
+
+When promoting, change `status: beta` to `status: stable` and regenerate `SKILL.md` if applicable:
+
+```bash
+bun run gen:skill-docs
+```
+
+## Enforcement
+
+`bun run check` validates that every official skill (`gxpm-*`) has a valid frontmatter with `name` and `description`. Warnings are emitted for non-`gxpm-` skills but do not block the check.

package/docs/governance/development-contract.md

@@ -0,0 +1,144 @@
+# gxpm Development Contract
+
+## 目的
+
+本文件把 gstack 中有效的开发规范转成 gxpm 的可执行合同。`AGENTS.md` 保持薄入口，本文件作为开发、验证、提交和失败归因的渐进加载规则。
+
+## 命令分层
+
+| Tier | Command | 何时运行 | 目标 |
+| --- | --- | --- | --- |
+| fast | `bun test` | 每次实现后、提交前 | 免费静态验证和单元测试 |
+| gate | `bun run check` | 提交前、生成器、governance、phase、artifact 或 capability 改动后 | host config、生成文档、治理文档、phase gate、capability output 和 artifact validator 一致性检查 |
+| generated | `bun run gen:skill-docs` | 修改 `*.tmpl`、host config、preamble 后 | 刷新生成的 skill surface |
+| state | `gxpm issue create/status/transition` | state graph 或 phase 规则改动后 | 本地 `.gxpm` 真值写回和恢复验证 |
+| capability | `gxpm capability list/show` | 新增或修改 runtime capability contract 后 | 检查 input/output、mutation、idempotency、failure mode 和 evidence metadata |
+| evidence | `bun test test/evidence.test.ts test/investigate.test.ts` | issue-local evidence store、browser/investigation/review 证据写入改动后 | 路径安全、partial failure evidence、截图/日志路径和 payload 保持兼容 |
+| runtime | `gxpm issue ready/claim/release/reconcile-claim`、`gxpm run start/list/status/event`、`gxpm workspace plan/ensure/cleanup`、`gxpm orchestrator tick --dry-run` | claim lifecycle、run ledger、workspace runtime、orchestrator dry-run 改动后 | 执行运行时原语、路径安全、只读派发判断 |
+| artifact | `gxpm triage init`、`gxpm plan init`、`gxpm dispatch init`、`gxpm implement verify`、`gxpm local-verify ac-check`、`gxpm ac-check self-review`、`gxpm self-review ship`、`gxpm ship pr-check`、`gxpm pr-check verify`、`gxpm verify qa`、`gxpm qa land`、`gxpm artifact list/read` | artifact store 或 phase gate 改动后 | 产物写入、读取、索引和 gate 验证 |
+| human-docs | `gxpm wiki init`、`gxpm wiki update`、`gxpm wiki query <text>`、`gxpm wiki status` | 人类需要本地项目说明书、onboarding 或治理文档导航 | 可选原生 wiki、本地索引和 Markdown 概览 |
+| agent-code-intel | GitNexus MCP: `list_repos`、`query`、`context`、`impact`、`detect_changes`、`cypher` | Agent 需要代码理解、调试、重构影响面或 PR 风险判断 | 图谱驱动的代码智能、调用链、影响半径和 diff 影响分析 |
+| future-e2e | 待实现 | browser/runtime capability 落地后 | 真实浏览器和 agent workflow 证据 |
+| future-eval | 待实现 | 高风险 prompt/capability 改动 | LLM judge 或 paid eval，需先确认成本 |
+
+## 生成物规则
+
+- `SKILL.md.tmpl` 是真值，`SKILL.md` 是生成产物。
+- 修改模板后必须运行 `bun run gen:skill-docs` 并提交模板与生成物。
+- 生成物冲突只能通过模板和生成器解决，再重新生成。
+- `bun run check` 必须能发现生成物漂移。
+- scaffold check 流程的真值是 `scripts/scaffold-check.ts`；`gxpm check` 和 `gxpm-check.ts` 只能调用它。
+- scaffold check 必须能发现 layered workflow 漂移：phase gate required artifact、capability output artifact 和 artifact validator 覆盖必须一致。
+- skill 模板中的 gate command、artifact read list 和 transition summary 必须由 `scripts/gen-skill-docs.ts` 从 phase gate registry 生成。
+- README 只展示稳定入口命令，不复制完整 phase gate 链；完整 gate guidance 以生成的 `skills/gxpm/SKILL.md` 为准。
+- `docs/architecture/gxpm-v0-contract.md` 可保留人类可读列表，但必须由测试证明和 phase、artifact、gate registry 一致。
+
+## Phase Artifact 规则
+
+- 新增 phase artifact initializer 时，优先使用 `core/phase-artifact.ts` 的 `createPhaseArtifactInitializer`。
+- initializer 文件只声明 required phase、artifact type、label 和 draft payload。
+- 不要在每个 initializer 中重复 `readIssueState`、phase 校验和 `writeArtifact` 样板。
+- `triage` 这类没有前置 phase gate 的入口 artifact 可以保留专用实现。
+- `ARTIFACT_TYPES` 可以包含 non-gate artifact；只有 `GATE_ARTIFACT_TYPES` 需要 phase gate command 和 initializer 绑定。
+- 每个 `ARTIFACT_TYPES` 成员都必须被 `core/artifact-validator.ts` 覆盖；即使 schema 暂时宽松，也要显式声明原因。
+- 新增 artifact-backed transition 时，必须先更新 `core/phase-gates.ts`；`scripts/phase-artifact-commands.ts` 只绑定 initializer 和 success message。
+- `test/phase-gates.test.ts` 必须证明 CLI artifact command 顺序和 gate rule 顺序保持一致。
+- gate 测试需要把通用 phase setup 放在 `test/helpers/workflow.ts`，不要在每个 gate 文件重复写完整前置 phase 链。
+- `test/helpers/workflow.ts` 的 phase setup 顺序必须从 phase gate registry 派生，不再手写第二份 workflow chain。
+- gate 测试文件只保留当前 gate 的 artifact payload、blocked event、CLI command 和 transition 断言。
+
+## Execution Runtime 规则
+
+- `core/capabilities.ts` 是 runtime capability contract 的描述性 registry。新增 capability slice 时，先声明 input/output、mutation scope、idempotency、failure modes、commands 和 source anchors，再接执行实现。
+- 每个 phase gate required artifact 都必须至少由一个 capability 的 `outputContract.artifacts` 声明。Command 不能成为唯一知识来源。
+- `gxpm capability list/show` 必须保持只读；它只能检查 registry，不得执行 capability、写 artifact、claim issue 或调用外部 provider。
+- `gxpm run *` 只记录或读取 issue-local run ledger；不得隐式推进 phase。
+- `gxpm issue claim/release/reconcile-claim` 只更新本地 issue claim 生命周期；不得隐式推进 phase。
+- `gxpm workspace plan` 是只读路径规划；`ensure` 只创建/复用当前 issue workspace；`cleanup` 只能删除该 issue 对应 workspace。
+- workspace key 必须由 issue identifier 派生并限制在 `[A-Za-z0-9._-]`，不允许把用户输入拼进任意路径。
+- `gxpm orchestrator tick --dry-run` 必须保持只读：不 claim、不创建 workspace、不启动 agent、不写 artifact、不 transition。
+- 真正的长驻 poll/retry daemon 需要另行设计；不要把 dry-run tick 偷偷扩成后台服务。
+
+## Evidence Store 规则
+
+- `core/evidence.ts` 是 issue-local 原始证据的唯一写入/路径分配入口。新增 command、browser、review、release 或 investigate 证据时，先使用它分配 `evidence/<kind>/<filename>`，不要在调用方手拼 `.gxpm/issues/<id>/evidence` 路径。
+- evidence filename 必须是单一安全文件名，不能包含 `/`、`..` 或绝对路径。issue id 校验必须复用 `core/state.ts`，写入前必须确认 issue state 存在。
+- phase artifact 和 evidence 分工保持清楚：结论、gate 结果和验收状态写 `artifacts/*.json`；截图、console、命令输出、review 原文或调查过程写 `evidence/`。
+- `gxpm-investigate` 必须保持 partial evidence 行为：任何 cmux 子命令失败前已经收集到的 URL、viewport、snapshot、screenshot、console 等内容都要落到 `evidence/investigations/*.json`。
+
+## 失败归因协议
+
+不要直接说“这是旧问题”或“与本次无关”。需要满足以下任一证据：
+
+1. 同一命令在 base/main 上也失败。
+2. 有仓库已有记录证明该失败是基线噪声。
+3. 无法验证时，明确标记为“未验证，可能相关”，并把风险写进汇报。
+
+## 提交规则
+
+- 每个提交只表达一个逻辑变化。
+- 模板改动和生成物刷新可以同一提交，但不要混入无关重构。
+- 测试基础设施、host adapter、产品文档变更应尽量独立，便于回滚。
+- 提交前至少运行 `bun test`、`bun run check`、`git diff --check`。
+- 主目录 checkout 必须保持在 `main`。`gxpm gate branch-policy` 会阻止 canonical main checkout 在非 `main` 分支上提交或推送；feature 分支应在 dedicated git worktree 中运行。
+
+## Live Install 风险
+
+未来 gxpm 支持本地 `.agents/` 或 `.claude/` dev install 后，修改模板和生成器可能立即影响其他会话。大改前先确认：
+
+- 当前 host skill 是 symlink 还是 copy。
+- 是否有并行会话依赖当前安装。
+- 是否需要先切回稳定全局安装或隔离 worktree。
+
+## 需求确认 / Brainstorming Gate
+
+- 新的非平凡任务或范围变化，先做 read-only 探查，再给用户确认目标、范围、非目标、成功标准和预计改动。
+- 优先使用当前 host 的原生选择表单。Codex 中如果 `request_user_input` 在当前模式可用，就用 1 个短问题和 2-3 个互斥选项；不可用时用简短文字确认，不伪装成表单。
+- 用户明确说“直接做 / 继续推进 / 按已有计划执行”时，可以跳过确认闸门。
+- 外部 tracking id 只能写入 artifact 作为来源信息，不作为 GXPM-N；本地 issue 永远用 `gxpm issue create --auto-id`。
+- Superpowers 和 gstack 只作为上游交互模式参考，不能引入为 gxpm 运行时依赖。
+
+## gxpm 原生 Wiki
+
+- `gxpm wiki` 是可选的人类文档面，不是 Agent 默认代码智能层；Agent 的代码理解、调试、重构和 review 默认使用 GitNexus。
+- `gxpm wiki init` 生成 gxpm 自有的 `.gxpm/wiki/index/files.json`、`.gxpm/wiki/index/graph.json`、`.gxpm/wiki/content/` 和 `.gxpm/wiki/state.json`。
+- `gxpm wiki update` 只在人类需要刷新本地项目说明书时手动运行；V1 是确定性本地索引、导入图谱和 Markdown 概览，不调用 IDE 或外部付费服务。
+- `gxpm wiki status` 报告原生 wiki 的 absent/current/stale 状态。原生 wiki stale 的标准包括 state/index 缺失、`baseCommit` 落后当前 `HEAD`、或已索引的 git-tracked 文件发生变更。
+- 原生 wiki 优先使用 `git ls-files` 索引 git-tracked 文本文件；git 不可用时退回同样 skip-list 的本地扫描。`.codex/`、`.claude/`、`.gxpm/`、`.qoder/` 等 ignored/local/generated 内容以及未跟踪 scratch 文件不得进入仓库知识索引。
+- `gxpm wiki query <text>` 基于结构化索引返回 source files 和 suggested human docs，适合作为人工项目导览，不作为 Agent 深层代码导航替代。
+- `gxpm wiki context <issue-id>` 基于 issue state/artifacts 生成查询并返回相关 source files 与 suggested human docs；需要把结果落盘时使用 `--write-artifact` 写入非 gate 的 `wiki-context` artifact。
+- SessionStart、post-checkout 和 post-commit 不自动刷新或注入 wiki；如果人类需要最新 wiki，显式运行 `gxpm wiki update`。
+- `.gxpm/wiki/` 保持 git 外状态；需要提交的是生成逻辑、契约和测试，不提交具体仓库 wiki 内容。
+
+## 长任务规则
+
+长时间测试、E2E、浏览器验证和部署验证必须持续轮询到结束。不能把“后台会通知”当作完成证据。每次轮询只汇报新进展、失败和下一步。
+
+## 规格驱动开发（SDD）宪法
+
+gxpm 采用 Spec-Driven Development 方法论。`templates/constitution-template.md` 定义 Nine Articles，以下为可直接映射到 gxpm 的条款：
+
+| Article | gxpm 映射 | 检查点 |
+|---------|----------|--------|
+| Capability-First | `core/capabilities.ts` 必须先声明 capability slice | plan phase `constitutionCheck.capabilityDeclared` |
+| Test-First | 红-绿-重构，`bun test` 为 fast gate | plan phase `constitutionCheck.testStrategyDefined` |
+| Simplicity Gate | 最多 3 个模块/特性，MVP 优先 | plan phase `constitutionCheck.simplicityJustified` |
+| Anti-Abstraction | 直接使用框架特性，不造 wrapper | code review 时检查 |
+| Integration-First | 集成测试用真实环境，单元测试才 mock | plan phase `constitutionCheck.integrationPathClear` |
+
+### Phase -1 Gates
+
+在 `triage -> plan` 推进前，implementation-plan artifact 自动包含 `constitutionCheck` 字段：
+
+- `capabilityDeclared` — 是否已在 capabilities registry 声明
+- `testStrategyDefined` — 实现计划是否包含测试策略
+- `simplicityJustified` — 复杂度是否最小可行
+- `integrationPathClear` — 集成测试是否计划用真实环境
+
+Spike/调查类 issue（`type=spike`）可跳过 Phase -1 Gates。Feature 交付类 issue（默认类型）必须全部通过。
+
+## 文档边界
+
+- `AGENTS.md` 只放不可推断的执行边界。
+- `CLAUDE.md` 只放 Claude Code 启动差异。
+- 专项规则放 `docs/governance/`，不要把所有细节塞回根文件。

package/docs/governance/gherkin-style.md

@@ -0,0 +1,90 @@
+# Gherkin 写作风格指南 (v1)
+
+> 本文档源自 AutomationPanda/gherkin-guidelines-for-ai (MIT)，加 gxpm 本地补充。
+> 所有 gxpm-driven issue 在 specify 阶段必须遵循本规则集。
+
+## 核心原则
+
+- **行为驱动**：描述系统*做什么*而非*怎么做*
+- **领域语言**：使用 CONTEXT.md 中的术语，不出现 UI/HTTP/SQL 等技术词
+- **示例规约**：scenario 用具体例子展示行为
+- **每个 scenario 一个行为**
+- **可独立执行**：scenario 之间无顺序依赖
+
+## Feature 结构
+
+- 单一 `Feature:` 标题与文件名一致
+- User Story 紧跟标题：
+  - `As a <role>`
+  - `I want <goal>`
+  - `So that <reason>`
+
+## Scenario 设计规则
+
+- 单行、行为聚焦的标题
+- 步骤可按时间顺序执行
+- 声明式语言，非命令式
+- 不混合多个无关关注点（功能 + 性能 + 可访问性必须拆分）
+- 步骤数 < 10，超过用 data table
+
+## Given / When / Then 语义
+
+- `Given` 建立上下文（Arrange）
+- `When` 触发动作（Act）
+- `Then` 验证可观察结果（Assert）
+
+**严格顺序**：`Given → When → Then`，禁止重复阶段。
+
+**关键词**：
+- `And` 续相同类型（OK）
+- `But` 用于对比（少用）
+- **禁止 `Or`** —— 拆 Scenario Outline 或独立 scenario
+
+**可观察结果**：`Then` 必须可从场景文本验证。禁止 "it works"、"it succeeds" 这类模糊断言；必须说出"发生了什么"、"用户看到什么"、"系统报告什么"。
+
+## 词汇与命名
+
+- 整个 issue 内使用稳定词汇，禁止同义词替换
+- 第三人称、现在时、主谓结构
+- 字符串参数用双引号
+- 步骤数据用 doc string (`"""`) 或 data table，禁止用 `And` 串联
+
+## 反模式（禁止）
+
+- 在 Given/When/Then 写入 UI 选择器、XPath、`click #id`
+- 在 Then 写 SQL 断言、HTTP 状态码（除非这就是被测的接口）
+- 占位符数据：`foo`、`bar`、`test`、纯数字 `123`（数字若有业务含义可用）
+- 一个 scenario 多个行为
+- 步骤超过 10 个
+- 把"用户登录"描述成 10 步点击；改用状态："用户已以 Editor 身份登录"
+
+## gxpm 本地补充
+
+- **中文允许**：领域词允许中文，但同一 issue 内保持中英一致
+- **必须引用 CONTEXT.md 术语**：scenario 中提及的实体名必须在 CONTEXT.md 中有定义；新词需先扩展 CONTEXT.md
+- **stubPath 必须真实**：每个 scenario 的 `stubPath` 字段指向的测试文件必须存在
+- **scenario.id 命名**：`scn-NN`（两位数字补零）
+- **禁止 `<placeholder>` 留存**：specifier 草拟阶段允许 `<placeholder>` 字符串占位，但 `gxpm specify confirm` 会拒绝任何残留 placeholder 的 spec
+
+## Pre-confirm 自查清单
+
+specifier agent 在调用 `gxpm specify confirm` 前必须自查：
+
+- [ ] 单一行为，可独立执行
+- [ ] 无混合无关关注点
+- [ ] 词汇稳定，CONTEXT.md 术语对齐
+- [ ] 领域级抽象，无 UI/HTTP/SQL 管道术语
+- [ ] 最小但充分的 Given
+- [ ] 真实示例数据（无 foo/bar/test）
+- [ ] 第三人称、现在时、主谓结构
+- [ ] 严格 Given → When → Then，Then 可观察
+- [ ] 步骤数 < 10
+- [ ] 每个 scenario.stubPath 真实存在
+- [ ] 全文无 `<placeholder>` 残留
+
+## 参考
+
+- [AutomationPanda/gherkin-guidelines-for-ai](https://github.com/AutomationPanda/gherkin-guidelines-for-ai)（一手规则源）
+- `CONTEXT.md`（领域词典）
+- `docs/brainstorms/2026-05-14-bdd-then-tdd-design.md`（设计 spec）
+- `docs/plans/bdd-then-tdd-plan.md`（实施计划）