freeharness 0.4.1

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

@@ -0,0 +1,403 @@
+"use strict";
+/**
+ * theme-claro.js — "Claro" theme library for docx reports (docx-js).
+ *
+ * House typography, applied by the helpers: two fonts only (Arial prose, Consolas
+ * code); justified body at 1.15 line spacing with widow/orphan control; headings
+ * keep with the next paragraph; table rows never split and short tables, code
+ * blocks and callouts stay on one page. Usage and API: reference/HELPERS.md.
+ * Requires: npm i docx image-size
+ */
+
+const fs = require("fs");
+const path = require("path");
+const {
+  Document, Paragraph, TextRun, Table, TableRow, TableCell,
+  Header, Footer, AlignmentType, BorderStyle, WidthType, ShadingType,
+  VerticalAlign, PageNumber, ImageRun, PageBreak,
+} = require("docx");
+
+// ---- DESIGN TOKENS ----
+const FONT = "Arial";
+const MONO = "Consolas";
+// Claro institutional palette (aligned with theme_claro_pptx.py). Red anchors,
+// gray hierarchy, red table headers with white text.
+const C = {
+  title: "B8000D", subtitle: "333333", h1: "B8000D", h2: "333333", h3: "666666",
+  accent: "E2000F", muted: "666666", body: "333333",
+  red: "E2000F", deepRed: "B8000D", green: "2E7D32", amber: "B36B00",
+  tblHeadFill: "B8000D", tblHeadText: "FFFFFF", tblBorder: "E5D3D3",
+  zebra: "F7F1F1", white: "FFFFFF",
+  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,
+// 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.
+const PAGE = { width: 11906, height: 16838, margin: 1134, header: 708, footer: 708 };
+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 },
+};
+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.
+const SZ = { body: 22, mono: 18, cell: 20, cellMono: 17 };
+// Claro logo asset (transparent PNG), resolved relative to this file.
+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: {} };
+/** 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. */
+const geometry = () => ({ ...(LAYOUTS[DEFAULTS.layout] || LAYOUTS.report), ...DEFAULTS.page });
+/** Usable text width (DXA) for the configured layout. */
+const contentWidth = () => { const g = geometry(); return PAGE.width - g.left - g.right; };
+/** Scale column widths so they sum to the usable width (keeps old 9640-based tables aligned). */
+function fitCols(cols) {
+  const W = contentWidth(), sum = cols.reduce((a, b) => a + b, 0);
+  if (!sum || sum === W) return cols;
+  const out = cols.map((c) => Math.floor(c * W / sum));
+  out[out.length - 1] += W - out.reduce((a, b) => a + b, 0);
+  return out;
+}
+const jc = () => (DEFAULTS.justify ? AlignmentType.JUSTIFIED : undefined);
+
+/** ImageRun of the Claro logo at a pixel height; null when the asset is missing. */
+function logoRun({ height = 28 } = {}) {
+  if (!fs.existsSync(LOGO_PATH)) return null;
+  const data = fs.readFileSync(LOGO_PATH);
+  let w = height;
+  try {
+    const s = require("image-size");
+    const d = s.imageSize ? s.imageSize(data) : s(data);
+    w = Math.round(height * d.width / d.height);
+  } catch (e) { w = Math.round(height * 543 / 490); }
+  return new ImageRun({ type: "png", data, transformation: { width: w, height } });
+}
+
+// ---- RUNS ----
+/** Body TextRun (Arial); o = extra TextRun options. */
+const t = (text, o = {}) => new TextRun({ text, font: FONT, ...o });
+/** Monospaced (Consolas) run for commands/identifiers; sz in half-points. */
+const mono = (text, sz = SZ.mono) => new TextRun({ text, font: MONO, size: sz, color: C.codeText });
+/** Bold colored label run that opens a callout or paragraph. */
+const cap = (label, color = C.accent) => t(label + " ", { size: SZ.cell, bold: true, color });
+
+/** Markdown-lite inline parser: `code` -> mono run, **bold** (may wrap code), *italic*; the rest is body text. */
+function rich(text, { size = SZ.body, monoSize = SZ.mono, color = C.body } = {}) {
+  const runs = [];
+  const emit = (seg, bold) => {
+    for (const part of seg.split(/(`[^`]+`)/g)) {
+      if (!part) continue;
+      if (part.length >= 2 && part.startsWith("`") && part.endsWith("`")) { runs.push(new TextRun({ text: part.slice(1, -1), font: MONO, size: monoSize, color: C.codeText, bold })); continue; }
+      for (const it of part.split(/(\*[^*\s][^*]*\*)/g)) {
+        if (!it) continue;
+        if (it.length >= 3 && it.startsWith("*") && it.endsWith("*")) runs.push(t(it.slice(1, -1), { size, italics: true, bold, color }));
+        else runs.push(t(it, { size, bold, color }));
+      }
+    }
+  };
+  for (const b of String(text).split(/(\*\*[^*]+(?:\*(?!\*)[^*]*)*\*\*)/g)) {
+    if (!b) continue;
+    if (b.length >= 4 && b.startsWith("**") && b.endsWith("**")) emit(b.slice(2, -2), true);
+    else emit(b, false);
+  }
+  return runs;
+}
+/** rich() at table-cell sizes (10 pt / 8.5 pt mono). */
+const rc = (text) => rich(text, { size: SZ.cell, monoSize: SZ.cellMono });
+
+// ---- TEXT BLOCKS ----
+const asRuns = (runs, size = SZ.body) => (Array.isArray(runs) ? runs : [t(runs, { size, color: C.body })]);
+
+/** Body paragraph (justified, 1.15). o = Paragraph options plus `before` (DXA), e.g. { keepNext: true } before a code block. */
+function body(runs, { before, ...o } = {}) {
+  return new Paragraph({ alignment: jc(), spacing: { before, after: 120, line: DEFAULTS.line }, children: asRuns(runs), ...o });
+}
+/** body() over rich() text. */
+const p = (text, o = {}) => body(rich(text), o);
+
+const heading = (text, { size, color, before, after, o = {} }) => new Paragraph({
+  spacing: { before, after, line: DEFAULTS.line }, keepNext: true, keepLines: true,
+  children: [t(text, { bold: true, color, size })], ...o,
+});
+/** Heading 1; o e.g. { pageBreakBefore: true }. */
+const h1 = (text, o = {}) => heading(text, { size: 30, color: C.h1, before: 300, after: 120, o: { outlineLevel: 0, ...o } });
+/** Heading 2. */
+const h2 = (text, o = {}) => heading(text, { size: 25, color: C.h2, before: 220, after: 80, o: { outlineLevel: 1, ...o } });
+/** Heading 3. */
+const h3 = (text, o = {}) => heading(text, { size: 23, color: C.h3, before: 160, after: 60, o: { outlineLevel: 2, ...o } });
+/** Italic grey caption (figure/table legend). */
+const caption = (text, opts = {}) => new Paragraph({ spacing: { before: 40, after: 220, line: DEFAULTS.line }, keepLines: true, alignment: opts.center ? AlignmentType.CENTER : undefined, children: [t(text, { italics: true, color: C.muted, size: SZ.cell })] });
+/** Empty paragraph used as vertical space (DXA). */
+const spacer = (after = 120) => new Paragraph({ spacing: { after }, children: [] });
+/** Hard page break. */
+const pageBreak = () => new Paragraph({ children: [new PageBreak()] });
+
+/** Bulleted list item; lvl 0 or 1. */
+function bullet(runs, lvl = 0, o = {}) {
+  return new Paragraph({ alignment: jc(), numbering: { reference: "bullets", level: lvl }, spacing: { after: 70, line: DEFAULTS.line }, children: asRuns(runs), ...o });
+}
+/** bullet() over rich() text. */
+const li = (text, lvl = 0, o = {}) => bullet(rich(text), lvl, o);
+
+/** Numbered list item; each distinct instance restarts at 1 (instance 0 is shared). */
+function numItem(runs, opts = 0, o = {}) {
+  const { instance = 0, lvl = 0 } = typeof opts === "number" ? { instance: opts } : opts;
+  return new Paragraph({ alignment: jc(), numbering: { reference: "nums", level: lvl, instance }, spacing: { after: 80, line: DEFAULTS.line }, children: asRuns(runs), ...o });
+}
+/** numItem() over rich() text. */
+const num = (text, opts = 0, o = {}) => numItem(rich(text), opts, o);
+/** Whole numbered list (1..n) from rich() strings, as its own instance. */
+const numbered = (items, instance) => items.map((s) => num(s, instance));
+
+// ---- TABLES ----
+const cb = { style: BorderStyle.SINGLE, size: 1, color: C.tblBorder };
+const cellBorders = { top: cb, bottom: cb, left: cb, right: cb };
+
+/** One table cell; keepNext holds the row with the next one (whole-table keep). */
+function cell(content, { fill, w, align, header = false, valign, keepNext = false } = {}) {
+  let kids;
+  if (Array.isArray(content) && content[0] instanceof Paragraph) kids = content;
+  else {
+    const rpr = header ? { bold: true, color: C.tblHeadText, size: SZ.cell } : { size: SZ.cell, color: C.body };
+    kids = [new Paragraph({ alignment: align, keepNext, spacing: { line: DEFAULTS.line }, children: typeof content === "string" ? [t(content, rpr)] : content })];
+  }
+  return new TableCell({
+    borders: cellBorders, width: { size: w, type: WidthType.DXA },
+    shading: { fill: fill || (header ? C.tblHeadFill : C.white), type: ShadingType.CLEAR },
+    margins: { top: 70, bottom: 70, left: 120, right: 120 },
+    verticalAlign: valign || VerticalAlign.CENTER, children: kids,
+  });
+}
+
+/** Data table: red header (repeats per page), zebra rows, rows never split; keepTogether defaults to rows <= 12; rich parses string cells. */
+function makeTable(cols, head, rows, { keepTogether, rich: useRich = false } = {}) {
+  cols = fitCols(cols);
+  const keep = keepTogether === undefined ? rows.length <= 12 : keepTogether;
+  const last = rows.length - 1;
+  const txt = (s) => (useRich ? rc(s) : [t(s, { size: SZ.cell, color: C.body })]);
+  const headRow = new TableRow({ tableHeader: true, cantSplit: true, children: head.map((h, i) => cell(h, { w: cols[i], header: true, keepNext: keep })) });
+  const bodyRows = rows.map((r, ri) => new TableRow({
+    cantSplit: true,
+    children: r.map((cv, ci) => {
+      const zebra = ri % 2 === 1 ? C.zebra : C.white;
+      const keepNext = keep && ri < last;
+      if (cv && typeof cv === "object" && !Array.isArray(cv)) {
+        const fill = cv.fill || zebra;
+        const runs = typeof cv.runs === "string" ? txt(cv.runs) : cv.runs;
+        return cell([new Paragraph({ alignment: cv.align, keepNext, spacing: { line: DEFAULTS.line }, children: runs })], { w: cols[ci], fill, valign: VerticalAlign.TOP });
+      }
+      return cell(useRich ? txt(cv) : cv, { w: cols[ci], fill: zebra, valign: VerticalAlign.TOP, keepNext });
+    }),
+  }));
+  return new Table({ alignment: AlignmentType.CENTER, width: { size: contentWidth(), type: WidthType.DXA }, columnWidths: cols, borders: cellBorders, rows: [headRow, ...bodyRows] });
+}
+
+/** Two-column metadata (memo) table: column 1 is a highlighted label, column 2 the value. Always held together on one page. */
+function metaTable(rows, col1 = 2500) {
+  const cols = [col1, contentWidth() - col1];
+  const last = rows.length - 1;
+  return new Table({
+    alignment: AlignmentType.CENTER, width: { size: contentWidth(), type: WidthType.DXA }, columnWidths: cols, borders: cellBorders,
+    rows: rows.map((r, i) => new TableRow({ cantSplit: true, children: [
+      cell(r[0], { w: cols[0], fill: C.tblHeadFill, header: true, keepNext: i < last }),
+      cell([new Paragraph({ keepNext: i < last, spacing: { line: DEFAULTS.line }, children: typeof r[1] === "string" ? rc(r[1]) : r[1] })], { w: cols[1], fill: C.white }),
+    ] })),
+  });
+}
+
+// ---- CALLOUTS ----
+const CALLOUT_KINDS = {
+  info:    { fill: C.infoFill,    bar: C.accent },
+  note:    { fill: C.noteFill,    bar: C.amber },
+  danger:  { fill: C.dangerFill,  bar: C.red },
+  success: { fill: C.successFill, bar: C.green },
+};
+/** A callout box: one bordered cell with a colored left bar and tinted fill. The box never splits across pages. */
+function callout(paras, kindOrFill = "info", barColor) {
+  let fill, bar;
+  if (CALLOUT_KINDS[kindOrFill]) { ({ fill, bar } = CALLOUT_KINDS[kindOrFill]); }
+  else { fill = kindOrFill; bar = barColor || C.rule; }
+  const arr = typeof paras === "string" ? [p(paras, { spacing: { after: 0, line: DEFAULTS.line } })] : Array.isArray(paras) ? paras : [paras];
+  const W = contentWidth();
+  return new Table({
+    alignment: AlignmentType.CENTER, width: { size: W, type: WidthType.DXA }, columnWidths: [W], borders: cellBorders,
+    rows: [new TableRow({ cantSplit: true, children: [new TableCell({
+      borders: { ...cellBorders, left: { style: BorderStyle.SINGLE, size: 18, color: bar } },
+      width: { size: W, type: WidthType.DXA },
+      shading: { fill, type: ShadingType.CLEAR },
+      margins: { top: 120, bottom: 120, left: 200, right: 180 }, children: arr,
+    })] })],
+  });
+}
+/** One-line "Label: text" callout; text accepts rich() syntax. */
+function calloutLine(label, text, kind = "info", labelColor) {
+  const bar = CALLOUT_KINDS[kind] ? CALLOUT_KINDS[kind].bar : C.accent;
+  return callout([new Paragraph({ alignment: jc(), spacing: { line: DEFAULTS.line }, children: [cap(label, labelColor || bar), ...rich(text, { size: SZ.cell, monoSize: SZ.cellMono })] })], kind);
+}
+
+// ---- CODE / LOG BLOCK ----
+/** Monospaced code/log block with a grey bar, held on one page. */
+function codeBlock(lines) {
+  const arr = Array.isArray(lines) ? lines : String(lines).split("\n");
+  const W = contentWidth();
+  return new Table({
+    alignment: AlignmentType.CENTER, width: { size: W, type: WidthType.DXA }, columnWidths: [W], borders: cellBorders,
+    rows: [new TableRow({ cantSplit: true, children: [new TableCell({
+      borders: { ...cellBorders, left: { style: BorderStyle.SINGLE, size: 18, color: C.codeBar } },
+      width: { size: W, type: WidthType.DXA },
+      shading: { fill: C.codeFill, type: ShadingType.CLEAR },
+      margins: { top: 100, bottom: 100, left: 160, right: 140 },
+      children: arr.map((ln, i) => new Paragraph({
+        keepNext: i < arr.length - 1, keepLines: true,
+        spacing: { after: i === arr.length - 1 ? 0 : 20, line: 240 },
+        children: [mono(ln.length ? ln : " ", SZ.cellMono)],
+      })),
+    })] })],
+  });
+}
+
+// ---- STAT CARDS ----
+/** Row of equal-width stat cards: big number over a small label. */
+function statCards(cards) {
+  const W = contentWidth();
+  const w = Math.floor(W / cards.length);
+  return new Table({
+    alignment: AlignmentType.CENTER, width: { size: W, type: WidthType.DXA }, columnWidths: cards.map(() => w), borders: cellBorders,
+    rows: [new TableRow({ cantSplit: true, children: cards.map((c) => new TableCell({
+      borders: cellBorders, width: { size: w, type: WidthType.DXA },
+      shading: { fill: c.fill || C.infoFill, type: ShadingType.CLEAR },
+      margins: { top: 120, bottom: 120, left: 90, right: 90 }, verticalAlign: VerticalAlign.CENTER,
+      children: [
+        new Paragraph({ alignment: AlignmentType.CENTER, spacing: { after: 20 }, children: [t(c.value, { bold: true, size: 32, color: c.color || C.title })] }),
+        new Paragraph({ alignment: AlignmentType.CENTER, children: [t(c.label, { size: 15, color: C.muted })] }),
+      ],
+    })) })],
+  });
+}
+
+// ---- IMAGES / DIAGRAMS ----
+/** Centered PNG scaled to fit the text width and ~half a page height; keepNext glues it to its caption. */
+function image(filePath, maxWidthEmu, { keepNext = true, maxHeightEmu } = {}) {
+  if (!maxWidthEmu) maxWidthEmu = contentWidth() * 635;  // full text width
+  const g = geometry();
+  if (!maxHeightEmu) maxHeightEmu = Math.round((PAGE.height - g.top - g.bottom) * 635 * 0.55);  // never taller than ~half a page
+  const data = fs.readFileSync(filePath);
+  let width, height;
+  try {
+    const sizeOf = require("image-size");
+    const dim = sizeOf.imageSize ? sizeOf.imageSize(data) : sizeOf(data);
+    width = dim.width; height = dim.height;
+  } catch (e) {
+    width = 1600; height = 900; // reasonable fallback when image-size is missing
+  }
+  const wEmu = width * EMU_PER_PX, hEmu = height * EMU_PER_PX;
+  const scale = Math.min(1, maxWidthEmu / wEmu, maxHeightEmu / hEmu);
+  return new Paragraph({
+    spacing: { before: 120, after: 60 }, alignment: AlignmentType.CENTER, keepNext,
+    children: [new ImageRun({ type: "png", data, transformation: { width: Math.round(wEmu / EMU_PER_PX * scale), height: Math.round(hEmu / EMU_PER_PX * scale) } })],
+  });
+}
+
+// ---- COVER ----
+/** Build the cover page block (centered logo, title, subtitle, tagline, org, meta lines). Falls back to a spacer when the logo asset is missing. */
+function coverBlock({ title, subtitle, tagline, org, metaLines = [], rule = true }) {
+  const out = [spacer(40)];
+  const lr = logoRun({ height: 96 });
+  if (lr) out.push(new Paragraph({ alignment: AlignmentType.CENTER, spacing: { after: 200 }, children: [lr] }));
+  else out.push(spacer(60));
+  out.push(spacer(40));
+  out.push(new Paragraph({ spacing: { after: 120 }, alignment: AlignmentType.CENTER, children: [t(title, { bold: true, color: C.title, size: 44 })] }));
+  if (subtitle) out.push(new Paragraph({ spacing: { after: 80 }, alignment: AlignmentType.CENTER, children: [t(subtitle, { color: C.subtitle, size: 30 })] }));
+  if (tagline) out.push(new Paragraph({ spacing: { after: 60 }, alignment: AlignmentType.CENTER, children: [t(tagline, { italics: true, color: C.muted, size: 24 })] }));
+  if (org) out.push(new Paragraph({ spacing: { after: 400 }, alignment: AlignmentType.CENTER, children: [t(org, { color: C.muted, size: SZ.body })] }));
+  if (rule) out.push(new Paragraph({ spacing: { after: 200 }, border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: C.rule, space: 1 } }, children: [] }));
+  metaLines.forEach((s) => out.push(new Paragraph({ spacing: { after: 60 }, alignment: AlignmentType.CENTER, children: [t(s, { italics: true, color: C.muted, size: SZ.cell })] })));
+  return out;
+}
+
+// ---- 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 } = {}) {
+  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));
+  out.push(new Paragraph({ keepNext: true, spacing: { before: 160, after: 120 }, border: { top: { style: BorderStyle.SINGLE, size: 6, color: C.rule, space: 1 } }, children: [] }));
+  out.push(line(hd, { spacing: { after: 60 }, run: { bold: true, color: C.h1, size: SZ.cell } }));
+  if (name) out.push(line(name, { spacing: { after: 30 }, run: { bold: true, size: 26, color: C.subtitle } }));
+  if (role) out.push(line(role, { spacing: { after: 20 }, run: { size: SZ.body, color: C.body } }));
+  if (area) out.push(line(area, { spacing: { after: 20 }, run: { size: SZ.cell, color: C.muted } }));
+  if (project) out.push(line(project, { spacing: { after: 0 }, run: { size: SZ.cell, color: C.muted } }));
+  return out;
+}
+
+// ---- 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 }) {
+  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 });
+  }
+  const geo = geometry();
+  const W = contentWidth();
+  const hLogo = logoRun({ height: 24 });
+  const headerChildren = [t(headerText, { italics: true, color: C.muted, size: 18 })];
+  if (hLogo) headerChildren.push(t("\t", { size: 18 }), hLogo);
+  const header = new Header({ children: [new Paragraph({
+    spacing: { after: 100 }, border: { bottom: { style: BorderStyle.SINGLE, size: 3, color: C.tblBorder, space: 1 } },
+    tabStops: [{ type: "right", position: W }],
+    children: headerChildren,
+  })] });
+  const footer = new Footer({ children: [new Paragraph({
+    spacing: { before: 100 }, border: { top: { style: BorderStyle.SINGLE, size: 3, color: C.tblBorder, space: 1 } },
+    tabStops: [{ type: "right", position: W }],
+    children: [
+      t(footerAuthor, { color: C.muted, size: 18 }),
+      t(`\t${footerNote}  |  Página `, { color: C.muted, size: 18 }),
+      new TextRun({ children: [PageNumber.CURRENT], font: FONT, color: C.muted, size: 18 }),
+      t(" de ", { color: C.muted, size: 18 }),
+      new TextRun({ children: [PageNumber.TOTAL_PAGES], font: FONT, color: C.muted, size: 18 }),
+    ],
+  })] });
+
+  return new Document({
+    features: { updateFields },  // true when a TOC field must refresh on open
+    hyphenation: { autoHyphenation: DEFAULTS.hyphenate, doNotHyphenateCaps: true, consecutiveHyphenLimit: 2 },
+    styles: { default: { document: {
+      run: { font: FONT, size: SZ.body, color: C.body, language: { value: DEFAULTS.lang } },
+      paragraph: { spacing: { line: DEFAULTS.line }, widowControl: true },
+    } } },
+    numbering: { config: [
+      { reference: "bullets", levels: [{ level: 0, format: "bullet", text: "•", alignment: AlignmentType.LEFT, style: { paragraph: { indent: { left: 540, hanging: 280 } } } },
+                                       { level: 1, format: "bullet", text: "◦", alignment: AlignmentType.LEFT, style: { paragraph: { indent: { left: 1080, hanging: 280 } } } }] },
+      { reference: "nums", levels: [{ level: 0, format: "decimal", text: "%1.", alignment: AlignmentType.LEFT, style: { paragraph: { indent: { left: 540, hanging: 320 } } } },
+                                    { level: 1, format: "lowerLetter", text: "%2)", alignment: AlignmentType.LEFT, style: { paragraph: { indent: { left: 1080, hanging: 320 } } } }] },
+    ] },
+    sections: [{
+      properties: { page: { size: { width: PAGE.width, height: PAGE.height }, margin: { top: geo.top, right: geo.right, bottom: geo.bottom, left: geo.left, header: geo.header, footer: geo.footer } } },
+      headers: { default: header }, footers: { default: footer }, children,
+    }],
+  });
+}
+
+module.exports = {
+  // tokens
+  C, FONT, MONO, SZ, CONTENT_W, PAGE, LAYOUTS, DEFAULTS, configure, contentWidth, geometry, fitCols,
+  // runs
+  t, mono, cap, rich, rc,
+  // blocks
+  body, p, h1, h2, h3, caption, spacer, pageBreak, bullet, li, numItem, num, numbered,
+  // tables
+  makeTable, metaTable, cell,
+  // highlights
+  callout, calloutLine, codeBlock, statCards,
+  // media / structure
+  image, logoRun, coverBlock, authorBlock, buildDocument, LOGO_PATH,
+};

package/canonical/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: subagent-driven-development
+description: Use when executing an approved tasks.md from an OpenSpec change: one brief per task under .freeharness/sdd/<change>/, a fresh implementer per dispatch with an explicit tier and a disjoint write scope, a JSON handoff, the lead's own test run and diff review, one combined task reviewer, a 5-round circuit breaker and one final branch review via code-review. Not for ad-hoc one-file edits.
+---
+
+# Subagent-Driven Development Protocol
+
+<orchestrator_directive>
+The primary session is the lead: it dispatches, evaluates and rules; it never writes production code while executing `tasks.md`. A feature starts at `/opsx:propose`; this skill runs the approved `tasks.md` after `/opsx:apply`. Continuous execution: no "should I continue?" between tasks; the stop conditions below are the only pauses.
+</orchestrator_directive>
+
+<workspace>
+- Artifacts live in `.freeharness/sdd/<change>/` (gitignored; `init --project` creates it): `<task>.brief.md` and `<task>.review.md`. Files survive compaction; after compaction trust the review packages, `tasks.md` checkboxes and `git log`, never recollection.
+- Templates: `reference/brief.md`, `reference/handoff.md`. The validator `scripts/validate-handoff.mjs` has six subcommands: `briefs <dir|file...>` (header lines, Spec = change id, digest budget, write-scope overlap), `handoff <file> [--base <sha>] [--brief <brief.md>] [--in-flight <brief.md>...] [--lead <path>...]` (schema plus the diff guards; `--lead` excludes the lead's own paths), `budget <ledger.jsonl> <task> [--ceiling <n>]`, `ledger <change-dir>`, `recover <transcript.jsonl> <report> [--force]` and `name <dispatch-name>` (checks a dispatch name and prints the corrected form).
+- Worker rules, restated in every brief: never `git stash`, `git checkout --` or `git reset` in the shared working tree (prove RED by writing the tests first or against a temp copy), and never dispatch a subagent.
+- Before task 1: read `tasks.md` once, list the tasks, note Global Constraints; scan pairs of tasks that share a file or an interface and rule on conflicts (spec is the authority) in a `## Preflight` note of the first review package.
+</workspace>
+
+<dispatch>
+1. Brief: write `<task>.brief.md` (template). Header `Spec:` is the OpenSpec change id, never a copied spec; `Tier:` is explicit on every dispatch (fast for transcription of complete plan text or one-file mechanical edits, standard for multi-file integration, strong for design judgment; an omitted tier silently inherits the session model). Write scope names every file the worker may touch.
+2. Disjoint write scopes: run `validate-handoff.mjs briefs` over the batch; any overlap refuses the whole batch naming the file. Two implementers never run in parallel on intersecting scopes.
+3. Batch small same-shape tasks (the same one-line edit or field across files) into one brief and one dispatch; work that needs its own tests, judgment or review surface gets its own dispatch.
+4. Dispatch a fresh implementer with the brief path, the report path and the interfaces earlier tasks produced; nothing from the session history. The implementer follows `test-driven-development`; dispatch `test-writer` for the RED step when the failing tests are non-trivial. Record `Base:` (`git rev-parse HEAD`) before dispatching.
+5. At most 3 implementers in flight; a fix-round resumption counts as one. The fourth task waits for a slot; more than three needs a user ask recorded in the review package.
+6. Dispatch names follow `<role>-<task>[-r<round>][-<slug>]`: `impl-2_3`, `fix-2_3-r2`, `impl-1_3b` (a batch), `review-final-r1` (the final review) and `review-final-r1-security` (one of that round's parallel reviewers, the slug naming its lens). Write `_` for `.` because the Agent tool rejects a dot in a name; the ledger stores the dotted id and reads role, task and round through the slug. The lens slug is lowercase letters, digits and hyphens (`review-final-r1-lenses-b`); any other character leaves role and task null in the ledger. Before every dispatch, run `validate-handoff.mjs name <dispatch-name>` and use the printed corrected form.
+7. Budget: run `validate-handoff.mjs budget <ledger.jsonl> <task>` before every dispatch of a task, and again when its handoff is accepted; the brief's `Ceiling:` header overrides the default of 25,000,000 cache-read tokens for that task.
+8. Rewrite the brief's `## Why and rulings` digest before every re-dispatch (a fix round, a re-brief after `partial` or `blocked`) so it still matches the current decisions; a deviation the handoff does not cite is a reviewer P0 tagged `why-digest`.
+9. No nested subagents: a worker never dispatches helpers or reviewers; a worker-spawned reviewer is a defect, not rigor.
+</dispatch>
+
+<handoff>
+The worker returns only the JSON block (schema in `reference/handoff.md`): `task`, `status: completed|partial|blocked`, `files_changed`, `tests_run` (command, result, summary), `evidence` (one line per Verify item), `partial_output` (label of what is missing; required when partial), `blocked_reason` (stop token then detail; required when blocked), `concerns`. Stop tokens end the dispatch at the first one: `too-big`, `needs-confirm`, `ambiguous`, `regressed`, `scope`. Handle: `partial` -> re-dispatch with the label as the task; `blocked` -> fix the cause (context, tier, split, ruling) and re-dispatch; never re-run the same dispatch unchanged.
+On a missing, empty or block-less reply the first step is `validate-handoff.mjs recover <transcript.jsonl> <report>` over `~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl`, never a re-dispatch: it rebuilds the handoff from the last assistant-authored json block and writes it as the head of the review package.
+</handoff>
+
+<acceptance>
+- Worker reports are not acceptance. The lead reviews the final diff (`git diff <base>..HEAD`) and runs the Verify commands itself, then appends `## Lead evaluation` to the review package with the commands and their summary lines. A task with only the worker's claim is never marked done.
+- Guards before the reviewer: run `validate-handoff.mjs handoff <report> --base <Base> --brief <brief.md>`, adding `--in-flight <brief.md>` for every other brief still running so a peer's files are not charged to this worker, and `--lead <path>` for the lead's own paths (the change's `tasks.md`, any review package outside `.freeharness/`) so they are not charged either; a `claimed-unchanged`, `changed-unclaimed`, `scope`, `peer-scope` or `lead-path` failure returns to the worker as findings (a round), never straight to the reviewer; `peer-scope` means the worker claimed a file another dispatch owns, `lead-path` means it claimed one of the lead's own paths, neither ever worth passing on.
+- One combined task reviewer per task (spec compliance + code quality in one dispatch, tier explicit) reads the brief, the review package and the diff file; it treats the report as unverified claims. Findings follow the reviewer contract: `path:line: P0|P1|P2: problem. fix.` At most 3 reviewer dispatches per round; a fourth waits for a second round unless a user ask for more is recorded in the review package.
+- No finding suppression: never tell a reviewer what not to flag, never downgrade a finding for a stated rationale, never drop a finding silently; disagreement is a written ruling.
+- `test-driven-development` proof (failing run, then passing run) is part of the evidence; coverage numbers are not.
+</acceptance>
+
+<fix_loop>
+- A fix round = one fix dispatch + one scoped re-review of the fix diff only. Rounds 1-3 resume the same implementer with the findings verbatim; rounds 4-5 dispatch a fresh implementer one tier up with the brief, the report and the findings.
+- Circuit breaker: after round 5 with findings still open, stop dispatching. Write `## Controller ruling` to the review package for every open finding (real and load-bearing: smallest unblocking change, carried into the next brief; real and deferred, or contested: parked with the reason and the cost if wrong). Then ask the user before the next task; a structural defect that leaves every path a guess stops the run.
+- Second breaker: the budget ceiling. When `budget` reports `FAIL ceiling reached` for the task, stop dispatching it and write the same `## Controller ruling` as at round 5, one entry per open finding, each ruling carrying an id in the `R:<task>.<n>` form so the next brief's digest can cite it.
+- Every round appends `round <n>/5: <addressed>/<open>` to the review package. The lead never fixes findings itself.
+</fix_loop>
+
+<completion>
+- Per task: lead evaluation present, review clean (or rulings written at the cap), `verification-before-completion` evidence recorded, then tick `[x]` in `tasks.md`.
+- After the last task: one final branch review via `code-review` over `git merge-base` to HEAD (domain reviewers + `pr-reviewer`, strong tier), under the same cap of 3 reviewer dispatches per round unless a user ask for more is recorded in the review package; one fix dispatch for the whole findings list, one scoped re-review, rulings for residuals. Then `git-workflow` for commit and PR; `/opsx:archive` when the change is done, with its compound step (retrospective line, telemetry file, rules or skill delta, memory observation).
+- Every deferred item (a parked ruling, a reviewer finding carried forward, a machine-only measurement) is recorded with `openspec follow-up add <change-id> "<text>" --from <task>`, never as prose; archive prints the unclaimed items.
+- Final message lists every ruling made (what, why, cost if wrong) and the `validate-handoff.mjs ledger <change-dir>` summary of dispatches and cache-read spend per task: a ruling that dies in the workspace was a decision made in secret.
+</completion>
+
+<stop_conditions>
+Stop and ask the user only for: an irreversible or destructive operation; a security-sensitive action; a side effect outside the worktree (merge, push to a shared branch, publish); a task flagged "Ask first" in the proposal; the circuit breaker; a plan so broken that every path forward is a guess. Everything else is a ruling, written down, and the run continues.
+</stop_conditions>