feat(titan): first full pipeline run — audit report + skill improvements

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

@@ -58,13 +58,18 @@ Your goal: analyze all commits on the current branch, split them into focused PR
 4. **Load artifacts.** Read:
    - `.codegraph/titan/titan-state.json` — session state, baseline metrics, progress
    - `.codegraph/titan/GLOBAL_ARCH.md` — architecture document
-   - `.codegraph/titan/gauntlet-summary.json` — audit results
+   - `.codegraph/titan/gauntlet.ndjson` — full per-target audit data (pillar verdicts, metrics, violations)
+   - `.codegraph/titan/gauntlet-summary.json` — audit result totals
    - `.codegraph/titan/sync.json` — execution plan (commit grouping)
-   - `.codegraph/titan/gate-log.ndjson` — validation history
+   - `.codegraph/titan/gate-log.ndjson` — validation history (may not exist if gate wasn't run)
    - `.codegraph/titan/issues.ndjson` — issue tracker from all phases
+   - `.codegraph/titan/arch-snapshot.json` — pre-forge architectural snapshot (communities, structure, drift). Use for before/after comparison in the Metrics section. May not exist if capture failed.
+   - `.codegraph/titan/drift-report.json` — cumulative drift reports from all phases. May not exist if no drift was detected.
 
    If `titan-state.json` is missing after the search, stop: "No Titan session found. Run `/titan-recon` first."
 
+   > **When called from `/titan-run`:** The orchestrator already ensured worktree isolation, synced with main, and all artifacts are in the current worktree. Steps 0.1–0.3 (worktree search, isolation check, main sync) can be skipped if the orchestrator tells you to skip them.
+
 5. **Detect version.** Extract from `package.json`:
    ```bash
    node -e "console.log(require('./package.json').version)"
@@ -193,6 +198,10 @@ codegraph complexity --health --sort bugs -T --json --limit 10
 codegraph complexity --health --sort mi -T --json --limit 10
 ```
 
+### Architecture comparison (if arch-snapshot.json exists)
+
+If `.codegraph/titan/arch-snapshot.json` was captured before forge, compare its `structure` data against current `codegraph structure --depth 2 --json` output. Report cohesion changes per directory (improved / degraded / unchanged). Include in the "Metrics: Before & After" section of the report.
+
 ### Compute deltas
 
 Compare final metrics against `titan-state.json` baseline:
@@ -505,10 +514,7 @@ Write `.codegraph/titan/close-summary.json`:
    ```
    Delete any remaining batch snapshots.
 
-3. **Add report to .gitignore** if `generated/titan/` is not already ignored:
-   ```bash
-   grep -q "generated/titan/" .gitignore || echo "generated/titan/" >> .gitignore
-   ```
+3. **Titan reports are committed to the repo** (not gitignored). The `generated/titan/` directory is tracked so reports are preserved in git history.
 
 ---
 

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

@@ -28,7 +28,7 @@ You are the **orchestrator** for the full Titan Paradigm pipeline. Your job is t
    ```bash
    git rev-parse --show-toplevel && git worktree list
    ```
-   If you are NOT in a worktree, **stop:** "Run `/worktree` first. The Titan pipeline writes artifacts and makes code changes — worktree isolation is required."
+   The Titan pipeline writes artifacts and makes code changes — worktree isolation is required. If you are NOT in a worktree, **create one automatically** using the `EnterWorktree` tool (fetch it via `ToolSearch` if needed) with name `titan-run`. Do NOT stop and ask the user — just enter the worktree and continue.
 
 2. **Parse arguments.** Determine:
    - `targetPath` (default: `.`)
@@ -58,7 +58,7 @@ You are the **orchestrator** for the full Titan Paradigm pipeline. Your job is t
    Forge requires explicit confirmation (analysis phases are safe to automate).
    ```
 
-   If `--yes` is NOT set, ask user to confirm before proceeding.
+   Start immediately — do NOT ask for confirmation before analysis phases. The user invoked `/titan-run`; that is the confirmation. Analysis phases (recon, gauntlet, sync) are read-only and safe to automate. The forge checkpoint (Step 3.5b) still applies unless `--yes` is set.
 
 ---
 
@@ -577,58 +577,27 @@ Print forge summary.
 
 ---
 
-## Step 5 — Final Report
+## Step 5 — CLOSE (report + PRs)
 
-Read all artifacts and produce a summary:
+After forge completes, dispatch `/titan-close` to produce the final report with before/after metrics and split commits into focused PRs.
+
+### 5a. Run Pre-Agent Gate (G1-G4)
+
+### 5b. Dispatch sub-agent
 
 ```
-============================================
-  TITAN PIPELINE COMPLETE
-============================================
-
-Target: <path>
-Duration: <first timestamp> → <last timestamp>
-
-RECON:
-  Files: <N>, Symbols: <N>, Domains: <N>
-  Quality score: <N>
-
-GAUNTLET:
-  Audited: <N>/<M> targets (<pct>% coverage)
-  Pass: <N> | Warn: <N> | Fail: <N> | Decompose: <N>
-  NDJSON integrity: <valid>/<total> lines
-
-SYNC:
-  Execution phases: <N>
-  Shared abstractions: <N>
-
-FORGE:
-  Commits: <N>
-  Targets completed: <N>
-  Targets failed: <N>
-  Diff review rejections: <N>
-  Diff review warnings: <N>
-  Gate verdicts: <pass> PASS, <fail> FAIL
-  Semantic assertion failures: <N>
-  Architectural violations caught: <N>
-
-  Failed targets (if any):
-  - <target>: <reason>
-
-Validation warnings (if any):
-  - <warning>
-
-Artifacts:
-  .codegraph/titan/titan-state.json
-  .codegraph/titan/GLOBAL_ARCH.md
-  .codegraph/titan/gauntlet.ndjson
-  .codegraph/titan/gauntlet-summary.json
-  .codegraph/titan/sync.json
-  .codegraph/titan/arch-snapshot.json
-  .codegraph/titan/gate-log.ndjson
-============================================
+Agent → "Run /titan-close. Read .claude/skills/titan-close/SKILL.md and follow it exactly.
+         Skip worktree check and main sync — already handled."
 ```
 
+### 5c. Post-phase validation
+
+After the agent returns, verify:
+- `.codegraph/titan/TITAN_REPORT.md` or `generated/titan/titan-report-*.md` exists and has content (> 20 lines)
+- Print: "CLOSE complete. Report: <report path>"
+
+If the agent created PRs, print the PR URLs.
+
 ---
 
 ## Error Handling

.gitignore

@@ -9,8 +9,5 @@ grammars/*.wasm
 .claude/session-edits.log
 generated/DEPENDENCIES.md
 generated/DEPENDENCIES.json
-generated/titan/
 artifacts/
 pkg/
-generated/DEPENDENCIES.md
-generated/DEPENDENCIES.json

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

@@ -21,9 +21,11 @@ A single AI agent cannot hold an entire large codebase in context. The Titan Par
       │
       ├─→ /titan-sync → sync.json (execution plan)
       │
-      └─→ /titan-forge → code changes + commits (loops phases)
-              │
-              └─→ /titan-gate (validates each commit)
+      ├─→ /titan-forge → code changes + commits (loops phases)
+      │       │
+      │       └─→ /titan-gate (validates each commit)
+      │
+      └─→ /titan-close → PRs + titan-report.md
 
 /titan-reset (escape hatch: clean up everything)
 ```
@@ -38,6 +40,7 @@ A single AI agent cannot hold an entire large codebase in context. The Titan Par
 | `/titan-sync` | GLOBAL SYNC | Dependency clusters, code ownership, shared abstractions, ordered execution plan with logical commits | `sync.json` |
 | `/titan-forge` | FORGE | Executes the sync plan — makes code changes, validates with `/titan-gate`, commits, advances state. One phase per invocation | `titan-state.json` |
 | `/titan-gate` | STATE MACHINE | `codegraph check --staged --cycles --blast-radius 30 --boundaries` + lint/build/test. Snapshot restore on failure | `gate-log.ndjson` |
+| `/titan-close` | CLOSE | Splits branch commits into focused PRs, captures final metrics, generates comprehensive audit report with before/after comparison | `titan-report-*.md` |
 | `/titan-reset` | ESCAPE HATCH | Restores baseline snapshot, deletes all artifacts and snapshots, rebuilds graph | — |
 
 ## Installation
@@ -118,11 +121,14 @@ All artifacts are written to `.codegraph/titan/` (6 files, no redundancy):
 | `gauntlet-summary.json` | JSON | GAUNTLET | RUN, SYNC, GATE |
 | `sync.json` | JSON | SYNC | RUN, FORGE (diff review), GATE |
 | `arch-snapshot.json` | JSON | RUN (pre-forge) | GATE (architectural comparison) |
-| `gate-log.ndjson` | NDJSON | GATE | RUN, Audit trail |
+| `gate-log.ndjson` | NDJSON | GATE | RUN, CLOSE, Audit trail |
+| `drift-report.json` | JSON | GAUNTLET, SYNC, CLOSE | RUN, CLOSE |
+| `close-summary.json` | JSON | CLOSE | — |
+| `generated/titan/titan-report-*.md` | Markdown | CLOSE | — (committed to repo) |
 
 NDJSON format (one JSON object per line) means partial results survive crashes mid-batch.
 
-**Tip:** Add `.codegraph/titan/` to `.gitignore` — these are ephemeral analysis artifacts, not source code.
+**Tip:** Add `.codegraph/titan/` to `.gitignore` — these are ephemeral analysis artifacts. The final report (`generated/titan/`) is tracked in git.
 
 ## Snapshots