titan-gauntlet

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)

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: find or create the Titan worktree

1. Locate the Titan session. A prior phase (RECON) may have run in a different worktree or branch. Search for it:

   git worktree list
   

   For each worktree, check if it contains Titan artifacts:

   ls <worktree-path>/.codegraph/titan/titan-state.json 2>/dev/null
   

   Also check branches for titan state:

   git branch -a --list '*titan*'
   

   Decision logic:

   • Found exactly one worktree with titan-state.json: Read the state. If currentPhase is "recon" (RECON completed), this is the right one. Switch to it or merge its branch into your worktree.
   • Found a worktree but currentPhase is NOT "recon": This worktree may be mid-phase or from a different pipeline run. Keep searching other worktrees/branches. If no better match, ask the user: "Found Titan state at <path> but phase is <phase>. Is this the session to continue?"
   • Found multiple worktrees with titan-state.json: List them with their currentPhase and lastUpdated. Ask the user: "Multiple Titan sessions found. Which one should GAUNTLET continue?"
   • Found a branch (not worktree) with titan artifacts: Merge it into your current worktree:

     git merge <titan-branch> --no-edit
     

   • Found nothing: Warn: "No RECON artifacts found in any worktree or branch. Run /titan-recon first for best results." Fall back: codegraph triage -T --limit 50 --json for a minimal queue.

2. Ensure worktree isolation:

   git rev-parse --show-toplevel && git worktree list
   

   If you are NOT in a worktree, stop: "Run /worktree first."

3. Sync with main:

   git fetch origin main && git merge origin/main --no-edit
   

   If there are merge conflicts, stop: "Merge conflict detected. Resolve conflicts and re-run /titan-gauntlet."

4. Load state. Read .codegraph/titan/titan-state.json.

5. Load architecture. Read .codegraph/titan/GLOBAL_ARCH.md for domain context.

6. Resume logic. If titan-state.json has completed batches, skip them. Start from the first pending batch.

7. 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 — Drift detection: has main moved since the last phase?

The codebase may have changed significantly since RECON ran. Detect this before auditing stale data.

1. Compare main SHA:

   git rev-parse origin/main
   

   Compare against titan-state.json → mainSHA. If identical, skip to Step 2.

2. If main has advanced, find what changed:

   git diff --name-only <mainSHA>..origin/main
   

3. Cross-reference with Titan targets. Check which changed files overlap with:

   • Files in the priority queue (titan-state.json → priorityQueue)
   • Files in pending batches (titan-state.json → batches)
   • Hot files (titan-state.json → hotFiles)
   • Core symbols (titan-state.json → roles.coreCount files)

4. Run structural diff to detect architecture-level changes:

   codegraph diff-impact <mainSHA>..origin/main -T --json 2>/dev/null || echo "DIFF_UNAVAILABLE"
   

   If unavailable (e.g., old SHA not in graph), fall back to file-count heuristics.

5. Classify staleness:

   Level	Condition	Action
   none	main unchanged	Continue normally
   low	main changed but <5 files, none in priority queue	Continue — note in issues.ndjson
   moderate	Some overlap: changed files appear in priority queue or batches (<20% of batches affected)	Continue but mark affected batches for re-audit
   high	>20% of batches affected OR core symbols changed	Warn user: "Significant changes on main since RECON. Recommend re-running affected batches or /titan-recon."
   critical	New files in src/, deleted files that were in batches, or >50% of priority queue affected	Stop and recommend: "Main has diverged significantly. Run /titan-recon to rebuild the baseline."

6. Append drift report to .codegraph/titan/drift-report.json (the file is a JSON array — read existing entries first, push the new entry, write back):

   {
     "timestamp": "<ISO 8601>",
     "detectedBy": "gauntlet",
     "mainAtLastPhase": "<stored SHA>",
     "mainNow": "<current SHA>",
     "commitsBehind": 0,
     "changedFiles": ["<files changed on main>"],
     "impactedTargets": ["<priority queue targets in changed files>"],
     "impactedBatches": [1, 3],
     "impactedDomains": ["<domains containing changed files>"],
     "staleness": "none|low|moderate|high|critical",
     "recommendation": "continue|reassess-targets|rerun-gauntlet|rerun-recon",
     "reassessmentScope": {
       "targets": ["<specific targets to re-audit>"],
       "batches": [1, 3],
       "files": ["<specific files to re-check>"],
       "fullRecon": false
     }
   }
   

7. Update state: Set titan-state.json → mainSHA to current origin/main after merging.

8. If moderate: Mark impacted batches as "stale" in titan-state.json (change status from "completed" to "stale" or from "pending" to "pending-reassess"). These get re-audited during the batch loop.

9. If re-running GAUNTLET and a previous drift-report.json exists with reassessmentScope, only re-audit the targets listed — don't repeat the entire pipeline. Clear completed targets from the scope as you go.

---

Step 2 — 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)

codegraph complexity --file <f> --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)

codegraph ast --kind await --file <f> -T --json
codegraph ast --kind call --file <f> -T --json

Cross-reference: .then() calls without .catch() on the same chain; async functions without try/catch wrapping await calls. Also grep:

grep -n "\.then(" <f>
grep -n "async " <f>

Fail: uncaught promise chains or async functions without error handling.

Rule 3 — Dependency direction (no upward imports)

codegraph check --boundaries -T --json
codegraph deps <f> --json

Cross-reference with GLOBAL_ARCH.md layer rules. Fail: import from a higher layer.

Rule 4 — Dead code (no unused exports)

codegraph roles --role dead --file <f> -T --json
codegraph exports <f> -T --json

Fail: dead exports or unreferenced symbols.

Rule 5 — Resource hygiene

codegraph ast --kind call --file <f> -T --json

Find addEventListener, setInterval, setTimeout, createReadStream, .on( — verify matching cleanup. Fail: resource acquired without cleanup.

Rule 6 — Immutability

codegraph dataflow <f> -T --json

Also grep for mutation patterns:

grep -n "\.push(\|\.splice(\|\.sort(\|\.reverse(\|delete " <f>

Fail: direct mutation of function arguments or external state.

Pillar II: Data & Type Sovereignty

Rule 7 — Magic values

codegraph ast --kind string --file <f> -T --json

Also grep for numeric literals in logic branches:

grep -nE "[^a-zA-Z_][0-9]{2,}[^a-zA-Z_]" <f>

Filter out imports, log format strings, test assertions. Warn: present. Fail: in if/switch conditions.

Rule 8 — Boundary validation

codegraph roles --role entry --file <f> -T --json
codegraph where --file <f> -T --json

For entry-point functions, verify schema validation before processing. Fail: missing validation at system boundaries.

Rule 9 — Secret hygiene

grep -niE "api.?key|secret|password|token|credential" <f>

Verify values come from config/env, not literals. Fail: hardcoded secret values.

Rule 10 — Error integrity (no empty catches)

grep -nA2 "catch" <f>

Fail: empty catch block or catch with only // ignore or // TODO.

Pillar III: Ecosystem Synergy

Rule 11 — DRY (no duplicated logic)

codegraph search "<function purpose>" -T --json
codegraph co-change <f> -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.

Don't trust embeddingsAvailable blindly — verify it against the current worktree. .codegraph/ is gitignored, so graph.db and its embeddings are local, per-worktree filesystem state; they are never carried over by a branch merge or a "switch to that worktree's state" step in Step 0. A titan-state.json merged in from a different worktree/session can say embeddingsAvailable: true while the graph.db actually open right now has none — codegraph search will then run without erroring and silently return empty results, so Rule 11 looks clean when it never actually checked anything.

Before relying on embeddingsAvailable, do a deterministic identity check first: compare git rev-parse --show-toplevel (this worktree) against titan-state.json → embeddingsWorktreePath (the worktree RECON actually ran codegraph embed in). Any mismatch — or a missing embeddingsWorktreePath from an older state file — means embeddingsAvailable cannot be trusted as-is; treat it as false until re-verified. Then, at the start of Step 2 (not per-file), run a one-time smoke-test: codegraph search "test query" --json. Treat only an explicit error or ENGINE_UNAVAILABLE as failure — the same concrete criterion RECON uses — not a subjective "no hit where one seemed likely" judgment call, since a generic query legitimately returning zero results is not itself proof of a broken engine. If either check fails, regenerate for this worktree — codegraph embed -m minilm — and update both titan-state.json → embeddingsAvailable and embeddingsWorktreePath before trusting it for any Rule 11 check this run. If regeneration also fails, fall back to grep-only DRY checks and log it to issues.ndjson rather than proceeding on a false green.

Rule 12 — Naming symmetry

codegraph where --file <f> -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

codegraph deps <f> --json

Also grep:

grep -n "process.env\|NODE_ENV\|production\|development" <f>

Verify env-specific behavior driven by config, not inline branches. Warn: inline env branch.

Pillar IV: The Quality Vigil

Rule 14 — Naming quality

codegraph where --file <f> -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

codegraph ast --kind call --file <f> -T --json

Also grep:

grep -n "console\.\(log\|warn\|error\|info\)" <f>

Warn: console.log in source files. Fail: in production code paths (non-debug, non-test).

Rule 16 — Testability

codegraph fn-impact <fn> -T --json
codegraph query <fn> -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

codegraph roles --role core --file <f> -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 3 — Batch audit loop

For each pending batch (from titan-state.json):

3a. Save pre-batch snapshot

codegraph snapshot save titan-batch-<N>

Delete the previous batch snapshot if it exists:

codegraph snapshot delete titan-batch-<N-1>

3b. Collect all metrics in one call

codegraph batch complexity <target1> <target2> ... -T --json

This returns complexity + health metrics for all targets in one call. Parse the results.

For deeper context on high-risk targets:

codegraph batch context <target1> <target2> ... -T --json

3c. 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 <f> -T --json
• Check immutability (Rule 6): codegraph dataflow + grep

3d. 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

3e. 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

3f. 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

3g. 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:

codegraph fn-impact <target> -T --json

3h. Write batch results

Append to .codegraph/titan/gauntlet.ndjson (one line per target):

{"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."}

3i. 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

3j. 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 4 — Clean up batch snapshots

After all batches complete, delete the last batch snapshot:

codegraph snapshot delete titan-batch-<N>

Keep titan-baseline — GATE may need it.

If stopping early for context, keep the last batch snapshot for safety.

---

Step 5 — 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:

{
  "phase": "gauntlet",
  "timestamp": "<ISO 8601>",
  "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

---

Issue Tracking

Throughout this phase, if you encounter any of the following, append a JSON line to .codegraph/titan/issues.ndjson:

• Codegraph bugs: wrong metrics, incorrect role classification, missing symbols, parse failures
• Tooling issues: batch command failures, AST query errors, embedding unavailability
• Process suggestions: threshold adjustments, missing rules, pillar improvements
• Codebase observations: patterns not covered by the manifesto, architectural smells

Format (one JSON object per line, append-only):

{"phase": "gauntlet", "timestamp": "<ISO 8601>", "severity": "bug|limitation|suggestion", "category": "codegraph|tooling|process|codebase", "description": "<what happened>", "context": "<command, target, or file involved>"}

Log issues as they happen — don't batch them. The /titan-close phase compiles these into the final report.

---

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 <command> <targets> 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.
• If any command fails or produces unexpected output, log it to issues.ndjson before continuing.

Self-Improvement

This skill lives at .claude/skills/titan-gauntlet/SKILL.md. Adjust thresholds or rules after dogfooding.