Skip to content

t1k:doctor

FieldValue
Modulet1k-base
Version5.15.36
Effortmedium
Tools—

Keywords: broken, check, diagnose, health, integrity, registry, validate

/t1k:doctor
[fix]

Validates that all registry fragments, skills, and manifest are consistent and coherent.

/t1k:doctor # Read-only validation report
/t1k:doctor fix # Attempt to fix detected issues
/t1k:doctor --ci # CI mode: run all checks, exit code 1 on any fail, GitHub annotations

Live Registry State (fetch on demand — do NOT inline in body)

Section titled “Live Registry State (fetch on demand — do NOT inline in body)”

When running checks, fetch live registry state via tool calls AFTER the skill body is loaded — NEVER embed inline shell-substitution tokens (the !-prefix-then-backtick syntax) here (cache-busts the cached prefix on every fragment edit; doctor runs constantly during dev). Use:

  • Read each .claude/t1k-routing-*.json matching glob → routing fragments
  • Read each .claude/t1k-activation-*.json matching glob → activation fragments
  • Read .claude/metadata.json → kit + module metadata
  • Glob .claude/agents/*.md then Read each → agent files
  • Glob .claude/skills/*/SKILL.md then Read each → skill files

If a glob returns no matches, treat as “no entries” — do not echo error.

Run all checks in sequence. Full check list: references/checks.md

  • Core checks (#1–6): Role coverage, skill existence, cross-layer hardcoding, manifest, registry version, config completeness

  • Module checks (#7–17): File ownership, dependency integrity, activation match, agent presence, routing overlays, stale files, origin frontmatter

  • Manifest checks (#21): Per-module manifest integrity, orphaned flat files

  • SSOT checks (#22–27): schemaVersion, version presence, no stale modules/, context requiredPaths, activation format, v3 installedModules

  • No-override checks (#28–29): Filename collision detection, agent prefix correctness. detail (references/check-groups.md)

  • Frontmatter quality (#18–20): Agent turn cap absence (#18 — maxTurns retired), skill effort, agent model appropriateness

  • Cross-platform (#30): Hook files free of shell-only patterns (2>/dev/null, /dev/stdin, execSync shell strings)

  • MCP health (#31): Required MCPs connected, recommended MCPs present. detail (references/check-groups.md)

  • Sync-back health (#32): Recent sync-back PRs are healthy (no CONFLICTING state, no phantom-file diffs)

  • Kits membership SSOT (#33): Object.keys(metadata.kits) === unique(installedModules[*].kit) — runs scripts/check-kits-membership.cjs to catch drift between the derived kit membership and the source installedModules. WARN level on mismatch.

  • Orphaned agents (#34): Agent files under .claude/agents/ whose origin: frontmatter points to a kit no longer in installedModules[*].kit (or metadata.kits on older schemas) — leftovers from pre-manifest installs. detail (references/check-groups.md)

  • CLAUDE.md bloat (#35): Project CLAUDE.md exceeds 5k token budget (char/4 heuristic). Runs scripts/check-claude-md-bloat.cjs. WARN level; fix: move details to docs/ + deduplicate with auto-loaded rules/*.md.

  • Rule duplication (#36): Same rule filename present in both ~/.claude/rules/ and project .claude/rules/ (double-loaded, wastes context). detail (references/check-groups.md)

  • Context budget (#37): Sums token estimates for all .claude/rules/*.md + project CLAUDE.md. detail (references/check-groups.md)

  • Always-loaded union (#59): The check that measures the launch-loaded union in TOKENS and attributes it per kit — the UNION of the always-loaded set across BOTH scopes (~/.claude/ and the project .claude/), for … detail (references/check-groups.md)

  • Oversized rules (#38): Per-file check — any .claude/rules/*.md exceeding 5 000 tokens (char/4 heuristic) gets a WARN. detail (references/check-groups.md)

  • Modules registry sync (#39): .claude/t1k-modules.json modules field must match the projection of every .claude/modules/*/module.json (description, required, dependencies, skills, activationFragment). detail (references/check-groups.md)

  • Module detect coverage (#41): Every non-core module in .claude/modules/ (excluding the frozen t1k-base/t1k-extended/t1k-maintainer set and any required: true kit-base module) must carry an active detect: block, … detail (references/check-groups.md)

  • Statusline wiring (#42): Validates the T1K statusline is wired end-to-end: detail (references/check-groups.md)

  • No inlined universal rules (#44): SKILL.md files must not inline the 3 boilerplate blocks that auto-load from .claude/rules/ (skill-security, AI-Driven Design, fork-hygiene 5-line). detail (references/check-groups.md)

  • Auto-pipelines GitHub MCP prereq (#46): When features.autoIssueSubmission or features.autoLessonSync is ON, correlates that with the GitHub MCP’s presence — a missing/unauthenticated github MCP means the … detail (references/check-groups.md)

  • Activation skill resolution (#47): Every skill ref in every activation fragment’s sessionBaseline[] and mappings[].skills[] must name a skill directory that exists — in EITHER scope, since a session loads skills from … detail (references/check-groups.md)

  • Global install core-only (#48): $HOME/.claude/metadata.json should contain ONLY core under .kits. detail (references/check-groups.md)

  • Multimodal setup (#49): When t1k-extended is installed AND skills/t1k-extended-multimodal/SKILL.md is present: validates GEMINI_API_KEY (WARN), MINIMAX_API_KEY (WARN, optional), python3 ≥ 3.10 (FAIL), and … detail (references/check-groups.md)

  • Stale-backup folders inside auto-scanned dirs (#50): Detects quarantine subdirectories (.stale-backup-*, .zombies-*, .backup-*, .archive-*, .old, .deprecated, .trash) sitting INSIDE Claude Code’s auto-scanned … detail (references/check-groups.md)

  • Agent budget calibration (#51): Scans .claude/agents/*.md for budget-checkpoint calibration per … detail (references/check-groups.md)

  • Hook registration drift (#52): Compares installed enforcement hook scripts with their required event + matcher registrations in settings.json. detail (references/check-groups.md)

  • Agent routing reachability (#53): Every agent .md under .claude/agents/ must be reachable by the data-driven routing index (hooks/lib/agent-routing-index.cjs) that generic-agent-detector consults — an agent … detail (references/check-groups.md)

  • Agent MCP tool-grant drift (#54): Reconciles mcp__<server>__<tool> grants in every agent’s tools: frontmatter against the servedTools manifest declared for that server in t1k-config-*.json. detail (references/check-groups.md)

  • Kit file drift (#55): Compares project-local .claude/ against the global install and reports four states: modules BEHIND the global version, kit executables MISSING locally, executables that DIFFER and are BEHIND (local is … detail (references/check-groups.md)

  • Dead permission rules (#56): Flags permissions.{allow,deny,ask} entries whose tool name Claude Code’s file-permission matcher never consults — Write(path), MultiEdit(path), NotebookEdit(path) (use Edit(path)) and … detail (references/check-groups.md)

  • Global bootstrap state (#57): Reports what the silent global-bootstrap did on this machine, read back from its sentinel <realHome>/.t1k/global-bootstrap.json. detail (references/check-groups.md)

  • Kit install scope (#58): Reports kits installed in BOTH scopes at once. detail (references/check-groups.md)

  • Local core shadow (#77): Reports global-scope kit (core) content under a PROJECT-LOCAL .claude/ shadowing its global twin — the exact mirror of #48, and the case metadata.json is blind to. detail (references/check-groups.md)

  • Markdown link integrity (#60): Relative markdown links inside .claude/ whose target exists in neither the on-disk layout nor the FLATTENED namespace a consumer holds (flatten-module-files.cjs collapses … detail (references/check-groups.md)

  • Skill reference citations (#61): A SKILL.md naming its own references/<file> must ship that file. detail (references/check-groups.md)

  • Orphan reference files (#62): references/**.md that nothing anywhere under .claude/ cites. detail (references/check-groups.md)

  • Unused local modules — engine mismatch (#63): A locally installed kit whose own context.requiredPaths are absent from the project (e.g. unity with no Assets//ProjectSettings/). detail (references/check-groups.md)

  • Uninstall integrity (#64): A stale interrupted-uninstall journal (FAIL, idempotent re-run remedy — an in-flight uninstall reports INFO instead) and unacknowledged auto-removal ledger entries (WARN, with a situation-correct … detail (references/check-groups.md)

  • Install-ledger drift (#65): Content under .claude/ the install ledger does not account for — a kit-shipped file absent from metadata.kits[].files[] (unupdatable AND unprunable), a modules/<name>/ the owning kit no … detail (references/check-groups.md)

  • DOTS project fitness (#66): Unused theonekit-unity dots-* modules (dots-core, dots-ai, dots-combat, dots-inventory, dots-nav, dots-rendering, dots-testing) — installed but no DOTS/ECS evidence anywhere in the project (no … detail (references/check-groups.md)

  • Session-memory graph integrity (#67): Session memory IS a graph and was never validated as one — memory files are nodes (identity = frontmatter name:, class = metadata.type), [[wikilinks]] are edges, MEMORY.md is the … detail (references/check-groups.md)

  • Inheritance integrity (#68): When metadata.json contains inheritsFrom, validates the parent .claude/ path is well-formed: exists, is a directory, ends in .claude, contains a valid T1K metadata.json, is not a … detail (references/check-groups.md)

  • Rule citation graph (#69): The always-loaded rule corpus modelled as a GRAPH — each rule a node, each rule-name.md it cites an edge. detail (references/check-groups.md)

  • Phantom kits (#71): Iterates metadata.kits entries and warns on any where files is undefined or an empty array. detail (references/check-groups.md)

  • Plaintext reference mentions (#74): Closes the gap #60/#61 both PASS through — a plain-text references/<name>.md mention in an HTML comment, other prose, or a .cjs/.mjs string literal, where neither markdown-link … detail (references/check-groups.md)

  • StatusLine outdated form (#75): t1k modules update never upgrades an EXISTING statusLine.command (core#1396) — only backfillStatusLine, scoped to an ABSENT key, ever writes it, so an install whose t1k init predates … detail (references/check-groups.md)

  • Unreachable kit fragment (#76): a kit-root t1k-activation-<suffix>.json that NO refresh path reaches, so its content freezes at install time (core#1385). detail (references/check-groups.md)

  • Engine-bridge stale install (#78): A commit dropped t1k-engine-bridge from core’s full/developer/maintainer presets (#1427 Step 1), but t1k modules update never prunes a module that left a preset (#1085) — so an … detail (references/check-groups.md)

  • Cross-kit dependency (#80): an installed module declares a cross-kit "<kit>:<module>": "<range>" dependency that is not installed, or is installed outside the range. detail (references/check-groups.md)

  • Artifact readers (#81): Enforces hooks/lib/artifact-contract.cjs’s reader-registry contract for cross-reader artifacts (schema’d JSON written by one agent/hook/skill, read by a different one; graph-engineering sprint item … detail (references/check-groups.md)

  • StatusLine refresh interval (#82): statusLine.refreshInterval missing means the line goes silently FROZEN for the whole duration of any blocking hook — Claude Code re-runs statusLine only on event-driven triggers (new … detail (references/check-groups.md)

  • Orphan skill directories (#83): directories under .claude/skills/ with no SKILL.md — kit-release residue. Runs .claude/hooks/doctor-check-83-orphan-skill-directories.cjs. WARN, report-only, no --fix. See references/checks.md #83.

  • Skill-list autoload bytes (#84): the consumer-machine measurement half of the skill-list-cost program — model-invocable skill-list bytes (name:+description:, dual-scope), duplicate installs across scopes, skills with no … detail (references/check-groups.md)

  • claude CLI version vs omitClaudeMd agents (#85): WARNs when the installed claude --version is below 2.1.271 (the version that started honoring an agent’s omitClaudeMd: true frontmatter key) AND at least one … detail (references/check-groups.md)

  • Consumer instruction total (#86): owns the launch-set enumeration for the whole kit — sums the launch-loaded instruction set for the current project and compares it to Claude Code’s own 150,000-character limit, the … detail (references/check-groups.md)

  • Stale kit rules (#88): a THIN FILTER over check #65’s exported computeInstallLedgerDrift() — reports exactly the subset of #65’s own retired-upstream findings (already minus anything a surviving SKILL.md cites) whose … detail (references/check-groups.md)

  • Claude Code mods (#89): the t1k-meter mod is in the RUNTIME path (<claudeDir>/skills/t1k-meter/ with SKILL.md, plugin.json, hooks.json, register.ts, mod-pin.json) and compatible with claude --version: CLI below minVersion SKIPs (mods inert, classic hooks cover), a file missing or broken on a CLI that loads mods FAILs, a CLI more than one minor past testedVersion WARNs. Report-only, no --fix. … detail (references/checks.md)

  • MCP demand (#90, optional module t1k-mcp): WARN-level hint (never FAIL) when mcp-demand.cjs finds an allowlisted per-session stdio MCP server registered in a project that never called it in the last 14 days (with enough interactive sessions to say so). Counts only, report-only, nothing applied; a partial scan SKIPs. … detail (references/checks.md)

  • MCP registration ownership (#91): WARN-level hint (never FAIL) naming each registered MCP server (~/.claude.json user + per-project, project .mcp.json) that NO installed kit declares in mcp.required|recommended|optional — a leftover of a removed kit or one you added yourself; names only, nothing unregistered; an install declaring none is UNKNOWN. … detail (references/checks.md)

  • Unity CLI health (#92): inside a Unity project, delegates to the unity kit facade t1k-unity.cjs doctor (resolved from the .claude that loaded the check, then global; never an unrelated repo copy): ok PASS, exit 4/12 FAIL with the envelope fix, other errors WARN; facade absent or unusable output SKIPs, never a default PASS. No Unity logic here. … detail (references/checks.md)

  • Removed Unity editor MCP leftovers (#93): FAIL (one prefilled command per finding, never edits) when the removed server is still registered, named in settings or Packages/manifest.json, or left as stale kit copies. … detail (references/checks.md)

  • cf pin freshness (#94): WARN (never FAIL for upstream drift) when the pinned cf version is behind npm; a missing or malformed pin marker is FAIL; npm unreachable is WARN, never PASS. … detail (references/checks.md)

  • Module required binaries (#95): WARN-level (never FAIL, never installs) when an INSTALLED module declares requires.binaries and one is not runnable; the install hint is printed as data, never executed; nothing declared SKIPs. … detail (references/checks.md)

  • Vault access (#96): FAIL (exit 1, names the fix) when no accepted GitHub token is found, secrets.the1studio.org is unreachable, or t1k vault list errors; PASS only when all three hold; never prints a secret. … detail (references/checks.md)

  • cf-only config (#97): FAIL when the cf-only-guard hook is installed but the resolved cfOnly block is missing or empty; WARN when a coverage list is absent; SKIP when the hook is not installed. … detail (references/checks.md)

  • Routing role resolution (#98): FAIL when a merged routing role names an agent absent from both scopes. … detail (references/checks.md)

  • Registry auth (#99): FAIL (exit 1, names bun <path>/registry-auth-sync.cjs --force) when an enabled UPM/CPM registry’s stored token is absent, expired, or rejected by GET /-/whoami; UNKNOWN (exit 0) when the host is unreachable; PASS only on a 200 with a username; SKIP when none is enabled. … detail (references/checks.md)

  • Hook health (#101): FAIL (exit 1, read-only, names the settings entry) when a per-hook entry shadows a batch entry that already runs the hook (it executes twice per PreToolUse call), identical entries repeat, or a gateway-migrated tool starts more launchers than gateway[] + 2; pure per-hook installs PASS. … detail (references/checks.md)

  • Scratch hygiene (#103): FAIL when the installed scratch-hygiene / scratch-write-guard hook is absent or unwired, a lib is missing, the scratch root is unusable, or the reaper is stuck; WARN on RAM-backed root or pressure. Read-only. detail (references/checks.md)

  • Worktree roots (#104): runs the installed worktree-root-census.cjs; FAIL only when it is missing, UNKNOWN when it cannot run, WARN on dangling gitdirs or clutter. Read-only. detail (references/checks.md)

  • Shared-content copies (#105): when theonekit-gamedev is installed, runs the installed scripts/shared-content-check.cjs against the installed shared-content-index.json; FAIL per copy of gamedev-owned content, naming the file to remove and the module to depend on; N/A when gamedev is absent. Read-only. detail (references/checks.md)

  • Submodule heads (#106): FAIL when a submodule’s detached HEAD holds commits no remote branch reaches, or the installed guard/lib is missing or unwired; WARN on uncommitted edits there or an unfetchable pointer. A clean detached checkout is a PASS. Read-only. detail (references/checks.md)

  • Retired manifest claims (#108): WARN, report-only — a manifest entry no module ships, still on disk (#4754); prints the rm. detail (references/checks.md)

  • Scope remediation: the background agent features.contextBloatGuard dispatches on a duplication-over-threshold session — reads checks #55/#58/#63 findings, refuses far more than it acts, and when it does remove a kit, backs … detail (references/check-groups.md)

  • Doctor-sweep report lifecycle (core#1526): doctor-sweep-reminder.cjs dispatches t1k-doctor-manager with a message naming <claudeDir>/session-state/doctor-sweep-report.json when the daily sweep has attention findings. When dispatched this way, t1k-doctor-manager MUST mark the report consumed by writing the sentinel <path>.consumed (never rm). detail (references/check-groups.md)

  • A #55 sweep row is not a verdict until it is re-run online: check #55’s offline path is a deliberate SKIP — on a global-only install (the shape the scope policy mandates for core) it prints SKIP … 0 claimed file(s) … were NOT compared to any reference (unverified, not clean), exit 0. Re-running the same target with T1K_DOCTOR_ONLINE=1 compares the claimed files[] against the tag metadata.json names and commonly FAILs on an install reading t1k --version as up to date (measured: offline status=skip hashed=0, online behind=14 diverged=94). Offline, BEHIND (t1k modules update) and DIVERGED-AHEAD (/t1k:sync-back FIRST) are indistinguishable, so reporting a row’s direction from an offline run hands the reader the wrong remedy. t1k-doctor-manager owes the --online re-run before it reports a #55 row; the sweep itself opts in with its own --online flag (core#6392), and a declined comparison now reaches attentionChecks rather than dying as ok. detail (references/check-groups.md)

  • manifestMismatches rows are self-sufficient (core#2682): each row names the module, the .t1k-manifest.json path to regenerate, and — per stale category — the category, its TRUE entry count, up to five of the unresolvable … detail (references/check-groups.md)

See references/frontmatter-recommendations.md for recommended values and output format.

When invoked as /t1k:doctor --ci, the doctor runs in non-interactive CI mode:

  • Runs all checks from the standard check list plus the Tier 2 eval registry checks
  • Emits GitHub Actions workflow annotations (::error file=...:: format) for each failure
  • Writes a machine-readable summary to .claude/telemetry/doctor-ci-{date}.json
  • Exits with code 1 if ANY check fails (suitable as a blocking CI gate)
  • Exits with code 0 only if all checks pass
  • Completes in < 60s on theonekit-core

The eight checks in CI mode, with their token cost and gating, are tabulated in references/ci-mode.md § “Check Sequence (ordered, fast-first)” — that table is the SSOT; it is not repeated here.

See references/ci-mode.md for full spec and GitHub Actions workflow snippet.

Only deterministic fixes: regenerate .t1k-manifest.json, detect orphaned/stale files, report what needs manual attention. Full details: references/fix-mode.md

## Doctor Report — {date}
### Checks
- Role coverage: [PASS | FAIL — missing agent for role X]
- Skill existence: [PASS | FAIL — missing skill: Y]
...
### Issues Found
- [issue description + file + line]
### Recommended Fixes
- [action]

Registry validation and manifest repair only.

Runs in t1k-doctor-manager (or inline). The scripts/check-*.cjs registry checks are deterministic; interpreting a WARN/FAIL and choosing the fix stays reasoning-tier.

StepAgent
Run the scripts/check-*.cjs checks and collect their outputt1k-doctor-manager
Interpret failures and propose the fixt1k-doctor-manager