Knowledge Module Contract

Extends Knowledge Source Hierarchy and ADR 002: Standards Precedence. This document defines the purpose, structure, consumption modes, and governance requirements for A11YSmith knowledge modules.

Purpose

A knowledge module is a structured representation of accessibility knowledge for a specific domain and topic. It serves two distinct consumers:

Generators — consume all fields to inject knowledge into agent prompts at generation time
Runtime rules — consume only deterministic subsets (thresholds, role mappings, validation tables)

Knowledge modules are not raw documentation. They are structured data with explicit source traceability, normative strength tagging, and TAS-first content ordering.

Interface

The full TypeScript interface is defined in packages/agents/src/knowledge/types.ts. Key types:

KnowledgeModule — complete module with all fields
KnowledgeModuleIndex — minimal metadata for indexing and discovery
GuidanceBlock — a single block of instructional guidance
IssuePriorityHints — Target issue priority and timeline data
TestBaseline — browsers, ATs, devices, and test procedures

Two-Layer Architecture

Layer 1: Structured Standards Data (Runtime-Safe)

These fields can be consumed by runtime rule engines:

Layer 1 fields for runtime consumption
Field	Purpose
`normativeRefs`	Standard IDs this module implements
`ruleMappings`	A11YSmith rule IDs
`thresholds`	Numeric values (contrast ratios, target sizes)
`roleMappings`	Element-to-role lookup tables
`validationTables`	Structured validation data
`mappingStatus`	How TAS entries map to automation

Constraint: Layer 1 fields must be deterministic and machine-consumable. No narrative, no broad prose, no ambiguous advisory.

Layer 2: Instructional Guidance (Generator-Only)

The guidanceBlocks array contains instructional content for agent prompt generation.

Constraint: guidanceBlocks MUST NOT be consumed by runtime rule engines. They exist solely for generator injection into agent prompts.

Each GuidanceBlock carries:

GuidanceBlock fields
Field	Purpose
`title`	What the block covers
`content`	Markdown guidance text
`sourceTier`	Which tier (1-4) this derives from
`normativeStrength`	`requirement` / `recommendation` / `example`
`contentTag`	Template insertion tag

TAS-First Fields

Every knowledge module must specify:

Required TAS-first fields
Field	Required	Purpose
`tasIds`	Yes	TAS standard IDs — primary authority
`tasTitles`	Yes	Human-readable TAS titles
`wcagFallbackIds`	Yes	WCAG SC IDs — fallback only
`sourceTier`	Yes	Which tier drives primary content
`sourceAuthority`	Yes	Source authority label
`normativeStrength`	Yes	How strongly primary content binds

Resolution follows the Knowledge Source Hierarchy: TAS first, WCAG only when TAS is broad or silent.

Target Operational Context

Optional but strongly recommended:

Optional operational context fields
Field	Purpose
`issuePriorityHints`	Severity, timeline, escalation from Target guidance
`testBaseline`	Browsers, screen readers, devices, test procedures
`platformScope`	Which platforms apply (web, android, ios)
`audienceScope`	Which audiences (developers, consultants, designers)

Governance Requirements

Every module must include a governance block:

Governance block fields
Field	Required	Purpose
`owner`	Yes	Who owns this module
`lastVerified`	Yes	ISO date of last verification
`sourceDocument`	Yes	Approved source file or path
`sourceTitle`	Yes	Human-readable source title
`sourceVersion`	No	Document version if available
`sourceUrl`	No	Internal URL if available
`verifiedBy`	Yes	Who verified against approved source
`verificationDate`	Yes	ISO date of verification

What Goes In a Knowledge Module

TAS pattern requirements with IDs and titles
Platform implementation techniques (Tier 2)
Deterministic thresholds and lookup tables
Structured failure patterns with TAS citations
Fix patterns and code examples tagged with contentTag
Test procedures using Target technology baseline

What Does NOT Go In a Knowledge Module

Raw documentation or prose copied verbatim from source docs
Narrative explanations that could drift from normative source
Broad advisory without a credible normative or experience-based source
Tool-specific content tied to one testing tool version
Content likely to become stale within 6 months
Content not useful to at least one Target audience

Content Tags

Use these tags on GuidanceBlock entries to mark authority level:

Content authority tags
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

Consumption Modes

Generator Consumption (All Fields)

Generators read the full module and inject content into agent prompts:

Module → Generator → Agent template with TAS-tagged sections

Generators must:

Order content by source tier (Tier 1 first)
Apply content tags to each injected block
Preserve normative strength distinctions

Runtime Consumption (Deterministic Subsets Only)

Rule engines read only Layer 1 fields:

Module.thresholds → Rule engine → Finding
Module.roleMappings → Rule engine → Finding
Module.validationTables → Rule engine → Finding

Rule engines must NOT read guidanceBlocks.

Relationship to Existing Modules

The existing knowledge modules in packages/agents/src/knowledge/web/*.ts predate this contract. They export ad-hoc constants and functions. During Phase 1 (Epic 1.2), the forms module will be the first to conform to this interface as a proof of concept. Remaining modules will be migrated in Phase 2 (Epic 2.1).

Existing modules remain valid as-is until migration. The contract does not require retroactive changes — it defines the target shape for new and upgraded modules.