okstra 0.25.1 → 0.27.0

package/runtime/templates/reports/final-report.template.md

@@ -225,6 +225,40 @@ revert 경로와 롤백 트리거 신호를 표로 정리합니다. 추상적
 - 본 섹션에는 승인 결정에 영향을 주는 *플랜 측 보충 메모*만 적습니다(예: 위험을 줄이기 위한 사전 작업, 승인 전 사용자가 확인해 두어야 할 사항). 승인 마커는 본 섹션이 아니라 상단 블록의 체크박스로만 부여합니다.
 - 사용자가 답하거나 자료를 첨부해야만 승인이 가능한 항목은 **이 섹션에 적지 않습니다** — `## 5. Clarification Items` 표에 한 행으로 등록하고 `Blocks=approval` 로 표시하세요. 같은 항목을 두 위치에 적으면 sync 가 깨집니다.
 
+### 4.5.9 Plan Body Verification (워커 사후 검증)
+
+> **이 sub-section 은 `task-type` = `implementation-planning` 실행 결과에만 포함하세요.** Phase 6 에서 report-writer 가 합성한 4.5 본문(Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)을 lead 가 plan-item 단위로 쪼개 워커들에게 다시 던지고 `AGREE / DISAGREE / SUPPLEMENT` 평결을 수집한 결과입니다. 자세한 라운드 프로토콜은 `skills/okstra-convergence/SKILL.md` "Plan-body verification mode" 섹션을 참고하세요.
+
+- **Round count**: `<N>` (default: 1)
+- **Gate result**: `<passed | passed-with-dissent | blocked-by-disagreement | aborted-non-result>`
+  - `passed` → 본 보고서 상단 `User Approval Request` 체크박스가 렌더됩니다.
+  - `passed-with-dissent` → 상단 체크박스가 렌더되되, 반대 의견은 아래 `Dissent log` 에 기록.
+  - `blocked-by-disagreement` → 상단 체크박스 라인 자체를 **렌더하지 않습니다**. majority DISAGREE 인 plan item 마다 `## 5. Clarification Items` 에 `Blocks=approval` row 가 추가되며, 사용자가 응답해야 다음 phase 로 넘어갈 수 있습니다.
+  - `aborted-non-result` → 워커 dispatch 가 모두 non-result (timeout / error). 상단 체크박스 라인 렌더하지 않음 + `## 5. Clarification Items` 에 "plan-body verification could not run" row 가 추가됩니다.
+
+#### Verdict table
+
+각 plan item 1 행. `Plan item` 열은 `P-Opt-<N>` / `P-Step-<N>` / `P-Dep-<N>` / `P-Val-<N>` / `P-Rb-<N>` prefix 사용. `Section` 열은 4.5 내부 sub-section 번호 (예: `4.5.4`).
+
+| Plan item | Ticket ID | Section | <worker1> | <worker2> | ... | Classification |
+|-----------|-----------|---------|-----------|-----------|-----|----------------|
+| P-Opt-1   | `<id>`    | 4.5.1   | AGREE     | AGREE     | ... | full-consensus |
+| P-Step-3  | `<id>`    | 4.5.4   | DISAGREE(a) | DISAGREE(a) | ... | majority-disagree → C-7 |
+
+- DISAGREE 셀에는 spec 의 `(a|b|c|d|e)` breakage kind 를 함께 표기 (예: `DISAGREE(a)` = 참조 file path / symbol 불일치).
+- 마지막 열 `Classification` ∈ `{full-consensus, partial-consensus, worker-unique, majority-disagree → C-<N>}`. `majority-disagree → C-<N>` 의 `C-<N>` 은 본 보고서 `## 5. Clarification Items` 표에서 해당 변환 row 의 ID 와 일치해야 합니다.
+
+#### Dissent log
+
+`partial-consensus` 와 `worker-unique` 로 분류된 plan item 의 반대 의견을 plan item 별로 묶어 적습니다. `majority-disagree` 항목의 반대 의견은 본 섹션 대신 `## 5. Clarification Items` 의 해당 row 의 `Statement` 컬럼에 옮겨 적습니다.
+
+- **P-XXX-N**: `<worker-role>` — `<반대 의견 본문 2-3 sentences>`
+
+#### Notes
+
+- 본 sub-section 이 누락된 채로 task-type = implementation-planning final report 가 생성되면 validator 가 `contract-violated` 로 종료합니다.
+- `Gate result` 가 `blocked-by-disagreement` / `aborted-non-result` 인데 상단 `User Approval Request` 체크박스 라인이 존재하면 동일하게 contract violation 입니다.
+
 ## 4.6 Release Handoff Deliverables (release-handoff runs only)
 
 > **이 섹션은 `task-type` = `release-handoff` 실행 결과에만 포함하세요. 다른 task-type에서는 섹션 전체를 삭제하고 5번 섹션으로 넘어갑니다.**

package/runtime/templates/reports/settings.template.json

@@ -131,14 +131,14 @@
       "Bash(codex exec:*)",
       "Bash(okstra)",
       "Bash(okstra:*)",
+      "Bash(npx okstra@latest:*)",
+      "Bash(npx -y okstra@latest:*)",
       "Bash($HOME/.okstra/bin/:*)",
+      "Bash(STATE_FILE=:*)",
 
       "Bash(gemini)",
       "Bash(gemini:*)",
 
-      "Bash($HOME/.okstra/bin/okstra-trace-cleanup.sh)",
-      "Bash($HOME/.okstra/bin/okstra-trace-cleanup.sh:*)",
-
       "Bash(claude)",
       "Bash(claude:*)",
 
@@ -150,7 +150,10 @@
     "SessionEnd": [
       {
         "hooks": [
-          { "type": "command", "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh" }
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh"
+          }
         ]
       }
     ]

package/runtime/validators/lib/fixtures.sh

@@ -51,8 +51,7 @@ write_validation_brief() {
 
 - Config file: \`.claude/settings.json\`
   - Expected values:
-    - project-local okstra Claude assets must remain discoverable under \`.claude/skills/\` and \`.claude/agents/\`
-    - refresh should occur only when \`--refresh-assets\` is used
+    - installed okstra Claude assets must remain discoverable under \`~/.claude/skills/\` and \`~/.claude/agents/\` (managed by \`okstra install\`)
 - Config file: \`.project-docs/okstra/discovery/latest-task.json\`
   - Expected values:
     - latest prepared task pointer must include the current task key
@@ -257,6 +256,15 @@ if isinstance(lead, dict):
     lead["status"] = "completed"
 team_state["workflowState"] = "worker-results-collected"
 
+# validate-run.py requires team-state.teamCreate.attempted=true with a
+# status of ok|error once any worker has been dispatched (see
+# validators/validate-run.py:334-337). Mirror that here so the fixture
+# represents a valid post-Phase-3 state.
+team_state["teamCreate"] = {
+    "attempted": True,
+    "status": "ok",
+}
+
 # Phase 7 token-usage collection is normally produced by okstra-token-usage.py.
 # The validator (`team-state.usageSummary is empty`) treats absence as a contract
 # violation, so the fixture must mirror that step with a synthetic-but-valid object.

package/runtime/validators/lib/validate-assets.sh

@@ -1,40 +1,66 @@
 # shellcheck shell=bash
 
+# Verify that the npm build output under `runtime/` is fresh and matches the
+# source files that `okstra install` (src/install.mjs) copies into the user's
+# `~/.claude/skills/`, `~/.claude/agents/`, and `~/.okstra/` directories.
+#
+# Historically this validator checked a *project-local* `.claude/skills/` +
+# `.claude/agents/` tree that `okstra.sh` seeded into the project root on
+# every run. That seeding step was removed when install moved into
+# `src/install.mjs`; install now writes only to the user's
+# `$HOME/.claude` + `$HOME/.okstra`, never to the project root. The runtime/
+# tree is the canonical staging area that `okstra install` rsyncs from, so we
+# validate parity there instead.
 validate_seeded_assets() {
   local validation_mode="$1"
+  local runtime_root="$WORKSPACE_ROOT/runtime"
 
-  python3 - "$SOURCE_ASSET_ROOT" "$PROJECT_ROOT/.claude" "$validation_mode" <<'PY'
+  if [[ ! -d "$runtime_root" ]]; then
+    printf 'runtime/ build output is missing — run `npm run build` before validating.\n' >&2
+    return 1
+  fi
+
+  python3 - "$SOURCE_ASSET_ROOT" "$WORKSPACE_ROOT/skills" "$runtime_root" "$validation_mode" <<'PY'
 from pathlib import Path
 import sys
 
-source_root = Path(sys.argv[1])
-target_root = Path(sys.argv[2])
-validation_mode = sys.argv[3]
+agents_source_root = Path(sys.argv[1])      # <repo>/agents
+skills_source_root = Path(sys.argv[2])      # <repo>/skills
+runtime_root = Path(sys.argv[3])            # <repo>/runtime
+validation_mode = sys.argv[4]
 errors = []
 
-for source_path in sorted(source_root.rglob("*.md")):
-    relative_path = source_path.relative_to(source_root)
-    parts = relative_path.parts
-
-    if relative_path.as_posix() == "SKILL.md":
-        target_path = target_root / "skills" / "okstra" / "SKILL.md"
-    elif parts[0] == "skills":
-        target_path = target_root / "skills" / Path(*parts[1:])
-    elif parts[0] == "workers":
-        # `agents/workers/<name>.md` 는 `.claude/agents/<name>.md` 로 시드된다.
-        # seeding.sh 의 분기와 동일하게 유지해야 한다.
-        target_path = target_root / "agents" / Path(*parts[1:])
-    elif parts[0] == "agents":
-        target_path = target_root / "agents" / Path(*parts[1:])
-    else:
-        target_path = target_root / "skills" / "okstra" / relative_path
 
+def check(source_path: Path, target_path: Path) -> None:
     if not target_path.is_file():
-        errors.append(f"missing seeded asset: {target_path}")
-        continue
-
+        errors.append(f"missing build-output asset: {target_path}")
+        return
     if validation_mode == "match" and target_path.read_bytes() != source_path.read_bytes():
-        errors.append(f"seeded asset content does not match source: {target_path}")
+        errors.append(f"build-output asset does not match source: {target_path}")
+
+
+# 1. Worker agent files: agents/workers/*-worker.md -> runtime/agents/workers/*-worker.md
+workers_source = agents_source_root / "workers"
+workers_target = runtime_root / "agents" / "workers"
+if not workers_source.is_dir():
+    errors.append(f"missing agents/workers source directory: {workers_source}")
+else:
+    for source_path in sorted(workers_source.glob("*.md")):
+        check(source_path, workers_target / source_path.name)
+
+# 2. Lead agent SKILL.md: agents/SKILL.md -> runtime/agents/SKILL.md
+lead_source = agents_source_root / "SKILL.md"
+if lead_source.is_file():
+    check(lead_source, runtime_root / "agents" / "SKILL.md")
+
+# 3. Skill packages: skills/<name>/SKILL.md -> runtime/skills/<name>/SKILL.md
+if not skills_source_root.is_dir():
+    errors.append(f"missing skills source directory: {skills_source_root}")
+else:
+    for skill_dir in sorted(p for p in skills_source_root.iterdir() if p.is_dir()):
+        for source_path in sorted(skill_dir.rglob("*.md")):
+            relative = source_path.relative_to(skills_source_root)
+            check(source_path, runtime_root / "skills" / relative)
 
 if errors:
     for error in errors:

package/runtime/validators/validate-brief.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python3
+"""Validate brief markdown files produced by the okstra-brief skill.
+
+Checks performed per brief file:
+
+1. YAML frontmatter exists on line 1 with required keys.
+2. brief-id matches the filename stem.
+3. depth equals the number of `sub/` segments in the path (relative to the
+   `briefs/` root).
+4. Every Open Questions row starts with one of the five signal prefixes
+   (general | terminology | intent-check | conversion-block | adr-candidate).
+   `adr-candidate:` targets okstra-internal
+   `<PROJECT_ROOT>/.project-docs/okstra/decisions/`, not external `docs/adr/`.
+5. Every Augmentation entry (inline `> augmented: <label>` blockquotes and
+   `Augmentation` section bullets) carries one of the four labels
+   (evidence-link | format-conversion | terminology-mapping | intent-inference).
+   Both documented forms are accepted: `label: ...` and `label — ...`.
+6. Every `intent-inference` augmentation has a corresponding
+   `intent-check:` row in Open Questions (auto-mirroring rule).
+7. Every `terminology-mapping` augmentation (excluding Step 4.5 outcome
+   markers `applied glossary:` / `skipped glossary:`) has a corresponding
+   `terminology:` row in Open Questions.
+8. `parent-id` chain: at depth 0 the value MUST be the literal `self`;
+   at depth ≥ 1 it MUST NOT be `self` and MUST differ from the brief's
+   own `brief-id`.
+9. `reporter-confirmations` consistency: when `complete`, every
+   `intent-check:` and `conversion-block:` row in Open Questions MUST
+   carry a `[CONFIRMED YYYY-MM-DD → RC-N]` marker.
+
+Exit code 0 on PASS, 1 on FAIL.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+REQUIRED_FRONTMATTER_KEYS = {
+    "type",
+    "brief-id",
+    "parent-id",
+    "ticket-id",
+    "source-type",
+    "task-group",
+    "depth",
+    "created",
+    "generator",
+    "reporter-confirmations",
+}
+
+OPEN_QUESTIONS_PREFIXES = {
+    "general:",
+    "terminology:",
+    "intent-check:",
+    "conversion-block:",
+    "adr-candidate:",
+}
+
+AUGMENTATION_LABELS = {
+    "evidence-link",
+    "format-conversion",
+    "terminology-mapping",
+    "intent-inference",
+}
+
+REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, str], int]:
+    """Return (frontmatter dict, line after closing `---`)."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError("missing opening frontmatter delimiter on line 1")
+    out: dict[str, str] = {}
+    for idx in range(1, len(lines)):
+        line = lines[idx]
+        if line.strip() == "---":
+            return out, idx + 1
+        # naive key: value (comments after #)
+        bare = line.split("#", 1)[0].strip()
+        if not bare:
+            continue
+        if ":" not in bare:
+            raise ValueError(f"frontmatter line without colon: {line!r}")
+        key, _, value = bare.partition(":")
+        out[key.strip()] = value.strip()
+    raise ValueError("missing closing frontmatter delimiter")
+
+
+def section_body(text: str, heading: str) -> str:
+    """Return the body lines between `## <heading>` and the next `## ` heading."""
+    pattern = re.compile(
+        r"^##\s+" + re.escape(heading) + r"\s*$(.*?)(?=^##\s|\Z)",
+        re.MULTILINE | re.DOTALL,
+    )
+    match = pattern.search(text)
+    if not match:
+        return ""
+    return match.group(1)
+
+
+def is_placeholder(line: str) -> bool:
+    bare = line.strip().lstrip("-").strip()
+    return bare in {"_(none)_", "_(none — pending or skipped)_", ""}
+
+
+def is_template_example(line: str) -> bool:
+    """Lines that are template scaffolding (placeholder/example), not real entries."""
+    bare = line.strip().lstrip("-").strip()
+    return bare.startswith("<") and bare.endswith(">")
+
+
+def open_questions_rows(text: str) -> list[str]:
+    body = section_body(text, "Open Questions")
+    rows: list[str] = []
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        content = stripped[2:].strip()
+        if is_placeholder(content) or is_template_example(content):
+            continue
+        # strip backticks if the row body is wrapped in `…`
+        content = content.strip("`")
+        rows.append(content)
+    return rows
+
+
+def augmentation_entries(text: str) -> list[str]:
+    """Bullets under the `## Augmentation` section (entries that look like real data)."""
+    body = section_body(text, "Augmentation")
+    entries: list[str] = []
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        content = stripped[2:].strip()
+        if is_placeholder(content) or is_template_example(content):
+            continue
+        # strip backticks
+        content = content.strip("`")
+        entries.append(content)
+    return entries
+
+
+def inline_augmented_blockquotes(text: str) -> list[str]:
+    """Lines starting with `> augmented:`."""
+    out: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("> augmented:"):
+            payload = stripped[len("> augmented:"):].strip()
+            if payload.startswith("<") and payload.endswith(">"):
+                # template scaffold, e.g. `> augmented: <label> — <interpretation>`
+                continue
+            out.append(payload)
+    return out
+
+
+def parse_augmentation_label(entry: str) -> tuple[str | None, str]:
+    """Return (label, payload) for documented augmentation forms."""
+    stripped = entry.strip()
+    for label in AUGMENTATION_LABELS:
+        if stripped == label:
+            return label, ""
+        for sep in (":", " — ", " - "):
+            prefix = f"{label}{sep}"
+            if stripped.startswith(prefix):
+                return label, stripped[len(prefix):].strip()
+    return None, stripped
+
+
+def validate_brief(path: Path, briefs_root: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    errors: list[str] = []
+
+    # 1. frontmatter
+    try:
+        fm, _ = parse_frontmatter(text)
+    except ValueError as exc:
+        return [f"frontmatter: {exc}"]
+
+    missing = REQUIRED_FRONTMATTER_KEYS - fm.keys()
+    if missing:
+        errors.append(f"frontmatter missing keys: {sorted(missing)}")
+
+    if fm.get("type") != "brief":
+        errors.append(f"frontmatter type must be 'brief', got {fm.get('type')!r}")
+
+    if fm.get("generator") != "okstra-brief":
+        errors.append(
+            f"frontmatter generator must be 'okstra-brief', got {fm.get('generator')!r}"
+        )
+
+    if fm.get("reporter-confirmations") not in REPORTER_CONFIRMATION_VALUES:
+        errors.append(
+            "frontmatter reporter-confirmations must be one of "
+            f"{sorted(REPORTER_CONFIRMATION_VALUES)}, got "
+            f"{fm.get('reporter-confirmations')!r}"
+        )
+
+    # 2. brief-id matches filename stem
+    stem = path.stem
+    if fm.get("brief-id") and fm["brief-id"] != stem:
+        errors.append(
+            f"brief-id {fm['brief-id']!r} does not match filename stem {stem!r}"
+        )
+
+    # 3. depth equals path's `sub/` nesting depth
+    try:
+        rel = path.relative_to(briefs_root)
+    except ValueError:
+        rel = path
+    # path components after the task-group dir: any number of `sub` segments + filename
+    parts = list(rel.parts)
+    if len(parts) >= 2:
+        nested = [p for p in parts[1:-1] if p == "sub"]
+        expected_depth = len(nested)
+        try:
+            actual_depth = int(fm.get("depth", "0"))
+        except ValueError:
+            actual_depth = -1
+        if actual_depth != expected_depth:
+            errors.append(
+                f"depth mismatch: path has {expected_depth} `sub/` segments, "
+                f"frontmatter says depth={fm.get('depth')!r}"
+            )
+
+    # 4. Open Questions prefixes
+    oq_rows = open_questions_rows(text)
+    intent_check_rows: list[str] = []
+    terminology_rows: list[str] = []
+    conversion_block_rows: list[str] = []
+    for row in oq_rows:
+        if not any(row.startswith(prefix) for prefix in OPEN_QUESTIONS_PREFIXES):
+            errors.append(f"Open Questions row lacks a known prefix: {row!r}")
+        if row.startswith("intent-check:"):
+            intent_check_rows.append(row)
+        elif row.startswith("terminology:"):
+            terminology_rows.append(row)
+        elif row.startswith("conversion-block:"):
+            conversion_block_rows.append(row)
+
+    # 5. Augmentation labels
+    augmentation_lines: list[str] = []
+    augmentation_lines.extend(augmentation_entries(text))
+    augmentation_lines.extend(inline_augmented_blockquotes(text))
+    intent_inference_count = 0
+    terminology_mapping_count = 0
+    for entry in augmentation_lines:
+        label, payload = parse_augmentation_label(entry)
+        if label not in AUGMENTATION_LABELS:
+            errors.append(
+                f"Augmentation entry lacks a known label: {entry!r} "
+                f"(label parsed as {label!r})"
+            )
+            continue
+        if label == "intent-inference":
+            intent_inference_count += 1
+        elif label == "terminology-mapping":
+            # Step 4.5 outcome markers do not need a paired Open Questions row.
+            if payload.startswith("applied glossary:") or payload.startswith(
+                "skipped glossary:"
+            ):
+                continue
+            terminology_mapping_count += 1
+
+    # 6. auto-mirroring rule (intent-inference ↔ intent-check:)
+    if intent_inference_count > len(intent_check_rows):
+        errors.append(
+            f"intent-inference augmentations present ({intent_inference_count}) "
+            f"but only {len(intent_check_rows)} intent-check: row(s) in Open Questions"
+        )
+
+    # 7. dual-record rule (terminology-mapping ↔ terminology:)
+    if terminology_mapping_count > 0 and not terminology_rows:
+        errors.append(
+            f"terminology-mapping augmentations present ({terminology_mapping_count}) "
+            f"but no terminology: row(s) in Open Questions"
+        )
+
+    # 8. parent-id chain
+    parent_id = fm.get("parent-id", "")
+    brief_id = fm.get("brief-id", "")
+    try:
+        depth_value = int(fm.get("depth", "0"))
+    except ValueError:
+        depth_value = -1
+    if depth_value == 0:
+        if parent_id != "self":
+            errors.append(
+                f"parent-id for the root (depth 0) brief must be 'self', "
+                f"got {parent_id!r}"
+            )
+    elif depth_value > 0:
+        if parent_id == "self":
+            errors.append(
+                f"parent-id for a descendant (depth {depth_value}) brief must not be 'self'"
+            )
+        elif parent_id == brief_id:
+            errors.append(
+                f"parent-id for a descendant brief must differ from its own brief-id "
+                f"({brief_id!r})"
+            )
+
+    # 9. reporter-confirmations consistency
+    rc_status = fm.get("reporter-confirmations")
+    if rc_status == "complete":
+        unconfirmed = [
+            row
+            for row in (intent_check_rows + conversion_block_rows)
+            if "[CONFIRMED" not in row
+        ]
+        if unconfirmed:
+            sample = unconfirmed[0]
+            errors.append(
+                f"reporter-confirmations is 'complete' but {len(unconfirmed)} "
+                f"intent-check:/conversion-block: row(s) lack a [CONFIRMED …] "
+                f"marker (e.g. {sample!r})"
+            )
+
+    return errors
+
+
+def find_briefs(root: Path) -> Iterable[Path]:
+    yield from root.rglob("*.md")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "briefs_dir",
+        type=Path,
+        help="Directory containing brief markdown files (recursed).",
+    )
+    parser.add_argument(
+        "--briefs-root",
+        type=Path,
+        default=None,
+        help=(
+            "Root used for depth computation (defaults to briefs_dir). "
+            "Usually `<PROJECT_ROOT>/.project-docs/okstra/briefs`."
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    briefs_dir: Path = args.briefs_dir
+    if not briefs_dir.exists():
+        print(f"[FAIL] briefs directory not found: {briefs_dir}", file=sys.stderr)
+        return 1
+
+    briefs_root: Path = args.briefs_root or briefs_dir
+
+    total = 0
+    failed_files: list[tuple[Path, list[str]]] = []
+    for brief in find_briefs(briefs_dir):
+        total += 1
+        errors = validate_brief(brief, briefs_root)
+        if errors:
+            failed_files.append((brief, errors))
+
+    if total == 0:
+        print(f"[PASS] no briefs found under {briefs_dir} (nothing to validate)")
+        return 0
+
+    if not failed_files:
+        print(f"[PASS] {total} brief(s) validated under {briefs_dir}")
+        return 0
+
+    for path, errors in failed_files:
+        print(f"[FAIL] {path}")
+        for err in errors:
+            print(f"  - {err}")
+    print(
+        f"[FAIL] {len(failed_files)}/{total} brief(s) failed validation",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/validators/validate-brief.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# Validate brief markdown files produced by okstra-brief.
+#
+# Usage:
+#   validators/validate-brief.sh <briefs-dir> [--briefs-root <dir>]
+#
+# Typical invocation (inside a project that has run okstra-setup):
+#   validators/validate-brief.sh "$PROJECT_ROOT/.project-docs/okstra/briefs"
+#
+# Thin bash entrypoint — delegates to validate-brief.py for content checks.
+
+set -euo pipefail
+
+SOURCE_PATH="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE_PATH" ]]; do
+  SOURCE_DIR="$(cd -P "$(dirname "$SOURCE_PATH")" && pwd)"
+  SOURCE_PATH="$(readlink "$SOURCE_PATH")"
+  [[ "$SOURCE_PATH" != /* ]] && SOURCE_PATH="$SOURCE_DIR/$SOURCE_PATH"
+done
+
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE_PATH")" && pwd)"
+PYTHON_VALIDATOR="$SCRIPT_DIR/validate-brief.py"
+
+if [[ ! -f "$PYTHON_VALIDATOR" ]]; then
+  echo "[FAIL] python helper not found: $PYTHON_VALIDATOR" >&2
+  exit 1
+fi
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $0 <briefs-dir> [--briefs-root <dir>]" >&2
+  exit 1
+fi
+
+exec python3 "$PYTHON_VALIDATOR" "$@"