@geminix/gxpm 0.1.0

package/skills/gxpm-review-changes/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: gxpm-review-changes
+description: Structured code review using change detection and impact analysis. Use when reviewing a pull request, assessing risk before merging, or checking for missing test coverage after changes.
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+## gxpm-review-changes
+
+Perform a thorough, risk-aware code review using GitNexus.
+
+### 入口条件
+
+- **触发时机**：Use when reviewing a pull request, assessing risk before merging, or checking for missing test coverage after changes.
+- **目标**：Perform a thorough, risk-aware code review using GitNexus.
+
+### 可操作流程
+
+1. Run `detect_changes` to map the diff to affected symbols and execution flows.
+2. For high-risk symbols, run `impact` with `direction: "upstream"` and `includeTests: true` when useful.
+3. Use `context` on key symbols to understand callers, callees, and process participation.
+4. Use `query` for broader execution-flow questions raised by the diff.
+5. For any untested changes, suggest specific test cases.
+
+### 红旗清单 / 反模式
+
+- Start with `detect_changes`, then inspect only the highest-risk symbols.
+- Use `impact`/`context` before raw `cypher`.
+- Target: complete any review/debug/refactor task in ≤5 graph tool calls.
+
+### 验证清单 / 出口条件
+
+Provide findings grouped by risk level (high/medium/low) with:
+- What changed and why it matters
+- Test coverage status
+- Suggested improvements
+- Overall merge recommendation

package/skills/gxpm-setup/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: gxpm-setup
+description: Scaffold per-repo configuration for gxpm skills. Use when first using gxpm in a repo, or when issue tracker, triage labels, or domain doc layout is unclear.
+---
+
+# Setup
+
+Scaffold the per-repo configuration that gxpm skills consume:
+
+- **Issue tracker** — where issues live (GitHub, Linear, or local markdown)
+- **Triage labels** — the strings used for the five canonical triage roles
+- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
+
+## 入口条件
+
+**何时触发**
+- 首次在当前 repo 使用 gxpm skills。
+- `gxpm-triage`、`gxpm-planning` 等 skill 缺少 issue tracker 或 label 上下文。
+- 用户说 "setup gxpm"、"configure gxpm"、"初始化 gxpm"。
+- 刚创建新 repo，需要配置 gxpm 工作流。
+
+**Skill 边界**
+- 需要创建 issue → `/gxpm-triage`
+- 需要写计划 → `/gxpm-planning`
+- 需要调试 → `/gxpm-diagnose`
+
+## 可操作流程
+
+### 1. Explore
+
+Read the current repo state:
+
+- `git remote -v` — GitHub? GitLab? No remote?
+- `AGENTS.md` / `CLAUDE.md` at root — does either exist?
+- `CONTEXT.md` / `CONTEXT-MAP.md` at root
+- `docs/adr/` or `.gxpm/out-of-scope/` directories
+- Existing `.gxpm/config.json`
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Walk the user through three decisions **one at a time**.
+
+**Section A — Issue tracker.**
+
+Default: if `git remote` points at GitHub, propose GitHub Issues. Otherwise offer:
+
+- **GitHub** — uses `gh` CLI
+- **Linear** — uses Linear CLI
+- **Local markdown** — issues as files under `.gxpm/issues/` (gxpm default)
+- **Other** — ask user to describe the workflow in one paragraph
+
+**Section B — Triage label vocabulary.**
+
+The five canonical roles:
+
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter
+- `ready-for-agent` — fully specified, AFK-ready
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+Default: each role's string equals its name. Ask if they want to override any.
+
+**Section C — Domain docs.**
+
+Confirm layout:
+
+- **Single-context** — one `CONTEXT.md` + `docs/adr/` at repo root (most repos)
+- **Multi-context** — `CONTEXT-MAP.md` at root pointing to per-context `CONTEXT.md` files (monorepo)
+
+### 3. Write config
+
+Write to `.gxpm/agents/`:
+
+```
+.gxpm/
+├── agents/
+│   ├── issue-tracker.md
+│   ├── triage-labels.md
+│   └── domain.md
+```
+
+Also update `AGENTS.md` or `CLAUDE.md` with an `## Agent skills` block if not present.
+
+## 红旗清单 / 反模式
+
+- **STOP：不要假设用户的 issue tracker。** 总是先检查 `git remote` 再提问。
+- **STOP：不要覆盖用户已有的配置。** 如果 `.gxpm/agents/` 已存在，先展示当前内容，询问是否更新。
+- **STOP：不要同时问三个问题。** 一次只问一个 section，得到回答后再继续。
+
+## 验证清单 / 出口条件
+
+- [ ] `.gxpm/agents/issue-tracker.md` 已写入，包含 tracker 类型和 CLI 工具。
+- [ ] `.gxpm/agents/triage-labels.md` 已写入，包含 5 个 canonical roles 的映射。
+- [ ] `.gxpm/agents/domain.md` 已写入，包含 CONTEXT.md / ADR 布局规则。
+- [ ] `AGENTS.md` 或 `CLAUDE.md` 已更新 `## Agent skills` 区块（如果不存在）。
+- [ ] 用户已确认配置正确。
+
+**失败时路由**
+- 配置后需要创建 issue → `/gxpm-triage`
+- 配置后需要制定计划 → `/gxpm-planning`

package/skills/gxpm-specifier/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: gxpm-specifier
+description: BDD behavior specification design skill. Use during gxpm specify phase, when user mentions BDD, Gherkin, Given-When-Then, behavior spec, or behavior-first development.
+---
+
+# gxpm-specifier
+
+## Core Principle
+
+**Specify is BDD. Implement is TDD. The two must be separated by a user confirmation.**
+
+在 specify 阶段，**不写一行测试逻辑代码**。产出的仅是 Gherkin 行为注释 + 空函数 stub + 结构化 artifact。
+
+## 入口条件
+
+- gxpm issue 处于 `specify` phase
+- 用户要求"先写行为再写代码"、"BDD 先行"、"Given-When-Then"
+- `dispatch-handoff.json` 已存在
+
+## Constitution Gate（宪法门）
+
+在 specify 阶段，**CANON.md 是最高权威**。每次生成 spec 前，必须：
+
+1. **读取 CANON.md**，提取与当前 feature 相关的 3-5 条核心纪律
+2. **在 spec 开头写入宪法合规声明**：
+   ```markdown
+   ## Constitution Compliance
+   
+   本规格遵循 CANON.md 以下条款：
+   - Article X: [相关条款摘要]
+   - Article Y: [相关条款摘要]
+   - ...
+   
+   任何违反上述条款的实现方案都必须显式说明理由。
+   ```
+3. **检查清单**（spec 末尾必须包含）：
+   - [ ] 没有过工程化（≤3 个核心模块）
+   - [ ] 没有过早抽象（直接使用框架能力）
+   - [ ] 测试优先（contracts → tests → source）
+   - [ ] 无 `[NEEDS CLARIFICATION]` 残留
+
+## [NEEDS CLARIFICATION] 强制标记
+
+遇到以下情况时，**禁止猜测**，必须使用 `[NEEDS CLARIFICATION: 具体问题]` 标记：
+
+- 用户 prompt 未明确的技术栈或架构选择
+- 需求中缺失的边界条件、错误处理策略
+- 与现有代码风格/模式冲突的实现方式
+- 性能、安全、并发等非功能性需求未量化
+- 与上游 artifact（acceptance-contract / implementation-plan）不一致的地方
+
+**规则**：
+- 每个 `[NEEDS CLARIFICATION]` 必须包含具体的、可回答的问题
+- 标记数量 > 3 时，必须暂停生成，向用户呈现所有标记并请求澄清
+- 用户澄清后，替换标记为确定内容，不得删除标记不留痕迹
+
+## Hard Rules
+
+```
+NO TEST LOGIC IN SPECIFY PHASE
+NO IMPLEMENTATION CODE IN SPECIFY PHASE
+NO PLACEHOLDER DATA (foo/bar/test/123)
+NO SCENARIO WITH > 10 STEPS
+NO MIXED CONCERNS IN ONE SCENARIO
+NO <placeholder> SENTINEL REMAINS AT CONFIRM TIME
+NO CONSTITUTION VIOLATION WITHOUT DOCUMENTED RATIONALE
+NO GUESSING — USE [NEEDS CLARIFICATION] INSTEAD
+```
+
+违反任一条 = 删除产出，从 `gxpm specify init` 重新开始。
+
+## 可操作流程
+
+1. 读取上游 artifact：`acceptance-contract`、`implementation-plan`、`dispatch-handoff`
+2. 读取治理文档：`docs/governance/gherkin-style.md`
+3. 在 `test/` 下找 1-2 个既有测试文件作为风格参照
+4. 草拟 Feature + Scenarios（每 scenario `given`/`when`/`then` 各 ≥1 项）
+5. 为每个 scenario 生成空 stub：
+
+   ```ts
+   // Feature: <title>
+   //
+   // Scenario (scn-01): <name>
+   //   Given <given[0]>
+   //   And <given[1]>
+   //   When <when>
+   //   Then <then[0]>
+   //   And <then[1]>
+
+   test("test_<scenario_name_in_snake_case>", () => {
+     // intentionally empty — awaiting user confirmation
+   });
+   ```
+
+6. 运行 `gxpm specify init <issue-id>` 写入 `behavior-spec.json`（自动用 `<placeholder>` 占位）
+7. 直接编辑 `.gxpm/issues/<issue-id>/artifacts/behavior-spec.json`，把所有 `<placeholder>` 替换为真实领域语言（`gxpm specify edit` 命令未实现，请用 $EDITOR 直接打开 JSON 文件）
+8. 调用 AskUserQuestion 呈现三选项：
+   - 行为正确，继续
+   - 需要调整：用户反馈 → 回到步骤 4
+   - 补充边界场景：增加 scenario → 回到步骤 4
+9. 用户确认后运行 `gxpm specify confirm <issue-id>`
+
+## 红旗清单
+
+立即停止并重新开始：
+
+- 在 specify 阶段写了 `expect` / `assert` 语句
+- 用 `foo` / `bar` / `test` 等占位符
+- scenario 步骤 > 10
+- 一个 scenario 同时测功能 + 性能
+- 在 Then 写 UI 选择器、HTTP 状态码（除非接口本身被测）
+- 跳过用户确认直接 `gxpm specify confirm`
+- 跳过 specify 直接 implement（phase-gate 会拒绝）
+- confirm 时 `<placeholder>` 字符串仍残留（`confirmSpecify` 会拒绝）
+
+## 验证清单
+
+每次 `gxpm specify confirm` 前自查：
+
+- [ ] 单一行为，可独立执行
+- [ ] 无混合关注点
+- [ ] 词汇稳定，CONTEXT.md 术语对齐
+- [ ] 领域级抽象，无 UI/HTTP/SQL 管道术语
+- [ ] 最小但充分的 Given
+- [ ] 真实示例数据
+- [ ] 第三人称、现在时、主谓结构
+- [ ] 严格 Given→When→Then，Then 可观察
+- [ ] 步骤数 < 10
+- [ ] 每个 scenario.stubPath 真实存在
+- [ ] 全文无 `<placeholder>` 残留
+- [ ] 用户已通过 AskUserQuestion 或终端确认
+
+## Handoff
+
+`confirmedAt` 写入 → phase 可转 implement → `gxpm-tdd` skill 接管。

package/skills/gxpm-tdd/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: gxpm-tdd
+description: Test-driven development with red-green-refactor loops via vertical slices. Use when user wants to build features or fix bugs using TDD, mentions 'red-green-refactor', wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means. The warning sign: your test breaks when you refactor, but behavior hasn't changed.
+
+**Violating the letter of the rules is violating the spirit of the rules.**
+
+## 入口条件
+
+在以下场景触发本 skill：
+
+- 用户要求使用 TDD 构建功能或修复 bug
+- 用户提到 "red-green-refactor"
+- 用户需要集成测试
+- 用户要求测试优先开发
+
+在 gxpm 工作流中，`implement` 阶段应将首个子任务视为 **tracer bullet**，从该任务开始 TDD 循环。
+
+## 可操作流程
+
+### The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+Implement fresh from tests. Period.
+
+See [references/red-green-refactor.md](references/red-green-refactor.md) for the full red-green-refactor cycle.
+
+### The Specify-First Iron Law
+
+**Before writing ANY test logic, the test scenario MUST already exist in `.gxpm/issues/<id>/artifacts/behavior-spec.json` with `confirmedAt` set.**
+
+If you find yourself writing a test without a corresponding entry in `behavior-spec.json`:
+
+- STOP
+- Delete the test code you wrote
+- Return to specify phase: `gxpm phase rewind <id> --to specify --reason "missing scenario"`
+- Run `gxpm specify revise <id>` to clear `confirmedAt`
+- Add the scenario to `behavior-spec.json`
+- Re-confirm with `gxpm specify confirm <id>`
+- Then resume TDD
+
+**Why:** BDD describes WHAT behavior we want; TDD enforces THAT behavior incrementally. Jumping to TDD without a confirmed BDD spec means the agent is inventing test cases — the precise failure mode this discipline prevents.
+
+**The test stub file at `scenario.stubPath` is your contract.** Open it; the Gherkin comment block at the top is the only legitimate source of assertions you may translate into code.
+
+### 正确做法：垂直切片（Vertical Slices）
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things rather than user-facing behavior
+- Tests become insensitive to real changes
+
+**Correct approach**: Vertical slices via tracer bullets.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+See [references/workflow.md](references/workflow.md) for the full TDD workflow.
+
+### 卡壳时的应对策略
+
+See [references/troubleshooting.md](references/troubleshooting.md) for detailed guidance.
+
+Quick reference:
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
+| Test too complicated | Design too complicated. Simplify interface. |
+| Must mock everything | Code too coupled. Use dependency injection. |
+| Test setup huge | Extract helpers. Still complex? Simplify design. |
+
+### 调试集成
+
+Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
+
+Never fix bugs without a test.
+
+### 添加 mock 或测试工具时
+
+Read [references/mocking.md](references/mocking.md) before adding mocks, changing tests, or adding test-only methods to production code.
+
+See [references/interface-design.md](references/interface-design.md) for designing testable interfaces.
+
+## 红旗清单 / 反模式
+
+### 必须立即停止并重新开始的情况
+
+- Code before test
+- Test after implementation
+- Test passes immediately
+- Can't explain why test failed
+- Tests added "later"
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "Keep as reference" or "adapt existing code"
+- "Already spent X hours, deleting is wasteful"
+- "TDD is dogmatic, I'm being pragmatic"
+- "This is different because..."
+- Writing a test without a matching scenario in `behavior-spec.json`
+- Adding assertions that do not appear in the scenario's `then` clauses
+
+**All of these mean: Delete code. Start over with TDD.**
+
+### 水平切片（Horizontal Slices）
+
+一次性写完全部测试再写全部实现是水平切片，会产生脆弱且脱离实际的测试。必须按垂直切片逐个 RED→GREEN→REFACTOR 推进。
+
+## 验证清单 / 出口条件
+
+每个 TDD 循环完成后检查：
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+[ ] Verify RED executed (test failed for expected reason)
+[ ] Verify GREEN executed (test passes + all others pass + output clean)
+```
+
+### Final Rule
+
+```
+Production code → test exists and failed first
+Otherwise → not TDD
+```
+
+No exceptions without your human partner's permission.
+
+### 验证与证据
+
+单个 TDD 循环的测试验证由测试运行器覆盖。全部 TDD 循环完成后，加载 `/gxpm-verify` 运行完整验证流水线并收集 `local-verify` 证据。
+
+在 gxpm 工作流中：
+- 使用 `gxpm run event <issue-id> <run-id> --type test-passed` 记录测试里程碑。
+- TDD 循环完成后，加载 `/gxpm-verify` 执行完整验证流水线并产出 `local-verify` 证据。
+- 如果在 TDD 过程中发现 bug，先写重现该 bug 的 failing test。仅当根因不明时才切换到 `/gxpm-diagnose` skill。
+
+## 常见说辞表
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
+| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
+| "Existing code has no tests" | You're improving it. Add tests for existing code. |

package/skills/gxpm-tdd/references/interface-design.md

@@ -0,0 +1,23 @@
+# Interface Design for Testability
+
+Reference for `/gxpm-tdd`.
+
+## Deep modules
+
+A deep module encapsulates a lot of functionality in a simple, testable interface which rarely changes. Aim for small interface, deep implementation.
+
+> "The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."
+> — John Ousterhout, A Philosophy Of Software Design
+
+## Testability checklist
+
+- [ ] Can I test this through its public interface only?
+- [ ] Would this test survive a complete internal rewrite?
+- [ ] Is the interface smaller than the implementation?
+- [ ] Are error modes explicit and testable?
+
+## Warning signs
+
+- Constructor takes 5+ dependencies → module is doing too much.
+- Test needs to know internal state → interface is incomplete.
+- Renaming a private function breaks tests → tests are coupled to implementation.

package/skills/gxpm-tdd/references/mocking.md

@@ -0,0 +1,27 @@
+# Mocking Guidelines
+
+Reference for `/gxpm-tdd`. Read this before adding mocks, changing tests, or adding test-only methods to production code.
+
+## Prefer real collaborators
+
+Mock only at system boundaries (HTTP, database, file system, clock). Everything inside the application boundary should use real objects.
+
+## Mocking red flags
+
+- You need to mock more than 2 collaborators for a single test → design is too coupled.
+- The mock verifies it was called with specific arguments → test is coupled to implementation, not behavior.
+- You need a "test-only" method on production code → the seam is in the wrong place.
+
+## Good seams for mocking
+
+| Boundary | Mock strategy |
+|----------|--------------|
+| HTTP client | Stub the transport layer, not the service calling it |
+| Database | In-memory test DB or transaction rollback |
+| File system | Temp directory with cleanup |
+| Clock | Injectable `now()` function or frozen time |
+| Random | Injectable seed |
+
+## One adapter = hypothetical seam. Two adapters = real seam.
+
+If you have one production adapter and one test adapter, the seam is real and worth keeping. If you only have a test adapter, reconsider whether the abstraction pulls its weight.

package/skills/gxpm-tdd/references/red-green-refactor.md

@@ -0,0 +1,61 @@
+## Red-Green-Refactor
+
+Each vertical slice follows this cycle. No skips. No shortcuts.
+
+### RED — Write Failing Test
+
+Write one minimal test showing what should happen.
+
+**Requirements:**
+- One behavior
+- Clear name
+- Real code (no mocks unless unavoidable)
+
+### Verify RED — Watch It Fail (MANDATORY. Never skip.)
+
+```bash
+bun test path/to/test.test.ts
+```
+
+Confirm:
+- Test fails (not errors)
+- Failure message is expected
+- Fails because feature missing (not typos)
+
+**Test passes?** You're testing existing behavior. Fix test.
+
+**Test errors?** Fix error, re-run until it fails correctly.
+
+### GREEN — Minimal Code
+
+Write simplest code to pass the test.
+
+Don't add features, refactor other code, or "improve" beyond the test.
+
+### Verify GREEN — Watch It Pass (MANDATORY)
+
+```bash
+bun test path/to/test.test.ts
+```
+
+Confirm:
+- Test passes
+- Other tests still pass
+- Output pristine (no errors, warnings)
+
+**Test fails?** Fix code, not test.
+
+**Other tests fail?** Fix now.
+
+### REFACTOR — Clean Up
+
+After green only:
+- Remove duplication
+- Improve names
+- Extract helpers
+
+Keep tests green. Don't add behavior.
+
+### Repeat
+
+Next failing test for next feature.

package/skills/gxpm-tdd/references/troubleshooting.md

@@ -0,0 +1,28 @@
+# TDD Troubleshooting
+
+Reference for `/gxpm-tdd`.
+
+## Don't know how to test
+
+Write the wished-for API first. Write the assertion first. If still stuck, ask your human partner — the interface design is unclear.
+
+## Test too complicated
+
+Design is too complicated. Simplify the interface. A hard-to-test module is hard to use.
+
+## Must mock everything
+
+Code is too coupled. Use dependency injection. Move integration points to the edges.
+
+## Test setup is huge
+
+Extract helpers. If still complex after helpers, simplify the design — the module has too many dependencies.
+
+## Test passes immediately
+
+This usually means:
+- The test doesn't actually assert anything meaningful.
+- The implementation was written before the test (violation of Iron Law).
+- The test is asserting on the wrong thing.
+
+**Action:** Stop. Verify the test can fail by deliberately breaking the assertion. If it still passes, delete and rewrite.

package/skills/gxpm-tdd/references/workflow.md

@@ -0,0 +1,50 @@
+## Workflow
+
+### 1. Planning
+
+Before writing any code:
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm which behaviors to test (prioritise)
+- [ ] Identify opportunities for deep modules (small interface, deep implementation)
+- [ ] Design interfaces for testability
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+**You can't test everything.** Focus on critical paths and complex logic.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → verify it fails correctly
+GREEN: Write minimal code to pass → verify it passes
+```
+
+This is your tracer bullet — proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → verify it fails correctly
+GREEN: Minimal code to pass → verify it passes + all other tests pass
+```
+
+Rules:
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+- **Never skip Verify RED or Verify GREEN**
+
+### 4. Refactor
+
+After all tests pass, look for refactor candidates:
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.