codex-workflow-v2 2.0.0-beta.10 → 2.0.0-beta.12

package/schemas/review-result.schema.json

@@ -22,7 +22,23 @@
           "requirement": { "type": ["string", "null"] },
           "summary": { "type": "string", "minLength": 1 },
           "evidence": { "type": "string", "minLength": 1 },
-          "requiredAction": { "type": "string", "minLength": 1 }
+          "requiredAction": { "type": "string", "minLength": 1 },
+          "route": { "enum": ["fix", "replan"] },
+          "planConflict": {
+            "anyOf": [
+              { "type": "null" },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["planClause", "whyFixCannotFit", "minimalPlanChange"],
+                "properties": {
+                  "planClause": { "type": "string", "minLength": 1 },
+                  "whyFixCannotFit": { "type": "string", "minLength": 1 },
+                  "minimalPlanChange": { "type": "string", "minLength": 1 }
+                }
+              }
+            ]
+          }
         }
       }
     }

package/schemas/step-review-event.schema.json

@@ -34,6 +34,21 @@
     "eventType": { "enum": ["pending", "review-recorded", "attestation-verified"] },
     "decision": { "enum": ["pending", "passed", "failed", "unverified"] },
     "reviewerAttestationHash": { "$ref": "#/$defs/nullableHash64" },
+    "remediationRoute": { "enum": ["fix", "replan", null] },
+    "planConflicts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["findingId", "planClause", "whyFixCannotFit", "minimalPlanChange"],
+        "properties": {
+          "findingId": { "type": "string", "minLength": 1 },
+          "planClause": { "type": "string", "minLength": 1 },
+          "whyFixCannotFit": { "type": "string", "minLength": 1 },
+          "minimalPlanChange": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
     "previousEventHash": { "$ref": "#/$defs/nullableHash64" },
     "recordedAt": { "type": "string", "format": "date-time" },
     "eventHash": { "$ref": "#/$defs/hash64" }

package/schemas/task-handoff-event.schema.json

@@ -45,6 +45,12 @@
     "planHash": { "$ref": "#/$defs/nullableHash64" },
     "knowledgeMapRevision": { "type": ["integer", "null"], "minimum": 1 },
     "knowledgeMapHash": { "$ref": "#/$defs/nullableHash64" },
+    "dependencyBinding": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "#/$defs/dependencyBinding" }
+      ]
+    },
     "expectedNext": { "type": "string", "minLength": 1 },
     "delegate": { "type": "string", "minLength": 1 },
     "grantId": { "type": ["string", "null"], "minLength": 1 },
@@ -94,8 +100,18 @@
   "$defs": {
     "taskId": { "type": "string", "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" },
     "hash64": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
-    "nullableHash64": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" }
-    ,"handback": {
+    "nullableHash64": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+    "dependencyBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["milestoneRevision", "membershipRevision", "milestonePlanHash"],
+      "properties": {
+        "milestoneRevision": { "type": "integer", "minimum": 1 },
+        "membershipRevision": { "type": "integer", "minimum": 1 },
+        "milestonePlanHash": { "$ref": "#/$defs/hash64" }
+      }
+    },
+    "handback": {
       "type": "object",
       "additionalProperties": false,
       "required": ["status", "mergedCommit", "planHash", "resultHash", "evidenceHash", "reviewAttestationHash", "knowledgeMapRevision", "knowledgeMapHash", "limitations", "recommendedNext"],

package/scripts/generate-pdf-docs.py

@@ -0,0 +1,513 @@
+#!/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"]
+RELEASE_LABEL = PACKAGE_VERSION.rsplit("-", 1)[-1]
+
+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"{RELEASE_LABEL} | {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())

package/scripts/run-pdf-docs.mjs

@@ -0,0 +1,62 @@
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const repositoryRoot = path.resolve(import.meta.dirname, '..');
+const generator = path.join(repositoryRoot, 'scripts', 'generate-pdf-docs.py');
+const configuredPython = process.env.CODEX_WORKFLOW_PDF_PYTHON?.trim() || null;
+const bundledPython = path.join(
+  os.homedir(),
+  '.cache',
+  'codex-runtimes',
+  'codex-primary-runtime',
+  'dependencies',
+  'python',
+  'bin',
+  'python3',
+);
+const candidates = [configuredPython, bundledPython, 'python3'].filter((value, index, values) =>
+  value && values.indexOf(value) === index,
+);
+
+let selected = null;
+const diagnostics = [];
+for (const candidate of candidates) {
+  if (path.isAbsolute(candidate) && !existsSync(candidate)) {
+    diagnostics.push({ candidate, reason: 'not-found' });
+    continue;
+  }
+  const probe = spawnSync(candidate, ['-c', 'import reportlab'], { encoding: 'utf8' });
+  if (probe.status === 0) {
+    selected = candidate;
+    break;
+  }
+  diagnostics.push({
+    candidate,
+    reason: probe.error?.code ?? 'reportlab-unavailable',
+    stderr: probe.stderr?.trim() || null,
+  });
+}
+
+if (!selected) {
+  process.stderr.write(`${JSON.stringify({
+    ok: false,
+    error: 'PDF_PYTHON_UNAVAILABLE',
+    required: 'Python 3 with reportlab 4.4.x',
+    diagnostics,
+  })}\n`);
+  process.exit(1);
+}
+
+const result = spawnSync(selected, [generator, ...process.argv.slice(2)], {
+  cwd: repositoryRoot,
+  encoding: 'utf8',
+});
+if (result.stdout) process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(result.stderr);
+if (result.error) {
+  process.stderr.write(`${JSON.stringify({ ok: false, error: result.error.message })}\n`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);