Knowledge Source Hierarchy

Extends ADR 002: Standards Precedence and Standards Ingestion. This document defines the source precedence model, resolution algorithm, citation format, and conflict handling that all A11YSmith agents, knowledge modules, templates, and severity outputs must follow.

Source Precedence Order

Every knowledge lookup, agent resolution, template section, and finding citation must follow this tiered precedence. Higher tiers override lower tiers when both apply.

Source precedence tiers
Tier	Source	Role	Resolution behavior
1	TAS Patterns and Practices	Primary normative authority	TAS-specific requirement wins. Always cite TAS ID.
2	Target platform implementation guidance	Platform detail when TAS is broad	Confirm implementation technique. Cite alongside TAS.
3	Target issue priority + technology baseline	Severity, timing, and validation context	Drive severity hints, fix urgency, and AT test matrix.
4	WCAG 2.2 AA + official platform vendor docs	Fallback when TAS is silent or broad	Cite only when TAS does not answer precisely.
5	Human review required	Conflict resolution	Flag when sources conflict or case is novel.

Tier 1: Target Normative Sources

These are the default authority for all Target-facing accessibility work.

Accessibility at Target
Accessibility Standards Overview
All TAS Patterns (component-level requirements)
All TAS Practices (cross-cutting guidance)
Issue Priority and Timelines
Technology Baseline
Tools page (where it defines approved testing expectations)

Tier 2: Target Implementation Guidance

These fill in platform detail when TAS is broad or pattern-level.

Android Accessibility Techniques repository
iOS SwiftUI Accessibility Techniques repository
Keyboard-only testing guidance (including mobile keyboard procedures)
Any combined standards document already in use for AI experiments

Tier 3: Design-System and Product-Pattern Context

These drive product-shape reasoning.

Canvas and Nicollet accessibility and component guidance
Content design and written content guidance (where naming and labeling matter)
Inclusive Product Design Playbook (where it adds Target-specific inclusive design framing)

Tier 4: External Fallback Sources

Use only when the Target layers are not specific enough.

WCAG 2.2 JSON and official Understanding documents
Apple developer documentation
Android developer documentation
ARIA Authoring Practices Guide (APG)
HTML specification

Resolution Algorithm

When an agent, knowledge module, or rule needs to answer an accessibility question:

Check Tier 1: Does TAS have a specific pattern or practice that addresses this? If yes, resolve from TAS. Cite the TAS ID.
If TAS is broad: Check Tier 2 Target platform technique guidance. Resolve with platform-specific detail. Cite both TAS ID and technique reference.
If TAS is broad and no platform technique applies: Check Tier 3 for severity, timing, or validation context. Apply issue priority hints and test baseline.
If Target guidance is absent: Check Tier 4 (WCAG 2.2 AA + platform vendor docs). Resolve from external sources. Cite WCAG SC ID.
If sources conflict: Do not silently prefer one source. Flag for human review (Tier 5).

Decision Rules

Never emit a WCAG-only finding without first attempting to map it to a TAS pattern or practice. (Carried forward from standards-ingestion.md rule 4.)
If both TAS and WCAG apply, report both, but lead with Target framing. (Carried forward from standards-ingestion.md rule 5.)
A TAS practice that is broad or cross-cutting does not automatically imply a detection rule. Practices may be represented as guidance-only, testing-baseline, or reviewer expectations.

Citation Format

In Agent Prompts and Templates

TAS-sourced requirement: [TAS: TGT-FORMS-001]
WCAG fallback: [WCAG: 1.3.1]
Platform technique: [Target-Android: content-description-technique]
Combined: [TAS: TGT-FORMS-001] [WCAG: 1.3.1]

In Structured Output (Findings, Knowledge Modules)

Every guidance block and finding must carry:

sourceTier: 1 | 2 | 3 | 4 | 5
normativeStrength: requirement | recommendation | example

Content Tags (for Templates)

Use these tags in agent template sections to mark the authority level of each content block:

Content tags and their meanings
Tag	Meaning	Source tier
`[TAS-REQUIREMENT]`	Normative TAS pattern or practice; must be followed	1
`[TAS-GUIDANCE]`	Target implementation or operational guidance	2-3
`[WCAG-FALLBACK]`	WCAG detail used because TAS is broad or silent	4
`[ADVISORY]`	Best practice or recommendation; not normative	Any
`[EXAMPLE]`	Illustrative code, pattern, or scenario	Any

Conflict Handling

When TAS and WCAG or platform docs provide conflicting guidance:

Do not silently resolve. The agent or module must flag the conflict.
Escalation path: Target Accessibility team is the final normative authority for Tier 1 content conflicts.
Product or design-system teams can supply implementation detail but cannot override TAS.
WCAG fills gaps — it does not outrank TAS for Target-facing decisions.

TAS Entry Classification

Every TAS entry ingested into the A11YSmith catalog must be classified with a mapping status:

TAS entry mapping statuses
Status	Meaning
`directly-rule-mapped`	Links to one or more A11YSmith rule IDs
`prompt-guidance-only`	Informs agent behavior but no detection rule exists
`testing-baseline-only`	Defines validation procedure, not a finding source
`issue-priority-only`	Defines severity or timeline, not detection
`needs-human-interpretation`	Too broad or ambiguous for automated mapping

Patterns vs. Practices

TAS content falls into two entry types with different downstream behavior:

Patterns (component-level): Usually support component behavior, detection rules, and prompt workflows. More likely to be directly-rule-mapped.
Practices (cross-cutting): Usually support guidance, testing expectations, and reviewer checklists. More likely to be prompt-guidance-only or testing-baseline-only. Do not force practices into rule mappings.

Relationship to Existing Documents

ADR 002 establishes the policy: TAS is primary, WCAG is fallback. This document operationalizes that policy across the knowledge layer.
standards-ingestion.md describes the catalog API and ingestion process. This document adds the multi-tier resolution model and classification system.
severity-confidence-verdict.md describes the scoring engines. This document adds the requirement that severity outputs distinguish TAS-backed findings from WCAG-fallback and guidance-only recommendations.