Strengthen design contract + instantiation: shared Rating, hero wiring, visual gate

[chumleesockson]

Why

A run-through showed the built app diverging sharply from the design we are aiming for: the hero rendered as a broken image (empty box with alt text), the modal rating stars were thin grey outlines instead of filled orange, the hero stats came out as boxed tiles, and the comment textarea was in a monospace font. The design contract actually specifies all of this correctly, so the contract is not the problem. The problem is that the instantiation and tasks did not force the agent to honour it, and there was no visual gate, so tsc/lint/test passed while the page looked wrong.

This PR strengthens the spec where it was weak and adds the missing design verification. Follows PR #7; sits on top of it.

Root causes and fixes

1. The Rating was hand-rolled three times, so the fills drifted. The produced app had three separate star blocks (session-card__star, modal__rating-readout, modal__star) and the picker never applied the orange active fill. Fix: make "build it once, reuse by mode" a hard requirement.

• design-contract.md §4.9: a > Build it once note (one component, three modes; per-surface star code is the named failure) and an explicit "on marks are filled #F5400D, not a coloured stroke; outline-only pickers fail conformance".
• session-feedback-instantiation.md new §3.8: the card read-out, modal picker, and success confirmation all use the one shared component, with the two fills restated (gold settled, orange picker).
• Task 2 builds the component (first surface with marks); Task 3 reuses it.

2. The hero broke because the asset was imported across the specs/ boundary and nothing checked it. The agent wrote import heroImage from "../specs/assets/hero.jpg", which is fragile under Vite. Fix: session-feedback-instantiation.md new §3.0 "Brand assets and wiring" — copy assets into src/assets/ or public/ and reference the Vite way, never across specs/. The hero is made required for this app (it is the "Power Up" key art, the brand moment Vibe cannot match), overriding the contract's optional-hero allowance. Task 4 scope/gate updated to wire assets and confirm the hero renders.

3. Stats were boxed; textarea was monospace. Cheap, visible misses the contract already implies. Fix: instantiation §3.3 pins the baseline stat cluster (not boxes); contract §4.10 now says inputs/textareas set font-family to the Barlow UI font (browsers default <textarea> to monospace).

4. None of it was caught, because design fidelity had no gate. The verify gate is tsc/lint/test, none of which can see a broken hero, outline stars, a mono input, or boxed stats. Fix: AGENTS.md "How we work" adds a visual check for design-bearing tasks (2, 3, 4) — run the app and compare against the contract §8 checklist; green verify is necessary, not sufficient. Each of Tasks 2/3/4 gains a concrete "Visual check (run the app)" gate. The contract §8 checklist gains items for the shared Rating fills, brand media actually rendering, and inputs not being monospace.

Whitepaper alignment

• Day 4 (Agent Quality): the core lesson is "verification is the new craft". The gap here was a missing verification surface (design), so the fix adds a visual conformance gate, the design analogue of the data-layer audit pass.
• Day 5 (Spec-Driven): the contract is the asset and it was already right; the fix is to make the binding spec (instantiation) and the tasks actually enforce it, and to pin the asset pipeline so the spec is buildable, not just describable.
• Day 1: still "configuration failures, not model failures" — a fast model produced outline stars and a broken hero because the harness let it, not because it couldn't render the design.

No src/, package.json, or tsconfig* is committed: the app is regenerated on the day, so the fixes live in the contract, the instantiation, the tasks, and the steering doc.

[Copilot]

Pull request overview

This PR tightens the spec “harness” for the EPPC session feedback Code App so the generated UI is forced to match the design contract (especially the hero asset pipeline, the Rating component’s filled stars, the stat cluster layout, and textarea font), and adds a visual verification gate for design-bearing tasks.

Changes:

• Require a single shared Rating component (mode-switched) across card, modal picker, and confirmation, with explicit “filled” behavior in the picker.
• Add explicit asset wiring requirements to avoid importing brand media across the specs/ boundary and ensure hero/logo actually render.
• Introduce “Visual check (run the app)” gates for Tasks 2/3/4 and expand the conformance checklist accordingly.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
specs/tasks/task-2-home-list.md	Requires building the shared Rating component in Task 2 and adds a visual check for stat cluster + gold settled stars.
specs/tasks/task-3-rate-modal.md	Requires reusing the shared Rating component in the modal and adds a visual check for filled orange picker stars + textarea font.
specs/tasks/task-4-branding.md	Clarifies brand asset wiring + hero requiredness and adds a visual check for hero/logo rendering.
specs/session-feedback-instantiation.md	Adds explicit “brand assets and wiring” section and pins shared Rating usage across all surfaces.
specs/design-contract.md	Strengthens Rating guidance (single component, filled picker marks) and adds textarea/input font-family requirement plus checklist items.
AGENTS.md	Adds a design visual-check requirement for Tasks 2/3/4 (verify is necessary but not sufficient).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.