confidence-engine/.claude/architecture-guardrails.md

Architecture Guardrails

Hard boundary for UX tasks

When a task is described as UI, UX, layout, styling, loading feedback or presentation work, do not modify:

• reasoning algorithms;
• unknown selection;
• reasoning-pattern selection;
• question formulation;
• atomicity or answerability assessment;
• graph mutation;
• graph schemas;
• API request or response contracts;
• reconstruction prompts;
• provider configuration;
• confidence propagation;
• compatibility validation.

If a UX request appears to require one of those changes, stop and report the dependency rather than changing it silently.

Reasoning invariants

Preserve these invariants:

• The LLM proposes information; deterministic code owns graph mutation.
• Every user-facing question comes from an explicit unresolved graph node.
• Questions contain one primary concept and seek one coherent answer.
• Unknowns must be atomic or decomposed.
• Atomic wording alone is insufficient; a selected unknown must be independently answerable.
• Question family must match the active reasoning pattern.
• Active investigation nodes must be compatible with the reasoning pattern.
• Relationship classification cannot outrun comparability assessment.
• Ambiguity remains explicit rather than being resolved alphabetically.
• Parent unknowns do not resolve before their completion rule is satisfied.
• Confidence must not outrun evidence or completeness.
• Duplicate evidence must not increase confidence.
• Conflicting evidence caps conclusion confidence.
• A successful update must rerun deterministic next-question selection when eligible unknowns remain.
• No question is preferable to an unjustified question.

Current architecture, simplified

Scenario → reconstruction → situation graph → unknown selection → atomicity → answerability → reasoning pattern → investigation strategy → question family → question formulation → complexity validation → user answer → proposed graph update → deterministic validation/application → propagation → confidence/completeness update → next unknown

Compatibility discipline

Do not expand schemas merely because a model emits a synonym.

Prefer:

1. identify the source;
2. determine whether it is a synonym;
3. normalise deterministically when justified;
4. retain strict validation.

Do not weaken validation globally to fix a single malformed response.