Upgrade Schema Validator

custom-skills/16-seo-schema-validator/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: 16-seo-schema-validator
+description: |
+  Validates an AUTHORED JSON-LD schema dataset (pre-deployment QA) and audits
+  live structured data (post-deployment). Runs a 5-layer offline validation
+  pipeline (coverage, syntax, vocabulary, Google rich-result requirements,
+  business-logic/consistency) and emits a severity-ranked defect log, a gate
+  decision, and a Markdown report. Fills the "16-seo-schema-validator" slot
+  referenced by seo-comprehensive-audit.
+  Triggers: schema validation, JSON-LD QA, structured data check, schema 검수,
+  스키마 유효성 검증, 구조화 데이터 검토, rich result eligibility, schema 오류 점검.
+version: "1.0"
+author: OurDigital / D.intelligence
+environment: Code
+---
+
+# SEO Schema Validator (16)
+
+Quality-assure structured data at scale. Built for the kind of failure where a
+client review of hundreds of authored entries surfaces "too many errors" — by
+moving the cheap, machine-checkable errors OUT of the human review and INTO an
+automated gate that runs first.
+
+## Two modes
+
+| Mode | When | Input | Adds |
+|------|------|-------|------|
+| **A — Dataset QA (default)** | Before deployment, while authoring/reviewing | An authored dataset: `.xlsx` / `.csv` (one row per entry, a JSON-LD column), `.jsonl`, `.json`, or a directory of `.json/.jsonld` | Layer 0 coverage vs the canonical URL list |
+| **B — Live audit** | After deployment, or feeding `seo-comprehensive-audit` | Live URLs (extract embedded JSON-LD first, then validate) | Layer 5 rendering-reality (schema present in rendered HTML, matches content) |
+
+This skill's primary job is **Mode A**: catch errors before the client sees them.
+
+## The 5 validation layers
+
+| # | Layer | Catches | Default severity |
+|---|-------|---------|------------------|
+| L0 | Coverage | URLs with no entry; entries whose URL isn't in the inventory | P1 / P2 |
+| L1 | Syntax | invalid JSON, missing/wrong `@context`, no `@type`, encoding corruption | P0 / P1 |
+| L2 | Vocabulary | unknown type, property not valid for type, bad value formats (URL/date/lang/currency/number) | P1 / P2 |
+| L3 | Rich-result | Google **required** missing (blocks rich result); recommended absent | P0 / P2 |
+| L4 | Consistency | NAP mismatch across a property, `@id` dupes/dangling refs, swapped geo, placeholder text, duplicate descriptions | P0 / P1 |
+
+Full rationale and the type→requirement matrix: `references/validation-methodology.md`.
+Severity + category codes: `references/defect-taxonomy.md`.
+Shilla page-type → schema-type map: `references/shilla-type-map.md`.
+Client-facing report + P1 decision log: `templates/client-qa-report-template.md`, `templates/decision-log.md`.
+
+## Stage gates (aligned to the project lifecycle 설계→개발→테스트→안정화→런칭 후)
+
+- **G1 설계** — Lock the schema spec and the page-type→type map (`shilla-type-map.md`). Approve the entry template. *DoD:* every page template has an assigned schema type and a required-property list.
+- **G2 개발** — Authors produce entries. Run the validator with `--strict`. *DoD (gate):* **zero P0**, JSON parses for 100% of entries. Entries failing this NEVER reach client review.
+- **G3 테스트** — Re-run; triage P1 in `defect_log.csv` (assign owner/status). Client reviews ONLY the clean, P0-free entries, against a defect report — not raw JSON. *DoD:* P1 triaged, decisions logged in `templates/decision-log.md`.
+- **G4 안정화** — Fix → re-run → confirm no regressions. Spot-check a sample in Google Rich Results Test (online, outside this runtime). *DoD:* P0=0, P1 accepted/closed, online validator green on sample.
+- **G5 런칭 후** — Mode B live audit + GSC "Rich results" report monitoring. *DoD:* deployed schema matches authored dataset; no new GSC structured-data errors.
+
+## How to run
+
+```bash
+# Mode A — validate an authored dataset (the common case)
+python scripts/validate_schema.py path/to/schema_dataset.xlsx \
+    --url-list path/to/URLlist.xlsx \
+    --out schema_qa_out
+
+# Highest signal for the pre-review gate (unexpected props -> P1, drop optional recommended)
+python scripts/validate_schema.py dataset.csv --strict --no-recommended --out qa_strict
+
+# Try it on the bundled flawed fixture first
+python scripts/make_sample.py
+python scripts/validate_schema.py fixtures/sample_schema.csv --out demo_out
+```
+
+**Input expectations (Mode A tabular):** the loader auto-detects a JSON-LD column
+(`jsonld`, `schema`, `structured_data`, `스키마`, …) plus optional `url`/`메뉴 URL`,
+`lang`/`언어코드`, `device`/`PC/MOBILE`, `page_type` columns. Multi-sheet `.xlsx`
+is supported (each sheet with a JSON-LD column is read). No JSON-LD column → clear error.
+
+## Reading the output
+
+- `report.md` — counts, **gate decision (PASS = zero P0)**, defects-by-category, top P0 entries, next step.
+- `defect_log.csv` — one row per finding with `status/owner/note` columns ready for triage. This is the client-facing artifact (open issues, not raw schema).
+- `results.json` — full machine-readable results for dashboards / CI.
+
+**The rule:** an entry advances to client review only when it has **zero P0**. P1 =
+triage backlog (fix before launch). P2 = optimization backlog (recommended props, style).
+
+## Limits & honesty
+
+- Offline by design — the runtime can't reach schema.org or Google. The bundled
+  rule set (`scripts/schema_rules.json`) is a curated hotel-focused subset; unknown
+  types/properties degrade to warnings (never hard errors) to avoid false positives.
+- Authoritative rich-result eligibility still requires Google's online testers on a
+  sample at G4. This skill makes that sample small and clean, not redundant.
+- Adding a new schema type or tightening a rule = edit `schema_rules.json` only.
+
+## Integration
+
+`seo-comprehensive-audit` calls this skill as pipeline stage 4 ("Schema Validation").
+For that orchestrator, run **Mode B** on a sample of live URLs and return the score
+(100 − weighted defect penalty) and the issue list. For day-to-day client work, run
+**Mode A** on the authored dataset.