diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md new file mode 100644 index 00000000..eff495c4 --- /dev/null +++ b/.claude/skills/review/SKILL.md @@ -0,0 +1,188 @@ +--- +name: review +description: Check all open PRs, resolve conflicts, update branches, address Claude and Greptile review concerns, fix CI failures, and retrigger reviewers until clean +allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent +--- + +# PR Review Sweep + +You are performing a full review sweep across all open PRs in this repository. Your goal is to bring every PR to a clean, mergeable state: no conflicts, CI passing, all reviewer comments addressed, and reviewers re-triggered until satisfied. + +--- + +## Step 0: Worktree Isolation + +Before doing anything else, run `/worktree` to get an isolated copy of the repo. CLAUDE.md mandates that every session starts with `/worktree` to prevent cross-session interference. All subsequent steps run inside the worktree. + +--- + +## Step 1: Discover Open PRs + +```bash +gh pr list --repo optave/codegraph --state open --json number,title,headRefName,baseRefName,mergeable,statusCheckRollup,reviewDecision --limit 50 +``` + +Record each PR's number, branch, base, merge status, and CI state. + +--- + +## Step 2: Process Each PR + +For **each** open PR, perform the following steps in order. Process PRs one at a time to avoid cross-contamination. + +### 2a. Switch to the PR branch + +Ensure the working tree is clean before switching to avoid cross-PR contamination: + +```bash +if [ -n "$(git status --porcelain)" ]; then + git stash push -m "pre-checkout stash" +fi +``` + +Then check out the PR branch: + +```bash +gh pr checkout +``` + +### 2b. Resolve merge conflicts + +Check if the PR has conflicts with its base branch: + +```bash +gh pr view --json mergeable --jq '.mergeable' +``` + +If `CONFLICTING`: + +1. Merge the base branch into the head branch (never rebase): + ```bash + git merge origin/ + ``` +2. Resolve all conflicts by reading the conflicting files, understanding both sides, and making the correct resolution. +3. After resolving, stage the resolved files by name (not `git add .`), commit with: `fix: resolve merge conflicts with ` +4. Push the updated branch. + +### 2c. Check CI status + +```bash +gh pr checks +``` + +If any checks are failing: + +1. Read the failing check logs: + ```bash + gh run view --log-failed + ``` +2. Diagnose the failure — read the relevant source files, understand the error. +3. Fix the issue in code. +4. Run tests locally to verify: `npm test` +5. Run lint locally: `npm run lint` +6. Commit the fix with a descriptive message: `fix: ` +7. Push and wait for CI to re-run. Check again: + ```bash + gh pr checks + ``` +8. Repeat until CI is green. + +### 2d. Gather all review comments + +Fetch **all** review comments from both Claude and Greptile: + +```bash +# PR review comments (inline code comments) +gh api repos/optave/codegraph/pulls//comments --paginate --jq '.[] | {id: .id, user: .user.login, body: .body, path: .path, line: .line, created_at: .created_at}' + +# PR reviews (top-level review bodies) +gh api repos/optave/codegraph/pulls//reviews --paginate --jq '.[] | {id: .id, user: .user.login, body: .body, state: .state}' + +# Issue-style comments (includes @greptileai trigger responses) +gh api repos/optave/codegraph/issues//comments --paginate --jq '.[] | {id: .id, user: .user.login, body: .body, created_at: .created_at}' +``` + +### 2e. Address every comment + +For **each** review comment — including minor suggestions, nits, style feedback, and optional improvements: + +1. **Read the comment carefully.** Understand what the reviewer is asking for. +2. **Read the relevant code** at the file and line referenced. +3. **Make the change.** Even if the comment is marked as "nit" or "suggestion" or "minor" — address it. The goal is zero outstanding comments. +4. **If you disagree** with a suggestion (e.g., it would introduce a bug or contradicts project conventions), do NOT silently ignore it. Reply to the comment explaining why you chose a different approach. +5. **Reply to each comment** explaining what you did: + ```bash + gh api repos/optave/codegraph/pulls//comments//replies \ + -f body="Fixed — " + ``` + For issue-style comments, reply on the issue: + ```bash + gh api repos/optave/codegraph/issues//comments \ + -f body="Addressed: " + ``` + +### 2f. Commit and push fixes + +After addressing all comments for a PR: + +1. Stage only the files you changed. +2. Group changes by concern — each logically distinct fix gets its own commit (e.g., one commit for a missing validation, another for a naming change). Do not lump all feedback into a single commit. +3. Use descriptive messages per commit: `fix: (#)` +4. Push to the PR branch. + +### 2g. Re-trigger reviewers + +**Greptile:** Always re-trigger after pushing fixes. Post a comment: + +```bash +gh api repos/optave/codegraph/issues//comments \ + -f body="@greptileai" +``` + +**Claude (claude-code-review / claude bot):** Only re-trigger if you addressed something Claude specifically suggested. If you did: + +```bash +gh api repos/optave/codegraph/issues//comments \ + -f body="@claude" +``` + +If all changes were only in response to Greptile feedback, do NOT re-trigger Claude. + +### 2h. Wait and re-check + +After re-triggering: + +1. Wait for the new reviews to come in (check after a reasonable interval). +2. Fetch new comments again (repeat Step 2d). +3. If there are **new** comments from Greptile or Claude, go back to Step 2e and address them. +4. **Repeat this loop for a maximum of 3 rounds.** If after 3 rounds there are still actionable comments, mark the PR as "needs human review" in the summary table and move to the next PR. +5. Verify CI is still green after all changes. + +--- + +## Step 3: Summary + +After processing all PRs, output a summary table: + +``` +| PR | Branch | Conflicts | CI | Comments Addressed | Reviewers Re-triggered | Status | +|----|--------|-----------|----|--------------------|----------------------|--------| +| #N | branch | resolved/none | green/red | N comments | greptile, claude | ready/needs-work | +``` + +--- + +## Rules + +- **Never rebase.** Always `git merge ` to resolve conflicts. +- **Never force-push** unless fixing a commit message that fails commitlint. Amend + force-push is the only way to fix a pushed commit title (messages are part of the SHA). This is safe on feature branches. For all other problems, fix with a new commit. +- **Address ALL comments**, even minor/nit/optional ones. Leave zero unaddressed. +- **Always reply to comments** explaining what was done. Don't just fix silently. +- **Always re-trigger Greptile** after pushing fixes — it must confirm satisfaction. +- **Only re-trigger Claude** if you addressed Claude's feedback specifically. +- **No co-author lines** in commit messages. +- **No Claude Code references** in commit messages or comments. +- **Run tests and lint locally** before pushing any fix. +- **One concern per commit** — don't lump conflict resolution with code fixes. +- **Flag scope creep.** If a PR's diff contains files unrelated to its stated purpose (e.g., a docs PR carrying `src/` or test changes from a merged feature branch), flag it immediately. Split the unrelated changes into a separate branch and PR. Do not proceed with review until the PR is scoped correctly — scope creep is not acceptable. +- If a PR is fundamentally broken beyond what review feedback can fix, note it in the summary and skip to the next PR. diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md new file mode 100644 index 00000000..c1d7c359 --- /dev/null +++ b/.claude/skills/titan-gate/SKILL.md @@ -0,0 +1,262 @@ +--- +name: titan-gate +description: Validate staged changes — codegraph checks + project lint/build/test, auto-rollback on failure, pass/fail commit gate (Titan Paradigm Phase 4) +argument-hint: <--force to skip warnings> +allowed-tools: Bash, Read, Write, Edit, Grep +--- + +# Titan GATE — Change Validation & State Machine + +You are running the **GATE** phase (State Machine) of the Titan Paradigm. + +Your goal: validate staged changes against codegraph quality checks AND the project's own lint/build/test. Produce a clear PASS/WARN/FAIL verdict. Auto-rollback on failure. + +> **Context budget:** Lightweight — only checks staged changes. Should complete quickly. + +**Force mode:** If `$ARGUMENTS` contains `--force`, warnings are downgraded (failures still block). + +--- + +## 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. **Staged changes?** + ```bash + git diff --cached --name-only + ``` + If nothing staged, stop: "Nothing staged. Use `git add` first." + +3. **Load state (optional).** Read `.codegraph/titan/titan-state.json` if it exists — use for thresholds, baseline comparison, and sync alignment. If missing or corrupt, proceed with defaults. + +--- + +## Step 1 — Structural validation (codegraph) + +Run the full change validation predicates in one call: + +```bash +codegraph check --staged --cycles --blast-radius 30 --boundaries -T --json +``` + +This checks: manifesto rules, new cycle introduction, blast radius threshold, and architecture boundary violations. Exit code 0 = pass, 1 = fail. + +Also run detailed impact analysis: + +```bash +codegraph diff-impact --staged -T --json +``` + +Extract: changed functions (count + names), direct callers affected, transitive blast radius, historically coupled files. + +--- + +## Step 2 — Cycle check + +```bash +codegraph cycles --json +``` + +Compare against RECON baseline (if `titan-state.json` exists): +- **New cycles?** → FAIL +- **Cycles resolved?** → Note as positive + +--- + +## Step 3 — Complexity delta + +For each changed file (from diff-impact): + +```bash +codegraph complexity --file --health -T --json +``` + +Check all metrics against thresholds: +- `cognitive` > 30 → FAIL +- `halstead.bugs` > 1.0 → FAIL (estimated defect) +- `mi` < 20 → FAIL +- Function moved from PASS → FAIL on any metric? → FAIL +- Function improved but still above threshold? → WARN + +--- + +## Step 4 — Lint, build, and test + +Detect project tools from `package.json`: + +```bash +node -e "const p=require('./package.json');console.log(JSON.stringify(Object.keys(p.scripts||{})))" +``` + +Run in order — stop on first failure: + +```bash +npm run lint 2>&1 || echo "LINT_FAILED" +``` + +```bash +npm run build 2>&1 || echo "BUILD_FAILED" +``` +(Skip if no `build` script.) + +```bash +npm test 2>&1 || echo "TEST_FAILED" +``` + +If any fail → overall verdict is FAIL → proceed to auto-rollback. + +--- + +## Step 5 — Branch structural diff + +```bash +codegraph branch-compare main HEAD -T --json +``` + +Cumulative structural impact of all changes on this branch (broader than `diff-impact --staged`). Detect cumulative drift. + +--- + +## Step 6 — Sync plan alignment + +If `.codegraph/titan/sync.json` exists: +- Are changed files part of the current execution phase? +- Are dependencies for these targets already completed? +- Skipping ahead in execution order? → WARN + +Advisory — prevents jumping ahead and creating conflicts. + +--- + +## Step 7 — Blast radius check + +From diff-impact results: +- Transitive blast radius > 30 → FAIL +- Transitive blast radius > 15 → WARN +- Historically coupled file NOT staged? → WARN ("consider also updating X") + +--- + +## Step 8 — Verdict and auto-rollback + +Aggregate all checks: + +| Verdict | Meaning | +|---------|---------| +| **PASS** | Safe to commit | +| **WARN** | Warnings only — commit at your discretion | +| **FAIL** | Failures present — auto-rollback triggered | + +### Auto-rollback on FAIL (build/test/lint failures only) + +1. **Restore graph** to the most recent snapshot: + ```bash + codegraph snapshot restore titan-batch- # or titan-baseline if no batch snapshot + ``` + Check `titan-state.json → snapshots.lastBatch` first; fall back to `snapshots.baseline`. + +2. **Unstage changes** (preserve in working tree): + ```bash + git reset HEAD + ``` + +3. **Rebuild graph** for current working tree state: + ```bash + codegraph build + ``` + +> "GATE FAIL: [reason]. Graph restored, changes unstaged but preserved. Fix and re-stage." + +For structural-only failures (Steps 1-3, 5-7), do NOT auto-rollback — report and let user decide. + +### Snapshot cleanup on pipeline completion + +When the full Titan pipeline is done (all SYNC phases complete, final GATE passes): + +```bash +codegraph snapshot delete titan-baseline +codegraph snapshot delete titan-batch- # if any remain +``` + +> "All Titan snapshots cleaned up. Codebase is in its final validated state." + +--- + +## Step 9 — Update state machine + +Append to `.codegraph/titan/gate-log.ndjson`: + +```json +{ + "timestamp": "", + "verdict": "PASS|WARN|FAIL", + "stagedFiles": ["file1.js"], + "changedFunctions": 3, + "blastRadius": 12, + "checks": { + "manifesto": "pass|fail", + "cycles": "pass|fail", + "complexity": "pass|warn|fail", + "lint": "pass|fail|skipped", + "build": "pass|fail|skipped", + "tests": "pass|fail|skipped", + "syncAlignment": "pass|warn|skipped", + "blastRadius": "pass|warn|fail" + }, + "rolledBack": false +} +``` + +Update `titan-state.json` (if exists): increment `progress.fixed`, update `fileAudits` for fixed files. + +--- + +## Step 10 — Report to user + +**PASS:** +``` +GATE PASS — safe to commit + Changed: 3 functions across 2 files + Blast radius: 12 transitive callers + Lint: pass | Build: pass | Tests: pass + Complexity: all within thresholds (worst: halstead.bugs 0.3) +``` + +**WARN:** +``` +GATE WARN — review before committing + Changed: 5 functions across 3 files + Warnings: + - utils.js historically co-changes with config.js (not staged) + - parseConfig MI improved 18 → 35 but still below 50 +``` + +**FAIL:** +``` +GATE FAIL — changes unstaged, graph restored + Failures: + - Tests: 2 suites failed + - New cycle: parseConfig → loadConfig → parseConfig + Fix issues, re-stage, re-run /titan-gate +``` + +--- + +## Rules + +- **Fast execution.** Only staged changes, not full codebase. +- **Always use `--json` and `-T`.** +- **Never auto-commit.** Verdict only — user decides. +- **Auto-rollback is gentle** — `git reset HEAD`, never `git checkout`. Work preserved. +- **Append to gate-log.ndjson** — the audit trail. +- **Force mode** downgrades WARN → PASS but cannot override FAIL. +- **Run the project's own lint/build/test** — codegraph checks are necessary but not sufficient. +- **Use the correct check flags:** `--cycles`, `--blast-radius `, `--boundaries`. + +## Self-Improvement + +This skill lives at `.claude/skills/titan-gate/SKILL.md`. Adjust thresholds or rollback behavior after dogfooding. diff --git a/.claude/skills/titan-gauntlet/SKILL.md b/.claude/skills/titan-gauntlet/SKILL.md new file mode 100644 index 00000000..d6ae1050 --- /dev/null +++ b/.claude/skills/titan-gauntlet/SKILL.md @@ -0,0 +1,358 @@ +--- +name: titan-gauntlet +description: Audit codebase files against the 4-pillar quality manifesto using RECON work batches, with batch processing and context budget management (Titan Paradigm Phase 2) +argument-hint: +allowed-tools: Bash, Read, Write, Glob, Grep, Edit +--- + +# Titan GAUNTLET — The Perfectionist Manifesto + +You are running the **GAUNTLET** phase of the Titan Paradigm. + +Your goal: audit every high-priority target from the RECON phase against 4 pillars of quality, using work batches to stay within context limits. Each batch writes results to disk before starting the next. If context reaches ~80% capacity, stop and tell the user to re-invoke — the state machine ensures no work is lost. + +**Batch size:** `$ARGUMENTS` (default: `5`) + +> **Context budget:** Process `$ARGUMENTS` targets per batch. Write results to NDJSON after each batch. If context grows large, save state and stop — the user re-invokes to continue. + +--- + +## 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 + ``` + +3. **Load state.** Read `.codegraph/titan/titan-state.json`. If missing: + - Warn: "No RECON artifacts. Run `/titan-recon` first for best results." + - Fall back: `codegraph triage -T --limit 50 --json` for a minimal queue. + +4. **Load architecture.** Read `.codegraph/titan/GLOBAL_ARCH.md` for domain context. + +5. **Resume logic.** If `titan-state.json` has completed batches, skip them. Start from the first `pending` batch. + +6. **Validate state.** If `titan-state.json` fails to parse, stop: "State file corrupted. Run `/titan-reset` to start over, or `/titan-recon` to rebuild." + +--- + +## Step 1 — The Four Pillars + +Every file must be checked against all four pillars. A file **FAILS** if it has any fail-level violation. + +### Pillar I: Structural Purity & Logic + +#### Rule 1 — Complexity (multi-metric) +```bash +codegraph complexity --file --health -T --json +``` +This returns ALL metrics in one call — use them all: + +| Metric | Warn | Fail | Why it matters | +|--------|------|------|---------------| +| `cognitive` | > 15 | > 30 | How hard to understand | +| `cyclomatic` | > 10 | > 20 | How many paths to test | +| `maxNesting` | > 3 | > 5 | Flatten with guards/extraction | +| `halstead.effort` | > 5000 | > 15000 | Information-theoretic complexity | +| `halstead.bugs` | > 0.5 | > 1.0 | Estimated defect count | +| `mi` (Maintainability Index) | < 50 | < 20 | Composite health score | +| `loc.sloc` | > 50 | > 100 | Function too long — split it | + +#### Rule 2 — Async hygiene (every Promise caught) +```bash +codegraph ast --kind await --file -T --json +codegraph ast --kind call --file -T --json +``` +Cross-reference: `.then()` calls without `.catch()` on the same chain; async functions without `try/catch` wrapping await calls. Also grep: +```bash +grep -n "\.then(" +grep -n "async " +``` +**Fail:** uncaught promise chains or async functions without error handling. + +#### Rule 3 — Dependency direction (no upward imports) +```bash +codegraph check --boundaries -T --json +codegraph deps --json +``` +Cross-reference with GLOBAL_ARCH.md layer rules. **Fail:** import from a higher layer. + +#### Rule 4 — Dead code (no unused exports) +```bash +codegraph roles --role dead --file -T --json +codegraph exports -T --json +``` +**Fail:** dead exports or unreferenced symbols. + +#### Rule 5 — Resource hygiene +```bash +codegraph ast --kind call --file -T --json +``` +Find `addEventListener`, `setInterval`, `setTimeout`, `createReadStream`, `.on(` — verify matching cleanup. **Fail:** resource acquired without cleanup. + +#### Rule 6 — Immutability +```bash +codegraph dataflow -T --json +``` +Also grep for mutation patterns: +```bash +grep -n "\.push(\|\.splice(\|\.sort(\|\.reverse(\|delete " +``` +**Fail:** direct mutation of function arguments or external state. + +### Pillar II: Data & Type Sovereignty + +#### Rule 7 — Magic values +```bash +codegraph ast --kind string --file -T --json +``` +Also grep for numeric literals in logic branches: +```bash +grep -nE "[^a-zA-Z_][0-9]{2,}[^a-zA-Z_]" +``` +Filter out imports, log format strings, test assertions. **Warn:** present. **Fail:** in if/switch conditions. + +#### Rule 8 — Boundary validation +```bash +codegraph roles --role entry --file -T --json +codegraph where --file -T --json +``` +For entry-point functions, verify schema validation before processing. **Fail:** missing validation at system boundaries. + +#### Rule 9 — Secret hygiene +```bash +grep -niE "api.?key|secret|password|token|credential" +``` +Verify values come from config/env, not literals. **Fail:** hardcoded secret values. + +#### Rule 10 — Error integrity (no empty catches) +```bash +grep -nA2 "catch" +``` +**Fail:** empty catch block or catch with only `// ignore` or `// TODO`. + +### Pillar III: Ecosystem Synergy + +#### Rule 11 — DRY (no duplicated logic) +```bash +codegraph search "" -T --json +codegraph co-change -T --json +``` +Find semantically similar functions. If `codegraph search` fails (no embeddings), use grep for function signature patterns. **Warn:** similar patterns. **Fail:** near-verbatim copy. + +> Note: requires embeddings from `/titan-recon`. If `titan-state.json → embeddingsAvailable` is false, skip semantic search and note it. + +#### Rule 12 — Naming symmetry +```bash +codegraph where --file -T --json +``` +Scan function names in the domain. Flag mixed `get`/`fetch`/`retrieve` or `create`/`make`/`build` for the same concept. **Warn:** inconsistent. **Advisory** — not a fail condition. + +#### Rule 13 — Config over code +```bash +codegraph deps --json +``` +Also grep: +```bash +grep -n "process.env\|NODE_ENV\|production\|development" +``` +Verify env-specific behavior driven by config, not inline branches. **Warn:** inline env branch. + +### Pillar IV: The Quality Vigil + +#### Rule 14 — Naming quality +```bash +codegraph where --file -T --json +``` +Flag vague names: `data`, `obj`, `temp`, `res`, `val`, `item`, `result`, single-letter vars (except `i/j/k`). **Warn:** present. **Advisory.** + +#### Rule 15 — Structured logging +```bash +codegraph ast --kind call --file -T --json +``` +Also grep: +```bash +grep -n "console\.\(log\|warn\|error\|info\)" +``` +**Warn:** console.log in source files. **Fail:** in production code paths (non-debug, non-test). + +#### Rule 16 — Testability +```bash +codegraph fn-impact -T --json +codegraph query -T --json +``` +High fan-out correlates with many mocks needed. Also read corresponding test file and count mock/stub/spy calls. **Warn:** > 10 mocks. **Fail:** > 15 mocks. + +#### Rule 17 — Critical path coverage +```bash +codegraph roles --role core --file -T --json +``` +If file contains core symbols (high fan-in), note whether test files exist for it. **Warn:** core symbol with no test file. **Advisory.** + +### Audit trail (per file) + +For every file, the NDJSON record MUST include: +- **Verdict** and **pillar verdicts** (pass/warn/fail per pillar) +- **All metrics** from `codegraph complexity --health` (cognitive, cyclomatic, nesting, MI, halstead.bugs, halstead.effort, loc.sloc) +- **Violation list** with rule number, detail, and level +- **Recommendation** for FAIL/DECOMPOSE targets + +Codegraph provides all the data needed for a verifiable audit — no need to manually traverse files for line counts or nesting proof. + +--- + +## Step 2 — Batch audit loop + +For each pending batch (from `titan-state.json`): + +### 2a. Save pre-batch snapshot +```bash +codegraph snapshot save titan-batch- +``` +Delete the previous batch snapshot if it exists: +```bash +codegraph snapshot delete titan-batch- +``` + +### 2b. Collect all metrics in one call +```bash +codegraph batch complexity ... -T --json +``` +This returns complexity + health metrics for all targets in one call. Parse the results. + +For deeper context on high-risk targets: +```bash +codegraph batch context ... -T --json +``` + +### 2c. Run Pillar I checks +For each file in the batch: +- Parse complexity metrics from batch output (Rule 1 — all 7 metric thresholds) +- Run AST queries for async hygiene (Rule 2), resource cleanup (Rule 5) +- Check boundary violations (Rule 3): `codegraph check --boundaries -T --json` +- Check dead code (Rule 4): `codegraph roles --role dead --file -T --json` +- Check immutability (Rule 6): `codegraph dataflow` + grep + +### 2d. Run Pillar II checks +For each file: +- Magic values (Rule 7): `codegraph ast --kind string` + grep +- Boundary validation (Rule 8): check entry points +- Secret hygiene (Rule 9): grep +- Empty catches (Rule 10): grep + +### 2e. Run Pillar III checks +- DRY (Rule 11): `codegraph search` (if embeddings available) + `co-change` +- Naming symmetry (Rule 12): `codegraph where --file` +- Config over code (Rule 13): `codegraph deps` + grep + +### 2f. Run Pillar IV checks +- Naming quality (Rule 14): `codegraph where --file` +- Structured logging (Rule 15): `codegraph ast --kind call` + grep +- Testability (Rule 16): `codegraph fn-impact` + test file mock count +- Critical path coverage (Rule 17): `codegraph roles --role core` + +### 2g. Score each target + +| Verdict | Condition | +|---------|-----------| +| **PASS** | No fail-level violations | +| **WARN** | Warn-level violations only | +| **FAIL** | One or more fail-level violations | +| **DECOMPOSE** | Complexity fail + `halstead.bugs` > 1.0 + high fan-out (needs splitting) | + +For FAIL/DECOMPOSE targets, capture blast radius: +```bash +codegraph fn-impact -T --json +``` + +### 2h. Write batch results + +Append to `.codegraph/titan/gauntlet.ndjson` (one line per target): + +```json +{"target": "", "file": "", "verdict": "FAIL", "pillarVerdicts": {"I": "fail", "II": "warn", "III": "pass", "IV": "pass"}, "metrics": {"cognitive": 28, "cyclomatic": 15, "maxNesting": 4, "mi": 32, "halsteadEffort": 12000, "halsteadBugs": 1.2, "sloc": 85}, "violations": [{"rule": 1, "pillar": "I", "metric": "cognitive", "detail": "28 > 30 threshold", "level": "fail"}], "blastRadius": {"direct": 5, "transitive": 18}, "recommendation": "Split: halstead.bugs 1.2 suggests ~1 defect. Separate validation from I/O."} +``` + +### 2i. Update state machine + +Update `titan-state.json`: +- Set batch status to `"completed"` +- Increment `progress.audited`, `.passed`, `.warned`, `.failed` +- Add entries to `fileAudits` map +- Update `snapshots.lastBatch` +- Update `lastUpdated` + +### 2j. Progress check + +Print: `Batch N/M: X pass, Y warn, Z fail` + +**Context budget:** If context is growing large: +1. Write all state to disk +2. Print: `Context budget reached after Batch N. Run /titan-gauntlet to continue.` +3. Stop. + +--- + +## Step 3 — Clean up batch snapshots + +After all batches complete, delete the last batch snapshot: +```bash +codegraph snapshot delete titan-batch- +``` +Keep `titan-baseline` — GATE may need it. + +If stopping early for context, keep the last batch snapshot for safety. + +--- + +## Step 4 — Aggregate and report + +Compute from `gauntlet.ndjson`: +- Pass / Warn / Fail / Decompose counts +- Top 10 worst offenders (by violation count or `halstead.bugs`) +- Most common violations by pillar +- Files with the most failing functions + +Write `.codegraph/titan/gauntlet-summary.json`: +```json +{ + "phase": "gauntlet", + "timestamp": "", + "complete": true, + "summary": {"totalAudited": 0, "pass": 0, "warn": 0, "fail": 0, "decompose": 0}, + "worstOffenders": [], + "commonViolations": {"I": [], "II": [], "III": [], "IV": []} +} +``` + +Set `"complete": false` if stopping early. + +Print summary to user: +- Pass/Warn/Fail/Decompose counts +- Top 5 worst (with their `halstead.bugs` and `mi` scores) +- Most common violation per pillar +- Next step: `/titan-gauntlet` to continue (if incomplete) or `/titan-sync` + +--- + +## Rules + +- **Batch processing is mandatory.** Never audit more than `$ARGUMENTS` targets at once. +- **Write NDJSON incrementally.** Partial results survive crashes. +- **Always use `--json` and `-T`** on codegraph commands. +- **Use `codegraph batch `** for multi-target queries — not separate calls. +- **Leverage `--health` and `--above-threshold`** — they give you all metrics in one call. +- **Context budget:** Stop at ~80%, save state, tell user to re-invoke. +- **Lint runs once in GATE**, not per-batch here. Don't run `npm run lint`. +- Advisory rules (12, 14, 17) produce warnings, never failures. +- Dead symbols from RECON should be flagged for removal, not skipped. + +## Self-Improvement + +This skill lives at `.claude/skills/titan-gauntlet/SKILL.md`. Adjust thresholds or rules after dogfooding. diff --git a/.claude/skills/titan-recon/SKILL.md b/.claude/skills/titan-recon/SKILL.md new file mode 100644 index 00000000..b1ae5428 --- /dev/null +++ b/.claude/skills/titan-recon/SKILL.md @@ -0,0 +1,316 @@ +--- +name: titan-recon +description: Map a codebase's dependency graph, identify hotspots, name logical domains, propose work batches, and produce a ranked priority queue for autonomous cleanup (Titan Paradigm Phase 1) +argument-hint: +allowed-tools: Bash, Read, Write, Glob, Grep, Edit +--- + +# Titan RECON — Codebase Reconnaissance + +You are running the **RECON** phase of the Titan Paradigm on the target at `$ARGUMENTS` (default: `.`). + +Your goal: map the dependency graph, identify structural hotspots, name logical domains, produce a global architecture document, propose work batches, and initialize the session state. Everything you produce feeds downstream phases (GAUNTLET, SYNC, GATE) via artifacts in `.codegraph/titan/`. + +> **Context budget:** Every codegraph command MUST use `--json` to keep output compact. Never dump raw CLI tables into context — parse JSON and extract only what you need. + +--- + +## Step 0 — Pre-flight: worktree and sync + +1. **Check for worktree isolation:** + ```bash + git rev-parse --show-toplevel && git worktree list + ``` + If you are NOT in a worktree, **stop:** "Run `/worktree` first. Titan phases write artifacts that should not interfere with other work." + +2. **Sync with main:** + ```bash + git fetch origin main && git merge origin/main --no-edit + ``` + If there are merge conflicts, stop and ask the user to resolve them. + +--- + +## Step 1 — Build the graph + +```bash +codegraph build $ARGUMENTS +``` + +Record: file count, node count, edge count, engine. + +--- + +## Step 2 — Generate embeddings (for DRY detection in GAUNTLET) + +```bash +codegraph embed -m minilm +``` + +This enables `codegraph search` for duplicate code detection in downstream phases. If it fails (e.g., missing model), note it and continue — DRY checks will be grep-only. + +--- + +## Step 3 — Collect baseline metrics + +Run in parallel: + +```bash +codegraph stats --json +codegraph structure --depth 2 --json +``` + +Extract from `stats`: `totalNodes`, `totalEdges`, `totalFiles`, `qualityScore`, `avgFanIn`, `avgFanOut`. + +Extract from `structure`: top 10 directories by file count, directories with cohesion < 0.3 (tangled). + +--- + +## Step 4 — Build the priority queue + +```bash +codegraph triage -T --limit 100 --json +``` + +Risk-ranked list combining connectivity, complexity, and role classification. Truncate to top 50 for the artifact if >100 items. + +--- + +## Step 5 — Community and drift analysis + +```bash +codegraph communities -T --json +codegraph communities --drift -T --json +``` + +Extract: community count, top 5 largest (member count + key files), drift warnings. + +--- + +## Step 6 — High-traffic files and role classification + +```bash +codegraph map --limit 30 -T --json +codegraph roles --role core -T --json +codegraph roles --role dead -T --json +``` + +Count core symbols (high fan-in) and dead symbols (zero fan-in, not exported). + +--- + +## Step 7 — Complexity health baseline + +Get the full metrics picture across the codebase — this is what makes codegraph powerful: + +```bash +codegraph complexity --health --above-threshold -T --json --limit 50 +``` + +This returns only functions exceeding configured warn thresholds, with all available metrics per function: +- **Structural:** `cognitive`, `cyclomatic`, `maxNesting` +- **Halstead:** `volume`, `difficulty`, `effort`, `bugs` (estimated bug count) +- **Size:** `loc.sloc`, `loc.commentLines` +- **Composite:** `mi` (Maintainability Index) + +Also get the worst offenders by different metrics: + +```bash +codegraph complexity --health --sort effort -T --json --limit 10 +codegraph complexity --health --sort bugs -T --json --limit 10 +codegraph complexity --health --sort mi -T --json --limit 10 +``` + +These three views reveal different quality dimensions: `effort` = hardest to understand, `bugs` = most likely to contain defects, `mi` = worst overall maintainability. + +--- + +## Step 8 — Domain inventory + +Using community detection (Step 5) and directory structure (Step 3), **name** the logical domains. A domain is a cohesive group of files serving a single concern. + +For each domain, record: +- **Name:** use the codebase's own vocabulary (directory names, module names) +- **Root directories** +- **File count** +- **Key symbols:** 3-5 most-connected symbols (from triage) +- **Community IDs:** which communities map to this domain +- **Health:** cohesion score, drift warnings, cycle participation + +For large domains, map inter-domain dependencies using key files (not directories — `deps` takes a file path): + +```bash +codegraph deps --json +``` + +--- + +## Step 9 — Global architecture document + +Write `.codegraph/titan/GLOBAL_ARCH.md`: + +```markdown +# Global Architecture + +**Date:** +**Codebase:** ( files, symbols) + +## Domain Map + +| Domain | Root Dirs | Files | Core Symbols | Health | +|--------|-----------|-------|-------------|--------| +| ... | ... | ... | ... | cohesion, drift? | + +## Dependency Flow + + + +## Shared Types and Interfaces + + + +## Architectural Rules + + + +## Cycles + + +``` + +--- + +## Step 10 — Propose work batches + +Decompose the priority queue into **work batches** of ~5-15 files each: +- Stay within a single domain where possible +- Group tightly-coupled files together (from communities) +- Order by priority: highest-risk domains first +- Note dependencies: "batch N depends on batch M being done first" + +--- + +## Step 11 — Save baseline snapshot + +```bash +codegraph snapshot save titan-baseline +``` + +This is the rollback point. If anything goes wrong downstream, any skill can restore it. + +--- + +## Step 12 — Write the state file + +Create `.codegraph/titan/titan-state.json` — the single source of truth for the entire pipeline: + +```bash +mkdir -p .codegraph/titan +``` + +```json +{ + "version": 1, + "initialized": "", + "lastUpdated": "", + "target": "", + "currentPhase": "recon", + "snapshots": { + "baseline": "titan-baseline", + "lastBatch": null + }, + "embeddingsAvailable": true, + "stats": { + "totalFiles": 0, + "totalNodes": 0, + "totalEdges": 0, + "qualityScore": 0, + "avgFanIn": 0, + "avgFanOut": 0 + }, + "healthBaseline": { + "functionsAboveThreshold": 0, + "worstByEffort": [""], + "worstByBugs": [""], + "worstByMI": [""] + }, + "domains": [ + { + "name": "", + "rootDirs": [""], + "fileCount": 0, + "status": "pending", + "audited": 0, + "passed": 0, + "failed": 0 + } + ], + "batches": [ + { + "id": 1, + "domain": "", + "files": [""], + "status": "pending", + "dependsOn": [], + "priority": 1 + } + ], + "priorityQueue": [ + { + "rank": 1, + "target": "", + "riskScore": 0, + "reason": "" + } + ], + "communities": { + "count": 0, + "driftWarnings": [] + }, + "roles": { + "coreCount": 0, + "deadCount": 0, + "deadSymbols": [""] + }, + "hotFiles": [""], + "tangledDirs": [""], + "fileAudits": {}, + "progress": { + "totalFiles": 0, + "audited": 0, + "passed": 0, + "warned": 0, + "failed": 0, + "fixed": 0 + } +} +``` + +--- + +## Step 13 — Report to user + +Print a concise summary: +- Graph size and quality score +- Domains identified (count and names) +- Complexity health: count of functions above threshold, top 3 worst by `halstead.bugs` +- Work batches proposed (count) +- Top 5 priority targets +- Dead symbol count +- Drift warnings +- Path to artifacts: `.codegraph/titan/titan-state.json` and `.codegraph/titan/GLOBAL_ARCH.md` +- Next step: `/titan-gauntlet` to audit the priority queue + +--- + +## Rules + +- **Always use `--json` and `-T`** on codegraph commands. +- **Never paste raw JSON** into your response — parse and extract. +- **Write artifacts before reporting.** +- If any command fails, note it and continue with partial data. +- **Domain naming** uses the codebase's own vocabulary. + +## Self-Improvement + +This skill lives at `.claude/skills/titan-recon/SKILL.md`. Edit it if you find improvements during execution. diff --git a/.claude/skills/titan-reset/SKILL.md b/.claude/skills/titan-reset/SKILL.md new file mode 100644 index 00000000..2c99704d --- /dev/null +++ b/.claude/skills/titan-reset/SKILL.md @@ -0,0 +1,89 @@ +--- +name: titan-reset +description: Clean up all Titan Paradigm artifacts and snapshots, restoring the codebase to pre-Titan state +argument-hint: <--keep-graph to preserve the codegraph database> +allowed-tools: Bash, Read, Write, Grep +--- + +# Titan RESET — Pipeline Cleanup + +You are resetting the Titan Paradigm pipeline, removing all artifacts and restoring the codebase to its pre-Titan state. + +--- + +## Step 1 — Restore baseline snapshot (if available) + +```bash +codegraph snapshot restore titan-baseline 2>/dev/null && echo "Baseline restored" || echo "No baseline snapshot found" +``` + +This restores the graph database to its pre-GAUNTLET state. + +--- + +## Step 2 — Delete all Titan snapshots + +```bash +codegraph snapshot delete titan-baseline 2>/dev/null +``` + +Also delete any batch snapshots: + +```bash +codegraph snapshot delete titan-batch-1 2>/dev/null +codegraph snapshot delete titan-batch-2 2>/dev/null +codegraph snapshot delete titan-batch-3 2>/dev/null +codegraph snapshot delete titan-batch-4 2>/dev/null +codegraph snapshot delete titan-batch-5 2>/dev/null +codegraph snapshot delete titan-batch-6 2>/dev/null +codegraph snapshot delete titan-batch-7 2>/dev/null +codegraph snapshot delete titan-batch-8 2>/dev/null +codegraph snapshot delete titan-batch-9 2>/dev/null +codegraph snapshot delete titan-batch-10 2>/dev/null +``` + +(Errors are expected for snapshots that don't exist — ignore them.) + +--- + +## Step 3 — Remove all Titan artifacts + +```bash +rm -rf .codegraph/titan/ +``` + +This removes: +- `titan-state.json` — session state +- `GLOBAL_ARCH.md` — architecture document +- `gauntlet.ndjson` — audit results +- `gauntlet-summary.json` — aggregated results +- `sync.json` — execution plan +- `gate-log.ndjson` — gate audit trail + +--- + +## Step 4 — Rebuild graph (unless --keep-graph) + +If `$ARGUMENTS` does NOT contain `--keep-graph`: + +```bash +codegraph build +``` + +This ensures the graph reflects the current state of the codebase without any Titan-era corruption. + +If `$ARGUMENTS` contains `--keep-graph`, skip this step. + +--- + +## Step 5 — Report + +``` +Titan pipeline reset complete. + - Baseline snapshot: restored and deleted + - Batch snapshots: deleted + - Artifacts: removed (.codegraph/titan/) + - Graph: rebuilt (clean state) + +To start a fresh Titan pipeline, run /titan-recon +``` diff --git a/.claude/skills/titan-sync/SKILL.md b/.claude/skills/titan-sync/SKILL.md new file mode 100644 index 00000000..6b93e0e4 --- /dev/null +++ b/.claude/skills/titan-sync/SKILL.md @@ -0,0 +1,233 @@ +--- +name: titan-sync +description: Identify overlapping fixes across audit results, plan shared abstractions, produce an ordered execution plan with logical commit grouping (Titan Paradigm Phase 3) +argument-hint: +allowed-tools: Bash, Read, Write, Glob, Grep, Edit +--- + +# Titan GLOBAL SYNC — Cross-Cutting Analysis & Execution Plan + +You are running the **GLOBAL SYNC** phase of the Titan Paradigm. + +Your goal: analyze GAUNTLET results to find overlapping problems, identify shared abstractions that should be built *before* individual fixes, group changes into logical commits, and produce an ordered execution plan. + +> **Context budget:** This phase reads artifacts, not source. Keep codegraph queries targeted — only for specific relationship questions between failing targets. + +--- + +## 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 + ``` + +3. **Load artifacts.** Read: + - `.codegraph/titan/titan-state.json` — state, domains, batches, file audits + - `.codegraph/titan/GLOBAL_ARCH.md` — architecture, dependency flow, shared types + - `.codegraph/titan/gauntlet.ndjson` — per-target audit details + - `.codegraph/titan/gauntlet-summary.json` — aggregated results + +4. **Validate state.** If `titan-state.json` fails to parse, stop: "State file corrupted. Run `/titan-reset`." + +5. **Check GAUNTLET completeness.** If `gauntlet-summary.json` has `"complete": false`: + > "GAUNTLET incomplete (/ batches). SYNC will plan based on known failures only. Run `/titan-gauntlet` first for a complete plan." + +6. **Extract.** From artifacts, collect: + - All FAIL and DECOMPOSE targets with violations and files + - Common violation patterns by pillar + - Community assignments + - Dead symbols (cleanup candidates) + - Domain boundaries and dependency flow + +--- + +## Step 1 — Find dependency clusters among failing targets + +For FAIL/DECOMPOSE targets that share a file or community, check connections: + +```bash +codegraph path -T --json +``` + +Group connected failures into **clusters**. Also check for cycles among them: + +```bash +codegraph cycles --functions --json +``` + +Filter to cycles including at least one FAIL/DECOMPOSE target. + +--- + +## Step 2 — Identify shared dependencies and ownership + +For each cluster, find what they share: + +```bash +codegraph deps --json +``` + +Look for: +- **Shared imports:** multiple failures import the same module → interface extraction candidate +- **Shared callers:** multiple failures called by the same function → caller needs updating +- **Common violations:** similar pillar violations across targets + +Check **code ownership** for cross-team coordination: + +```bash +codegraph owners -T --json +``` + +If different teams own files in the same cluster, note the coordination requirement. + +Run **branch structural diff** to see what's already changed: + +```bash +codegraph branch-compare main HEAD -T --json +``` + +Avoid re-auditing or conflicting with in-progress work. + +--- + +## Step 3 — Detect extraction candidates + +For DECOMPOSE targets: + +```bash +codegraph context -T --json +codegraph ast --kind call --file -T --json +``` + +Look for: +- Functions with multiple responsibilities (high cognitive + high fan-out + high `halstead.bugs`) +- Repeated patterns across failures (similar call chains) +- God files (many failing functions → split along community boundaries) + +--- + +## Step 4 — Plan shared abstractions + +Identify what to build BEFORE individual fixes: + +1. **Interface extractions** — shared dependency → extract interface +2. **Utility extractions** — repeated patterns → shared utility +3. **Module splits** — god files → split by community structure +4. **Cycle breaks** — circular deps → identify weakest link + +For each, check blast radius: +```bash +codegraph fn-impact -T --json +``` + +--- + +## Step 5 — Build execution order with logical commits + +### Phases (in order) + +1. **Dead code cleanup** — zero risk, reduces noise + - Commit: `chore: remove dead code` +2. **Shared abstractions** — before individual fixes + - One commit per abstraction: `refactor: extract X from Y` +3. **Cycle breaks** — unblocks dependent targets + - One commit per break: `refactor: break cycle between X and Y` +4. **Decompositions** — highest risk, after abstractions + - One commit per decomposition: `refactor: split X into A and B` +5. **Fail fixes** — ordered by blast radius (lowest first) + - Group by domain: `fix: address quality issues in ` +6. **Warn improvements** — optional, lowest priority + - Group by domain: `refactor: address warnings in ` + +### Ordering within each phase +- Dependencies first (if A depends on B, fix B first) +- Lower blast radius first +- Same community together + +### Each commit should: +- Touch one domain where possible +- Address one concern +- Be independently revertible +- Run `/titan-gate` before committing + +--- + +## Step 6 — Write the SYNC artifact + +Write `.codegraph/titan/sync.json`: + +```json +{ + "phase": "sync", + "timestamp": "", + "clusters": [ + { + "id": 1, + "name": "", + "targets": ["t1", "t2"], + "sharedDeps": ["mod"], + "hasCycle": false, + "owners": ["team-a", "team-b"], + "proposedAction": "Extract interface" + } + ], + "abstractions": [ + { + "type": "interface_extraction|utility_extraction|module_split|cycle_break", + "description": "...", + "source": "", + "unblocks": ["t1", "t2"], + "blastRadius": 0, + "commit": "refactor: ..." + } + ], + "executionOrder": [ + { + "phase": 1, + "label": "Dead code cleanup", + "targets": ["sym1", "sym2"], + "risk": "none", + "commit": "chore: remove dead code", + "dependencies": [] + } + ], + "deadCodeTargets": [""], + "cyclesInvolvingFailures": [] +} +``` + +Update `titan-state.json`: set `currentPhase` to `"sync"`. + +--- + +## Step 7 — Report to user + +Print: +- Dependency clusters found (count) +- Shared abstractions proposed (count) +- Execution order summary (phases, target counts, estimated commits) +- Key insight: what SYNC prevented (e.g., "3 targets share configLoader — without SYNC, 3 conflicting refactors") +- Path to `sync.json` +- Next step: start Phase 1 (dead code cleanup), validate each commit with `/titan-gate` + +--- + +## Rules + +- **Read artifacts, don't re-scan.** Codegraph commands only for targeted relationship queries. +- **Always use `--json` and `-T`.** +- **The execution order is the key output.** +- **Logical commits matter.** Never mix concerns. +- If GAUNTLET found zero failures, produce minimal plan (dead code + warnings only). +- Keep `codegraph path` queries targeted — same file or community only. + +## Self-Improvement + +This skill lives at `.claude/skills/titan-sync/SKILL.md`. Edit if clustering misses connections or execution order causes conflicts. diff --git a/docs/examples/claude-code-skills/README.md b/docs/examples/claude-code-skills/README.md new file mode 100644 index 00000000..bd1398e4 --- /dev/null +++ b/docs/examples/claude-code-skills/README.md @@ -0,0 +1,196 @@ +# Claude Code Skills for Codegraph + +This directory contains example [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) that use codegraph to power autonomous codebase cleanup — based on the [Titan Paradigm](../../use-cases/titan-paradigm.md). + +## The Problem: Context Window Explosion + +A single AI agent cannot hold an entire large codebase in context. The Titan Paradigm solves this with a phased approach where each phase: + +1. Runs targeted codegraph queries (not raw file reads) +2. Writes structured **artifacts** to `.codegraph/titan/` +3. Next phase reads only those artifacts — not the original sources + +``` +/titan-recon → titan-state.json + GLOBAL_ARCH.md + │ + ▼ +/titan-gauntlet → gauntlet.ndjson (batches of 5, resumes across sessions) + │ + ▼ +/titan-sync → sync.json (execution plan) + │ + ▼ +/titan-gate (validates each commit: codegraph + lint/build/test) + +/titan-reset (escape hatch: clean up everything) +``` + +## Skills + +| Skill | Phase | What it does | Key artifact | +|-------|-------|-------------|-------------| +| `/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-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 | — | + +## Installation + +Copy the skill directories into your project's `.claude/skills/` directory: + +```bash +# From your project root +mkdir -p .claude/skills +cp -r titan-recon titan-gauntlet titan-sync titan-gate titan-reset .claude/skills/ +``` + +Then install codegraph if you haven't: + +```bash +npm install -g @optave/codegraph +codegraph build . +``` + +## Usage + +### Full pipeline + +``` +/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 +``` + +If GAUNTLET runs out of context, just re-invoke `/titan-gauntlet` — it resumes from the next pending batch. + +### Standalone phases + +- `/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-gate` works with or without prior artifacts (uses default thresholds) +- `/titan-reset` cleans up everything — use when you want to start over + +### Iterative workflow + +``` +/titan-recon # Once: map the codebase +/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 +``` + +## Artifacts + +All artifacts are written to `.codegraph/titan/` (6 files, no redundancy): + +| File | Format | Written by | Read by | +|------|--------|-----------|---------| +| `titan-state.json` | JSON | RECON (init), ALL (update) | ALL | +| `GLOBAL_ARCH.md` | Markdown | RECON | GAUNTLET, SYNC | +| `gauntlet.ndjson` | NDJSON | GAUNTLET | SYNC | +| `gauntlet-summary.json` | JSON | GAUNTLET | SYNC, GATE | +| `sync.json` | JSON | SYNC | GATE | +| `gate-log.ndjson` | NDJSON | GATE | Audit trail | + +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. + +## Snapshots + +Codegraph snapshots provide instant graph database backup/restore: + +| Snapshot | Created by | Restored by | Deleted by | +|----------|-----------|------------|-----------| +| `titan-baseline` | RECON | GATE (on failure) | GATE (final success) or RESET | +| `titan-batch-N` | GAUNTLET (per batch) | GATE (on failure) | GAUNTLET (next batch) or RESET | + +## Context Window Management + +1. **JSON over tables.** All codegraph commands use `--json` for compact output. +2. **Batch processing with resume.** GAUNTLET processes 5 targets at a time (configurable), writes to NDJSON, stops at ~80% context. Re-invoking resumes automatically. +3. **Artifact bridging.** Each phase reads compact JSON artifacts, not raw source files. +4. **`codegraph batch `** queries multiple targets in one call (e.g., `batch complexity t1 t2 t3`). +5. **`--above-threshold`** returns only functions exceeding thresholds — skip the noise. +6. **No-test filtering.** All commands use `-T` to exclude test files. + +### Cross-session continuity + +Run each `/titan-*` skill in a separate conversation if needed: +- Artifacts on disk bridge between conversations +- `titan-state.json` tracks progress, pending batches, and file audit status +- No context is lost because each phase's output is self-contained + +## Customizing Thresholds + +Edit the Rule 1 threshold table in `.claude/skills/titan-gauntlet/SKILL.md`: + +```markdown +| Metric | Warn | Fail | Why | +|--------|------|------|-----| +| cognitive | > 15 | > 30 | How hard to understand | +| cyclomatic | > 10 | > 20 | How many paths to test | +| maxNesting | > 3 | > 5 | Flatten with guards | +| halstead.effort | > 5000 | > 15000 | Information-theoretic density | +| halstead.bugs | > 0.5 | > 1.0 | Estimated defect count | +| mi | < 50 | < 20 | Composite health | +| loc.sloc | > 50 | > 100 | Too long — split | +``` + +Adjust for your codebase — stricter for greenfield, more lenient for legacy code. + +## Worktree Isolation + +All skills enforce worktree isolation as their first step. If invoked from the main checkout, they stop and ask for `/worktree`. This prevents: + +- Titan artifacts from polluting the main checkout +- Concurrent sessions from interfering +- Accidental commits of analysis artifacts + +## Codegraph Commands Used + +| Command | Used by | Purpose | +|---------|---------|---------| +| `codegraph build` | RECON | Build/refresh the dependency graph | +| `codegraph embed` | RECON | Generate embeddings for DRY detection | +| `codegraph stats` | RECON | Baseline metrics | +| `codegraph triage` | RECON, GAUNTLET (fallback) | Ranked priority queue | +| `codegraph map` | RECON | High-traffic files | +| `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 --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 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 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 | +| `codegraph snapshot save\|restore\|delete` | RECON, GAUNTLET, GATE, RESET | Graph database backup/restore | + +## Further Reading + +- [Titan Paradigm Use Case](../../use-cases/titan-paradigm.md) — the full rationale and codegraph command mapping +- [AI Agent Guide](../../ai-agent-guide.md) — general guide for using codegraph with AI agents +- [MCP Examples](../MCP.md) — using codegraph via MCP for programmatic agent access +- [Claude Code Hooks](../claude-code-hooks/README.md) — automated hooks that complement these skills diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md new file mode 100644 index 00000000..c1d7c359 --- /dev/null +++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md @@ -0,0 +1,262 @@ +--- +name: titan-gate +description: Validate staged changes — codegraph checks + project lint/build/test, auto-rollback on failure, pass/fail commit gate (Titan Paradigm Phase 4) +argument-hint: <--force to skip warnings> +allowed-tools: Bash, Read, Write, Edit, Grep +--- + +# Titan GATE — Change Validation & State Machine + +You are running the **GATE** phase (State Machine) of the Titan Paradigm. + +Your goal: validate staged changes against codegraph quality checks AND the project's own lint/build/test. Produce a clear PASS/WARN/FAIL verdict. Auto-rollback on failure. + +> **Context budget:** Lightweight — only checks staged changes. Should complete quickly. + +**Force mode:** If `$ARGUMENTS` contains `--force`, warnings are downgraded (failures still block). + +--- + +## 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. **Staged changes?** + ```bash + git diff --cached --name-only + ``` + If nothing staged, stop: "Nothing staged. Use `git add` first." + +3. **Load state (optional).** Read `.codegraph/titan/titan-state.json` if it exists — use for thresholds, baseline comparison, and sync alignment. If missing or corrupt, proceed with defaults. + +--- + +## Step 1 — Structural validation (codegraph) + +Run the full change validation predicates in one call: + +```bash +codegraph check --staged --cycles --blast-radius 30 --boundaries -T --json +``` + +This checks: manifesto rules, new cycle introduction, blast radius threshold, and architecture boundary violations. Exit code 0 = pass, 1 = fail. + +Also run detailed impact analysis: + +```bash +codegraph diff-impact --staged -T --json +``` + +Extract: changed functions (count + names), direct callers affected, transitive blast radius, historically coupled files. + +--- + +## Step 2 — Cycle check + +```bash +codegraph cycles --json +``` + +Compare against RECON baseline (if `titan-state.json` exists): +- **New cycles?** → FAIL +- **Cycles resolved?** → Note as positive + +--- + +## Step 3 — Complexity delta + +For each changed file (from diff-impact): + +```bash +codegraph complexity --file --health -T --json +``` + +Check all metrics against thresholds: +- `cognitive` > 30 → FAIL +- `halstead.bugs` > 1.0 → FAIL (estimated defect) +- `mi` < 20 → FAIL +- Function moved from PASS → FAIL on any metric? → FAIL +- Function improved but still above threshold? → WARN + +--- + +## Step 4 — Lint, build, and test + +Detect project tools from `package.json`: + +```bash +node -e "const p=require('./package.json');console.log(JSON.stringify(Object.keys(p.scripts||{})))" +``` + +Run in order — stop on first failure: + +```bash +npm run lint 2>&1 || echo "LINT_FAILED" +``` + +```bash +npm run build 2>&1 || echo "BUILD_FAILED" +``` +(Skip if no `build` script.) + +```bash +npm test 2>&1 || echo "TEST_FAILED" +``` + +If any fail → overall verdict is FAIL → proceed to auto-rollback. + +--- + +## Step 5 — Branch structural diff + +```bash +codegraph branch-compare main HEAD -T --json +``` + +Cumulative structural impact of all changes on this branch (broader than `diff-impact --staged`). Detect cumulative drift. + +--- + +## Step 6 — Sync plan alignment + +If `.codegraph/titan/sync.json` exists: +- Are changed files part of the current execution phase? +- Are dependencies for these targets already completed? +- Skipping ahead in execution order? → WARN + +Advisory — prevents jumping ahead and creating conflicts. + +--- + +## Step 7 — Blast radius check + +From diff-impact results: +- Transitive blast radius > 30 → FAIL +- Transitive blast radius > 15 → WARN +- Historically coupled file NOT staged? → WARN ("consider also updating X") + +--- + +## Step 8 — Verdict and auto-rollback + +Aggregate all checks: + +| Verdict | Meaning | +|---------|---------| +| **PASS** | Safe to commit | +| **WARN** | Warnings only — commit at your discretion | +| **FAIL** | Failures present — auto-rollback triggered | + +### Auto-rollback on FAIL (build/test/lint failures only) + +1. **Restore graph** to the most recent snapshot: + ```bash + codegraph snapshot restore titan-batch- # or titan-baseline if no batch snapshot + ``` + Check `titan-state.json → snapshots.lastBatch` first; fall back to `snapshots.baseline`. + +2. **Unstage changes** (preserve in working tree): + ```bash + git reset HEAD + ``` + +3. **Rebuild graph** for current working tree state: + ```bash + codegraph build + ``` + +> "GATE FAIL: [reason]. Graph restored, changes unstaged but preserved. Fix and re-stage." + +For structural-only failures (Steps 1-3, 5-7), do NOT auto-rollback — report and let user decide. + +### Snapshot cleanup on pipeline completion + +When the full Titan pipeline is done (all SYNC phases complete, final GATE passes): + +```bash +codegraph snapshot delete titan-baseline +codegraph snapshot delete titan-batch- # if any remain +``` + +> "All Titan snapshots cleaned up. Codebase is in its final validated state." + +--- + +## Step 9 — Update state machine + +Append to `.codegraph/titan/gate-log.ndjson`: + +```json +{ + "timestamp": "", + "verdict": "PASS|WARN|FAIL", + "stagedFiles": ["file1.js"], + "changedFunctions": 3, + "blastRadius": 12, + "checks": { + "manifesto": "pass|fail", + "cycles": "pass|fail", + "complexity": "pass|warn|fail", + "lint": "pass|fail|skipped", + "build": "pass|fail|skipped", + "tests": "pass|fail|skipped", + "syncAlignment": "pass|warn|skipped", + "blastRadius": "pass|warn|fail" + }, + "rolledBack": false +} +``` + +Update `titan-state.json` (if exists): increment `progress.fixed`, update `fileAudits` for fixed files. + +--- + +## Step 10 — Report to user + +**PASS:** +``` +GATE PASS — safe to commit + Changed: 3 functions across 2 files + Blast radius: 12 transitive callers + Lint: pass | Build: pass | Tests: pass + Complexity: all within thresholds (worst: halstead.bugs 0.3) +``` + +**WARN:** +``` +GATE WARN — review before committing + Changed: 5 functions across 3 files + Warnings: + - utils.js historically co-changes with config.js (not staged) + - parseConfig MI improved 18 → 35 but still below 50 +``` + +**FAIL:** +``` +GATE FAIL — changes unstaged, graph restored + Failures: + - Tests: 2 suites failed + - New cycle: parseConfig → loadConfig → parseConfig + Fix issues, re-stage, re-run /titan-gate +``` + +--- + +## Rules + +- **Fast execution.** Only staged changes, not full codebase. +- **Always use `--json` and `-T`.** +- **Never auto-commit.** Verdict only — user decides. +- **Auto-rollback is gentle** — `git reset HEAD`, never `git checkout`. Work preserved. +- **Append to gate-log.ndjson** — the audit trail. +- **Force mode** downgrades WARN → PASS but cannot override FAIL. +- **Run the project's own lint/build/test** — codegraph checks are necessary but not sufficient. +- **Use the correct check flags:** `--cycles`, `--blast-radius `, `--boundaries`. + +## Self-Improvement + +This skill lives at `.claude/skills/titan-gate/SKILL.md`. Adjust thresholds or rollback behavior after dogfooding. diff --git a/docs/examples/claude-code-skills/titan-gauntlet/SKILL.md b/docs/examples/claude-code-skills/titan-gauntlet/SKILL.md new file mode 100644 index 00000000..d6ae1050 --- /dev/null +++ b/docs/examples/claude-code-skills/titan-gauntlet/SKILL.md @@ -0,0 +1,358 @@ +--- +name: titan-gauntlet +description: Audit codebase files against the 4-pillar quality manifesto using RECON work batches, with batch processing and context budget management (Titan Paradigm Phase 2) +argument-hint: +allowed-tools: Bash, Read, Write, Glob, Grep, Edit +--- + +# Titan GAUNTLET — The Perfectionist Manifesto + +You are running the **GAUNTLET** phase of the Titan Paradigm. + +Your goal: audit every high-priority target from the RECON phase against 4 pillars of quality, using work batches to stay within context limits. Each batch writes results to disk before starting the next. If context reaches ~80% capacity, stop and tell the user to re-invoke — the state machine ensures no work is lost. + +**Batch size:** `$ARGUMENTS` (default: `5`) + +> **Context budget:** Process `$ARGUMENTS` targets per batch. Write results to NDJSON after each batch. If context grows large, save state and stop — the user re-invokes to continue. + +--- + +## 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 + ``` + +3. **Load state.** Read `.codegraph/titan/titan-state.json`. If missing: + - Warn: "No RECON artifacts. Run `/titan-recon` first for best results." + - Fall back: `codegraph triage -T --limit 50 --json` for a minimal queue. + +4. **Load architecture.** Read `.codegraph/titan/GLOBAL_ARCH.md` for domain context. + +5. **Resume logic.** If `titan-state.json` has completed batches, skip them. Start from the first `pending` batch. + +6. **Validate state.** If `titan-state.json` fails to parse, stop: "State file corrupted. Run `/titan-reset` to start over, or `/titan-recon` to rebuild." + +--- + +## Step 1 — The Four Pillars + +Every file must be checked against all four pillars. A file **FAILS** if it has any fail-level violation. + +### Pillar I: Structural Purity & Logic + +#### Rule 1 — Complexity (multi-metric) +```bash +codegraph complexity --file --health -T --json +``` +This returns ALL metrics in one call — use them all: + +| Metric | Warn | Fail | Why it matters | +|--------|------|------|---------------| +| `cognitive` | > 15 | > 30 | How hard to understand | +| `cyclomatic` | > 10 | > 20 | How many paths to test | +| `maxNesting` | > 3 | > 5 | Flatten with guards/extraction | +| `halstead.effort` | > 5000 | > 15000 | Information-theoretic complexity | +| `halstead.bugs` | > 0.5 | > 1.0 | Estimated defect count | +| `mi` (Maintainability Index) | < 50 | < 20 | Composite health score | +| `loc.sloc` | > 50 | > 100 | Function too long — split it | + +#### Rule 2 — Async hygiene (every Promise caught) +```bash +codegraph ast --kind await --file -T --json +codegraph ast --kind call --file -T --json +``` +Cross-reference: `.then()` calls without `.catch()` on the same chain; async functions without `try/catch` wrapping await calls. Also grep: +```bash +grep -n "\.then(" +grep -n "async " +``` +**Fail:** uncaught promise chains or async functions without error handling. + +#### Rule 3 — Dependency direction (no upward imports) +```bash +codegraph check --boundaries -T --json +codegraph deps --json +``` +Cross-reference with GLOBAL_ARCH.md layer rules. **Fail:** import from a higher layer. + +#### Rule 4 — Dead code (no unused exports) +```bash +codegraph roles --role dead --file -T --json +codegraph exports -T --json +``` +**Fail:** dead exports or unreferenced symbols. + +#### Rule 5 — Resource hygiene +```bash +codegraph ast --kind call --file -T --json +``` +Find `addEventListener`, `setInterval`, `setTimeout`, `createReadStream`, `.on(` — verify matching cleanup. **Fail:** resource acquired without cleanup. + +#### Rule 6 — Immutability +```bash +codegraph dataflow -T --json +``` +Also grep for mutation patterns: +```bash +grep -n "\.push(\|\.splice(\|\.sort(\|\.reverse(\|delete " +``` +**Fail:** direct mutation of function arguments or external state. + +### Pillar II: Data & Type Sovereignty + +#### Rule 7 — Magic values +```bash +codegraph ast --kind string --file -T --json +``` +Also grep for numeric literals in logic branches: +```bash +grep -nE "[^a-zA-Z_][0-9]{2,}[^a-zA-Z_]" +``` +Filter out imports, log format strings, test assertions. **Warn:** present. **Fail:** in if/switch conditions. + +#### Rule 8 — Boundary validation +```bash +codegraph roles --role entry --file -T --json +codegraph where --file -T --json +``` +For entry-point functions, verify schema validation before processing. **Fail:** missing validation at system boundaries. + +#### Rule 9 — Secret hygiene +```bash +grep -niE "api.?key|secret|password|token|credential" +``` +Verify values come from config/env, not literals. **Fail:** hardcoded secret values. + +#### Rule 10 — Error integrity (no empty catches) +```bash +grep -nA2 "catch" +``` +**Fail:** empty catch block or catch with only `// ignore` or `// TODO`. + +### Pillar III: Ecosystem Synergy + +#### Rule 11 — DRY (no duplicated logic) +```bash +codegraph search "" -T --json +codegraph co-change -T --json +``` +Find semantically similar functions. If `codegraph search` fails (no embeddings), use grep for function signature patterns. **Warn:** similar patterns. **Fail:** near-verbatim copy. + +> Note: requires embeddings from `/titan-recon`. If `titan-state.json → embeddingsAvailable` is false, skip semantic search and note it. + +#### Rule 12 — Naming symmetry +```bash +codegraph where --file -T --json +``` +Scan function names in the domain. Flag mixed `get`/`fetch`/`retrieve` or `create`/`make`/`build` for the same concept. **Warn:** inconsistent. **Advisory** — not a fail condition. + +#### Rule 13 — Config over code +```bash +codegraph deps --json +``` +Also grep: +```bash +grep -n "process.env\|NODE_ENV\|production\|development" +``` +Verify env-specific behavior driven by config, not inline branches. **Warn:** inline env branch. + +### Pillar IV: The Quality Vigil + +#### Rule 14 — Naming quality +```bash +codegraph where --file -T --json +``` +Flag vague names: `data`, `obj`, `temp`, `res`, `val`, `item`, `result`, single-letter vars (except `i/j/k`). **Warn:** present. **Advisory.** + +#### Rule 15 — Structured logging +```bash +codegraph ast --kind call --file -T --json +``` +Also grep: +```bash +grep -n "console\.\(log\|warn\|error\|info\)" +``` +**Warn:** console.log in source files. **Fail:** in production code paths (non-debug, non-test). + +#### Rule 16 — Testability +```bash +codegraph fn-impact -T --json +codegraph query -T --json +``` +High fan-out correlates with many mocks needed. Also read corresponding test file and count mock/stub/spy calls. **Warn:** > 10 mocks. **Fail:** > 15 mocks. + +#### Rule 17 — Critical path coverage +```bash +codegraph roles --role core --file -T --json +``` +If file contains core symbols (high fan-in), note whether test files exist for it. **Warn:** core symbol with no test file. **Advisory.** + +### Audit trail (per file) + +For every file, the NDJSON record MUST include: +- **Verdict** and **pillar verdicts** (pass/warn/fail per pillar) +- **All metrics** from `codegraph complexity --health` (cognitive, cyclomatic, nesting, MI, halstead.bugs, halstead.effort, loc.sloc) +- **Violation list** with rule number, detail, and level +- **Recommendation** for FAIL/DECOMPOSE targets + +Codegraph provides all the data needed for a verifiable audit — no need to manually traverse files for line counts or nesting proof. + +--- + +## Step 2 — Batch audit loop + +For each pending batch (from `titan-state.json`): + +### 2a. Save pre-batch snapshot +```bash +codegraph snapshot save titan-batch- +``` +Delete the previous batch snapshot if it exists: +```bash +codegraph snapshot delete titan-batch- +``` + +### 2b. Collect all metrics in one call +```bash +codegraph batch complexity ... -T --json +``` +This returns complexity + health metrics for all targets in one call. Parse the results. + +For deeper context on high-risk targets: +```bash +codegraph batch context ... -T --json +``` + +### 2c. Run Pillar I checks +For each file in the batch: +- Parse complexity metrics from batch output (Rule 1 — all 7 metric thresholds) +- Run AST queries for async hygiene (Rule 2), resource cleanup (Rule 5) +- Check boundary violations (Rule 3): `codegraph check --boundaries -T --json` +- Check dead code (Rule 4): `codegraph roles --role dead --file -T --json` +- Check immutability (Rule 6): `codegraph dataflow` + grep + +### 2d. Run Pillar II checks +For each file: +- Magic values (Rule 7): `codegraph ast --kind string` + grep +- Boundary validation (Rule 8): check entry points +- Secret hygiene (Rule 9): grep +- Empty catches (Rule 10): grep + +### 2e. Run Pillar III checks +- DRY (Rule 11): `codegraph search` (if embeddings available) + `co-change` +- Naming symmetry (Rule 12): `codegraph where --file` +- Config over code (Rule 13): `codegraph deps` + grep + +### 2f. Run Pillar IV checks +- Naming quality (Rule 14): `codegraph where --file` +- Structured logging (Rule 15): `codegraph ast --kind call` + grep +- Testability (Rule 16): `codegraph fn-impact` + test file mock count +- Critical path coverage (Rule 17): `codegraph roles --role core` + +### 2g. Score each target + +| Verdict | Condition | +|---------|-----------| +| **PASS** | No fail-level violations | +| **WARN** | Warn-level violations only | +| **FAIL** | One or more fail-level violations | +| **DECOMPOSE** | Complexity fail + `halstead.bugs` > 1.0 + high fan-out (needs splitting) | + +For FAIL/DECOMPOSE targets, capture blast radius: +```bash +codegraph fn-impact -T --json +``` + +### 2h. Write batch results + +Append to `.codegraph/titan/gauntlet.ndjson` (one line per target): + +```json +{"target": "", "file": "", "verdict": "FAIL", "pillarVerdicts": {"I": "fail", "II": "warn", "III": "pass", "IV": "pass"}, "metrics": {"cognitive": 28, "cyclomatic": 15, "maxNesting": 4, "mi": 32, "halsteadEffort": 12000, "halsteadBugs": 1.2, "sloc": 85}, "violations": [{"rule": 1, "pillar": "I", "metric": "cognitive", "detail": "28 > 30 threshold", "level": "fail"}], "blastRadius": {"direct": 5, "transitive": 18}, "recommendation": "Split: halstead.bugs 1.2 suggests ~1 defect. Separate validation from I/O."} +``` + +### 2i. Update state machine + +Update `titan-state.json`: +- Set batch status to `"completed"` +- Increment `progress.audited`, `.passed`, `.warned`, `.failed` +- Add entries to `fileAudits` map +- Update `snapshots.lastBatch` +- Update `lastUpdated` + +### 2j. Progress check + +Print: `Batch N/M: X pass, Y warn, Z fail` + +**Context budget:** If context is growing large: +1. Write all state to disk +2. Print: `Context budget reached after Batch N. Run /titan-gauntlet to continue.` +3. Stop. + +--- + +## Step 3 — Clean up batch snapshots + +After all batches complete, delete the last batch snapshot: +```bash +codegraph snapshot delete titan-batch- +``` +Keep `titan-baseline` — GATE may need it. + +If stopping early for context, keep the last batch snapshot for safety. + +--- + +## Step 4 — Aggregate and report + +Compute from `gauntlet.ndjson`: +- Pass / Warn / Fail / Decompose counts +- Top 10 worst offenders (by violation count or `halstead.bugs`) +- Most common violations by pillar +- Files with the most failing functions + +Write `.codegraph/titan/gauntlet-summary.json`: +```json +{ + "phase": "gauntlet", + "timestamp": "", + "complete": true, + "summary": {"totalAudited": 0, "pass": 0, "warn": 0, "fail": 0, "decompose": 0}, + "worstOffenders": [], + "commonViolations": {"I": [], "II": [], "III": [], "IV": []} +} +``` + +Set `"complete": false` if stopping early. + +Print summary to user: +- Pass/Warn/Fail/Decompose counts +- Top 5 worst (with their `halstead.bugs` and `mi` scores) +- Most common violation per pillar +- Next step: `/titan-gauntlet` to continue (if incomplete) or `/titan-sync` + +--- + +## Rules + +- **Batch processing is mandatory.** Never audit more than `$ARGUMENTS` targets at once. +- **Write NDJSON incrementally.** Partial results survive crashes. +- **Always use `--json` and `-T`** on codegraph commands. +- **Use `codegraph batch `** for multi-target queries — not separate calls. +- **Leverage `--health` and `--above-threshold`** — they give you all metrics in one call. +- **Context budget:** Stop at ~80%, save state, tell user to re-invoke. +- **Lint runs once in GATE**, not per-batch here. Don't run `npm run lint`. +- Advisory rules (12, 14, 17) produce warnings, never failures. +- Dead symbols from RECON should be flagged for removal, not skipped. + +## Self-Improvement + +This skill lives at `.claude/skills/titan-gauntlet/SKILL.md`. Adjust thresholds or rules after dogfooding. diff --git a/docs/examples/claude-code-skills/titan-recon/SKILL.md b/docs/examples/claude-code-skills/titan-recon/SKILL.md new file mode 100644 index 00000000..b1ae5428 --- /dev/null +++ b/docs/examples/claude-code-skills/titan-recon/SKILL.md @@ -0,0 +1,316 @@ +--- +name: titan-recon +description: Map a codebase's dependency graph, identify hotspots, name logical domains, propose work batches, and produce a ranked priority queue for autonomous cleanup (Titan Paradigm Phase 1) +argument-hint: +allowed-tools: Bash, Read, Write, Glob, Grep, Edit +--- + +# Titan RECON — Codebase Reconnaissance + +You are running the **RECON** phase of the Titan Paradigm on the target at `$ARGUMENTS` (default: `.`). + +Your goal: map the dependency graph, identify structural hotspots, name logical domains, produce a global architecture document, propose work batches, and initialize the session state. Everything you produce feeds downstream phases (GAUNTLET, SYNC, GATE) via artifacts in `.codegraph/titan/`. + +> **Context budget:** Every codegraph command MUST use `--json` to keep output compact. Never dump raw CLI tables into context — parse JSON and extract only what you need. + +--- + +## Step 0 — Pre-flight: worktree and sync + +1. **Check for worktree isolation:** + ```bash + git rev-parse --show-toplevel && git worktree list + ``` + If you are NOT in a worktree, **stop:** "Run `/worktree` first. Titan phases write artifacts that should not interfere with other work." + +2. **Sync with main:** + ```bash + git fetch origin main && git merge origin/main --no-edit + ``` + If there are merge conflicts, stop and ask the user to resolve them. + +--- + +## Step 1 — Build the graph + +```bash +codegraph build $ARGUMENTS +``` + +Record: file count, node count, edge count, engine. + +--- + +## Step 2 — Generate embeddings (for DRY detection in GAUNTLET) + +```bash +codegraph embed -m minilm +``` + +This enables `codegraph search` for duplicate code detection in downstream phases. If it fails (e.g., missing model), note it and continue — DRY checks will be grep-only. + +--- + +## Step 3 — Collect baseline metrics + +Run in parallel: + +```bash +codegraph stats --json +codegraph structure --depth 2 --json +``` + +Extract from `stats`: `totalNodes`, `totalEdges`, `totalFiles`, `qualityScore`, `avgFanIn`, `avgFanOut`. + +Extract from `structure`: top 10 directories by file count, directories with cohesion < 0.3 (tangled). + +--- + +## Step 4 — Build the priority queue + +```bash +codegraph triage -T --limit 100 --json +``` + +Risk-ranked list combining connectivity, complexity, and role classification. Truncate to top 50 for the artifact if >100 items. + +--- + +## Step 5 — Community and drift analysis + +```bash +codegraph communities -T --json +codegraph communities --drift -T --json +``` + +Extract: community count, top 5 largest (member count + key files), drift warnings. + +--- + +## Step 6 — High-traffic files and role classification + +```bash +codegraph map --limit 30 -T --json +codegraph roles --role core -T --json +codegraph roles --role dead -T --json +``` + +Count core symbols (high fan-in) and dead symbols (zero fan-in, not exported). + +--- + +## Step 7 — Complexity health baseline + +Get the full metrics picture across the codebase — this is what makes codegraph powerful: + +```bash +codegraph complexity --health --above-threshold -T --json --limit 50 +``` + +This returns only functions exceeding configured warn thresholds, with all available metrics per function: +- **Structural:** `cognitive`, `cyclomatic`, `maxNesting` +- **Halstead:** `volume`, `difficulty`, `effort`, `bugs` (estimated bug count) +- **Size:** `loc.sloc`, `loc.commentLines` +- **Composite:** `mi` (Maintainability Index) + +Also get the worst offenders by different metrics: + +```bash +codegraph complexity --health --sort effort -T --json --limit 10 +codegraph complexity --health --sort bugs -T --json --limit 10 +codegraph complexity --health --sort mi -T --json --limit 10 +``` + +These three views reveal different quality dimensions: `effort` = hardest to understand, `bugs` = most likely to contain defects, `mi` = worst overall maintainability. + +--- + +## Step 8 — Domain inventory + +Using community detection (Step 5) and directory structure (Step 3), **name** the logical domains. A domain is a cohesive group of files serving a single concern. + +For each domain, record: +- **Name:** use the codebase's own vocabulary (directory names, module names) +- **Root directories** +- **File count** +- **Key symbols:** 3-5 most-connected symbols (from triage) +- **Community IDs:** which communities map to this domain +- **Health:** cohesion score, drift warnings, cycle participation + +For large domains, map inter-domain dependencies using key files (not directories — `deps` takes a file path): + +```bash +codegraph deps --json +``` + +--- + +## Step 9 — Global architecture document + +Write `.codegraph/titan/GLOBAL_ARCH.md`: + +```markdown +# Global Architecture + +**Date:** +**Codebase:** ( files, symbols) + +## Domain Map + +| Domain | Root Dirs | Files | Core Symbols | Health | +|--------|-----------|-------|-------------|--------| +| ... | ... | ... | ... | cohesion, drift? | + +## Dependency Flow + + + +## Shared Types and Interfaces + + + +## Architectural Rules + + + +## Cycles + + +``` + +--- + +## Step 10 — Propose work batches + +Decompose the priority queue into **work batches** of ~5-15 files each: +- Stay within a single domain where possible +- Group tightly-coupled files together (from communities) +- Order by priority: highest-risk domains first +- Note dependencies: "batch N depends on batch M being done first" + +--- + +## Step 11 — Save baseline snapshot + +```bash +codegraph snapshot save titan-baseline +``` + +This is the rollback point. If anything goes wrong downstream, any skill can restore it. + +--- + +## Step 12 — Write the state file + +Create `.codegraph/titan/titan-state.json` — the single source of truth for the entire pipeline: + +```bash +mkdir -p .codegraph/titan +``` + +```json +{ + "version": 1, + "initialized": "", + "lastUpdated": "", + "target": "", + "currentPhase": "recon", + "snapshots": { + "baseline": "titan-baseline", + "lastBatch": null + }, + "embeddingsAvailable": true, + "stats": { + "totalFiles": 0, + "totalNodes": 0, + "totalEdges": 0, + "qualityScore": 0, + "avgFanIn": 0, + "avgFanOut": 0 + }, + "healthBaseline": { + "functionsAboveThreshold": 0, + "worstByEffort": [""], + "worstByBugs": [""], + "worstByMI": [""] + }, + "domains": [ + { + "name": "", + "rootDirs": [""], + "fileCount": 0, + "status": "pending", + "audited": 0, + "passed": 0, + "failed": 0 + } + ], + "batches": [ + { + "id": 1, + "domain": "", + "files": [""], + "status": "pending", + "dependsOn": [], + "priority": 1 + } + ], + "priorityQueue": [ + { + "rank": 1, + "target": "", + "riskScore": 0, + "reason": "" + } + ], + "communities": { + "count": 0, + "driftWarnings": [] + }, + "roles": { + "coreCount": 0, + "deadCount": 0, + "deadSymbols": [""] + }, + "hotFiles": [""], + "tangledDirs": [""], + "fileAudits": {}, + "progress": { + "totalFiles": 0, + "audited": 0, + "passed": 0, + "warned": 0, + "failed": 0, + "fixed": 0 + } +} +``` + +--- + +## Step 13 — Report to user + +Print a concise summary: +- Graph size and quality score +- Domains identified (count and names) +- Complexity health: count of functions above threshold, top 3 worst by `halstead.bugs` +- Work batches proposed (count) +- Top 5 priority targets +- Dead symbol count +- Drift warnings +- Path to artifacts: `.codegraph/titan/titan-state.json` and `.codegraph/titan/GLOBAL_ARCH.md` +- Next step: `/titan-gauntlet` to audit the priority queue + +--- + +## Rules + +- **Always use `--json` and `-T`** on codegraph commands. +- **Never paste raw JSON** into your response — parse and extract. +- **Write artifacts before reporting.** +- If any command fails, note it and continue with partial data. +- **Domain naming** uses the codebase's own vocabulary. + +## Self-Improvement + +This skill lives at `.claude/skills/titan-recon/SKILL.md`. Edit it if you find improvements during execution. diff --git a/docs/examples/claude-code-skills/titan-reset/SKILL.md b/docs/examples/claude-code-skills/titan-reset/SKILL.md new file mode 100644 index 00000000..2c99704d --- /dev/null +++ b/docs/examples/claude-code-skills/titan-reset/SKILL.md @@ -0,0 +1,89 @@ +--- +name: titan-reset +description: Clean up all Titan Paradigm artifacts and snapshots, restoring the codebase to pre-Titan state +argument-hint: <--keep-graph to preserve the codegraph database> +allowed-tools: Bash, Read, Write, Grep +--- + +# Titan RESET — Pipeline Cleanup + +You are resetting the Titan Paradigm pipeline, removing all artifacts and restoring the codebase to its pre-Titan state. + +--- + +## Step 1 — Restore baseline snapshot (if available) + +```bash +codegraph snapshot restore titan-baseline 2>/dev/null && echo "Baseline restored" || echo "No baseline snapshot found" +``` + +This restores the graph database to its pre-GAUNTLET state. + +--- + +## Step 2 — Delete all Titan snapshots + +```bash +codegraph snapshot delete titan-baseline 2>/dev/null +``` + +Also delete any batch snapshots: + +```bash +codegraph snapshot delete titan-batch-1 2>/dev/null +codegraph snapshot delete titan-batch-2 2>/dev/null +codegraph snapshot delete titan-batch-3 2>/dev/null +codegraph snapshot delete titan-batch-4 2>/dev/null +codegraph snapshot delete titan-batch-5 2>/dev/null +codegraph snapshot delete titan-batch-6 2>/dev/null +codegraph snapshot delete titan-batch-7 2>/dev/null +codegraph snapshot delete titan-batch-8 2>/dev/null +codegraph snapshot delete titan-batch-9 2>/dev/null +codegraph snapshot delete titan-batch-10 2>/dev/null +``` + +(Errors are expected for snapshots that don't exist — ignore them.) + +--- + +## Step 3 — Remove all Titan artifacts + +```bash +rm -rf .codegraph/titan/ +``` + +This removes: +- `titan-state.json` — session state +- `GLOBAL_ARCH.md` — architecture document +- `gauntlet.ndjson` — audit results +- `gauntlet-summary.json` — aggregated results +- `sync.json` — execution plan +- `gate-log.ndjson` — gate audit trail + +--- + +## Step 4 — Rebuild graph (unless --keep-graph) + +If `$ARGUMENTS` does NOT contain `--keep-graph`: + +```bash +codegraph build +``` + +This ensures the graph reflects the current state of the codebase without any Titan-era corruption. + +If `$ARGUMENTS` contains `--keep-graph`, skip this step. + +--- + +## Step 5 — Report + +``` +Titan pipeline reset complete. + - Baseline snapshot: restored and deleted + - Batch snapshots: deleted + - Artifacts: removed (.codegraph/titan/) + - Graph: rebuilt (clean state) + +To start a fresh Titan pipeline, run /titan-recon +``` diff --git a/docs/examples/claude-code-skills/titan-sync/SKILL.md b/docs/examples/claude-code-skills/titan-sync/SKILL.md new file mode 100644 index 00000000..6b93e0e4 --- /dev/null +++ b/docs/examples/claude-code-skills/titan-sync/SKILL.md @@ -0,0 +1,233 @@ +--- +name: titan-sync +description: Identify overlapping fixes across audit results, plan shared abstractions, produce an ordered execution plan with logical commit grouping (Titan Paradigm Phase 3) +argument-hint: +allowed-tools: Bash, Read, Write, Glob, Grep, Edit +--- + +# Titan GLOBAL SYNC — Cross-Cutting Analysis & Execution Plan + +You are running the **GLOBAL SYNC** phase of the Titan Paradigm. + +Your goal: analyze GAUNTLET results to find overlapping problems, identify shared abstractions that should be built *before* individual fixes, group changes into logical commits, and produce an ordered execution plan. + +> **Context budget:** This phase reads artifacts, not source. Keep codegraph queries targeted — only for specific relationship questions between failing targets. + +--- + +## 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 + ``` + +3. **Load artifacts.** Read: + - `.codegraph/titan/titan-state.json` — state, domains, batches, file audits + - `.codegraph/titan/GLOBAL_ARCH.md` — architecture, dependency flow, shared types + - `.codegraph/titan/gauntlet.ndjson` — per-target audit details + - `.codegraph/titan/gauntlet-summary.json` — aggregated results + +4. **Validate state.** If `titan-state.json` fails to parse, stop: "State file corrupted. Run `/titan-reset`." + +5. **Check GAUNTLET completeness.** If `gauntlet-summary.json` has `"complete": false`: + > "GAUNTLET incomplete (/ batches). SYNC will plan based on known failures only. Run `/titan-gauntlet` first for a complete plan." + +6. **Extract.** From artifacts, collect: + - All FAIL and DECOMPOSE targets with violations and files + - Common violation patterns by pillar + - Community assignments + - Dead symbols (cleanup candidates) + - Domain boundaries and dependency flow + +--- + +## Step 1 — Find dependency clusters among failing targets + +For FAIL/DECOMPOSE targets that share a file or community, check connections: + +```bash +codegraph path -T --json +``` + +Group connected failures into **clusters**. Also check for cycles among them: + +```bash +codegraph cycles --functions --json +``` + +Filter to cycles including at least one FAIL/DECOMPOSE target. + +--- + +## Step 2 — Identify shared dependencies and ownership + +For each cluster, find what they share: + +```bash +codegraph deps --json +``` + +Look for: +- **Shared imports:** multiple failures import the same module → interface extraction candidate +- **Shared callers:** multiple failures called by the same function → caller needs updating +- **Common violations:** similar pillar violations across targets + +Check **code ownership** for cross-team coordination: + +```bash +codegraph owners -T --json +``` + +If different teams own files in the same cluster, note the coordination requirement. + +Run **branch structural diff** to see what's already changed: + +```bash +codegraph branch-compare main HEAD -T --json +``` + +Avoid re-auditing or conflicting with in-progress work. + +--- + +## Step 3 — Detect extraction candidates + +For DECOMPOSE targets: + +```bash +codegraph context -T --json +codegraph ast --kind call --file -T --json +``` + +Look for: +- Functions with multiple responsibilities (high cognitive + high fan-out + high `halstead.bugs`) +- Repeated patterns across failures (similar call chains) +- God files (many failing functions → split along community boundaries) + +--- + +## Step 4 — Plan shared abstractions + +Identify what to build BEFORE individual fixes: + +1. **Interface extractions** — shared dependency → extract interface +2. **Utility extractions** — repeated patterns → shared utility +3. **Module splits** — god files → split by community structure +4. **Cycle breaks** — circular deps → identify weakest link + +For each, check blast radius: +```bash +codegraph fn-impact -T --json +``` + +--- + +## Step 5 — Build execution order with logical commits + +### Phases (in order) + +1. **Dead code cleanup** — zero risk, reduces noise + - Commit: `chore: remove dead code` +2. **Shared abstractions** — before individual fixes + - One commit per abstraction: `refactor: extract X from Y` +3. **Cycle breaks** — unblocks dependent targets + - One commit per break: `refactor: break cycle between X and Y` +4. **Decompositions** — highest risk, after abstractions + - One commit per decomposition: `refactor: split X into A and B` +5. **Fail fixes** — ordered by blast radius (lowest first) + - Group by domain: `fix: address quality issues in ` +6. **Warn improvements** — optional, lowest priority + - Group by domain: `refactor: address warnings in ` + +### Ordering within each phase +- Dependencies first (if A depends on B, fix B first) +- Lower blast radius first +- Same community together + +### Each commit should: +- Touch one domain where possible +- Address one concern +- Be independently revertible +- Run `/titan-gate` before committing + +--- + +## Step 6 — Write the SYNC artifact + +Write `.codegraph/titan/sync.json`: + +```json +{ + "phase": "sync", + "timestamp": "", + "clusters": [ + { + "id": 1, + "name": "", + "targets": ["t1", "t2"], + "sharedDeps": ["mod"], + "hasCycle": false, + "owners": ["team-a", "team-b"], + "proposedAction": "Extract interface" + } + ], + "abstractions": [ + { + "type": "interface_extraction|utility_extraction|module_split|cycle_break", + "description": "...", + "source": "", + "unblocks": ["t1", "t2"], + "blastRadius": 0, + "commit": "refactor: ..." + } + ], + "executionOrder": [ + { + "phase": 1, + "label": "Dead code cleanup", + "targets": ["sym1", "sym2"], + "risk": "none", + "commit": "chore: remove dead code", + "dependencies": [] + } + ], + "deadCodeTargets": [""], + "cyclesInvolvingFailures": [] +} +``` + +Update `titan-state.json`: set `currentPhase` to `"sync"`. + +--- + +## Step 7 — Report to user + +Print: +- Dependency clusters found (count) +- Shared abstractions proposed (count) +- Execution order summary (phases, target counts, estimated commits) +- Key insight: what SYNC prevented (e.g., "3 targets share configLoader — without SYNC, 3 conflicting refactors") +- Path to `sync.json` +- Next step: start Phase 1 (dead code cleanup), validate each commit with `/titan-gate` + +--- + +## Rules + +- **Read artifacts, don't re-scan.** Codegraph commands only for targeted relationship queries. +- **Always use `--json` and `-T`.** +- **The execution order is the key output.** +- **Logical commits matter.** Never mix concerns. +- If GAUNTLET found zero failures, produce minimal plan (dead code + warnings only). +- Keep `codegraph path` queries targeted — same file or community only. + +## Self-Improvement + +This skill lives at `.claude/skills/titan-sync/SKILL.md`. Edit if clustering misses connections or execution order causes conflicts. diff --git a/docs/use-cases/titan-paradigm.md b/docs/use-cases/titan-paradigm.md index 73cb1fbb..9c3a6b10 100644 --- a/docs/use-cases/titan-paradigm.md +++ b/docs/use-cases/titan-paradigm.md @@ -31,6 +31,8 @@ That's exactly what codegraph provides. ### RECON: Map the dependency graph, prioritize high-traffic files +> **Claude Code skill:** [`/titan-recon`](../examples/claude-code-skills/titan-recon/SKILL.md) automates this entire phase — builds the graph, names domains, produces `GLOBAL_ARCH.md`, and writes a ranked priority queue with work batches. + This is codegraph's bread and butter. The RECON phase needs a dependency graph — codegraph **is** a dependency graph. ```bash @@ -81,6 +83,8 @@ codegraph where resolveImports ### THE GAUNTLET: Audit every file against strict standards +> **Claude Code skill:** [`/titan-gauntlet`](../examples/claude-code-skills/titan-gauntlet/SKILL.md) implements all 4 pillars (17 rules) with batch processing, multi-agent dispatch, context budget management, and session resumability via `titan-state.json`. + The Gauntlet needs each sub-agent to understand what a file does, what depends on it, and how risky changes are. The `audit` command gives each agent everything in one call: ```bash @@ -125,6 +129,8 @@ codegraph audit parseConfig -T --json > audit/parser.json ### GLOBAL SYNC: Identify overlapping fixes, build shared abstractions +> **Claude Code skill:** [`/titan-sync`](../examples/claude-code-skills/titan-sync/SKILL.md) reads GAUNTLET artifacts, finds dependency clusters among failures, plans shared abstractions, and produces an ordered execution plan with logical commit grouping. + Before the swarm starts coding, a lead agent needs to see the big picture: which files are tightly coupled, where circular dependencies exist, and what shared abstractions could be extracted. ```bash @@ -150,6 +156,8 @@ The lead agent can use `cycles` to identify dependency knots, `path` to understa ### STATE MACHINE: Track changes, verify impact, enable rollback +> **Claude Code skill:** [`/titan-gate`](../examples/claude-code-skills/titan-gate/SKILL.md) validates staged changes against codegraph thresholds AND the project's own lint/build/test. Auto-rolls back on failure. Maintains an append-only audit trail in `gate-log.ndjson`. + The State Machine phase needs yes/no answers: "Did this change introduce a cycle?" "Did blast radius exceed N?" "Did any boundary get violated?" The `check` command provides exactly this: ```bash @@ -251,10 +259,82 @@ Several planned features would make codegraph even more powerful for the Titan P --- +## Claude Code Skills — Ready-Made Titan Pipeline + +We've built five Claude Code skills that implement the full Titan Paradigm using codegraph. Each phase writes structured JSON artifacts to `.codegraph/titan/` that the next phase reads — this keeps context usage minimal even on large codebases. + +``` +/titan-recon → titan-state.json + GLOBAL_ARCH.md + │ + ▼ +/titan-gauntlet → gauntlet.ndjson (batches of 5, resumes across sessions) + │ + ▼ +/titan-sync → sync.json (execution plan with logical commits) + │ + ▼ +/titan-gate (validates each commit: codegraph + lint/build/test) + +/titan-reset (escape hatch: clean up all artifacts and snapshots) +``` + +| Skill | Phase | What it does | +|-------|-------|-------------| +| `/titan-recon` | RECON | Builds graph + embeddings, runs complexity health baseline (`--health --above-threshold`), identifies domains, produces priority queue + work batches + `GLOBAL_ARCH.md`, saves baseline snapshot | +| `/titan-gauntlet` | GAUNTLET | 4-pillar audit (17 rules) leveraging codegraph's full metrics (`cognitive`, `cyclomatic`, `halstead.bugs`, `halstead.effort`, `mi`, `loc.sloc`). Batches of 5 (configurable), NDJSON incremental writes, resumes across sessions via `titan-state.json` | +| `/titan-sync` | GLOBAL SYNC | Finds dependency clusters among failures using `codegraph path` + `owners` + `branch-compare`. Plans shared abstractions, produces ordered execution plan with logical commit grouping | +| `/titan-gate` | STATE MACHINE | Validates staged changes: `codegraph check --staged --cycles --blast-radius 30 --boundaries` + project lint/build/test. Auto-rollback with snapshot restore on failure. Append-only audit trail | +| `/titan-reset` | ESCAPE HATCH | Restores baseline snapshot, deletes all Titan artifacts and snapshots, rebuilds graph clean | + +### Context window management + +The original Titan Paradigm prompt struggles with large codebases because a single agent cannot hold everything in context. These skills solve this two ways: + +1. **Artifact bridging:** each phase writes compact JSON artifacts. The next phase reads only those — not the full source. Works across separate conversations too. +2. **Batch processing with resume:** the GAUNTLET audits 5 files at a time (configurable), writes to NDJSON between batches, and stops at ~80% context usage. Re-invoking `/titan-gauntlet` resumes from the next pending batch automatically. + +### Snapshot lifecycle + +Codegraph snapshots provide instant graph database backup/restore at each stage: + +| Snapshot | Created by | Restored by | Deleted by | +|----------|-----------|------------|-----------| +| `titan-baseline` | RECON | GATE (on failure) | GATE (on final success) or RESET | +| `titan-batch-N` | GAUNTLET (per batch) | GATE (on failure) | GAUNTLET (next batch replaces it) or RESET | + +See [Claude Code Skills Example](../examples/claude-code-skills/) for installation and usage. + +--- + ## What's Next All six recommendations from v2.5.0 — `audit`, `batch`, `triage`, `check`, `snapshot`, and MCP orchestration tools — shipped in v2.6.0. The remaining enhancements that would make codegraph even more powerful for the Titan Paradigm are in the LLM integration roadmap: +### New backlog items surfaced by skill development + +Building and reviewing the Titan skills revealed gaps where codegraph could provide first-class support instead of relying on grep patterns or manual analysis: + +**Detection gaps — rules that currently fall back to grep:** + +| Feature | GAUNTLET Rule | How it helps | Backlog candidate | +|---------|--------------|-------------|-------------------| +| **Async hygiene detection** | Pillar I, Rule 2 | AST-level detection of uncaught promises, `.then()` without `.catch()`, and async functions without `try/catch`. Currently grep-based | `codegraph check --floating-promises` | +| **Resource leak detection** | Pillar I, Rule 5 | AST detection of `addEventListener`/`setInterval`/`createReadStream` without matching cleanup. Currently grep-based and fragile | `codegraph check --resource-leaks` | +| **Mutation tracking** | Pillar I, Rule 6 | Detect functions that mutate their arguments or external state. `codegraph dataflow` tracks flow but not mutation specifically | Enhancement to `dataflow` | +| **Empty catch detection** | Pillar II, Rule 10 | Find empty `catch` blocks or catch blocks with only comments. AST-level, not grep | `codegraph check --empty-catches` | +| **Magic literal detection** | Pillar II, Rule 7 | Find hardcoded strings/numbers in logic branches (if/switch conditions) vs constants. Currently uses `ast --kind string` but misses numeric literals | Extend `ast` with `--kind literal` | +| **Duplicate code detection** | Pillar III, Rule 11 | Identify semantically similar functions — near-duplicates to merge. `codegraph search` finds related code but doesn't specifically flag duplicates | `codegraph duplicates` or `--duplicates` on `search` | + +**Orchestration gaps — pipeline features that could be built into codegraph:** + +| Feature | Phase | How it helps | Backlog candidate | +|---------|-------|-------------|-------------------| +| **Domain inventory command** | RECON | Auto-name logical domains from communities + directory structure. Currently the skill infers this manually | `codegraph domains` combining `communities`, `structure`, and `deps` | +| **Session state persistence** | ALL | Built-in state tracking for multi-phase pipelines — per-file audit status, batch progress, execution phase. Currently the skills manage `titan-state.json` themselves | `codegraph session init/update/status` | +| **Batch complexity with `--health`** | GAUNTLET | `codegraph batch complexity` returns metrics but the skill needs `--health` data (Halstead, MI) for each target in one call. Currently must run separate per-file calls for `--health` mode | `codegraph batch complexity --health` support | +| **NDJSON integrity check** | GAUNTLET/GATE | Validate that `.ndjson` artifacts have no truncated lines from partial writes. A single malformed line corrupts downstream parsing | `codegraph session validate` or built-in NDJSON repair | +| **Concurrent-safe graph operations** | GAUNTLET | Multiple agents running codegraph simultaneously corrupt the SQLite database. A locking mechanism or read-only mode would enable safe parallel querying | `--read-only` flag on query commands, or WAL mode with proper locking | + ### LLM-enhanced features (Roadmap Phase 4+) | Feature | How it helps the Titan Paradigm | @@ -276,7 +356,25 @@ cd your-project codegraph build ``` -Then wire your orchestrator's RECON phase to start with: +### With Claude Code skills (recommended) + +Copy the skills into your project and run the pipeline: + +```bash +# Install skills +cp -r node_modules/@optave/codegraph/docs/examples/claude-code-skills/titan-* .claude/skills/ + +# In Claude Code: +/titan-recon # Map the codebase, produce priority queue +/titan-gauntlet 5 # Audit top targets in batches of 5 +/titan-sync # Plan shared abstractions and execution order +# ... make changes ... +/titan-gate # Validate before each commit +``` + +### With raw commands + +Wire your orchestrator's RECON phase to start with: ```bash codegraph triage -T --limit 50 --json # Ranked priority queue (one call) diff --git a/tests/unit/db.test.js b/tests/unit/db.test.js index a1be6c4b..4f13fc39 100644 --- a/tests/unit/db.test.js +++ b/tests/unit/db.test.js @@ -321,11 +321,12 @@ describe('findDbPath with git ceiling', () => { try { _resetRepoRootCache(); const result = findDbPath(); - // Verify the DB was found (file exists) and is the worktree DB, not the outer one + // Avoid exact path comparison — realpathSync doesn't resolve Windows + // 8.3 short names (RUNNER~1 vs runneradmin) on CI. Instead verify + // existence, suffix, and that it's not the outer directory's DB. expect(fs.existsSync(result)).toBe(true); expect(result).toMatch(/\.codegraph[/\\]graph\.db$/); - // The outer DB is at outerDir/.codegraph — verify we didn't find that one - expect(result).not.toContain(`${path.basename(outerDir)}${path.sep}.codegraph`); + expect(result).not.toContain(path.basename(outerDir) + path.sep + '.codegraph'); } finally { process.cwd = origCwd; fs.rmSync(path.join(worktreeRoot, '.codegraph'), { recursive: true, force: true });