docs: complete v2.3.0 milestone — archive planning artifacts

.planning/MILESTONES.md

@@ -1,5 +1,31 @@
 # Project Milestones: RuleZ (AI Policy Engine)
 
+## v2.3.0 Multi-Runtime Skill Portability (Shipped: 2026-03-18)
+
+**Delivered:** New `rulez skills` subcommand family — discover, transform, and install Claude Code skills to any AI runtime. Author once in `.claude/`, convert at install time, run everywhere.
+
+**Phases completed:** 34-38 (5 phases, ~2,099 new Rust LOC)
+**Timeline:** 2026-03-16 → 2026-03-17 (2 days)
+**PR:** #116 — 9/9 CI checks passed (Release + Full Validation)
+
+**Key accomplishments:**
+
+- `Runtime` enum covering Claude, OpenCode, Gemini, Codex, Custom — each profile resolves its own skills dir, command separator, tool name style, and path prefix
+- Skill discovery scans `.claude/skills/` and `.claude/commands/` plus extra sources (mastering-hooks at repo root)
+- 6-transform pipeline: tool name rewrite, path references, command filename flattening, YAML frontmatter conversion, MCP tool exclusion (Gemini), colors
+- `rulez skills install --runtime <rt>` / `--dry-run` / `rulez skills clean` — clean-install writer
+- Config file generation: marker-based GEMINI.md updates, AGENTS.md generation for Codex
+- `rulez skills status`, `rulez skills diff --runtime <rt>`, `rulez skills sync` — full DX subcommand family
+
+**Known Gaps (accepted as tech debt):**
+- CONFIG-04: mastering-hooks uses generic transform pipeline — no context-aware Gemini rewriting (todo)
+- DX-04: colorized terminal output not implemented — plain println!, no color crate (todo)
+
+**Stats:**
+- 5 phases (34-38), ~2,099 Rust LOC — 13 source files added across `rulez/src/skills/` and `rulez/src/cli/`
+
+---
+
 ## v2.2.2 Documentation Audit & Multi-CLI Guides (Shipped: 2026-03-17)
 
 **Delivered:** Complete documentation overhaul — all reference docs audited against source code, per-CLI usage guides created, and new feature documentation for external logging, lint, and test.

.planning/PROJECT.md

@@ -8,9 +8,9 @@
 
 | Component | Location | Priority | Status |
 |-----------|----------|----------|--------|
-| **RuleZ Core** | `rulez/` | P1 - Primary | v1.4 Shipped |
+| **RuleZ Core** | `rulez/` | P1 - Primary | v2.3.0 Shipped |
 | **Mastering Hooks** | `mastering-hooks/` | P2 - Secondary | Complete (skill) |
-| **RuleZ UI** | `rulez-ui/` | P1 - Primary (v1.5) | M1 Scaffold Complete, v1.5 Active |
+| **RuleZ UI** | `rulez-ui/` | P1 - Primary | Complete (Tauri 2.0) |
 
 ## Core Value
 
@@ -32,9 +32,10 @@ RuleZ positions itself as comparable to:
 
 ## Current State
 
-### RuleZ Core (v2.2.2)
+### RuleZ Core (v2.3.0)
 - Policy engine with blocking, injection, validation, inline scripting, schema validation
-- CLI: init, install, uninstall, validate, logs, explain, debug, repl, test, lint, upgrade
+- CLI: init, install, uninstall, validate, logs, explain, debug, repl, test, lint, upgrade, skills
+- `rulez skills` family: install, clean, status, diff, sync — cross-runtime skill portability
 - Multi-CLI support: Claude Code, Gemini, Copilot, OpenCode (install/doctor commands)
 - Parallel rule evaluation, config caching, globset matching
 - E2E test harness across 5 CLIs (Claude Code, Gemini, Copilot, OpenCode, Codex)
@@ -89,43 +90,20 @@ RuleZ positions itself as comparable to:
 - ✓ FEAT-01..03: Feature documentation (external logging, lint, test) — v2.2.2
 - ✓ AUDIT-01..02: Accuracy audit against source code and --help output — v2.2.2
 
-### Active
+- ✓ PROFILE-01..04: Runtime profiles (Claude, OpenCode, Gemini, Codex, Custom) with discovery — v2.3.0
+- ✓ XFORM-01..05: Transform pipeline (tool names, paths, filenames, frontmatter, MCP exclusion) — v2.3.0
+- ✓ CLI-01..04: `rulez skills install/clean` with dry-run and clean-install writer — v2.3.0
+- ✓ CONFIG-01..03: GEMINI.md marker-based update, AGENTS.md generation, non-skill preservation — v2.3.0
+- ✓ DX-01..03: `rulez skills status/diff/sync` subcommand family — v2.3.0
 
-- [ ] PROFILE-01: Runtime profiles define per-platform conventions (dirs, separators, tool style)
-- [ ] PROFILE-02: Skill discovery scans .claude/skills/, .claude/commands/, and extra dirs
-- [ ] PROFILE-03: Extra skill sources (mastering-hooks at repo root) discovered automatically
-- [ ] XFORM-01: Tool names converted from PascalCase to runtime conventions
-- [ ] XFORM-02: Path references rewritten (~/.claude/ -> runtime equivalents)
-- [ ] XFORM-03: Command filenames flattened (dot to hyphen) with cross-reference rewriting
-- [ ] XFORM-04: YAML frontmatter converted (allowed-tools -> tools, color hex, strip unsupported)
-- [ ] XFORM-05: MCP tools excluded for Gemini, preserved for OpenCode
-- [ ] CLI-01: `rulez skills install --runtime <rt>` installs to target runtime
-- [ ] CLI-02: `rulez skills install --dry-run` previews without writing
-- [ ] CLI-03: `rulez skills clean --runtime <rt>` removes generated files
-- [ ] CONFIG-01: Auto-update GEMINI.md skill registry with marker sections
-- [ ] CONFIG-02: Auto-generate AGENTS.md for Codex with skill registry
-- [ ] CONFIG-03: Mastering-hooks platform references rewritten context-aware
-- [ ] DX-01: `rulez skills status` shows human-readable dates and freshness
-- [ ] DX-02: `rulez skills diff --runtime <rt>` shows colored diff of changes
-- [ ] DX-03: `rulez skills sync` installs to all detected runtimes
-- [ ] DX-04: Colorized output with progress indicators
+### Active (next milestone)
 
-## Current Milestone: v2.3.0 Multi-Runtime Skill Portability
+*(None defined — run `/gsd:new-milestone` to define next milestone requirements)*
 
-**Goal:** Build an installer-based conversion pipeline that transforms canonical Claude Code skills into runtime-specific installations. Author once in `.claude/`, convert at install time, run everywhere.
+### Known Tech Debt
 
-**Target features:**
-- Runtime profiles and skill discovery (Phase 34 — DONE)
-- Content transformation engine with 6 transform types (Phase 35 — DONE)
-- CLI integration with file writer (Phase 36 — DONE)
-- Config file generation for GEMINI.md, AGENTS.md (Phase 37)
-- DX polish: status, diff, sync, clean (Phase 38)
-
-**Plan:** `docs/plans/multi-runtime-skill-portability.md`
-
-## Shipped: v2.2.2 Documentation Audit & Multi-CLI Guides (2026-03-17)
-
-All documentation audited against source code, per-CLI usage guides created for Claude Code/Gemini/OpenCode, feature docs for external logging/lint/test. 11/11 requirements satisfied, 4 phases, 8 plans.
+- [ ] CONFIG-04: mastering-hooks context-aware transform for non-Claude runtimes — todo added
+- [ ] DX-04: Colorized terminal output with progress indicators for skills CLI — todo added
 
 ### Out of Scope
 
@@ -167,9 +145,11 @@ All documentation audited against source code, per-CLI usage guides created for
 | LazyLock pre-compiled validators | <0.1ms validation overhead at runtime | ✓ Good |
 | ubuntu-22.04 for Tauri builds | webkit2gtk-4.1 requirement, ubuntu-latest may break | ✓ Good |
 | E2E gate before Tauri builds | Fast feedback (2-3min) prevents expensive failed builds | ✓ Good |
-| Hardcoded Rust transforms, not YAML-configurable | 4 well-known runtimes + Custom variant covers long tail | — Pending |
-| Clean-install writer (rm + recreate) | Prevents orphan files across versions, proven in GSD | — Pending |
-| `rulez skills` subcommand family, not extending `rulez install` | Hook registration and skill distribution are orthogonal | — Pending |
+| Hardcoded Rust transforms, not YAML-configurable | 4 well-known runtimes + Custom variant covers long tail | ✓ Good |
+| Clean-install writer (rm + recreate) | Prevents orphan files across versions, proven in GSD | ✓ Good |
+| `rulez skills` subcommand family, not extending `rulez install` | Hook registration and skill distribution are orthogonal | ✓ Good |
+| Skip colorized output (DX-04) in v2.3.0 | Ship fast, polish in next milestone | ⚠️ Revisit |
+| Generic transform for mastering-hooks (CONFIG-04) | Context-aware rewriting is complex; generic covers the 80% case | ⚠️ Revisit |
 
 ## Quality Gates
 
@@ -188,6 +168,6 @@ All documentation audited against source code, per-CLI usage guides created for
 
 ---
 
-*Last updated: 2026-03-16 after v2.3.0 milestone start*
+*Last updated: 2026-03-18 after v2.3.0 milestone*
 *Reorganized as monorepo on 2026-02-06*
 *Renamed from CCH to RuleZ*

.planning/RETROSPECTIVE.md

@@ -42,15 +42,60 @@
 
 ---
 
+## Milestone: v2.3.0 — Multi-Runtime Skill Portability
+
+**Shipped:** 2026-03-18
+**Phases:** 5 (34-38) | **Plans:** 0 (direct implementation) | **Sessions:** ~2
+
+### What Was Built
+- `Runtime` enum with 5 variants (Claude, OpenCode, Gemini, Codex, Custom) — each resolves its own install paths and conventions
+- `SkillInventory` discovery: scans `.claude/skills/`, `.claude/commands/`, and extra sources (mastering-hooks at repo root)
+- 6-transform pipeline across 6 dedicated files: tool name rewrite, path refs, command filename flattening, frontmatter conversion, MCP exclusion, color handling
+- `rulez skills install --runtime <rt>` / `--dry-run` / `rulez skills clean` with clean-install writer
+- GEMINI.md marker-based update and AGENTS.md auto-generation for Codex
+- `rulez skills status`, `rulez skills diff`, `rulez skills sync` — complete DX subcommand family
+- 2,099 new Rust LOC across 13 source files; PR #116 — 9/9 CI checks passed
+
+### What Worked
+- **Module-first design**: Creating `rulez/src/skills/` as a dedicated module with clear internal boundaries (discovery → transform → writer → config_gen) made the dependency chain clean
+- **`Custom` runtime variant**: Adding a catch-all `Runtime::Custom(PathBuf)` from the start avoided needing a separate "generic" code path — the `--dir` flag routes through the same pipeline
+- **Clean-install writer pattern**: Removing the target directory before writing prevents orphaned files from previous installs — zero special-case cleanup logic needed
+- **2-day ship velocity**: Implementing 5 phases without GSD phase artifacts (directly in release branch) moved faster than the full execute-phase cycle for a well-specified feature
+
+### What Was Inefficient
+- **Missing GSD phase artifacts**: No PLAN.md, SUMMARY.md, VERIFICATION.md, or VALIDATION.md for any of the 5 phases — the milestone audit had to rely on integration checker code analysis instead of structured evidence. This made the audit slower and less reliable.
+- **CONFIG-04 and DX-04 slipped**: Two requirements were marked `[x]` in REQUIREMENTS.md but not fully implemented (no context-aware mastering-hooks transform, no color output). Should have caught this before tagging.
+- **Local main divergence**: Local branch had 18 diverging commits vs. 1 on origin/main after the squash merge — had to use `git checkout origin/main -- .planning/` to sync. Avoid letting local main diverge from remote after squash merges.
+
+### Patterns Established
+- `rulez skills` as a separate subcommand family (orthogonal to `rulez install` which handles hook registration)
+- `<!-- RULEZ_SKILLS_START -->` / `<!-- RULEZ_SKILLS_END -->` marker pattern for idempotent config file injection
+- `TransformPipeline::for_runtime(runtime)` as the factory for per-runtime transform chains
+
+### Key Lessons
+1. **Mark requirements complete only when implemented** — checked `[x]` in REQUIREMENTS.md before confirming DX-04 and CONFIG-04 were in the code. The audit caught it, but it added overhead. Rule: requirements table reflects implementation state, not intent.
+2. **Direct-to-release-branch implementation skips GSD workflow** — fast to ship but loses verification artifacts. For well-specified features with CI coverage this is acceptable; for complex features use `gsd:execute-phase` to get the evidence trail.
+3. **Squash-merge leaves local main diverged** — after `release/v2.3.0` merged to `origin/main`, local `main` had 18 unrelated commits. Clean up with `git checkout origin/main -- <dirs>` when `git reset --hard` is blocked by RuleZ itself.
+
+### Cost Observations
+- Model mix: ~70% opus, ~30% sonnet
+- Sessions: ~2
+- Notable: Feature implementation + audit + milestone completion in a single extended session
+
+---
+
 ## Cross-Milestone Trends
 
 ### Process Evolution
 
 | Milestone | Sessions | Phases | Key Change |
 |-----------|----------|--------|------------|
 | v2.2.2 | ~4 | 4 | Docs-only milestone pattern, audit-last approach |
+| v2.3.0 | ~2 | 5 | Direct-to-release-branch implementation, integration checker as substitute audit |
 
 ### Top Lessons (Verified Across Milestones)
 
 1. Dedicated audit phases catch drift that incremental reviews miss
 2. Docs-only milestones are fast and valuable — prevents documentation debt from accumulating
+3. Requirements table must reflect implementation state, not intent — check [x] only when code exists
+4. Direct branch implementation trades GSD evidence trail for speed — acceptable when CI is comprehensive