refactor(frontmatter): unified frontmatter contract + handoff spec (ORCH-52c)

src/frontmatter.py grows from a single-key reader into the full machine
contract: reader (read_frontmatter_value, unchanged), one parse primitive
(parse_frontmatter), writer (render/write_frontmatter), schema validator
(validate_schema/REQUIRED_FIELDS, warning-only by default) and a shared
strip_frontmatter helper. The five verdict gates (check_reviewer_verdict,
_parse_tests_verdict, _parse_deploy_status, _parse_staging_status,
parse_security_status) now read through the single parse_frontmatter point
instead of duplicated ad-hoc YAML logic; review_parse._strip_frontmatter and
security_gate.extract_security_findings reuse the shared helper.

Strictly backward compatible + never-raise: STAGE_TRANSITIONS, the QG_CHECKS
composition, verdict semantics (incl. ORCH-047 three-field tester + negative
token priority), reason-strings and worktree->origin/main fallback are 1:1.
The schema validator never influences a gate verdict by default; hard-fail is
reserved behind the frontmatter_validation_strict kill-switch (default False).

New formal handoff spec docs/_standards/HANDOFF_PROTOCOL.md ("stage -> required
output" + required frontmatter schema), aligned 1:1 with PIPELINE_DOCS.md.

Tests: test_frontmatter.py (TC-01..07), test_qg_verdicts.py (TC-08..15),
test_security_gate.py (TC-12), test_stages_invariants.py (TC-16). Full
tests/ green (1212).

Refs: ORCH-076

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/test_security_gate.py

@@ -202,6 +202,32 @@ def test_tc09_missing_or_broken_frontmatter_failclosed():
     assert ok is False
 
 
+def test_orch076_parse_security_status_via_unified_api():
+    """ORCH-076 TC-12: parse_security_status now reads through the unified
+    frontmatter primitive; the PASS/FAIL semantics are 1:1 with before, and an
+    old report WITHOUT the new schema fields still reads exactly the same."""
+    from src import frontmatter as fm
+
+    # Delegates to the single parse primitive (no private duplicated parse).
+    assert "parse_frontmatter" in sg.parse_security_status.__doc__
+
+    # PASS / FAIL semantics preserved.
+    assert sg.parse_security_status("---\nsecurity_status: PASS\n---\n")[0] is True
+    assert sg.parse_security_status("---\nsecurity_status: FAIL\n---\n")[0] is False
+
+    # An additive full schema does not change the verdict (FR-5 / AC-4).
+    schema = (
+        "work_item: ORCH-076\nstage: deploy-staging\nauthor_agent: deployer\n"
+        "status: PASS\ncreated_at: 2026-06-09\nmodel_used: claude-opus-4-8\n"
+    )
+    with_schema = fm.render_frontmatter(
+        {**{k.split(":")[0]: v for k, v in
+            (line.split(": ", 1) for line in schema.strip().splitlines())},
+         "security_status": "PASS"}
+    )
+    assert sg.parse_security_status(with_schema)[0] is True
+
+
 def test_tc10_artifact_has_valid_frontmatter_and_body(tmp_path, monkeypatch):
     """TC-10: 17-security-report.md is written with valid frontmatter (all machine
     fields) and a body listing the findings; read-back == the written verdict."""