@orchestrator-claude/definitions 3.30.1 → 3.31.0

package/skills/compositional-intelligence/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: compositional-intelligence
+description: Routing decisions + plugin coexistence protocol. Load when [CAPABILITY-MATRIX] routing hints are insufficient for a dispatch decision, or when plugin vs sub-agent choice is ambiguous.
+---
+
+# Compositional Intelligence — Routing & Coexistence
+
+## Routing Table (defaults — overridden by [CAPABILITY-MATRIX] routing hints)
+
+| Activity | Primary | Fallback |
+|----------|---------|----------|
+| Exploratory design | brainstorming (native skill) | Main inline |
+| Codebase analysis | feature-dev:code-explorer | researcher sub-agent |
+| Formal spec | specifier sub-agent | Main inline |
+| Sprint plan | planner sub-agent | Main inline |
+| Task decomposition | task-generator sub-agent | Main inline |
+| Code review | reviewer sub-agent | feature-dev:code-reviewer |
+| PR review (parallel) | code-review command | coderabbit:review |
+| PR review (autofix) | coderabbit:autofix | Manual |
+| Implementation | implementer sub-agent | N/A |
+| Technical research | researcher sub-agent | perplexity MCP |
+| Debug | systematic-debugging (native skill) | Main inline |
+
+## Decision Criteria
+
+1. **Delegation > Inline** — preserve Main context window
+2. **Sub-agent > Plugin agent** — sub-agents respect gates, use MCP, store artifacts
+3. **Plugin for read-only analysis** — no side-effects (no advancePhase, no artifactStore)
+4. **Opus (Main) only for heavy intellectual work** — brainstorm, architectural decisions
+5. **Vault tier < 2 → simplify** — fewer phases, less ceremony
+6. **Plugin not installed → automatic fallback** — use the fallback column
+
+## Plugin Decision Matrix
+
+When multiple plugins could handle a task, use these rules:
+
+### 1. Code Review
+- General quality/bugs → `pr-review-toolkit` (6 specialized agents: types, comments, silent-failures, tests, simplification, code-review)
+- Fix PR comments → `coderabbit:autofix` (unique automated fix workflow)
+- Full PR review for GitHub → `code-review` command (5-parallel-agent, confidence scoring, posts comments)
+- During workflow review phase → native `reviewer` agent (governance + artifact validation)
+
+### 2. Symbol Navigation
+- Local file/symbol → `serena` (LSP, precise, semantic)
+- Cross-repo or pattern search → `sourcegraph` (broad, enterprise)
+
+### 3. Documentation
+- External library (React, Prisma, etc.) → `context7` (upstream, version-specific)
+- Project conventions/architecture → `/kb-lookup` (vault KB)
+
+### 4. Creating Extensions
+- New plugin/skill/agent → `plugin-dev` (structure + creation, 7 skills + 3 agents)
+- Eval/benchmark existing skill → `skill-creator` (metrics, triggering optimization)
+- Interactive hook from conversation → `hookify` (conversation analyzer)
+- Programmatic hook → native `.claude/hooks/` (TypeScript, DI pattern)
+
+### 5. Design/Planning
+- Explore what to build → `brainstorming` (native skill)
+- How to execute → `/orchestrator` workflow
+- NEVER follow writing-plans or executing-plans pipelines
+
+### 6. Web/Research
+- Web scraping/crawling → `firecrawl` (LLM-optimized output)
+- Technical research → `perplexity` MCP
+- Library docs → `context7`
+
+## Coexistence Protocol
+
+### Rule 1 — Plugins DO NOT pass through gates
+Plugin agents execute and terminate. They do not call `advancePhase`, do not store artifacts in MinIO, do not create checkpoints. For gate-aware tasks, always use built-in sub-agents.
+
+### Rule 2 — Plugins for read-only analysis
+Plugin output is INPUT for a sub-agent, not a final artifact:
+- `feature-dev:code-explorer` → explore codebase (input for specifier)
+- `feature-dev:code-architect` → blueprints (input for planner)
+- `coderabbit:review` → PR review (complements reviewer)
+
+### Rule 3 — Native Skills at Level 1 (Behavioral Disciplines)
+Native behavioral skills operate at the strategic level:
+- `brainstorming` → design exploration (terminal state: `/orchestrator`)
+- `systematic-debugging` → root cause investigation (loaded in implementer via frontmatter)
+- `receiving-code-review` → technical rigor for review feedback (loaded in reviewer via frontmatter)
+- `finishing-branch` → branch completion guide (invoked at `completeWorkflow`)
+- `verification-before-completion` → PreToolUse hook (evidence before git commit/push)
+- `tdd-discipline` → TDD protocol (loaded in implementer via frontmatter)
+
+### Rule 4 — Gap Detection
+Hook detects installed plugins vs stack profile. Missing `core` = warning in greeting. Missing `recommended` = suggestion. The user decides whether to install.
+
+## When to Load This Skill
+- On first dispatch decision of the session IF [CAPABILITY-MATRIX] routing hints are unclear
+- When plugin vs sub-agent choice is ambiguous (e.g., two plugins both do code review)
+- DO NOT load for every dispatch — routing hints in [CAPABILITY-MATRIX] suffice for standard decisions

package/skills/design-system-validated-loop/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: design-system-validated-loop
+description: Use BEFORE writing markdown patches in design-system docs that drive LLM-rendered UI (Bolt, v0, Lovable, Cursor design rules, Replit Agent). Triggers on "design system patch", "responsive change", "Bolt sync", "v0 update", "high-fidelity screen", "design-system markdown", or any rendering-decision change (layout, palette, spacing, density, hierarchy). Provides 6-step canary-validated loop optimizing token economy + audit trail + design quality. Skip for typo fixes or namespace renames.
+---
+
+# Design-System Validated Loop (DSVL)
+
+Empirically validated process for evolving markdown design-systems consumed by downstream LLM tools (Bolt/v0/Lovable/Cursor/Replit). Canonical reference: `project-guidelines/processes/design-system-validated-loop.md` (354L). Empirical base: **5 consecutive applications** (S163b 11/11 PASS · S164 ~98% single-shot · S165 15/15 PASS · S166 18/19 PASS single-shot · S167 18/18 PASS post-route-around-Bolt). Production-ready for Bolt + TRC + design-system-v5; universal generalization still requires application in a distinct LLM tool + tier + non-pt-BR i18n.
+
+## When to use
+
+USE when:
+- Design-system markdown drives downstream LLM-rendered UI
+- Change involves rendering decisions: layout, responsive, palette, spacing, density rhythm, hierarchy
+- Downstream tool charges tokens per render (Bolt $0.x/k, v0 credits, etc.)
+- Multiple iteration expected (design-sensitive work never lands first try)
+
+DO NOT use when:
+- Text-only spec changes without rendering implications
+- Namespace fixes (token rename, link cross-doc) — referential integrity (substituto #5) covers
+- One-off prototypes (canary overhead > value)
+- Spec exploration phase (DSVL is for evolution, not creation from scratch)
+
+## Mandatory enforcement (S165 lesson)
+
+T-001 = canary HTML creation. **NOT optional, NOT post-Bolt recovery.** Per `feedback_dsvl_canary_must_be_t001_not_optional`:
+- specifier MUST list canary as ARTIFACT REQUIRED in spec.md (skip requires explicit justification)
+- planner MUST cover all 6 etapas in plan.md (skip requires explicit justification)
+- task-generator MUST emit T-001 as canary creation with gate
+- reviewer MUST audit DSVL conformance, not only the final artifact
+
+If working a feature_development workflow where DSVL applies and T-001 is not canary, **stop and fix the workflow** before implementing.
+
+## The 6 etapas (with Etapa 2.5 — added in v2 post-S166)
+
+```
+[LOCAL, zero downstream tokens]                        [REMOTE, billing tokens]
+┌─────────────────────────────────────┐    ┌──────────────────────────────────┐
+│ 1. Canary HTML preview              │    │ 2.5. Storybook validation        │
+│ 2. Markdown patches + 7 substitutos │    │    (post-push, parallel ingest,  │
+│ 3. Push design-system repo (HUMAN)  │ ─→ │    Bolt-hosted, free, NEW S166)  │
+│                                     │    │ 4. Bolt/v0/Lovable re-ingest +   │
+│                                     │    │    re-render + publish           │
+│                                     │    │ 5. Playwright autonomous validate│
+│                                     │    │ 6. Session closure (memorias +   │
+│                                     │    │    BACKLOG + commit)             │
+└─────────────────────────────────────┘    └──────────────────────────────────┘
+```
+
+### Etapa 1 — Canary HTML preview (LOCAL)
+
+**What:** Self-contained HTML rendering N viewports stacked with the same container queries / tokens / layouts that will become markdown patches.
+
+**Where:** consumer-project repo, NOT design-system repo. TRC convention: `~/desenvolvimento/trc/trc-platform/docs/assets/preview/[tela]-v[N]-preview.html`.
+
+**Properties:**
+- Single file, vanilla CSS, zero deps, zero build
+- Identical content to prior remote render for direct comparison
+- Viewport widths fixed via attribute selectors or inline style
+- Real container queries
+- Toggleable patch debug overlays (`<body class="show-tags">`)
+
+**Gate 1:** human visually validates N viewports. PASS → Etapa 2. FAIL → orchestrator iterates local CSS until PASS (zero token cost).
+
+### Etapa 2 — Markdown patches + pre-push verification
+
+**What:** translate validated canary CSS into prescriptive markdown in design-system files.
+
+**Prescriptive pattern (proven empirically S162→S163):**
+- Intent-driven naming (`--column-decision`, NOT `--max-w-720`)
+- Concept × forbidden × required-substitute tables for anti-patterns (positive-prescriptive > negative-generic for LLM-ingest)
+- Audit-trail line at top of each section: "Validated via canary [path] section [N]"
+- Specific px/rem values, NOT "subtle" or "comfortable"
+- Inline "Why" for threshold rules
+
+**9 substitutos verification (ALL mandatory; #8 + #9 added post-S167):**
+
+| # | Check | How |
+|---|---|---|
+| 1 | Completeness | N patches written per declared scope |
+| 2 | Consistency | Terminology consistent cross-files |
+| 3 | Integrity | Code-fences paired (`grep -c '^\`\`\`'` returns even per file) |
+| 4 | Mapping documented | Each patch maps explicitly to canary section |
+| 5 | Referential integrity | `grep -hoE 'var\(--[a-z-]+\)'` cross-checked vs tokens.md `:root {}` block (NOT just markdown tables — S166 caught typography gap here; S167 caught broken token chain `--pivot-hover-bg` aliased to undefined `--hover-overlay-light`) |
+| 6 | Visual smoke test post-render | Etapa 5 — covers structure + rendering + density rhythm + audience-fit (4 layers, S163b v3) |
+| 7 | Visual decision pre-validation | Canary HTML approved at Gate 1 |
+| 8 | **Sort order verification (NEW post-S167)** | `grep -nE '\.sort\(\)' [files]` em prompt/spec. Para keys com semantic order (months, weekdays, status sequence, priority), `.sort()` default JS e lexicografico — REQUER comparator explicito (e.g., `.sort((a,b) => MONTHS.indexOf(a) - MONTHS.indexOf(b))`) ou keys lex-friendly (zero-padded/ISO). Output PASS/FAIL binario. ROI: 30s grep evita ~50k tokens recovery + delay sessao. Generalizable beyond DSVL para qualquer LLM-codegen com time/enum-keyed strings (Bolt/v0/Lovable/Cursor/Replit). Per `dsvl_substituto_8_spec_sort_order_verification` (S167). |
+| 9 | **Route-around-Bolt for trivial fixes (NEW post-S167)** | Para fixes triviais post-G3 (CSS, 1-line JS, token chain repairs, sub-rounds DSVL onde score esta perto do target): dispatchar implementer para fix DIRETO no consumer-project repo + push GitHub + **F5 manual no Bolt UI** = sync gratis. Economia empirica S167: ~500k-1M tokens vs full Bolt re-render. NAO usar para refactor estrutural, mudancas que requerem Bolt AI, adicao de funcionalidade, codigo do design-system (mecanismo ingest diferente). Ver Etapa 6.5 detalhada. Per `dsvl_route_around_bolt_for_trivial_fixes` (S167). |
+
+**Gate 2:** all 9 substitutos PASS (or N/A justified). Bug catched here (undefined token, sort order trap, etc.) is fixed before push, preventing broken downstream render.
+
+**Note:** Storybook visual confirmation is NOT a substituto — it is **Etapa 2.5** (a separate phase, post-push, free Bolt-hosted). Earlier numbering in v1 conflated them; v2 separates clearly.
+
+### Etapa 2.5 — Storybook validation (NEW v2, post-S166)
+
+**What:** post-push, paralelo a re-ingest (Etapa 4), Bolt auto-builda Storybook revision tied to design-system commit. Use Playwright para validar specs INDEPENDENTEMENTE de canary local + ANTES de queimar tokens em Bolt re-render. Disambigua "spec bug" de "Bolt codegen bug" antes de Etapa 5.
+
+**URL pattern (Bolt-hosted):** `https://bolt.new/api/design-systems/{id}/revisions/{revId}/storybook-build/?path=/docs/{kebab-component}--docs&_t={auth-token}`
+
+**O que Storybook valida:**
+- Wrapper anatomy (header + body + footer) + spacing/padding/radius/shadow
+- Props TypeScript signature derivada do markdown (variants, types, optional)
+- Tokens var() resolvidos (--badge-*, --chart-*, --status-*, --text-*)
+- Auto-generated interactive controls (sliders/dropdowns/booleans dos props)
+- Sub-stories auto-extracted (e.g., variant=bar/line/stacked/alerts → 4 stories individuais)
+
+**O que Storybook NAO valida (vai para Etapa 5):**
+- Charts SVG real (children prop = placeholder no Storybook)
+- List rendering com mock data real
+- Composition cross-component (Card 3 + 5 FoundryPatternBadges inline)
+- Layout grid em viewport breakpoints
+- Click handlers, hover states, deep-links
+- Console errors, BrowserRouter F5 SPA routing
+
+**Disambiguation power:**
+- Storybook PASS + Bolt deploy FAIL → Bolt codegen bug (LLM mistraduce spec)
+- Storybook FAIL + Bolt deploy FAIL → spec markdown ambiguo/inconsistente
+- Storybook PASS + Bolt deploy PASS → spec + codegen ambos corretos (case S166: 18/19 AC)
+
+**Operational caveats (auth):**
+- URL token `_t=` expira em ~minutos. Automation autonoma orchestrator NAO pode cachear nem agendar
+- **Cenario A (S166 validated):** Playwright headed mode, CMAC loga em Bolt no Playwright browser, navega para Storybook, orchestrator usa browser_* tools com session auth persistente
+- **Cenario B fallback:** CMAC copia URL com token fresh do browser pessoal e cola para orchestrator navegar dentro de ~30s window
+- **Cenario C theoretical:** storage_state JSON com cookies Bolt — mais setup mas persistente cross-sessao
+
+**Wall-clock:** ~5-10min para 2-3 components novos. Cost: 0 tokens (Bolt auto-builds Storybook free).
+
+**Gate 2.5:** Storybook PASS (components docs renderizam, sub-stories funcionam, tokens resolvidos, interactive controls ok) → continua Etapa 3 push (or Etapa 4 if push ja feito). FAIL → forward-fix patches + re-validar.
+
+**Generalization:** Bolt-hosted only validated empirically. Outros LLM codegen tools podem ter equivalentes:
+- v0 (Vercel): preview deployments tied to PR (similar pattern provavel)
+- Lovable: a verificar empirico
+- Cursor design rules: NAO tem preview equivalente nativo (gap real)
+- Replit: a verificar
+- Standalone: design-system com CI/CD Storybook deploy (Vercel/Netlify/Chromatic auto)
+
+**Per memoria evidence:** `feedback_storybook_dsvl_etapa_2_5_validates_spec_not_composition` (S166 NEW).
+
+### Etapa 3 — Push design-system repo (HUMAN executes)
+
+Push to design-system repo is HUMAN action. Orchestrator NEVER pushes external repos (Universal Invariant #1).
+
+Commit message format:
+```
+feat(vN): [round] [scope-summary] (sessionID)
+
+P_M [file] [type: NEW/REFINE/EXTEND]: [short description]
+P_M+1 ...
+
+Validated via canary HTML preview pre-push (substituto #7).
+Catches: [bugs catched in substituto #5 etc].
+
+Co-Authored-By: Claude (orchestrator) <noreply@anthropic.com>
+```
+
+### Etapa 4 — Human syncs Bolt + prompts + publishes
+
+Manual SaaS operation by human:
+1. Tool re-ingest auto-detected (~12min Bolt for ~1.4kL design-system, 0 tokens billing)
+2. Human prompts re-render (~2k tokens Bolt per complex screen)
+3. Tool publishes new version
+
+**Critical caveats (empirically catched):**
+- **Bolt re-ingest is ADDITIVE, not destructive** — patches that REMOVE/REPLACE existing rendered code DO NOT regenerate. Force removal via explicit prompt: "remove X" / "regenerate from scratch using latest specs". Per `feedback_bolt_reingest_additive_not_destructive`.
+- **Bolt deploy ≠ Bolt-state** — `git push` triggers source sync (~30s) but NOT deploy. Human must click Publish in Bolt UI (~1-2min Vite build). Per `feedback_bolt_deploy_requires_manual_publish_after_git_sync`.
+- **Bolt GitHub sync is ASYMMETRIC (S167 discovered)** — push (Bolt → GitHub) auto on Bolt-side changes; pull (GitHub → Bolt) NAO e auto for `trc-platform-app` consumer-project code — **requires F5 manual in Bolt UI** to trigger lazy sync. Vite re-build subsequente serves new code (~30s). DIFFERENT from design-system repo which has bidirectional auto ~12min. Implication: any flow that pushes consumer-project code (Etapa 6.5 route-around-Bolt, external commits) DEPENDS on human F5; silent failure if forgotten (deploy serves old build). Per `bolt_github_pull_requires_f5_refresh_to_resync`.
+- **Bolt rollback loses forward versions** — operates as `git reset --hard`, not `git revert`. NEVER rollback without (a) git push backup branch + (b) Bolt UI Export ZIP. Per `feedback_bolt_rollback_loses_forward_versions`.
+- **Bolt deploy URL changes when re-publish** — human provides updated URL.
+
+### Etapa 5 — Playwright autonomous validation
+
+Orchestrator validates published render independently:
+
+```
+1. mcp__plugin_playwright_playwright__browser_navigate(url)
+2. For each viewport [1920, 768, 412]:
+   a. browser_resize(width=N, height=...)
+   b. browser_take_screenshot(fullPage=true, filename=`r[N]-[viewport].png`)
+3. browser_close()
+4. Cross-check screenshots vs pre-defined R-N criteria
+5. Output: PASS/PARTIAL/FAIL table with root-cause analysis per FAIL
+```
+
+**Gate 3:** complete PASS (all R-criteria PASS) → continue Etapa 6. PARTIAL/FAIL → branch decision: trivial fix (CSS/1-line JS/token repair) → **Etapa 6.5 route-around-Bolt** (cheap). Structural refactor, new functionality, design-system code → second round full Bolt re-render (Etapa 4 → 5 again, expensive).
+
+### Etapa 6.5 — Route-around-Bolt for trivial post-G3 fixes (NEW post-S167)
+
+**When:** Gate 3 returns PARTIAL/FAIL with score close to target AND the failures are trivial (CSS one-liners, 1-line JS fixes, token chain repairs, sort comparator additions, hover state tweaks).
+
+**Why:** Full Bolt re-render costs ~500k-1M tokens for a complex screen. A 2-line CSS fix does not justify that spend. Edit the consumer-project repo directly + push + F5 in Bolt UI → free sync.
+
+**Flow (S167 empirical, validated):**
+1. **Diagnose** — orchestrator pinpoints the offending file/line in the consumer-project repo (e.g., `trc-platform-app/src/components/X.tsx` or `src/styles/Y.css`).
+2. **Dispatch implementer** with surgical scope: file path, line range, exact change. NO refactor, NO new features. Implementer writes a focused commit.
+3. **Push to GitHub** — implementer pushes to consumer-project main (or hotfix branch). Skip if push permission requires human authorization.
+4. **HUMAN F5 in Bolt UI** — orchestrator MUST explicitly remind the human: "Please F5 the Bolt UI now to trigger lazy GitHub pull. Vite will re-build (~30s)." Failure to F5 = silent stale-build failure.
+5. **Re-validate Etapa 5** — Playwright re-runs failing R-criteria only, not full screen.
+6. **Update Gate 3 status** — PARTIAL becomes PASS or escalates.
+
+**DO use for:**
+- CSS triviais (color, spacing, hover states)
+- 1-line JS bug fixes (sort comparator, conditional check)
+- Token chain repairs (e.g., `--pivot-hover-bg` aliased to wrong token)
+- Sub-rounds DSVL where final score is just shy of target
+
+**DO NOT use for:**
+- Structural refactors (component re-architecture)
+- New functionality (new components, new routes, new flows)
+- Changes that require Bolt AI re-reasoning (e.g., layout strategy shift)
+- Code in the design-system repo (different ingest mechanism, ~12min bidirectional auto-sync — use Etapa 4 normal flow)
+
+**Risk residual:** F5 is a human-action point of failure. Orchestrator MUST emit an explicit F5 reminder; ideally as an `AskUserQuestion` confirmation step before re-validating.
+
+**Token economy S167:** 2 commits (8f4dad0 + ab8858a) on `trc-platform-app` repaired AC-02 (sort) + AC-03 (hover token) → **~500k-1M Bolt tokens preserved** vs. full re-render. Wall-clock: ~5min implementer + 30s Vite build + ~30s Playwright re-validation = ~7min total vs. ~15-20min Bolt full re-render path.
+
+Per `dsvl_route_around_bolt_for_trivial_fixes` (S167) and `bolt_github_pull_requires_f5_refresh_to_resync` (S167).
+
+### Etapa 6 — Session closure (orchestrator self-driven)
+
+1. Create memorias for session learnings (type=feedback, frontmatter complete with claude_session + orchestrator_session)
+2. Update `memory-index.yaml` (project override; NOT MEMORY.md which is read-only legacy per RFC-027 Sprint 3)
+3. Update `BACKLOG.md` (bump version, update last_session, add closure paragraph, update tech-debt counters)
+4. Commit orchestrator repo (do NOT push — human authorizes separately)
+
+**Gate 4:** working tree clean, memorias indexed, BACKLOG up-to-date, commit pending for human push.
+
+## Token economics
+
+| Etapa | Wall-clock | Downstream tokens | Frequency |
+|---|---|---|---|
+| 1. Canary | ~10min initial + ~10s/iter | 0 | 1× (iters until PASS) |
+| 2. Markdown patches | ~5-10min | 0 | 1× |
+| 2.5. Storybook validate | ~5-10min | 0 (Bolt-hosted free) | 1× post-push |
+| 3. Push design-system | ~30s | 0 | 1× |
+| 4. Bolt re-ingest | ~12min | 0 (free) | 1× |
+| 4. Bolt re-render | ~30s | see capacity table below | 1× / screen |
+| 5. Playwright validate | ~30s | 0 | 1× |
+| 6.5. Route-around-Bolt fix | ~7min (if triggered) | 0 (Bolt) + ~5k Claude implementer | optional, post-G3 trivial |
+| 6. Closure | ~5min | 0 | 1× |
+
+### Bolt token capacity per screen (empirically refined S164→S167)
+
+| Screen complexity | Bolt tokens / render | Empirical sample | Plan Team 10M/month |
+|---|---|---|---|
+| **Simple** (<3 new components, no new tokens, reuse layout A/B/C) | ~700k | S163b, S165 | ~14 screens/month |
+| **Complex** (multiple new components OR new tokens OR new layout) | ~900k | S164, S166 | ~11 screens/month |
+| **Novel pattern** (external lib like TanStack Table v8 + new layout + many new tokens + new stories) | ~2M | S167 (pivot cross-tab) | ~5 screens/month |
+| Pristine project (1st screen) | ~500k | S162 outlier | n/a |
+| Incremental design-system fix | ~3k | S163b mid-fix | n/a |
+
+**Capacity planning rule of thumb (TRC Phase 1 Plan Team 10M/month):** mix profile 14 simple / 11 complex / 5 novel = ceiling. Overrun → request token bump or split screens across months. Per `feedback_bolt_tokens_per_screen_context_dependent` + S167 update with novel-pattern tier.
+
+**Total wall-clock per screen:** ~30-45min (simple) up to ~60-90min (novel pattern with route-around-Bolt sub-round).
+
+**Break-even vs naive flow:** ~2 issues. Above 2 issues, DSVL saves materially.
+- S163b: 3 issues catched in canary = ~6-12k Bolt tokens saved.
+- S164 + S165: single-shot ≥98% / 15-15 PASS confirmed canary catches issues that would cost render iterations.
+- S167: 2 PARTIAL post-G3 routed via Etapa 6.5 = ~500k-1M Bolt tokens preserved vs. full re-render.
+
+## Roles
+
+| Role | Responsibilities | Restrictions |
+|---|---|---|
+| Orchestrator | Canary write/iterate, markdown patches, pre-push verify, Playwright validate, closure (memorias + BACKLOG + local commit) | NO push external repos; NO prompt Bolt; NO unilateral palette/aesthetic decisions |
+| Human (CMAC) | Canary visual approval (Gate 1), push authorization (Gate 2 confirm + execute), Bolt sync prompt (Etapa 4), strategic audience-fit decisions | n/a — product owner + brand decisions |
+| Bolt/v0/Lovable | Ingest design-system markdown, render UI per spec, publish | NO self-validation; NO regeneration of existing code in re-ingest (additive caveat) |
+
+## Routing inside orchestrator workflow
+
+When dispatching a feature_development workflow that triggers this skill:
+
+| Phase | DSVL alignment |
+|---|---|
+| specifier | spec.md MUST list canary HTML as REQUIRED artifact (Etapa 1 deliverable). Justify if skipped. Sort-keyed semantic data MUST list comparator strategy upfront (substituto #8 prevention). |
+| planner | plan.md MUST address all 6 etapas (+ Etapa 2.5 if Bolt-hosted Storybook applies, + Etapa 6.5 fallback for trivial post-G3 fixes) explicitly. Justify if any skipped. |
+| task-generator | T-001 = canary HTML creation with explicit gate. NEVER optional. T-N (pre-push gate task) MUST run all 9 substitutos including #8 grep `.sort()` and #9 route-around-Bolt readiness check. |
+| implementer | Iterates Etapa 1 (canary CSS) until Gate 1 PASS, then Etapa 2 markdown patches with substituto #1-#5 + #8 self-check. Substitutos #6-#7 covered by Gate 1. Substituto #9 only invoked post-G3. |
+| reviewer | Audits BOTH artifact correctness AND DSVL conformance per etapa. Flag missing canary, missing substituto runs (including #8 sort verification), missing audit-trail lines, missing Etapa 2.5 Storybook validation when Bolt-hosted Storybook applies. |
+
+If workflow violates this contract, escalate to orchestrator (you) — recovery via secondary workflow costs ~80k tokens + ~7min wall-clock (S165 empirical). Prevention >> recovery.
+
+## Pair with frontend-design skill
+
+For markdown patches in responsive / aesthetic-sensitive work, invoke `frontend-design:frontend-design` skill explicitly. Default orchestrator heuristics drift toward "Tailwind generic defaults" (Inter universal, purple gradients, neumorphism) — exactly the AI-aesthetic anti-pattern DSVL prevents. Skill load ~5-30s avoids ~1h rework. Per `feedback_frontend_design_skill_for_responsive_work`.
+
+## Canary HTML skeleton
+
+```html
+<!DOCTYPE html>
+<html lang="pt-BR">
+<head>
+<meta charset="UTF-8">
+<title>[Tela] vN canary preview</title>
+<style>
+  /* design-system tokens copied verbatim from tokens.md */
+  :root { --column-decision: 720px; /* etc */ }
+  body { margin: 0; background: #FAFAF9; font-family: 'Inter Tight', system-ui; }
+  .viewport-frame { margin: 24px auto; border: 1px solid #ccc; resize: horizontal; overflow: auto; }
+  .viewport-frame[data-w="1920"] { width: 1920px; }
+  .viewport-frame[data-w="768"]  { width: 768px; }
+  .viewport-frame[data-w="412"]  { width: 412px; }
+  body.show-tags .patch-region { outline: 2px dashed magenta; }
+  /* component CSS — IDENTICAL to what will go into markdown patches */
+</style>
+</head>
+<body>
+  <div class="viewport-frame" data-w="1920"><!-- desktop render --></div>
+  <div class="viewport-frame" data-w="768"><!-- tablet render --></div>
+  <div class="viewport-frame" data-w="412"><!-- mobile render --></div>
+</body>
+</html>
+```
+
+## Generalization caveats
+
+5 applications all share: same project (TRC) + same tool (Bolt) + same design-system tier (v5) + same i18n (pt-BR). **Generalization to v0/Lovable/Cursor/Replit requires ≥1 empirical application in a distinct tool before declaring universal pattern.** Young design-systems (<5 components) may behave differently. Apply skill faithfully but treat tool-specific caveats as Bolt-anchored until empirically validated elsewhere.
+
+**Sub-patterns with stronger universal claim (validated reasoning, NOT cross-tool empirical):**
+- Substituto #8 sort order — applies to any LLM-codegen tool that translates spec markdown to JS sort logic. Lexicographic-default trap is JS-language behavior, not Bolt-specific.
+- Etapa 1 canary HTML — applies to any LLM-rendered UI tool. Local visual gate is tool-agnostic by design.
+
+**Sub-patterns Bolt-anchored (require re-validation per tool):**
+- Etapa 2.5 Storybook (Bolt-hosted Storybook URL pattern is Bolt-specific; equivalents in v0 / Lovable / Cursor / Replit unknown)
+- Etapa 6.5 route-around-Bolt (sync mechanism is Bolt-specific; F5 manual step is Bolt UI-specific)
+- Capacity baselines (700k/900k/2M token tiers are Bolt-billing-specific)
+
+## Evidence base (memorias)
+
+**Foundation (S163-S165):**
+- `feedback_html_canary_preview_before_remote_design_render` — Pattern principal Etapa 1 (S163b origin)
+- `feedback_dsvl_2nd_application_98pct_single_shot` — S164 KPICard ~98% single-shot validation
+- `feedback_dsvl_3rd_application_skill_conversion_ready` — S165 Drilldown 15/15 PASS, gate ≥3 met
+- `feedback_dsvl_canary_must_be_t001_not_optional` — S165 methodology violation + recovery, T-001 enforcement
+- `feedback_smoke_test_must_include_visual_rhythm_not_just_structure` — Substituto #6 v3 (4 layers)
+
+**Skill conversion (S166):**
+- `feedback_dsvl_skill_conversion_executed` — S166 Fase A skill conversion governance pattern
+- `feedback_dsvl_4th_application_s166_18_of_19` — S166 4th application validates skill v1 auto-enforcement
+- `feedback_storybook_dsvl_etapa_2_5_validates_spec_not_composition` — S166 NEW pattern (Etapa 2.5 Storybook)
+- `feedback_design_system_git_backup_documentary_not_recovery_vector` — S166 architectural distinction
+
+**S167 expansion (this update):**
+- `dsvl_5th_application_s167_admin_pivot_18_of_18` — S167 5th application, 2M token novel-pattern baseline
+- `dsvl_substituto_8_spec_sort_order_verification` — S167 NEW Substituto #8 (sort order)
+- `dsvl_route_around_bolt_for_trivial_fixes` — S167 NEW Etapa 6.5 + Substituto #9
+- `bolt_github_pull_requires_f5_refresh_to_resync` — S167 Bolt sync asymmetric F5 caveat
+
+**Bolt platform caveats:**
+- `feedback_bolt_reingest_additive_not_destructive` — Etapa 4 caveat (REMOVE/REPLACE prompts)
+- `feedback_bolt_deploy_requires_manual_publish_after_git_sync` — Etapa 4 caveat (Publish manual)
+- `feedback_bolt_rollback_loses_forward_versions` — Etapa 4 caveat (rollback destructive)
+- `feedback_bolt_deploy_supports_spa_routing_natively` — Etapa 4 fact (BrowserRouter default)
+- `feedback_bolt_prompt_template_v2_multi_route_clauses` — Etapa 4 prompt template (no opt-outs)
+- `feedback_bolt_tokens_per_screen_context_dependent` — Capacity planning (refined here with S167 novel tier)
+
+**Workflow / pairing:**
+- `feedback_external_ai_as_clarity_validator_not_designer` — Mining pattern for external AI feedback
+- `feedback_self_critique_beats_retroactive_defense` — receiving-code-review when render contradicts smoke test
+- `feedback_frontend_design_skill_for_responsive_work` — Skill pairing for markdown patches
+
+## Related
+
+- **Canonical doc:** `project-guidelines/processes/design-system-validated-loop.md` (354L narrative + token economics + appendix)
+- **RFC-022:** Skill-based orchestration (skill conversion target spec)
+- **ADR-019:** Three-layer orchestrator identity (this skill is Layer B — loaded on demand)
+- **CLAUDE.md Universal Invariants:** Memory protocol + workflow start rule

package/skills/finishing-branch/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: finishing-branch
+description: "Use when implementation is complete and all tests pass — guides the decision and execution of merge, PR, or branch cleanup."
+triggers:
+  - "When implementation work is done"
+  - "When the user says 'we're done' or 'ship it'"
+  - "After all tasks in a workflow are complete"
+  - "When asked how to integrate completed work"
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-branch skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Determine Base Branch
+
+```bash
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main — is that correct?"
+
+### Step 3: Present Options
+
+Present exactly these 4 options:
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Don't add explanation** — keep options concise.
+
+### Step 4: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+<test command>
+git branch -d <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 2: Push and Create PR
+
+```bash
+git push -u origin <feature-branch>
+
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+### Step 5: Cleanup Worktree
+
+**For Options 1, 2, 4:**
+
+Check if in worktree:
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | Yes | - | - | Yes |
+| 2. Create PR | - | Yes | Yes | - |
+| 3. Keep as-is | - | - | Yes | - |
+| 4. Discard | - | - | - | Yes (force) |
+
+## Common Mistakes
+
+**Skipping test verification**
+- Problem: Merge broken code, create failing PR
+- Fix: Always verify tests before offering options
+
+**Open-ended questions**
+- Problem: "What should I do next?" — ambiguous
+- Fix: Present exactly 4 structured options
+
+**Automatic worktree cleanup**
+- Problem: Remove worktree when might need it (Option 2, 3)
+- Fix: Only cleanup for Options 1 and 4
+
+**No confirmation for discard**
+- Problem: Accidentally delete work
+- Fix: Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+
+**Always:**
+- Verify tests before offering options
+- Present exactly 4 options
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 and 4 only