freeharness 0.4.1

package/canonical/skills/report-formatting/scripts/architecture-template.md

@@ -0,0 +1,271 @@
+---
+lang: pt-BR
+app: <app>
+title: <app> — <papel do sistema em uma linha>
+doc_type: Documento de Arquitetura de Software e System Design
+version: <1.0>
+status: <Em revisão | Aprovado | Rascunho>
+date: <DD/MM/AAAA>
+audience: <Arquitetura de IA, CCoE, time de desenvolvimento>
+system_version: <x.y.z-commit ou tag do código descrito>
+project: <Projeto> — Claro
+org: <Área> | DADOS & IA
+author: André Negrelli
+role: Tech Lead AI Data Engineer
+area: DADOS & IA
+---
+<!--
+Architecture & System Design model (reference/ARCHITECTURE.md). Fixed sections, in
+this order; the build fails on an unknown or missing mandatory section. Numbered
+sections are numbered automatically (0. Sumário executivo ...), "### " sub-headings
+get "N.k" numbers, "#### " are unnumbered. Diagrams: ```mermaid blocks are rendered
+and embedded (title + legend inside the diagram; one concern per diagram); a line
+"Figura N – ..." right after becomes the caption. Callouts: "> **Nota:** ..." explains a
+non-trivial concept in two or three lines. Pointers to code as `path/file.py:line`.
+Every number comes from a measurement, a manifest, a test run or a commit. "<!-- width: 70 -->" before a diagram scales it to 70 % of the text width; "<!-- cols: 30 70 -->" before a table fixes column widths. Comments like this one are never rendered. Sections marked "agentic" are mandatory for
+LLM/agent systems; for a plain service write "Não se aplica." and say why in one line.
+-->
+
+## Elaboração e revisão
+<!-- mandatory · who wrote, designed and reviewed; then the cover table is printed from the front matter. -->
+| Nome | Papel | Responsabilidade |
+|---|---|---|
+| <Nome> | <Tech Lead — AI Data Engineer> | <Elaboração, desenho e revisão técnica> |
+| <Nome> | <Arquiteto de IA / revisor> | <Revisão> |
+
+## Histórico de revisões
+<!-- mandatory · one row per issued version of THIS document. -->
+| Versão | Data | Responsável | Descrição |
+|---|---|---|---|
+| <1.0> | <DD/MM/AAAA> | <Nome> | <Emissão para revisão> |
+
+## Convenções
+<!-- optional · how to read the document and where the other documents are. -->
+**Convenções deste documento.** Diagramas em Mermaid (C4 e sequência). Callouts explicam, em duas ou três linhas, conceitos não triviais. Ponteiros `arquivo:linha` apontam para o código descrito, na versão `<system_version>`.
+
+**Outros documentos.** <guia de operação>, <guia de deploy>, <inventário de variáveis>, <caderno de testes>, <release notes>.
+
+## Sumário executivo
+<!-- mandatory · arc42 §1+§4 in one page: what the system is, for whom, the core solution strategy (workflow vs agent, orchestration pattern, framework, model tier, persistence), and the architecture principles that constrain every decision. -->
+<O que o sistema é, para quem, o que entra e o que sai, volume-alvo e o que ele NÃO faz — em um parágrafo.>
+
+<Estratégia da solução em um parágrafo: por que este nível de complexidade (chamada direta ao modelo → agente único com ferramentas → multiagente), padrão de orquestração escolhido, framework, modelo por tarefa, persistência.>
+
+### Princípios de arquitetura
+| # | Princípio | Consequência de desenho |
+|---|---|---|
+| P1 | <princípio em uma frase> | <o que ele obriga ou proíbe no código> |
+| P2 | <...> | <...> |
+
+## Visão e contexto
+<!-- mandatory · arc42 §1-3 + ISO 42010: goals and non-goals, stakeholders and their concerns, constraints (technical, organisational, regulatory/LGPD, cost/latency ceilings), business and technical context with the C4 L1 diagram. For agents: which systems it may act upon vs only read. -->
+### Objetivos e não objetivos
+- **Objetivo:** <meta mensurável>.
+- **Não objetivo:** <o que fica explicitamente fora>.
+
+### Stakeholders e preocupações
+| Stakeholder | Preocupação | Onde é respondida |
+|---|---|---|
+| <Operação / CCoE> | <disponibilidade, custo, rollback> | <§ Infraestrutura, § Observabilidade> |
+| <Negócio> | <qualidade da resposta, prazo> | <§ Atributos de qualidade> |
+
+### Restrições
+- <Técnica: plataforma, linguagem, provedor de modelo, versão de runtime.>
+- <Organizacional: times, janelas, aprovações.>
+- <Regulatória: LGPD/PII, residência de dados, termos do provedor.>
+- <Orçamento: teto de custo por execução, latência-alvo.>
+
+### Contexto de negócio e técnico
+<!-- width: 75 -->
+```mermaid
+C4Context
+  title Contexto do sistema (C4 L1)
+  Person(user, "Usuário/Operador", "quem aciona e quem opera")
+  System(sys, "<app>", "<papel em uma linha>")
+  System_Ext(llm, "Provedor de modelo", "API de inferência")
+  System_Ext(ext, "<sistema externo>", "<fila, CRM, bucket>")
+  Rel(user, sys, "aciona", "HTTPS")
+  Rel(sys, llm, "inferência", "HTTPS")
+  Rel(sys, ext, "lê/grava", "<protocolo>")
+```
+Figura 1 – Contexto do sistema (C4 L1): atores, sistemas externos e protocolos.
+
+<Tabela ou lista: sobre quais sistemas o agente AGE e quais ele apenas LÊ.>
+
+## Visão lógica
+<!-- mandatory · C4 L2 containers (runtime, agent, stores, queues, MCP servers, observability) and L3 components of the agent container; layers / bounded contexts and the rule each layer obeys. -->
+<!-- width: 75 -->
+```mermaid
+C4Container
+  title Containers (C4 L2)
+  Person(user, "Usuário")
+  Container(api, "<API / worker>", "<tecnologia>", "<responsabilidade>")
+  Container(agent, "<runtime do agente>", "<LangGraph / ...>", "<orquestra nós e ferramentas>")
+  ContainerDb(db, "<estado / checkpoints>", "<PostgreSQL>", "<o que persiste>")
+  System_Ext(llm, "Provedor de modelo", "")
+  Rel(user, api, "HTTPS")
+  Rel(api, agent, "invoca")
+  Rel(agent, db, "lê/grava estado")
+  Rel(agent, llm, "inferência")
+```
+Figura 2 – Containers (C4 L2) e fronteiras de confiança.
+
+| Camada | Módulos | Regra |
+|---|---|---|
+| <Composição> | `<cli.py>` | <único lugar que constrói configuração e clientes> |
+| <Domínio> | `<pacote>` | <não importa infraestrutura> |
+
+## Estrutura de diretório
+<!-- optional · the source tree with one comment per directory (code block). -->
+```
+<app>/
+  src/<pacote>/      # <o que vive aqui>
+  tests/             # <caderno de testes>
+  deploy/            # <manifests e perfis>
+```
+
+## Agentes e orquestração
+<!-- agentic (mandatory for LLM/agent systems; "Não se aplica." otherwise) · topology and pattern with the justification for the complexity level; loop exit conditions and iteration caps; state & memory model; tool contracts with side-effect class, risk and permission scope (MCP/A2A boundaries); model/prompt/config registry and promotion path; human-in-the-loop gates. -->
+### Topologia e padrão de orquestração
+```mermaid
+flowchart LR
+  subgraph Orquestrador
+    S[supervisor] -->|tool call| A[agente A]
+    S -->|tool call| B[agente B]
+  end
+  A -->|handoff| B
+```
+Figura 3 – Topologia de agentes: arestas de tool call vs handoff; condições de saída do loop e limite de iterações.
+
+| Agente / nó | Papel | Modelo | Ferramentas | Saída do loop |
+|---|---|---|---|---|
+| `<supervisor>` | <roteia e consolida> | `<modelo@versão>` | <lista> | <resposta final \| sem tool call \| N turnos \| erro \| HITL> |
+
+### Estado e memória
+| Camada | Onde vive | Escopo / chave | Papel |
+|---|---|---|---|
+| <Estado do grafo> | <checkpointer (PostgreSQL)> | <thread_id> | <retomada sem repetir trabalho> |
+| <Memória de longo prazo> | <store> | <user_id> | <preferências / fatos> |
+
+### Ferramentas e integrações
+| Ferramenta | Contrato (schema) | Efeito colateral | Risco | Permissão / identidade | Via |
+|---|---|---|---|---|---|
+| `<tool>` | <entrada → saída> | <leitura \| escrita \| irreversível> | <baixo \| médio \| alto> | <least privilege, usuário propagado> | <MCP (stdio/HTTP) \| A2A \| SDK> |
+
+### Modelos, prompts e configuração
+| Item | Versão fixada | Promoção |
+|---|---|---|
+| Modelo `<papel>` | `<id/snapshot, quantização>` | <dev → hml → prd com eval> |
+| Prompt `<nome>` | `<id@versão \| hash>` | <gate de regressão> |
+
+### Human-in-the-loop
+<Portões (obrigatórios vs opcionais), gatilhos (ação irreversível, alto risco, limiar de falha), o que é persistido no portão para retomar.>
+
+## Visão de runtime
+<!-- mandatory · 2-3 key scenarios as sequence diagrams (one failure path, one HITL/interrupt-resume when applicable); the agent loop as a state machine; concurrency model; lifecycle of a request/message; failures, retries, idempotency, degradation. -->
+### Cenário principal
+```mermaid
+sequenceDiagram
+  participant U as Usuário
+  participant A as <app>
+  participant M as Modelo
+  U->>A: requisição
+  A->>M: prompt + contexto
+  M-->>A: resposta
+  A-->>U: resultado validado
+```
+Figura 4 – Cenário principal.
+
+### Falhas, retentativas e idempotência
+| Classificação | Significado | Destino |
+|---|---|---|
+| <permanente> | <repetir não muda> | <registro + DLQ> |
+| <transitória> | <dependência indisponível> | <retry com backoff; circuit breaker> |
+
+## Contratos
+<!-- mandatory · input/output messages, APIs, stored objects — fields, schemas, versioning rule (additive keys only), examples. -->
+### <Contrato de entrada>
+<Campos, tipos, defaults, o que é ignorado, versão.>
+
+### <Contrato de saída / objeto persistido>
+<Campos, chaves congeladas vs aditivas, `contract_version`.>
+
+## Dados, memória e persistência
+<!-- optional (recommended for agentic) · stores, cache layers, queues, retention, PII handling, lineage of grounding data. -->
+| Dado | Onde | Retenção | PII / tratamento |
+|---|---|---|---|
+| <trilha de decisão> | <PostgreSQL> | <90 dias> | <redigido em log/trace> |
+
+## Configuração e ambiente
+<!-- optional · reader of the environment, groups, sensitivity, defaults that changed, where the inventory lives. -->
+<Quem lê o ambiente, grupos de variáveis, sensibilidade (secret | identifier | plain), defaults e inventário.>
+
+## Infraestrutura e recursos
+<!-- mandatory · C4 deployment: environments, topology, network boundaries, secrets, pod/instance resources, capacity and autoscaling, cost model. -->
+### Topologia
+<Ambientes, cluster/região, objetos criados, fronteiras de rede, segredos.>
+
+### Capacidade, escala e custo
+| Grandeza | Valor | Origem |
+|---|---|---|
+| <volume-alvo> | <1,6 M/dia> | <requisito> |
+| <custo por execução> | <R$ / tokens> | <medido em DD/MM> |
+
+## Observabilidade
+<!-- mandatory · logs, metrics, traces (OTel GenAI spans: invoke_agent, chat, execute_tool, retrieval; token/latency per agent; content capture policy), correlation ids, dashboards/alerts, what is never logged. -->
+| Sinal | Como |
+|---|---|
+| Logs | <JSON estruturado; correlação por id; nunca texto do cliente> |
+| Métricas | <por agente: tokens, latência, erros> |
+| Traces | <OTLP; spans GenAI; conteúdo/PII não capturado> |
+
+## Segurança e AI Safety
+<!-- mandatory · principles, threat model mapped to OWASP LLM Top 10 (2025) with a guardrail at each trust boundary (input, tool call, tool result, output), secrets, identities/least privilege, data governance. -->
+### Princípios
+- <Entrada não confiável é sanitizada e delimitada; decisão de negócio nunca depende de texto livre.>
+- <Segredos fora do repositório; credencial nunca em log.>
+
+### Modelo de ameaças
+| Ameaça (OWASP LLM) | Vetor | Mitigação | Verificação |
+|---|---|---|---|
+| LLM01 Prompt injection | <texto livre, documento recuperado, resultado de ferramenta> | <sanitização, delimitação, saída tipada> | <suíte adversarial como regressão> |
+| LLM06 Excessive agency | <ferramenta com escrita> | <least privilege, HITL> | <teste de permissão> |
+
+## Atributos de qualidade, avaliação e testes
+<!-- mandatory · quality-attribute scenarios (SEI: stimulus → response measure), the eval strategy and release gates (datasets@version, scorers / LLM-as-judge, thresholds), the test suite and structural gates. -->
+| Atributo | Cenário / requisito | Como o desenho atende | Medida |
+|---|---|---|---|
+| <Latência> | <p95 < N s em carga X> | <assíncrono, filas> | <medido em DD/MM> |
+| <Qualidade da resposta> | <eval suite@versão ≥ limiar> | <gate de release> | <resultado> |
+
+<Suíte de testes: o que roda por padrão, gates estruturais, o que exige GPU/rede/amostras.>
+
+## Decisões de arquitetura
+<!-- mandatory · ADR log: one row per significant decision with rationale and consequence (alternatives considered inline or linked). -->
+| ADR | Decisão | Motivo | Consequência / alternativas rejeitadas |
+|---|---|---|---|
+| 01 | <decisão> | <por quê> | <o que custa; o que foi descartado> |
+
+## Riscos, premissas e pontos em aberto
+<!-- mandatory · premises/constraints with origin; risks and open items with impact, owner and status. -->
+| # | Item | Impacto | Dono | Status |
+|---|---|---|---|---|
+| 1 | <risco ou ponto em aberto> | <o que bloqueia> | <quem> | <Aberto \| Mitigado> |
+
+## Roadmap e fases
+<!-- optional · phases, what is out of scope now, migration steps, capacity/cost per phase. -->
+- <Fase 1: ...> — <critério de saída>.
+
+## Rastreabilidade e referências
+<!-- mandatory · requirement/US/CCDA → component → test; related documents (guide, deploy, release notes, specs). -->
+| Requisito | Componente | Verificação |
+|---|---|---|
+| <US/CCDA/spec> | <módulo> | <teste / eval> |
+
+- <Documento relacionado e caminho.>
+
+## Glossário
+<!-- optional · domain and agent terms. -->
+| Termo | Significado |
+|---|---|
+| <Handoff> | <transferência de controle entre agentes> |

package/canonical/skills/report-formatting/scripts/assets/claro-wordmark.svg

@@ -0,0 +1 @@
+<svg width="425.3" height="159.7" viewBox="0 0 425.3 159.7" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" overflow="visible"><defs/><g id="g116-4_1_" transform="translate(654.66 -4.54285)"><path d="M-343.6 4.5C-337.7 4.6-331.8 4.5-325.8 4.5-325.8 22.7-325.8 40.8-325.8 59-331.7 59-337.7 59-343.6 59-343.6 40.9-343.6 22.7-343.6 4.5M-304.3 66C-288 49.2-271.9 32.2-255.7 15.4-251.5 19.8-247.2 24.1-243.1 28.6-259.2 45.6-275.4 62.3-291.5 79.3-295.9 74.9-300 70.4-304.3 66M-616 56C-611.5 54.9-606.9 54.3-602.3 54.5-587 54.1-572.2 62.2-562.7 74.5-558.2 80.3-554.9 87.2-553.1 94.4-560.1 94.4-567.1 94.4-574.1 94.4-577.2 88-581.9 82.3-588.1 79-591.5 77.1-595.2 75.8-599.1 75.3-602.7 75.2-606.3 74.9-609.9 75.9-615.8 77.2-621.3 80.5-625.5 85-631 90.3-634.6 97.9-634.9 105.7-635.6 113.2-634.2 121-630.1 127.3-626.2 133.3-620.6 138.4-614 140.9-603 145.2-589.6 142.6-581.2 133.9-578.4 130.9-575.9 127.4-574.1 123.7-567.1 123.7-560.2 123.7-553.2 123.7-554.9 131.4-558.7 138.5-563.4 144.6-566.7 148.1-569.9 151.9-573.9 154.5-591.9 167.4-618 166.7-634.9 152.1-640.2 147.4-645 142.1-648.3 135.7-654.4 124.4-655.9 110.9-653.8 98.3-652 87.6-646.6 77.7-639.2 70.2-632.8 63.3-624.8 58.2-616 56M-542.5 54.5C-535.9 54.5-529.2 54.5-522.6 54.5-522.6 91.1-522.6 127.6-522.6 164.2-529.2 164.2-535.9 164.2-542.5 164.2-542.5 127.6-542.5 91.1-542.5 54.5M-482.2 76.3C-478.4 75.5-474.6 76-470.7 75.9-466.3 76.3-461.8 77-457.6 78.5-453.4 80-449 81.9-446.1 85.6-442.6 89.9-441.4 95.7-441.1 101.2-441.1 122.2-441.1 143.2-441.1 164.2-447.8 164.2-454.6 164.3-461.3 164.1-461.4 161.2-461.2 158.4-461.3 155.5-467.2 160.8-474.9 163.2-482.5 163.8-487.3 164.7-492.3 163.9-496.9 162.3-502.8 160.3-507.7 155.1-509.4 148.9-511.3 142.2-510.9 135-508.7 128.4-506.3 121.8-500.5 117-494.2 114.9-486.1 111.9-477.4 111.4-469 109.7-466.1 109.7-463.2 107.8-462.1 105-461.3 101.9-462 98-464.6 96-467.5 94-471 93.6-474.4 93.5-477.4 93.6-480.6 93.6-483.2 95.3-486.7 97.3-488.2 101.4-488.9 105.3-495.6 105.2-502.3 105.3-508.9 105.2-508.1 98.3-506.7 91-502 85.8-497.3 79.8-489.6 76.9-482.2 76.3M-467.5 123.8C-471.4 124.8-475.3 126-479.3 126.6-482.5 127.3-485.8 128.3-488.1 130.9-491.3 134.8-491.5 140.8-489 145.1-487.9 147.1-485.8 148.1-483.9 148.8-477.6 150.1-470.6 148-466 143.3-461.3 137.1-462.1 128.8-462.1 121.3-464.1 121.9-465.6 123.4-467.5 123.8M-393.6 78.8C-389.5 77.7-385.4 76-381.1 76.4-381.1 83.5-380.7 90.6-380.8 97.7-384.5 97.2-388.3 96.7-391.9 97.9-399.7 100.1-406.2 107.3-407.1 115.8-407.2 117.7-407.6 119.5-407.7 121.4-407.7 135.7-407.7 149.9-407.7 164.2-414.3 164.2-421 164.2-427.6 164.2-427.7 136.1-427.6 108-427.6 80-421.2 79.9-414.8 80.2-408.3 80.4-408.3 83.9-408.4 87.3-408.3 90.8-404.6 85.5-399.6 81-393.6 78.8M-344 76.7C-341 76.4-338 76.1-335.1 76.4-317.2 76.6-300.9 91-296.6 109-292.9 123.7-296.5 140.6-307.1 151.2-313.3 158.1-321.7 162.8-330.7 164.3-335 164.3-339.3 164.3-343.7 164.3-356.6 162.4-367.8 153.2-374.2 141.6-380.8 128.8-380.8 112.6-374.4 99.8-368.1 87.9-356.9 78.6-344 76.7M-342.4 97.5C-348.4 98.9-353.4 103.3-356.5 108.7-361 116.6-360.3 127.5-354.7 134.6-348.9 143.2-337.1 146.2-328.1 141.7-322.8 139.2-318.8 134.4-316.6 128.9-314.1 122.6-314.6 115.2-317.5 109.2-320.6 103.1-326.4 98.3-333 97.2-336 97-339.2 96.9-342.4 97.5M-282.7 100.6C-264.9 100.6-247.2 100.6-229.4 100.6-229.4 106.8-229.4 112.9-229.4 119.1-247.2 119.1-264.9 119.1-282.7 119.1-282.7 113-282.6 106.8-282.7 100.6L-282.7 100.6Z" id="path114-5_1_" fill="#FFFFFF"/></g></svg>

package/canonical/skills/report-formatting/scripts/build-architecture.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * build-architecture.js — Software Architecture & System Design document (.docx,
+ * Claro theme) from a content file with fixed sections. Generic: system, version and
+ * authors come from the content file (architecture-template.md; guide
+ * reference/ARCHITECTURE.md). Engine: docmodel.js.
+ *
+ *   node build-architecture.js <architecture.md> <output.docx>
+ */
+
+const { main } = require("./docmodel");
+
+const model = {
+  name: "architecture",
+  layout: "compact",
+  cover: "page",                                   // cover page + table of contents
+  tocTitle: "Sumário",
+  coverTitle: "Documento de Arquitetura de Software",
+  subtitle: (m) => m.title,                         // system name + one-line role
+  tagline: (m) => "System Design",
+  org: (m) => m.org || m.project,
+  title: (m) => m.title,
+  headerText: (m) => `Documento de Arquitetura de Software — ${m.app}  |  ${m.project || ""}`.replace(/\s+\|\s+$/, ""),
+  requiredMeta: ["app", "title", "version", "date", "status"],
+  meta: [
+    ["app", "Aplicação"], ["doc_type", "Tipo de documento"], ["version", "Versão do documento"],
+    ["status", "Status"], ["date", "Data de emissão"], ["audience", "Público"], ["system_version", "Versão do sistema"],
+  ],
+  monoMeta: ["system_version"],
+  numberFrom: 0,                                    // numbered sections start at "0. Sumário executivo"
+  sections: [
+    { title: "Elaboração e revisão", key: "authors", mandatory: true },
+    { title: "Histórico de revisões", key: "history", mandatory: true },
+    { title: "Convenções", key: "conventions", mandatory: false },
+    { title: "Sumário executivo", key: "summary", mandatory: true, numbered: true },
+    { title: "Visão e contexto", key: "context", mandatory: true, numbered: true },
+    { title: "Visão lógica", key: "logical", mandatory: true, numbered: true },
+    { title: "Estrutura de diretório", key: "tree", mandatory: false, numbered: true },
+    { title: "Agentes e orquestração", key: "agents", mandatory: true, numbered: true },
+    { title: "Visão de runtime", key: "runtime", mandatory: true, numbered: true },
+    { title: "Contratos", key: "contracts", mandatory: true, numbered: true },
+    { title: "Dados, memória e persistência", key: "data", mandatory: false, numbered: true },
+    { title: "Configuração e ambiente", key: "config", mandatory: false, numbered: true },
+    { title: "Infraestrutura e recursos", key: "infra", mandatory: true, numbered: true },
+    { title: "Observabilidade", key: "observability", mandatory: true, numbered: true },
+    { title: "Segurança e AI Safety", key: "security", mandatory: true, numbered: true },
+    { title: "Atributos de qualidade, avaliação e testes", key: "quality", mandatory: true, numbered: true },
+    { title: "Decisões de arquitetura", key: "decisions", mandatory: true, numbered: true },
+    { title: "Riscos, premissas e pontos em aberto", key: "risks", mandatory: true, numbered: true },
+    { title: "Roadmap e fases", key: "roadmap", mandatory: false, numbered: true },
+    { title: "Rastreabilidade e referências", key: "refs", mandatory: true, numbered: true },
+    { title: "Glossário", key: "glossary", mandatory: false },
+  ],
+};
+
+main(model);

package/canonical/skills/report-formatting/scripts/build-md-claro.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * build-md-claro.js — render a Markdown document into the Claro theme, faithfully.
+ *
+ * Usage:
+ *   node build-md-claro.js <input.md> <output.docx> [--diagrams DIR] [--title T] [--subtitle S]
+ *        [--header H] [--author NAME] [--role ROLE] [--project P] [--skip-h1]
+ *        [--meta "Chave=Valor;Chave=Valor"]   (metadata table under the cover)
+ *
+ * Every Markdown block maps to one theme helper: `##` -> h1, `###` -> h2, `####` -> h3,
+ * paragraphs (inline code, bold, italic), bullet and numbered lists (two levels),
+ * pipe tables, fenced code (```mermaid -> pre-rendered diagram_NN.png in --diagrams, in
+ * document order; other fences -> codeBlock), blockquotes -> info callout, `---` -> spacer.
+ * Nothing is added or dropped: what is not recognised is emitted as body text.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { Packer, AlignmentType } = require("docx");
+const T = require("./theme-claro");
+
+// ---- args -----------------------------------------------------------------
+const argv = process.argv.slice(2);
+const positional = [];
+const opt = { diagrams: null, title: null, subtitle: null, header: "", author: "", role: "", project: "", skipH1: false, meta: null };
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--diagrams") opt.diagrams = argv[++i];
+  else if (a === "--title") opt.title = argv[++i];
+  else if (a === "--subtitle") opt.subtitle = argv[++i];
+  else if (a === "--header") opt.header = argv[++i];
+  else if (a === "--author") opt.author = argv[++i];
+  else if (a === "--role") opt.role = argv[++i];
+  else if (a === "--project") opt.project = argv[++i];
+  else if (a === "--skip-h1") opt.skipH1 = true;
+  else if (a === "--meta") opt.meta = argv[++i];
+  else positional.push(a);
+}
+const [inputPath, outputPath] = positional;
+if (!inputPath || !outputPath) {
+  console.error("usage: build-md-claro.js <input.md> <output.docx> [options]");
+  process.exit(2);
+}
+const md = fs.readFileSync(inputPath, "utf8").split(/\r?\n/);
+
+// ---- inline ---------------------------------------------------------------
+const BODY = 22, MONO = 18, CELL = 20, CELL_MONO = 17;
+function inline(text, size = BODY, monoSize = MONO, color = T.C.body) {
+  const runs = [];
+  const parts = text.split(/(`[^`]+`)/g);
+  for (const part of parts) {
+    if (!part) continue;
+    if (part.length >= 2 && part.startsWith("`") && part.endsWith("`")) {
+      runs.push(T.mono(part.slice(1, -1), monoSize));
+      continue;
+    }
+    // bold, then italic inside the remainder
+    const bolds = part.split(/(\*\*[^*]+\*\*)/g);
+    for (const b of bolds) {
+      if (!b) continue;
+      if (b.length >= 4 && b.startsWith("**") && b.endsWith("**")) {
+        runs.push(T.t(b.slice(2, -2), { size, bold: true, color }));
+        continue;
+      }
+      const its = b.split(/(\*[^*\s][^*]*\*)/g);
+      for (const it of its) {
+        if (!it) continue;
+        if (it.length >= 3 && it.startsWith("*") && it.endsWith("*")) runs.push(T.t(it.slice(1, -1), { size, italics: true, color }));
+        else runs.push(T.t(it, { size, color }));
+      }
+    }
+  }
+  return runs;
+}
+const stripLinks = (s) => s.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+
+// ---- table ----------------------------------------------------------------
+function splitRow(line) {
+  let s = line.trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  if (s.endsWith("|")) s = s.slice(0, -1);
+  return s.split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, "|"));
+}
+function tableWidths(head, rows) {
+  const n = head.length;
+  const maxLen = head.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] || "").length)));
+  const total = maxLen.reduce((a, b) => a + b, 0) || 1;
+  // floor: the longest single word of the column must fit on one line (~95 DXA per char)
+  const longestWord = head.map((h, i) => Math.max(...[h, ...rows.map((r) => r[i] || "")].flatMap((c) => c.replace(/`/g, "").split(/\s+/)).map((w) => w.length)));
+  let widths = maxLen.map((l, i) => Math.max(1200, longestWord[i] * 95 + 220, Math.round((l / total) * T.CONTENT_W)));
+  const sum = widths.reduce((a, b) => a + b, 0);
+  widths = widths.map((w) => Math.round((w / sum) * T.CONTENT_W));
+  widths[n - 1] += T.CONTENT_W - widths.reduce((a, b) => a + b, 0);
+  return widths;
+}
+
+// ---- walk -----------------------------------------------------------------
+const children = [];
+let diagramIndex = 0;
+let firstH1 = true;
+let i = 0;
+let listInstance = 0;
+const isTableLine = (l) => /^\s*\|.*\|\s*$/.test(l);
+const isSep = (l) => /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/.test(l);
+
+while (i < md.length) {
+  const line = md[i];
+
+  if (/^\s*$/.test(line)) { i++; continue; }
+  if (/^---+\s*$/.test(line)) { children.push(T.spacer(120)); i++; continue; }
+
+  // fenced code
+  const fence = line.match(/^(\s*)```(\w+)?\s*$/);
+  if (fence) {
+    // Indented fences (inside list items) are fences too; their indent is stripped.
+    const indent = fence[1].length;
+    const lang = (fence[2] || "").toLowerCase();
+    const buf = [];
+    i++;
+    while (i < md.length && !/^\s*```\s*$/.test(md[i])) { buf.push(md[i].slice(Math.min(indent, md[i].match(/^\s*/)[0].length))); i++; }
+    i++;
+    if (lang === "mermaid") {
+      diagramIndex++;
+      const png = opt.diagrams ? path.join(opt.diagrams, `diagram_${String(diagramIndex).padStart(2, "0")}.png`) : null;
+      if (png && fs.existsSync(png)) {
+        children.push(T.image(png, 6050000));
+        children.push(T.caption(`Figura ${diagramIndex}`, { center: true }));
+      } else {
+        children.push(T.codeBlock(buf));
+      }
+    } else {
+      children.push(T.codeBlock(buf.length ? buf : [""]));
+    }
+    continue;
+  }
+
+  // headings
+  const h = line.match(/^(#{1,4})\s+(.*)$/);
+  if (h) {
+    const level = h[1].length;
+    const text = stripLinks(h[2].trim());
+    if (level === 1) {
+      if (firstH1) { firstH1 = false; if (opt.skipH1) { i++; continue; } }
+      children.push(T.h1(text));
+    } else if (level === 2) children.push(T.h1(text));
+    else if (level === 3) children.push(T.h2(text));
+    else children.push(T.h3(text));
+    i++;
+    continue;
+  }
+
+  // table
+  if (isTableLine(line) && i + 1 < md.length && isSep(md[i + 1])) {
+    const head = splitRow(line);
+    i += 2;
+    const rows = [];
+    while (i < md.length && isTableLine(md[i])) { rows.push(splitRow(md[i])); i++; }
+    const widths = tableWidths(head, rows);
+    const body = rows.map((r) => head.map((_, c) => ({ runs: inline(stripLinks(r[c] || ""), CELL, CELL_MONO) })));
+    children.push(T.makeTable(widths, head.map((x) => stripLinks(x.replace(/\*\*/g, ""))), body));
+    children.push(T.spacer(100));
+    continue;
+  }
+
+  // blockquote -> info callout
+  if (/^\s*>/.test(line)) {
+    const buf = [];
+    while (i < md.length && /^\s*>/.test(md[i])) { buf.push(md[i].replace(/^\s*>\s?/, "")); i++; }
+    const text = stripLinks(buf.join(" ").replace(/\s+/g, " ").trim());
+    const { Paragraph } = require("docx");
+    children.push(T.callout(new Paragraph({ children: inline(text, 20, 17) }), "info"));
+    children.push(T.spacer(80));
+    continue;
+  }
+
+  // lists (bullets and numbered, two levels)
+  const li = line.match(/^(\s*)([-*]|\d+[.)])\s+(.*)$/);
+  if (li) {
+    listInstance += 1;  // each list block restarts its numbering at 1
+    while (i < md.length) {
+      const m = md[i].match(/^(\s*)([-*]|\d+[.)])\s+(.*)$/);
+      if (!m) break;
+      const indent = m[1].replace(/\t/g, "    ").length;
+      const lvl = indent >= 2 ? 1 : 0;
+      const numbered = /^\d/.test(m[2]);
+      let text = m[3];
+      // continuation lines (indented, not a new item, not blank)
+      let j = i + 1;
+      while (j < md.length && /^\s{2,}\S/.test(md[j]) && !/^\s*([-*]|\d+[.)])\s+/.test(md[j]) && !isTableLine(md[j]) && !/^\s*```/.test(md[j])) {
+        text += " " + md[j].trim(); j++;
+      }
+      const runs = inline(stripLinks(text));
+      if (numbered && lvl === 0) children.push(T.numItem(runs, listInstance));
+      else children.push(T.bullet(runs, lvl));
+      i = j;
+    }
+    children.push(T.spacer(60));
+    continue;
+  }
+
+  // paragraph: gather until blank line or block start
+  const buf = [line];
+  i++;
+  while (i < md.length && !/^\s*$/.test(md[i]) && !/^(#{1,4})\s/.test(md[i]) && !isTableLine(md[i]) && !/^\s*```/.test(md[i]) && !/^\s*>/.test(md[i]) && !/^(\s*)([-*]|\d+[.)])\s+/.test(md[i]) && !/^---+\s*$/.test(md[i])) {
+    buf.push(md[i]); i++;
+  }
+  const text = stripLinks(buf.join(" ").replace(/\s+/g, " ").trim());
+  children.push(T.body(inline(text)));
+}
+
+// ---- assemble -------------------------------------------------------------
+const front = T.coverBlock({ title: opt.title || path.basename(inputPath, ".md"), subtitle: opt.subtitle || undefined });
+if (opt.meta) {
+  const rows = opt.meta.split(";").map((pair) => pair.split("=")).filter((r) => r.length === 2).map(([k, v]) => [k.trim(), v.trim()]);
+  if (rows.length) front.push(T.metaTable(rows), T.spacer(120));
+}
+const tail = opt.author ? T.authorBlock({ name: opt.author, role: opt.role, project: opt.project }) : [];
+const doc = T.buildDocument({ children: [...front, T.spacer(160), ...children, ...tail], headerText: opt.header, footerAuthor: opt.author ? `${opt.author} — ${opt.role}` : "" });
+Packer.toBuffer(doc).then((buf) => {
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, buf);
+  console.log("Gerado:", outputPath, `(${buf.length} bytes)`, `diagramas: ${diagramIndex}`);
+});

package/canonical/skills/report-formatting/scripts/build-release.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * build-release.js — release document (.docx, Claro theme) from a content file with
+ * fixed sections. Generic: application and version come from the content file
+ * (release-template.md; guide reference/RELEASE.md). Engine: docmodel.js.
+ *
+ *   node build-release.js <release.md> <output.docx>
+ */
+
+const T = require("./theme-claro");
+const { main } = require("./docmodel");
+
+const model = {
+  name: "release",
+  layout: "compact",
+  cover: "compact",
+  title: (m) => `${m.app} — Release ${m.version}`,
+  headerText: (m) => `${m.app} — Release`,
+  requiredMeta: ["app", "version", "artifact", "date"],
+  meta: [
+    ["app", "Aplicação"], ["version", "Versão"], ["type", "Tipo"], ["artifact", "Artefato"],
+    ["digest", "Digest"], ["date", "Data"], ["status", "Status"], ["previous", "Release anterior"],
+    ["audience", "Público"], ["risk", "Risco / janela"],
+  ],
+  monoMeta: ["artifact", "digest", "previous"],
+  subHeadings: "h3",  // "### Corrigido" etc. stay small inside "Mudanças"
+  categories: ["Adicionado", "Alterado", "Corrigido", "Removido", "Obsoleto", "Segurança"],
+  sections: [
+    { title: "Resumo", key: "summary", mandatory: true },
+    { title: "Mudanças incompatíveis", key: "breaking", mandatory: true },
+    { title: "Mudanças", key: "changes", mandatory: true },
+    { title: "Modelos, prompts e avaliação", key: "models", mandatory: false },
+    { title: "Configuração", key: "config", mandatory: false },
+    { title: "Rollout e rollback", key: "rollout", mandatory: true },
+    { title: "Verificação", key: "verify", mandatory: true },
+    { title: "Problemas conhecidos e pendências", key: "known", mandatory: false },
+    { title: "Referências", key: "refs", mandatory: false },
+  ],
+  // "Nenhuma." -> green callout; anything else -> the whole section inside a danger callout
+  renderSection(key, body, ctx, children, content) {
+    if (key !== "breaking") return false;
+    if (/^nenhuma\.?$/i.test(content)) { children.push(T.callout("**Nenhuma.**", "success")); children.push(T.spacer(80)); return true; }
+    const { renderBlocks } = require("./docmodel");
+    const inner = renderBlocks(body, ctx).filter((b) => b.constructor && b.constructor.name === "Paragraph");
+    children.push(T.callout(inner, "danger")); children.push(T.spacer(80));
+    return true;
+  },
+};
+
+main(model);