dsh-aris-panel 0.1.0

package/skills/paper-poster-html/IMPLEMENTATION_CONVENTIONS.md

@@ -0,0 +1,161 @@
+# paper-poster-html 实现约定(所有实现 agent 必读)
+
+配合 DESIGN_FINAL.md(规格)使用。本文档定死跨文件契约——实现时**逐字遵守**,
+有疑问按本文档,不要自由发挥。
+
+## A. CSS Token 契约(templates + tokens/*.json + style_check 三方共享)
+
+`:root` 中的 token block 必须被注释 `/* ===== DESIGN TOKENS ===== */` 和
+`/* ===== END DESIGN TOKENS ===== */` 包围(style_check 靠这对注释定位 token block)。
+
+颜色 token(只有这些地方允许出现颜色字面量):
+```css
+--accent: #2D5F8B;  --accent-deep: #1F4566;  --accent-light: #E8F1F8;  --accent-soft: #D7E5F0;
+--gold: #C9A24A;    --gold-soft: #FFF7E0;
+--text-primary: #1A1A1A;  --text-secondary: #555555;  --text-muted: #888888;
+--bg-page: #F6F2F0;  --bg-card: #FFFFFF;  --bg-card-tint: #FAFAFB;  --bg-emphasis: var(--accent-light);
+--border-soft: #D8D8D8;  --border-strong: var(--accent);
+```
+
+字号 scale(9 档,模板内所有 font-size 必须引用之一;`calc(var(--fs-N) * k)` 仅许
+COMPONENTS.md 预定义 variant 使用):
+```css
+--fs-1: calc(9 * var(--u));   /* 微标签 */      --fs-2: calc(10 * var(--u));  /* 小 caption */
+--fs-3: calc(11 * var(--u));  /* caption/表格 */ --fs-4: calc(12 * var(--u));  /* 正文 */
+--fs-5: calc(13 * var(--u));  /* 公式/强调 */    --fs-6: calc(15 * var(--u));  /* 副标题 */
+--fs-7: calc(16 * var(--u));  /* 节标题 */       --fs-8: calc(22 * var(--u));  /* banner 数字 */
+--fs-9: calc(32 * var(--u));  /* 主标题 */
+```
+
+单位:`--u: 1.6px`(screen)/ `@media print { :root { --u: 1mm } }`。其余尺寸一律
+`calc(N * var(--u))`,hairline 可用裸 px(≤2px)。
+
+## B. HTML 属性契约
+
+| 属性 | 用途 | 谁检查 |
+|------|------|--------|
+| `data-measure-role="poster|header|banner|body|column|card|hero|footer-strip|footer"` | vendored measure 的定位锚(原契约,勿改) | poster_check measure |
+| `data-source="paper"` + `data-asset-id="<manifest id>"` | 标记来自论文的图 | asset_check + style_check 豁免 |
+| `data-color-exempt="logo"` | logo/印章 SVG 的调色豁免 | style_check |
+| `data-fig-layout="beside-text"` | 图文并排的 AR 门 opt-out(vendored) | poster_check polish |
+
+**模板和最终 poster 中禁止任何 `style=` 属性**(零容忍,style_check 规则 2 实现成这样,
+简单可靠)。例外:`data-color-exempt="logo"` 元素的内部 SVG 标记、`data-source="paper"`
+的 `<img>` 上仅允许 `style="width: NN%"`(AR 调宽)。
+为此模板必须自带 utility classes(替代 posterly 模板里的 inline style):
+```css
+.fs-1 … .fs-9        /* font-size: var(--fs-N) */
+.mt-1 … .mt-6        /* margin-top: calc(N * var(--u)) */
+.mb-1 … .mb-4        /* margin-bottom */
+.w-45 .w-50 … .w-100 /* 图宽 45%…100%,步长 5 */
+.text-secondary .text-muted .nowrap .text-center
+```
+
+## C. CLI 契约(scripts/)
+
+全部 Python 3.10+,只用 stdlib + 已确认可用的 PyMuPDF(fitz)/PIL/playwright(lazy import,
+缺失时给可读错误+降级指引)。每个脚本 `--help` 完整。exit code:0=pass,1=hard fail,2=用法/环境错误。
+
+### style_check.py
+```
+python3 style_check.py POSTER.html [--tokens TOKENS.json] [--json OUT.json]
+                       [--no-render]  # 跳过渲染门(规则4、12 标 SKIPPED)
+```
+实现 DESIGN_FINAL §3 的 12 条规则 + §12.5 nit 1。源门(规则 1-3,5-11)纯静态解析
+(html.parser + 正则提 CSS);渲染门(规则 4、12)用 playwright 取 computed style。
+色相聚类:rgba→HSL;非中性= alpha≥0.10 且 S≥0.18;greedy 聚类半径 18°(色环距离);
+聚类数 ≤2 且每类中心落在 tokens 的 accent/gold hue ±22°(hue_centers 来自 --tokens JSON,
+缺省从 :root 解析 --accent/--gold 算)。
+JSON 输出:`{"gate":"style","status":"PASS|FAIL|WARN","rules":[{"id":1,"severity":"hard","status":"PASS","detail":"..."}]}`
+
+### asset_check.py
+```
+python3 asset_check.py POSTER.html --manifest FIGURE_MANIFEST.json [--json OUT.json]
+                       [--min-paper-figs 2] [--min-fig-area 0.015] [--min-total-area 0.12]
+                       [--waive-total-area]   # 纯理论论文 waiver(DESIGN_FINAL §12.5 nit 2)
+                       [--no-render]          # 面积检查降级为 natural-size 估算
+```
+检查:≥N 张 data-source="paper" 且 manifest 里 from_paper=true;每张渲染面积 ≥ poster 1.5%;
+总面积 ≥ body 12%(可 waive);natural_px ≥ rendered px 1.5×(WARN 在 <2×);
+manifest 必填字段齐全(见 D);文件存在且 sha256 匹配。
+
+### run_gates.py
+```
+python3 run_gates.py POSTER.html [--report GATE_REPORT.json] [--fail-fast]
+                     [--strict-polish] [--tokens TOKENS.json] [--manifest FIGURE_MANIFEST.json]
+                     [--waive-total-area] [--no-render]
+```
+canonical order:preflight → style → asset → measure → polish。默认 accumulate。
+子门以 subprocess 调同目录脚本(sys.executable;poster_check.py 子命令用其 CLI)。
+GATE_REPORT.json 严格按 DESIGN_FINAL §7 schema(canvas 信息从 POSTER_STATE.json 读,
+读不到则从 @page 解析,source 标 "page-rule")。汇总 overall=PASS/FAIL + hard_failures + warnings。
+
+### extract_pdf_figures.py
+```
+python3 extract_pdf_figures.py PAPER.pdf --out DIR [--dpi 350]
+        contact-sheet                      # 整页缩略 contact sheet + 自动候选框
+        crop --page P --bbox x0,y0,x1,y1 --name ID [--caption-hint "..."]
+        auto                               # 自动检测大图块候选(图/表),输出候选列表
+```
+bbox 单位 = PDF points(72dpi 坐标,fitz 默认)。crop 模式渲染该区域至 --dpi,写 PNG 到
+DIR,并 upsert FIGURE_MANIFEST.json(同目录上级)。contact-sheet 写 DIR/contact_sheet_pNN.png。
+
+### preprocess_figures.py
+```
+python3 preprocess_figures.py IMG... [--autocrop] [--pad 6] [--min-px 1200 700] [--manifest M.json]
+```
+PIL autocrop 白边(ImageChops.difference vs 白底,留 --pad px),报告 natural size,
+低于 --min-px 给 WARN;改动后同步更新 manifest 的 natural_px/sha256。
+
+## D. FIGURE_MANIFEST.json schema
+
+```json
+{
+  "schema_version": 1,
+  "source_pdf": {"path": "…", "sha256": "…"},
+  "figures": [
+    {"asset_id": "fig_method", "file": "assets/paper_figures/fig_method.png",
+     "from_paper": true, "page": 3, "bbox": [72.0, 100.0, 520.0, 380.0], "dpi": 350,
+     "sha256": "…", "natural_px": [2178, 1362], "caption_hint": "Figure 2: …"}
+  ]
+}
+```
+
+## E. 模板改造配方(posterly → ARIS fork)
+
+对 3 个模板各做(以上游 posterly 仓库的 templates/*.html 为底):
+1. 文件头注释:保留原说明,追加 "Adapted from posterly (MIT, © 2026 Ruishuo Chen) — see LICENSES/ & NOTICE.md; ARIS modifications: flat de-gradient, --fs token scale, zero-inline-style utilities, data-source/data-color-exempt contracts."
+2. **去渐变**:`.poster::before` 顶条 → 纯色 `var(--accent)`;`.framework-banner`、
+   `.takeaways-strip` 背景 → 纯 `var(--bg-emphasis)`;`.callout.gold` → 纯 `var(--gold)`。
+   `.poster` 的 radial tint(alpha≤0.06)保留。
+3. **token block**:按 §A 注释包围;加 --fs-1..9;所有 font-size 改 var(--fs-N)。
+4. **消灭 inline style**:模板正文里所有 `style="…"` 换成 §B utility classes(在 CSS 段新增)。
+5. **图组件**:`.figure img` 的 TODO 注释里写明契约:`<img src="assets/paper_figures/x.png" data-source="paper" data-asset-id="x" class="w-95">`。
+6. logo 槽注释写明 `data-color-exempt="logo"`。
+7. `data-measure-role` 一律保留。
+8. @page 默认值保留(60×36in / 24×36in),在头注释加"画布重定位:同步改 @page 与 .poster 的
+   width/height(各一处),ICLR 2026 main = 185cm 90cm landscape 示例"。
+9. eqn 组件加 variant `.eqn--large`(font-size: calc(var(--fs-5) * 1.25),预定义 calc 豁免)。
+10. 自检:改完后模板里 grep 不到 `linear-gradient`、`style="`(除 §B 两个例外注释示例)、
+    裸 `#hex`(token block 与 logo SVG 例外)。
+
+## F. tokens/*.json schema
+
+```json
+{"name": "generic",
+ "accent": {"base": "#2D5F8B", "deep": "#1F4566", "light": "#E8F1F8", "soft": "#D7E5F0"},
+ "gold": {"base": "#C9A24A", "soft": "#FFF7E0"},
+ "neutrals": {"text_primary": "#1A1A1A", "text_secondary": "#555555", "text_muted": "#888888",
+              "bg_page": "#F6F2F0", "bg_card": "#FFFFFF", "bg_card_tint": "#FAFAFB",
+              "border_soft": "#D8D8D8"},
+ "hue_centers": {"accent": 210, "gold": 43}}
+```
+venue 包约束:accent S≤0.55、L∈[0.25,0.45]、禁 H 250–285;gold 全包固定 generic 值;
+light/soft 从 base 推(同 hue 低饱和高亮度)。bg_page 可随 accent 微调暖/冷但 ΔE 要小。
+
+## G. 测试基线
+
+上游 posterly 仓库的 examples/hello_world/poster.html 是全门 PASS 的参照(vendored 四门)。
+新脚本写完后:style_check 对 hello_world 允许 FAIL(它有 inline style——posterly 原版风格),
+但对我们改造后的模板(填充前)源门必须 PASS;run_gates 对脚手架预期 measure FAIL(未填充),
+这是正常的(模板=脚手架)。

package/skills/paper-poster-html/LICENSES/posterly-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruishuo Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/paper-poster-html/NOTICE.md

@@ -0,0 +1,57 @@
+# NOTICE — third-party provenance
+
+`paper-poster-html` vendors part of **posterly** and adds ARIS-specific components on top.
+This file records the vendor boundary so upstream sync stays clean and attribution is preserved.
+
+## Vendored from posterly (MIT)
+
+- **Upstream**: posterly — https://github.com/Chenruishuo/posterly
+- **License**: MIT, © 2026 Ruishuo Chen. Full text: `LICENSES/posterly-MIT.txt`.
+- **Why vendored** (DESIGN_FINAL §0): the posterly tools are copied into this skill, not pulled
+  as an external dependency and not rewritten — so the skill is self-contained and the original
+  measurement/render logic is preserved unchanged.
+
+Vendored, **unmodified** components (the vendor boundary — keep diffs minimal across syncs):
+
+| Path | Origin in posterly |
+|------|--------------------|
+| `scripts/poster_check.py` | `tools/poster_check.py` (measure / preflight / polish / verify-final) |
+| `scripts/render_preview.py` | `tools/render_preview.py` (Playwright print render) |
+| `scripts/_posterly/` | `tools/_posterly/` internal modules (measure, render, polish, preflight, canvas, verify_final, textutil) |
+
+Vendored and **adapted** (templates):
+
+| Path | Origin | ARIS modifications |
+|------|--------|--------------------|
+| `templates/landscape_4col.html` | `templates/landscape_4col_neutral.html` | flat de-gradient, `--fs-*` token scale, zero-inline-style utility classes, `data-source`/`data-color-exempt` contracts |
+| `templates/landscape_hero.html` | `templates/landscape_hero_neutral.html` | (same modifications) |
+| `templates/portrait_2col.html` | `templates/portrait_2col_neutral.html` | (same modifications) |
+
+The component **class names** are inherited verbatim from posterly; the catalog in
+`templates/COMPONENTS.md` therefore describes both the originals and the ARIS forks.
+
+## ARIS-side additions (not from posterly)
+
+These are original ARIS work, layered on top of the vendored base:
+
+- `scripts/style_check.py` — style hard-gate, 12 rules (DESIGN_FINAL §3 / §12.5 nit 1).
+- `scripts/asset_check.py` — real-figure provenance gate (DESIGN_FINAL §4).
+- `scripts/run_gates.py` — runs all gates in canonical order, writes `GATE_REPORT.json`
+  (DESIGN_FINAL §7).
+- `scripts/extract_pdf_figures.py` — PDF → contact sheet → candidate crops (DESIGN_FINAL §4).
+- `scripts/preprocess_figures.py` — autocrop / format-convert / resolution check.
+- `templates/tokens/*.json` — generic + venue color packs (generic, iclr, icml, neurips, cvpr,
+  acl).
+- `templates/COMPONENTS.md`, `templates/README.md`, this `NOTICE.md`.
+- The template modifications listed above (de-gradient, token scale, zero-inline-style
+  utilities, contract attributes).
+
+## Upstream-sync rule
+
+When pulling new posterly releases, **preserve the vendor boundary**: re-vendor the unmodified
+files (`scripts/poster_check.py`, `scripts/render_preview.py`, `scripts/_posterly/`) as drop-in
+replacements, and re-apply the documented template adaptations on top of the new neutral
+templates. Do **not** fold ARIS additions into the vendored files — keep `style_check.py`,
+`asset_check.py`, `run_gates.py`, `extract_pdf_figures.py`, `preprocess_figures.py`, the token
+packs, and the docs as separate ARIS-owned files so the posterly diff stays clean and
+re-syncable.

package/skills/paper-poster-html/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: paper-poster-html
+description: "DEFAULT poster pipeline — build an academic conference poster (ICML/NeurIPS/ICLR/CVPR/...) as a single HTML/CSS file with measurement-driven hard gates, real paper figures, a two-hue design-token system, and print-ready PDF via headless Chromium. Use when the user says \"做海报\", \"poster\", \"conference poster\", \"paper poster\", or asks to design/redo a research poster. Supersedes the retired LaTeX /paper-poster."
+argument-hint: "[paper-dir-or-pdf] [— venue: ICLR, canvas: 185x90cm landscape, venue-colors: true]"
+allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, AskUserQuestion, mcp__codex__codex
+---
+
+# Paper Poster (HTML): measurement-gated poster generation
+
+One HTML file styled for an exact print canvas (`@page { size: W H }`), rendered to PDF
+via Playwright print emulation. **Iterate by measuring, not eyeballing** — the screen
+preview lies; only print emulation at the correct viewport tells the truth. Core gate
+machinery is adapted from [posterly](https://github.com/Chenruishuo/posterly) (MIT, ©
+2026 Ruishuo Chen — see `NOTICE.md` and `LICENSES/posterly-MIT.txt`); ARIS adds style
+discipline gates, figure-provenance gates, the cross-model review loop, and the
+anti-patch-loop fix vocabulary.
+
+## Why this skill exists (the failure it prevents)
+
+A predecessor pipeline produced a poster with **30+ colors, zero real paper figures, a
+screen-pixel canvas, and tiny formulas floating in oversized boxes**, then spent 12+
+review rounds making it *worse* — each round added a new badge color or bespoke SVG
+patch. The cure is structural, not exhortative:
+
+1. **Hard gates run before any aesthetic opinion** (alignment, style, assets must PASS
+   first — a reviewer never sees an unmeasured poster).
+2. **A closed fix vocabulary** — visual-review fixes can only touch design tokens,
+   whole catalogued components, content rebalance, assets, or canvas choice. New inline
+   styles / new hex values / bespoke decorations are structurally forbidden.
+3. **Two-hue discipline as a machine check**, not a style suggestion.
+4. **Real paper figures with provenance manifest**, or the gate fails.
+
+## Mental model
+
+```
+paper (.tex / PDF) ──► content plan + claim→evidence audit (codex, fresh)
+                              │
+   figures extracted ─────────┤  FIGURE_MANIFEST.json (provenance, sha256)
+   (real paper figures ONLY)  ▼
+   template scaffold ──► fill ──► run_gates.py            ◄─── HARD, loop here
+                                  preflight → style → asset → measure → polish
+                              │ all hard gates PASS
+                              ▼
+                    Claude visual review (≤3 issues × ≤3 rounds, fix-vocabulary only)
+                              │ score ≥ 9
+                              ▼
+                    codex final cross-model review (fresh thread, full HTML+PDF)
+                              │ pass
+                              ▼
+                    verify-final → poster.pdf + GATE_REPORT.json
+```
+
+## Constants
+
+- **SKILL_SCRIPTS** = `${CLAUDE_SKILL_DIR}/scripts` — all helpers are single-owner and
+  ship inside this skill (Arch C). If the directory is missing the install is broken:
+  abort and tell the user to re-install the skill (Policy A — the gates ARE the skill;
+  never improvise replacements).
+- **REVIEWER_MODEL** = `gpt-5.6-sol`, reasoning `xhigh`, **fresh thread per review call**
+  (`mcp__codex__codex`, never `codex-reply` across review boundaries).
+- **CANVAS** — from the venue's official spec, looked up live in Phase 0. Never assume.
+  (Known anchor: ICLR 2026 main = 185×90 cm landscape per its official printing
+  service; ICML/NeurIPS commonly 60×36 in landscape; workshop posters often 61×91 cm
+  portrait. Specs change yearly — verify.)
+- **PALETTE** — default = `templates/tokens/generic.json` (slate-blue `#2D5F8B` accent
+  + gold `#C9A24A` highlight + neutrals) for **all** venues. Venue packs are opt-in via
+  `— venue-colors: true`. Purple-dominant accents (hue 250–285) are banned unless the
+  user passes `— allow-purple: true`.
+- **AUTO_PROCEED = false** — wait for explicit confirmation at every 🚦 checkpoint.
+- **OUTPUT_DIR** = `poster_html/` in the working directory.
+
+## Workflow
+
+### Phase 0 — Resume, dependencies, venue spec
+
+1. **Resume**: if `poster_html/POSTER_STATE.json` exists with `status: in_progress`
+   (< 24 h), resume from the saved phase.
+2. **Dependencies** (degradation chain, in order):
+   - Playwright + bundled Chromium → if missing, `python3 -m playwright install
+     chromium` → if install fails but system Chrome exists, scripts fall back to
+     `channel="chrome"` → if all fail: you may produce the content plan and scaffold
+     only, label everything **"not print verified"**, and must NOT emit a final PDF.
+   - `pdfinfo` missing → PyMuPDF reads PDF dimensions. At least one of
+     pdftoppm / PyMuPDF must exist for PNG review renders.
+   - MathJax: download `tex-svg.js` once into `poster_html/assets/mathjax/` and
+     reference it locally in the HTML. CDN is acceptable only for drafts; the measure
+     gate hard-fails on unrendered MathJax either way.
+3. **Venue spec lookup (live)**: consult the venue's official poster-instructions page
+   (search + fetch). Extract dimensions, orientation, font floor, logo policy,
+   anonymity rules, file format. Record `{spec, source_url, retrieved}` into
+   `POSTER_STATE.json` — specs change yearly; never reuse a cached spec silently.
+
+**🚦 Checkpoint**: echo the venue spec table (canvas, orientation, source URL) and the
+chosen template. Wait.
+
+### Phase 0.5 — Design discovery (one AskUserQuestion batch)
+
+Ask once, ≤4 questions: layout template (from `templates/README.md`), palette
+(default generic pack / venue pack / custom within constraints), logos + venue mark
+(paths or "none" — never fabricate; check the venue's logo policy), QR target (paper /
+code / project page / none — generate **offline** with `qrencode` or python-`qrcode`;
+never a remote QR-service URL). Persist answers in `POSTER_STATE.json` as
+`design_decisions` — re-read before any later "improvement" so deliberate choices are
+never reverted.
+
+### Phase 1 — Paper ingest, content plan, claim audit
+
+1. Read the paper source (`.tex` ideal; PDF otherwise). Extract: title/authors/affils,
+   the 3–5 headline numbers, core method (equations verbatim), main results
+   (tables/figures and what they show), takeaways. Build
+   `poster_html/POSTER_CONTENT_PLAN.md` — what goes in which column, word budget per
+   card. **Target density** (excluding table cells, captions, author line, footer):
+   standard poster **550–850 words**; dense theory+empirical poster **750–1050 words**,
+   allowed only when ≥2 compact components are used (`eqn-anatomy`, `flow-strip`,
+   `derived-col`, `claim-pills`, `keybox--4`). Warn yourself below 500 words on a
+   4-column landscape (it will read as sparse next to professionally dense posters)
+   unless the template is hero/visual-first; warn above 1100 unless the user asked for
+   dense mode. Bullets ≤ 8 words when possible — density comes from *structure*, not
+   long prose. **Prefer compact structure over prose**: if the paper contains an
+   explicit objective, algorithm, theorem mechanism, or baseline comparison, extract at
+   least two of: (1) empirical objective / loss stack; (2) term-by-term equation
+   anatomy; (3) a method-flow strip grounded in paper variables; (4) a derived-Δ column
+   for method-vs-baseline rows; (5) a 4-up implementation/theory keybox; (6) a
+   claim/evidence pill table for numeric-heavy posters. **Do not invent an algorithm.**
+   If the paper has only an objective, label the component "objective flow" or "loss
+   anatomy", never "algorithm".
+2. **Cross-model content audit** (fresh codex thread, `xhigh`): give it the content
+   plan path + paper source path(s) — paths only, no summaries — and ask for a
+   claim→evidence table: `| claim on poster | paper file:line | paper says (verbatim) |
+   match? |` with match ∈ {OK, NUMERIC-MISMATCH, OVERCLAIM, MISSING-PRECONDITION,
+   NOT-IN-PAPER, SCOPE-NARROWED}. Save to `poster_html/CLAIM_EVIDENCE.md`.
+3. Fix every non-OK row or record it as a user-acknowledged tradeoff.
+
+**🚦 Checkpoint**: content plan + audit summary. Wait.
+
+### Phase 2 — Real paper figures (provenance-gated)
+
+Source preference chain:
+1. Paper source `figures/` (vector SVG/PDF → convert to SVG via
+   `inkscape`/`pdf2svg` if available, else rasterize ≥ 2× rendered px).
+2. PDF-only: `extract_pdf_figures.py contact-sheet` + `auto` to list candidate
+   regions → pick crops (**🚦 human confirms crop choices**) → `crop` at 300–450 DPI.
+3. Last resort: user supplies explicit `page,x0,y0,x1,y1` bboxes.
+
+Then `preprocess_figures.py --autocrop` every asset. Every paper-derived image gets a
+`FIGURE_MANIFEST.json` entry (source hash, page, bbox, dpi, sha256, natural_px) and is
+embedded as `<img data-source="paper" data-asset-id="...">`.
+
+**Hard rule**: ≥ 2 paper-derived visuals or the asset gate fails. Theory-only papers
+may waive the *total-area* rule (`--waive-total-area`) at a human checkpoint — never
+silently. Never draw bespoke decorative SVG "figures" as substitutes.
+
+**Figure-area bands** (asset gate, fractions of *body*): total target **14–22 %**
+(warn < 12 % / > 24 %, hard < 10 % / > 28 %); per ordinary figure target 4–8 % (warn
+> 10 %, hard > 13 %); `figure--duo` combined 8–12 %. Hero templates pass `--hero`
+(centerpiece may take 30–40 %). The failure mode is symmetric: too small reads as
+decoration, too big crowds out content. Sibling figures that share axes or tell a
+before→after story belong in one `figure--duo` card, not two cards.
+
+### Phase 3 — Scaffold + tokens
+
+`cp templates/<chosen>.html poster_html/poster.html`; retarget `@page` + `.poster`
+dims to the venue canvas (two edits, same values); apply the chosen token pack onto the
+`:root` DESIGN TOKENS block; fill content per the plan; embed manifest figures.
+Run `preflight` + `style_check` — both must PASS before any layout iteration. (A fresh
+scaffold is *expected* to fail `measure` — that gate judges a filled poster.)
+
+### Phase 4 — Layout hard loop
+
+After every layout change:
+
+```bash
+python3 "$SKILL_SCRIPTS/run_gates.py" poster_html/poster.html \
+    --tokens <pack.json> --manifest poster_html/FIGURE_MANIFEST.json \
+    --report poster_html/GATE_REPORT.json
+```
+
+Canonical order: preflight → style → asset → measure → polish. Targets: column-bottom
+**spread < 5 px** (aim < 3), footer gap ∈ [30, 50] px, intercard gap ∈ [12, 50] px,
+canvas-fill ∈ [95, 101] %, poster bbox aligned to page within ±2 px. Fix guidance for
+each failure mode lives in the gate output and `templates/COMPONENTS.md`. **Do not
+proceed while any hard gate fails. Do not let a reviewer see an unmeasured poster.**
+Balance under-filled columns with *content from the paper* (Gate C), never with
+whitespace, `space-between`, or stretched cards.
+
+### Phase 5 — Claude visual review (gated aesthetics)
+
+Render and read the result yourself:
+
+```bash
+python3 "$SKILL_SCRIPTS/render_preview.py" poster_html/poster.html
+pdftoppm -r 100 poster_html/poster_preview.pdf poster_html/review_full -png -f 1 -l 1
+# plus 2-4 region crops at higher res (header / one column / equations) via PIL
+```
+
+**Calibrate first** (`../shared-references/taste-calibration.md`): if
+**human-curated** `references/good/` + `references/bad/` exist under this skill
+dir (or the project supplies its own pair), score those 3+3 reference posters
+on the axes below BEFORE the target, anchoring the scale. Never select, search
+for, or generate anchors yourself; if no reference sets exist, proceed
+uncalibrated and mark `CALIBRATION: none` — never fabricate anchor scores.
+Axes (weights sum 1.0): Design 0.35 · Craft 0.30 · Functionality 0.20 ·
+Originality 0.15. Mapping: `SCORE = min(round(1 + 9 × COMPOSITE), lowest
+triggered cap)` — caps apply AFTER the mapping, and the loop's `Score ≥ 9`
+threshold below always reads this final capped `SCORE`, never the raw
+composite.
+
+Score strictly 1–10. **Critical caps** (hard floors — a calibrated composite
+never overrides them): < 2 real paper figures → ≤ 3; broken canvas /
+clipped content / unreadable math → ≤ 4; ≥ 4 visible hue families or gradient-heavy
+header → ≤ 4; large blank cards or columns → ≤ 5; fabricated visual claim → ≤ 3.
+Checks: posterly-showcase gestalt (would this hang next to a professionally designed
+poster without looking like a patched dashboard?), single-accent discipline, real
+figures readable and central, print hierarchy (title → headline stats → figures →
+detail), column fill, **equation prominence** (no tiny math in oversized boxes),
+serif-body/sans-display pairing, no gradient kitsch, component consistency, 60-second
+narrative. Output format:
+
+```
+SCORE: N/10            (= min(round(1 + 9 × COMPOSITE), lowest cap); drives the loop)
+COMPOSITE: 0.xx        (weighted; list the four per-axis scores)
+CALIBRATION: anchored | none
+GAP: <which reference poster the target falls short of / exceeds, on which axis, and why — one paragraph; omit only when CALIBRATION: none>
+CAPS_TRIGGERED: ...
+TOP_ISSUES: (max 3)
+ALLOWED_FIX_TYPE per issue: token | component | rebalance | asset | template/canvas
+PATCH_LOOP_RISK: low | medium | high
+```
+
+Loop: fix (fix vocabulary below) → re-run Phase 4 gates → re-score. **≤ 3 issues per
+round, ≤ 3 rounds.** Score ≥ 9 → Phase 6. Still < 9 after 3 rounds → STOP patching;
+escalate to template / canvas / content re-choice (back to Phase 3) or a human
+decision. Never enter round 4 of cosmetic patching.
+
+#### Fix vocabulary (closed set — the anti-patch-loop core)
+
+Allowed: **(a)** edit a `:root` token value; **(b)** swap/remove/add a whole component
+instance from `templates/COMPONENTS.md`; **(c)** content rebalance (move a card across
+columns, trim/grow text *from the paper*, resize a figure within its AR band);
+**(d)** template/canvas re-choice; **(e)** global edits to an existing component's CSS
+that reference only tokens; **(f)** switching predefined variants (`.eqn--large`,
+`.card--compact`, `.figure--wide`, `.nowrap`, …); **(g)** asset fixes (re-crop, swap
+for a clearer figure from the same paper, re-preprocess).
+
+Forbidden: new inline styles, new hex values anywhere, bespoke decorative SVG,
+per-element font-size overrides. **A new component may not be born inside the visual
+loop** — stop, get a human checkpoint, add it to `COMPONENTS.md`, re-run from Phase 3.
+
+### Phase 6 — Codex final review (fresh thread, cross-model)
+
+All hard gates PASS + polish warnings zero-or-waived + visual ≥ 9 first. Then a fresh
+codex thread (`xhigh`) reviews the **final artifacts** (not the content plan):
+`poster.html`, the rendered PDF/PNG, the paper source, `GATE_REPORT.json`,
+`CLAIM_EVIDENCE.md` — paths only, no executor framing. It checks: (1) fidelity &
+overclaims **re-checked on final text** (polish introduces new claims), (2) residue
+(`\ref{`, `TODO`, raw `<` in math, missing images, remote URLs), (3) visual rhetoric
+(headline numbers prominent, banner readable from 2 m), (4) gate-log coherence. The
+reviewer recommends; it does not edit. Any fix → back through Phase 4/5 gates — never
+straight to re-review.
+
+### Phase 7 — Final verification + report
+
+```bash
+python3 "$SKILL_SCRIPTS/poster_check.py" verify-final poster_html/poster_preview.pdf \
+    --from-html poster_html/poster.html --max-size-mb 20
+```
+
+Page count 1, dimensions match `@page`, size ≤ 20 MB, no TODO/residue, no remote
+assets. Report: PDF path, final spread px, footer-gap range, gate summary table,
+unresolved waivers, codex verdict. Update `POSTER_STATE.json` → `done`.
+
+## State persistence
+
+`poster_html/POSTER_STATE.json`: `{phase, venue, canvas{w,h,orientation,source_url,
+retrieved}, template, token_pack, design_decisions{...}, figures_selected[],
+visual_rounds, codex_threads{audit, final}, status, timestamp}` — written after every
+phase; enables compact-recovery resume.
+
+## Key rules
+
+- **Measure, don't eyeball.** No layout claim without `run_gates.py` output.
+- **Gates before aesthetics.** Claude/codex review only ever sees a poster whose hard
+  gates PASS. This ordering is what kills the patch-loop death spiral.
+- **Never invent paper numbers or figures.** Numbers come from the paper source;
+  visuals carry manifest provenance. Fabrication = critical cap ≤ 3.
+- **Two hues, one system.** Accent + gold + neutrals. The style gate enforces it;
+  don't negotiate with the gate.
+- **Real figures are the poster.** A poster without the paper's own figures is a
+  dashboard, not a poster.
+- **Fix vocabulary is closed.** If a fix isn't expressible as token / component /
+  rebalance / asset / canvas, it's the wrong fix.
+- **Cross-model verdicts.** Claude drives the loop and scores visuals; acceptance of
+  content fidelity comes from the fresh codex thread (a loop can drive, never acquit).
+- **Preserve user decisions.** Re-read `design_decisions` before "improving" anything.
+- **Vendor boundary.** `poster_check.py`, `render_preview.py`, `_posterly/` are
+  vendored from posterly — keep diffs minimal; ARIS-side logic goes in the new
+  scripts, not in vendored files.
+
+## Review tracing
+
+Save every codex reviewer call's trace per `shared-references/review-tracing.md` to
+`.aris/traces/paper-poster-html/<date>_run<NN>/` (audit + final threads, raw responses).
+
+## Output contract
+
+```
+poster_html/
+├── poster.html              # single-file source of truth
+├── poster_preview.pdf       # print-emulated, verify-final-checked
+├── poster_preview.png       # thumbnail
+├── POSTER_STATE.json        # resume state
+├── GATE_REPORT.json         # canonical gate ledger (schema v1)
+├── POSTER_CONTENT_PLAN.md   # what-goes-where + word budgets
+├── CLAIM_EVIDENCE.md        # codex claim→evidence audit
+├── FIGURE_MANIFEST.json     # figure provenance (sha256, page, bbox, dpi)
+└── assets/{paper_figures,logos,qr,mathjax}/
+```
+
+## When NOT to use
+
+- Slides, not a poster → `/paper-talk` / `/slides-polish`.
+- The paper's headline isn't stable yet — fix the paper first; a poster amplifies
+  whatever story it's given.