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

1. Worktree check:

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

   If not in a worktree, stop: "Run /worktree first."

2. 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."

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)

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.

Note: requires embeddings from /titan-recon. If titan-state.json → embeddingsAvailable is false, skip semantic search and note it.

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 2 — Batch audit loop

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

2a. 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>

2b. 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

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 <f> -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:

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

2h. 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."}

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:

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 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:

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

---

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.

Self-Improvement

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