Judgment in Markdown, determinism in Python.
The repo's own design splits the two files by what each is good at: sync.md holds judgment, lib/context-audit.py holds determinism.
sync.md is a YAML-frontmatter-plus-Markdown Claude Code slash command scoped to the Read, Write, Edit, Bash, Grep, and Glob tools. On invocation it runs a hard guard, refusing at $HOME, root, or any directory with no project signal, then detects mode by filesystem signals: .git or a manifest file means project mode, SOUL.md plus HEARTBEAT.md plus a daily/ directory means vault mode, being the parent of multiple vaults means orchestrator mode. In project mode only, it calls lib/context-audit.py --project <cwd> as Step 1c, ahead of its own read, classify, and write pass.
The helper's classification is entirely config-driven: one file, lib/context-audit.config.json (23 lines, 9 top-level keys), sets the token-weight constants and the tool and domain signatures that decide whether an MCP server reads as used, unused, or uncertain. The same server can land on opposite verdicts on two different projects; jcodemunch classifies as kept on a code project and flagged on a docs vault under identical global scope, because the config's value-earning signatures match code-project signals and not vault ones. Action tier is a separate axis from verdict, and it is narrow by construction: a server can only become auto-safe if it is scoped to the current project's own .mcp.json, because only a project's local .claude/settings.json can add to disabledMcpjsonServers without touching anything global. Everything scoped globally or at the user level is recommend-only, printed as a claude mcp remove command for a human to run. install.sh (14 lines) is the only thing that writes outside the project: it copies sync.md and the lib/ folder into ~/.claude/commands/.
Every figure here traces to a command output or a file path.
Compiled 2026-08-03 from 24 commits spanning 2026-05-29 to 2026-06-26.
| Metric | Value | Evidence |
|---|---|---|
| Commit count | 24 | git log --oneline | wc -l |
| First commit | 2026-05-29 | "Add design spec for /sync context-audit pre-run" |
| Last commit | 2026-06-26 | "feat: make Second_Brain dispatch path configurable + document it" |
| Commit distribution | 16 / 8 | 16 commits on 2026-05-29, 8 on 2026-06-26, two sessions 28 days apart |
| Merge commits | 1 | "Merge feat/context-audit: /sync context-audit pre-run" (175f961) |
| Authors | 2 identities, 1 person | Rainier <info@singlesource.co.za>, Rainier Potgieter <rain.singlesource@gmail.com> |
| Git tags / releases | 0 | git tag returns empty |
| Python LOC | 615 | lib/context-audit.py 327, lib/__init__.py 0, tests/test_context_audit.py 288 |
| Test functions | 34 | grep -c '^def test_' tests/test_context_audit.py, no .venv present so counted by inspection |
| Test-count discrepancy | 29 vs 34 | README.md and docs/how-sync-works.md badge/state 29 tests; the file on disk has 34 |
| Markdown LOC | 1,997 | 7 files, tracked and untracked, excluding .pytest_cache |
| Config JSON LOC | 23 | lib/context-audit.config.json |
| Shell LOC | 14 | install.sh |
| CI workflow YAML LOC | 63 | 2 files: pylint.yml, python-package.yml |
| SVG diagram assets | 3 files, 274 lines | docs/assets/hero-modes.svg, sync-pass.svg, context-audit.svg |
| Git-tracked files | 16 | git ls-files | wc -l |
| Untracked-but-present files | .claude/commands/install-verify.md + docs/superpowers/ | excluded from git by .gitignore (docs/* with two exceptions) |
| Working tree at compile time | 1 uncommitted diff | CLAUDE.md has a 10-line uncommitted addition per git diff --stat |
| CI matrix | 2 workflows, 5 version combos | Pylint on Python 3.8/3.9/3.10; python-package on 3.9/3.10/3.11 with flake8 + pytest |
| Published packages | 0 | no package.json, pyproject.toml, setup.py, or Cargo.toml in the repo |
| Deploy targets / live URLs | 0 | no Dockerfile, no hosting config, no URL strings referencing a deploy target |
| CLI surface | 1 slash command, 1 helper CLI, 1 project command | /sync; context-audit.py with 4 flags; /install-verify (untracked) |
| Config tuning surface | 1 file, 9 keys | lib/context-audit.config.json |
A discover, estimate, classify, report pipeline with no classes.
Two cooperating pieces, split by the repo's own stated design: judgment in sync.md, determinism in lib/context-audit.py.
sync.md
orchestrationRuns the hard guard, detects mode, and in project mode calls lib/context-audit.py --project <cwd> as Step 1c ahead of its existing read, classify, write pipeline. Scoped to Read, Write, Edit, Bash, Grep, Glob.
lib/context-audit.py
discover → estimate → classify → reportdetect_project_type (lines 53-70) inspects manifests, SOUL.md, and a file-extension ratio. detect_project_signals (79-102) builds a set of dep:/file:/dir:/gitremote: tokens from package.json, requirements.txt/pyproject.toml, the directory listing, and .git/config. discover_mcp_servers (116-132) and dedupe_servers (134-140) read ~/.claude.json and project .mcp.json, ranking scope as global < project-user < project-mcpjson. discover_plugins/discover_hooks (156-172) read the three settings files (global, project, project-local). measure_memory (174-182) sizes files under ~/.claude/projects/<slug>/memory/. classify_server (210-227) and _classify_memory (229-246) apply the config-driven rules; build_report (268-290) assembles the final JSON, sorted by estimated token weight descending. resolve_second_brain (248-266) resolves an optional dispatch-target vault path, defaulting to ~/development/Vaults/Second_Brain. Entry point main (311-327) exposes --project, --home, --config, --format.
install.sh
14 linesCopies sync.md, lib/context-audit.py, and lib/context-audit.config.json into ~/.claude/commands/ and ~/.claude/commands/lib/. The project documents, but does not ship in this repo, a Hermes Agent runtime port at ~/.hermes/skills/sync/, added only as an uncommitted CLAUDE.md edit.
Six decisions that show up as code, not as slogans.
Action tier follows config-write scope, not size or confidence
Only project-.mcp.json servers are auto-safe, because a project's own .claude/settings.json can add to disabledMcpjsonServers; anything global or user-scoped is recommend-only with a printed claude mcp remove command, since a project cannot disable a globally or user-scoped server.
lib/context-audit.py:201-208; design spec line 25-28
The never-touch list is checked before the value-earning heuristic
Ordering exists to stop a substring collision: context7 contains the substring context, one of the value-earning tool signatures, and would otherwise be miscategorized.
lib/context-audit.py:214-221; README.md:101, 196
Per-project plugin disabling was ruled out as an auto-action
enabledPlugins merge semantics, replace versus union, are undocumented and treated as unreliable. disableAllHooks was ruled out on the same page as too blunt for a selective hook trim.
design spec, lines 29-31
Token figures are labeled estimates, never exact
/context is a client-side TUI command whose numbers cannot be invoked by a custom slash command or the model and are not exposed programmatically, so the helper reconstructs the signal and labels every output an estimate.
design spec, lines 21-23; lib/context-audit.py:293
Unknown items default to keep, never to auto-disable
classify_server's fallthrough branch returns verdict: "uncertain", tier: "none". Uncertain items are settled by model judgment inside sync.md, never by the helper.
lib/context-audit.py:227; tests/test_context_audit.py:249-256, 274-280
Second_Brain dispatch is a bonus, not a prerequisite
resolve_second_brain only enables dispatch if the configured directory exists on disk, and an empty string disables it outright regardless of what's on the filesystem.
lib/context-audit.py:248-266
Two build sessions, 28 days apart, 24 commits total.
Session 1 (2026-05-29, 15 non-merge commits plus 1 merge) is the build: design spec, implementation plan, then a sequential feature build, config loader, project-type detection, MCP discovery, plugin/hook/memory discovery, token estimation, classification, report assembly, wiring into sync.md, closing with a review pass and a dry-run verification commit, merged via 175f961.
Session 2 (2026-06-26, 8 commits) is documentation and hardening: a CLAUDE.md plus how-sync-works writeup, a full README rewrite with new SVG diagrams, a .gitignore change that untracked the docs/superpowers/ design corpus while keeping the how-it-works writeup and diagram assets tracked, two GitHub Actions workflows, and a final commit making the Second_Brain dispatch path configurable.
2026-05-29 Add design spec for /sync context-audit pre-run
2026-05-29 Add implementation plan for context-audit pre-run
2026-05-29 scaffold: context-audit module, config, pytest
...
2026-05-29 feat: wire context-audit stage into sync.md (Step 1c + report + rules)
2026-05-29 Merge feat/context-audit: /sync context-audit pre-run
2026-06-26 docs: add CLAUDE.md and how-sync-works writeup
2026-06-26 docs: rewrite README to LOGIC.md standard + add animated architecture SVGs
2026-06-26 chore: gitignore docs/ except how-sync-works.docx; untrack assets + superpowers
2026-06-26 Add GitHub Actions workflow for Python package
2026-06-26 Add Pylint workflow for Python code analysis
2026-06-26 feat: make Second_Brain dispatch path configurable + document itWhat this is not.
This is a Claude Code slash-command package plus a Python CLI helper, not a hosted service. It has no deploy target, no live URL, no published package, and no database.
Its tests claim in shipped docs, 29, does not match the test file on disk, 34, as of this compile. Treat the README and how-sync-works badges as stale, not authoritative.
The docs/superpowers/ design and plan corpus, and the .claude/commands/install-verify.md command, exist on the local filesystem but are excluded from git tracking by .gitignore, so they are not part of what a fresh git clone of this repo would produce.
The documented Hermes Agent variant, ~/.hermes/skills/sync/, is referenced only in an uncommitted CLAUDE.md edit and lives outside this repo entirely. It was not inspected and is not evidenced here.
Evidence: compiled from the sync-context-audit repository on 2026-08-03. Every number on this page traces to a file path or command output in the source tree. Last updated: 2026-08-03.