lazycodex-ai 5.1.33 → 5.1.34

package/packages/shared-skills/skills/ulw-research/references/report-visualization.md

@@ -0,0 +1,126 @@
+# ulw-research - report visualization playbook
+
+Read this before the asset lanes start in the final-materials phase. A report the reader has to dig through as plain text has failed even when every claim is right: people understand structure from a diagram and a trend from a chart faster than from prose. Every final report therefore carries visuals, and this file says which visual fits which finding, how to make each one, and how the gates check them.
+
+## 1. The binding minimum
+
+- At least one data visualization of the report's own findings (a chart drawn from the run's data table), placed next to the claim it supports. The executive summary carries the headline visual.
+- A diagram wherever structure matters: a process, an architecture, a timeline, a dependency or influence graph, a comparison of options, the evidence flow behind a contested claim.
+- When the topic has visual or video source material (product screenshots, demo videos, talks, viral posts with media), the report embeds or links it with attribution. In a paginated format, use a captioned still frame plus the link and timestamp.
+- Every visual sits in a `<figure>` with a caption that says what it shows and where the data came from (`[S<n>]` or a lineage tag), and every `<img>` has alt text.
+- A light-tier answer (a chat or thread post) still carries one visual when it reports numbers or structure: a Mermaid block the destination renders, or a single chart image.
+
+A report that ships with none of these is incomplete. The static gate raises `report_without_visual` for it and `image_missing_alt` for an image without alt text (section 6).
+
+## 2. Which tool for which finding
+
+| Finding | Tool | Output |
+| --- | --- | --- |
+| Numbers: trends, comparisons, distributions, shares, rankings | A chart computed from a real data table | SVG with live text (PNG only for DOCX or slides) |
+| Process, pipeline, decision flow, sequence of calls | Mermaid `flowchart` or `sequenceDiagram` | SVG |
+| Timeline or history | Mermaid `timeline` or `gantt` | SVG |
+| Relationships: who builds on whom, ownership, influence, dependency | Mermaid `flowchart` or `graph`; `mindmap` for a topic tree | SVG |
+| System or product architecture | Mermaid `flowchart` with subgraphs, or `architecture-beta` where the renderer supports it | SVG |
+| Neural-network architecture in a paper-format (LaTeX) report | PlotNeuralNet | PDF for LaTeX, SVG or PNG for HTML |
+| A product, interface, or page the report discusses | A screenshot captured while reading the source, through the browser skill | PNG |
+| A concept that has no data and no structure, a cover | The image-generation skill, only when it helps the reader understand | PNG |
+| A source video or talk | An embed (web) or a still frame plus link and timestamp (paginated) | iframe or PNG |
+
+Image generation never draws data, numbers, diagrams with labels, or anything the reader could mistake for evidence. Its caption says it is an illustration.
+
+## 3. How to make each one
+
+Save every asset under `$SESSION_DIR/assets/` and confirm the file exists and is non-empty before the document references it.
+
+### Charts from data
+
+Put the numbers in a table first (`$SESSION_DIR/data/<name>.csv`), then plot from the table, never from prose. Follow the data-scientist doctrine in SKILL.md (numpy, Polars, DuckDB, no pandas).
+
+```bash
+uv run --with numpy --with polars --with matplotlib python plot_<name>.py
+```
+
+- Keep chart text as real text: set `matplotlib.rcParams["svg.fonttype"] = "none"` before saving an SVG. The default converts text to paths, and the static gate then sees a chart with no title, ticks, or labels.
+- Use the design spec's font family and palette tokens (`rcParams["font.family"]`, explicit colors from the spec). One accent color for the series that carries the finding; neutral tones for the rest.
+- Title, axis labels with units, value labels on bars or end points, ticks at round values computed from the data range.
+- One message per chart. A chart that needs a paragraph to explain is two charts.
+- For a web deliverable, HTML/CSS bars or an inline SVG built from the same table are preferred over an image.
+
+### Mermaid diagrams
+
+Write the source to `assets/<name>.mmd` and render it to SVG with the design spec's font and palette:
+
+```bash
+cat > "$SESSION_DIR/assets/mermaid-config.json" <<'EOF'
+{ "theme": "base", "htmlLabels": false, "flowchart": { "htmlLabels": false }, "themeVariables": { "fontFamily": "<spec body font>", "primaryColor": "<spec surface>", "primaryTextColor": "<spec text>", "primaryBorderColor": "<spec accent>", "lineColor": "<spec rule>", "arrowheadColor": "<spec rule>" } }
+EOF
+npx -y @mermaid-js/mermaid-cli -i "$SESSION_DIR/assets/<name>.mmd" -o "$SESSION_DIR/assets/<name>.svg" -c "$SESSION_DIR/assets/mermaid-config.json" -b transparent
+```
+
+- Keep `htmlLabels` off. With HTML labels the node text lands in `foreignObject` HTML instead of SVG `<text>`, so the static gate sees a diagram with no labels, and PDF and DOCX converters often drop it.
+- The CLI drives its own headless renderer. When it cannot start in this session, keep the `.mmd` source, deliver the diagram as a Mermaid code block only where the destination renders Mermaid (GitHub, Notion, many Markdown viewers), and record the render as not run in the closing section. The static gate counts only rendered figures, so an HTML report still needs another rendered visual.
+- Keep a diagram to about 15 nodes. Split a bigger one by subgraph or by step.
+- Lay a chain of more than about five nodes out top to bottom (`flowchart TB`). A wide left-to-right diagram scaled down to the page width shrinks its labels below legible size, worst on a phone.
+- Label every edge whose meaning is not obvious. Node text is short nouns; the caption carries the explanation.
+- Inline the rendered SVG in HTML reports (the gates read its text) or reference the file inside a `<figure>`.
+
+### PlotNeuralNet (paper-format reports)
+
+Use it when the deliverable is LaTeX or a paper-style PDF and the report describes a convolutional or encoder-decoder model whose layer shapes matter. It draws 3D layer blocks with TikZ from a short Python description. It needs a LaTeX toolchain (`pdflatex` with TikZ; on Debian or Ubuntu `texlive-latex-base`, `texlive-latex-extra`, `texlive-fonts-recommended`, `texlive-fonts-extra`; on macOS a TeX distribution) and Python 3. Source: https://github.com/HarisIqbal88/PlotNeuralNet
+
+```bash
+git clone --depth 1 https://github.com/HarisIqbal88/PlotNeuralNet "$SESSION_DIR/tools/PlotNeuralNet"
+mkdir -p "$SESSION_DIR/tools/PlotNeuralNet/report" && cd "$SESSION_DIR/tools/PlotNeuralNet/report"
+# write arch.py from the README's Python example: to_head(".."), to_cor(), to_begin(), layers, to_connection(...), to_end()
+python3 arch.py                  # writes arch.tex
+pdflatex -interaction=nonstopmode arch.tex
+pdftocairo -svg arch.pdf "$SESSION_DIR/assets/arch.svg"   # for an HTML report; LaTeX reports \input the .tex or include the PDF
+```
+
+- Run `pdflatex` directly instead of the repository's `tikzmake.sh`: that script deletes the generated `.tex` (which a LaTeX report needs to `\input`) and opens a PDF viewer. The repository has had no commits since 2020; pin the cloned commit in the closing section.
+- Layer captions carry the real shapes and channel counts from the cited paper or code, with the citation in the figure caption.
+- It does not fit transformers, graph models, or training pipelines well. Draw those with Mermaid or a hand-built TikZ figure instead.
+
+### Screenshots and video
+
+- Capture product and page screenshots through the browser skill while the source is open, at a readable width, and crop to the part the claim is about. Caption with the source and the access date.
+- Embed a video in a web report with the platform's embed and a timestamp; in a paginated report, use a still frame from the moment the claim refers to, with the link and timestamp in the caption.
+
+### Generated illustrations
+
+Use the image-generation skill only for a cover or a concept illustration that helps the reader, prompted from the design spec's palette and register. Never let generated images carry text, numbers, or logos the reader could read as fact.
+
+## 4. Choosing the output format
+
+A post by Andrej Karpathy on 2026-10-02 ranks the formats that make model output easier to understand, each better than the last: controlled clean writing, diagrams and images, interactive web pages, and custom explainer videos (https://x.com/karpathy/status/2105819303471976479). Apply it as follows:
+
+- Prose: write in the direction of ASD-STE100 (simplified technical English): short sentences, one idea per sentence, active voice, the same word for the same thing. The post suggests asking for about "80% of the way" when the full spec is too strict.
+- Before writing a long explanation of structure, draw it. A diagram usually replaces several paragraphs.
+- When the destination allows it, prefer a self-contained HTML report with interactive elements (hover values, toggles between series, expandable evidence) over a static document.
+- When the requester asks for it, or the topic is a process best seen in motion, an explainer video (for example a 3Blue1Brown-style animation, narrated with a speech API or a local text-to-speech model) is a valid extra deliverable. Record it in `outcome.json` like any other promised format.
+
+## 5. Quality bar
+
+- Every figure follows the figure standard in SKILL.md: fixed container, contain-fit, aspect ratio preserved, spec fonts and palette.
+- The caption alone tells the reader what the visual shows and what to conclude: "Median build time fell from 9.4 to 3.1 minutes after the cache change [S4]" beats "Build times".
+- Alt text states the content, not the file: the key values or the shape of the trend for a chart, the main nodes and flow for a diagram. A purely decorative image takes `alt=""` plus `role="presentation"` and does not count as a visual; an empty alt without that marker is reported as missing.
+- Every number in a visual comes from the data table and carries its source or lineage tag in the caption.
+- Colors are never the only signal: label series directly or use distinct markers, so the figure reads in grayscale.
+
+## 6. QA checklist
+
+The static gate (`report-tools check`) enforces the machine-checkable rows; visual QA checks the rest on the rendered pages.
+
+| Check | Enforced by |
+| --- | --- |
+| The report has at least one chart, diagram, or figure image | `report_without_visual` |
+| Every visual sits in a figure with a non-empty caption | `chart_without_figure` |
+| Every chart SVG has a title, ticks, and a text label | `chart_svg_no_text`, `chart_svg_missing_labels` |
+| Every `<img>` has alt text | `image_missing_alt` |
+| Every referenced asset exists and is non-empty | `broken_asset_reference` |
+| Chart and diagram colors are spec tokens | `palette_off_token` |
+| No image is stretched, cropped, or spilling its container | `layout_image_distorted`, `layout_overflow` |
+| Each major quantitative finding has a chart and each structural finding has a diagram | visual QA |
+| Diagram and chart text renders in the spec font and is legible at phone width | visual QA |
+| Source videos and screenshots are embedded or linked with attribution where the topic has them | visual QA |
+| Generated illustrations carry no fake data or text and are captioned as illustrations | visual QA |

package/packages/shared-skills/skills/ulw-research/scripts/contracts.mjs

@@ -25,6 +25,8 @@ export const DEFECT_CODES = deepFreeze({
 	chart_without_figure: { severity: "major", integrity: false, hint: "Wrap the image or chart in a figure container with a caption." },
 	chart_svg_no_text: { severity: "major", integrity: false, hint: "Give the chart a title, axis labels, units, and value labels as SVG text." },
 	chart_svg_missing_labels: { severity: "minor", integrity: false, hint: "Add the missing title, axis ticks, or unit label to the chart." },
+	report_without_visual: { severity: "major", integrity: false, hint: "Add at least one captioned visual of the findings: a chart from the data table, a rendered Mermaid diagram, or a figure image (references/report-visualization.md)." },
+	image_missing_alt: { severity: "minor", integrity: false, hint: "Give the image an alt attribute that states what it shows, not its file name; mark a purely decorative image alt=\"\" with role=\"presentation\"." },
 	korean_serif_font: { severity: "major", integrity: false, hint: "Use a gothic (sans) Korean family; serif and brush families are banned by the design spec." },
 	section_without_citation: { severity: "major", integrity: false, hint: "Cite at least one source inside this section or merge it into a cited one." },
 	missing_closing_section: { severity: "blocker", integrity: true, hint: "Add the closing section that explains how the report was made (method, sources, gates)." },
@@ -40,7 +42,7 @@ export const DEFECT_CODES = deepFreeze({
 })
 
 const LAYOUT_PREFIX = "layout_"
-/** Codes checkStatic can raise (G1-G15). */
+/** Codes checkStatic can raise (G1-G17). */
 export const STATIC_CODES = Object.freeze(
 	Object.keys(DEFECT_CODES).filter((code) => !code.startsWith(LAYOUT_PREFIX) && code !== "missing_promised_deliverable"),
 )

package/packages/shared-skills/skills/ulw-research/scripts/contracts.test.ts

@@ -33,6 +33,8 @@ const STATIC_CODES_EXPECTED = [
 	"chart_without_figure",
 	"chart_svg_no_text",
 	"chart_svg_missing_labels",
+	"report_without_visual",
+	"image_missing_alt",
 	"korean_serif_font",
 	"section_without_citation",
 	"missing_closing_section",

package/packages/shared-skills/skills/ulw-research/scripts/gates-figures.mjs

@@ -1,5 +1,5 @@
 // gates-figures.mjs - visual gates: G2 palette, G8 chart without figure, G9 chart svg text,
-// G10 Korean serif/brush fonts.
+// G10 Korean serif/brush fonts, G16 report without any visual, G17 image without alt text.
 //
 // Each gate is { codes, skip?(ctx), run(ctx) -> Defect[] } over the context built by
 // gates-static.mjs. Plain Node ESM, sibling imports only.
@@ -84,6 +84,19 @@ function missingChartLabels(raw) {
 	return missing
 }
 
+const DECORATIVE_ROLE = /^(?:presentation|none)$/i
+
+/** An image explicitly marked decorative: empty alt plus role=presentation|none or aria-hidden=true. */
+function isDecorative(node) {
+	if (node.tag !== "img" || node.attrs.alt === undefined || String(node.attrs.alt).trim()) return false
+	return DECORATIVE_ROLE.test(String(node.attrs.role ?? "").trim()) || String(node.attrs["aria-hidden"] ?? "").trim() === "true"
+}
+
+/** A rendered diagram (Mermaid marks its root with aria-roledescription) has node labels, not axes and ticks. */
+function isDiagram(node) {
+	return Boolean(node.attrs["aria-roledescription"])
+}
+
 function colorUses(ctx) {
 	const uses = new Map()
 	const add = (hex, node) => {
@@ -147,6 +160,10 @@ export const figureGates = [
 			for (const node of visuals(ctx)) {
 				if (node.tag !== "svg") continue
 				if (!((declaredSize(node) ?? 0) >= CHART_MIN || ctx.util.closest(node, isFigure(ctx)))) continue
+				if (isDiagram(node)) {
+					if (!svgTexts(node.raw ?? "").length) defects.push(ctx.defect("chart_svg_no_text", node, `${label(node)} diagram has no <text> labels (render Mermaid with htmlLabels off)`))
+					continue
+				}
 				const missing = missingChartLabels(node.raw ?? "")
 				if (missing === null) defects.push(ctx.defect("chart_svg_no_text", node, `${label(node)} chart has no <text> and no <title>`))
 				else if (missing.length) defects.push(ctx.defect("chart_svg_missing_labels", node, `${label(node)} chart is missing: ${missing.join(", ")}`))
@@ -154,6 +171,21 @@ export const figureGates = [
 			return defects
 		},
 	},
+	{
+		codes: ["report_without_visual"],
+		run(ctx) {
+			if (visuals(ctx).some((node) => declaredSize(node) !== 0 && !isDecorative(node))) return []
+			return [ctx.defect("report_without_visual", ctx.body, "the report has no chart, diagram, or figure image")]
+		},
+	},
+	{
+		codes: ["image_missing_alt"],
+		run(ctx) {
+			return visuals(ctx)
+				.filter((node) => node.tag === "img" && !String(node.attrs.alt ?? "").trim() && !isDecorative(node))
+				.map((node) => ctx.defect("image_missing_alt", node, `${label(node)} has no alt text`))
+		},
+	},
 	{
 		codes: ["korean_serif_font"],
 		run(ctx) {

package/packages/shared-skills/skills/ulw-research/scripts/gates-static.mjs

@@ -1,4 +1,4 @@
-// gates-static.mjs - deterministic static gates (G1-G15) over a parsed report.
+// gates-static.mjs - deterministic static gates (G1-G17) over a parsed report.
 //
 // Builds one document context (a document-order walk with h2 sections, citation helpers and a
 // defect factory) and hands it to the text, figure and structure gate modules. Every severity
@@ -144,7 +144,7 @@ function buildContext(doc, options) {
 }
 
 /**
- * Run G1-G15 over a parsed report (html-lite root).
+ * Run G1-G17 over a parsed report (html-lite root).
  * @param {object} doc parseHtml(...) result
  * @param {{ palette?: Set<string>, lineageMode?: "inline"|"section", requireSections?: (RegExp|string)[],
  *   baseDir?: string, fs?: { statSync(path: string): { size: number } }, closingPattern?: RegExp|string }} options

package/packages/shared-skills/skills/ulw-research/scripts/gates-static.test.ts

@@ -42,14 +42,14 @@ describe("checkStatic fixtures", () => {
 		expect([...result.gatesRun].sort()).toEqual([...STATIC_CODES].sort())
 	})
 
-	test("#given the failing fixture report #when every gate runs #then each static code is raised exactly once", () => {
+	test("#given the failing fixture report #when every gate runs #then each static code except the no-visual one is raised exactly once", () => {
 		// given
 		const options = { requireSections: [/risks/i] }
 		// when
 		const result = run(BAD, options)
 		// then
-		expect([...codes(result)].sort()).toEqual([...STATIC_CODES].sort())
-		expect(STATIC_CODES).toHaveLength(17)
+		expect([...codes(result)].sort()).toEqual(STATIC_CODES.filter((code) => code !== "report_without_visual").sort())
+		expect(STATIC_CODES).toHaveLength(19)
 		expect(codes(result)).not.toContain("missing_promised_deliverable")
 	})
 
@@ -228,6 +228,59 @@ describe("figures and charts", () => {
 	})
 })
 
+describe("report-level visuals", () => {
+	const figures = /<figure\b[\s\S]*?<\/figure>/g
+
+	test("#given the passing fixture with every figure removed #when checked #then only report_without_visual is raised", () => {
+		// given
+		const html = GOOD.replace(figures, "")
+		// when
+		const result = run(html, { requireSections: [/sources/i, /review/i] })
+		// then
+		expect(codes(result)).toEqual(["report_without_visual"])
+		expect(result.defects[0]?.severity).toBe("major")
+	})
+
+	test("#given a header logo, an unrendered Mermaid source block, a zero-size svg, then a rendered diagram #when checked #then only the rendered diagram counts as a visual", () => {
+		// given
+		const logo = '<header><img src="data:image/png;base64,iVBORw0KGgo=" alt="logo" width="120" height="40"></header><p>x</p>'
+		const unrendered = `${logo}<pre class="mermaid">flowchart LR\n  A --> B</pre><figure><svg width="0" height="0"><text>A</text></svg><figcaption>c</figcaption></figure>`
+		const rendered = `${logo}<figure><svg width="600" height="300" aria-roledescription="flowchart-v2"><text>A</text><text>B</text></svg><figcaption>c</figcaption></figure>`
+		// when / then
+		expect(has(unrendered, "report_without_visual")).toBe(true)
+		expect(has(rendered, "report_without_visual")).toBe(false)
+	})
+
+	test("#given rendered Mermaid diagrams with SVG text labels and with HTML-only labels #when checked #then only the HTML-only one is flagged and neither needs chart ticks", () => {
+		// given
+		const diagram = (labels: string) => `<figure><svg width="600" height="300" aria-roledescription="flowchart-v2">${labels}</svg><figcaption>Gate order</figcaption></figure>`
+		const textLabels = diagram("<text>static check</text><text>repair decide</text>")
+		const htmlLabels = diagram("<foreignObject><div>static check</div></foreignObject>")
+		// when
+		const chartCodes = (html: string) => codes(run(html)).filter((code) => code.startsWith("chart_"))
+		// then
+		expect(chartCodes(textLabels)).toEqual([])
+		expect(chartCodes(htmlLabels)).toEqual(["chart_svg_no_text"])
+	})
+
+	test("#given figure images with no alt, a bare empty alt, role- and aria-marked decorative alts and a descriptive alt #when checked #then only the unmarked two raise image_missing_alt", () => {
+		// given
+		const img = (alt: string) => `<figure><img src="data:image/png;base64,iVBORw0KGgo=" ${alt} width="480" height="240"><figcaption>c</figcaption></figure>`
+		const html = ["", 'alt=""', 'alt="" role="presentation"', 'alt="" aria-hidden="true"', 'alt="Deploys per week, 2025"'].map(img).join("")
+		// when
+		const found = run(html).defects.filter((d) => d.code === "image_missing_alt")
+		// then
+		expect(found).toHaveLength(2)
+	})
+
+	test("#given a report whose only image is marked decorative #when checked #then report_without_visual is raised", () => {
+		// given
+		const html = '<figure><img src="data:image/png;base64,iVBORw0KGgo=" alt="" role="presentation" width="480" height="240"><figcaption>c</figcaption></figure>'
+		// when / then
+		expect(has(html, "report_without_visual")).toBe(true)
+	})
+})
+
 describe("gate bookkeeping", () => {
 	test("#given a spec with an empty palette #when checked #then palette_off_token is skipped, not run", () => {
 		// given

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/bad-report.html

@@ -34,6 +34,10 @@ body { background: var(--bg); color: var(--fg); font-family: "Nanum Myeongjo", s
 <img src="assets/missing-figure.png" alt="lost asset" width="480" height="240">
 <figcaption>Lost asset [S1]</figcaption>
 </figure>
+<figure>
+<img src="data:image/png;base64,iVBORw0KGgo=" width="480" height="240">
+<figcaption>Image without alt text [S1]</figcaption>
+</figure>
 </section>
 <section>
 <h2>팀 구성은 그대로였다</h2>