@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-assist/CODE_OF_CONDUCT.md

@@ -0,0 +1,129 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/src/a11y-assist/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing to Ally
+
+Thank you for your interest in contributing to the Ally accessibility toolchain.
+
+Ally is designed as **infrastructure**, not a feature playground.
+Correctness, determinism, and user trust matter more than speed.
+
+Please read this document carefully before submitting changes.
+
+---
+
+## Core principles (non-negotiable)
+
+All contributions must respect these principles:
+
+1. **Additive only**
+   - Ally must never rewrite, hide, or correct ground-truth tool output.
+
+2. **Deterministic**
+   - Same input must always produce the same output.
+   - No randomness, timestamps, or network calls.
+
+3. **SAFE by default**
+   - v0.x must never emit RISKY or DESTRUCTIVE commands.
+   - Suggested commands must appear verbatim in the input.
+
+4. **Confidence-honest**
+   - Confidence may never increase.
+   - If input is ambiguous, Ally must say so.
+
+5. **Guarded**
+   - All profile transforms are subject to the Profile Guard.
+   - Guard violations are engine bugs and must not be bypassed.
+
+---
+
+## What kinds of contributions are welcome
+
+### ✅ Good contributions
+- Bug fixes
+- Documentation improvements
+- Test coverage
+- New profiles (following the profile contract)
+- Reference integrations
+- CI and tooling improvements
+
+### ❌ Not accepted (without major discussion)
+- Auto-fix behavior
+- Executing commands
+- "Smart" inference that invents facts
+- Removing safety checks
+- Making output less explicit to appear "cleaner"
+
+---
+
+## Adding or modifying a profile
+
+Profiles are **policy**, not intelligence.
+
+When proposing a profile:
+1. Document the target audience.
+2. Define exact transformation rules.
+3. Define guard constraints.
+4. Add golden tests.
+5. Prove no new facts or commands are introduced.
+
+If a change cannot be proven safe by tests, it must not ship.
+
+---
+
+## Tests are mandatory
+
+Every PR must include tests that demonstrate:
+- determinism
+- invariant preservation
+- no invented IDs
+- no invented commands
+- correct guard behavior
+
+Golden tests are strongly preferred.
+
+---
+
+## Questions or uncertainty
+
+If you are unsure whether a change aligns with Ally's philosophy:
+- open an issue first
+- describe the problem, not the solution
+
+Maintainers will help guide the decision.
+
+---
+
+## Code of conduct
+
+Be respectful. Be patient. Accessibility work affects real people.
+
+Thank you for helping make developer tools more humane.

package/src/a11y-assist/ENGINE.md

@@ -0,0 +1,363 @@
+# Ally Engine Contract (a11y-assist)
+
+**Status:** Finalized (v0.3.1)
+**Scope:** Engine-level guarantees and invariants
+
+Ally is a deterministic recovery engine for CLI failures.
+It helps humans recover from errors without rewriting, hiding, or second-guessing the tool's original output.
+
+This document defines the platform contract for Ally as an engine behind current and future applications.
+
+---
+
+## 1. Design goals (non-negotiable)
+
+Ally is designed to be:
+
+- **Additive** – never rewrites or suppresses ground-truth output
+- **Deterministic** – same input always produces the same output
+- **Safe by default** – v0.x emits SAFE-only command suggestions
+- **Profile-driven** – presentation policies change *how*, not *what*
+- **Guarded** – engine invariants are enforced at runtime
+- **Adapter-friendly** – CLI today, MCP/IDE/CI adapters later
+
+Ally is intentionally conservative. When in doubt, it withholds help rather than inventing it.
+
+---
+
+## 2. Ground truth vs Assist output
+
+### 2.1 Ground truth
+
+Ground truth is produced by the tool that failed. Preferred formats:
+
+- `cli.error.v0.1` JSON (highest confidence)
+- `a11y-lint` scorecard JSON (medium confidence)
+- Raw CLI text (lowest confidence; best-effort only)
+
+**Ground truth is never modified by Ally.**
+
+### 2.2 Assist output
+
+Assist output is an additional block clearly labeled as such (e.g., `ASSIST (Low Vision):`).
+
+Assist output:
+
+- explains the situation
+- suggests safe next steps
+- discloses confidence
+- preserves user control
+
+---
+
+## 3. Engine API (source of truth)
+
+All adapters (CLI, MCP, IDE, CI) are thin layers over the engine API.
+
+### 3.1 assist.request (engine input)
+
+**Schema:** `assist.request.v0.1`
+
+Required:
+
+- `profile` – presentation policy (lowvision, cognitive-load, screen-reader, etc.)
+- `input.kind` – cli_error_json | scorecard_json | raw_text | last_log
+
+Optional:
+
+- `preferences.max_steps`
+- `preferences.show_next_command`
+
+### 3.2 assist.response (engine output)
+
+**Schema:** `assist.response.v0.1`
+
+Required:
+
+- `confidence` – High | Medium | Low
+- `safest_next_step` – one sentence
+- `plan` – ordered list of steps
+
+Optional:
+
+- `anchored_id` – string or null
+- `next_safe_commands` – SAFE commands only
+- `notes`
+- `methods_applied` – audit-only method identifiers (see §15)
+- `evidence` – audit-only source anchors (see §15)
+
+This schema is the engine contract.
+Human-readable output is a *rendering* of this structure.
+
+---
+
+## 4. Confidence semantics (monotonic and enforced)
+
+Confidence reflects the reliability of the input, not the quality of the advice.
+
+| Confidence | Meaning |
+|------------|---------|
+| High | Validated `cli.error.v0.1` JSON |
+| Medium | Scorecard input or raw text with explicit `(ID: …)` |
+| Low | Raw text without ID, partial parsing, or validation failure |
+
+### Invariant
+
+**Confidence may never increase during profile transformation.**
+Profiles may only preserve or downgrade confidence.
+
+Enforced by the Profile Guard.
+
+---
+
+## 5. Safety model
+
+### 5.1 Risk taxonomy
+
+- **SAFE** – read-only, dry-run, validation, inspection
+- **RISKY** – reversible state changes
+- **DESTRUCTIVE** – irreversible state changes
+
+### v0.x policy
+
+- Ally MAY emit SAFE commands only
+- Ally MUST NOT emit RISKY or DESTRUCTIVE commands
+- Ally NEVER executes commands
+
+### Command provenance rule
+
+Every emitted command must:
+
+1. appear verbatim in the ground truth (e.g., Fix lines or structured next)
+2. be classified SAFE
+3. be allowed by confidence level (no commands on Low confidence)
+
+Enforced by the Profile Guard.
+
+---
+
+## 6. Profiles (policy transforms)
+
+Profiles are deterministic presentation policies.
+
+### 6.1 Profile contract
+
+A profile is a pure function:
+
+```
+AssistResult (base) → AssistResult (profiled)
+```
+
+**Allowed:**
+
+- reorder steps
+- truncate steps
+- simplify phrasing
+- change rendering style
+
+**Forbidden:**
+
+- inventing IDs
+- inventing commands
+- adding new facts
+- increasing confidence
+- bypassing safety rules
+
+### 6.2 Built-in profiles (v0.3.x)
+
+| Profile | Purpose |
+|---------|---------|
+| lowvision | Visual clarity, spacing, redundancy |
+| cognitive-load | Reduce steps and complexity |
+| screen-reader | Audio-first, spoken-friendly output |
+| dyslexia | Reduced reading friction, explicit labels |
+| plain-language | Maximum clarity, one clause per sentence |
+
+Adding a new profile is non-breaking.
+Changing semantics of an existing profile is a breaking change.
+
+---
+
+## 7. Profile Guard (runtime invariant enforcement)
+
+### 7.1 Purpose
+
+The Profile Guard enforces engine invariants after every profile transform.
+
+Guard violations indicate engine bugs, not user errors.
+
+### 7.2 Enforced invariants (v0.3.x)
+
+**Hard errors (fail execution):**
+
+- Anchored ID invented or changed
+- Confidence increased
+- Invented commands
+- Commands emitted on Low confidence
+- Exceeding profile step limits
+- Forbidden tokens (e.g., parentheticals in screen-reader)
+- Visual navigation references in screen-reader output
+
+**Warnings (non-fatal):**
+
+- Content Support Invariant violations
+  (output contains facts not supported by base input)
+
+Warnings are surfaced for developers but do not block output by default.
+
+### 7.3 Guard behavior
+
+- Violations raise `GuardViolation`
+- CLI emits structured error output with guard codes
+- Exit code: 2 (engine/validation failure)
+- Output must not be trusted when guard fails
+
+---
+
+## 8. Content Support Invariant (WARN-level)
+
+Profiles must not introduce new factual topics.
+
+### Enforcement approach
+
+A deterministic heuristic checks whether each output step:
+
+1. shares content tokens with base input text, or
+2. consists only of allowed "glue" language plus supported tokens
+
+If unsupported, a WARN-level guard issue is emitted.
+
+This balances safety with legitimate rephrasing.
+
+---
+
+## 9. CLI adapter behavior (current reference)
+
+**Commands:**
+
+- `explain --json <path>`
+- `triage --stdin`
+- `last`
+- `assist-run <command...>`
+
+**Rules:**
+
+- Original tool output is printed unchanged
+- Assist block is clearly labeled
+- Guard is always enforced
+
+**Exit codes:**
+
+- 0 – success
+- 2 – validation/guard failure
+
+The CLI is the reference adapter, not the engine itself.
+
+---
+
+## 10. Determinism and locality
+
+- No randomness
+- No timestamps
+- No network calls
+- Local state limited to:
+  - `~/.a11y-assist/last.log`
+
+Telemetry, analytics, or remote calls are explicitly out of scope.
+
+---
+
+## 11. Versioning policy
+
+### Schemas
+
+- `cli.error.v0.1`
+- `assist.request.v0.1`
+- `assist.response.v0.1`
+
+### Versioning rules
+
+- **Patch:** bug fixes, stricter enforcement, clearer wording
+- **Minor:** new profiles, new optional fields, new adapters
+- **Major:** changes to required fields or invariant semantics
+
+Backward compatibility is preferred but correctness takes priority.
+
+---
+
+## 12. Testing requirements (quality gate)
+
+Every release must include:
+
+- Determinism tests (same input → same output)
+- Guard unit tests for every invariant
+- Profile integration tests
+- Golden tests for all profiles:
+  - lowvision
+  - cognitive-load
+  - screen-reader
+  - dyslexia
+  - plain-language
+- Methods metadata tests (if metadata is present, it must not affect deterministic output)
+
+If a change cannot be proven safe by tests, it must not ship.
+
+---
+
+## 13. MCP and future adapters (explicitly deferred)
+
+Ally becomes an MCP tool only after:
+
+1. engine contracts are stable
+2. guard invariants are proven in real usage
+3. consumers want programmatic access
+
+When this happens, MCP will be a thin adapter over the engine API.
+
+---
+
+## 14. Methods metadata (optional, audit-only)
+
+Ally may emit optional metadata fields in `assist.response.v0.1` to support auditing and future "methods/tests" mapping.
+These fields must not change engine behavior and must not be required.
+
+### 14.1 methods_applied
+
+Optional list of stable method identifiers indicating which deterministic procedures contributed to the output.
+
+Examples:
+- `engine.normalize.from_cli_error_v0_1`
+- `profile.screen_reader.apply`
+- `guard.validate_profile_transform`
+
+Rules:
+- append-only and stable once published
+- identifiers are descriptive, not user-facing UI
+- may be omitted or empty
+
+### 14.2 evidence
+
+Optional list of lightweight source anchors mapping output text back to input text.
+
+Each evidence entry references:
+- `field`: which output field it supports (e.g., `safest_next_step`, `plan[0]`)
+- `source`: where it came from (e.g., `cli.error.fix[1]`, `cli.error.why[0]`, `raw_text:Fix:2`)
+- optional `note`
+
+Rules:
+- anchors must be deterministic
+- no large blobs; references only
+- may be omitted or empty
+
+### 14.3 Rendering and testing
+
+- Renderers must ignore metadata by default (no visible output change)
+- Golden fixtures compare rendered text only; metadata does not affect comparison
+- Dedicated metadata tests verify correctness without affecting golden test stability
+
+---
+
+## 15. Design philosophy (final)
+
+> Accessibility is not a feature.
+> It is a contract—explicit, testable, enforced, and safe.

package/src/a11y-assist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/a11y-assist/PRESS_RELEASE.md

@@ -0,0 +1,71 @@
+# a11y-assist v0.1.0 Released
+### Human help for CLI failures — without replacing ground truth
+
+Today we're releasing **a11y-assist v0.1.0**, a low-vision-first assistant for command-line tools that helps users *act* on failures without rewriting, hiding, or second-guessing the original output.
+
+a11y-assist is the third component in the accessibility toolchain:
+
+- **a11y-lint** defines the accessibility contract
+- **a11y-ci** enforces it in continuous integration
+- **a11y-assist** helps humans recover when things go wrong
+
+## What problem this solves
+
+CLI errors often fail users at the worst possible moment:
+- when they're under time pressure
+- when output is dense or poorly structured
+- when vision or cognitive load makes scanning difficult
+
+a11y-assist does **not** fix errors automatically.
+Instead, it provides a clear, additive explanation that helps users regain control.
+
+## Key principles
+
+- **Additive, not destructive**
+  The original tool output is never modified or hidden.
+
+- **Ground truth anchored**
+  When available, assistance is anchored to `cli.error.v0.1` IDs and structure.
+
+- **Low-vision-first**
+  Output uses clear labeling, spacing, redundancy, and short line lengths.
+
+- **Safe by default**
+  v0.1 emits only non-destructive, read-only next steps.
+
+- **Deterministic and local**
+  No background services. No network calls. No hidden state.
+
+## What's included in v0.1.0
+
+- `a11y-assist explain --json <file>`
+  High-confidence assistance from structured CLI error JSON
+
+- `a11y-assist triage --stdin`
+  Best-effort help for raw terminal output (clearly labeled lower confidence)
+
+- `a11y-assist last`
+  Assistance for the most recent failed command via a local wrapper
+
+- `assist-run <command>`
+  A zero-config wrapper that captures output and suggests help on failure
+
+## What this release deliberately does *not* include
+
+- No interactive chat
+- No autonomous fixes
+- No risky command suggestions
+- No AI dependency
+
+These capabilities are intentionally deferred to future versions.
+
+## Why this matters
+
+Accessibility is not just about correctness — it's about **recoverability**.
+
+a11y-assist makes CLI tools more humane without sacrificing determinism, debuggability, or trust.
+
+---
+
+Repository: https://github.com/mcp-tool-shop-org/a11y-assist
+Release: v0.1.0