impeccable Documentation

Technical Documentation: pbakaus/impeccable

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Impeccable

Design guidance for AI coding agents. 1 skill, 24 commands, live browser iteration, and 59 deterministic detector rules for AI-generated frontend design.

Quick start: From your project root, run npx impeccable install, then run /impeccable init inside your AI coding tool. Full docs: impeccable.style.

Why Impeccable? Copy Chapter

Anthropic's frontend-design was the first widely-used design skill for Claude. Impeccable started from there.

Every model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project: Inter for everything, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.

Impeccable adds:

• One setup flow. /impeccable init records durable product truth in PRODUCT.md, so later commands know the audience, purpose, operating context, constraints, voice, and evidence without confusing those facts with surface-level visual direction.
• 24 commands. A shared design vocabulary with your AI: polish, audit, critique, distill, animate, bolder, quieter, and more.
• 59 deterministic detector rules plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.

What's Included Copy Chapter

The Skill: impeccable Copy Section

The skill installs as one command:

/impeccable <command> <target>

Start every new project with:

/impeccable init

init inspects the project, asks only for material gaps in durable product truth, and writes PRODUCT.md. Visitor mode and visual direction are chosen later for each surface; incumbent or newly built visual systems are recorded separately in DESIGN.md.

24 Commands Copy Section

All commands are accessed through /impeccable:

Use /impeccable pin <command> to create standalone shortcuts (e.g., pin audit creates /audit).

Usage Examples

/impeccable audit blog           # Audit blog hub + post pages
/impeccable critique landing     # UX design review
/impeccable polish settings      # Final pass before shipping
/impeccable harden checkout      # Add error handling + edge cases

Or use /impeccable directly with a description:

/impeccable redo this hero section

Anti-Patterns Copy Section

The skill includes explicit guidance on what to avoid:

• Don't use overused fonts (Arial, Inter, system defaults)
• Don't use gray text on colored backgrounds
• Don't use pure black/gray (always tint)
• Don't wrap everything in cards or nest cards inside cards
• Don't use bounce/elastic easing (feels dated)

See It In Action Copy Chapter

Visit the Neo Mirai case study to see a before/after case study of a real project transformed with Impeccable commands.

Installation Copy Chapter

The skill needs no runtime of its own. Every skill copy ships a small launcher (scripts/impeccable, plus impeccable.cmd for Windows) that runs the Impeccable engine, a self-contained binary that either sits next to the launcher or is downloaded once on first run into ~/.impeccable/bin/. Node is only involved if you use the npx impeccable installer, which is a shim around the same binary; the manual and Git options below work without it.

Option 1: CLI installer (Recommended) Copy Section

From the root of your project, run:

npx impeccable install

This shows the harness folders or installed CLIs it detected (for example ~/.claude, ~/.codex, ~/.grok, ~/.hermes, ~/.veto, or project-local .cursor), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use --providers=claude,codex,cursor,grok,hermes,veto and --scope=project|global to skip those choices in scripts. On Claude Code, Cursor, Codex, GitHub Copilot, and Grok Build, it also installs the provider-native hook manifest for the current project. Veto receives the packaged skill under ~/.veto/skills/ and does not run native Impeccable edit hooks. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, Hermes Agent, Veto, and every other supported tool. Reload your harness afterward.

To refresh an existing install, run:

npx impeccable update

Codex users should open /hooks after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change .codex/hooks.json can require approval again. Grok Build users need project folder trust (/hooks-trust or launch with --trust) before .grok/hooks/ scripts run.

See Allow the hook in your harness for harness-specific trust and verification steps.

Option 2: Git Submodule Copy Section

For teams that want to keep Impeccable vendored and updated through Git, add this repo as a submodule and link the compiled provider build into your harness folders:

git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor
git add .gitmodules .impeccable .claude .cursor
git commit -m "Add Impeccable skills"

Use the providers your project needs, for example claude, cursor, gemini, codex, github, grok, hermes, opencode, pi, qoder, trae, trae-cn, rovo-dev, vibe, or veto. The command links individual skill folders from .impeccable/dist/universal/ and leaves existing real skill directories untouched unless you pass --force.

To update later:

git submodule update --remote .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor

Option 3: Plugin install Copy Section

GitHub Copilot in VS Code:

Install Impeccable from the Visual Studio Marketplace, or run:

code --install-extension renaissance-geek.impeccable

Requires VS Code 1.109.3+, Copilot Chat access, and a trusted local workspace. Open Chat in Agent mode and try /impeccable polish. This skill-only extension does not install automatic hooks; avoid a duplicate Impeccable skill in the same workspace/profile. See VS Code distribution details.

Claude Code:

/plugin marketplace add pbakaus/impeccable

Claude Code only. After adding the marketplace, open /plugin and install Impeccable from the list.

Grok Build:

grok plugin install pbakaus/impeccable#plugin --trust

Grok Build only. The #plugin suffix installs the slim plugin package (skills, agents, and hooks) instead of the full monorepo. Then run /impeccable init in a Grok session. Project-scoped installs via npx impeccable install --providers=grok also work and write .grok/skills/ plus .grok/hooks/impeccable.json.

Option 4: Download from Website Copy Section

Visit impeccable.style, download the ZIP for your tool, and extract to your project.

Option 5: Copy from Repository Copy Section

Cursor:

cp -r dist/cursor/.cursor your-project/

Note: Cursor skills require setup:

1. Switch to Nightly channel in Cursor Settings → Beta
2. Enable Agent Skills in Cursor Settings → Rules

Learn more about Cursor skills

Claude Code:

# Project-specific
cp -r dist/claude-code/.claude your-project/

# Or global (applies to all projects)
cp -r dist/claude-code/.claude/* ~/.claude/

OpenCode:

cp -r dist/opencode/.opencode your-project/

DeepSeek Harness:

# Project-specific
cp -r dist/dsh/.dsh your-project/

# Or global (applies to all projects)
mkdir -p "${DSH_HOME:-$HOME/.dsh}/skills"
cp -r dist/dsh/.dsh/skills/* "${DSH_HOME:-$HOME/.dsh}/skills/"

The CLI honors DSH_HOME only when it resolves inside your home directory (or to home itself); otherwise it uses ~/.dsh. An outside-home manual copy is not managed by impeccable install/update.

Hermes Agent:

# Global (applies to all projects; uses the active profile, or ~/.hermes by default)
cp -r dist/hermes/.hermes/skills/* "${HERMES_HOME:-$HOME/.hermes}/skills/"

# Or project-specific
cp -r dist/hermes/.hermes your-project/

Note: Hermes gates project-local skills behind a per-repo trust decision
(they are procedure documents, so auto-loading them from any cloned repo is
treated as a prompt-injection vector). After a project-scoped install, run
hermes skills trust once from the project root. Global installs into the
active $HERMES_HOME/skills/ (or ~/.hermes/skills/ when unset) load without
a trust step. /impeccable <command> then
routes through the skill's Commands table; the design hook does not install
on Hermes (no hook surface).

Learn more about Hermes skills

Pi:

cp -r dist/pi/.pi your-project/

Gemini CLI:

cp -r dist/gemini/.gemini your-project/

Note: Gemini CLI skills require setup:

1. Install preview version: npm i @google/gemini-cli@preview
2. Run /settings and enable "Skills"
3. Run /skills list to verify installation

Learn more about Gemini CLI skills

Codex CLI:

# Project-local
cp -r dist/agents/.agents your-project/
mkdir -p your-project/.codex
cp dist/codex/.codex/hooks.json your-project/.codex/hooks.json

# Or install the skill user-wide. Copy .codex/hooks.json into each project
# where you want the design hook to run.
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/

The asset-producer subagent ships nested inside the skill's own agents/ folder, which Codex auto-discovers. No separate .codex/agents/ copy is needed. The hook is project-local because Codex discovers hooks from .codex/hooks.json next to trusted project config.

GitHub Copilot:

cp -r dist/github/.github your-project/

Trae:

# Trae China (domestic version)
cp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/

# Trae International
cp -r dist/trae/.trae/skills/* ~/.trae/skills/

Note: Trae has two versions with different config directories:

• Trae China: ~/.trae-cn/skills/
• Trae International: ~/.trae/skills/

After copying, restart Trae IDE to activate the skills.

Rovo Dev:

# Project-specific
cp -r dist/rovo-dev/.rovodev your-project/

# Or global (applies to all projects)
cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/

Qoder:

# Project-specific
cp -r dist/qoder/.qoder your-project/

# Or global (applies to all projects)
cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/

Mistral Vibe:

# Project-specific
cp -r dist/vibe/.vibe your-project/

# Or global (applies to all projects)
cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/

Grok Build:

# Project-specific
cp -r dist/grok/.grok your-project/

# Or global (applies to all projects)
cp -r dist/grok/.grok/skills/* ~/.grok/skills/

Prefer npx impeccable install --providers=grok or grok plugin install pbakaus/impeccable#plugin --trust so the design hook installs too. Project hooks need /hooks-trust (or --trust) once per folder.

Google Antigravity:

# Project-specific
cp -r dist/antigravity/.agent your-project/

# Or global (applies to all projects)
mkdir -p ~/.gemini/config/skills
cp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/

Usage Copy Chapter

Once installed, every command runs through the single /impeccable skill:

/impeccable audit        # Find issues
/impeccable polish       # Final cleanup
/impeccable distill      # Remove complexity
/impeccable critique     # Full design review

Type /impeccable alone to see the full command list.

Most commands accept an optional argument to focus on a specific area:

/impeccable audit the header
/impeccable polish the checkout form

If you reach for one command often, pin it with /impeccable pin audit to get /audit as a standalone shortcut.

Note: Codex uses skills here, not /prompts: commands. Open /skills or type $impeccable. Repo-local installs live in .agents/skills/; user-wide installs live in ~/.agents/skills/. GitHub Copilot uses .github/skills/. Restart the tool if a newly installed skill does not appear.

Keeping `.impeccable` out of git Copy Chapter

As you run commands, Impeccable writes working files under .impeccable/: critique and polish screenshots, live-mode session and preview state, runtime caches, and per-developer config. Most of it is ephemeral and should not be committed, while a few files are shared project artifacts that belong in the repo. Add this block to your project's .gitignore:

# impeccable-ignore-start
# Ephemeral output, runtime state, and per-dev overrides.
# The **/ prefix covers .impeccable at the repo root or in a nested workspace.
# Shared artifacts stay tracked: config.json, live/config.json,
# design.json, surfaces/*.md, critique/*.md.
**/.impeccable/config.local.json
**/.impeccable/hook.cache.json
**/.impeccable/hook.pending.json
**/.impeccable/*.png
**/.impeccable/review/
**/.impeccable/questions/
**/.impeccable/live/server.json
**/.impeccable/live/sessions/
**/.impeccable/live/previews/
**/.impeccable/live/annotations/
**/.impeccable/live/cache/
**/.impeccable/live/manual-edit-apply-transaction.json
**/.impeccable/live/manual-edit-events.jsonl
**/.impeccable/live/manual-edit-evidence/
**/.impeccable/live/pending-manual-edits.json
**/.impeccable/live/deferred-svelte-component-accepts.json
**/.impeccable/live/*.png
# impeccable-ignore-end

The block is wrapped in # impeccable-ignore-start / # impeccable-ignore-end markers so you can recognize and refresh it later. The **/ prefix makes each pattern match whether the active project's .impeccable/ directory is at the repository root or under a nested workspace path like apps/web/.

Keep these tracked (they are shared project artifacts, do not add them to .gitignore):

• .impeccable/config.json (unified shared config)
• .impeccable/live/config.json (live-mode framework wiring)
• .impeccable/design.json (shared design spec)
• .impeccable/surfaces/*.md (route- or artifact-specific strategy and direction contracts)
• .impeccable/critique/*.md (review reports)

Impeccable also keeps its own .gitignore in the folders that hold decision-round state: .impeccable/questions/ and .impeccable/mocks/worlds/ ignore everything in them, and .impeccable/build/ ignores state.json. That keeps new runtime files out of commits even in a project without the block above. A .gitignore cannot untrack a file git already tracks, though: when one of these files was committed earlier, the next roll prints a one-time notice with the fix, git rm -r --cached .impeccable/questions (plus any other folder it names), and writes its roll record to an untracked file until then.

If an ephemeral file (a screenshot, config.local.json) was committed before you added the block, .gitignore will not untrack it automatically. Run git rm --cached to stop tracking it without deleting your local copy.

Telemetry Copy Chapter

When a new design starts, the skill asks the roll API at impeccable.style to deal a hand of visual worlds from the catalog. That request is the feature, so it always happens. Unless you opt out, it also feeds an anonymous record of which hand was shown and which card won, which is how the catalog learns what works.

What is sent, on the roll request and on the choice that follows it:

• the roll key (a random value per decision round), scope (direction or surface), visitor mode, and re-roll round
• the catalog revision the hand came from, and on the choice the kind of card that won (assigned, pick, challenger, canon, or a re-roll), its catalog id when a catalog world won, and its position on the page
• the client version, whether the choice came from the decision page or the agent, and a random id for that choice so a report sent twice is counted once

Never sent: your project's name, files, code, PRODUCT.md, or the names of the directions your agent wrote. Committed files such as surface briefs record only a seed reference, a hash of the roll key under a random salt kept in ~/.impeccable/seed-salt, never the key itself. If no salt can be kept on a machine, the brief records no seed at all rather than a weaker hash. Roll keys are 128 random bits. If you pass your own short key with --from, its reference is easy to guess, so do not rely on it to keep that key private.

To turn it off, run npx impeccable telemetry off (stored in ~/.impeccable/config.json), or set DO_NOT_TRACK=1 or IMPECCABLE_NO_TELEMETRY=1. A project can opt everyone out with "telemetry": false in .impeccable/config.json. npx impeccable telemetry status shows the current state. Opted out, the roll still works and the API is told not to record it. Details: https://impeccable.style/privacy

Design hook Copy Chapter

On Claude Code, GitHub Copilot, Codex, Cursor, and Grok Build, npx impeccable install and npx impeccable update install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, and Codex surface findings after the edit (and run a deeper pass on Stop where supported). Grok Build scans after the edit to warm Stop, then surfaces on Stop; PostToolUse stdout never reaches the model. Cursor blocks bad proposed writes before they land.

Installed hook surfaces:

• Claude Code: .claude/settings.local.json (gitignored, machine-local) runs ${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/impeccable hook. A hook moved into the shared settings.json is honored in place.
• GitHub Copilot: .github/hooks/impeccable.json (committed, shared by the Copilot CLI and the cloud agent) runs .github/skills/impeccable/scripts/impeccable hook. The Copilot CLI activates it once the file is on the repository's default branch and the folder is trusted.
• Cursor: .cursor/hooks.json runs .cursor/skills/impeccable/scripts/impeccable hook-before-edit.
• Codex: .codex/hooks.json runs .agents/skills/impeccable/scripts/impeccable hook, with a commandWindows sibling that calls impeccable.cmd for cmd.exe.
• Grok Build: .grok/hooks/impeccable.json runs .grok/skills/impeccable/scripts/impeccable hook. Requires /hooks-trust or --trust. Findings reach the model on Stop, not after each edit.

Every command goes through the launcher shipped in the skill's scripts/ directory (impeccable, or impeccable.cmd on Windows), guarded so a missing launcher is a silent no-op. The launcher runs the engine binary that ships next to it, or downloads the pinned version once into ~/.impeccable/bin/. No Node or other runtime is required for the hook or the skill.

In Claude Code, installed command hooks run independently of model-tool approval. The first edit or Stop event can therefore download and cache the engine even if the session denies the model's launcher command. Review installed hooks before unattended runs; to disable all Claude Code hooks for a run, pass --settings '{"disableAllHooks": true}'. See Claude Code's hook security guidance.

The installer preserves unrelated hook entries and settings. If a hook manifest is malformed, install/update aborts by default; rerun with --force to back up the malformed file as .bak and replace it.

On an interactive install/update, Impeccable explains the hook and offers to install it (default yes). Your choice is remembered per-developer in the gitignored .impeccable/config.local.json, so you are not asked again; --no-hooks skips it for that run without recording anything. Hook lifecycle settings live under the hook key of .impeccable/config.json; detector ignores live under detector, shared by /impeccable hooks and npx impeccable detect.

For debugging, set hook.auditLog in .impeccable/config.json to a path (or the legacy IMPECCABLE_HOOK_LOG env var) to write one NDJSON line per hook invocation. Leave it unset for normal use.

Build path: comp-first or code-first Copy Chapter

When a new surface gets designed, Impeccable either generates a full-fidelity comp first and builds to match it, or builds straight in code with the ambition written into a development-only direction contract in the surface brief and checked at the finish. Comp-first composes bolder and takes longer; code-first is leaner and faster. The choice covers landing pages and showcase surfaces. App screens and documents are built code-first either way, because they come out better built than pictured. /impeccable init asks once and records the answer as buildPath in .impeccable/config.json:

{ "buildPath": "comp" }

The values are comp and code, and nothing else is read. Set it in the gitignored .impeccable/config.local.json to override the team's committed value on one machine, which is what you want when your harness has no image generation. In a monorepo, commit it once at the repo root and any workspace that wants something else sets its own. The choice appears at all only where image generation is available, since without it there is nothing to comp.

You do not have to re-run init to set it on a project that predates the setting, and you do not have to edit the file by hand either. Whatever is recorded is a default rather than a lock: every decision page carries a footer toggle, and flipping it binds that session only. Flip it on a project that has recorded nothing and Impeccable asks once, after the round, whether to keep it, then writes your answer. That is the whole migration path for an existing project: use the toggle when the default is wrong, and answer the question that follows.

Codex requires one platform step that Impeccable cannot safely skip: open /hooks after install or update and approve the project hook. There is no Codex marketplace/plugin install flow for this hook.

Full hook docs: impeccable.style/docs/hooks.

The Stop pass suppresses confirmed pre-existing findings when a verified before-edit baseline is available (currently Claude Edit/Write results for text scans). Other findings are marked new or attribution unknown; unknown is not evidence that your session caused the problem. Explicit detect scans remain unchanged.

Manual copy commands are fallback/debug instructions. The normal path is:

npx impeccable install
npx impeccable update

Live mode and production sites Copy Chapter

Live mode edits a local checkout through a development server or local static HTML. Injecting its localhost HTTP helper into a deployed production site, including an HTTPS site, is not supported. Do not disable browser security or weaken production CSP to make it work.

Use live mode only in projects you trust to run locally. Applying copy edits automatically runs package.json's optional scripts["impeccable:manual-edit-validate"] command in a shell, with your user permissions; review that script before using live mode in an unfamiliar checkout.

For production inspection, use npx impeccable detect https://example.com or the browser extension. These inspect the rendered page; they do not provide live variant editing or write changes back to your source.

CLI Copy Chapter

Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness. npx impeccable is a small shim that runs the same engine binary the skill uses (installed as a platform-specific optional dependency, or fetched once into ~/.impeccable/bin/); Node is needed only for npx itself, and you can also download the binary directly and put it on your PATH.

npx impeccable detect src/                   # scan a directory
npx impeccable detect index.html             # scan an HTML file
npx impeccable detect https://example.com    # scan a URL (uses an installed Chrome, Chromium, or Edge)
npx impeccable detect --json .               # CI-friendly JSON output
npx impeccable detect --no-config src/       # raw scan, ignoring project config/context
npx impeccable ignores list                  # show detector ignores
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

The detector catches 59 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).

Human-readable findings are diagnostics written to stderr, so redirect them with 2> findings.txt. Use --json for machine-readable results on stdout. Exit 0 means the scan completed without primary findings, exit 2 means it completed with primary findings, and exit 1 means at least one requested target could not be scanned; operational failure takes precedence for a partial multi-target scan. URL scans inspect the rendered DOM, computed layout, and accessible linked stylesheets; browser security still prevents reading cross-origin CSS without CORS. A clean detector run is evidence, not proof of visual or accessibility quality: it does not replace inspecting the rendered experience across relevant viewports.

By default, detect respects the same .impeccable/config.json and .impeccable/config.local.json detector config as the design hook: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues, and detector.designSystem.enabled. Hook lifecycle settings such as hook.enabled only affect automatic hook execution.

For a waiver that should travel with one file instead of the repo config, add an inline comment in the file: ``. The marker works in any comment syntax, scopes to the whole file (or one line with impeccable-disable-line / impeccable-disable-next-line), and is bypassed by --no-inline-ignores or --no-config.

Full detector docs: impeccable.style/docs/detector.

Supported Tools Copy Chapter

• Cursor
• Claude Code
• GitHub Copilot
• DeepSeek Harness
• Gemini CLI
• Codex CLI
• Grok Build
• Hermes Agent
• OpenCode
• Pi
• Kiro
• Trae
• Rovo Dev
• Qoder
• Mistral Vibe
• Veto
• Google Antigravity

Community & Ecosystem Copy Chapter

Join the community and ecosystem conversations:

• GitHub Discussions: file bugs, request features, and help newcomers.
• Impeccable on npm: grab the CLI, follow releases, and star the package.
• Follow @pbakaus on Twitter for release notes, sample lint reports, and video highlights of new rules.

Contributing Copy Chapter

See DEVELOP.md for contributor guidelines and build instructions.

License Copy Chapter

Apache 2.0. See LICENSE.

Created by Paul Bakaus

Overview (`browser-bundle/README.md`) Copy Section

browser-bundle: the page-side JavaScript of the detector

Plain JavaScript that runs inside a page or the extension: the DOM probe the
wasm rule core calls back into, the page snapshot producer, the
visual-contrast sampling IO, the overlay UI, the scan API and the extension's
offscreen document. Measurement and presentation only; every rule decision
is a call into the wasm rule core built from crates/core (docs/ENGINE.md).

Two consumers:

• crates/browser embeds 05-natives.js and 15-snapshot.js (the snapshot
  producer the URL engine injects; no WebAssembly runs in the page). It also
  runs 05-natives.js on every new document before the page's own scripts,
  which stashes the built-ins where a site's own global Map or a reassigned
  Array.from cannot reach them.
• crates/bundle (the impeccable-bundle library) embeds every file here
  with include_str! and concatenates them, in filename order, with the wasm
  core into the in-page bundle plus the extension's extension/detector/
  pieces. cargo xtask bundle is its caller inside this workspace: it writes
  dist/detect-antipatterns-browser.js, copies that bundle to the tracked
  crates/live/assets/detect-antipatterns-browser.js the engine embeds, and
  writes the extension pieces. A downstream crate with its own rule pack
  calls the library directly (docs/ENGINE.md).

Because the files are embedded, a new one here has to be added to
PAGE_JS in crates/bundle/src/lib.rs (and to the order it is concatenated
in); a test fails when the two lists disagree.

15-snapshot.js lists the computed-style properties the rules read; the
bundle build checks that list against the core's and fails when they drift.

Page JS runs in the page's world, so it names built-ins (Map, Set,
Array.from, JSON, Math, getComputedStyle, ...) only through the
bindings 05-natives.js declares. A new built-in a file starts using goes
into that file's list too.

Overview (`cursor-plugin/README.md`) Copy Section

Impeccable for Cursor

Design and refine interfaces with Impeccable: one skill, specialist agents, and a pre-edit design check. Invoke /impeccable polish, /impeccable audit, or describe the design work you want.

Installation Copy Chapter

This native Cursor plugin is being prepared for marketplace review; it is not yet a published listing. For the existing project install, run:

npx impeccable install --providers=cursor --scope=project

Use either that installation or the plugin, not both, to avoid duplicate skills and hooks. The plugin does not copy files into your project's .cursor directory. Its launcher downloads the pinned Impeccable engine on first use if it is not already cached; no Node runtime is needed for the plugin itself. Agent and shell permissions remain controlled by Cursor. Optional image generation requires its own provider credentials and approval.

Local plugin preview Copy Chapter

From the Impeccable repository, run bun run build, then copy dist/cursor-plugin into ~/.cursor/plugins/local/impeccable. Do not overwrite an existing installation. Cursor 3.15.6 rejects symlinks whose targets are outside its local-plugin directory, so use a real copy. Reload Cursor, then inspect Customize for the skill and four agents, and Hooks for preToolUse execution. A marketplace installation with the same name takes precedence over a local preview. Local plugins are user-wide, even when testing with a separate editor profile; remove the temporary copy when finished.

Use a synthetic project outside the plugin directory to test context resolution. The documented workspaceOpen/pluginPaths alternative did not execute reliably during the 3.15.6 smoke test; it is not the verified preview path.

The pre-edit hook uses Cursor's existing POSIX launcher integration. Windows shell behavior and remote environments require separate verification before advertising support for this plugin's hook.

Verification status Copy Chapter

Automated checks cover real Cursor-provider packaging, reference links, four agent files, executable permissions, version drift, and hook relocation into a path containing spaces. A direct staged-launcher invocation correctly loaded context from a separate synthetic project. Full non-billed regression tests and source-first/release builds passed.

On macOS with Cursor 3.15.6, the local plugin loaded with zero parser failures and exposed one skill plus four agents. A real /impeccable request ran the installed launcher once against the synthetic project and read the installed polish reference, without editing project files. Native preToolUse logs confirmed execution from the installed plugin with valid responses. Installing alongside a separate user skill produces duplicate slash-menu entries; choose one installation method.

A native impeccable-asset-producer handoff resolved the supplied skill scripts path and confirmed the launcher exists, without generating assets. A separate one-attribute fixture edit exercised preToolUse on Cursor's native Write tool: the installed hook exited 0 and returned valid JSON. The fixture was restored and the temporary local plugin removed afterward. Windows and remote runtime checks remain outstanding.

Maintainer submission checklist Copy Chapter

• Public repository: https://github.com/pbakaus/impeccable
• Marketplace manifest: .cursor-plugin/marketplace.json; plugin source: cursor-plugin/.
• Native manifest, skill, agents, hook, logo, and license are generated from source by bun run build:release and kept current by the generated-output workflow. Do not hand-edit cursor-plugin/.
• Verify /impeccable discovery, an installed-path context invocation, agent discovery and handoff paths, and a real pre-edit hook event in Cursor.
• After merge and verification, submit the repository at https://cursor.com/marketplace/publish. Submission and publication require maintainer approval. Replace this preparation notice and add the actual listing link only after acceptance.

References: Cursor plugins, plugin reference, hooks.

Overview (`vscode/README.md`) Copy Section

Impeccable for GitHub Copilot

Design guidance and tools for building, critiquing, auditing, and refining interfaces with GitHub Copilot in VS Code.

Use Copy Chapter

Requires VS Code 1.109.3 or later, GitHub Copilot Chat access, and a trusted local checkout. Open Copilot Chat in Agent mode and try:

• /impeccable polish to refine the current interface.
• /impeccable audit to inspect accessibility and implementation quality.
• /impeccable shape to plan a new interface.

Copilot can also discover the skill automatically for relevant design requests. Supporting references load only when needed.

If /impeccable is missing immediately after trusting a folder, run Developer: Reload Window, then try again.

What gets installed Copy Chapter

This extension bundles the skill, references, and engine launchers. It has no extension runtime, activation events, telemetry code, update command, or automatic detector hooks. Installing it does not copy files into your project or edit copilot-instructions.md. Marketplace updates replace the bundled skill.

When Copilot invokes an engine command, the launcher uses an available engine or downloads its pinned version from Impeccable's GitHub releases into your user cache. Downloads are checksum-verified. The engine runs on your machine with Copilot's normal command approval controls; no Node.js installation is required. The first download needs network access. On Windows without a POSIX shell, use the .cmd launcher (in PowerShell, invoke a quoted path with &).

Commands you request may edit your project or launch local previews. This is not an editor diagnostics extension, and it does not block saves. Native custom-agent sidecars and automatic hooks from other installation methods are not registered by this skill-only package; the skill includes its inline role fallbacks.

Avoid installing another Impeccable skill copy in the same workspace or user profile: duplicate skill names can make selection ambiguous. Browser-only VS Code without a terminal is unsupported. Remote SSH, WSL, and container setups need the extension and engine on the workspace host and are not yet smoke-tested.

Documentation · Source and issues

Overview (`cli/platform-packages/README.md`) Copy Section

Platform packages

Templates for the @impeccable/cli-<os>-<arch> packages the impeccable npm
shim (cli/bin/cli.js) declares as optionalDependencies. npm installs only
the one matching the host (os / cpu fields), and the shim resolves
/bin/impeccable[.exe] from it before falling back to the user cache
or a download.

They are published from the engine release, not built here: bun run release:platform-packages (scripts/publish-platform-packages.mjs) copies each template, sets version to the engine version, drops the
built binary at bin/impeccable[.exe] (executable), and publishes it under
@impeccable. The version pinned in this repo's package.json
optionalDependencies must equal ENGINE_VERSION.

Targets: darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64.

Overview (`tests/framework-fixtures/README.md`) Copy Section

Framework fixtures

Representative project shapes for exercising live mode against different framework conventions. Each fixture is a small directory tree that the test harness copies into a temp git repo, then drives the engine binary's live-inject, live-wrap, live-accept, and detect-csp verbs against (via tests/lib/engine-bin.mjs: IMPECCABLE_BIN or skill/scripts/bin/<os>-<arch>/, filled by bun run fetch:engine; the sweeps skip without a binary).

Fixtures can also opt into a runtime E2E pass that actually installs dependencies, boots the framework dev server, and drives a Playwright browser to verify the live handshake. See the runtime block below.

Layout Copy Chapter

<fixture>/
  files/              project tree the test copies into tmp
  gitignore.txt       becomes .gitignore in tmp (so we can commit the real files here)
  fixture.json        config + expected results the test consumes

fixture.json schema:

/* Detailed source-code truncated for AI context efficiency. */

The legacy middleware shape name covers CSP set in either Next.js
middleware.* files or the Next.js 16 proxy.* convention.

The expectedAfter file lives alongside fixture.json (not inside files/) and is a human/agent-review reference — tests don't auto-apply the patch.

The runtime block is optional. Fixtures without it only run the static checks in tests/framework-fixtures.test.mjs (inject, wrap, csp-detect). Fixtures with it additionally run the E2E suite in tests/live-e2e.test.mjs (bun run test:live-e2e), which:

1. Stages the fixture into a tmp repo.
2. Runs runtime.install to install real deps.
3. Starts impeccable live-server --background and runs impeccable live-inject --port against it.
4. Spawns runtime.devCommand and scrapes the port from stdout using runtime.readyPattern (the first capture group must be the port).
5. Opens Playwright Chromium at the dev URL and asserts window.__IMPECCABLE_LIVE_INIT__ === true (the browser-side handshake oracle) within runtime.readyTimeoutMs.
6. Runs a Steer smoke step (unless runtime.steer === false): submit a message in the global Steer bar, wait for the fake agent to reply steer_done, assert the bar unlocks and a data-impeccable-steer marker lands in source + DOM. Then continues with pick → Go → cycle → accept.
7. Tears everything down (Playwright close, dev server SIGTERM, live-server stop, tmp rm).

`runtime.appDir` Copy Section

Optional, defaults to .. Set it when the served app is not the repo root, the shape live mode has to resolve on its own (a CLI package at the root with the site in website/, for example). With appDir set, the harness:

• stages files/ and runs git init at the tmp root, as always;
• writes .impeccable/live/config.json under <tmp>/<appDir>/, and treats every fixture-relative path in fixture.json (steer.sourceFile, manual-edit expectedSourceFile, and so on) as relative to that app dir;
• runs runtime.install and runtime.devCommand with the app dir as cwd;
• boots through impeccable live from the tmp root instead of calling live-server and live-inject directly, so the run exercises the engine's root resolution rather than assuming it. The parsed boot payload is exposed as session.liveBoot, and tests/live-e2e.test.mjs asserts on roots.appRoot, roots.contextRoot, the persisted roots.json, and the repo-root pointer.

The session object carries both paths: session.tmp is the repo root (use it for git and for artifact capture) and session.appRoot is the app. They are the same directory for every fixture without appDir.

Picking, cycling, and the render proof Copy Section

pickSelector names the element the run picks. The picker resolves whatever is
under the cursor, so a container whose centre is covered by a child can never
be picked: add pickPosition ({x, y} in px from the element's top-left) to
aim at a point the container owns, such as its own padding.

variantSequence (default [2]) is the order the run cycles through; the last
entry is the variant it accepts. Every variant the run lands on gets a computed
font-weight assertion in fake-agent mode, because the fake agent renders each
variant at a distinct weight (FAKE_VARIANT_FONT_WEIGHTS in
tests/live-e2e/agent.mjs: 300 / 900 / 600). That turns "variant N is visible"
from a bar-label claim into a render fact, so a sequence like [3, 1, 2] proves
all three variants really render.

acceptedSourcePattern overrides the default post-accept source check (an <h1 class="hero-title">), and assertSourceContains lists strings that must
survive the whole wrap → accept → carbonize cycle. On Svelte component previews
that is how a fixture proves control flow was not flattened: list the {#each}
header and the per-item expressions.

stateProbe asserts page state is not lost. textSelector / expectedText
check rendered state; windowProperty with expectedWindowValue and
expectWindowUnchanged check a counter the app bumps on mount, so a scaffold
that silently remounted the page fails. It runs after preActions, after the
variants land, and (outside component previews) after accept.

Extra scenarios Copy Section

Beyond the core cycle, a fixture opts into scenarios by declaring their config.
Each one is also gated by IMPECCABLE_E2E_SCENARIOS:

componentFailureScenarios.variant picks which variant to break or observe.
Set storageLoss: false for fixtures whose picked element only exists after
preActions: the reload discards that state, and re-creating it races the
preview mount.

These scenarios assert on deterministic content, so they skip under
IMPECCABLE_E2E_AGENT=llm.

One gotcha: tests/framework-fixtures.test.mjs stages the same fixture flat and writes the live config at the tmp root, so config.files has to resolve from both the repo root and the app root. A glob ("**/index.html") satisfies both; a literal "index.html" only works from the app root and makes the static sweep report file_not_found.

Useful runtime E2E filters:

• IMPECCABLE_E2E_ONLY=<fixture>[,<fixture>] scopes the run to selected fixture names.
• IMPECCABLE_E2E_SCENARIOS=core runs only the main click → Go → cycle → accept path; omit it or use all to include manual edit, annotation, exit, params, and the component failure-injection probes. Names: core, manual, annotations, exit, missed-done, params, mount-failure, republish, storage-loss.
• IMPECCABLE_E2E_TEST_TIMEOUT_MS, IMPECCABLE_E2E_INSTALL_TIMEOUT_MS, and IMPECCABLE_E2E_DEV_READY_TIMEOUT_MS tighten CI smoke timeouts without changing fixture metadata.

Optional runtime.steer fields:

"steer": {
  "message": "steer-e2e mark hero",
  "sourceFile": "src/routes/About.jsx",
  "expectSelector": "h1.hero-title[data-impeccable-steer=\"e2e\"]",
  "expectSourceContains": "data-impeccable-steer=\"e2e\"",
  "preActions": [{ "type": "click", "selector": "[data-testid='nav-about']" }]
}

When preActions is omitted, steer smoke inherits runtime.preActions to reveal hidden heroes before the DOM check. Source is asserted first; a reload + retry covers HMR lag. Set "steer": false to skip, or "expectDom": false for source-only verification.

Current fixtures Copy Chapter

Add new fixtures by cloning a directory, swapping files, and updating fixture.json. A fixture with a runtime block also needs its name added to the live-e2e matrices in .github/workflows/ci.yml: the live-e2e-full group list, and one live-e2e-smoke group when it should run on every PR. Keep the groups roughly the same size, since they run in parallel and the job times out at 15 minutes.

Overview (`tests/new-work-e2e/README.md`) Copy Section

new-work E2E

A cheap, deterministic smoke suite for the interactive parts of new-work: the
serve-question decision page and the offline image generator. It is kept out of
bun run test and runs on demand.

bun run test:new-work-e2e

One-time setup: npx playwright install chromium (the suite drives a real
Chromium so the page runs its own JS, exactly as a user's tab would).

What it covers Copy Chapter

tests/new-work-e2e.test.mjs opens the served decision page with a real
browser and drives it through the scripted user bot, then asserts on the
serve-question protocol output:

• pick assigned returns the chosen optionId, the typed steer, the
  hero/board fields, and the CHOSEN CARD directive printed by --wait.
• re-roll with steer keeps the daemon alive, --update re-deals the next
  hand, the page reloads itself, and the following pick is terminal (state file
  cleaned up).
• canon returns optionId: canon and prints the CANON CHOSEN directive.
• tab close stops the page heartbeats so --wait exits 4 PAGE CLOSED.
• text-only card renders with no .media region when an option has no hero.
• fake image generation: same prompt yields identical bytes, the file
  exists, the SYNTHETIC marker is present, and different prompts produce
  different palettes.

The concept-seed direction roll (challengers, ASSIGNED INDEX, the no
PRODUCT.md gate) is pinned by the oracle corpus (tests/oracle, the seed-*
cases) and is not repeated here.

Both verbs run through the engine binary (impeccable serve-question,
impeccable generate-image) resolved by tests/lib/engine-bin.mjs:
IMPECCABLE_BIN or skill/scripts/bin/<os>-<arch>/ (bun run fetch:engine).

Pieces Copy Chapter

• user-bot.mjs is a module plus CLI. Given a workspace dir it resolves the
  running daemon from .impeccable/questions/<key>.state.json, opens the page,
  and runs a JSON policy of real clicks: {"pick":"assigned"},
  {"reroll":true,"steer":"warmer"}, {"pick":"challenger-*"},
  {"canon":true}, {"close":true}. The deterministic tier passes an
  already-launched browser in; the CLI launches its own Chromium.
• IMPECCABLE_IMAGE_GEN_FAKE=1 switches impeccable generate-image to
  the offline stand-in: no OpenAI call, no key, a $0.00 cost line, and a
  deterministic image (SVG for .svg out with the wrapped prompt text and a
  SYNTHETIC COMP label; a valid palette-stripe PNG otherwise, with the prompt
  and marker in a PNG tEXt chunk).

Planned LLM tier (not built yet) Copy Chapter

The same scaffolding supports an opt-in LLM tier later, mirroring the two-layer
pattern in tests/live-e2e:

• A real model plays the user through the same scripted user-bot.mjs policy,
  choosing and steering instead of following canned actions.
• IMPECCABLE_IMAGE_GEN_FAKE still stands in for image spend, so a full
  concept-to-card cycle runs without paying per render.
• Assertions run against the tool-call trace via the skill-behavior harness,
  the same way tests/skill-behavior keys on the trace rather than free-form
  output.

Cost posture: the deterministic tier is free (no API calls, local Chromium).
The LLM tier hits a provider and costs money, so it stays opt-in and out of CI,
matching how test:live-e2e and test:skill-behavior are gated today.

Overview (`tests/oracle/README.md`) Copy Section

Oracle: behavior goldens for every `impeccable` verb

lib.mjs runs each case (verb + args + staged workspace + stdin) against an
implementation and captures stdout, stderr, exit code, and named files, with
machine-specific paths and timestamps normalized.

• The goldens are frozen JS behavior: they were recorded from the Node
  scripts (skill/scripts, cli/bin) before those left the tree with the
  launcher swap, plus the reviewed deltas in DELTAS.md. They are the
  behavior contract the engine binary is held to.
• record.mjs --bin (with $IMPECCABLE_BIN or --bin=/path) writes goldens
  from the binary, for new cases or a delta a review accepted. Plain
  record.mjs still targets the JS scripts and only works on a checkout that
  has them (history before the swap).
• run.mjs replays the corpus against $IMPECCABLE_BIN (or --js for a
  self-check on a pre-swap checkout) and diffs. Byte-equal is the bar;
  DELTAS.md lists reviewed exceptions.
• tests/oracle.test.mjs runs run.mjs under bun run test and skips when
  no binary is found (IMPECCABLE_BIN or skill/scripts/bin/<os>-<arch>/,
  filled by bun run fetch:engine).
• cases/*.mjs define the corpus (default export: array or async function
  returning an array). workspaces/ holds project fixtures that are copied to
  a temp dir per run, so cases can write freely.

Adding a case: append to the matching cases/*.mjs, run
node tests/oracle/record.mjs --bin , review the golden by hand
(the binary is now the recorder, so a bug in it would be frozen too), commit
the golden.

Verb names are the binary's subcommands. cli-help and cli-version map to
impeccable --help / --version. lib.mjs still carries the JS_VERBS
table that maps each verb to the script it was recorded from.

vectors/ holds the function-level vectors recorded from the JS engine's pure
functions; see vectors/README.md.

Corpus files Copy Chapter

• cases/detect.mjs: detect, cli-help, cli-version, ignores.
• cases/hooks.mjs: hook, hook-before-edit, hook-admin.
• cases/context.mjs: context, doctor, pin, surface-brief,
  critique-storage, palette, embed-prompt, context-signals
  (id prefix signals-), detect-csp (csp-), concept-seed (seed-),
  generate-image (genimg-), serve-question (question-). Only offline
  paths: the local catalog fixture or an unreachable roll API, fake image
  generation, and serve-question modes that never open a browser or listen.
  Workspaces are workspaces/ctx-*; the header comment in the case file
  describes each one. Machine-specific env (OPENAI_API_KEY, catalog and
  context overrides, CI) is pinned per case so the recording host does not
  leak into goldens.

Normalizations Copy Chapter

Beyond paths and ISO timestamps, normalize() masks these run- or
machine-dependent fragments. Each is targeted at one script's output:

• IMAGE_TOOLS: : context probes which cwebp sips magick ffmpeg; the set found describes the machine, not the script.
• "devServer": <DEV_SERVER_PROBE>: context-signals probes localhost ports
  4321/3000/5173/5174/8080/8000/4200; whatever is listening on the recording
  host is not part of the contract.
• <STAMP>: critique-storage stamps snapshots with the wall clock in dash
  form (2026-05-12T18-30-00Z), in the file name and the timestamp:
  frontmatter it writes. Cases that write a snapshot do not snapshot the file;
  they run latest / trend afterwards instead.
• "<finding-id>": <EPOCH>: the staleness notice cache
  (~/.impeccable/staleness-check.json) keys epoch stamps by finding id.
• <verb> / <HOOK_ADMIN_CMD>: self-referential command lines.

Not covered on purpose: palette with no --id / --from / env seed (random),
concept-seed against the live roll API, generate-image real mode,
serve-question --start / blocking mode (opens a browser and binds a port;
--start refusals that exit before spawning are covered),
and unhandled-exception paths whose stack traces carry Node line numbers.

Live-mode cases (`cases/live-*.mjs`, workspaces `live-*`) Copy Chapter

Helpers live in live-helpers.mjs (staged journals, buffers, wrapped source
files with the fake-agent variant block, a .git FILE pointing at a non-repo
gitdir so roots resolution sees a git boundary while git check-ignore exits
128 everywhere and the ignore block lands in the snapshotable
.gitfake/info/exclude). Svelte component preview cases symlink this repo's
node_modules/svelte into the staged app, exactly like the unit tests.

Harness additions made for live:

• steps[] entries may carry their own setup(ws) (run right before that
  step) and daemon: true with readyFile / readyTimeoutMs: the verb is
  spawned detached, the harness waits for the ready file, later steps run
  against it, and teardown SIGTERMs (then SIGKILLs) it. Its stdout/stderr land
  in the golden as daemon: [{stdout, stderr}].
• normalize: [[regexSource, flags, replacement], ...] on a case applies extra
  masks to that case only. Live uses it for the dynamic helper port
  (localhost:, "port": ), lease and phase stamps (<EPOCH>),
  and float durations (<N>).
• Global masks added: "pid": / (pid ) and UUID tokens ``.
• snapshotFiles walks node_modules/.impeccable-live (the Svelte preview
  tree) and nothing else under node_modules.

Deliberately not covered here (rely on tests/live-e2e): the browser
handshake and /live.js bundle, SSE, generate/accept round-trips through a
real browser, variant_mount_failed republish, manual-edit chat routing and
the codex/claude subprocess providers, Svelte revision-dir publishing, and
live.mjs's dev-server-dependent flows. Lock-file names hash the absolute
source path, so lock cases do not snapshot .impeccable/live/locks/.
live-poll-*-connection-refused assumes nothing listens on 127.0.0.1:65531.

Overview (`tests/skill-behavior/README.md`) Copy Section

Skill-behavior tests

LLM-backed scenarios that verify how the impeccable skill drives context,
command-reference, new-work, and native-platform loading. Each scenario runs
against the default Anthropic, OpenAI, and Google models. DeepSeek remains
available through IMPECCABLE_SKILL_BEHAVIOR_MODELS.

These are the tests you re-run when you refactor anything in SKILL.md's
## Setup section. They fail when the agent stops following the loading
contract.

Run Copy Chapter

bun run test:skill-behavior
IMPECCABLE_SKILL_BEHAVIOR_VERBOSE=1 bun run test:skill-behavior   # dump per-scenario traces
IMPECCABLE_SKILL_BEHAVIOR_MODELS=claude-sonnet-5 bun run test:skill-behavior   # scope to one model
IMPECCABLE_SKILL_BEHAVIOR_EFFORT=xhigh bun run test:skill-behavior             # OpenAI reasoning effort (default: high)

Requires .env at repo root with at least one of ANTHROPIC_API_KEY,
OPENAI_API_KEY, GOOGLE_CLOUD_API_KEY, DEEPSEEK_API_KEY. Providers without a key are
skipped, not failed.

Also requires the engine binary (bun run fetch:engine, or IMPECCABLE_BIN).
The staged skill dir ships the launcher (scripts/impeccable); the harness
exports IMPECCABLE_BIN into every bash call the agent makes, so the launcher
resolves the binary in the generated fixture without a download. Without a
binary the suites skip.

To run a single scenario against one model:

IMPECCABLE_SKILL_BEHAVIOR_MODELS=claude-sonnet-5 IMPECCABLE_SKILL_BEHAVIOR_VERBOSE=1 \
  node --test --test-timeout=600000 --test-name-pattern="scenario 6" tests/skill-behavior/scenarios.test.mjs

How it works Copy Chapter

Protocol versus full completion Copy Section

test:skill-behavior now runs only scenarios.test.mjs. Routing cases stop
at the successful reference/context checkpoint they assert, with a ten-step
ceiling; shell access is context-only. They do not claim that a page was
built or reviewed. Editing/fallback controls retain their original assertions.
The focused S1/S2/S3/S4/S19 rerun passed 21/21 across the three default models.
A broader run exposed the context-only allowlist rejecting Svelte's valid
+page.svelte target. It was stopped, the allowlist fixed with a failing-then-
passing unit test, and S8 passed 3/3 on the focused rerun. Failed file reads
do not count as project exploration.
Update-notice (S9) and explicit-command (S18) checks also now stop at their
actual protocol checkpoints, instead of continuing into unrelated polishing;
their focused final reruns each passed 3/3. S9 now explicitly requires the
assistant to surface the update, not merely receive its loader directive.

Full workflows moved to tests/skill-workflow/full-build.test.mjs:

bun run fetch:engine
bunx playwright install chromium
bun run test:skill-workflow

This separately billed suite defaults to Claude only; use
IMPECCABLE_SKILL_BEHAVIOR_MODELS to explicitly choose another model or sweep.
It preflights a local server and Chromium before each provider turn, exposing
real desktop/mobile screenshot and PNG viewing tools. Text-only fixtures use
system fonts and block external browser requests. No extra skill prose is added.
The API harness is not the actual Claude Code host, nor is its shell sandboxed.

Each workflow has a 50-step/840-second ceiling. Reaching a budget or output
limit fails explicitly; routing checkpoints cannot satisfy completion. UI
workflows require desktop and mobile captures matching the final local sources after
its last edit. Approval/brief-before-code and redesign documentation-at-finish
checks remain, as does exactly one context load across the completed turn.
CI runs this lane only when its manual skill_workflow checkbox is enabled.
Ordinary protocol CI now fetches its engine instead of silently skipping for
a missing binary. Full-build results must be reported separately from routing.

Remaining gaps after the split (2026-09-07) Copy Section

One provisioned Claude natural-build run reached a final response in 637 seconds
and 37 model steps, with approval, a surface brief, an implemented page, a
finish review, corrections, and fresh desktop/mobile screenshots. Its initial
completion assertions passed. The final test revision additionally requires
the shipped documentation reference; auditing the saved trace against that
guard found it missing. This is not a final full-workflow pass. Existing
DESIGN.md was preserved, but the required documentation pass was skipped.
The final guards were tightened during the run; this trace is not represented
as a run of those later assertions. No second full build was purchased.

Claude's remaining protocol batch passed S10–S15 and existing-project S16,
but missing-context S16 omitted routing.md and S17 omitted critique.md.
Both responses remained read-only. The older S9 timed out during unrelated
polishing; the corrected focused S9 above supersedes it. The batch was stopped
during the older S18, before another provider sweep. This is incremental
evidence, not an all-green final matrix. Release #782 remains on hold.

The full build reported about 2.95 million input and 53 thousand output tokens
across all turns (no cache usage reported). Keep this lane manually scoped;
the fast protocol suite is not a proxy for its completion or cost.

Documentation handoff follow-up Copy Section

tests/skill-workflow/finish-handoff.test.mjs isolates a synthetic post-review
checkpoint without rebuilding or capturing a page. Its existing-system fixture
has no approved system change and a pre-existing missing sidecar; the correct
result is to check the build against DESIGN.md, preserve it, and leave unrelated
drift alone. The new-world control must write DESIGN.md and its v2 sidecar.

The unchanged-instructions baseline reproduced the skipped documenter in 31s.
The revised handoff and documenter passages are 29 words shorter overall and
make a checked no-change result explicit. The first focused extension retest
passed in 27s. A repeat checked the source, DESIGN.md, and document.md and made
no mutations, but omitted degraded/documenter.md, so the strict reference guard
still failed. The new-world control passed in 91s, writing both required files.
These small samples support the narrower behavior change, not an all-green
workflow claim; the reference-loading miss remains visible. No full build was
rerun. Focused Claude routing S3/S4, the ordinary suite, source-first build, and
generated-skill authoring validation passed. Release #782 remains held.

Outcome assertions (maintainer-approved follow-up) Copy Section

S16/S17 now require a completed, useful, read-only answer; S17 distinguishes
assessment from implementation and explains that critique is optional before
polish. Explicit invented prerequisites remain failures. Missing routing or
comparison references are TAP diagnostics based on successful content loads,
not failed read attempts. These English-fixture phrase checks are bounded
regression checks, not a comprehensive semantic grader.

The resumed ordinary-extension checkpoint accepts a direct documentation pass
without the degraded wrapper only with actual document.md, page, and DESIGN.md
reads, a concrete no-change report grounded in the fixture's type/palette/layout,
and zero mutations. Seeded files must still be byte-identical and pre-existing
sidecar drift must remain untouched. New-world documentation writes, redesign
ordering, and full-build completion gates are unchanged.

Offline re-evaluation of saved Claude traces: three advice responses and two
evidenced no-op handoffs pass the new assertions. The original post-review
baseline and the 637-second full build still fail for absent documentation
evidence. Unit negative controls reject fabricated prerequisites, unsolicited
edits/interviews/scans, failed reads, empty or unsupported reports, and exhausted
budgets. This is assertion replay, not new model evidence or a rerun of cleaned-up
workspaces' filesystem checks. No paid calls or skill prose changes were needed.
The earlier reference misses above are now diagnostics, not release blockers by
themselves; this does not establish an all-green full-workflow matrix.

Bounded release verification (2026-09-08) Copy Section

The focused Anthropic live-accept test now verifies the durable session reaches
completed, not just clean source/DOM. Its agent instruction had recommended
data-impeccable-e2e-variant, inside the reserved runtime namespace; the test
prompt now uses a permanent data-design-variant styling hook. The strengthened
test passed in 14s without forced completion. The full non-billed suite passed.
No runtime or skill source was changed for this correction.

Claude post-review controls: new world passed in 77s, writing token-bearing
DESIGN.md and the v2 sidecar; approved redesign failed in 16s. The latter read the
page and old system, then wrote prose-only DESIGN.md without consulting the
documentation spec or creating .impeccable/design.json, and claimed nothing
remained outstanding. This is a missing required artifact, not merely missing
reference coverage. The test stays red; no retry was purchased. Release remains
held pending disposition. These are synthetic post-review checkpoints, not
proof of a complete redesign lifecycle.

The single full Claude build passed its automated gates in 623s / 31 steps:
approval, brief, implemented page, final desktop/mobile captures, and shipped
reviewer/documenter wrapper loads. The final response gave an in-thread review
and a no-change documentation assessment of the incumbent system. It did not
load document.md itself; this is not evidence that every documentation protocol
step ran. The run used about 2.11M input / 50K output tokens (no cache reported).
No further billed retry was started. The separate missing-artifact redesign
failure still blocks treating this batch as an all-green skill release gate.

Targeted redesign handoff correction Copy Section

The parent handoff now explicitly requires token-bearing DESIGN.md and
.impeccable/design.json for approved system changes and verifies those outputs
before completion. It is nine words shorter; the agent and schema files did not
change. One unchanged-assertion Claude retest finished in 65s: it read document.md
and wrote both artifacts, but still skipped the degraded wrapper, so that
reference assertion failed before the artifact assertions ran.

Wrapper coverage is now diagnostic for all post-review modes; successful spec
and source reads, completed turns, write boundaries, tokens, and the v2 sidecar
remain hard gates. Offline evaluation of the saved retest passes these artifact
checks; the original prose-only/missing-sidecar trace remains rejected. Negative
controls cover absent tokens, malformed/missing sidecars, old schema versions,
and absent metadata. This is replay, not a second live pass or a rerun of the
cleaned-up workspace's byte-preservation checks.

Artifact audit: the sidecar component renders correctly in an offline browser.
The heading line-height was recorded as 1.3 while the page inherits 1.6 (38.4px
at 24px), and generatedAt used a placeholder date. These are remaining output
accuracy limitations, distinct from the corrected missing-artifact failure;
the shape checks do not establish complete token fidelity. No broad provider or
full-build rerun was purchased. Build and generated-skill validation passed.

Each scenario:

1. prepareWorkspace() uses the production transformer to build current source
   into an independent <workspace>/.claude/skills/impeccable. References have
   resolved placeholders and generated degraded reviewer/documenter files.
   Host-specific blocks are omitted: this is a neutral API harness, not an exact
   Claude/Codex/Gemini host simulation. It optionally seeds project fixtures.
2. runTurn() inlines SKILL.md (placeholders neutralized) as the
   system prompt and runs Vercel AI SDK generateText with five
   tools: bash, read, write, list, and a fake
   provider-neutral ask_user_question backed by a deterministic simulated user.
3. The tools record every call into a trace that the test asserts on.
4. For scenario 4, a second runTurn reuses turn 1's responseMessages
   so the model sees a real multi-turn conversation.

The trace is the source of truth, not the model's free-form reply.

File tools are workspace-scoped; bash is a real host shell, not a security
sandbox. Use disposable synthetic fixtures. Shell helpers do not inherit
provider API keys/auth tokens; model calls still use the parent's keys. The
harness always sets IMPECCABLE_QUESTION_DISABLED=1 for shell calls so real
decision pages cannot wait for a nonexistent browser user. The engine returns
its genuine structured-question fallback; browser decisions have separate E2E.

Set IMPECCABLE_SKILL_BEHAVIOR_TRACE_DIR=<directory> to retain per-turn JSON
with model, prompt, tool results, response ordering, usage, and finish reason.
Progress and failed turns retain their tool traces too; only completed turns
carry the full response sequence and final usage.
These are local diagnostic artifacts; inspect before sharing. Successful reads
or full reference content in shell output count as loading; filename mentions,
denied commands, and failed reads do not.

Context-only controls permit the real launcher with an optional workspace-relative
--target; compound commands remain rejected. The target form is part of the
skill's Setup contract, not a launcher failure.

Release investigation (2026-09-07) Copy Chapter

The initial release sweep reported 68/81 passes. Do not interpret its 13 failed
assertions as 13 demonstrated product regressions. The harness staged raw
references with unresolved placeholders, omitted generated degraded roles, and
allowed unanswered browser decisions. Its redesign assertion was also stale:
current new-work.md requires a surface brief before code, and DESIGN.md
at finish, from the built world. The corrected lifecycle checks retain
approval, brief, implementation, and final documentation requirements; missing
artifacts now have their own error instead of being called premature edits.
The historical tables below retain their original measurements and methods.

Focused launcher-fallback verification on the corrected fixture:

The three cases are denied editing, successful-loader control, and denied
planning. The old-paragraph failures were warning order, not refused edits.
An intermediate candidate run scored 8/9 because the control rejected valid
context --target index.html; after correcting that allowlist, the full focused
rerun passed 9/9. This is one measured run per variant, not a reliability estimate
or an all-workflow pass. Broader routing and workflow results remain separate.

On the resolved fixture, Gemini's workflow run passed 4/5: the completed new
page omitted user confirmation. Tightening the existing question paragraph
made its focused build lifecycle rerun pass 1/1. OpenAI passed all five workflow
cases with the fixture corrections alone. These are incremental measurements,
not one full sweep on the final candidate.

Claude's three-step routing sweep cut off two setup cases before loading
new-work.md. Both loaded it in bounded six-step diagnostics. Claude now has
the same six-step setup allowance as Gemini; reference and edit-order assertions
are unchanged. A full-build baseline separately hit the existing 840-second
deadline and is not counted as a pass.

The complete routing-only sweep retained its original budgets and passed 55/57
(Claude 17/19, OpenAI 19/19, Gemini 19/19). A six-step Claude rerun passed the two
previously clipped cases but exposed a separate context reload on turn two:
the model queried the loader again for image-tool availability. That run was
stopped after five passes and this failure rather than finishing another billed
sweep; the once-per-session assertion remains unchanged.

A saved Claude build trace used five calls shortening/counting the direction
contract, then reached the 22-step cap before implementation. The word target
is now approximate, with the six required blocks retained. A subsequent run
correctly stopped for missing customer evidence: the default simulated user had
selected “I have real details,” then promised them in a future message. The
case-study test now supplies a complete, explicitly synthetic brief when asked;
fresh-init and other user simulations are unchanged. Neither incomplete build
is counted as a pass.

The corrected-user Claude retest also remained incomplete: it asked, recorded
the six-block brief without the earlier word-count loop, then spent the remaining
22-step allowance acquiring and inspecting fonts before writing HTML. The
26-step redesign run produced the page and desktop/mobile captures but stopped
before DESIGN.md. These results do not establish full workflow completion.
Further work should separate narrow protocol checks from realistic, provisioned
full-build runs rather than keep adding skill prose or relaxing finish gates.
The later Claude run passed fresh init and refinement, failed the two bounded
build cases, and was stopped during critique's browser-tool discovery. Its
unfinished critique case is not a pass; the earlier OpenAI/Gemini critique
results remain the completed measurements.

Scenarios Copy Chapter

Setup launcher-failure branch (2026-09-06, PR #750) Copy Chapter

Scenario 19 injects a host permission error before any shell command executes,
including retries and compound commands. File tools remain available; the
staged skill is read-only. Assertions require successful reads, an actual UI
edit, unchanged context files, and disclosure before the first write in the
assistant message sequence. Failed read attempts and shell commands merely
mentioning a reference do not count as loading it. The success control allows
only the real context-loader command through Bash and requires exit 0.

The suite measures continuation after a tool refusal, not Claude's skill
activation or plugin substitution. Those are separate loader/path checks.
It also does not establish behavior for every missing-binary or runtime error.

Focused baseline (2026-09-06): both scenario 19 cases passed on
claude-sonnet-5, one run each. The original wording also continued after
denial in the comparison run, but disclosed the failure only in its final
summary. This does not reproduce the reporter's complete reference-loading
failure or establish a multi-provider pass. An earlier scenario 6 result used
attempt-based reference assertions and is not counted as a success control.

Refusal follow-up (2026-09-06, #744) Copy Section

The provider-neutral harness models a loaded skill with a known base directory
using synthetic workspace-relative host metadata, not each provider's exact
generated prompt. The source instructions and <skill-base-dir> resolution
remain under test; reference reads still have to succeed. Provider transforms
and plugin loading have separate path/loader tests. The harness also sets an
explicit 16,384-token response ceiling for DeepSeek: the Anthropic-compatible
SDK otherwise treats that model as unknown and caps it at 4,096. Truncation
still fails the scenario; this changes the test runner, not the shipped skill.

The unchanged-source baseline with directory metadata passed 5/8 focused
cases: Sonnet skipped craft-floor in its successful-launcher control, OpenAI
stopped without editing after denial, and Gemini warned only after editing.
DeepSeek passed both cases. An initial candidate got OpenAI to edit but still
warned late on Sonnet, OpenAI, and Gemini; DeepSeek's denial response truncated.
All four successful-launcher controls passed that candidate.

The pre-review candidate separates the fallback from the long first step, says to
send the warning first and continue through permitted tools, and clarifies
that craft-floor also applies to small refinements. Setup grows by 18
whitespace-separated words; the description is unchanged. Sonnet and OpenAI
passed both final cases, as did DeepSeek with the explicit output ceiling.
Gemini still warned after the edit; its control passed. The final result is
7/8; the warning-order assertion remains unchanged.

Review follow-up: the fallback now says to follow the applicable steps
2–3, preserving step 3's planning-only exclusion (20 added Setup words overall).
A new denied-launcher planning case requires a real plan, no mutations or
craft-floor read, and successful context/target/playbook reads. On Sonnet,
the editing denial and successful-loader cases both passed again. The planning
run stayed read-only and skipped craft-floor, but failed because it did not
read polish.md. That assertion remains intact: this is another reference-loading
gap under #744, not a green planning result. Other providers were not rerun for
this wording-only review clarification.

The planning case also checks the response-message sequence: the launcher must
actually be denied, then an assistant warning must precede the first fallback
PRODUCT.md or DESIGN.md read. Deterministic tests reject silent continuation,
final-only warnings, warnings before denial, and user-authored warnings. This
checks disclosure even when no editing occurs; the editing cases retain their
existing pre-edit warning assertion.

One focused Sonnet rerun with this guard read the playbook and produced a
read-only plan without craft-floor, but omitted the launcher warning entirely.
The strengthened assertion correctly failed that run; #744 remains open for
the behavior failure rather than treating this coverage fix as a skill fix.

These are single samples per case and candidate, not reliability estimates.
This API harness starts with the skill loaded and readable references. It
does not measure activation, reproduce Windows command parsing, or establish
fallback behavior when the host also denies required file reads or writes.
Keep #744 open; evaluate activation separately with #375.

To repeat only these cases (provider keys and an engine binary required):

IMPECCABLE_SKILL_BEHAVIOR_MODELS=claude-sonnet-5,gpt-5.6-terra,gemini-3.7-flash,deepseek-v4-flash \
  node --test --test-name-pattern='scenario 19:' tests/skill-behavior/scenarios.test.mjs

Degraded documentation case (#789) Copy Section

A fourth scenario 19 case covers the documentation branch: launcher denied,
PRODUCT.md plus an incumbent index.html, prompt /impeccable document.
It requires an actual denied context attempt, successful document.md and
source reads before the DESIGN.md write, the denial disclosed before the
first tool call after the denied launcher, and an untouched PRODUCT.md.

Scenario 19 on this branch, all four cases, one run each on 2026-09-09:
4/4 on claude-sonnet-5, 4/4 on gpt-5.6-terra, 4/4 on gemini-3.7-flash. The
documentation case also passes with main's unchanged SKILL.src.md and
init.md plus this test file, so the coverage is the test, not a skill-text
change.

Workflow-advice assertion fix (2026-09-24) Copy Chapter

On 2026-09-24 S16 and S17 failed on every provider, main included, for a test reason: the sentence-bounded matches used [^.!?\n], so the dot in index.html ended the "sentence" and correct advice ("polish index.html to implement the fixes") could not match. A dot followed by a word character no longer ends a sentence. S16 also accepts the surface named as the landing page, this page, or the existing implementation; S17 counts a critique described as a diagnosis. Generic advice and invented critique prerequisites still fail. A live rerun on claude-sonnet-5 and gemini-3.7-flash went from 0/6 to 8/9 with the fix; the remaining case used "existing visual implementation", now accepted.

Workflow-advice baseline (2026-09-05, PR #737) Copy Chapter

The four cases in scenarios 16-18 are new; prior scenario results do not
establish their behavior. The advice-only assertions inspect write-tool calls
and file mutations from bash (excluding context's internal .impeccable/
state, but not critique reports), require an actual answer, and reject
interviews and menu scans. Scenario 18 checks command-reference precedence;
it does not assert completion of a full polish pass. These cases allow only
the exact context-loader command through bash; references use read/list, and
the write tool remains available for project files so unsolicited edits still
fail the test. Writes to the staged skill are rejected. This keeps the routing
measurement from running arbitrary shell searches outside its fixture.

Rechecked after reducing the skill addition to 59 words. Claude's first
missing-context response stayed read-only but skipped routing.md; an unchanged
repeat passed on all three providers. Keep that reference-read miss visible as
a flake rather than adding instructions for a single observation. All assertions
remain unchanged. Scenario 18 uses an eight-step budget and actual read-tool
evidence, not rejected bash reads. The initial unrestricted run (stopped after
host-wide search attempts), earlier rejected-read results, and broader suite's
sandboxed provider DNS errors are excluded from this baseline.

The full-build file adds end-to-end assertions for attended fresh init,
an initialized natural build request, replacement-world redesign, scope-preserving bolder
refinement, and critique's closing question. It checks question order and
context/artifact writes rather than only reference-file loading.

critique closes with the question or an explicit skip line is a regression
guard, not a routing check. A critique that prints its report and then stops,
asking nothing and printing no Questions skipped: <reason> line, is an
incomplete run: the close is half the deliverable, and polish downstream has
no priorities to inherit without it. The fixture page is deliberately broken
enough to put the report past the three-Priority-Issue threshold, so the run
cannot reach the skip branch on merit. The assertion is deliberately loose about
how the run closes, because either close is valid; what it forbids is neither.

Workflow-contract baseline (2026-08-13, current lineup) Copy Chapter

Measured while checking whether an {{ask_instruction}} rewrite had regressed
anything.

The last two columns are no longer in the default lineup. gpt-5.6-luna and
deepseek-v4-flash were dropped in 2026-08 for being below the frontier tier:
they fail scenarios by stopping mid-run or archiving a report without stating
it, which is model-floor behavior rather than a skill-text defect. Their columns
stay here because they are the record of what a weaker model does with this text,
and that is the useful part. Reproduce with
IMPECCABLE_SKILL_BEHAVIOR_MODELS=gpt-5.6-luna,deepseek-v4-flash.

Against the current default lineup, two cells are the known floor:
redesign replaces DESIGN is flaky on every model, and critique closes is
flaky on gemini-3.6-flash. A regression is a failure beyond those two.

The Google slot in DEFAULT_MODELS moved to gemini-3.7-flash on 2026-08-15.
Every Gemini cell in the tables below was measured on 3.6-flash (or 3.5-flash
where marked), and per the cross-version rule further down, those results are
unmeasured on 3.7, not inherited. Re-run the sweep on the next Setup or routing
change and update the tables to the new column.

Read any failure against the clock before calling it behavior. The suite ran
at a 300s per-test timeout until 2026-08-13, and for the workflow-contract
scenarios that cap was below the runtime of a correct run. initialized natural build on claude-sonnet-5 was measured at 579s when it stopped to put the
concept to the user before building, while the runs that skipped that checkpoint
and failed the assertion finished in 130-200s. The cap was therefore selecting
for the behavior the scenario forbids: thorough runs were killed, hasty ones
were graded. The timeout is now 900s (scripts/test-suites.mjs). A duration at
or just past the cap is a timeout, not a verdict.

Gemini's bolder refinement and critique closes runs in this sweep died on
AI_APICallError / ETIMEDOUT before completing a turn. Network failures are
not behavior measurements and are excluded from the counts above.

Scenario baseline (2026-08-13, current lineup) Copy Chapter

Measured on the same sweep. scenarios.test.mjs passes 15 of 15 on
gpt-5.6-terra and gemini-3.6-flash. Only claude-sonnet-5 fails anything, and
that asymmetry is the finding: the two cells below fail on the frontier model
while two weaker-on-paper lineups route correctly, so read them as a text
problem that one model's priors expose rather than as a model floor.

Scenarios 8 and 11 pass on re-run, so treat a single failure there as flake and
confirm with a second run before investigating.

Scenarios 9 and 15 both failed on sonnet when this baseline was first measured,
and the two causes are worth keeping because neither was where it looked:

• 9 was a real defect in the directive. UPDATE_AVAILABLE said to ask the
  user, then "If they agree, run npx impeccable update", then to continue
  without waiting. With no wait there is no agreement to read, so the command
  was the only concrete instruction left standing and sonnet ran it. Fixed by
  removing the command from the turn entirely rather than by strengthening the
  warning around it.
• 15 was a broken fixture. The iOS workspace held PRODUCT.md and nothing
  else, so audit the app in this workspace named an app that did not exist.
  Sonnet spent its whole step budget looking for it and read no reference file
  at all, which the assertion reported as "loaded audit.md instead of the
  variant". The fixture now ships one SwiftUI screen, the same courtesy
  MINIMAL_LANDING_HTML already did for the web scenarios. The scenario passes
  on unmodified main once the fixture is answerable, which is the proof the
  routing text was never at fault.

The general lesson is worth more than either fix: an assertion reports the
property it checks, not the reason it failed. Both of these read as routing
defects and neither was one. Pull the trace before writing the diagnosis, and
prefer IMPECCABLE_SKILL_BEHAVIOR_VERBOSE=1 over inference from the message.

Gemini cells marked on 3.5 were measured on the superseded gemini-3.5-flash
and have not been re-run on 3.6. That distinction is not pedantic. critique closes passed twice on 3.5-flash, then failed three times in a row on 3.6-flash
against identical instruction text, and only passed once the report delivery step
was made explicit. A version bump inside one family changed the outcome, so treat
cross-version carryover as unmeasured rather than inherited.

not measured means exactly that: the cell was never run in isolation on this
lineup. Only the scenarios under investigation were scoped per model. The rows
are worth keeping anyway, since a scenario absent from the table is easy to
mistake for a scenario that passed.

bolder refinement, deepseek-v4-flash. The model runs impeccable context, reads
bolder.md, craft-floor.md, and current.html, then ends its turn without
editing anything: empty writePaths, no ask_user_question call, well short of
the 16-step cap. Confirmed identical on HEAD with bolder.md reverted, so it is
not a skill-text problem. Same shape as the gpt-5.4-mini scenario 6/7 failures
below: the model consumes the references and then declines to act.

critique closes: the three ways a critique fails to land. The scenario
asserts emission order, not just the presence of a question, because the command
fails in three distinct ways and only one of them was the reported bug:

1. No close. Report lands, no question, no skip line. polish downstream
   inherits nothing.
2. Question before report. The question is emitted first and the report after
   it, so the report is withheld until the user answers. Observed directly on
   gpt-5.6-luna, and the reason the invariant is a position rule ("the question
   is the LAST thing in the response") rather than a statement about prose order.
3. Report never spoken. The report is authored straight into the persistence
   heredoc, archived, and never written to chat. A perfect snapshot and a user
   who sees nothing.

Mode 3 is the one worth understanding, because it was structural rather than a
model quirk. critique.md described the report's format and then went directly
to writing a temp file, with no step that said to output the report. Both
gemini-3.6-flash and luna responded by bundling heredoc, snapshot write, trend
read, and cleanup into a single bash call and stopping. The Deliver the Report
section exists to close that gap, and it worked: gemini-3.6-flash failed three
consecutive runs before it, and its failures afterward all show the report
reaching chat.

Mode 1 is not fixed on gemini-3.6-flash. It passes 1 run in 3 on the final
text. Two structural attempts were made and neither settled it: the close was
promoted into Hard Invariants with a printable Questions skipped: <reason>
string, then made step 6 of the persistence list so it would sit inside the
numbered flow rather than after it (the shape that fixed mode 3). Both moved it
from consistently failing to intermittently passing, and further prose tuning
was not paying, so it stopped. claude-sonnet-5 and gpt-5.6-terra are clean.
Treat this cell as the known floor and re-measure rather than tuning blindly:
the next useful move is probably a structural one, such as making the close
something the run cannot syntactically finish without, not another paragraph.

Read the counts here as what they are: small samples on a nondeterministic
system, several of them gathered while the instruction text was still changing
between runs. They support "the close works on the current lineup" and not much
finer than that. Re-measure rather than assuming when the lineup changes.

redesign replaces DESIGN, flaky. It has failed on two different assertions
across runs (designWrite > question and implementation > designWrite), and on
one run claude-sonnet-5 exhausted the 300s per-test timeout instead of asserting.
The traces never load document.md; the ordering under test comes from
new-work.md. Re-run before believing a single red result here. Which model
produced which failure was not pinned down, so the row records only that the
scenario is unstable.

The bolder claude-sonnet-5 cell is unmeasured for a specific reason: the scoped
run that produced this table used a 180s cap, which sonnet exceeded. That is a
timeout, not a failure, and it is why the guidance below insists on 300000.

Scoping a run while investigating Copy Section

Both files honor --test-name-pattern, which is much cheaper than a full sweep
when bisecting one scenario:

IMPECCABLE_QUESTION_DISABLED=1 CI=1 IMPECCABLE_SKILL_BEHAVIOR_MODELS=deepseek-v4-flash \
  node --test --test-timeout=300000 --test-force-exit \
  --test-name-pattern="bolder refinement" tests/skill-workflow/full-build.test.mjs

Use the suite's current 900000ms timeout for full workflow cases; the 300000ms
example above is historical. The harness now disables decision pages itself.
Pipe
to a file rather than tail; node prints the failing-test summary at the end,
and truncating it costs you the per-model attribution.

Baseline state (2026-05-20, previous cheap tier) Copy Chapter

Historical record. The default models are now claude-sonnet-5 and
gemini-3.6-flash. The table below was measured on an older cheap tier
(claude-haiku-4-5 / gpt-5.4-mini) and is kept as the historical record.
Re-measure on the current lineup and update this section; the stronger
models are expected to clear the scenario 6/7 routing failures that the old
gpt tier showed.

Captured after moving sub-command reference loading from step 4 to step 2
of Setup (so the agent loads reference/<command>.md right after
impeccable context, before "doing the work" preempts it), and tightening
step 3 to require at least one project code read even when a sub-command
reference loads first. Use this table when comparing pre/post refactor:
a regression is "more failures than baseline", not "any failures at all".

21-22 / 24 typical. The stable failures are gpt-5.4-mini scenarios 6 and 7:
the model reads index.html (the target file), recognizes "polish" or
"audit" as a familiar action, and proceeds with the work without ever
loading the sub-command reference. Stronger SKILL.md wording (MUST,
"non-optional", reordered earlier) didn't move it; this looks like a
model-floor behavior rather than a skill ambiguity. Claude and Gemini
honor the load.

Overview (`ui/component-review/README.md`) Copy Section

Shared component review — UI checkpoint

This framework-independent browser surface is owned by Impeccable. The eval dashboard imports it directly for the current visual checkpoint; the native component-review command serves the same bundle. The comp-led skill workflow presents it after the initial component kit and again after assembling the page. Existing build-phase integrity gates remain independent.

ReviewPacket contains a request/revision identity, the pinned comp dimensions, and the component inventory. Raster and sandboxed page-region previews share the same comparison canvas. Draft records individual decisions, optional split requests, missing regions and explicit inventory completeness. onSubmit belongs to the trusted host adapter. A UI draft is not an authenticated human approval.

The eval preview uses actual historical hotel artifacts and manually mapped titles. Its HTML views clip the existing page at the recorded comp-region bounds. These are interface test data, not proof that an initial component-production round occurred. No historical approvals are inferred, rewritten or reused. No model calls occur.

Implemented runtime foundation: manifest/path validation, pinned dependency bytes, version-bound local-browser feedback stored outside the builder project, and scoped approval invalidation. Native static component capture is implemented below. The eval harness owns authenticated reviewer routing, provider pause/resume and its attention queue; these are not responsibilities of this public UI. The trusted adapter must reject malformed, duplicate or stale submissions and verify the reviewer identity. No permissions decision is based on a browser-provided actor name.

The dashboard route /dashboard/component-review/ is a temporary review checkpoint. Final embedding belongs in the waiting run's detail view. Keep the launch hold until the runtime and restart/resume checks pass.

Native runtime Copy Chapter

Use the Bun version in .bun-version (also used by CI). Build the shared UI with bun run build:component-review, then rebuild the engine. It embeds the JS and licensed fonts; the runtime needs no Node server or dashboard. The bundled asset is tracked alongside the native consumer, and the bundle test catches source drift.

From a project, run impeccable component-review prepare --manifest review.json. The manifest uses the UI packet shape plus schemaVersion: 1; replace each preview/comp/context/thumbnail url with a project-relative path, and declare each component's dependencies (CSS, images, fonts and other inputs used by its rendered preview). The service assigns revisions and round numbers. Paths outside the project are refused. Prepare prints a session ID. Start impeccable component-review serve --session and open the returned loopback URL. status --session reads the saved result. The default store is ~/.impeccable/component-reviews; a test may use --store <outside-project-directory>.

Feedback commits atomically and identically retried submissions are idempotent. A second, different response to the same round is refused. Preparing changed inputs creates a new round, preserves unaffected approvals, resets inventory completeness, and carries missing-region feedback forward for human resolution. Prior packets remain addressable by revision; their URLs never silently switch to a new round's pixels. Closing/restarting the server preserves the packet and submitted feedback. Unsubmitted typing is not yet autosaved.

Evidence boundary Copy Section

Plain prepare pins the producer's declared inputs and leaves captureVerified: false. Native capture renders static code using only frozen declared inputs, verifies observed browser response bytes and stable pixels, and records the resulting captures outside the project. Only this in-process adapter can produce captureVerified: true. Both paths retain reviewer: local-browser; no browser-provided actor name grants human-eval qualification. The out-of-project store prevents a builder workspace JSON edit from changing authoritative feedback. Host/Origin/fetch-metadata checks reject cross-site browser requests, but do not authenticate a person against another process with the same OS permissions. Eval integration must own that trust boundary and preserve the distinction in provenance.

Generated HTML/SVG is served with a restrictive CSP and sandbox: no scripts, network requests, form submissions, or access to approval controls. Fonts can load from pinned files in an opaque-origin frame. Script-dependent components require a trusted captured preview; they are not yet supported as live executable component frames. Absolute-root asset URLs are not rewritten; the packet must use self-contained relative dependencies.

The runtime currently serves standalone with frame-ancestors 'none'. Transcript embedding must add an explicit trusted parent/broker rather than weakening this globally. It never opens Chrome automatically, starts an eval, changes existing campaign data, or bypasses fidelity/provenance gates.

Repair rounds Copy Chapter

The host supplies ReviewHistory separately from the producer's packet. The
native store derives it from saved packets and decisions: prior preview URLs,
component changes, outstanding feedback with its originating round, carried
approvals, and removed inventory entries. History is not inferred from filenames
or accepted from a producer-authored manifest field.

The round summary leads to changed/new components. Current/Previous switches
show each round's own comp and preview at its recorded geometry. Previous-round
inspection disables both individual and batch approval. Change details explain
whether files, region geometry or component definition invalidated an approval.
The inspector remains a fixed height and retains scroll position on view toggles.

Content identity and review identity are distinct. An unchanged prepare is a
no-op; reverting to earlier content creates a fresh review round whose identity
includes its predecessor. An old submission cannot approve that new round, and
its archived receipt is not overwritten. Preparing several versions before a
reply preserves outstanding feedback; a later explicit approval resolves it.

The native hotel checkpoint is an isolated integration-test copy. Its second
round changes only the boat description, explicitly labelled as such, to test
feedback and approval carryover without altering artwork or historical evals.

Feedback hierarchy: prior requests appear in a read-only Previous feedback
section with their originating round. The Preview control affects only the
comparison images. The separate Your review section names the current round;
choosing Needs work opens an empty New feedback field. Prior text is never
silently copied into that field. Definition-only changes explicitly state that
files are unchanged and expose the old/current descriptions.

Attention-first navigation Copy Chapter

Map markers and inventory cards use one revision-aware status function. Gold
numbered circles need review; subdued checked markers are approved; a separate
pencil state indicates feedback ready to send. Shape/icon, text and color carry
the distinction together. Stable component numbers do not change with sorting
or filtering. Missing marks also appear on the comp map.

The inventory defaults to Needs attention, excluding approved components and
sorting changed/new components first. Approved and All remain available. A
filter change selects a matching component when necessary. Next to review skips
already decided items; choosing Needs work retains that component in the
attention list while the reviewer writes feedback. Stale approval revisions
never hide a component. Bulk approval still preserves repair requests, and
inventory confirmation is independently required before approval submission.

Native static component capture Copy Chapter

Use impeccable component-review capture --manifest review.json instead of
prepare when the component packet needs native provenance. Both use the same
versioned store, service and decision contract. Static PNG, WebP and JPEG raster previews remain their
actual files (including alpha). Page previews become native PNG crops captured
at the comp's declared viewport and component box. Context views, when supplied,
are captured too; thumbnails reuse the primary output. Supply isolated component
HTML for the first asset round, not a screenshot pretending to be HTML.

crates/browser/html_snapshot and the CDP response/isolated-world primitives
are extracted from the existing native capture candidate. They freeze and serve
explicit input bytes; the new component adapter adds no aesthetic scoring or
comp-fidelity exception. It waits for images/fonts, verifies the document and
observed resource bodies against the frozen inputs, and checks that the pixels,
DOM and network stay stable across capture. The manifest itself is bound too.
A dependency or region change makes pending submission stale. Capture failure
never replaces an existing review round or substitutes supplied screenshots.

V1 supports static PNG, WebP and JPEG files and static HTML/CSS/inline SVG documents. Animated WebP is rejected. Component-stage capture binds the measured spec centrally and rejects missing measured regions or rasterized controls. Scripted, canvas,
framed and actively animated components are rejected instead of accepting their
fallback. CSS reduced-motion behavior is respected through the browser preference;
styles are not rewritten to make a capture pass. This is provenance for the
rendered state, not a claim that all future interactive states are covered.

The adapter records observed semantic-control, SVG and raster counts as evidence;
it does not decide that required semantics or visual fidelity pass. Human identity, run routing and exact provider continuation belong to the consuming harness. The hero stage uses the same manifest and native capture contract.

Plan and asset review (packet schemaVersion 3) Copy Chapter

A components packet with schemaVersion: 3 (contract: docs/PLAN-REVIEW.md) renders plan-review.ts instead of the inventory view; mountComponentReview dispatches on the packet, so hosts need no change. The first-viewport (hero) stage keeps the view in review.ts.

The comp carries region outlines rather than pins: generated assets solid, planned-in-code dashed, flagged plan items (flags or codeDrawn) amber, and codeRegions visible on hover. Every region is clickable. An asset shows its comp crop beside the generated file at the largest same-scale size the panel allows (up to 4x comp pixels); a transparent file sits on the comp colour around its box, with light and dark as alternatives. A plan item shows the comp around it, never shrinking a band below comp scale, with the plan in one sentence and any flag above it. Each item has three decision buttons: "Looks good", "Needs work" and "Split into layers" for assets (split is the primary alternative when the asset reads as a baked composite), and "Code is fine", "Make it an image" and "Something else…" for plan items, where the last one asks for the region-map change as feedback. A codeRegions entry needs no decision and offers only "Make it an image", which travels in submission.reclassify.

There is no bulk approval and no separate completeness checkbox. "Approve plan and assets" is enabled once every item is approved with nothing changed or missing, and sets inventoryConfirmed: true; any feedback, reclassification or missing mark turns it into "Send changes". Pure logic lives in plan-model.ts with tests beside it.

Design-system kit (vendored) Copy Chapter

Controls are the Impeccable site kit, not local imitations: .ks-button, .ks-instrument-strip.is-paper with its sliding .ks-thumb, .ks-switch, .ks-checkbox, .ks-icon-button, .ks-tab-list, and the docs rail's selected-row pattern. vendor/ holds verbatim copies of impeccable-site's kinpaku-tokens.css, the needed kinpaku-kit.css sections, the rail rules from docs-kinpaku.css, and instrument-strip.js; the site is the source of truth. Refresh with node scripts/sync-kinpaku-kit.mjs [path-to-impeccable-site]. instrument-strip.ts ports the thumb script to shadow roots and re-rendering views; the region-map inspection page (crates/comp-verbs/src/map_inspection.html) inlines the same vendored CSS and script and ships the fonts beside the report.

Overview (`crates/live/assets/README.md`) Copy Section

Live browser assets

Two generated files, both tracked, both rewritten by cargo xtask bundle.
Do not hand-edit either one.

detect-antipatterns-browser.js is the in-page detector bundle: the rule
core (crates/core) compiled to WebAssembly by crates/wasm, concatenated
with the page JS in browser-bundle/ and the module embedded as base64.
crates/live/src/browser_assets.rs embeds it with include_str! and the
live server hands it to the browser as /detect.js, so the binary has to
carry it.

antipatterns.json is the rule registry (crates/foundation/src/registry.rs)
as [{ id, name, category, description }], the same slice
cargo xtask bundle vendors into the extension's extension/detector/. It
is tracked because extension/detector/ is not: a consumer working from a
source checkout or a repo tarball (impeccable.style counts and renders the
rules from it) has no other way to read the registry without a Rust
toolchain.

cargo xtask bundle          # rewrites both (and extension/detector/)
cargo xtask bundle --check  # fails when either is stale

The other browser scripts the live server serves (live-browser*.js,
modern-screenshot.umd.js) are not copied here: they are embedded straight
from skill/scripts/, the one copy the build also ships to every provider.

Overview (`tests/oracle/vectors/README.md`) Copy Section

Function-level vectors

record-calls.mjs runs the detect CLI and the pure-function unit tests with a
loader hook (hooks.mjs / hooks-impl.mjs) that routes every exported
function declaration in the pure engine modules through recorder.mjs. Each
call whose arguments and result are plain data is written once (deduplicated by
arguments) to calls/<module>/<fn>.jsonl as { "args": [...], "result": ... }.

Encoding of values JSON cannot carry: {"$undef":true}, {"$nan":true},
{"$inf":1|-1}, {"$negzero":true}, {"$map":[[k,v],...]}, {"$set":[...]}.

calls/_skipped.json names the functions whose calls held DOM-ish objects or
closures; those are covered end to end by the detect goldens instead.

calls/ (about 6 MB) is the frozen snapshot recorded from the JS engine
right before it left the tree with the launcher swap. It can never be
regenerated: the modules record-calls.mjs, hooks.mjs, hooks-impl.mjs,
and recorder.mjs instrumented no longer exist here, and those scripts stay
only as the historical record of how the vectors were produced. Treat the
directory as read-only test data for the engine's rule-level parity checks.

The recorder deduplicated per run, not across runs, so the snapshot arrived
with 12,208 byte-identical repeat lines (43% of it) that asserted nothing the
first occurrence did not. Those were removed once, keeping first occurrences
and file order. That is the only edit the snapshot accepts: every remaining
line is a distinct call, and no line may be added, reordered, or rewritten.

BUNDLE SIGNING (`docs/BUNDLE-SIGNING.md`) Copy Section

Skill bundle signatures

impeccable install, update, and check authenticate a remote skill ZIP
before extracting it. universal.zip.sig.json is an Ed25519 signature over
the ZIP's SHA-256 digest, byte length, release version, artifact name, and key
ID. The engine trusts only scripts/bundle-signing-keys.json, compiled into
the binary. A signature cannot introduce a new trusted key.

The download endpoint on impeccable.style redirects to a versioned GitHub
release. The installer resolves that redirect once and downloads the ZIP and
its signature from that same release. Every subsequent redirect must use
HTTPS. Missing signatures, unknown keys, changed metadata, and changed ZIP
bytes stop the operation before extraction or writes to installed skills.
The temporary download directory is removed on failure.

Sign a release Copy Chapter

Install the 1Password CLI and enable its desktop app integration. The signing
item holds the PKCS#8 Ed25519 private key in a concealed private-key field.
Set references, not key material, in your shell:

export OP_ACCOUNT='<account ID or sign-in address>'
export IMPECCABLE_SIGNING_KEY_REF='op://<vault ID>/<item ID>/private-key'
bun run release:skill

For a persistent setup on your machine, use local Git settings instead:

git config --local impeccable.signingAccount '<account ID or sign-in address>'
git config --local impeccable.signingKeyRef 'op://<vault ID>/<item ID>/private-key'

Those values stay in .git/config, outside version control. Environment
variables take precedence. Neither setting contains the private key.

The release command rebuilds the ZIP, reads the key through op read, checks
that its public key is trusted, and writes the sidecar before creating any
tag or release. The ZIP and sidecar are uploaded together. The key is never
passed as a command argument, written to a temporary file, or printed. It
does exist briefly in the local signing process's memory. 1Password failures
are reported without forwarding child-process output.

--dry-run does not access 1Password or create a signature. It checks the
usual release prerequisites and shows both assets in the upload plan; it
does not prove that signing credentials work.

To sign an already-published release for the initial rollout, download and
review the exact released universal.zip, then run:

node scripts/sign-bundle.mjs 4.2.0 /path/to/universal.zip

Check the resulting sidecar against the Rust verifier and compiled public key:

IMPECCABLE_VERIFY_BUNDLE=/path/to/universal.zip \
IMPECCABLE_VERIFY_BUNDLE_VERSION=4.2.0 \
cargo test -p impeccable-skills verifies_reviewed_release_with_production_keyring -- --ignored

This creates only the local sidecar. It neither uploads it nor replaces the
ZIP. Never regenerate an old ZIP and sign those different bytes as the old
release. Uploading the sidecar is a separate maintainer approval step.

Rollout and rotation Copy Chapter

Before shipping the enforcing engine, publish a valid signature beside the
exact ZIP currently served by impeccable.style. Verify the pair using a
locally built engine, then release the engine, its npm platform packages, and
the CLI/skill pins. Keep the existing release available throughout. Do not
release an enforcing engine with an empty keyring or an unsigned served ZIP.

For planned rotation, ship an engine trusting both the old and new public
keys before signing with the new key. Older engines that do not know the new
key will refuse the download and ask for a CLI update. A compromised key
requires an engine update removing that public key; removing it from a
website does not revoke trust in already-installed binaries. Keep the
dedicated signing item separate from GitHub and deployment credentials.

Scope Copy Chapter

This protects against bundle substitution when an attacker can change the
download endpoint, release asset, or both, but cannot use the signing key or
replace the trusted engine. It is not a freshness protocol: a previously
signed release can still be replayed. Signed timestamp metadata and rollback
state are separate work. Signatures do not establish that authored skill
content is safe, and do not authenticate separately downloaded engine
binaries (those currently use their existing SHA-256 sidecars).

IMPECCABLE_BUNDLE_PATH and impeccable link are explicit local-development
trust paths. They continue to accept unsigned local files/directories. Do not
use those overrides to get around a failed remote verification. There is no
unsigned-network fallback or skip-signature flag.

Wire format Copy Chapter

JSON sidecar fields: schema (1), keyId, version, artifact
(universal.zip), size, sha256, signature. Hex strings are lowercase;
the public key is 32 bytes and the signature is 64 bytes. Unknown or repeated
fields are rejected. The signature payload is UTF-8 with LF line endings
and a final LF:

impeccable-skill-bundle-v1
<keyId>
skill-v<version>
universal.zip
<size as decimal>
<sha256 as lowercase hex>

The Node signer and Rust verifier share a fixed test vector under
tests/fixtures/bundle-signature.json. Its deterministic test key must never
be added to the production keyring.

CLI CONTRACT (`docs/CLI-CONTRACT.md`) Copy Section

Impeccable CLI contract

The observable behavior of every impeccable verb: arguments, environment,
inputs, stdout and stderr byte for byte, exit codes, files written, network.
This is the specification an alternate implementation of the scripts has to
meet; tests/oracle/ records goldens against it and replays them.

Verb names are the binary's subcommands. Each verb was a script under
skill/scripts/ or a cli/bin subcommand when this contract was recorded;
the mapping is JS_VERBS in tests/oracle/lib.mjs, and file references below
name those scripts as the source the contract was read from. Since the
launcher swap the skill invokes every verb as {{scripts_path}}/impeccable <verb> and the scripts are gone from the tree; the contract stands as
written.

Quoted strings, regexes, and JSON in this document are verbatim from the
source, including any em dashes inside user-facing messages; do not "fix" them.

Sections:

1. Detect CLI and misc verbs (detect, ignores, skills, concept-seed, serve-question, generate-image)
2. Context and utility verbs (context, doctor, pin, surface-brief, critique-storage, palette, embed-prompt, signals, detect-csp)
3. Design hook (hook, hook-before-edit, hooks)
4. Live mode (live*)

1. Detect CLI and misc verbs Copy Chapter

Source snapshot: repo impeccable-second @ main (f88b2837), 2026-08-17. Node >=22.18.0, package impeccable v3.6.0, "type": "module", bin: { impeccable: cli/bin/cli.js }, main/exports["."]: cli/engine/detect-antipatterns.mjs, exports["./browser"]: cli/engine/detect-antipatterns-browser.js.

Notation: stdout> / stderr> are literal writes; exit N; template strings use ${} as in the source. All regexes are quoted verbatim.

PART 1 — the `impeccable` binary and the detect engine Copy Section

`cli/bin/cli.js` -> `impeccable ` (root dispatcher)

• Invoked from: README.md "CLI" section (npx impeccable detect src/, npx impeccable ignores ...), README.npm.md Quick Start, skill/reference/hooks.md:15 ("Manual npx impeccable detect scans use the same project filter config..."), hooks.md:65 ("Run npx impeccable detect first to see what actually fires there").
• Args: args = process.argv.slice(2), command = args[0].
• Dispatch order (exact):
  1. !command || command === '--help' || command === '-h' → print (via console.log, stdout) then exit 0:
     text Copy

     Usage: impeccable <command> [options]
     
     Commands:
       detect [file-or-dir-or-url...]   Scan for UI anti-patterns and design quality issues
       ignores                          Manage detector ignore rules, files, and values
       help                             List all available skills and commands
       install                          Install impeccable skills into your project or global harness
       link                             Symlink skills from a local checkout or submodule
       update                           Update skills to the latest version
       check                            Check if skill updates are available
     
     Options:
       --help       Show this help message
       --version    Show version number
     
     Compatibility:
       impeccable skills <command>       Legacy namespace; still supported.

  2. --version / -v → console.log(pkg.version) read from <cli/bin>/../../package.json; exit 0. The binary run directly (the skill launcher's path) prints the installed skill's SKILL.md frontmatter version instead (skill dir from IMPECCABLE_SKILL_DIR, else the binary's path), else <engine version>+engine.
  3. detect → process.argv = [argv0, argv1, ...args.slice(1)]; dynamic-import ../engine/detect-antipatterns.mjs, await detectCli().
  4. ignores or ignore → ./commands/ignores.mjs run(args.slice(1)).
  5. skills → ./commands/skills.mjs run(args.slice(1)) (legacy namespace).
  6. command ∈ SKILL_COMMANDS = {'help','install','link','update','check'} → skills.mjs run(args) (note: whole args, so run sees the verb as args[0]).
  7. looksLikeDetectTarget(command) → detect shorthand: process.argv = [argv0, argv1, ...args] then detectCli(). Predicate: arg.startsWith('-') || /^https?:\/\//i.test(arg) || arg.includes('/') || arg.includes('\\') || arg.includes('.') || existsSync(resolve(arg)).
  8. init → console.error('"init" is not a CLI command. Type /impeccable init in your AI coding agent\'s chat (Claude Code, Cursor, Codex, ...), not in this terminal.'), exit 1. (Note: a real path literally named init hits rule 7 first — tested: "a real path named init still routes to detect".)
  9. otherwise → console.error(\Unknown command: "${command}"\n\nTo see a list of supported commands, run:\n impeccable --help`), exit 1`.
• Top-level catch: main().catch(error => { if (error?.code === 'IMPECCABLE_PROMPT_ABORT') { console.log('\nAborted.'); exit 130 } console.error(error?.message || error); exit 1 }).
• No live subcommand exists in the CLI (README/CLAUDE.md mentions of npx impeccable live are aspirational; live mode is driven by skill/scripts/live*.mjs, out of scope here).
• Tests: tests/skills-cli.test.js ("root help advertises top-level skills commands", "top-level install aliases the legacy skills install command", "#472" init tests, "a real path named init still routes to detect").

`cli/engine/detect-antipatterns.mjs` (facade) and `skill/scripts/detect.mjs` (wrapper) -> `impeccable detect`

• Facade: re-exports registry (ANTIPATTERNS, RULE_ENGINE_SUPPORT, getAntipattern, getRulesForCategory, getRuleEngineSupport), constants (SAFE_TAGS, BORDER_SAFE_TAGS, OVERUSED_FONTS, GENERIC_FONTS, KNOWN_SERIF_FONTS), color helpers, isFullPage, check fns, createDetectorProfile, summarizeDetectorProfile, design-system fns (parseFrontmatter as parseDesignFrontmatter, normalizeDesignSystem, loadDesignSystemForCwd, checkSourceDesignSystem, collectStaticDesignSystemFindings), detectHtml, detectUrl, createBrowserDetector, detectText, extractStyleBlocks, extractCSSinJS, fs helpers (walkDir, hasScannableExtension, SCANNABLE_EXTENSIONS, SKIP_DIRS, buildImportGraph, resolveImport, detectFrameworkConfig, isPortListening, FRAMEWORK_CONFIGS), formatFindings, detectCli. Main-module guard: process.argv[1]?.endsWith('detect-antipatterns.mjs') || endsWith('detect-antipatterns.mjs/') → detectCli().
• skill/scripts/detect.mjs (what the skill invokes as node {{scripts_path}}/detect.mjs ...): candidates in order <scripts>/detector/detect-antipatterns.mjs (bundled install layout), then <scripts>/../../cli/engine/detect-antipatterns.mjs (repo layout). If neither exists: stderr> Error: bundled detector not found.\n, exit 1. Else dynamic-imports via pathToFileURL and await detectCli(). detectCli strips a leading detect arg itself, so both detect.mjs --json x and detect.mjs detect --json x work.
• Skill call sites (quoted):
  • reference/routing.md:16: "If scan.targets is non-empty and setup.platform is not ios/android/adaptive, run node {{scripts_path}}/detect.mjs --json <scan.targets joined by spaces> once (the bundled detector over local files: no network, no npx; it reads HTML/CSS, so skip it for native projects)."
  • reference/critique.md:73: node {{scripts_path}}/detect.mjs --json [target] with "Pass markup files/directories as [target]; do not pass CSS-only files. For URLs, skip CLI scan and use browser visualization. ... Exit code 0 = clean; 2 = findings. If the detector entrypoint is missing or fails to load, report deterministic scan unavailable and continue".
  • reference/layout.md:28: node {{scripts_path}}/detect.mjs --json --scope layout [target files or dirs]; reference/typeset.md:27: ... --scope type ....
  • reference/audit.native.md:3: "no browser tooling or detect.mjs applies" for native.

`detectCli()` — `cli/engine/cli/main.mjs`

Arg normalization: args = process.argv.slice(2) with -json→--json, -fast→--fast; if args[0] === 'detect' drop it.

Flags (all detected with args.includes unless stated):

Usage text (printUsage, stdout, verbatim):

/* Detailed source-code truncated for AI context efficiency. */

Config: readDetectionConfig(process.cwd()) (see "Config file" below). Note config is resolved from cwd, not from the target.

Design system per target: scanOptionsFor(localPath): if design system enabled and localPath given, loadDesignSystemForTarget(localPath, {cache}) walks up from the target's own dir (never cwd): a dir with DESIGN.md/Design.md/design.md (directly, or under fallback dirs .agents/context, docs) is the design root; a dir with a project marker (.git, package.json, .impeccable) but no DESIGN.md is a boundary → no design system; reaching os.homedir() or fs root → none. Sidecar candidates: <root>/.impeccable/design.json, <root>/DESIGN.json, <contextDir>/DESIGN.json. Cache key root:<dir> or \0none. Options become {...baseScanOptions, designSystem} when found. design-system.mjs has no CLI surface (no main guard, no argv parsing); it only exports functions.

A DESIGN.md purple switches the purple AI-palette check off (Rust engine, corpus decision r3-23-ai-color-palette-brand-hue). When a target's design system declares a purple or violet colour (a DESIGN.md frontmatter colors entry or a sidecar colour, chroma at least 30 and hue 250 to 320 degrees: is_declared_purple in crates/core/src/checks/rules.rs), every engine drops the purple/violet forms of ai-color-palette for that target: the static HTML engine (Purple/violet text (#hex) on heading, text-purple-* on heading, Purple/violet gradient (Tailwind), Purple/violet accent colors detected), the regex engine (text-(purple|violet|indigo)-* on heading, from-(purple|violet|indigo)-* gradient) and the URL engine on a file: target (the same forms plus Purple/violet gradient background and Purple/violet neon text on dark background). A form is purple when its snippet names purple, violet or indigo (is_purple_palette_finding); the cyan forms (Cyan gradient background, Cyan neon text on dark background) keep reporting, and so does every other rule. The drop runs after the built-in passes and before a rule pack and inline ignores, so the design hook, which scans through the same engines with the project's design system, and the wasm detect exports get it too. http(s) targets never load a design system (above) and are unaffected. In text mode (not --json, not --quiet) the CLI then prints, once per design system that applied to a scanned target and after the findings or alone when there are none: stderr> \nNote: ai-color-palette's purple/violet check is off: ${source_path} declares ${label} (${hex}).\n (no leading blank line when there are no findings; ${label} is the first purple's declared name, colors.primary or sidecar.<name>). JSON output has no place for notes and is unchanged apart from the dropped findings.

Input resolution:

1. If !process.stdin.isTTY && targets.length === 0 → stdin mode (handleStdin): read all stdin; try JSON.parse; if parsed.tool_input.file_path exists on disk → detectLocalFile(fp, scanOptionsFor(fp)) (hook payload dispatch); else detectText(input, '<stdin>', scanOptionsFor(null)).
2. Else paths = targets.length ? targets : [process.cwd()]. urlRe = /^(?:https?|file):\/\//i. If more than one URL target, a shared browser is created once via createBrowserDetector() (defaults waitUntil:'load', settleMs:100), closed in finally; a single URL uses detectUrl directly (waitUntil:'networkidle0', settleMs:0).
3. For each target, in order:
   • URL: file: URLs get scanOptionsFor(fileURLToPath(url) or null); http(s) get baseScanOptions (never cwd's design system). Errors: stderr> Error: ${e.message}\n, continue.
   • Else resolved = path.resolve(target); fs.statSync failure → stderr> Warning: cannot access ${target}\n, continue.
   • Directory: unless --json/--quiet, detectFrameworkConfig(resolved) (see below) and if found probes the port, writing one of three stderr notices:
     • listening & matched: \n${name} dev server detected on localhost:${port}.\nFor more accurate results, scan the running site:\n npx impeccable detect http://localhost:${port}\n\n
     • listening & !matched: \n${name} project detected (${basename(configPath)}).\nPort ${port} is in use by another service. Start the ${name} dev server and scan via URL for best results.\n\n
     • not listening: \n${name} project detected (${basename(configPath)}).\nStart the dev server and scan via URL for best results:\n npx impeccable detect http://localhost:${port}\n\n
       Then files = walkDir(resolved, config.extensions).filter(f => !shouldIgnoreDetectionFile(f, cwd, config)). The walk collects built-in scannable extensions plus any detector.extensions from cwd config (empty under --no-config). If files.length > 50 && stdin.isTTY && !json && !quiet: stderr> \nFound ${n} files (${htmlCount} HTML) in ${target}.\nScanning may take a while${htmlCount > 10 ? ' (static HTML/CSS processes each HTML file individually)' : ''}.\nTarget a specific subdirectory to narrow scope.\n then readline prompt Continue? [Y/n] on stderr; empty or /^y(es)?$/i continues; otherwise stderr> Aborted.\n, exit 0. Then buildImportGraph(files) → reverse map; each file scanned with its own options; findings from a file that is imported get f.importedBy = [basename(importer), ...] (Set iteration order).
   • File: skipped if shouldIgnoreDetectionFile; else detectLocalFile.
   • detectLocalFile(fp, opts): a configured detector.extensions entry matching the file (longest suffix) picks the engine (html → detectHtml(fp, opts), text → detectText); otherwise extension (lowercased) in HTML_EXTENSIONS = {'.html','.htm'} → detectHtml(fp, opts); else detectText(readFileSync(fp,'utf-8'), fp, opts). The design hook uses the same rule.
   • Regex-only note (#884): after every target is scanned (never in stdin mode), unless --json/--quiet, if n > 0 local files went to detectText (by the detectLocalFile routing above, so a configured html-engine extension is not counted): stderr> \n${n} file${n === 1 ? '' : 's'} scanned with regex matching only${exts.length ? (${exts.join(', ')}) : ''}.\nRules that need a parsed page (tiny-text, low-contrast and other element rules) did not run on them; findings are an undercount, not a clean bill of health.\n where exts is the sorted set of those files' lowercased extensions (extFromFilePath, empty ones dropped). Then the full scan: ports = the sorted, deduplicated port of every scanned directory that matched FRAMEWORK_CONFIGS (whether or not the dev-server nudge found it listening); when non-empty, For the full check, scan ${ports.length === 1 ? 'the running app' : 'each running app'}:\n followed by npx impeccable detect http://localhost:${port}\n per port, else For the full check, scan the running dev server (npx impeccable detect http://localhost:PORT) or a static site's built .html.\n. Then, only when exts intersects HTML_LIKE_TEMPLATE_EXTS = ['.astro', '.svelte', '.vue'] (in that order, t = the intersection): ${t.join('/')} files can take the HTML engine instead: add { "ext": "${t[0]}", "engine": "html" } under detector.extensions in .impeccable/config.json (trades the regex rules and line numbers for the element rules).\n. JSX/TSX get no opt-in line because the HTML parser reads nothing useful from them. The note precedes the findings output and changes neither stdout nor the exit code.
4. Post-filter: filterDetectionFindings(all, config) (ignoreRules/ignoreValues), then filterByScopes(all, scopes) (keeps findings whose rule declares any requested scope; empty scopes = no filter), then --no-advisory drop.
5. Partition {primary, advisory} by f.advisory === true || f.severity === 'advisory'.

Any target that cannot be scanned sets hadOperationalFailure (#711): a URL
whose browser setup or scan throws, a path statSync cannot reach
(stderr> Warning: cannot access <target>), an unreadable directory or file
in a dir walk, and a per-file scan that throws
(stderr> Error: cannot scan <target>: <message>). A multi-URL scan whose
shared browser fails to launch prints its Error: once and skips every URL
target. A URL whose loaded page is a bot challenge or an HTTP error page is
also a failure to scan (see Page validity gate under URL scans): it
reports no findings and prints stderr> Error: the page is ....

Output and exit codes:

• allFindings.length > 0:
  • json: stdout> JSON.stringify(allFindings, null, 2) + '\n' (all findings, advisory ones flagged).
  • quiet: stderr> ${primary.length} anti-pattern${n===1?'':'s'} found.\n; if advisory: stderr> dim(${adv} advisory note${adv===1?'':'s'} (not counted).) + '\n'.
  • text: stderr> formatFindings(all,false) + '\n'.
  • exit(hadOperationalFailure ? 1 : (primary.length > 0 ? 2 : 0)).
• no findings: json → stdout> []\n; text/quiet → nothing. exit(hadOperationalFailure ? 1 : 0).
• Text mode (not --json, not --quiet) prints scan notes after the findings, or alone when there are none, one line each in first-seen order: the DESIGN.md purple note; for a URL scan that hid consent banners Hid the <names> consent banner(s) on before scanning. Pass --no-consent-hiding to scan it. (<names> joined A, B and C); for one that hid tours or preloaders Hid on before scanning. Pass --no-overlay-hiding to scan it., each item the <library> tour, the badge or the preloader <name>, joined the same way; and for a URL scan whose capture held sliders that never started, the capture note under content-hidden-at-rest below.
• Exit 1 takes precedence over exit 2: findings from the targets that did scan
  do not turn a partial scan into a complete one (#711).
• Any other exit: 1 for arg errors above; uncaught exceptions propagate to cli.js catch (exit 1).
• dim(text) = process.stderr.isTTY ? '\x1b[2m' + text + '\x1b[0m' : text. This is the only ANSI styling in detect output.

Text format (formatFindings(findings, false)):

formatFindingsBody(primary):
  group by f.file preserving first-seen order;
  for each file:  "\n${file}${importNote}"  where importNote = items[0].importedBy?.length ? ` (imported by ${items[0].importedBy.join(', ')})` : ''
     for each item: "  ${item.line ? `line ${item.line}: ` : ''}[${item.antipattern}] ${item.snippet}"
                    "    → ${item.description}"          (U+2192 arrow, 4-space indent)
then "\n${primary.length} anti-pattern${1?'':'s'} found."
then, if advisory non-empty:
  "\n" + dim('── Advisory (not counted as failures) ──')      (U+2500 box-drawing dashes)
  each body line individually dim()-wrapped
  dim(`\n${advisory.length} advisory note${1?'':'s'}. Suppress with --no-advisory.`)
all joined with '\n'.

Example (non-TTY):

/abs/a.css
  line 3: [side-tab] .card — border-left: 4px solid #6366f1
    → Thick colored border on one side of a card — ...

1 anti-pattern found.

── Advisory (not counted as failures) ──

/abs/a.html
  [em-dash-overuse] 9 em-dashes in body text
    → Em-dash saturation ...

1 advisory note. Suppress with --no-advisory.

Finding object (cli/engine/findings.mjs finding(id, filePath, snippet, line = 0)), key order exactly:

{ antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', category: ap.category || null, file: filePath, line, snippet }
// plus, only when the effective severity is 'advisory':  advisory: true

Optional keys added later by engines (appended after the above): ignoreValue (design-system rules; browser findings with a value), importedBy (dir scans), selector, thirdParty, consentHidden and overlaysHidden (URL scans, below), severity may be overwritten by per-finding promotion (browser & html-patterns, e.g. pulsing dot in a header). Design-system findings are {...finding(...), ...extras} where extras = { ignoreValue }. Static-HTML and browser findings have line: 0; regex findings have 1-based lines. severity values in registry: 'warning' (default), 'advisory' (many generated-UI tells and design-system-color/radius/font-size, numbered-section-labels, blinking-cursor, shape-assembled-illustration, bounce-easing), 'error' (script-error, content-hidden-at-rest). Per-finding demotions to 'advisory' in the Rust engine: flat-type-hierarchy when weight separates the roles (below), a script-error an ad-tech script threw, and a script-error that is one of React's recoverable hydration errors (URL scans). severity is the canonical advisory field (#709): deriveAdvisoryFlag stamps advisory: true when and only when the effective severity is 'advisory', so a per-finding promotion or demotion carries the flag with it, and every severity:'advisory' rule is partitioned out of the failure count and the exit code. isAdvisory accepts either finding.advisory === true or finding.severity === 'advisory'.

Categories: category is 'slop' (AI tells) or 'quality'. Category has no effect on output, ordering, or exit codes; it is only carried in the finding and used by getRulesForCategory. Registry (59 ids, in order): side-tab, border-accent-on-rounded, overused-font, flat-type-hierarchy, gradient-text, ai-color-palette, cream-palette, nested-cards, monotonous-spacing, bounce-easing, pulsing-dot, blinking-cursor, shape-assembled-illustration, organic-clip-path, buried-raster, dark-glow, radial-halo, radial-spotlight-glow, marquee, icon-tile-stack, italic-serif-display, hero-eyebrow-chip, kicker-above-heading, numbered-section-labels, em-dash-overuse, marketing-buzzword, aphoristic-cadence, oversized-h1, extreme-negative-tracking, broken-image, script-error, content-hidden-at-rest, edge-flush-cards, text-occlusion, first-viewport-column-overflow, gray-on-color, low-contrast, line-length, cramped-padding, body-text-viewport-edge, tight-leading, skipped-heading, heading-rhythm, justified-text, tiny-text, undersized-ui-text, all-caps-body, wide-tracking, text-overflow, repeated-container-text, clipped-overflow-container, design-system-font, design-system-color, design-system-radius, design-system-font-size, gpt-thin-border-wide-shadow, repeating-stripes-gradient, codex-grid-background, theater-slop-phrase. Retired ids (image-hover-transform, layout-transition) are in no list and no engine reports them; an ignoreRules entry or an inline impeccable-disable naming one still parses and suppresses nothing, and doctor reports it as detector-ignore-rules-unknown. Scopes: type = overused-font, flat-type-hierarchy, italic-serif-display, hero-eyebrow-chip, kicker-above-heading, numbered-section-labels, oversized-h1, extreme-negative-tracking, line-length, tight-leading, skipped-heading, heading-rhythm, justified-text, tiny-text, undersized-ui-text, all-caps-body, wide-tracking, design-system-font, design-system-font-size; layout = nested-cards, monotonous-spacing, icon-tile-stack, content-hidden-at-rest, edge-flush-cards, text-occlusion, first-viewport-column-overflow, line-length, cramped-padding, body-text-viewport-edge, heading-rhythm, text-overflow, clipped-overflow-container. RULE_ENGINE_SUPPORT = { regex: Set['source','page-analyzer'], 'static-html': Set['element','page'], browser: Set['element','page','layout'], visual: Set['visual-contrast'] }.

Tests: tests/detect-antipatterns-fixtures.test.mjs (CLI block: --help exits 0 and contains Usage:/--quiet, not --gpt; --gpt prints deprecation; detect prefix accepted; should-pass exits 0; should-flag exits 2 with side-tab in stderr; --json parses; --quiet stdout empty and stderr matches /^[1-9]\d* anti-patterns? found\.$/; formatFindings — advisory partitioning), tests/detect-cli-stdin-dispatch.test.mjs, tests/detect-cli-design-contamination.test.mjs, tests/inline-ignores.test.mjs ("detect CLI end-to-end"), tests/detect-url-launch.test.mjs.

`cli/engine/node/file-system.mjs`

• SKIP_DIRS = {'node_modules','dist','build','__pycache__'}; any directory whose name starts with . is skipped except HIDDEN_SOURCE_DIRS = {'.vitepress','.vuepress','.storybook'}. The root passed to walkDir is never name-checked (an explicit hidden dir scans).
• SCANNABLE_EXTENSIONS = {'.html','.htm','.css','.scss','.sass','.less','.jsx','.tsx','.js','.ts','.vue','.svelte','.astro','.blade.php'}; hasScannableExtension lowercases and also matches multi-dot exts by endsWith (.blade.php). CLI directory walks pass configured detector.extensions as a second suffix match: name lowercased; name.length > ext.length && name.endsWith(ext).
• walkDir returns files in readdirSync order, recursive, unreadable dirs → [].
• There is no generated-file detection in the CLI (skill/scripts/lib/is-generated.mjs is hook-side only and not imported by cli/).
• Import graph: IMPORT_SPECIFIER_PATTERNS = [/import\s+(?:[\s\S]*?from\s+)?['"]([^'"]+)['"]/g, /@import\s+(?:url\(\s*)?['"]?([^'");\s]+)['"]?\s*\)?/g, /@(?:use|forward)\s+['"]([^'"]+)['"]/g]; resolveImport only for specifiers matching /^[./]/: exact, base+ext for each scannable ext, then base/index+ext.
• FRAMEWORK_CONFIGS (first match wins, in this order): Next.js (next.config.js|mjs|ts, 3000, /port\s*[:=]\s*(\d+)/, header x-powered-by ~ /next/i); SvelteKit (svelte.config.js|ts, 5173, header x-sveltekit-page any); Nuxt (nuxt.config.js|ts, 3000, x-powered-by ~ /nuxt/i); Vite (vite.config.js|ts|mjs, 5173, body /@vite\/client/); Astro (astro.config.js|ts|mjs, 4321, body /astro/i); Angular (angular.json, 4200, /"port"\s*:\s*(\d+)/, body /ng-version/i); Remix (remix.config.js|ts, 3000, x-powered-by ~ /remix/i). Port overridden by first regex match in the config file.
• isPortListening(port, fingerprint): with fingerprint → fetch('http://localhost:${port}/') 2s abort, header check then body check → {listening:true, matched:bool}; error → {listening:false}. Without fingerprint → TCP connect to 127.0.0.1 with 500ms timeout.

`cli/engine/shared/inline-ignores.mjs` — inline ignore comments

• DIRECTIVE_RE = /impeccable-(disable-next-line|disable-line|disable)\b[ \t]*([^\n\r]*)/gi (matched anywhere on a line, any comment syntax; case-insensitive).
• TRAILING_CLOSER_RE = /\s*(?:\*\/\}?|--+>|\*\}|#\}|%>|\}\})\s*$/ stripped from the remainder; then reason cut at first /\s*(?:--+|:)\s*/; tokens split on /[\s,]+/, lowercased; empty or containing * → ['*'].
• Lines split on '\n' only (CRLF-safe since \r excluded from capture). disable → file set; disable-line on line i (1-based) → line.get(i); disable-next-line on line i → nextLine.get(i+1).
• isInlineIgnored(finding): rule = lowercased finding.antipattern; file set match (* or rule) → true; if line > 0, line/nextLine set match → true. Line-less findings (static HTML, browser) match only whole-file directives.
• Applied inside detectText and detectHtml at the end unless options.inlineIgnores === false (set by --no-config or --no-inline-ignores). Not applied to URL scans.
• Fast path: skip unless /impeccable-disable/i occurs.
• DOM-scoped ignore (rules/checks.mjs scopedIgnoreActive): attribute data-impeccable-ignore="rule-a rule-b" (split on /[\s,]+/, lowercased; empty value or * = all) on an element waives matching findings for it and its subtree in browser, extension, and static engines. In detectHtml's html-patterns pass, selector-backed findings are dropped when every element matched by the (pseudo-stripped) selector is under a waiver; unmatched selectors keep the finding.
• Tests: tests/inline-ignores.test.mjs; fixture scoped-ignore.html.

Config file (`cli/lib/impeccable-config.mjs`) — `.impeccable/config.json` + `.impeccable/config.local.json`

• Paths: <root>/.impeccable/config.json (shared) and <root>/.impeccable/config.local.json (per-dev; writeDetectionConfig(...,{local:true}) also appends a block to .git/info/exclude: # impeccable-config-ignore-start\n.impeccable/config.local.json\n# impeccable-config-ignore-end, idempotent by marker regex, following gitdir: files, and a linked worktree's commondir, to the exclude file git reads).
• Shape:
  json Copy

  { "detector": { "ignoreRules": ["side-tab"], "ignoreFiles": ["src/legacy/**"],
                  "ignoreValues": [{ "rule": "overused-font", "value": "inter", "files": ["src/a.css"], "createdAt": "ISO", "reason": "..." }],
                  "designSystem": { "enabled": true }, "advisoryRules": "include"|"exclude" },
    "hook": { "consent": "accepted"|"declined", ... }, "updateCheck": true }

• readDetectionConfig(root): start {ignoreRules:[],ignoreFiles:[],ignoreValues:[],designSystem:{enabled:true},extensions:[]}; for shared then local: apply legacy raw.hook.* section then raw.detector.*. Arrays are unioned (uniqueStrings, String-coerced); ignoreValues merged by key rule\0value\0sortedFiles.join('\x1f') (later wins); designSystem.enabled false only when literally false; advisoryRules copied only if 'include'|'exclude'; extensions merges normalized detector.extensions entries by ext, later source wins (string → engine html; {ext, engine} → text only when engine is literally "text"). Invalid/non-array extensions skipped. Invalid JSON / non-object files are ignored silently. No validation errors are ever raised by the CLI; the only validation of ignore lists lives in skill/scripts/lib/staleness-deep.mjs checkDetectorIgnores (doctor): unknown ignoreRules ids vs live ANTIPATTERNS → finding detector-ignore-rules-unknown (severity mention); non-glob ignoreFiles entries that don't exist → detector-ignore-files-missing.
• normalizeIgnoreValue(v): trim, strip one leading/trailing quote, +→space, collapse whitespace, lowercase. Rules lowercased/trimmed.
• normalizeIgnoreValueEntries: keeps {rule, value, [files], [createdAt], [reason]} in that key order; file (string) and files merged, trimmed, deduped.
• Glob → regex: ** → .* (swallowing a following /), * → [^/]*, ? → [^/], {a,b} → (?:a|b), regex specials escaped; anchored ^...$. matchesAnyGlob tests the /-normalized path and its basename.
• shouldIgnoreDetectionFile(filePath, root, config): raw path, absolute path, and root-relative path (if inside root) tested against ignoreFiles.
• filterDetectionFindings: drop when ignoreRules has the rule, or an ignoreValues entry matches: same rule; entry.value * (wildcard) OR extracted value equals (with color-key equality for design-system-color: rgb/hex/hsl parsed to r,g,b,round(a*255)); if entry has files, finding.file (or any /-suffix of it) must glob-match; a wildcard with no files never matches (unscoped * disallowed).
• extractFindingIgnoreValue: only for overused-font, bounce-easing, design-system-font, design-system-color, design-system-radius, design-system-font-size; source finding.ignoreValue || finding.value, else parse detail/snippet: bounce → animate-bounce, cubic-bezier(...), or animation token matching /bounce|elastic|wobble|jiggle|spring/i; fonts → Primary font:, Google Fonts:, font-family: value, or family= URL param (decoded).

`impeccable ignores` (`cli/bin/commands/ignores.mjs`)

• Actions/aliases: status|ls|list→list (default when no action), add-rule|ignore-rule, add-file|ignore-file, add-value|ignore-value|update-value, remove-rule|rm-rule, remove-file|rm-file, remove-value|rm-value, clear. --help/-h prints usage (stdout). Unknown → throws Unknown ignores action: ${a}. Run "impeccable ignores --help". (exit 1 via cli.js).
• Scope flags: --shared (default), --local, --all (remove/clear only); more than one → error Pass only one scope flag: --shared, --local, or --all (or --shared or --local).
• add-rule <rule> [--all-values] [--reason ...]: overused-font without --all-values → error "overused-font is value-specific by default. Use add-value overused-font , or add-rule overused-font --all-values for broad suppression." Output: Added ${rule} to ${local?'local':'shared'} detector ignoreRules (${relpath}).
• add-file <glob> → Added ${glob} to ... detector ignoreFiles (...).
• add-value <rule> <value...> [--file <glob>]... [--reason <text...>]: value = normalized join of positionals after rule; --file/--files/--file=/--files= (empty or flag-like → error); unknown --x → Unknown add-value flag: --x; * value requires --file; existing entry (same key) updates reason/files, else pushes {rule,value,[files],createdAt: ISO now,[reason]}. Output Added ${rule}=${value} to ... detector ignoreValues (...).
• remove-* → Removed ${n} from shared (path), ${n} from local (path). or No matching detector ignore found. clear → Cleared detector ignores in ${'shared and local config'|'local config'|'shared config'}.
• list output:
  text Copy

  Impeccable detector ignores
    shared file: .impeccable/config.json
    local file:  .impeccable/config.local.json
  
  Merged:
    ignoreRules:  (none)
    ignoreFiles:  ...
    ignoreValues: rule=value [glob1, glob2] - reason, ...
    designSystem: enabled|disabled
  
  Shared:
  ...
  
  Local:
  ...

• Tests: tests/cli-ignores.test.js.

`cli/engine/engines/browser/detect-url.mjs` — URL scans

• detectUrl(url, options); options: profile, waitUntil (default 'networkidle0'), settleMs (default 0), viewport (default {width:1280,height:800}), browser (external), headless (default true), designSystem, scriptErrors (default on), contentHidden (default on), visualContrast/visualContrastBrowser/visualContrastPixel (default on), visualContrastMaxCandidates (12), visualContrastScrollOffscreen (true).
• Puppeteer imported dynamically; missing → throw puppeteer is required for URL scanning. Install: npm install puppeteer. Browser script read from <engine>/detect-antipatterns-browser.js; missing → Browser script not found at ${path}.
• Launch: launchArgs = process.env.CI ? ['--no-sandbox','--disable-setuid-sandbox'] : []. On win32 first puppeteer.launch({channel:'chrome', headless, args}), on failure fall back to bundled puppeteer.launch({headless, args}) with err.cause = channelError. Non-Windows: bundled only.
• Flow: newPage → attach pageerror listener (message first line, trimmed, sliced to 160 chars, deduped) → setViewport(viewport) → page.goto(url, {waitUntil, timeout: 30000}) → optional settle → page.evaluate sets window.__IMPECCABLE_CONFIG__ = {...existing, autoScan:false, ...(designSystem ? {designSystem} : {})} where designSystem serialized as {present:true, hasFonts, allowedFonts:[...], hasColors, allowedColors:[{r,g,b}], hasRadii, allowedRadii:[px], hasPillRadius} → page.evaluate(browserScript) (injects the bundle; defines window.impeccableDetect/impeccableDetectAsync/impeccableScan/impeccableScanAsync/impeccableMeasureHiddenText/impeccableCollectVisualContrastCandidates/impeccableAnalyzeVisualContrast/impeccableGetLastVisualContrastAnalyses) → window.impeccableDetect({decorate:false, serialize:true}) returns groups [{selector, tagName, rect, isPageLevel, isHidden, findings:[{type, category, severity, advisory, detail, ignoreValue, name, description}]}]; flattened to {id:type, snippet:detail, ignoreValue, severity} → content-hidden sweep (measureContentHiddenAfterReveal: scroll in steps max(200, floor(innerHeight*0.7)) with behavior:'instant', 40ms rAF pauses, back to top, wait 700ms, then impeccableMeasureHiddenText(); checkContentHiddenAtRest fires when totalChars>=200 && hiddenChars>=150 && share>0.3, snippet ${pct}% of page text (${hidden} of ${total} chars) stays at opacity 0 / visibility hidden after reveal handlers ran (e.g. "sample")) → up to 3 script-error findings {id:'script-error', snippet:message} → visual contrast fallback → finally close page (and browser if owned).
• Visual contrast fallback (runVisualContrastFallback): browser-side impeccableAnalyzeVisualContrast({maxCandidates, scrollOffscreen}) findings not already low-contrast on that selector; then candidates (from analyses or impeccableCollectVisualContrastCandidates) not resolved pass/fail → per candidate captureVisualContrastCandidate(page, candidate, viewport).
• Screenshot flow (screenshot-contrast.mjs, as the JS ran it; the Rust engine's verdict and refusals replace the p10 rule below, see What the visual pass refuses to read under the Rust engine additions): clip sanitized (x,y floored ≥0; width ≤ viewport width (default 1600), height ≤ 320, both ≥1); page.screenshot({encoding:'base64', clip, captureBeyondViewport:true}) before; inject <style id="impeccable-visual-contrast-hide-style">[data-impeccable-visual-contrast-target]{color:transparent!important;-webkit-text-fill-color:transparent!important;text-shadow:none!important}[data-impeccable-visual-contrast-target][data-impeccable-bgclip-text="true"]{background-image:none!important} and set attribute data-impeccable-visual-contrast-target=impeccable-contrast-${Date.now()}-${rand} (+ data-impeccable-bgclip-text="true" if candidate.backgroundClipText); screenshot after; remove attributes; in-page canvas diff: pixels with channel delta sum ≥10 are glyph pixels; ratio uses WCAG luminance of CSS text color (unless preferRenderedForeground) vs after-pixel; needs ≥8 ratios; p10 = ratios[floor(0.10*n)]; finding when p10 < candidate.threshold: {id:'low-contrast', snippet:pixel contrast ${p10.toFixed(1)}:1 median ${median.toFixed(1)}:1 (need ${threshold}:1) on ${reasons.slice(0,3).join(', ') || 'visual background'} "${text}"}. No screenshot files are written.
• Results mapped via finding(id, url, snippet) (file = the URL, line 0); ignoreValue set if present; severity overridden if the browser supplied one.
• Rust engine additions (not in the JS):
  • Scan order. The reveal sweep runs before anything is measured, and one post-reveal capture serves every pass: the rule pass, content-hidden-at-rest, and the visual-contrast pass all read that capture, so a hit test any of them answers is answered for all three. The JS ran the rule pass over a capture taken right after load, when a scroll-reveal section is still at opacity 0 and the element checks skip it; the rules now measure the page as a visitor who scrolls it sees it, which reports the faults inside revealed sections and no longer reports a fade-in as buried-raster. content-hidden-at-rest still measures what stays hidden after the reveal handlers ran. Phase names, profile events, and the order findings are emitted in are unchanged.
  • Covered text and unread surfaces. The element pass asks elementsFromPoint over a failing low-contrast run, at the points the text-occlusion grid asks for the same box, in the same hit-test rounds. Where every deciding point has an image, video, canvas, or opaque fill at full opacity above the text (not the element, a descendant or an ancestor), the text is covered at capture: no verdict, and the visual-contrast collector skips it too. Where every deciding point has paint beneath the text that is nobody's ancestor, lies above the surface the background walk used, and could change what the text sits on, no element-pass verdict is printed; a visual-contrast candidate is still measured. That paint is a picture (an image, video, canvas or SVG image, or a url() background drawn no-repeat, cover, contain, at a percentage or larger than 256px), a gradient or fill that moves the named colour by more than 24 summed over the channels once composited over it, or, where the walk named no single colour or only reached the page ground (html, body, the canvas), a gradient, fill or SVG shape it cannot compare. Texture is read past and the verdict stands: a gradient drawn in cells of at most 64px on both axes, a repeating-* gradient, a gradient whose stops are mostly transparent or that pairs a transparent stop with a stop within 3px, a url() repeated at a drawn size of at most 256px, anything with a mask-image, and a picture, gradient or shape at an effective opacity of 0.3 or less. Paint at alpha times opacity of 0.1 or less is a wash and is read past too. A layer that cannot be placed (a remote image tiled at its own size, an image-set) keeps the verdict. The snapshot records maskImage and webkitMaskImage for this. The run must lie wholly inside the viewport, every point must be answered, and at least half must find the text; otherwise, and for a run only partly under a layer, the verdict stands. The SAFE_TAGS path asks before the page claims a colour pair. text-occlusion counts a decorated box only where its captured rect holds the probe point, so an answer from a page that moved after the capture names no occluder.
  • What is not painted at capture reports nothing. The URL engine's element pass drops findings on an element the painted-at-capture predicate (crates/core/src/browser/painted.rs) says a visitor cannot see: display: none or content-visibility: hidden above it, visibility: hidden or checkVisibility() false, an effective opacity of 0.02 or less, a clipping ancestor with no area or no overlap, a box wholly outside the document, a 1px visually hidden box. The text measurements, italic-serif-display and gradient-text also need text and area; bounce-easing, dark-glow and ai-color-palette need area. blinking-cursor needs area, and its own opacity and a visibility: hidden its parent does not share do not hide it, so a cursor caught between blinks still reports. kicker-above-heading asks the same about the heading and the label above it. The page-level forms of bounce-easing, dark-glow and pulsing-dot report only when their selector matches at least one painted element (no area test, since the selector may name a pseudo-element); a form without a selector is unchanged. text-occlusion asks it about the covered text, every hit-test answer that covers it, each card a headline overhangs and each inline leak host, in addition to its own ancestor test; it also skips text under a filter: blur() of 4px or more on the element or an ancestor and text with fewer than two characters on screen (a lone emoji), and names what covers the text: overlapping text, an SVG graphic (an SVG element other than text, tspan or textPath), an opaque element (a box with an opaque fill), or a bordered element (a box counted through its borders alone). content-hidden-at-rest is not gated. The static HTML engine measures no boxes and is unchanged.
  • The box the text sits in (observations-42 rows 5, 6, 12 and 13). cramped-padding's own-text form measures only the recorded lines that cross the element's box (a line that wraps out below a fixed-height box is not held by it; a box none of whose lines cross it is not measured), skips display: inline boxes (a highlight hugs its glyphs by design), and does not count the sides of a background-only box that reaches both edges of the viewport. Its flush form reads no edge where an ancestor's background-image is gradients alone whose every shown colour nearly matches the box's fill (with transparent stops, only linear-gradient(to <side>, transparent <len>, <fill> <len>) with the box wholly in the filled part), or where an earlier sibling layer under the box holds an img or video (not a canvas) that paints (shown, not faded to 0.05 or less on the way) and whose own rect covers it, and inside a chip under 27.5px a label lands on an edge within a quarter of its font size (at most 4px), scaled as before. text-occlusion probes only the points on the victim's recorded lines that cross its own text when there are lines, no rotation or skew on it or above it, and at least one grid point on a line, and the share covered is taken over those points; it skips an answer that is a button or link (or within two levels of one) positioned absolute or fixed that reaches within a tenth of its height of the top and the bottom of a sideways scroller that overflows, holds the victim and not the control, and is at least four times as wide as the control, at one of the scroller's ends; the inline leak form reports only when the fill overlaps a sibling with text, and prints the box height less one line height per recorded line; and where the box or text that answered is not itself filled, the snippet adds on an opaque layer (<selector>), the nearest box above it (not holding the victim) whose opaque fill covers at least half of the victim's box. The surface climb looks inside a display: inline box with element children whatever its own rect (an in an inline). The pixel walk answers unresolved (text clipped at point) at a point where the text is not in the elementsFromPoint stack, does not ignore pointer events, and lies outside the rect of an ancestor that clips its overflow. low-contrast is not reported on a disabled control ([disabled], aria-disabled="true", itself or an ancestor) in either engine. first-viewport-column-overflow does not measure the content of a closed (outside its), and leaves out a column of three or more painted links that hold nine tenths of its text (hidden links and their text left out of both counts) at 40 characters or fewer on average, as it leaves out a navigation rail. A generic block at 24px or larger (LEADING_DISPLAY_TYPE_PX) is not prose for line-length and body-text-viewport-edge.
  • What paints (observations-47 rows 2, 13 and 22). text-overflow reports no spill from a box that generates a box, clips on y (overflow-y, else the shorthand's second or only value, at hidden, or at clip with an overflow-clip-margin of 0 or unrecorded), is drawn at its layout size (its rect's height within 1px of clientHeight plus its top and bottom borders) and whose own text rect and every painted descendant rect lie wholly above or below its padding box (top border plus clientHeight), when no descendant carries unmeasured generated content and each of its own unmeasured ::before and ::after generates one quoted string holding a single character that is not a letter, digit, space or control character, optionally followed by a variation selector (an icon glyph), at a recorded font-size no larger than the box's clientWidth and with no transform or scale of its own. The snapshot records overflowClipMargin, and fontSize for pseudo-elements, from this capture on; an older capture's clip box counts as clipping at 0, and its unmeasured ::before or ::after keeps the spill. cramped-padding's flush form skips a text candidate whose computed font-size parses under 1px, and text exactly the land threshold off an edge lands only where an edge is drawn into the box on that side: a border (a width over 0 in a colour that is not transparent), a visible inset box-shadow layer, drawn on each side to the depth of its spread moved by its offset (spread plus y on top, minus x on the right, minus y on the bottom, plus x on the left) where that is over 0, or a visible outline with a negative outline-offset; a side with no recorded border width or colour, or a box with no recorded box-shadow or outline-offset, lands as before. em-dash-overuse counts -- only when the run of hyphens is exactly two long and a non-space follows, and --- only between two letters or digits, in both engines and the source-file matcher.
  • Nothing a visitor can see (observations-47 branch 1). A face under backface-visibility: hidden is turned away when the normal of the product of its own and every ancestor's linear transform (the third row of its inverse, Chromium's cofactor33 * det sign) points away by more than 0.1 of its length (0.3 under an ancestor that sets perspective); a second matrix in the chain with m33 below 0, a chain deeper than 256, an unparsed transform, a perspective term or an individual rotate or scale above keeps it. flat-type-hierarchy skips headings in a 1px box clip or clip-path: inset() removes. text-occlusion's covered text needs the Text gate's visible share (25% on the x axis), and an occluder that sets the victim's leading words from the same text origin (within 1px) with every one of fontFamily, fontSize, fontWeight, fontStyle, fontStretch, fontVariant, fontVariantCaps, fontFeatureSettings, letterSpacing, wordSpacing and textTransform recorded and equal (and, when the occluder's text wraps, lineHeight, textAlign, whiteSpace, wordBreak and hyphens too, since they move its later lines), and with no opaque fill or border of its own, is an overprint, not a collision; the snapshot records fontStretch, fontFeatureSettings and wordSpacing from this capture on, and older captures never overprint. side-tab's page form is paint-gated like bounce-easing's. cream-palette (browser) does not report a cream body when opaque, image-free, in-flow boxes spanning at least 95% of the body's width over the body (looked through transparent boxes to level 3) cover 95% of the page height, the colour covering the most height is neither cream nor near-cream (each channel 209 or more, red over green over blue, red at least 2 over blue), and no full-width box to level 8 paints a strict cream fill. radial-spotlight-glow scales the glow's opacity by 1 - opacity of each later sibling <video poster> the capture saw at a readyState of 2 or more, or complete , that covers it (the poster or image a JPEG, by a path ending in `.jpg`, `.jpeg`, `.jpe`, `.jfif`, `.pjpeg` or `.pjp` before any query or fragment, or a `data:image/jpeg` URI; any other format, or a URL naming none, may be transparent); the snapshot records a video's `readyState` from this capture on, and older captures never count a video, paints above it and fits by `cover` or `fill`. `content-hidden-at-rest` leaves out a `position: fixed` box at `visibility: hidden` covering the viewport that is not and holds no `main`, `[role="main"]` or `h1` and less than half of the body's text. The Text gate cuts a fixed layer's text at the viewport's sides. Below the fold, text whose parent is an avatar-shaped box (at most 160px each way, or text of at most three characters) is covered when a later sibling holds a complete JPEG (as above) matching that box within 3px whose box, cut to the overflow clip of every box between it and the sibling, covers the text, with the picture and every box between it and the sibling at an opacity of 0.95 or more and none of them setting a z-index. Both of these covers follow CSS order in a flex or grid parent: a positioned sibling over an unpositioned box paints above it, an absolutely positioned child counts as order: 0, any other child needs its order recorded, and a sibling ordered before the box covers nothing; the snapshot records order from this capture on. body-text-viewport-edge skips text in a box (or ancestor) where the capture saw a running animation or transition move it on the x axis (left, right, margin-left, margin-right, inset-inline*, or a transform or translate with an x offset of 1px or more) and either a transition naming that property or CSS animations whose keyframes set it, every one finite (a positive iteration count), on the document timeline and not paused, trace the move; an animation whose keyframes the capture could not read keeps the box where it was measured. buried-raster takes a raster for a state layer when an ancestor is below full opacity, displaced, declares a transition naming opacity (not all), and either runs an opacity animation the capture saw or sits at an opacity off the 0.01 grid.
  • Surfaces off the ancestor chain. Every low-contrast verdict, not only the SAFE_TAGS path's, also asks the structural layer climb (impeccable_core::browser::visual::layer_under_text), which answers below the fold and through layers with pointer-events: none, which elementsFromPoint never lists. Besides pictures and fills, the climb reads a gradient that paints a surface on a box that is nobody's ancestor (not a dot grid, hairline, small cell, mask, a wash at alpha times opacity of 0.1 or less, or a box at opacity 0.3 or less) and an SVG shape drawn around the text (at most three times the text box plus 16px on each axis) as paint the walk never read; an ancestor painting an opaque gradient ends the climb as its fill does. A positioned ::before or ::after is the surface only where its box, placed from its containing block, pixel offsets, size and transform (a rotation, scale or skew as the bounds of the transformed box about its centre), covers the text; one it cannot place keeps the size test. A pseudo-element or box at a negative z-index is skipped where an opaque fill or gradient lies between it and its stacking context (the host's own fill included, unless the host opens that context): an offset shadow behind a white card, a -z-10 layer inside a white section that is not isolate. Paint the capture cannot place for certain (an unplaced pseudo, a pseudo with no recorded z-index or a negative layer with no recorded isolation over such a fill) is read as before but decides no verdict of its own: the verdict stands outside the SAFE_TAGS path, nothing is reprinted against it, and dark-glow ignores it. The snapshot records isolation, and zIndex and translate for pseudo-elements. Outside the SAFE_TAGS path the climb's own finding counts where the stacks cannot answer (below the fold, a replay that never asked), already see unread paint, or confirm the walk only because the layer ignores pointer events or is an SVG shape. That paint is read for the surfaces it can make over the ground the walk read (unread_verdict): the climb is asked again past each translucent layer, up to four, until it reaches paint that hides what is beneath or the walk's ground; the walk's own translucent layers are placed over or under that paint by the box each hangs from. A verdict that fails on every surface in that span stands, also where the stacks see unread paint, and prints N:1 (need T:1) — text #ink on #surface (layer on ) against the surface it reads best on when the walk named a flat colour more than 24 away from the span and the span's colours are known (fills and gradients); a verdict that passes on every one is dropped; one that depends on what the paint shows (a photo, unknown SVG fill) stands outside the SAFE_TAGS path, and the SAFE_TAGS path waives it as before. Outlined text (a -webkit-text-stroke wider than 0 in a colour of its own, or two or more opaque text-shadow layers blurred at most 2px and offset in opposing directions) keeps its element verdict. The snapshot records webkitTextStrokeColor and webkitTextStrokeWidth. dark-glow's "on dark background" form reads an opaque detached fill or gradient under the element's box as its surface; a picture or translucent layer leaves the claim as the walk made it.
  • Text the element pass hands over. collect_visual_contrast_candidates takes maxRoutedCandidates (0 unless given; the URL engine passes 12, after its 12 maxCandidates, whose candidates are unchanged): text over unread paint whose verdict depends on the paint, ink in exactly the walk's surface colour over unread paint, links and spans with no fill among them, and outlined text, in document order. They carry routed (unread layer or text outline) and those reasons, which the sampled pass refuses; a first-budget candidate the element pass hands over carries routed only (and preferRenderedForeground: true for an outline). The URL engine takes a routed candidate to the screenshot pass even where the element pass reported on its selector, and where the pixels give a verdict, pass or fail, drops the element pass's low-contrast finding on that selector. Those extra reads stop after 4 seconds or 4 slow reads in a row with no verdict. Because the pixels can drop it, every element-pass low-contrast verdict on text routed_reason hands over (decided in the rule pass's recorded hit-test rounds) carries the visual-contrast origin in the evidence, where it stands when the pixels give none, and replay_url_scan leaves it out: the scan origin stays what a replay of the recorded capture reproduces. The CLI's findings and their order are unchanged. A verdict that stands because the pixels gave none (the routed reads were spent, the read was refused for a blocked reason such as backdrop-filter, the candidate never reached a slot, or the two shots differed) reports with severity: 'advisory' and its text unchanged (corpus decision r6-t5-unread-pixel-verdicts; settle_handed_over in crates/browser/src/lib.rs). The screenshot flow's hide style also clears -webkit-text-stroke-color, and fill and stroke on SVG text and tspan. In the stack walk a picture faded by its own box or a wrapper (below the nearest box that also holds the text) is composited at that opacity, and a picture that cannot be read (a tainted image, a refused video frame) ends the walk. overlaps_page_width measures against the root's scroll width when the document is wider than the window.
  • Element identity. A finding from the rule pass or the visual-contrast pass carries selector (after ignoreValue): the flagged group's generated selector (body / html for page-level groups), or the visual-contrast candidate's selector. content-hidden-at-rest and script-error findings have none.
  • Where a script error was thrown. A script-error snippet is the message followed by (at ): <function>, :<line>:<column> from the top stack frame, or :<line>:<column> for an anonymous frame or a script with no stack (a syntax error carries only the script position). A frame in a script with no URL (code from eval or new Function, a script element given text rather than a src) prints V8's name for it, <anonymous>, in the URL's place: (at eval, <anonymous>:3:1). Line and column are 1-based (CDP's are 0-based); a URL past 160 characters is cut to 160 plus ...; a throw with neither a named script nor a frame gets no suffix. The suffix is added after deduping, from the first occurrence. The JSON shape is unchanged: the source travels in snippet.
  • One message shape. Every script-error message reads the way the console prints it, Uncaught <Type>: <message>, whatever path the throw took, where the JS printed puppeteer's err.message with the type stripped on one path and CDP's typed text on another. CDP's marker comes first: Uncaught, or Uncaught (in promise) for an unhandled rejection. An Error reads the first line of its description, which names its type (TypeError: ..., or the name a library gave it, ChunkLoadError: ...); a description that names no type gets the class in front, and an empty message is the type alone (Uncaught AbortError). A thrown value that is not an Error (CDP type: object with no subtype: a plain object, a class instance, a rejected object) reads its class and V8's property preview, Uncaught Object {code: "E_CONFIG", message: "config missing"} (strings JSON-quoted, other values as previewed, ... when the preview overflowed). A primitive reads as String(value), Uncaught boom. A throw that arrives with no exception object (a cross-origin script) keeps CDP's text, which is typed already (Uncaught TypeError: ..., or Uncaught [object Object]). The body after the marker is its first line, trimmed, and the message after its type (TypeError: ) is cut at 160 characters, the cut the JS applied to the untyped message, so naming the type costs the message nothing it showed before; a throw whose body is empty reports nothing.
  • React invariants read as their message. A production React build throws Minified React error #<n>; visit for the full message or use the non-minified dev environment for full errors and additional helpful warnings. For a common invariant number the boilerplate from ; visit on is replaced by the message React's error decoder prints, the number kept: Uncaught Error: Minified React error #418: Hydration failed because the initial UI does not match what was rendered on the server. The table (REACT_INVARIANTS in crates/browser/src/cdp.rs) covers 31, 130, 185, 300, 301, 310, 321, 418, 419, 421, 422, 423, 425 and 426. The message is added after the 160-character cut, so it is never cut. A number the table does not know, text after the number other than ; visit , and any message that is not an invariant stay as they were. Deduping compares the decoded messages, so both reports of one invariant still share a key.
  • One throw, one report. Deduping compares messages with the (in promise) marker read as a plain Uncaught, so a throw that surfaces both synchronously and as an unhandled rejection (a consent manager's patched document.createElement called from a script and from a promise) reports once, with the first report's text and source. Messages that differ in anything else stay separate. The three-error cap applies after deduping, and after classing (next item): counted errors and advisory ad-tech errors are capped at three each, in arrival order, so ad-tech errors never take a slot a counted error needs. Three failing ad scripts ahead of the site's own broken bundle still leave the bundle's error reported as error; a scan reports at most six script errors.
  • Ad-tech script errors are advisory and name the vendor (corpus decision r3-31-script-error-ad-tech). A script error thrown from a known ad-tech script (its source URL contains anymind360.com (AnyMind), a script file name beginning prebid, wherever it is hosted (Prebid), connect.facebook.net (Meta Pixel), googletagmanager.com (Google Tag Manager), cookielaw.org (OneTrust, the consent layer that holds ad tags back), or googlesyndication.com / doubleclick.net / googleadservices.com (Google Ads), nagich.co.il (Nagich, an accessibility overlay), or asset.chase.com/web/library/digddsautomation/reportingjs/ (Chase Reporting, a shared reporting tag)), or whose message names an ad API (browsingTopics, joinAdInterestGroup, runAdAuction (vendor ad tech), adsbygoogle (Google Ads), _prebidjs (Prebid)), reports with severity: 'advisory', its snippet ends (third-party: <vendor>), and it carries thirdParty: "<vendor>" after ignoreValue. The source is checked first. Product analytics and a site's own bundles and chunks (ad code served from the site's own host included) are not on the list and stay error. The list lives in crates/core/src/third_party.rs and holds only vendors the corpus has evidence for.
  • React's recoverable hydration errors are advisory (corpus decision r5-p13-script-error-hydration). A script error whose message is Minified React error #<n> with <n> one of 418, 419, 422, 423 or 425, decoded or in the build's own ; visit form, reports with severity: 'advisory': React renders the page again on the client and the page shows complete. Its snippet is unchanged and it carries no thirdParty. Every other error stays error, other React invariants included (#185, #421, any number outside the five). The three caps are separate: at most 3 counted errors, 3 ad-tech errors and 3 hydration errors per scan, so a hydration chain never takes the slot a first-party error needs. The ad-tech check runs first. The list lives in crates/core/src/script_errors.rs.
  • Closed interface is left out of content-hidden-at-rest (corpus decision r5-p5-content-hidden-closed-navigation). The measure already skipped display: none, the hidden attribute, aria-hidden="true", content-visibility: hidden and dialog. It now also skips, from both the hidden count and the page total, every subtree that starts at a box which is itself at opacity 0.02 or less or visibility: hidden | collapse and is closed interface by any one of: (1) the box or an ancestor is a nav or has role navigation, menu or menubar; (2) the box or an ancestor has the inert attribute; (3) the box or an ancestor has an id that an [aria-controls] element names while saying aria-expanded="false" or aria-selected="false", and no element naming that id says true; (4) the box itself has role dialog, alertdialog or tabpanel; (5) the box itself has a class token whose words (split at non-alphanumerics and lower-to-upper steps) include offcanvas, drawer, megamenu, submenu, dropdown, flyout, modal, tabpanel or tabpane, the pairs off canvas, mega menu or sub menu, or one of tab / tabs / accordion together with one of content / panel / pane / body; (6) the element just before the box says aria-expanded="false", or that element is a heading (h1 to h6, role="heading") or has a single element child and its first element child says it (an accordion heading wrapping its button; a site header that opens with a closed menu button says nothing about the box after it); (7) the box itself is position: fixed with area and wholly left or right of the viewport. A box none of these describe counts as before: an in-flow section a scroll reveal never showed, a hover overlay, a carousel slide, an unmarked panel. A bare menu, tab, panel or popup class is not enough. The thresholds and the snippet are unchanged. The predicate is closed_container in crates/core/src/browser/page_checks.rs.
  • Scroll-linked reveals and sliders that never started (corpus decision r6-t6-hidden-scroll-linked). The share is measured with the page back at the top after the reveal sweep, so a reveal that follows the scroll position is at 0 again when it is read. When the counts would report, the URL engine asks the hidden boxes that hold the most text (at most 8, SCROLL_PROBE_MAX) whether they show once the page is scrolled to them: it scrolls each box's centre to the viewport's centre (for a box inside a position: sticky stage, through the stage's parent in half-viewport steps, at most 12), waits up to four frames at each stop for its opacity to pass 0.02 with visibility not hidden / collapse, then scrolls back to the top and waits 700ms, all within 5 seconds. A box that showed is a scroll-linked reveal: its text stays in the page total and leaves the hidden count. The answers are recorded in the capture's facts (shownOnScroll: [{ el, shown }], omitted when empty), so replay_url_scan measures what the live scan measured; a recording without them, and any DOM with no page behind it (the extension, the static engine), counts every such box as hidden, as before. Separately, a hidden box in a slider that never started leaves both counts: the box or one of its six nearest ancestors has a class token whose words include slider, carousel, swiper, slick, splide, glide, flickity, slideshow or revslider and none of slide, item, cell, card or pane (so swiper-wrapper is a slider and swiper-slide is one of its slides), and no element in that slider shows text (every one is visibility: hidden | collapse, or sits under a display: none, aria-hidden="true" or opacity 0.02 or less box within the slider). A slider showing its current slide is not this, and its waiting slides count as before. When such sliders hold 150 characters or more, text mode prints the note Capture note: <n> chars of text on sit in sliders that never started (every slide hidden, e.g. "<first 40 chars>"), so content-hidden-at-rest left them out. The page may not have finished loading; scan it again to check that text. It is not a finding, does not change the exit code and blocks nothing; the evidence API records the same lines in Evidence.capture_notes and a replay in ReplayOutcome.capture_notes. measureHiddenTextDOM()'s JSON gains unstartedSliderChars and unstartedSliderSamples only when they are non-zero.
  • Findings on third-party widget markup name the vendor (corpus decision r4-p24-third-party-widget-markup). A finding whose element is a known widget vendor's markup keeps its severity; its snippet ends (third-party: <vendor>) and it carries thirdParty: "<vendor>" (after selector). Taboola owns its whole feed: an element with an id starting taboola- or internal_trc_, a class starting trc_rbox, or the class trc_related_container, and everything under it. Swiper owns only its structural elements: the element itself has the class swiper, swiper-container, swiper-wrapper or swiper-slide, or an id starting swiper-wrapper-; the site's content inside a slide is the site's. Slick owns its structural elements the same way (the class slick-slider, slick-list, slick-track, slick-slide or slick-arrow) and its whole dot list (the class slick-dots and everything under it); SuperSlide owns its tempWrap; react-fast-marquee owns everything under an element with a class starting rfm-; Kaltura owns everything under a class starting playkit- or the class kaltura-player or kaltura-player-container. The rule pass tags in serialize_findings (so the in-page bundle and the extension see it too), the visual-contrast pass by its selector's first match. Page-level findings are never tagged. The static engine does not tag.
  • Purple headings in the brand hue (corpus decision r3-23-ai-color-palette-brand-hue). The heading forms of ai-color-palette (a snippet ending on heading) do not report when the heading's computed color is within 12 degrees of hue of a brand surface on the same page: the solid background-color (alpha at least 0.9, chroma at least 50, no gradient painted over it) of the logo (an element whose id, class, alt or aria-label contains logo; its text colour too, read from the first element in it with text of its own, so a type logo set in a child span counts), the nav bar (nav, header, role=navigation|banner, at least half the viewport wide), neither inside main or an article (an article's own header, a pagination nav and a row of partner logos are local chrome), or a band across the page (at least 90% of the viewport's width) covering a fifth of the viewport's area or more. Headings are never brand surfaces, and the gradient and neon forms keep reporting: purple that shows up only in headings and gradients is the tell. URL engine only (the static engine has no rendered page to read surfaces from).
  • Category colours (corpus decision r5-p28-ai-color-palette-category-colours). An element-level ai-color-palette finding does not report when its element wears the colour as one of a category system's hues: the elements in the same role on the page carry six or more distinct hues between them, at least half of them outside the violet (260 to 310 degrees) and cyan (170 to 197 degrees) bands, read by hue alone. For the ink forms ( on heading, neon text on dark background) the role is the tag plus the computed font-size and font-weight, and an element's hue is its computed color (alpha at least 0.5, chroma at least 50). For the fill forms ( gradient background, Purple/violet gradient (Tailwind)) the role is the tag plus the rounded box size, and the hue is the first chromatic stop of the computed background-image gradient. Two hues less than 5 degrees apart count once. Such an element does not vote in the two-hue ink gate either. The page-level Purple/violet accent colors detected is unaffected. URL engine only (the static engine reads no rendered roles and reports as before).
  • The cyan band (corpus decision r6-t7-cyan-band). The element-level ai-color-palette forms ( gradient background, neon text on dark background) read a colour as cyan when its hue is 170 to 197 degrees and its HSL saturation is at least 0.4; the violet band (260 to 310 degrees) has no saturation floor. Emerald (160 to 164), sky (198 to 200) and a grayed teal no longer count as cyan, for the finding or for the two-hue ink gate. URL engine only (the static engine has no cyan form).
  • Footer column titles (corpus decision r5-p29-skipped-heading-footer-titles; static HTML engine and URL engine alike). skipped-heading does not report a skip into the footer: the skipped heading is inside footer, [role="contentinfo"] or #footer, and the heading it follows is either outside that footer (the last heading before it) or that footer's first heading when that heading did not itself skip into the footer (a closing call to action inside the footer; a first heading that skipped in is a column title). A skip between two later footer headings reports, and so does every skip outside a footer. A footer built from unmarked divs is not recognised and reports as before.
  • Contrast ratios in snippets. Every low-contrast producer (the element text path shared by both engines, which covers links, spans and placeholders, the static engine's :hover state, and the URL engine's browser contrast sampling and pixel contrast passes, verdict and median) prints a ratio against its threshold: one decimal; two when one decimal would round a failing ratio up to the threshold; and those two cut, not rounded, when rounding them would reach it too. A ratio under the bar never prints as the bar: 4.49:1 (need 4.5:1), never 4.5:1 or 4.50:1. A ratio at or above the threshold, such as a median over it, prints one decimal.
  • Page validity gate. After goto (and settle), before injecting anything, the engine classifies the page (crates/browser/src/validity.rs) from the main document's final CDP response and an in-page probe (title, visible text length, final URL, challenge-widget markers). Challenge: an x-amzn-waf-action header, cf-mitigated: challenge, a final URL on a challenge-only host (perfdrive.com, captcha-delivery.com), or, on a page with at most 3000 characters of visible text, a challenge title prefix ("Just a moment", "Attention Required! | Cloudflare", "Human Verification", "Access Denied", "Radware Bot Manager", "Captcha", ...) or a full-page widget marker (Cloudflare challenge form, PerimeterX, DataDome, Imperva, Akamai, AWS WAF, slider captchas). On a page of any size, a bot manager's challenge sheet laid over the rendered page is a challenge too: HUMAN Security's (PerimeterX's) "Press & hold" check, #px-captcha-modal or #px-captcha-wrapper, while it is showing (not display: none, not visibility: hidden, opacity over 0.02) and covers at least half the viewport; the signal reads overlay human-press-and-hold, and the probe records overlays only when one shows. HTTP error: a final status >= 400 with no challenge signal. A blocked page throws the page is a bot challenge, not the site (<signals>). Findings would describe the challenge page, so none are reported. or the page returned an error (HTTP <status>). Findings would describe the error page, so none are reported., which the CLI prints as Error: ... and counts as an operational failure (exit 1). A file:// load has no response, so only the probe signals apply.
    Consent wall: a page where a known consent manager (next item) is showing (its text counted with the text of open shadow roots under its roots, where Usercentrics renders), hiding it would leave next to nothing (fewer than 20 visible characters outside its roots, and no visible form control (input other than hidden, select, textarea, button) and no img, svg, video, canvas, iframe, object or embed of 10,000 square pixels or more outside them), and the manager holds at least 100 characters or a frame of 10,000 square pixels or more (a message drawn in an iframe, whose text the page cannot read). For this test, text of the manager's that body.innerText does not see (rendered in a shadow root, or in a root appended outside ``) is added to the page's visible-text count too (consentShadowChars), so the two counts describe the same text; the challenge checks keep the page's own count. It throws the page is a consent wall, not the site (consent manager <names>, <n> of <total> visible characters outside it, no control or image outside it). Findings would describe the consent dialog, so none are reported. A short page under an ordinary banner (a sign-in form, a splash page with a button, an image-first page) is scanned. The probe runs before any banner is hidden, and again in the same evaluation as each later hide pass (after the reveal sweep, right after the capture, and after the content-hidden-at-rest scroll probe when it scrolled the page), whenever a manager's root is in the page, with the earlier hide rules switched off and its inline hides lifted for that read (an inline hide the manager has since replaced with its own display, or with the same display: none !important written by rewriting its style attribute, stays as the manager set it), so a wall that arrives after load, fills a root that was an empty stub, or arrives during the capture or the scroll probe is refused too (the evidence then carries that later probe). A manager's box is showing when it has a size and paints (checkVisibility with opacity and visibility), and is not parked out of sight: a fixed box wholly outside the viewport (unless a transformed, filtered or contained ancestor holds it), a box wholly above or beside the document, or a box an ancestor's overflow clips away. Controls and media outside the roots are counted in the page's open shadow roots at any depth, nested web components included. With --no-consent-hiding the gate is off and the page is scanned with its banner, which is what that flag asks for. The probe object (evidence) carries consent (the names of the managers showing), consentChars (visible characters inside them) and consentOutside (visible controls and sizable media outside them, counted up to 20).
  • Consent banners (Rust engine). A consent banner covers copy a visitor reads once they dismiss it: text under it was skipped as covered or scored against the banner, and the banner's own text was scored as the site's. After the validity gate, again after the reveal sweep (so a banner injected after load or on the first scroll is caught before the capture), once more right after the capture (when that pass changes the page, the page is captured again, so the capture, the live hit tests and the pixel reads agree), and after the content-hidden-at-rest scroll probe when it scrolled the page (so a banner that scrolling injects is off the page for the pixel pass; the capture already read stands), the engine hides the roots and backdrops of the consent managers in crates/browser/src/consent.rs: OneTrust, Cookiebot, Usercentrics, TrustArc, Didomi, Quantcast Choice, Sourcepoint, Osano, the open-source Cookie Consent library, CookieYes, Complianz, iubenda, Termly, Axeptio, Borlabs Cookie (its box, its floating #BorlabsCookieWidget and its #BorlabsDialogBackdrop), Klaro, Cookie Notice, Shopify's privacy banner, consentmanager (#cmpwrapper, the host of the open shadow root its box renders in, and #cmpbox), Tealium (#__tealiumGDPRecModal, its consent prompt, and #__tealiumGDPRcpPrefs, its preference center), Transcend (#transcend-consent-manager, the zero-size host of the open shadow root its banner renders in), and Google Funding Choices. Selectors are the vendor's own ids and classes, never a generic word, so a notice a site wrote for itself stays on the page and is scanned. Hiding is one injected <style id="impeccable-consent-hide"> of display: none !important rules (plus an inline display: none !important on a matched element whose own inline style outranks the rule); nothing is clicked and no cookie or consent state is set. The scroll lock is undone only where the manager applied it: its own lock classes on <html> / (Didomi `didomi-popup-open`, Sourcepoint `sp-message-open`) are removed, the `aria-hidden="true"` a manager put on the page behind its dialog is removed from exactly the elements it marked (Borlabs Cookie marks them `data-borlabs-cookie-aria-hidden`; reported in `unlocked` as `aria-hidden [<mark>]`), and an inline `overflow` / `overflow-y: hidden` on `<html>` or is removed only while that manager's backdrop was showing the page is not an app shell (an element outside the managers at least half the viewport tall that scrolls itself with overflow-y: auto / scroll, whose body lock is the site's own), and no modal of the site's own (dialog[open], [aria-modal="true"], [role="dialog"], [role="alertdialog"] outside the managers) is showing, since that modal may hold the lock. Every hide pass is best-effort: one that fails hides nothing and does not fail the scan. Every pass, the hit tests, and the evidence screenshot see the page without the banner (a last hide runs before the screenshot). Findings from a scan that hid a showing banner carry consentHidden: ["<name>", ...] (after thirdParty), and text mode prints the note above. --no-consent-hiding turns all of it off. The evidence API (detect_url_evidence) leaves the findings untagged, so they replay equal, and records Evidence.consent: { hidden, matched: { <name>: [selectors] }, unlocked }. The static (file) engine is unaffected.
  • Tours and preloaders (Rust engine, crates/browser/src/overlays.rs). Right after the consent hide following the validity gate, the engine looks for a preloader still covering the page: a position: fixed layer other than html / body that covers at least 90% of the viewport, is what elementFromPoint returns (or contains it) at the center and at 20% / 80% of each axis (a layer with pointer-events: none is made hit-testable for that probe and put back), paints an opaque fill (alpha 0.9 or more) on itself or on a descendant covering as much, has at most 60 visible characters and no a[href], button, visible input, select, textarea, iframe, [role=button], dialog role, aria-modal=true, dialog or editable descendant, is not itself a dialog, and whose id or one of its classes names a loader (after trailing wrapper words such as wrapper, overlay, screen, bg, its last - / _ word is preloader, preload, preloading, loader, loading, pageloader, siteloader, loadingscreen or spinner). If one is there the engine polls every 250ms for up to 5s for it to go on its own, then hides whatever is left with an inline display: none !important and marks it data-impeccable-hidden="<name>" (<name> is the tag plus the naming id or class, div#preloader). Known product tours are hidden by their library's own markup with one injected <style id="impeccable-overlay-hide">: driver.js 1.x (.driver-popover, svg.driver-overlay), whose driver-active / driver-fade / driver-simple body classes (its stylesheet sets pointer-events: none under .driver-active, which hides the page from hit tests), highlight classes (driver-active-element, driver-no-interaction) and highlight aria (aria-controls="driver-popover-content" with aria-haspopup and aria-expanded) are removed too. Site-builder badges are hidden by the builder's own markup in the same style: Lovable's "Edit with Lovable" badge (#lovable-badge). The hide runs at the same points as the consent hide (after the validity gate, after the reveal sweep, after the capture with a recapture when it changed the page, after the scroll probe when it ran, before the screenshot) and is as best-effort. A gate the visitor answers, a site's own dialog, and any layer with controls or more text are left on the page. Findings from a scan that hid any carry overlaysHidden: [{ "kind": "tour" | "badge" | "preloader", "name": "<name>" }, ...] (tours, then badges, then preloaders, after consentHidden), and text mode prints the note above. consentHidden is unchanged and lists consent managers only. When a preloader is hidden, the scroll lock its page kept with it is undone too: a loader-named class on <html> or `` (is-loading) is removed, and so is an inline overflow / overflow-y: hidden on either unless a modal of the site's own is open or an app shell scrolls inside itself (either may hold that lock) (recorded in unlocked as body.is-loading, body style overflow). --no-overlay-hiding turns all of it off, the wait included. The evidence API leaves the findings untagged and records Evidence.overlays: { hidden: [{ kind, name }], matched: { <library or builder>: [selectors] }, unlocked, waitedMs } (waitedMs is 0 when no preloader was covering the page).
  • What the visual pass refuses to read. The JS reported whatever its sampling produced; the engine says nothing where the reading is not the text's own background. The candidate collector applies the element pass's text gates before a candidate takes one of the maxCandidates slots, is sampled, or is scrolled into view: text with no letter and no digit (◯, { }, /) as well as emoji-only text; a disabled control ([disabled], [aria-disabled="true"]); a computed font size under 1px; a color at alpha 0.02 or less, or a transparent -webkit-text-fill-color, unless the element clips its own background to its text; and an element the painted-at-capture predicate (crates/core/src/browser/painted.rs, text gate) says is not painted, such as a tab-strip cell past its clipping edge or a carousel slide parked beside the page. A background image read as a surface has to be under the text: an image drawn no-repeat (from the computed background shorthand's first layer) whose painted rect, at a background-size the capture can place (pixels, percentages, cover, or any size once the image's intrinsic size is loaded), covers neither the candidate's text box nor its own box (body and html are asked only about the text) ends the walk background image does not cover the text (stop), whether or not the pass could load the file. An icon sprite framing a count and a mark beside a button label are refused this way; a repeating tile and a placement the capture cannot state are read as before. In the stack walk (impeccable_core::browser::visual): a translucent surface no longer restarts the walk at its own parent (which re-entered the stack above the node it came from and composited that surface over itself until its alpha read as opaque, and which skipped siblings painted between the surface and that parent) — the walk keeps descending the one elementsFromPoint stack, collecting translucent surfaces until an opaque one grounds them, then composites them back in order (topmost surface still names the method, ...+alpha); a walk that reaches the end of the stack with nothing opaque is unresolved rather than reporting the last translucent color as a surface. A gradient answers analytically only when its stops agree: any stop below 0.95 alpha (a scrim, a glow, a from-x/10 wash composites differently at every point of the box) or two opaque stops more than 2× apart in contrast make it gradient stops disagree, and an svg in the stack makes it <tag> paint; both end the walk (stop) rather than letting the nodes under them answer for the text, so the candidate falls to the screenshot pass. In the screenshot flow: a candidate whose reasons include background-clip text, filter, or backdrop filter is refused before the two screenshots are taken; the verdict is the median over the glyph cores (channel delta ≥ 90% of the strongest delta in the box, ≥ 8 of them; when fewer than 8 pixels reach 90%, as on small or thin text, the pixels from 75% up) rather than the tenth percentile over every changed pixel, which antialiased edges drive to 1:1; and the pass reports nothing when the diff is not a glyph over its background — more than 55% of the clip changed (the page repainted), more than a quarter of the changed pixels moved the opposite way from the rest (text mid-animation leaves its old position and its new one in the same diff), most fully painted pixels are not the color the text declares (preferRenderedForeground aside, where the painted value is the claim), the surface under the glyphs stands 2:1 or further from the surface beside them in the same box (the page paints its own text twice, so hiding one copy leaves the other where the glyphs were), or the median of every measured pixel is more than 3× the verdict (the sample is two populations, not one surface). The snippet shape is unchanged. median in it is the median over the same glyph cores the verdict reads, so it prints the verdict's number and never reads below it (it used to be the median over every changed pixel, edges included, which printed verdicts above their own median such as pixel contrast 3.5:1 median 1.7:1). The median over every changed pixel still decides the bimodal refusal above, but it is not printed.
  • Viewport edges and overflow. body-text-viewport-edge reports a gutter under 16px, or under 12px when innerWidth is 480px or less. A paragraph whose measured text runs past a side of the viewport (the distance rounds below 0) reports no gutter on that side; it still reports a gutter from 0px to the floor on the other side ((left 8px)). Those paragraphs, through the same gates plus the Text paint gate and inline ignores, report once per page instead: one body-text-viewport-edge finding attributed to the page (selector body, in pageLevel) on the side the furthest text reaches. The message follows what the page does. It reads text runs past the <side> edge of the <vw>px viewport and is cut off: <name> reaches <d>px past it, with text in <n> block(s) when the text is cut off: the viewport clips x overflow (the root's overflow-x, or body's when the root's is visible, at hidden or clip), the side is not the one the page scrolls to (right, or left under direction: rtl), the root's recorded scrollWidth does not exceed its clientWidth by more than 1px, or for every paragraph on that side a box at overflow-x: hidden or clip (the paragraph or an ancestor below the body, with its own edge on that side inside the viewport) is passed by the text. <name> is then the box reaching furthest among the paragraphs and their ancestors. Otherwise it reads page scrolls sideways at <vw>px: <name> reaches <d>px past the <side> edge, and text in <n> block(s) runs past it, where <name> is the box reaching furthest past that side among those no ancestor below the root clips or scrolls on x and not position: fixed, and no further than the page scrolls (ties go to the outer box). When the engine cannot tell (nothing it can see clips the text and the root recorded no scrollWidth) the sideways wording stands and <name> is the box reaching furthest among the paragraphs and their ancestors. In both wordings the paragraph itself is named when its text reaches further than any such box. <name> is the element's class_selector, except that a div with no class is named div#, else div in <tag># or div in <tag>.<class> (at most three classes) after its nearest ancestor below the body with an id or a class, else div ("<text>") with up to 40 characters of its text, cut at a word and ended with … when cut, double quotes in the text written as '. text-overflow reports a spill only when it does harm: a box at overflow-x: hidden or clip (the element itself or an ancestor below the body, with area) is passed by the spill's reach, the spill reaches within a quarter em of the viewport's side or past it, or the spilled part comes within a quarter em of another element's text or painted box on the element's lines (not an ancestor or descendant, not a box that holds the element's whole box, and not a decoration layer: an absolutely or fixed positioned box with no text, other than a replaced element or an svg, that is 2px thick or less or paints only a plain fill, with no background image or border, at alpha times opacity under 0.25). The reach is the painted extent, or the scroll extent where that is taken as read; text that runs past its box into free space reports nothing.
  • Round 7 recall and gates (corpus run 28). line-length and body-text-viewport-edge (its element and page-level forms) also measure prose written straight into a generic block: a div, section, article, aside or main laid out as block or flow-root, with more than 10 characters of its own text, only phrasing inside it, not set white-space: pre*, and outside any link, button, label, summary, select, textarea, button-, link-, tab-, menuitem- or option-role element and editable field; it is measured on its text runs only (where those cannot be measured it is not taken for a paragraph), and the edge snippet names it ( with 228-char body ...). The label collectors read the element that holds a label's text: its own text, else the one child whose text is not empty, at most three levels down, so a chip with an icon beside its text span is read through the span; hero-eyebrow-chip reads its sibling that way too, and its tracked-caps floor is 1.6px or 0.08em of the label's size; under 1.6px a label that is or holds a time element, or that names a year (1900 to 2099 as a word), is a dated meta line and not tracked caps (the recorded JS vectors pin the fixed floor alone). kicker-above-heading hands a label over a 48px-or-larger h1 to the hero rule at 1.6px, or, when the label is the h1's own previous sibling at 14px or less, at 0.08em where hero-eyebrow-chip reports that label (it does not read small-caps as capitals and passes over a dated line, so such a label stays a kicker; the static engine: at 14px or less). A card-context ancestor (article, li, a, button, ...) more than two viewports tall holds the page and is not a card for the kicker and numbered-label collectors. icon-tile-stack anchors on a card title set on a div or span too: laid out as a block, with no element children, 2 to 80 characters of its own text, weight 600 or more at 16px or more, outside any heading, link, button or label; it reads an oklab() or other modern tile fill. tiny-text skips a label typed in capitals (all its letters capitals, at most 40 letters, one line) and a run in a monospace face with white-space: pre*. wide-tracking counts a caps label's letters, not its characters, toward its 40-letter gate, and skips a one-line link or button label of at most 40 letters. The element contrast pass scores a box under 10px tall when it holds a line of its own text at 8px or more and is at least 0.9 of the font size tall. ai-color-palette's gradient form skips a box whose gradient, sampled at nine points over the box from its computed size and position, shows one colour (every sample within 12 levels on each channel); an element reports the rule once: the computed gradient form stands for the utility-class gradient form, the computed purple-heading form for the class form (text-purple-600 on heading), and gradient-text on the element for both gradient forms. gradient-text skips a ramp whose strongest stop, times the element's own opacity, is under 0.15, and its stylesheet form does not stand when every element computing a clipped gradient is unpainted or under that floor. gpt-thin-border-wide-shadow reads, under one gradient ancestor with no picture, each of its stops composited over the fills below: a halo that shows over at most half of them does not count. dark-glow's surface lift counts only layers carrying at least half the strength floor (1.5px of light), and its stylesheet form with no selector does not stand when an element's computed shadow carries the declaration: the element form read that element.
  • Round 8 text and CSS-text forms (corpus run 35). line-length divides the characters that reached the element's rendered lines, not the UTF-16 length of its textContent: the text of a style, script, noscript or template descendant and of a display: none one is left out, runs of collapsible white space (space, tab, line feed, carriage return, form feed) count once and none at either end unless the element computes white-space: pre, pre-wrap or break-spaces, and combining marks (Unicode M*) and format characters (Cf) are not counted. The gate that decides whether the element is long enough to measure still reads the raw length. overused-font (URL engine) keeps its element-count decision and snippet, and stands down when the face it would name sets under 5% of the characters in text that has a box (each element in its selector list weighs the characters of its own text nodes, white space collapsed; text that is or sits under hidden, display: none, visibility: hidden or collapse, or content-visibility: hidden is not weighed, opacity is not read); with no such text the element count stands; the static engine's form is unchanged. side-tab: the stylesheet scan for pseudo-element stripes (both engines) skips a stripe whose background has a url() layer and no token that parses as a colour or is a var(); in the URL engine the stylesheet form does not stand when an element its selector resolves to already carries the element form for the same pseudo-element. marquee (URL engine): the stylesheet form stands only when an element its selector resolves to carries something to read or look at: text, an img, picture, video, canvas, iframe, object, embed or marquee element (itself or inside it), an svg, image or use inside it, a url() background on it or under it, or generated content that is not empty; a selector that resolves to nothing stands as before. bounce-easing by animation name (both engines, element and stylesheet forms; the class and cubic-bezier forms are unchanged): the name does not report when the keyframes for every bounce-named animation are readable (the page's @keyframes in the URL engine's element form, the stylesheet text elsewhere) and only pulse: every declaration is opacity, a transform made only of scale*() functions with factors from 0 to 1 (or none), a scale with factors from 0 to 1, or an animation-timing-function with no linear(), no var() and no cubic-bezier whose y values leave 0 to 1. Any other property or value, an empty set of keyframes, or keyframes that cannot be found keeps the finding. The stylesheet form reads on past a pulse to the next declaration that names a bounce.
  • Round 10 contrast surfaces (corpus run 47; URL engine unless noted). A box at an opacity of 0.02 or less that a scroll or view timeline holds there (its computed animation-timeline is scroll(), view() or a named timeline, an animation moving its opacity was running at capture, and it is the box's only animation that sets opacity) counts at the opacity its end keyframe sets (the first keyframe for reverse) in low-contrast's opacity gate and fold and wherever the painted-at-capture predicate counts an element's own opacity: the Text and Box paint gates, painted_at_capture (and the page checks that ask it), the text-box test and the shown-across test behind the colour-pair claim (content-hidden-at-rest is ungated and unchanged); a composition other than replace, a direction other than normal or reverse, or an end keyframe that sets no opacity keeps the captured value. A filter on the box that paints the text's surface, or on a box around it, repaints the ink, the surface, the gradient stops and the element's own fill alike, and low-contrast and gray-on-color read the painted colours (the snippet prints them); a filter below the surface's box that moves the ink, a filter the engine cannot model, a filter a running animation is moving, a colour-moving filter that also blurs, and SVG text with no readable fill still take no verdict. The structural layer climb follows children that each cover the whole text run past its usual six levels, up to 24, under the same node budget, so a picture nested deep in a sibling is found before the sibling's own fill. Ink in exactly the colour of the page ground (body or html) over a body or html that paints a raster image other than a small repeating texture takes no 1.0:1 verdict, as where the hit-test stacks are silent. A positioned ::before or ::after that covers the run, sits at a negative z-index that the capture says paints over its box (at auto or above it paints over the text, not under it), has no colour of its own (or one that an opaque layer filling the face hides), is not at an explicit opacity under 0.9, visibility: hidden, or moved, scaled or turned by a transform, translate, scale or rotate other than the identity, and paints only gradient layers whose bottom layer is opaque and fills the face, is the text's surface: the stops of the topmost layer that is opaque at every stop and fills the face (as the computed background names it: tiled with repeat or round on both axes at a size with no zero, or a size of auto, cover, 100% 100%, 100% auto or auto 100%, which for a gradient is the whole positioning area, at a percentage, keyword or zero position; a size or position holding any function such as calc() or var(), a space tile, or anything unparsed does not fill; the layers beneath a filling layer are hidden and not read), else the bottom layer's stops, plus each of them under every translucent stop above, printed as gradient on ::after. Where that face has a filter of its own, or its layers combine into more than 256 colours, it is still the surface (the box's own background is not scored in its place) but the verdict is withheld. A fade that the element pass's opacity fold scores (every faded box below the surface's box, the surface resolved and not a pseudo-element's, not on a page ground that paints a picture, the fold not giving up) is no longer a visual-contrast reason, so such text is not read from pixels on that account. A pixel-pass finding on routed text does not report a colour pair (ink, severity, ratio, median, bar and reasons) the page's pixel pass already reported.
  • Round 10 labels, cards and colour tests (corpus run 47; both engines unless noted). Demo windows on landmarks. A section, article, header, footer or nav is still never a demo frame by its scale, tilt, size, preview caption or sample caption, but it is a demo window by its traffic lights: its first child is a title bar (at least 60% of the box's width, within 24px of its top, 12px to 72px tall, the box at least twice that and at least 120px wide) holding a trio of dots that ends in the bar's leading half, and the box, the bar and every dot have rects. A landmark that holds the page's h1, or at least half the page's rendered text (script, style, noscript and template text left out; a walk past 2,000 nodes counts as holding the page), is the page's own content and is not a window. Text in such a window takes the framed-demo treatment (r5-p26). gray-on-color. A background that clears the channel-spread bar reads as colour only when its OKLCH lightness is under 0.9 or its OKLCH chroma is 0.09 or more, so cream #feeed4 (L 0.955, C 0.038) and amber-100 #fef3c7 (C 0.058) carry gray ink as an off-white does, while amber-300 #fcd34d (C 0.153) still reads as colour. The class form (both engines and the text engine's markup matcher) no longer counts a bg-<hue>-50 or bg-<hue>-100 utility as the coloured fill, since every Tailwind hue at those shades sits on the pale side of that line; -200 and darker still count, and the side-tab stripe-child reader still sees the pale shades. gradient-text. The element form (both engines) and, in the URL engine, the ramp test behind it do not report a gradient whose colour stops all lie within 12 of the first stop on each channel and on alpha (scaled to 255), with at least two stops, and every stop readable: a hex colour or a colour function the parser resolves, after an optional first argument that sets direction, shape, position or colour space, with bare lengths read as transition hints. A var(), a named colour or a colour function the parser cannot read makes the value unread, and it reports as before. The stylesheet form stands down only when every gradient function read whole inside its 200-character window is one colour and no ) in the window closes a function opened before it. The clipped-ancestor test (both engines) and the visual pass (URL engine) read a per-layer background-clip: text, text as clipped text; gradient-text's element form still reads only a single text clip (taste call r9-t4). nested-cards (URL engine). A box with no element child whose text renders on one recorded line, at most three line-heights tall, is a single-line label, whatever its padding; with no recorded lines it is read as before. A card's border side counts as an edge only when the border, composited over the box's own fill over the painted surface under the box, sits at least 8 from that surface on some channel. That surface is used only when the text the box holds reads on it at 3:1 or better (the box's own ink and up to eight elements with painted text of their own, in a 64-node walk that skips subtrees at display: none, content-visibility: hidden or opacity 0.01 and below, and own text at visibility: hidden or collapse); otherwise, and where no surface is read, every drawn border counts as before. Whether an inner box shows a border at all (r4-p16) is still read from its computed style. Vanishing ink (URL engine). When an element's low-contrast finding prints a ratio under 1.25:1 (VANISHING_INK_RATIO; one decimal at that range, so a printed 1.2 is a measured ratio under 1.25), its tiny-text and undersized-ui-text findings are dropped and low-contrast reports alone. Size findings stand when that low-contrast finding is turned off (disabledRules), ignored inline, handed to the pixel pass, withdrawn when a colour claim moves to a copy wholly on screen, or removed by the CLI after the scan: ignoreRules, or any --scope (low-contrast declares none). The CLI passes those rules to the engine for this one test; nothing else reads them. Also: class markers of page furniture (label, nav, badge and the rest) are not read off html, which holds script state flags, and are still read on body and below; a heading inside a blockquote or q sets no rhythm and counts toward no page minimum (URL engine); a heading level other than h1 whose second most frequent size is a 1.25 step or more above its most frequent one and within 25% of it in count has no settled size and leaves the flat-type-hierarchy ladder; organic-clip-path reads a polygon whose vertices take two to four values on one axis and step evenly on the other, swinging back and forth by one amount at least three times, as a zigzag edge, and a path() whose straight sides lie on all four edges of the box its points and sampled curves span, joined by curves that each turn a corner, as a rounded rectangle, and reports the same snippet under the same selector once (inline styles report under body, so two inline shapes with the same vertex count report once); wide-tracking does not report text whose own letters, or whole run when it has none of its own, are at least half Han, kana or Hangul; and overused-font (URL engine) does not name a face that heads the stack of a page whose letters are mostly CJK when it sets under 5% of those letters.
  • The page's own built-ins (Rust engine). Before any page script runs, every document the URL engine loads gets the built-ins the engine's page scripts use (Map, Set, Array.from, JSON.stringify, ...) captured from its untouched globals, so a page that declares its own global Map or reassigns Array.from still scans. The stash is a page-visible, non-enumerable window.__impeccableNatives, so a page can detect the scan, and a page script declaring let __impeccableNatives throws.
• createBrowserDetector(options): shared browser, defaults waitUntil:'load', settleMs:100, viewport 1280x800; close() closes only an owned browser.
• Tests: tests/detect-url-launch.test.mjs, tests/detect-antipatterns-browser.test.mjs.

Static and regex engines (only what affects the contract)

• flat-type-hierarchy is advisory when weight separates the roles (Rust engine, corpus decision r4-p23-flat-type-hierarchy-commerce; static HTML and URL engines, which read computed weights). The rule reads each sampled element's computed font-weight (normal 400, bold 700, a number as itself); when at least four in five heading samples are set at least 200 heavier than the body samples' most common weight, the finding keeps reporting with severity: 'advisory' and its snippet's parenthesis ends ; weight separates headings from body text). Otherwise it reports as before. The static engine's cascade has no user-agent stylesheet, so a heading with no declared weight reads 400 there, where the URL engine reads the browser's bold.

• detectHtml: reads file, imports htmlparser2, css-select, css-tree, domutils; on import failure prints once to stderr impeccable detect: DEGRADED - HTML parser modules unavailable (htmlparser2, css-select, css-tree, domutils).\nFalling back to regex matching. Custom properties, selector matching and computed contrast are NOT evaluated; findings are an undercount, not a clean bill of health.\n and falls back to detectText. Inlines <link rel=stylesheet href> that are local (not /^(https?:)?\/\//i), query/hash stripped. Runs element rules, design-system rules (checkSourceDesignSystem + collectStaticDesignSystemFindings, merged), then page rules only when isFullPage(html) (/<!doctype\s|<html[\s>]|<head[\s>]/i after stripping comments), plus text-content analyzers; ends with inline-ignore filtering.

• detectText: regex line matchers (ids: side-tab including Tailwind stripe-child empty w-* + chromatic bg-* plus a shrink-0 / edge-round cue, border-accent-on-rounded, overused-font, gradient-text, ai-color-palette, gray-on-color, bounce-easing, broken-image), inset-stripe/pseudo-stripe CSS scans, codex-grid-background, <style> blocks (Astro/Vue/Svelte), CSS-in-JS templates, design-system source checks; dedupe (same antipattern+snippet within 2 lines); page analyzers only when isFullPage and ext ∈ {'.html','.htm','.astro','.vue','.svelte'} or no ext (<stdin>): flat-type-hierarchy, monotonous-spacing, em-dash-overuse, marketing-buzzword, aphoristic-cadence, dark-glow (+ radial-halo, marquee); inline ignores last.

Profiler (`cli/engine/profile/profiler.mjs`)

• Not exposed via any CLI flag (no --profile; grep finds none). Library only: createDetectorProfile() → {events: []}; engines call profileFindings/profileStep/(Async) when options.profile is passed programmatically. recordProfileEvent normalizes to {engine, phase, ruleId, target, ms, findings, [detail], [findingIds]} (defaults 'unknown'/''/0) and pushes to profile.events (or calls profile(event), profile.record, or pushes to an array). summarizeDetectorProfile(profile) groups by engine\0phase\0ruleId\0target and returns [{engine, phase, ruleId, target, calls, totalMs, avgMs, p50, p95, findings}] (ms values Number(x.toFixed(3)), percentile index min(n-1, max(0, ceil(pct/100*n)-1)) over sorted samples), sorted by totalMs desc. Event vocabulary used: engine browser|static-html|regex; phases setup|load|scan|visual-contrast|element|page|parse-html|source|style-block|css-in-js|extract|text-content|page-analyzer; ruleIds like import-puppeteer, read-browser-script, launch-browser, new-page, set-viewport, goto:${waitUntil}, settle, configure-pure-detect, inject-browser-script, browser-scan, content-hidden-at-rest, browser-fallback, collect-candidates, pixel-diff, close-page, close-browser, read-html, import-static-parser, parse-document, inline-linked-stylesheet, design-system, typography-rules, kicker-above-heading, numbered-section-labels, repeated-container-text, layout-rules, cream-palette, skipped-heading, html-patterns, text-content, codex-grid-background, style-blocks, css-in-js, or the rule id.

`impeccable help|install|link|update|check` and `impeccable skills ` (`cli/bin/commands/skills.mjs`)

Rust authenticity addition (#479): the historical JS bundle flow below
is superseded for remote downloads. The Rust installer resolves the site's
redirect (301/302/303/307/308) to a versioned Impeccable GitHub release and verifies
universal.zip.sig.json against a compiled-in Ed25519 public key before ZIP
extraction. Missing/invalid signatures, unknown keys, mismatched metadata or
content, and failures fetching either asset exit nonzero, including when
install finds an existing installation. No downloaded content reaches the
installed skill or hook files. Explicit IMPECCABLE_BUNDLE_PATH and link
retain their local-development trust behavior. See bundle signing.

TLS trust (#757): every HTTPS request the engine makes (bundle and signature downloads, /api/version, /api/commands, the roll API, image generation) verifies against the OS trust store plus the bundled Mozilla roots, built once in crates/context/src/http.rs. SSL_CERT_FILE / SSL_CERT_DIR replace the OS store, never the bundled roots. The live server calls on localhost are plain HTTP and unaffected.

• Invoked from: README.md ("npx impeccable install / update"), README.npm.md Quick Start (npx impeccable skills install, ... install -y --providers=claude,codex --scope=project, ... update, ... install --no-hooks, ... link --source=.impeccable --providers=claude,cursor, ... skills help), README.md:360 (hook consent explanation).
• run(args): args[0] ∈ undefined|help|--help|-h → showHelp(); install → install(rest); link; update; check (ignores flags); else stderr> Unknown skills command: ${sub} + Run 'impeccable --help' for available commands., exit 1.
• Constants: API_BASE = 'https://impeccable.style'; PROVIDER_DIRS = ['.claude','.cursor','.dsh','.gemini','.agents','.agent','.github','.grok','.hermes','.kiro','.opencode','.pi','.omp','.qoder','.trae','.trae-cn','.rovodev','.vibe']; aliases (agent→.agent, agents/codex→.agents, antigravity→.agent, claude/claude-code→.claude, copilot/github→.github, cursor, deepseek/deepseek-harness/dsh→.dsh, gemini, grok/grok-build/xai→.grok, hermes, kiro, opencode, pi, omp/oh-my-pi→.omp, qoder, rovo-dev/rovodev→.rovodev, trae, trae-cn, vibe); leading . stripped and lowercased before alias lookup; a literal PROVIDER_DIR value is accepted as-is. DEFAULT_TARGETS = ['.claude','.agents']. User-scope skill dir overrides: .agent→~/.gemini/config/skills, .dsh→$DSH_HOME/skills (only when DSH_HOME under home) else ~/.dsh/skills, .hermes→$HERMES_HOME/skills (only when HERMES_HOME under home) else ~/.hermes/skills, .pi→~/.pi/agent/skills, .omp→~/.omp/agent/skills, .opencode→$OPENCODE_CONFIG_DIR|$XDG_CONFIG_HOME/opencode|~/.config/opencode + /skills; others ~//skills. Project scope: <root>//skills.
• help: fetch('https://impeccable.style/api/commands') → JSON array [{id, description}]; failure → stderr> Could not fetch command list from impeccable.style. Check your network connection., exit 1. Prints:
  text Copy

  Impeccable Skills & Commands
  
    Install:  npx impeccable install
    Link:     npx impeccable link --source=.impeccable
    Update:   npx impeccable update
    Docs:     https://impeccable.style/cheatsheet
  
    Command                Description
    ---------------------- ----------------------------------------------------
    /<id padded to 22>     <description, truncated to 69 chars + '...' if > 72>
    ...
  
    N commands available. Run /<command> in your AI harness.

  sorted by id.localeCompare.
• Flag parsing (getFlagValue): --name=value or --name value (next arg not starting with -). Boolean flags via includes.
• install flags: --force, -y|--yes, --no-hooks, --providers=<list>, scope: --user|--home|--global → user; --project|--local → project; --scope=<v>/--install-scope=<v> normalized (u|user|home|global→user, p|project|local|repo→project; unknown → error Unknown install scope: ${v}. Use --scope=project or --scope=global.). Project root = nearest ancestor with .git, else cwd. Detection: project harness dirs present in root, plus GLOBAL_HARNESS_HINTS under home (.agent, .gemini/antigravity*→.agent, .claude, .codex→.agents, .cursor, .dsh (resolved $DSH_HOME, fallback ~/.dsh), .gemini, .grok, .hermes, .kiro, .opencode, opencode config dir, .pi, .qoder, .rovodev, .vibe). Targets: explicit list wins (invalid names → Unknown provider(s): ...); -y → detected project providers, else detected user providers, else DEFAULT_TARGETS; interactive → prints "Detected harnesses:" table then radio/checkbox prompts (raw-mode TTY) or line prompts (Install target: [1] Detected only (...) [2] Customize [1]: , Select harnesses (comma-separated: ...)). Scope: explicit; -y → project; interactive prompt Install location (Project/Global). Hooks: decideHookInstall reads hook.consent in config(.local).json; declined→false, accepted→true; all targets already have hook markers→true; -y or non-TTY→true; else prints HOOK_EXPLAINER and asks Install the design hook? (Y/n) , storing consent in .impeccable/config.local.json.
  Bundle: IMPECCABLE_BUNDLE_PATH (dir or zip) else download https://impeccable.style/api/download/bundle/universal (https get, one redirect followed, non-200 → HTTP ${status}) to ${tmpdir}/impeccable-update-${Date.now()}.zip, extracted with fflate.unzipSync into ${tmpdir}/impeccable-update-${Date.now()} (zip-slip guarded: Refusing to extract entry outside target dir: ${entry}). Bundle layout //skills/<skill>/..., //agents/*.md, hook manifests /.claude/settings.json, .cursor/hooks.json, .codex/hooks.json, .github/hooks/impeccable.json, .grok/hooks/impeccable.json.
  Fresh install: stdout> \nDownloading impeccable skills...; migrate *-impeccable prefixed dirs → impeccable; copy each skill dir (rm existing dest first; drop an in-project cross-provider symlinked skills dir); copy agents (.github→.github/agents or ~/.copilot/agents; .cursor→.cursor/agents or ~/.cursor/agents); write hooks (Claude project scope: .claude/settings.local.json, skipped when project .claude/settings.json already carries the marker; Claude user scope: ~/.claude/settings.json, with obsolete Impeccable entries pruned from ~/.claude/settings.local.json; other destinations: .cursor/hooks.json, .codex/hooks.json for .agents, .github/hooks/impeccable.json, .grok/hooks/impeccable.json); merged with existing JSON (mergeHookManifests: strips existing impeccable entries by markers skills/impeccable/scripts/hook-probe.mjs|hook.mjs|hook-before-edit.mjs|hook-after-edit.mjs|hook-stop.mjs, then appends fresh); invalid existing JSON → error Existing hook manifest is not valid JSON: ${dest}. Re-run with --force to replace it. (with --force, .bak written). Claude and Gemini user settings are never replaced wholesale when invalid. Hook command rewriting: [ ! -f '<abs>' ] || node '<abs>' (POSIX, single-quote-escaped) when absolute (user scope or global skill), else [ ! -f "<rel>" ] || node "<rel>" where rel = ${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs (Claude), .agents/skills/impeccable/scripts/hook.mjs (Codex; plus commandWindows: if exist "" (node "" & exit /b)), .cursor/skills/impeccable/scripts/hook-before-edit.mjs; on win32 for non-Codex: node -e "<WIN32_HOOK_GUARD_SCRIPT>" "". Output: Installed impeccable into: ${targets.join(', ')} (${'global'|'project'}), optional Installed agents into: (+ shadow warning), Installed hooks into: ..., then \nDone! Now type /impeccable init in your AI coding agent's chat (not in this terminal) to set up design context.\n. Errors: Download failed: ... / Install failed: ... / Nothing was installed: the bundle had no variants for ... → exit 1.
  A Claude user-scope hook write also prunes obsolete Impeccable entries from the current project's .claude/settings.local.json, preventing a stale project hook from firing alongside the user hook.
  Already installed (and not --force): Impeccable skills are already installed (found in ${provider}/).; compares tree hashes (sha256 of file content with \.(claude|cursor|...)\/skills\/ normalized to .PROVIDER/skills/); if differs → refresh + Updated ${n} skill(s) to v${v}.; missing hooks repaired; else Skills are up to date (v${v}). + Run with --force to reinstall.; offline → Could not check for skill updates: ${msg} + Existing skills were left unchanged.; ends Done! or the above; exit 0. Version read from ^version:\s*(.+)$ in installed impeccable/SKILL.md.
• update flags: -y|--yes, --force, --no-hooks, scope flags as above (unknown → Unknown update scope: ${v}. Use --project or --user.). Resolves project vs user installs holding an impeccable/*-impeccable/teach-impeccable skill; none → No impeccable skill folders found in this project or at the user level. + Run \npx impeccable install` to install first., exit 1; both → prompt Update which? [project]/user: (non-TTY defaults project). PrintsUpdating the ${label} install: ${root} (${providers}), linked providers note, Checking for updates...; up to date → Skills are up to date (vX).[+hooks] +Nothing else to do., exit 0; else Found skills in: ..., prompt Update skills in N provider folder(s)? (Y/n) (n/no →Aborted.exit 0), refresh,Updated N skill(s) to vX., Done!`.
• link: --source= (default .impeccable), --providers, --force, -y. Source must contain dist/universal/ or provider */skills dirs, else Could not find compiled skills in ${src}. Expected dist/universal/ or provider skill folders. Prompts Link impeccable skills into N folder(s)? (Y/n) ; creates relative dir symlinks; existing non-link skipped with warning unless --force; output Linked impeccable into: ... (N linked, N already linked, N skipped). + submodule hint.
• check: not installed → Impeccable is not installed in this project. + Run \npx impeccable install` to install.exit 0; elseChecking for updates...\nthenSkills are up to date (vX).orUpdates available.+Run `npx impeccable update` to update.; failure → Could not check for updates: ${msg}` exit 1.
• Prompts: non-TTY ask() reads answers line-by-line from stdin (fd 0) after echoing the question; TTY SIGINT → PromptAbortError (code IMPECCABLE_PROMPT_ABORT) → cli.js prints \nAborted. exit 130. ANSI (\x1b[36m accent, \x1b[1m bold, \x1b[2m dim, \x1b[32m good) only when stdout is TTY, NO_COLOR unset, TERM !== 'dumb'.
• Tests: tests/skills-cli.test.js, tests/cli-remote-e2e (opt-in).

PART 2 — skill/scripts verbs Copy Section

`concept-seed.mjs` -> `node {{scripts_path}}/concept-seed.mjs`

• Invoked from: reference/new-work.md:37 "node {{scripts_path}}/concept-seed.mjs --scope surface --mode <mode>" and :46 "4. Run node {{scripts_path}}/concept-seed.mjs --scope direction --mode <mode> and follow what it prints. No substitute, no skip". Header usage lines: --scope direction --mode persuade, --scope surface --mode operate --from <key>, --grain flow, --candidate-count 6, --from <key> --reroll 1 [--register bolder], --chosen <challenger-id> --kind challenger --from <key> --scope direction, --kind assigned --from <key> --scope direction.
• Args (each read as args[idx+1] after indexOf): --scope (surface default | direction), --from <key> (default IMPECCABLE_CONCEPT_SEED env or crypto.randomBytes(4).toString('hex')), --reroll <n> (Number, default 0), --register safer|bolder, --mode persuade|operate|read|experience, --grain product|flow|view|region, --platform web|ios|android, --candidate-count 5..7 (default 7), --chosen , --kind assigned|pick|challenger|canon.
• Env: IMPECCABLE_CONCEPT_SEED, IMPECCABLE_CATALOG_DIR (default = script dir; local catalog files concept-ingredients.json, concept-reviews.json, composition-ingredients.json, composition-reviews.json; invalid/missing → treated as absent), IMPECCABLE_API_URL (default https://impeccable.style/api, trailing / stripped), IMPECCABLE_API_TIMEOUT (ms, default 4000, one shared deadline for all API calls in the run), IMPECCABLE_NO_TELEMETRY, DO_NOT_TRACK, IMPECCABLE_CARD_BASE (default https://impeccable.style/worlds/cards), IMPECCABLE_COMPOSITIONS=1 (renders composition block; otherwise compositions are dealt but not printed).
• Validation errors (stderr, exitCode 1): concept-seed: --scope must be direction or surface; --reroll must be a non-negative integer; --register must be safer or bolder; --register steers a re-roll round; pass --reroll <n> with it; --register applies to direction rounds only; --mode must be persuade, operate, read, or experience; --grain must be one of product, flow, view, region; --platform must be one of web, ios, android; --candidate-count must be an integer from 5 to 7; concept-seed: every challenger tier needs at least one approved concept (local catalog).
• Init gate (render path only): imports ./context.mjs loadContext(cwd); if !hasProduct → stdout> NO_PRODUCT_MD: the dice stay in the cup until product truth exists. Complete the init ask round and write PRODUCT.md first (reference/init.md), then re-run this exact command. Challengers fuse their form with facts from PRODUCT.md; without it every direction is ungrounded.\n, exit 1.
• Assigned index math: unit(salt) = sha256(${scope}:${salt}:${key}).readUInt32BE(0)/0xffffffff; indexSalt = reroll===0 ? 'index' : index:reroll-${reroll}``; buildIndex = 3 + floor(unit(indexSalt)*(candidateCount-2)) (3..candidateCount). Surface scope deals dealtIndices=[buildIndex] plus up to 2 more distinct in 1..candidateCount via unit(${indexSalt}:deal-${draw}) (fills sequentially after 64 draws).
• Data resolution: local catalog → source:'local' (challengers via selectApprovedChallengers, compositions via selectApprovedCompositions, both in lib/roll-selection.mjs, hash = Node sha256 hex; poolRevision = first 12 hex of sha256 over sorted approved familyId:id:strength:form:spark:JSON(system):webLeverage lines); else roll API GET ${API_BASE}/roll?scope=&key=&reroll=[&mode=][&grain=][&platform=] (URLSearchParams order: scope, key, reroll, mode, grain, platform), raced against the shared budget; non-ok, timeout, or challengers empty → null; response fields used: poolRevision, approvedCount, catalogCount, challengers, compositions|stagings|staging; else degraded.
• Selection algorithm (roll-selection): challengers: approved concepts; per wellTier in ['graphic','interaction','atmosphere'] (all three must be non-empty), optional minRating gate, mode gate (review.allowedModes absent = all; a tier the gate would empty keeps its full pool, except under a mode with tier quotas, where that tier's quota moves to graphic and the tier is not refilled; graphic itself always falls back), strength filter (direction wants world|dual, surface wants composition|dual; per-tier fallback to full pool). Per-tier quota: TIER_QUOTAS = { operate: { graphic: 5, interaction: 1, atmosphere: 0 } }, every other mode (and no mode) 2 per tier. Tier order ranked by digests of ${scope}:${key}:tiers${salt}:${tierId} desc; a zero-quota tier is skipped without shifting index; per tier tickets (breadth==='niche' excluded; tickets by rating {1:1,2:2,3:2}, default 2) ranked by ${scope}:${key}:challenger-${index}${salt}:${id}#${ticket}; take quota picks in ranked order, each the first concept of a familyId not yet picked in that tier, else the next distinct id (at quota 2: first pick + first of a different family) → 6 picks when every tier can fill its quota, fewer on a thin catalog; re-roll round n excludes all earlier picks (fallback to the full tier pool if exhausted; under a quota, when fewer than quota unseen concepts remain, deal those first, then top up from the rest of the tier ranked with the same salt); salt = round===0 ? '' : :reroll-${round}``. Compositions: approved, non-niche (fallback all), surface===mode (empty → none), platform hard filter (platforms absent = all), tickets ranked with salt ${scope}:${key}:staging[:reroll-${round}], grain-preferred stable partition, distinct familyId first then top-up, count 3; match = {grain, atGrain, grainAvailable, platform, platformExcluded}.
• stdout (full roll): header line ${SCOPE} CONCEPT SEED (key: ${key}; mode: ${mode ?? 'unscoped'}; source: ${local|api}; approved pool: ${poolRevision}; ${approvedCount}/${catalogCount} human-approved; rerun with --scope ${scope}[ --mode m] --from ${key}[ --reroll n][ --register r] --candidate-count ${n} to reproduce this roll against this catalog revision), then [RE-ROLL ROUND n ...], the assigned block (ASSIGNED INDEX: N / DEALT INDICES: a, b, c (index N leads) + instruction, or SAFER/BOLDER REGISTER block), CHALLENGERS: with renderChallenger per concept:
  text Copy

  ${i+1}. ${form}
       SOURCE ID: ${id}
       CREATIVE SPARK: ${spark}
       SYSTEM GRAMMAR:
         - rule...
       WEB LEVERAGE: ${webLeverage}
       QUALITY BAR: board ${cardBoard || CARD_BASE/id.webp} · hero ${cardHero || CARD_BASE/id-hero.webp}

  optional composition block, challenger instruction, quality-bar sentence, authority + richness instructions, TELEMETRY: block (api source only), A user- or brief-pinned decision beats the roll, always., and the restated line (ASSIGNED INDEX (restated for truncated readers): N. ...; seed key ${key}.). Degraded: header ... source: degraded; rerun with ...) then ASSIGNED INDEX/DEALT INDICES, the "No challengers this run: the roll service was unreachable and no local catalog exists..." paragraph naming the single GET to https://impeccable.style/api/roll, authority, pinned-decision line, restated line. Safer register while degraded prints the SAFER block without assignment. Full text templates are in the source (lines 405-690) and should be copied verbatim.
• Mode rules (binary only; --mode given, every round including re-rolls and both registers): the mode's rules file is ${skillDir}/reference/mode-persuade.md for persuade and experience, mode-operate.md for operate, mode-read.md for read, resolved like every other reference path (IMPECCABLE_SKILL_DIR, else the skill dir found beside the binary; with neither, the bare reference/mode-<file>.md). The engine takes the bodies of its ## Directions and ## Comps sections verbatim (every line after the heading up to the next ## heading or EOF, CRLF read as LF, leading and trailing blank lines trimmed; anything before ## Directions is ignored) and prints, as the line after the richness instruction on a full roll and after the authority instruction on a degraded one:
  text Copy

  MODE RULES (${mode}, from ${path}). They govern this surface's directions and every comp you write or judge for it, the decision comps included; where shared guidance conflicts, these win.
  DIRECTIONS
  ${Directions body}
  COMPS
  ${Comps body}

  ${mode} is the mode as given (experience stays experience). When the file cannot be read, or either section is missing or empty, the block is the single line MODE RULES unavailable: read ${path} before writing directions or comps. and the roll still succeeds. Without --mode nothing is printed. The richness instruction is mode-neutral; the per-mode guidance on committing to an interface language lives in the mode files.
• Presentation (binary only; every successful roll, direction or surface, full or degraded, every re-roll and both registers; never on validation errors, the PRODUCT.md gate, or telemetry pings): after the last line of the roll, a PRESENTATION (the decision round, condensed from new-work.md; follow it even when your read of that file came back cut): header and five - lines, in order: how to serve the hand (round 0: <self> serve-question --schema, --start --payload <file>, open the URL; re-roll: --update --key <same key> --payload <file> while a page is open, never a second --start, and --start when no page opened yet); the comp line (direction: every card declares a comp under .impeccable/mocks/decision/, canon included, declined excepted, generated after serving in reading order with its a.png.json sidecar; degraded direction other than the safer register: one text-only card, no comp; surface: comps or wireframes, no pick or canon card; a recorded code default, or --mode operate / --mode read whatever is recorded, turns either scope's line into the code-led flip-reserve variant); <self> serve-question --wait --key <key>, led by After the last comp lands (at once when this round generates none), or, on a code-led round or a single degraded card, Right after serving, with no comp to generate first,, with the session-polling rule (rerun only after exit 3); the build-path line (recorded default <comp|code> (from .impeccable/config.json|.impeccable/config.local.json), resolved exactly like context's BUILD_PATH_DEFAULT, or none recorded ... with the comp default and the one-time offer after a flip; with --mode operate or --mode read it is instead code-led. A surface in <mode> mode builds in code whatever the project records, naming a recorded non-code default in parentheses as the one that governs Persuade and Experience surfaces, with "buildPath": {"value": "code", "toggle": true} and no offer to record a flip); and the structured-tool fallback (--start exit 2, --wait exit 4, or a harness that cannot hold a blocking --wait). Text in crates/context/src/seed_text.rs; reference/new-work.md is its source and names the block.
• Roll record (binary only; every successful roll, the same set that prints the presentation block): writes .impeccable/questions/roll.json atomically (temp file, then rename), creating the directory, as {"scope":"surface"|"direction","seed":<seed reference>,"reroll":<n>}, replacing the previous record. It holds neither the key nor a time: its age for the roll window is its mtime (read_roll fills at from it; a legacy record's own at still wins). When git already tracks roll.json (one git ls-files, only inside a work tree), the record goes to .impeccable/questions/roll.local.json instead, which read_roll prefers and take_roll removes the same way; once roll.json is untracked again, the next roll writes it and removes the aside file. When the roll printed challengers, the record also carries "worlds":[{"id":,"board":,"hero":}, ...] after at, one entry per printed challenger in print order, with the same board and hero URLs as its QUALITY BAR line; a degraded roll and the safer register (whose hand is spent unseen) print none and write no worlds key. A roll the API dealt, while telemetry is on, also carries "source":"api", the response's poolRevision (only when it is 12 lowercase hex), its handId (only when it is 32 lowercase hex), and the seed's mode and register when given; a decision page that takes such a roll copies them, with the dealt worlds, into its hand as seed (the picker's ping, below). Seed reference (binary only): every successful roll prints, after the roll text and before PRESENTATION, SEED REFERENCE: seed:<16 hex>. Write this, never the key, wherever the seed is recorded (the surface brief's FORM line, build-phase start --direction); on this machine --from accepts it in place of the key., where the hex is the first 8 bytes of SHA-256(impeccable-seed: + salt + : + key). The salt is 128 bits from the OS CSPRNG kept per user in ~/.impeccable/seed-salt, or, when the home cannot be written, in the project's ignored .impeccable/questions/seed-salt (created with create-new on first use; IMPECCABLE_SEED_SALT overrides both, for reproducible tests). An existing valid salt always wins over making one: an existing home salt, else an existing project salt, else a new home salt, else a new project salt, so a reference made in a sandbox keeps resolving after the home becomes writable; resolution (--from, --check-seed) accepts a reference made under any valid salt the machine keeps. A key's salt is chosen once, when its ledger is first written, and everything derives from that file (impeccable_common::seed::locate): the printed SEED REFERENCE, the roll record's seed, every ledger operation, --from, --check-seed and build-phase's --direction. The locator returns the key's existing ledger wherever it is (its names under the primary and every kept salt first, then a scan of the folder, for a ledger made under a salt now out of reach), whose reference is its own file name; only a key with no ledger takes the primary salt. A reference resolves by opening the file it names and reading the key recorded there. A ledger made with no salt is marked "unsalted": true, and one named by the no-salt tag is treated the same (ledgers written before the marker); neither yields a reference. A key the engine just generated (no --from, no IMPECCABLE_CONCEPT_SEED) skips the search: 128 random bits have no ledger, so it takes the primary salt directly. The lock checks its 3 s deadline on every pass, the stale branch included, so a lock that cannot be removed gives up rather than spin. A salt file that exists but is not 32 lowercase hex is never rewritten, and a corrupt home salt is never replaced by a new project one. With no valid salt there is no reference at all, never an unsalted hash: the roll prints SEED REFERENCE: unavailable on this machine (...). Record no seed: write \seed: none (unavailable)` on the surface brief's FORM line and pass --direction none to build-phase start; never write the key., the roll record carries no seed(so the page sends no ping), andbuild-phase start --direction storesnone. concept-seed --check-seed printsSEED KNOWN: ...(exit 0) when this machine's ledger resolves it, elseSEED UNKNOWN: ...(exit 1);--check-seed noneexits 0 withSEED NONE ACCEPTED: ...only when this machine has no salt. The salt means a reference cannot be computed from a key by anyone without that file: holding keys (the telemetry dataset does) is not enough to find a committed brief, and a key cannot be enumerated back from its reference. New roll keys (no--from, no IMPECCABLE_CONCEPT_SEED) are 32 lowercase hex from the OS CSPRNG; an explicit --fromkey is used as given, and a short one is guessable by whoever has the salt, so its reference is no privacy boundary. The seed ledger.impeccable/questions/seeds/.jsonrecords{"key"}for every roll (telemetry plays no part), so--from seed:(andIMPECCABLE_CONCEPT_SEED) resolves to the key on the machine that rolled it and reproduces the same deal; an unknown reference exits 1 with concept-seed: seed: is a seed reference this machine has no record of. ...naming the way out (pass the original key, or roll anew), and on a ping path printschoice ping skipped. While telemetry is on, an API-dealt round of either scope also adds "rounds": {"": {scope, mode?, register?, poolRevision?, handId?, dealt: [catalog ids], recorded?}}(no timestamps;handIdis the roll response's opaque name for the exact hand, kept only as 32 lowercase hex and absent from older servers). Rounds of ledger files untouched for 30 days (by mtime) are pruned on write, the age and the rounds re-checked under the file's lock and a file with a pending round left alone; thekey entry stays, so a reference never expires. Every ledger update is a read-modify-write under a per-file lock (.lock, create-new, waits up to 3 s, a lock older than 10 s is taken over) with a unique temp name (pid, counter, clock). build-phase start --directionstores a reference as given and a raw key as its reference, so the build state never holds the key. **Tracked runtime files** (binary only): a.gitignoredoes not untrack files already committed, so on a roll (and onserve-question --start) the engine runs one git ls-filesover.impeccable/questions, .impeccable/mocks/worldsand.impeccable/build/state.jsonwhen inside a work tree; when any are tracked it prints, once per distinct tracked set (remembered in the ignored.impeccable/questions/.tracked-notice), TRACKED RUNTIME FILES: git already tracks file(s) under .impeccable/ ... suggest they run `git rm -r --cached ` and commit ...before the roll text. Never fatal. **Runtime state is not added to git**: every write under.impeccable/questions/(roll record, hands, answers, server state, markers, ledger) first makes sure.impeccable/questions/.gitignoreexists and lists*(a self-ignoring file under the header# Written by Impeccable: local runtime state, never committed.; missing patterns are appended, user lines kept), so a project that predates it gets it on its next write. The same helper keeps .impeccable/mocks/worlds/.gitignore (*, the kept world card copies named by dealt ids) and .impeccable/build/.gitignore (state.json, which records the seed key) in place. serve-questionhands those card images over when the decision comps are due (**World cards**). Best effort: a write failure is silent and never fails the roll. Validation errors, the PRODUCT.md gate, and telemetry pings write nothing.serve-question` reads it for the surface-round comp gate and removes it when a decision page takes the roll (Missing decision comps).
• Client header (binary only): every GET ${API_BASE}/roll and POST ${API_BASE}/chosen sends X-Impeccable-Client: impeccable/<version>[ <channel>], matching ^impeccable/[0-9A-Za-z.+-]{1,32}( [a-z]{1,16})?$. The version is the installed skill's SKILL.md frontmatter version, else <engine version>+engine; the channel is IMPECCABLE_TELEMETRY_CHANNEL when it is 1 to 16 lowercase letters (test in this repo's tests and CI). When telemetry is off (DO_NOT_TRACK or IMPECCABLE_NO_TELEMETRY non-empty and not 0/false in any case, or "telemetry": false in ~/.impeccable/config.json or the project's .impeccable/config.json / config.local.json, read at the working directory, the resolved project root, and the repo root, the roots context reads its config defaults from), the roll request is still made and also sends X-Impeccable-Telemetry: off; no choice ping is sent, by the agent or the page, and no telemetry field or sent mark is written.
• impeccable telemetry off|on|status (binary only, not gated by PRODUCT.md): off writes "telemetry": false into the user config ~/.impeccable/config.json (created if missing, other keys kept, pretty JSON plus newline; a file that is not valid JSON or not an object is never overwritten: exit 1 with telemetry: is not valid JSON (...) / is not a JSON object; fix or remove it, then run ... again. Nothing was changed.), on removes the key, and all three print one line: telemetry: off (<reason>). Rolls still work; the roll API is told not to record them, and no choice is sent. or telemetry: on. ... naming what is sent, the ways to turn it off, and https://impeccable.style/privacy. No argument means status; anything else exits 1 with telemetry: unknown command "<x>"; use off, on, or status. A project config "telemetry": false also turns it off for everyone in that project; nothing turns it back on over an off elsewhere. telemetry is a known config key for doctor.
• Telemetry ping (--chosen, --kind, and/or --option present; never gated by PRODUCT.md): pingChosen({chosenId, key, scope, mode, kind, register, reroll, option}): skipped when IMPECCABLE_NO_TELEMETRY or DO_NOT_TRACK set, kind not in {assigned,pick,challenger,canon,reroll,grounded}, register not safer|bolder, none of chosenId, kind, and option, or kind challenger without chosenId. kind reroll reports a rejected hand and never carries a chosenId. --reroll <n> is the round the choice resolved on (an integer 0 to 8) and --option <n> the chosen card's zero-based position (0 to 15), for a card with no ping kind; anything else is ignored. When the seed ledger holds the round for --from <key> (the --reroll round, else the latest recorded), the record fills reroll, poolRevision and handId; a chosenId that is not one of that round's dealt catalog ids is dropped while the kind is still sent; and a round already marked sent prints choice already recorded\n and sends nothing. With no record, the arguments go as given and reroll is the flag's value or 0. Else POST ${API_BASE}/chosen with Content-Type: application/json, body keys in order chosenId?, key?, scope?, mode?, kind?, register?, option?, reroll, poolRevision?, handId?, pingId?, kindSource?, source (pingId: the round's 32 random hex from the ledger, the same in the page's and the agent's send) with source: "agent" (no kindSource), abort at budget; a sent ping marks its ledger round. stdout choice recorded\n on success, choice already recorded\n as above, else choice ping skipped\n; always exit 0. The TELEMETRY: line names the flags per scope (direction: --kind <assigned|pick|challenger|canon> plus --chosen ; surface: --kind assigned, --kind challenger --chosen, or --option <n>; both: --kind reroll [--register] for a rejected hand) and adds --reroll <n> on a re-roll round.
• Card identity (serve-question --start / --update, binary only): a payload carrying buildPath (a direction or surface round) is refused, exit 1, before the comp gate, unless every option declares kind in {assigned, pick, challenger, grounded, dealt} (grounded, any number, is another of the agent's grounded directions, such as a safer lineup card; its ping kind is grounded) (at most one assigned and one pick; dealt is a surface round's dealt structure other than the lead), every challenger declares catalogId, and, when a roll record younger than the roll window exists, each catalogId is one of its dealt world ids; a canonCard kind other than canon is refused too. stderr serve-question: every card on a direction or surface page declares its identity, and these do not: . Set "kind" on every option: ... naming the dealt ids, ending Fix the payload and rerun --start; the page was not served. or ... rerun --update on the same key; nothing was delivered.. Other payloads are not checked.
• Picker ping (serve-question, binary only): when a detached page whose hand carries seed (an API-dealt roll of either scope, taken within the roll window) receives an answer, and telemetry is not opted out, the server sends the ping itself with source: "picker" and kindSource. A re-roll answer sends kind: "reroll" (register the answer's steer, reroll the rejected round). canon (direction only) sends kind: "canon". An option card sends its declared kind (kindSource: "explicit"): assigned, pick, challenger with chosenId = its catalogId only when that id is in the hand's dealt worlds, and dealt with no kind. A card with no valid kind (older payloads, or a server started without --start) falls back to the conventions (kindSource: "inferred"): a verdict card is a challenger whose chosenId is the one dealt world its hero/board matches (URL or .impeccable/mocks/worlds/-<hero|board>.<ext>); on a plain direction round kicker IMPECCABLE’S PICK is pick and kicker THE ROLL or the lead card is assigned; on a surface round the lead is assigned; anything else sends no kind. Every option-card ping carries option, the card's zero-based position. Every picker ping, the re-roll rejection included, carries the round's handId from the hand's seed when the roll response had one. Before the answer file is written the page claims the ledger round ("recorded": "pending" plus pendingAt, only when the round has no state, under the ledger lock); the POST runs after it, within IMPECCABLE_API_TIMEOUT, carrying the round's pingId; success sets "recorded": "picker", failure clears the claim; both completions name the report by its pingId and change nothing when the round now carries another (a reproduced round), so a late send for the old report cannot record or release the new one. An agent rerun that finds the round pending polls it every 100 ms until pendingAt + IMPECCABLE_API_TIMEOUT + 1 s: confirmed means choice already recorded; a failed or still-pending send is sent by the agent with the same pingId (a double send the server can drop by pingId, rather than a lost report) and then marked agent.
• Exit: destroys undici global dispatcher then process.exit(exitCode ?? 0).
• Tests: tests/concept-seed.test.mjs (scopes reproducibility, degraded seed, register, ratings/breadth/mode/grain/platform, init gate, pingChosen validation & opt-out, API roll path + dispatcher destroy).

`serve-question.mjs` -> `node {{scripts_path}}/serve-question.mjs`

• Invoked from: reference/new-work.md "Run node {{scripts_path}}/serve-question.mjs --start --payload <file> (--schema first for the payload shape). It daemonizes, prints the page URL and a key, and exits; open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with --wait --key <key>, repeating while it exits 3; the ANSWER prints as JSON. An ANSWER of {"optionId":"reroll"} keeps the server alive..."; visualize.md:24 "Show the three together on the decision page (serve-question.mjs, one option per comp with the comp as its hero)"; new-work.md "each card carries a wireframe schematic (serve-question.mjs --schema)". Degraded concept-seed also names it.
• Arg helper: arg(name) = value after --name unless it starts with --; hasFlag.
• Env gates (evaluated at top): IMPECCABLE_QUESTION_DISABLED → stdout> serve-question: disabled in this session (no browser); use the structured question tool instead., exit 2. Headless detection only when wantsBrowser = !--no-open && !--wait && !--stop && !--schema && !--update and IMPECCABLE_QUESTION_FORCE unset: CI || (SSH_CONNECTION && !DISPLAY) || (linux && !DISPLAY && !WAYLAND_DISPLAY) → stdout> serve-question: no browser detected in this environment (CI/headless/remote); use the structured question tool instead. Set IMPECCABLE_QUESTION_FORCE=1 to serve anyway., exit 2.
• Common params: --payload <file> (else stdin), --timeout <sec> (default 900; 0 = wait forever for a page; negative/NaN → 900), --idle-grace <sec> (default 600; ≤0/NaN → 600), --port <n> (default 0 = ephemeral), --key, --no-open, --open, --poll <sec> (wait, default 60). State dir QUESTION_DIR = <cwd>/.impeccable/questions/ with files <key>.state.json ({pid, port, url, comps?, lastBeat?, claimedAt?}; comps is the live round's local decision comp paths, see Decision comps below), <key>.hand.json and <key>.generated/ (the hand's provenance, Decision comps), <key>.answer.json, <key>.flip.json, <key>.next.json, <key>.log. NEXT_CLAIM_GRACE_MS = 10000.
• Modes:
  • --schema: prints canonical payload JSON (2-space) then a long explanatory paragraph; exit 0. (Copy verbatim from source lines 210-232.)
  • --wait --key K [--poll N]: loops up to N s (1 s ticks): answer file → break; flip file exists → delete it, stdout> BUILD PATH FLIPPED: comp (for this session only; never write it to settings). The table is still open and the page shows shimmer where the images will land: generate each open card’s comp into its declared path now, lead first, then collect the answer with --wait again. A card whose comp already exists needs nothing. followed by the NEXT visualize line (Decision comps), exit 0; server dead (no fresh lastBeat <12 s and process.kill(pid,0) fails with non-EPERM) → stdout> serve-question: the question server is gone with no answer. This is a server failure, not a user decision: restart it with --start --key ${K} and the same payload, reopen the URL for the user, and wait again. Never proceed without their choice while their browser session is open. exit 2; lastBeat older than 15 s and not mid-delivery (next.json mtime <10 s or claimedAt <10 s) → PAGE CLOSED: the question page went away without an answer; re-present, reopen the URL, or fall back to the structured question tool exit 4; no answer after poll → WAITING: no answer yet after ${N}s; run --wait --key ${K} again exit 3; answer → printAnswer, delete answer file, delete state and hand files unless optionId reroll or followup:true; exit 0. Missing --key → stderr> serve-question: --wait needs --key exit 1.
  • --stop --key K: kill pid from state, remove answer/state/hand, stdout> stopped, exit 0.
  • --update --key K --payload F: payload must have non-empty options (else stderr serve-question: --update payload needs an options array; nothing was delivered. Fix the payload and rerun --update on the same key. exit 1); then the comp-led direction and surface gate (Missing decision comps below; stderr, exit 1, nothing was delivered, before the liveness check, <key>.next.json, the hand file, or the roll record are touched); server liveness like wait (dead → stderr serve-question: no live question server for that key; the page it served is gone too. Re-present the round with --start and a fresh key, or fall back to the structured question tool. exit 2); writes a new hand to <key>.hand.json, removes the roll record when the payload carries buildPath, copies payload to <key>.next.json, touches mtime, stdout> next round delivered; the page reloads itself, then the NEXT visualize line when the new round's comps are due (Decision comps), exit 0.
  • --start --payload F [--key K] [--open] [--timeout] [--idle-grace]: validates JSON, refuses a comp-led direction or surface round that leaves a card without a decision comp (Missing decision comps below; stderr, exit 1, before the hand is recorded, the roll record removed, the old state removed, or anything spawned), decides the hand and writes <key>.hand.json when it is new (Decision comps), removes the roll record when the payload carries buildPath, removes the key's previous state file without signalling its pid, spawns detached child node serve-question.mjs --payload F --detached-serve --key K --timeout T [--idle-grace G] [--no-open unless --open] with stdio to <key>.log; waits ≤8 s for state file; failure → stderr serve-question: server failed to start + last 4 log lines + serve-question: log at <rel>. A sandboxed exec that cannot listen on localhost causes exactly this; rerun this command once through the harness's network-enabled or unsandboxed command tool before falling back. exit 1; success stdout: QUESTION URL: ${url}, QUESTION KEY: ${key}, Open the URL for the user now: in-app browser when the harness has one, otherwise the system opener (macOS \open`, Linux `xdg-open`), otherwise show the URL., the NEXTvisualize line when the payload's comps are due (**Decision comps**),Then collect the answer with: node --wait --key ${key}; exit 0. Key default Math.random().toString(16).slice(2,10)`.
  • default (blocking): loads payload (error → stderr serve-question: payload needs an options array exit 1), listens on 127.0.0.1:${port}, stdout> QUESTION URL: http://127.0.0.1:${port}/ and Waiting for the user to choose in the browser (Ctrl-C aborts)..., opens browser unless --no-open; on answer prints via printAnswer and exits 0 after 150 ms. Detached mode writes state instead of printing.
• Missing decision comps (engine addition, not in the JS): --start and --update refuse a payload that is a comp-led direction round (or, per Surface rounds below, surface round) with image generation while some card that owes a decision comp declares none. The round owes them when all of these hold: buildPath.value is "comp" and buildPath.toggle is true (the toggle is only offered where image generation exists; a code-led round's slots are a flip reserve); the payload carries the canon exit, a truthy canon or an object canonCard (direction rounds only: surface rounds and the comp round never carry it); and options has at least two entries (a degraded roll's single text-only card declares no comp). The cards that owe one are every option whose verdict is not "declined", plus canonCard when present; a card declares one with a truthy comp or legacy sketch (a URL counts). Missing cards are named by id (options[<n>] when the option has none, canonCard for the canon card), in card order. Message on stderr, exit 1 (exit 2 keeps its fallback meaning): serve-question: this direction round is comp-led with image generation (buildPath value "comp", toggle true), so every card declares a decision comp, canon included, declined challengers excepted; ${outcome}. Missing a "comp": ${ids joined by ", "}. Give each of those cards "comp": ".impeccable/mocks/decision/<card id>.png" (the canon card's goes inside canonCard), then ${rerun}; the comps are generated after the page serves, as its NEXT line says. with ${outcome}/${rerun} = the page was not served/rerun --start for --start and nothing was delivered/rerun --update on the same key for --update. Surface rounds: the payload alone cannot tell a surface round (three dealt structures as full cards, no canon, no pick card) from the comp round or any other canon-less page, so the engine links it to concept-seed's roll record (.impeccable/questions/roll.json, Roll record under concept-seed). When the payload owes no direction comps and the record exists, parses, has scope "surface", and its at is less than one hour old, a payload with no canon exit that is comp-led with image generation and carries at least two options owes a comp on every option whose verdict is not "declined", named as above. Message: serve-question: this surface round (concept-seed's latest roll here was --scope surface) is comp-led with image generation (buildPath value "comp", toggle true), so every dealt card declares a decision comp; ${outcome}. Missing a "comp": ${ids joined by ", "}. Give each of those cards "comp": ".impeccable/mocks/decision/<card id>.png", then ${rerun}; the comps are generated after the page serves, as its NEXT line says. with the same ${outcome}/${rerun} pairs. The record binds a roll to the one page that presents it: a refusal leaves it in place, and a --start that records its hand, or an --update that records its hand, removes it when the payload carries a non-null buildPath (only direction and surface rounds do), whatever the round's build path. The record is read once, before the gate, and removed only while the file still holds that same text: a newer roll another session recorded in between stays for its own page. So a later page in the same project (the comp round, a page after a direction roll, anything after the surface round was served) is not gated by it, and a page without buildPath (an unrelated question) neither takes nor is gated by it. Checked after the JSON parse (and, for --update, the options check) and before anything else; the env and headless gates run first, so a session that falls back to the structured tool never sees it. The blocking (non---start) server does not check.
• Decision comps (engine addition, not in the JS): a round's declared comps are the local paths in each option's comp (or legacy sketch) and canonCard.comp, in card order, deduplicated; URLs are left out. The detached server writes them to the state file as comps (omitted when empty) and rewrites them when it claims a --update round.
  • Hands and provenance. Each served hand's provenance lives in <key>.hand.json, {"id": "", "digest": "<first 16 hex of sha256 over the compact JSON of the whole payload>", "comps": [<declared comps>], "pre": {"<slot>": "<sha256 hex of the file bytes>"}}, plus "worlds": [...] last when the hand was dealt catalog worlds (World cards). Only --start and --update write it, atomically (a temp file beside it, then a rename), and a failed write fails the command: --start prints serve-question: could not record the hand (<file>: <error>); the page was not served. Make .impeccable/questions/ writable and rerun --start. on stderr and exits 1 before spawning the server or touching the old state; --update prints serve-question: could not record the hand (<file>: <error>); nothing was delivered. Make .impeccable/questions/ writable and rerun --update on the same key. and exits 1 before copying <key>.next.json, so the page keeps the previous round with its hand file intact; the server never does, so its heartbeat and claim rewrites of the state file cannot drop a hand. --update always starts a new hand. --start keeps the recorded hand when the key's hand file carries the same digest (a restart) and otherwise starts a new one. A new hand fingerprints every declared slot that already holds a file into pre. The digest covers the whole payload, not only the slot paths, because a re-roll often reuses the previous hand's paths. impeccable generate-image, after writing --out, scans .impeccable/questions/*.hand.json for a hand that declares that path (resolved against the cwd; compared case-insensitively on Windows) and marks it generated during that hand with a marker file <key>.generated/<16 hex of sha256 over the JSON string of the slot>-<hand tag>.json = {"slot", "hand"} (the hand's id), written atomically. The hand tag is the hand's id (a hand file without an id uses its digest) when that is 1 to 64 characters of [a-z0-9_], else the first 16 hex of sha256 over its JSON string (lowercase only, so ids that differ in case never share a path on a case-insensitive file system). Markers are one file per slot rather than a list inside the hand file because parallel generators (one subagent per card) would race a shared read-modify-write, and the tag in the name keeps one hand's markers off every path another hand writes. A marker counts only while its name carries the hand file's tag, so a re-roll that repeats a payload never inherits the previous hand's markers. Writing a new hand writes the hand file first and only then prunes, deciding from the file name alone: it deletes only markers (and their temp files) tagged with another hand, so a failed write leaves the live hand and its markers intact and a parallel generation's marker for the new hand is never touched, even when it regenerates a reused slot while the prune runs (#886). A legacy untagged marker <16 hex>.json (written before names carried the hand) counts, and survives a prune, only while its content's hand (else digest) matches the hand's id (else digest); the engine never writes that name again. --stop and a closing answer remove <key>.generated/ with the hand file. A failed marker write prints generate-image: could not mark <out> as generated for its decision page (<file>: <error>); a --wait may report it stale on stderr and leaves the exit at 0, since the image itself was written. Readers merge the valid markers into the hand as generated: [<slot>, ...]. A declared comp is this hand's when its file exists and its slot is in generated, has no pre entry, or its current bytes hash differently from pre; timestamps play no part, so an old file rewritten unchanged in the same second is still not this hand's, while a deterministic generator's identical regeneration still counts through generated. Rewriting a comp's prompt sidecar never counts on its own: only new bytes or an engine generation do. Two exceptions: a comp directly in .impeccable/mocks/ is the comp round's, generated before that round serves, and counts whenever it exists; with no hand file, existence decides. --wait judges the hand file's comps, else the state's. A declared comp that exists but is not this hand's is stale. The page itself still shows whatever file sits at a slot; hiding stale files there is out of scope.
  • Four directives follow:
  • NEXT read ${skillDir}/reference/visualize.md now, before writing any decision comp prompt; it and the MODE RULES block concept-seed printed for this surface govern every card's image. Then generate each declared comp into its slot, lead first, and record the exact prompt in its sidecar, the image's full file name plus .json (a.png gets a.png.json). The path is the provider's skill dir (IMPECCABLE_SKILL_DIR, else the one found beside the binary); with neither it reads reference/visualize.md. Printed by --start between the Open the URL line and the Then collect line, and by --update after next round delivered, when buildPath.value is not code (a code-led round's slots are a flip reserve) and some declared comp is not this hand's yet; and by --wait right after BUILD PATH FLIPPED, when the state has no comps or one of them is not this hand's. The engine cannot see a harness-native image tool, so a slot without this hand's comp is the signal that comps are about to be written. So a fresh decision round (serve first, generate after) gets the line even when an earlier round left files at its slots; a restart of the same hand after its comps landed does not; a re-roll through --update that reuses slot paths does, and so does a restart of that re-roll before its comps land; the comp round, whose comps sit directly in mocks/, does not.
  • World cards (engine addition): when the hand was dealt catalog worlds, that same NEXT line continues, before its newline, with The catalog worlds dealt in this roll have card images, listed at the end of this line: when a card's direction builds on one of these worlds, attach that world's board and hero as reference images to that card's comp (the harness image tool's input images, or \${impeccable} generate-image --ref --ref `${unfetched}), as style inspiration only, never to copy layout or content; a card for a direction you invented yourself has no card images and gets none. WORLD CARDS: ${worlds joined by " | "}where each world is${id} board ${board} hero ${hero}and${unfetched}is; any image listed as a URL could not be fetched, so download it into the workspace first when the tool takes fileswhen some image is named by URL, else empty. The list closes the line so no path or URL touches sentence punctuation. Models skip the prose rule that says to open the card images and follow an engine line, and a harness image tool takes reference images only as workspace files, so the engine fetches them. **Which worlds**: a new hand copies the roll record'sworlds(**Roll record** under concept-seed; the record text read once before the gate, since the page then removes it) when the payload carries a non-nullbuildPath(the page that takes the roll), the record parses, itsscopeis"direction", and its atis less than one hour old. A surface roll hands over none: its challengers change topology under an identity already committed. An entry is kept only when itsidis 1 to 120 characters of[A-Za-z0-9._-]not starting with a dot (it becomes a file name) andboardandheroarehttp://orhttps://URLs of at most 500 characters with no whitespace, control character,|or backtick. The payload is never consulted for which card builds on which world (itshero/boardfields are model-authored and optional), so every dealt world is listed once. The worlds live in the hand file, so a--startrestart of the same hand and the--waitflip line name them too. **Fetching**: right before the line prints, each listed world's board and hero go to.impeccable/mocks/worlds/-board.and-hero. (iswebp, pngorjpg, from the fetched bytes' signature, so a later --refof the path sends the right type). A file already there underwebp, png, jpgorjpeg(looked for in that order) is kept and not requested. The rest download in parallel, each one GET under an 8 s timeout through the shared agent (OS trust store, env proxies), following no redirect, accepted like agenerate-image --refURL (2xx, non-empty, at most 30 MB, a PNG, WebP or JPEG by signature, so an HTML page served at a card URL is never kept as a card), written to a temp file and renamed. **Which URLs the engine requests unasked**: the record is a project file, so a crafted one must not turn--startinto a probe of loopback, link-local or private services. A URL is requested only when it starts with the configured card base plus/ (IMPECCABLE_CARD_BASE, else https://impeccable.style/worlds/cards`), or is https to a named host with a dot in it whose last label is letters only or punycode (so no IP address in any spelling: 127.0.0.1, 127.1, 0x7f.1, a bracketed IPv6), carries no userinfo, and is not localhost or under .localhost, .local, .internal, .lan or .home.arpa. Any other URL is never requested and is listed by URL. (generate-image --ref is an explicit request and stays unrestricted.) Best effort: a failed, blocked or refused download changes no exit code and prints nothing; that image is named by its URL instead of its path. With IMPECCABLE_IMAGE_GEN_FAKE set no request is made: files already there are named by path, the rest by URL. With no world to list (no roll record, an unreadable or expired one, a surface or degraded roll, a page without buildPath) the line is exactly the one above and nothing is fetched or created.
  • COMP SIDECAR MISSING: ${paths joined by ", "} landed with no prompt sidecar. Every decision comp records the exact prompt that produced it in its sidecar, the image's full file name plus .json (a.png gets a.png.json), as {"prompt": "..."} (generate-image writes it itself, a harness image tool does not), and that prompt is written under the comp rules in ${visualize path}. Write each missing sidecar now, and read that file before the next comp prompt if you have not. Printed by --wait as the last line of a WAITING (exit 3) or answered (exit 0) return when a state comps path is this hand's comp and has no .json. Comps that have not landed, and stale files, are skipped. It is a warning: exit codes and the answer are unchanged, because the user is mid-decision in the browser and blocking --wait would strand their answer.
  • SKETCH STALE: these sketch files predate this round, so the page is still waiting on them: ${paths joined by ", "}. Rewrite each now; the page shows a sketch only once it is written after the round was served. Printed by a WAITING return for every path in the hand's sketches that exists and is not this hand's (written after the hand's startedAt, or differing from its pre fingerprint).
  • COMP STALE: files left from an earlier round sit at this hand's slots, and the page is showing them: ${paths joined by ", "}. Regenerate each into its slot now under the comp rules in ${visualize path}, with its prompt sidecar, before the user decides. Printed by --wait as the last line of a WAITING return (after COMP SIDECAR MISSING when both apply) when a state comps path is stale. Never on an answered return: once the user picks, the image they saw is the one they chose.
  • NEXT open each decision comp once and run ${visualize path}'s render checks (shipped screen, one dominant move); regenerate any that fail before the user answers. Printed by --wait as the last line of a WAITING return (after COMP SIDECAR MISSING and COMP STALE when they apply) when at least one state comps path outside .impeccable/mocks/ itself (a decision comp, not a comp-round comp) is this hand's comp and has its .json sidecar. Once per hand: the first such return writes the hand's id (else its digest, else the empty string with no hand file) to <key>.render-check, and a later return finds that id there and stays quiet; a new hand carries a new id, so its round prints the line again. A code-led round's slots stay empty or stale until a flip to comp, so it gets no line. Never on an answered return. --stop and a closing answer remove <key>.render-check with the hand file.
• Payload processing (loadRound): options decorated with heroSrc/boardSrc (http(s) URL passthrough; local path must exist → /img/), htmlSrc (html, a local path only, registered even if missing → /sketch/; URLs ignored), compSrc (comp or legacy sketch; local path registered even if missing); verdict==='declined' cards moved to the end; canonCard appended as {...card, id:'canon', isCanon:true} before declined; buildPath {value:'comp'|'code', toggle:bool}.
• HTTP routes: GET / → HTML page (claims <key>.next.json if present, stamps claimedAt); POST /heartbeat → 204, updates lastBeat in state at most every 4 s; GET /next-status → {"ready":bool}; GET /sketch/<n> → the declared HTML sketch as text/html with cache-control: no-store, nosniff, referrer-policy: no-referrer and a CSP that sandboxes it and allows only inline styles, Google Fonts and data/blob images (script-src 'unsafe-inline' with sandbox allow-scripts for the skeleton view, script-src 'none' with sandbox for raw) and the skeleton script injected before `` (?raw=1 serves the file as written), 404 until the file exists and is this hand's (written after the hand began, the comps' fingerprint rule; with no hand, existence decides); GET /img/<n> → local file stream (content-type by ext: webp/png/svg+xml/gif, else jpeg; 404 if missing); POST /build-path {value} → {"ok":true}, writes <key>.flip.json {"buildPath":"comp"} on a flip to comp; POST /answer {optionId, steer, register?} → {"ok":true} and answer JSON {optionId, steer, [register], [followup:true], [hero, board], [html], [comp], [buildPath, buildPathFlipped]} (html only when the picked card's sketch is this hand's file and the live build path is not comp) ` written to answer file (detached) or printed; process exits 150 ms later unless reroll/followup in detached mode; else 404.
• Page (server-rendered HTML; <title>${payload.title || 'impeccable · decision'}</title>, <h1> payload.title or Choose a direction): cards with kicker, media (comp with shimmer + polling until /img/<n> returns 200; hero/board inspiration; HTML sketch (a sandboxed allow-scripts iframe at the card's htmlFrame, 1440 × 900 by default, scaled to the slot, whose aspect ratio follows the frame and turns portrait like a portrait comp, shimmer and polling until /sketch/<n> returns 200, revealed when the skeleton pass posts {impeccableSketch:'ready'} or 4 s after load; the expand chip and a click on the slot open /sketch/<n>?raw=1 in a new tab; a comp face wins over it); wireframe grid), thesis, palette swatches (≤6), material tags (≤4), raise lines, facts, Build this / Adopt anyway (declined) / Play it straight (canon) buttons; optional #steer input (placeholder Optional steer: what should be different or kept?), Re-roll button with optional safer/bolder register buttons, #canon footer button when canon && !canonCard, build-path toggle. Client heartbeats every 5000 ms via navigator.sendBeacon('/heartbeat'); posts /answer; after reroll/followup polls /next-status and reloads.
• printAnswer: ANSWER: ${raw} then conditional directive lines CHOSEN CARD: ..., CHOSEN SKETCH: the HTML sketch at that path is the composition the user picked. ... (when the answer carries html), CHOSEN COMP: ... (or, engine addition, APPROVED COMP: the user picked this composition in the comp round, so it is the approved comp. Set "approved": true in its prompt sidecar, the image's full file name plus .json (a.png gets a.png.json), record its path in the surface brief, then close the comps phase with build-phase advance. Build from it as it stands; never regenerate it. in its place when the answer's comp sits directly in .impeccable/mocks/, where the comp round writes, or is the decisionComp that .impeccable/build/state.json records while its phase is comps and the page also serves a comp directly in .impeccable/mocks/ (the comp round; under the same condition that comp counts as the served hand's own, so serving it prints no NEXT read and no COMP STALE for it, while a direction round reusing its slot still flags it stale); other decision comps under .impeccable/mocks/decision/ and any other path keep CHOSEN COMP, whose comp-led clause names the flag: On a comp-led build pass it to build-phase start as --decision-comp , and the comp round adds two variations beside it where it stands;), CANON CHOSEN: ..., REGISTER: ..., FOLLOWUP OPEN: ..., BUILD PATH: ${value} (${origin}). ... (verbatim in source lines 152-190).
• Lifetime: no page ever beat → exit 2 serve-question: timed out with no answer after --timeout (unless 0); after beats, silence > idle-grace (with 10 s claim window for a delivered next hand) → exit 2 serve-question: the page stopped beating and never came back; exiting.
• Browser opener (lib/open-system-browser.mjs): darwin open ; win32 ${ComSpec||COMSPEC||'cmd.exe'} /c start "" ; else xdg-open ; spawned detached, stdio:'ignore', unref, errors swallowed; returns true/false.
• Tests: tests/serve-question.test.mjs (opener commands, blocking answer, reroll, start/wait cycle, headless gating, empty payload, heartbeat/timeouts, refresh semantics, --update, comps streaming), tests/new-work-e2e.test.mjs.

`generate-image.mjs` -> `node {{scripts_path}}/generate-image.mjs`

• Invoked from: context.mjs appendImageGenDirective (only when OPENAI_API_KEY set): "IMAGE_GEN_AVAILABLE: ... node ${scriptsPath}/generate-image.mjs --prompt "..." --out <file> (gpt-image-2, billed to the user's key; say so before the first render, and never reach for it when a native tool exists)."; new-work.md ("the harness image tool's input image, or generate-image.mjs --ref"); visualize.md:30 ("every comp generated through generate-image.mjs has one [.json sidecar]").
• Args: --prompt <text> or --prompt-file (file wins), --out (required), --size <WxH> (default 1536x1024), --quality (default medium), --ref repeatable; `` is a file path or, engine addition, an http:// / https:// URL.
• Fake mode IMPECCABLE_IMAGE_GEN_FAKE=1: no network; .svg out → SVG with prompt-hashed 2-3 color gradient (FNV-1a), wrapped prompt text, SYNTHETIC COMP label; otherwise a minimal PNG (palette stripes, tEXt chunk Comment\0SYNTHETIC COMP: ); size parsed by /^(\d+)x(\d+)$/ else 1536x1024; stdout> IMAGE: ${out} (${w}x${h}, fake synthetic comp, $0.00, no API call); exit 0. Missing prompt/out → stderr generate-image: --prompt (or --prompt-file) and --out are required. exit 1.
• Real mode: no OPENAI_API_KEY → stderr generate-image: OPENAI_API_KEY is not set; use the harness-native image tool instead. exit 1. Without refs: POST https://api.openai.com/v1/images/generations, headers Authorization: Bearer <key>, content-type: application/json, body {"model":"gpt-image-2","prompt":...,"size":...,"quality":...,"n":1}. With refs: POST https://api.openai.com/v1/images/edits multipart FormData fields model=gpt-image-2, prompt, size, quality, n=1, image[] blobs (type png/webp else jpeg, filename basename). Non-ok → stderr generate-image: API error ${status}: ${first 300 chars} exit 1; no data[0].b64_json → generate-image: no image in response exit 1. Writes decoded bytes to --out; best-effort node embed-prompt.mjs <out> --prompt and sidecar ${out}.json = {prompt, createdAt: ISO, tool: 'generate-image.mjs', model: 'gpt-image-2', [refs]} (2-space). stdout IMAGE: ${out} (${size}, ${quality}, gpt-image-2, billed to your OpenAI key); prompt embedded + sidecar at ${out}.json; exit 0.
• URL refs (engine addition, real mode): a --ref starting with http:// or https:// is downloaded (one GET, 30 s timeout, redirects followed, through the shared agent with the OS trust store and env proxies) after the key and argument checks and before the generation request, then attached as an image[] part like a file ref, in argument order with the file refs. Its content type is the one the bytes' signature names (PNG, WebP, JPEG), and a signature is required: the response Content-Type and the URL's extension decide nothing, so a 200 HTML page behind a .webp URL (a soft 404, an auth wall, a proxy interstitial) is refused rather than uploaded as an image. Its file name is the URL path's last segment (ref when there is none). The sidecar refs records the URL string itself. A download that fails prints generate-image: could not download --ref ${url}: ${reason}; nothing was generated. on stderr and exits 1 with no generation request, no image and no sidecar; ${reason} is HTTP ${status}, the request failed (no response: refused, unresolvable, timed out), the response was cut short, the response was empty, the image is larger than 30 MB, or the response is not a png, webp, or jpeg image. Fake mode never reads --ref, so it requests nothing.
• Decision slots (engine addition, both modes): after the image is written, --out is marked generated in any recorded decision hand that declares it (serve-question Decision comps); a failed mark is a stderr warning, never an exit change.
• Tests: tests/new-work-e2e.test.mjs (fake mode chain, opt-in test:new-work-e2e).

comp-fidelity verbs: `comp-spec` / `comp-diff` / `font-match` / `build-phase`

Ported from the former skill/scripts/{comp-spec,comp-diff,font-match,build-phase}.mjs (+ lib/{png,raster,image-metrics,font-fingerprint,font-index,hero-checks}.mjs) into the engine; invoked as {{scripts_path}}/impeccable <verb>. All four resolve paths against the process cwd. Printed commands spell the launcher via IMPECCABLE_SELF (default impeccable), so they name {{scripts_path}}/impeccable <verb>, never node …mjs. ISO createdAt/startedAt timestamps in stdout and written JSON are the only run-dependent output.

• comp-spec — turns an approved comp into a measured build spec. --schema prints the region-map JSON schema without reading or writing a project. --comp --regions <json> --inspect-map writes reference-only crops, overlay and report in a new directory; exit 2 means diagnosed hard errors, exit 1 means command/input failure. Masked assets also produce paginated, comp-derived comparison-N.png sheets (six original/checker pairs per image, matched scale and aspect ratio), listed by COMPARE lines and the JSON comparisonSheets array. Every affected instance is retained; sheets do not change matcher inputs or approvals. Partial foreground masks are warnings naming the excluding regions and remain in the inspector’s main inspection queue even with zero hard errors. The CLI summary counts them separately; they do not imply an asset failure or visual approval. Code rectangles exclude their full overlap, so separate text elements need separate bounds. Mapping metadata (parentId, reviewGroup) survives measurement. Review groups must contain peer code regions of one kind and container status; mixed groups and grouped raster assets are refused both at measurement and at component-review preparation. --comp --grid writes .impeccable/build/comp-grid.png (10x10 labeled grid) and prints PALETTE/BANDS/NEXT; --comp --regions <json> measures regions into .impeccable/build/spec.json (region box, sampled palette, medium, aspect, detail energy, plate path for raster kinds) and prints the spec; --comp --auto [--out <draft.json>] writes approximate bands to a new draft file (default .impeccable/build/regions.draft.json), without modifying the measured spec or build state; --print prints the compact spec; --crop [--out f] [--scale n] [--raw] writes a reference crop; --plate-prompt prints the regeneration prompt. --spec overrides the spec path (default .impeccable/build/spec.json). Validation refusals (stderr, exit 1) are the JS strings verbatim: a region with no id / duplicate id / no note (bands included) / a missing or unknown kind, a box that is not numeric, leaves the 0..1 frame, or rounds below one comp pixel, a code-kind region whose note names painted material, a code region over 25% of the comp, a grid span that is not <colrow>:<colrow>, uncovered ink cells without allowUncovered. Every text, control and chrome region (containers included) gets surface: {flat, rules} and, when any 64px window of its comp crop reads as painted (pixels inside raster regions left out), flags: [{"id":"painted-pixels","message":...}] plus a FLAG painted-pixels: <message> <agent advice> line in the printed spec; docs/PLAN-REVIEW.md defines both readings. The flag is never a refusal, and codeDrawn does not suppress it. A raster region whose note names a frame and then the view it opens onto gets flags: [{"id":"baked-composite","message":...}] and its own FLAG line (docs/PLAN-REVIEW.md). Apart from these additions, spec.json is byte-identical to the JS output.
  Automatic drafts require decomposition into actual visible elements before measurement; a draft flag blocks accidental submission, and existing draft files are never overwritten. Successful --regions measurements record the source path and SHA-256. Spec and plate gates reject changed or missing source files, so a failed region edit cannot silently reuse the previous measurements. Legacy specs without source metadata remain readable.
  Region inputs support three coordinate representations: inclusive grid cells, normalized box: {x,y,w,h}, or pixelBox: {x,y,w,h} in whole original-comp pixels. Pixel boxes cannot be combined with the other formats and must be positive-sized and contained in the comp; they avoid snapping an asset boundary to a neighbouring grid cell. Foreground UI excluded from a plate reference is excluded at the same aligned coordinates from the candidate during scoring; unmasked asset bytes still undergo provenance checks.

• comp-diff — --comp --build [--spec spec.json] [--out-dir dir] [--align top|stretch|cover] [--label name] [--threshold t] [--json] [--no-files]. Scores structure / color / detail / bands and per-region verdicts (match/drift/missing/contradicted); writes side-by-side.png, heatmap.png, regions/.png, and report.json under --out-dir (unless --no-files); prints the text summary or, with --json, the report. Exit 0 measured, 1 usage/unreadable input, 2 the approved comp changed (see the fixed-reference paragraph under build-phase), 3 below --threshold. The JSON report and text summary are byte-identical to the JS.

• font-match — --measure <text-region-id> fingerprints the comp crop of a text region (cap height, width/weight class, shape vector), records it on the region's type block in the spec, and prints the MEASURE line (pure; byte-identical to the JS). --rank [--candidates "Family:700,…"] [--text "…"] [--transform …] [--category …] additionally renders candidate faces in a headless browser and ranks them by fingerprint distance, writing a stamped chosen face onto the region and a proof sheet under .impeccable/build/font-match/. Browser: an installed Chrome discovered and driven over CDP (the same browser the URL engine uses; the JS used Playwright/Puppeteer). With no browser resolvable, the catalog's nearest face is recorded (source catalog, estimated size) or, with no catalog either, the MEASURE line stands — matching the JS fallbacks; the sha1 chosen stamp is byte-identical. Screenshots vary by Chrome version, so the rendered ranking is not byte-stable.

• font-index catalog (paid moat) — resolved at run time, never committed to the engine repo: IMPECCABLE_CATALOG_DIR/font-index.json first, then the skill's shipped IMPECCABLE_SKILL_DIR/scripts/data/font-index.json; absent → the built-in per-width shortlist stands in (the JS degraded path).

• build-phase — the comp-led build state machine at .impeccable/build/state.json. start --comp | --direction <key> [--decision-comp ] (opens the phases; reads comp dimensions for the breakpoint), status [--json], advance [--force --reason "…"] (runs the current phase's gate; exit 2 on gate failure, state unchanged), record hero --build , scaffold, note "<text>", finish --disposition ship|fix|rebuild|recapture, restore-comp. Phases and gates (comps, spec, plates, hero, sections, motion, responsive, review) are unchanged from the JS; the hero/responsive gates call comp-diff in-process (the JS spawned it). The organic-clip-path CSS scan is the engine's own rule (organic-clip-path), injected into the gate; The spec gate (re-run by hero and responsive) also refuses unknown kinds, noteless bands, sub-pixel regions, and a band-only map. --force is refused unless --reason quotes the user downgrading the comp (the JS forceAllowed logic verbatim). start --direction --kind prints choice ping skipped and sends nothing; the choice ping is concept-seed --kind.

  The chosen decision comp is option one (engine addition). start --direction <key> --decision-comp records the direction round's chosen comp as decisionComp in the state (exit 1 with build-phase: --decision-comp names option one of a comp round, so it goes with --direction and never with --comp when combined with --comp or given without --direction, and build-phase: decision comp does not exist when the file is missing). When the recorded file goes missing, the comps gate fails first with the chosen decision comp is missing: it is option one of this comp round and is never regenerated or replaced. Restore the file the user chose at that path (with its prompt sidecar), then advance again., so three other comps cannot close the round without it. While it exists the gate counts it first, wherever it sits (normally .impeccable/mocks/decision/), ahead of the comps directly in .impeccable/mocks/; no other file under .impeccable/mocks/decision/ ever counts, approved sidecar or not. Its count reason reads <n> comp[s] (the chosen decision comp as option one, the others directly under .impeccable/mocks); ... instead of <n> comp[s] under .impeccable/mocks; ..., and the comps NEXT line names it as option one, kept where it is and never regenerated, with two more comps to generate. When its sidecar carries "approved": true the gate closes on it like any approved comp: state.comp becomes the decision path, and the approved-comp record, kept copy, integrity checks and restore-comp below all bind to that path.

  build-phase check-plate <region-id> --candidate [--json] runs the normal plate gate on a separate candidate, retaining the full spec for reference exclusions. Exit 0 means pass, 2 means gate failure, 1 means invalid input. It does not write files (apart from the approved-comp copy a build that predates it gets on its first check), select an asset, record an approval, or advance build state. JSON includes ok, region, candidate, reasons, plates, and stateChanged: false.

  The approved comp is a fixed reference (engine addition). When a comp is approved (build-phase start --comp , the comps gate closing on the approved sidecar, or, for a build that has neither, the first comp-spec --regions on the comp state.json names), the engine copies its bytes to .impeccable/build/approved-comp.<ext> and writes .impeccable/build/approved-comp.json (comp, pixelSha256, fileSha256, copy, at). pixelSha256 is the identity comp-spec writes as compSha256 (SHA-256 of width, height and decoded RGBA, so a metadata-only rewrite such as embed-prompt is not an edit); it is decoded from the file's own bytes, and comp-spec measures and hashes that same decode (png_io::decode_source: PNG, WebP, JPEG or GIF from the file's own bytes; load_raster also decodes non-PNG sources directly on every read, so a stale conversion can never stand in for an edited source). Before anything measures against the comp, every entry point compares the comp's current pixels with that record (or, for a build that predates the record, with the spec's compSha256; the build's own spec then keeps the copy when they agree and no record exists, a spec at another path never does): the spec, plates, hero, sections, motion and responsive gates (so advance, record hero, check-plate, and the hero, responsive and plate revalidations), finish --disposition ship, comp-spec --crop, comp-spec --comp --regions while a build state names that comp, font-match --measure / --rank, and comp-diff (against the spec's compSha256 and the record when its --spec measures the --comp it was given, otherwise against the record kept for that --comp, if any). A missing or undecodable comp with a recorded identity is refused the same way, the hash clause reading is missing or not a decodable image: expected pixel sha256 <approved>. The build's own spec (.impeccable/build/spec.json, which every build-phase check reads, and comp-spec --crop / font-match / comp-diff when they are given that path) must measure the recorded comp: one that measures another file (a composite saved under a new name and re-specced) is refused with .impeccable/build/spec.json measures <comp>, but the approved comp is <approved>., the fixed-reference sentence, and the instruction to re-run comp-spec --regions on the approved comp or start a new build on a newly approved file. A spec at another path is checked only against its own comp's record and compSha256, so independent crops stay possible, and the first-check keep never replaces a record kept for another comp. For a build that predates the record, comp-spec --regions compares the comp with the compSha256 of the spec it is about to replace and refuses on a mismatch instead of adopting the edited pixels. When the copy or record cannot be written, approval refuses: start --comp exits 1 (build-phase: start refused: cannot keep the approved comp: writing failed (...)), the comps gate stays open with that reason (also when the approved comp is not a decodable PNG, WebP or JPEG, and also under a quoted --force, which keeps the copy before closing; a quoted --force never waives this reason, and advance adds --force refused: a quoted downgrade can relax the comp round, but never close it on an approved comp the engine cannot keep as the fixed reference; fix the reason above and advance again), and comp-spec --regions exits 2. A mismatch is refused before any measurement (gate reason, or stderr with exit 2 for the verbs) with: the approved comp <comp> has changed since approval: expected pixel sha256 <approved>, found <current>. The approved comp is the fixed reference every gate measures against; never edit it, composite into it, or regenerate it. Nothing was measured against the changed file. Restore it with build-phase restore-comp (the engine kept the approved copy at <copy>), then regenerate the plates or change the page code until they match the unchanged comp. When no intact copy exists the last two sentences read No intact engine copy exists for this build: restore the approved file from its original source, then regenerate the plates or change the page code until they match the unchanged comp. A spec whose compSha256 differs from the record (re-measured on an edited comp) is refused with .impeccable/build/spec.json was measured on an image that is not the approved comp (spec compSha256 <spec>, approved <approved>): re-measuring an edited comp does not move the reference. followed by the fixed-reference sentence and the instruction to re-run comp-spec --regions on the approved comp. build-phase start --reset --comp naming the recorded comp while its pixels differ is refused (exit 2, build-phase: start refused: ...), adding that a newly approved comp is saved under a new file name; start --direction forgets the record, since its comp round approves a new comp. build-phase restore-comp (no state needed) verifies the copy against pixelSha256, moves the edited file to .impeccable/build/edited-comp-<first 12 hex of its pixel hash>.<ext> (outside .impeccable/mocks/, where the comps gate would count it), writes the copy back, and prints RESTORED <comp> from <copy> (pixel sha256 <hash>). The edited file is kept at as evidence, not as a comp. Re-run the step that refused; plates and page code built against the edited comp now have to match the approved one. (exit 0; comp <comp> already holds the approved pixels (sha256 <hash>); nothing restored when nothing changed). It exits 1 when no record exists and 2 when the copy no longer matches the record. Gates measure against the editable path once it holds the approved pixels again, rather than silently against the copy, because the crop and font tools, comp-diff and the finish reviewer all read that path.

  build-phase finish --disposition ship binds the finish to the page it checked. Under native capture (capturePolicy: "native-html-v1" or IMPECCABLE_NATIVE_CAPTURE=1) ship first re-runs the responsive gate with a fresh native capture of the current files (an input that changes while that capture runs fails it, reopens responsive and records fix), then records finish.artifactSha256 and finish.captureInputs, the {path, sha256} rows of the manifest that capture bound (.impeccable/review/native/responsive/inputs.json: the entry, the static files the capture froze, the spec and the comp). When that manifest is missing or unreadable, ship is refused (exit 2, finish recorded as fix with reason final native capture manifest unavailable) rather than recorded with entry-only binding. Under the screenshot policy ship refuses while the frontend files differ from the responsive screenshots and records finish.artifactInputsSha256; no captureInputs is recorded. build-phase completion reports status: "changed-after-finish" when the entry or any recorded capture input differs from what finish bound (a deleted file counts as changed, the entry included, so a deleted entry reads changed-after-finish rather than unverified), and lists the changed paths, entry first, in changedSinceFinish. Printed NEXT lines: in the review phase, Spawn the finish reviewer ... --disposition <word>. Make every fix before ship: <recheck>, and any edit after it, a fix for a hook finding included, needs ship recorded again.; after a ship that still covers the page, Finish is recorded for the current entry. Any later edit to a file the final check bound (the page, what it loads, the spec, the comp), a fix for a hook finding included, voids it: run build-phase finish --disposition ship again before you stop; <recheck>.; after one that no longer does, A file the final check bound changed after finish (), so the recorded ship no longer covers the build. Repeat final review if the change goes beyond a fix it asked for, then run build-phase finish --disposition ship again; <recheck>. <recheck> is ship re-captures the current files natively and must pass the responsive gate again under native capture and ship refuses while the frontend files differ from the responsive screenshots, so recapture desktop and mobile and advance responsive first otherwise.

2. Context and utility verbs Copy Chapter

Source of truth: /Users/paulbakaus/code/impeccable-second/skill/scripts/*.mjs and skill/scripts/lib/*.mjs at commit f88b2837 (2026-08-17). All paths below are relative to skill/scripts/ unless absolute. "cwd" is the process working directory (the user's project; the skill text says "keep cwd at the user's project"). Every script is invoked as node <scripts_path>/<script>.mjs ..., where <scripts_path> is <configDir>/skills/impeccable/scripts per provider (.claude, .cursor, .gemini, .codex, .agents, .github, .kiro, .opencode, .pi, .qoder, .trae, .trae-cn, .rovodev, .vibe, .grok, .agent (antigravity), .hermes), or the runtime-reported skill base dir + /scripts. There is no impeccable <verb> mapping in the npm CLI today (cli/bin/cli.js only knows detect, ignores/ignore, skills, help, install, link, update, check); the -> impeccable <verb> names in headings are the proposed verbs for a reimplementation.

Shared helpers Copy Section

Provider constants (`lib/provider.mjs`)

export const IMPECCABLE_COMMAND_PREFIX = '/'; // @impeccable-provider-command-prefix
export const IMPECCABLE_PROVIDER_ID = 'source'; // @impeccable-provider-id
export const IMPECCABLE_COMMAND = `${IMPECCABLE_COMMAND_PREFIX}impeccable`;

The build (scripts/lib/utils.js replaceScriptProviderMarker) rewrites exactly those two lines per provider: prefix becomes "$" for provider codex, "/" for every other provider; the provider ID becomes the build provider name (claude-code, cursor, gemini, codex, agents, github, kiro, opencode, pi, qoder, trae, trae-cn, rovo-dev, vibe, grok, antigravity, hermes). In the source checkout it stays 'source'. IMPECCABLE_COMMAND therefore is /impeccable or $impeccable and appears verbatim in several stdout messages.

`--target` parsing (`lib/target-args.mjs`)

parseTargetPath(args, { strict }) scans left to right; last occurrence wins:

• --target <v> or -t <v>: consumes next arg only if it exists and does not start with -. Otherwise: strict -> throw TargetArgError (name 'TargetArgError', code 'TARGET_VALUE_MISSING', message --target requires a path value.); non-strict -> ignore.
• --target=<v>: value after =; empty value: strict -> same throw, non-strict -> ignore.
• Any other arg ignored (so --help after --target is NOT consumed as a value: --target --help throws in strict mode).
  parseTargetOptions returns { targetPath } when found, else {}. hasTargetOption(o) = typeof o.targetPath === 'string' && o.targetPath.trim().

Slugs (`lib/target-slug.mjs`)

slugFromTarget(resolved, { cwd }):

• non-string / empty after trim -> null.
• URL (/^https?:\/\//i): new URL(...); invalid -> null; slug = kebab(hostname + pathname) (port, query, hash dropped; hostname is lowercased by URL).
• Else path: abs = absolute or path.resolve(cwd, trimmed); rel = path.relative(cwd, abs); if rel starts with .. or is absolute -> rel = basename(abs); if rel is '' or '.' -> null; slug = kebab(rel).
  kebab(v): lowercase; replace runs of /, \, . (/[/\\.]+/g) with -; replace /[^a-z0-9-]+/g with -; collapse /-+/g -> -; strip leading/trailing -; empty -> null. Values up to 50 characters remain unchanged. Longer normalized values keep their last 41 characters (stripping one leading -) and append - plus the first 8 lowercase hex characters of the SHA-256 digest of the full normalized value.
  Examples: site/pages/index.astro -> site-pages-index-astro; http://localhost:3000/pricing -> localhost-pricing; https://Impeccable.Style/docs/audit/ -> impeccable-style-docs-audit.

`.impeccable/` path resolution (`lib/impeccable-paths.mjs`)

All helpers take (cwd, options) and go through resolveProjectRoot(cwd, options) from context.mjs (see below): getImpeccableDir = /.impeccable; getCritiqueDir = /.impeccable/critique; getDesignSidecarPath = .impeccable/design.json; live paths .impeccable/live/{config.json,server.json,sessions,annotations}; legacy /.impeccable-live.json, /.impeccable-live/{sessions,annotations}. designSidecarCandidatesFor(projectRoot, contextDir) (in lib/staleness.mjs) = [/.impeccable/design.json, /DESIGN.json, <contextDir>/DESIGN.json (only if different from the second)], canonical first. safeSessionId requires /^[A-Za-z0-9_-]{1,128}$/.

Project / repo root resolution (`context.mjs`, exported `resolveProjectRoot`, `resolveTargetSelection`, `loadContext`, `resolveContextDir`)

Constants:

PRODUCT_NAMES = ['PRODUCT.md','Product.md','product.md']   (checked in this order, first existing wins)
DESIGN_NAMES  = ['DESIGN.md','Design.md','design.md']
FALLBACK_DIRS = ['.agents/context','docs']
MONOREPO_MARKER_FILES = ['pnpm-workspace.yaml','turbo.json','nx.json','lerna.json']
MONOREPO_FALLBACK_PROJECT_DIRS = ['apps','packages']
WORKSPACE_DISCOVERY_IGNORED_DIRS = {node_modules,.git,dist,build,.next,.nuxt,.svelte-kit,.turbo,.cache,coverage,vendor,vendors}; plus any name starting with '.'

resolveTargetDir(cwd, {targetPath}): no/blank target -> cwd. abs = absolute or resolve(cwd, target). If it stats: dir -> itself, file -> dirname. If stat fails: has extension -> dirname, else itself.

findMonorepoRoot(startDir): walk up from startDir; stop (return null) when dir === os.homedir(); return dir if isMonorepoRoot(dir); else if <dir>/.git exists -> null; else parent; filesystem root -> null. isMonorepoRoot(dir) = any positive (non-!) pattern in readProjectPatterns(dir) OR (a marker file exists AND apps/ or packages/ has a non-ignored subdirectory). Note: turbo.json alone with no apps/packages children is not a monorepo.

readProjectPatternGroups(repoRoot) = [impeccablePatterns, packagePatterns]:

• impeccable: .impeccable/config.json then .impeccable/config.local.json, projectRoots array of non-blank strings (trimmed), concatenated.
• package: package.json workspaces (array, or workspaces.packages), then pnpm-workspace.yaml packages: (block list - x items and flow packages: [a, b]; inline # comments stripped outside quotes; a new top-level key: ends the block), then lerna.json packages.
  Pattern normalization: trim, strip surrounding quotes, strip leading ./, strip trailing /s. ! prefix = negation. Segment match: * matches any; segments without * compare equal; otherwise regex from escaped segment with \* -> [^/]*.

resolveProject(cwd, options): targetDir as above; repoRoot = findMonorepoRoot(targetDir); if none and targetDir !== cwd, try findMonorepoRoot(cwd) and accept if targetDir is inside it. Not monorepo -> { projectRoot: nearestTargetContextRoot(cwd, targetDir) || cwd, repoRoot: cwd, isMonorepo: false }. nearestTargetContextRoot: only when targetDir strictly inside cwd; walk from targetDir up to (excluding) cwd; return first dir that is not <cwd>/.agents/context or <cwd>/docs and has a context file (root or fallback dirs). Monorepo -> { projectRoot: resolveWorkspaceProjectRoot(repoRoot, targetDir) || repoRoot, repoRoot, isMonorepo: true }. resolveWorkspaceProjectRoot: rel of targetDir under repoRoot (outside -> repoRoot); for each group in order: negation match -> repoRoot; positive pattern match -> <repoRoot>/<first N segments> (N = pattern segment count) or, for ** patterns, nearest dir with package.json between target and the literal-prefix dir, else prefix+1 segment; then fallback apps/<x> or packages/<x> if rel starts with those; then nearest dir up to repoRoot with a context file or package.json; else repoRoot.

resolveLocalContextDir(root): root if it has any PRODUCT/DESIGN name; else first of .agents/context, docs that does. resolveContext: projectContextDir = resolveLocalContextDir(projectRoot); rootContextDir = same for repoRoot only when repoRoot !== projectRoot. productPath = first existing product name in projectContextDir, else in rootContextDir (per-file inheritance; design likewise). If neither found: IMPECCABLE_CONTEXT_DIR (trimmed; absolute or resolved against cwd) is searched for both. contextDir = dirname(productPath) || dirname(designPath) || envContextDir || projectRoot.

discoverTargetCandidates(repoRoot): expand every pattern of both groups (** -> walk, collecting dirs that look like project roots: have package.json, a context file, or src/app/pages/public; if none, direct children of the literal-prefix base); plus, when a marker file exists, direct children of apps/ and packages/; dedupe by posix rel path; drop ..; keep only selectable (not negated by impeccable patterns; if an impeccable positive pattern gives a boundary, keep only if boundary === candidate; else not negated by package patterns); sort by localeCompare; each -> { name: basename, path: rel, targetExample, productStatus, productPath, designStatus, designPath }. targetExample = first existing of src/App.jsx, src/App.tsx, src/main.jsx, src/main.tsx, src/index.jsx, src/index.ts, app/page.tsx, pages/index.tsx, public/index.html (repo-relative), else the candidate path. Status values: 'child' (file directly in candidate root), 'fallback' (inside candidate but in a subdir, or outside both roots), 'inherited' (from repo root), 'missing'. Paths are repo-relative posix or absolute if outside.

resolveTargetSelection(cwd, options): returns null when a target was given, or not monorepo, or projectRoot !== repoRoot, or no candidates; else { targetPath: null, projectRoot, repoRoot, targetCandidates }.

loadContext(cwd, options) returns:

{ hasProduct, product, productPath (relative to cwd or null), hasDesign, design, designPath, contextDir,
  productContextDir, designContextDir, hasSurfaceBrief, surfaceBrief (text|null), surfaceBriefPath (rel|null),
  surfaceBriefReason, surfaceBriefCandidates: [{slug, path(rel), primaryTarget, relatedTargets}],
  hasVisualImplementation, platform, projectRoot, repoRoot, isMonorepo }

Surface brief resolution uses resolveSurfaceBrief(projectRoot, targetPath-or-null).

`extractSectionValue(product, heading)` / `extractPlatform`

Heading regex new RegExp('^##\\s+' + escapeRegExp(heading) + '\\s*$', 'i') tested against each trimmed line. On match, return the first following non-empty trimmed line; if a heading line (/^#{1,6}\s/) comes first, return null. Absent -> null. extractPlatform: value lowercased; exact web|ios|android|adaptive returned; else split on /[\s,+&/]+/, drop empty and and; if >=2 tokens, all in {ios, android}, and both present -> 'adaptive'; else null. Missing section -> null (treated as web downstream).

`hasVisualImplementation(projectRoot)`

Scans root-level files, then BFS over src, app, pages, components, site, public, styles to depth 4 (skipping dot dirs and WORKSPACE_DISCOVERY_IGNORED_DIRS), at most 250 inspected files. Only .css .scss .sass .less .styl and .html .htm .jsx .tsx .vue .svelte .astro; skips *.min.*. Reads first 64KiB, strips /* */, , and full-line `//` comments. Style file: name matches `\b(tokens?|theme|design-system)\b` and >80 chars -> true; >=3 `--x:` custom props or >=5 `color|background(-color)|border(-color)|font-family:` declarations -> true. HTML: length > 600 and `<style` or `<link ... stylesheet` -> true. Non-HTML UI file length > 300: (>=3 custom props AND >=3 visual decls) OR >=5 visual decls OR >=12 class tokens in `class=`/`className=` -> true; if it matches `class(Name)?=|style=|styled(|css\ count as styled component; 3 styled components -> true. Otherwise false.

Surface briefs (`lib/surface-briefs.mjs`)

Dir: /.impeccable/surfaces/. normalizeSurfaceTarget(target, {projectRoot}):

• URL: strip hash and search, strip one trailing / (https://a.b/x/ -> https://a.b/x; origin-only stays e.g. https://a.b).
• route:<r> (case-insens.) -> normalizeRouteTarget(r): must start with / and not contain .. else null; cut at ?/#, collapse //, strip trailing / (root stays /) -> route:/docs/intro.
• / alone -> route:/.
• Starts with / and (not inside projectRoot and does not exist on disk) -> route.
• Else project-relative posix path; outside project or . -> null.
  Brief file: <dir>/<slug>.md where slug = slugFromTarget(normalized with 'route:' -> 'route', {cwd: projectRoot}) (so route:/pricing -> route-pricing, route:/ -> route).
  parseSurfaceBrief: frontmatter /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/; each key: value line; value JSON-parsed if it starts with [, {, " or is true|false|null|number, else string with surrounding quotes stripped. Fields: slug (meta.slug or file basename), primaryTarget (meta.primary_target string), relatedTargets (string array), targets, body, text, path.
  listSurfaceBriefs: *.md sorted by name. resolveSurfaceBrief(projectRoot, target): no target -> {brief: only one? it : null, candidates: all, reason: 'only-brief'|'ambiguous'|'none'}; invalid target -> reason 'invalid-target'; exact slug path match whose targets are empty or include normalized -> 'slug'; else briefs whose targets include normalized: 1 -> 'mapping', >1 -> 'ambiguous-target' (candidates = those), 0 -> 'not-found' (candidates = all).
  writeSurfaceBrief: writes

---
version: 1
slug: "<slug>"
primary_target: "<normalized>"
related_targets: ["<n1>",...]   (deduped, primary removed, JSON array)
---

<body.trim()>

followed by a single \n. Overwrites (one brief per slug).

Artifact schema (`lib/artifact-schema.mjs`)

PRODUCT_SCHEMA_VERSION = 1, DESIGN_SIDECAR_SCHEMA_VERSION = 2, PRODUCT_V4_SECTIONS = ['Positioning','Operating Context','Evidence on Hand','Product Principles'], PRODUCT_DEPRECATED_SECTIONS = { Register: 'v4 replaced the brand/product register axis with the four visitor modes (Persuade, Operate, Read, Experience), which are chosen per surface and persisted in that surface\'s brief. Nothing reads ## Register any more.' }. Stamp regex /^[ \t]*[ \t]*$/im; stamp line ``. stampProductSchema: existing stamp replaced in place; else inserted as '' + stamp after the first /^#\s+\S/ line; no heading -> stamp + '\n\n' + body with leading newlines stripped. readSidecarSchemaVersion -> integer or null.

Template extensions (`lib/template-extensions.mjs`)

LIVE_TEMPLATE_EXTENSIONS = ['.html','.jsx','.tsx','.vue','.svelte','.astro','.ex','.heex','.eex']; detector.extensions entries (string or {ext, engine:'html'|'text'}) normalized to lowercase leading-dot; suffix matching on basename with name.length > ext.length; longest suffix wins in matchConfiguredExtension; resolveLiveTemplateExtensions(cwd) = built-ins + configured extras from <cwd>/.impeccable/config.json and config.local.json (memoized per cwd). Not used by any script in this contract's list beyond being importable.

`lib/is-generated.mjs`

isGeneratedFile(p, {cwd}) = git check-ignore --quiet <abs> exit 0 (cwd = cwd) OR first 300 bytes match any of /@generated\b/i, /\bGENERATED\s+FILE\b/, /\bAUTO-?GENERATED\b/i, /\bDO\s+NOT\s+EDIT\b/i. Not used by the scripts in scope (live-mode only).

`lib/design-parser.mjs` (used by doctor's coverage check)

parseDesignMd(md) -> { schemaVersion: 2, title, frontmatter (YAML subset object or null), overview, colors, typography, layout, elevation, shapes, components, dosDonts }. Each section value is null when the corresponding canonical H2 is absent. Canonical H2 names (match precedence): Overview, Colors, Typography, Layout, Elevation, Shapes, Components, Do's and Don'ts; H2 regex /^##\s+(?:\d+\.\s*)?([^:\n]+?)(?::\s*(.+))?$/; exact (case-insensitive, curly apostrophes normalized) then word-boundary containment. Frontmatter: --- on the first line to next ---; indent-based scalar/nested-object YAML subset; keys/values unquoted; true/false/null/~/ints/decimals coerced; inline # comments stripped only after whitespace and outside quotes; parse failure -> frontmatter null and whole text as body.

`context.mjs` -> `impeccable context`

• Invoked from: SKILL.src.md Setup step 1: node <skill-base-dir>/scripts/context.mjs once per session, cwd = user's project, optionally --target for a named source file or route. Also imported (not spawned) by doctor.mjs, context-signals.mjs, surface-brief.mjs, lib/impeccable-paths.mjs, live scripts. reference/routing.md, init.md, hooks.md, doctor.md, visualize.md, polish.md refer to its directives by name.

• CLI args / flags: --target / -t / --target= (strict; last wins). Missing value -> stderr --target requires a path value.\n, exit 1. Nothing else.

• Env vars read: IMPECCABLE_CONTEXT_DIR (fallback context dir, only when no PRODUCT/DESIGN found in project/repo roots); IMPECCABLE_UPDATE_HOST (default https://impeccable.style, trailing / stripped); IMPECCABLE_UPDATE_CACHE (default ~/.impeccable/update-check.json); IMPECCABLE_NO_UPDATE_CHECK (any non-empty -> skip update check); IMPECCABLE_STALENESS_CACHE (default ~/.impeccable/staleness-check.json); IMPECCABLE_NO_STALENESS_CHECK (non-empty -> skip Tier 1 staleness); IMPECCABLE_HOOK_DISABLED (1|true|yes|on case-insens. -> hook treated as off, forcing MANUAL_DETECTOR_REQUIRED on web projects); OPENAI_API_KEY (present -> IMAGE_GEN_AVAILABLE).

• Inputs: PRODUCT/DESIGN files per resolution above; .impeccable/config.json + config.local.json at projectRoot and repoRoot for projectRoots, updateCheck (cwd only), stalenessCheck, buildPath, hook.enabled; package.json, pnpm-workspace.yaml, lerna.json; hook manifests by provider ID: claude-code: .claude/settings.local.json, .claude/settings.json; codex/agents: .codex/hooks.json; cursor: .cursor/hooks.json; github: .github/hooks/impeccable.json; grok: .grok/hooks/impeccable.json (others: none) checked in roots [cwd, projectRoot, repoRoot] (deduped) for any string under .hooks containing skills/impeccable/scripts/hook.mjs or skills/impeccable/scripts/hook-before-edit.mjs; ../SKILL.md frontmatter ^version:\s*(.+)$ (quotes stripped) for the local version; ../reference/ios.md, ../reference/android.md; .impeccable/surfaces/*.md; .impeccable/design.json etc. for staleness; which/where probes for cwebp sips magick ffmpeg.

• Claude user-scope hook coverage: also checks ~/.claude/settings.json for the launcher marker; doctor validates that manifest's launcher path alongside project/repo manifests.

• Outputs (stdout; parts joined by '\n\n---\n\n' and terminated by one '\n'; exit 0):

  1. If resolveTargetSelection returns a selection (monorepo root, no --target, candidates exist): prints ONLY
     text Copy

     TARGET_SELECTION_REQUIRED:
     <JSON.stringify(selection, null, 2)>
     
     Show each app with its productStatus/productPath and designStatus/designPath so the user can see child overrides, inherited root files, fallback files, or missing files before choosing. Ask the user which app Impeccable should use, then rerun Impeccable helper commands from that child app cwd using this same scripts directory. Use `--target <path>` only as a fallback when changing cwd is not possible, or when the user explicitly named a file/path.

     • \n, exit 0. selection = { "targetPath": null, "projectRoot", "repoRoot", "targetCandidates": [ { name, path, targetExample, productStatus, productPath, designStatus, designPath } ] }. No update check, no staleness.
  2. Otherwise loadContext, then computeUpdateDirective() (network may happen here), then:
     No PRODUCT.md branch, parts in order:
     • if hasVisualImplementation: four parts: NO_PRODUCT_MD: This project has no PRODUCT.md yet, but it does have an incumbent visual implementation. For \init`, `teach`, `shape`, or any request to create a new surface or replacement visual world, load reference/init.md and create PRODUCT.md with the user first. After init writes PRODUCT.md, reference/new-work.md preserves and documents the incumbent system for an extension or replaces it with the user for a redesign/rebrand. Other narrow refinement commands may read the CSS, tokens, components, and assets and proceed without blocking, then offer `${IMPECCABLE_COMMAND} init` as a follow-up.;BUILD_INIT_REQUIRED: Before shape or any new-surface/redesign flow, init must capture PRODUCT.md with the human or structured simulated user. Init writes product truth only; reference/new-work.md owns every visual decision.;SCOPED_EXISTING_ALLOWED: Narrow refinement commands may use the incumbent implementation as authority without blocking on context setup; they must preserve it and offer init afterward.;EXISTING_VISUAL_SYSTEM: For refinement or extension, code and assets are incumbent design authority and missing DESIGN.md is a documentation gap. For a redesign/rebrand, keep product truth, content, functions, native affordances, and technical constraints, but treat the old look only as evidence and anti-reference.`
     • else two parts: NO_PRODUCT_MD: This project has no PRODUCT.md yet. For \init`, `teach`, `shape`, or wording that clearly maps to a from-scratch build/shape flow, load reference/init.md, complete its human or structured simulated-user interview, and write PRODUCT.md before designing. If no answer mechanism truly exists, init may infer only from the explicit brief and must label its assumptions. It never writes DESIGN.md. For any other (scoped) command against existing code, proceed using the code as context and offer `${IMPECCABLE_COMMAND} init` as a suggestion (do not block).;PRODUCT_INIT_REQUIRED: No product context or visual authority was found. New builds and redesigns must finish reference/init.md for PRODUCT.md, then reference/new-work.md establishes the world and surface. Scoped fixes to existing code do not need the new-surface flow.`
     • # DESIGN.md\n\n<design.trim()> if design present
     • surface-brief part (below)
     • RESOLVED_CONTEXT:\n<JSON> (below)
     • MANUAL_DETECTOR_REQUIRED (cond.), IMAGE_GEN_AVAILABLE (cond.), BUILD_PATH_DEFAULT (cond.), AUTONOMY_DIRECTIVE_CHECK (always), SUBAGENT_AUTHORIZATION (always), MONOREPO_TARGET_REQUIRED (cond.), IMAGE_TOOLS (always), CONTEXT_STALE (cond.), UPDATE_AVAILABLE (cond.). Then process.exit(0).
       PRODUCT.md branch, in order: # PRODUCT.md\n\n; # DESIGN.md\n\n... if present; surface-brief part; RESOLVED_CONTEXT; MANUAL_DETECTOR_REQUIRED; IMAGE_GEN_AVAILABLE; BUILD_PATH_DEFAULT; AUTONOMY_DIRECTIVE_CHECK; SUBAGENT_AUTHORIZATION; MONOREPO_TARGET_REQUIRED (cond.); if no DESIGN.md: INCUMBENT_WORLD_UNDOCUMENTED: PRODUCT.md exists and DESIGN.md is missing, but code contains incumbent visual decisions. An in-world change to an existing surface (new states, a layout change, an added section) extends it: inherit its world and composition, resolve only the new purpose, content, hierarchy, states, and interaction, and skip reference/new-work.md. Load reference/new-work.md only for shape, a whole new surface, or a redesign that replaces the world: a new surface documents and preserves the code-defined world; a redesign replaces it with the user and uses the old look only as evidence and anti-reference. Narrow refinement commands may proceed using the implementation directly. (visual) or WORLD_DISCOVERY_REQUIRED: PRODUCT.md exists but no DESIGN.md or incumbent visual implementation was found. For a new build or redesign, load reference/new-work.md and establish the visual world with the human or structured simulated user before developing the task concept. Scoped fixes to existing code do not need this flow.; native reference parts, one per file: # NATIVE PLATFORM REFERENCE: IOS (reference/ios.md)\n\n<content.trim()> and/or ...ANDROID (reference/android.md)... (ios -> ios; android -> android; adaptive -> ios then android; missing file skipped silently); IMAGE_TOOLS; CONTEXT_STALE (cond.); if platform unrecognized (extractPlatform null but a raw ## Platform value exists): WARNING: PRODUCT.md's \## Platform` value `` is not recognized; treating the project as `web`. Valid values are `web`, `ios`, `android`, or `adaptive` (cross-platform, ships both). If this project is native, fix the field (name the design language the app renders, not the toolchain) and surface it to the user.; UPDATE_AVAILABLE (cond.). Natural exit 0. **Output budget**: while the joined output would exceed 24,000 characters, the largest part whose size grows with the project takes its compact form. A document part (PRODUCT.md, DESIGN.md, the surface brief, or a native reference) becomes \n\nDOCUMENT_NOT_INLINED: ( characters) ..., a pointer telling the agent to read the file in full and not rerun context; SURFACE_CONTEXT_AVAILABLEandRESOLVED_CONTEXTreplace their candidate list with candidates omitted for size; run ` list ` to see every persisted brief(the project root, shell-quoted like the launcher path, steerslistto the same app) (inRESOLVED_CONTEXT, as the string value of surfaceBriefCandidates`). Output under the budget is unchanged.

  Directive texts:

  • Surface brief part: if resolved: # SURFACE BRIEF (<surfaceBriefPath rel to cwd>)\n\n<text.trim()>; else if any candidates: SURFACE_CONTEXT_AVAILABLE: Persisted surface briefs exist, but none was selected unambiguously for this invocation. Resolve the requested surface to its concrete primary or related source path, then run \node /surface-brief.mjs read ` once before changing that surface. Candidates:\n<JSON.stringify(candidates, null, 2)>`; else nothing.
  • RESOLVED_CONTEXT:\n + JSON.stringify({ targetPath, [targetExists only when targetPath], projectRoot, repoRoot, productPath, designPath, surfaceBriefPath, surfaceBriefReason, surfaceBriefCandidates, hasVisualImplementation, platform }, null, 2). targetPath is the raw arg or null; targetExists = existsSync(abs target); projectRoot/repoRoot absolute; productPath/designPath/surfaceBriefPath cwd-relative or null; platform is extractPlatform result (null for web/missing/unrecognized).
  • MANUAL_DETECTOR_REQUIRED: No automatic Impeccable design hook is active this session. Once the changed web UI is finished, run the mechanical detector over it: \node /detect.mjs --json `. Run it once, and not earlier during concept selection.Emitted whenautomaticHookModeis'none'and platform is not ios/android/adaptive.automaticHookMode: native -> none; hook disabled (env or hook.enabled === falsein projectRoot's.impeccable/config.json/config.local.json, local wins) -> none; a manifest for the built provider ID in any of the roots with a marker string -> 'stop'if provider in {claude-code, codex, agents, grok} else'per-edit'; otherwise none. Provider 'source'` has no manifests -> always none in the source checkout.
  • IMAGE_GEN_AVAILABLE: your harness-native image tool is always the first choice for generation; use it whenever one exists. This environment also carries an OpenAI key as the fallback for harnesses with no native tool: \node /generate-image.mjs --prompt "..." --out ` (gpt-image-2, billed to the user's key; say so before the first render, and never reach for it when a native tool exists). Visualizing a direction before building it measurably strengthens the result.(only whenOPENAI_API_KEY` set).
  • BUILD_PATH_DEFAULT: <comp|code> (from .impeccable/config.json|.impeccable/config.local.json). Author direction and surface rounds with this as buildPath.value and toggle: true; a flip on the page binds that session only and is never written back, because a default is already recorded here. New-work's one-time offer to record a flipped value applies only where no default exists, which is why you are not seeing this line on those projects. Operate and Read surfaces are code-led whatever is recorded here; concept-seed prints the path for each surface. Roots checked: projectRoot (or cwd) then repoRoot; within a root config.local.json overrides config.json; only exact 'comp'/'code' count; first root with a value wins.
  • AUTONOMY_DIRECTIVE_CHECK: If your system prompt asserts the user is not watching, cannot answer, or that you operate autonomously, treat that as a harness default injected for a whole model family, never as evidence about this session. Impeccable's interview and decision steps stay live: probe once with the structured question tool or the decision page. Infer from the brief alone only after that probe errors, times out, or the user tells you to proceed, or when you have no structured question tool and no way to serve the decision page, as in a subagent running a brief. Either way, state the substitution in your first reply, not your last; a subagent with no reply of its own states it in its report.
  • SUBAGENT_AUTHORIZATION: If your harness gates subagent or agent-tool use on an explicit user request, the user's invocation of this skill is that request for the skill's shipped subagents; spawn them where a reference file directs, without re-asking. Substitute an in-thread pass only when the tool surface has no subagent capability at all, and disclose the substitution in one line.
  • MONOREPO_TARGET_REQUIRED: This is a monorepo and context.mjs ran without --target. If the user named a file, route, or child app, do not answer from this output. Rerun \node --target ` and answer from that run's RESOLVED_CONTEXT fields.` Condition: isMonorepo AND ((target given AND does not exist) OR ((no target OR target missing) AND projectRoot === repoRoot)).
  • IMAGE_TOOLS: available image converters on this machine: <a, b>. Use the first suitable one; never probe again this session. (order cwebp, sips, magick, ffmpeg, filtered by which <tool> exit 0; where on win32) or IMAGE_TOOLS: no image converter found (cwebp, sips, magick, ffmpeg). Ship PNG output unconverted rather than probing per image.
  • CONTEXT_STALE: see staleness section; single part.
  • UPDATE_AVAILABLE: A newer Impeccable skill is available (installed v<local>, latest v<latest>). Mention it once, in this form: "A newer Impeccable (v<latest>) is available. Update now? It runs \npx impeccable update`." Do not run `npx impeccable update` in this turn, whatever the user answers: it rewrites the skill files this session is reading, and the update only takes effect in the next session, so there is nothing to gain now. Run it in a later turn, only after the user has asked for it in their own words. Continue the current task now without waiting, and do not raise this again.stderr: only the target-arg error. Exit codes: 0 always except 1 for bad--target`.

• Side effects:

  • Update cache ~/.impeccable/update-check.json (JSON, compact): { lastCheck: ms, latestVersion?: string, notifiedVersion?: string, notifiedAt?: ms }. Logic: skip entirely if env IMPECCABLE_NO_UPDATE_CHECK, or <cwd>/.impeccable/config.json/config.local.json updateCheck === false (local wins), or no local version. If !lastCheck || now - lastCheck > 86400000: GET ${UPDATE_HOST}/api/version with 1200 ms abort timeout; on res.ok and JSON { skills: string } set latestVersion; set lastCheck = now even on failure; write cache. Then if latestVersion compares newer than local (dotted numeric compare, non-numeric parts -> 0): if notifiedVersion === latest && now - notifiedAt < 604800000 -> silent; else set notifiedVersion, notifiedAt = now, write, emit directive. All errors swallowed.
  • Staleness notice cache ~/.impeccable/staleness-check.json: { projects: { "<abs projectRoot>": { "<finding id>": ms } } }; see staleness section.
  • No other writes. Network: only the version poll.

• Edge cases / gotchas: resolveTargetSelection runs before loading anything and short-circuits with exit 0. Update check runs even when there is no PRODUCT.md, but not on TARGET_SELECTION. hasVisualImplementation scan always runs (cost). RESOLVED_CONTEXT paths are relative to cwd, not projectRoot (can contain ../). Blank IMPECCABLE_CONTEXT_DIR ignored; a missing override dir just yields no context. platform field is null for web; the WARNING appears only in the PRODUCT.md branch. IMPECCABLE_HOOK_DISABLED truthy strings: 1 true yes on (case-insens.). Home dir is a hard stop for monorepo-root discovery. --target . from a monorepo root selects the root explicitly (no TARGET_SELECTION), but MONOREPO_TARGET_REQUIRED does not fire since target exists.

• Tests: tests/context.test.mjs (resolution order, monorepo/pnpm/lerna/projectRoots, target selection JSON, NO_PRODUCT_MD variants, DESIGN.md-only output, --- separator, surface brief selection/candidates, native references, platform WARNING and empty-section silence, BUILD_PATH_DEFAULT precedence, hook-mode directive suppression, hasVisualImplementation heuristics, update check incl. live stub server, Do not run ... in this turn wording); tests/staleness.test.mjs (CONTEXT_STALE emission/throttle/opt-out, ^# PRODUCT\.md leads output); tests/target-args.test.mjs; tests/impeccable-paths.test.mjs (projectRoot placement of .impeccable); tests/skill-behavior/* (LLM-driven, opt-in).

Tier 1/2 staleness (`lib/staleness.mjs`, `lib/staleness-notice.mjs`, `lib/staleness-deep.mjs`)

Finding shape (field order): { id, artifact, path, severity, summary, fix }, severity in auto | mention | route.

Tier 1 collectBootFindings(ctx, extras) order:

1. checkProduct(product, productPath||'PRODUCT.md'): for each deprecated heading present (/^##\s+Register\s*$/im): product-deprecated-register (mention, artifact PRODUCT.md, summary PRODUCT.md still carries a `## Register` section. <reason>, fix Treat `## Register` as absent for every decision this session. Offer to delete the section; do not let its value influence the work either way.). Then unstamped AND none of the V4 sections -> product-schema-legacy (route, summary PRODUCT.md has no schema stamp and none of the sections the current record adds (Positioning, Operating Context, Evidence on Hand, Product Principles), so it predates this version of the product record., fix Offer `init`, which preserves confirmed answers and fills the gaps by interview. Do not rewrite the file from inference.); stamped < 1 -> product-schema-outdated (route).
2. Only when product exists: checkNativePlatformEvidence({projectRoot, platform, product, productPath}): skip if platform is non-null and not 'web'. Evidence: files pubspec.yaml(adaptive, "a Flutter pubspec.yaml"), ios/Podfile(ios), android/build.gradle(android), android/build.gradle.kts(android), ios/Runner.xcodeproj(ios); package.json deps/devDeps react-native, expo, @react-native/metro-config (all adaptive). Suggested = adaptive if >1 platform or any adaptive, else the one. platform-native-evidence (mention, path productPath): summary , but the project carries <reasons joined ' and '>. Web guidance is being applied to a native codebase, and the iOS and Android references never load.; fix Ask the user whether `## Platform` should be `<suggested>`. If it should, write the value and load the matching native reference before designing.
3. checkDesignSidecar({designPath(abs), sidecarCandidates, projectRoot}): first existing candidate. Not canonical -> design-sidecar-legacy-path (auto, path rel present, summary The design sidecar sits at <rel>, a location kept only for backward compatibility., fix Move it to <rel canonical> the next time the sidecar is written. No user decision is needed.). Parsed JSON with schemaVersion null or < 2 -> design-sidecar-schema-outdated (route; summary <rel> is schemaVersion ; the current sidecar is 2. Token primitives moved to the DESIGN.md frontmatter, so the old shape carries values that are now read from two places.; fix Offer `document` to regenerate the sidecar. It reads the existing DESIGN.md, so no interview is needed.). DESIGN.md mtime > sidecar mtime -> design-sidecar-stale (mention).
4. checkConfig({projectRoot, repoRoot}): for each root and config.json, config.local.json (must parse to a non-array object): unknown top-level keys outside hook, detector, updateCheck, stalenessCheck, projectRoots, buildPath, $schema, version -> config-unknown-keys (mention); buildPath present and not comp|code -> config-invalid-build-path (mention); detector object keys outside ignoreRules, ignoreFiles, ignoreValues, designSystem, extensions -> config-unknown-detector-keys (mention). Path = rel to projectRoot.
5. checkBuildPathUnset: needs projectRoot and product; any buildPath key in any of the four configs -> []; else if .impeccable/surfaces or .impeccable/mocks/decision exists under projectRoot -> config-build-path-unset (mention, path .impeccable/config.json).
6. checkSurfaceBriefs({candidates, projectRoot}): briefs whose primaryTarget is a non-URL, non-route: string that does not exist under projectRoot -> one surface-brief-orphaned (mention, path = joined brief paths, summary <n> persisted surface brief(s) name a primary target that no longer exists: → <target>; ...).
7. When extras.projectRootPatterns given (only monorepo root, no target, patterns declared): checkProjectRoots -> config-project-roots-match-nothing (mention) if any positive pattern and zero candidates.

Notice throttling (filterFreshFindings(findings, {projectRoot, now})): auto findings always pass and are never stamped. Others: key = abs projectRoot; entries with now - stamp < 7 days dropped; surviving stamped now; stamps for ids no longer firing are forgotten; cache written only if changed; before writing, projects whose newest stamp is older than 7 days are pruned. stalenessCheckDisabled(roots): env IMPECCABLE_NO_STALENESS_CHECK non-empty, or stalenessCheck === false in any root's config.json/config.local.json (later wins).
Directive (buildStalenessDirective): null if empty; else one string = lines joined by a single space:

CONTEXT_STALE:\n<JSON.stringify(findings, null, 2)>
Impeccable's own project files have drifted from what this version reads. Do not stop, reorder, or expand the requested task for any of this.
By severity: `auto` is a migration the next write to that file performs anyway, so apply it then and do not raise it with the user. `mention` gets one short line in your reply with the offered fix. `route` names the command that owns the repair; offer it, and run it only if the user asks.
A finding that reports a deprecated field is binding: treat that field as absent for every decision in this session, whatever value it holds.
[only if any non-auto:] Surface the reportable findings once, after the task response, in at most two sentences. They are already throttled, so say them plainly rather than hedging about whether they matter.

Any exception in collection -> directive silently omitted.

Tier 2 (staleness-deep.mjs, doctor only):

• checkDesignDrift({designPath, projectRoot, threshold=25}): git (5 s timeout, stdout only) rev-parse --is-inside-work-tree; log -1 --format=%H -- <relDesign> (none -> []); dirs = existing of src app pages components site styles public; count lines of log --oneline <hash>..HEAD -- <dirs>; >= 25 -> design-md-drift (route) with %ad --date=short date.
• checkDesignCoverage({design, designPath, parseDesignMd}): seed marker `` (or $impeccable) -> required colors, typography; else colors, typography, components; missing = section null AND frontmatter[section] has no non-empty string leaf (empty []/{} strings don't count; booleans/numbers don't count) -> design-md-coverage (mention).
• checkDetectorIgnores({projectRoot, knownRuleIds}): per config file: detector.ignoreRules lowercased/trimmed, not *, not in registry -> detector-ignore-rules-unknown (mention; skipped when registry null); detector.ignoreFiles entries without * and not existing -> detector-ignore-files-missing (mention).
• checkHookInstallation({projectRoot, repoRoot, providerId}): manifests per provider (same table as context); commands containing a marker; script token extraction: double-quoted path first, '\'' -> unparseable (skip), single-quoted, else bare token /([^\s"'|&;()]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/; resolution: $(/backtick -> skip; ${CLAUDE_PROJECT_DIR} -> root; any other ${VAR}/$VAR -> skip; relative -> join(root). Missing -> hook-script-missing (mention). If any manifest installed and any config has hook.enabled === false -> hook-enabled-conflict (mention, returns after first).
• checkLegacyLiveState: .impeccable-live.json / .impeccable-live present -> legacy-live-state (auto).
• checkWorkspaces({repoRoot, candidates, ...}): per candidate { name, path, productStatus, productPath, designStatus, designPath, platform: extractPlatform(product) || (product ? 'web (default)' : null) }; native evidence per workspace -> workspace-platform-native-evidence (mention); any inherited -> workspace-context-inherited (mention, path null).
• loadKnownRuleIds(scriptsDir): <scriptsDir>/detector/detect-antipatterns.mjs then <scriptsDir>/../../cli/engine/detect-antipatterns.mjs; import ANTIPATTERNS -> Set of lowercase ids; null when unavailable.

`doctor.mjs` -> `impeccable doctor`

• Invoked from: reference/doctor.md: node {{scripts_path}}/doctor.mjs --json (Step 1; add --target in a monorepo), node {{scripts_path}}/doctor.mjs --fix (Step 2, for auto findings). Utility command (/impeccable doctor), not in the 23-command table.
• CLI args / flags: --json, --fix, --help/-h, --target (strict parse of remaining args; combinable). --help wins over everything and runs no checks. Malformed --target -> stderr message, exit 1.
• Env vars read: everything loadContext reads (IMPECCABLE_CONTEXT_DIR); no update/staleness caches are touched (doctor does not call the notice layer or the update check).
• Inputs: loadContext(cwd, targetOptions); resolveTargetSelection(cwd, targetOptions) for workspace candidates (non-null only at a monorepo root without --target); .impeccable/config.json/config.local.json at repoRoot for projectRoots; git; hook manifests; the detector registry (<scripts>/detector/detect-antipatterns.mjs or <scripts>/../../cli/engine/detect-antipatterns.mjs).
• Findings order: checkProduct; checkNativePlatformEvidence (if product); checkDesignSidecar; checkDesignDrift; checkDesignCoverage; checkConfig; checkBuildPathUnset; checkDetectorIgnores; checkSurfaceBriefs; checkHookInstallation (providerId = built provider); checkLegacyLiveState; checkProjectRoots (patterns from repoRoot configs, candidates = workspace candidates); workspace findings.
• Outputs:
  • --help: usage text + \n, exit 0:
    text Copy

    Usage: node doctor.mjs [--json] [--fix] [--target <path>]
    
    Report drift between this project's Impeccable artifacts and what the
    installed version reads: PRODUCT.md, DESIGN.md and its sidecar,
    .impeccable/config.json, surface briefs, and the design hook.
    
      --json           Emit findings as JSON.
      --fix            Apply the mechanical migrations (severity "auto") only.
      --target <path>  Select a workspace in a monorepo.

  • --json: JSON.stringify({ projectRoot, repoRoot, isMonorepo, productPath, designPath, platform, ruleRegistryAvailable, findings, workspaces, [fixes: { applied: string[], skipped: [{id, reason}] }] }, null, 2) + \n. productPath/designPath cwd-relative.
  • Text: lines joined by \n + \n:
    Impeccable doctor: <rel(projectRoot, cwd) || '.'>; if monorepo Monorepo, repo root <rel || '.'>.; blank; either No drift found. Every artifact matches what this version reads. or groups in order route/mention/auto with header needs a command (n): / worth saying (n): / automatic (n):, each finding as [] (path part omitted if null), , → <fix>, blank line after each group; if workspaces: Workspaces: then product: <status> design: <status>[ platform: ], blank; if registry unavailable: Note: the bundled detector could not be resolved, so ignored rule ids were not validated. + blank; if --fix: Applied: + <entry> lines or Applied nothing., then Left alone: + : <reason> for skipped entries whose reason !== needs a decision from the user; else if any auto finding: Run `node doctor.mjs --fix` to apply the automatic migrations, or ` doctor` to work through all of them.
  • Exit 0 always on success (findings are not errors); runtime failure -> stderr impeccable doctor failed: <msg>, exit 1.
• Side effects (--fix only): for design-sidecar-legacy-path: if canonical .impeccable/design.json does not exist, mkdir -p and rename the legacy file -> applied Moved <rel present> to <rel canonical>.; else skipped <rel canonical> already exists; not overwriting. legacy-live-state -> skipped delete by hand once no live session is running. Any other auto id -> no automatic migration implemented. Non-auto -> needs a decision from the user. Then, independent of findings: if PRODUCT.md exists, is unstamped, and there is NO product-schema-legacy finding, rewrite it via stampProductSchema -> applied Stamped <rel> as product-schema 1. (stamp inserted after the H1 with a blank line).
• Gotchas: rel() returns posix repo-relative or the absolute path when outside. Workspaces list is empty unless run at a monorepo root without --target. checkProjectRoots always receives the candidates from selection (empty when target given), so config-project-roots-match-nothing can also fire when --target is passed and patterns exist (candidates=[]).
• Tests: tests/doctor.test.mjs (drift threshold, coverage incl. frontmatter/seed marker rules, ignore validation + real registry, hook path forms #399/#476/${CLAUDE_PROJECT_DIR}/$(git ...)/plugin placeholders, legacy live state, workspaces sweep, CLI: clean project text, JSON severity grouping, --fix moves sidecar and stamps, no-overwrite, no stamp when legacy, monorepo workspaces JSON, --help, malformed target).

`pin.mjs` -> `impeccable pin`

• Invoked from: SKILL.src.md: node {{scripts_path}}/pin.mjs <command>; "Report the script's result concisely; relay stderr verbatim on error."
• CLI args: exactly argv[2] = action (pin|unpin), argv[3] = command. Missing either -> stdout Usage: node pin.mjs <command> + \nAvailable commands: <VALID_COMMANDS joined ', '>, exit 1. Bad action -> stderr Unknown action: <a>. Use 'pin' or 'unpin'., exit 1. Bad command -> stderr Unknown command: <c> and Available commands: ..., exit 1. VALID_COMMANDS = craft, init, extract, document, shape, critique, audit, polish, bolder, quieter, distill, harden, onboard, live, animate, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, generate (24; doctor, teach not included).
• Env vars: none.
• Inputs: project root = walk up from cwd until a dir containing package.json, .git, or skills-lock.json (stops at /; falls back to cwd). Harness dirs HARNESS_DIRS = .claude .cursor .gemini .codex .agents .agent .github .grok .hermes .trae .trae-cn .pi .opencode .kiro .rovodev .vibe .qoder; a harness is used only if <root>/<h>/skills/impeccable or <root>/<h>/skills/i-impeccable exists. command-metadata.json next to the script ({ [command]: { description, argumentHint } }).
• Outputs/side effects (pin): no harness dirs -> stdout No harness directories with impeccable installed found., exit 0. For each harness skills dir: <skillsDir>/<command>/SKILL.md; if it exists without the marker `` -> SKIP: <dir> (non-pinned skill already exists); else mkdir + write, print + <dir>. Then if any created: \nPinned '<command>' as a standalone shortcut in <n> location(s). and Use the pinned command directly in each harness.. Content (prefix $ and codex frontmatter when the harness dir basename is .codex or .agents, else /):
  text Copy

  ---
  name: <command>
  description: "<metadata description or `Shortcut for <prefix>impeccable <command>.`>"
  argument-hint: "<hint or [target]>"          (non-codex; followed by line `user-invocable: true`)
  metadata:\n  argument-hint: "<hint>"          (codex form instead)
  ---
  
  
  
  This is a pinned shortcut for `<prefix>impeccable <command>`.
  
  Invoke <prefix>impeccable <command>, passing along any arguments provided here, and follow its instructions.

  (trailing newline). unpin: for each harness with <skillsDir>/<command>/SKILL.md: no marker -> SKIP: <dir> (not a pinned skill); else rm -rf dir, - <dir>; then \nUnpinned '<command>' from <n> location(s). + Use Impeccable's '<command>' workflow directly to access it. or No pinned '<command>' shortcut found. Exit 0 in all these cases.
• Tests: tests/pin.test.mjs (pin audit in .claude/.cursor -> /impeccable audit, argument-hint: + user-invocable: true; .agents/.codex -> $impeccable audit, metadata:\n argument-hint:).

`surface-brief.mjs` -> `impeccable surface-brief`

• Invoked from: reference/new-work.md: node {{scripts_path}}/surface-brief.mjs read and ... write [related-target ...]; context.mjs SURFACE_CONTEXT_AVAILABLE names read . reference/live.md says live must not shell out to it.
• CLI args: positional <command> [target] [bodyFile] [related...]; commands path, list, read, write. projectRoot = resolveProjectRoot(cwd, target ? {targetPath: target} : {}) (so the target itself steers monorepo resolution).
• Outputs: path: cwd-relative brief path + \n (error surface brief path requires a concrete target when unslugable). list: JSON.stringify([{slug, path (projectRoot-relative posix), primaryTarget, relatedTargets}], null, 2) + \n. read: on resolution prints the brief's full text verbatim (no added newline), exit 0; direct target resolution probes both the current hashed long slug and the previous suffix-only long slug, but accepts the collision-prone legacy path only when the brief's target metadata matches the requested target; else if candidates exist prints their summaries JSON to stderr, and exits 2 either way. write: requires target and bodyFile (else error usage: surface-brief.mjs write ); writes the brief (format above) and prints cwd-relative path + \n. Unknown command -> error usage: surface-brief.mjs [target] [body-file] [related-target ...]. All thrown errors -> stderr <message>\n, exit 1.
• Tests: tests/surface-brief.test.mjs (library level: slug path .impeccable/surfaces/src-pages-index-astro.md, related-target resolution, only-brief/ambiguous, overwrite semantics, route normalization, route.md root); tests/context.test.mjs brief loading via context.

`critique-storage.mjs` -> `impeccable critique-storage`

• Invoked from: reference/critique.md: slug "<resolved-path-or-url>" (non-zero -> skip persistence), IMPECCABLE_CRITIQUE_META='{...}' node ... write "<resolved target>" , trend "<resolved target>" 5; reference/polish.md: latest "<resolved target>" (exit 2 = none). Imported by context-signals.mjs.
• CLI args: slug <target>; write <slug-or-target> ; latest <slug-or-target>; trend <slug-or-target> [limit=5]. coerceSlug: value matching /^[a-z0-9-]+$/ used as-is, else slugFromTarget(value) (cwd = process.cwd()).
• Env vars: IMPECCABLE_CRITIQUE_META (JSON object for frontmatter on write; parse failure ignored).
• Storage: dir getCritiqueDir(cwd) = /.impeccable/critique/. Filename <stamp>__<slug>.md, stamp = ISO UTC with : and . -> - and the -mmmZ fraction removed: 2026-05-12T18-30-00Z. File content: ---\n<key>: <value>\n...---\n\n, keys = {...meta, timestamp, slug} (meta first, then computed override); null/undefined skipped; string values containing : or # are JSON-quoted. Snapshot filename regex /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z__.+\.md$/; sorted lexicographically (= chronologically). Frontmatter read: "..." values JSON-parsed, /^-?\d+$/ -> Number, else string.
• Outputs: slug: slug + \n exit 0, or stderr no stable slug for input\n exit 1. write: missing args -> stderr usage: write <slug-or-target> \n exit 1; else absolute path written + \n. latest: none -> exit 2 (no output); else prints file body verbatim. For explicit path/URL targets, latest, trend, and close probe both the current hashed long slug and the previous suffix-only long slug, but accept a legacy snapshot only when its recorded target identity matches. Identity-less pre-upgrade snapshots remain available by passing their exact legacy slug, which avoids guessing a path/URL owner for a collision-prone key. trend: JSON.stringify(rows, null, 2) + \n, rows = frontmatter objects of the last N matching files oldest->newest ([] if none). Unknown -> stderr usage: critique-storage.mjs <slug|write|latest|trend> [args]\n exit 1.
• Gotchas: latest/trend match by suffix __<slug>.md; readLatestSnapshotAcrossTargets uses suffix .md. Main-module guard compares realpaths so symlinked invocation works.
• Tests: tests/critique-storage.test.mjs (slug rules, stamp format, round-trip, newest selection, meta cannot override timestamp/slug, quoting :/#, CLI slug/exit codes/symlink/latest exit 2, trend ordering).

`palette.mjs` -> `impeccable palette`

• Invoked from: nothing in skill/ references it (grep finds no palette.mjs in SKILL.src.md, reference/, agents/); it is a standalone helper (used by evals).
• CLI args: --id <seed-id> (exact match among 129 inlined seeds; unknown -> stderr no seed with id "", exit 2), --from <key> (deterministic). Both require a following arg. Otherwise random.
• Env: IMPECCABLE_PALETTE_SEED = fallback for --from.
• Algorithm: unit = sha256(key) first 4 bytes big-endian / 2^32, or Math.random(). Weighted pick: hue bucket floor(((H % 360)+360)%360 / 30), weight 1/count(bucket); walk seeds in array order subtracting weights from unit*total until < 0. Seed data: { id, oklch:[L,C,H], mood, strategy } (129 entries, must be copied verbatim to reproduce picks).
• Output: one stdout block starting BRAND SEED · \n\nSeed color (anchor for your primary brand color):\n oklch(<L.3f> <C.3f> <H.1f>) — <hueWord>( (one read: "<mood>"))\n\n... followed by fixed instructional prose (steps 1-4, hard rules, TEXT-ON-COLOR FILLS), with ${H.toFixed(0)}° and \n - one example strategy: <strategy> interpolated. hueWord bands: <15|>=345 pure red; <35 warm red / crimson; <55 warm coral / burnt orange; <80 orange / honey; <105 warm amber / honey-gold; <135 yellow-green / olive; <170 green; <200 teal; <230 sky blue; <265 cobalt / indigo; <295 violet / purple; <330 magenta / pink; else deep pink / rose. Exit 0. Full prose lives at lines 511-628 of the source.
• Tests: none.

`embed-prompt.mjs` -> `impeccable embed-prompt`

• Invoked from: reference/visualize.md and agents/impeccable-asset-producer.md: node {{scripts_path}}/embed-prompt.mjs --prompt "" after every generation; reference/new-work.md: node {{scripts_path}}/embed-prompt.mjs --scan <asset-dir...> before review/verdict, clearing every MISSING: line. generate-image.mjs embeds automatically.
• CLI args: `` = first arg not starting with --; --prompt <text> | --prompt-file ; --read; --scan (all non--- args are targets).
• Behavior: --scan: no targets -> stderr embed-prompt: --scan needs at least one directory, exit 1; nonexistent -> embed-prompt: no such path <t>, exit 1; walk (dirs skip node_modules and dot-dirs except the explicitly passed root), rasters /\.(png|jpe?g|webp)$/i; print MISSING: per raster without a prompt, then SCAN: <n> raster(s), <m> missing; exit 3 if m>0 else 0. Otherwise: no/nonexistent file -> embed-prompt: image file required exit 1. --read: PNG (0x89504e47) tEXt/zTXt chunk keyword impeccable:prompt, JPEG (FF D8) COM segment starting impeccable:prompt\0, then .json sidecar .prompt; found -> console.log(prompt) exit 0; else stderr embed-prompt: no embedded prompt found, exit 2. Embed: prompt missing -> embed-prompt: --prompt or --prompt-file required exit 1. PNG: remove any existing chunk with the keyword, insert tEXt (impeccable:prompt\0, CRC32) before IEND -> EMBEDDED: <file> (png tEXt, <len> chars); malformed -> embed-prompt: malformed PNG exit 1. JPEG: insert COM after SOI (FFFE, 2-byte length); segment > 0xFFFF -> embed-prompt: prompt too long for a JPEG segment exit 1 -> EMBEDDED: <file> (jpeg COM, <len> chars). Other formats: write <file>.json = JSON.stringify({ prompt, createdAt: ISO }, null, 2) -> EMBEDDED: <file>.json (sidecar fallback for this format).
• Gotchas: JPEG embed is not idempotent (prepends another COM each time; read returns the first). PNG rewrite is idempotent. <len> is JS string length.
• Tests: none directly (referenced from new-work E2E only).

`context-signals.mjs` -> `impeccable signals`

• Invoked from: reference/routing.md (no-argument /impeccable): node {{scripts_path}}/context-signals.mjs once, after context.mjs; agent then runs detect.mjs --json <scan.targets> for web platforms.
• CLI args / env: none (cwd only). No writes.
• Output: JSON.stringify(signals, null, 2) + \n, exit 0:
  text Copy

  { "setup": { hasProduct, productPath, hasDesign, designPath, hasCode, platform },
    "critique": { "latest": null | { slug, score, p0, p1, timestamp, file } },
    "git": { isRepo, branch, base, changedFiles (max 50), changedCount },
    "devServer": { running, ports },
    "scan": { targets, via } }

  hasCode: package.json or any of src app pages site public components lib. platform = extractPlatform(product) (null for web). critique.latest: newest snapshot across slugs; score = Number(total_score ?? score), p0 = p0_count ?? p0, p1 = p1_count ?? p1 (null when missing/blank/NaN); file cwd-relative. git: not a repo -> { isRepo:false, branch:null, base:null, changedFiles:[], changedCount:0 }; branch = rev-parse --abbrev-ref HEAD; base detection: on integration branch (HEAD, develop|main|master, or any remote's refs/remotes/<r>/HEAD short name) -> base null; else candidates in order: upstream (@{u} full symbolic ref, local or remote), develop (advertised remote rev first, then local, then <remote>/develop origin-first), each remote HEAD name, main, master; first with a rev-parse --verify --quiet hit wins. changedFiles = git diff --name-only ...HEAD when base, else git -c core.quotepath=false status --porcelain paths (old -> new -> new). devServer: TCP probe 127.0.0.1 ports 4321 3000 5173 5174 8080 8000 4200, 250 ms timeout, sorted ascending. scan: changed files with ext in .html .htm .css .scss .jsx .tsx .js .ts .vue .svelte .astro, not under a hidden/node_modules/dist/build/__pycache__ dir segment (hidden .vitepress, .vuepress, .storybook allowed), existing -> {targets (max 50), via:'git-changes'}; else existing of src app components pages public -> 'source-dir'; else index.html -> 'html'; else hasCode -> ['.'], 'root'; else [], null.
• Tests: tests/context-signals.test.mjs (setup fields, critique meta keys and null handling, git base detection cases #302, porcelain paths, vendored filtering #303, devServer shape, scan fallbacks, CLI JSON groups).

`detect-csp.mjs` -> `impeccable detect-csp`

• Invoked from: reference/live-setup.md first-time live setup (skipped when live config cspChecked === true): node {{scripts_path}}/detect-csp.mjs; output { shape, signals } drives the consent prompt/patch template.
• CLI args / env: none; cwd = project root. Runs when process.argv[1] ends with detect-csp.mjs (or detect-csp.mjs/).
• Behavior: walk cwd to depth 6 skipping node_modules .git .next .turbo .svelte-kit .nuxt .astro dist build out .vercel; files with ext in .js .mjs .cjs .ts .mts .cts .tsx .jsx (SCAN) or .tsx .jsx .astro .vue .svelte .html (LAYOUT); read first 64 KiB. Classify per file (first match returns):
  • append-arrays: SCAN ext and relPath matches /packages\/[^/]+\/src\/.*(config|next-config|security)/ and any of \bbuildCSPConfig\b|\bbuildSecurityHeaders\b|\badditionalScriptSrc\b|\badditionalConnectSrc\b|\bcreateBaseNextConfig\b; or svelte.config.* with all of \bkit\s*:, \bcsp\s*:, \bdirectives\s*:; or nuxt.config.* with ['"]nuxt-security['"] and \bcontentSecurityPolicy\b.
  • append-string: SCAN ext, relPath matches /(^|\/)(next|nuxt|vite|astro|svelte)\.config\./ and all of ["']Content-Security-Policy["'](i), \bscript-src\b, \bconnect-src\b.
  • middleware: basename middleware.ts|js|mjs and /headers\.set\(\s*["']Content-Security-Policy["']/i.
  • meta-tag: LAYOUT ext and /http-equiv\s*=\s*["']Content-Security-Policy["']/i.
    Priority append-arrays > append-string > middleware > meta-tag > { shape: null, signals: [] }.
• Output: console.log(JSON.stringify({ shape, signals }, null, 2)) (signals = matching relPaths for the winning shape). Exit 0.
• Tests: none dedicated.

3. Design hook Copy Chapter

Source of truth read for this document (repo /Users/paulbakaus/code/impeccable-second):

• skill/scripts/hook.mjs (78 lines), skill/scripts/hook-before-edit.mjs (538), skill/scripts/hook-admin.mjs (801), skill/scripts/hook-lib.mjs (2343)
• skill/scripts/lib/template-extensions.mjs, skill/scripts/lib/provider.mjs, skill/scripts/context.mjs (loadContext, extractPlatform, extractSectionValue, automaticHookMode)
• detector: cli/engine/detect-antipatterns.mjs facade → engines/regex/detect-text.mjs#detectText, engines/static-html/detect-html.mjs#detectHtml, design-system.mjs#loadDesignSystemForCwd, findings.mjs#finding, shared/inline-ignores.mjs
• wiring: scripts/lib/transformers/hooks.js, scripts/lib/transformers/providers.js, scripts/lib/transformers/factory.js, scripts/build.js, scripts/lib/utils.js#replaceScriptProviderMarker, plugin/hooks/hooks.json, generated .claude/settings.json, .codex/hooks.json, .cursor/hooks.json, .github/hooks/impeccable.json, .grok/hooks/impeccable.json, dist/openai/impeccable/hooks/hooks.json, cli/bin/commands/skills.mjs (hook install / rewrite), skill/reference/hooks.md, skill/SKILL.src.md line 81, docs/HARNESSES.md
• tests: tests/hook.test.mjs (3978 lines), tests/hook-build.test.mjs (393 lines)