Context Kit Check

Context-Kit Integrity & Concurrency Check

A read-only audit of a whole context kit -- a CLAUDE.md entry point plus its docs/ tree -- that confirms it is internally consistent, fully wired, free of secret leaks, and safe to edit when more than one session or agent shares the same context. Fix only trivially-safe issues; propose the rest. This audit never writes anything on its own.

Conventions (governed by context-kit-steward)

--- GOVERNED CONVENTIONS (source: context-kit-steward charter v1.0) --- Do not edit here. Change the charter in context-kit-steward and re-run it to re-sync; local edits to this block will be overwritten on the next sync.

This skill is the family's VERIFIER -- it checks that operating kits obey the shared Context Kit conventions (full text + rationale in the context-kit-steward charter):

• Verifies C1 (dating): flags any future date in CLAUDE.md or changelog rows.
• Verifies C2 (ordering): changelog rows are reverse-chronological.
• Verifies C3 (concurrency): CLAUDE.md Version matches the top changelog row.
• Verifies C4 (session folders): each docs/sessions/<dir>/ has notes.md; any date prefix parses and is not in the future.
• Verifies C7 (hygiene): secret/credential scan + mount/session-path leak scan.
• Verifies C8 (read-only): flags edits under leading-underscore directories.
• Follows C10: moves stray artifacts to Trash, never rm.

What this audits

A context kit following the common convention:

CLAUDE.md                 # entry point: role, standards, doc index, Version header
docs/
  changelog.md            # CLAUDE.md revision table (top row = current Version, newest first)
  history.md              # durable record of completed work
  status.md               # current state + open work queue
  runbooks/*.md           # procedures, often paired with <name>-lessons.md
  sessions/<session-date>-<slug>/notes.md   # per-session notes, keyed to conversation-start date
  plans/  reviews/  _reference/             # supporting trees

It does not require those exact filenames everywhere -- the script degrades gracefully when a directory is absent.

This check is the companion to the context-kit-capture skill: capture writes entries (task files, changelog/history rows, session folders) and this check verifies they are wired correctly, ordered correctly, and collision-free. The two share the same conventions -- conversation-start dating, reverse-chronological changelog, one writer-of-record -- but neither invokes the other.

When to use

• Start or end of a working session, especially before an end-of-session capture.
• After any change that touched several docs or added a runbook / plan / session.
• Whenever multiple sessions or agents are open in the same context -- to catch collisions in the shared index files (see "Concurrency-safe updates").
• When inheriting or onboarding a kit you did not write.

How to run it

This is read-only. Run the bundled checker against the kit root (the directory that contains CLAUDE.md):

python3 <skill-dir>/scripts/check_kit.py /path/to/kit-root

(<skill-dir> is this skill's own directory; the kit root defaults to the current directory if omitted.) The script needs only Python 3 standard library. It runs these mechanical checks and prints a [FAIL]/[WARN]/[INFO]/[OK] line for each:

1. Version coherence -- CLAUDE.md Version: equals the top row of docs/changelog.md. A mismatch is a concurrency red flag: another session likely bumped it; reconcile before writing.
2. Registration -- every docs/runbooks/*.md is referenced in CLAUDE.md, and every *-lessons.md has its base runbook.
3. Link resolution -- every relative Markdown link in CLAUDE.md and docs/** resolves on disk (code spans and <PLACEHOLDER> targets are ignored).
4. Orphans (advisory) -- docs referenced nowhere: candidates to wire in or retire, not necessarily errors.
5. Secret / hygiene scan -- committed AWS keys, PEM private-key/cert headers, client_secret/app_secret/password assignments with real (non-placeholder) values, leaked /sessions/... or /mnt/... absolute paths, and stray .DS_Store / *.swp. Flagged hits say "REVIEW each" -- a documented secret-pattern example is a false positive; a real value is not.
6. Date plausibility -- CLAUDE.md "Last Updated" and every date cell in docs/changelog.md parse and are not in the future. Dates record the conversation-START date (the context-kit-capture convention), so a future date means the capture used wall-clock time instead of the session-start date.
7. Changelog ordering -- docs/changelog.md rows are in reverse-chronological order: version numbers (and dates, when a date column is present) are non-increasing from top to bottom. An out-of-order row means a capture slotted its entry in the wrong position -- a hard failure, since the table's order is its contract.
8. Sessions convention -- each docs/sessions/<dir>/ has a notes.md manifest, and any leading YYYY-MM-DD date prefix parses and is not in the future. A session dir with no date prefix is advisory (the convention is <session-date>-<slug>/).

The script exits non-zero only on hard failures (version mismatch, broken links, suspected secrets, out-of-order changelog). Orphans, sessions advisories, and date warnings never fail the run.

Judgment checks (do these by reading, after the script)

The script cannot reliably judge these -- read the top of each file and assess:

• Conventions -- each dated docs/sessions/<session-date>-<slug>/ has a notes.md manifest; canonical reusable assets live in docs/runbooks/assets/<runbook>/ while the dated sessions/ copies are provenance snapshots.
• Session dating -- spot-check that a session folder's date prefix and its changelog/history rows reflect the date the conversation started, not when the capture was run. The script catches future dates and ordering breaks; it cannot tell a plausible-but-wrong past date from a correct one, so confirm a sample by reading.
• State coherence -- status.md "Open work queue" items point to real files/paths; the newest history.md entries have matching status.md "Recently completed" rows, and history.md entries read in chronological order.
• Read-only respect -- nothing under a leading-underscore dir (e.g. _reference/) was edited without authorization.

Fix vs propose

• Fix now (safe): a broken relative link or typo'd path; a missing index/Resources line for a doc that clearly should be registered; a stray .DS_Store (move it to the trash -- never rm). Re-run the script after.
• Propose (get approval): retiring an orphan; content/scope changes; version / changelog reconciliation across sessions; re-ordering changelog rows; anything touching a read-only _ dir.

End with a one-screen PASS / FIX / PROPOSE summary.

Concurrency-safe updates (when multiple sessions or agents share the context)

The collision-prone files are the shared index/durable files: CLAUDE.md (especially the Version), docs/changelog.md, docs/history.md, docs/status.md. Session-owned files (a new runbook, its assets/, a dated docs/sessions/<session-date>-<slug>/) are isolated and safe.

Rules for editing a shared index file:

1. Re-read from disk immediately before editing -- never write from a stale in-context copy.
2. Make a minimal targeted edit, not a full-file rewrite -- insert the single new row/line in its correct position (reverse-chronological for changelog, chronological for history) and preserve everything else byte-for-byte. A blind whole-file rewrite clobbers rows a concurrent session appended.
3. Take the version from disk: bump CLAUDE.md Version to (current on-disk value
   • 1. and add the changelog row for that number. If Version and the top changelog row already disagree, another session is mid-update -- pause and reconcile first.
4. One writer-of-record is the simplest guard: when several sessions or agents are open, only one edits those shared files; the others record their work in their own session notes.md and hand the summary to the writer-of-record.

The edit tooling refuses a write when its expected text no longer matches on disk -- a useful backstop, but coordination (rule 4) beats relying on it.

Read-only by default. ASCII-only content for universal compatibility.