okstra 0.96.1 → 0.97.0

package/runtime/python/okstra_token_usage/collect.py

@@ -13,10 +13,9 @@ from .claude import (
     find_claude_agent_sessions,
     find_claude_team_sessions,
 )
-from .codex import codex_session_total, find_codex_session, find_codex_sessions
+from .codex import codex_session_total, find_codex_sessions
 from .antigravity import (
     antigravity_session_total,
-    find_antigravity_session,
     find_antigravity_sessions,
 )
 from .paths import claude_project_dir, utc_now
@@ -342,6 +341,39 @@ def _cli_usage_block(provider: str, totals: dict, session_paths: list[Path]) ->
     return block
 
 
+def _attach_cli_usage(
+    block: dict,
+    provider: str,
+    project_root: Path,
+    wrapper_start: str,
+    wrapper_end: str,
+) -> None:
+    """Layer aggregated CLI token/cost onto a Claude-side worker ``block``.
+
+    A codex/antigravity worker re-dispatched within one aggregated wrapper
+    window produces several rollout jsonls; pricing only the latest (the old
+    ``find_codex_session`` -> ``sessions[-1]`` behavior) dropped the earlier
+    attempts' tokens. We sum every in-window session here so the redispatched
+    CLI spend is fully reported. (agy print mode leaves no transcript, so the
+    antigravity path still resolves to "session not found" → na cost.)
+    """
+    session_paths = _cli_sessions_for_windows(
+        provider, project_root, [(wrapper_start, wrapper_end)]
+    )
+    if not session_paths:
+        block["cliNote"] = f"{provider} CLI session not found in wrapper window (fallback or never invoked)"
+        return
+    block["cliSessionPaths"] = [str(path) for path in session_paths]
+    totals = _cli_session_totals(provider, session_paths)
+    if not totals:
+        block["cliNote"] = f"{provider} CLI session found but no usage recorded (likely errored before completion)"
+        return
+    cli = _cli_usage_block(provider, _aggregate_totals(totals), session_paths)
+    for key in ("cliTotalTokens", "cliEstimatedCostUsd", "cliModel"):
+        if key in cli:
+            block[key] = cli[key]
+
+
 def _collect_codex_runtime_usage(state: dict, project_root: Path) -> dict:
     windows_by_worker = _codex_worker_windows(project_root, state)
     state["leadUsage"] = na_block(
@@ -551,43 +583,16 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
             block["additionalSessionIds"] = [sid for sid, _, _ in matched[1:]]
             block["matchedAgentNames"] = sorted({t.get("agentName") for _, _, t in matched if t.get("agentName")})
 
-        # For codex/antigravity workers, find every CLI session that fell inside
-        # the aggregated wrapper window. (agy print mode leaves no transcript, so
-        # the antigravity path always resolves to "session not found" → na cost.)
-        wrapper_start = aggregate.get("startedAt") or ""
-        wrapper_end = aggregate.get("endedAt") or ""
+        # For codex/antigravity workers, sum every CLI session that fell inside
+        # the aggregated wrapper window (re-dispatches leave one rollout each).
         if agent in ("codex", "antigravity"):
-            if agent == "codex":
-                cli = find_codex_session(cwd, wrapper_start, wrapper_end)
-                cli_totals = codex_session_total(cli) if cli else None
-            else:
-                cli = find_antigravity_session(cwd, wrapper_start, wrapper_end)
-                cli_totals = antigravity_session_total(cli) if cli else None
-            if cli is None:
-                block["cliNote"] = f"{agent} CLI session not found in wrapper window (fallback or never invoked)"
-            else:
-                block["cliSessionPath"] = str(cli)
-                if cli_totals.get("model"):
-                    block["cliModel"] = cli_totals["model"]
-                if cli_totals.get("available"):
-                    block["cliTotalTokens"] = cli_totals["totalTokens"]
-                    if agent == "codex":
-                        cost = codex_cost_usd(
-                            cli_totals.get("model"),
-                            cli_totals.get("inputTokens", 0) or 0,
-                            cli_totals.get("cachedInputTokens", 0) or 0,
-                            cli_totals.get("outputTokens", 0) or 0,
-                        )
-                    else:
-                        cost = antigravity_cost_usd(
-                            cli_totals.get("model"),
-                            cli_totals.get("inputTokens", 0) or 0,
-                            cli_totals.get("outputTokens", 0) or 0,
-                        )
-                    if cost is not None:
-                        block["cliEstimatedCostUsd"] = cost
-                else:
-                    block["cliNote"] = f"{agent} CLI session found but no usage recorded (likely errored before completion)"
+            _attach_cli_usage(
+                block,
+                agent,
+                cwd,
+                aggregate.get("startedAt") or "",
+                aggregate.get("endedAt") or "",
+            )
         worker["usage"] = block
 
     # Fold team-tagged worker sessions that carry no agentName into the worker

package/runtime/skills/okstra-brief/SKILL.md

@@ -54,6 +54,13 @@ okstra-brief (codebase-scan variant)
       → okstra-run (implementation)
         → okstra-run (final-verification)
           → okstra-run (release-handoff)
+
+okstra-brief (error-feedback variant)
+  → okstra-run (error-analysis)
+    → okstra-run (implementation-planning)
+      → okstra-run (implementation)
+        → okstra-run (final-verification)
+          → okstra-run (release-handoff)
 ```
 
 ## When to use
@@ -135,6 +142,7 @@ Parse the JSON from stdout:
 - **Options**:
   1. `Reporter input` — reporter 발화 / 티켓 / 링크 / 자유 텍스트를 verbatim 으로 흡수. 기존 4-source 흐름.
   2. `Codebase scan` — 코드베이스 범위 + lens 우선순위만 받아 `improvement-discovery` phase 의 입력을 생성.
+  3. `Error feedback` (`error-feedback`) — `okstra error-zip` 이 만든 `.zip` 의 빈발 클러스터 1개를 `error-analysis` brief 로 변환 (okstra 자가수정용).
 
 ### 1.A. Reporter input (variant 1)
 
@@ -342,6 +350,29 @@ Validation (before Step 4 sharpening):
 
 Once validation passes, jump to Step 2 (task key).
 
+### 1.C. Error feedback (`error-feedback`, variant 3) — okstra 자가수정용
+
+If the user picked `Error feedback`, the input is a `.zip` produced by `okstra error-zip --out <path>`. 이 variant 는 빈발 에러 클러스터 1개를 골라 `error-analysis` brief 로 변환하며, **수정 대상은 okstra 레포 자신**이다.
+
+입력: `okstra error-zip` 이 만든 `.zip`. 사용자에게 zip 경로를 묻는다(이전에 받은 경로가 있으면 `Recommended:` 로 재사용 제안).
+
+1. zip 의 `report.md` 를 읽어 빈발 클러스터 표를 사용자에게 보여주고, **클러스터 1개**를 고르게 한다.
+   `AskUserQuestion` (single-select, `직접 지정` always last):
+   1. top-1 클러스터 (빈도 최다) — `Recommended:` 표시.
+   2. top-2 클러스터.
+   3. `직접 지정` — 사용자가 표에서 직접 클러스터를 지정.
+2. 고른 클러스터의 익명화 레코드를 brief 의 `## Source Material` 에 인용한다 — zip 내부 `errors/anonymized.jsonl` 에서 **선택한 클러스터 번호(`report.md` 표의 `#`)와 일치하는 `clusterId` 레코드**만 추려, errorType · command · exitCode · phase · agent · 대표 메시지를 표/리스트로 옮긴다. (`#` ↔ `clusterId` 는 1:1 대응이며, 같은 errorType+phase+agent 라도 정규화 메시지가 다르면 별개 클러스터다 — 병합하지 않는다.)
+3. frontmatter `scope` 는 reporter-input 으로 둔다 — 이 variant 는 익명화 에러 레코드를 `## Source Material` 에 verbatim 으로 담는 reporter-input 계열이므로 `scope` 키를 생략한다(⇒ `reporter-input`). codebase-scan 전용 키(`priority-lenses`·`scan-scope` 등)는 쓰지 않는다. 다음 phase 신호는 Step 6 의 `Recommended next phase: error-analysis` 헤더 줄로 보낸다(별도 frontmatter 키를 만들지 않는다). 본문에는 수정 대상을 명시한다: "이 에러는 okstra 런타임/프롬프트/래퍼/권한 seed 결함 신호이며, 수정 대상은 okstra 소스(`prompts/`·`agents/`·`scripts/`·`templates/`)다."
+4. **단일 클러스터 = 단일 실패조건** 원칙을 지킨다 — 이질적 errorType 을 한 brief 에 섞지 않는다(`error-analysis` 의 symptom-lock 요건). 다른 클러스터도 고치고 싶으면 클러스터마다 별도 brief 를 만든다.
+5. 생성된 brief 끝에 다음 단계를 인라인으로 적는다: "okstra 레포에서 `okstra-run --task-type error-analysis` 로 이 brief 를 실행하세요."
+
+Validation (before Step 4 sharpening):
+
+- zip 경로가 실제 존재하고 `report.md` + `errors/anonymized.jsonl` 을 포함하는지 확인 — 없으면 한 질문으로 정정.
+- 고른 클러스터가 단일 errorType 인지 확인 — 여러 errorType 이 섞이면 한 질문으로 1개만 남긴다.
+
+Once validation passes, jump to Step 2 (task key).
+
 ## Step 2: Identify task key & filename
 
 ### 2a. Task group
@@ -717,21 +748,21 @@ Material).
 
 The installed template `~/.okstra/templates/reports/brief.template.md` is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, section ordering, and inline `<!-- author guidance -->` HTML comments. Render that file with the per-brief values substituted; leave any section's body as `_(none)_` rather than fabricating content. Preserve the template's HTML comments verbatim (they are part of the contract) but do NOT promote them to body prose.
 
-**Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to both variants.
+**Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). For the error-feedback variant (`scope` omitted ⇒ `reporter-input`), use the reporter-input shape: KEEP `## Source Material` (the chosen cluster's anonymized error records) and `## Problem / Symptom`, and OMIT the codebase-only `## Scan Scope` / `## Priority Lenses` sections. The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to all variants.
 
 ### Required sections by variant
 
-| Section | `reporter-input` variant | `codebase` variant |
-|---|---|---|
-| `## Source Material` | Required | Not required — omit |
-| `## Problem / Symptom` | Required | Not required — omit |
-| `## Context` | Required | Required |
-| `## Desired Outcome` | Required | Required |
-| `## Constraints` | Required | Required |
-| `## Related Artifacts` | Required | Required |
-| `## Open Questions` | Required | Required |
-| `## Scan Scope` | Not applicable — omit | Required — one bullet per `scan-scope` path with a short description of what lives there |
-| `## Priority Lenses` | Not applicable — omit | Required — one bullet per priority lens with a short rationale for why that lens applies to this scope |
+| Section | `reporter-input` variant | `codebase` variant | `error-feedback` variant |
+|---|---|---|---|
+| `## Source Material` | Required | Not required — omit | Required — anonymized error records of the chosen cluster |
+| `## Problem / Symptom` | Required | Not required — omit | Required |
+| `## Context` | Required | Required | Required |
+| `## Desired Outcome` | Required | Required | Required |
+| `## Constraints` | Required | Required | Required |
+| `## Related Artifacts` | Required | Required | Required |
+| `## Open Questions` | Required | Required | Required |
+| `## Scan Scope` | Not applicable — omit | Required — one bullet per `scan-scope` path with a short description of what lives there | Not applicable — omit |
+| `## Priority Lenses` | Not applicable — omit | Required — one bullet per priority lens with a short rationale for why that lens applies to this scope | Not applicable — omit |
 
 ### Frontmatter rules
 

package/runtime/skills/okstra-inspect/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: okstra-inspect
 description: |
-  Use for any read-side okstra inspection or status mutation. Single skill dispatches by sub-command to eight facets — status, history, report, time, logs, cost, errors, recap. Trigger words include "okstra status", "task status", "current phase", "next phase", "okstra status set", "okstra mark", "<task-id> done|in-progress|진행중|완료", "okstra history", "past runs", "re-run", "resume", "list tasks", "find report", "show report for", "read the okstra report", "continue from report", "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석", "okstra logs", "로그 현황", "로그 파일", "log size", "log status", "로그 정리", "log cleanup", "okstra context-cost", "context cost", "context-cost", "컨텍스트 비용", "읽기 비용", "산출물 비용", "okstra errors", "error report", "에러 리포트", "에러 보고", "에러 모아줘", "okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문", "실패 로그 정리".
+  Use for any read-side okstra inspection or status mutation. Single skill dispatches by sub-command to nine facets — status, history, report, time, logs, cost, errors, error-zip, recap. Trigger words include "okstra status", "task status", "current phase", "next phase", "okstra status set", "okstra mark", "<task-id> done|in-progress|진행중|완료", "okstra history", "past runs", "re-run", "resume", "list tasks", "find report", "show report for", "read the okstra report", "continue from report", "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석", "okstra logs", "로그 현황", "로그 파일", "log size", "log status", "로그 정리", "log cleanup", "okstra context-cost", "context cost", "context-cost", "컨텍스트 비용", "읽기 비용", "산출물 비용", "okstra errors", "error report", "에러 리포트", "에러 보고", "에러 모아줘", "okstra error-zip", "에러 zip", "에러 환류", "에러 번들", "cross-project 에러", "okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문", "실패 로그 정리".
 ---
 
 # OKSTRA Inspect
@@ -17,6 +17,7 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `logs` | Inventory codex/antigravity wrapper `.log` sidecars; emit cleanup commands. |
 | `cost` | Estimate file/read context cost for a task bundle. |
 | `errors` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
+| `error-zip` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
 | `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`. |
 
 ## Step 0: Verify okstra runtime + project setup (shared)
@@ -38,6 +39,8 @@ Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this ski
 
 Classify the user's request into one sub-command using the trigger table above. If ambiguous (e.g. "okstra 보여줘"), ask which facet — do not silently default. After routing, the chosen sub-command's section below governs the rest of the response.
 
+When you ask which facet, the option list is **authoritative**: enumerate every sub-command in the `Sub-command | What it does` table above as a numbered text list, in table order, each with its one-line description, and let the user pick by number or name. Never present a hand-picked subset — the AskUserQuestion 4-option cap is not a reason to drop facets; render the full menu as text in the question body so no facet (e.g. a newly added one) is ever hidden. The table is the single source of truth for this menu; adding a row there is all it takes for the facet to appear here.
+
 When the user chains multiple facets in one message (e.g. "status, and then time for DEV-9047"), execute them sequentially — Step 0 runs once, each sub-command section runs once.
 
 ---
@@ -759,6 +762,46 @@ Parse the stdout JSON and report:
 
 ---
 
+## error-zip
+
+Trigger phrases: "okstra error-zip", "에러 zip", "에러 환류", "에러 번들", "cross-project 에러".
+
+머신 내 모든 타겟 프로젝트의 okstra 실행 에러(`runs/*/logs/errors-*.jsonl`)를 글로벌 run-index 로 수집·익명화해 `.zip`(집계 리포트 + 익명화 JSONL)으로 묶는다. 모든 타겟의 `.okstra/` 에 대해 read-only.
+
+### error-zip.1 — 출력 경로 결정 (picker)
+
+이전 출력 경로를 `~/.okstra/error-zip.json` 의 `lastOutputPath` 에서 읽는다. 그 값이 있으면 3-옵션 picker 로 제시:
+
+1. (이전 경로 있음) `<lastOutputPath>` 재사용 — 추천, 첫 옵션.
+   (이전 경로 없음) 기본 경로 `~/okstra-error-feedback-<YYYY-MM-DD>.zip` 제안 — 추천.
+2. 직접 입력 (항상 마지막 옵션).
+
+`~/.okstra/error-zip.json` 읽기는 Read 로 직접 수행한다(없으면 이전 경로 없음으로 간주).
+
+### error-zip.2 — 렌더 실행
+
+```bash
+okstra error-zip --out <결정된 경로>
+```
+
+### error-zip.3 — 요약 보고
+
+stdout JSON 을 파싱해 보고:
+
+| 필드 | 출처 |
+|---|---|
+| 출력 zip | `outPath` |
+| 총 에러 | `errorCount` |
+| 로그(run) | `runCount` |
+| 도달 불가 run | `unreachableRuns` |
+| 클러스터 수 | `clusterCount` |
+| 프로젝트 수 | `projectCount` |
+
+- `unreachableRuns > 0` 이면 표면화한다(침묵 누락 금지).
+- 끝에 다음 단계를 안내한다: "이 zip 으로 okstra 자신을 고치려면 `/okstra-brief` 의 error-feedback variant 로 brief 를 만든 뒤 `okstra-run --task-type error-analysis` 를 okstra 레포에서 실행하세요."
+
+---
+
 ## recap
 
 Trigger phrases: "okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문".

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

@@ -340,7 +340,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 
 | {{ t("releaseHandoff.questionsTableHeader.questionId") }} | {{ t("releaseHandoff.questionsTableHeader.questionBody") }} | {{ t("releaseHandoff.questionsTableHeader.userResponse") }} | {{ t("releaseHandoff.questionsTableHeader.allowedOptions") }} |
 |---------|-----------|--------------------|--------------------|
-| H1 | {{ t("releaseHandoff.h1Body") }} | `{{ releaseHandoff.userSelections.h1 | mdcell }}` | `local only` / `push + PR` / `skip` |
+| H1 | {{ t("releaseHandoff.h1Body") }} | `{{ releaseHandoff.userSelections.h1 | mdcell }}` | `local checkout` / `push + PR` / `skip` |
 | H2 | {{ t("releaseHandoff.h2Body") }} | `{{ (releaseHandoff.userSelections.h2 or t("releaseHandoff.h2DefaultLabel")) | mdcell }}` | {{ t("releaseHandoff.h2OptionsLabel") }} |
 | H2b | Merge conflict probe | `{{ (releaseHandoff.userSelections.h2b or releaseHandoff.mergeConflictProbe.kind) | mdcell }}` | `not-run` / `clean` / `proceed anyway` / `change base branch` / `cancel` |
 | H3 | {{ t("releaseHandoff.h3Body") }} | `{{ releaseHandoff.userSelections.h3 | mdcell }}` | `use as-is` / `edit then proceed` / `cancel` |
@@ -372,7 +372,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 ### 5.6.6 Merge Conflict Probe
 
 {% if releaseHandoff.mergeConflictProbe.kind == 'not-run' -%}
-- Not run (user picked local only or skip).
+- Not run (user picked local checkout or skip).
 {%- elif releaseHandoff.mergeConflictProbe.kind == 'clean' -%}
 - Clean — no conflicts against {{ releaseHandoff.mergeConflictProbe.baseBranch }} at {{ releaseHandoff.mergeConflictProbe.baseSha }}.
 {%- else -%}

package/runtime/templates/reports/release-handoff-input.template.md

@@ -63,7 +63,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## User-Selection Defaults (advisory only — the user still chooses interactively)
 
-- Suggested action (Q1): `local only` | `push + PR` | `skip`
+- Suggested action (Q1): `local checkout` | `push + PR` | `skip`
 - Suggested base (Q2): one of the candidate base branches above
 - Suggested message handling (Q3): `use as-is` | `edit then proceed`
 

package/runtime/validators/forbidden_actions.py

@@ -36,7 +36,14 @@ _UNIVERSAL = [
     ("docker push", re.compile(r"\bdocker\s+push\b")),
     ("terraform apply", re.compile(r"\bterraform\s+apply\b")),
     ("kubectl apply", re.compile(r"\bkubectl\s+apply\b")),
-    ("git push --force", re.compile(r"\bgit\s+push\b.*(?:--force(-with-lease)?|\s-[A-Za-z]*f)")),
+    # 강제 push 만 잡는다: force 플래그가 같은 명령 절에 있어야 하므로 git push 와
+    # 플래그 사이의 gap 이 shell 구분자(`&&`/`||`/`;`/`|`/개행)를 넘지 못하게 막아
+    # `git push origin && rm -rf …` 의 `-rf` 같은 후속 명령 토큰을 오탐하지 않는다.
+    # 단문자 플래그 클러스터는 `f` 가 어디에 있든(`-qf`/`-fq`) 매칭한다.
+    (
+        "git push --force",
+        re.compile(r"\bgit\s+push\b[^\n;&|]*(?:--force(-with-lease)?\b|\s-[A-Za-z]*f[A-Za-z]*\b)"),
+    ),
 ]
 _NON_HANDOFF_PUSH = ("git push", re.compile(r"\bgit\s+push\b"))
 

package/runtime/validators/validate-brief.py

@@ -90,6 +90,18 @@ REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
 SCOPE_VALUES = {"reporter-input", "codebase"}
 
 
+def strip_yaml_comment(line: str) -> str:
+    """Drop a YAML inline comment, keeping `#` that is part of a value.
+
+    Per YAML, `#` starts a comment only at line start or after whitespace;
+    a `#` glued to a non-space char (e.g. `ticket-id: PROJ-42#thread`) is data.
+    """
+    for i, ch in enumerate(line):
+        if ch == "#" and (i == 0 or line[i - 1].isspace()):
+            return line[:i]
+    return line
+
+
 def parse_frontmatter(text: str) -> tuple[dict[str, str], int]:
     """Return (frontmatter dict, line after closing `---`)."""
     lines = text.splitlines()
@@ -100,8 +112,7 @@ def parse_frontmatter(text: str) -> tuple[dict[str, str], int]:
         line = lines[idx]
         if line.strip() == "---":
             return out, idx + 1
-        # naive key: value (comments after #)
-        bare = line.split("#", 1)[0].strip()
+        bare = strip_yaml_comment(line).strip()
         if not bare:
             continue
         if ":" not in bare:

package/runtime/validators/validate-run.py

@@ -1225,6 +1225,16 @@ _GATE_RESULT_RE = re.compile(
     re.IGNORECASE,
 )
 
+# §5.5.9 Plan Body Verification section body — scopes the gate-result search
+# so an earlier prose mention of "Gate result" elsewhere in the report cannot
+# hijack the authoritative value. Matched from the `Plan Body Verification`
+# heading to the next heading (or end-of-file).
+_PLAN_BODY_VERIFICATION_BLOCK_RE = re.compile(
+    r"^#{2,}[ \t][^\n]*\bPlan Body Verification\b[^\n]*\n"
+    r"(?P<body>.*?)(?=^#{2,}[ \t]|\Z)",
+    re.DOTALL | re.MULTILINE,
+)
+
 # Frontmatter approval flag — `approved: true|false` line inside the
 # leading `---` YAML block. Mirrors `APPROVED_FRONTMATTER_PATTERN` in
 # scripts/okstra_ctl/run.py.
@@ -1232,7 +1242,10 @@ _APPROVED_FRONTMATTER_RE = re.compile(
     r"^approved:[ \t]+(true|false)[ \t]*$",
     re.IGNORECASE | re.MULTILINE,
 )
-_FRONTMATTER_BLOCK_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
+# Tolerate a leading UTF-8 BOM and/or blank lines before the opening `---`
+# so a hand-edited or differently-rendered report does not silently bypass
+# the approved-frontmatter gate (the `.match` would otherwise return None).
+_FRONTMATTER_BLOCK_RE = re.compile(r"\A\ufeff?\s*---\n(.*?)\n---\n", re.DOTALL)
 _REQUIREMENT_COVERAGE_HEADING_RE = re.compile(
     r"^###[ \t]+(?:5\.5\.8[ \t]+)?Requirement Coverage\b",
     re.IGNORECASE | re.MULTILINE,
@@ -1339,7 +1352,10 @@ def _append_requirement_coverage_failures(
         return
 
     for row_id, status in rows:
-        if not re.fullmatch(r"covered|gap|blocked C-\d{3,}", status):
+        # `status` is already lower-cased at parse time, so the blocker form
+        # arrives as `blocked c-001`; match lower-case here even though the
+        # canonical authored form (and the remedy message) is `blocked C-NNN`.
+        if not re.fullmatch(r"covered|gap|blocked c-\d{3,}", status):
             failures.append(
                 "implementation-planning Requirement Coverage row "
                 f"`{row_id}` has invalid Status `{status}`; expected "
@@ -1697,8 +1713,8 @@ def validate_phase_boundary(
                 "release-handoff report is missing `### 5.6.6 Merge Conflict "
                 "Probe` sub-section — required by the release-handoff profile "
                 "(self-review 6, merge-conflict probe audit). When the run is "
-                "`local only` / `skip`, record the single line `- Not run "
-                "(user picked local only or skip).` under the heading."
+                "`local checkout` / `skip`, record the single line `- Not run "
+                "(user picked local checkout or skip).` under the heading."
             )
 
     if task_type != "implementation-planning":
@@ -1710,7 +1726,12 @@ def validate_phase_boundary(
                 f"`{needle}`"
             )
 
-    gate_match = _GATE_RESULT_RE.search(content)
+    # Scope the gate-result search to the §5.5.9 Plan Body Verification block
+    # so an earlier prose mention of "Gate result" cannot hijack the value.
+    pbv_block = _PLAN_BODY_VERIFICATION_BLOCK_RE.search(content)
+    gate_match = (
+        _GATE_RESULT_RE.search(pbv_block.group("body")) if pbv_block else None
+    )
     if gate_match is None:
         # The `Plan Body Verification` heading check above already covers
         # the wholly-missing case; a heading present without a `Gate result`
@@ -2044,7 +2065,7 @@ def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
             (team_state.get("leadUsage") or {}).get("source") == "unavailable"
         )
         workers_unavailable = any(
-            (w or {}).get("usage", {}).get("source") == "unavailable"
+            ((w or {}).get("usage") or {}).get("source") == "unavailable"
             for w in (team_state.get("workers") or [])
         )
         if lead_unavailable or workers_unavailable:

package/runtime/validators/validate-schedule.py

@@ -128,7 +128,7 @@ DAYS_TOTAL_RE = re.compile(
 # generically as `<2+ uppercase letters>-<digits>` and then filtered against
 # the TASK-ID whitelist (extracted from At a Glance) so legitimate task
 # references (`DEV-1234`, `MOBILE-42`) pass through.
-OPAQUE_DASHED_CODE_RE = re.compile(r"\b([A-Z]{1,5})-(\d+)\b")
+OPAQUE_DASHED_CODE_RE = re.compile(r"\b([A-Z]{2,5})-(\d+)\b")
 
 # Decision-item letter codes (`A1`, `B2`, `C3`, `D4`). These represent
 # approval/decision items in source reports and are forbidden in the schedule
@@ -229,7 +229,6 @@ def validate(path: Path) -> list[str]:
     task_heading_re = re.compile(r"^###\s+\d+-\d+\.\s+", re.MULTILINE)
     for m in task_heading_re.finditer(text):
         start = m.start()
-        block_end = start
         # find the next ### or ## heading
         next_h = re.search(r"^(##\s|###\s)", text[start + len(m.group(0)):], re.MULTILINE)
         block = text[start: start + len(m.group(0)) + (next_h.start() if next_h else len(text))]

package/runtime/validators/validate_improvement_report.py

@@ -75,11 +75,25 @@ def _candidate_cap(brief_frontmatter: dict) -> int:
         return DEFAULT_CANDIDATE_CAP
 
 
+def _as_path_list(value) -> list[str]:
+    """Normalize a frontmatter scope field to a list of path strings.
+
+    ``_parse_brief_frontmatter`` only returns a list for inline-flow ``[a, b]``
+    syntax; a scalar ``scan-scope: src/`` arrives as a bare string. Iterating a
+    string yields characters, so coerce a scalar into a single-element list.
+    """
+    if isinstance(value, str):
+        return [value] if value.strip() else []
+    return list(value)
+
+
 def _scope_subset(
     candidate_scope_csv: str,
     scan_scope: list[str],
     out_of_scope: list[str],
 ) -> tuple[bool, str]:
+    scan_scope = _as_path_list(scan_scope)
+    out_of_scope = _as_path_list(out_of_scope)
     paths = [p.strip() for p in candidate_scope_csv.split(",") if p.strip()]
     if not paths:
         return False, "empty Scope"