Add a human-ratified /sanity/ architecture-coherence view to Repository Intelligence

[szmyty]

Outcome

Add a first-class /sanity/ route to Repository Intelligence that presents architecture coherence in a human-friendly way while preserving a strict distinction between AI/reviewer assessment and explicit human ratification.

The friendly route name is intentionally memorable. The formal semantics come from:

• Aether architecture-coherence review: egohygiene/aether#87
• Hygiene applicability/ratification policy: egohygiene/hygiene#59
• Observatory normalized review/ratification model: egohygiene/observatory#21

Core question

The page should help a maintainer answer:

Does this architecture still make sense to me, can I explain why its pieces exist, what concerns does the evidence raise, and have I explicitly accepted the current architecture as an intentional basis for continued work?

This is not an AI certification page.

UX principle

The default experience should feel like a compact architecture sanity check rather than a dense governance dashboard.

A useful hierarchy:

1. Architecture in plain English
2. What owns what
3. How the pieces connect
4. What looks strong
5. What deserves skepticism / human attention
6. What changed since the last accepted review
7. Human ratification state
8. Deep links to evidence

No fake meter

Do not produce one opaque numeric "sanity score" such as 87/100.

If a meter-like visual is useful, use explicit independent dimensions such as:

• ownership clarity;
• dependency coherence;
• source-of-truth clarity;
• complexity justification;
• architecture/document alignment;
• unresolved architecture questions;
• evidence freshness;
• human review status.

Each dimension must expose the underlying evidence/state and may be unknown or not applicable.

The most prominent overall state should be the human ratification state, not an AI score.

Required sections

Architecture summary

Provide a concise current explanation of:

• purpose;
• major components/repositories/modules;
• ownership boundaries;
• main data/control flow;
• important dependencies;
• major architecture decisions;
• current architectural maturity/known incompleteness.

Architecture map

Where structured relationship data exists, render an accessible diagram/map with:

• components;
• ownership;
• dependency direction;
• canonical source links;
• key trust/data boundaries;
• clear distinction between authoritative and inferred edges.

The text-equivalent view must remain first-class.

Reviewer assessment

Show the latest AI/reviewer assessment separately:

• represented revision;
• review date/freshness;
• confidence;
• strengths;
• concerns;
• contradictions;
• potentially unjustified complexity;
• missing/unowned responsibilities;
• alternatives/counterarguments;
• unresolved questions;
• recommended disposition.

Never style a model recommendation as human approval.

Human ratification

Show an explicit state such as:

• not reviewed;
• review due;
• review in progress;
• ratified;
• ratified with notes;
• revision required;
• rejected;
• deferred;
• stale;
• not applicable/unavailable.

When ratified, show the exact represented revision/review and any notes/caveats.

What changed since ratification

When possible, summarize only material architecture changes since the ratified state:

• accepted/superseding ADRs;
• ownership changes;
• new dependencies;
• new persistent data boundaries;
• trust/security changes;
• major runtime/framework changes;
• significant architecture-document changes.

Do not flood the page with ordinary implementation commits.

Human review queue

Surface unresolved questions that actually require human judgment, such as:

• "Should these two repositories remain separate?"
• "Is this dependency direction intentional?"
• "Does this abstraction still earn its complexity?"
• "Which repository is the canonical owner of this capability?"

Questions must link to their source evidence and should never auto-resolve.

Ratification interaction boundary

The static/public Repository Intelligence page may render ratification state and guidance, but it must not silently mutate governance records.

If an authenticated/manual workflow is later supported, ratification must still require a deliberate explicit action and create durable review evidence.

A simple initial implementation may present the exact command/workflow needed to record the human disposition elsewhere.

Relationship to other routes

Cross-link without collapsing semantics:

• /decisions/ — why consequential architecture choices were made;
• /dependencies/ — detailed dependency evidence;
• /audits/ — broader findings/risks/opportunities;
• /hygiene/ — contract conformance;
• /health/ — operational posture;
• /roadmap/ — intended future architecture work.

/sanity/ is the human architecture alignment checkpoint across those sources.

Partial / missing data

• No architecture review → not reviewed, not green.
• No human ratification → unratified, regardless of AI opinion.
• Stale architecture evidence → explicit stale/unknown state.
• Inaccessible/private evidence → unavailable without leaking details.
• Missing architecture docs → call out missing evidence rather than fabricating a complete model.

Accessibility and cognitive load

• readable mobile-first summary before diagrams/tables;
• keyboard navigation and screen-reader semantics;
• no color-only state;
• text alternative for diagrams;
• reduced-motion support;
• progressive disclosure for deep evidence;
• avoid jargon in the primary explanation where plain language is possible.

Acceptance criteria

• /sanity/ exists as a first-class Repository Intelligence route.
• AI/reviewer assessment and human ratification are visually and semantically separate.
• The page shows a plain-language architecture explanation before detailed evidence.
• Ownership, dependencies, source-of-truth boundaries, complexity concerns, and unresolved questions are visible.
• No opaque universal numeric architecture score is used.
• Any dimension/meter visualization exposes explicit evidence/state and supports unknown/not-applicable.
• Human ratification is the primary overall architecture-alignment state.
• Material changes since ratification can make the view stale/review-due without reacting to every commit.
• Review-due, unreviewed, stale, revision-required, deferred, unavailable, and ratified states render honestly.
• Deep links reach canonical architecture, ADRs, reviews, audits, issues, and represented revisions where authorized.
• The route integrates with the shared Repository Intelligence shell and deterministic publication.
• Responsive, keyboard, screen-reader, text-equivalent, and reduced-motion behavior is verified.

Dependencies / related

• Parent Repository Intelligence: Build the Repository Intelligence experience #27
• Architecture review skill: egohygiene/aether#87
• Ratification policy: egohygiene/hygiene#59
• Normalized read model: egohygiene/observatory#21
• /audits/: Add an evidence-first /audits/ view to Repository Intelligence #74
• /hygiene/: Add a contract-first /hygiene/ view to Repository Intelligence #75
• /dependencies/ and /health/: Add supporting intelligence views for dependencies, health, releases, work, search, and compare #29

Non-goals

• Letting AI ratify architecture.
• Replacing ADRs, audits, Hygiene, or CI.
• Automatically redesigning the architecture.
• Treating complexity as inherently bad.
• Hiding uncertainty behind a single score.