@hecer/yoke 1.11.0 → 1.13.0

package/docs/superpowers/specs/2026-06-29-baustein-h-loop-robustness-design.md

@@ -1,113 +1,113 @@
-# Baustein H — Loop Robustness (verify-as-truth + flaky-tolerant verify)
-
-**Status:** Design approved 2026-06-29
-**Component:** Yoke (🐂)
-**Relates to:** [[harness-build-progress]], [[harness-loop-technique]]
-
-## Problem & Goal
-
-Evidence from a real autonomous run (NewMarket, 52/57 stories): the loop blocked and needed
-human intervention on a handful of stories. Two of those block causes are **harness defects**,
-not project defects, and both are cheap to fix:
-
-1. **Runner exit-code is treated as ground truth (SE5).** The story was implemented and the full
-   suite was green (769/769), but the `claude` `.cmd` wrapper on Windows exited **127**. The loop
-   checks `result.success` *before* running verify, so it **blocked a successful story** on a
-   spurious exit code and didn't auto-commit. This contradicts the loop's own stated philosophy
-   (Baustein C2): *"independent verification is the source of truth, not the agent's exit code."*
-
-2. **No flaky-test tolerance (T4).** Under autonomous load, a heavy background task caused an
-   async test to time out — a **false** red, not a real defect. The single-shot verify gate
-   blocked the story. The user had to manually add `retry: 2` to the project's `vitest.config`.
-   That resilience belongs in the harness.
-
-**Goal:** make the loop trust **verify**, not the agent's exit code, and tolerate transient
-flakes — closing two real block causes without weakening the gate.
-
-**Out of scope (deferred):** cross-story regression repair (S5/S6 — a later story breaking an
-earlier story's tests). That needs its own design; this spec does not address it.
-
-## Key Decisions (locked)
-
-| Decision | Choice |
-|---|---|
-| Verify authority | The **implementer** runner's `success` flag is advisory; **verify decides**. Run verify regardless of runner exit, block only on verify failure. |
-| Runner-fail + verify-pass | Proceed (commit) — the exit code was a ghost. Note it via the reporter / summary. |
-| Runner-fail + verify-fail | Block, with a reason naming both signals. |
-| Reviewer runner | **Unchanged** — its non-zero exit *is* the reject verdict (there is no separate verify for the review). |
-| Flaky tolerance | `retryingVerifier(inner, retries)` re-runs a failing verify up to `retries` times; first pass wins. |
-| Retry default | `config.verify.retries` default **1** (one retry). `0` = strict/no-retry. A real failure still fails (twice). |
-| Out of scope | Cross-story regression repair; changing the reviewer's exit-code semantics. |
-
-## Architecture
-
-### 1. `src/loop/verify.ts` — `retryingVerifier`
-```ts
-export function retryingVerifier(inner: Verifier, retries: number): Verifier {
-  return (targetDir) => {
-    let last = inner(targetDir)
-    let attempt = 0
-    while (!last.passed && attempt < retries) {
-      attempt++
-      last = inner(targetDir)
-    }
-    if (last.passed && attempt > 0) {
-      return { passed: true, summary: `${last.summary} (passed on retry ${attempt})` }
-    }
-    return attempt > 0 && !last.passed
-      ? { passed: false, summary: `${last.summary} (still failing after ${attempt} retr${attempt === 1 ? 'y' : 'ies'})` }
-      : last
-  }
-}
-```
-Pure, injectable `inner` for tests (no real command needed).
-
-### 2. `src/loop/loop.ts` — verify is the gate
-In **both** the isolate and non-isolate paths, restructure the implementer step so verify always
-runs:
-
-- Run the implementer runner (keep `result` for its summary).
-- `reporter.phase('verifying')`; run `opts.verify(dir)`.
-- If verify **fails**: block. Reason = verify summary, and if the runner *also* reported failure,
-  prepend that (`runner reported failure (<summary>); verify also red: <verify summary>`).
-- If verify **passes**: proceed to review/commit even if `result.success` was false. When the
-  runner had reported failure, the committed decision/summary notes
-  `(runner exited non-zero but verify is green)` so the ghost is auditable.
-
-The reviewer step is untouched: `if (!reviewResult.success) → block` stays (exit = verdict).
-
-The Baustein-E invariant (no `passes:true` without a commit; decision rollback on commit failure)
-and the leftover-hint are preserved exactly — only the implementer-failure gate moves from
-"before verify" to "verify decides".
-
-### 3. `src/retrofit/config.ts` — `verify.retries`
-Extend the `verify` config object: `verify: { command: string; retries?: number }`.
-Backwards-compatible (optional).
-
-### 4. `src/loop/run-command.ts` — wire the retry
-When building the verifier from config, wrap it:
-`verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1)`.
-The injected-verifier test path (`opts.verify`) is unchanged.
-
-### 5. README + loop-spec
-Document: verify is the source of truth (a spurious agent exit code can't block a green story),
-and `verify.retries` (default 1) for flaky suites. Update `canon/loop/loop-spec.md` step 5.
-
-## Testing (subagent-driven TDD)
-- **verify.ts:** `retryingVerifier` passes immediately when inner passes (no retry); passes on
-  retry N when inner fails then passes; fails after exhausting retries; `retries: 0` = single
-  shot; summary notes the retry/exhaustion. Inner is a stub Verifier.
-- **loop.ts:** runner-fail + verify-pass → story is committed + `passes:true` (the SE5 case);
-  runner-fail + verify-fail → blocked with a combined reason; runner-pass + verify-fail →
-  blocked (unchanged); the reviewer still blocks on its own failure; existing invariant tests
-  (commit-failure revert, leftover hint) stay green; applies to both isolate and non-isolate.
-- **config.ts:** `verify.retries` accepted + optional.
-- **run-command.ts:** the built verifier is wrapped with the resolved retry count (assert via a
-  small seam or by config round-trip).
-- Full suite green; `tsc` clean.
-
-## What this would have done for the run
-- **SE5:** runner exits 127 but suite is 769/769 green → verify passes → story auto-commits. No
-  manual finalize.
-- **T4:** the load-flake fails once, the retry passes → story proceeds. No manual `vitest.config`
-  patch, no false block.
+# Baustein H — Loop Robustness (verify-as-truth + flaky-tolerant verify)
+
+**Status:** Design approved 2026-06-29
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-build-progress]], [[harness-loop-technique]]
+
+## Problem & Goal
+
+Evidence from a real autonomous run (NewMarket, 52/57 stories): the loop blocked and needed
+human intervention on a handful of stories. Two of those block causes are **harness defects**,
+not project defects, and both are cheap to fix:
+
+1. **Runner exit-code is treated as ground truth (SE5).** The story was implemented and the full
+   suite was green (769/769), but the `claude` `.cmd` wrapper on Windows exited **127**. The loop
+   checks `result.success` *before* running verify, so it **blocked a successful story** on a
+   spurious exit code and didn't auto-commit. This contradicts the loop's own stated philosophy
+   (Baustein C2): *"independent verification is the source of truth, not the agent's exit code."*
+
+2. **No flaky-test tolerance (T4).** Under autonomous load, a heavy background task caused an
+   async test to time out — a **false** red, not a real defect. The single-shot verify gate
+   blocked the story. The user had to manually add `retry: 2` to the project's `vitest.config`.
+   That resilience belongs in the harness.
+
+**Goal:** make the loop trust **verify**, not the agent's exit code, and tolerate transient
+flakes — closing two real block causes without weakening the gate.
+
+**Out of scope (deferred):** cross-story regression repair (S5/S6 — a later story breaking an
+earlier story's tests). That needs its own design; this spec does not address it.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Verify authority | The **implementer** runner's `success` flag is advisory; **verify decides**. Run verify regardless of runner exit, block only on verify failure. |
+| Runner-fail + verify-pass | Proceed (commit) — the exit code was a ghost. Note it via the reporter / summary. |
+| Runner-fail + verify-fail | Block, with a reason naming both signals. |
+| Reviewer runner | **Unchanged** — its non-zero exit *is* the reject verdict (there is no separate verify for the review). |
+| Flaky tolerance | `retryingVerifier(inner, retries)` re-runs a failing verify up to `retries` times; first pass wins. |
+| Retry default | `config.verify.retries` default **1** (one retry). `0` = strict/no-retry. A real failure still fails (twice). |
+| Out of scope | Cross-story regression repair; changing the reviewer's exit-code semantics. |
+
+## Architecture
+
+### 1. `src/loop/verify.ts` — `retryingVerifier`
+```ts
+export function retryingVerifier(inner: Verifier, retries: number): Verifier {
+  return (targetDir) => {
+    let last = inner(targetDir)
+    let attempt = 0
+    while (!last.passed && attempt < retries) {
+      attempt++
+      last = inner(targetDir)
+    }
+    if (last.passed && attempt > 0) {
+      return { passed: true, summary: `${last.summary} (passed on retry ${attempt})` }
+    }
+    return attempt > 0 && !last.passed
+      ? { passed: false, summary: `${last.summary} (still failing after ${attempt} retr${attempt === 1 ? 'y' : 'ies'})` }
+      : last
+  }
+}
+```
+Pure, injectable `inner` for tests (no real command needed).
+
+### 2. `src/loop/loop.ts` — verify is the gate
+In **both** the isolate and non-isolate paths, restructure the implementer step so verify always
+runs:
+
+- Run the implementer runner (keep `result` for its summary).
+- `reporter.phase('verifying')`; run `opts.verify(dir)`.
+- If verify **fails**: block. Reason = verify summary, and if the runner *also* reported failure,
+  prepend that (`runner reported failure (<summary>); verify also red: <verify summary>`).
+- If verify **passes**: proceed to review/commit even if `result.success` was false. When the
+  runner had reported failure, the committed decision/summary notes
+  `(runner exited non-zero but verify is green)` so the ghost is auditable.
+
+The reviewer step is untouched: `if (!reviewResult.success) → block` stays (exit = verdict).
+
+The Baustein-E invariant (no `passes:true` without a commit; decision rollback on commit failure)
+and the leftover-hint are preserved exactly — only the implementer-failure gate moves from
+"before verify" to "verify decides".
+
+### 3. `src/retrofit/config.ts` — `verify.retries`
+Extend the `verify` config object: `verify: { command: string; retries?: number }`.
+Backwards-compatible (optional).
+
+### 4. `src/loop/run-command.ts` — wire the retry
+When building the verifier from config, wrap it:
+`verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1)`.
+The injected-verifier test path (`opts.verify`) is unchanged.
+
+### 5. README + loop-spec
+Document: verify is the source of truth (a spurious agent exit code can't block a green story),
+and `verify.retries` (default 1) for flaky suites. Update `canon/loop/loop-spec.md` step 5.
+
+## Testing (subagent-driven TDD)
+- **verify.ts:** `retryingVerifier` passes immediately when inner passes (no retry); passes on
+  retry N when inner fails then passes; fails after exhausting retries; `retries: 0` = single
+  shot; summary notes the retry/exhaustion. Inner is a stub Verifier.
+- **loop.ts:** runner-fail + verify-pass → story is committed + `passes:true` (the SE5 case);
+  runner-fail + verify-fail → blocked with a combined reason; runner-pass + verify-fail →
+  blocked (unchanged); the reviewer still blocks on its own failure; existing invariant tests
+  (commit-failure revert, leftover hint) stay green; applies to both isolate and non-isolate.
+- **config.ts:** `verify.retries` accepted + optional.
+- **run-command.ts:** the built verifier is wrapped with the resolved retry count (assert via a
+  small seam or by config round-trip).
+- Full suite green; `tsc` clean.
+
+## What this would have done for the run
+- **SE5:** runner exits 127 but suite is 769/769 green → verify passes → story auto-commits. No
+  manual finalize.
+- **T4:** the load-flake fails once, the retry passes → story proceeds. No manual `vitest.config`
+  patch, no false block.

package/docs/superpowers/specs/2026-06-30-baustein-i-visual-design-verification-design.md

@@ -1,98 +1,98 @@
-# Baustein I — Visual & Design Verification
-
-**Status:** Design approved 2026-06-30 (autonomous)
-**Component:** Yoke (🐂)
-**Relates to:** [[harness-build-progress]], [[readme-always-update]]
-**Inspired by:** [vibecoded-design-tells](https://github.com/JCarterJohnson/vibecoded-design-tells) (MIT © 2026 Carter Johnson) — a data-ranked study of the visual "tells" of AI-generated UIs. Yoke implements the *idea* natively in TypeScript and credits the research; no code or data is copied.
-
-## Problem & Goal
-
-Yoke's verify gate is **code-only** (`tsc` + unit/component tests). It does not check that the UI is **visually sound** (free of generic AI-slop design) or that **user flows actually work end-to-end**. Evidence: in the real NewMarket run, integration/visual bugs (unwired auth pages, a seed id-collision, an old "purple #6c5ce7 dark theme" — itself a classic AI-slop tell) slipped past the unit-test gate and were only caught by a later manual QA sweep.
-
-**Goal:** add a **visual & design verification layer** that plugs into the existing verify model (so it's gated, not advisory) and is honest about cost:
-1. **Mechanical:** a static **design-slop scanner** (`yoke design-scan`) that flags the high-signal AI-slop tells and gates on exit code.
-2. **Methodology:** two canon skills — `unslop-ui` (the design rubric) and `visual-verification` (compose a verify pipeline: types + unit + design-scan + a Playwright flow-smoke; capture video only on failure).
-
-Both integrate through one idea: **the project's `verify.command` becomes a pipeline**, and Baustein-H's verify-as-truth makes those gates authoritative.
-
-## Key Decisions (locked)
-
-| Decision | Choice |
-|---|---|
-| Design-slop detection | A **TS-native** scanner built into the `yoke` CLI (`yoke design-scan`), not a port of the upstream Python; high-precision static heuristics |
-| Gate model | Exit non-zero when the weighted tell-score exceeds `--max` (default **4**); `--report` lists without failing |
-| Flow / video | **Methodology, not CLI** — the agent drives the wired Playwright MCP per the `visual-verification` skill. Yoke gates + guides; it does not embed a browser. Video capture is **opt-in, on failure only** (token-aware). |
-| Skills | `unslop-ui` (rubric) + `visual-verification` (pipeline + flow-smoke + video-on-failure) → all 3 agents |
-| Attribution | Credit vibecoded-design-tells (MIT) in `ATTRIBUTION.md` + README + the skill |
-| Canon count | 24 → **26** skills |
-| Out of scope (YAGNI) | Embedding Playwright/a browser in the Yoke CLI; structural-layout detection ("centered hero + 3 cards") — left to the rubric + agent eye; auto-fixing slop (the agent fixes, guided by the skill) |
-
-## Architecture
-
-### 1. `src/scan/design.ts` (new) — the static scanner
-Pure + unit-testable. Walks the project's source and scores AI-slop tells.
-
-```ts
-export interface Tell { name: string; weight: number; test: (line: string) => boolean; hint: string }
-export interface Finding { file: string; line: number; tell: string; hint: string; text: string }
-export interface ScanResult { findings: Finding[]; score: number }
-
-export const TELLS: Tell[]            // the curated tell set (below)
-export function scanText(text: string, tells?: Tell[]): { line: number; tell: Tell; text: string }[]
-export function scanDir(dir: string, tells?: Tell[]): ScanResult   // walks files, aggregates
-```
-
-**Curated high-precision tells** (each match adds `weight` to the score):
-
-| Tell | weight | matches (case-insensitive) | hint |
-|---|---|---|---|
-| `ai-purple` | 2 | hex `#6c5ce7\|#7c3aed\|#8b5cf6\|#a855f7\|#9333ea`, or Tailwind `(from\|via\|to)-(purple\|violet\|fuchsia)-(4\|5\|6\|7)00` | AI-purple is the #1 vibecoded tell — choose a real brand color |
-| `gradient-clip-text` | 2 | a line containing both `bg-clip-text` and `text-transparent`, or CSS `-webkit-background-clip:\s*text` near a gradient | gradient hero text reads as AI-slop — solid color + weight instead |
-| `neon-glow` | 2 | Tailwind `(shadow\|drop-shadow)-\[0_0_`, or CSS `box-shadow:[^;]*0\s+0\s+\d{2,}px` with a color | neon glow is a tell — use subtle, neutral elevation |
-| `gradient-overload` | 1 | `bg-gradient-to-` or CSS `linear-gradient(` | gradients everywhere flatten hierarchy — use them sparingly |
-| `emoji-icon` | 1 | an emoji (unicode pictographic) inside a `.tsx/.jsx` line that also contains `<button`, `<a `, `aria-hidden`, or a JSX `>…<` icon slot | emoji-as-icons is a tell — use a real icon set |
-
-File walk: extensions `.css .scss .tsx .jsx .ts .js .html .vue .svelte .astro`; skip `node_modules`, `dist`, `.next`, `build`, `.yoke`, `coverage`, `.git`. The tell set is the default but injectable (for tests). Heuristic by design — documented as high-signal, not exhaustive.
-
-### 2. `src/cli.ts` — `yoke design-scan [dir] [--max=N] [--report]`
-- Runs `scanDir(dir)`, prints findings grouped by tell as `file:line  <tell>  — <hint>`.
-- `--report`: print + summary, **always exit 0** (advisory).
-- default (gate): print + summary; **exit 1 if `score > max`** (default `max=4`), else 0. So a couple incidental matches pass; pervasive slop fails. Designed to sit in a verify pipeline.
-- A small body extracted to `runDesignScan(dir, { max, report }): number` for testability.
-
-### 3. `canon/skills/unslop-ui/SKILL.md` (new) — the rubric
-Agent-facing. Lists the ranked tells (AI-purple gradients, gradient hero text, neon glow, emoji-as-icons, shadcn defaults left unchanged, "centered hero + three cards", homogeneous spacing) and how to fix each. Instructs: before finishing UI work, run `yoke design-scan .` and resolve findings; also apply the structural items the scanner can't see. Credits the research.
-
-### 4. `canon/skills/visual-verification/SKILL.md` (new) — ties it together
-Methodology for UI projects:
-- **Compose the verify pipeline** so the loop gate covers more than units: `verify.command` chains types → unit tests → `yoke design-scan .` → a Playwright flow-smoke. (Baustein-H makes these authoritative.)
-- **Flow-smoke via the wired Playwright MCP:** load the key routes against the dev server, assert they render and the console has **no errors**, screenshot each. This catches the "unwired page / runtime crash" bugs unit tests miss.
-- **Video only when necessary:** capture a video of a flow **only on failure** (or when explicitly debugging a UX issue), then analyse it — keeps tokens down. Never record every run.
-
-### 5. Wiring
-- `canon/manifest.yaml`: add `unslop-ui` + `visual-verification` (kind: methodology).
-- `canon/skills/ATTRIBUTION.md`: credit vibecoded-design-tells (MIT © Carter Johnson).
-- `README.md` (**mandatory**): a "Visual & design verification" section (the scanner + the two skills + the pipeline idea), the catalog updated (24 → 26, methodology group +2), and the test-count badge synced.
-
-## Data flow (gate)
-```
-verify.command =  tsc --noEmit  &&  vitest run  &&  yoke design-scan .  &&  <playwright flow-smoke>
-                                                     │ exit 1 if slop-score > max
-   loop verify (Baustein H: verify is the source of truth) ──► block on any red step
-```
-
-## Testing (subagent-driven TDD)
-- **design.ts:** `scanText` flags each tell with correct line + weight; clean text → no findings; `scanDir` walks + skips ignored dirs + aggregates score; injected tell-set works; emoji/purple/clip/glow/gradient cases each covered; a known-clean snippet scores 0.
-- **cli:** `runDesignScan` exits 1 when score > max, 0 when ≤ max, 0 always in `--report`; `--max` parsed; bad `--max` rejected.
-- **canon:** `unslop-ui` + `visual-verification` registered; `validateCanon` stays zero-error; real-canon asserts both present.
-- Full suite green; `tsc` clean.
-
-## What this would have caught
-- NewMarket's old **purple `#6c5ce7` dark theme** → `ai-purple` tell, scored, flagged before it shipped.
-- **Unwired auth pages / runtime crashes** → the flow-smoke (render + no console errors) gate, not the unit tests.
-
-## Non-goals (YAGNI)
-- No browser embedded in the Yoke CLI (Playwright MCP is the agent's tool).
-- No always-on video (opt-in, on failure).
-- No auto-rewrite of slop (the agent fixes via the rubric).
-- No structural-layout static detection (rubric + agent eye).
+# Baustein I — Visual & Design Verification
+
+**Status:** Design approved 2026-06-30 (autonomous)
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-build-progress]], [[readme-always-update]]
+**Inspired by:** [vibecoded-design-tells](https://github.com/JCarterJohnson/vibecoded-design-tells) (MIT © 2026 Carter Johnson) — a data-ranked study of the visual "tells" of AI-generated UIs. Yoke implements the *idea* natively in TypeScript and credits the research; no code or data is copied.
+
+## Problem & Goal
+
+Yoke's verify gate is **code-only** (`tsc` + unit/component tests). It does not check that the UI is **visually sound** (free of generic AI-slop design) or that **user flows actually work end-to-end**. Evidence: in the real NewMarket run, integration/visual bugs (unwired auth pages, a seed id-collision, an old "purple #6c5ce7 dark theme" — itself a classic AI-slop tell) slipped past the unit-test gate and were only caught by a later manual QA sweep.
+
+**Goal:** add a **visual & design verification layer** that plugs into the existing verify model (so it's gated, not advisory) and is honest about cost:
+1. **Mechanical:** a static **design-slop scanner** (`yoke design-scan`) that flags the high-signal AI-slop tells and gates on exit code.
+2. **Methodology:** two canon skills — `unslop-ui` (the design rubric) and `visual-verification` (compose a verify pipeline: types + unit + design-scan + a Playwright flow-smoke; capture video only on failure).
+
+Both integrate through one idea: **the project's `verify.command` becomes a pipeline**, and Baustein-H's verify-as-truth makes those gates authoritative.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Design-slop detection | A **TS-native** scanner built into the `yoke` CLI (`yoke design-scan`), not a port of the upstream Python; high-precision static heuristics |
+| Gate model | Exit non-zero when the weighted tell-score exceeds `--max` (default **4**); `--report` lists without failing |
+| Flow / video | **Methodology, not CLI** — the agent drives the wired Playwright MCP per the `visual-verification` skill. Yoke gates + guides; it does not embed a browser. Video capture is **opt-in, on failure only** (token-aware). |
+| Skills | `unslop-ui` (rubric) + `visual-verification` (pipeline + flow-smoke + video-on-failure) → all 3 agents |
+| Attribution | Credit vibecoded-design-tells (MIT) in `ATTRIBUTION.md` + README + the skill |
+| Canon count | 24 → **26** skills |
+| Out of scope (YAGNI) | Embedding Playwright/a browser in the Yoke CLI; structural-layout detection ("centered hero + 3 cards") — left to the rubric + agent eye; auto-fixing slop (the agent fixes, guided by the skill) |
+
+## Architecture
+
+### 1. `src/scan/design.ts` (new) — the static scanner
+Pure + unit-testable. Walks the project's source and scores AI-slop tells.
+
+```ts
+export interface Tell { name: string; weight: number; test: (line: string) => boolean; hint: string }
+export interface Finding { file: string; line: number; tell: string; hint: string; text: string }
+export interface ScanResult { findings: Finding[]; score: number }
+
+export const TELLS: Tell[]            // the curated tell set (below)
+export function scanText(text: string, tells?: Tell[]): { line: number; tell: Tell; text: string }[]
+export function scanDir(dir: string, tells?: Tell[]): ScanResult   // walks files, aggregates
+```
+
+**Curated high-precision tells** (each match adds `weight` to the score):
+
+| Tell | weight | matches (case-insensitive) | hint |
+|---|---|---|---|
+| `ai-purple` | 2 | hex `#6c5ce7\|#7c3aed\|#8b5cf6\|#a855f7\|#9333ea`, or Tailwind `(from\|via\|to)-(purple\|violet\|fuchsia)-(4\|5\|6\|7)00` | AI-purple is the #1 vibecoded tell — choose a real brand color |
+| `gradient-clip-text` | 2 | a line containing both `bg-clip-text` and `text-transparent`, or CSS `-webkit-background-clip:\s*text` near a gradient | gradient hero text reads as AI-slop — solid color + weight instead |
+| `neon-glow` | 2 | Tailwind `(shadow\|drop-shadow)-\[0_0_`, or CSS `box-shadow:[^;]*0\s+0\s+\d{2,}px` with a color | neon glow is a tell — use subtle, neutral elevation |
+| `gradient-overload` | 1 | `bg-gradient-to-` or CSS `linear-gradient(` | gradients everywhere flatten hierarchy — use them sparingly |
+| `emoji-icon` | 1 | an emoji (unicode pictographic) inside a `.tsx/.jsx` line that also contains `<button`, `<a `, `aria-hidden`, or a JSX `>…<` icon slot | emoji-as-icons is a tell — use a real icon set |
+
+File walk: extensions `.css .scss .tsx .jsx .ts .js .html .vue .svelte .astro`; skip `node_modules`, `dist`, `.next`, `build`, `.yoke`, `coverage`, `.git`. The tell set is the default but injectable (for tests). Heuristic by design — documented as high-signal, not exhaustive.
+
+### 2. `src/cli.ts` — `yoke design-scan [dir] [--max=N] [--report]`
+- Runs `scanDir(dir)`, prints findings grouped by tell as `file:line  <tell>  — <hint>`.
+- `--report`: print + summary, **always exit 0** (advisory).
+- default (gate): print + summary; **exit 1 if `score > max`** (default `max=4`), else 0. So a couple incidental matches pass; pervasive slop fails. Designed to sit in a verify pipeline.
+- A small body extracted to `runDesignScan(dir, { max, report }): number` for testability.
+
+### 3. `canon/skills/unslop-ui/SKILL.md` (new) — the rubric
+Agent-facing. Lists the ranked tells (AI-purple gradients, gradient hero text, neon glow, emoji-as-icons, shadcn defaults left unchanged, "centered hero + three cards", homogeneous spacing) and how to fix each. Instructs: before finishing UI work, run `yoke design-scan .` and resolve findings; also apply the structural items the scanner can't see. Credits the research.
+
+### 4. `canon/skills/visual-verification/SKILL.md` (new) — ties it together
+Methodology for UI projects:
+- **Compose the verify pipeline** so the loop gate covers more than units: `verify.command` chains types → unit tests → `yoke design-scan .` → a Playwright flow-smoke. (Baustein-H makes these authoritative.)
+- **Flow-smoke via the wired Playwright MCP:** load the key routes against the dev server, assert they render and the console has **no errors**, screenshot each. This catches the "unwired page / runtime crash" bugs unit tests miss.
+- **Video only when necessary:** capture a video of a flow **only on failure** (or when explicitly debugging a UX issue), then analyse it — keeps tokens down. Never record every run.
+
+### 5. Wiring
+- `canon/manifest.yaml`: add `unslop-ui` + `visual-verification` (kind: methodology).
+- `canon/skills/ATTRIBUTION.md`: credit vibecoded-design-tells (MIT © Carter Johnson).
+- `README.md` (**mandatory**): a "Visual & design verification" section (the scanner + the two skills + the pipeline idea), the catalog updated (24 → 26, methodology group +2), and the test-count badge synced.
+
+## Data flow (gate)
+```
+verify.command =  tsc --noEmit  &&  vitest run  &&  yoke design-scan .  &&  <playwright flow-smoke>
+                                                     │ exit 1 if slop-score > max
+   loop verify (Baustein H: verify is the source of truth) ──► block on any red step
+```
+
+## Testing (subagent-driven TDD)
+- **design.ts:** `scanText` flags each tell with correct line + weight; clean text → no findings; `scanDir` walks + skips ignored dirs + aggregates score; injected tell-set works; emoji/purple/clip/glow/gradient cases each covered; a known-clean snippet scores 0.
+- **cli:** `runDesignScan` exits 1 when score > max, 0 when ≤ max, 0 always in `--report`; `--max` parsed; bad `--max` rejected.
+- **canon:** `unslop-ui` + `visual-verification` registered; `validateCanon` stays zero-error; real-canon asserts both present.
+- Full suite green; `tsc` clean.
+
+## What this would have caught
+- NewMarket's old **purple `#6c5ce7` dark theme** → `ai-purple` tell, scored, flagged before it shipped.
+- **Unwired auth pages / runtime crashes** → the flow-smoke (render + no console errors) gate, not the unit tests.
+
+## Non-goals (YAGNI)
+- No browser embedded in the Yoke CLI (Playwright MCP is the agent's tool).
+- No always-on video (opt-in, on failure).
+- No auto-rewrite of slop (the agent fixes via the rubric).
+- No structural-layout static detection (rubric + agent eye).