okstra 0.83.0 → 0.84.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.83.0",
+  "version": "0.84.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.83.0",
-  "builtAt": "2026-06-15T16:01:38.767Z",
+  "package": "0.84.0",
+  "builtAt": "2026-06-15T18:39:25.947Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/okstra-coding-preflight/scripts/preedit-check.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# PreToolUse hook for okstra-coding-preflight.
+#
+# Inspects the target file path of a Write/Edit/MultiEdit/NotebookEdit
+# call. If the extension matches a language covered by this skill,
+# emits a `hookSpecificOutput.additionalContext` JSON payload that
+# reminds the agent to invoke the skill before writing.
+#
+# Fires at most once per session per language (marker file).
+# Exits 0 in every case — never blocks the tool call.
+
+set -euo pipefail
+
+input="$(cat)"
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
+case "$tool_name" in
+  Write|Edit|MultiEdit|NotebookEdit) ;;
+  *) exit 0 ;;
+esac
+
+file_path="$(printf '%s' "$input" \
+  | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty')"
+[[ -z "$file_path" ]] && exit 0
+
+lang=""
+ref=""
+extra_hint=""
+case "$file_path" in
+  *.java)
+    lang="Java"
+    ref="languages/java.md"
+    ;;
+  *.kt|*.kts)
+    lang="Kotlin"
+    ref="languages/kotlin.md"
+    ;;
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)
+    lang="JavaScript-TypeScript"
+    ref="languages/javascript-typescript.md"
+    extra_hint=" If this file is part of a Node.js server (Express/Fastify/Nest/etc.), also read languages/nodejs.md."
+    ;;
+  *.py)
+    lang="Python"
+    ref="languages/python.md"
+    ;;
+  *.sql)
+    lang="SQL"
+    ref="languages/sql.md"
+    ;;
+  *.rs)
+    lang="Rust"
+    ref="languages/rust.md"
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+session_id="$(printf '%s' "$input" | jq -r '.session_id // "no-session"')"
+marker_dir="${TMPDIR:-/tmp}/mcbsc"
+mkdir -p "$marker_dir"
+marker="${marker_dir}/${session_id}_${lang}"
+
+if [[ -f "$marker" ]]; then
+  exit 0
+fi
+
+: > "$marker"
+
+skill_root="$HOME/.okstra/prompts/okstra-coding-preflight"
+msg="[okstra-coding-preflight] About to edit a ${lang} file (${file_path}). Before writing, you MUST Read ${skill_root}/${ref} plus ${skill_root}/clean-code.md (the skill is user-invocable:false — read the files directly).${extra_hint} If the project uses ports-and-adapters (domain/ + ports/ + adapters/, *.port.* files), also Read ${skill_root}/architecture/hexagonal.md. (Fires once per session per language.)"
+
+jq -nc \
+  --arg event "PreToolUse" \
+  --arg ctx "$msg" \
+  '{hookSpecificOutput: {hookEventName: $event, additionalContext: $ctx}}'
+
+exit 0

package/runtime/python/okstra_ctl/run.py

@@ -79,6 +79,7 @@ from .session import (
 from .pr_template import PrTemplateError, resolve_pr_template_path
 from .workers import (
     normalize_workers,
+    resolve_optional_workers,
     resolve_profile_workers,
     validate_workers_against_profile,
 )
@@ -1402,10 +1403,11 @@ def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str],
     if inp.task_type == "release-handoff":
         return [], ""
     profile_workers = resolve_profile_workers(profile_file)
+    optional_workers = resolve_optional_workers(profile_file)
     profile_workers_csv = ",".join(profile_workers)
     workers = normalize_workers(inp.workers_override or profile_workers_csv)
     if inp.workers_override.strip():
-        validate_workers_against_profile(workers, profile_workers)
+        validate_workers_against_profile(workers, profile_workers, optional_workers)
     if not workers:
         raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
     return workers, ",".join(workers)

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

@@ -145,7 +145,7 @@ If the user picked `Reporter input`, proceed to Step 1.A's sub-flow below — th
 - **Label**: "Source of this brief?"
 - **Options** (single-select):
   1. `File` — path to an existing markdown / txt / issue-export file
-  2. `Issue tracker ticket` — Linear / Jira / GitHub Issue / Notion key or URL
+  2. `Issue tracker ticket` — Linear URL/ Jira URL/ GitHub Issue URL/ Notion key or URL
   3. `Link URL` — general web page, blog, spec doc, design doc, etc.
   4. `User input` — synthesize from the current conversation context, or
      accept a short free-text from the user
@@ -678,7 +678,7 @@ Use the same template per brief file. In tracker mode producing a parent
 plus N children, you write **N+1 files** (each carries only its own Source
 Material).
 
-[`templates/reports/brief.template.md`](../../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.
+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.
 
@@ -710,6 +710,22 @@ Material).
   frontmatter.
 - `ticket-id` is populated only for tracker sources; leave it as an empty
   string otherwise.
+- `source-type` records the input origin (`file | linear | jira | github |
+  notion | url | user-input`).
+- `task-group` echoes the Step 2a value.
+- `created` is the brief's creation date (`YYYY-MM-DD`).
+- `generator: okstra-brief` is a fixed value.
+- `reporter-confirmations` is set by Step 6.5 (`complete | partial | pending |
+  skipped`).
+- `scope` is `codebase` for the codebase-scan variant; omit it (⇒
+  `reporter-input`) for the reporter-input variant.
+
+The required-key set (`type`, `brief-id`, `parent-id`, `ticket-id`,
+`source-type`, `task-group`, `depth`, `created`, `generator`,
+`reporter-confirmations`) and every consistency rule above are enforced by
+`~/.okstra/lib/validators/validate-brief.py` — run in
+Step 6.6. The byte-for-byte field shape remains the job of
+`~/.okstra/templates/reports/brief.template.md`.
 
 Echo the file path back on one line. Show the rendered brief to the user
 inline and ask:
@@ -750,8 +766,17 @@ cannot resolve:
 - `intent-check:` (auto-mirrored from `intent-inference` augmentations)
 - `conversion-block:` (translation failed in Step 3c)
 
-If the resulting list is empty, set `reporter-confirmations: complete` in
-the brief's frontmatter and skip the rest of this step.
+**Re-run reseed (rebuild from disk).** A prior run may have left this brief at
+`reporter-confirmations: partial` with some rows already answered. Before
+building the pending list, exclude every `intent-check:` / `conversion-block:`
+row that already carries a `[CONFIRMED <date> → RC-N]` marker — those were
+resolved in an earlier run and their answers already live under `## Reporter
+Confirmations`. Only the unmarked rows are pending this run. This mirrors the
+visited-set rebuild rule in Step 1b: confirmation state lives on disk, not in
+memory.
+
+If the resulting pending list is empty, set `reporter-confirmations: complete`
+in the brief's frontmatter and skip the rest of this step.
 
 ### 6.5b. Ask once: collect now or later
 
@@ -839,6 +864,37 @@ rows (`complete` / `partial` with remainder in the same file) or an
 explicit `skipped` signal that downstream phases consume per the
 "Brief consumption" addendum in `_common-contract.md`.
 
+## Step 6.6: Self-validate before hand-off
+
+After every brief is written (Step 5) and its `reporter-confirmations` state
+is set (Step 6.5), and **before** printing the Step 7 hand-off message, you
+MUST validate every brief produced this run. The validator enforces the
+labelled-handoff contract — required frontmatter keys, Augmentation labels,
+`intent-inference ↔ intent-check:` auto-mirroring, `parent-id`/`depth`
+consistency, `reporter-confirmations` markers, and the codebase-scan
+`scope`/`Scan Scope`/`Priority Lenses` rules.
+
+1. Run the validator over the briefs directory:
+
+   ```bash
+   ~/.okstra/lib/validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
+   ```
+
+   If you are working from a repo checkout instead of an install, the dev
+   copy is at `validators/validate-brief.sh`.
+
+2. If it exits non-zero, **fix the offending brief(s) and re-run**. Do NOT
+   print the Step 7 message until the validator passes.
+
+3. If neither validator copy is present, fall back to a manual checklist:
+   confirm each brief has all ten required frontmatter keys (`type`,
+   `brief-id`, `parent-id`, `ticket-id`, `source-type`, `task-group`,
+   `depth`, `created`, `generator`, `reporter-confirmations`); every
+   Augmentation entry carries one of the four labels; every `intent-inference`
+   has a paired `intent-check:` row; `parent-id` is `self` at depth 0 and a
+   real parent id below; and for `scope: codebase` briefs, `Scan Scope` is
+   non-empty and `Priority Lenses` lists 1–4 whitelist lenses.
+
 ## Step 7: Hand off
 
 Single brief:
@@ -866,13 +922,10 @@ started.
 
 ## Output Rules
 
-- All okstra-generated artifacts live under
-  `<PROJECT_ROOT>/.okstra/`. This skill's brief files go
-  under `.okstra/briefs/`; its glossary writes go to
-  `.okstra/glossary.md` (Step 4.5 approval flow).
-- Paths outside `<PROJECT_ROOT>/.okstra/**` are read-only
-  source material only when explicitly cited by the reporter. This skill
-  never writes outside okstra's subtree.
+- **Artifact-home** (see the "Artifact-home rule" section above): every write
+  stays under `<PROJECT_ROOT>/.okstra/` — briefs in `.okstra/briefs/`, glossary
+  in `.okstra/glossary.md` (Step 4.5). Paths outside that subtree are read-only
+  source material, and only when the reporter cited them.
 - **Verbatim source**: never paraphrase, summarize, restructure, or reorder
   the Source Material section. Only format conversion (ADF → MD, HTML → MD)
   is allowed, and the conversion must be annotated in the `format:` meta.
@@ -910,3 +963,4 @@ started.
 | URL fetch fails or 401 / login wall | intranet, paywall, JS-rendered page | Ask the user to paste the core body. Never guess. |
 | Tracker body is in non-MD format (ADF / HTML) | Jira description, Notion blocks | Convert format only, preserve semantics. Annotate the conversion in the `format:` meta. |
 | Brief comes out skeletal after synthesis | source too thin AND user picked `User input` with little context | Switch to inline input mode and ask one or two targeted questions. |
+| `validate-brief` exits non-zero in Step 6.6 | missing frontmatter key, unlabelled augmentation, broken auto-mirroring, or codebase-scan lens out of whitelist | Read the validator's per-row message, fix the cited brief, re-run. Never print the Step 7 hand-off until it passes. |

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

@@ -360,7 +360,7 @@ If a run never reached Phase 7, its `team-state` lacks `durationMs`. Mark such r
 3. Multiple matches → list candidates (`taskKey`, `taskType`, `updatedAt`) and ask the user to pick.
 4. Read `historyTimelinePath` from the chosen entry.
 
-If `task-catalog.json` is missing: `No okstra history found. Run scripts/okstra.sh first.`
+If `task-catalog.json` is missing: `No okstra history found. Run /okstra-run first.`
 
 ### time.2 — Walk runs and collect durations
 

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

@@ -236,7 +236,7 @@ The validator rejects any of these patterns.
 
 ## Section Contract (required)
 
-The canonical template lives at `templates/reports/schedule.template.md`. **Read it before writing the schedule** and follow it byte-for-byte for headings.
+The canonical template lives at `~/.okstra/templates/reports/schedule.template.md`. **Read it before writing the schedule** and follow it byte-for-byte for headings.
 
 ### MUST — exact ordered heading list
 
@@ -441,14 +441,14 @@ After writing the file and before printing the completion message in Step 7, you
 1. **Re-read the file** you just wrote.
 2. **Run the validator**:
    ```bash
-   python3 validators/validate-schedule.py <output-path>
+   python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
    ```
 3. If the validator exits non-zero, **fix the file and re-validate**. Do not print the completion message until the validator passes.
-4. If `validators/validate-schedule.py` is not present in the repo, fall back to a manual checklist: confirm each of the 11 mandatory headings from `### MUST — exact ordered heading list` (above) appears in the file with that exact spelling, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
+4. If `~/.okstra/lib/validators/validate-schedule.py` is not present, fall back to a manual checklist: confirm each of the 11 mandatory headings from `### MUST — exact ordered heading list` (above) appears in the file with that exact spelling, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
 
 ## Schedule Document Template
 
-[`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md) is the byte-for-byte SSOT for section ordering, heading spelling, table columns, and per-section HTML-comment guidance (Dependency Graph Shape A/B, Gantt rules, optional Glossary gate). Do not omit sections; if data is unavailable, render the section with `_없음_` rather than skipping it.
+The installed template `~/.okstra/templates/reports/schedule.template.md` is the byte-for-byte SSOT for section ordering, heading spelling, table columns, and per-section HTML-comment guidance (Dependency Graph Shape A/B, Gantt rules, optional Glossary gate). Do not omit sections; if data is unavailable, render the section with `_없음_` rather than skipping it.
 
 The two rules below complement the template — they encode COMPUTATION that the template scaffold cannot carry inline.
 

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

@@ -250,8 +250,8 @@ back it up as `.bak.<timestamp>` rather than overwriting silently.
 ## Step 4.8 (optional, opt-in): register a project PR body template
 
 `release-handoff` fills the PR body from a template. By default it uses the
-bundled skill template at
-`~/.claude/skills/templates/prd/pr-body.template.md`. Most projects
+installed template at
+`~/.okstra/templates/prd/pr-body.template.md`. Most projects
 want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
 keep PRs consistent with what the team already merges manually.
 

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

@@ -14,140 +14,31 @@
       "WebFetch",
       "WebSearch",
       "TodoWrite",
-
-      "Bash(pwd)",
-      "Bash(cd)",
-      "Bash(cd:*)",
-
-      "Bash(ls)",
-      "Bash(ls:*)",
-      "Bash(cat:*)",
-      "Bash(head:*)",
-      "Bash(tail:*)",
-      "Bash(wc:*)",
-
-      "Bash(git)",
-      "Bash(git:*)",
-      "Bash(gh)",
-      "Bash(gh:*)",
-
-      "Bash(rg:*)",
-      "Bash(grep:*)",
-      "Bash(find:*)",
-      "Bash(diff:*)",
-
-      "Bash(jq:*)",
-      "Bash(yq:*)",
-      "Bash(awk:*)",
-      "Bash(sed:*)",
-      "Bash(tr:*)",
-      "Bash(sort:*)",
-      "Bash(uniq:*)",
-      "Bash(xargs:*)",
-
-      "Bash(mkdir:*)",
-      "Bash(cp:*)",
-      "Bash(mv:*)",
-      "Bash(rm:*)",
-      "Bash(chmod:*)",
-
-      "Bash(printf:*)",
-      "Bash(echo)",
-      "Bash(echo:*)",
-      "Bash(export:*)",
-      "Bash(env)",
-      "Bash(env:*)",
-      "Bash(test:*)",
-      "Bash(true)",
-      "Bash(true:*)",
-      "Bash(false)",
-      "Bash(false:*)",
-
-      "Bash(bash:*)",
-      "Bash(sh:*)",
-      "Bash(eval:*)",
-
-      "Bash(python)",
-      "Bash(python:*)",
-      "Bash(python3)",
-      "Bash(python3:*)",
-      "Bash(pip)",
-      "Bash(pip:*)",
-      "Bash(pip3)",
-      "Bash(pip3:*)",
-      "Bash(uv:*)",
-      "Bash(poetry:*)",
-      "Bash(pytest:*)",
-
-      "Bash(node)",
-      "Bash(node:*)",
-      "Bash(npm)",
-      "Bash(npm:*)",
-      "Bash(npx)",
-      "Bash(npx:*)",
-      "Bash(pnpm)",
-      "Bash(pnpm:*)",
-      "Bash(yarn)",
-      "Bash(yarn:*)",
-      "Bash(tsc)",
-      "Bash(tsc:*)",
-
-      "Bash(cargo)",
-      "Bash(cargo:*)",
-      "Bash(rustc)",
-      "Bash(rustc:*)",
-
-      "Bash(go)",
-      "Bash(go:*)",
-      "Bash(java)",
-      "Bash(java:*)",
-      "Bash(javac)",
-      "Bash(javac:*)",
-      "Bash(mvn)",
-      "Bash(mvn:*)",
-      "Bash(gradle)",
-      "Bash(gradle:*)",
-      "Bash(./gradlew)",
-      "Bash(./gradlew:*)",
-      "Bash(make)",
-      "Bash(make:*)",
-
-      "Bash(docker)",
-      "Bash(docker:*)",
-      "Bash(docker compose)",
-      "Bash(docker compose:*)",
-      "Bash(docker-compose)",
-      "Bash(docker-compose:*)",
-      "Bash(kubectl)",
-      "Bash(kubectl:*)",
-      "Bash(helm)",
-      "Bash(helm:*)",
-
-      "Bash(curl:*)",
-      "Bash(wget:*)",
-
-      "Bash(codex)",
-      "Bash(codex:*)",
-      "Bash(codex exec:*)",
       "Bash(okstra)",
       "Bash(okstra:*)",
       "Bash(npx okstra@latest:*)",
       "Bash(npx -y okstra@latest:*)",
       "Bash($HOME/.okstra/bin/:*)",
-      "Bash(STATE_FILE=:*)",
-      "Bash(ROOT=:*)",
-
+      "Bash(codex)",
+      "Bash(codex:*)",
       "Bash(gemini)",
       "Bash(gemini:*)",
-
       "Bash(claude)",
-      "Bash(claude:*)",
-
-      "mcp__test-context7__resolve-library-id",
-      "mcp__test-context7__query-docs"
+      "Bash(claude:*)"
     ]
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.okstra/prompts/okstra-coding-preflight/scripts/preedit-check.sh\""
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/runtime/validators/validate-brief.py

@@ -25,7 +25,13 @@ Checks performed per brief file:
    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.
+   carry a `[CONFIRMED YYYY-MM-DD → RC-N]` marker; when `partial`, at
+   least one such row MUST carry the marker (use `skipped` when nothing
+   was answered).
+10. `scope` is one of {reporter-input, codebase} (absent ⇒ reporter-input).
+11. codebase-scan variant (`scope: codebase`): the Scan Scope section is
+    non-empty and Priority Lenses lists 1–4 values from the lens whitelist
+    (`scripts/okstra_ctl/improvement_lenses.py` SSOT).
 
 Exit code 0 on PASS, 1 on FAIL.
 """
@@ -38,6 +44,19 @@ import sys
 from pathlib import Path
 from typing import Iterable
 
+# scripts/ (repo) or python/ (installed under ~/.okstra/lib) is not a package;
+# insert whichever exists so okstra_ctl is importable for the lens whitelist.
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
+
+from okstra_ctl.improvement_lenses import (
+    LENSES,
+    MAX_PRIORITY_LENSES,
+    MIN_PRIORITY_LENSES,
+)
+
 REQUIRED_FRONTMATTER_KEYS = {
     "type",
     "brief-id",
@@ -68,6 +87,8 @@ AUGMENTATION_LABELS = {
 
 REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
 
+SCOPE_VALUES = {"reporter-input", "codebase"}
+
 
 def parse_frontmatter(text: str) -> tuple[dict[str, str], int]:
     """Return (frontmatter dict, line after closing `---`)."""
@@ -173,6 +194,68 @@ def parse_augmentation_label(entry: str) -> tuple[str | None, str]:
     return None, stripped
 
 
+def meaningful_bullets(text: str, heading: str) -> list[str]:
+    """Real `- ` bullets under a heading, excluding placeholders/template scaffold."""
+    body = section_body(text, heading)
+    out: 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
+        out.append(content.strip("`"))
+    return out
+
+
+def priority_lens_values(text: str) -> list[str]:
+    """Lens tokens from the `## Priority Lenses` bullets (`- <lens>: <rationale>`)."""
+    return [
+        bullet.split(":", 1)[0].strip()
+        for bullet in meaningful_bullets(text, "Priority Lenses")
+    ]
+
+
+def check_codebase_scope(text: str, errors: list[str]) -> None:
+    """codebase-scan variant: Scan Scope non-empty, Priority Lenses ⊆ whitelist."""
+    if not meaningful_bullets(text, "Scan Scope"):
+        errors.append("scope is 'codebase' but the Scan Scope section has no entries")
+    lenses = priority_lens_values(text)
+    if not (MIN_PRIORITY_LENSES <= len(lenses) <= MAX_PRIORITY_LENSES):
+        errors.append(
+            f"Priority Lenses must list {MIN_PRIORITY_LENSES}–{MAX_PRIORITY_LENSES} "
+            f"lens(es), found {len(lenses)}"
+        )
+    unknown = [lens for lens in lenses if lens not in LENSES]
+    if unknown:
+        errors.append(
+            f"Priority Lenses contains values outside the lens whitelist: {unknown} "
+            f"(allowed: {sorted(LENSES)})"
+        )
+
+
+def check_reporter_confirmations(
+    rc_status: str | None, reporter_rows: list[str], errors: list[str]
+) -> None:
+    """`complete` ⇒ every reporter row confirmed; `partial` ⇒ at least one."""
+    confirmed = [row for row in reporter_rows if "[CONFIRMED" in row]
+    if rc_status == "complete":
+        unconfirmed = [row for row in reporter_rows if "[CONFIRMED" not in row]
+        if unconfirmed:
+            errors.append(
+                f"reporter-confirmations is 'complete' but {len(unconfirmed)} "
+                f"intent-check:/conversion-block: row(s) lack a [CONFIRMED …] "
+                f"marker (e.g. {unconfirmed[0]!r})"
+            )
+    elif rc_status == "partial" and reporter_rows and not confirmed:
+        errors.append(
+            "reporter-confirmations is 'partial' but no intent-check:/"
+            "conversion-block: row carries a [CONFIRMED …] marker "
+            "(use 'skipped' when nothing was answered)"
+        )
+
+
 def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     text = path.read_text(encoding="utf-8")
     errors: list[str] = []
@@ -202,6 +285,15 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
             f"{fm.get('reporter-confirmations')!r}"
         )
 
+    scope = fm.get("scope", "reporter-input")
+    if scope not in SCOPE_VALUES:
+        errors.append(
+            f"frontmatter scope must be one of {sorted(SCOPE_VALUES)} "
+            f"(or absent ⇒ reporter-input), got {scope!r}"
+        )
+    if scope == "codebase":
+        check_codebase_scope(text, errors)
+
     # 2. brief-id matches filename stem
     stem = path.stem
     if fm.get("brief-id") and fm["brief-id"] != stem:
@@ -306,21 +398,12 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
                 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})"
-            )
+    # 9. reporter-confirmations consistency (complete / partial)
+    check_reporter_confirmations(
+        fm.get("reporter-confirmations"),
+        intent_check_rows + conversion_block_rows,
+        errors,
+    )
 
     return errors