chore: machine-readable + contractile currency checkpoint

.machine_readable/agent_instructions/README.adoc → .machine_readable/bot_directives/README.adoc

@@ -1,10 +1,14 @@
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
-= Agent Instructions
+= Bot Directives
 :toc: preamble
 
-Methodology-aware configuration for AI agents. Read by any AI agent
-(Claude, Gemini, Copilot, etc.) at session start.
+Methodology-aware configuration for AI agents and bots. Read by any AI
+agent (Claude, Gemini, Copilot, etc.) or estate bot at session start.
+
+NOTE: This directory was renamed `agent_instructions/` -> `bot_directives/`
+to align with the estate-wide naming convention. Contents (methodology,
+coverage, debt, lessons) are unchanged.
 
 == Files
 
@@ -32,8 +36,8 @@ Methodology-aware configuration for AI agents. Read by any AI agent
 == Relationship to Other Files
 
 * `AGENTIC.a2ml` says WHAT agents can do (permissions, gating)
-* `agent_instructions/` says HOW agents should work (methodology)
-* `bot_directives/` says what the gitbot-fleet does (fleet-specific)
+* This directory (`bot_directives/`) says HOW agents should work — methodology, coverage, debt (the renamed methodology layer)
+* Per-bot fleet directives (hypatia, gitbot-fleet, .git-private-farm) are not yet populated — they will be added here as named files (deferred; see issue)
 * `CLAUDE.md` says how Claude specifically should work (Claude-specific)
 
 == Reference

.machine_readable/contractiles/adjust/Adjustfile.a2ml

@@ -1,211 +1,55 @@
 # SPDX-License-Identifier: MPL-2.0
-# Adjustfile — Accessibility Contract for Burble
+# Adjustfile — Accessibility / drift-tolerance contract for Ephapax
 # 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)
 
 @abstract:
-Accessibility requirements and compliance for the Burble voice-first communications platform.
-These requirements ensure Burble is usable by everyone, regardless of ability.
+Ephapax is a language toolchain (Rust compiler + mechanised metatheory), not a
+GUI application — so conventional WCAG *UI* accessibility largely does not apply.
+This contract deliberately scopes "accessibility" to the surfaces ephapax does
+expose to humans: compiler diagnostics, documentation, and CLI ergonomics.
+Advisory (continue-with-warnings), not a hard gate.
 @end
 
-## Keyboard Accessibility
+## Documentation Accessibility
 
-### keyboard-navigation
-- description: All features accessible via keyboard
+### docs-semantic-asciidoc
+- description: Documentation uses semantic AsciiDoc (heading order, image alt text) for screen-reader/navigation friendliness
 - 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
+- compliance: WCAG 2.1 AA (documents)
+- notes: docs/ is AsciiDoc; audit for alt text and heading order.
 
-## Auditory Accessibility
-
-### screen-reader-support
-- description: Full screen reader compatibility
+### readme-plain-language-summary
+- description: README opens with a plain-language summary before substructural-logic notation
 - 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
+- notes: Linear/affine notation should be preceded by prose intent for non-specialist readers.
 
-## Motor Accessibility
+## Diagnostic Clarity (compiler 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
+### error-messages-actionable
+- description: Type/borrow errors name the offending region/modality and suggest a remedy
 - status: partial
-- compliance: WCAG 2.1 AA
-- notes: Some hover tooltips need click-to-show option
-- fix: Audit and add click alternatives
+- notes: Four-layer (L1–L4) errors should state in plain terms which layer failed (region capability / modality / echo residue / dyadic mode).
 
-## Cognitive Accessibility
+### no-bare-panic-diagnostics
+- description: User-facing failures are structured diagnostics, not raw Rust panics
+- status: declared
+- probe: test -d src/ephapax-typing
+- notes: Track panics reaching the CLI surface; convert to diagnostics.
 
-### 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
+## CLI Ergonomics
 
-### predictable-navigation
-- description: Consistent navigation patterns
-- status: partial
-- compliance: WCAG 2.1 AA
-- notes: Navigation structure varies between pages
-- fix: Standardize navigation layout
+### cli-help-available
+- description: The ephapax CLI exposes --help with usage
+- status: declared
+- notes: Verified in CI via `ephapax --help`; crate-presence proxy here.
 
-### 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
+## Compliance Posture
 
-### en-301-549
-- description: EU EN 301 549 compliance
+### wcag-scope-statement
+- description: Accessibility scope (docs + diagnostics, not GUI) is documented so "N/A" never drifts silently
 - 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)
+- target: docs/accessibility/SCOPE.adoc
+- notes: A compiler core has no GUI surface; an explicit scope statement prevents false-N/A drift.

.machine_readable/contractiles/dust/Dustfile.a2ml

@@ -1,14 +1,15 @@
 # SPDX-License-Identifier: MPL-2.0
-# Dustfile — Cleanup and hygiene contract for Burble
+# Dustfile — Cleanup and hygiene contract for Ephapax
 # Author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 #
 # What should be cleaned up. Housekeeping, not blockers.
 # Run with: dust status
 # Roll back with: dust rollback <name>
 
 @abstract:
-Cleanup and hygiene items for the Burble voice platform.
-These are maintenance tasks — not blocking, but should be addressed.
+Cleanup and hygiene items for Ephapax. Maintenance tasks — not blocking, but
+should be addressed. Destructive actions are dry-run by default and gated
+behind --apply with per-item approval.
 @end
 
 ## Stale Files
@@ -19,60 +20,40 @@ These are maintenance tasks — not blocking, but should be addressed.
 - severity: info
 
 ### no-ai-djot
-- description: AI.djot is superseded by 0-AI-MANIFEST.a2ml
+- description: AI.djot superseded by 0-AI-MANIFEST.a2ml
 - run: test ! -f AI.djot
 - severity: warning
 
-### no-next-steps
-- description: NEXT_STEPS.md superseded by ROADMAP
-- run: test ! -f NEXT_STEPS.md
-- severity: info
+### no-lust-dir
+- description: The lust/ contractile verb was removed estate-wide 2026-04-18 (semantics absorbed into intend)
+- run: test ! -d .machine_readable/contractiles/lust
+- severity: warning
+- notes: Any lust/ dir is drift; horizon/aspiration semantics live in intend now.
 
 ## Build Artifacts
 
-### no-tracked-elixir-build
-- description: No Elixir build artifacts tracked in git
-- run: test -z "$(git ls-files server/_build/ server/deps/ 2>/dev/null)"
-- severity: warning
-
-### no-tracked-rescript-build
-- description: No ReScript build artifacts tracked in git
-- run: test -z "$(git ls-files 'client/web/src/**/*.res.mjs' client/web/lib/ 2>/dev/null)"
+### no-tracked-rust-build
+- description: No Rust build artifacts tracked in git
+- run: test -z "$(git ls-files 'target/' '**/target/' 2>/dev/null)"
 - severity: warning
 
-## Burble-Specific Cleanup
-
-### stale-room-processes
-- description: Room processes should auto-terminate after idle timeout
-- verification: Burble.Rooms.Room uses @idle_timeout_ms (5 minutes)
-- severity: info
-- notes: Not a file check — design verification that idle rooms are cleaned up
-
-### expired-invite-tokens
-- description: Expired invite tokens should be purged periodically
-- verification: Scheduled task purges tokens past expires_at
-- severity: info
-- notes: Planned — not yet implemented
-
-### orphaned-turn-credentials
-- description: TURN credentials expire after 1 hour
-- verification: Burble.Media.Privacy.generate_turn_credential sets TTL
-- severity: info
+## Duplicates
 
-### template-example-trustfile
-- description: Remove the example Trustfile (keep only the real one)
-- run: test ! -f .machine_readable/contractiles/trust/Trustfile_just_an_example.a2ml
+### single-contributing-format
+- description: Prefer a single CONTRIBUTING (DOC-FORMAT prefers .adoc; .md is the GitHub community-health exception)
+- run: test -z "$(test -f CONTRIBUTING.adoc && test -f CONTRIBUTING.md && echo dup)"
 - severity: info
-- rollback: git checkout HEAD -- .machine_readable/contractiles/trust/Trustfile_just_an_example.a2ml
-
-## Format Duplicates
-
-### no-duplicate-contributing
-- description: Only one CONTRIBUTING format
-- run: test -z "$(test -f CONTRIBUTING.md && test -f CONTRIBUTING.adoc && echo dup)"
-- severity: warning
+- notes: Both CONTRIBUTING.adoc and CONTRIBUTING.md currently exist (2026-06-05); owner decides which to retire.
 
 ### no-duplicate-readme
 - description: Only one README format
 - run: test ! -f README.md || test ! -f README.adoc
 - severity: warning
+
+## Formal Archive Hygiene
+
+### preservation-design-is-canonical
+- description: PRESERVATION-DESIGN.md is the canonical design; PRESERVATION-HANDOFF.md is historical diagnostic only
+- run: test -f formal/PRESERVATION-DESIGN.md
+- severity: info
+- notes: HANDOFF carries the pre-discovery record; do not act on it as instructions. Keep both.