---
description: Documentation drift warning on commit (non-blocking)
trigger: tool-use
match: git commit*
blocking: false
---

# Documentation Drift Check (Low Token)

Lightweight pre-commit check that warns about documentation drift. Reads manifest only, non-blocking.

## Script

```bash
#!/bin/bash
MANIFEST="docs-manifest.json"

# Skip if no manifest exists
if [ ! -f "$MANIFEST" ]; then
  exit 0
fi

# Check if jq is available
if ! command -v jq &> /dev/null; then
  exit 0
fi

# Get staged files
STAGED_FILES=$(git diff --cached --name-only 2>/dev/null)
if [ -z "$STAGED_FILES" ]; then
  exit 0
fi

# Check each module in manifest for drift
DRIFT_FOUND=false
DRIFT_MODULES=""

for MODULE_PATH in $(jq -r '.modules | keys[]' "$MANIFEST" 2>/dev/null); do
  # Get code files for this module
  CODE_FILES=$(jq -r ".modules[\"$MODULE_PATH\"].codeFiles[]?" "$MANIFEST" 2>/dev/null)

  for CODE_FILE in $CODE_FILES; do
    # Check if any staged file matches a module's code files
    if echo "$STAGED_FILES" | grep -q "$CODE_FILE"; then
      STATUS=$(jq -r ".modules[\"$MODULE_PATH\"].status" "$MANIFEST" 2>/dev/null)
      LAST_DOC=$(jq -r ".modules[\"$MODULE_PATH\"].lastDocUpdate" "$MANIFEST" 2>/dev/null)
      FEATURE_ID=$(jq -r ".modules[\"$MODULE_PATH\"].featureId" "$MANIFEST" 2>/dev/null)

      if [ "$STATUS" != "synced" ] || [ "$LAST_DOC" = "null" ]; then
        DRIFT_FOUND=true
        DRIFT_MODULES="$DRIFT_MODULES\n  - $MODULE_PATH ($FEATURE_ID) — last doc update: ${LAST_DOC:-never}"
      fi
      break
    fi
  done
done

if [ "$DRIFT_FOUND" = true ]; then
  echo ""
  echo "Documentation drift detected:"
  echo -e "$DRIFT_MODULES"
  echo ""
  echo "Consider running /documentation to update."
  echo ""
fi

exit 0
```

## Behavior

| Condition | Output | Blocks? |
|-----------|--------|---------|
| No manifest file | Silent | No |
| No jq available | Silent | No |
| No staged files | Silent | No |
| Staged files match synced modules | Silent | No |
| Staged files match drifted modules | Warning with module list | No |

## Token Cost

- **Normal case (no drift):** 0 tokens (pure bash, no LLM)
- **Drift detected:** ~10 tokens (displays warning message)

## Integration

This hook integrates with:
- `docs-manifest.json` (created by BA step-06)
- `/documentation` skill for documentation updates

## Notes

- **Non-blocking by design:** Documentation drift should never prevent commits
- The warning suggests running `/documentation` to update
- If `jq` is not installed, the hook silently exits (graceful degradation)
- Cross-platform: Works on Linux, macOS, and Windows (Git Bash/WSL)
