design/ — the YazSes design record¶
This is the public engineering and scientific record of YazSes: why the software is built the way it is, what the evidence says, and what is still unknown. It is licensed with the rest of the repository (Apache-2.0) and is meant to be read.
If you want to know how to use YazSes, you want the documentation site instead. This directory answers the other question: why does it behave this way?
What is here¶
| Path | What it holds |
|---|---|
adr/ | ~180 Architecture Decision Records — one per real decision, with the context, the options, and the consequence. The primary record. |
specs/ | Implementation-ready feature specs in ADR house style. |
research/ | The scientific layer: the 105-reference HCI corpus, the research agenda, literature sweeps, and hci-corpus.bib. |
research/studies/ | State-of-the-art studies: scope, SoA matrix, gap analysis, capability cards. |
architecture.md | The as-built architecture reference. |
white-paper-authoring-standard.md | Evidence, structure, visual, benchmark, citation, release, and QA standard for future YazSes white papers and one-page briefs. |
threat-model.md | The privacy and threat model behind the offline-by-construction stance. |
emg-protocol.md | The YESP serial protocol for the EMG activation source. |
v2-cognitive-layer/ | Design notes for the opt-in perceptual/personalization features. |
meeting-mode/, mobile/ | Subsystem design notes. |
chinese/ | First-class Mandarin support design package: architecture, model policy, validation, risk controls, community task contracts, and release evidence gates. |
xr/ | Proposed future research: ten voice/gaze/metaverse interaction ideas, conditional delivery plan, adapter architecture, safety gates, evaluation and contributor work packages. No shipped XR support or implementation approval. |
eye-control/ | Eye/gaze/head/face-camera accessibility programme: as-built audit, roadmap, test gates and agent-sized tasks. |
packaging/ | Release-engineering runbooks: APT, PPA, Snap, macOS notarisation, Windows signing. Procedures only — they name GitHub Secret keys, never values. |
The visibility contract¶
One directory, one visibility. There is no per-file exception list to keep in sync, and a new file's status is never ambiguous.
| Directory | Visibility | Why |
|---|---|---|
design/ | Public | Engineering and science. The argument for the software is the software's best evidence. |
docs/ | Public | User-facing documentation, published to the docs site. |
strategy/ | Private | Marketing copy, SEO analysis, vision/idea notes for features that may never ship, distribution status. Tactics lose value when public, and unbuilt ideas read as promises. |
papers/ | Private | The manuscripts, the benchmark harness, the archived result files and the corpus: everything the author's papers rest on lives here, in its own private repository, and none of it is published. docs/benchmarks.md gives the numbers and the method; it does not ship the harness. |
paper/ | Private | The old name of the harness and results folder, retired. Nothing under it may be committed. |
.claude/ | Private | Coding-agent artifacts: plans, memory, project-local skills. |
Enforced in three places, all of which must agree: .gitignore, .git/hooks/pre-commit (the maintainer's local hook; a fresh clone has none, so tests/test_private_tiers_stay_private.py is what guards a contributor's commit), and hooks/design_tier.py — the hook that mirrors this tree onto the documentation site. Changing one without the others is a bug.
The third one used to be the odd one out, and the way it failed is worth recording. It carried its own list of directories to publish, so packaging/, v2-cognitive-layer/, mobile/ and meeting-mode/ — named as public in the table above, and committed to this public repository — were absent from the site for months because no line in the hook mentioned them. Nothing failed: an omission produces no warning, no broken link, no red build. It now publishes everything git tracks under design/ that is not under a private prefix, which is the same rule the table states, derived rather than restated.
Tracked-ness, not the filesystem, is what decides. A file that is not committed is not in the public repository, and the site must never be the first place it appears.
| Excluded from the site today | Why |
|---|---|
design/vision/ | Unbuilt-feature idea notes. Private by the contract above, and untracked, so two independent things would have to be wrong before it could be published. |
Nothing else is excluded.
A public file must never contain a path into a private tree¶
The link dangles, and the filename itself leaks what is being held back. Where a document here refers to internal material, it names it in prose — "the Punch-In vision card (internal)" — rather than linking a path. The pre-commit hook rejects commits that reintroduce one. Everything load-bearing from an internal note is restated here, so these documents stand alone.
No third-party PDFs. Ever.¶
Papers we cite are downloaded for personal research use. Redistributing them would violate the authors' copyright, so no PDF is committed to this repository: .gitignore excludes *.pdf, tests/test_citation_hygiene.py fails the build if one is tracked, and the maintainer's local pre-commit hook blocks it too.
What we publish instead is strictly better for the reader anyway:
- the citation, with a DOI resolved against Crossref or DataCite;
- our own summary of what the work establishes and which decision it drives.
If you want to add a reference, put it in research/hci-corpus.bib, then verify it: write a one-item JSON list such as [{"key": "...", "section": "...", "title": "...", "author": "<surname>", "doi": "..."}] (or "arxiv": "2401.01234" in place of doi), and run python design/research/verify_refs.py candidates.json out.json. It needs the network, because it queries Crossref and DataCite. Only an entry that comes back OK goes in, and then you cite it. Do not commit the paper.
Link the landing page, not the file. A URL ending in .pdf is the wrong citation even though linking is not redistribution: it skips the abstract or publisher page that carries the version, the licence and the DOI, and it breaks as soon as the author reorganises their site — which is most of why link rot exists in bibliographies. Cite arxiv.org/abs/1710.10468, not .../1710.10468.pdf.
Both rules are enforced by tests/test_citation_hygiene.py, which also asserts that no PDF is tracked — the ignore rule and the hook guard the commit, and neither notices one that arrived by a merge or a git add -f. It keeps a short, named exception list for sources that genuinely have no landing page, such as a conference presentation hosted by its author; that list is a debt, and the test fails if it grows.
Planning traceability¶
The design record answers what was decided; it is not, by itself, a delivery promise. Current planning relationships live in traceability.yml, which keeps decision status separate from delivery status and names the right-sized tracking surface for active work.
A bounded contributor task does not need its own GitHub issue. For example, feature wiring uses issue #164 as the umbrella and one WIRE-<SLUG>-001 row in campaign/tasks.json per capability. Programme coordination uses an issue/epic. Research questions may stay research. Deferred or declined decisions carry no fake schedule.
The normal validation is offline:
Live GitHub facts such as whether an issue is still open or a milestone still exists are intentionally checked separately; the ordinary test suite must remain fully offline. The scheduled .github/workflows/traceability.yml workflow runs scripts/check-traceability-live.py (read-only; exit 1 = violation, 2 = GitHub unreadable, 3 = misconfigured). Deliberate exceptions to that audit go in traceability-exceptions.yml. The same run also reports advisory tracker drift: open issues with no milestone and no exempt class, stale "do not start" banners whose numbered blockers have all closed, and closed issues still listed beside an open tracker. This drift appears in the job summary and the traceability-live artifact and never changes the exit code.
Which open issues must carry a milestone is decided by the milestone policy (#480): delivery issues carry exactly one, epics carry the one their sub-issues share, and evergreen issues carry an evergreen:<class> label and none. scripts/milestone_policy.py checks an issue snapshot against it offline, alone or via scripts/check-traceability.py --issues issues.json. The scheduled live audit applies the same module to its own issue listing and reports the policy's violations, advisory, in their own section of the job summary.
Contributing to the design record¶
- Changing behaviour that had an ADR? Update the ADR or supersede it. An ADR is a historical record: supersede, don't silently rewrite.
- Proposing something new? An ADR or a spec is the right first artifact, and it is a genuinely welcome contribution on its own — a well-argued decision record is worth more than a rushed implementation.
- Adding a research claim? It needs a verified citation. See the verification protocol — fifteen entries in the corpus would have been wrong if written from memory, so this is not ceremony.
Start with CONTRIBUTING.md for the code side.