mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-09 06:28:59 +02:00
docs: NOTICE, Apache license text, README interop, project structure
NOTICE.md names what gstack derived from impeccable (rule ids and names in the catalog and the registry fixture; the visitor modes, craft-floor reflexes, and calibration in the design resolvers; the font procedure in the consultation template) and from Google's DESIGN.md specification (the format lib/design-md.ts implements), states that gstack does not distribute or audit the impeccable engine, and points at licenses/Apache-2.0.txt (verbatim). README: the design-consultation, design-review, and design-html rows say what changes when impeccable or the open DESIGN.md format is in play, and a "Works with impeccable" paragraph explains the pre-pass, the shared ids, PRODUCT.md and DESIGN.md as the shared surface, the handoffs, the no-nag posture without impeccable, and the off switch. docs/skills.md gets the detector paragraph under /design-review. docs/PROJECT_STRUCTURE.md lists the new lib and bin files, NOTICE.md, and licenses/. docs/designs/IMPECCABLE_INTEROP.md promotes the CEO plan (its ~/.gstack copy is flipped to PROMOTED) with a "what shipped" summary. TODOS.md files the seven deferrals from the reviews: the design-review Phases 7-11 carve (the budget lever, with the +2.87K vs 2.5K landing recorded), the Bun .env audit across bin/*.ts, the Kiro bin/lib gap, the $D check slop rubric, taste-profile interplay, the CEO Section 11 bullets, and the scan cache. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
co-authored by
Claude Fable 5.1
Claude Fable 5.1
parent
59cfa1547f
commit
f1ce46eb8b
@@ -0,0 +1,35 @@
|
||||
# Third-Party Notices
|
||||
|
||||
gstack is MIT. The files below contain material derived from Apache-2.0 works,
|
||||
rewritten in gstack's voice and modified. Rewriting is not an exemption: the
|
||||
license text is in `licenses/Apache-2.0.txt`, and each derived file carries a
|
||||
notice that it was changed. Unmodified copies (the rule-registry fixture, the
|
||||
license text) carry no header and are listed here instead.
|
||||
|
||||
## impeccable — Copyright Paul Bakaus — Apache License 2.0
|
||||
|
||||
https://github.com/pbakaus/impeccable
|
||||
|
||||
Derived, modified:
|
||||
|
||||
- `lib/design-catalog.ts`: rule ids and names from `crates/live/assets/antipatterns.json`; the prose is gstack's.
|
||||
- `scripts/resolvers/design.ts`: the Persuade / Operate / Read / Experience visitor modes, the craft-floor reflexes (browser surfaces, one authored motion moment, depth has an offset, tinted secondary text, space above headings, light-or-dark from the use scene), and the three-looks calibration, from `SKILL.md`, `reference/craft-floor.md`, and `reference/new-work.md`, rewritten.
|
||||
- `design-consultation/sections/proposal-and-preview.md.tmpl`: the font-selection procedure and the calibration paragraph, rewritten; and the `SKILL.md` / `sections/*.md` files generated from these sources.
|
||||
|
||||
Unmodified copy:
|
||||
|
||||
- `test/fixtures/impeccable-antipatterns.json`: `crates/live/assets/antipatterns.json` at commit 87d8f6d6 (engine-v0.1.3), wrapped in a `_source` provenance object.
|
||||
|
||||
Not distributed: `bin/gstack-design-detect.ts` invokes an impeccable engine the
|
||||
user installed. gstack does not ship, download, or install that engine, and does
|
||||
not audit its network behavior; the wrapper refuses URL targets so gstack never
|
||||
asks it to touch the network.
|
||||
|
||||
## DESIGN.md specification — Copyright Google LLC — Apache License 2.0
|
||||
|
||||
https://github.com/google-labs-code/design.md
|
||||
|
||||
`lib/design-md.ts`, `bin/gstack-design-md.ts`, and the Phase 6 template in
|
||||
`design-consultation/sections/proposal-and-preview.md.tmpl` implement the
|
||||
format (YAML token front matter in five groups, eight canonical sections in
|
||||
spec order, `{path}` token references). No specification text is reproduced.
|
||||
@@ -201,13 +201,13 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
|
||||
| `/plan-eng-review` | **Eng Manager** | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. |
|
||||
| `/plan-design-review` | **Senior Designer** | Rates each design dimension 0-10, explains what a 10 looks like, then edits the plan to get there. AI Slop detection. Interactive — one AskUserQuestion per design choice. |
|
||||
| `/plan-devex-review` | **Developer Experience Lead** | Interactive DX review: explores developer personas, benchmarks against competitors' TTHW, designs your magical moment, traces friction points step by step. Three modes: DX EXPANSION, DX POLISH, DX TRIAGE. 20-45 forcing questions. |
|
||||
| `/design-consultation` | **Design Partner** | Build a complete design system from scratch. Researches the landscape, proposes creative risks, generates realistic product mockups. |
|
||||
| `/design-consultation` | **Design Partner** | Build a complete design system from scratch. Researches the landscape, proposes creative risks, generates realistic product mockups. Writes `DESIGN.md` in the open DESIGN.md format, so impeccable, Google Stitch, and any tool that reads it share one file. |
|
||||
| `/review` | **Staff Engineer** | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. Advisory simplification lens flags over-built code — never blocks, never auto-applies. |
|
||||
| `/investigate` | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
|
||||
| `/design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. |
|
||||
| `/design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. If you have impeccable installed, its engine runs first and every mechanical finding arrives tagged with its rule id. |
|
||||
| `/devex-review` | **DX Tester** | Live developer experience audit. Actually tests your onboarding: navigates docs, tries the getting started flow, times TTHW, screenshots errors. Compares against `/plan-devex-review` scores — the boomerang that shows if your plan matched reality. |
|
||||
| `/design-shotgun` | **Design Explorer** | "Show me options." Generates 4-6 AI mockup variants, opens a comparison board in your browser, collects your feedback, and iterates. Taste memory learns what you like. Repeat until you love something, then hand it to `/design-html`. |
|
||||
| `/design-html` | **Design Engineer** | Turn a mockup into production HTML that actually works. Pretext computed layout: text reflows, heights adjust, layouts are dynamic. 30KB, zero deps. Detects React/Svelte/Vue. Smart API routing per design type (landing page vs dashboard vs form). The output is shippable, not a demo. |
|
||||
| `/design-html` | **Design Engineer** | Turn a mockup into production HTML that actually works. Pretext computed layout: text reflows, heights adjust, layouts are dynamic. 30KB, zero deps. Detects React/Svelte/Vue. Smart API routing per design type (landing page vs dashboard vs form). One slop-gate pass through the impeccable engine when you have it. The output is shippable, not a demo. |
|
||||
| `/qa` | **QA Lead** | Test your app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. |
|
||||
| `/qa-only` | **QA Reporter** | Same methodology as /qa but report only. Pure bug report without code changes. |
|
||||
| `/pair-agent` | **Multi-Agent Coordinator** | Share gstack's own browser with any AI agent. One command, one paste, connected. Works with OpenClaw, Hermes, Codex, Cursor, or anything that can curl. Each agent gets its own tab. Auto-launches headed mode so you watch everything. Auto-starts ngrok tunnel for remote agents. Scoped tokens, tab isolation, rate limiting, activity attribution. (Runs on the bundled browser — the fallback engine; agents driving Aside just open their own tabs.) |
|
||||
@@ -319,6 +319,8 @@ gstack works well with one sprint. It gets interesting with ten running at once.
|
||||
|
||||
**`/design-shotgun` is how you explore.** You describe what you want. It generates 4-6 AI mockup variants using GPT Image. Then it opens a comparison board in your browser with all variants side by side. You pick favorites, leave feedback ("more whitespace", "bolder headline", "lose the gradient"), and it generates a new round. Repeat until you love something. Taste memory kicks in after a few rounds so it starts biasing toward what you actually like. No more describing your vision in words and hoping the AI gets it. You see options, pick the good ones, and iterate visually.
|
||||
|
||||
**Works with impeccable.** If you use [impeccable](https://impeccable.style) too, gstack does not fight it. gstack runs impeccable's deterministic engine as a pre-pass in `/design-review`, `/review`, `/ship`, and `/design-html` when you have it installed (gstack never installs, downloads, or runs anything that could download it), speaks the same 61 rule ids in its own voice, reads `PRODUCT.md`, writes `DESIGN.md` in the open DESIGN.md format both tools read, and hands deferred findings to `/impeccable <command>`. Without impeccable, nothing changes: no nag, no missing step. `gstack-config set design_detector off` turns the pre-pass off. Attribution for the material gstack derived from impeccable and the DESIGN.md spec is in `NOTICE.md`.
|
||||
|
||||
**`/design-html` makes it real.** Take that approved mockup (from `/design-shotgun`, a CEO plan, a design review, or just a description) and turn it into production-quality HTML/CSS. Not the kind of AI HTML that looks fine at one viewport width and breaks everywhere else. This uses Pretext for computed text layout: text actually reflows on resize, heights adjust to content, layouts are dynamic. 30KB overhead, zero dependencies. It detects your framework (React, Svelte, Vue) and outputs the right format. Smart API routing picks different Pretext patterns depending on whether it's a landing page, dashboard, form, or card layout. The output is something you'd actually ship, not a demo.
|
||||
|
||||
**`/qa` was a massive unlock.** It let me go from 6 to 12 parallel workers. Claude Code saying *"I SEE THE ISSUE"* and then actually fixing it, generating a regression test, and verifying the fix — that changed how I work. The agent has eyes now.
|
||||
|
||||
@@ -2,6 +2,48 @@
|
||||
|
||||
## NEXT PRIORITY
|
||||
|
||||
### P2/P3: impeccable interop deferrals (filed 2026-09-08, from the CEO + eng reviews of docs/designs/IMPECCABLE_INTEROP.md)
|
||||
|
||||
Each item was weighed during the review and deferred with a reason; none blocks
|
||||
the shipped detector, catalog, or open DESIGN.md format.
|
||||
|
||||
- **Carve design-review Phases 7-11 into a section (budget lever)** — design-review's
|
||||
eager tokens landed at +2.87K against the review's 2.5K target after every
|
||||
planned lever (ids-only detector rules in category 9, the dump script moved to
|
||||
`lib/dom-dump.js`, trimmed prose); the ceiling in
|
||||
`test/fixtures/context-budget.json` moved to the measured 31,319. The next real
|
||||
lever is carving the fix loop (Phases 7-11) into a section, which touches the
|
||||
E2E copy logic in `test/skill-e2e-design.test.ts`. Effort M. Priority P2.
|
||||
- **Bun `.env` auto-load audit across `bin/*.ts`** — Bun loads a cwd `.env` into
|
||||
`process.env` even for a script outside cwd. `gstack-design-detect.ts` and
|
||||
`gstack-design-md.ts` render with `--no-env-file` and ignore in-repo
|
||||
`IMPECCABLE_BIN` / `IMPECCABLE_HOME`; every other `bun run
|
||||
~/.claude/skills/gstack/bin/*.ts` a skill renders has the same exposure for any
|
||||
env-driven exec path. Audit them, render `--no-env-file` where an env var can
|
||||
name a binary or a path. Effort S. Priority P2.
|
||||
- **Kiro install arm links `SKILL.md` and `sections/` only** — every gstack
|
||||
`bin/` path a Kiro render carries (the detector, the DESIGN.md tool, the render
|
||||
CLI, review-log, diff-scope) is a pre-existing gap on that host. Link `bin/`
|
||||
and `lib/` together there like the other arms (`setup` ~2341). Effort S.
|
||||
Priority P2. Collaborative repo, not fixed in the interop PR.
|
||||
- **`$D check` slop rubric** — add the catalog's LLM-only tells (hero metrics,
|
||||
identical cards, glassmorphism, content stand-ins) to `design/src/check.ts`'s
|
||||
vision pass once those entries have been exercised in reviews. Open questions:
|
||||
a paid GPT-4o call per variant, and vision misjudging cream palettes and nested
|
||||
cards. Effort M. Priority P3.
|
||||
- **Taste-profile interplay for `overused-font`** — downgrade a detector
|
||||
overused-font hit to polish when the face is in the user's approved taste
|
||||
profile. Today `impeccable hooks ignore-value overused-font <face>` covers it
|
||||
without coupling the two schemas. Effort S. Priority P3.
|
||||
- **plan-ceo-review Section 11 catalog bullets** — render `{{DESIGN_SLOP_BULLETS}}`
|
||||
into the CEO review's design section. Blocked on the plan-ceo-review doctrine
|
||||
carve (~555 B of skeleton headroom today). Effort S. Priority P3.
|
||||
- **Detector scan cache** — cache `gstack-design-detect.ts scan` results under
|
||||
`${GSTACK_HOME}/cache/design-detect/` keyed on engine hash, target-set hash,
|
||||
and `.impeccable/config*.json` hash, so Phase 9's rescan and repeated ship
|
||||
reviews skip unchanged files. Effort S. Priority P3.
|
||||
|
||||
|
||||
### P2: fork-port residual wave deferrals (filed at Wave A, 2026-09-03)
|
||||
|
||||
Filed from the time-attack/gstack residual evaluation
|
||||
|
||||
@@ -63,7 +63,7 @@ gstack/
|
||||
├── freeze/ # /freeze skill; bin/check-freeze.sh (PreToolUse edit-boundary hook; sources careful/bin/hook-extract.sh, fails closed)
|
||||
├── guard/, unfreeze/ # /guard (careful + freeze in one), /unfreeze
|
||||
├── gstack-upgrade/ # /gstack-upgrade skill + migrations/ (run after ./setup during an upgrade)
|
||||
├── bin/ # CLI utilities (gstack-render.ts = render a local HTML file through Aside or the engine, gstack-repo-mode, gstack-slug, gstack-config, gstack-wtree, gstack-evidence, gstack-issue-guard, gstack-relink, etc.)
|
||||
├── bin/ # CLI utilities (gstack-render.ts = render a local HTML file through Aside or the engine; gstack-design-detect.ts = probe/scan through a user-installed impeccable engine; gstack-design-md.ts = open DESIGN.md check/convert/tokens/mark; gstack-repo-mode, gstack-slug, gstack-config, gstack-wtree, gstack-evidence, gstack-issue-guard, gstack-relink, etc.)
|
||||
├── document-release/ # /document-release skill (post-ship doc updates + Diataxis coverage map)
|
||||
├── document-generate/ # /document-generate skill (Diataxis doc generator: tutorial/how-to/reference/explanation)
|
||||
├── cso/ # /cso skill (OWASP Top 10 + STRIDE security audit)
|
||||
@@ -81,7 +81,7 @@ gstack/
|
||||
│ └── dist/ # Compiled binary
|
||||
├── agents-digest/ # Committed 2KB instruction-tier rules digest (gstack-AGENTS.md) for rules-reading hosts
|
||||
├── extension/ # Chrome extension (side panel + activity feed + CSS inspector)
|
||||
├── lib/ # Shared libraries (aside-render.ts = local-HTML rendering, Aside first, engine fallback; claude-bin.ts, error-handling.ts, worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, tracker-guard.ts, version-source.ts, code-intelligence/)
|
||||
├── lib/ # Shared libraries (aside-render.ts = local-HTML rendering, Aside first, engine fallback; design-catalog.ts = the typed design anti-pattern catalog every design skill renders from; design-detect-contract.ts = detector sentinel vocabulary; design-md.ts = open DESIGN.md reader/writer; dom-dump-script.ts + generated dom-dump.js = rendered-DOM dump for the detector; frontend-scope.ts; claude-bin.ts, error-handling.ts, worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, tracker-guard.ts, version-source.ts, code-intelligence/)
|
||||
│ └── diagram-render/ # Vendored mermaid + excalidraw runtimes, built into one offline bundle the renderer loads
|
||||
├── patches/ # bun `patchedDependencies` patches (playwright-core windowsHide)
|
||||
├── docs/designs/ # Design documents (incl. fork-port-residual-2026-09/ evaluation evidence)
|
||||
@@ -95,5 +95,7 @@ gstack/
|
||||
├── SKILL.md # Generated from SKILL.md.tmpl (don't edit directly)
|
||||
├── SKILL.md.tmpl # Template: edit this, run gen:skill-docs
|
||||
├── ETHOS.md # Builder philosophy (Boil the Ocean, Search Before Building)
|
||||
├── NOTICE.md # Third-party notices: material derived from impeccable and the DESIGN.md spec (both Apache-2.0)
|
||||
├── licenses/ # Verbatim license texts for the notices above (Apache-2.0.txt)
|
||||
└── package.json # Build scripts for browse
|
||||
```
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# 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 installs, downloads, or runs anything that could download) 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`.
|
||||
|
||||
## 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(", ") + "."` 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: `IMPECCABLE_HOOK: present` suppresses the source-mode scan only (the hook already scans edited files). 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 (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, otherwise the resolved binary 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).
|
||||
@@ -401,6 +401,8 @@ It runs an 80-item visual audit on your live site — in your Aside browser, so
|
||||
|
||||
The self-regulation heuristic is tuned for design work — CSS-only changes get a free pass (they are inherently safe and reversible), but changes to component JSX/TSX files count against the risk budget. Hard cap at 30 fixes. If the risk score exceeds 20%, it stops and asks.
|
||||
|
||||
**Design detector.** When you have [impeccable](https://impeccable.style) installed, its engine runs first: on a URL the page's rendered DOM is dumped (linked styles inlined) and scanned; on a feature branch with no URL the changed frontend files are scanned. Every mechanical finding arrives as a `FINDING-NNN` tagged with its rule id (`[nested-cards]`, `[low-contrast]`), and the report closes with `Detector: N → M`. gstack never installs or downloads the engine; without it the audit is unchanged, with no nag. `gstack-config set design_detector off` disables the pre-pass.
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
|
||||
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
Reference in New Issue
Block a user