freeharness 0.4.1 → 0.4.2

package/canonical/skills/git-workflow/SKILL.md

@@ -20,6 +20,7 @@ Git operations are deterministic and reversible. The orchestrator runs them dire
 <push_and_pr>
 1. Never commit directly on `main`/`master`: create `type/short-topic` from the current branch first.
 2. `git push -u origin <branch>`. Never `--force` or `--force-with-lease` on a shared branch; if history must change, ask the user and explain the consequence.
+   The config guard hook denies history-destroying git commands (e.g. `reset --hard`, `--force` push, `branch -D`, `clean -f`, discarding `checkout`/`restore`, `stash drop`, `worktree remove --force` outside the temp root) from the model, also when a same-line variable, `xargs ... sh -c` or interpreter code that spawns processes runs them; the user runs an intended one with the `!` prompt prefix. Git text inside a quoted argument, a `sed`/`grep`/`awk` script or interpreter code without a process-spawning call passes. The hook lets `--force-with-lease` through, so the shared-branch ban on it rests on the rule above.
 3. Open the PR with `gh pr create`: title = the commit summary (or the change id for spec-driven work), body = summary of what and why, the OpenSpec change reference, the verification evidence (test/type/lint commands and results), and a checklist of review items. Draft when verification is incomplete.
 4. Report the PR URL.
 </push_and_pr>
@@ -34,6 +35,7 @@ Local branches whose remote is gone: `git fetch --prune`, list `git branch -vv |
 - Never offer "discard" as an option for uncommitted work: the choices are commit, stash (`git stash push -u` inside that worktree) or leave it.
 - Never operate on another worktree's branch: no `git switch`/`git checkout` to a branch checked out elsewhere, no `gh pr checkout` in the current tree unless the user asks; inspect PRs with `gh pr view`, `gh pr diff`, `git show <ref>:<path>` against fetched refs.
 - Rebase conflicts: resolve only in files this branch modified; a conflict in a file it did not touch means abort and ask.
+- SDD task trees under `.worktrees/<change>/<task>` are created, landed and removed by the subagent-driven-development tree rule (`validate-handoff.mjs tree` and `commit --tree`), never by hand.
 </worktrees>
 
 <output_format>

package/canonical/skills/local-code/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: local-code
-description: Use when a file exceeds 100 lines, a log or stack trace is large, or a bulk multi-file scan or AST summary is needed before reading: offloads ingestion to the local llama.cpp server (llama-server on localhost:8080) and returns a compressed digest. Falls back to Grep/Glob when the server is down.
+description: Use when a log or stack trace is large, or a bulk multi-file scan or AST summary is needed before reading: offloads ingestion to llama-server on localhost:8080 and returns a compressed digest. Falls back to Grep/Glob when the server is down.
 tools: Read, Glob, Grep, Bash
 ---
 
@@ -14,7 +14,7 @@ tools: Read, Glob, Grep, Bash
 
 <workflow>
 1. Identify Files:
-   Identify candidate files using `Glob` or `Grep`. For files exceeding 100 lines, delegate reading to the local model.
+   Identify candidate files using `Glob` or `Grep`. Read source files directly with `Read` line ranges; delegate large logs, stack traces, bulk multi-file scans, or an AST or call-graph summary the caller asks for, to the local model.
 
 2. Execute Local Extraction:
    Call the local extractor pointing to the skill script path:

package/canonical/skills/local-code/evals/cases.yaml

@@ -75,7 +75,7 @@ cases:
     dogfood: 2026-09-06 STT
     provisional: true
     input: "Read src/stt/config.py (40 lines) and tell me the default sample rate."
-    expected: "A 40-line file is read directly; the local extractor is not invoked below the 100-line threshold."
+    expected: "A 40-line file is read directly; the local extractor is not invoked for a single small source file."
     graders:
       - type: tool_used
         expected: "Read:src/stt/config.py"

package/canonical/skills/report-formatting/SKILL.md

@@ -54,9 +54,17 @@ Do not author a standalone JS script.
 </pipeline_routing>
 
 <editorial_invariants>
+- Page identity (every .docx, categories A and B): the layout of the reference release
+  document (stt-whisperx — Release 0.4.2), as encoded in `scripts/theme-claro.js` — A4,
+  `compact` geometry (1 cm left/right, top 1.35 cm, bottom 1.03 cm, header 0.31 cm, footer
+  0.29 cm), header `<app> — <document type>` italic grey 9 pt with the Claro logo right and
+  a bottom rule, footer `<author> — <role> | <area>` left and `Confidencial – Uso Interno |
+  Página X de Y` right over a top rule, `ELABORAÇÃO` block at the end. Use the theme
+  defaults (`T.headerLine`, `T.footerAuthorLine`, `T.HOUSE`); never hand-set margins,
+  header or footer. Details: `reference/authoring.md`.
 - Typography: Arial for prose, Consolas for code/identifiers. Body justified at 1.15 line spacing.
 - Pagination integrity: Heading lines enforced with `keepNext`; short tables and code blocks kept on single page; zero orphaned lines.
 - Semaphore colors: Red = Critical/Action, Amber = Attention/Hypothesis, Green = Healthy/Target, Blue = Insight.
-- File Lock Safety: If `~$<name>.docx` exists, Microsoft Word has the file locked. Write to an incremented filename (`<name>_v2.docx`) to prevent corruption.
-- Deliverable: Deliver `.docx` or `.pptx` only. Never leave throwaway validation PDFs in production paths.
+- File Lock Safety: If `~$<name>.docx` exists, Microsoft Word has the file locked. Never overwrite it: the category A engines write `<name>-new.docx` automatically; a category B build writes `<name>-new.docx` the same way.
+- Deliverable: `.docx` or `.pptx` only. No PDF is generated, not even as a check: the `.docx` is the print master (printed from Word).
 </editorial_invariants>

package/canonical/skills/report-formatting/reference/ARCHITECTURE.md

@@ -12,7 +12,7 @@ build fails on an unknown section, a missing mandatory section or a malformed ta
 node scripts/build-architecture.js <architecture.md> <out.docx>
 ```
 
-Deliver only the `.docx` (PDF render only as a throwaway check in a scratch directory).
+Deliver only the `.docx` (print master). No PDF is generated.
 Same page identity as every house document: Claro logo, compact layout (1 cm lateral
 margins), justified 1.15 text, two fonts, blocks flush with the text. Cover page +
 static table of contents (titles only, no field update prompt; Word's navigation pane
@@ -77,8 +77,8 @@ sections as H1 (numbered), `###` as numbered H2 (N.k), `####` as H3; ```mermaid
 rendered and embedded (scaled to the text width and at most ~half a page; `<!-- width:
 70 -->` before a diagram scales it); "Figura N – …" / "Tabela N – …" lines become
 captions; `> **Nota:** …` callouts; pipe tables (`<!-- cols: 30 70 -->` fixes widths);
-`ELABORAÇÃO` block at the end; header "Documento de Arquitetura de Software — <app> |
-<project>".
+`ELABORAÇÃO` block at the end; header "<app> — Arquitetura de Software" (house
+identity, reference/authoring.md).
 
 ## Diagram set (minimum)
 

package/canonical/skills/report-formatting/reference/HELPERS.md

@@ -14,9 +14,10 @@ Import: `const T = require("./theme-claro");`
 - Lead-in sentences before a code block or table take `{ keepNext: true }` so the
   sentence and the block never separate.
 - Page geometry by layout — select it with `T.configure({ layout })` **before building
-  any block**, because the usable width derives from it: `report` (2 cm all round,
-  header/footer at 1.25 cm) and `compact` (release documents: 1 cm left/right, top
-  1.35 cm, bottom 1.03 cm, header 0.31 cm, footer 0.29 cm from the page edge).
+  any block**, because the usable width derives from it: `compact` (default, the house
+  page of every .docx: 1 cm left/right, top 1.35 cm, bottom 1.03 cm, header 0.31 cm,
+  footer 0.29 cm from the page edge) and `report` (opt-out: 2 cm all round,
+  header/footer at 1.25 cm).
   `T.configure({ page: { left, right, top, bottom, header, footer } })` overrides in DXA
   ("personalizado"). `T.contentWidth()` is the usable width; tables, code blocks,
   callouts, stat cards and images span exactly that width and are centered, so their
@@ -94,9 +95,13 @@ Import: `const T = require("./theme-claro");`
   (spread: `children.push(...T.coverBlock({...}))`). `rule: false` for the compact
   release front page (title + metaTable, no cover rule).
 - `T.authorBlock({ heading, name, role, area, project })` -> array; heading defaults to
-  "ELABORAÇÃO E ANÁLISE" ("ELABORAÇÃO" for release docs).
+  "ELABORAÇÃO", name/role to the house author (`T.HOUSE`).
 - `T.buildDocument({ children, headerText, footerAuthor, footerNote, layout, page })` ->
-  Document for `Packer.toBuffer`. `footerNote` defaults to "Confidencial – Uso Interno".
+  Document for `Packer.toBuffer`. `footerAuthor` defaults to `T.footerAuthorLine()`,
+  `footerNote` to "Confidencial – Uso Interno".
+- `T.headerLine(app, docType)` -> `"<app> — <document type>"`; `T.footerAuthorLine({ author, role, area })`
+  -> `"<author> — <role> | <area>"` (missing fields keep the house value). Page identity:
+  reference/authoring.md.
   Prefer `T.configure({ layout })` at the top of the script; passing `layout`/`page` here
   applies them to the page only and warns (blocks were already sized).
 

package/canonical/skills/report-formatting/reference/RELEASE.md

@@ -15,8 +15,7 @@ unknown change category — the structure is the model, not a suggestion.
 node scripts/build-release.js <release.md> <out.docx>
 ```
 
-Deliver only the `.docx`. A PDF render (soffice) is allowed only as a throwaway visual
-check in a scratch directory; it is never written next to the deliverable.
+Deliver only the `.docx` (print master). No PDF is generated.
 
 ## Where the structure comes from (2024-2026 practice)
 

package/canonical/skills/report-formatting/reference/TEMPLATES.md

@@ -36,8 +36,9 @@ project data, clear + rebuild a slide. Preferred over rebuilding by hand; see PP
 
 All .docx templates share the house typography (reference/HELPERS.md, "House
 typography"): two fonts, justified 1.15 text, headings kept with their text, tables and
-code blocks never cut by a page break. The release and architecture models use `layout: "compact"` (1 cm lateral margins);
-the others keep the default `report` geometry.
+code blocks never cut by a page break — and the house page identity of the release
+document (compact geometry, header `<app> — <document type>`, footer author + page
+count; reference/authoring.md). `.docx` is the only output; no PDF is generated.
 
 ## Adding a new template
 

package/canonical/skills/report-formatting/reference/authoring.md

@@ -4,50 +4,38 @@ Defaults for the authorship block and footer. Override if the user names another
 author/project. These are house defaults, not hardcoded — pass different values
 to the helpers when needed.
 
-## Default author
+## House page identity (every .docx)
 
-- Name: André Negrelli
-- Role: Tech Lead — AI Data Engineer
-- Area: DADOS & IA | Tech Dados & IA — Aquisição e Transformação de Dados & IA
-- Project: configurable per document (e.g. "Projeto STT — Claro")
+Measured from the reference release document (stt-whisperx — Release 0.4.2) and encoded
+as the defaults of `scripts/theme-claro.js`; categories A and B use it unchanged.
 
-```js
-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: "<Project> — <Client>  ·  <DATE>",
-});
-```
+| Element | Value |
+|---|---|
+| Page | A4 portrait (11906 x 16838 DXA) |
+| Layout | `compact` (default): left/right 1 cm (567), top 1.35 cm (767), bottom 1.03 cm (586), header 0.31 cm (177), footer 0.29 cm (162) from the edge |
+| Header content | `<app> — <document type>` (`T.headerLine(app, type)`), e.g. `stt-whisperx — Release` |
+| Header format | Arial italic 9 pt grey `666666`; Claro logo 24 px on a right tab at the text width; bottom rule 3/8 pt `E5D3D3`; 5 pt after |
+| Footer content | left `<author> — <role> \| <area>` (`T.footerAuthorLine()`); right `Confidencial – Uso Interno  \|  Página X de Y` (fields) |
+| Footer format | Arial 9 pt grey `666666`; top rule 3/8 pt `E5D3D3`; 5 pt before; right tab at the text width |
+| Closing block | `ELABORAÇÃO` (default heading of `T.authorBlock`) with name, role, project |
 
-Footer:
+House author (`T.HOUSE`): André Negrelli, Tech Lead AI Data Engineer, DADOS & IA. Override
+only when the user names another author/project; pass the fields, not a new format.
 
 ```js
-T.buildDocument({
-  children,
-  headerText: "<Title>  |  <Project>",
-  footerAuthor: "André Negrelli — DADOS & IA",
-});
+T.configure({ layout: "compact" });  // first line of the build (already the default)
+T.authorBlock({ project: "Speech-to-text Claro / stt-whisperx" });
+T.buildDocument({ children, headerText: T.headerLine("stt-whisperx", "Release") });  // footer = T.footerAuthorLine()
 ```
 
-## Release documents
-
-Shorter identity, measured from the reference release document
-(stt-whisperx — Release 0.4.2): header `"<app> — Release"`, footer author
-`"André Negrelli — Tech Lead AI Data Engineer | DADOS & IA"`, authorship heading
-`"ELABORAÇÃO"` with name, role and `"<Project> — Claro / <app>"`, `T.configure({ layout: "compact" })`.
-
-```js
-T.authorBlock({ heading: "ELABORAÇÃO", name: "André Negrelli", role: "Tech Lead AI Data Engineer", project: "Speech-to-text Claro / stt-whisperx" });
-T.configure({ layout: "compact" });  // first line of the build
-T.buildDocument({ children, headerText: "stt-whisperx — Release", footerAuthor: "André Negrelli — Tech Lead AI Data Engineer | DADOS & IA" });
-```
+Document types in the header: `Release`, `Arquitetura de Software`, `Relatório Técnico`,
+`Relatório Executivo`, `Revisão Arquitetural`. `layout: "report"` (2 cm all round) is an
+opt-out used only when the user asks for it.
 
 ## Document identity (Claro theme)
 
-- A4 page, Arial for prose + Consolas for code (no third font); geometry per layout
-  (`report`: 2 cm all round; `compact` for release documents: 1 cm left/right, tight
-  top/bottom, header/footer close to the edge). Blocks span the text width, centered.
+- A4 page, Arial for prose + Consolas for code (no third font); `compact` geometry for
+  every document (table above). Blocks span the text width, centered.
 - Body text justified, 1.15 line spacing; headings keep with the next paragraph;
   tables, code blocks and callouts are never cut by a page break.
 - Claro institutional palette (red anchors, gray hierarchy): red headings, red
@@ -57,9 +45,9 @@ T.buildDocument({ children, headerText: "stt-whisperx — Release", footerAuthor
   coverBlock) and small in the top-right of every page header (via buildDocument).
   Both degrade cleanly if the asset is missing. Use `T.logoRun({height})` to place
   it elsewhere.
-- Italic grey header with a bottom rule + logo; footer with author on the left and
-  "Confidencial – Uso Interno | Página X de Y" on the right.
-- Centered "ELABORAÇÃO E ANÁLISE" authorship block at the end.
+- Header and footer exactly as the table above.
+- Centered "ELABORAÇÃO" authorship block at the end.
+- Deliverable is the .docx (print master); no PDF is generated.
 - Output language: PT-BR by default (client-facing); change per request.
 
 The logo asset is shared by both formats at scripts/assets/claro-logo.png (pptx uses

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

@@ -21,7 +21,7 @@ const model = {
   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+$/, ""),
+  headerText: (m) => `${m.app} — Arquitetura de Software`,     // house header "<app> — <document type>"
   requiredMeta: ["app", "title", "version", "date", "status"],
   meta: [
     ["app", "Aplicação"], ["doc_type", "Tipo de documento"], ["version", "Versão do documento"],

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

@@ -210,15 +210,12 @@ while (i < md.length) {
 }
 
 // ---- assemble -------------------------------------------------------------
-const front = T.coverBlock({ title: opt.title || path.basename(inputPath, ".md"), subtitle: opt.subtitle || undefined });
+const title = opt.title || path.basename(inputPath, ".md");
+const front = T.coverBlock({ title, subtitle: opt.subtitle || undefined, rule: false });  // compact front page, as the release
 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}`);
-});
+const tail = T.authorBlock({ name: opt.author || undefined, role: opt.role || undefined, area: T.HOUSE.area, project: opt.project || undefined });
+const doc = T.buildDocument({ children: [...front, T.spacer(160), ...children, ...tail], headerText: opt.header || title, footerAuthor: T.footerAuthorLine({ author: opt.author, role: opt.role }) });
+T.saveDocx(doc, outputPath).then(() => console.log(`diagramas: ${diagramIndex}`));

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

@@ -49,10 +49,6 @@ function hasChrome() {
 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

@@ -259,18 +259,10 @@ async function build(model, inputPath, outputPath) {
     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 });
+  children.push(...T.authorBlock({ heading: model.authorHeading || "ELABORAÇÃO", name: meta.author || T.HOUSE.author, role: meta.role || T.HOUSE.role, area: meta.area, project: meta.project || meta.app }));
+  const doc = T.buildDocument({ children, headerText: model.headerText(meta), footerAuthor: T.footerAuthorLine({ author: meta.author, role: meta.role, area: meta.area }), 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)`);
+  await T.saveDocx(doc, outputPath);  // Word lock guard lives in the theme (one implementation)
 }
 
 /** CLI wrapper: `node build-<model>.js <content.md> <out.docx>`. */

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

@@ -20,6 +20,8 @@ const path = require("path");
 const { Packer, AlignmentType } = require("docx");
 const T = require("./theme-claro");
 
+T.configure({ layout: "compact" });  // house page (release geometry); set before any block
+
 const children = [];
 
 // ---- CAPA ----
@@ -98,22 +100,18 @@ children.push(T.codeBlock([
 
 // ---- 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",
+  heading: "ELABORAÇÃO",
+  name: T.HOUSE.author,
+  role: T.HOUSE.role,
   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",
+  headerText: T.headerLine("<app>", "Relatório Técnico"),  // house header "<app> — <document type>"
+  footerAuthor: T.footerAuthorLine(),             // "André Negrelli — Tech Lead AI Data Engineer | 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)`);
-});
+T.saveDocx(doc, outPath);  // writes <name>-new.docx when Word holds the file open

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

@@ -24,6 +24,8 @@ const path = require("path");
 const { Packer, AlignmentType } = require("docx");
 const T = require("./theme-claro");
 
+T.configure({ layout: "compact" });  // house page (release geometry); set before any block
+
 const children = [];
 
 /** Severity scale shared by the findings table and the summary cards. */
@@ -175,21 +177,17 @@ children.push(T.callout([
 
 // ---- 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",
+  heading: "ELABORAÇÃO",
+  name: T.HOUSE.author,
+  role: T.HOUSE.role,
   project: "<Projeto> — Claro  ·  DD/MM/AAAA",
 }));
 
 const doc = T.buildDocument({
   children,
-  headerText: "Revisão Arquitetural  |  <Projeto> Claro",
-  footerAuthor: "André Negrelli — DADOS & IA",
+  headerText: T.headerLine("<app>", "Revisão Arquitetural"),  // house header "<app> — <document type>"
+  footerAuthor: T.footerAuthorLine(),             // "André Negrelli — Tech Lead AI Data Engineer | 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)`);
-});
+T.saveDocx(doc, outPath);  // writes <name>-new.docx when Word holds the file open

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

@@ -19,6 +19,8 @@ const path = require("path");
 const { Packer, AlignmentType } = require("docx");
 const T = require("./theme-claro");
 
+T.configure({ layout: "compact" });  // house page (release geometry); set before any block
+
 const children = [];
 
 // ---- COVER (rich) ----
@@ -94,21 +96,17 @@ children.push(T.callout([
 
 // ---- 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",
+  heading: "ELABORAÇÃO",
+  name: T.HOUSE.author,
+  role: T.HOUSE.role,
   project: "Projeto STT — Claro  ·  22/06/2026",
 }));
 
 const doc = T.buildDocument({
   children,
-  headerText: "Relatório Executivo  |  STT Claro",
-  footerAuthor: "André Negrelli — DADOS & IA",
+  headerText: T.headerLine("<app>", "Relatório Executivo"),  // house header "<app> — <document type>"
+  footerAuthor: T.footerAuthorLine(),             // "André Negrelli — Tech Lead AI Data Engineer | DADOS & IA"
 });
 
 const outPath = process.argv[2] || path.join(process.cwd(), "out", "Relatorio_Executivo.docx");
-fs.mkdirSync(path.dirname(outPath), { recursive: true });
-Packer.toBuffer(doc).then((buf) => {
-  fs.writeFileSync(outPath, buf);
-  console.log("Gerado:", outPath, `(${buf.length} bytes)`);
-});
+T.saveDocx(doc, outPath);  // writes <name>-new.docx when Word holds the file open

package/canonical/skills/report-formatting/scripts/theme-claro.js

@@ -12,7 +12,7 @@
 const fs = require("fs");
 const path = require("path");
 const {
-  Document, Paragraph, TextRun, Table, TableRow, TableCell,
+  Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell,
   Header, Footer, AlignmentType, BorderStyle, WidthType, ShadingType,
   VerticalAlign, PageNumber, ImageRun, PageBreak,
 } = require("docx");
@@ -31,9 +31,10 @@ const C = {
   noteFill: "FFF2CC", dangerFill: "FFE0E0", successFill: "E2EFDA", infoFill: "FBEDED",
   rule: "E2000F", codeFill: "F5F5F5", codeText: "1F1F1F", codeBar: "555555",
 };
-// A4 portrait. Geometry per layout (DXA): "report" is the classic page (2 cm all
-// round); "compact" is the release page — 1 cm lateral margins, tight top/bottom,
-// header and footer close to the page edge. Blocks (tables, code, callouts,
+// A4 portrait. Geometry per layout (DXA): "compact" is the house page, measured from
+// the reference release document (stt-whisperx — Release 0.4.2) and the default for
+// every .docx — 1 cm lateral margins, top 1.35 cm, bottom 1.03 cm, header 0.31 cm and
+// footer 0.29 cm from the page edge; "report" (2 cm all round) is an explicit opt-out. Blocks (tables, code, callouts,
 // images) span exactly the text width and are centered, so their edges meet the
 // justified text. Select the layout with T.configure({ layout }) BEFORE building
 // blocks: the usable width depends on it.
@@ -42,6 +43,15 @@ const LAYOUTS = {
   report:  { top: 1134, bottom: 1134, left: 1134, right: 1134, header: 708, footer: 708 },
   compact: { top: 767,  bottom: 586,  left: 567,  right: 567,  header: 177, footer: 162 },
 };
+// House identity (same reference document): header "<app> — <document type>" in italic
+// grey 9 pt with the Claro logo (24 px) right-aligned over a bottom rule; footer over a top
+// rule with "<author> — <role> | <area>" on the left and "<note>  |  Página X de Y" on the
+// right (9 pt grey). The .docx is the print master: no PDF is produced.
+const HOUSE = { author: "André Negrelli", role: "Tech Lead AI Data Engineer", area: "DADOS & IA", footerNote: "Confidencial – Uso Interno" };
+/** Footer author line "<author> — <role> | <area>"; o overrides any field (falsy keeps the house value). */
+const footerAuthorLine = (o = {}) => `${o.author || HOUSE.author} — ${o.role || HOUSE.role} | ${o.area || HOUSE.area}`;
+/** Header line "<app> — <document type>" (e.g. "stt-whisperx — Release"). */
+const headerLine = (app, docType) => [app, docType].filter(Boolean).join(" — ");
 const CONTENT_W = 9640;  // legacy constant (report layout); prefer contentWidth()
 const EMU_PER_PX = 9525;
 // Font sizes in half-points: body 11 pt, code 9 pt, table cell 10 pt, cell code 8.5 pt.
@@ -51,7 +61,7 @@ const LOGO_PATH = path.join(__dirname, "assets", "claro-logo.png");
 
 // Mutable house defaults; T.configure({ justify: false }) opts out for a build.
 // Justified text needs automatic hyphenation to avoid rivers of white space.
-const DEFAULTS = { justify: true, hyphenate: true, line: 276, lang: "pt-BR", layout: "report", page: {} };
+const DEFAULTS = { justify: true, hyphenate: true, line: 276, lang: "pt-BR", layout: "compact", page: {} };
 /** Override the house defaults (layout, page overrides, justify, hyphenate, line, lang) for the current build. */
 function configure(o = {}) { Object.assign(DEFAULTS, o); }
 /** Page geometry of the configured layout, with DEFAULTS.page overrides applied. */
@@ -324,8 +334,8 @@ function coverBlock({ title, subtitle, tagline, org, metaLines = [], rule = true
 }
 
 // ---- AUTHORSHIP BLOCK ----
-/** Authorship block closing the document; heading defaults to "ELABORAÇÃO E ANÁLISE". */
-function authorBlock({ heading: hd = "ELABORAÇÃO E ANÁLISE", name, role, area, project } = {}) {
+/** Authorship block closing the document; heading "ELABORAÇÃO", name/role default to the house author. */
+function authorBlock({ heading: hd = "ELABORAÇÃO", name = HOUSE.author, role = HOUSE.role, area, project } = {}) {
   const out = [];
   const line = (text, o) => new Paragraph({ alignment: AlignmentType.CENTER, keepNext: true, keepLines: true, spacing: o.spacing, children: [t(text, o.run)] });
   out.push(spacer(240));
@@ -339,8 +349,8 @@ function authorBlock({ heading: hd = "ELABORAÇÃO E ANÁLISE", name, role, area
 }
 
 // ---- DOCUMENT ----
-/** Final Document: A4, header/footer, lists, house defaults; layout "report" | "compact", page = DXA overrides. */
-function buildDocument({ children, headerText = "", footerAuthor = "", footerNote = "Confidencial – Uso Interno", layout, page, updateFields = false }) {
+/** Final Document: A4, house header/footer, lists, house defaults; layout "compact" (default) | "report", page = DXA overrides. */
+function buildDocument({ children, headerText = "", footerAuthor = footerAuthorLine(), footerNote = HOUSE.footerNote, layout, page, updateFields = false }) {
   if ((layout && layout !== DEFAULTS.layout) || page) {
     console.warn("theme-claro: pass layout/page to T.configure() before building blocks; buildDocument() applies them to the page only");
     configure({ layout: layout || DEFAULTS.layout, page: page || DEFAULTS.page });
@@ -387,9 +397,28 @@ function buildDocument({ children, headerText = "", footerAuthor = "", footerNot
   });
 }
 
+/**
+ * Write the Document to outPath, never over a file Word holds open: with a lock
+ * "~$<name>" beside it, writes "<name>-new.docx" and warns (Word reloads images lazily
+ * and would save broken links). Resolves to the path actually written.
+ */
+async function saveDocx(doc, outPath) {
+  const outAbs = path.resolve(outPath);
+  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(`${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)`);
+  return target;
+}
+
 module.exports = {
   // tokens
   C, FONT, MONO, SZ, CONTENT_W, PAGE, LAYOUTS, DEFAULTS, configure, contentWidth, geometry, fitCols,
+  // house identity
+  HOUSE, footerAuthorLine, headerLine,
   // runs
   t, mono, cap, rich, rc,
   // blocks
@@ -399,5 +428,5 @@ module.exports = {
   // highlights
   callout, calloutLine, codeBlock, statCards,
   // media / structure
-  image, logoRun, coverBlock, authorBlock, buildDocument, LOGO_PATH,
+  image, logoRun, coverBlock, authorBlock, buildDocument, saveDocx, LOGO_PATH,
 };