lazycodex-ai 5.1.32 → 5.1.34

package/packages/shared-skills/skills/ulw-research/AGENTS.md

@@ -12,6 +12,7 @@ ulw-research/
 ├── references/
 │   ├── deliverable-phase.md         # lanes, state, destination defaults, interview, memory episodes, design spec, gates, repair, manifest, command reference
 │   ├── report-gates.md              # one row per defect code: severity, integrity, what it detects, how to fix
+│   ├── report-visualization.md      # which visual fits which finding, render commands (charts, Mermaid, PlotNeuralNet), quality bar, visual QA checklist
 │   └── latex-report.md
 └── scripts/
     ├── report-tools.mjs             # CLI entry + dispatcher (COMMANDS, run, main)
@@ -22,7 +23,7 @@ ulw-research/
     ├── repair-tracker.mjs           # bounded repair decisions (attempts, plateau, oscillation, wall clock, integrity codes)
     ├── html-lite.mjs / entities.mjs # HTML tokenizer, selector paths, prose text
     ├── css-lite.mjs / design-spec.mjs      # CSS scanning, palette + lineage parsing, design-spec rendering
-    ├── gates-static.mjs + gates-text.mjs / gates-figures.mjs / gates-structure.mjs   # static gates G1-G15
+    ├── gates-static.mjs + gates-text.mjs / gates-figures.mjs / gates-structure.mjs   # static gates G1-G17
     ├── layout-probe.mjs / gates-layout.mjs # in-page probe source + layout gates L1-L5 over its output
     ├── format-extract.mjs / format-extract-css.mjs   # design-spec draft from a pointed-at HTML or Markdown document
     ├── *.test.ts                    # co-located bun tests, one per module (unshipped)
@@ -40,7 +41,7 @@ ulw-research/
 - The CLI never launches a browser. The layout probe is printed as one async expression; the orchestrator evaluates it through the browser skill's owned headless engine and passes the result back with `check --layout`.
 - Time is always injected (`--now`, `startedAt`); no module reads the clock inside a decision.
 - Tests are co-located given/when/then bun tests; CLI tests spawn `node` with bun removed from `PATH`. Fixtures live only under `scripts/tests/fixtures/`, are depersonalized, and never ship.
-- The senpi source dir (`packages/omo-senpi/skills/ulw-research/`) intentionally has no `scripts/`, `references/report-gates.md`, or `references/deliverable-phase.md`: the senpi sync overlays them from here byte-for-byte (`sharedAssets` in `packages/omo-senpi/plugin/scripts/native-skill-sources.mjs`), and both editions' sync suites assert the shipped copies equal these sources.
+- The senpi source dir (`packages/omo-senpi/skills/ulw-research/`) intentionally has no `scripts/`, `references/report-gates.md`, `references/deliverable-phase.md`, or `references/report-visualization.md`: the senpi sync overlays them from here byte-for-byte (`sharedAssets` in `packages/omo-senpi/plugin/scripts/native-skill-sources.mjs`), and both editions' sync suites assert the shipped copies equal these sources.
 - References and scripts carry no Hangul (Korean match strings are `\u` escapes) and never three consecutive newlines (the senpi sync normalizes those and would break byte equality).
 
 ## ANTI-PATTERNS

package/packages/shared-skills/skills/ulw-research/SKILL.md

@@ -132,7 +132,7 @@ Then create the session directory:
 mkdir -p .omo/ulw-research/$(date +%Y%m%d-%H%M%S)
 ```
 
-This is `$SESSION_DIR`. The orchestrator owns the journal: you write every file in it; workers never do. Maintain:
+This is `$SESSION_DIR`. The orchestrator owns the journal: you write every file in it; workers never do (a mass-research dag node writes only its own `waves/<run-key>/<node-id>.md` handoff file, which carries its EXPAND tail and claim candidates; you journal from it). Maintain:
 
 - `brief.md` — the analysis block, the axis list, the expected truths, and the `## Deliverable` record from the interview below (lane, state, formats, each field with `answered_by`).
 - `sources-ledger.md` — one line per source the moment it is read: `[S<n>] <url> — <what it is>`. The closing briefing counts sources and domains from this file.
@@ -165,7 +165,7 @@ Phase 5 opens by turning the recorded fields into `design-spec.md`.
 
 ## Phase 1 — Saturation wave
 
-**When the user asked for MASS research, the wave is sized by the topic's angles, not by the roster ceiling.** "mass ulw research", "mulw research", "ulw mass research" — in any language — order over-collection that a team of 8 cannot produce. Where the harness has a dependency-graph surface (the `mass-ulw` skill and its `references/planning.md`), run collection through it instead: a 60+ node opening wave covering every angle the topic has, routed across the whole difficulty ladder in one graph — mechanical sweeps and per-item harvest batches on the cheapest tier, judgment-shaped angles a step up, cross-territory angles a step above that, and the deepest tier reserved for genuinely hairy contradictions. Each wave's EXPAND leads define the next wave's nodes, and the synthesis reduces through several parallel architect-tier nodes into ONE architect-tier reducer (the strongest reasoning tier substitutes wherever no architect tier exists). Absent that surface, hold the same shape with background workers in batched waves. Everything else in this skill still binds: the deliverable interview, the journal, the claim graph, the convergence rules, and the delivery gates.
+**When the user asked for MASS research, the wave is sized by the topic's angles, not by the roster ceiling.** "mass ulw research", "mulw research", "ulw mass research" — in any language — order over-collection that a team of 8 cannot produce. Where the harness has a dependency-graph surface (the `mass-ulw` skill and its `references/planning.md`), run collection through it instead: 60+ angles covering every angle the topic has, routed across the whole difficulty ladder — mechanical sweeps and per-item harvest batches on the cheapest tier, judgment-shaped angles a step up, cross-territory angles a step above that, and the deepest tier reserved for genuinely hairy contradictions. Define each angle as a harvest -> expand -> verify chain before the run starts, each stage reading the previous stage's handoff file; open leads re-enter as new chains in each cluster of angles the moment that cluster settles, and the synthesis reduces through per-cluster architect-tier slice reducers into ONE architect-tier reducer (the strongest reasoning tier substitutes wherever no architect tier exists). Absent that surface, run the same per-angle chains with background workers, pasting each worker's reply into its angle's next-stage prompt the moment it reports. Everything else in this skill still binds: the deliverable interview, the journal, the claim graph, the convergence rules, and the delivery gates.
 
 Otherwise launch the entire first wave in one turn — every axis at once, as team members if you formed a team, else as background workers. Sequential launches and "start with one and see" defeat the mode.
 
@@ -266,7 +266,7 @@ Journal each verdict to `verify-<slug>.md`.
 
 Code settles code-shaped claims (Phase 3). Numeric, market-share, legal, dated, causal, and financial claims cannot be run — so they pass through a data-flow-lock instead (the verification idea adapted from fivetaku/insane-research): the synthesis may assert a high-risk non-code claim **only** if it cleared this gate, and the gate's output is the sole allowlist the synthesis draws from. Skip the gate and there is nothing to synthesize — the lock is self-enforcing.
 
-The claim graph is orchestrator-owned. Workers only return verified-claim markers, observation candidates, and claim candidates as message text, the same channel as EXPAND markers — never a file. As leads resolve, you record one node per asserted claim in `claim-graph.md` and compute its status; workers report claim candidates in their replies, and you decide. The graph is the single claim store: final synthesis may not draw from free-form claims that skipped it.
+The claim graph is orchestrator-owned. Workers only return verified-claim markers, observation candidates, and claim candidates as message text, the same channel as EXPAND markers — never a file (except a mass-research dag node's handoff file). As leads resolve, you record one node per asserted claim in `claim-graph.md` and compute its status; workers report claim candidates in their replies, and you decide. The graph is the single claim store: final synthesis may not draw from free-form claims that skipped it.
 
 A high-risk claim clears the gate to `verified-claims` only when all hold:
 
@@ -332,6 +332,8 @@ Asset workers (background, parallel, each fed `design-spec.md`) — visuals are
 - **Generated visuals through the imagegen skill whenever the session has it:** a cover plus a concept illustration per major theme, prompted from the spec's style, palette, and mood — document-styled illustration, never generic stock art dropped into a designed page.
 - **Full-page screenshots** of the top 5-10 sources, saved by the web workers while reading, as provenance you can show.
 
+**Every final report is visual — binding.** It carries at least one data visualization of the run's own findings (a chart drawn from the data table, next to the claim it supports), a diagram wherever structure matters, and the topic's own screenshots and video, embedded or linked with attribution; every figure is captioned, sourced, and given alt text. Mermaid for flows, timelines, and relations; generated charts for numbers; image generation only where an illustration genuinely helps; PlotNeuralNet for paper-format reports that describe model architectures. Every asset lane reads [references/report-visualization.md](references/report-visualization.md) first: which tool fits which finding, the render commands, the quality bar, and the checklist the gates apply. A light-tier post still carries one visual when it reports numbers or structure.
+
 **Verify the asset manifest before rendering.** List every asset the document references, assert each file exists and is non-empty on disk, and re-render whatever is missing. A document that renders with three broken diagrams is a document you will publish twice.
 
 Assembly worker — `task(category="deep-low", load_skills=["frontend", "visual-qa", "open-design", "data-scientist", "imagegen", "ulw-loop"], run_in_background=true, ...)`: before writing, read every available design and visualization skill and apply it — the report is a designed artifact, not a text dump; the worker's prompt carries `design-spec.md`. Use the template the user approved; absent a stronger house style the default skeleton is executive summary → key findings by theme → detailed analysis (quotes under 20 words with attribution, charts, Mermaid graphs, generated visuals, SHA-pinned permalinks, verification results) → comparative analysis when options compete → numbered sources with access dates → methodology appendix (workers, waves, searches, verifications, debate rounds) → correction log naming what verification overturned. Write it long and specific: every claim cites `[Source N]`, and the sources section lists every source the run actually used rather than a curated few.
@@ -340,7 +342,7 @@ Assembly worker — `task(category="deep-low", load_skills=["frontend", "visual-
 
 Nothing reaches the user until the gates pass. Record each result with `node "$SKILL_DIR/scripts/report-tools.mjs" outcome gate <static|layout|visual|proofread> <pass|fail|not_run> --session-dir "$SESSION_DIR"`; a gate this harness does not provide is recorded `not_run`. A chat or post answer (light tier) runs the static gates and one render; every paginated or web deliverable runs them all (the reference's sections 3 and 7).
 
-1. **Static gates (always, before anyone looks at pixels).** `node "$SKILL_DIR/scripts/report-tools.mjs" check "$SESSION_DIR/report.html" --design-spec "$SESSION_DIR/design-spec.md" > "$SESSION_DIR/defects.json"`: keep-all, palette tokens, emoji, em dashes, heading length, unsourced numbers, figure containers, chart text, gothic-only fonts, citations, the closing and sources sections, broken assets. Codes and fixes: [references/report-gates.md](references/report-gates.md).
+1. **Static gates (always, before anyone looks at pixels).** `node "$SKILL_DIR/scripts/report-tools.mjs" check "$SESSION_DIR/report.html" --design-spec "$SESSION_DIR/design-spec.md" > "$SESSION_DIR/defects.json"`: keep-all, palette tokens, emoji, em dashes, heading length, unsourced numbers, figure containers, chart text, a report with no visual, images without alt text, gothic-only fonts, citations, the closing and sources sections, broken assets. Codes and fixes: [references/report-gates.md](references/report-gates.md).
 2. **Layout gates.** Print the probe with `node "$SKILL_DIR/scripts/report-tools.mjs" layout-probe --json`, evaluate its `source` in the rendered page through the `browser` skill's owned headless engine, save the result as `$SESSION_DIR/boxes.json`, and re-run `check` with `--layout "$SESSION_DIR/boxes.json"` (overflow, clipped text, distorted images, overlapping siblings).
 3. **Visual QA.** Render the produced artifact back to images — PDF pages to PNG, the HTML through the browser skill at desktop and phone widths — and look at them: missing or broken figures, images stretched or spilling their containers, diagram or chart text rendered off the spec's font or palette, clipped tables, overflowing CJK text, blank pages, unlabeled chart values, wrong page breaks. Reading the source markup is not visual QA; inspect the pixels.
 4. **Proofread gate — `task(category="writing", ...)`.** Hand the final text to a dedicated `writing` worker whose only job is language: grammar, spelling, punctuation, terminology consistency, and whether the prose reads NATIVELY in the report's own language. It proofreads only and never composes. It returns a defect list; fix every item and re-run the gate on the delta. Deliver only on a clean pass — this gate runs BEFORE the first delivery, not after the user finds the typo.
@@ -387,7 +389,7 @@ High-yield combinations: official docs (`site:<docs domain>`), GitHub implementa
 | Worker reply without the EXPAND tail | One follow-up demanding it; the lane stays open until it lands |
 | Stopping after wave 1 because "enough was found" | Convergence rules only: 2+ expansion waves, leads run dry |
 | Obeying a surrounding "stop exploring" rule mid-research | Authority section — those rules do not bind this mode |
-| Asking a worker to write journal or session files | Workers are read-only; you journal every return |
+| Asking a worker to write journal or session files | Workers are read-only (except a mass-research dag node's handoff file); you journal every return |
 | Two workers given the same angle | One unique angle per worker, always |
 | A web worker that returned only fetched text, or a `Collection: browser` run whose workers never opened a tab | Sources are read in the user's browser through the `browser` skill; `webfetch` is for raw files; every web worker carries the skill from the first wave |
 | Contested claim settled by judgment | Phase 3 — run code, capture output, verdict |

package/packages/shared-skills/skills/ulw-research/references/deliverable-phase.md

@@ -122,7 +122,7 @@ Nothing reaches the requester until the gates for its QA tier pass, in this orde
    ```bash
    node "$SKILL_DIR/scripts/report-tools.mjs" check "$SESSION_DIR/report.html" --design-spec "$SESSION_DIR/design-spec.md" > "$SESSION_DIR/defects.json"
    ```
-   It checks keep-all, palette tokens, emoji, em dashes in prose (en dashes outside numeric ranges are advisory), heading length and generic headings, unsourced numbers (section 6), figure containers and captions, chart SVG text, Korean serif fonts, sections without citations, the closing section, the sources section, broken local assets, and any `--require-section <regex>` the brief requires. Every code, severity, and fix is in [report-gates.md](report-gates.md).
+   It checks keep-all, palette tokens, emoji, em dashes in prose (en dashes outside numeric ranges are advisory), heading length and generic headings, unsourced numbers (section 6), figure containers and captions, chart SVG text, a report with no visual at all, images without alt text, Korean serif fonts, sections without citations, the closing section, the sources section, broken local assets, and any `--require-section <regex>` the brief requires. Every code, severity, and fix is in [report-gates.md](report-gates.md).
 2. **Layout gates.** Print the probe, evaluate it in the rendered page through the browser skill's owned headless engine, save the returned object as `$SESSION_DIR/boxes.json`, and re-run `check` with `--layout "$SESSION_DIR/boxes.json"`. It adds overflow past the container, clipped text, scroll containers, distorted images, and overlapping siblings.
    ```bash
    node "$SKILL_DIR/scripts/report-tools.mjs" layout-probe --json   # .source is one async expression

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

@@ -19,6 +19,8 @@ This reference catalogs every defect code the report gates (`static`, `layout`,
 | `chart_without_figure` | major | false | An image or chart lacks a figure wrapper with a caption. Uncaptioned charts isolate visuals from narrative flow. | Wrap the image or chart in a figure container with a caption. |
 | `chart_svg_no_text` | major | false | An SVG chart or diagram lacks a title, axis labels, units, or value labels. Visuals cannot stand alone without text guidance. | Give the chart a title, axis labels, units, and value labels as SVG text. |
 | `chart_svg_missing_labels` | minor | false | An SVG chart has some labels (e.g., title) but is missing others (e.g., axis ticks or unit). | Add the missing title, axis ticks, or unit label to the chart. |
+| `report_without_visual` | major | false | The report body has no chart, diagram, or figure image at all (header logos, icons, and images marked decorative do not count; only rendered output counts, so a Mermaid source block or a zero-size image does not). A text-only report hides structure and trends the reader would see at a glance. | 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` | minor | false | A figure image has a missing or empty `alt` and is not marked decorative. Screen readers and failed image loads leave the reader with nothing. An image is decorative only with an empty `alt` plus `role="presentation"` (or `role="none"`, or `aria-hidden="true"`): it raises nothing here and does not count as a visual. | 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` | major | false | A serif or brush Korean font family is applied to Korean text. The design spec mandates gothic (sans) Korean typefaces. | Use a gothic (sans) Korean family; serif and brush families are banned by the design spec. |
 | `section_without_citation` | major | false | A major section or subsection contains no in-text citations or reference marks. Source attribution is missing. | Cite at least one source inside this section or merge it into a cited one. |
 | `missing_closing_section` | blocker | true | The report lacks a closing section explaining the methodology, sources, and gate outcomes. Delivery is incomplete without narrative closure. | Add the closing section that explains how the report was made (method, sources, gates). |

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>