sdd-layer 0.26.1

Spec-Driven Development CLI and agent harness
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# Formato do Relatório HTML

## Scaffold

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Architecture review — {{repo name}}</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <script type="module">
      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
    </script>
    <style>
      /* small custom layer for things Tailwind doesn't cover cleanly:
         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
      .seam { stroke-dasharray: 4 4; }
      .leak { stroke: #dc2626; }
      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
    </style>
  </head>
  <body class="bg-stone-50 text-slate-900 font-sans">
    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
      <header>...</header>
      <section id="candidates" class="space-y-10">...</section>
      <section id="top-recommendation">...</section>
    </main>
  </body>
</html>
```

## Header

Nome do repo, data, e uma legenda compacta: caixa sólida = module, linha tracejada = seam, seta vermelha = leakage, caixa escura grossa = deep module. Sem parágrafo de introdução — direto para os candidatos.

## Card de candidato

Os diagramas carregam o peso. A prosa é enxuta, clara, e usa os termos do glossário (da skill `/codebase-design`) sem cerimônia.

Cada candidato é um `<article>`:

- **Title** — curto, nomeia o deepening (ex: "Collapse the Order intake pipeline").
- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), mais uma tag para a categoria de dependência (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
- **Files** — lista monospaced, `font-mono text-sm`.
- **Before / After diagram** — o centro da peça. Duas colunas, lado a lado. Veja padrões abaixo.
- **Problem** — uma frase. O que dói.
- **Solution** — uma frase. O que muda.
- **Wins** — bullets, ≤6 palavras cada. ex: "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
- **ADR callout** (se aplicável) — uma linha em uma caixa amber-tinted.

Sem parágrafos de explicação. Se o diagrama precisa de um parágrafo para ser entendido, redesenhe o diagrama.

## Padrões de diagrama

Escolha o padrão que se encaixa no candidato. Misture-os. Não faça todo diagrama parecer o mesmo — variedade é parte do ponto.

### Mermaid graph (o workhorse para dependências / call flow)

Use um Mermaid `flowchart` ou `graph` quando o ponto é "X chama Y chama Z, e olha o caos." Envolva em um card estilizado com Tailwind para não parecer parachutado. Estilize com classDef para colorir edges de leakage em vermelho e o deep module em escuro. Sequence diagrams funcionam bem para "before: 6 round-trips; after: 1."

```html
<div class="rounded-lg border border-slate-200 bg-white p-4">
  <pre class="mermaid">
    flowchart LR
      A[OrderHandler] --> B[OrderValidator]
      B --> C[OrderRepo]
      C -.leak.-> D[PricingClient]
      classDef leak stroke:#dc2626,stroke-width:2px;
      class C,D leak
  </pre>
</div>
```

### Boxes-and-arrows feitos à mão (quando o layout do Mermaid briga com você)

Módulos como `<div>`s com bordas e labels. Setas como inline SVG `<line>` ou `<path>` posicionados absolutamente sobre um container relative. Alcance isto quando você quer que o diagrama "after" pareça um deep module de borda grossa com internals acinzentados — Mermaid não renderiza isso com o peso certo.

### Cross-section (bom para rasidão em camadas)

Empilhe bandas horizontais (`h-12 border-l-4`) para mostrar camadas por onde uma chamada passa. Before: 6 camadas finas cada uma não fazendo nada. After: 1 banda grossa rotulada com a responsabilidade consolidada.

### Mass diagram (bom para "interface tão larga quanto implementação")

Dois retângulos por módulo — um para área de superfície da interface, um para implementação. Before: retângulo da interface quase tão alto quanto o da implementação (raso). After: retângulo da interface é baixo, o da implementação é alto (profundo).

### Call-graph collapse

Before: uma árvore de chamadas de função renderizada como nested boxes. After: a mesma árvore colapsada em uma caixa, com as chamadas agora internas mostradas faded dentro dela.

## Orientação de estilo

- Editorial enxuto, não corporate-dashboard. Whitespace generoso. Serif opcional para headings (`font-serif` funciona bem com stone/slate).
- Cor com parcimônia: um accent (emerald ou indigo) mais vermelho para leakage e amber para warnings.
- Mantenha diagramas ~320px de altura para before/after sentar confortavelmente lado a lado sem scroll.
- Use `text-xs uppercase tracking-wider` para labels de módulos dentro de diagramas — devem ler como esquemático, não como UI.
- Os únicos scripts são o Tailwind CDN e o Mermaid ESM import. O relatório é otherwise estático — sem app code, sem interatividade além da renderização do Mermaid.

## Seção Top recommendation

Um card maior. Nome do candidato, uma frase do porquê, anchor link para seu card. Só isso.

## Tom

Português claro, conciso — mas os substantivos e verbos arquiteturais vêm direto da skill `/codebase-design`. Concisão não é desculpa para derivar.

**Use exatamente:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.

**Nunca substitua:** component, service, unit (por module) · API, signature (por interface) · boundary (por seam) · layer, wrapper (por module, quando você quer dizer module).

**Frases que se encaixam no estilo:**

- "O módulo de Order intake é raso — interface quase igual à implementação."
- "Pricing vaza através do seam."
- "Deepen: uma interface, um lugar para testar."
- "Dois adapters justificam o seam: HTTP em prod, in-memory em testes."

**Bullets de Wins** nomeiam o ganho em termos do glossário: *"locality: bugs concentram em um módulo"*, *"leverage: uma interface, N call sites"*, *"interface encolhe; implementação absorve os wrappers"*. Não escreva *"mais fácil de manter"* ou *"código mais limpo"* — esses termos não estão no glossário e não ganham seu lugar.