schema-validate

schema-validate — governance skill (Phase 13)

Read-only schema audit. Enumerate all schemas/*.schema.json via runtime glob() (NOT hardcoded count — count drift is the failure mode this skill is designed to surface), validate each as a well-formed JSON Schema Draft7 meta-schema, validate the cross-sheet-invariants instance document's rules[] array (≥20 rule registry, key=rules per S3.5 instance pivot; additive growth via K-02 paterni), and validate every skills/**/SKILL.md frontmatter block against schemas/skill-frontmatter.schema.json.

Read-only contract: master.xlsx MUST NOT be opened, mutated, or referenced from outputs[]. The skill writes only to outputs/reports/{date}-schema-validate.md (markdown report) and _state/events.jsonl (single event_kind=audit row).

Foundational Principles (3-layer enforce)

This skill operates under the three Foundational Principles (authority: rules/schema-first.md + rules/single-source-of-truth.md

• rules/append-only-state.md — schema-first authoritative reference; applied principles converge in rules/content-quality.md):

1. Truth-verifiable — every assertion in the report MUST trace back to a schema authority (the schema file itself or its Draft7Validator.iter_errors output). No prose fabrication.
2. Profile-aware (5-enum) — the skill respects the project profile enum (solo / agency / inhouse / enterprise / pilot). Strict mode default mirrors the agency/enterprise CI gate semantics.
3. AI suistimal yasağı — the skill MUST NOT call any LLM tool to "explain" a schema error away. Failures surface as-is in the report; human judgment owns repair. mcp_tools=[] enforces this at the contract level.

DURUR (no fall-back) conditions

1. DURUR #1 — import jsonschema smoke fails → AMBER + exit 1. The skill cannot proceed without the validator library; this is an environment defect, not a data defect.
2. DURUR #2 — schemas/ directory missing → exit 1. The skill uses a runtime glob('schemas/*.schema.json') enumerate (NOT a hardcoded count) precisely so that schema additions/removals do NOT silently change behaviour. Missing root directory is fatal.
3. DURUR #3 — strict=true AND any FAIL → exit 1; non-strict mode downgrades to AMBER + report-only (CI gate skipped, manager review required). Never silently PASS on FAIL.

Inputs (frontmatter contract)

Name	Type	Default	Notes
schema_path	string	schemas/	Root dir for runtime glob enumerate. NOT a count parameter.
strict	boolean	true	True → any FAIL exits 1. False → AMBER + report.

Outputs (artifacts produced)

• outputs/reports/{date}-schema-validate.md — human-readable report enumerating every schema validated, every cross-sheet-invariants rule structurally checked, every SKILL.md frontmatter result.
• _state/events.jsonl — single event_kind=audit entry (audit_action="accessed", audit_target="schemas:bulk-validate", actor="agent:schema-validate").

8-Step Body Protocol

Step 1 — validator_smoke (DURUR #1)

# Standalone-executable entrypoint (Phase 14 W3-W1 helper exec compliance):
# imports + entrypoint variables init for downstream concat blocks.
import os
import sys
import json
import re
from pathlib import Path

import yaml

# sys.path insert so `scripts.*` packages resolve under subprocess exec.
sys.path.insert(0, os.getcwd())

# Entrypoint variables (placeholder defaults — orchestrator overrides at runtime)
schema_path = "schemas/"
strict = True
project_id = "drifttest"
REPO_ROOT = Path.cwd()
failures: list = []

try:
    import jsonschema
    from jsonschema import Draft7Validator
except ImportError as exc:
    raise SystemExit(f"DURUR #1: jsonschema unavailable: {exc}")

Draft7Validator.check_schema(schema) is the meta-schema gate; without it the skill cannot validate anything.

Step 2 — enumerate_schemas (runtime glob, NOT hardcoded count)

schema_root = Path(schema_path)
if not schema_root.exists():
    raise SystemExit(f"DURUR #2: {schema_root} missing")
schema_files = sorted(schema_root.glob("*.schema.json"))
# IMPORTANT: count is computed at runtime; F-13.1 manager finding —
# brief authority claim "19 schema" diverged from filesystem 18.
# Schema authority kazanır (lesson 31+34 schema-first override).

Hardcoded counts in this skill body or description WOULD reintroduce the very drift this skill exists to detect. Count is reported to the report markdown but never asserted as a constant.

Step 3 — meta_validate_each_schema

for sp in schema_files:
    schema = json.loads(sp.read_text(encoding="utf-8"))
    Draft7Validator.check_schema(schema)  # raises SchemaError on bad meta

Each .schema.json file must itself be a valid Draft7 meta-schema. This catches $ref typos, malformed enum, unrecognized keywords.

Step 4 — validate_cross_sheet_invariants_rules

csi = json.loads((schema_root / "cross-sheet-invariants.json").read_text("utf-8"))
rules = csi["rules"]   # KEY = "rules" — NOT "invariants"
assert isinstance(rules, list)
assert len(rules) >= 1
required_per_rule = {"id", "severity", "category", "rule"}
for entry in rules:
    missing = required_per_rule - set(entry.keys())
    assert not missing, f"rule {entry.get('id', '?')} missing keys: {missing}"

The cross-sheet-invariants instance document carries 31 rules (F-01..F-15 + D-01..D-03 + M-01..M-02 baseline = 20; F-16..F-22 additive K-02 v1.5-Phase-2 = 27; F-23..F-26 SF MCP cross-sheet additive v1.8 Phase 4 = 31, terminal F-26) per spec §7. Per-rule F-NN ↔ validate_invariants.py parity is enforced separately by tests/schemas/test_cross_sheet_invariants_sync.py (bidirectional + KNOWN_SCHEMA_ONLY known-deferred for F-06/F-07). The top-level key is rules per S3.5 pivot — NOT invariants. This skill explicitly exercises that key so a memory-drift typo (the natural mistake) is caught at the audit step, not silently masked.

Step 5 — validate_skill_frontmatter_compliance

fm_schema = json.loads((schema_root / "skill-frontmatter.schema.json").read_text("utf-8"))
fm_validator = Draft7Validator(fm_schema)
skill_root = REPO_ROOT / "skills"
skill_files = sorted(skill_root.rglob("SKILL.md"))
for skill_md in skill_files:
    text = skill_md.read_text(encoding="utf-8")
    m = re.match(r"^---\n(.*?)\n---\n", text, re.DOTALL)
    if not m:
        # FAIL: frontmatter block missing
        failures.append(f"{skill_md}: no frontmatter block")
        continue
    fm = yaml.safe_load(m.group(1))
    errors = sorted(fm_validator.iter_errors(fm), key=lambda e: list(e.absolute_path))
    # accumulate per-file
    if errors:
        failures.extend(f"{skill_md}: {e.message}" for e in errors)

Every skills/**/SKILL.md frontmatter is Draft7-validated against the canonical skill-frontmatter.schema.json. The 13 root properties declared there (name, description, version, status, category, inputs, outputs, triggers, consumes, produces, mcp_tools, budget, autonomy) are the contract surface.

Step 6 — aggregate_verdict (DURUR #3)

overall = "GREEN" if not failures else ("RED" if strict else "AMBER")
if strict and failures:
    raise SystemExit(1)   # DURUR #3

Strict + FAIL → exit 1. Non-strict + FAIL → AMBER report, no exit. Never silently PASS on FAIL.

Step 7 — render_report

Write outputs/reports/{date}-schema-validate.md with sections:

• Schemas — count (runtime), per-file PASS/FAIL with first 3 errors.
• Cross-Sheet Invariants — rules array length, per-rule structural PASS/FAIL.
• SKILL.md Frontmatter — count (runtime), per-file PASS/FAIL with Draft7 errors.
• Summary — overall verdict (GREEN/AMBER/RED).

Step 8 — emit_audit_event

from scripts.state import events_writer
# Documented invocation (orchestrator runs at workflow time):
# events_writer.append_audit(
#     project_id=project_id,
#     audit_action="accessed",
#     audit_target="schemas:bulk-validate",
#     actor="agent:schema-validate",
#     notes=f"verdict={overall} schemas={len(schema_files)} skills={len(skill_files)}",
# )
audit_payload = {
    "event_kind": "audit",
    "audit_action": "accessed",
    "audit_target": "schemas:bulk-validate",
    "actor": "agent:schema-validate",
    "notes": f"verdict={overall} schemas={len(schema_files)} skills={len(skill_files)}",
}

The audit event_kind requires the audit_action + audit_target + actor triple per events.schema.json allOf rule. event_type (the WORK-only closed 10-value enum) is NOT used here; that field is reserved for work-tracking events (DONE protocol §21.4) and the schema-first override (lesson 31+34) directs governance signals to the audit kind.

v1.8 Phase 1 — sf-mcp-tool-mapping.schema.json (additive enumerate)

The Phase 1 schema schemas/sf-mcp-tool-mapping.schema.json (155L, Screaming Frog 24 native MCP integration contract) is picked up by the runtime glob('schemas/*.schema.json') enumerate (Step 2) automatically — no enumeration code change required (F-13.1 schema-first override discipline: count is runtime, not hardcoded).

The companion instance document templates/sf-mcp/use-case-example.json is a SAMPLE instance (Phase 1 scaffold demonstrating the contract). Phase 4 verification: that sample MUST Draft7Validator(schema).validate(instance) cleanly, otherwise the schema contract is broken. The schema-validate skill covers this implicitly via the meta-schema gate (Step 3); the dedicated positive-instance assertion lives in tests/skills/test_schema_validate.py::test_sf_mcp_tool_mapping_in_sweep (Phase 4 test extension).

The Phase 1 baseline schemas/ count was 18 (per F-13.1); Phase 1 added sf-mcp-tool-mapping.schema.json → 19+ depending on prior additions. The exact number is reported by the runtime glob at every run — never asserted as a constant.

Master.xlsx WRITE forbidden

This skill MUST NOT call transaction.append, transaction.update, transaction.delete, or wb.save against master.xlsx. It does not even open the workbook — schemas live under schemas/ and SKILL.md files live under skills/, both outside the project state tree. The test suite enforces this by regex grep over the production prose: the call-site syntax (transaction-dot-append-with-paren etc.) is forbidden in this body, and the body intentionally references those tokens WITHOUT the trailing paren to discuss them in negative form.

Why the rules key matters (W-H1 finding F-13.1 reuse)

The cross-sheet-invariants instance document uses the top-level key rules (per spec §3.5 instance pivot). Memory drift naturally produces the misspelling invariants (the document title has "Invariants" in it). schema-validate explicitly tests the rules key so this drift is caught the moment it appears — schema authority wins over memory authority (lesson 31+34 schema-first override).

Why hardcoded schema count is forbidden

The brief's authority claim ("19 schema") diverged from the actual filesystem count (18). The natural temptation is to lock the count in a constant; schema-validate explicitly avoids this. glob() enumerate makes the skill self-aware: it reports whatever exists at runtime, and the report records the count for the manager to cross-check. This is the lesson 31+34 schema-first override paterni applied to a count authority.

Cross-references

• Schemas: schemas/skill-frontmatter.schema.json, schemas/cross-sheet-invariants.json, schemas/events.schema.json (event_kind=audit branch).
• Cross-modules: scripts/state/events_writer.py (audit append), scripts/reporting/render_template.py (report render).
• Tests: tests/skills/governance/test_schema_validate.py.
• Sibling governance skills: drift-check (master.xlsx invariants), glossary-audit (term drift), load-context (session wakeup).