spec: ClaudeTools harness optimization (3-way reviewed)

Optimize the harness (not projects) for accuracy/completeness with context pressure
as a first-class constraint; token efficiency secondary. Authored as a Claude+Grok+
Gemini review (see review-3way.md): P0 reliability footguns (submodule-safe sync,
serialized/staged wiki synthesis, syncro SSOT, warn-only guard), P1 context diet
(one-line registry descriptions, CLAUDE CORE/EXTENDED, thin save/sync), P2 delegation
re-tune, P3 knowledge tiering. Adds harness VERSION marker + OOB recovery as rollout
safety. Python port split to a separate future spec.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

specs/claudetools-harness-optimization/references.md

@@ -0,0 +1,56 @@
+# ClaudeTools Harness Optimization — Code References
+
+Harness files (the ClaudeTools repo `.claude/` + root), with their role and current cost.
+
+## Always / repeatedly in context (the diet targets)
+- `.claude/CLAUDE.md` — 351 lines / ~4.9k tokens. Injected every session; observed
+  re-injected mid-session as a full system-reminder. -> Task 6 (CORE/EXTENDED split).
+- Skill/command REGISTRY — each `.claude/skills/*/SKILL.md` `description:` frontmatter +
+  each `.claude/commands/*.md` description. The full list injects repeatedly (~4x in one
+  session). Paragraph-length offenders: rmm-audit (669 ln), gc-audit (669), b2 (261),
+  bitdefender, packetdial, mailprotector. -> Task 5 (one-line descriptions).
+- `.claude/memory/MEMORY.md` — 114 lines, auto-loaded each session. -> Task 10.
+
+## Injected on invoke (command bodies)
+- `.claude/commands/syncro.md` — 1139 lines. -> Task 8 (shard) + Task 3 (SSOT vs standard).
+- `.claude/commands/rmm.md` — 783 lines. -> Task 8.
+- `.claude/commands/save.md`, `.claude/commands/sync.md` — multi-K bodies injected every
+  use. -> Task 7 (thin wrappers).
+
+## Workflow / write-safety
+- `.claude/scripts/sync.sh` — `git add -A` auto-commit + rebase + push + deploy
+  commands/skills to global + vault sync. The `git add -A` + submodule = the gitlink
+  footgun. Phase 5b (commands->global) + the new Phase 5c (skills->global, added
+  2026-06-08). -> Task 1, Task 4, Task 11.
+- `/save` flow — writes a session log, then a Sonnet wiki recompile, then `sync.sh`. The
+  inline recompile is the 3-way-conflict source. -> Task 2.
+- `.claude/commands/wiki-compile.md` (403 ln) — full re-synthesis; should merge + lock.
+  -> Task 2.
+- The git submodule: `projects/msp-tools/guru-rmm` (and `guru-connect`). Parent pins a
+  commit that intentionally lags `main`. -> Task 1.
+
+## Standards / source-of-truth
+- `.claude/standards/` (19 files, ~12k tokens, on-demand) + `index.yml`. The
+  `syncro/time-entry-protocol.md` vs `commands/syncro.md` contradiction. -> Task 3.
+
+## Hooks
+- `.claude/settings.json` hooks: PreToolUse, SessionStart, UserPromptSubmit.
+  `.claude/hooks/` (3 entries, incl. `block-backslash-winpath.sh`). -> Task 4
+  (pre-commit guard), Task 12 (SessionStart smoke checks).
+
+## Knowledge layers
+- `wiki/` — 57 articles, compiled from session logs (the synthesized layer).
+- `session-logs/` — 283 logs (write-only archive). -> Task 10 (INDEX).
+- `.claude/memory/` — 97 files + MEMORY.md. `memory-dream` skill lints/dedupes. -> Task 10.
+
+## Cross-OS fragility (Task 11 targets)
+- `TZ=America/Phoenix date` silently returns UTC on Git Bash (mis-dates logs).
+- `.claude/scripts/post-bot-alert.sh` — 400s on em-dash/`$` (no JSON escaping).
+- `/tmp` resolves differently in the Write tool vs Git Bash (documented; heredocs used).
+- The skills-deploy gap (global `~/.claude/skills` was empty until Phase 5c).
+
+## Existing tooling to lean on
+- `coord` skill / API — inter-session locks + broadcast (use for serialized wiki writes,
+  fleet rollout announcements).
+- `self-check` skill — harness conformance; extend with smoke tests (Task 12).
+- `memory-dream` skill — memory dedupe/lint (Task 10).