svg-quality-gate
Deterministic quality gate for canonical SVG deck pages: dual gates (early method sample P01-P05 + final whole-deck), three-severity model (error blocks / warning passes / no auto-fix), bidirectional content-SSOT text-run diff, and SHA-256 fingerprint reports required for export. Use when: running or interpreting svg_check.py on a deck, or deciding whether a deck may export.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- svg-quality-gate
- owner
- pm
- scope
- co-work
- status
- active
- version
- 1.3.0
- metadata
- { "type": "process", "triggers": [ "svg quality gate", "deck gate", "svg-check", "final gate deck", "early gate slides" ] }
- description
- Deterministic quality gate for canonical SVG deck pages: dual gates (early method sample P01-P05 + final whole-deck), three-severity model (error blocks / warning passes / no auto-fix), bidirectional content-SSOT text-run diff, and SHA-256 fingerprint reports required for export. Use when: running or interpreting svg_check.py on a deck, or deciding whether a deck may export.
- last_reviewed
- 1794009600000
- prerequisites
- Python 3.10+, templates/co-work/scripts/deck/svg_check.py
03 SKILL.md 正文
🛠️ Skill: svg-quality-gate
Context
LLM-authored SVG is not deterministic — contract violations creep in over long decks and surface at export or, worse, silently in PowerPoint. The gate turns "PowerPoint shows a broken slide" into "page N violates the canonical contract" before any conversion happens. It reads authored state only — it never rewrites pages (no auto-fix by design: a mechanical patch can silently overwrite valid design intent).
When to Use
- After authoring P01–P05 (early gate; skipped for rosters of 6 or fewer pages)
- Before export (final gate — mandatory, whole deck)
- After any page repair, at the owning stage (early repairs re-run early; final repairs re-run final)
Severity Model
| Severity | Classification | Pipeline behavior |
|---|---|---|
error |
Broken contract: non-whitelisted element/attribute, invalid color spelling, malformed path, missing required marker, XML malformation, text run not present in deck_content.md |
Re-author the page and re-run the gate; export refuses while any blocking error remains |
warning |
Documented compatible form: relative path commands, lowercase hex, scale transforms |
Record and pass; fix when the same warning repeats across pages (that is a prompt/authoring-method issue) |
There is intentionally no auto-fix and no gray zone: if it must be corrected for delivery, it is an error.
Execution Steps
- Early gate (first 5 pages as a method sample; skip for rosters ≤ 6):
Classify the complete issue set: method-level (fix the authoring method, not just the page), page-local, and not-yet-exercised capabilities. Fix every blocking error and selected advisory warnings in ONE consolidated pass before authoring further pages.python3 templates/co-work/scripts/deck/svg_check.py --deck <deck-dir> \ --content <deck-dir>/deck_content.md --stage early --json - Final gate (whole deck):
Zero errors required to proceed. The report's SHA-256 fingerprint must match the bytes at export time — any edit after the final gate invalidates it; re-run the gate.python3 templates/co-work/scripts/deck/svg_check.py --deck <deck-dir> \ --content <deck-dir>/deck_content.md --stage final --json - Repair loop: fix at the page level (max 2 rounds per page; exceeding → PM escalation). Re-run the owning stage's gate after each consolidated repair pass.
Report Shape (JSON)
{
"stage": "final",
"deck": "<dir>",
"pages": [ { "file": "01-title.svg", "errors": [], "warnings": [] } ],
"summary": { "pages": 10, "errors": 0, "warnings": 1 },
"content_diff": { "unmatched_runs": [], "unrendered_runs": 0 },
"fingerprint": "sha256:<hex>",
"generated_at": "<ISO-8601>"
}
Output Format
- Pass verdict:
stage, error/warning counts, fingerprint - On failure: per-page error list with rule ids (e.g.
E-WHITELIST,E-COLOR,E-PATH-CMD,E-MARKER,E-CONTENT-DIFF,E-XML)
Related Skills
svg-slide-authoring— owns the canonical contract this gate enforcespptx-export— refuses exports without this gate's fingerprint-matching final report
Verification Policy (no Office tooling)
LibreOffice (and PowerPoint automation) is never installed or invoked by this pipeline. Visual acceptance renders the authored SVG via render_previews.py (white-underlay resvg previews; resvg-py engine, bun + @resvg/resvg-js fallback); package correctness rests on the exporter's validators plus this gate's empirical contract — checker rules thicken as real PowerPoint breakage surfaces, not by rendering packages through an Office emulator.
Checker implementation (v1.3.0, oracle retirement)
The gate is the python checker svg_check.py — the single checker since the oracle retirement (2026-11-07): svg_check.py 2.0.0 was proven over the 100-page main deck, the 12-page exec cut, and the golden fixture by the differential harness of design 2026-11-06-deck-emitter-ppt-master-rebase-design D6 (byte-identical fingerprints, identical verdicts), after which the bun oracle svg-check.ts was DELETED and the harness became the python-only semantics suite scripts/deck/tests/test_svg_check.py (in the consuming project; real-deck fingerprints aa3baf43… / ffa4d390… pinned).
Checker 2.1.0 adds exec-cut contract support: the reverse diff (W-CONTENT-UNRENDERED) is active for ## E01–## E12 contracts — any other markdown heading terminates a section, structured field bullets (- focal: / - title: / - runs: items) contribute only their content, footnote: / table: / visual: blocks are structural apparatus exempt from the reverse diff (the forward E-CONTENT-DIFF gate still enforces rendered text verbatim), and loose matching is punctuation-insensitive (word-sequence containment). ## Page <n> contracts are unaffected.
References
- Spec:
docs/designs/2026-11-03-co-work-native-pptx-deck-design.md(§3, §6) - Authoring contract:
svg-slide-authoringskill - Export coupling:
pptx-exportskill (fingerprint refusal rule)
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.