chore: prevent future doc + diagram drift (file-move, COPY, diagram-pair guards + rules)

[emeraldleaf]

Summary

Four-layer prevention loop for the drift class surfaced by PR #112 (CatalogService Clean → VSA collapse fallout that left CLAUDE.md, demo docs, Dockerfile.catalog, and the perf doc referencing files that didn't exist anymore — for months, silently). Plus an extension to treat docs and diagrams as the review surface, not byproducts.

Layers added across two commits on this branch

Tier	Mechanism	Catches
1. Convention	CLAUDE.md "Doc-and-diagram discipline" + "File-move discipline"	Documents the rule
2. Edit-time hook	check-file-moves.sh PostToolUse on Bash	Same-session feedback when git mv / git rm runs
3. PR-review automation	.coderabbit.yaml path_instructions (topology files + file-rename catch-all)	Review-time flag when paired docs/diagrams missing
4. Mechanical (build-fail)	Broken-link audit (from #112) + Broken-COPY audit + Diagram-pair audit	Merge-gate fail when refs/paths/pairs broken

What's in here

Commit cf27628 (already on branch):

• check-file-moves.sh PostToolUse hook on Bash — git mv / git rm triggers a grep for refs to the old path
• CLAUDE.md "File-move discipline" rule
• CodeRabbit ** path_instruction for file rename/delete review

Commit 4e1ba94 (this commit):

• Broken-COPY audit in ci.yml — Dockerfile* COPY/ADD source paths that don't exist in the build context
• Diagram-pair audit in ci.yml — every docs/*.excalidraw must have its sibling docs/*.svg and vice versa
• CLAUDE.md "Doc-and-diagram discipline" rule — docs and diagrams are the REVIEW SURFACE, not byproducts; pairings table for AppHost.cs ↔ architecture.svg, Extensions.cs ↔ service-request-flow.svg, EF/cache/outbox changes ↔ perf-doc + sibling diagrams
• CodeRabbit path_instructions for NextAurora.AppHost/AppHost.cs (topology) and NextAurora.ServiceDefaults/Extensions.cs (middleware order) — flag missing paired doc/diagram updates at review time

Verification

All three mechanical guards smoke-tested locally on current tree:

broken-COPY audit       → exit=0 (Dockerfile.catalog clean post-#112)
diagram-pair audit      → exit=0 (7 .excalidraw + 7 .svg paired)
broken-link audit       → exit=0 (post-INDEX.md exclusion from #112)

What's intentionally NOT in this PR

• Rendered-SVG-matches-source check (would catch "I edited the .excalidraw but forgot to re-render the .svg"). Requires Playwright + uv setup in CI — heavier; can be a separate workflow gated on .excalidraw changes if drift in that direction becomes a real problem.
• PreToolUse hook for file moves. The PostToolUse hook + CodeRabbit + CI guards already close the merge gate; pre-edit blocking would be overkill.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Enhanced CI/CD validation to detect broken Docker file references during builds
  • Implemented automatic tracking to flag stale file references during renames and deletions
  • Strengthened requirements for keeping architecture documentation and diagrams synchronized with code changes
  • Added repository discipline guidelines for maintaining code quality and documentation consistency

[emeraldleaf]

Retracting per user request.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d33030f0-7812-4597-b9ad-b554a9c766da

📥 Commits

Reviewing files that changed from the base of the PR and between 81fb33e and 4e1ba94.

📒 Files selected for processing (5)

• .claude/scripts/check-file-moves.sh
• .claude/settings.json
• .coderabbit.yaml
• .github/workflows/ci.yml
• CLAUDE.md

---

Walkthrough

This PR establishes three coordinated enforcement layers to maintain repo hygiene: a Claude hook that detects stale references during file moves, a CI audit that validates Dockerfile source paths, and CodeRabbit rules paired with documented discipline standards for file moves and architectural diagram synchronization.

Changes

Repository discipline and file-move/reference enforcement

Layer / File(s)	Summary
File-move detection hook implementation .claude/scripts/check-file-moves.sh, .claude/settings.json	Adds a PostToolUse Bash hook that intercepts git mv and git rm commands, extracts old paths, greps the repo for lingering references across source/docs/config files, and emits JSON context to Claude if matches are found. Wired into .claude/settings.json as a Bash matcher hook.
CI Dockerfile source-path audit .github/workflows/ci.yml	Inserts a "Broken-COPY audit" step into the CI build job that parses all Dockerfiles for COPY/ADD instructions, skips cross-stage and glob patterns, checks that all remaining source paths exist in the repo, and fails the build if any are missing.
CodeRabbit path rules and discipline documentation .coderabbit.yaml, CLAUDE.md	Adds CodeRabbit path_instructions that require paired doc/diagram updates when AppHost.cs or Extensions.cs change. Documents two new repo discipline rules in CLAUDE.md: file-move discipline (with enumerated grep targets and enforcement layers) and doc-and-diagram discipline (specifying doc/diagram pairings, pairing constraints, and rebuild scripts).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/prevent-future-doc-drift

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!