architecture-drift-check

name	architecture-drift-check
description	Use when the user asks whether architecture docs are stale, whether docs and code still match, whether to validate before refresh, or when map validate needs semantic drift checks beyond schema validation.

Architecture Drift Check

Mission

Determine whether hello-scholar architecture assets still match the repository. This is a semantic drift review, not a refresh. Report evidence-backed stale areas and recommend precise updates.

Boundaries

• Read only by default.
• Do not rewrite architecture-map.json unless the user explicitly asks for refresh/update.
• Follow the native architecture boundary in ../references/native-boundaries.md; do not read .env secrets.
• Do not silently delete stale claims. Report them.
• Treat hello-scholar map validate as a structural check, then add semantic checks.

Load Reference

Read ../references/native-boundaries.md and references/drift-checklist.md before starting.

Workflow

1. Run structural validation when possible.
   • Prefer hello-scholar map validate; if commands cannot run, mirror the same checks manually and say so.
   • Check schema version, required arrays, edge endpoints, diagram paths, confidence values, and path references.
2. Establish revision context.
   • Read project.generatedAt and project.sourceRevision from the map.
   • Compare with current git revision when available.
   • Treat revision mismatch as a drift signal, not automatic failure.
3. Compare repository surfaces against map sources.
   • manifests, package scripts, catalogs, entrypoint files, routes, agents, skills, profiles, tests, runtime stores.
4. Check node and edge freshness.
   • stale paths
   • deleted modules
   • nodes with missing evidence
   • new entrypoints not represented
   • changed command/profile/skill/agent catalogs
5. Check view and flow quality.
   • diagram references exist
   • view nodes and edges still exist
   • flows still match command/request/startup/experiment lifecycle
   • inferred edges that can now be verified are flagged
6. Compare companion artifacts.
   • Markdown views should agree with JSON facts.
   • Mermaid should not mention missing nodes or edges.
   • README/AGENTS claims should not contradict code-backed map facts.
7. Report findings with severity.
   • Error: broken schema/reference or deleted path that invalidates a node/edge/flow.
   • Warning: likely stale or missing coverage but map is still usable.
   • Info: improvement opportunity or inferred claim to verify.

Output Contract

Use this structure:

1. Drift Summary: current map status and generated revision/date.
2. Errors: broken references or invalid facts.
3. Warnings: stale paths, missing nodes, undocumented entrypoints, changed catalogs.
4. Inferred Claims To Verify: weak edges or nodes that deserve code evidence.
5. Suggested Refresh Plan: exact views/nodes/flows to update.
6. Commands: validation/view/export commands when useful.

Quality Bar

• Cite paths for every drift finding.
• Separate map defects from code defects.
• Do not refresh automatically.
• Prefer precise remediation over generic "regenerate map" advice.