t1k:doctor
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | medium |
| Tools | — |
Keywords: broken, check, diagnose, health, integrity, registry, validate
How to invoke
Section titled “How to invoke”/t1k:doctor[fix]TheOneKit Doctor — Registry Validation
Section titled “TheOneKit Doctor — Registry Validation”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 annotationsLive 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:
Readeach.claude/t1k-routing-*.jsonmatching glob → routing fragmentsReadeach.claude/t1k-activation-*.jsonmatching glob → activation fragmentsRead .claude/metadata.json→ kit + module metadataGlob .claude/agents/*.mdthenReadeach → agent filesGlob .claude/skills/*/SKILL.mdthenReadeach → skill files
If a glob returns no matches, treat as “no entries” — do not echo error.
Check Groups
Section titled “Check Groups”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 —
maxTurnsretired), 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)— runsscripts/check-kits-membership.cjsto catch drift between the derived kit membership and the sourceinstalledModules. WARN level on mismatch. -
Orphaned agents (#34): Agent files under
.claude/agents/whoseorigin:frontmatter points to a kit no longer ininstalledModules[*].kit(ormetadata.kitson older schemas) — leftovers from pre-manifest installs. detail (references/check-groups.md) -
CLAUDE.md bloat (#35): Project
CLAUDE.mdexceeds 5k token budget (char/4 heuristic). Runsscripts/check-claude-md-bloat.cjs. WARN level; fix: move details todocs/+ deduplicate with auto-loadedrules/*.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+ projectCLAUDE.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/*.mdexceeding 5 000 tokens (char/4 heuristic) gets a WARN. detail (references/check-groups.md) -
Modules registry sync (#39):
.claude/t1k-modules.jsonmodulesfield 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 frozent1k-base/t1k-extended/t1k-maintainerset and anyrequired: truekit-base module) must carry an activedetect: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.autoIssueSubmissionorfeatures.autoLessonSyncis ON, correlates that with the GitHub MCP’s presence — a missing/unauthenticatedgithubMCP means the … detail (references/check-groups.md) -
Activation skill resolution (#47): Every skill ref in every activation fragment’s
sessionBaseline[]andmappings[].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.jsonshould contain ONLYcoreunder.kits. detail (references/check-groups.md) -
Multimodal setup (#49): When
t1k-extendedis installed ANDskills/t1k-extended-multimodal/SKILL.mdis 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/*.mdfor 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
.mdunder.claude/agents/must be reachable by the data-driven routing index (hooks/lib/agent-routing-index.cjs) thatgeneric-agent-detectorconsults — an agent … detail (references/check-groups.md) -
Agent MCP tool-grant drift (#54): Reconciles
mcp__<server>__<tool>grants in every agent’stools:frontmatter against theservedToolsmanifest declared for that server int1k-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)(useEdit(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.cjscollapses … 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/**.mdthat nothing anywhere under.claude/cites. detail (references/check-groups.md) -
Unused local modules — engine mismatch (#63): A locally installed kit whose own
context.requiredPathsare absent from the project (e.g. unity with noAssets//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 frommetadata.kits[].files[](unupdatable AND unprunable), amodules/<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.mdis the … detail (references/check-groups.md) -
Inheritance integrity (#68): When
metadata.jsoncontainsinheritsFrom, validates the parent.claude/path is well-formed: exists, is a directory, ends in.claude, contains a valid T1Kmetadata.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.mdit cites an edge. detail (references/check-groups.md) -
Phantom kits (#71): Iterates
metadata.kitsentries and warns on any wherefilesisundefinedor 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>.mdmention in an HTML comment, other prose, or a.cjs/.mjsstring literal, where neither markdown-link … detail (references/check-groups.md) -
StatusLine outdated form (#75):
t1k modules updatenever upgrades an EXISTINGstatusLine.command(core#1396) — onlybackfillStatusLine, scoped to an ABSENT key, ever writes it, so an install whoset1k initpredates … detail (references/check-groups.md) -
Unreachable kit fragment (#76): a kit-root
t1k-activation-<suffix>.jsonthat 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-bridgefrom core’sfull/developer/maintainerpresets (#1427 Step 1), butt1k modules updatenever 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.refreshIntervalmissing means the line goes silently FROZEN for the whole duration of any blocking hook — Claude Code re-runsstatusLineonly on event-driven triggers (new … detail (references/check-groups.md) -
Orphan skill directories (#83): directories under
.claude/skills/with noSKILL.md— kit-release residue. Runs.claude/hooks/doctor-check-83-orphan-skill-directories.cjs. WARN, report-only, no--fix. Seereferences/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) -
claudeCLI version vsomitClaudeMdagents (#85): WARNs when the installedclaude --versionis below2.1.271(the version that started honoring an agent’somitClaudeMd: truefrontmatter 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 ownretired-upstreamfindings (already minus anything a survivingSKILL.mdcites) whose … detail (references/check-groups.md) -
Claude Code mods (#89): the
t1k-metermod is in the RUNTIME path (<claudeDir>/skills/t1k-meter/with SKILL.md, plugin.json, hooks.json, register.ts, mod-pin.json) and compatible withclaude --version: CLI belowminVersionSKIPs (mods inert, classic hooks cover), a file missing or broken on a CLI that loads mods FAILs, a CLI more than one minor pasttestedVersionWARNs. Report-only, no--fix. … detail (references/checks.md) -
MCP demand (#90, optional module
t1k-mcp): WARN-level hint (never FAIL) whenmcp-demand.cjsfinds 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.jsonuser + per-project, project.mcp.json) that NO installed kit declares inmcp.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.claudethat loaded the check, then global; never an unrelated repo copy): ok PASS, exit 4/12 FAIL with the envelopefix, 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
cfversion 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.binariesand 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.orgis unreachable, ort1k vault listerrors; PASS only when all three hold; never prints a secret. … detail (references/checks.md) -
cf-only config (#97): FAIL when the
cf-only-guardhook is installed but the resolvedcfOnlyblock 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 byGET /-/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-guardhook 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-gamedevis installed, runs the installedscripts/shared-content-check.cjsagainst the installedshared-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.contextBloatGuarddispatches 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.cjsdispatchest1k-doctor-managerwith a message naming<claudeDir>/session-state/doctor-sweep-report.jsonwhen the daily sweep has attention findings. When dispatched this way,t1k-doctor-managerMUST mark the report consumed by writing the sentinel<path>.consumed(neverrm). 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 printsSKIP … 0 claimed file(s) … were NOT compared to any reference (unverified, not clean), exit 0. Re-running the same target withT1K_DOCTOR_ONLINE=1compares the claimedfiles[]against the tagmetadata.jsonnames and commonly FAILs on an install readingt1k --versionas up to date (measured: offlinestatus=skip hashed=0, onlinebehind=14 diverged=94). Offline, BEHIND (t1k modules update) and DIVERGED-AHEAD (/t1k:sync-backFIRST) are indistinguishable, so reporting a row’s direction from an offline run hands the reader the wrong remedy.t1k-doctor-managerowes the--onlinere-run before it reports a #55 row; the sweep itself opts in with its own--onlineflag (core#6392), and a declined comparison now reachesattentionChecksrather than dying asok. detail (references/check-groups.md) -
manifestMismatchesrows are self-sufficient (core#2682): each row names the module, the.t1k-manifest.jsonpath 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.
CI Mode (--ci flag)
Section titled “CI Mode (--ci flag)”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.
Auto-Healing (fix mode)
Section titled “Auto-Healing (fix mode)”Only deterministic fixes: regenerate .t1k-manifest.json, detect orphaned/stale files, report what needs manual attention. Full details: references/fix-mode.md
Output Format
Section titled “Output Format”## 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.
Executed by
Section titled “Executed by”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.
| Step | Agent |
|---|---|
Run the scripts/check-*.cjs checks and collect their output | t1k-doctor-manager |
| Interpret failures and propose the fix | t1k-doctor-manager |