Tier vs Relevance

This document defines the difference between tier and relevance metadata.
They solve different problems, apply to different consumers, and must remain independent.

Confusing them leads to bloated context packs, misplaced authority, and degraded agent behavior.

Tier controls how content is surfaced to humans.

It exists to prevent overwhelm in navigation, indexes, and reading flows.

Tier does not imply importance, correctness, or authority.

Allowed Values

• tier: 0 — hidden or internal
• tier: 1 — default surfaced
• tier: 2 — secondary / discoverable
• tier: 3 — deep reference / long-form

Rules

• Tier is UI-facing only
• Tier must never be used to decide context-pack inclusion
• Tier may be omitted on purely agent-facing documents

Relevance controls whether a topic participates in agent context packs.

It answers: "Is this topic useful for making or supporting decisions?"

Allowed Values

• decision — changes what an agent should do next
• supporting — improves correctness and judgment
• background — provides understanding, narrative, or rationale
• routing — helps find other content

Rules

• Relevance is execution-facing
• Relevance does not imply truth ranking
• A document must explicitly declare relevance
• Relevance is evaluated per topic/file, not per heading

Tier controls visibility. Relevance controls usability.
They must never substitute for each other.

• Treating tier: 1 as "important for agents"
• Using numeric tiers to encode execution depth
• Inferring relevance from tier automatically

If any of the above occur, fix the metadata — not the compiler.

• MUST NOT use tier to decide context-pack inclusion; use relevance instead
• MUST NOT infer relevance from tier automatically
• MUST declare relevance explicitly on each document
• MUST keep tier and relevance as independent axes
• MUST fix metadata errors, not compiler behavior, when conflation occurs

• Tier defaults to 2 (secondary/discoverable) when not specified
• Relevance defaults to supporting when not specified
• When uncertain whether content is decision-grade, start at supporting and upgrade based on observed impact
• Treat tier as UI-facing only; treat relevance as execution-facing only

• Tier as Agent Signal: Using tier: 1 to mean "important for agents"
• Numeric Depth Encoding: Using tier numbers to encode execution priority
• Automatic Inference: Deriving relevance from tier programmatically
• Axis Conflation: Treating visibility and usability as the same concern
• Pack Bloat: Including content in context packs based on tier instead of relevance

• Context pack inclusion is determined by relevance, not tier
• Tier assignment reflects human navigation needs only
• Relevance assignment reflects agent decision-making needs only
• Metadata explicitly declares both values when both apply
• Changes to tier do not affect context pack composition