Michat docs drift guard

MiChat Docs Drift Guard

Canonical Rules

• Code is ground truth when ambiguous: michat/ and toolset configs.
• Canonical documentation lives in docs/.
• profiles/assistant/library/michat-specs/ must be an exact mirror of docs/ (same filenames, same contents).
• docs/MICHAT_REFERENCE.md is human-facing and can be higher-level, but must not contradict docs/ or code.
• profiles/_global/library/operating_guide_for_assistants.md and profiles/_global/library/troubleshooting_for_assistants.md are derived assistant guides and must not contradict their named sources or code.

Update Workflow (Use This Order)

1. Verify truth if needed
   • If changing paths, defaults, gates, UI labels, or dev/frozen behavior: confirm by reading the relevant code.
2. Update canonical docs
   • Edit the owning file(s) under docs/.
3. Update the human-facing guide
   • If the change affects a user-visible behavior or concept, update docs/MICHAT_REFERENCE.md.
   • Keep it readable; remove minutiae, not facts.
4. Update derived assistant guides
   • If assistants rely on the claim for operations/troubleshooting, update the derived guides.
   • Keep “Derived from:” lines consistent with the current source versions/dates.
5. Bump version/date headers
   • If a doc has a — vX.Y.Z — YYYY-MM-DD header, update date whenever the change is user-meaningful.
   • Bump version for non-trivial changes, following the repo’s existing pattern (do not invent a new scheme).
6. Resync the mirror
   • Copy docs/*.md to profiles/assistant/library/michat-specs/*.md.
   • Verify the mirror matches exactly (hash or diff).

Drift Checks (Fast, Deterministic)

1) Mirror equality (hash check)

$docsDir = 'docs'
$mirrorDir = 'profiles/assistant/library/michat-specs'
$docNames = (Get-ChildItem -LiteralPath $docsDir -File | Sort-Object Name).Name
foreach ($name in $docNames) {
  $h1 = (Get-FileHash -Algorithm SHA256 -LiteralPath (Join-Path $docsDir $name)).Hash
  $h2 = (Get-FileHash -Algorithm SHA256 -LiteralPath (Join-Path $mirrorDir $name)).Hash
  if ($h1 -ne $h2) { Write-Output ("DRIFT " + $name) }
}

2) Spot-check a single file (diff)

git --no-pager diff --no-index -- docs/MICHAT_REFERENCE.md profiles/assistant/library/michat-specs/MICHAT_REFERENCE.md

High-Risk Claim Types (Always Verify In Code)

• Paths: data root, profiles root, credentials root, frozen vs dev locations
• Gates: what enables a toolset vs what toggles a permission
• UI exact text: Settings labels, buttons, tooltips
• Allow-lists: file extensions, blocked actions, safety restrictions

When editing these, prefer citing/aligning to the exact module (e.g., michat/runtime_paths.py, michat/toolsets/*/__init__.py, michat/qt_shell.py).