okstra 0.34.0 → 0.36.0

package/runtime/templates/reports/i18n/ko.json

@@ -0,0 +1,135 @@
+{
+  "_meta": {
+    "lang": "ko",
+    "note": "okstra final-report 고정 문자열 (한국어). 키는 en.json 과 정확히 일치해야 한다. 키를 추가하면 en.json 도 같은 커밋에서 추가한다."
+  },
+  "emptyState": {
+    "consensusItems": "- 합의 항목 없음.",
+    "differences": "- 유의미한 차이 없음. 1.1 Consensus 가 그대로 유효합니다.",
+    "primaryEvidence": "- 주 증거 없음.",
+    "secondaryEvidence": "- 보조 증거 또는 대안 해석 없음.",
+    "risks": "- 누락된 정보·위험 없음.",
+    "dependencyRisk": "- 의존성·마이그레이션 위험 없음.",
+    "dissent": "- 반대 의견 없음.",
+    "outOfPlanEdits": "- 계획 외 편집 없음.",
+    "declinedFixRecommendations": "- 없음.",
+    "discrepancy": "- 없음.",
+    "lingeringRisks": "- 추적 대상 잔존 위험 없음.",
+    "noClarification": "- 추가 정보 요청 없음. Section 2 의 최종 판단이 그대로 유효합니다.",
+    "noFollowUp": "- 후속 작업 없음. 본 run 의 다음 phase 는 §6 (Recommended Next Steps) 참고."
+  },
+  "columns": {
+    "summary": "한 줄 요약",
+    "source": "출처 (brief/source/worker)",
+    "rawTokens": "처리 토큰",
+    "billableTokens": "환산 토큰",
+    "billableTokensInputEquiv": "환산 토큰 (input 기준)",
+    "cost": "비용 (USD)",
+    "checkMethod": "확인 방법"
+  },
+  "sectionAside": {
+    "dependencyRisk": "의존성·마이그레이션 위험",
+    "validationChecklist": "검증 체크리스트",
+    "rollbackStrategy": "롤백 전략",
+    "planBodyVerification": "계획 본문 검증",
+    "recommendedOption": "권장 옵션",
+    "optionCandidates": "옵션 후보",
+    "tradeOffMatrix": "트레이드오프 매트릭스",
+    "stepwiseExecutionOrder": "단계별 실행 순서"
+  },
+  "sectionIntro": {
+    "verdictCard": "한눈에 보는 결과 카드. 본 표의 모든 값은 `## 2. Final Verdict` 및 `## 6. Recommended Next Steps` 의 권위 있는 값과 정확히 일치해야 합니다.",
+    "clarificationCarryIn": "이전 보고서의 `## 5. Clarification Items` 표 매 행(`C-001`, `C-002`, …) 을 새 증거에 비추어 검토하고, 각 행의 `Status` 를 `resolved` 또는 `obsolete` 로 갱신한 뒤 본 run 의 `## 5.` 표에 carry-in 합니다. 해소 근거(파일:라인 / 로그 / 워커 결과) 를 함께 인용합니다.",
+    "ticketCoverage": "3~5 개 row 로 핵심 문제·요구사항·검증 대상을 표로 정리합니다. brief, 소스 자료, worker 결과를 근거로 작성합니다.",
+    "executionStatus": "각 worker 의 status, 배정 모델, key finding 을 한 표에 모읍니다. worker 산출물을 근거 없는 주장으로 대체하지 않습니다.",
+    "sourceItemsRule": "`Source items` 규칙: 본 합의 row 가 어느 워커의 어느 항목들에서 합성됐는지를 `<worker>:<item-id>` 페어 콤마-리스트로 적습니다. 자세한 정책은 `prompts/profiles/_common-contract.md` \"Cross-worker traceability\" SSOT.",
+    "stepRule": "규칙: 한 step 은 약 2~5 분. 모든 step 은 정확한 파일 경로와 명령어 포함.",
+    "planBodyVerification": "Phase 6 에서 report-writer 가 합성한 4.5 본문을 lead 가 plan-item 단위로 워커들에게 다시 던지고 평결을 수집한 결과.",
+    "clarificationItems": "다음 run 으로 넘어가기 전에 사용자가 답하거나 자료를 첨부해야 하는 항목을 **한 표 안에서** 추적합니다."
+  },
+  "tokenSummary": {
+    "heading": "토큰 사용량 요약",
+    "tableHeaderItem": "항목",
+    "rowLead": "Lead",
+    "rowWorkerTotal": "Worker 합계",
+    "rowGrandTotal": "**전체 합계**",
+    "rowCliExtra": "Codex/Gemini CLI 추가 비용"
+  },
+  "verdictCard": {
+    "tableHeaderLabel": "항목",
+    "tableHeaderValue": "값",
+    "approvalRequiredSuffix": "frontmatter `approved` 가 `true` 여야 `implementation` 진입 가능",
+    "rationaleLabel": "근거 요약",
+    "nextStepLabel": "다음 단계"
+  },
+  "ticketCoverage": {
+    "intro": "본 run 이 다룬 ticket 의 역방향 인덱스. 본문 항목들은 모두 `Ticket ID` 컬럼 또는 `[TICKETID: <id>]` 태그로 ticket 과 묶여 있습니다.",
+    "columnSections": "등장 섹션",
+    "columnRelatedIds": "관련 항목 IDs",
+    "ruleNote": "규칙: `Ticket ID` 는 본문에서 등장한 ticket 키와 정확히 동일 문자열. `Issue / Ticket` 이 비어 폴백된 경우 `Task ID` 값을 prefix 없이 그대로 (예: `8852`). 식별 불가는 `unknown`."
+  },
+  "finalVerdict": {
+    "intro": "최종 결론과 권장 방향을 한 표로 명시합니다. `Direction` ∈ `continue-investigation / begin-implementation / approve / reject / hold`. `task-type` 이 `final-verification` 이면 `Verdict Token` 은 `accepted / conditional-accept / blocked` 중 하나여야 하며, `release-handoff` 는 이 값을 진입 게이트로 사용합니다. 다른 task-type 에서는 `not-applicable`."
+  },
+  "evidence": {
+    "sourceItemsColumnNote": "`Source items` 컬럼 규칙은 §1.1 과 동일."
+  },
+  "roundHistory": {
+    "round2SkippedReasonNote": "값은 `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only` 중 하나."
+  },
+  "implementationPlanning": {
+    "optionInterfacesLabel": "영향 인터페이스 / 공개 계약 / 다운스트림 소비자",
+    "optionBlastRadiusLabel": "폭발 반경 추정",
+    "recommendedTableHeaderLabel": "항목",
+    "recommendedTableHeaderValue": "값",
+    "coreReasonLabel": "핵심 이유",
+    "rationaleLabel": "근거 (Trade-off 행 / 원칙)",
+    "rejectedSummaryLabel": "채택되지 않은 옵션 요약",
+    "columnImpact": "영향",
+    "columnMitigation": "완화 / 선행 작업"
+  },
+  "releaseHandoff": {
+    "auditNote": "git/gh mutating 명령이 실행된 phase 의 감사 기록.",
+    "branchStateAside": "run 시작 시점",
+    "gitStatusShortLabel": "`git status --short` 출력",
+    "existingPrLabel": "기존 PR 존재 여부",
+    "userSelectionsAside": "메뉴 응답 기록",
+    "questionsTableHeader": {
+      "questionId": "질문 ID",
+      "questionBody": "질문 본문",
+      "userResponse": "사용자 응답 (원문)",
+      "allowedOptions": "응답이 가능한 보기"
+    },
+    "h1Body": "어떤 작업을 실행할까요?",
+    "h2Body": "PR base 브랜치 (H1=`push + PR` 인 경우)",
+    "h3Body": "PR title/body 초안 처리",
+    "h2DefaultLabel": "(n/a)",
+    "h2OptionsLabel": "staging / preprod / prod / main / dev / 사용자 입력",
+    "noMutationNote": "(mutating 명령 미실행 — H1=`skip` 또는 H3=`cancel`)",
+    "commandsTableHeader": {
+      "outputSummary": "stdout/stderr 요약"
+    }
+  },
+  "executionMeta": {
+    "runExecutorWorktreePath": "본 run 의 `EXECUTOR_WORKTREE_PATH`",
+    "runBaseRef": "본 run 의 base ref"
+  },
+  "evidenceMeta": {
+    "commitListSummary": "인용된 commit list / diff summary 요약",
+    "targetWorktreePath": "검증 대상 worktree path",
+    "capturedHeadBaseSha": "run 시작 시 capture 한 head/base SHA",
+    "gitStatusAtRunStart": "`git status --short` (run 시작 시점)"
+  },
+  "clarification": {
+    "fillAndRerun": "답을 채우신 뒤 같은 phase 를 다시 실행:",
+    "separateTerminalLabel": "별도 터미널",
+    "columnGuide": "컬럼 가이드 (전체 정의는 `prompts/profiles/_common-contract.md §Clarification request policy` SSOT 참조):"
+  },
+  "followUpTasks": {
+    "headingAside": "후속 작업"
+  },
+  "finalVerification": {
+    "validationEvidenceAside": "요구사항 커버리지",
+    "columnRequirement": "Requirement (plan/brief 인용)"
+  }
+}

package/runtime/templates/reports/implementation-planning-input.template.md

@@ -105,3 +105,21 @@ The final report of an `implementation-planning` run MUST contain every section
 
 - This input can be used as a planning draft before creating `okstra-task-brief.md`.
 - Reuse the same `Task Group` and `Task ID` if this plan belongs to the same long-lived task.
+
+## Stage Output Shape (reference)
+
+This run's final report MUST emit `## 4.5 Stage Map` and `## 4.5.<i> Stage <i>` sections per the implementation-planning profile §"Required deliverable shape". Two illustrative shapes:
+
+### Shape A — single stage (small work)
+| stage | title | depends-on | step-count | exit-contract-summary |
+|-------|-------|-------|-------|-------|
+| 1 | tiny rename | (none) | 2 | src/foo.ts:renamedFoo |
+
+### Shape B — three stages, two parallel
+| stage | title | depends-on | step-count | exit-contract-summary |
+|-------|-------|-------|-------|-------|
+| 1 | foo API skeleton | (none) | 4 | src/foo/api.ts:exportedFoo |
+| 2 | baz settings split | (none) | 2 | src/baz/settings.ts, env BAZ_MODE |
+| 3 | bar integration | 1, 2 | 3 | src/bar/use-foo.ts, GET /bar |
+
+Stages 1 and 2 in Shape B are `depends-on (none)` → can be run by two parallel `implementation` runs.

package/runtime/templates/reports/improvement-discovery-input.template.md

@@ -0,0 +1,78 @@
+---
+title: OKSTRA Improvement Discovery Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
+---
+
+# OKSTRA Improvement Discovery Input
+
+## Identity
+
+- Project ID:
+- Task Group:
+- Task ID:
+- Related Tasks:
+- Issue / Ticket:
+  - 값이 비면 워커는 `Task ID` 로 폴백한다.
+- Task Type: `improvement-discovery`
+- Requested Outcome:
+
+## Scope (from brief frontmatter)
+
+- scan-scope:
+- out-of-scope:
+- priority-lenses:
+- candidate-cap (1..12, default 8):
+
+## Context
+
+- Why this scope is being scanned now:
+- Recent change context (last N commits to scan-scope):
+- Stakeholders or owners of the scope:
+
+## Desired Outcome
+
+- What kinds of improvements do you want surfaced?
+- Anti-goals (improvements you do NOT want this run to propose):
+
+## Constraints
+
+- Untouchable areas:
+- Compatibility / deadline constraints:
+- Performance / regression budget (if applicable):
+
+## Phase 1.5 — Lead Reflect-Back Grilling
+
+This section is filled in by the lead during Phase 1.5 before worker dispatch.
+Workers MUST read the resolved values from `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`
+rather than the unresolved brief.
+
+- Reflect-back summary:
+- Open questions (Q1..QN):
+- Resolved scope:
+- Resolved lenses:
+
+## Improvement Candidates (workers populate this)
+
+| Cand ID | Lens | Title | Scope | Severity | Effort | Consensus | Source workers | Recommended next-phase | Evidence |
+|---------|------|-------|-------|----------|--------|-----------|----------------|------------------------|----------|
+
+## Questions for Analysers
+
+1. Within the resolved scope and priority lenses, what are the highest-impact improvement candidates?
+2. Which candidates have full cross-worker consensus, and which are worker-unique?
+3. For each candidate, what is the safest next phase (requirements-discovery / implementation-planning / error-analysis)?
+4. Which candidates would you intentionally exclude despite being technically valid, and why?
+5. Are there any signals that the scope itself is mis-defined (and should be re-narrowed before discovery proceeds)?
+
+## Conversion Note
+
+- Each candidate the user picks becomes a new okstra task. Suggested task-key: `<task-group>/imp-<Cand-ID>`.
+- The candidate row's Recommended next-phase determines which `--task-type` to launch with.

package/runtime/templates/reports/task-brief.template.md

@@ -65,7 +65,7 @@ taskType: "{{FM_TASK_TYPE}}"
   - What trade-offs, dependencies, or migrations matter?
   - What validation and rollback approach is expected?
 - If `Task Type` is `implementation`:
-  - Which approved `implementation-planning` final report authorises this run, and where is the explicit user-approval marker quoted?
+  - Which approved `implementation-planning` final report authorises this run, and is its frontmatter `approved: true` cited verbatim?
   - What is the authoritative file list and step order copied from that plan?
   - Which validation, TDD, and rollback commands must be executed and recorded with actual output?
 - If `Task Type` is `final-verification`:
@@ -141,7 +141,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`agents/SKILL.md`). The lead and every worker stay inside that boundary.
 - "다음 단계 진행해" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`.
 - For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories.
-- For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or has no explicit user-approval marker. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.
+- For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or its frontmatter `approved` field is not `true`. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.
 
 ## Available MCP Servers
 

package/runtime/validators/lib/fixtures.sh

@@ -374,6 +374,36 @@ report_path.write_text("\n".join(report_lines) + "\n")
 import os
 WORKSPACE_ROOT = os.environ.get("OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE", "")
 if WORKSPACE_ROOT:
+    # Write final-report .data.json SSOT next to the markdown. The validator's
+    # validate_final_report_data() reads this via _data_path_for(report_path)
+    # and the renderer treats it as the canonical source — the markdown alone
+    # is no longer a valid run artifact (dual-format final-report rollout).
+    # Sample bundled in tests/fixtures is patched with this run's task identity.
+    task_type = str(task_manifest.get("taskType", ""))
+    sample_path = (
+        Path(WORKSPACE_ROOT)
+        / "tests" / "fixtures" / "final-report-data"
+        / f"{task_type}-001.data.json"
+    )
+    if sample_path.is_file():
+        sample = json.loads(sample_path.read_text(encoding="utf-8"))
+        sample["frontmatter"]["taskGroup"] = str(task_manifest.get("taskGroup", ""))
+        sample["frontmatter"]["taskId"] = str(task_manifest.get("taskId", ""))
+        sample["frontmatter"]["taskType"] = task_type
+        sample["frontmatter"]["projectId"] = str(task_manifest.get("projectId", ""))
+        sample["header"]["taskKey"] = str(task_manifest.get("taskKey", ""))
+        sample["header"]["taskType"] = task_type
+        name = report_path.name
+        data_path = (
+            report_path.with_name(name[:-3] + ".data.json")
+            if name.endswith(".md")
+            else report_path.with_suffix(".data.json")
+        )
+        data_path.write_text(
+            json.dumps(sample, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+
     import sys as _sys
     _sys.path.insert(0, str(Path(WORKSPACE_ROOT) / "scripts"))
     try:

package/runtime/validators/lib/runners.sh

@@ -41,7 +41,7 @@ run_validator_expectation() {
 
   expected_task_manifest_relative_path="$(task_manifest_relative_path "$task_group" "$task_id")"
 
-  python3 - "$PROJECT_ROOT" "$expected_task_manifest_relative_path" "$RUN_VALIDATOR_SCRIPT" "$expected_status" "$expected_failure_substring" <<'PY'
+  python3 - "$PROJECT_ROOT" "$expected_task_manifest_relative_path" "$RUN_VALIDATOR_PATH" "$expected_status" "$expected_failure_substring" <<'PY'
 from pathlib import Path
 import json
 import subprocess

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

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""S1–S8 checks for the Stage Map structure of an approved
+implementation-planning final-report.md. Run from prepare_task_bundle
+of `implementation` task or standalone."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Tuple
+
+STAGE_MAP_HEADING = re.compile(r"^##\s+4\.5\s+Stage\s+Map\b", re.M)
+STAGE_SECTION = re.compile(
+    r"^##\s+4\.5\.(\d+)\s+Stage\s+\1\s*:\s*(.+)$", re.M
+)
+REQUIRED_SUBSECTIONS = (
+    "Carry-In",
+    "Stepwise Execution Order",
+    "Stage Exit Contract",
+    "Stage Validation",
+)
+
+
+@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..S8
+    stage: int  # 0 = global
+    message: str
+
+
+def _check_stage_map_present(text: str) -> List[ValidationError]:
+    if not STAGE_MAP_HEADING.search(text):
+        return [ValidationError("S1", 0,
+            "section '## 4.5 Stage Map' is missing")]
+    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 = [c.strip() for c in line.strip().strip("|").split("|")]
+        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()
+        depends = [] if depends_raw in ("(none)", "") else [
+            int(x.strip()) for x in depends_raw.split(",") if x.strip()
+        ]
+        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 _count_effective_steps(section: str) -> int:
+    m = re.search(r"^###\s+Stepwise Execution Order\b", section, re.M)
+    if not m:
+        return 0
+    body = section[m.end():]
+    nxt = re.search(r"^###\s+\w", body, re.M)
+    if nxt:
+        body = body[: nxt.start()]
+    count = 0
+    for line in body.splitlines():
+        s = line.strip()
+        if not s or s.startswith("<!--"):
+            continue
+        if not s.startswith("|"):
+            continue
+        # Reuse the same header/divider detection as _parse_stage_map:
+        # split on `|`, inspect first non-empty cell.
+        first_cell = s.strip("|").split("|")[0].strip()
+        if first_cell.lower() == "step":
+            continue
+        if set(first_cell) <= set("-: "):
+            continue
+        count += 1
+    return count
+
+
+def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[ValidationError]:
+    errs: List[ValidationError] = []
+    for s in stages:
+        pattern = rf"^##\s+4\.5\.{s.stage_number}\s+Stage\s+{s.stage_number}\s*:"
+        start_m = re.search(pattern, text, re.M)
+        if not start_m:
+            errs.append(ValidationError("S3", s.stage_number,
+                f"stage section '## 4.5.{s.stage_number} Stage {s.stage_number}:' missing"))
+            continue
+        # Slice the stage's section body
+        start = start_m.end()
+        nxt = re.search(
+            rf"^##\s+4\.5\.{s.stage_number + 1}\s+Stage\s+",
+            text[start:], re.M,
+        )
+        section = text[start: start + nxt.start()] if nxt else text[start:]
+
+        for sub in REQUIRED_SUBSECTIONS:
+            if not re.search(rf"^###\s+{re.escape(sub)}\b", section, re.M):
+                errs.append(ValidationError("S4", s.stage_number,
+                    f"required subsection '### {sub}' missing"))
+
+        # S5: effective step count
+        steps = _count_effective_steps(section)
+        if steps > 6:
+            errs.append(ValidationError("S5", s.stage_number,
+                f"effective step count {steps} exceeds 6"))
+
+        # S7: step-count cell vs. real count
+        if s.step_count >= 0 and s.step_count != steps:
+            errs.append(ValidationError("S7", s.stage_number,
+                f"Stage Map step-count={s.step_count} but real count={steps}"))
+    return errs
+
+
+def _check_depends_on(stages: List[StageMeta]) -> List[ValidationError]:
+    errs: List[ValidationError] = []
+    valid = {s.stage_number for s in stages}
+    for s in stages:
+        for d in s.depends_on:
+            if d == s.stage_number:
+                errs.append(ValidationError("S8", s.stage_number, "self depends-on"))
+            elif d not in valid:
+                errs.append(ValidationError("S6", s.stage_number,
+                    f"depends-on {d} does not exist"))
+
+    # DAG cycle detection via Kahn's algorithm
+    # Build a graph only from valid edges (S6 errors already reported above)
+    indeg = {s.stage_number: 0 for s in stages}
+    graph: dict[int, list[int]] = {s.stage_number: [] for s in stages}
+    for s in stages:
+        for d in s.depends_on:
+            if d in graph and d != s.stage_number:
+                graph[d].append(s.stage_number)
+                indeg[s.stage_number] += 1
+
+    queue = [n for n, k in indeg.items() if k == 0]
+    visited = 0
+    while queue:
+        n = queue.pop()
+        visited += 1
+        for m in graph[n]:
+            indeg[m] -= 1
+            if indeg[m] == 0:
+                queue.append(m)
+    if visited != len(stages):
+        errs.append(ValidationError("S8", 0, "depends-on graph has a cycle"))
+    return errs
+
+
+def main(argv: List[str]) -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--plan", required=True)
+    args = p.parse_args(argv)
+    text = Path(args.plan).read_text(encoding="utf-8")
+
+    errors: List[ValidationError] = []
+    errors.extend(_check_stage_map_present(text))
+    if errors:
+        for e in errors:
+            print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)
+        return 1
+
+    stages, s2_errs = _parse_stage_map(text)
+    errors.extend(s2_errs)
+    if stages:
+        errors.extend(_check_each_stage_section(text, stages))
+        errors.extend(_check_depends_on(stages))
+
+    if errors:
+        for e in errors:
+            print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))