Skip to content

Commit 995f97a

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
feat: deploy UX Manifesto infrastructure
Adds quickstart guides, contractiles, doctor/heal/tour recipes, LLM warmup scripts, guix.scm, and fixes hardcoded paths. Part of the UX Manifesto "Impossible to Criticise" campaign. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 2331c8c commit 995f97a

14 files changed

+1179
-2
lines changed

‎.machine_readable/ADJUST.contractile‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
; SPDX-License-Identifier: PMPL-1.0-or-later
2+
; ADJUST.contractile — Accessibility invariants for hyperpolymath.github.io
3+
; "ADJUST" = Accessibility & Digital Justice for Universal Software & Technology
4+
;
5+
; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST
6+
; This file is machine-readable. LLM/SLM agents MUST NOT violate these invariants.
7+
8+
; ── Definitions ──────────────────────────────────────────────────
9+
;
10+
; ADJUST (noun/verb)
11+
; The accessibility contractile. Defines how software must adapt to serve
12+
; all users regardless of ability, device, or context. Named for the verb
13+
; "adjust" — to make suitable, to adapt, to accommodate — which is the
14+
; core action of accessible design.
15+
;
16+
; Scope:
17+
; ADJUST governs all user-facing interfaces: GUI, TUI, CLI, web, mobile,
18+
; documentation, error messages, and installation flows. It applies to
19+
; both human users and assistive technologies (screen readers, switch
20+
; devices, braille displays, voice control).
21+
;
22+
; Relationship to other contractiles:
23+
; - MUST: ADJUST invariants are a subset of MUST — violating ADJUST
24+
; is a MUST violation. ADJUST exists separately because accessibility
25+
; rules are numerous enough to warrant their own file, and because
26+
; LLMs frequently forget accessibility unless explicitly reminded.
27+
; - TRUST: ADJUST does not affect trust levels. All trust tiers must
28+
; respect ADJUST invariants equally.
29+
; - DUST: Deprecating a feature does not exempt it from ADJUST until
30+
; it is fully removed. Deprecated UI must remain accessible.
31+
; - INTENT: ADJUST supports the anti-purpose "this software is NOT
32+
; only for able-bodied users with modern hardware."
33+
;
34+
; Standard: WCAG 2.2 Level AA (minimum)
35+
; https://www.w3.org/WAI/WCAG22/quickref/?levels=aaa
36+
;
37+
; Why a separate file:
38+
; Experience shows LLMs and developers alike treat accessibility as an
39+
; afterthought. By placing invariants in a contractile that is loaded
40+
; at session start, we make it structurally impossible to forget.
41+
;
42+
; ── End Definitions ──────────────────────────────────────────────
43+
44+
(adjust-contractile
45+
(version "1.0.0")
46+
(full-name "Accessibility & Digital Justice for Universal Software & Technology")
47+
(standard "WCAG-2.2-AA")
48+
(repo "hyperpolymath.github.io")
49+
50+
(invariants
51+
; ── Visual ──
52+
(adjust "colour-contrast-ratio >= 4.5:1 for normal text")
53+
(adjust "colour-contrast-ratio >= 3:1 for large text (18pt+ or 14pt+ bold)")
54+
(adjust "no information conveyed by colour alone")
55+
(adjust "no flashing or strobing content (3 flashes/second max)")
56+
(adjust "text resizable to 200% without loss of content or function")
57+
(adjust "focus indicators visible on all interactive elements")
58+
59+
; ── Keyboard ──
60+
(adjust "all interactive elements reachable via keyboard (Tab/Shift+Tab)")
61+
(adjust "no keyboard traps — user can always Tab away")
62+
(adjust "skip navigation link present on pages with repeated blocks")
63+
(adjust "logical focus order follows visual reading order")
64+
65+
; ── Screen reader ──
66+
(adjust "all images have meaningful alt text (or alt='' if decorative)")
67+
(adjust "all form inputs have associated labels")
68+
(adjust "ARIA landmarks used for page regions (main, nav, banner, etc.)")
69+
(adjust "dynamic content updates announced via aria-live regions")
70+
(adjust "semantic HTML used (headings, lists, tables) — not div soup")
71+
72+
; ── Interactive ──
73+
(adjust "touch targets minimum 44x44px on mobile/touch interfaces")
74+
(adjust "error messages identify the field and describe the error")
75+
(adjust "error messages not conveyed by colour or position alone")
76+
(adjust "form validation provides suggestions for correction")
77+
78+
; ── Media ──
79+
(adjust "video has captions (closed or open)")
80+
(adjust "audio-only content has text transcript")
81+
(adjust "no autoplay of media with sound")
82+
83+
; ── Motion ──
84+
(adjust "animations respect prefers-reduced-motion media query")
85+
(adjust "no content depends on motion to convey meaning")
86+
87+
; ── CLI/TUI ──
88+
(adjust "CLI output must not rely solely on colour (use symbols: [OK] [FAIL])")
89+
(adjust "TUI must support high-contrast mode")
90+
(adjust "all CLI commands support --help with plain-text output")
91+
(adjust "error messages written in plain language, not jargon or codes alone")
92+
93+
; ── Documentation ──
94+
(adjust "docs use clear language, short sentences, logical structure")
95+
(adjust "code examples include comments explaining non-obvious steps")
96+
(adjust "diagrams have text descriptions or alt text")
97+
98+
; ── Internationalisation (i18n) ──
99+
(adjust "all user-facing strings externalisable for translation")
100+
(adjust "no hardcoded English in error messages — use message keys")
101+
(adjust "date/time/number formats locale-aware")
102+
(adjust "RTL (right-to-left) layout support where applicable")
103+
(adjust "Unicode handled correctly throughout (UTF-8 everywhere)")
104+
)
105+
106+
(related-resources
107+
; LOL — super-parallel corpus crawler for 1500+ languages
108+
; Use for linguistic data, translation coverage, and i18n validation
109+
(lol "standards/lol — multilingual NLP corpus, see README.adoc")
110+
(polyglot-i18n "polyglot-i18n — i18n framework and WASM translation engine")
111+
)
112+
113+
(enforcement
114+
(ci "accessibility linting in quality.yml workflow")
115+
(pr-block "PR blocked if accessibility regression detected")
116+
(tool "axe-core or pa11y for automated checks on web UI")
117+
(tool "CLI output inspected for colour-only signalling")
118+
(manual "manual screen reader test before major releases")
119+
)
120+
121+
(notes
122+
"These are MINIMUM requirements. Exceeding them (AAA) is encouraged."
123+
"When in doubt about an accessibility decision, ask — don't guess."
124+
"Accessibility is not optional polish — it is a structural requirement."
125+
)
126+
)

‎.machine_readable/INTENT.contractile‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
; SPDX-License-Identifier: PMPL-1.0-or-later
2+
; INTENT.contractile — Purpose and scope for hyperpolymath.github.io
3+
; Helps LLM/SLM agents understand what this repo IS and IS NOT.
4+
;
5+
; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST
6+
7+
; ── Definitions ──────────────────────────────────────────────────
8+
;
9+
; INTENT (noun)
10+
; The purpose contractile. Defines what this repository IS, what it is
11+
; NOT (anti-purpose), and which architectural decisions are load-bearing.
12+
; Without INTENT, LLMs drift into scope creep, reverse key decisions,
13+
; or add features that belong in a different repo.
14+
;
15+
; Scope:
16+
; INTENT governs the conceptual boundaries of the project — its reason
17+
; for existing, its domain, and its relationship to the ecosystem.
18+
; It does NOT specify implementation details (that's MUST and code).
19+
;
20+
; Relationship to other contractiles:
21+
; - MUST: INTENT explains WHY certain MUSTs exist. If you don't
22+
; understand a MUST, read INTENT first.
23+
; - TRUST: The "ask-before-touching" section in INTENT maps directly
24+
; to TRUST.trust-deny for the most sensitive areas.
25+
; - ADJUST: INTENT's anti-purpose should include "this software is
26+
; NOT only for users with perfect vision/hearing/mobility."
27+
; - DUST: When INTENT changes (repo pivots), related DUST entries
28+
; should be created for the abandoned direction.
29+
;
30+
; ── End Definitions ──────────────────────────────────────────────
31+
32+
(intent-contractile
33+
(version "1.0.0")
34+
(repo "hyperpolymath.github.io")
35+
36+
; === Purpose (what this repo IS) ===
37+
(purpose
38+
"{{ONE_PARAGRAPH_PURPOSE}}"
39+
)
40+
41+
; === Anti-Purpose (what this repo is NOT — prevents scope creep) ===
42+
(anti-purpose
43+
"{{ONE_PARAGRAPH_ANTI_PURPOSE}}"
44+
; Examples:
45+
; "This is NOT a general-purpose database — it solves one specific problem."
46+
; "This is NOT a framework — it is a library with a focused API."
47+
; "This does NOT handle authentication — that is delegated to [other repo]."
48+
)
49+
50+
; === Key Architectural Decisions That Must Not Be Reversed ===
51+
(architectural-invariants
52+
; *REMINDER: List the foundational decisions*
53+
; ("Idris2 for ABI definitions — dependent types prove interface correctness")
54+
; ("Zig for FFI — zero-cost C ABI compatibility")
55+
; ("Elixir for supervision — OTP fault tolerance")
56+
)
57+
58+
; === Sensitive Areas (if in doubt, ask) ===
59+
(ask-before-touching
60+
; *REMINDER: List areas where LLMs should check before modifying*
61+
; "src/abi/ — formal proofs, changes require re-verification"
62+
; "ffi/zig/ — C ABI boundary, changes affect all language bindings"
63+
; ".machine_readable/ — checkpoint files, format is specified"
64+
)
65+
66+
; === Ecosystem Position ===
67+
(ecosystem
68+
(belongs-to "{{MONOREPO_OR_STANDALONE}}")
69+
(depends-on ("{{DEP1}}" "{{DEP2}}"))
70+
(depended-on-by ("{{CONSUMER1}}" "{{CONSUMER2}}"))
71+
)
72+
)

‎.machine_readable/MUST.contractile‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
; SPDX-License-Identifier: PMPL-1.0-or-later
2+
; MUST.contractile — Baseline invariants for hyperpolymath.github.io
3+
; These constraints MUST NOT be violated. K9 validators enforce them.
4+
;
5+
; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST
6+
7+
; ── Definitions ──────────────────────────────────────────────────
8+
;
9+
; MUST (noun/verb)
10+
; The hard-constraint contractile. Defines invariants that are structurally
11+
; required for the repository to function correctly and safely. Violating
12+
; a MUST is always a bug — there are no "soft" MUSTs.
13+
;
14+
; Scope:
15+
; MUST governs code, configuration, CI, and structure. It does NOT govern
16+
; style, preference, or approach — those belong in CLAUDE.md or coding
17+
; standards. MUST is for things that break the project if violated.
18+
;
19+
; Relationship to other contractiles:
20+
; - TRUST: MUST is enforced regardless of trust level. Even maximal-trust
21+
; agents cannot violate MUST constraints.
22+
; - ADJUST: All ADJUST invariants are implicitly MUST invariants too.
23+
; ADJUST exists separately for visibility.
24+
; - INTENT: MUST protects the architectural decisions described in INTENT.
25+
; - DUST: When a feature enters DUST (deprecation), its MUST constraints
26+
; remain active until the feature is fully removed.
27+
;
28+
; Enforcement:
29+
; K9 validators in contractiles/k9/ machine-check MUST constraints.
30+
; CI runs these on every PR. Violations block merge.
31+
;
32+
; ── End Definitions ──────────────────────────────────────────────
33+
34+
(must-contractile
35+
(version "1.0.0")
36+
(repo "hyperpolymath.github.io")
37+
38+
; === Universal Invariants (apply to ALL repos) ===
39+
40+
(invariants
41+
; Paths
42+
(must "no hardcoded absolute paths (/home/*, /mnt/*, /var/mnt/*)")
43+
(must "all paths use env vars, XDG dirs, or relative references")
44+
45+
; Language policy
46+
(must "no new TypeScript files")
47+
(must "no new Python files")
48+
(must "no new Go files")
49+
(must "no npm/bun/yarn/pnpm dependencies — Deno only")
50+
51+
; Dangerous patterns
52+
(must "no believe_me (Idris2)")
53+
(must "no assert_total (Idris2)")
54+
(must "no Admitted (Coq)")
55+
(must "no sorry (Lean)")
56+
(must "no unsafeCoerce (Haskell)")
57+
(must "no Obj.magic (OCaml)")
58+
(must "no unsafe {} blocks without safety comment (Rust)")
59+
60+
; License
61+
(must "SPDX-License-Identifier header on every source file")
62+
(must "no removal or modification of LICENSE file")
63+
64+
; Structure
65+
(must ".machine_readable/ directory preserved")
66+
(must "0-AI-MANIFEST.a2ml preserved")
67+
(must "no SCM files in repo root — only in .machine_readable/")
68+
69+
; CI
70+
(must "no removal of CI workflows without explicit approval")
71+
(must "all GitHub Actions SHA-pinned")
72+
73+
; Code quality
74+
(must "tests must not be deleted or weakened")
75+
(must "generated code in generated/ directory only")
76+
(must "no introduction of OWASP top 10 vulnerabilities")
77+
78+
; ABI/FFI (if applicable)
79+
(must "no modification of ABI contracts without proof update")
80+
(must "no removal of formal verification proofs")
81+
)
82+
83+
; === Project-Specific Invariants ===
84+
; *REMINDER: Add invariants specific to this repo*
85+
; (must "# Add project-specific invariants here")
86+
87+
(enforcement
88+
(k9-validator "contractiles/k9/must-check.k9.ncl")
89+
(ci "quality.yml runs must-check on every PR")
90+
)
91+
)

‎.machine_readable/TRUST.contractile‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
; SPDX-License-Identifier: PMPL-1.0-or-later
2+
; TRUST.contractile — Trust boundaries for hyperpolymath.github.io
3+
; Defines what LLM/SLM agents are trusted to do without asking.
4+
;
5+
; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST
6+
7+
; ── Definitions ──────────────────────────────────────────────────
8+
;
9+
; TRUST (noun/verb)
10+
; The permission contractile. Defines the boundary between what an AI
11+
; agent may do autonomously and what requires human approval. Trust is
12+
; graduated — not binary — with four levels from minimal to maximal.
13+
;
14+
; Trust levels:
15+
; - maximal: Agent may read, build, test, lint, format, heal freely.
16+
; Only destructive/external actions require approval.
17+
; - standard: Agent may read and build. Test/lint need approval.
18+
; - restricted: Agent may read only. All modifications need approval.
19+
; - minimal: Agent may read specific files only. Everything else blocked.
20+
;
21+
; Scope:
22+
; TRUST governs AI agent behaviour only. It does not affect human
23+
; contributors — humans follow CONTRIBUTING.md and GOVERNANCE.adoc.
24+
;
25+
; Relationship to other contractiles:
26+
; - MUST: Trust never overrides MUST. Even at maximal trust, MUST
27+
; violations are blocked.
28+
; - ADJUST: Trust does not exempt from ADJUST. All trust tiers must
29+
; produce accessible output.
30+
; - INTENT: TRUST.trust-deny protects the sensitive areas listed in
31+
; INTENT.ask-before-touching.
32+
; - DUST: Deprecated features have the same trust rules as active ones.
33+
;
34+
; ── End Definitions ──────────────────────────────────────────────
35+
36+
(trust-contractile
37+
(version "1.0.0")
38+
(repo "hyperpolymath.github.io")
39+
40+
(trust-level "maximal") ; maximal | standard | restricted | minimal
41+
42+
; === Maximal Trust (default) ===
43+
; LLM may freely do these without asking:
44+
(trust-actions
45+
"read" ; Read any file in the repo
46+
"build" ; Run build commands
47+
"test" ; Run test suites
48+
"lint" ; Run linters and formatters
49+
"format" ; Auto-format code
50+
"doctor" ; Run self-diagnostics
51+
"heal" ; Attempt automatic repair
52+
"git-status" ; Check git status
53+
"git-diff" ; View diffs
54+
"git-log" ; View history
55+
)
56+
57+
; === Denied Actions (always require human approval) ===
58+
(trust-deny
59+
"delete-branch" ; Could lose work
60+
"force-push" ; Overwrites history
61+
"modify-ci-secrets" ; Security sensitive
62+
"publish" ; External visibility
63+
"push-to-main" ; Protected branch
64+
"delete-files-bulk" ; More than 5 files at once
65+
"modify-license" ; Legal implications
66+
"modify-security-policy" ; Security implications
67+
"remove-proofs" ; Formal verification regression
68+
"disable-ci-checks" ; Safety regression
69+
)
70+
71+
; === Trust Boundary ===
72+
(trust-boundary "repo") ; LLM confined to this repo unless explicitly told otherwise
73+
74+
; === Override ===
75+
; Repos requiring tighter trust override these settings with justification:
76+
; (override
77+
; (trust-level "restricted")
78+
; (reason "Contains production secrets / handles PII / etc.")
79+
; )
80+
)

0 commit comments

Comments
 (0)