Resolve

doc-sentinel:resolve

Process accumulated drift warnings from .doc-sentinel-drift.json. For each warning, verify whether the doc actually drifted, fix it if so, or dismiss if it is a false positive.

Phase 1: Load Drift Queue

cat .doc-sentinel-drift.json 2>/dev/null || echo "No drift warnings pending"

If the file is empty or missing, report "No drift warnings to resolve" and exit.

Phase 2: Deduplicate and Group

Group warnings by doc file. Multiple source changes may affect the same doc — process them together for coherent updates.

Example grouping:

ARCHITECTURE.md
  - src/routes/auth.ts changed (commit abc123)
  - src/routes/users.ts changed (commit def456)

docs/api.md
  - src/controllers/payments.ts changed (commit abc123)

Present the grouped summary and total count before proceeding.

Phase 3: Triage Each Group

For each doc file with drift warnings:

3a: Read Current State

Read the doc file and the changed source files to understand what actually changed.

3b: Classify the Drift

Determine what kind of drift occurred:

3c: Apply Fix or Dismiss

For real drift:

• Read the doc section that references the changed code
• Read the new state of the source code
• Update the doc to reflect the current reality
• Keep the same writing style and level of detail as the surrounding content
• If unsure about intent, add a <!-- TODO: verify --> comment rather than guessing

For false positives:

• Record as dismissed (remove from queue)
• No changes needed

Phase 4: Commit Fixes

After processing all groups:

# Stage only modified doc files
git add <fixed-doc-files>
git commit -m "docs: resolve documentation drift from recent changes

Updated docs to reflect code changes detected by doc-sentinel:
- <brief summary of fixes>"

Use the docs: commit prefix to prevent the post-commit hook from re-triggering on this commit.

Phase 5: Clear Drift Queue

# Remove the drift file — it is session-scoped
rm -f .doc-sentinel-drift.json

Phase 6: Report

Print resolution summary:

doc-sentinel: resolved N drift warning(s)

Fixed:
  - ARCHITECTURE.md — updated 2 path references
  - docs/api.md — updated endpoint documentation

Dismissed (false positives):
  - README.md — logo path unchanged despite src/ changes

Remaining:
  - None (all warnings resolved)

If any warnings could not be resolved automatically (require human judgment about intent), list them separately under "Needs Review" with specific questions.

Rules

• Always read both the doc and the source before making changes
• Preserve the existing writing style — match tone, detail level, and formatting
• Never remove documentation sections wholesale — update them
• Use docs: commit prefix to avoid hook feedback loops
• If a doc file has >5 drift warnings from a single commit, consider whether the doc needs a broader rewrite rather than point fixes — dispatch a drift-resolver agent for complex cases
• Delete .doc-sentinel-drift.json after processing, even if some warnings were dismissed
• If doc-sync or inkwell is also installed, do not duplicate their work — sentinel fixes references and accuracy, not content generation