okstra 0.151.1 → 0.153.0

package/runtime/templates/reports/schedule.template.md

@@ -89,12 +89,12 @@ _none_
 Day:            1    5    10   15   20   25   30
                 |    |    |    |    |    |    |
 Phase 1
-  <TASK-ID> (<size>)           ██████          ! crit
-  <TASK-ID> (<size>)                 ████████
+  <TASK-ID>/S<stage-number>    ██████          ! crit days=<lower>~<upper>
+  <TASK-ID>/S<stage-number>          ████████  days=<lower>~<upper>
 Phase 2
-  <TASK-ID> (<size>)                         ██████░░  est
+  <TASK-ID>/S<stage-number>                  ██████░░  est days=<lower>~<upper>
 Phase 3
-  <TASK-ID> (<size>)                                  ████  (after <TASK-ID>)
+  <TASK-ID>/S<stage-number>                           ████  (after <TASK-ID>/S<stage-number>) days=<lower>~<upper>
 ```
 
 > The axis is in **relative day-counts** (Day 1 = Phase 1 start). Legend: `! crit` = critical path, `est` = estimated allocation, `█` = confirmed span, `░` = upper-bound / uncertain span.
@@ -110,7 +110,7 @@ Phase 3
 | **Category** | <category> |
 | **Priority** | <P0~P3> |
 | **Effort** | **<S/M/L/XL>** (<scope summary>) |
-| **Status** | <workStatus + currentPhase summary> |
+| **Status** | <taskType> / <currentPhase> |
 | **Risk** | <risk> |
 | **Scope** | <files / repos summary> |
 | **Repo** | <repos> |
@@ -121,9 +121,10 @@ Phase 3
 
 **Work Breakdown**:
 
-| Step | File | Action | Detail |
-|------|------|--------|--------|
-| 1 | <path> | CREATE/MODIFY/VERIFY | <detail> |
+| Stage | Title | Steps | Depends On | Days |
+|---:|---|---:|---|---:|
+| 2 | Build adapter | 3 | 1 (done) | 2.0 ~ 3.0 |
+| 3 | Wire consumer | 2 | 2 | 1.0 ~ 2.0 |
 
 **Verification Commands**:
 ```bash
@@ -183,4 +184,3 @@ _none_ <!-- or repeat per-task block -->
 |------|-------------|
 | FC-5 | Missing payment gateway timeout handling |
 -->
-

package/runtime/validators/validate-implementation-plan-stages.py

@@ -20,8 +20,13 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
         sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.md_table import split_pipe_row  # noqa: E402
+from okstra_ctl.stage_map import (  # noqa: E402
+    STAGE_MAP_HEADING,
+    StageMapError,
+    StageMapStage,
+    parse_stage_map_text,
+)
 
-STAGE_MAP_HEADING = re.compile(r"^##\s+5\.5\s+Stage\s+Map\b", re.M)
 HARD_STEP_CAP = 8
 REQUIRED_SUBSECTIONS = (
     "Carry-In",
@@ -36,15 +41,6 @@ EXIT_CONTRACT_HEADING = re.compile(r"^###\s+Stage Exit Contract\b", re.M)
 PATH_TOKEN = re.compile(r"(?:[\w.@-]+/)+[\w.@-]+")
 
 
-@dataclass
-class StageMeta:
-    stage_number: int
-    title: str
-    depends_on: List[int]
-    step_count: int
-    exit_contract_summary: str
-
-
 @dataclass
 class ValidationError:
     code: str   # S1..S11
@@ -59,51 +55,26 @@ def _check_stage_map_present(text: str) -> List[ValidationError]:
     return []
 
 
-def _parse_stage_map(text: str) -> Tuple[List[StageMeta], List[ValidationError]]:
-    m = STAGE_MAP_HEADING.search(text)
-    if not m:
-        return [], []   # S1 already reported
-    body = text[m.end():]
-    rows = []
-    for line in body.splitlines():
-        if line.startswith("##"):
-            break
-        if not line.strip().startswith("|"):
-            continue
-        cells = split_pipe_row(line)
-        if len(cells) != 5:
-            continue
-        # skip header and separator rows (all-dash of any length is covered by set check)
-        if cells[0] == "stage" or set(cells[0]) <= set("-"):
-            continue
-        try:
-            n = int(cells[0])
-        except ValueError:
-            continue
-        depends_raw = cells[2].strip()
-        if depends_raw in ("(none)", ""):
-            depends = []
-        else:
-            try:
-                depends = [int(x.strip()) for x in depends_raw.split(",") if x.strip()]
-            except ValueError:
-                # 비정수 depends_on 셀 → 행 skip (비정수 stage_number 와 동일). raw
-                # ValueError 를 흘리면 _stage_map_reject_detail·handoff 의 except
-                # PrepareError 를 우회해 traceback 으로 죽으므로, 누락된 행을 하류
-                # S2(비단조) 검사가 잡게 한다.
-                continue
-        try:
-            step_count = int(cells[3])
-        except ValueError:
-            step_count = -1
-        rows.append(StageMeta(n, cells[1], depends, step_count, cells[4]))
-    errors: List[ValidationError] = []
-    for i, r in enumerate(rows, start=1):
-        if r.stage_number != i:
-            errors.append(ValidationError("S2", r.stage_number,
-                f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}"))
-    return rows, errors
+def _parse_depends_on_cell(raw: str) -> List[int] | None:
+    """Stage numbers from schema-v2 `stageMap[].dependsOn`."""
+    value = raw.strip()
+    if value in ("(none)", ""):
+        return []
+    try:
+        return [int(x.strip()) for x in value.split(",") if x.strip()]
+    except ValueError:
+        return None
+
 
+def _stage_numbers_monotonic(
+    stages: List[StageMapStage],
+) -> List[ValidationError]:
+    return [
+        ValidationError("S2", r.stage_number,
+            f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}")
+        for i, r in enumerate(stages, start=1)
+        if r.stage_number != i
+    ]
 
 def _slice_stage_section(text: str, stage_number: int) -> str:
     """Return the body of `## 5.5.<n> Stage <n>:` up to the next stage heading."""
@@ -151,7 +122,7 @@ def _count_effective_steps(section: str) -> int:
     return len(_effective_step_rows(section))
 
 
-def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[ValidationError]:
+def _check_each_stage_section(text: str, stages: List[StageMapStage]) -> List[ValidationError]:
     errs: List[ValidationError] = []
     for s in stages:
         if not re.search(
@@ -213,7 +184,7 @@ def _exemption_reason_allowed(section: str) -> bool:
     return any(cat in reason for cat in TDD_EXEMPTION_ALLOWED)
 
 
-def _check_slice_tdd(text: str, stages: List[StageMeta]) -> List[ValidationError]:
+def _check_slice_tdd(text: str, stages: List[StageMapStage]) -> List[ValidationError]:
     """S10: each stage declares a vertical slice and follows RED→GREEN ordering.
 
     S10a — `Slice value:` line with a non-empty value.
@@ -291,7 +262,7 @@ def _check_red_green_steps(section: str, stage_number: int) -> List[ValidationEr
 
 
 def _check_conformance_declaration(
-    text: str, stages: List[StageMeta]
+    text: str, stages: List[StageMapStage]
 ) -> List[ValidationError]:
     """S11: 각 stage 는 conformance 검증을 선언하거나 명시적으로 면제한다.
 
@@ -312,7 +283,7 @@ def _check_conformance_declaration(
     return errs
 
 
-def _check_depends_on(stages: List[StageMeta]) -> List[ValidationError]:
+def _check_depends_on(stages: List[StageMapStage]) -> List[ValidationError]:
     errs: List[ValidationError] = []
     valid = {s.stage_number for s in stages}
     for s in stages:
@@ -358,16 +329,8 @@ def _extract_exit_contract_files(section: str) -> set:
     return set(PATH_TOKEN.findall(body))
 
 
-def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[ValidationError]:
-    """S9: two `depends-on (none)` stages must not predict the same file —
-    otherwise two parallel implementation runs would edit it concurrently."""
-    files = {
-        s.stage_number: _extract_exit_contract_files(
-            _slice_stage_section(text, s.stage_number)
-        )
-        for s in stages
-        if not s.depends_on
-    }
+def _report_shared_parallel_files(files: dict) -> List[ValidationError]:
+    """S9 over an already-extracted {stage_number: {path}} map."""
     errs: List[ValidationError] = []
     nums = sorted(files)
     for i in range(len(nums)):
@@ -381,6 +344,20 @@ def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[Validatio
     return errs
 
 
+def _check_parallel_safety(
+    text: str, stages: List[StageMapStage],
+) -> List[ValidationError]:
+    """S9: two `depends-on (none)` stages must not predict the same file —
+    otherwise two parallel implementation runs would edit it concurrently."""
+    return _report_shared_parallel_files({
+        s.stage_number: _extract_exit_contract_files(
+            _slice_stage_section(text, s.stage_number)
+        )
+        for s in stages
+        if not s.depends_on
+    })
+
+
 def collect_validation_errors(text: str) -> List[ValidationError]:
     """All S1–S11 checks against the report text; empty list means valid.
 
@@ -393,8 +370,10 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
         return present
 
     errors: List[ValidationError] = []
-    stages, s2_errs = _parse_stage_map(text)
-    errors.extend(s2_errs)
+    try:
+        stages = parse_stage_map_text(text)
+    except StageMapError as exc:
+        return [ValidationError("S2", 0, exc.reason)]
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
         errors.extend(_check_slice_tdd(text, stages))
@@ -404,6 +383,130 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
     return errors
 
 
+def _data_stage_metas(
+    stage_map: List[dict],
+) -> Tuple[List[StageMapStage], List[ValidationError]]:
+    rows = []
+    for row in stage_map:
+        if not isinstance(row, dict) or not isinstance(row.get("stage"), int):
+            continue
+        depends = _parse_depends_on_cell(str(row.get("dependsOn") or ""))
+        if depends is None:
+            continue
+        rows.append(StageMapStage(
+            row["stage"],
+            str(row.get("title") or ""),
+            depends,
+            row.get("stepCount") if isinstance(row.get("stepCount"), int) else -1,
+            str(row.get("exitContractSummary") or ""),
+        ))
+    return rows, _stage_numbers_monotonic(rows)
+
+
+def _check_data_slice_tdd(stage: dict) -> List[ValidationError]:
+    """S10c / S10e over one schema-v2 `stages[]` entry.
+
+    The schema already requires `sliceValue`, `acceptance`, and — through its
+    `if not tddExemption then testCase*` conditional — the three test cases, so
+    S10a/S10b/S10d are covered declaratively. Two rules a JSON Schema cannot
+    state are left: the RED→GREEN ordering across `stepwiseExecution` rows, and
+    that a `tddExemption` naming no allowed category cannot waive them. The
+    schema types `tddExemption` as a plain string, so `""` currently satisfies
+    the conditional and drops all three test cases with no reason given.
+    """
+    number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
+    if "tddExemption" in stage:
+        reason = str(stage.get("tddExemption") or "").lower()
+        if not any(cat in reason for cat in TDD_EXEMPTION_ALLOWED):
+            return [ValidationError("S10", number,
+                "S10e: 'tddExemption' reason must be one of "
+                + " / ".join(TDD_EXEMPTION_ALLOWED)
+                + " — an empty or arbitrary reason cannot waive RED/GREEN "
+                "and the three test cases")]
+        return []
+
+    steps = [s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)]
+    actions = [str(s.get("action") or "") for s in steps]
+    if not (actions and actions[0].startswith("RED:")
+            and any(a.startswith("GREEN:") for a in actions)):
+        return [ValidationError("S10", number,
+            "S10c: first stepwiseExecution action must start with 'RED:' and "
+            "some action with 'GREEN:', or declare a 'tddExemption'")]
+
+    errs: List[ValidationError] = []
+    for step in steps:
+        action = str(step.get("action") or "")
+        expected = str(step.get("expected") or "")
+        if action.startswith("RED:") and "FAIL" not in expected.upper():
+            errs.append(ValidationError("S10", number,
+                f"S10c: 'RED:' step's expected must read FAIL, got '{expected}'"))
+        elif action.startswith("GREEN:") and "PASS" not in expected.upper():
+            errs.append(ValidationError("S10", number,
+                f"S10c: 'GREEN:' step's expected must read PASS, got '{expected}'"))
+    return errs
+
+
+def _check_data_step_counts(
+    stage_map: List[StageMapStage], stages: List[dict]
+) -> List[ValidationError]:
+    """The Stage Map row is the plan's own index of its stage body. A row
+    claiming a step count the body does not have makes the map unusable for
+    sizing a stage, which is the only reason the cell exists."""
+    by_number = {
+        s.get("stage"): s for s in stages
+        if isinstance(s, dict) and isinstance(s.get("stage"), int)
+    }
+    errs: List[ValidationError] = []
+    for meta in stage_map:
+        stage = by_number.get(meta.stage_number)
+        if stage is None:
+            errs.append(ValidationError("S3", meta.stage_number,
+                "stageMap row has no matching stages[] entry"))
+            continue
+        actual = len([
+            s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)
+        ])
+        if meta.step_count != actual:
+            errs.append(ValidationError("S4", meta.stage_number,
+                f"stageMap stepCount {meta.step_count} != "
+                f"{actual} stepwiseExecution rows"))
+    for number in sorted(n for n in by_number if n not in {m.stage_number for m in stage_map}):
+        errs.append(ValidationError("S3", number,
+            "stages[] entry has no matching stageMap row"))
+    return errs
+
+
+def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
+    """The S-checks that schema v2 cannot express, over `implementationPlanning`.
+
+    `collect_validation_errors` scans rendered v1 Markdown, and
+    `validate_phase_boundary` returns before calling it for a v2 report — so on
+    the current schema nothing enforced the depends-on DAG, parallel-stage file
+    safety, RED→GREEN ordering, or the TDD-exemption vocabulary. The schema
+    covers presence and cardinality; this covers the relationships between
+    fields, which is what a JSON Schema has no way to say.
+    """
+    stage_map, errors = _data_stage_metas(planning.get("stageMap") or [])
+    stages = [s for s in (planning.get("stages") or []) if isinstance(s, dict)]
+    if not stage_map and not stages:
+        return errors
+
+    errors.extend(_check_data_step_counts(stage_map, stages))
+    errors.extend(_check_depends_on(stage_map))
+    errors.extend(_report_shared_parallel_files({
+        meta.stage_number: set(PATH_TOKEN.findall(
+            str((next(
+                (s for s in stages if s.get("stage") == meta.stage_number), {}
+            )).get("exitContract") or "")
+        ))
+        for meta in stage_map
+        if not meta.depends_on
+    }))
+    for stage in stages:
+        errors.extend(_check_data_slice_tdd(stage))
+    return errors
+
+
 def main(argv: List[str]) -> int:
     p = argparse.ArgumentParser()
     p.add_argument("--plan", required=True)

package/runtime/validators/validate-run.py

@@ -3249,6 +3249,10 @@ def validate_final_report_data(
             (data.get("implementationPlanning") or {}).get("planBodyVerification") or {}
         ):
             print(f"validate-run: warning: {warning}", file=sys.stderr)
+        for warning in _detect_uniform_verifier(
+            (data.get("implementationPlanning") or {}).get("planBodyVerification") or {}
+        ):
+            print(f"validate-run: warning: {warning}", file=sys.stderr)
         for warning in _detect_unmapped_incremental_fallback(data, report_path):
             print(f"validate-run: warning: {warning}", file=sys.stderr)
         for warning in _detect_missing_dependency_precondition(
@@ -3259,6 +3263,7 @@ def validate_final_report_data(
         _validate_self_fix_grouping(data, failures)
         _validate_clarification_evidence_note(data, failures)
         _validate_plan_body_verdict_provenance(data, report_path, failures)
+        _validate_reverify_result_addresses_prior_dissent(data, report_path, failures)
         _validate_aborted_gate_has_clarification(data, failures)
         _validate_round_recorded_verdicts(data, failures)
         _validate_verdicts_match_current_subjects(data, failures)
@@ -5048,6 +5053,111 @@ def _validate_plan_body_verdict_provenance(
         )
 
 
+_UNIFORM_VERIFIER_MIN_ITEMS = 5
+
+
+def _detect_uniform_verifier(pbv: dict) -> list[str]:
+    """Verifiers whose every vote in the round was the same verdict.
+
+    `participatingAnalysers` counts whether a worker voted, not whether the
+    votes carried information. A verifier that answers AGREE to every item is
+    counted as a third opinion while contributing no refutation signal, so the
+    report reads as a three-way cross-check backed by two. (fontsninja-nlpvibe
+    `nlpvibe-vs-fontradar-baseline` seq 001: 63/63 AGREE off six inspected
+    evidence paths, on a round where the two other analysers jointly refuted a
+    real defect.)
+
+    Advisory only. A unanimous round is a legitimate outcome, and any ratio
+    strict enough to catch a rubber stamp also fails honest agreement, so this
+    reports the counts and leaves the judgement to the reader.
+    """
+    items = pbv.get("planItems") if isinstance(pbv, dict) else None
+    if not isinstance(items, list):
+        return []
+    verdicts_by_worker: dict[str, set[str]] = {}
+    counts: dict[str, int] = {}
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        for verdict in item.get("verdicts") or []:
+            if not isinstance(verdict, dict):
+                continue
+            worker = str(verdict.get("worker") or "").strip()
+            value = str(verdict.get("verdict") or "").strip()
+            if not worker or not value or value == "verification-error":
+                continue
+            verdicts_by_worker.setdefault(worker, set()).add(value)
+            counts[worker] = counts.get(worker, 0) + 1
+    warnings = []
+    for worker in sorted(verdicts_by_worker):
+        distinct = verdicts_by_worker[worker]
+        total = counts[worker]
+        if len(distinct) != 1 or total < _UNIFORM_VERIFIER_MIN_ITEMS:
+            continue
+        warnings.append(
+            f"plan-body verification: {worker} returned `{next(iter(distinct))}` "
+            f"for all {total} items it voted on, so this round's refutation "
+            "signal came from its peers alone. Confirm the worker actually "
+            "opened the cited evidence (its `-audit-` sidecar lists what it "
+            "read) before reading the gate as a full cross-check."
+        )
+    return warnings
+
+
+_PRIOR_DISSENT_ANCHOR = "**Prior dissent**"
+_PLAN_VERIFY_ROUND_RE = re.compile(r"-plan-verify-r(?P<round>\d+)-")
+
+
+def _plan_verify_round_number(file_name: str) -> int | None:
+    match = _PLAN_VERIFY_ROUND_RE.search(file_name)
+    return int(match.group("round")) if match else None
+
+
+def _validate_reverify_result_addresses_prior_dissent(
+    data: dict,
+    report_path: Path,
+    failures: list[str],
+) -> None:
+    """A round 2+ plan-body verdict must engage the dissent it re-verifies.
+
+    The self-fix loop re-dispatches the same workers against a corrected plan,
+    but nothing carried the previous round's objection into the new prompt. The
+    worker that objected then restates its verdict unchanged and its peers
+    re-judge from nothing, so the loop spends its whole `selfFixMaxRounds`
+    budget re-deriving one split instead of settling it. (fontsninja-nlpvibe
+    `nlpvibe-vs-fontradar-baseline` seq 001: three self-fix rounds to
+    `max-rounds-reached`, gate still `blocked-by-disagreement`, codex holding
+    every DISAGREE it opened.)
+    """
+    worker_results_dir = report_path.parent.parent / "worker-results"
+    if not worker_results_dir.is_dir():
+        return
+    task_type = str((data.get("header") or {}).get("taskType") or "")
+    seq = _report_run_seq(report_path)
+    pattern = f"*-plan-verify-r*-{task_type}-{seq or '*'}.md"
+    silent = []
+    for path in sorted(worker_results_dir.glob(pattern)):
+        if "-audit-plan-verify-r" in path.name:
+            continue
+        round_number = _plan_verify_round_number(path.name)
+        if round_number is None or round_number < 2:
+            continue
+        body = path.read_text(encoding="utf-8", errors="replace")
+        if _PRIOR_DISSENT_ANCHOR not in body:
+            silent.append(path.name)
+    if silent:
+        failures.append(
+            "plan-body re-verification: "
+            f"{silent} carry no `{_PRIOR_DISSENT_ANCHOR}` line. A round 2+ "
+            "verdict exists to settle the previous round's objection, so the "
+            "prompt MUST carry that dissent forward and the worker MUST answer "
+            "whether the correction resolved it. Without it the objecting "
+            "worker repeats its verdict and its peers judge from nothing, and "
+            "the self-fix budget drains on the same split "
+            '(plan-body-verification.md §"Re-verification rounds (round 2+)").'
+        )
+
+
 def _validate_plan_item_extraction_completeness(
     data: dict,
     failures: list[str],
@@ -6177,6 +6287,31 @@ def _load_stage_validator():
     return mod
 
 
+def _append_stage_data_failures(data: Mapping[str, Any], failures: list[str]) -> None:
+    """Run the stage relationship checks that schema v2 cannot express.
+
+    `_append_stage_structure_failures` scans rendered Markdown and sits after
+    the v2 early return in `validate_phase_boundary`, so for a v2 report the
+    depends-on DAG, parallel-stage file safety, RED→GREEN ordering, and the
+    TDD-exemption vocabulary had nothing enforcing them. The same validator
+    owns both modes so the rule vocabulary stays defined once.
+    """
+    if (data or {}).get("schemaVersion") != "2.0":
+        return  # v1 reports are covered by the Markdown scan.
+    planning = (data or {}).get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        return  # Schema validation already reported the missing block.
+    mod = _load_stage_validator()
+    if mod is None:  # pragma: no cover — repo/runtime always ship the file
+        failures.append(f"cannot load Stage Map validator at {_STAGE_VALIDATOR_PATH}")
+        return
+    for e in mod.collect_data_validation_errors(dict(planning)):
+        failures.append(
+            f"implementation-planning stage contract invalid "
+            f"[{e.code} stage={e.stage}]: {e.message}"
+        )
+
+
 def _append_stage_structure_failures(content: str, failures: list[str]) -> None:
     """Enforce the Stage Map structural contract at the implementation-planning
     boundary. Without this, a plan missing `## 5.5 Stage Map` passes the
@@ -7420,6 +7555,7 @@ def main() -> int:
                     validation_data, brief_path, failures
                 )
                 _validate_stage_has_requirement(validation_data, failures)
+                _append_stage_data_failures(validation_data, failures)
         if task_type == "improvement-discovery":
             run_dir = report_path.parent.parent
             _validate_improvement_discovery(report_path, run_dir, brief_path, failures)

package/runtime/validators/validate-schedule.py

@@ -5,10 +5,12 @@ defined in skills/okstra-schedule-gen/SKILL.md.
 
 Usage:
     python3 validators/validate-schedule.py <path-to-schedule.md>
+    python3 validators/validate-schedule.py <path-to-schedule.md> \
+        --selection-json <selection.json>
 
-Exits 0 if compliant, 1 with a list of violations otherwise. Intended to be
-called by the okstra-schedule-gen skill (self-validation step) and by humans /
-hooks before committing a schedule.
+Exits 0 if compliant, 1 with a list of violations, or 2 for invalid arguments.
+Intended to be called by the okstra-schedule-gen skill (self-validation step)
+and by humans / hooks before committing a schedule.
 """
 
 from __future__ import annotations
@@ -25,6 +27,11 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
         sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.md_table import split_pipe_row  # noqa: E402
+from okstra_ctl.schedule_semantics import (  # noqa: E402
+    ScheduleSemanticError,
+    parse_effort_ranges,
+    validate_schedule_semantics,
+)
 
 REQUIRED_SECTIONS_IN_ORDER: list[str] = [
     "## At a Glance",
@@ -142,12 +149,31 @@ DECISION_ITEM_ALLOWLIST = set()  # nothing legitimate matches this shape
 MILESTONE_RE = re.compile(r"\bM(\d+)\b")
 
 
-def validate(path: Path) -> list[str]:
+def _outside_fenced_lines(text: str) -> list[str]:
+    visible: list[str] = []
+    fence_marker = ""
+    for line in text.splitlines():
+        stripped = line.lstrip()
+        marker = stripped[:3] if stripped.startswith(("```", "~~~")) else ""
+        if fence_marker:
+            visible.append("")
+            if marker == fence_marker:
+                fence_marker = ""
+        elif marker:
+            fence_marker = marker
+            visible.append("")
+        else:
+            visible.append(line)
+    return visible
+
+
+def _validate_format(path: Path) -> list[str]:
     if not path.exists():
         return [f"file not found: {path}"]
 
     text = path.read_text(encoding="utf-8")
     lines = text.splitlines()
+    visible_lines = _outside_fenced_lines(text)
     violations: list[str] = []
 
     # 1. Title must end with "— Work Schedule"
@@ -172,7 +198,7 @@ def validate(path: Path) -> list[str]:
     #    Phase 1: Critical Fixes.
     section_positions: dict[str, int] = {}
     optional_positions: dict[str, int] = {}
-    for idx, line in enumerate(lines):
+    for idx, line in enumerate(visible_lines):
         stripped = line.rstrip()
         if stripped in REQUIRED_SECTIONS_IN_ORDER and stripped not in section_positions:
             section_positions[stripped] = idx
@@ -186,6 +212,14 @@ def validate(path: Path) -> list[str]:
     for s in missing:
         violations.append(f"missing required section: {s!r}")
 
+    for authority in ("## At a Glance", REQUIRED_EXEC_SUMMARY_SUBSECTION):
+        count = sum(line.rstrip() == authority for line in visible_lines)
+        if count > 1:
+            violations.append(
+                f"semantic authority {authority!r} must appear exactly once; "
+                f"found {count}"
+            )
+
     if not missing:
         ordered_actual = sorted(section_positions, key=lambda s: section_positions[s])
         if ordered_actual != REQUIRED_SECTIONS_IN_ORDER:
@@ -206,10 +240,19 @@ def validate(path: Path) -> list[str]:
                     "'## Task Dependency Graph' and '## Phase 1: Critical Fixes'"
                 )
     # 4. Executive Summary subsection
-    if REQUIRED_EXEC_SUMMARY_SUBSECTION not in text:
+    effort_heading_count = sum(
+        line.rstrip() == REQUIRED_EXEC_SUMMARY_SUBSECTION
+        for line in visible_lines
+    )
+    if effort_heading_count == 0:
         violations.append(
             f"missing subsection {REQUIRED_EXEC_SUMMARY_SUBSECTION!r} inside Executive Summary"
         )
+    elif effort_heading_count == 1:
+        try:
+            parse_effort_ranges(text)
+        except ScheduleSemanticError as exc:
+            violations.append(str(exc))
 
     # 5. Forbidden translated/extra headings
     for match in FORBIDDEN_HEADINGS_RE.finditer(text):
@@ -503,6 +546,16 @@ def validate(path: Path) -> list[str]:
     return violations
 
 
+def validate(
+    path: Path, selection_path: Path | None = None,
+) -> list[str]:
+    violations = _validate_format(path)
+    if violations or selection_path is None:
+        return violations
+    text = path.read_text(encoding="utf-8")
+    return violations + validate_schedule_semantics(text, selection_path)
+
+
 def _strip_code_fences(text: str) -> str:
     """Remove ``` fenced blocks so opaque-id regex doesn't false-positive
     on shell commands, file paths, etc."""
@@ -654,11 +707,26 @@ def _check_self_contained_identifiers(text: str, lines: list[str],
 
 
 def main(argv: list[str]) -> int:
-    if len(argv) != 2:
-        print(f"usage: {argv[0]} <path-to-schedule.md>", file=sys.stderr)
+    usage = (
+        f"usage: {argv[0]} <path-to-schedule.md> "
+        "[--selection-json <selection.json>]"
+    )
+    args = argv[1:]
+    if len(args) == 1 and not args[0].startswith("-"):
+        path = Path(args[0])
+        selection_path = None
+    elif (
+        len(args) == 3
+        and args[1] == "--selection-json"
+        and not args[0].startswith("-")
+        and not args[2].startswith("-")
+    ):
+        path = Path(args[0])
+        selection_path = Path(args[2])
+    else:
+        print(usage, file=sys.stderr)
         return 2
-    path = Path(argv[1])
-    violations = validate(path)
+    violations = validate(path, selection_path)
     if not violations:
         print(f"OK: {path} conforms to okstra-schedule-gen Section Contract")
         return 0