okstra 0.34.0 → 0.36.0

package/runtime/python/okstra_ctl/workflow.py

@@ -20,6 +20,7 @@ PHASE_SEQUENCE = [
 
 DEFAULT_NEXT_PHASE = {
     "requirements-discovery": "pending-routing-decision",
+    "improvement-discovery": "pending-routing-decision",
     "error-analysis": "implementation-planning",
     "implementation-planning": "implementation",
     "implementation": "final-verification",
@@ -47,6 +48,24 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - starting `error-analysis`, `implementation-planning`, or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
         ),
     },
+    "improvement-discovery": {
+        "allowed": (
+            "  - improvement candidate discovery within the lens whitelist defined in `scripts/okstra_ctl/improvement_lenses.py`\n"
+            "  - top-N ranking (default 8, brief `candidate-cap` overrides within 1..12)\n"
+            "  - per-candidate columns Lens / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Evidence (path:line)\n"
+            "  - Phase 1.5 reflect-back grilling log at `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`\n"
+            "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique)"
+        ),
+        "forbidden": (
+            "  - source code edits of any kind\n"
+            "  - implementation planning, root-cause analysis, builds, migrations, or deployments\n"
+            "  - starting `implementation-planning`, `implementation`, `error-analysis`, or any other lifecycle phase inside this run\n"
+            "  - generating candidates outside the lens whitelist (Lens enum violation rejects the report)\n"
+            "  - exceeding the candidate cap (absolute cap 12)\n"
+            "  - free external data fetch beyond the brief's Source Material or Phase 1.5 resolved scope\n"
+            "  - interpreting user phrases like `다음 단계 진행해` as authorisation to enter another phase"
+        ),
+    },
     "error-analysis": {
         "allowed": (
             "  - symptom and trigger evidence\n"
@@ -69,7 +88,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - bite-sized stepwise execution order for the recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
             "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
             "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 5. Clarification Items` table (do NOT create a separate `Open Questions` block under `4.5.x` — the unified table is the single home)\n"
-            "  - explicit `User Approval Request` block awaiting human approval\n"
+            "  - YAML frontmatter line `approved: false` awaiting human flip to `true`\n"
             "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)"
         ),
         "forbidden": (
@@ -95,7 +114,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - routing recommendation for `final-verification` (ready / needs new error-analysis or planning loop)"
         ),
         "forbidden": (
-            "  - any Edit/Write or state-mutating Bash before the pre-implementation gate passes (gate requires --approved-plan pointing to a final-report.md with a recorded user approval marker)\n"
+            "  - any Edit/Write or state-mutating Bash before the pre-implementation gate passes (gate requires --approved-plan pointing to a final-report.md whose frontmatter has `approved: true`)\n"
             "  - `git push` of any kind, `npm publish` / `cargo publish` / `pip publish`, `gh release`, `docker push`\n"
             "  - real database migrations, schema changes against shared environments, or writes to non-local datastores\n"
             "  - production credentials, deploy commands, infra mutation (`terraform apply`, `kubectl apply` against non-local cluster, etc.)\n"

package/runtime/python/okstra_ctl/worktree.py

@@ -43,7 +43,14 @@ from typing import Optional
 
 from .ids import _safe_fs_segment
 from . import worktree_registry
-from .seeding import SettingsLinkError, ensure_project_settings_symlink
+from .seeding import (
+    AgentsMdLinkError,
+    ClaudeMdLinkError,
+    SettingsLinkError,
+    ensure_project_agents_md,
+    ensure_project_claude_md,
+    ensure_project_settings_symlink,
+)
 
 
 # Project-root directories that hold okstra task state, ignored by git, or
@@ -390,6 +397,48 @@ def _seed_worktree_settings_symlink(worktree_path: Path) -> None:
         )
 
 
+def _seed_worktree_claude_md(worktree_path: Path) -> None:
+    """Seed `.project-docs/okstra/CLAUDE.md` symlink + `<worktree>/CLAUDE.md`
+    import block in the worker worktree so dispatched Claude sessions auto-load
+    okstra's runtime guidance. Mirrors `_seed_worktree_settings_symlink` —
+    needed because the worktree's `CLAUDE.md` comes from the git checkout (no
+    marker block unless committed) and `.project-docs/` is only dir-symlinked,
+    not its contents.
+    """
+    try:
+        link = ensure_project_claude_md(project_root=worktree_path)
+    except ClaudeMdLinkError as exc:
+        print(
+            f"okstra-claude-md: failed to seed worker worktree CLAUDE.md at "
+            f"{worktree_path} — dispatched Claude sessions will not auto-load "
+            f"okstra guidance. ({exc})",
+            file=__import__("sys").stderr,
+        )
+        return
+    if link is None:
+        print(
+            "okstra-claude-md: ~/.okstra/templates/okstra.CLAUDE.md missing — "
+            "re-run 'npx okstra@latest install' to provision the symlink target.",
+            file=__import__("sys").stderr,
+        )
+
+
+def _seed_worktree_agents_md(worktree_path: Path) -> None:
+    """Seed `<worktree>/AGENTS.md` symlink so codex / aider sessions dispatched
+    into this worktree auto-load okstra's guidance. Only acts when AGENTS.md
+    is absent — never overwrites user content.
+    """
+    try:
+        ensure_project_agents_md(project_root=worktree_path)
+    except AgentsMdLinkError as exc:
+        print(
+            f"okstra-agents-md: failed to seed worker worktree AGENTS.md at "
+            f"{worktree_path} — dispatched codex / aider sessions will not "
+            f"auto-load okstra guidance. ({exc})",
+            file=__import__("sys").stderr,
+        )
+
+
 def _copy_snapshot_files(source_root: Path, worktree_path: Path) -> list[str]:
     """Copy fixture files from MAIN → task worktree as read-only snapshots
     (FU-V3).
@@ -515,6 +564,8 @@ def provision_task_worktree(
     if existing is not None and existing.status == "active":
         worktree_registry.touch_phase(safe_project, safe_group, safe_task, task_type)
         _seed_worktree_settings_symlink(Path(existing.worktree_path))
+        _seed_worktree_claude_md(Path(existing.worktree_path))
+        _seed_worktree_agents_md(Path(existing.worktree_path))
         return WorktreeProvision(
             status="reused",
             path=existing.worktree_path,
@@ -617,6 +668,8 @@ def provision_task_worktree(
         raise
 
     _seed_worktree_settings_symlink(worktree_path)
+    _seed_worktree_claude_md(worktree_path)
+    _seed_worktree_agents_md(worktree_path)
 
     base_label = (
         f"{base_origin} @ {resolved_base_ref[:12]}"

package/runtime/python/okstra_project/resolver.py

@@ -118,9 +118,10 @@ def upsert_project_json(project_root: Path, project_id: str, *,
                 f"under a different id. "
                 f"(projectId 불일치: 한 PROJECT_ROOT 에는 하나의 projectId 만 허용됩니다.)")
         # Preserve any user-managed fields (e.g. `worktreeSyncDirs`,
-        # `mcpServers`) so manual edits to project.json are not wiped
-        # by the per-run self-registration upsert. Only the canonical
-        # identity/timestamp fields below are owned by this function.
+        # `qaCommands`, `prTemplatePath`, `reportLanguage`, `mcpServers`) so
+        # manual edits to project.json are not wiped by the per-run
+        # self-registration upsert. Only the canonical identity/timestamp
+        # fields below are owned by this function.
         result = dict(data) if isinstance(data, dict) else {}
         result["projectId"] = project_id
         result["projectRoot"] = abs_root

package/runtime/python/okstra_token_usage/report.py

@@ -15,7 +15,7 @@ if str(_HERE) not in sys.path:
     sys.path.insert(0, str(_HERE))
 
 from okstra_ctl.render_final_report import (  # noqa: E402
-    RenderError,
+    FinalReportRenderError,
     render_to_file,
 )
 
@@ -171,6 +171,6 @@ def populate_and_render(
 
     try:
         bytes_written = render_to_file(data_path, output_path)
-    except RenderError as exc:
+    except FinalReportRenderError as exc:
         raise SubstituteRefusedError(f"render after substitute failed: {exc}") from exc
     return changes, bytes_written

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

@@ -6,6 +6,7 @@
   "type": "object",
   "required": [
     "schemaVersion",
+    "meta",
     "frontmatter",
     "header",
     "verdictCard",
@@ -27,6 +28,19 @@
       "description": "Schema version. Renderer refuses to process unknown versions."
     },
 
+    "meta": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["reportLanguage"],
+      "properties": {
+        "reportLanguage": {
+          "type": "string",
+          "enum": ["en", "ko"],
+          "description": "Resolved language used for prose + i18n dictionary. 'auto' must be resolved to 'en' or 'ko' by the lead before the report-writer worker writes data.json."
+        }
+      }
+    },
+
     "frontmatter": {
       "type": "object",
       "required": [
@@ -40,7 +54,8 @@
         "taskGroup",
         "projectId",
         "taskType",
-        "workerId"
+        "workerId",
+        "approved"
       ],
       "additionalProperties": false,
       "properties": {
@@ -64,7 +79,11 @@
         "taskGroup": { "type": "string", "minLength": 1 },
         "projectId": { "type": "string", "minLength": 1 },
         "taskType": { "$ref": "#/$defs/TaskType" },
-        "workerId": { "const": "report-writer" }
+        "workerId": { "const": "report-writer" },
+        "approved": {
+          "type": "boolean",
+          "description": "사용자 승인 플래그. report-writer 는 항상 false 로 발행하고, 사용자가 `--approve` 또는 직접 편집으로 true 로 토글합니다. `implementation` task-type 의 prepare 단계가 `--approved-plan` 으로 지정된 보고서의 이 필드를 읽어 진입 여부를 결정합니다. 다른 task-type 에서는 의미 없이 false 로 유지됩니다."
+        }
       }
     },
 
@@ -94,19 +113,6 @@
       }
     },
 
-    "approvalBlock": {
-      "type": "object",
-      "description": "RENDER_IF taskType == implementation-planning. Renderer emits the User Approval Request section.",
-      "required": ["approved"],
-      "additionalProperties": false,
-      "properties": {
-        "approved": {
-          "type": "boolean",
-          "description": "When true, renders `- [x] Approved`; when false, `- [ ] Approved`. Plan Body Verification gate decides which."
-        }
-      }
-    },
-
     "clarificationCarryIn": {
       "type": "object",
       "description": "RENDER_IF non-empty. Carry-in clarifications from the previous run.",
@@ -593,7 +599,7 @@
         "required": ["header"]
       },
       "then": {
-        "required": ["implementationPlanning", "approvalBlock"]
+        "required": ["implementationPlanning"]
       }
     },
     {

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

@@ -41,12 +41,19 @@ cross-verification and would conflict with anything decided here.
 ## Intended chain
 
 ```
-okstra-brief
+okstra-brief (reporter-input variant)
   → okstra-run (requirements-discovery | error-analysis)
     → okstra-run (implementation-planning)
       → okstra-run (implementation)
         → okstra-run (final-verification)
           → okstra-run (release-handoff)
+
+okstra-brief (codebase-scan variant)
+  → okstra-run (improvement-discovery)
+    → okstra-run (implementation-planning)
+      → okstra-run (implementation)
+        → okstra-run (final-verification)
+          → okstra-run (release-handoff)
 ```
 
 ## When to use
@@ -70,8 +77,7 @@ okstra-brief
 
 **All okstra-generated artifacts live under `<PROJECT_ROOT>/.project-docs/okstra/`.**
 This includes briefs, run manifests, reports, worker results, status,
-sessions, and any other run output. okstra itself never writes to `.scratch/`
-or other project paths.
+sessions, and any other run output.
 
 All writes by this skill stay inside `.project-docs/okstra/`. When domain
 alignment (Step 3b / Step 4.5) yields a glossary change that the user
@@ -81,12 +87,11 @@ approves inline, the change is written to:
   glossary. Created if absent; appended to a `## Glossary` section
   otherwise.
 
-External `<PROJECT_ROOT>/CONTEXT.md` / `<PROJECT_ROOT>/CONTEXT-MAP.md` /
-`<PROJECT_ROOT>/docs/adr/` are read-only references; this skill never
-writes to them. Decision files (when raised by `implementation-planning`)
-also live inside okstra's subtree at
-`<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`, never
-at external `docs/adr/`.
+Paths outside `<PROJECT_ROOT>/.project-docs/okstra/**` are not okstra
+memory. This skill reads them only when the reporter explicitly cited them
+as source material, and never writes them. Decision files (when raised by
+`implementation-planning`) also live inside okstra's subtree at
+`<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
 
 ## Authority files
 
@@ -128,6 +133,19 @@ Parse the JSON from stdout:
 
 ## Step 1: Choose input source
 
+### 1.0. brief variant
+
+`AskUserQuestion` (single-select):
+
+- **Label**: `"Brief variant?"`
+- **Options**:
+  1. `Reporter input` — reporter 발화 / 티켓 / 링크 / 자유 텍스트를 verbatim 으로 흡수. 기존 4-source 흐름.
+  2. `Codebase scan` — 코드베이스 범위 + lens 우선순위만 받아 `improvement-discovery` phase 의 입력을 생성.
+
+### 1.A. Reporter input (variant 1)
+
+If the user picked `Reporter input`, proceed to Step 1.A's sub-flow below — this is the existing 4-source flow. Choose ONE of:
+
 `AskUserQuestion` (tool constraint: max 4 options):
 
 - **Label**: "Source of this brief?"
@@ -291,6 +309,34 @@ Two sub-modes combined under one option.
 When both are used, record them as two separate sub-sources under Source
 Material.
 
+### 1.B. Codebase scan (variant 2)
+
+If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
+
+1. `AskUserQuestion` (free text):
+   `"Scan scope — comma-separated paths inside the project (e.g. src/foo/, src/bar/baz.py)"` → `scan_scope` (CSV).
+2. `AskUserQuestion` (multi-select, options = the 8 lens enum values from `scripts/okstra_ctl/improvement_lenses.py`'s `LENSES`):
+   `"Priority lenses (pick 1–4)"` → `priority_lenses` (1..4 values from the enum).
+   Enum values: `performance`, `security`, `readability`, `architecture`, `test-coverage`, `dx`, `observability`, `accessibility`.
+3. `AskUserQuestion` (free text):
+   `"Out-of-scope paths (optional, comma-separated)"` → `out_of_scope` (CSV, empty allowed).
+4. `AskUserQuestion` (free text):
+   `"Candidate cap (1–12, default 8)"` → `candidate_cap` (integer; empty → 8).
+5. `AskUserQuestion` (free text):
+   `"Context — why is this scope being scanned now? One short paragraph."` → `context`.
+6. `AskUserQuestion` (free text):
+   `"Desired outcome — what kinds of improvements do you want surfaced? Anti-goals?"` → `desired_outcome`.
+7. `AskUserQuestion` (free text):
+   `"Constraints — untouchable areas, deadlines, compatibility (optional)"` → `constraints`.
+
+Validation (before Step 4 sharpening):
+
+- `scan_scope` 의 각 path 가 `<PROJECT_ROOT>` 안에 실제 존재하는지 `ls` 로 확인 — 없으면 한 질문으로 정정.
+- `priority_lenses` 가 `scripts/okstra_ctl/improvement_lenses.py` 의 `LENSES` 부분집합 (1–4) 인지 확인 — 위반 시 enum 표시 + 재선택.
+- `candidate_cap` 이 1–12 정수인지 확인.
+
+Once validation passes, jump to Step 2 (task key).
+
 ## Step 2: Identify task key & filename
 
 ### 2a. Task group
@@ -344,7 +390,7 @@ to Source Material body, not to the filename):
   3. Lowercase (Hangul untouched) — **filename normalization only**.
      The Source Material section MUST preserve the original title's case
      byte-for-byte; lowercase applies strictly to the on-disk filename.
-  4. Cut to 60 chars at a word boundary (hard-cut at 60 if no boundary)
+  4. Cut to 60 chars at a word boundary (cut at 60 if no boundary)
   5. Trim leading/trailing `-`
   - Example: Linear `LIN-1234 "Fix flaky login retry on 5xx"` →
     `LIN-1234-fix-flaky-login-retry-on-5xx.md`
@@ -385,12 +431,9 @@ never error:
 1. **okstra-internal (authoritative)** — always check first:
    - `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` if present
    - `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present
-2. **External (supplementary read-only reference)** — read if present:
-   - `<PROJECT_ROOT>/CONTEXT.md` (or `CONTEXT-MAP.md` → per-context
-     `CONTEXT.md`)
-   - `<PROJECT_ROOT>/docs/adr/` titles
-   - `<PROJECT_ROOT>/.scratch/CONTEXT.md` (output of external skills like
-     grill-with-docs, if any)
+2. **Explicit source material only** — if the reporter cited a path outside
+   okstra's subtree, read it as source evidence only; do not treat it as
+   okstra memory.
 
 If none of these exist, skip 3b/3c silently.
 
@@ -398,7 +441,7 @@ If none of these exist, skip 3b/3c silently.
 
 For each domain-significant noun in Source Material, classify:
 
-- **conflict** — the source uses a term that `CONTEXT.md` defines
+- **conflict** — the source uses a term that okstra memory defines
   differently. Example: source says "cancellation" meaning refund, glossary
   says "cancellation" means order-state transition.
 - **fuzzy / overloaded** — a term that has no canonical definition yet but
@@ -415,7 +458,7 @@ on a project-internal concrete object whenever possible.
     (so the next phase can resolve it during `requirements-discovery`).
   - One line under `Augmentation > Domain alignment` with the
     `terminology-mapping` label (Step 4 label rules), recording the
-    observation (what the source said vs. what CONTEXT.md says).
+    observation (what the source said vs. what okstra memory says).
 - **File paths and symbols are resolved to absolute, in-repo references.**
   When the source mentions a module / class / endpoint / config key, run
   `Read` / `Grep` to locate the concrete file path (relative to
@@ -434,8 +477,7 @@ on a project-internal concrete object whenever possible.
   knows to query the reporter directly rather than infer.
 - See Step 4.5 for the approval-gated path to actually write the
   okstra-internal glossary at
-  `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`. External
-  `CONTEXT.md` / `CONTEXT-MAP.md` / `docs/adr/` are never edited.
+  `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`.
 
 Skip 3b/3c for purely external request material with no overlap to the
 project's domain.
@@ -473,7 +515,7 @@ The following rules absorb the useful parts of `grill-me` /
    draft, then ask the next.
 4. **Bounded budget** — at most **1** sharpening question per empty
    required section, plus **at most 2** disambiguation questions arising
-   from Step 3b (terminology conflicts / fuzzy terms). Hard cap: **6
+   from Step 3b (terminology conflicts / fuzzy terms). Cap: **6
    questions total** across the whole brief. Anything beyond the cap is
    recorded under `Open Questions` instead of asked.
 5. **Scenario probe (optional)** — when `Desired Outcome` is empty or one
@@ -491,6 +533,23 @@ or to a `> augmented: <label>` blockquote inside the required section, so
 it is clear that the content is the skill's / user's added interpretation
 rather than the original source.
 
+### codebase-scan variant 전용 강화 규칙 (improvement-discovery)
+
+이 5개 규칙은 `scope: codebase` brief 에 한해 적용. budget 은 기본 6 → **8** 로 확대.
+
+1. **scan-scope 경로 존재 검증.** 각 path 를 `ls` / `Read` 로 확인. 없으면 한 질문으로 정정 (path 의 가장 가까운 후보를 `Recommended:` 로 제시).
+2. **모호 path narrowing.** `"백엔드"`, `"결제 모듈"` 같은 추상 path 는 구체 디렉토리 1개 이상으로 narrowing. codebase-first 추측 후 한 질문으로 확정.
+3. **priority-lenses 화이트리스트 검증.** `scripts/okstra_ctl/improvement_lenses.py` 의 `LENSES` 부분집합인지 확인. out-of-enum 이면 enum 내 가장 가까운 값을 `Recommended:` 로 제시.
+4. **out-of-scope 일관성.** `out-of-scope` 의 각 path 가 `scan-scope` 의 부분집합인지 확인. 무관한 path 면 한 질문으로 제거 또는 scan-scope 에 흡수.
+5. **lens 우선순위 근거 1줄.** 각 priority lens 가 *왜* 이 scope 에서 우선인지 brief 본문에 한 줄 없으면, codebase 1차 훑은 결과를 `Recommended:` 로 제시 후 한 질문.
+
+stop conditions (codebase-scan 한정 추가):
+
+- `scan-scope` 의 모든 path 가 codebase 에 존재
+- `priority-lenses` 가 valid enum 부분집합 (1–4개)
+
+위 두 조건이 모두 만족되면 budget 이 남아 있어도 sharpening 종료 가능.
+
 ### Augmentation labels (REQUIRED — no unlabelled augmentation)
 
 Every augmentation — both inline `> augmented: …` blockquotes and
@@ -501,7 +560,7 @@ labels. Unlabelled augmentation is rejected as half-formed translation.
 |---|---|---|
 | `evidence-link` | Cross-reference / file path / symbol resolved from the source against the actual codebase. Pure fact, verified by `Read` / `Grep`. | Trust without verification. |
 | `format-conversion` | Format-only transform (Jira ADF → Markdown, HTML → Markdown, etc.). Semantics unchanged. | Trust without verification. |
-| `terminology-mapping` | Reporter's word mapped to a project-canonical term (from `CONTEXT.md` or resolved during Step 3b). | Verify against `CONTEXT.md`; if mismatch, treat as a clarification candidate. |
+| `terminology-mapping` | Reporter's word mapped to an okstra-canonical term from Step 3b. | Verify against `.project-docs/okstra/glossary.md`; if mismatch, treat as a clarification candidate. |
 | `intent-inference` | Reporter did NOT literally state this — the skill inferred meaning from context (e.g. classifying "가끔 안 됨" as "intermittent failure on a specific path"). Qualitative only — **never** invent quantitative thresholds (numbers, latencies, percentages, counts). | **Verify with the reporter before acting.** Auto-mirrored into `Open Questions`. |
 
 **Inline form** — `> augmented: intent-inference — <one line>`.
@@ -559,8 +618,7 @@ For each `conflict` / `fuzzy` term collected in Step 3b that *was not*
 resolved by a budgeted Step 4 question, draft a glossary proposal and
 offer it to the user. This step writes to the **okstra-internal
 glossary** at `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` only —
-external `<PROJECT_ROOT>/CONTEXT.md` / `CONTEXT-MAP.md` are never edited
-by this skill.
+the skill does not write outside okstra's subtree.
 
 > **Decision scope**: this skill does NOT evaluate decision candidates
 > and does NOT draft decision files. Decision creation requires context
@@ -569,8 +627,7 @@ by this skill.
 > goes to `Open Questions` with the `adr-candidate:` prefix and is
 > evaluated by `implementation-planning` against the three-criteria
 > gate. Approved decision files land at
-> `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`,
-> never at external `<PROJECT_ROOT>/docs/adr/`.
+> `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
 
 ### 4.5a. Draft glossary proposals
 
@@ -635,6 +692,12 @@ depth: 0                                     # 0=parent/single, 1=child, 2=grand
 created: <YYYY-MM-DD>
 generator: okstra-brief
 reporter-confirmations: <complete | partial | pending | skipped>  # set by Step 6.5
+# codebase-scan variant frontmatter (omit for reporter-input briefs):
+scope: <reporter-input | codebase>              # 'codebase' for codebase-scan variant; omit for reporter-input variant
+priority-lenses: []                              # codebase-scan only: lens enum subset, size 1..4
+scan-scope: []                                   # codebase-scan only: 1+ paths
+out-of-scope: []                                 # codebase-scan only: optional
+candidate-cap: 8                                 # codebase-scan only: 1..12, default 8
 ---
 
 # Task Brief: <task_group>/<filename-without-ext>
@@ -698,6 +761,20 @@ between current and desired.>
 <Deadlines, compatibility, technical/operational limits. Use _(none)_ if
 none.>
 
+## Scan Scope
+
+<!-- codebase-scan variant only — omit this section for reporter-input briefs. -->
+<!-- Author guidance: one bullet per `scan-scope` path with a short description of what lives there. -->
+
+- <path>: <one-line description of contents / responsibility>
+
+## Priority Lenses
+
+<!-- codebase-scan variant only — omit this section for reporter-input briefs. -->
+<!-- Author guidance: one bullet per priority lens explaining why it is a priority for THIS scope. -->
+
+- <lens>: <short rationale tying this lens to the scope's risk surface>
+
 ## Related Artifacts
 
 - <file path / URL / issue / prior task-key>
@@ -810,6 +887,22 @@ Use `_(none)_` if none. -->
 - <fill in one entry per conversion, or replace with `_(none)_`>
 ````
 
+**Variant note:** The template above 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, ADD `## Scan Scope` and `## Priority Lenses` sections (already present in the template above, marked with HTML comments). The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to both 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 |
+
 ### Frontmatter rules
 
 - Every brief starts on line 1 with a YAML frontmatter delimited by `---`.
@@ -842,6 +935,7 @@ Inspect the finalized brief and recommend the next `okstra-run` task-type:
 |---|---|
 | `Problem / Symptom` describes a repro / log / stack trace / observable error | `error-analysis` |
 | `Open Questions` is large or `Desired Outcome` is ambiguous / needs classification | `requirements-discovery` |
+| `scope: codebase` frontmatter | `improvement-discovery` |
 | Both / ambiguous | `requirements-discovery` (safe default — the phase itself decides branching) |
 
 Write the chosen recommendation into the `Recommended next phase:` header
@@ -886,7 +980,7 @@ For each pending row, formulate one question. Because the
 `AskUserQuestion` tool caps options at 4 per call and questions per call
 also at 4, split into batches of ≤ 4 questions.
 
-**Hard cap — 12 questions per Step 6.5 run.** When the pending list
+**Cap — 12 questions per Step 6.5 run.** When the pending list
 exceeds 12 rows, sort by priority and ask only the top 12 this round:
 
 1. `conversion-block:` rows first (translation failure — highest
@@ -983,10 +1077,9 @@ started.
   `<PROJECT_ROOT>/.project-docs/okstra/`. This skill's brief files go
   under `.project-docs/okstra/briefs/`; its glossary writes go to
   `.project-docs/okstra/glossary.md` (Step 4.5 approval flow).
-- External paths (`<PROJECT_ROOT>/CONTEXT.md`,
-  `<PROJECT_ROOT>/CONTEXT-MAP.md`, `<PROJECT_ROOT>/docs/adr/`,
-  `<PROJECT_ROOT>/.scratch/`) are read-only references. This skill
-  never writes to them. Absent external files are the normal state.
+- Paths outside `<PROJECT_ROOT>/.project-docs/okstra/**` are read-only
+  source material only when explicitly cited by the reporter. This skill
+  never writes outside okstra's subtree.
 - **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.

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

@@ -465,7 +465,7 @@ Plan-body verification is configured under `convergence.planBodyVerification` in
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `enabled` | `true` | If `false`, the round is skipped and the top-of-report Approval marker is rendered unconditionally (legacy behaviour). |
-| `maxRounds` | `1` | Hard upper bound. Plan-body verification is consistency / completeness checking, not fact checking — additional rounds rarely help. Range 1–3. |
+| `maxRounds` | `1` | Upper bound. Plan-body verification is consistency / completeness checking, not fact checking — additional rounds rarely help. Range 1–3. |
 | `gating` | `true` | If `true` (default), `majority-disagree` blocks the Approval marker. If `false`, the round is advisory-only and the marker always renders. |
 
 Default values are emitted into the manifest by `scripts/okstra_ctl/render.py` (`_build_convergence_block`). The ctx knob `OKSTRA_PLAN_VERIFICATION=false` flips `planBodyVerification.enabled` to false.
@@ -632,5 +632,4 @@ Mirrors finding convergence (§"Worker failure handling in reverify"). Concretel
 
 - A dispatch that returns terminal non-result MUST NOT be aggregated as `DISAGREE`.
 - If at least one dispatch was issued AND **all** plan-body dispatches return non-result, the Gate result is `aborted-non-result`. Record one `contract-violation` event per non-result dispatch.
-- The Approval marker is NOT rendered when the gate is `aborted-non-result`. A single row is added to `## 5. Clarification Items` with `Statement="plan-body verification could not run — all workers returned non-result"`, `Kind=decision`, `Blocks=approval`, allowing the user to either retry the phase or override by manually approving the plan (via `--approve` on the resume command).
-
+- When the gate is `aborted-non-result`, report-writer MUST keep the frontmatter `approved: false` (publishing `approved: true` under this gate result is a validator failure). A single row is added to `## 5. Clarification Items` with `Statement="plan-body verification could not run — all workers returned non-result"`, `Kind=decision`, `Blocks=approval`, allowing the user to either retry the phase or override by manually flipping the frontmatter to `approved: true` (or running `--approve` on the resume command).