Proactive Watch — Drift Detection

Proactive Watch — Drift Detection Skill

Continuous enforcement of the Executable Contracts meta-principle (ADR-002). Catches drift across 10 universal drift classes on every session start.

Skill Purpose

Detect silent drift between declared reality (docs, manifests, inventories, ADRs) and actual reality (filesystem, git state, dependencies, hooks). Report findings with severity, triage routing, and evidence — so drift is fixed while it's cheap, not months later when it's entrenched.

Activation

Dispatch Path

TASK arrives with "check drift" / "audit" / "session start"
  │
  ▼
Maxim skill .claude/skills/proactive-watch/ matches
  │
  ▼
Load config/watch-profile.yml (per project)
  │
  ▼
For each ENABLED checker:
  ├── Run checker (bash watch.sh <checker> OR pwsh watch.ps1 <checker>)
  ├── Capture JSONL report line per drift
  └── On checker error: apply fail-mode policy (hybrid)
  │
  ▼
Aggregate report → .mxm-skills/watch-report.jsonl
Emit summary block to stderr / chat (LIGHT phase)
Route critical drift to triaged office (FULL phase, v1.0.0)

Behavioral Framing

Apply Fogg + COM-B + Present-Bias principles when surfacing drift:

1. Fogg B=MAT — run at SessionStart when developer is engaged (max M × A)
2. COM-B — provide clear Evidence + Action path, not just "something's wrong"
3. Present-Bias Mitigation — frame every finding in terms of "fix now vs cost later"

Output language:

• ✗ Bad: "Drift detected"
• ✓ Good: "Declared 90 agents, filesystem has 91 — add to documents/ledgers/AGENT_SKILL_INVENTORY.md §1 (60s fix)"

Proactive Loops

The skill is itself a proactive loop. Additionally:

• After fixing an inventory drift, proactively scan for recurring-pattern opportunities — if 3+ inventory drifts happened in one month, recommend a stronger pre-commit gate
• After fixing a compliance drift, auto-route to CSO for root-cause analysis
• After fixing a contract drift, check whether the underlying ADR needs superseding

Confidence Tagging

Output Format

LIGHT summary (SessionStart banner)

Maxim WATCH (light)
  Drift detected : 3
  ⚠ inventory-drift: declared 90 agents, filesystem has 91 (severity 3)
  ⚠ version-drift: README badge v1.0.0, registry v1.0.0 (severity 3)
  ⚠ stale-handoff: handoff.md 9 days old (severity 2)
  Checker errors : 0
  Report         : .mxm-skills/watch-report.jsonl

JSONL report (machine-readable)

{"ts":"2026-04-18T12:00Z","phase":"light","project":"maxim","drift_class":"inventory-drift","severity":3,"declared":90,"actual":91,"evidence":"agents/MXM/ceo/new-agent.md","triage":"coo","action":"review-queue"}

Checker Execution Model

The skill ships two unified drivers that implement all 11 checkers (Classes 1–10 from v1.0.0; Class 11 surface-claims-drift added v1.0.1 with companion tool bootstrap/sync-counts.{sh,ps1} for mechanical propagation):

• watch.sh — bash (Linux/macOS/Git-Bash)
• watch.ps1 — PowerShell 7+ (Windows primary, cross-platform)

Each driver accepts one argument: the checker name. Running watch.sh all runs every enabled checker and aggregates output.

# Run single checker
.claude/skills/proactive-watch/watch.sh inventory-drift

# Run all enabled checkers (LIGHT phase default)
.claude/skills/proactive-watch/watch.sh all

Files in this Skill

Self-Adoption (maxim repo)

This repo ships its own config/watch-profile.yml in v1.0.0 — the framework's first consumer is itself. Any drift that sneaks into this repo across multi-session work should surface at the next /mxm-watch or SessionStart.

Extending

Projects may add custom checkers by:

1. Writing a script at .claude/skills/proactive-watch/custom/<name>.sh (+ .ps1)
2. Registering it in config/watch-profile.yml under custom_checkers:
3. Emitting JSONL lines matching schemas/watch-report.schema.json

Custom checkers run after standard checkers.

Related

• Framework doc: composable-skills/frameworks/proactive-watch.md
• ADR-002: documents/ADRs/ADR-002-executable-contracts.md
• Command: .claude/commands/mxm-watch.md
• Hook: .claude/hooks/session-start.{sh,ps1} calls watch --light
• MCP: mxm-context tools watch_run, watch_report, watch_configure (v1.0.0+)

Copyright (c) 2026 iSystematic Inc. Maxim product. BSL 1.1.