chore: sync local state and update contractiles

Author: hyperpolymath

.github/workflows/boj-build.yml

@@ -1,19 +1,48 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
+#
+# OPTIONAL: BoJ Server Build Trigger
+# This workflow notifies a BoJ Server instance when code is pushed.
+# It is a no-op if BOJ_SERVER_URL is not set or the server is unreachable.
+# To enable: set BOJ_SERVER_URL as a repository secret or variable.
+# To disable: delete this file or leave BOJ_SERVER_URL unset.
 name: BoJ Server Build Trigger
+
 on:
   push:
     branches: [main, master]
   workflow_dispatch:
+
+permissions:
+  contents: read
+
 jobs:
   trigger-boj:
     runs-on: ubuntu-latest
+    if: ${{ vars.BOJ_SERVER_URL != '' || secrets.BOJ_SERVER_URL != '' }}
     steps:
       - name: Checkout
-        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
       - name: Trigger BoJ Server (Casket/ssg-mcp)
+        env:
+          BOJ_URL: ${{ secrets.BOJ_SERVER_URL || vars.BOJ_SERVER_URL }}
+          REPO_NAME: ${{ github.repository }}
+          BRANCH_NAME: ${{ github.ref_name }}
         run: |
-          # Send a secure trigger to boj-server to build this repository
-          curl -X POST "http://boj-server.local:7700/cartridges/ssg-mcp/invoke"             -H "Content-Type: application/json"             -d "{\"repo\": \"${{ github.repository }}\", \"branch\": \"${{ github.ref_name }}\", \"engine\": \"casket\\"}"}
-        continue-on-error: true
-permissions:
-  contents: read
+          set -euo pipefail
+
+          if [ -z "$BOJ_URL" ]; then
+            echo "BOJ_SERVER_URL not configured - skipping"
+            exit 0
+          fi
+
+          payload="$(jq -cn \
+            --arg repo "$REPO_NAME" \
+            --arg branch "$BRANCH_NAME" \
+            --arg engine "casket" \
+            '{repo:$repo, branch:$branch, engine:$engine}')"
+
+          curl -sf -X POST "${BOJ_URL}/cartridges/ssg-mcp/invoke" \
+            -H "Content-Type: application/json" \
+            --data "$payload" \
+            || echo "BoJ server unreachable - skipping (non-fatal)"

.github/workflows/casket-pages.yml

@@ -49,6 +49,10 @@ jobs:
 
       - name: Prepare site source
         shell: bash
+        env:
+          REPO_NAME: ${{ github.event.repository.name }}
+          REPO_FULL_NAME: ${{ github.repository }}
+          BRANCH_NAME: ${{ github.ref_name }}
         run: |
           set -euo pipefail
           rm -rf .site-src _site
@@ -58,14 +62,14 @@ jobs:
           else
             mkdir -p .site-src
             TODAY="$(date +%Y-%m-%d)"
-            REPO_NAME="${{ github.event.repository.name }}"
-            REPO_URL="https://github.com/${{ github.repository }}"
+            REPO_NAME="${REPO_NAME}"
+            REPO_URL="https://github.com/${REPO_FULL_NAME}"
             README_URL=""
 
             if [ -f README.md ]; then
-              README_URL="${REPO_URL}/blob/${{ github.ref_name }}/README.md"
+              README_URL="${REPO_URL}/blob/${BRANCH_NAME}/README.md"
             elif [ -f README.adoc ]; then
-              README_URL="${REPO_URL}/blob/${{ github.ref_name }}/README.adoc"
+              README_URL="${REPO_URL}/blob/${BRANCH_NAME}/README.adoc"
             fi
 
             {
@@ -78,12 +82,12 @@ jobs:
               echo
               echo "Static documentation site for ${REPO_NAME}."
               echo
-              echo "- Source repository: [${{ github.repository }}](${REPO_URL})"
+              echo "- Source repository: [${REPO_FULL_NAME}](${REPO_URL})"
               if [ -n "${README_URL}" ]; then
                 echo "- README: [project README](${README_URL})"
               fi
               if [ -d docs ]; then
-                echo "- Docs directory: [docs/](${REPO_URL}/tree/${{ github.ref_name }}/docs)"
+                echo "- Docs directory: [docs/](${REPO_URL}/tree/${BRANCH_NAME}/docs)"
               fi
               echo
               echo "Project-specific site content can be added later under site/."

.github/workflows/dogfood-gate.yml

@@ -38,7 +38,7 @@ jobs:
 
       - name: Validate A2ML manifests
         if: steps.detect.outputs.count > 0
-        uses: hyperpolymath/a2ml-validate-action@main
+        uses: hyperpolymath/a2ml-validate-action@cb3c1e298169dc5ac2b42e257068b0fb5920cd5e # main
         with:
           path: '.'
           strict: 'false'
@@ -86,7 +86,7 @@ jobs:
 
       - name: Validate K9 contracts
         if: steps.detect.outputs.k9_count > 0
-        uses: hyperpolymath/k9-validate-action@main
+        uses: hyperpolymath/k9-validate-action@236f0035cc159051c8dd5dc7cd8af1e8cf961462 # main
         with:
           path: '.'
           strict: 'false'

.github/workflows/instant-sync.yml

@@ -30,4 +30,35 @@ jobs:
             }
 
       - name: Confirm
-        run: echo "::notice::Propagation triggered for ${{ github.event.repository.name }}"
+        env:
+          REPO_NAME: ${{ github.event.repository.name }}
+        run: echo "::notice::Propagation triggered for ${REPO_NAME}"
+
+  - name: K9-SVC Validation
+    run: |
+      echo "Running K9-SVC contractile validation..."
+      if [ -f .machine_readable/contractiles/must/Mustfile.a2ml ]; then
+        echo "✅ Mustfile found - running validation"
+        # Placeholder for actual K9 validation
+        echo "K9 validation would run here"
+      else
+        echo "❌ Mustfile not found"
+        exit 1
+      fi
+      
+  - name: Contractile Check
+    run: |
+      echo "Checking contractile completeness..."
+      contractiles=("must" "trust" "dust" "lust" "adjust" "intend")
+      missing=0
+      for c in "${contractiles[@]}"; do
+        if [ ! -f ".machine_readable/contractiles/$c/${c^}file.a2ml" ]; then
+          echo "❌ Missing: $c"
+          missing=$((missing + 1))
+        fi
+      done
+      if [ $missing -gt 0 ]; then
+        echo "❌ $missing contractiles missing"
+        exit 1
+      fi
+      echo "✅ All contractiles present"

.machine_readable/contractiles/README.adoc

@@ -0,0 +1,19 @@
+= Contractiles Template Set
+:toc:
+:sectnums:
+
+This directory contains the generalized contractiles templates. Copy the `.machine_readable/contractiles/` directory into a new repo to establish a consistent operational, validation, trust, recovery, and intent framework.
+
+== Fill-In Instructions
+
+1. Update the Mustfile to reflect your real invariants (paths, schema versions, ports).
+2. Replace Trustfile.hs placeholders with your actual key paths and verification commands.
+3. Adjust Dustfile handlers to match your rollback and recovery tooling.
+4. Update Intentfile to mirror the roadmap you want the system to evolve toward.
+
+== Contents
+
+* `must/Mustfile` - required invariants and validations.
+* `trust/Trustfile.hs` - cryptographic verification steps.
+* `dust/Dustfile` - rollback and recovery semantics.
+* `lust/Intentfile` - future intent and roadmap direction.

.machine_readable/contractiles/adjust/Adjustfile.a2ml

@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# 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)
+
+@abstract:
+Accessibility requirements and compliance for the Burble voice-first communications platform.
+These requirements ensure Burble is usable by everyone, regardless of ability.
+@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)