feat(release): ship 5.2.0 operational reliability upgrades

- Add markdown scanner config support (.a11y-markdown-config.json)
- Add markdown SARIF export and configurable gate modes (none/error/warning)
- Add workflow_dispatch controls and SARIF artifact upload in a11y-check
- Add orchestrator-specialist dispatch contract validator + CI workflow
- Upgrade web-severity-scoring guidance with v2 calibration/drift metadata
- Add metadata and markup conventions guide + AGENTS/README/docs updates
- Add templates/markdown-config-moderate.json starter profile
- Bump release version to 5.2.0 across plugin.yaml, gemini-extension.json, mcp-server/package.json
- Update CHANGELOG and add RELEASE-5.2.0.md

Notes:
- Intentionally excludes signing/key-management changes per release scope

Author: accesswatch

.github/scripts/markdown-a11y-lint.mjs

@@ -27,6 +27,18 @@ Weights:
 Floor: 0 (minimum score)
 ```
 
+### Scoring Profiles
+
+Use a profile to tune strictness by context while keeping comparable grade bands:
+
+| Profile | Intended Use | Multiplier |
+|---------|--------------|------------|
+| balanced (default) | Standard product delivery | 1.0 |
+| strict | Regulated/public-sector releases | 1.15 |
+| advisory | Early design and prototyping | 0.8 |
+
+Apply the profile multiplier to each final deduction after confidence handling.
+
 ### Formula
 
 ```pseudocode
@@ -43,6 +55,26 @@ The values in the lookup table above are **base deductions** (pre-multiplier).
 
 **Example:** One Critical finding at confirmed confidence = 18 (base) × 1.2 = **21.6 points** deducted → page score 78.
 
+### Calibration Layer (v2)
+
+To reduce false-positive inflation and stabilize trends, apply a calibration coefficient by rule family:
+
+```text
+calibrated_deduction = deduction × calibration_coefficient(rule_family)
+```
+
+Recommended initial coefficients:
+
+| Rule Family | Coefficient | Rationale |
+|-------------|-------------|-----------|
+| Keyboard/focus | 1.1 | High functional impact at runtime |
+| Forms/labels/errors | 1.05 | High completion risk for core tasks |
+| Semantics/structure | 1.0 | Baseline scoring |
+| Link text/context | 0.9 | Higher context variance |
+| Content quality (alt/link clarity) | 0.85 | Needs human review more often |
+
+Update coefficients quarterly from confirmed outcomes. Avoid changing coefficients more than +/-0.1 per cycle.
+
 ## Score Grades
 
 | Score | Grade | Meaning |
@@ -74,6 +106,20 @@ Issues found by all three sources (axe-core + agent review + Playwright behavior
 
 When Playwright is not available, the maximum achievable confidence remains **High (100%)**. The confirmed tier is additive — it never downgrades findings.
 
+### Confidence Drift Guard
+
+Track predicted confidence versus post-triage outcome and compute drift:
+
+```text
+drift = abs(predicted_confidence_score - observed_confirmation_rate)
+```
+
+Operational guideline:
+
+- drift <= 0.10: stable
+- drift 0.11-0.20: tune coefficients and source mapping
+- drift > 0.20: freeze profile changes and run rule-level review
+
 ## Scorecard Format
 
 ### Single Page
@@ -131,6 +177,37 @@ When Playwright is not available, the maximum achievable confidence remains **Hi
 - **Pages improved:** count of pages with higher scores than previous audit
 - **Trend:** improving (score up 5+), stable (within 5), declining (score down 5+)
 
+### Normalized Trend Metric (Cross-Audit)
+
+When audit scope changes between runs, use normalized change:
+
+```text
+normalized_score = raw_score - (scope_variance_penalty)
+scope_variance_penalty = min(10, abs(previous_pages - current_pages) * 0.8)
+```
+
+Use normalized score for trend charts and use raw score for release gates.
+
+## Output Metadata (Recommended)
+
+Include these fields in generated score artifacts for reproducibility:
+
+```yaml
+scoring:
+  model: web-severity-scoring-v2
+  profile: balanced
+  calibrationVersion: 2026-q2
+  confidenceSources:
+    - axe-core
+    - agent-review
+    - playwright
+  failThresholds:
+    critical: 1
+    score: 75
+```
+
+This metadata allows deterministic re-runs and audit-to-audit comparisons.
+
 ## Issue Severity Categories
 
 ### Critical

.github/skills/web-severity-scoring/SKILL.md

@@ -13,6 +13,16 @@ on:
       - "**/*.css"
       - "**/*.scss"
       - "**/*.md"
+  workflow_dispatch:
+    inputs:
+      enforcement_mode:
+        description: "Markdown lint gate mode (none|error|warning)"
+        required: false
+        default: "error"
+      output_format:
+        description: "Markdown lint output format (text|sarif|both)"
+        required: false
+        default: "both"
 
 jobs:
   a11y-lint:
@@ -92,6 +102,9 @@ jobs:
   markdown-lint:
     name: Markdown Accessibility Lint
     runs-on: ubuntu-latest
+    env:
+      A11Y_ENFORCE_MODE: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.enforcement_mode || vars.A11Y_MARKDOWN_FAIL_ON || 'error' }}
+      A11Y_OUTPUT_FORMAT: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.output_format || vars.A11Y_MARKDOWN_FORMAT || 'both' }}
     steps:
       - uses: actions/checkout@v6
 
@@ -101,7 +114,19 @@ jobs:
           node-version: "20"
 
       - name: Run markdown accessibility lint
-        run: node .github/scripts/markdown-a11y-lint.mjs .
+        run: |
+          node .github/scripts/markdown-a11y-lint.mjs . \
+            --fail-on "$A11Y_ENFORCE_MODE" \
+            --format "$A11Y_OUTPUT_FORMAT" \
+            --output artifacts/markdown-a11y.sarif
+
+      - name: Upload markdown a11y SARIF artifact
+        if: always() && (env.A11Y_OUTPUT_FORMAT == 'sarif' || env.A11Y_OUTPUT_FORMAT == 'both')
+        uses: actions/upload-artifact@v4
+        with:
+          name: markdown-a11y-sarif
+          path: artifacts/markdown-a11y.sarif
+          if-no-files-found: ignore
 
   # Optional: GitHub Accessibility Scanner for deployed pages
   # Uncomment and configure URLs to enable automated scanning on PR.

.github/workflows/a11y-check.yml

@@ -0,0 +1,32 @@
+name: Validate Orchestrator Contracts
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '.claude/agents/**'
+      - '.claude/specialists/**'
+      - 'scripts/validate-orchestrator-dispatch.js'
+      - '.github/workflows/validate-orchestrator-contracts.yml'
+  pull_request:
+    paths:
+      - '.claude/agents/**'
+      - '.claude/specialists/**'
+      - 'scripts/validate-orchestrator-dispatch.js'
+      - '.github/workflows/validate-orchestrator-contracts.yml'
+
+jobs:
+  validate-dispatch-contracts:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+
+      - name: Validate orchestrator-specialist dispatch contracts
+        run: node scripts/validate-orchestrator-dispatch.js

.github/workflows/validate-orchestrator-contracts.yml

@@ -156,6 +156,48 @@ description: What this skill provides
 Skill content in markdown...
 ```
 
+### Recommended Metadata (2026)
+
+Use `metadata` for stable machine-readable attributes that improve routing, validation, and release reporting.
+
+Agent frontmatter example:
+
+```yaml
+---
+name: agent-name
+description: What this agent does
+tools: ['read', 'edit', 'search']
+metadata:
+  owner: accessibility-team
+  domain: web|document|github|developer
+  maturity: stable|beta|experimental
+  release-phase: ga|preview
+  capability-tags: ["wcag-2.2", "keyboard", "forms"]
+  dispatch-contract: required|optional
+---
+```
+
+Skill frontmatter example:
+
+```yaml
+---
+name: skill-name
+description: What this skill provides
+metadata:
+  spec-version: "2026-05"
+  model-compatibility: ["copilot", "claude", "gemini"]
+  scoring-model: "v2"
+  compliance-profiles: ["wcag-2.2-aa", "en-301-549"]
+---
+```
+
+Instruction markup guidance:
+
+- Keep one H1 per file.
+- Use explicit `## Decision Matrix` and `## Non-Negotiable Standards` headings for scanners.
+- Prefer checklist-style acceptance criteria sections for automation (`## Acceptance Criteria`).
+- Keep line-based examples in fenced code blocks with explicit language tags.
+
 ## Build & Test
 
 No build step required - agents are markdown files.

AGENTS.md

@@ -5,6 +5,30 @@ All notable changes to the Accessibility Agents project will be documented in th
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.2.0] - 2026-05-06
+
+### Added
+
+- **Markdown scanner config support** via `.a11y-markdown-config.json` in `.github/scripts/markdown-a11y-lint.mjs` with per-rule enable/disable, severity overrides, ignore directory control, and configurable per-rule output limits.
+- **SARIF export support** for markdown accessibility findings (`--format sarif|both`, `--output`) to enable machine-readable CI artifacts.
+- **New template**: `templates/markdown-config-moderate.json` for fast adoption of markdown scanning defaults.
+- **Orchestrator dispatch contract validator**: `scripts/validate-orchestrator-dispatch.js` to enforce required `Specialist Dispatch` sections and verify specialist file references exist.
+- **New CI workflow**: `.github/workflows/validate-orchestrator-contracts.yml` to run dispatch contract validation on PRs and pushes.
+- **New documentation guide**: `docs/guides/metadata-markup-conventions.md` defining recommended metadata and markup conventions for agents, skills, and instruction files.
+
+### Changed
+
+- **`a11y-check.yml` markdown lint job** now supports gate modes (`none|error|warning`) and output modes (`text|sarif|both`) through workflow dispatch inputs and repo variables (`A11Y_MARKDOWN_FAIL_ON`, `A11Y_MARKDOWN_FORMAT`).
+- **`web-severity-scoring` skill** upgraded with v2 guidance: scoring profiles, calibration coefficients, confidence-drift guardrails, normalized trend metric, and recommended scoring metadata fields.
+- **`docs/getting-started.md`** updated with markdown scanner config examples, CI gate mode behavior, and SARIF usage patterns.
+- **`AGENTS.md`** expanded with recommended metadata frontmatter conventions for agents and skills, plus instruction markup conventions.
+- **`README.md`** documentation index now includes the metadata and markup conventions guide.
+
+### Fixed
+
+- **Markdown lint CI resilience** improved by making scanner behavior configurable without code changes.
+- **Orchestrator-specialist drift risk** reduced by adding CI-enforced dispatch contract validation.
+
 ## [5.1.0] - 2026-05-03
 
 ### Added

CHANGELOG.md

@@ -482,6 +482,7 @@ The following guides cover advanced configuration, cross-platform handoff, and d
 |-------|---------------|
 | [Cross-Platform Handoff](docs/advanced/cross-platform-handoff.md) | Seamless handoff between Claude Code and Copilot |
 | [Advanced Scanning Patterns](docs/advanced/advanced-scanning-patterns.md) | Background scanning, worktree isolation, large libraries |
+| [Metadata and Markup Conventions](docs/guides/metadata-markup-conventions.md) | Recommended metadata fields and markdown structure conventions for agents, skills, and instructions |
 | [Plugin Packaging](docs/advanced/plugin-packaging.md) | Packaging and distributing agents for different environments |
 | [Platform References](docs/advanced/platform-references.md) | External documentation sources with feature-to-source mapping |
 | [Experimental Codex Multi-Agent Roles](docs/guides/codex-experimental-multi-agent.md) | Optional TOML-based Codex roles for focused accessibility passes |

README.md

@@ -0,0 +1,99 @@
+# Accessibility Agents 5.2: Calibrated Scoring, Configurable Gates, Stronger Contracts
+
+## Overview
+
+Accessibility Agents 5.2 focuses on operational quality and reliability: configurable markdown accessibility gates, SARIF output for machine-readable CI, calibrated web severity scoring guidance, and contract validation between orchestrators and specialists.
+
+This release intentionally excludes signing and key-management changes.
+
+---
+
+## Highlights
+
+### Configurable Markdown Accessibility Scanning
+
+`markdown-a11y-lint.mjs` now supports:
+
+- repository config file: `.a11y-markdown-config.json`
+- per-rule `enabled` and `severity` overrides
+- custom ignored directories
+- configurable per-rule output limits
+- runtime gate mode controls (`none`, `error`, `warning`)
+
+### SARIF Output for CI Pipelines
+
+Markdown accessibility findings can now be exported as SARIF:
+
+```bash
+node .github/scripts/markdown-a11y-lint.mjs . \
+  --format both \
+  --output artifacts/markdown-a11y.sarif
+```
+
+This enables downstream code-scanning and artifact workflows without custom parsers.
+
+### CI Gate Maturity Controls
+
+`a11y-check.yml` now supports dispatch-time and variable-driven gate controls:
+
+- workflow inputs: `enforcement_mode`, `output_format`
+- repo variables: `A11Y_MARKDOWN_FAIL_ON`, `A11Y_MARKDOWN_FORMAT`
+
+Teams can adopt advisory mode first and tighten enforcement later without editing workflow logic.
+
+### Orchestrator-Specialist Contract Validation
+
+New validator:
+
+- `scripts/validate-orchestrator-dispatch.js`
+
+New workflow:
+
+- `.github/workflows/validate-orchestrator-contracts.yml`
+
+The validator enforces required dispatch sections, verifies `Read(".claude/specialists/*.md")` references, checks `Task(...)` usage, and confirms referenced specialists exist.
+
+### Web Severity Scoring v2 Guidance
+
+`web-severity-scoring` now documents:
+
+- profile-based scoring (`balanced`, `strict`, `advisory`)
+- calibration coefficients by rule family
+- confidence drift guardrails
+- normalized trend scoring for cross-audit comparability
+- recommended output metadata for reproducibility
+
+### New Metadata and Markup Conventions
+
+A new guide standardizes metadata and markdown structure:
+
+- `docs/guides/metadata-markup-conventions.md`
+
+It includes recommended frontmatter metadata patterns for agents and skills and instruction markup conventions for automation-friendly docs.
+
+---
+
+## Additional Docs and Templates
+
+- Added template: `templates/markdown-config-moderate.json`
+- Updated: `docs/getting-started.md` with markdown scanner and CI gate usage
+- Updated: `AGENTS.md` with metadata conventions
+- Updated: `README.md` docs index to include metadata and markup conventions guide
+
+---
+
+## Why This Matters
+
+5.2 improves how teams operate these agents at scale:
+
+- less CI fragility through explicit configuration
+- better interop through SARIF
+- reduced orchestration drift via contract validation
+- more reliable trend analysis through calibrated scoring guidance
+- clearer machine-readable metadata standards for future automation
+
+---
+
+## Full Changelog
+
+See `CHANGELOG.md` for complete details.