Kanevry Session Orchestrator 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) 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.

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

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

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

Source: Kanevry/session-orchestrator — distributed by TomeVault.