docs: add /titan-forge skill (Titan Paradigm execution phase)

.claude/skills/titan-forge/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: titan-forge
+description: Execute the sync.json plan — refactor code, validate with /titan-gate, commit, and advance state (Titan Paradigm Phase 4)
+argument-hint: <--phase N> <--target name> <--dry-run> <--yes>
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Skill, Agent
+---
+
+# Titan FORGE — Execute Sync Plan
+
+You are running the **FORGE** phase of the Titan Paradigm.
+
+Your goal: read `sync.json`, find the next incomplete execution phase, make the actual code changes for each target, validate with `/titan-gate`, commit, and advance state.
+
+> **Context budget:** One phase per invocation. Do not attempt all phases in one session — the context window will fill. Run one phase, report, stop. User re-runs for the next phase.
+
+**Arguments** (from `$ARGUMENTS`):
+- No args → run next incomplete phase
+- `--phase N` → jump to specific phase
+- `--target <name>` → run single target only (for retrying failures)
+- `--dry-run` → show what would be done without changing code
+- `--yes` → skip confirmation prompt
+
+---
+
+## Step 0 — Pre-flight
+
+1. **Worktree check:**
+   ```bash
+   git rev-parse --show-toplevel && git worktree list
+   ```
+   If not in a worktree, stop: "Run `/worktree` first."
+
+2. **Sync with main:**
+   ```bash
+   git fetch origin main && git merge origin/main --no-edit
+   ```
+   If there are merge conflicts, stop: "Merge conflict detected. Resolve conflicts and re-run `/titan-forge`."
+
+3. **Load artifacts.** Read:
+   - `.codegraph/titan/sync.json` — execution plan (if missing: "Run `/titan-sync` first.")
+   - `.codegraph/titan/titan-state.json` — current state
+   - `.codegraph/titan/gauntlet.ndjson` — per-target audit details
+   - `.codegraph/titan/gauntlet-summary.json` — aggregated results
+
+4. **Validate state.** If `titan-state.json` has `currentPhase` other than `"sync"` and no existing `execution` block, stop: "State not ready. Run `/titan-sync` first."
+
+5. **Initialize execution state** (if first run). Add to `titan-state.json`:
+   ```json
+   {
+     "execution": {
+       "currentPhase": 1,
+       "completedPhases": [],
+       "currentTarget": null,
+       "completedTargets": [],
+       "failedTargets": [],
+       "commits": [],
+       "currentSubphase": null,
+       "completedSubphases": []
+     }
+   }
+   ```
+
+6. **Determine next phase.** Use `--phase N` if provided, otherwise find the lowest phase number not in `completedPhases`.
+
+7. **Print plan:**
+   > Phase N: \<label\> — N targets, estimated N commits
+
+8. **Ask for confirmation** before starting (unless `$ARGUMENTS` contains `--yes`).
+
+---
+
+## Step 1 — Phase-specific execution strategies
+
+Each phase type requires different code-change logic:
+
+### Phase 1: Dead code cleanup
+- Delete the symbol/export
+- Verify no consumers: `codegraph fn-impact <target> -T --json`
+- Remove any orphaned imports
+- Run lint to clean up
+
+### Phase 2: Shared abstractions
+- Extract function/interface to new or existing file
+- Update imports in all consumers
+- Verify with: `codegraph exports <file> -T --json`
+
+### Phase 3: Empty catches / error handling
+- Replace `catch {}` with `catch (e) { logger.debug(...) }` or explicit fallback
+- Use contextually appropriate error handling
+- Subphases: each distinct catch pattern = one commit
+
+### Phase 4: Extractor decomposition
+- Split large `walkXNode` switch cases into handler functions
+- Keep dispatcher thin — handler per node kind
+- Subphases: each extractor = one commit
+
+### Phase 5: General decomposition
+- Read the gauntlet recommendation for the specific target
+- Apply the recommended decomposition strategy
+- Subphases: each function split = one commit
+
+### Phase 6: Small FAIL fixes
+- Read the gauntlet recommendation for the specific target
+- Apply the recommended fix (complexity reduction, metric improvement)
+- Group by domain where possible
+
+---
+
+## Step 2 — Per-target execution loop
+
+For each target in the current phase:
+
+1. **Skip if done.** Check if target is already in `execution.completedTargets`. If so, skip.
+
+2. **Update state.** Set `execution.currentTarget` in `titan-state.json`.
+
+3. **Read gauntlet entry.** Find this target in `gauntlet.ndjson` → get recommendation, violations, metrics.
+
+4. **Understand before touching.** Run codegraph commands:
+   ```bash
+   codegraph context <target> -T --json
+   ```
+   If blast radius > 0:
+   ```bash
+   codegraph fn-impact <target> -T --json
+   ```
+
+5. **Check if already fixed.** If the file has changed since gauntlet ran, re-check metrics:
+   ```bash
+   codegraph complexity --file <file> --health -T --json
+   ```
+   If the target now passes all thresholds, skip with note: "Target already passes — skipping."
+
+6. **Read source file(s).** Understand the code before editing.
+
+7. **Apply the change** based on phase strategy (Step 1) + gauntlet recommendation.
+
+8. **Run tests:**
+   ```bash
+   npm test 2>&1
+   ```
+   If tests fail → go to rollback (step 11).
+
+9. **Run /titan-gate:**
+   Use the Skill tool to invoke `titan-gate`. If FAIL → go to rollback (step 11).
+
+10. **On success:**
+    ```bash
+    git add <specific changed files>
+    git commit -m "<commit message from sync.json>"
+    ```
+    - Record commit SHA in `execution.commits`
+    - Add target to `execution.completedTargets`
+    - Update `titan-state.json`
+
+11. **On failure (test or gate):**
+    ```bash
+    git checkout -- <changed files>
+    ```
+    - Add to `execution.failedTargets` with reason: `{ "target": "<name>", "reason": "<why>", "phase": N }`
+    - Clear `execution.currentTarget`
+    - **Continue to next target** — don't block the whole phase
+
+---
+
+## Step 3 — Phase completion
+
+When all targets in the phase are processed:
+
+1. Add phase number to `execution.completedPhases`
+2. Advance `execution.currentPhase` to the next phase number
+3. Clear `execution.currentTarget`
+4. Write updated `titan-state.json`
+
+---
+
+## Step 4 — Report
+
+Print:
+
+```
+## Phase N Complete: <label>
+
+Targets: X/Y completed, Z failed
+Commits: N
+Files changed: N
+
+### Failed targets (if any):
+- <target>: <reason>
+
+### Next: Phase M — <label> (N targets)
+Run /titan-forge to continue.
+```
+
+If all phases are complete:
+
+```
+## All phases complete
+
+Total commits: N
+Total targets: X completed, Y failed
+Failed targets: <list or "none">
+
+Run /titan-gate on the full branch to validate.
+```
+
+---
+
+## Edge Cases
+
+- **Test failure mid-phase:** Revert target, mark failed, continue. Don't block the whole phase.
+- **Merge conflict with main:** Stop, report, ask user to resolve.
+- **Gate detects new cycle:** Stop immediately — this is a real problem, not skippable.
+- **Target already fixed on main:** Check if file has changed since gauntlet. If metrics now pass, skip with note.
+- **Interrupted mid-phase:** Re-running picks up from `execution.currentTarget`. Already-committed targets are skipped.
+- **`--dry-run`:** Walk through all targets, print what would be done (phase strategy, gauntlet recommendation, files affected), but make no changes.
+- **`--target <name>`:** Run only that target. Useful for retrying entries in `failedTargets`.
+
+---
+
+## Rules
+
+- **One phase per invocation.** Stop after the phase completes. User re-runs for next.
+- **Resumable.** If interrupted, re-running picks up where it left off.
+- **Always use `--json` and `-T`** for codegraph commands.
+- **Gate before commit.** Every commit must pass `/titan-gate`. No exceptions.
+- **One commit per logical unit.** Use commit messages from `sync.json`.
+- **Stage only specific files.** Never `git add .` or `git add -A`.
+- **Rollback on failure is gentle** — `git checkout -- <files>`, not `git reset --hard`.
+- **Subphase awareness** — phases 3-6 have subphases. Each subphase = one commit. Track at subphase level.
+- **Never skip `/titan-gate`.** Even for "trivial" changes.
+
+## Relationship to Other Skills
+
+| Skill | Produces | Used by /titan-forge |
+|-------|----------|---------------------|
+| `/titan-recon` | `titan-state.json`, `GLOBAL_ARCH.md` | State tracking, domain context |
+| `/titan-gauntlet` | `gauntlet.ndjson`, `gauntlet-summary.json` | Per-target recommendations |
+| `/titan-sync` | `sync.json` | Execution plan (phases, targets, commits) |
+| `/titan-gate` | Gate verdict | Called per-commit for validation |
+| `/titan-reset` | Clean slate | Removes all artifacts |
+
+## Self-Improvement
+
+This skill lives at `.claude/skills/titan-forge/SKILL.md`. Edit if phase strategies need refinement or execution loop needs adjustment after dogfooding.

docs/examples/claude-code-skills/README.md

@@ -22,6 +22,12 @@ A single AI agent cannot hold an entire large codebase in context. The Titan Par
 /titan-sync → sync.json (execution plan)
       │
       ▼
+/titan-forge → executes sync.json (one phase per invocation, resumable)
+      │  ├─ codegraph context/fn-impact before each change
+      │  ├─ /titan-gate validates each commit
+      │  └─ advances titan-state.json
+      │
+      ▼
 /titan-gate (validates each commit: codegraph + lint/build/test)
 
 /titan-reset (escape hatch: clean up everything)
@@ -34,6 +40,7 @@ A single AI agent cannot hold an entire large codebase in context. The Titan Par
 | `/titan-recon` | RECON | Builds graph + embeddings, complexity health baseline, domains, priority queue, work batches, `GLOBAL_ARCH.md`, baseline snapshot | `titan-state.json` |
 | `/titan-gauntlet` | GAUNTLET | 4-pillar audit (17 rules) using full codegraph metrics (`cognitive`, `cyclomatic`, `halstead.bugs`, `halstead.effort`, `mi`, `loc.sloc`). Batches of 5, NDJSON writes, session resume | `gauntlet.ndjson` |
 | `/titan-sync` | GLOBAL SYNC | Dependency clusters, code ownership, shared abstractions, ordered execution plan with logical commits | `sync.json` |
+| `/titan-forge` | FORGE | Executes `sync.json` one phase at a time — makes code changes, validates with `/titan-gate`, commits, tracks progress. Resumable across sessions | `titan-state.json` (execution block) |
 | `/titan-gate` | STATE MACHINE | `codegraph check --staged --cycles --blast-radius 30 --boundaries` + lint/build/test. Snapshot restore on failure | `gate-log.ndjson` |
 | `/titan-reset` | ESCAPE HATCH | Restores baseline snapshot, deletes all artifacts and snapshots, rebuilds graph | — |
 
@@ -62,8 +69,8 @@ codegraph build .
 /titan-recon           # Map the codebase, produce priority queue + embeddings
 /titan-gauntlet 5      # Audit top targets in batches of 5
 /titan-sync            # Plan shared abstractions and execution order
-# ... make changes based on sync plan ...
-/titan-gate            # Validate before each commit
+/titan-forge            # Execute next phase (re-run for each phase)
+                       # (calls /titan-gate automatically per commit)
 ```
 
 If GAUNTLET runs out of context, just re-invoke `/titan-gauntlet` — it resumes from the next pending batch.
@@ -73,6 +80,7 @@ If GAUNTLET runs out of context, just re-invoke `/titan-gauntlet` — it resumes
 - `/titan-recon` always works standalone (builds graph fresh)
 - `/titan-gauntlet` falls back to `codegraph triage` if no RECON artifact exists
 - `/titan-sync` requires GAUNTLET artifacts (warns if missing)
+- `/titan-forge` requires SYNC artifacts (`sync.json`); supports `--phase N`, `--target <name>`, `--dry-run`
 - `/titan-gate` works with or without prior artifacts (uses default thresholds)
 - `/titan-reset` cleans up everything — use when you want to start over
 
@@ -83,11 +91,10 @@ If GAUNTLET runs out of context, just re-invoke `/titan-gauntlet` — it resumes
 /titan-gauntlet           # Once (or multiple sessions): audit everything
 /titan-sync               # Once: plan the work
 
-# Then for each fix:
-# 1. Make changes based on sync plan
-# 2. Stage changes
-/titan-gate               # Validate
-# 3. Commit if PASS
+# Then for each phase:
+/titan-forge               # Executes one phase, validates, commits
+/titan-forge               # Re-run for next phase
+/titan-forge               # ...until all phases complete
 ```
 
 ## Artifacts
@@ -100,7 +107,7 @@ All artifacts are written to `.codegraph/titan/` (6 files, no redundancy):
 | `GLOBAL_ARCH.md` | Markdown | RECON | GAUNTLET, SYNC |
 | `gauntlet.ndjson` | NDJSON | GAUNTLET | SYNC |
 | `gauntlet-summary.json` | JSON | GAUNTLET | SYNC, GATE |
-| `sync.json` | JSON | SYNC | GATE |
+| `sync.json` | JSON | SYNC | FORGE, GATE |
 | `gate-log.ndjson` | NDJSON | GATE | Audit trail |
 
 NDJSON format (one JSON object per line) means partial results survive crashes mid-batch.
@@ -170,21 +177,21 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph communities` | RECON | Module boundaries and drift |
 | `codegraph roles` | RECON, GAUNTLET | Core/dead/entry symbol classification |
 | `codegraph structure` | RECON | Directory cohesion |
-| `codegraph complexity --health` | RECON, GAUNTLET, GATE | Full metrics: cognitive, cyclomatic, nesting, Halstead, MI |
+| `codegraph complexity --health` | RECON, GAUNTLET, GATE, FORGE | Full metrics: cognitive, cyclomatic, nesting, Halstead, MI |
 | `codegraph complexity --above-threshold` | RECON | Only functions exceeding thresholds |
 | `codegraph batch complexity` | GAUNTLET | Multi-target complexity in one call |
 | `codegraph batch context` | GAUNTLET | Multi-target context in one call |
 | `codegraph check --staged --cycles --blast-radius --boundaries` | GATE | Full validation predicates |
 | `codegraph ast --kind call\|await\|string` | GAUNTLET | AST pattern detection |
 | `codegraph dataflow` | GAUNTLET | Data flow and mutation analysis |
-| `codegraph exports` | GAUNTLET | Per-symbol export consumers |
-| `codegraph fn-impact` | GAUNTLET, SYNC | Blast radius |
+| `codegraph exports` | GAUNTLET, FORGE | Per-symbol export consumers |
+| `codegraph fn-impact` | GAUNTLET, SYNC, FORGE | Blast radius |
 | `codegraph search` | GAUNTLET | Duplicate code detection (needs embeddings) |
 | `codegraph co-change` | GAUNTLET, SYNC | Git history coupling |
 | `codegraph path` | SYNC | Dependency paths between targets |
 | `codegraph cycles` | SYNC, GATE | Circular dependency detection |
 | `codegraph deps` | SYNC | File-level dependency map |
-| `codegraph context` | SYNC | Full function context |
+| `codegraph context` | SYNC, FORGE | Full function context |
 | `codegraph owners` | SYNC | CODEOWNERS mapping for cross-team coordination |
 | `codegraph branch-compare` | SYNC, GATE | Structural diff between refs |
 | `codegraph diff-impact` | GATE | Impact of staged changes |