ClarityRail

• 

  Accessibility settings: calm display, high contrast, reduced motion, readable type, and focus supports.

• 

  Capture workspace: paste a brief and compile it locally into an evidence-linked execution graph.

• 

  Review lineage: inspect revision digests, evidence ranges, stale propagation, and exportable handoff history.

• 

  Focus Rail: one dependency-safe next action with its source clause, status, and completion control.

Inspiration

The hard part of an assignment is sometimes not the work—it is deciding where to begin. Dense instructions mix actions, prerequisites, unclear deadlines, and group responsibilities. A long generated summary can create another wall of text. We wanted a calmer tool for the exact moment when a student is overloaded: show one next action, show why it exists, and never hide uncertainty.

What it does

ClarityRail compiles a pasted brief into a local execution graph and presents a four-part clarity contract:

• Focus Rail: isolates one currently eligible action.
• Evidence Thread: links each emitted step to its exact source clause and character range.
• Ambiguity Gate: asks the user to resolve missing cutoff times, formats, owners, or vague scope.
• Change Impact Guard: marks changed and dependent work STALE when the brief is revised.
• Dependency-Safe Detour: offers another READY action only when its prerequisites remain satisfied.

An interruption-recovery capsule records the last completed action, current focus, source revision, and unresolved questions. Users can export a Markdown handoff or JSON session backup.

How we built it

ClarityRail is a React 19 and TypeScript progressive web app with a deterministic compiler rather than neural inference. The compiler segments the brief, extracts actions using documented grammar rules, builds a dependency DAG, detects cycles, evaluates ambiguity rules, and computes a canonical SHA-256 content digest for revision comparison.

Zustand coordinates the execution state machine. Dexie persists sessions in IndexedDB with local fallbacks. Vite and Workbox produce a route-split PWA whose installed service worker has been tested for offline reload after an initial online visit. No application backend or analytics integration receives the brief.

The verification pipeline is fail-closed. It removes stale evidence, then runs type checking, linting, 78 unit/component tests, a 40-brief deterministic benchmark, full-history secret scanning, dependency audit, production build, and 33 Playwright executions. The report generator rejects missing, skipped, failed, flaky, or stale results.

Challenges we ran into

The hardest problem was not extracting verbs. It was preventing unsafe confidence. A step can be syntactically valid while still depending on an unanswered question or on a requirement that changed. We centralized readiness rules, separated PROPOSED from READY, and made revision invalidation transitive through the dependency graph.

Offline behavior also required more than adding a manifest. We test a real production service worker, first online and then offline after reload. IndexedDB schema upgrades are exercised with fake-indexeddb, including persistence across store reinitialization.

Accessibility defects surfaced only at narrow viewports: visually hidden navigation labels had lost their accessible names, custom labels no longer contained visible button text, and a scrollable export preview lacked keyboard focus. Automated Axe and keyboard-dialog tests caught and verified those fixes.

Accomplishments we are proud of

• A traceable workflow that does not manufacture unsupported actions.
• Canonical SHA-256 revision digests, explicitly scoped as integrity comparison—not digital signatures or an immutable ledger.
• Correct stale-state propagation and conservative clause-diff behavior.
• 78/78 unit and component tests with 92.03% statement and 81.40% branch coverage.
• 33/33 browser executions spanning seven responsive profiles and deep offline, dialog, runtime-error, overflow, and reduced-motion checks.
• Zero serious or critical automated Axe findings in the tested states.
• A reproducible 40-brief synthetic benchmark: 0.969 action F1, 0.914 ambiguity recall, and 100% repeatability.

What we learned

Cognitive accessibility is a state-model problem as much as a visual-design problem. A calm screen is insufficient if the system recommends an action whose evidence changed. We also learned that evidence should be generated by the same pipeline that makes the claim: every published metric now traces to a fresh machine-readable artifact.

What's next

Next we would run moderated usability sessions with neurodivergent students and disability-services staff, add import adapters with explicit parsing confidence, and publish an anonymized evaluation corpus reviewed for representativeness. We would also add optional encrypted export, multi-device synchronization only with informed consent, and manual assistive-technology audits.

AI assistance and prior work

ClarityRail was created during the TaskForge build window from a new repository. No pre-existing application codebase or proprietary algorithm was reused. Google Antigravity with Gemini 3.8 Flash assisted with implementation, automated-test drafting, documentation, and review. Product framing, architecture decisions, verification, and submission scope were directed and reviewed by Abhijeet Nardele. The judged runtime is deterministic and local-first; it does not require a remote neural model.

Built With

• accessibility
• github-actions
• indexeddb
• playwright
• pwa
• react
• typescript
• vite
• vitest
• zustand