okstra 0.142.0 → 0.143.0

package/runtime/python/okstra_ctl/run.py

@@ -102,6 +102,10 @@ from .worktree import (
     WorktreeProvision,
     provision_task_worktree,
 )
+from .brief_frontmatter import (
+    has_reporter_confirmation_contract,
+    read_brief_frontmatter,
+)
 
 # Frontmatter approval-flag matcher.
 #
@@ -854,6 +858,7 @@ class _ResolvedAssets:
     final_report_template: Path
     lead_contract: Path
     run_validator: Path
+    brief_validator: Path
 
 
 def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _ResolvedAssets:
@@ -877,7 +882,14 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
     )
     lead_contract = workspace_root / "prompts" / "lead" / "okstra-lead-contract.md"
     run_validator = workspace_root / "validators" / "validate-run.py"
-    for required in (task_index_template, final_report_template, run_validator, lead_contract):
+    brief_validator = workspace_root / "validators" / "validate-brief.py"
+    for required in (
+        task_index_template,
+        final_report_template,
+        run_validator,
+        brief_validator,
+        lead_contract,
+    ):
         if not required.is_file():
             raise PrepareError(
                 f"required okstra template or lead contract missing: {required}.{_INSTALL_HINT}"
@@ -889,12 +901,49 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
         final_report_template=final_report_template,
         lead_contract=lead_contract,
         run_validator=run_validator,
+        brief_validator=brief_validator,
     )
 
 
+def _validate_task_brief_preflight(
+    project_root: Path,
+    brief_path: Path,
+    validator_path: Path,
+) -> None:
+    """Validate canonical briefs before any prepare-time side effects."""
+    frontmatter = read_brief_frontmatter(brief_path)
+    if not has_reporter_confirmation_contract(frontmatter):
+        return
+
+    proc = _subprocess.run(
+        [
+            sys.executable,
+            str(validator_path),
+            str(brief_path),
+            "--briefs-root",
+            str(project_root / ".okstra" / "briefs"),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        detail = " ".join(
+            line.strip()
+            for output in (proc.stdout, proc.stderr)
+            for line in output.splitlines()
+            if line.strip()
+        )
+        raise PrepareError(f"task brief failed validation: {detail}")
+    if frontmatter["reporter-confirmations"] == "pending":
+        raise PrepareError(
+            "task brief reporter-confirmations is pending; rerun okstra-brief-gen "
+            "Step 6.5 before starting error-analysis"
+        )
+
+
 def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
-    """project_root/brief 존재와 task-type 별 입력 의미(plan 승인·stage·clarification)
-    를 검증하고, implementation 일 때 stage map 을 파싱해 돌려준다 (그 외엔 빈 리스트)."""
+    """Validate pure prepare inputs and return a final-verification stage map."""
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
     if inp.stages and inp.task_type != "release-handoff":
@@ -911,41 +960,14 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
         raise PrepareError(f"task brief not found: {inp.brief_path}")
     ctx_stage_map: list = []
     # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
-    # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope). plan-presence +
-    # stage-map 파싱은 공유하고, frontmatter 승인/option 주입/구조 검증 같은
-    # implementation 전용 단계만 따로 게이트한다.
+    # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope).
     if inp.task_type in ("implementation", "final-verification"):
         if not inp.approved_plan_path:
             raise PrepareError(
                 f"task-type {inp.task_type} requires "
                 "--approved-plan <path-to-final-report.md>"
             )
-        if inp.task_type == "implementation":
-            # --approve / --implementation-option 은 공유 approved-plan 파일에
-            # read-modify-write 한다. 같은 task-key 의 동시 stage run 둘이 둘 다
-            # 이 플래그를 주면 후발 write 가 선발의 frontmatter 변경을 덮어쓴다
-            # (lost update). 두 mutation 을 per-task-key 락으로 직렬화한다.
-            if inp.approve_plan_ack or inp.implementation_option:
-                with worktree_provision_mutex(
-                    okstra_home(), inp.project_id,
-                    slugify(inp.task_group), slugify(inp.task_id),
-                ):
-                    if inp.approve_plan_ack:
-                        # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로
-                        # 모델링한다. frontmatter approved 를 true 로 toggle 한 뒤
-                        # 동일한 검증 경로(`_validate_approved_plan`)를 통과시킨다.
-                        _apply_cli_approval(inp.approved_plan_path)
-                    if inp.implementation_option:
-                        # 유저가 고른 Option Candidate 이름을 approved-plan
-                        # frontmatter 의 `implementation-option:` 라인에 기록한다.
-                        # 빈 값이면 implementation 이 plan 의 `Recommended Option`
-                        # 으로 폴백하므로 호출하지 않는다.
-                        _apply_cli_implementation_option(
-                            inp.approved_plan_path, inp.implementation_option
-                        )
-            _validate_approved_plan(inp.approved_plan_path)
-            _validate_stage_structure(inp.approved_plan_path)
-        else:
+        if inp.task_type == "final-verification":
             # final-verification 에서 --approve / --implementation-option 은
             # 의미가 없다 (승인은 implementation 진입 시 이미 끝났다).
             if inp.approve_plan_ack:
@@ -958,7 +980,7 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
                     "--implementation-option is only meaningful with --task-type "
                     "implementation and --approved-plan <path>"
                 )
-        ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
+            ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
     else:
         if inp.approve_plan_ack:
             # implementation 외 task-type 에서 `--approve` 는 의미가 없다. 사용자에게
@@ -988,6 +1010,24 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     return ctx_stage_map
 
 
+def _prepare_implementation_approved_plan(inp: PrepareInputs) -> list:
+    """Apply approved-plan inputs only after canonical brief preflight succeeds."""
+    if inp.approve_plan_ack or inp.implementation_option:
+        with worktree_provision_mutex(
+            okstra_home(), inp.project_id,
+            slugify(inp.task_group), slugify(inp.task_id),
+        ):
+            if inp.approve_plan_ack:
+                _apply_cli_approval(inp.approved_plan_path)
+            if inp.implementation_option:
+                _apply_cli_implementation_option(
+                    inp.approved_plan_path, inp.implementation_option
+                )
+    _validate_approved_plan(inp.approved_plan_path)
+    _validate_stage_structure(inp.approved_plan_path)
+    return _parse_stage_map_into_ctx(inp.approved_plan_path)
+
+
 def _collect_handoff_source_report_rows(
     rows: list, nums: list,
 ) -> list:
@@ -2072,6 +2112,14 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     task_index_template = assets.task_index_template
     final_report_template = assets.final_report_template
     ctx_stage_map = _validate_prepare_inputs(project_root, inp)
+    if inp.task_type != "release-handoff":
+        _validate_task_brief_preflight(
+            project_root,
+            inp.brief_path,
+            assets.brief_validator,
+        )
+    if inp.task_type == "implementation":
+        ctx_stage_map = _prepare_implementation_approved_plan(inp)
 
     # release-handoff: 검증 보고서 인용 input 문서를 생성해 brief 자리에 채운다.
     # 이후의 모든 brief 소비 경로(material/instruction-set 복사)는 그대로 동작한다.

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -1,8 +1,9 @@
 """Build a task-type-scoped excerpt of the final-report schema.
 
 The full schema (``schemas/final-report-v1.0.schema.json``) carries the
-deliverable property blocks for ALL task-types (``implementationPlanning``,
-``releaseHandoff``, ``implementation``, ``finalVerification``) plus a
+deliverable property blocks for ALL task-types (``errorAnalysis``,
+``implementationPlanning``, ``releaseHandoff``, ``implementation``,
+``finalVerification``) plus a
 ``$defs`` library (~38% of the file) shared across them. A single run only
 authors ONE task-type's data.json, so the report-writer worker only needs
 the common structure + its own task-type's block + the ``$defs`` those
@@ -24,10 +25,11 @@ import json
 import re
 
 # task-type → the per-type deliverable property key it owns. task-types
-# absent from this map (requirements-discovery, error-analysis,
+# absent from this map (requirements-discovery,
 # improvement-discovery) have no per-type block; their excerpt keeps only
 # the common properties.
 _TASK_TYPE_PROPERTY = {
+    "error-analysis": "errorAnalysis",
     "implementation-planning": "implementationPlanning",
     "release-handoff": "releaseHandoff",
     "implementation": "implementation",

package/runtime/python/okstra_ctl/wizard.py

@@ -30,6 +30,7 @@ from pathlib import Path
 from typing import Any, Callable, Optional
 
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.brief_frontmatter import read_brief_frontmatter
 from okstra_ctl.models import (
     PROVIDER_MAPPINGS,
     UnknownModelError,
@@ -155,49 +156,6 @@ _RECENT_PREFIX = "__recent:"
 _REPORT_PREFIX = "__report:"
 _BRIEF_PREFIX = "__brief:"
 
-# Lines of `key: value` we pull from a brief markdown frontmatter. The
-# parser is intentionally lightweight (no yaml dep) and tolerant — a
-# malformed brief returns an empty dict.
-_BRIEF_FRONTMATTER_LINE_RE = re.compile(r"^([a-zA-Z0-9_\-]+)\s*:\s*(.*)$")
-
-
-def _parse_brief_frontmatter(path: Path) -> dict[str, str]:
-    """Read the YAML-style frontmatter at the top of a brief markdown file
-    and return a flat ``{key: value}`` map.
-
-    Returns ``{}`` if the file is unreadable, has no frontmatter, or the
-    frontmatter is malformed. Comments (``# ...``) and quoted values are
-    stripped. Placeholder values like ``<task-group>`` are kept verbatim;
-    callers decide whether to treat them as a real suggestion.
-    """
-    try:
-        text = path.read_text(encoding="utf-8")
-    except OSError:
-        return {}
-    if not text.startswith("---"):
-        return {}
-    lines = text.splitlines()
-    if not lines or lines[0].strip() != "---":
-        return {}
-    out: dict[str, str] = {}
-    for line in lines[1:]:
-        if line.strip() == "---":
-            break
-        # strip trailing inline comment
-        comment_idx = line.find("#")
-        if comment_idx >= 0:
-            line = line[:comment_idx]
-        m = _BRIEF_FRONTMATTER_LINE_RE.match(line.strip())
-        if not m:
-            continue
-        key, val = m.group(1), m.group(2).strip()
-        # strip matching quotes
-        if (len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"')):
-            val = val[1:-1]
-        out[key] = val
-    return out
-
-
 def _looks_like_template_placeholder(value: str) -> bool:
     """Treat ``<task-group>``, ``<...>``, empty strings, and ``self`` as
     non-suggestions. Anything else (a real slug-like value) is honored."""
@@ -223,7 +181,7 @@ def _brief_suggestions(path: Path) -> tuple[str, str]:
     A brief without frontmatter, or with placeholder values, yields two
     empty strings — callers fall back to plain-text input.
     """
-    fm = _parse_brief_frontmatter(path)
+    fm = read_brief_frontmatter(path)
     tg_raw = fm.get("task-group", "")
     bid_raw = fm.get("brief-id", "")
     tg = "" if _looks_like_template_placeholder(tg_raw) else tg_raw

package/runtime/schemas/final-report-v1.0.schema.json

@@ -384,6 +384,8 @@
       "items": { "$ref": "#/$defs/RiskRow" }
     },
 
+    "errorAnalysis": { "$ref": "#/$defs/ErrorAnalysis" },
+
     "implementationPlanning": {
       "type": "object",
       "description": "RENDER_IF taskType == implementation-planning. §5.5 deliverables.",
@@ -814,6 +816,16 @@
   },
 
   "allOf": [
+    {
+      "description": "error-analysis task-type requires a structured diagnosis block.",
+      "if": {
+        "properties": { "header": { "properties": { "taskType": { "const": "error-analysis" } } } },
+        "required": ["header"]
+      },
+      "then": {
+        "required": ["errorAnalysis"]
+      }
+    },
     {
       "description": "implementation-planning task-type requires §5.5 block.",
       "if": {
@@ -952,6 +964,7 @@
     "Direction": {
       "enum": [
         "continue-investigation",
+        "begin-planning",
         "begin-implementation",
         "approve",
         "reject",
@@ -959,6 +972,92 @@
       ]
     },
 
+    "ErrorAnalysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "symptomVerbatim",
+        "observableFailure",
+        "reproduction",
+        "causeCandidates",
+        "nextDiagnostic",
+        "routing"
+      ],
+      "properties": {
+        "symptomVerbatim": { "type": "string" },
+        "observableFailure": { "type": "string" },
+        "reproduction": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "evidence", "blockedReason"],
+          "properties": {
+            "status": {
+              "enum": ["reproduced", "not-reproduced", "blocked-before-repro"]
+            },
+            "evidence": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string" }
+            },
+            "blockedReason": { "type": "string" }
+          }
+        },
+        "causeCandidates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "statement",
+              "supportingEvidence",
+              "falsifyingEvidenceChecked",
+              "confidence",
+              "disproveWith"
+            ],
+            "properties": {
+              "id": { "type": "string", "pattern": "^EA-\\d{3,}$" },
+              "statement": { "type": "string" },
+              "supportingEvidence": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string" }
+              },
+              "falsifyingEvidenceChecked": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string" }
+              },
+              "confidence": { "enum": ["low", "medium", "high"] },
+              "disproveWith": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "nextDiagnostic": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["action", "confirmingSignal", "rejectingSignal"],
+          "properties": {
+            "action": { "type": "string", "minLength": 1 },
+            "confirmingSignal": { "type": "string", "minLength": 1 },
+            "rejectingSignal": { "type": "string", "minLength": 1 }
+          }
+        },
+        "routing": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["nextTaskType", "leadingCauseId", "rationale"],
+          "properties": {
+            "nextTaskType": {
+              "enum": ["error-analysis", "implementation-planning"]
+            },
+            "leadingCauseId": { "type": "string" },
+            "rationale": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+
     "TicketId": {
       "type": "string",
       "minLength": 1,

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

@@ -171,6 +171,32 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 {% endif %}
 
+{% if header.taskType == 'error-analysis' %}
+### 2.4 Error Analysis Result{% if t("errorAnalysis.heading") != "Error Analysis Result" %} ({{ t("errorAnalysis.heading") }}){% endif %}
+
+- **{{ t("errorAnalysis.symptomVerbatim") }}:** {{ errorAnalysis.symptomVerbatim }}
+- **{{ t("errorAnalysis.observableFailure") }}:** {{ errorAnalysis.observableFailure }}
+- **{{ t("errorAnalysis.reproductionStatus") }}:** `{{ errorAnalysis.reproduction.status }}`
+- **{{ t("errorAnalysis.reproductionEvidence") }}:** {{ errorAnalysis.reproduction.evidence | join(", ") }}
+{% if errorAnalysis.reproduction.blockedReason %}- **{{ t("errorAnalysis.blockedReason") }}:** {{ errorAnalysis.reproduction.blockedReason }}
+{% endif %}
+
+{% if errorAnalysis.causeCandidates | length == 0 -%}
+{{ t("emptyState.errorAnalysisCauseCandidates") }}
+{%- else %}
+| ID | {{ t("errorAnalysis.candidate") }} | {{ t("errorAnalysis.supportingEvidence") }} | {{ t("errorAnalysis.falsifyingEvidence") }} | {{ t("errorAnalysis.confidence") }} | {{ t("errorAnalysis.disproveWith") }} |
+|---|---|---|---|---|---|
+{% for row in errorAnalysis.causeCandidates -%}
+| {{ row.id | mdcell }} | {{ row.statement | mdcell }} | {{ row.supportingEvidence | join(", ") | mdcell }} | {{ row.falsifyingEvidenceChecked | join(", ") | mdcell }} | `{{ row.confidence | mdcell }}` | {{ row.disproveWith | mdcell }} |
+{% endfor %}
+{%- endif %}
+
+- **{{ t("errorAnalysis.nextDiagnostic") }}:** {{ errorAnalysis.nextDiagnostic.action }}
+- **{{ t("errorAnalysis.confirmingSignal") }}:** {{ errorAnalysis.nextDiagnostic.confirmingSignal }}
+- **{{ t("errorAnalysis.rejectingSignal") }}:** {{ errorAnalysis.nextDiagnostic.rejectingSignal }}
+- **{{ t("errorAnalysis.route") }}:** `{{ errorAnalysis.routing.nextTaskType }}`{% if errorAnalysis.routing.leadingCauseId %} — `{{ errorAnalysis.routing.leadingCauseId }}`{% endif %} — {{ errorAnalysis.routing.rationale }}
+{% endif %}
+
 ## 3. Recommended Next Steps
 
 {% if recommendedNextSteps | length == 0 -%}

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

@@ -19,7 +19,8 @@
     "lingeringRisks": "- No tracked lingering risks.",
     "noClarification": "- No additional information requested. The Section 7 verdict stands as-is.",
     "noFollowUp": "- No follow-up tasks. The next phase for this run is in §3 (Recommended Next Steps).",
-    "endStateCoverage": "No end-state coverage recorded for this phase."
+    "endStateCoverage": "No end-state coverage recorded for this phase.",
+    "errorAnalysisCauseCandidates": "No evidence-backed cause candidate yet."
   },
   "columns": {
     "recordMeta": "Record",
@@ -97,8 +98,25 @@
     "columnSections": "Sections",
     "columnRelatedIds": "Related item IDs"
   },
+  "errorAnalysis": {
+    "heading": "Error Analysis Result",
+    "symptomVerbatim": "Symptom Verbatim",
+    "observableFailure": "Observable Failure",
+    "reproductionStatus": "Reproduction Status",
+    "reproductionEvidence": "Reproduction Evidence",
+    "blockedReason": "Blocked Reason",
+    "candidate": "Cause Candidate",
+    "supportingEvidence": "Supporting Evidence",
+    "falsifyingEvidence": "Falsifying Evidence",
+    "confidence": "Confidence",
+    "disproveWith": "Disprove With",
+    "nextDiagnostic": "Next Diagnostic",
+    "confirmingSignal": "Confirming Signal",
+    "rejectingSignal": "Rejecting Signal",
+    "route": "Route"
+  },
   "finalVerdict": {
-    "intro": "This run's final conclusion and next action. **`Direction`** is the recommended next action — one of `continue-investigation`, `begin-implementation`, `approve`, `reject`, or `hold` — and is present for every task-type. **`Verdict Token`** is meaningful only for the `final-verification` task-type, where it is one of `accepted`, `conditional-accept`, or `blocked` and serves as the `release-handoff` entry gate. For every other task-type, `Verdict Token` is always `not-applicable`."
+    "intro": "This run's final conclusion and next action. **`Direction`** is the recommended next action — one of `continue-investigation`, `begin-planning`, `begin-implementation`, `approve`, `reject`, or `hold` — and is present for every task-type. `begin-planning` means the diagnosis is ready to enter `implementation-planning`. **`Verdict Token`** is meaningful only for the `final-verification` task-type, where it is one of `accepted`, `conditional-accept`, or `blocked` and serves as the `release-handoff` entry gate. For every other task-type, `Verdict Token` is always `not-applicable`."
   },
   "evidence": {
     "sourceItemsColumnNote": "The `Source items` column is described in §6.1."

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

@@ -19,7 +19,8 @@
     "lingeringRisks": "- 추적 대상 잔존 위험 없음.",
     "noClarification": "- 추가 정보 요청 없음. Section 7 의 최종 판단이 그대로 유효합니다.",
     "noFollowUp": "- 후속 작업 없음. 본 run 의 다음 phase 는 §3 (Recommended Next Steps) 참고.",
-    "endStateCoverage": "이번 phase 에 기록된 종료 상태 처리가 없습니다."
+    "endStateCoverage": "이번 phase 에 기록된 종료 상태 처리가 없습니다.",
+    "errorAnalysisCauseCandidates": "근거가 뒷받침하는 원인 후보가 아직 없습니다."
   },
   "columns": {
     "recordMeta": "항목",
@@ -97,8 +98,25 @@
     "columnSections": "등장 섹션",
     "columnRelatedIds": "관련 항목 IDs"
   },
+  "errorAnalysis": {
+    "heading": "오류 분석 결과",
+    "symptomVerbatim": "증상 원문",
+    "observableFailure": "관측된 실패",
+    "reproductionStatus": "재현 상태",
+    "reproductionEvidence": "재현 근거",
+    "blockedReason": "차단 사유",
+    "candidate": "원인 후보",
+    "supportingEvidence": "지지 근거",
+    "falsifyingEvidence": "반증 확인",
+    "confidence": "신뢰도",
+    "disproveWith": "반증 방법",
+    "nextDiagnostic": "다음 진단",
+    "confirmingSignal": "확인 신호",
+    "rejectingSignal": "기각 신호",
+    "route": "라우팅"
+  },
   "finalVerdict": {
-    "intro": "이 run 의 최종 결론과 다음 행동입니다. **`Direction`** 은 권장 다음 행동으로 `continue-investigation`(조사 계속) · `begin-implementation`(구현 시작) · `approve`(승인) · `reject`(반려) · `hold`(보류) 중 하나이며, 모든 task-type 에 존재합니다. **`Verdict Token`** 은 `final-verification` task-type 에서만 의미를 가집니다 — `accepted` · `conditional-accept` · `blocked` 중 하나로 `release-handoff` 진입 게이트로 쓰입니다. 그 외 task-type 에서 `Verdict Token` 은 항상 `not-applicable`(해당 없음) 입니다."
+    "intro": "이 run 의 최종 결론과 다음 행동입니다. **`Direction`** 은 권장 다음 행동으로 `continue-investigation`(조사 계속) · `begin-planning`(계획 시작) · `begin-implementation`(구현 시작) · `approve`(승인) · `reject`(반려) · `hold`(보류) 중 하나이며, 모든 task-type 에 존재합니다. `begin-planning`은 진단이 `implementation-planning`에 진입할 준비가 됐음을 뜻합니다. **`Verdict Token`** 은 `final-verification` task-type 에서만 의미를 가집니다 — `accepted` · `conditional-accept` · `blocked` 중 하나로 `release-handoff` 진입 게이트로 쓰입니다. 그 외 task-type 에서 `Verdict Token` 은 항상 `not-applicable`(해당 없음) 입니다."
   },
   "evidence": {
     "sourceItemsColumnNote": "`Source items` 열 설명은 §6.1 과 동일합니다."

package/runtime/validators/validate-brief.py

@@ -841,6 +841,10 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
 
 
 def find_briefs(root: Path) -> Iterable[Path]:
+    if root.is_file():
+        if root.suffix == ".md":
+            yield root
+        return
     yield from root.rglob("*.md")
 
 
@@ -849,7 +853,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "briefs_dir",
         type=Path,
-        help="Directory containing brief markdown files (recursed).",
+        help="Brief markdown file or directory containing brief files.",
     )
     parser.add_argument(
         "--briefs-root",