hyperpolymath · hyperpolymath · Jun 2, 2026 · Jun 2, 2026
@@ -1,211 +1,158 @@
 # SPDX-License-Identifier: MPL-2.0
-# Adjustfile — Accessibility Contract for Burble
-# Author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-#
-# Accessibility requirements and compliance for Burble.
-# Voice-first design must be inclusive for all users.
-#
-# Run with: adjust check
-# Fix with: adjust fix (where deterministic fix exists)
+# Adjustfile (A2ML Canonical)
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
 
 @abstract:
-Accessibility requirements and compliance for the Burble voice-first communications platform.
-These requirements ensure Burble is usable by everyone, regardless of ability.
+Adaptive-maintenance contract for Echidna. When an upstream dep,
+toolchain, prover binary, schema, or external API shifts, this file
+declares the migration sequence. Each adjustment is an error code, a
+probe to detect drift, and the deterministic-fix-or-defer recipe.
+
+Error-code namespace: A###
+Run with: just adjust-check
+Apply (where deterministic) with: just adjust-apply
 @end
 
-## Keyboard Accessibility
-
-### keyboard-navigation
-- description: All features accessible via keyboard
-- status: partial
-- probe: test -f server/lib/burble/accessibility/keyboard.ex
-- compliance: WCAG 2.1 AA
-- notes: Basic navigation implemented. Full keyboard-only flow needed.
-- fix: Port PanLL's comprehensive keyboard navigation system
-
-### custom-keybindings
-- description: User-configurable keybindings
-- status: implemented
-- probe: test -f server/lib/burble/accessibility/keyboard.ex
-- compliance: WCAG 2.1 AAA
-- notes: Users can remap PTT, mute, deafen, volume, and room navigation keys
-
-### keyboard-shortcuts-discoverable
-- description: Keyboard shortcuts are documented and discoverable
-- status: missing
-- compliance: WCAG 2.1 A
-- fix: Add keyboard shortcuts help modal in web client
-
-## Visual Accessibility
-
-### high-contrast-mode
-- description: High contrast UI theme
-- status: missing
-- compliance: WCAG 2.1 AA
-- fix: Port PanLL's high-contrast theme system
-- target: CSS variables for contrast ratios >= 4.5:1
-
-### colorblind-support
-- description: Colorblind-friendly color schemes
-- status: missing
-- compliance: WCAG 2.1 AA
-- fix: Implement deuteranopia, protanopia, and tritanopia palettes
-- reference: PanLL's palette system
-
-### font-size-adjustment
-- description: Resizable UI fonts (4 levels: 14-20px)
-- status: missing
-- compliance: WCAG 2.1 AA
-- fix: Port PanLL's font size adjustment system
-- target: User preference persists across sessions
-
-### theme-switching
-- description: Dark/Light/System theme support
-- status: missing
-- compliance: WCAG 2.1 AA
-- fix: Port PanLL's theme system
-- target: Respects OS preference, user override
-
-## Auditory Accessibility
-
-### screen-reader-support
-- description: Full screen reader compatibility
-- status: partial
-- probe: test -f server/lib/burble/accessibility/screen_reader.ex
-- compliance: WCAG 2.1 AA
-- notes: Basic announcements implemented. Needs ARIA attributes and live regions.
-- fix: Complete ARIA implementation in web client
-
-### closed-captions
-- description: Real-time captioning for voice chat
-- status: missing
-- compliance: WCAG 2.1 AA
-- notes: Requires Web Speech API or external STT integration
-- target: 90%+ accuracy for English, configurable display
-
-### visual-notifications
-- description: Visual indicators for audio events
-- status: missing
-- compliance: WCAG 2.1 A
-- notes: Speaking indicators, mute status, connection status
-- fix: Add visual cues that duplicate audio information
-
-### volume-normalization
-- description: Consistent volume levels across users
-- status: missing
-- compliance: WCAG 2.1 AA
-- notes: Prevents sudden loud sounds for sensitive users
-- target: -23 LUFS normalization per EBU R128
-
-## Motor Accessibility
-
-### voice-commands
-- description: Voice-controlled interface
-- status: missing
-- compliance: WCAG 2.1 AAA
-- notes: "Mute", "Deafen", "Join room X", "Volume up/down"
-- target: Web Speech API with fallback to keyboard
-
-### reduced-motion
-- description: Reduced animation options
-- status: missing
-- compliance: WCAG 2.1 AA
-- fix: Port PanLL's animation control (on/reduced/off)
-- target: Respects prefers-reduced-motion media query
-
-### hover-alternatives
-- description: All hover interactions have click alternatives
-- status: partial
-- compliance: WCAG 2.1 AA
-- notes: Some hover tooltips need click-to-show option
-- fix: Audit and add click alternatives
-
-## Cognitive Accessibility
-
-### clear-language
-- description: Simple, consistent terminology
-- status: partial
-- compliance: WCAG 2.1 AAA
-- notes: Technical terms need plain language explanations
-- fix: Add tooltips/glossary for jargon
-
-### predictable-navigation
-- description: Consistent navigation patterns
-- status: partial
-- compliance: WCAG 2.1 AA
-- notes: Navigation structure varies between pages
-- fix: Standardize navigation layout
-
-### error-prevention
-- description: Confirmation for destructive actions
-- status: partial
-- compliance: WCAG 2.1 AA
-- notes: Room deletion has confirmation, others may not
-- fix: Audit all destructive actions
-
-### help-availability
-- description: Context-sensitive help always available
-- status: missing
-- compliance: WCAG 2.1 AAA
-- notes: No persistent help system
-- fix: Add help button with contextual guidance
-
-## Compliance Targets
-
-### wcag-2.1-aa
-- description: WCAG 2.1 AA compliance
-- status: partial
-- target: Full compliance by Q4 2026
-- tracking: https://github.com/hyperpolymath/burble/issues/XXX
-
-### section-508
-- description: U.S. Section 508 compliance
-- status: partial
-- target: Full compliance by Q4 2026
-- notes: Aligns with WCAG 2.1 AA for most requirements
-
-### en-301-549
-- description: EU EN 301 549 compliance
-- status: partial
-- target: Full compliance by Q4 2026
-- notes: EU public sector procurement requirement
-
-## Integration Requirements
-
-### panll-accessibility-port
-- description: Port PanLL's accessibility engine to Burble
-- status: planned
-- reference: /var/mnt/eclipse/repos/panll/tests/accessibility_engine_test.js
-- target: Q2 2026
-
-### k9-accessibility-validator
-- description: Integrate K9 accessibility validator
-- status: planned
-- reference: /var/mnt/eclipse/repos/panll/contractiles/k9/validators/accessibility-baseline.k9.ncl
-- target: Q2 2026
-
-### accessibility-testing
-- description: Add accessibility tests to CI/CD
-- status: planned
-- target: pa11y or axe-core integration
-- compliance: Automated WCAG testing
-
-## Documentation Requirements
-
-### accessibility-guide
-- description: User-facing accessibility guide
-- status: missing
-- target: docs/accessibility/USER-GUIDE.adoc
-- notes: Keyboard shortcuts, screen reader setup, theme switching
-
-### developer-accessibility
-- description: Developer accessibility guidelines
-- status: missing
-- target: docs/accessibility/DEVELOPER.adoc
-- notes: Coding standards, testing requirements, compliance checklist
-
-### compliance-report
-- description: Accessibility compliance report
-- status: missing
-- target: docs/compliance/ACCESSIBILITY.adoc
-- notes: VPAT (Voluntary Product Accessibility Template)
+@requires:
+- section: Toolchain-Adjust
+- section: Dep-Adjust
+- section: Schema-Adjust
+- section: Prover-Adjust
+- section: Workflow-Adjust
+@end
+
+## Toolchain-Adjust
+
+### A001-rust-toolchain-drift
+- description: rust-toolchain.toml pin behind current stable
+- probe: rustc --version | grep -q $(cat rust-toolchain.toml 2>/dev/null | grep channel | cut -d'"' -f2)
+- severity: low
+- adjust: bump rust-toolchain.toml to current stable; run `cargo update --workspace` to refresh transitives
+- defer-if: any pinned-feature crate breaks on bump
+
+### A002-julia-channel-drift
+- description: juliaup default channel mismatches Project.toml `julia` compat
+- probe: julia --version | grep -q "$(grep -E '^julia = ' src/julia/Project.toml | cut -d'"' -f2 | head -1)"
+- severity: low
+- adjust: juliaup default release ; juliaup update
+- defer-if: a key dep (Flux, CUDA, GNN) doesn't yet support new Julia
+
+### A003-chapel-version-bump
+- description: chapel-ci.yml pin behind upstream
+- probe: grep -E '^CHAPEL_VERSION:' .github/workflows/chapel-ci.yml | grep -q '2.8.0'
+- severity: medium
+- adjust: bump CHAPEL_VERSION env in chapel-ci.yml ; verify .deb URL + SHA via curl
+- defer-if: existing chapel source uses removed syntax (out/label keywords, char-quote rules)
+
+### A004-idris2-version-drift
+- description: idris2 binary doesn't match src/abi/echidnaabi.ipkg pin
+- probe: idris2 --version | grep -q "0.8.0"
+- severity: medium
+- adjust: install matching idris2 via guix or upstream binary
+- defer-if: 0.8.0 reserved-keyword rules break src/abi/ (see [[reference_idris2_0_8_0_reserved_keywords]])
+
+### A005-zig-version-drift
+- description: zig binary doesn't match ffi/zig pin
+- probe: zig version | grep -q "0.15"
+- severity: low
+- adjust: install matching zig version
+- defer-if: 0.15 breaking changes hit ffi/zig (see [[reference_zig_015_breaking_changes]])
+
+## Dep-Adjust
+
+### A010-cargo-deps-major-bump-available
+- description: a tracked Cargo dep has a major bump available
+- probe: cargo outdated --workspace --depth 1 2>/dev/null | grep -E '^\w+\s+\S+\s+\S+\s+\d' | head -5
+- severity: low
+- adjust: review changelog; bump via `cargo update -p <crate> --precise <new>`; run full test suite
+- defer-if: major bump introduces API break with no migration path (nom 7→8, rand 0.9→0.10 examples)
+
+### A011-julia-pkg-major-bump-available
+- description: a tracked Julia pkg has a compat-bound bump available
+- probe: julia --project=src/julia -e 'using Pkg; Pkg.status(outdated=true)' 2>&1 | grep -q '⌃'
+- severity: low
+- adjust: review upstream NEWS; bump `[compat]` in Project.toml; Pkg.resolve()
+- defer-if: GNN-stack (Flux/CUDA/GraphNeuralNetworks) interlock requires waiting on co-bump
+
+### A012-dependabot-pr-backlog
+- description: open dependabot PRs accumulating
+- probe: gh pr list --repo hyperpolymath/echidna --author 'app/dependabot' --state open --limit 50 --json number | jq 'length' | grep -q '^0$'
+- severity: low
+- adjust: triage with `just blocked-pr-triage` style sweep; auto-merge low-risk patches
+- defer-if: dependabot phantom-version (e.g. rand 0.10 not on crates.io)
+
+## Schema-Adjust
+
+### A020-capnp-schema-out-of-sync
+- description: crates/echidna-wire/schemas/*.capnp changed but bindings stale
+- probe: git diff --quiet HEAD~10 crates/echidna-wire/schemas/ && git diff --quiet HEAD~10 crates/echidna-wire/src/
+- severity: high
+- adjust: just capnp-gen ; verify Rust/Julia/Idris2/Zig/AffineScript bindings all regenerated
+- defer-if: schema bump requires owner approval (Cap'n Proto IPC is owner-gated per #194)
+
+### A021-graphql-sdl-no-export
+- description: src/interfaces/graphql/schema.rs changed but no SDL file tracked
+- probe: test -f src/interfaces/graphql/schema.graphql
+- severity: medium
+- adjust: cargo test --package echidna-graphql export_schema (writes schema.graphql) ; commit it
+- defer-if: schema considered internal-only
+
+### A022-openapi-spec-drift
+- description: REST handlers changed but OpenAPI spec stale
+- probe: test -f src/interfaces/rest/openapi.json && cargo run -- export-openapi 2>/dev/null | diff -q - src/interfaces/rest/openapi.json
+- severity: medium
+- adjust: regenerate via aide / utoipa ; commit ; CI diff-gate
+- defer-if: aide/utoipa not yet adopted; file follow-up to wire
+
+### A023-verisim-er-schema-drift
+- description: crates/echidna-wire/schemas/verisim_er.capnp diverged from docs/architecture/VERISIM-ER-SCHEMA.md crosswalk table
+- probe: diff <(grep -E '^\| .+ \| .+ \|' docs/architecture/VERISIM-ER-SCHEMA.md) <(parse schema → rows)
+- severity: high
+- adjust: update whichever lags; both must move together
+- defer-if: VerisimDB upstream schema is itself in flux (federation pending)
+
+## Prover-Adjust
+
+### A030-new-prover-added-upstream
+- description: an upstream prover repo bumped to a new release
+- probe: scripts/provision_corpora.sh --status | grep -E 'ahead' | head -1
+- severity: low
+- adjust: pin new tag in scripts/provision_corpora.sh ; just provision-corpora ; just corpus-ingest-saturation <name> ; retrain
+- defer-if: upstream release breaks the extractor (file in src/rust/corpus/<name>.rs)
+
+### A031-prover-kind-enum-expansion
+- description: a new prover backend is wanted (ProverKind::all_core gap)
+- probe: manual — owner identifies
+- severity: medium
+- adjust: add variant to ProverKind enum; implement ProverBackend trait; wire ProverFactory::create; tier-assign in docs/PROVER_COUNT.md
+- defer-if: prover lacks open-source binary distribution
+
+## Workflow-Adjust
+
+### A040-standards-reusable-sha-stale
+- description: a standards-reusable workflow caller is behind current main
+- probe: grep -rE 'uses: hyperpolymath/standards/.+@[0-9a-f]{40}' .github/workflows/ | while read l; do sha=$(echo "$l" | grep -oE '[0-9a-f]{40}'); current=$(gh api repos/hyperpolymath/standards/commits/main --jq .sha); [ "$sha" = "$current" ] || echo STALE; done | head -1
+- severity: low
+- adjust: bump SHA pin; verify the SHA exists via `gh api repos/hyperpolymath/standards/commits/<sha>`
+- defer-if: a recent reusable change introduces breaking input shape
+
+### A041-action-sha-pin-fake
+- description: a 3rd-party action SHA pin is fake (does not exist upstream)
+- probe: scripts/verify-action-shas.sh 2>&1 | grep -q 'FAKE'
+- severity: critical
+- adjust: replace with current real SHA via `gh api repos/<org>/<action>/commits/<branch>`
+- defer-if: never — fake SHA is a supply-chain hazard
+
+### A042-codeql-cron-drift
+- description: codeql cron drifted from standards canonical schedule (monthly per cut 3)
+- probe: grep -A 2 '^on:' .github/workflows/codeql.yml | grep -q 'cron.*0 0 1 \*'
+- severity: low
+- adjust: bump to '0 0 1 * *' monthly; or drop file entirely and let standards reusable provide
+- defer-if: project-specific gate requires more frequent scan
+
+@adjust-philosophy:
+- always check before adjust (every recipe has both)
+- never adjust without an explicit defer-if escape hatch
+- adjustments cascade: bump rust → cargo update → check tests → check ABI → check container
+- prefer the narrowest change that resolves the drift
+@end