Define an architecture-coherence review and human-ratification skill

[szmyty]

Outcome

Define a reusable Aether workflow for architecture coherence review: an AI-assisted, evidence-backed explanation and critique of a repository or organization architecture that ends at an explicit human ratification boundary.

The intended user-facing concept may be called a sanity check, but the canonical contract should avoid pretending that an AI can objectively certify architecture as "sane." The durable semantics are:

AI reconstructs and challenges the architecture → human reviews the explanation and concerns → human explicitly ratifies, requests revision, or defers.

This should extend Aether's existing Reflective Development System rather than introduce a parallel governance model.

Existing foundation

library/organization/specs/methodology/reflector.spec.md already defines:

• a Human Alignment Anchor responsible for scope, architecture, escalation, and continuation approval;
• Recursive Drift as loss of coherence, scope control, or intentionality;
• drift indicators including duplicated responsibility, architecture/implementation divergence, contradictory decisions, and hidden unresolved questions;
• a synchronization-required state that cannot advance without approval;
• explicit human synchronization outcomes such as continue, revise architecture, reduce scope, enter recovery, or complete.

This issue should make that architecture checkpoint concrete and reusable.

Core workflow

resolve represented architecture/revision
        ↓
reconstruct architecture in plain language
        ↓
map components + ownership + dependency direction
        ↓
identify assumptions, contradictions, duplication, gaps, and complexity
        ↓
challenge the design with alternatives / counterarguments
        ↓
produce AI assessment with confidence + evidence
        ↓
HUMAN REVIEW BOUNDARY
        ↓
ratify | ratify-with-notes | revise | reject | defer

Silence or continued implementation must never count as ratification.

Review dimensions

The skill should evaluate, where applicable:

• system purpose and whether the architecture actually serves it;
• repository/component responsibility boundaries;
• source-of-truth ownership;
• dependency direction and cycles;
• cohesion versus unnecessary fragmentation;
• duplicated or overlapping ownership;
• abstractions that have become too broad or too speculative;
• missing responsibilities or unowned concepts;
• coupling between repositories/modules;
• implementation versus documented architecture;
• ADR/roadmap consistency;
• extension points and replaceability;
• operational/deployment/data-flow plausibility;
• security/privacy/trust boundaries;
• maintainability and cognitive load;
• whether complexity is justified by demonstrated requirements;
• whether the current design is still the simplest credible architecture for the stated goals.

The review must distinguish wrong, risky, unverified, intentional trade-off, and simply complex but justified.

Required AI output

Every review should produce both:

1. Human explanation

A concise, low-cognitive-load explanation of:

• what the system is;
• what each major piece owns;
• how information/control flows;
• why major boundaries exist;
• what appears especially strong;
• what appears questionable or hard to justify;
• what the reviewer would change, if anything;
• what remains uncertain.

The explanation should be understandable without requiring the human reviewer to reread the entire architecture corpus.

2. Structured assessment

Machine-readable fields should include at least:

• review ID;
• scope: repository / subsystem / organization;
• represented source revision(s);
• architecture/spec/ADR revisions consumed;
• reviewer/provider metadata where safe;
• review dimensions;
• findings/concerns with evidence and confidence;
• strengths;
• unresolved questions;
• recommended disposition;
• review freshness/staleness inputs;
• human-ratification state and metadata.

Human ratification model

Define explicit states such as:

• unreviewed
• review-in-progress
• ratified
• ratified-with-notes
• revision-required
• rejected
• deferred
• stale

Ratification means only:

A named human alignment authority reviewed the represented architecture and accepted it as an intentional basis for continued work at that revision.

It must not mean:

• objectively optimal;
• bug free;
• contract conformant;
• secure;
• permanent;
• approved by the AI;
• immune to future change.

Staleness semantics

A prior human ratification should become stale or require review when evidence indicates a material architecture change, such as:

• accepted/superseding ADR;
• repository ownership change;
• new cross-repository dependency;
• new persistent data boundary;
• security/trust-boundary change;
• major technology/runtime replacement;
• significant new subsystem;
• architecture document change classified as material;
• explicit human invalidation.

Minor implementation commits should not automatically invalidate the record.

AI self-check / anti-loop requirement

The review procedure must actively resist self-reinforcing AI architecture drift.

Require the reviewer to:

• cite architecture evidence rather than relying on prior AI prose alone;
• identify assumptions inherited from existing documents;
• present at least one credible alternative or counterargument for consequential design choices;
• identify unnecessary complexity even if the architecture is internally consistent;
• separate "this is coherent" from "this is a good trade-off";
• preserve low-confidence concerns instead of turning them into conclusions;
• never self-ratify its own recommendation.

Where practical, support an optional second-pass/challenger review without making multiple models mandatory.

Artifact location

Define a portable canonical record contract. Consumer repositories may project records into a location such as:

architecture/reviews/
  architecture-coherence-<timestamp>.md

or another accepted repository convention.

Do not hard-code the consumer path into the semantic contract if a portable artifact ID is sufficient.

Skill

Add a reusable Aether skill with an explicit name such as:

review-architecture-coherence

The skill should consume canonical architecture, ADR, roadmap, repository, and normalized evidence where available, produce the review artifact, then stop for human ratification.

It must not modify architecture or implementation unless a later separately authorized workflow is invoked.

Acceptance criteria

• A versioned architecture-coherence review contract exists.
• It composes the existing reflector human-alignment/drift semantics instead of duplicating them.
• A reusable Aether skill performs the review in read-only mode.
• Human explanation and machine-readable assessment are both defined.
• System boundaries, ownership, dependency direction, complexity, gaps, drift, and alternatives are considered.
• AI conclusions preserve evidence and confidence.
• At least one credible counterargument/alternative is required for consequential architecture claims.
• Human ratification is explicit and cannot be inferred from silence or continued work.
• Ratification states and staleness rules are versioned.
• AI/provider output cannot self-ratify architecture.
• Review artifacts preserve represented revision and evidence links.
• Fixtures cover coherent, over-engineered, contradictory, incomplete, stale, and insufficient-evidence architectures.
• Aether validation/evaluation/catalog/distribution checks pass.

Related

• reflector specification and Human Alignment Anchor
• auditor specification
• egohygiene/aether#86 — composable audit profiles
• egohygiene/reflector#258 — repository/fleet audit orchestration

Non-goals

• Producing a universal numeric architecture score.
• Automatically blocking development because an AI dislikes a trade-off.
• Replacing ADRs.
• Treating ratification as permanent or objective truth.
• Letting AI approve its own architecture recommendation.
• Automatically implementing proposed architecture changes.