Claude Md Drift Check

CLAUDE.md Drift-Check Skill

The instruction file is alias-resolved per skills/_shared/instruction-file-resolution.md: CLAUDE.md (Claude Code / Cursor IDE) wins ties; AGENTS.md (Codex CLI) is picked up as a transparent alias when CLAUDE.md is absent. The resolved path and kind are surfaced in the JSON output (resolved_path, resolved_kind).

Status

PHASE 1 IMPLEMENTED (2026-04-19). Session-end opt-in quality gate. Upstream of /close commit preparation, downstream of vault-sync.

Why this exists

CLAUDE.md is narrative SSOT for a repo's Session Config and project context. It decays quickly when surrounding state changes — paths get renamed, project counts shift, issues close, session files get pruned in digests. The drift-cluster closed by agents/vault#57 (3 items in one sweep) was the 4th incidence of the issue-description-drift-stale-filecount learning. Manual curation does not scale; this skill turns drift detection into a repeatable gate.

Checks

Check 3 deliberately scopes to forward-looking sections. Mentions inside "Recently Closed", "Decisions", "Archive", etc. describe history and must not be flagged.

Check 5 counts *.md files directly inside commands/ (non-recursive, non-hidden). The commands/ directory is resolved relative to VAULT_DIR by default; use --commands-dir <path> to override.

Check 6 (issue #30; severity split per #785) extracts the YAML block under ## Session Config from both the canonical template (docs/session-config-template.md by default, override with --config-template) and the resolved local instruction file — reading the template TWICE, once per occurrence: { occurrence: 'first' } reaches the "Full minimal baseline" (the 7 schema-mandatory keys), { occurrence: 'last' } reaches the "Full opt-in baseline" (the full key catalog, a strict superset of the minimal block). A template key missing from the local file is a session-config-parity error when it belongs to the minimal-baseline set, and a warning when it is opt-in-baseline-only — a consumer repo that legitimately does not adopt an opt-in feature (e.g. no handover-gate) must not go red; only the true 7-key mandatory contract does. When the template carries a single ## Session Config heading (no separate opt-in block), 'first' and 'last' resolve to the same block and every key is treated as mandatory, preserving prior behaviour for single-block templates. Both fenced YAML (```yaml ... ```) and raw YAML body (up to next ## heading) are accepted. The check skips gracefully when the template file is absent, when no instruction file is detected, or when explicitly disabled via --skip-session-config-parity.

The parity set is template-driven: every column-0 YAML key under ## Session Config in the template (across both occurrences) is checked. As of the gsd Pattern Adoption Quick-Wins bundle (PRD 2026-05-22, issues #517–#521), the template-side keys include four opt-in top-level blocks:

• state-md-lock (Pattern 1 / #518) — mechanical STATE.md write lock
• slopcheck (Pattern 2 / #520) — opt-in package legitimacy gate
• templates-first (Pattern 3 / #519) — gh/glab template-read enforcement hook
• verification-auto-fix (Pattern 4 / #521) — opt-in auto-fix retry loop after Quality-Gate fail

A local CLAUDE.md / AGENTS.md that omits any of these now surfaces a session-config-parity warning (not an error) — they are opt-in-baseline-only keys, so omitting them never trips mode: hard, and never blocks autonomous-gated skill-evolution's runConfigValidationGate() (which runs the checker with --mode hard and reads only errors[]).

Check 7 (issue #600) is the only check that intentionally reads BOTH instruction files rather than the single alias-resolved one. The alias rule (CLAUDE.md wins ties, AGENTS.md is the Codex alias) means resolveInstructionFile() picks exactly one — so a repo carrying both files can silently let AGENTS.md drift out of sync with CLAUDE.md. A sibling project ran for weeks with a correct vault-integration.vault-dir in CLAUDE.md and a dead path in AGENTS.md. Check 7 reads vault-integration.vault-dir from each file (reusing the _parseVaultIntegration parser from scripts/lib/config/vault-integration.mjs — no hand-rolled YAML) and flags a vault-dir-parity error when the two values diverge (the error is attributed to AGENTS.md, the secondary alias, and names both values). The check skips gracefully when only one instruction file is present (nothing to compare), when neither file declares a vault-integration: block, or when explicitly disabled via --skip-vault-dir-parity. Two files that both omit vault-dir (both unset) agree and pass.

Check 9 (rule-scoping) validates .claude/rules/*.md frontmatter against the scripts/lib/rule-loader.mjs contract, catching the class of defect where a rule silently drifts out of the activation pipeline the loader actually implements. Four probes: (1) paths-presence — a top-level paths: frontmatter key is not a key rule-loader.mjs recognises (it only reads globs:), so a rule with paths: silently loads ALWAYS-ON regardless of intended file scope; flagged as an error. (2) cited-but-missing — (a) .claude/rules/<name>.md citations inside CLAUDE.md/AGENTS.md that don't resolve to a file on disk, and (b) bare <name>.md tokens in a rule's own ## See Also footer that don't exist as sibling rule files (tokens carrying a path separator, e.g. ../../skills/_shared/state-ownership.md, are cross-directory references and explicitly out of scope); both flagged as errors. (3) zero-match-globs — a globs: pattern matching zero files in git ls-files (falls back to a manual directory walk when git is unavailable); flagged as a WARNING, not an error, because library/exemplar repos legitimately carry dead stack rules (this repo alone carries ~37 by design — Swift/Next.js/Supabase rules with no matching files in a pure-Node-ESM codebase). (4) foreign-glob — a glob pattern containing a PascalCase product-like token (regex [A-Z][a-z]+[A-Z], e.g. WalkAITalkieTests) — a likely copy-paste leftover from another project's rule scope; flagged as a WARNING. Glob matching reuses the same picomatch-with-inline-fallback resolution scripts/lib/rule-loader.mjs uses (parseGlobsFrontmatter is imported directly; the picomatch resolution itself is duplicated locally since rule-loader.mjs does not export a public matcher function). The check is skipped silently (no checks_run entry, no checks_skipped entry) when .claude/rules/ is absent, or explicitly via --skip-rule-scoping.

Check 10 (docs-parity, issue #780) validates the public docs surface against live repository state via three sub-checks, all reported under the single docs-parity check id: (a) count-claims — docs/components.md's own heading counts ("## Skills (N user-facing)", "## Commands (N)", "## Agents (N typed sub-agents)", "## Hook event types (N)") are compared against the SAME actual on-disk derivation the surface-count family (Check 5) uses (countSkills/the commands-dir listing/countAgents/readHookCounts) — NOT Check 5's claimRe regexes, which are tuned for CLAUDE.md/README prose phrasing and verifiably do not match components.md's own heading convention; a dedicated set of regexes tailored to the doc's actual authored structure is used instead. (b) config-block-parity — top-level Session Config keys documented in docs/session-config-template.md (opt-in baseline, via the Check 6 'last'-occurrence extractor) are compared against docs/session-config-reference.md; a key is considered documented in the reference when it appears in a yaml fence (any indent), a ##/###/#### heading, or the first cell of a markdown table row (| `key-name` | ...) — the reference's dominant documentation shape is one table row per field, so a naive fence-only extraction under-counts what it actually documents. Missing keys surface as docs-parity errors attributed to docs/session-config-reference.md. (c) metrics-path-liveness — any .claude/metrics/ path reference (stale; canonical is .orchestrator/metrics/) found in root docs/*.md or docs/examples/*.md surfaces as an error at its exact file/line. The whole check is skipped silently (no checks_run entry, no checks_skipped entry) when docs/components.md is absent, or explicitly via --skip-docs-parity.

Files

• checker.mjs — pure Node ESM, no runtime deps. Reads scope files, runs enabled checks, emits JSON on stdout.
• checker.sh — POSIX shim. Resolves VAULT_DIR, execs Node. No pnpm install needed (zero deps).
• package.json — declares Node engine; no dependencies.
• tests/ — vitest suite added in Quality wave.

Invocation

VAULT_DIR=/path/to/vault bash checker.sh --mode warn

CLI flags (all optional):

Environment:

• VAULT_DIR — project root to scan. Defaults to $PWD. Can also be passed as positional arg 1.

JSON output

{
  "status": "ok|invalid|skipped|skipped-mode-off",
  "mode": "hard|warn|off",
  "vault_dir": "<absolute path>",
  "resolved_path": "<absolute path to CLAUDE.md or AGENTS.md, or null>",
  "resolved_kind": "claude|agents|null",
  "files_scanned": N,
  "checks_run": ["path-resolver", "project-count-sync", "issue-reference-freshness", "session-file-existence", "command-count", "session-config-parity", "vault-dir-parity", "generated-rule-staleness", "rule-scoping", "docs-parity"],
  "checks_skipped": ["<name>: <reason>"],
  "errors": [
    { "check": "<name>", "file": "<relative path>", "line": N, "message": "<human>", "extracted": "<raw text>" }
  ],
  "warnings": [
    { "check": "<name>", "file": "<relative path>", "line": N, "message": "<human>", "extracted": "<raw text>" }
  ],
  "command_count": { "actual": N }
}

The resolved_path / resolved_kind pair surfaces the alias resolution outcome (issue #33 AC2) so users on either platform can audit which instruction file the checker scanned. kind: 'claude' for CLAUDE.md, kind: 'agents' for AGENTS.md, null when neither was found.

When command-count fires a drift error, the error object also carries "command_count": { "actual": N, "claimed": M } for easy programmatic diffing.

Exit codes:

• 0 — no errors, or errors present but mode=warn, or short-circuit (mode=off / no scope files)
• 1 — errors present and mode=hard
• 2 — invocation or infra error (missing VAULT_DIR, unreadable file, malformed glob)

Session Config block (opt-in)

In repo-level CLAUDE.md under ## Session Config:

drift-check:
  enabled: true
  mode: warn          # hard | warn | off
  include-paths:
    - CLAUDE.md
    - AGENTS.md
    - _meta/**/*.md
  check-path-resolver: true
  check-project-count-sync: true
  check-issue-reference-freshness: true
  check-session-file-existence: true
  check-command-count: true
  check-session-config-parity: true
  check-vault-dir-parity: true
  check-generated-rule-staleness: true
  check-rule-scoping: true
  check-docs-parity: true

When drift-check.enabled is false or the block is absent, the session-end phase is a no-op.

Invocation points

Session-End Phase 2.2 — opt-in quality gate

• Trigger: after Phase 2.1 vault-sync, before commit prep
• Behavior: full scan of the configured include-paths
• Error handling: mode=hard exits non-zero and session-end converts errors into carryover + continue; mode=warn surfaces in quality-gate report; mode=off skipped silently
• Rationale: drift is narrative-level; vault-sync catches frontmatter-level. The two gates are complementary.

Future: wave-executor (not implemented)

A lightweight variant could run after Impl-Polish when CLAUDE.md is edited mid-session. Out of scope for Phase 1.

Design notes

• No zod. Output is emission-only, input is plain text. Pure stdlib keeps dep footprint zero.
• No frontmatter parsing. Scope files are scanned as Markdown prose; vault-sync owns frontmatter validation.
• Code-fence aware. Path extraction skips triple-backtick blocks to avoid flagging example paths. Issue-ref extraction does NOT skip fences (configs and snippets often cite real live issues).
• Section-aware Check 3. A #NN mention in "Recently Closed" is context; the same mention in "What's Next" is drift. The checker tracks the current ## heading to decide.
• glab optional. If glab is missing or not authenticated, Check 3 degrades to checks_skipped with a clear reason — never blocks.

Relationship to vault-sync

They are siblings, not overlapping. vault-sync is the structural gate; drift-check is the narrative gate.

Source: hashgraph-online/awesome-codex-plugins → plugins/Kanevry/session-orchestrator/skills/claude-md-drift-check/SKILL.md