canon(constraint): Legibility Standard — glyphs are a legend, not garnish — at-a-glance captain communication (DRAFT — do not merge)

[git-repo-auth]

🛬 Draft — canon is the captain's authorial domain. Merge = ratify; do not merge without the captain's word.

What this changes

Adds one new canon constraint: canon/constraints/legibility-standard.md at the URI three ratified docs already cite but which resolves NOT_FOUND today — klappy://canon/constraints/legibility-standard. It is the communication policy you have asked for repeatedly across the last week: emoji as visual aid for at-a-glance information in agent→captain messages — glyphs as a legend carrying state (🔴🟢🟡⚪✅ · 🛫✈️🛬✅ · workstream glyphs), never garnish.

The decision

Ratify (or redline) the fourth member of the captain-facing communication contract: legibility (readable) alongside reviewability-standard (reachable), seeded-response-standard (answerable), triangle-of-yaps (shaped).

Enough to decide, inline

• Legend source of truth = the live board (header legend + HUD KEY), quoted not owned; glyph meanings are fetched, not recalled. Verified against today's board export.
• Two layers, per your 2026-07-11 ruling: fixed legend for state glyphs; semantic inline emoji stay a principle, not a legend — judgment-driven, untabulated.
• Enforcement honestly graded on PR docs: E0008.1 — X-Ray Tracing and Infrastructure Optimization #89's ladder: message formatting is L3/L4 — detection, not an enforcer. What is mechanical: legend served at preflight (fetched not recalled); dispatch-guard glyph-lint flags glyph-less or state-contradicting captain messages where wired. No fake L1 claim.
• Acceptance test: after merge, oddkit_get klappy://canon/constraints/legibility-standard returns the doc in one call. That call returned NOT_FOUND on 2026-07-18 despite a week of the seat reporting this policy existed — the WHY section records that failure as the motivating incident.
• Frontmatter validates (scripts/validate-frontmatter.py ✅); target_repo: outcomes-driven-development, matching its two ratified companions.

Options considered

1. ⭐ Ratify as-is — closes the dangling URI; the contract set is complete. (recommended)
2. Redline first — mark up the doc; the flight folds and re-presents.
3. Fold into PR canon: three captain-facing dispatch constraints (legibility, fresh-copy, no-durable-memory) — draft for review #287's captain-message-legibility instead — rejected by the draft because canon: three captain-facing dispatch constraints (legibility, fresh-copy, no-durable-memory) — draft for review #287 governs message shape for one seat and defines no vocabulary; this defines the legend for all captain-facing surfaces and is the URI already cited.
4. Other — say the word.

👉 Say "merge legibility" — or redline inline.

Reversibility

Fully reversible: one new file, no code, no existing doc touched. Revert = delete the file; the URI returns to NOT_FOUND (which is also the honest failure state).

---

Note

Low Risk
Documentation-only addition with no code or config changes; operational impact depends on future ratification and optional enforcement wiring.

Overview
Adds canon/constraints/legibility-standard.md (draft) so klappy://canon/constraints/legibility-standard can resolve after ratification—filling a URI already referenced by reviewability and seeded-response standards while the corpus returned NOT_FOUND.

The new constraint defines captain-facing legibility as the fourth communication-contract sibling (readable): Layer-1 state glyphs must lead status, decisions, flights, incidents, and PR trays, with meanings fetched from the live board legend (not owned or recalled from memory); Layer-2 inline emoji stay judgment-driven and untabulated per the 2026-07-11 ruling. It documents honest L3/L4 enforcement (preflight legend serve, optional dispatch-guard glyph-lint, inherited ARS §1.6 review) and sets oddkit_get on that URI as the acceptance test.

No existing files or runtime code are modified—revert is delete-only.

^{Reviewed by Cursor Bugbot for commit 648fc3f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Canon Quality — oddkit_audit ✅

No dead klappy:// references or legacy link patterns found in writings/. 53 files scanned.

_{Spec: klappy://docs/oddkit/specs/oddkit-audit · Workflow: .github/workflows/canon-quality.yml · Run: #417}

[github-actions]

Canon Quality — Homepage Surfacing ✅

51 essay(s) scanned. Soft report — never blocks; the hard field gate is the Frontmatter Schema job.

All published essays resolve to the homepage feed.

_{Report: scripts/surfacing-report.py · Canon: klappy://canon/constraints/frontmatter-validation-before-merge}

[github-actions]

Canon Quality — P0010 Retrieval-Readiness ⚠️

Soft report for klappy://canon/constraints/retrieval-disclosure-contract. 709 files scanned. Never blocks — informational until the corpus is ready to enforce.

• Blocking-class findings: 15 (structural fields the contract would filter on)
• Warnings: 0 (kind resolves to unknown)
• Informational: 13 (exempt templates/archive/drafts)

Kind distribution: {'essays': 53, 'canon': 245, 'apocrypha': 38, 'docs': 307, 'journals': 60, 'unknown': 6}
Kind source: {'path': 574, 'frontmatter': 129, 'none': 6} (frontmatter-primary, path-secondary)
Default-include visibility: 605 visible, 104 hidden (journals/apocrypha/unknown)

By rule: {'audience-invalid': 2, 'exposure-missing': 5, 'tier-missing': 5, 'tier-invalid': 7, 'fm-missing': 3, 'kind-unresolvable': 6}

These are not schema violations (see the Frontmatter Schema job for those on writings/). They are corpus-readiness signals for the retrieval contract: invalid/missing audience, exposure, tier, and docs whose kind cannot be resolved. Fix in a corpus-cleanup PR before the contract flips to enforcing. See the retrieval-readiness-findings artifact for the full list.

_{Validator: scripts/audit-retrieval-readiness.py · Constraint: klappy://canon/constraints/retrieval-disclosure-contract · Run: #417}

[github-actions]

Canon Quality — Frontmatter Schema ✅

All 51 file(s) in writings/ conform to klappy://canon/meta/frontmatter-schema.

_{Validator: scripts/validate-frontmatter.py · Canon: klappy://canon/constraints/frontmatter-validation-before-merge · Run: #417}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Layer two contradicts key glyph
  • Replaced the Layer 2 auth-work example's reserved 🔑 glyph with 🔐, preserving 🔑 exclusively for Layer 1 human-only status.

_{You can send follow-ups to the cloud agent here.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit df57a2e. Configure here.}