okstra 0.34.1 → 0.36.1

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
 
@@ -619,196 +676,23 @@ 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).
 
-Use this exact template. Leave a section's body as `_(none)_` rather than
-fabricating content. (The outer fence uses 4 backticks so it does not
-collide with the inner 3-backtick code block.)
-
-````markdown
----
-type: brief
-brief-id: <ticket-id>-<file-title>          # equals the filename stem
-parent-id: self                              # always `self` at root; child briefs use parent's brief-id
-ticket-id: <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12 | "">
-source-type: <file | linear | jira | github | notion | url | user-input>
-task-group: <task-group>
-depth: 0                                     # 0=parent/single, 1=child, 2=grandchild, ...
-created: <YYYY-MM-DD>
-generator: okstra-brief
-reporter-confirmations: <complete | partial | pending | skipped>  # set by Step 6.5
----
-
-# Task Brief: <task_group>/<filename-without-ext>
-
-> Generated: okstra-brief · <YYYY-MM-DD>
-> Source type: <file | linear | jira | github | notion | url | user-input>
-> Tracker key (if any): <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12>
-> Parent brief (child briefs only): <relative path>
-> Recommended next phase: <requirements-discovery | error-analysis>  ← from Step 6
-> Handoff contract: see `prompts/profiles/_common-contract.md` § "Brief handoff contract"
-
-## Source Material
-
-<!-- author guidance — strip out at fill-in time:
-Paste each source separately and as-is. No paraphrasing, summarizing, or
-restructuring. Format conversion (e.g. Jira ADF → Markdown) is allowed and
-must be annotated in the header meta. Heading was originally
-"Source Material (verbatim — do not modify)" — the parenthetical is a
-reviewer note, not body text.
--->
-
-### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
-
-- ref: <abs file path | LIN-1234 | https://... | "conversation synthesis">
-- fetched-via: <Read | mcp__linear__getIssue | mcp__notion__... | gh issue view | WebFetch | user-paste>
-- fetched-at: <YYYY-MM-DD HH:MM>
-- format: <as-is | "Jira ADF → Markdown (semantics preserved)" | "tool-truncated — missing body requested from reporter">
-
-```
-<Paste the raw source here without changing a single character.>
-```
-
-<!-- Repeat `### Source N — …` blocks as needed. -->
-
-## Context
-
-<Background / scope / why now. If self-evident from Source Material, quote
-it briefly and stop. Use the blockquote below when augmentation is needed.>
-
-> augmented: <label> — <Interpretation added by the skill or user.>
-
-<!-- label MUST be one of: `evidence-link` / `format-conversion` /
-`terminology-mapping` / `intent-inference`. Do NOT add any extra
-interpretation outside the `> augmented:` blockquote. -->
-
-## Problem / Symptom
-
-<Current state. For bugs: repro / observed / expected. For greenfield: gap
-between current and desired.>
+[`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.
 
-<!-- Same source-quote + `> augmented:` rule as the Context section. -->
+**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.
 
-## Desired Outcome
+### Required sections by variant
 
-<Shape of success.>
-
-<!-- Do NOT prescribe a solution — that belongs to implementation-planning. -->
-
-## Constraints
-
-<Deadlines, compatibility, technical/operational limits. Use _(none)_ if
-none.>
-
-## Related Artifacts
-
-- <file path / URL / issue / prior task-key>
-
-## Open Questions
-
-<!-- author guidance — strip out at fill-in time:
-Prefix every row with one of these signals so the next phase knows how to
-handle it. Free-form rows are allowed only as `general:`.
-
-Allowed signals:
-- `general: <unresolved question the user flagged>`
-- `terminology: <reporter word> — needs canonical resolution against
-  <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
-- `intent-check: <restated inference> — confirm with reporter`
-  (auto-paired with every `intent-inference` augmentation)
-- `conversion-block: <reporter statement> — could not be mapped to project
-  vocabulary; reporter query required`
-- `adr-candidate: <topic>` — signal only; `implementation-planning`
-  evaluates and, if accepted, drafts a decision file at
-  `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
-
-Use `_(none)_` only if every signal is empty. `intent-check:` and
-`conversion-block:` rows that are answered in Step 6.5 are NOT removed
-from this list — they receive a `[CONFIRMED <YYYY-MM-DD> → RC-N]`
-marker that links to the corresponding entry under
-`## Reporter Confirmations`.
--->
-
-- <fill in one row per signal, or replace with `_(none)_`>
-
-## Reporter Confirmations
-
-<!-- Populated by Step 6.5. Each subsection records one reporter answer
-verbatim, with a link back to the originating `Open Questions` row. -->
-
-_(none — pending or skipped)_
-
-<!-- when populated, the shape is:
-### RC-1 — <intent-check: or conversion-block: row id / topic>
-- asked: <YYYY-MM-DD HH:MM>
-- linked-row: `<exact Open Questions row text>`
-- answer (verbatim):
-
-  > <reporter's answer, byte-for-byte>
--->
-
-## Augmentation
-
-<!-- author guidance — strip out at fill-in time:
-Cross-references / interpretation / context added by the user or skill that
-is not in the original source. May be empty. Keep this section visually
-separated from Source Material — never inline it inside Source Material.
-
-Every entry below must start with one of the four labels:
-`evidence-link` / `format-conversion` / `terminology-mapping` /
-`intent-inference`. Unlabelled entries are forbidden.
--->
-
-### Domain alignment
-
-<!-- author guidance — strip out at fill-in time:
-Observations from Step 3b and the outcome of Step 4.5 (glossary applied
-vs. skipped). The actual glossary edits live in
-`<PROJECT_ROOT>/.project-docs/okstra/glossary.md` when applied; this
-section records what happened. Decision candidates are NOT recorded here —
-they flow through `Open Questions` as `adr-candidate:` rows for
-`implementation-planning` to evaluate (and, if accepted, draft into
-`<PROJECT_ROOT>/.project-docs/okstra/decisions/`).
-
-Allowed entry shapes:
-- `terminology-mapping: <reporter word> → <okstra glossary canonical>` —
-  routine glossary alignment, paired with `terminology:` in Open Questions
-  when unresolved.
-- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
-- `terminology-mapping: skipped glossary: <term> = <definition>` —
-  Step 4.5 outcomes.
-Use `_(none)_` if every alignment entry is empty.
--->
-
-- <fill in one entry per alignment, or replace with `_(none)_`>
-
-### Evidence links (file / symbol resolution)
-
-<!-- Allowed entry shapes:
-`evidence-link: <reporter phrase> → <relative path>:<line>` or
-`evidence-link: <reporter phrase> → <symbol> in <relative path>`.
-Use `_(none)_` if none. -->
-
-- <fill in one entry per link, or replace with `_(none)_`>
-
-### Intent inferences
-
-<!-- Every entry here is an unverified hypothesis. Each one MUST have a
-paired `intent-check:` row under Open Questions.
-
-Allowed entry shape:
-`intent-inference: <reporter phrase> → <qualitative restatement>`
-(qualitative only — never invent numeric thresholds).
-Use `_(none)_` if none. -->
-
-- <fill in one entry per inference, or replace with `_(none)_`>
-
-### Format conversions
-
-<!-- Allowed entry shape:
-`format-conversion: <ref> — <e.g. Jira ADF → Markdown, semantics preserved>`.
-Use `_(none)_` if none. -->
-
-- <fill in one entry per conversion, or replace with `_(none)_`>
-````
+| 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
 
@@ -842,6 +726,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 +771,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 +868,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).