feat: give the design persona a visual-direction step and a foundation token contract

[vnlebaoduy]

Summary

The design persona's knowledge (core/knowledge/aidlc-design-agent/) settles UX structure - the five screen states, information architecture, WCAG, interaction patterns, breakpoints - and says almost nothing about the visual layer the developer builds from. design-system-mapping.md, a refined-mockups output, has no stated contents beyond "component mapping"; a grep of the knowledge directory finds one spacing-scale line and no type scale, semantic colour tokens, contrast pairs, light/dark pairing, radius, elevation, or motion guidance. Nothing asks the persona to read the brief (existing assets, audience, overriding constraints) before choosing a look, so the look arrives by default and the visual decisions are made silently at code generation, outside the refined-mockups gate.

This adds a visual-direction contract with three surfaces that agree: a knowledge file, the persona that owns stating it, and the stage that asks for its inputs and names it in the artifact.

Closes #1137.

Changes

• core/knowledge/aidlc-design-agent/visual-design-foundations.md (new) - the one-line design read the persona states before designing (product kind, audience, visual language, design system or aesthetic family), derived in a fixed order: existing assets, audience, quiet constraints (regulated, public-sector, accessibility-first), references from the stories and Q&A; an unsettled read is a clarifying question, not a guess. A short list of generated-design defaults to reach past deliberately. The foundation token table design-system-mapping.md must carry: type (scale by role, line height, measure, weight hierarchy, pairing, tabular figures), colour (semantic tokens, per-pair contrast ratios, light and dark defined together, never colour-only meaning), space/shape/depth (spacing, radius, elevation scales), motion (durations, easing, reduced-motion behaviour per animation), iconography (one set). Per-screen rules (one primary action, distinct interaction states, wrap over truncation, platform idioms) and a six-line hand-off checklist.
• core/agents/aidlc-design-agent.md - a ### Visual Direction responsibility group under Core Responsibilities (state the read, define the token table, map every value to a token, reach past defaults) and a seventh principle, "Read the audience before choosing a look". Frontmatter unchanged.
• core/aidlc-common/stages/inception/refined-mockups.md - one question added to the question set (existing brand assets, design system, or aesthetic references, and the audience - the inputs to the design read) and the artifact step names the design read and the foundation token table as the opening of the design system mapping. The produces / outputs frontmatter is unchanged: same five artifacts, no new file.
• docs/reference/agents/design-agent.md, docs/reference/04-stages/inception.md - the knowledge table gains the new file; the stage's question list and outputs table match the stage file.
• tests/unit/t15-knowledge-file-inventory.test.ts - the inventory pin moves from 5 to 6 files for aidlc-design-agent and from 59 to 60 for the tree total (TAP plan 94 -> 95); the per-agent counts for every other agent are unchanged.
• tests/unit/t340-design-visual-foundations.test.ts - pins the knowledge file's sections (design read, defaults, five token groups, per-pair contrast, both themes, handoff checklist), its harness-neutrality and byte-identity in dist/claude, the persona's Visual Direction group and {{HARNESS_DIR}} reference (resolved to .claude/ in the projection), and the stage's question and artifact wording alongside the unchanged outputs: line.

No engine or tool change; the knowledge directory is copied wholesale by every harness manifest. No version bump, badge, or CHANGELOG entry, per the Release Metadata Policy in AGENTS.md.

User experience

Before: a human approving refined-mockups approves layout and states but not typography, colour, or elevation, because none of that is in the artifact; two units built by two code-generation runs can diverge visually with nothing to review them against.

After: design-system-mapping.md opens with a one-line design read and carries a token table the developer maps to directly; the approval gate covers the visual layer, and the question file asks for the inputs (assets, audience, references) when they are not in the stories. Turn cost: one added question in the existing question flow; no added stage, artifact, or tool call.

Checklist

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• If this change adds an input to any fingerprint, epoch, or receipt identity, the description names the human-visible change it detects

Test plan

On c0eb2921 (2.8.2):

bun scripts/package.ts
bun test tests/unit/t340-design-visual-foundations.test.ts          # 5 pass
bun test tests/unit/t15-knowledge-file-inventory.test.ts            # 19 pass
bun test tests/unit/t04-agent-frontmatter.test.ts \
         tests/unit/t146-core-hygiene.test.ts \
         tests/unit/t174-docs-legacy-refs-gate.test.ts \
         tests/unit/t116-directive-path-resolution.test.ts          # all pass
bun run lint && bun run typecheck
bun scripts/package.ts --check                                      # deterministic, 7 harnesses
bun tests/run-tests.ts                                              # 393 / 395 files

Full default suite in an isolated worktree: 393 / 395 files. The two failures were t15 before its pin was bumped (now 19 / 19 alone) and tests/integration/t19.test.ts, the live-substrate preflight that drives a real Claude Agent SDK turn; it fails identically when run alone on this machine and on the two sibling branches (#1135, #1138) (binary and STS probes pass, the driven turn times out), so it is my environment, not this change.

The new pin fails without the edits: git stash push -u -- core/ && bun test tests/unit/t340-design-visual-foundations.test.ts reports 4 failures (the one survivor reads the already-built dist/ projection).

Open question from #1137 stands: whether the token table should live in the design persona's knowledge (as here) or in aidlc-shared/ so the developer persona reads the same contract at code generation. Happy to move it.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[vnlebaoduy]

Withdrawing this one, on the same standard I applied to its two siblings.

This PR is the third of a series: #1135 (reviewer personas) and #1138 (producing personas) were the first two. I closed both on 2026-09-14 after measuring them — two lab projects identical but for the persona file, 5 planted defects and 3 traps per artifact, 3 review runs per variant in both advisory and adversarial modes, 12 runs total. The result was parity: 14/15 planted defects caught either way, no trap taken on either side, and the failure mode the change assumed would occur did not occur once.

This PR carries no equivalent measurement. Its test (t340) pins that the prose exists and that the projections stay byte-identical — it does not show the design agent behaves differently with the token contract than without it. By the bar I set for the other two, that is unproven, and it would be inconsistent to ask for a review here after withdrawing those.

The underlying gap still seems real to me, so I am leaving #1137 open rather than closing it: the design stages cover UX structure but state no visual direction or foundation tokens, so typography, color and elevation get decided implicitly at code-generation time, outside any approval gate. If a maintainer thinks that gap is worth closing, I am happy to re-propose with an A/B on design-system-mapping.md with and without the token contract, in the same shape as the measurement above.

No action needed from anyone here.