optave/ops-codegraph-tool/titan-sync

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

1. Locate the Titan session. Prior phases (RECON, GAUNTLET) may have run in a different worktree or branch. Search for it:

``bash git worktree list ``

For each worktree, check if it contains Titan artifacts: ``bash ls <worktree-path>/.codegraph/titan/titan-state.json 2>/dev/null ``

Also check branches: ``bash git branch -a --list '*titan*' ``

Decision logic:

• Found exactly one worktree with `titan-state.json` and `currentPhase` is `"gauntlet"`: GAUNTLET completed — this is the right session. Merge its branch into your worktree.
• Found a worktree but `currentPhase` is not `"gauntlet"`: Suspicious — could be mid-phase or a different run. If currentPhase is "recon", GAUNTLET hasn't run yet. If "sync" or later, someone else may be ahead. Ask the user: "Found Titan state at <path> with phase <phase>. Is this the session to continue?"
• Found multiple worktrees with `titan-state.json`: List them with currentPhase and lastUpdated. Ask the user which to continue.
• Found a branch (not worktree) with titan artifacts: Merge it: git merge <titan-branch> --no-edit
• Found nothing: Stop: "No Titan artifacts found. Run /titan-recon then /titan-gauntlet first."

1. Ensure worktree isolation:

``bash git rev-parse --show-toplevel && git worktree list ` If not in a worktree, stop: "Run /worktree` first."

1. Sync with main:

``bash 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-sync`."

1. 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

1. Validate state. If titan-state.json fails to parse, stop: "State file corrupted. Run /titan-reset."

1. Check GAUNTLET completeness. If gauntlet-summary.json has "complete": false:

> "GAUNTLET incomplete (<N>/<M> batches). SYNC will plan based on known failures only. Run /titan-gauntlet first for a complete plan."

1. 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 — Drift detection: has main moved since GAUNTLET?

The codebase may have changed between GAUNTLET and now. Detect this before planning on stale audit data.

1. Compare main SHA:

``bash git rev-parse origin/main ` Compare against titan-state.json → mainSHA`. If identical, skip to Step 2.

1. If main has advanced, find what changed:

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

1. Cross-reference with GAUNTLET results. Check which changed files overlap with:

• Files that were audited (gauntlet.ndjson → file field)
• FAIL/DECOMPOSE targets (the ones SYNC plans around)
• Dead symbols targeted for removal

1. Classify staleness:

1. Append drift report to .codegraph/titan/drift-report.json (the file is a JSON array — read existing entries, push the new entry, write back; same schema as GAUNTLET, with "detectedBy": "sync").

1. Update state: Set titan-state.json → mainSHA to current origin/main.

1. If `moderate`: Proceed but annotate affected clusters in sync.json with "driftWarning": true. The execution order should prioritize non-stale targets and defer stale ones pending re-audit.

1. If re-running SYNC and a previous drift-report.json exists with reassessmentScope.targets, re-read GAUNTLET results only for those targets and rebuild affected clusters.

Step 2 — Find dependency clusters among failing targets

For FAIL/DECOMPOSE targets that share a file or community, check connections:

codegraph path <target1> <target2> -T --json

Group connected failures into clusters. Also check for cycles among them:

codegraph cycles --functions --json

Filter to cycles including at least one FAIL/DECOMPOSE target.

Step 3 — Identify shared dependencies and ownership

For each cluster, find what they share:

codegraph deps <key-file> --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:

codegraph owners <file1> <file2> -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:

codegraph branch-compare main HEAD -T --json

Avoid re-auditing or conflicting with in-progress work.

Step 4 — Detect extraction candidates

For DECOMPOSE targets:

codegraph context <target> -T --json
codegraph ast --kind call --file <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 5 — 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:

codegraph fn-impact <shared-dep> -T --json

Step 6 — Build execution order with logical commits

Phases (in order)

1. Dead code cleanup — zero risk, reduces noise

• Commit: chore: remove dead code

1. Shared abstractions — before individual fixes

• One commit per abstraction: refactor: extract X from Y

1. Cycle breaks — unblocks dependent targets

• One commit per break: refactor: break cycle between X and Y

1. Decompositions — highest risk, after abstractions

• One commit per decomposition: refactor: split X into A and B

1. Fail fixes — ordered by blast radius (lowest first)

• Group by domain: fix: address quality issues in <domain>

1. Warn improvements — optional, lowest priority

• Group by domain: refactor: address warnings in <domain>

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 7 — Write the SYNC artifact

Write .codegraph/titan/sync.json:

{
  "phase": "sync",
  "timestamp": "<ISO 8601>",
  "clusters": [
    {
      "id": 1,
      "name": "<descriptive>",
      "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": "<current location>",
      "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": ["<from recon>"],
  "cyclesInvolvingFailures": []
}

Update titan-state.json: set currentPhase to "sync".

Step 8 — 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

Issue Tracking

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

• Codegraph bugs: incorrect path queries, wrong cycle detection, relationship errors
• Tooling issues: artifact parsing failures, state inconsistencies
• Process suggestions: better clustering strategies, execution order improvements
• Codebase observations: cross-cutting concerns not captured by GAUNTLET

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

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

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

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

Self-Improvement

This skill lives at .claude/skills/titan-sync/SKILL.md. Edit if clustering misses connections or execution order causes conflicts.