Plan & evidence for #293 — Make every published surface state the shipped version, count and contrast

[RafaelGorski]

Main issue: #293 — Make every published surface state the shipped version, count and contrast

This sub-issue was opened to address the problems found while auditing the whole open
backlog with the Problem-Based SRS methodology (/problem-based-srs functional-requirements,
2026-09-28). It carries the executable plan, the acceptance criteria and the verification
evidence its main issue needs in order to close.

Problem addressed

CP.01 — Published surfaces disagree with what the repository ships. The project must publish one version, one skill count and one node count across README, the documentation site and the landing page, or no published number can be cited as evidence.

CP.07 — Keyboard-only navigation is unreadable when focused. A keyboard or screen-reader user must be able to read the first control they reach, or the one affordance built for assistive navigation fails the users it exists for.

Observed on 2026-09-28: README.md#L3 badges 2.6.0 after v2.7 shipped; docs/docs.html repeats 2.6.0 at lines 13 and 22; docs/index.html#L103 says "Ten AgentSkills" although one skill ships; the generated dashboard still reads 2.6.0 / 1.1.3 against a published 2.7.0 / 1.1.5, which is what today's canvas e2e failure reports. docs/assets/site.css#L114-L117 renders the skip link as --ink-heading on --primary, measured at 2.39:1 against a 4.5:1 AA floor. Confirmed visually on 2026-09-28 by running npx playwright test --project=site (18 passed, 1 failed): the landing badge screenshots as v2.7.0 while the dashboard one click away reads v2.6.0 / v1.1.3, generated 2026-08-15 — and advertises Passed, 1299 tests, 0 failing, a verdict the same day's runner contradicts at 1,287 / 1,299 with 12 failures. The one failing site test is exactly the dashboard names the same version as the site badge.

Requirements discharged

ID	Statement	Traces to
FR.01.1.1	The system shall state, on every published surface, the plugin and canvas versions that are actually published, as two separately-named trains.	CN.01.1 → CP.01
FR.01.2.1	The system shall report the same skill and action counts on every published surface as the repository actually ships, and shall fail the check when any surface disagrees.	CN.01.2 → CP.01
FR.07.1.1	The system shall render the skip link legible against its own background when focused, at a contrast ratio meeting WCAG AA.	CN.07.1 → CP.07
NFR.04	The focused skip link shall render at a contrast ratio of at least 4.5:1 against its background, meeting WCAG 2.1 AA for normal text.	quality — Usability

Full model: docs/spec/01-customer-problems.md,
docs/spec/03-customer-needs.md,
docs/spec/functional-requirements/_index.md.

Plan

1. Derive every version token on README, docs/docs.html, docs/index.html and the generated dashboard from .claude-plugin/plugin.json and VERSION, so parity is produced rather than maintained by hand.
2. State the two release trains separately wherever both appear — plugin 2.7.0 and canvas 1.1.5 are different numbers for different artifacts and must not be collapsed into one badge.
3. Correct the skill count to the single consolidated skill and reconcile the node count against .spec/crm-system.json, which the visual suite already asserts at 29.
4. Change the skip link foreground to --on-primary and add a contrast assertion so the value cannot regress silently.
5. Keep the parity and contrast assertions in the merge gate, not only in the nightly monitor.

Acceptance criteria

• README, docs/docs.html, docs/index.html and the generated dashboard all read plugin 2.7.0 and canvas 1.1.5
• node --test evals/tests/docs-version-parity.test.mjs exits 0
• The landing page states the shipped skill count (one consolidated skill), and the node count agrees with .spec/crm-system.json
• The focused skip link measures >= 4.5:1 against its background, asserted by a test rather than by inspection
• A deliberate mutation of any single version token fails the parity test (negative-test the guard)
• The committed dashboard's verdict agrees with the runner that produced it — no stored green verdict survives a red run

Verification

Closure requires reproducible evidence: a Playwright capture for anything user-visible
in the app or the site, a CLI transcript for anything in the skills or the pipeline. A green
claim without an attached artifact does not close this issue (NFR.02).

App / site — Playwright with screenshots

cd .github/extensions/srs-navigator
npx playwright test site.test.mjs --project=site

Evidence to attach: Full green site project run.

cd .github/extensions/srs-navigator
npx playwright test site.test.mjs --project=site --grep "skip link"

Evidence to attach: Screenshot of the focused skip link showing readable text, with the measured contrast ratio printed in the assertion output.

Captures land in .github/extensions/srs-navigator/test-results/ (git-ignored) — attach
them here rather than committing them.

Skills / pipeline — CLI transcript

node --test evals/tests/docs-version-parity.test.mjs

Evidence to attach: Exit 0, plus a transcript of the same file failing before the fix.

node scripts/check-distribution.mjs --strict

Evidence to attach: Findings list with no version-parity error; registry drift may remain and is tracked separately by #300/#301/#302.

Every CLI transcript must record the command, its exit code and its totals. Findings are
read separately from the exit code.

Sequencing

Wave	0 of 8 — Baseline green
Blocked by	nothing — can start now
Blocks	#294, #306, #138, #139, #316, #313
Vehicle	PR #320 — already green and awaiting review

Nothing blocks this. It is in the first wave precisely because everything else cites evidence it produces.

Supersedes

Nothing — this is the only active child of its main issue.

---

Generated from the Problem-Based SRS requirement model for this backlog
(docs/spec/remediation-plan.md).
Baseline: main at 7737b3d, 2026-09-28.

[RafaelGorski]

Closing as a redundant duplicate tracking layer on #293 - this issue's body restates #293 plan and acceptance criteria without adding independent scope. Sharper criteria worth preserving were folded into a reviewer comment on #293. (Reviewer triage, 2026-09-28)