okstra 0.1.0

package/runtime/validators/validate-schedule.py

@@ -0,0 +1,665 @@
+#!/usr/bin/env python3
+"""
+Validate that an okstra schedule Markdown file conforms to the Section Contract
+defined in skills/okstra-schedule/SKILL.md.
+
+Usage:
+    python3 validators/validate-schedule.py <path-to-schedule.md>
+
+Exits 0 if compliant, 1 with a list of violations otherwise. Intended to be
+called by the okstra-schedule skill (self-validation step) and by humans /
+hooks before committing a schedule.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REQUIRED_SECTIONS_IN_ORDER: list[str] = [
+    "## At a Glance",
+    "## Executive Summary",
+    "## Task Dependency Graph",
+    "## Phase 1: Critical Fixes",
+    "## Phase 2: Enhancements",
+    "## Phase 3: Architecture",
+    "## Execution Priority Matrix",
+    "## Cross-Task Dependencies & Shared Concerns",
+    "## Risk Mitigation Strategy",
+    "## Recommended Immediate Actions",
+]
+
+OPTIONAL_GRAPHIC_SECTIONS_IN_ORDER: list[str] = [
+    "## Gantt Chart",
+]
+
+REQUIRED_EXEC_SUMMARY_SUBSECTION = "### Effort Sizing 기준"
+
+REQUIRED_TASK_FIELDS = [
+    "**Category**",
+    "**Priority**",
+    "**Effort**",
+    "**Status**",
+    "**Risk**",
+    "**Scope**",
+    "**Repo**",
+]
+
+FORBIDDEN_HEADINGS_RE = re.compile(
+    r"^##\s+("
+    # Korean translations of mandatory/optional headings
+    r"전체\s*개요|요약(\s*\(Executive\s*Summary\))?|단위\s*간\s*의존성\s*그래프|"
+    r"단위\s*간\s*의존성\s*&\s*공유\s*사항|위험\s*완화\s*전략|즉시\s*권장\s*액션|"
+    r"Gantt\s*다이어그램.*|누적\s*일정표.*|Cumulative\s*Timeline.*|Effort-to-Day\s*매핑.*|"
+    # French translations of mandatory/optional headings (require French-distinctive
+    # tokens — never match the canonical English forms like `Phase 3: Architecture`)
+    r"Vue\s*d['’]?Ensemble|Résumé\s*Exécutif|"
+    r"Graphe\s*de\s*Dépendances.*|Diagramme\s*de\s*Gantt.*|"
+    r"Calendrier\s*Cumulé.*|Référentiel\s*Effort-to-Day.*|"
+    r"Dépendances\s*Inter-Tâches.*|Stratégie\s*d['’]?Atténuation.*|"
+    r"Stratégie\s*de\s*Mitigation.*|Actions\s*Immédiates\s*Recommandées|"
+    r"Actions\s*Recommandées\s*Immédiates|Phase\s*\d+\s*:\s*Correctifs\s*Critiques.*|"
+    r"Phase\s*\d+\s*:\s*Améliorations|Phase\s*\d+\s*:\s*Architecture\s*\(Volumes.*|"
+    r"Phase\s*\d+\s*:\s*Extension.*"
+    r")\s*$",
+    re.MULTILINE,
+)
+
+FORBIDDEN_FRENCH_BODY_RE = re.compile(
+    # Require accented forms only — plain ASCII variants would clash with
+    # legitimate English (`Detail`, `Repo`, `Category`).
+    r"(Charge\s+estimée|Catégorie\s*\||Priorité\s*\||Risque\s*\||Dépôt\s*\||Détail\s*\|)"
+)
+
+# Allowed enum values for At a Glance table cells. Cell text is normalized
+# (strip + collapse spaces) before matching.
+ALLOWED_EFFORT = {"S", "M", "L", "XL", "XXL"}
+ALLOWED_PRIORITY = {"P0", "P1", "P2", "P3"}
+ALLOWED_RISK = {"Very Low", "Low", "Medium", "Med-High", "High"}
+ALLOWED_PHASE = {"1", "2", "3"}
+
+# Per-task block sub-section labels in REQUIRED order. Each label is matched
+# at the start of a line as `**Label**:` or as a `####` heading for the last.
+PER_TASK_SUBSECTIONS_IN_ORDER = [
+    "**Problem**:",
+    "**Solution**:",
+    "**Work Breakdown**:",
+    "**Verification Commands**:",
+    "**Rollback**:",
+]
+
+# Forbidden graph-DSL fences inside `## Gantt Chart` (the only ASCII section).
+FORBIDDEN_GANTT_DSL_FENCES = (
+    "```mermaid",
+    "```gantt",
+    "```plantuml",
+    "```graphviz",
+    "```dot",
+)
+
+# Calendar-date / weekday tokens that must NOT appear in the Gantt axis line.
+CALENDAR_DATE_RE = re.compile(
+    r"\b(20\d{2}-\d{2}-\d{2}"
+    r"|\d{4}/\d{2}/\d{2}"
+    r"|Mon|Tue|Wed|Thu|Fri|Sat|Sun"
+    r"|월요일|화요일|수요일|목요일|금요일|토요일|일요일"
+    r"|오늘\s*\+\s*\d+)\b"
+)
+
+DAYS_TOTAL_RE = re.compile(
+    r"\*\*총\s*\d+개\s*task\s*/\s*예상\s*소요:\s*"
+    r"\d+(?:\.\d+)?\s*~\s*\d+(?:\.\d+)?\s*days?\s*\(Effort\s*합산\)\*\*"
+)
+
+# Opaque cross-document identifiers from internal report formats.
+# These mean nothing to a client reading the schedule alone, so they MUST
+# either be inlined in plain prose (Form A) or resolved in `## Glossary`
+# (Form B).
+#
+# Patterns that are TASK-ID-shaped (`FC-5`, `UC-3`, etc.) are detected
+# generically as `<2+ uppercase letters>-<digits>` and then filtered against
+# the TASK-ID whitelist (extracted from At a Glance) so legitimate task
+# references (`DEV-1234`, `MOBILE-42`) pass through.
+OPAQUE_DASHED_CODE_RE = re.compile(r"\b([A-Z]{1,5})-(\d+)\b")
+
+# Decision-item letter codes (`A1`, `B2`, `C3`, `D4`). These represent
+# approval/decision items in source reports and are forbidden in the schedule
+# at all — the glossary cannot whitewash them.
+DECISION_ITEM_RE = re.compile(r"\b([A-D])(\d{1,2})\b")
+DECISION_ITEM_ALLOWLIST = set()  # nothing legitimate matches this shape
+
+# Milestone codes (`M1`, `M2`, …). Allowed in body only if resolved in `## Glossary`.
+MILESTONE_RE = re.compile(r"\bM(\d+)\b")
+
+
+def validate(path: Path) -> list[str]:
+    if not path.exists():
+        return [f"file not found: {path}"]
+
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+    violations: list[str] = []
+
+    # 1. Title must end with "— Work Schedule"
+    title_line = next((ln for ln in lines if ln.startswith("# ")), "")
+    if not title_line:
+        violations.append("missing top-level title (# …)")
+    elif not title_line.rstrip().endswith("— Work Schedule"):
+        violations.append(
+            f'title must end with "— Work Schedule"; got: {title_line!r}'
+        )
+
+    # 2. Metadata header lines required
+    if not re.search(r"^>\s*Generated:.*\|\s*Project:.*\|\s*Task Group:", text, re.MULTILINE):
+        violations.append(
+            "missing `> Generated: <…> | Project: <…> | Task Group: <…>` metadata line"
+        )
+    if not re.search(r"^>\s*Source:\s*okstra\b", text, re.MULTILINE):
+        violations.append("missing `> Source: okstra <mode> …` metadata line")
+
+    # 3. Required sections present and in order. The optional `## Gantt Chart`
+    #    section, if present, MUST sit between Task Dependency Graph and
+    #    Phase 1: Critical Fixes.
+    section_positions: dict[str, int] = {}
+    optional_positions: dict[str, int] = {}
+    for idx, line in enumerate(lines):
+        stripped = line.rstrip()
+        if stripped in REQUIRED_SECTIONS_IN_ORDER and stripped not in section_positions:
+            section_positions[stripped] = idx
+        elif (
+            stripped in OPTIONAL_GRAPHIC_SECTIONS_IN_ORDER
+            and stripped not in optional_positions
+        ):
+            optional_positions[stripped] = idx
+
+    missing = [s for s in REQUIRED_SECTIONS_IN_ORDER if s not in section_positions]
+    for s in missing:
+        violations.append(f"missing required section: {s!r}")
+
+    if not missing:
+        ordered_actual = sorted(section_positions, key=lambda s: section_positions[s])
+        if ordered_actual != REQUIRED_SECTIONS_IN_ORDER:
+            violations.append(
+                "required sections are out of order. expected:\n  "
+                + "\n  ".join(REQUIRED_SECTIONS_IN_ORDER)
+                + "\nactual:\n  "
+                + "\n  ".join(ordered_actual)
+            )
+
+        # Optional sections must sit between Task Dependency Graph and Phase 1
+        dep_idx = section_positions["## Task Dependency Graph"]
+        phase1_idx = section_positions["## Phase 1: Critical Fixes"]
+        for opt_name, opt_idx in optional_positions.items():
+            if not (dep_idx < opt_idx < phase1_idx):
+                violations.append(
+                    f"optional section {opt_name!r} is misplaced — must appear between "
+                    "'## Task Dependency Graph' and '## Phase 1: Critical Fixes'"
+                )
+    # 4. Executive Summary subsection
+    if REQUIRED_EXEC_SUMMARY_SUBSECTION not in text:
+        violations.append(
+            f"missing subsection {REQUIRED_EXEC_SUMMARY_SUBSECTION!r} inside Executive Summary"
+        )
+
+    # 5. Forbidden translated/extra headings
+    for match in FORBIDDEN_HEADINGS_RE.finditer(text):
+        violations.append(
+            f"forbidden heading (translated or extra): {match.group(0).strip()!r} "
+            "— see SKILL Section Contract"
+        )
+
+    # 6. Forbidden French body labels (per-task field labels in French, etc.)
+    if FORBIDDEN_FRENCH_BODY_RE.search(text):
+        violations.append(
+            "found French structural label (e.g. 'Charge estimée', 'Catégorie |', "
+            "'Détail |'); per-task tables MUST use English field labels "
+            "(**Category**, **Priority**, **Risk**, **Repo**, …)"
+        )
+
+    # 7. Per-task field labels — every per-task heading (### N-i.) MUST be followed
+    #    (within the next 60 lines) by all required field labels.
+    task_heading_re = re.compile(r"^###\s+\d+-\d+\.\s+", re.MULTILINE)
+    for m in task_heading_re.finditer(text):
+        start = m.start()
+        block_end = start
+        # find the next ### or ## heading
+        next_h = re.search(r"^(##\s|###\s)", text[start + len(m.group(0)):], re.MULTILINE)
+        block = text[start: start + len(m.group(0)) + (next_h.start() if next_h else len(text))]
+        for label in REQUIRED_TASK_FIELDS:
+            if label not in block:
+                heading_line = text[start: text.find("\n", start)]
+                violations.append(
+                    f"per-task block {heading_line.strip()!r} missing required field {label!r}"
+                )
+
+    # 8. Item table header literal
+    if "| Item | Detail |" not in text and any(
+        h.startswith("## Phase") for h in section_positions
+    ):
+        # only flag if there is at least one phase with a per-task block
+        if task_heading_re.search(text):
+            violations.append(
+                "per-task tables must use header `| Item | Detail |` (literal English)"
+            )
+
+    # 9. Checklist tables MUST carry a leading `Done` column with markdown
+    #    checkboxes. The check is a header-presence test — we require the
+    #    canonical header literal to appear in the section's text block.
+    checklist_header_specs = [
+        (
+            "## Execution Priority Matrix",
+            ["| Priority | Task | Effort | Risk | Next Action |"],
+            "Execution Priority Matrix table must use header "
+            "`| Priority | Task | Effort | Risk | Next Action |` "
+            "(client-facing schedule — no Done/Ready/Blocking columns)",
+        ),
+    ]
+    for section_name, expected_substrings, message in checklist_header_specs:
+        if section_name not in section_positions:
+            continue
+        start = section_positions[section_name]
+        # find next `## ` heading or end of file
+        next_h = re.search(r"^##\s", "\n".join(lines[start + 1:]), re.MULTILINE)
+        end = (start + 1 + (next_h.start() if next_h else len(text))) if next_h else len(lines)
+        section_text = "\n".join(lines[start:end])
+        if not any(sub in section_text for sub in expected_substrings):
+            violations.append(message)
+
+    # Forbid client-leaking artifacts: Consolidated User Decision Checklist /
+    # per-task 사용자 확인 필요 항목 — schedule is for client delivery, blocking
+    # / approval items must NOT surface.
+    if "## Consolidated User Decision Checklist" in text:
+        violations.append(
+            "`## Consolidated User Decision Checklist` is forbidden — schedule "
+            "is a client-facing work plan; blocking/approval items belong in "
+            "internal task reports, not the schedule"
+        )
+    if re.search(r"^####\s+사용자\s*확인\s*필요\s*항목\s*$", text, re.MULTILINE):
+        violations.append(
+            "per-task `#### 사용자 확인 필요 항목` is forbidden in schedule — "
+            "client-facing document; surface confirmation items in the source "
+            "report instead"
+        )
+
+    # 10. Days total format inside At a Glance: `**총 N개 task / 예상 소요: X.X ~ Y.Y days (Effort 합산)**`
+    if "## At a Glance" in section_positions:
+        start = section_positions["## At a Glance"]
+        rest = "\n".join(lines[start + 1:])
+        next_h = re.search(r"^##\s", rest, re.MULTILINE)
+        body = rest[: next_h.start()] if next_h else rest
+        if not DAYS_TOTAL_RE.search(body):
+            violations.append(
+                "At a Glance must contain a totals line matching "
+                "`**총 N개 task / 예상 소요: X.X ~ Y.Y days (Effort 합산)**`"
+            )
+
+        # 11. At a Glance row enum check (Effort / Priority / Risk / Phase)
+        for row in re.finditer(
+            r"^\|\s*\d+\s*\|.*$", body, re.MULTILINE
+        ):
+            cells = [c.strip() for c in row.group(0).strip().strip("|").split("|")]
+            # header: # | Task ID | Title | Category | Priority | Effort | Days | taskType | Risk | Phase
+            if len(cells) < 10:
+                continue
+            priority = re.sub(r"\*+", "", cells[4]).strip()
+            effort = re.sub(r"\*+", "", cells[5]).strip()
+            # `Effort` cell may contain extra hint like `L (5-15 files)`; pick the leading token
+            effort_token = effort.split()[0] if effort else ""
+            risk = re.sub(r"\*+", "", cells[8]).strip()
+            phase = re.sub(r"\*+", "", cells[9]).strip()
+            task_id = cells[1]
+            if priority and priority not in ALLOWED_PRIORITY:
+                violations.append(
+                    f"At a Glance row for {task_id!r}: Priority {priority!r} "
+                    f"not in allowed set {sorted(ALLOWED_PRIORITY)}"
+                )
+            if effort_token and effort_token not in ALLOWED_EFFORT:
+                violations.append(
+                    f"At a Glance row for {task_id!r}: Effort {effort_token!r} "
+                    f"not in allowed set {sorted(ALLOWED_EFFORT)}"
+                )
+            if risk and risk not in ALLOWED_RISK:
+                violations.append(
+                    f"At a Glance row for {task_id!r}: Risk {risk!r} "
+                    f"not in allowed set {sorted(ALLOWED_RISK)}"
+                )
+            if phase and phase not in ALLOWED_PHASE:
+                violations.append(
+                    f"At a Glance row for {task_id!r}: Phase {phase!r} "
+                    f"not in allowed set {sorted(ALLOWED_PHASE)}"
+                )
+
+    # 12. Gantt Chart content checks — forbid DSL fences, force relative-day axis
+    if "## Gantt Chart" in optional_positions:
+        start = optional_positions["## Gantt Chart"]
+        rest = "\n".join(lines[start + 1:])
+        next_h = re.search(r"^##\s", rest, re.MULTILINE)
+        body = rest[: next_h.start()] if next_h else rest
+
+        for forbidden in FORBIDDEN_GANTT_DSL_FENCES:
+            if forbidden in body:
+                violations.append(
+                    f"`## Gantt Chart` contains forbidden DSL fence {forbidden!r} — "
+                    "only plain ``` (no language tag) ASCII blocks are allowed"
+                )
+
+        # Detect any ``` fence with a language hint inside the Gantt section.
+        for m in re.finditer(r"^```([^\s`]+)\s*$", body, re.MULTILINE):
+            lang = m.group(1)
+            if lang.lower() not in {""}:
+                violations.append(
+                    f"`## Gantt Chart` fence has language tag ```{lang}``` — "
+                    "fence MUST be plain ``` with no language hint"
+                )
+
+        # Calendar-date / weekday axis check on the body.
+        cal_match = CALENDAR_DATE_RE.search(body)
+        if cal_match:
+            violations.append(
+                f"`## Gantt Chart` axis contains calendar/weekday token "
+                f"{cal_match.group(0)!r} — use relative day-counts only "
+                "(`Day 1`, `J1`, …)"
+            )
+
+    # 12b. Task Dependency Graph content check.
+    if "## Task Dependency Graph" in section_positions:
+        start = section_positions["## Task Dependency Graph"]
+        rest = "\n".join(lines[start + 1:])
+        next_h = re.search(r"^##\s", rest, re.MULTILINE)
+        body = (rest[: next_h.start()] if next_h else rest).strip()
+
+        no_data_marker = "_의존 정보 없음_"
+        fence_match = re.search(r"^```([^\n]*)\n(.*?)^```\s*$", body, re.MULTILINE | re.DOTALL)
+
+        if not body:
+            violations.append(
+                "`## Task Dependency Graph` is empty — must contain either "
+                f"`{no_data_marker}` or an adjacency-list fenced block"
+            )
+        elif fence_match:
+            lang = fence_match.group(1).strip()
+            inner = fence_match.group(2)
+            if lang:
+                violations.append(
+                    f"`## Task Dependency Graph` fence has language tag ```{lang}``` — "
+                    "fence MUST be plain ``` with no language hint"
+                )
+            for forbidden in FORBIDDEN_GANTT_DSL_FENCES:
+                if forbidden in body:
+                    violations.append(
+                        f"`## Task Dependency Graph` contains forbidden DSL fence "
+                        f"{forbidden!r} — only ASCII adjacency lines are allowed"
+                    )
+            adjacency_re = re.compile(
+                r"^[A-Za-z][A-Za-z0-9_-]*\s*->\s*"
+                r"[A-Za-z][A-Za-z0-9_-]*(?:\s*,\s*[A-Za-z][A-Za-z0-9_-]*)*\s*$"
+            )
+            for line_no, raw in enumerate(inner.splitlines(), start=1):
+                ln = raw.rstrip()
+                if not ln.strip():
+                    continue
+                if ln.lstrip().startswith("#"):
+                    continue
+                if "→" in ln:
+                    violations.append(
+                        f"`## Task Dependency Graph` line {line_no} uses Unicode '→' "
+                        "— use ASCII '->' only"
+                    )
+                    continue
+                if not adjacency_re.match(ln.strip()):
+                    violations.append(
+                        f"`## Task Dependency Graph` line {line_no} is not a valid "
+                        "adjacency line: expected `<TASK-ID> -> <TASK-ID>[, <TASK-ID>]*`; "
+                        f"got {ln.strip()!r}"
+                    )
+        elif no_data_marker not in body:
+            violations.append(
+                "`## Task Dependency Graph` must be either the literal "
+                f"`{no_data_marker}` or a plain ``` fenced adjacency-list "
+                "block — free-form prose is not allowed"
+            )
+
+    # 13. Per-task block sub-section order check
+    task_heading_re = re.compile(r"^###\s+\d+-\d+\.\s+", re.MULTILINE)
+    headings = list(task_heading_re.finditer(text))
+    for idx, m in enumerate(headings):
+        block_start = m.start()
+        block_end = headings[idx + 1].start() if idx + 1 < len(headings) else len(text)
+        # also stop at the next `## ` heading. Skip past the current line first
+        # so the heading itself ('### N-i. …') doesn't match `^##\s` from offset 1.
+        body_start = text.find("\n", block_start) + 1
+        next_phase_re = re.compile(r"^##\s", re.MULTILINE)
+        np = next_phase_re.search(text, body_start, block_end)
+        if np:
+            block_end = np.start()
+        block = text[block_start:block_end]
+        heading_line = text[block_start : text.find("\n", block_start)].strip()
+
+        # Skip blocks marked as NEEDS-OKSTRA-RUN or PARSE-ERROR — these are
+        # intentionally partial.
+        if "[NEEDS-OKSTRA-RUN]" in block or "[PARSE-ERROR" in block:
+            continue
+
+        last_pos = -1
+        for label in PER_TASK_SUBSECTIONS_IN_ORDER:
+            pos = block.find(label)
+            if pos == -1:
+                violations.append(
+                    f"per-task block {heading_line!r} missing required "
+                    f"sub-section {label!r}"
+                )
+                last_pos = -1  # avoid cascading order errors after a missing one
+                break
+            if pos < last_pos:
+                violations.append(
+                    f"per-task block {heading_line!r}: sub-section {label!r} "
+                    "appears out of required order "
+                    "(Problem → Solution → Work Breakdown → Verification Commands "
+                    "→ Rollback → 사용자 확인 필요 항목)"
+                )
+                break
+            last_pos = pos
+
+    # Recommended Immediate Actions must be a bullet list (no numbered list,
+    # no checkboxes — this is a client-facing work plan, not an internal todo).
+    if "## Recommended Immediate Actions" in section_positions:
+        start = section_positions["## Recommended Immediate Actions"]
+        rest = "\n".join(lines[start + 1:])
+        next_h = re.search(r"^##\s", rest, re.MULTILINE)
+        body = rest[: next_h.start()] if next_h else rest
+        body = body.strip()
+        if body and not re.search(r"^-\s+\S", body, re.MULTILINE):
+            violations.append(
+                "Recommended Immediate Actions must be a markdown bullet list "
+                "(`- <action>`); numbered lists are forbidden"
+            )
+        if re.search(r"^-\s+\[[ xX]\]\s", body, re.MULTILINE):
+            violations.append(
+                "Recommended Immediate Actions must not use checkbox items "
+                "(`- [ ] …`) — schedule is a client-facing plan, not an "
+                "internal todo list"
+            )
+
+    # 14. Self-contained identifiers — opaque cross-doc codes (FC-N, UC-N,
+    # M-N, A1, B2, …) must be either inlined as prose (Form A) or resolved in
+    # `## Glossary` (Form B). Decision-item letters (A1-D99) are forbidden
+    # outright.
+    code_violations = _check_self_contained_identifiers(text, lines, section_positions)
+    violations.extend(code_violations)
+
+    return violations
+
+
+def _strip_code_fences(text: str) -> str:
+    """Remove ``` fenced blocks so opaque-id regex doesn't false-positive
+    on shell commands, file paths, etc."""
+    return re.sub(r"```.*?```", "", text, flags=re.DOTALL)
+
+
+def _extract_task_id_whitelist(text: str, section_positions: dict[str, int],
+                                lines: list[str]) -> set[str]:
+    """Pull TASK-IDs from the At a Glance table column 2."""
+    whitelist: set[str] = set()
+    if "## At a Glance" not in section_positions:
+        return whitelist
+    start = section_positions["## At a Glance"]
+    rest = "\n".join(lines[start + 1:])
+    next_h = re.search(r"^##\s", rest, re.MULTILINE)
+    body = rest[: next_h.start()] if next_h else rest
+    for row in re.finditer(r"^\|\s*\d+\s*\|.*$", body, re.MULTILINE):
+        cells = [c.strip() for c in row.group(0).strip().strip("|").split("|")]
+        if len(cells) >= 2 and re.fullmatch(r"[A-Z][A-Z0-9_-]*", cells[1]):
+            whitelist.add(cells[1])
+    return whitelist
+
+
+def _extract_glossary(text: str) -> tuple[bool, set[str], int]:
+    """Return (present, code_set, header_line_index).
+
+    A `## Glossary` section is recognized by the literal heading. Codes are
+    extracted from the first column of `| Code | Description |` rows.
+    """
+    m = re.search(r"^##\s+Glossary\s*$", text, re.MULTILINE)
+    if not m:
+        return False, set(), -1
+    after = text[m.end():]
+    next_h = re.search(r"^##\s", after, re.MULTILINE)
+    body = after[: next_h.start()] if next_h else after
+    codes: set[str] = set()
+    for row in re.finditer(r"^\|\s*([^|\s][^|]*?)\s*\|.*\|.*$", body, re.MULTILINE):
+        cell = row.group(1).strip()
+        # skip header / separator rows
+        if cell.lower() in {"code", "---", ":---", "---:"} or set(cell) <= {"-", ":"}:
+            continue
+        if cell:
+            codes.add(cell)
+    return True, codes, m.start()
+
+
+def _check_self_contained_identifiers(text: str, lines: list[str],
+                                       section_positions: dict[str, int]) -> list[str]:
+    """Enforce schedule self-containment — see SKILL §"Audience"."""
+    violations: list[str] = []
+
+    glossary_present, glossary_codes, glossary_pos = _extract_glossary(text)
+
+    # Body excludes Glossary section and code fences.
+    if glossary_present:
+        body_text = text[:glossary_pos]
+    else:
+        body_text = text
+    body_text = _strip_code_fences(body_text)
+
+    task_ids = _extract_task_id_whitelist(text, section_positions, lines)
+
+    # Decision-item letters: forbidden everywhere (not just unresolved).
+    seen_decision: set[str] = set()
+    for m in DECISION_ITEM_RE.finditer(body_text):
+        code = m.group(0)
+        if code in seen_decision:
+            continue
+        seen_decision.add(code)
+        violations.append(
+            f"forbidden decision-item code {code!r} in schedule body — "
+            "decision/approval items must not appear in a client-facing "
+            "schedule (see SKILL §'Audience'); inline the underlying work "
+            "as prose or drop the reference"
+        )
+
+    # Dashed codes: <2+ uppercase>-<digits>. Filter out TASK-IDs.
+    seen_dashed: set[str] = set()
+    for m in OPAQUE_DASHED_CODE_RE.finditer(body_text):
+        code = m.group(0)
+        if code in task_ids:
+            continue
+        if code in seen_dashed:
+            continue
+        seen_dashed.add(code)
+        if glossary_present and code in glossary_codes:
+            continue
+        if glossary_present:
+            violations.append(
+                f"opaque code {code!r} appears in body but is missing from "
+                "`## Glossary` — every opaque identifier must be resolved "
+                "in the glossary (Form B) or inlined as prose (Form A)"
+            )
+        else:
+            violations.append(
+                f"opaque cross-document code {code!r} found in schedule body "
+                "— schedule must be self-contained. Either inline the item "
+                "content as prose (Form A) or add a `## Glossary` section at "
+                "document bottom resolving every code (Form B). See SKILL "
+                "§'Audience'"
+            )
+
+    # Milestone-style codes (M1, M2, …).
+    seen_milestone: set[str] = set()
+    for m in MILESTONE_RE.finditer(body_text):
+        code = m.group(0)
+        if code in seen_milestone:
+            continue
+        seen_milestone.add(code)
+        if glossary_present and code in glossary_codes:
+            continue
+        if glossary_present:
+            violations.append(
+                f"milestone code {code!r} appears in body but is missing "
+                "from `## Glossary` — resolve it or inline as prose"
+            )
+        else:
+            violations.append(
+                f"opaque milestone code {code!r} found in schedule body — "
+                "either inline the milestone description as prose (Form A) "
+                "or add a `## Glossary` section (Form B)"
+            )
+
+    # Glossary placement: must sit AFTER `## Recommended Immediate Actions`.
+    if glossary_present and "## Recommended Immediate Actions" in section_positions:
+        actions_idx = section_positions["## Recommended Immediate Actions"]
+        # Re-locate glossary by line index for ordering check.
+        glossary_line_idx = next(
+            (i for i, ln in enumerate(lines) if ln.rstrip() == "## Glossary"), -1
+        )
+        if 0 <= glossary_line_idx <= actions_idx:
+            violations.append(
+                "`## Glossary` must be the last `##` section, placed AFTER "
+                "`## Recommended Immediate Actions`"
+            )
+
+    # Glossary header literal check.
+    if glossary_present:
+        gloss_section = text[glossary_pos:]
+        next_h = re.search(r"^##\s", gloss_section[3:], re.MULTILINE)
+        gloss_body = gloss_section[: next_h.start() + 3] if next_h else gloss_section
+        if "| Code | Description |" not in gloss_body:
+            violations.append(
+                "`## Glossary` table must use header `| Code | Description |` "
+                "(literal English)"
+            )
+
+    return violations
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print(f"usage: {argv[0]} <path-to-schedule.md>", file=sys.stderr)
+        return 2
+    path = Path(argv[1])
+    violations = validate(path)
+    if not violations:
+        print(f"OK: {path} conforms to okstra-schedule Section Contract")
+        return 0
+    print(f"FAIL: {path}", file=sys.stderr)
+    for v in violations:
+        print(f"  - {v}", file=sys.stderr)
+    print(
+        "\nFix per skills/okstra-schedule/SKILL.md "
+        "(Section Contract).",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))