codex-workflow-v2 2.0.0-beta.1 → 2.0.0-beta.11

package/schemas/transition-payloads.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/transition-payloads.schema.json",
+  "$defs": {
+    "taskId": { "type": "string", "minLength": 1 },
+    "expectedRevision": { "type": "integer", "minimum": 0 },
+    "nonEmptyString": { "type": "string", "minLength": 1 },
+    "stringArray": { "type": "array", "items": { "type": "string" } },
+    "taskPlanInput": {
+      "type": "object",
+      "required": ["objective", "requirements", "acceptance", "risks", "knowledgeImpact", "knowledgeImpactReason", "knowledgeTargets", "knowledgeMapRevision", "knowledgeMapHash", "graphUse", "steps"],
+      "properties": {
+        "objective": { "$ref": "#/$defs/nonEmptyString" },
+        "requirements": { "$ref": "#/$defs/stringArray" },
+        "acceptance": { "$ref": "#/$defs/stringArray" },
+        "risks": { "$ref": "#/$defs/stringArray" },
+        "knowledgeImpact": { "enum": ["none", "update", "create", "retire"] },
+        "knowledgeImpactReason": { "type": "string" },
+        "knowledgeTargets": { "type": "array", "items": { "$ref": "#/$defs/knowledgeTarget" } },
+        "knowledgeMapRevision": { "type": "integer", "minimum": 0 },
+        "knowledgeMapHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "graphUse": { "enum": ["code-aware", "not-applicable"] },
+        "steps": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/planStep" } }
+      },
+      "additionalProperties": false
+    },
+    "knowledgeTarget": {
+      "type": "object",
+      "required": ["category", "path", "reason", "requirementIds"],
+      "properties": {
+        "category": { "enum": ["agent-guidance", "onboarding", "architecture", "decisions", "commands", "ownership", "testing", "operations", "domain"] },
+        "path": { "$ref": "#/$defs/nonEmptyString" },
+        "reason": { "$ref": "#/$defs/nonEmptyString" },
+        "requirementIds": { "$ref": "#/$defs/stringArray" }
+      },
+      "additionalProperties": false
+    },
+    "planStep": {
+      "type": "object",
+      "required": ["id", "title", "objective", "requirements", "dependencies", "expectedOutputs", "allowedWrites", "forbiddenScope", "checks"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "title": { "$ref": "#/$defs/nonEmptyString" },
+        "objective": { "$ref": "#/$defs/nonEmptyString" },
+        "requirements": { "$ref": "#/$defs/stringArray" },
+        "dependencies": { "$ref": "#/$defs/stringArray" },
+        "expectedOutputs": { "$ref": "#/$defs/stringArray" },
+        "allowedWrites": { "$ref": "#/$defs/stringArray" },
+        "forbiddenScope": { "$ref": "#/$defs/stringArray" },
+        "checks": { "$ref": "#/$defs/stringArray" }
+      },
+      "additionalProperties": false
+    },
+    "planRiskAuditInput": {
+      "type": "object",
+      "required": ["summary", "decision", "splitRationale", "stepClassifications"],
+      "properties": {
+        "summary": { "$ref": "#/$defs/nonEmptyString" },
+        "decision": { "enum": ["approved", "approved-with-rationale", "split-required", "stop-escalate"] },
+        "splitRationale": { "type": ["string", "null"] },
+        "stepClassifications": { "type": "array", "items": { "$ref": "#/$defs/riskStepClassification" } }
+      },
+      "additionalProperties": false
+    },
+    "riskStepClassification": {
+      "type": "object",
+      "required": ["stepId", "categories", "reviewRequired", "failureModes", "requiredEvidence"],
+      "properties": {
+        "stepId": { "$ref": "#/$defs/nonEmptyString" },
+        "categories": { "type": "array", "uniqueItems": true, "items": { "enum": ["migration", "concurrency", "restart-replay", "crash-window", "external-provider", "runtime-composition", "security-boundary", "auth-secrets", "irreversible-execution"] } },
+        "reviewRequired": { "type": "boolean" },
+        "failureModes": { "$ref": "#/$defs/stringArray" },
+        "requiredEvidence": { "$ref": "#/$defs/stringArray" },
+        "proofObligations": { "type": "array", "items": { "$ref": "#/$defs/riskProofObligation" } }
+      },
+      "additionalProperties": false
+    },
+    "riskProofObligation": {
+      "type": "object",
+      "required": ["failureMode", "counterexample", "expectedResult", "evidence"],
+      "properties": {
+        "failureMode": { "$ref": "#/$defs/nonEmptyString" },
+        "counterexample": { "$ref": "#/$defs/nonEmptyString" },
+        "expectedResult": { "$ref": "#/$defs/nonEmptyString" },
+        "evidence": { "$ref": "#/$defs/nonEmptyString" }
+      },
+      "additionalProperties": false
+    },
+    "correctiveReplanSnapshot": {
+      "type": "object",
+      "required": ["taskId", "taskRevision", "taskStatus", "currentPlanHash", "stepId", "stepStatus", "inProgressStepIds", "remediationAttemptCount", "correctivePosture", "correctiveDecision", "candidatePlanHash", "candidateStepIds", "actorRoleEligible", "c1ClaimAbsent", "writerLeaseAbsent", "planValidationPassed", "receiptValid", "riskAuditPassed"],
+      "properties": {
+        "taskId": { "$ref": "#/$defs/taskId" },
+        "taskRevision": { "$ref": "#/$defs/expectedRevision" },
+        "taskStatus": { "type": "string" },
+        "currentPlanHash": { "type": ["string", "null"] },
+        "stepId": { "type": "string", "minLength": 1 },
+        "stepStatus": { "type": ["string", "null"] },
+        "inProgressStepIds": { "type": "array", "items": { "type": "string" } },
+        "remediationAttemptCount": { "type": "integer", "minimum": 0 },
+        "correctivePosture": { "type": "string" },
+        "correctiveDecision": { "type": ["object", "null"] },
+        "candidatePlanHash": { "type": ["string", "null"] },
+        "candidateStepIds": { "type": ["array", "null"], "items": { "type": "string" } }
+        ,"actorRoleEligible": { "type": "boolean" }
+        ,"c1ClaimAbsent": { "type": "boolean" }
+        ,"writerLeaseAbsent": { "type": "boolean" }
+        ,"planValidationPassed": { "type": "boolean" }
+        ,"receiptValid": { "type": "boolean" }
+        ,"riskAuditPassed": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "correctiveReplanBindings": {
+      "type": "object",
+      "required": ["taskId", "expectedRevision", "currentPlanHash", "stepId", "correctiveDecisionEventId"],
+      "properties": {
+        "taskId": { "$ref": "#/$defs/taskId" },
+        "expectedRevision": { "$ref": "#/$defs/expectedRevision" },
+        "currentPlanHash": { "type": "string", "minLength": 1 },
+        "stepId": { "type": "string", "minLength": 1 },
+        "correctiveDecisionEventId": { "type": "string", "minLength": 1 },
+        "candidatePlanHash": { "type": "string", "minLength": 1 },
+        "candidateStepIds": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      },
+      "additionalProperties": false
+    },
+    "taskStateReadback": {
+      "type": "object",
+      "required": ["id", "revision", "status", "planHash"],
+      "properties": {
+        "id": { "$ref": "#/$defs/taskId" },
+        "revision": { "$ref": "#/$defs/expectedRevision" },
+        "status": { "type": "string" },
+        "planHash": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/scripts/generate-pdf-docs.py

@@ -0,0 +1,512 @@
+#!/usr/bin/env python3
+"""Generate the tracked Russian Workflow V2 PDF documentation.
+
+The Markdown sources under docs/pdf/sources are the reviewable authority for the
+three human-facing PDF artifacts. The generator is deterministic so release
+validation can compare regenerated bytes with the committed files.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import html
+import json
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+from reportlab.lib import colors
+from reportlab.lib.enums import TA_CENTER, TA_LEFT
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+from reportlab.lib.units import mm
+from reportlab.pdfbase import pdfmetrics
+from reportlab.pdfbase.ttfonts import TTFont
+from reportlab.pdfgen import canvas
+from reportlab.platypus import (
+    KeepTogether,
+    ListFlowable,
+    ListItem,
+    LongTable,
+    PageBreak,
+    Paragraph,
+    SimpleDocTemplate,
+    Spacer,
+    Table,
+    TableStyle,
+)
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCE_DIR = ROOT / "docs" / "pdf" / "sources"
+OUTPUT_DIR = ROOT / "docs" / "pdf"
+PACKAGE = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+PACKAGE_VERSION = PACKAGE["version"]
+
+DOCUMENTS = (
+    ("codex-workflow-v2-architecture-ru.md", "codex-workflow-v2-architecture-ru.pdf"),
+    ("codex-workflow-v2-chat-only-guide-ru.md", "codex-workflow-v2-chat-only-guide-ru.pdf"),
+    ("codex-workflow-v2-technical-reference-ru.md", "codex-workflow-v2-technical-reference-ru.pdf"),
+)
+
+PAGE_WIDTH, PAGE_HEIGHT = A4
+LEFT = 22 * mm
+RIGHT = 20 * mm
+TOP = 22 * mm
+BOTTOM = 18 * mm
+CONTENT_WIDTH = PAGE_WIDTH - LEFT - RIGHT
+
+NAVY = colors.HexColor("#14213D")
+BLUE = colors.HexColor("#2563EB")
+PALE_BLUE = colors.HexColor("#EFF6FF")
+PALE_GREEN = colors.HexColor("#ECFDF5")
+PALE_ORANGE = colors.HexColor("#FFF7ED")
+PALE_GRAY = colors.HexColor("#F8FAFC")
+MID_GRAY = colors.HexColor("#CBD5E1")
+TEXT = colors.HexColor("#172033")
+MUTED = colors.HexColor("#64748B")
+
+
+def first_existing(candidates: tuple[str, ...]) -> str:
+    for candidate in candidates:
+        if Path(candidate).is_file():
+            return candidate
+    raise RuntimeError(f"No usable font found in: {', '.join(candidates)}")
+
+
+def register_fonts() -> None:
+    regular = first_existing((
+        "/System/Library/Fonts/Supplemental/Arial.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+        "/usr/share/fonts/dejavu/DejaVuSans.ttf",
+    ))
+    bold = first_existing((
+        "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+        "/usr/share/fonts/dejavu/DejaVuSans-Bold.ttf",
+    ))
+    italic = first_existing((
+        "/System/Library/Fonts/Supplemental/Arial Italic.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Oblique.ttf",
+        "/usr/share/fonts/dejavu/DejaVuSans-Oblique.ttf",
+    ))
+    bold_italic = first_existing((
+        "/System/Library/Fonts/Supplemental/Arial Bold Italic.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-BoldOblique.ttf",
+        "/usr/share/fonts/dejavu/DejaVuSans-BoldOblique.ttf",
+    ))
+    pdfmetrics.registerFont(TTFont("WorkflowBody", regular))
+    pdfmetrics.registerFont(TTFont("WorkflowBold", bold))
+    pdfmetrics.registerFont(TTFont("WorkflowItalic", italic))
+    pdfmetrics.registerFont(TTFont("WorkflowBoldItalic", bold_italic))
+    pdfmetrics.registerFontFamily(
+        "WorkflowBody",
+        normal="WorkflowBody",
+        bold="WorkflowBold",
+        italic="WorkflowItalic",
+        boldItalic="WorkflowBoldItalic",
+    )
+
+
+class InvariantCanvas(canvas.Canvas):
+    def __init__(self, *args, **kwargs):
+        kwargs["invariant"] = 1
+        super().__init__(*args, **kwargs)
+
+
+def styles() -> dict[str, ParagraphStyle]:
+    base = getSampleStyleSheet()
+    return {
+        "title": ParagraphStyle(
+            "Title",
+            parent=base["Title"],
+            fontName="WorkflowBold",
+            fontSize=25,
+            leading=30,
+            textColor=NAVY,
+            alignment=TA_LEFT,
+            spaceAfter=10,
+        ),
+        "subtitle": ParagraphStyle(
+            "Subtitle",
+            parent=base["Normal"],
+            fontName="WorkflowBody",
+            fontSize=12,
+            leading=17,
+            textColor=MUTED,
+            spaceAfter=18,
+        ),
+        "part": ParagraphStyle(
+            "Part",
+            parent=base["Normal"],
+            fontName="WorkflowBold",
+            fontSize=8,
+            leading=10,
+            textColor=BLUE,
+            spaceAfter=10,
+        ),
+        "h1": ParagraphStyle(
+            "H1",
+            parent=base["Heading1"],
+            fontName="WorkflowBold",
+            fontSize=18,
+            leading=22,
+            textColor=NAVY,
+            spaceBefore=10,
+            spaceAfter=8,
+            keepWithNext=True,
+        ),
+        "h2": ParagraphStyle(
+            "H2",
+            parent=base["Heading2"],
+            fontName="WorkflowBold",
+            fontSize=14,
+            leading=18,
+            textColor=BLUE,
+            spaceBefore=8,
+            spaceAfter=6,
+            keepWithNext=True,
+        ),
+        "h3": ParagraphStyle(
+            "H3",
+            parent=base["Heading3"],
+            fontName="WorkflowBold",
+            fontSize=11,
+            leading=14,
+            textColor=NAVY,
+            spaceBefore=6,
+            spaceAfter=4,
+            keepWithNext=True,
+        ),
+        "body": ParagraphStyle(
+            "Body",
+            parent=base["BodyText"],
+            fontName="WorkflowBody",
+            fontSize=9.1,
+            leading=13.2,
+            textColor=TEXT,
+            spaceAfter=5,
+            allowWidows=0,
+            allowOrphans=0,
+        ),
+        "small": ParagraphStyle(
+            "Small",
+            parent=base["BodyText"],
+            fontName="WorkflowBody",
+            fontSize=7.7,
+            leading=10.3,
+            textColor=TEXT,
+        ),
+        "code": ParagraphStyle(
+            "Code",
+            parent=base["BodyText"],
+            fontName="WorkflowBody",
+            fontSize=7.6,
+            leading=10.1,
+            textColor=colors.HexColor("#E2E8F0"),
+            backColor=NAVY,
+            borderPadding=0,
+            wordWrap="CJK",
+        ),
+        "callout": ParagraphStyle(
+            "Callout",
+            parent=base["BodyText"],
+            fontName="WorkflowBody",
+            fontSize=8.5,
+            leading=12,
+            textColor=TEXT,
+        ),
+        "footer": ParagraphStyle(
+            "Footer",
+            parent=base["Normal"],
+            fontName="WorkflowBody",
+            fontSize=7,
+            textColor=MUTED,
+            alignment=TA_CENTER,
+        ),
+    }
+
+
+def inline_markup(value: str) -> str:
+    escaped = html.escape(value.strip())
+    escaped = re.sub(r"`([^`]+)`", r'<font name="WorkflowBold">\1</font>', escaped)
+    escaped = re.sub(r"\*\*([^*]+)\*\*", r"<b>\1</b>", escaped)
+    escaped = re.sub(r"\*([^*]+)\*", r"<i>\1</i>", escaped)
+    return escaped
+
+
+def parse_source(path: Path) -> tuple[dict[str, str], list[str]]:
+    lines = path.read_text(encoding="utf-8").splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise RuntimeError(f"{path} must start with frontmatter")
+    metadata: dict[str, str] = {}
+    index = 1
+    while index < len(lines) and lines[index].strip() != "---":
+        line = lines[index]
+        if ":" not in line:
+            raise RuntimeError(f"Invalid frontmatter line in {path}: {line}")
+        key, value = line.split(":", 1)
+        metadata[key.strip()] = value.strip().strip('"')
+        index += 1
+    if index >= len(lines):
+        raise RuntimeError(f"Unclosed frontmatter in {path}")
+    return metadata, lines[index + 1 :]
+
+
+def table_widths(column_count: int) -> list[float]:
+    if column_count == 2:
+        return [CONTENT_WIDTH * 0.34, CONTENT_WIDTH * 0.66]
+    if column_count == 3:
+        return [CONTENT_WIDTH * 0.26, CONTENT_WIDTH * 0.34, CONTENT_WIDTH * 0.40]
+    return [CONTENT_WIDTH / column_count] * column_count
+
+
+def markdown_story(lines: list[str], style: dict[str, ParagraphStyle]) -> list:
+    story: list = []
+    index = 0
+    while index < len(lines):
+        raw = lines[index]
+        stripped = raw.strip()
+        if not stripped:
+            story.append(Spacer(1, 2.5))
+            index += 1
+            continue
+        if stripped == "<!-- pagebreak -->":
+            story.append(PageBreak())
+            index += 1
+            continue
+        if stripped.startswith("```"):
+            code_lines: list[str] = []
+            index += 1
+            while index < len(lines) and not lines[index].strip().startswith("```"):
+                code_lines.append(lines[index].rstrip())
+                index += 1
+            if index >= len(lines):
+                raise RuntimeError("Unclosed code block")
+            code_html = "<br/>".join(html.escape(line or " ") for line in code_lines)
+            block = Table([[Paragraph(code_html, style["code"])]], colWidths=[CONTENT_WIDTH])
+            block.setStyle(TableStyle([
+                ("BACKGROUND", (0, 0), (-1, -1), NAVY),
+                ("BOX", (0, 0), (-1, -1), 0.8, BLUE),
+                ("LEFTPADDING", (0, 0), (-1, -1), 10),
+                ("RIGHTPADDING", (0, 0), (-1, -1), 10),
+                ("TOPPADDING", (0, 0), (-1, -1), 8),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 8),
+            ]))
+            story.extend([block, Spacer(1, 6)])
+            index += 1
+            continue
+        heading = re.match(r"^(#{1,3})\s+(.+)$", stripped)
+        if heading:
+            level = len(heading.group(1))
+            story.append(Paragraph(inline_markup(heading.group(2)), style[f"h{level}"]))
+            index += 1
+            continue
+        if stripped.startswith("|"):
+            table_lines: list[str] = []
+            while index < len(lines) and lines[index].strip().startswith("|"):
+                table_lines.append(lines[index].strip())
+                index += 1
+            rows = [[cell.strip() for cell in line.strip("|").split("|")] for line in table_lines]
+            if len(rows) >= 2 and all(re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1]):
+                rows.pop(1)
+            column_count = max(len(row) for row in rows)
+            normalized = [row + [""] * (column_count - len(row)) for row in rows]
+            rendered = [
+                [Paragraph(inline_markup(cell), style["small"]) for cell in row]
+                for row in normalized
+            ]
+            table = LongTable(rendered, colWidths=table_widths(column_count), repeatRows=1)
+            table.setStyle(TableStyle([
+                ("BACKGROUND", (0, 0), (-1, 0), NAVY),
+                ("TEXTCOLOR", (0, 0), (-1, 0), colors.white),
+                ("FONTNAME", (0, 0), (-1, 0), "WorkflowBold"),
+                ("BACKGROUND", (0, 1), (-1, -1), PALE_GRAY),
+                ("GRID", (0, 0), (-1, -1), 0.45, MID_GRAY),
+                ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                ("LEFTPADDING", (0, 0), (-1, -1), 6),
+                ("RIGHTPADDING", (0, 0), (-1, -1), 6),
+                ("TOPPADDING", (0, 0), (-1, -1), 5),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+            ]))
+            story.extend([table, Spacer(1, 6)])
+            continue
+        if stripped.startswith(">"):
+            quote_lines: list[str] = []
+            while index < len(lines) and lines[index].strip().startswith(">"):
+                quote_lines.append(lines[index].strip()[1:].strip())
+                index += 1
+            value = " ".join(quote_lines)
+            color = PALE_ORANGE if "Важно" in value or "Стоп" in value else PALE_BLUE
+            callout = Table([[Paragraph(inline_markup(value), style["callout"])]], colWidths=[CONTENT_WIDTH])
+            callout.setStyle(TableStyle([
+                ("BACKGROUND", (0, 0), (-1, -1), color),
+                ("BOX", (0, 0), (-1, -1), 0.8, BLUE),
+                ("LINEBEFORE", (0, 0), (0, -1), 3, BLUE),
+                ("LEFTPADDING", (0, 0), (-1, -1), 10),
+                ("RIGHTPADDING", (0, 0), (-1, -1), 10),
+                ("TOPPADDING", (0, 0), (-1, -1), 7),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 7),
+            ]))
+            story.extend([callout, Spacer(1, 6)])
+            continue
+        if re.match(r"^-\s+", stripped):
+            items: list[ListItem] = []
+            while index < len(lines) and re.match(r"^-\s+", lines[index].strip()):
+                value = re.sub(r"^-\s+", "", lines[index].strip())
+                items.append(ListItem(Paragraph(inline_markup(value), style["body"]), leftIndent=10))
+                index += 1
+            story.append(ListFlowable(items, bulletType="bullet", leftIndent=16, bulletColor=BLUE))
+            story.append(Spacer(1, 3))
+            continue
+        if re.match(r"^\d+\.\s+", stripped):
+            items = []
+            while index < len(lines) and re.match(r"^\d+\.\s+", lines[index].strip()):
+                value = re.sub(r"^\d+\.\s+", "", lines[index].strip())
+                items.append(ListItem(Paragraph(inline_markup(value), style["body"]), leftIndent=12))
+                index += 1
+            story.append(ListFlowable(items, bulletType="1", leftIndent=18, bulletColor=BLUE))
+            story.append(Spacer(1, 3))
+            continue
+
+        paragraph_lines = [stripped]
+        index += 1
+        while index < len(lines):
+            candidate = lines[index].strip()
+            if (
+                not candidate
+                or candidate == "<!-- pagebreak -->"
+                or candidate.startswith(("#", "|", ">", "```", "- "))
+                or re.match(r"^\d+\.\s+", candidate)
+            ):
+                break
+            paragraph_lines.append(candidate)
+            index += 1
+        story.append(Paragraph(inline_markup(" ".join(paragraph_lines)), style["body"]))
+    return story
+
+
+def draw_page(canvas_obj: canvas.Canvas, doc: SimpleDocTemplate, title: str) -> None:
+    canvas_obj.saveState()
+    canvas_obj.setStrokeColor(MID_GRAY)
+    canvas_obj.setLineWidth(0.35)
+    canvas_obj.line(LEFT, PAGE_HEIGHT - 13 * mm, PAGE_WIDTH - RIGHT, PAGE_HEIGHT - 13 * mm)
+    canvas_obj.setFont("WorkflowBody", 7)
+    canvas_obj.setFillColor(MUTED)
+    canvas_obj.drawString(LEFT, PAGE_HEIGHT - 10 * mm, title[:74])
+    canvas_obj.drawRightString(PAGE_WIDTH - RIGHT, PAGE_HEIGHT - 10 * mm, f"beta.11 | {PACKAGE_VERSION}")
+    canvas_obj.line(LEFT, 11 * mm, PAGE_WIDTH - RIGHT, 11 * mm)
+    canvas_obj.drawString(LEFT, 7 * mm, "Codex Workflow V2")
+    canvas_obj.drawRightString(PAGE_WIDTH - RIGHT, 7 * mm, f"Страница {doc.page}")
+    canvas_obj.restoreState()
+
+
+def build_pdf(source_path: Path, output_path: Path) -> None:
+    metadata, lines = parse_source(source_path)
+    required = ("title", "subtitle", "part", "document_version", "date", "subject")
+    missing = [key for key in required if key not in metadata]
+    if missing:
+        raise RuntimeError(f"Missing metadata in {source_path}: {', '.join(missing)}")
+    style = styles()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    doc = SimpleDocTemplate(
+        str(output_path),
+        pagesize=A4,
+        leftMargin=LEFT,
+        rightMargin=RIGHT,
+        topMargin=TOP,
+        bottomMargin=BOTTOM,
+        title=metadata["title"],
+        author="Codex Workflow Maintainers",
+        subject=metadata["subject"],
+        creator="codex-workflow-v2 deterministic PDF generator",
+        pageCompression=1,
+    )
+    title_block = [
+        Spacer(1, 28 * mm),
+        Paragraph(inline_markup(metadata["part"].upper()), style["part"]),
+        Paragraph(inline_markup(metadata["title"]), style["title"]),
+        Paragraph(inline_markup(metadata["subtitle"]), style["subtitle"]),
+        Spacer(1, 8 * mm),
+        Table(
+            [[
+                Paragraph(
+                    inline_markup(
+                        f"Документ {metadata['document_version']} | Пакет {PACKAGE_VERSION} | {metadata['date']}"
+                    ),
+                    style["callout"],
+                )
+            ]],
+            colWidths=[CONTENT_WIDTH],
+            style=TableStyle([
+                ("BACKGROUND", (0, 0), (-1, -1), PALE_BLUE),
+                ("BOX", (0, 0), (-1, -1), 0.8, BLUE),
+                ("LEFTPADDING", (0, 0), (-1, -1), 10),
+                ("RIGHTPADDING", (0, 0), (-1, -1), 10),
+                ("TOPPADDING", (0, 0), (-1, -1), 8),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 8),
+            ]),
+        ),
+        Spacer(1, 55 * mm),
+        Paragraph(
+            inline_markup("Целевая среда: Codex App, один пользователь, одна машина, exact project-local package."),
+            style["small"],
+        ),
+        PageBreak(),
+    ]
+    story = title_block + markdown_story(lines, style)
+    doc.build(
+        story,
+        onFirstPage=lambda canv, current_doc: draw_page(canv, current_doc, metadata["title"]),
+        onLaterPages=lambda canv, current_doc: draw_page(canv, current_doc, metadata["title"]),
+        canvasmaker=InvariantCanvas,
+    )
+
+
+def sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def generate(output_dir: Path) -> None:
+    for source_name, output_name in DOCUMENTS:
+        build_pdf(SOURCE_DIR / source_name, output_dir / output_name)
+
+
+def check() -> int:
+    with tempfile.TemporaryDirectory(prefix="codex-workflow-pdf-") as directory:
+        candidate_dir = Path(directory)
+        generate(candidate_dir)
+        stale = []
+        for _, output_name in DOCUMENTS:
+            tracked = OUTPUT_DIR / output_name
+            candidate = candidate_dir / output_name
+            if not tracked.is_file() or tracked.read_bytes() != candidate.read_bytes():
+                stale.append({
+                    "file": str(tracked.relative_to(ROOT)),
+                    "trackedSha256": sha256(tracked) if tracked.is_file() else None,
+                    "generatedSha256": sha256(candidate),
+                })
+        print(json.dumps({"ok": not stale, "packageVersion": PACKAGE_VERSION, "stale": stale}, ensure_ascii=False))
+        return 0 if not stale else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="fail when tracked PDFs differ from deterministic output")
+    args = parser.parse_args()
+    register_fonts()
+    if args.check:
+        return check()
+    generate(OUTPUT_DIR)
+    print(json.dumps({
+        "ok": True,
+        "packageVersion": PACKAGE_VERSION,
+        "outputs": [str((OUTPUT_DIR / output).relative_to(ROOT)) for _, output in DOCUMENTS],
+    }, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())