gstack/docs/designs/IMPECCABLE_INTEROP.md

# impeccable interop — gstack's design skills and the impeccable engine, catalog, and open DESIGN.md format

**Status:** Shipped on `tehran-v1` (one PR, 13 bisected commits). Promoted from the CEO plan at `~/.gstack/projects/garrytan-gstack/ceo-plans/2026-09-08-impeccable-design-interop.md`.
**Last updated:** 2026-09-08
**Authors:** garrytan (with /plan-ceo-review, /plan-eng-review, and two Codex outside-voice passes)

## What shipped

- **Detector pre-pass.** `bin/gstack-design-detect.ts` probes for an impeccable engine the user installed (never runs impeccable's installer or launcher; after the review a consent-gated download of the engine binary itself was added: one question asked once, checksum-pinned in `lib/design-detect-contract.ts`, receipted fail-closed, installing no skill and no hook) and scans local files with it. `/design-review` (source mode on a diff, DOM mode on a URL through a rendered-DOM dump), `/ship` review-lite, `/review`'s Design specialist, and `/design-html`'s one-pass slop gate run it when `IMPECCABLE_READY`. Sentinel vocabulary: `lib/design-detect-contract.ts`. Off switch: `gstack-config set design_detector off`.
- **One typed catalog.** `lib/design-catalog.ts` replaced four drifting slop lists. Every one of impeccable's 61 rule ids is mapped with gstack prose, tier, impact, confidence, and `/impeccable` handoff; gstack-only judgment tells have no brackets. `review/design-checklist.md` and `lib/dom-dump.js` are generated from `lib/`.
- **Doctrine.** Persuade / Operate / Read / Experience modes, the craft-floor reflexes, the three-looks calibration, a font procedure with role-scoped overused lists, Restrained / Committed / Full palette / Drenched color strategies.
- **Open DESIGN.md format.** `lib/design-md.ts` + `bin/gstack-design-md.ts` read, convert, and write the google-labs-code/design.md format; the conversion answer is persisted in the file's marker line. gstack's own DESIGN.md is converted.
- **Generation-time guard.** The design binary's image prompt carries a "Never:" line built from ten catalog ids.
- **Attribution.** `NOTICE.md` + `licenses/Apache-2.0.txt`.

## Plugin discovery follow-up (2026-09-25)

The detector recognizes Claude Code marketplace installs at
`${CLAUDE_CONFIG_DIR:-~/.claude}/plugins/cache/<marketplace>/<plugin>/<version>/skills/impeccable/`
as well as traditional skill installs. A trusted absolute `CLAUDE_CONFIG_DIR`
replaces the default Claude user profile for both layouts. Relative, missing,
non-directory, or repository-resolving overrides are ignored; `probe --verbose`
explains the fallback. No Claude settings, plugin registry, or hook configuration
is changed.

Within each marketplace/plugin, discovery selects the newest semver directory
with a regular `SKILL.md`, including prerelease ordering. Equal versions use the
directory name as a stable tie-breaker. Hash and `unknown` directories remain
supported after semver candidates in stable name order; their names do not prove
recency. An incomplete directory is skipped, but a valid newer skill without an
engine does not borrow an older plugin's engine. Launcher, bundled engine and
engine `VERSION` stay associated with the selected installation. Plugin version
numbers never replace engine compatibility evidence.

Traditional user skill installs precede plugin candidates; explicit
`IMPECCABLE_BIN`, an accepted PATH binary and the standalone engine cache retain
their existing higher priority. The standalone engine cache shares strict
semver ordering so an rc directory cannot win over its stable release; unlike
plugin discovery, it still rejects opaque names. Multiple marketplaces/plugins are ordered by
name. A ready engine suppresses the install offer; a missing engine retains the
existing consent and never-ask controls. `IMPECCABLE_SKILL: present` still means
files were found on disk, not that a cached plugin is enabled in the current
Claude session. `IMPECCABLE_ENGINE_UNTESTED` remains an honest warning for engines
outside the captured test set.

Discovery is a fixed-depth, read-only filesystem walk. It does not execute
launchers, install plugins, prune caches, or recursively search arbitrary home
directories. Resolved paths inside the reviewed project are not executable
candidates, including symlinked installs. Cache traversal skips directory
symlinks and rejects a cache that resolves outside its configuration directory;
repository configuration links cannot redirect the walk outside the project.
Canonical HOME comparisons preserve
user installs when the home directory is
accessed through an alias, without allowing arbitrary home files as scan targets.
Verbose output records rejected paths and filesystem errors without breaking the
sentinel protocol. Runnable launcher
hints use POSIX-shell quoting; control-character or Markdown-breaking names and
Windows receive non-command guidance instead. The raw path used for engine
execution is separate from its sanitized display.

Regressions live in `test/gstack-design-detect.test.ts`; the plugin handoff agent
case in `test/skill-e2e-design.test.ts` exercises the actual discovery-to-report
path without an explicit engine override. Native Windows executable behavior and
macOS path alias behavior require their own platform results; Linux fixture
passes are not evidence of those native runs.

## CEO plan (promoted)

### CEO Plan: impeccable.style interop for gstack's design skills
Generated by /plan-ceo-review on 2026-09-08
Branch: tehran-v1 | Mode: SELECTIVE EXPANSION
Repo: garrytan/gstack

## Vision

### 10x Check

Every AI design skill on the market is a prose vocabulary, and two vocabularies loaded together cancel out (impeccable's own docs say so). The 10x version of "incorporate impeccable" is not a fifth vocabulary. It is gstack as the design orchestrator: it runs every deterministic check the ecosystem offers (today: impeccable's 61-rule engine, when the user installed it), speaks the shared rule ids in its own voice, reads and writes the open DESIGN.md interchange format that Google Stitch and impeccable both use, and keeps the three things nobody else has: a live-site design audit through the user's real browser (Aside), image mockups with a comparison board, and a plan-stage design review before a line of UI is written.

What the user feels: `/design-review` opens with the machine's findings already on the table, each tagged `[side-tab]` or `[nested-cards]`, then spends its judgment on hierarchy, trust, and copy. `/design-consultation` writes a DESIGN.md that impeccable, Stitch, and any future tool read without translation. The mockup board stops showing purple gradients because the generator prompt was told not to reach for them. And when the user has impeccable installed, every deferred finding ends with the command that fixes it.

### Platonic Ideal

Not run (SELECTIVE EXPANSION mode).

## Scope Decisions

| # | Proposal | Effort | Decision | Reasoning |
|---|----------|--------|----------|-----------|
| 1 | "Never:" line in `design/src/brief.ts` `briefToPrompt()` built from a pinned `MOCKUP_NEVER_NAMES` export (ten catalog ids, plain-English names, deduped) | S (human ~2 h / CC ~10 min) | ACCEPTED | Cheapest win in the plan: slop stopped at mockup generation; prompt text only; `design/test/brief.test.ts` added (no brief test exists today) |
| 2 | Detector on live URLs via a rendered-DOM dump (one shared dump script for both engines; Aside writes under `pwd`, browse engine writes under a temp dir via `$B eval --out --raw`; bash copies both into `$REPORT_DIR/dom/`), scanned by the static engine; wrapper allow-lists `${GSTACK_HOME:-$HOME/.gstack}/projects/*/designs/` as a scan root | M (human ~1.5 days / CC ~40 min) | ACCEPTED | Resolves the tension between Phase 0 scanning source and design-review Rule 4 ("never read source"); works on deployed sites; the wrapper root check, the dump script, and the `$REPORT_DIR` path fix are the real work |
| 3 | `detector: {mode, engine, total, byRule}` in `design-baseline.json`; regression mode reports ids that appeared and disappeared when `mode` matches, with an `engine changed` caveat when the engine differs | S (human ~4 h / CC ~15 min) | ACCEPTED | The number is already computed; tracked per rule id across runs; the mode gate and the engine caveat keep source-vs-DOM and engine upgrades from reading as regressions |
| 4 | Slop rubric in `$D check` (GPT-4o vision) | M (human ~2 days / CC ~40 min) | DEFERRED | Paid call per variant; vision misjudges cream palettes and nested cards; revisit once catalog LLM-tells are exercised |
| 5 | Taste-profile interplay for `overused-font` hits | S (human ~4 h / CC ~15 min) | DEFERRED | `.impeccable/config.json` ignore-value already covers the case without coupling two schemas |
| 6 | Catalog bullets in plan-ceo-review Section 11 | S | DEFERRED | plan-ceo-review skeleton has ~555 B of carve headroom; sequence after the doctrine-carve TODO |

Implementation approach decision (D1): B, the reviewed 13-commit plan, over A (detector only, 5/10) and C (B plus generation-time enforcement, 10/10). C's free half (proposal 1) accepted as a cherry-pick; its paid half (proposal 4) deferred.

Delivery: ONE PR (user decision 2026-09-08, overriding the review's two-PR suggestion). Commits stay bisected; goldens regenerated at commits 4, 7, and 9; commits 12 and 13 are whole.

## Accepted Scope (added to this plan)

**1. Generation-time slop guard (commit 7b).** `lib/design-catalog.ts` sets `mockupNever: true` on exactly these ten ids: `kicker-above-heading`, `icon-tile-stack`, `gradient-text`, `ai-color-palette`, `cream-palette`, `nested-cards`, `dark-glow`, `pulsing-dot`, and the gstack-only `identical-cards` and `hero-metrics`. It exports `MOCKUP_NEVER_NAMES: string[]` (their `name` fields, deduped, plain English, no ids). `design/src/brief.ts` `briefToPrompt()` pushes `"Never: " + MOCKUP_NEVER_NAMES.join(", ") + "."` (shipped as `Never by default (unless the brief above asks for it): …`) before its fixed tail. Import path `../../lib/design-catalog` (precedent: `design/src/receipted-fetch.ts` imports `../../lib/egress-receipt`; `scripts/build.sh` bundles relative TS into the binary; `setup` already treats `lib/` mtime as a rebuild trigger). `lib/design-catalog.ts` imports nothing from `scripts/`. The catalog invariant test checks the ten ids; the new `design/test/brief.test.ts` asserts the "Never:" line is present, precedes the fixed tail, and lists `MOCKUP_NEVER_NAMES.length` names. Binary rebuilt by `./setup`; `design/dist/` is never committed.

**2. Detector on live URLs via a rendered-DOM dump (commit 7).**
- Mode rule: the target is a URL (including an explicit `http://localhost:3000` on a feature branch) → DOM mode, no source scan. Diff-aware mode with no URL → source mode over the changed frontend dirs. Stated in the Phase 0 prose so nobody scans source "helpfully".
- Hook rule (superseded before shipping, eng review decision 35): `IMPECCABLE_HOOK: present` never skips a scan; the prose tells the agent to use gstack's rows and ignore the hook's vocabulary. DOM mode scans the dump regardless, because the hook cannot see a rendered page.
- One dump script for both engines, rendered once by the resolver as a fenced JS block, written as an IIFE expression with no single-quote characters (superseded before shipping: the script is an arrow function called in the page, spliced into the single-quoted Aside script and into `$B js '('"$_DUMP"')()'` through a closed-quote segment, never a double-quoted block; see lib/dom-dump-script.ts) (every `aside repl '...'` script is a single-quoted bash string, and `$B eval` wraps an expression): serialize the stylesheets whose `ownerNode` is a `<link>` (inline `<style>` nodes are already in the markup; serializing them too would double-count), catch cross-origin sheets and list them in a trailing HTML comment as unresolved, inject the text as `<style data-gstack-dom-css>` in `<head>`, return `document.documentElement.outerHTML`. Aside: the Phase 3 page script evaluates it, does `fs.writeFile(path.join(pwd, "{page}.dom.html"), html)` (the sandbox `fs` writes only under `pwd`), prints `ASIDE_DIR=`, and bash copies the file to `$REPORT_DIR/dom/`. Browse fallback: `_TMP=$(mktemp -d)`, write the same JS to `$_TMP/dom-dump.js`, run `$B eval "$_TMP/dom-dump.js" --out "$_TMP/{page}.dom.html" --raw` (`--out` accepts only temp dirs or cwd, `browse/src/path-security.ts:26`), then `cp` into `$REPORT_DIR/dom/`. `$B html` is not used: reading commands wrap stdout in untrusted-content markers (`browse/src/server.ts:1249-1255`). The row lives in design-review's own DOM-mode prose in `scripts/resolvers/design.ts`, not in the shared `{{BROWSE_FALLBACK}}` table (that table renders into ten skills). Same script, same serialization on both engines; page content may still differ by session. `{page}` reuses the slug the Phase 3 screenshots already use. In DOM mode, findings' `file:line` point into `{page}.dom.html`; the agent confirms the element in the rendered page (Rule 4), never by hunting a source line.
- `$REPORT_DIR` in `design-review/SKILL.md.tmpl:95` changes from `$HOME/.gstack/...` to `${GSTACK_HOME:-$HOME/.gstack}/...` (as `bin/gstack-slug` already does) so the allow-list and the report dir agree when `GSTACK_HOME` is set. The Output Structure tree at tmpl:119 and the `mkdir` at `design.ts:419` keep their `~/.gstack` shorthand; neither feeds the allow-list.
- Sequencing: in DOM mode the scan runs once, after the last Phase 3 page script has produced its dump; in source mode the scan runs in Setup. Phase 9 recomputes (DOM mode re-dumps the affected pages after reload and rescans; source mode rescans the touched files); Phase 10 reports `Detector: N → M`.
- Scan: `gstack-design-detect.ts scan --format gstack "$REPORT_DIR/dom"`; the wrapper's target validation accepts paths under the repo root OR under `${GSTACK_HOME:-$HOME/.gstack}/projects/*/designs/` (explicit allow-list, tested with a designs path accepted and a non-designs sibling refused). Report line once: "static scan of the rendered DOM; cross-origin CSS not resolved".
- The load-bearing assumption (impeccable's static engine reads inline `<style>` in a `.html` file) is pinned in commit 1, not commit 13: the fixture set includes `review-eval-design-slop.html` served locally, dumped with `$B eval dom-dump.js --out --raw`, and scanned. DOM mode ships in commit 7 on top of that fixture.

**3. Detector counts in the regression baseline (commit 7).** The `design-baseline.json` template and regression prose live in `scripts/resolvers/design.ts` (DESIGN_METHODOLOGY Phase 6, the JSON block and "Regression Output"), not in the skill template; edit there. Field: `detector: { mode: "dom"|"source", engine, total, byRule: {id: n} }`. `engine` is the version parsed from the READY path when it is the `~/.impeccable/bin/<version>/` cache, or from a sibling `VERSION` file, otherwise `sha256:<12 hex>` of the binary (superseded before shipping: never a filesystem path); a version field in `detect --json` output wins if the fixture shows one. Previous baseline = newest `${GSTACK_HOME:-$HOME/.gstack}/projects/$SLUG/designs/design-audit-*/design-baseline.json` older than today's `$REPORT_DIR` (a second run on the same day overwrites today's baseline and compares against the most recent prior day's, by design). Diff only when `mode` matches; otherwise say "detector modes differ (dom vs source), no delta". When `engine` differs, print the delta with the caveat `engine changed X → Y; rule set may differ`. Absent field → "no detector baseline (first scan)", never `+N`. Output: ids that appeared, ids that disappeared, totals, one example row in the prose (`+ kicker-above-heading (2)  - gradient-text (1)  total 14 → 9`). Known limitation stated: live DOM dumps jitter (ads, timestamps, A/B), so count deltas are advisory and id appear/disappear is the signal.

## Deferred to TODOS.md
- `$D check` slop rubric (P3, M): add catalog LLM-only tells to `design/src/check.ts` once the catalog's LLM-tell entries have been exercised in reviews; cost per variant and vision false positives are the open questions.
- Taste-profile interplay (P3, S): downgrade a detector `overused-font` hit to polish when the value is in the user's approved taste profile; today `impeccable hooks ignore-value` covers it.
- plan-ceo-review Section 11 catalog bullets (P3, S): blocked on the plan-ceo-review doctrine carve (TODOS.md line ~1100).

## Reviewer Concerns

Three adversarial review rounds (scores 6 → 8 → 7 out of 10; 26 issues raised, 26 fixed). The nine fixes from round 3 were applied after the last round and are therefore unreviewed: temp-dir `--out` then `cp` for the browse fallback; hook-skip scoped to source mode; `<link>`-only stylesheet inlining; `engine changed` caveat in the diff rule; `$B eval` row kept out of the shared fallback table; the IIFE/no-single-quote constraint on the shared script; DOM-dump fixture captured in commit 1; Phase 9 computes and Phase 10 reports; wording (session-dependent dumps, prior-day baseline, `{page}` placeholder, brief test asserts `MOCKUP_NEVER_NAMES.length`). Residual risk the reviewers named and this plan accepts: design-review's eager budget will need its fixture refreshed in commit 7 (expected, not conditional).