@etus/seven-skill 0.1.0-beta.3 → 0.1.0-beta.4

package/README.md

@@ -1,118 +1,79 @@
 # @etus/seven-skill
 
-Seven Design System skill, plugin, and CLI detector for AI coding agents.
+Build/runtime interno das skills de UI do Seven, agentes auxiliares, detector determinístico e Seven UI Guardian. Projetos consumidores devem instalar `@etus/seven`, cujo único binário `seven` instala estes artefatos junto com policy, contexto, hooks e enforcement local.
 
-This package distributes the Seven Design System guard-rails as a Claude Code plugin and a deterministic CLI detector. Phase 2 expands to Cursor, Codex, Gemini, OpenCode, and other AI harnesses.
+`@etus/seven-skill` não expõe um segundo binário `seven`.
 
-## What ships
+## O que é publicado
 
-- **Skill source-of-truth** under `source/`: the routing `SKILL.md` plus domain references for typography, color, motion, spatial design, voice, and the Phase 1 sub-commands (`shape`, `audit`, `polish`, `clarify`).
-- **Multi-harness build pipeline** in `build/` that emits one configured skill per target harness. Phase 1 ships Claude Code only at `.claude/skills/seven/`.
-- **Claude Code plugin** wrapper in `.claude-plugin/` with `plugin.json` and `marketplace.json` auto-synced from `package.json`.
-- **Deterministic CLI detector** in `cli/` with 35 Seven-tuned rules (`npx seven detect <path>`).
+- Skills nativas para Claude Code, Codex/Agent Skills, Cursor, Gemini CLI, Grok Build, Kiro, OpenCode, Pi, Qoder, Rovo Dev, Trae, Trae China e Mistral Vibe.
+- Três agentes auxiliares onde o host possui um contrato nativo: asset producer, finish reviewer e manual edit applier.
+- `.claude-plugin/` para compatibilidade com o plugin/marketplace do Claude.
+- `cli/engine/`, com as engines regex, HTML/cascade e navegador usadas por `seven check`.
+- `extension/`, a extensão Manifest V3 Seven UI Guardian, com popup, painel DevTools, marcações de findings e cliente Seven Live.
+- `docs/upstream-parity.json`, matriz executável e versionada contra o Impeccable auditado.
 
-## Status
+GitHub Copilot é a única distribuição upstream deliberadamente recusada: nenhum projeto consumidor recebe ou tem alterado um arquivo `.github/**`.
 
-Phase 1 — hardened Claude Code port. Claude Code target only, 35 detector rules, four sub-commands. Distributed as a Claude Code plugin via the marketplace configuration in this package and as an npm CLI/skill package.
+Alguns hosts exigem ativação fora do alcance do npm. `seven init` e `seven doctor` lembram o usuário de habilitar Agent Skills no Cursor/Gemini, aprovar hooks no Codex/Grok e reiniciar Trae quando aplicável. Esses consentimentos não podem ser automatizados com segurança; o pre-commit local continua protegendo arquivos de UI independentemente da ativação do host.
 
-## Install
+## Skill canônica
 
-### Claude Code plugin (recommended)
+`source/SKILL.md` é a fonte de verdade. Ela roteia 22 workflows de UI aplicáveis — `init`, `shape`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `clarify`, `adapt`, `optimize`, `overdrive` e `live` — mais `doctor`, `hooks` e `exceptions`.
 
-The plugin is configured by `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json` in this package. Inside the Seven monorepo it is available as a workspace dependency:
+Todo workflow de UI deve:
 
-```bash
-pnpm add -D @etus/seven-skill --workspace
-```
+1. resolver o arquivo, app e superfície exatos;
+2. carregar `PRODUCT.md`, `.seven/project.yml`, surface brief e release lock;
+3. validar a instalação com `seven doctor --quick`;
+4. procurar e reutilizar componentes/variantes do registry instalado;
+5. usar somente tokens Seven e voz de produto em português brasileiro;
+6. executar `seven check` em cada arquivo alterado;
+7. reportar evidência e gaps sem inventar contratos.
 
-For external projects, install the package or point the plugin manifest at the git source:
+Contexto de produto pode especializar usuários, jobs, estados, voz e acessibilidade. Não pode substituir cores, tipografia, spacing, radii, motion, variantes ou APIs do Seven. Não existe `DESIGN.md` consumidor com autoridade visual.
 
-```bash
-pnpm add -D @etus/seven-skill
-claude plugin install @etus/seven-skill
-
-# Git source fallback while marketplace propagation catches up:
-claude plugin install github:etusdigital/seven#path=packages/seven-skill
-```
+## Detector e enforcement
 
-### CLI detector
-
-Inside the monorepo:
-
-```bash
-pnpm --filter @etus/seven-skill exec seven detect packages/ui/src/
-```
+O catálogo possui 68 regras. Ele inclui as 59 regras determinísticas identificadas no Impeccable atual, classificadas como portadas, adaptadas à autoridade do Seven ou rejeitadas por conflito, além de regras exclusivas de tokens, Tailwind v4, React 19, pt-BR, shell Sidebar + Topbar, comportamento da Rail e boundary consumidor.
 
-## Commands (Phase 1)
+O pacote consumidor combina o detector com:
 
-| Command          | Purpose                                                                    |
-| ---------------- | -------------------------------------------------------------------------- |
-| `/seven shape`   | Plan UX shape before writing component code                                |
-| `/seven audit`   | Five-dimension scan: a11y, performance, theming, responsive, anti-patterns |
-| `/seven polish`  | Final-pass cleanup aligned to Seven tokens and conventions                 |
-| `/seven clarify` | UX copy in pt-BR: imperative leads, sentence case, no trailing periods     |
+- hooks semânticos nativos em Claude, Codex, Cursor e Grok;
+- pre-commit Git local para mudanças humanas ou feitas fora das ferramentas do agente;
+- checks `--all`, `--changed`, `--staged`, `--file` e URL renderizada;
+- exceções explícitas, baseline que só pode encolher, doctor, pin/unpin e update/uninstall ownership-safe.
 
-Phase 2 adds `craft`, `harden`, `layout`, `typeset`.
+O LLM nunca é hard gate. Código determinístico decide routing técnico, integridade e findings; o modelo é usado para julgamento de produto/design.
 
-## Detector rules
+## Seven Live e extensão
 
-The detector ships 35 rules across three engines (regex, static-html,
-browser). Each rule is `quality` (real design / a11y drift) or `slop` (an
-AI tell, Seven-flavored). The full catalog — every rule with its
-justification, a wrong/right example, and the design reference that grounds
-it — is in [`docs/detector-rules.md`](./docs/detector-rules.md).
+`seven live` usa um bridge em `127.0.0.1` com token aleatório, journal local e payload limitado. Seven UI Guardian seleciona o elemento e exibe direções HTML/CSS inertes. Um aceite autoriza uma edição pequena no código React usando contratos instalados; DOM/CSS de preview nunca vira produção automaticamente.
 
-**Token-aware.** Eight rules are grounded in Seven's real design tokens: a
-build step (`build:tokens`) reads `@etus/tokens` and embeds a token-data
-snapshot, so `hardcoded-color-not-token` names the exact token a literal
-maps to, `non-inter-font` reads the font tokens, `radius-mixed-scales` reads
-the radius scale, and `bounce-easing` knows the sanctioned easing tokens.
-When `@etus/tokens` rebuilds from a Figma sync, regenerate the snapshot. The
-other 27 rules are heuristics — language facts, CSS mechanics, and a11y
-standards no token defines. Each rule's verdict is in `RULE_GROUNDING`.
+Por segurança do navegador, npm não pode ativar a extensão sem consentimento. `seven extension path` informa o diretório publicado que deve ser carregado uma única vez como extensão sem compactação.
 
-Quick map: nine text rules (`non-inter-font`, `hardcoded-color-not-token`,
-`raw-tailwind-palette-color`, `missing-color-type-hint`,
-`missing-length-type-hint`, `leading-none-with-length-var`,
-`fuchsia-in-ui-chrome`, `pt-pt-vocab`, `pure-black-or-white`); three
-inverted from impeccable (`side-stripe-border`, `gradient-text-decorative`,
-`shadows-not-borders`); seventeen universal design-quality / a11y rules; six
-Seven-specific element rules (`missing-tactile-press`, `pill-on-button`,
-`radius-mixed-scales`, `non-lucide-icon`, `emoji-in-chrome`,
-`forbidden-em-dash`).
+## Build e verificação
 
-Exit codes follow the impeccable convention: `0` clean, `2` findings present, `1` usage error.
-
-## Architecture
-
-```
-packages/seven-skill/
-├── source/                # authoring source (not shipped to npm)
-│   ├── SKILL.md           # router + shared design laws
-│   ├── reference/         # domain + sub-command references
-│   └── scripts/           # consumer-side runtime scripts (Phase 2)
-├── build/                 # multi-harness build pipeline (not shipped)
-├── cli/                   # deterministic detector (shipped)
-├── .claude/skills/seven/  # Claude Code build output (shipped, tracked)
-├── .claude-plugin/        # Claude Code plugin wrapper (shipped)
-└── tests/                 # unit + fixture tests
+```bash
+pnpm --filter @etus/seven-skill build
+pnpm --filter @etus/seven-skill test
+pnpm --filter @etus/seven-skill typecheck
 ```
 
-Author in `source/`. Run `pnpm --filter @etus/seven-skill build` to regenerate the per-harness skill outputs and the plugin manifest.
-
-## Development
+O build regenera 13 provider trees, agentes, metadados de plugin, snapshot de tokens, browser detector e extensão. Artefatos gerados devem permanecer byte-for-byte derivados de `source/` e `extension-src/`.
 
-```bash
-pnpm --filter @etus/seven-skill build       # regenerate harness output and manifests
-pnpm --filter @etus/seven-skill test        # vitest unit + fixture suite
-pnpm --filter @etus/seven-skill typecheck   # tsc strict mode
-
-# Detector usage
-pnpm --filter @etus/seven-skill exec seven detect path/to/file-or-dir
-pnpm --filter @etus/seven-skill exec seven detect packages/ui/src/ --json
-pnpm --filter @etus/seven-skill exec seven help
+```text
+packages/seven-skill/
+├── source/                   # skill, referências, scripts e agentes canônicos
+├── build/                    # transformers e geradores
+├── cli/engine/               # detector determinístico
+├── extension-src/           # fonte da extensão
+├── extension/               # build publicável da extensão
+├── .claude/, .agents/, ...  # 13 outputs de hosts
+├── docs/                     # regras e matriz de paridade
+└── tests/                    # contratos, fixtures, build e paridade
 ```
 
-## License
+## Licença
 
-Apache-2.0. See `LICENSE`.
+Apache-2.0. A arquitetura adaptada do Impeccable é atribuída em `NOTICE.md` e nos headers relevantes.

package/cli/engine/browser/injected/index.mjs

@@ -16,19 +16,60 @@
  * dependent drift surfaces — the per-element work the static-html engine does
  * against a resolved cascade, here against the real browser.
  *
- * Impeccable's injected script also carries an inspector overlay, decoration,
- * visual-contrast capture, and the Chrome-extension bridge. Those are
- * extension UI, not detection — Seven has no extension, so they are omitted.
+ * Inspector overlays and the Live bridge stay in the packaged Seven browser
+ * extension. This detector remains UI-agnostic and returns stable selectors
+ * so the extension can decorate or focus the matching element.
  */
 
 ;(function sevenInstallBrowserDetector() {
   if (typeof window === 'undefined') return
 
+  function selectorFor(el) {
+    if (!el || el.nodeType !== 1) return ''
+    const escape = (value) => {
+      if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(value)
+      return String(value).replace(/[^a-zA-Z0-9_-]/g, (char) => `\\${char}`)
+    }
+    if (el.id && document.querySelectorAll(`#${escape(el.id)}`).length === 1) return `#${escape(el.id)}`
+    for (const attribute of ['data-testid', 'data-slot']) {
+      const value = el.getAttribute?.(attribute)
+      if (value) {
+        const selector = `[${attribute}="${String(value).replaceAll('"', '\\"')}"]`
+        if (document.querySelectorAll(selector).length === 1) return selector
+      }
+    }
+    const parts = []
+    let current = el
+    while (current && current !== document.documentElement && parts.length < 6) {
+      let part = current.tagName.toLowerCase()
+      const siblings = current.parentElement
+        ? [...current.parentElement.children].filter((item) => item.tagName === current.tagName)
+        : []
+      if (siblings.length > 1) part += `:nth-of-type(${siblings.indexOf(current) + 1})`
+      parts.unshift(part)
+      const selector = parts.join(' > ')
+      if (document.querySelectorAll(selector).length === 1) return selector
+      current = current.parentElement
+    }
+    return parts.join(' > ')
+  }
+
   function collectFindings() {
     const out = []
-    const push = (arr) => {
+    const seen = new Set()
+    const push = (arr, element = null) => {
       if (!arr) return
-      for (const f of arr) out.push({ type: f.id, detail: f.snippet })
+      for (const f of arr) {
+        const normalized = {
+          type: f.id,
+          detail: f.snippet,
+          ...(element ? { selector: selectorFor(element), tag: element.tagName?.toLowerCase() || '' } : {}),
+        }
+        const key = `${normalized.type}|${normalized.selector || ''}|${normalized.detail || ''}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        out.push(normalized)
+      }
     }
 
     for (const el of document.querySelectorAll('*')) {
@@ -38,14 +79,14 @@
         continue
       }
       try {
-        push(checkElementBordersDOM(el))
-        push(checkElementColorsDOM(el))
-        push(checkElementGlowDOM(el))
-        push(checkElementMotionDOM(el))
-        push(checkElementTactilePressDOM(el))
-        push(checkElementPillOnButtonDOM(el))
-        push(checkElementLucideIconDOM(el))
-        push(checkElementQualityDOM(el))
+        push(checkElementBordersDOM(el), el)
+        push(checkElementColorsDOM(el), el)
+        push(checkElementGlowDOM(el), el)
+        push(checkElementMotionDOM(el), el)
+        push(checkElementTactilePressDOM(el), el)
+        push(checkElementPillOnButtonDOM(el), el)
+        push(checkElementLucideIconDOM(el), el)
+        push(checkElementQualityDOM(el), el)
       } catch {
         // A malformed element must not abort the whole scan.
       }
@@ -64,6 +105,14 @@
       /* html-pattern check failed — continue */
     }
 
+    try {
+      // Rendered-text parity for Seven's source checks, including the stricter
+      // forbidden-em-dash adaptation of Impeccable's advisory saturation rule.
+      push(runChecks(document.documentElement.outerHTML))
+    } catch {
+      /* rendered-text check failed — continue */
+    }
+
     return out
   }