AGENT SKILL

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

  1. Early gate (first 5 pages as a method sample; skip for rosters ≤ 6):
    python3 templates/co-work/scripts/deck/svg_check.py --deck <deck-dir> \
      --content <deck-dir>/deck_content.md --stage early --json
    
    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.
  2. Final gate (whole deck):
    python3 templates/co-work/scripts/deck/svg_check.py --deck <deck-dir> \
      --content <deck-dir>/deck_content.md --stage final --json
    
    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.
  3. 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 enforces
  • pptx-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-authoring skill
  • Export coupling: pptx-export skill (fingerprint refusal rule)

04 同仓库更多 Skills

5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25