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	What it scans	How
1	`path-resolver`	Every absolute path `/Users/…` in scope files	`existsSync(path)`
2	`project-count-sync`	Hardcoded "N registered" / "N projects" claims next to `01-projects/`	compare to `ls -d 01-projects/*/`
3	`issue-reference-freshness`	`#NN` in forward-looking sections (What's Next, Backlog, Open Issues, Offene Themen, Todo, Next Steps)	`glab issue view NN --repo <origin>`
4	`session-file-existence`	`50-sessions/YYYY-MM-DD-*.md` references anywhere in scope	`existsSync(vault/50-sessions/<file>)`
5	`command-count`	"N commands" / "N /commands" claims in prose	compare to `ls commands/*.md \| wc -l`; skipped if no `commands/` dir
6	`session-config-parity`	Top-level keys under `## Session Config` in `CLAUDE.md` / `AGENTS.md`	diff against `docs/session-config-template.md`; missing keys flagged as errors
7	`vault-dir-parity`	`vault-integration.vault-dir` in BOTH `CLAUDE.md` AND `AGENTS.md`	reuse `_parseVaultIntegration`; flag when the two files disagree

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) 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. Top-level keys present in the template but missing locally surface as session-config-parity errors. 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 is checked. As of the gsd Pattern Adoption Quick-Wins bundle (PRD 2026-05-22, issues #517–#521), the template-side keys include the four new 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 fails session-config-parity in mode: hard. The bundle ships all four keys in CLAUDE.md and docs/session-config-template.md together (Wave 1 of the adoption plan) so the check stays green at adoption time.

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.

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):

Flag	Default	Effect
`--mode <hard\|warn\|off>`	`warn`	`hard` → exit 1 on errors; `warn` → exit 0, errors in JSON; `off` → short-circuit to `status: skipped-mode-off`
`--repo <owner/name>`	derived from `git remote get-url origin`	Override for Check 3's `glab issue view --repo`
`--include-path <glob>`	resolved instruction file (`CLAUDE.md` or `AGENTS.md` per alias rule), `_meta/*/.md`	Repeatable. Scope files, relative to `VAULT_DIR`. Defaults are seeded post-resolution so Codex-only repos (`AGENTS.md`) are scanned out of the box.
`--skip-path-resolver`	off	Disable Check 1
`--skip-project-count`	off	Disable Check 2
`--skip-issue-refs`	off	Disable Check 3 (also auto-skipped if `glab` not on PATH)
`--skip-session-files`	off	Disable Check 4
`--skip-command-count`	off	Disable Check 5
`--skip-session-config-parity`	off	Disable Check 6
`--skip-vault-dir-parity`	off	Disable Check 7
`--commands-dir <path>`	`<VAULT_DIR>/commands`	Override path to `commands/` directory for Check 5
`--config-template <path>`	`<VAULT_DIR>/docs/session-config-template.md`	Override path to the canonical Session Config template for Check 6

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"],
  "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
    - _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

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 blocks close; 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

Aspect	vault-sync	drift-check
Target	Frontmatter + wiki-links in vault/*.md	Narrative drift in CLAUDE.md / _meta/*.md
Schema source	Vendored Zod from baseline	None — regex + filesystem checks
Deps	`zod`, `yaml`	None (stdlib only)
Session-end phase	2.1	2.2
Default mode	`warn`	`warn`

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