Skip to content
Khala Khala

Adept

Adept is the ledger half of Khala’s answer to cognitive debt. The rest of the ecosystem keeps the org’s knowledge governed — approved, current, cited. Adept reads that same substrate from the other side and asks the uncomfortable question: can a named human still explain this? Not via a rubber-stamp “I understand” click, but by passing graded comprehension questions generated from the artifact’s actual content.

The framing is a ledger. Registered critical artifacts are the denominator — what must be known. Current vouches are the numerator — what someone can still explain. The gap is cognitive debt, and because it is measured, it can be repaid deliberately instead of discovered during an incident.

CRITICAL ARTIFACTS · 12 vouched ×9 stale / none ×3 COVERAGE 9 / 12 retry-policy.md no current voucher → repay first

Core concepts

  • Vouch. A passing, graded comprehension check by a named person, bound to the artifact’s content_hash. When the artifact changes, the vouch goes stale automatically — understanding of an old version doesn’t silently carry over.
  • Spaced repetition. Per-question mastery sits on a repetition ladder; questions resurface for re-testing until passed again. A vouch is a state you maintain, not a badge you earn once.
  • Coverage. The org-level metric: the fraction of registered critical artifacts with a current vouch. Its complement is the orphan hotlist — artifacts nobody can currently vouch for. Repay those first.
  • AI-authorship-safe. Adept never consults git history. Whether a human or an agent wrote the artifact is irrelevant; the only question is whether a human understands it now.

Quickstart

Terminal window
uv tool install ./adept    # or: pipx install ./adept — installs the global `adept` command

Run adept from anywhere in your project — the root is the nearest adept.manifest.yaml (walking up from the current directory). Artifact paths are stored relative to that root, so the manifest is clone-portable.

Terminal window
adept register PATH                    # register a critical artifact; prints its artifact_id
adept due --as PERSON                  # due questions / artifacts needing questions
adept coverage --as PERSON             # coverage, orphan hotlist, weakness map
adept review ARTIFACT_ID --as PERSON   # headless self-drive (needs ANTHROPIC_API_KEY)

The agent-driven loop (due → save-questions → record-attempt → coverage) needs no API key — a Claude Code session supplies the cognition (question generation, grading, remediation). Only adept review calls the model directly.

A browser + server-backed team surface lives in adept-web — the same meter with a shared backend (file or Postgres).