# Context Kit Check

> Read-only integrity, wiring, and hygiene audit of a project context kit -- a CLAUDE.md entry point plus its docs/ tree (runbooks, changelog, history, status, sessions). Verifies the CLAUDE.md Version matches the changelog, changelog rows stay in reverse-chronological order, every runbook/doc is registered and exists, all relative Markdown links resolve, no orphaned docs, no committed secrets or leaked mount paths, dates are never in the future, session folders follow the dated notes.md convention, and status/history docs stay coherent; plus concurrency-safe rules for editing shared index files when multiple sessions or agents share a context. Use whenever the user wants to audit, validate, verify, lint, or health-check their CLAUDE.md or docs context kit -- before or after an end-of-session capture, a docs reorg, or adding a runbook, when inheriting a kit, or on asks like "are my docs consistent", "any broken links", or "did I commit a secret". Trigger even on terse asks like "check my CLAUDE.md".

- Skill: `wawoodwa/context-kit-check` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add wawoodwa/context-kit-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wawoodwa/context-kit-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: wawoodwa (https://skillmd.com/u/wawoodwa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wawoodwa/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`):

```bash
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.*