docs: add Titan Paradigm Claude Code skills#473
Conversation
findDbPath() walks up from cwd looking for .codegraph/graph.db. In a git worktree (e.g. .claude/worktrees/agent-xxx/), this crosses the worktree boundary and finds the main repo's database instead. Add findRepoRoot() using `git rev-parse --show-toplevel` (which returns the correct root for both repos and worktrees) and use it as a ceiling in findDbPath(). The walk-up now stops at the git boundary, so each worktree resolves to its own database.
…t test - Ceiling test now uses `git init` to create a real git repo boundary, and verifies the outer DB is NOT found (without the ceiling fix it would be). Added separate test for finding DB within the boundary. - Non-git test uses a fresh mkdtemp dir instead of os.tmpdir(). - Added debug log when ceiling stops the walk-up. - Removed unused `origFindRepoRoot` variable.
- Mock execFileSync via vi.mock to verify caching calls exactly once and cache bypass calls twice (not just comparing return values) - Mock execFileSync to throw in "not in git repo" test so the null path is always exercised regardless of host environment - Rename "does not use cache" test to "bypasses cache" with spy assertion
…edback" This reverts commit 83efde5.
…eedback" This reverts commit ccb8bd5.
…rt name - Mock execFileSync to throw in "falls back gracefully when not in a git repo" test, preventing flakiness when os.tmpdir() is inside a git repo - Rename realExecFileSync → execFileSyncForSetup with comment explaining it resolves to the spy due to vi.mock hoisting
Combine PR's connection.js imports (findRepoRoot, _resetRepoRootCache) with main's barrel db/index.js pattern. Add missing re-exports to barrel. Impact: 22 functions changed, 10 affected
On macOS, os.tmpdir() returns /var/folders/... but git rev-parse returns /private/var/folders/... (resolved symlink). The ceiling comparison failed because the paths didn't match. Use fs.realpathSync on cwd to normalize symlinks before comparing against the ceiling. Impact: 1 functions changed, 1 affected
Impact: 1 functions changed, 1 affected
…boundary Impact: 9 functions changed, 19 affected
The 'returns default path when no DB found' test didn't control the git ceiling — if tmpDir was inside a git repo, findRepoRoot() would return a non-null ceiling and the default path would differ from emptyDir. Mock execFileSync to throw so the cwd fallback is always exercised.
…m ceiling On macOS, os.tmpdir() returns /var/... but git resolves symlinks to /private/var/..., and on Windows, 8.3 short names (RUNNER~1) differ from long names (runneradmin). findDbPath normalizes dir via fs.realpathSync but findRepoRoot only used path.resolve, causing the ceiling comparison to fail — the walk crossed the worktree boundary. Fix findRepoRoot to use fs.realpathSync on git output, and resolve test paths after directory creation so assertions match. Impact: 1 functions changed, 77 affected
git rev-parse resolves 8.3 short names (RUNNER~1 → runneradmin) but fs.realpathSync may not, causing the string comparison to fail and the walk to escape the git ceiling boundary. Replace string equality with isSameDirectory() that falls back to dev+ino comparison when paths differ textually but refer to the same directory. Also fix the test assertion to use findRepoRoot() for the expected ceiling path instead of the test's worktreeRoot, since git may resolve paths differently than realpathSync. Impact: 2 functions changed, 137 affected
Impact: 2 functions changed, 2 affected
…hort names Impact: 1 functions changed, 1 affected
…tave/codegraph into fix/db-path-worktree-boundary Impact: 13 functions changed, 3 affected
On Windows CI, fs.realpathSync(process.cwd()) and git rev-parse --show-toplevel can resolve 8.3 short names (RUNNER~1) differently than long names (runneradmin). Apply realpathSync to both sides of the assertion so the comparison is path-equivalent.
…leanup Five skills implementing the full Titan Paradigm pipeline: - /titan-recon: graph build, embeddings, health baseline, domain mapping - /titan-gauntlet: 4-pillar audit (17 rules) with batch processing and resume - /titan-sync: dependency cluster analysis and ordered execution planning - /titan-gate: staged change validation with auto-rollback on failure - /titan-reset: escape hatch to clean all artifacts and snapshots Skills use artifact-passing between phases to manage context window limits. Published as docs/examples for users to copy, with live copies in .claude/skills/. Updated titan-paradigm.md with skill references and new backlog items.
- Add openRepo to db/index.js barrel export (from main) - Keep realpathSync-based assertions for Windows 8.3 path normalization (from HEAD) Impact: 33 functions changed, 28 affected
Greptile SummaryThis PR adds five Claude Code skills ( Key findings:
Confidence Score: 2/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant RECON as /titan-recon
participant GAUNTLET as /titan-gauntlet
participant SYNC as /titan-sync
participant GATE as /titan-gate
participant RESET as /titan-reset
participant FS as .codegraph/titan/
participant CG as codegraph CLI
User->>RECON: /titan-recon
RECON->>CG: build, embed, stats, triage, communities, roles, complexity --health
RECON->>CG: snapshot save titan-baseline
RECON->>FS: write titan-state.json + GLOBAL_ARCH.md
User->>GAUNTLET: /titan-gauntlet [batch-size]
GAUNTLET->>FS: read titan-state.json (resume from pending batch)
loop For each pending batch
GAUNTLET->>CG: snapshot save titan-batch-N
GAUNTLET->>CG: batch complexity, AST, roles, dataflow checks (17 rules)
GAUNTLET->>FS: append to gauntlet.ndjson
GAUNTLET->>FS: update titan-state.json
GAUNTLET->>CG: snapshot delete titan-batch-(N-1)
end
GAUNTLET->>FS: write gauntlet-summary.json
User->>SYNC: /titan-sync
SYNC->>FS: read gauntlet.ndjson + gauntlet-summary.json + GLOBAL_ARCH.md
SYNC->>CG: path, cycles, deps, owners, branch-compare (targeted queries)
SYNC->>FS: write sync.json (execution plan)
SYNC->>FS: update titan-state.json (currentPhase=sync)
Note over User,GATE: For each fix in execution plan:
User->>GATE: /titan-gate [--force]
GATE->>CG: check --staged --cycles --blast-radius --boundaries
GATE->>CG: diff-impact, cycles, complexity --health
GATE->>CG: npm run lint / build / test
alt PASS or WARN
GATE->>FS: append to gate-log.ndjson
GATE-->>User: PASS — safe to commit
else FAIL
GATE->>CG: snapshot restore titan-batch-N (or titan-baseline)
GATE->>CG: git reset HEAD
GATE->>CG: codegraph build
GATE->>FS: append to gate-log.ndjson (rolledBack=true)
GATE-->>User: FAIL — changes unstaged, graph restored
end
User->>RESET: /titan-reset [--keep-graph]
RESET->>CG: snapshot restore titan-baseline
RESET->>CG: snapshot delete titan-baseline + all titan-batch-N
RESET->>FS: rm -rf .codegraph/titan/
RESET->>CG: codegraph build
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| ## Artifacts | ||
|
|
||
| All artifacts are written to `.codegraph/titan/` (5 files, no redundancy): |
There was a problem hiding this comment.
Artifact count is off by one
The text says "5 files" but the table immediately below lists 6 artifacts (titan-state.json, GLOBAL_ARCH.md, gauntlet.ndjson, gauntlet-summary.json, sync.json, gate-log.ndjson).
| All artifacts are written to `.codegraph/titan/` (5 files, no redundancy): | |
| All artifacts are written to `.codegraph/titan/` (6 files, no redundancy): |
There was a problem hiding this comment.
Fixed — changed '5 files' to '6 files' to match the artifact table.
docs/use-cases/titan-paradigm.md
Outdated
|
|
||
| ### 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 (31 rules) with batch processing, multi-agent dispatch, context budget management, and session resumability via `titan-state.json`. |
There was a problem hiding this comment.
Rule count mismatch: 31 vs 17
The GAUNTLET skill (titan-gauntlet/SKILL.md) defines 17 rules (Rules 1–17 across 4 pillars), and the README also says "17 rules". This line says "31 rules" which is inconsistent.
| > **Claude Code skill:** [`/titan-gauntlet`](../examples/claude-code-skills/titan-gauntlet/SKILL.md) implements all 4 pillars (31 rules) with batch processing, multi-agent dispatch, context budget management, and session resumability via `titan-state.json`. | |
| > **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`. |
There was a problem hiding this comment.
Fixed — changed '31 rules' to '17 rules' to match the GAUNTLET skill definition.
Skill checks all open PRs, resolves conflicts (via merge, never rebase), fixes CI failures, addresses all reviewer comments (Claude + Greptile), replies to each comment, and re-triggers reviewers in a loop until clean.
This reverts commit cc6dafd.
Replace realpathSync comparison in db.test.js ceiling test with existence-based assertions to avoid Windows 8.3 short name mismatch (RUNNER~1 vs runneradmin). Fix artifact count (5 -> 6 files) in skills README and rule count (31 -> 17 rules) in titan-paradigm.md.
| --- | ||
|
|
||
| ## Step 3 — Remove all Titan artifacts | ||
|
|
||
| ```bash | ||
| rm -rf .codegraph/titan/ | ||
| ``` | ||
|
|
||
| This removes: | ||
| - `titan-state.json` — session state | ||
| - `GLOBAL_ARCH.md` — architecture document |
There was a problem hiding this comment.
Hard-coded batch limit of 10 leaves stale snapshots on larger runs
The RESET skill deletes titan-batch-1 through titan-batch-10 only. GAUNTLET saves a snapshot before every batch (titan-batch-<N>) and the batch count scales with codebase size — a 100-file codebase with the default batch size of 5 produces up to 20 batches, and a 500-file codebase can produce far more. Any batches above index 10 will have their snapshots silently left behind after a reset, occupying disk space and potentially confusing future runs.
Consider replacing the fixed list with a dynamic approach that reads the actual snapshot count from titan-state.json before deleting, or iterates until no snapshot is found:
# Read max batch from titan-state.json if it exists, else fall back to a large N
MAX=$(node -e "try{const s=require('./.codegraph/titan/titan-state.json');const ids=s.batches.map(b=>b.id);console.log(Math.max(...ids))}catch(e){console.log(50)}" 2>/dev/null || echo 50)
for i in $(seq 1 $MAX); do
codegraph snapshot delete "titan-batch-$i" 2>/dev/null
doneThe same hard-coded limit exists in .claude/skills/titan-reset/SKILL.md.
There was a problem hiding this comment.
Fixed — replaced the hardcoded titan-batch-1 through titan-batch-10 deletion with dynamic snapshot discovery in both copies of titan-reset/SKILL.md.
| ``` | ||
|
|
||
| 3. **Load state.** Read `.codegraph/titan/titan-state.json`. If missing: | ||
| - Warn: "No RECON artifacts. Run `/titan-recon` first for best results." |
There was a problem hiding this comment.
Missing merge-conflict guard in pre-flight
RECON's pre-flight explicitly says "If there are merge conflicts, stop and ask the user to resolve them", but GAUNTLET (and SYNC) silently proceed past a failed --no-edit merge. A merge conflict will corrupt the working tree mid-audit.
Consider adding the same guard used in RECON:
| ``` | |
| 3. **Load state.** Read `.codegraph/titan/titan-state.json`. If missing: | |
| - Warn: "No RECON artifacts. Run `/titan-recon` first for best results." | |
| 2. **Sync with main:** | |
| ```bash | |
| git fetch origin main && git merge origin/main --no-edit |
If the merge fails due to conflicts, stop: "Merge conflict detected. Resolve conflicts and re-run /titan-gauntlet."
The same gap exists in `titan-sync/SKILL.md` (Step 0, item 2) and their mirror copies under `.claude/skills/`.
There was a problem hiding this comment.
Fixed — added merge-conflict guard after the git merge step in both titan-gauntlet and titan-sync pre-flights (all 4 SKILL.md copies), consistent with RECON's existing guard.
… docs/titan-paradigm-skills
| # From your project root | ||
| mkdir -p .claude/skills | ||
| cp -r titan-recon titan-gauntlet titan-sync titan-gate titan-reset .claude/skills/ | ||
| ``` |
There was a problem hiding this comment.
Installation cp command won't work from project root
The comment says "From your project root" but the source paths (titan-recon, titan-gauntlet, etc.) are bare directory names with no path prefix. Running this from a user's project root would fail with "No such file or directory" since those directories don't exist there — they live under docs/examples/claude-code-skills/ in the package.
docs/use-cases/titan-paradigm.md (added in this same PR) correctly uses the full npm package path:
cp -r node_modules/@optave/codegraph/docs/examples/claude-code-skills/titan-* .claude/skills/The README installation block should match, or at minimum clarify the required working directory:
| # From your project root | |
| mkdir -p .claude/skills | |
| cp -r titan-recon titan-gauntlet titan-sync titan-gate titan-reset .claude/skills/ | |
| ``` | |
| # From your project root (assuming codegraph is installed) | |
| mkdir -p .claude/skills | |
| cp -r node_modules/@optave/codegraph/docs/examples/claude-code-skills/titan-* .claude/skills/ |
There was a problem hiding this comment.
Fixed — updated the installation cp command to use the full node_modules path, consistent with titan-paradigm.md.
| Append to `.codegraph/titan/gauntlet.ndjson` (one line per target): | ||
|
|
||
| ```json | ||
| {"target": "<name>", "file": "<path>", "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."} |
There was a problem hiding this comment.
Incorrect violation detail in NDJSON example
The example NDJSON record has "cognitive": 28 with "detail": "28 > 30 threshold", "level": "fail". Per the Rule 1 threshold table directly above this line, the cognitive fail threshold is > 30 — a value of 28 fails the warn check (> 15) but does NOT trigger a fail. The violation level should be "warn", or the cognitive value should be ≥ 31 to justify a fail.
As written, anyone parsing this example to understand the verdict/level mapping will get incorrect guidance. The same error exists at the same line in .claude/skills/titan-gauntlet/SKILL.md:280.
| {"target": "<name>", "file": "<path>", "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."} | |
| {"target": "<name>", "file": "<path>", "verdict": "FAIL", "pillarVerdicts": {"I": "fail", "II": "warn", "III": "pass", "IV": "pass"}, "metrics": {"cognitive": 35, "cyclomatic": 15, "maxNesting": 4, "mi": 32, "halsteadEffort": 12000, "halsteadBugs": 1.2, "sloc": 85}, "violations": [{"rule": 1, "pillar": "I", "metric": "cognitive", "detail": "35 > 30 threshold", "level": "fail"}], "blastRadius": {"direct": 5, "transitive": 18}, "recommendation": "Split: halstead.bugs 1.2 suggests ~1 defect. Separate validation from I/O."} |
There was a problem hiding this comment.
Fixed — changed cognitive value from 28 to 35 and detail to '35 > 30 threshold' in both copies of titan-gauntlet/SKILL.md.
| Also delete any batch snapshots dynamically: | ||
|
|
||
| ```bash | ||
| for name in $(codegraph snapshot list --json 2>/dev/null | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));d.filter(s=>s.name.startsWith('titan-batch-')).forEach(s=>console.log(s.name))}catch(e){}"); do |
There was a problem hiding this comment.
/dev/stdin is not available on Windows
The inline Node script reads from /dev/stdin to parse the JSON snapshot list. This pseudo-device path is Unix-only and will fail silently (the catch(e){} block swallows the error) on Windows, meaning batch snapshots will not be deleted on that platform.
The same issue exists in .claude/skills/titan-reset/SKILL.md:33.
Use process.stdin instead, which works cross-platform:
| for name in $(codegraph snapshot list --json 2>/dev/null | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));d.filter(s=>s.name.startsWith('titan-batch-')).forEach(s=>console.log(s.name))}catch(e){}"); do | |
| for name in $(codegraph snapshot list --json 2>/dev/null | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{JSON.parse(d).filter(s=>s.name.startsWith('titan-batch-')).forEach(s=>console.log(s.name))}catch(e){}})"); do |
There was a problem hiding this comment.
Fixed — replaced /dev/stdin with process.stdin streaming in both copies of titan-reset/SKILL.md for Windows compatibility.
…add new tests from main)
…imports) The merge 362e875 re-introduced findRepoRoot and ceiling test blocks but did not restore the required imports (_resetRepoRootCache, execFileSyncSpy, execFileSyncForSetup, findRepoRoot, vi.mock). This caused ReferenceError failures across all 6 CI test jobs. Since this is a docs-only PR, db.test.js should match main exactly.
This is a docs-only PR — db.test.js should not have any changes. The conflict arose because a prior bad merge (362e875) re-introduced test blocks without their imports. Resolving by accepting main's version which has the complete, correct test file.
1 participant
Summary
/titan-recon,/titan-gauntlet,/titan-sync,/titan-gate,/titan-reset.codegraph/titan/) to manage context window limits on large codebasesdocs/examples/claude-code-skills/with live copies in.claude/skills/titan-paradigm.mdwith skill references and 11 new backlog items (6 detection gaps, 5 orchestration gaps)Test plan
/titan-recon— verify graph build,titan-state.json, andGLOBAL_ARCH.mdare produced/titan-gauntlet— verify batch processing, NDJSON output, and snapshot creation/titan-gatewith staged changes — verify check flags, lint/build/test, and verdict/titan-reset— verify artifact cleanup and snapshot deletion