freeharness 0.4.1

package/canonical/skills/report-formatting/scripts/check-env.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * check-env.js — Verifica os pré-requisitos para gerar os relatórios.
+ * Uso: node check-env.js
+ */
+const { execSync } = require("child_process");
+
+/** Print a green check line (requirement satisfied). @param {string} m */
+function ok(m) { console.log("  \x1b[32m✓\x1b[0m " + m); }
+/** Print a red cross line (required prerequisite missing). @param {string} m */
+function bad(m) { console.log("  \x1b[31m✗\x1b[0m " + m); }
+/** Print a yellow bullet line (optional/informational note). @param {string} m */
+function info(m) { console.log("  \x1b[33m•\x1b[0m " + m); }
+
+let fail = 0;
+
+console.log("\nVerificando ambiente para o tema Claro:\n");
+
+// Node
+try { const v = process.version; ok(`Node.js ${v}`); } catch { bad("Node.js não encontrado"); fail++; }
+
+// docx
+try { require.resolve("docx"); ok("pacote 'docx' instalado"); }
+catch { bad("pacote 'docx' ausente → npm i docx"); fail++; }
+
+// image-size
+try { require.resolve("image-size"); ok("pacote 'image-size' instalado"); }
+catch { info("pacote 'image-size' ausente (recomendado p/ diagramas) → npm i image-size"); }
+
+// mermaid-cli
+try { execSync("mmdc -V", { stdio: "pipe" }); ok("mermaid-cli (mmdc) disponível"); }
+catch { info("mermaid-cli ausente (só necessário se houver diagramas) → npm i -g @mermaid-js/mermaid-cli"); }
+
+// chrome para puppeteer
+const fs = require("fs"); const os = require("os"); const path = require("path");
+/** Whether a Chrome/Chromium binary is available (env var, puppeteer cache, or system path). @returns {boolean} */
+function hasChrome() {
+  if (process.env.PUPPETEER_EXECUTABLE_PATH && fs.existsSync(process.env.PUPPETEER_EXECUTABLE_PATH)) return true;
+  const cache = path.join(os.homedir(), ".cache", "puppeteer");
+  let found = false;
+  const walk = (d) => { let e = []; try { e = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const x of e) { const p = path.join(d, x.name); if (x.isDirectory()) walk(p);
+      else if (["chrome-headless-shell", "chrome", "chromium"].includes(x.name)) found = true; } };
+  walk(cache);
+  for (const p of ["/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"]) if (fs.existsSync(p)) found = true;
+  return found;
+}
+if (hasChrome()) ok("Chrome/Chromium para renderizar Mermaid");
+else info("Chrome ausente (só p/ diagramas) → npx puppeteer browsers install chrome-headless-shell");
+
+// validação opcional (soffice)
+try { execSync("soffice --version", { stdio: "pipe" }); ok("LibreOffice (soffice) — validação visual opcional"); }
+catch { info("LibreOffice ausente (opcional, só p/ gerar PDF de conferência)"); }
+
+console.log("");
+if (fail) { console.log(`\x1b[31m${fail} pré-requisito(s) obrigatório(s) faltando.\x1b[0m\n`); process.exit(1); }
+console.log("\x1b[32mPronto para gerar relatórios.\x1b[0m\n");

package/canonical/skills/report-formatting/scripts/docmodel.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * docmodel.js — render a .docx (Claro theme) from a content file with FIXED sections.
+ *
+ * A model (see build-release.js, build-architecture.js) declares the sections, the
+ * front-matter fields, the title/cover and the layout; the content file supplies
+ * front matter (key: value between `---` lines) plus `## ` sections in that order.
+ * Inside a section: paragraphs, `- ` bullets, `1. ` steps, pipe tables (optional
+ * `<!-- cols: 30 70 -->` before one), fenced code (```mermaid rendered to PNG via
+ * render-mermaid.js), `> ` callouts, `![caption](image.png)`, `### `/`#### `
+ * sub-headings, "Figura N –"/"Tabela N –" caption lines, HTML comments (ignored).
+ * Unknown sections, missing mandatory sections and malformed tables fail the build.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execFileSync } = require("child_process");
+const { Packer, Paragraph, PageBreak } = require("docx");
+const T = require("./theme-claro");
+
+// ---- parsing helpers -------------------------------------------------------
+const stripLinks = (s) => s.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+const isTableLine = (s) => /^\s*\|.*\|\s*$/.test(s);
+const isSep = (s) => /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(s);
+const splitRow = (line) => line.trim().replace(/^\|/, "").replace(/\|$/, "").split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, "|"));
+const isCaption = (s) => /^(Figura|Tabela|Quadro)\s+\d+\s*[–-]/.test(s.trim());
+const isBlockStart = (s) => /^\s*([-*]|\d+[.)])\s+/.test(s) || isTableLine(s) || /^\s*```/.test(s) || /^\s*>/.test(s) || /^#{3,4}\s+/.test(s) || /^\s*!\[/.test(s) || /^\s*<!--/.test(s) || isCaption(s);
+
+/** Column widths: the longest unbreakable token sets a floor; the longest cell shares the rest. */
+function colWidths(rows, override) {
+  const W = T.contentWidth(), n = rows[0].length;
+  let w;
+  if (override && override.length === n) {
+    const sum = override.reduce((a, b) => a + b, 0);
+    w = override.map((x) => Math.floor(W * x / sum));
+  } else {
+    const clean = (c) => (c || "").replace(/[`*]/g, "");
+    const mins = Array.from({ length: n }, (_, c) => 260 + 105 * Math.max(...rows.map((r) => Math.max(...clean(r[c]).split(/\s+/).map((x) => x.length)))));
+    const weights = Array.from({ length: n }, (_, c) => Math.max(...rows.map((r) => Math.min(70, clean(r[c]).length))));
+    const minSum = mins.reduce((a, b) => a + b, 0);
+    const scale = minSum > W ? W / minSum : 1;
+    const rest = Math.max(0, W - minSum * scale);
+    const wSum = weights.reduce((a, b) => a + b, 0);
+    w = mins.map((m, c) => Math.floor(m * scale + rest * weights[c] / wSum));
+  }
+  w[n - 1] += W - w.reduce((a, b) => a + b, 0);
+  return w;
+}
+
+/** Render every ```mermaid block of the content file to PNGs (document order). */
+function renderDiagrams(inputPath, fail) {
+  const src = fs.readFileSync(inputPath, "utf8");
+  if (!/^\s*```mermaid/m.test(src)) return [];
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "claro-diagrams-"));
+  try {
+    const out = execFileSync(process.execPath, [path.join(__dirname, "render-mermaid.js"), inputPath, dir], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    const json = JSON.parse(out.slice(out.indexOf("{")));
+    return json.pngs || [];
+  } catch (e) {
+    fail(`mermaid render failed (needs @mermaid-js/mermaid-cli + Chrome): ${String(e.stderr || e.message).trim().split("\n").pop()}`);
+  }
+  return [];
+}
+
+/**
+ * Parse the blocks of one section into theme elements.
+ * @param {string[]} body - section lines.
+ * @param {object} ctx - { fail, baseDir, diagrams, nextDiagram, listInstance, subHeadings, categories }.
+ * @returns {Array} theme elements.
+ */
+function renderBlocks(body, ctx) {
+  const out = [];
+  let colsOverride = null;
+  let widthOverride = null;
+  let j = 0;
+  while (j < body.length) {
+    const line = body[j];
+    if (!line.trim()) { j++; continue; }
+    if (/^\s*<!--/.test(line)) {  // guidance comments; "<!-- cols: 30 70 -->" sets the next table's widths, "<!-- width: 70 -->" the next image's width (% of text width)
+      const c = line.match(/cols:\s*([\d\s]+)-->/);
+      if (c) colsOverride = c[1].trim().split(/\s+/).map(Number);
+      const wd = line.match(/width:\s*(\d+)\s*-->/);
+      if (wd) widthOverride = Math.round(T.contentWidth() * 635 * Number(wd[1]) / 100);
+      while (j < body.length && !/-->/.test(body[j])) j++;
+      j++; continue;
+    }
+    const h = line.match(/^(#{3,4})\s+(.+?)\s*$/);
+    if (h) {
+      let title = h[2];
+      if (ctx.categories && h[1] === "###" && !ctx.categories.includes(title)) ctx.fail(`unknown category "### ${title}" — allowed: ${ctx.categories.join(" | ")}`);
+      const level = ctx.subHeadings === "h3" ? "h3" : (h[1] === "###" ? "h2" : "h3");
+      if (level === "h2" && ctx.sectionNumber !== undefined && ctx.sectionNumber !== null) { ctx.subCount += 1; title = `${ctx.sectionNumber}.${ctx.subCount} ${title}`; }
+      out.push(T[level](title));
+      j++; continue;
+    }
+    if (/^\s*```/.test(line)) {
+      const lang = line.trim().slice(3).trim().toLowerCase();
+      const code = [];
+      j++;
+      while (j < body.length && !/^\s*```/.test(body[j])) code.push(body[j++]);
+      j++;
+      if (lang === "mermaid") {
+        const png = ctx.diagrams[ctx.nextDiagram++];
+        if (!png) ctx.fail("mermaid block without a rendered diagram");
+        out.push(T.image(png, widthOverride || ctx.diagramWidth));
+        widthOverride = null;
+      } else out.push(T.codeBlock(code));
+      continue;
+    }
+    const img = line.match(/^\s*!\[([^\]]*)\]\(([^)]+)\)\s*$/);
+    if (img) {
+      const p = path.resolve(ctx.baseDir, img[2]);
+      if (!fs.existsSync(p)) ctx.fail(`image not found: ${img[2]}`);
+      out.push(T.image(p, widthOverride || ctx.diagramWidth));
+      widthOverride = null;
+      if (img[1]) out.push(T.caption(img[1], { center: true }));
+      j++; continue;
+    }
+    if (isCaption(line)) { out.push(T.caption(line.trim(), { center: true })); j++; continue; }
+    if (/^\s*>/.test(line)) {
+      let text = "";
+      while (j < body.length && /^\s*>/.test(body[j])) text += (text ? " " : "") + body[j++].replace(/^\s*>\s?/, "").trim();
+      const kind = /^\*\*(atenção|aviso|risco|não|nota)/i.test(text) ? "note" : /^\*\*(quebra|incompat|crítico|bloqueio)/i.test(text) ? "danger" : /^\*\*(decisão|ok|aprovado|recomenda)/i.test(text) ? "success" : "info";
+      out.push(T.callout(stripLinks(text), kind));
+      out.push(T.spacer(80));
+      continue;
+    }
+    if (isTableLine(line)) {
+      const rows = [];
+      while (j < body.length && isTableLine(body[j])) { if (!isSep(body[j])) rows.push(splitRow(body[j])); j++; }
+      if (rows.length < 2) continue;
+      const head = rows[0];
+      const data = rows.slice(1).map((r) => { if (r.length !== head.length) ctx.fail(`table row has ${r.length} cells, header has ${head.length} (escape a literal pipe as \\|): ${r.join(" | ")}`); return r.map(stripLinks); });
+      out.push(T.makeTable(colWidths(rows, colsOverride), head, data, { rich: true }));
+      colsOverride = null;
+      // a caption line directly after the table keeps its spacing tight
+      if (j < body.length && isCaption(body[j])) { out.push(T.caption(body[j].trim())); j++; } else out.push(T.spacer(100));
+      continue;
+    }
+    if (/^\s*([-*]|\d+[.)])\s+/.test(line)) {
+      ctx.listInstance += 1;
+      while (j < body.length) {
+        const m = body[j].match(/^(\s*)([-*]|\d+[.)])\s+(.*)$/);
+        if (!m) break;
+        const lvl = m[1].replace(/\t/g, "    ").length >= 2 ? 1 : 0;
+        let text = m[3];
+        let k = j + 1;
+        while (k < body.length && /^\s{2,}\S/.test(body[k]) && !isBlockStart(body[k])) text += " " + body[k++].trim();
+        if (/^\d/.test(m[2])) out.push(T.num(stripLinks(text), { instance: ctx.listInstance, lvl }));
+        else out.push(T.li(stripLinks(text), lvl));
+        j = k;
+      }
+      out.push(T.spacer(40));
+      continue;
+    }
+    let text = line.trim();
+    j++;
+    while (j < body.length && body[j].trim() && !isBlockStart(body[j])) text += " " + body[j++].trim();
+    out.push(T.p(stripLinks(text)));
+  }
+  return out;
+}
+
+/** Front matter + sections of the content file, validated against the model. */
+function parse(inputPath, model, fail) {
+  const lines = fs.readFileSync(inputPath, "utf8").split(/\r?\n/);
+  const meta = {};
+  let i = 0;
+  if (lines[0] && lines[0].trim() === "---") {
+    for (i = 1; i < lines.length && lines[i].trim() !== "---"; i++) {
+      const m = lines[i].match(/^([A-Za-z_]+)\s*:\s*(.*)$/);
+      if (m) meta[m[1]] = m[2].trim();
+    }
+    i += 1;
+  }
+  for (const k of model.requiredMeta) if (!meta[k]) fail(`front matter is missing "${k}"`);
+  const sections = new Map();
+  let current = null;
+  for (; i < lines.length; i++) {
+    const h = lines[i].match(/^##\s+(.+?)\s*$/);
+    if (h) {
+      const def = model.sections.find((s) => s.title === h[1]);
+      if (!def) fail(`unknown section "## ${h[1]}" — allowed: ${model.sections.map((s) => s.title).join(" | ")}`);
+      if (sections.has(def.key)) fail(`section "${def.title}" appears twice`);
+      current = []; sections.set(def.key, current);
+      continue;
+    }
+    if (current) current.push(lines[i]);
+  }
+  for (const s of model.sections) if (s.mandatory && !sections.has(s.key)) fail(`mandatory section "## ${s.title}" is missing`);
+  return { meta, sections };
+}
+
+/**
+ * Build the document for a model and write the .docx.
+ * @param {object} model - { name, layout, sections, requiredMeta, meta, title(meta), headerText(meta),
+ *   cover: "compact"|"page", subtitle(meta)?, subHeadings?, categories?, authorHeading?,
+ *   renderSection?(key, body, ctx, children) -> boolean handled }.
+ * @param {string} inputPath - content file (.md).
+ * @param {string} outputPath - target .docx.
+ */
+async function build(model, inputPath, outputPath) {
+  const fail = (msg) => { console.error(`${model.name} model: ${msg}`); process.exit(1); };
+  T.configure({ layout: model.layout || "compact" });
+  const { meta, sections } = parse(inputPath, model, fail);
+  const diagrams = renderDiagrams(inputPath, fail);
+  const ctx = { fail, baseDir: path.dirname(path.resolve(inputPath)), diagrams, nextDiagram: 0, listInstance: 0,
+    subHeadings: model.subHeadings, categories: model.categories, diagramWidth: model.diagramWidth, meta };
+
+  const children = [];
+  const metaRows = model.meta.filter(([k]) => meta[k]).map(([k, label]) => [label, (model.monoMeta || []).includes(k) ? meta[k].replace(/^(?!`)(\S+)/, "`$1`") : meta[k]]);
+  if (model.cover === "page") {
+    children.push(...T.coverBlock({ title: model.coverTitle || model.title(meta), subtitle: model.subtitle ? model.subtitle(meta) : undefined, tagline: model.tagline ? model.tagline(meta) : undefined, org: model.org ? model.org(meta) : undefined, metaLines: model.coverLines ? model.coverLines(meta) : [] }));
+    children.push(T.spacer(200));
+    if (model.coverTable !== false) children.push(T.metaTable(metaRows));
+    children.push(new Paragraph({ children: [new PageBreak()] }));
+    if (model.toc !== false) {
+      // static table of contents (titles only): deterministic in Word and LibreOffice,
+      // no "update fields" prompt; Word's navigation pane still works via outline levels
+      children.push(T.h1(model.tocTitle || "Sumário"));
+      let n = model.numberFrom === undefined ? null : model.numberFrom - 1;
+      for (const s of model.sections) {
+        const body = sections.get(s.key);
+        if (!body) continue;
+        let number = null;
+        if (s.numbered && n !== null) { n += 1; number = n; }
+        const label = number !== null ? `${number}. ${s.title}` : s.title;
+        children.push(new Paragraph({ spacing: { before: 80, after: 20 }, children: [T.t(label, { bold: true, size: T.SZ.body, color: T.C.h2 })] }));
+        let k = 0;
+        const clean = body.join("\n").replace(/<!--[\s\S]*?-->/g, "").split("\n");
+        for (const ln of clean) {
+          const m = ln.match(/^###\s+(.+?)\s*$/);
+          if (!m) continue;
+          k += 1;
+          const sub = number !== null ? `${number}.${k} ${m[1]}` : m[1];
+          children.push(new Paragraph({ spacing: { after: 10 }, indent: { left: 480 }, children: [T.t(sub, { size: T.SZ.cell, color: T.C.body })] }));
+        }
+      }
+      children.push(new Paragraph({ children: [new PageBreak()] }));
+    }
+  } else {
+    children.push(...T.coverBlock({ title: model.title(meta), rule: false }));
+    children.push(T.metaTable(metaRows));
+    children.push(T.spacer(200));
+  }
+
+  let seq = model.numberFrom === undefined ? null : model.numberFrom - 1;  // numbered sections count only those present
+  for (const s of model.sections) {
+    const body = sections.get(s.key);
+    if (!body) continue;
+    const content = body.join("\n").replace(/<!--[\s\S]*?-->/g, "").trim();
+    if (!content) fail(`section "## ${s.title}" is empty — fill it or remove it${s.mandatory ? ' (mandatory: write "Nenhuma." / "Não se aplica." when it does not apply)' : ""}`);
+    let number = null;
+    if (s.numbered && seq !== null) { seq += 1; number = seq; }
+    ctx.sectionNumber = number; ctx.subCount = 0;
+    children.push(T.h1(number !== null ? `${number}. ${s.title}` : s.title, s.pageBreakBefore ? { pageBreakBefore: true } : {}));
+    if (model.renderSection && model.renderSection(s.key, body, ctx, children, content)) continue;
+    children.push(...renderBlocks(body, ctx));
+  }
+
+  children.push(...T.authorBlock({ heading: model.authorHeading || "ELABORAÇÃO", name: meta.author || "André Negrelli", role: meta.role || "Tech Lead AI Data Engineer", area: meta.area, project: meta.project || meta.app }));
+  const doc = T.buildDocument({ children, headerText: model.headerText(meta), footerAuthor: `${meta.author || "André Negrelli"} — ${meta.role || "Tech Lead AI Data Engineer"} | ${meta.area || "DADOS & IA"}`, updateFields: false });
+
+  // never overwrite a document Word holds open (lock "~$<name>"): Word reloads images lazily and would save broken links
+  const outAbs = path.resolve(outputPath);
+  const lock = path.join(path.dirname(outAbs), "~$" + path.basename(outAbs).slice(2));
+  const target = fs.existsSync(lock) ? outAbs.replace(/\.docx$/i, "-new.docx") : outAbs;
+  if (target !== outAbs) console.warn(`${model.name} model: ${path.basename(outAbs)} is open in Word; writing ${path.basename(target)} instead — close Word and rename.`);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const buf = await Packer.toBuffer(doc);
+  fs.writeFileSync(target, buf);
+  console.log("Generated:", target, `(${buf.length} bytes)`);
+}
+
+/** CLI wrapper: `node build-<model>.js <content.md> <out.docx>`. */
+function main(model) {
+  const [inputPath, outputPath] = process.argv.slice(2);
+  if (!inputPath || !outputPath) { console.error(`usage: build-${model.name}.js <content.md> <output.docx>`); process.exit(2); }
+  build(model, inputPath, outputPath).catch((e) => { console.error(e); process.exit(1); });
+}
+
+module.exports = { build, main, renderBlocks, parse, colWidths };

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

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * example-build.js — Template MÍNIMO de geração de um relatório no tema Claro.
+ *
+ * Copie este arquivo, renomeie (ex.: build-<slug>.js) e preencha `children`
+ * com o conteúdo real, usando os helpers de ./theme-claro.js.
+ *
+ * Uso:
+ *   node example-build.js                      # gera ./out/Exemplo_Tema_Claro.docx
+ *   node example-build.js /caminho/saida.docx  # caminho de saída custom
+ *
+ * Para diagramas Mermaid: rode antes
+ *   node render-mermaid.js entrada.md ./_diagramas
+ * e use T.image("./_diagramas/diagram_01.png") nas posições certas.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { Packer, AlignmentType } = require("docx");
+const T = require("./theme-claro");
+
+const children = [];
+
+// ---- CAPA ----
+children.push(...T.coverBlock({
+  title: "Título do Relatório — Subsistema",
+  subtitle: "STT — Claro (Projeto Speech-to-Text)",
+  tagline: "Linha de descrição curta do que o relatório entrega",
+  org: "Projeto STT — Claro  |  Aquisição DADOS & IA",
+  metaLines: [
+    "Status: proposta para validação",
+    "Data: 19/06/2026",
+    "Fonte dos dados: <origem>",
+  ],
+}));
+children.push(T.spacer(240));
+
+// ---- METADADOS (memorando) ----
+children.push(T.metaTable([
+  ["Para", "Destinatário"],
+  ["De", "Aquisição DADOS & IA — (Projeto Speech-to-Text)"],
+  ["Data", "19/06/2026"],
+  ["Referência", [T.t("Documento relacionado, se houver", { size: 20, color: T.C.body })]],
+]));
+children.push(T.spacer(200));
+
+// ---- SUMÁRIO EXECUTIVO ----
+children.push(T.h1("1. Sumário executivo"));
+children.push(T.body([
+  T.t("Frase de abertura com o achado central em ", { size: 22, color: T.C.body }),
+  T.t("negrito para o que importa", { size: 22, bold: true }),
+  T.t(". O transporte é a poeira; o gargalo é a montanha.", { size: 22, color: T.C.body }),
+]));
+
+// stat cards (números que importam)
+children.push(T.statCards([
+  { value: "99,99%", label: "métrica crítica", color: T.C.deepRed, fill: "FFEDED" },
+  { value: "306×", label: "outro indicador", color: T.C.deepRed, fill: "FFEDED" },
+  { value: "16,3%", label: "alerta", color: T.C.amber, fill: T.C.noteFill },
+  { value: "OK", label: "saudável", color: T.C.green, fill: T.C.successFill },
+]));
+children.push(T.spacer(160));
+
+children.push(T.bullet([T.t("Mensagem-âncora 1. ", { size: 22, bold: true }), T.t("explicação.", { size: 22, color: T.C.body })]));
+children.push(T.bullet([T.t("Mensagem-âncora 2. ", { size: 22, bold: true }), T.t("explicação.", { size: 22, color: T.C.body })]));
+
+children.push(T.calloutLine("Recomendação:", "ação principal proposta, em uma frase.", "success"));
+children.push(T.spacer(200));
+
+// ---- SEÇÃO COM TABELA ----
+children.push(T.h1("2. Análise"));
+children.push(T.body("Texto introdutório da tabela."));
+children.push(T.makeTable(
+  [3200, 1600, 4840],
+  ["Item", "Valor", "Observação"],
+  [
+    [{ runs: "Linha A" }, { runs: [T.t("12.775", { size: 20, bold: true, color: T.C.red })], align: AlignmentType.RIGHT }, { runs: "nota" }],
+    [{ runs: "Linha B" }, { runs: "7.194", align: AlignmentType.RIGHT }, { runs: [T.t("ok", { size: 20, color: T.C.green })] }],
+  ]
+));
+children.push(T.caption("Tabela 1 – Legenda da tabela."));
+
+children.push(T.calloutLine("Leitura executiva:", "o que esses números significam para a decisão.", "info"));
+children.push(T.spacer(160));
+
+// ---- BLOCO DE CÓDIGO / LOG ----
+children.push(T.h2("2.1 Evidência (log)"));
+children.push(T.codeBlock([
+  '"event":"processing_error", "stage":"transcribe", "attempt":4,',
+  '"error_type":"UnboundLocalError"',
+]));
+
+// ---- DIAGRAMA (descomente após render-mermaid.js) ----
+// children.push(T.h1("3. Diagramas"));
+// children.push(T.image(path.join(__dirname, "_diagramas", "diagram_01.png"), 6050000));
+// children.push(T.caption("Figura 1 – Legenda.", { center: true }));
+
+// ---- AUTORIA ----
+children.push(...T.authorBlock({
+  name: "André Negrelli",
+  role: "Tech Lead — AI Data Engineer",
+  area: "DADOS & IA  |  Tech Dados & IA — Aquisição e Transformação de Dados & IA",
+  project: "Projeto STT — Claro  ·  19/06/2026",
+}));
+
+// ---- MONTAGEM ----
+const doc = T.buildDocument({
+  children,
+  headerText: "Título do Relatório  |  STT Claro",
+  footerAuthor: "André Negrelli — DADOS & IA",
+});
+
+const outPath = process.argv[2] || path.join(process.cwd(), "out", "Exemplo_Tema_Claro.docx");
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+Packer.toBuffer(doc).then((buf) => {
+  fs.writeFileSync(outPath, buf);
+  console.log("Gerado:", outPath, `(${buf.length} bytes)`);
+});

package/canonical/skills/report-formatting/scripts/example_build_ArchitectureReview_docx.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Template: Architecture review report (.docx, Claro theme).
+ *
+ * For a review of an existing system or agentic design: what was reviewed, how the
+ * architecture stands today, what was found (ranked by severity), which decisions
+ * the team already took, what still puts the system at risk, and the roadmap that
+ * closes the findings. The verdict is the first thing the reader sees. Copy this
+ * file, rename (build-<slug>.js), and fill `children` with the real content using
+ * the ./theme-claro.js helpers. Content placeholders are PT-BR (client-facing);
+ * comments are English.
+ *
+ * Differs from the Architecture & System Design model (build-architecture.js): that
+ * one DESCRIBES a system (arc42/C4); this one JUDGES it against criteria and ends
+ * with a PASS / FAIL / CONDITIONAL verdict and a remediation plan.
+ *
+ * Usage:
+ *   node example_build_ArchitectureReview_docx.js                 # ./out/Revisao_Arquitetural.docx
+ *   node example_build_ArchitectureReview_docx.js /path/out.docx
+ */
+const fs = require("fs");
+const path = require("path");
+const { Packer, AlignmentType } = require("docx");
+const T = require("./theme-claro");
+
+const children = [];
+
+/** Severity scale shared by the findings table and the summary cards. */
+const SEV = {
+  critica: { label: "Crítica", color: T.C.deepRed, fill: T.C.dangerFill },
+  alta: { label: "Alta", color: T.C.red, fill: "FFEDED" },
+  media: { label: "Média", color: T.C.amber, fill: T.C.noteFill },
+  baixa: { label: "Baixa", color: T.C.green, fill: T.C.successFill },
+};
+
+/**
+ * Builds one findings-table row with a severity chip in the first cell.
+ * @param {string} id Finding id (e.g. "F-01").
+ * @param {keyof SEV} sev Severity key.
+ * @param {string} area Architectural area (e.g. "Fronteira core/infra").
+ * @param {string} finding One-sentence finding.
+ * @param {string} evidence Where it was observed (file, module, trace).
+ * @returns {object[]} Row cells for T.makeTable.
+ */
+function findingRow(id, sev, area, finding, evidence) {
+  const s = SEV[sev];
+  return [
+    { runs: [T.t(id, { size: 20, bold: true })] },
+    { runs: [T.t(s.label, { size: 20, bold: true, color: s.color })], fill: s.fill, align: AlignmentType.CENTER },
+    { runs: area },
+    { runs: finding },
+    { runs: [T.mono(evidence, 18)] },
+  ];
+}
+
+// ---- COVER ----
+children.push(...T.coverBlock({
+  title: "Revisão Arquitetural — <Sistema / Componente>",
+  subtitle: "<Projeto> — Claro",
+  tagline: "Achados, decisões e roadmap de remediação",
+  org: "<Projeto> — Claro  |  DADOS & IA",
+  metaLines: ["Escopo: <versão / branch / PR revisados>", "Data: DD/MM/AAAA"],
+}));
+children.push(T.spacer(240));
+
+// ---- VERDICT FIRST ----
+children.push(T.h1("Resumo executivo e veredito"));
+children.push(T.body([
+  T.t("Veredito: ", { size: 22, bold: true }),
+  T.t("APROVADO COM CONDIÇÕES", { size: 22, bold: true, color: T.C.amber }),
+  T.t(" — uma frase com o motivo dominante e o que precisa mudar antes do próximo marco.", { size: 22, color: T.C.body }),
+]));
+children.push(T.statCards([
+  { value: "1", label: "achado crítico", color: SEV.critica.color, fill: SEV.critica.fill },
+  { value: "2", label: "achados altos", color: SEV.alta.color, fill: SEV.alta.fill },
+  { value: "3", label: "médios / baixos", color: SEV.media.color, fill: SEV.media.fill },
+  { value: "4 sem", label: "prazo de remediação", color: T.C.accent, fill: T.C.infoFill },
+]));
+children.push(T.spacer(140));
+children.push(T.calloutLine("Condição de aprovação:", "os achados críticos e altos fechados e re-verificados antes do go-live.", "note"));
+children.push(T.spacer(200));
+
+// ---- 1. CONTEXT ----
+children.push(T.h1("1. Contexto da revisão"));
+children.push(T.metaTable([
+  ["Objeto revisado", "<sistema / serviço / subgrafo> — versão <x.y> (commit <sha>)"],
+  ["Motivação", "<gate de fase, incidente, mudança de escopo, auditoria>"],
+  ["Critérios", "aderência ao blueprint, regra de dependência, contratos externos, segurança de entrada, observabilidade, testabilidade"],
+  ["Método", "leitura de código e specs, execução da suíte, rastreamento de uma requisição ponta a ponta"],
+  ["Fora de escopo", "<o que não foi avaliado e por quê>"],
+]));
+children.push(T.caption("Tabela 1 – Escopo e critérios da revisão."));
+
+// ---- 2. CURRENT ARCHITECTURE ----
+children.push(T.h1("2. Arquitetura atual"));
+children.push(T.p("Descrição curta de como o sistema está hoje: camadas, fronteiras, fluxo principal. Um diagrama pré-renderizado (render-mermaid.js) ajuda aqui."));
+// children.push(T.image("./_diagrams/contexto.png", T.CONTENT_W));
+children.push(T.makeTable(
+  [2400, 3600, 3440],
+  ["Camada", "Responsabilidade observada", "Desvio em relação ao blueprint"],
+  [
+    [{ runs: "core" }, { runs: "regra de negócio e contratos" }, { runs: [T.t("nenhum", { size: 20, color: T.C.green })] }],
+    [{ runs: "infra" }, { runs: "adaptadores LLM, persistência, observabilidade" }, { runs: [T.t("importa core corretamente; um adaptador acopla framework ao domínio", { size: 20, color: T.C.amber })] }],
+    [{ runs: "entry" }, { runs: "API HTTP, composição" }, { runs: [T.t("composição duplicada em dois pontos", { size: 20, color: T.C.deepRed })] }],
+  ]
+));
+children.push(T.caption("Tabela 2 – Camadas e desvios observados."));
+
+// ---- 3. FINDINGS BY SEVERITY ----
+children.push(T.h1("3. Achados por severidade"));
+children.push(T.p("Ordem: Crítica > Alta > Média > Baixa. Cada achado aponta a evidência (arquivo, módulo ou trace) e recebe uma ação no roadmap da seção 6."));
+children.push(T.makeTable(
+  [800, 1100, 1900, 3640, 2000],
+  ["ID", "Severidade", "Área", "Achado", "Evidência"],
+  [
+    findingRow("F-01", "critica", "Fronteira de decisão", "A decisão de negócio depende da saída do LLM em vez do motor determinístico.", "infra/llm/router.py:88"),
+    findingRow("F-02", "alta", "Contrato externo", "Campo renomeado no payload de resposta sem versionamento.", "core/contract.py"),
+    findingRow("F-03", "alta", "Segurança de entrada", "Texto livre do operador entra no prompt sem delimitação.", "infra/llm/prompts.py"),
+    findingRow("F-04", "media", "Observabilidade", "Trace não correlaciona a chamada LLM com a requisição HTTP.", "entry/api.py"),
+    findingRow("F-05", "baixa", "Toolchain", "Lint de dependência configurado mas não executado no CI.", ".github/workflows"),
+  ]
+));
+children.push(T.caption("Tabela 3 – Achados ordenados por severidade."));
+children.push(T.h2("Detalhe dos achados críticos e altos"));
+children.push(T.callout([
+  T.body([T.t("F-01 — ", { size: 22, bold: true }), T.t("o que acontece, por que viola o critério, qual o impacto se ficar como está.", { size: 22, color: T.C.body })]),
+  T.bullet([T.t("Evidência: ", { size: 22, bold: true }), T.t("trecho, log ou trace.", { size: 22, color: T.C.body })]),
+  T.bullet([T.t("Correção esperada: ", { size: 22, bold: true }), T.t("a mudança mínima que fecha o achado.", { size: 22, color: T.C.body })]),
+], "danger"));
+children.push(T.spacer(160));
+
+// ---- 4. DECISION RECORDS ----
+children.push(T.h1("4. Registro de decisões (ADR resumido)"));
+children.push(T.p("Decisões tomadas durante ou em consequência da revisão. Uma linha por decisão; o ADR completo fica na documentação de arquitetura."));
+children.push(T.makeTable(
+  [900, 3000, 2800, 2740],
+  ["ADR", "Decisão", "Alternativas descartadas", "Consequências"],
+  [
+    [{ runs: [T.t("ADR-01", { size: 20, bold: true })] }, { runs: "Motor determinístico decide; LLM só classifica e redige." }, { runs: "LLM decide com guardrails" }, { runs: "decisão auditável; menor latência; eval mais simples" }],
+    [{ runs: [T.t("ADR-02", { size: 20, bold: true })] }, { runs: "Contrato externo versionado por cabeçalho." }, { runs: "campo novo sem versão" }, { runs: "compatibilidade com o consumidor; custo de manter duas versões" }],
+  ]
+));
+children.push(T.caption("Tabela 4 – Decisões registradas."));
+
+// ---- 5. RISKS ----
+children.push(T.h1("5. Riscos residuais"));
+children.push(T.makeTable(
+  [900, 3400, 1400, 1400, 2340],
+  ["ID", "Risco", "Probabilidade", "Impacto", "Mitigação / dono"],
+  [
+    [{ runs: [T.t("R-01", { size: 20, bold: true })] }, { runs: "Regressão silenciosa no contrato após a migração." }, { runs: [T.t("Média", { size: 20, color: T.C.amber })], align: AlignmentType.CENTER }, { runs: [T.t("Alto", { size: 20, color: T.C.deepRed })], align: AlignmentType.CENTER }, { runs: "teste de contrato no CI — <dono>" }],
+    [{ runs: [T.t("R-02", { size: 20, bold: true })] }, { runs: "Provedor LLM indisponível durante o pico." }, { runs: [T.t("Baixa", { size: 20, color: T.C.green })], align: AlignmentType.CENTER }, { runs: [T.t("Médio", { size: 20, color: T.C.amber })], align: AlignmentType.CENTER }, { runs: "nó de erro de negócio + retry — <dono>" }],
+  ]
+));
+children.push(T.caption("Tabela 5 – Riscos que permanecem após a remediação planejada."));
+
+// ---- 6. RECOMMENDATION ROADMAP ----
+children.push(T.h1("6. Roadmap de recomendações"));
+children.push(T.p("Ondas curtas, cada uma fechando achados nomeados. A onda 1 é condição do veredito."));
+children.push(T.makeTable(
+  [1400, 3600, 1800, 2640],
+  ["Onda", "Ação", "Fecha", "Prazo / dono"],
+  [
+    [{ runs: [T.t("Onda 1", { size: 20, bold: true, color: T.C.deepRed })], fill: T.C.dangerFill }, { runs: "Mover a decisão para o motor determinístico; delimitar o texto do operador." }, { runs: [T.mono("F-01, F-03", 18)] }, { runs: "2 semanas — <dono>" }],
+    [{ runs: [T.t("Onda 2", { size: 20, bold: true, color: T.C.amber })], fill: T.C.noteFill }, { runs: "Versionar o contrato; correlacionar traces." }, { runs: [T.mono("F-02, F-04", 18)] }, { runs: "4 semanas — <dono>" }],
+    [{ runs: [T.t("Onda 3", { size: 20, bold: true, color: T.C.green })], fill: T.C.successFill }, { runs: "Lint de dependência no CI; higiene." }, { runs: [T.mono("F-05", 18)] }, { runs: "contínuo — <dono>" }],
+  ]
+));
+children.push(T.caption("Tabela 6 – Roadmap de remediação."));
+children.push(T.spacer(160));
+children.push(T.callout([
+  T.body([T.t("Re-verificação: ", { size: 22, bold: true }), T.t("a revisão é reaberta ao fim da onda 1 com os mesmos critérios; o veredito muda para APROVADO apenas com evidência (testes, traces) anexada.", { size: 22, color: T.C.body })]),
+], "info"));
+
+// ---- AUTHORSHIP ----
+children.push(...T.authorBlock({
+  name: "André Negrelli",
+  role: "Tech Lead — AI Data Engineer",
+  area: "DADOS & IA  |  Tech Dados & IA — Aquisição e Transformação de Dados & IA",
+  project: "<Projeto> — Claro  ·  DD/MM/AAAA",
+}));
+
+const doc = T.buildDocument({
+  children,
+  headerText: "Revisão Arquitetural  |  <Projeto> Claro",
+  footerAuthor: "André Negrelli — DADOS & IA",
+});
+
+const outPath = process.argv[2] || path.join(process.cwd(), "out", "Revisao_Arquitetural.docx");
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+Packer.toBuffer(doc).then((buf) => {
+  fs.writeFileSync(outPath, buf);
+  console.log("Gerado:", outPath, `(${buf.length} bytes)`);
+});