okstra 0.38.0 → 0.38.1

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.38.0",
-  "builtAt": "2026-05-28T09:52:37.801Z",
+  "package": "0.38.1",
+  "builtAt": "2026-05-29T06:34:56.309Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -35,7 +35,7 @@ You also write an audit sidecar at the path the lead registers as `**Worker Resu
 1. The canonical data.json path you wrote (project-relative).
 2. The rendered markdown path produced by the renderer (project-relative).
 3. Inputs reconciled (analysis-worker result files + convergence-state file).
-4. Any structural deviations from `schemas/final-report-v1.0.schema.json` and the reason.
+4. Any structural deviations from the `<instruction-set>/final-report-schema.json` excerpt and the reason.
 
 Do NOT duplicate the data.json contents here — the data.json is the canonical artifact; this sidecar is the validator-required pointer / audit record.
 
@@ -67,8 +67,8 @@ Before writing the data.json, you MUST:
 
 For the report writer specifically, the `## Inputs` list always includes:
 
-- `schemas/final-report-v1.0.schema.json` — the JSON Schema you must conform to. The renderer + validator both consume it.
-- `templates/reports/final-report.template.md` — the Jinja2 template the renderer uses. Read it to understand which data.json fields appear where in the rendered markdown; do NOT edit it.
+- `<instruction-set>/final-report-schema.json` — the **per-task-type excerpt** of the data.json schema (scoped to this run's task-type at prep time: other task-types' deliverable blocks and their unreachable `$defs` are stripped). This is the shape you must author. Read this, NOT the full `schemas/final-report-v1.0.schema.json` (it is not in the task bundle and its `schemas/...` path is not resolvable here). Validation still runs against the full schema post-hoc, so the excerpt never relaxes the contract.
+- `<instruction-set>/final-report-template.md` — the **phase-stripped** Jinja2 template the renderer uses (only this run's §4.x deliverable block remains). Read it to understand which data.json fields appear where in the rendered markdown; do NOT edit it, and do NOT pull the full `templates/reports/final-report.template.md` source.
 - `templates/reports/i18n/en.json` and `templates/reports/i18n/ko.json`.
 - Every analysis worker's result file under `worker-results/`.
 - `state/convergence-<task-type>-<seq>.json` (if present). When present, reproduce its `roundHistory[]`, `round2SkippedReason`, and `finalClassificationCounts` verbatim into the final report's Section 1 Round History sub-table — do not recompute from worker results.
@@ -79,7 +79,7 @@ Write a Reading Confirmation block to your **audit sidecar** at `runs/<task-type
 
 ## Authoring Contract
 
-You author the final-report data.json (the JSON SSOT). The schema is `schemas/final-report-v1.0.schema.json` — its `$defs` enumerate every row shape, enum value, and cross-field constraint. The validator rejects data that violates the schema; the renderer refuses to render against invalid data. Both consume the same schema, so a data.json that validates is a data.json that renders correctly.
+You author the final-report data.json (the JSON SSOT). You author it against the `<instruction-set>/final-report-schema.json` excerpt — its `$defs` enumerate every row shape, enum value, and cross-field constraint that applies to this run's task-type. The validator and renderer both consume the **full** `schemas/final-report-v1.0.schema.json` (the excerpt is a faithful task-type-scoped subset of it), so a data.json that satisfies the excerpt is a data.json that validates and renders correctly.
 
 The rendered markdown (`final-report-<task-type>-<seq>.md`) is produced by `scripts/okstra-render-final-report.py` immediately after you write the data.json. The HTML view (`*.html`) is produced from the markdown by Phase 7 step 1.5 (`scripts/okstra-render-report-views.py`). The data.json is the only file you write; the rest are derived.
 

package/runtime/bin/okstra-render-report-views.py

@@ -128,7 +128,10 @@ def main(argv: list[str] | None = None) -> int:
     css, js = _load_assets()
     meta = RunMeta(task_key=task_key, task_type=task_type, seq=seq, source_report=source_report)
     html_path = render_html_view(report_path, run_meta=meta, css=css, js=js)
-    print(f"html: {html_path}")
+    if html_path is None:
+        print("html: skipped (no §5 clarification rows — html view carries no interactive forms for this report)")
+    else:
+        print(f"html: {html_path}")
     return 0
 
 

package/runtime/prompts/launch.template.md

@@ -81,7 +81,7 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 ## Available MCP Servers
 
 {{AVAILABLE_MCP_SERVERS}}
-- The full usage policy and per-phase rules live in the task brief's `## Available MCP Servers` section. Read them there before dispatching workers and **forward that section verbatim into every worker prompt** during Phase 2 so workers know they are allowed to call these tools.
+- The full usage policy and per-phase rules live in the task brief's `## Available MCP Servers` section. Read them there before dispatching workers and inject only the one-line pointer below into each worker prompt (the brief is already in every worker's [Required reading], so verbatim copy is redundant): `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).`
 - **Invocation rule (forward to every worker prompt)**: MCP tools are addressed by their tool name through the host's tool interface — **never via `Bash`**. Claude-side workers call the tool directly (e.g. `mcp__<server>__<tool>`). Codex/Gemini workers call through their CLI's own MCP transport (e.g. `codex mcp call ...`). Running the tool name as a shell command is a contract violation and will always fail regardless of permission grants.
 - Codex worker and Gemini worker run external CLIs; they can only use these MCP servers if their own CLI configs mirror them. If not, instruct the worker to record `MCP not available in this CLI` in its `Missing Information or Assumptions` block rather than guessing or shell-falling-back.
 - MCP queries are evidence-grade. Cite server, table, and the SELECT used in worker output. MCP must NOT be used as a write path in any phase, including `implementation`.

package/runtime/python/okstra_ctl/paths.py

@@ -144,6 +144,7 @@ def compute_run_paths(
     final_status = run_status / f"final{suffixes['status']}.status"
     team_state = run_state / f"team-state{suffixes['state']}.json"
     final_report_template = instruction_set / "final-report-template.md"
+    final_report_schema = instruction_set / "final-report-schema.json"
     reference_expectations = instruction_set / "reference-expectations.md"
     claude_resume_command = run_sessions / f"claude-resume{suffixes['sessions']}.sh"
     latest_task_file = discovery_dir / "latest-task.json"
@@ -205,6 +206,7 @@ def compute_run_paths(
         "FINAL_STATUS_PATH": str(final_status),
         "TEAM_STATE_PATH": str(team_state),
         "FINAL_REPORT_TEMPLATE_PATH": str(final_report_template),
+        "FINAL_REPORT_SCHEMA_PATH": str(final_report_schema),
         "REFERENCE_EXPECTATIONS_FILE": str(reference_expectations),
         "CLAUDE_RESUME_COMMAND_PATH": str(claude_resume_command),
         "OKSTRA_LATEST_TASK_FILE": str(latest_task_file),
@@ -264,6 +266,7 @@ def compute_run_paths(
         ("WORKER_RESULTS_RELATIVE_PATH", worker_results),
         ("RUN_CARRY_RELATIVE_PATH", run_carry),
         ("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", final_report_template),
+        ("FINAL_REPORT_SCHEMA_RELATIVE_PATH", final_report_schema),
         ("REFERENCE_EXPECTATIONS_RELATIVE_PATH", reference_expectations),
         ("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", claude_resume_command),
         ("RUN_VALIDATOR_RELATIVE_PATH", run_validator_script),

package/runtime/python/okstra_ctl/report_views.py

@@ -664,17 +664,41 @@ def serialize_user_response(
 # Convenience entrypoint for tests + CLI.
 # --------------------------------------------------------------------------- #
 
+def report_has_clarification_items(src_md: str) -> bool:
+    """True when the final-report MD has at least one §5 ``C-*``
+    clarification row. This is the single predicate that gates HTML-view
+    generation: the self-contained html's only value over the markdown is
+    the embedded ``<form>`` widgets for those rows, so a clarification-free
+    report does not get an html sibling. The renderer, the CLI, and
+    ``validators/validate-report-views.py`` all key off this same function
+    so generation and validation never disagree."""
+    return any(
+        re.fullmatch(r"C-\d+", item.row_id)
+        for item in (parse_clarification_items(src_md) or [])
+    )
+
+
 def render_html_view(
     src_md_path: Path,
     *,
     run_meta: RunMeta,
     css: str,
     js: str,
-) -> Path:
-    """Write ``<stem>.html`` next to ``src_md_path`` and return its
-    path. Idempotent — overwrites the existing html sibling."""
+) -> Path | None:
+    """Write ``<stem>.html`` next to ``src_md_path`` and return its path,
+    or return ``None`` when generation is skipped because the report has
+    no §5 clarification rows (see ``report_has_clarification_items``).
+    Idempotent — overwrites an existing html sibling, and removes a stale
+    one when a previously-clarification-bearing report no longer has rows."""
     src_text = src_md_path.read_text(encoding="utf-8")
     html_path = src_md_path.with_name(src_md_path.stem + ".html")
+    if not report_has_clarification_items(src_text):
+        # Conditional generation: no interactive forms to render. Drop any
+        # stale html left over from a prior clarification-bearing run so the
+        # validator's "no rows → no html" branch stays consistent.
+        if html_path.is_file():
+            html_path.unlink()
+        return None
     html_text = render_html(src_text, run_meta=run_meta, css=css, js=js)
     html_path.write_text(html_text, encoding="utf-8")
     return html_path

package/runtime/python/okstra_ctl/run.py

@@ -35,7 +35,9 @@ from .material import (
     related_tasks_inline,
     resolve_related_tasks,
 )
+from .final_report_schema import load_schema
 from .models import resolve_model_metadata
+from .schema_excerpt import build_schema_excerpt
 from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
     apply_lead_prompt_defaults,
@@ -932,6 +934,26 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     render_template_with_ctx(
         str(final_report_template), ctx["FINAL_REPORT_TEMPLATE_PATH"], ctx,
     )
+    # Per-task-type schema excerpt for the report-writer worker. The full
+    # schema validates the data.json post-hoc (load_schema); the worker only
+    # needs the common structure + this run's task-type block, so we write a
+    # scoped excerpt into the instruction-set rather than make the worker read
+    # the whole 44 KB / all-task-types schema (whose repo `schemas/...` path is
+    # not resolvable from a consumer project's task bundle anyway).
+    #
+    # Guarded: a missing/unreadable schema must NOT break bundle preparation.
+    # If the excerpt cannot be produced (e.g. an older install that predates
+    # the schemas/ copy step), prep proceeds without it — the report-writer
+    # still has the phase-stripped template + skill structure guide, and
+    # validation runs against the full schema regardless.
+    try:
+        _excerpt = build_schema_excerpt(load_schema(), inp.task_type)
+        Path(ctx["FINAL_REPORT_SCHEMA_PATH"]).write_text(
+            json.dumps(_excerpt, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+    except Exception:  # noqa: BLE001 — advisory artifact; never fail prep over it
+        pass
     render_template_with_ctx(
         str(prompt_template), str(instruction_set / "claude-execution-prompt.md"), ctx,
     )

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -0,0 +1,116 @@
+"""Build a task-type-scoped excerpt of the final-report schema.
+
+The full schema (``schemas/final-report-v1.0.schema.json``) carries the
+deliverable property blocks for ALL task-types (``implementationPlanning``,
+``releaseHandoff``, ``implementation``, ``finalVerification``) plus a
+``$defs`` library (~38% of the file) shared across them. A single run only
+authors ONE task-type's data.json, so the report-writer worker only needs
+the common structure + its own task-type's block + the ``$defs`` those
+reach.
+
+This module produces that scoped excerpt, written into the run's
+instruction-set at prep time so the worker reads a smaller, path-local
+file (`instruction-set/final-report-schema.json`) instead of the full
+repo/installed schema (whose `schemas/...` path is not even resolvable
+from inside a consumer project's task bundle).
+
+The excerpt is ADVISORY — a reading aid for the author. Validation always
+runs against the FULL schema via ``final_report_schema.load_schema()``, so
+the excerpt never gates correctness; it only trims what the worker reads.
+"""
+from __future__ import annotations
+
+import json
+import re
+
+# task-type → the per-type deliverable property key it owns. task-types
+# absent from this map (requirements-discovery, error-analysis,
+# improvement-discovery) have no per-type block; their excerpt keeps only
+# the common properties.
+_TASK_TYPE_PROPERTY = {
+    "implementation-planning": "implementationPlanning",
+    "release-handoff": "releaseHandoff",
+    "implementation": "implementation",
+    "final-verification": "finalVerification",
+}
+_ALL_PER_TYPE_PROPERTIES = frozenset(_TASK_TYPE_PROPERTY.values())
+
+_REF_RE = re.compile(r'"\$ref"\s*:\s*"#/\$defs/([^"]+)"')
+
+
+def _refs_in(obj) -> set[str]:
+    """Every ``#/$defs/<name>`` referenced anywhere inside ``obj``."""
+    return set(_REF_RE.findall(json.dumps(obj)))
+
+
+def _conditional_applies(entry: dict, task_type: str) -> bool:
+    """True when an ``allOf`` if/then entry is relevant to *task_type*.
+
+    Universal entries (no ``header.taskType`` constraint) always apply;
+    ``const`` entries apply on exact match; ``enum`` entries apply when
+    *task_type* is a member.
+    """
+    constraint = (
+        entry.get("if", {})
+        .get("properties", {})
+        .get("header", {})
+        .get("properties", {})
+        .get("taskType", {})
+    )
+    const = constraint.get("const")
+    enum = constraint.get("enum")
+    if const is None and enum is None:
+        return True
+    if const is not None:
+        return const == task_type
+    return task_type in (enum or [])
+
+
+def build_schema_excerpt(schema: dict, task_type: str) -> dict:
+    """Return a task-type-scoped copy of *schema*.
+
+    Drops the per-type property blocks that do not belong to *task_type*,
+    the ``allOf`` conditionals that cannot fire for it, and the ``$defs``
+    that become unreachable as a result (transitive closure preserves any
+    def reachable from a kept property or conditional). Top-level metadata
+    and ``required`` are preserved (``required`` never lists per-type
+    blocks, but it is filtered defensively).
+    """
+    keep_per_type = _TASK_TYPE_PROPERTY.get(task_type)
+    drop_props = _ALL_PER_TYPE_PROPERTIES - ({keep_per_type} if keep_per_type else set())
+
+    props = {
+        k: v for k, v in schema.get("properties", {}).items() if k not in drop_props
+    }
+    all_of = [e for e in schema.get("allOf", []) if _conditional_applies(e, task_type)]
+
+    # Reachable $defs = transitive closure of $ref from kept props + allOf.
+    defs = schema.get("$defs", {})
+    reachable: set[str] = set()
+    work = list(_refs_in(props) | _refs_in(all_of))
+    while work:
+        name = work.pop()
+        if name in reachable or name not in defs:
+            continue
+        reachable.add(name)
+        work.extend(_refs_in(defs[name]))
+
+    excerpt = {
+        k: v
+        for k, v in schema.items()
+        if k not in ("properties", "allOf", "$defs", "required", "description")
+    }
+    excerpt["description"] = (
+        f"Per-task-type excerpt of the okstra final-report schema, scoped to "
+        f"`{task_type}`. Reading aid for the report-writer worker — validation "
+        f"runs against the full schema (schemas/final-report-v1.0.schema.json)."
+    )
+    excerpt["properties"] = props
+    excerpt["required"] = [
+        r for r in schema.get("required", []) if r not in drop_props
+    ]
+    if all_of:
+        excerpt["allOf"] = all_of
+    if reachable:
+        excerpt["$defs"] = {k: v for k, v in defs.items() if k in reachable}
+    return excerpt

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

@@ -322,8 +322,6 @@ For each finding:
 
 Save it to `runs/<task-type>/state/convergence-<task-type>-<seq>.json`.
 
-Schema version `1.1` extends `1.0` (legacy fields kept as aliases for backward-compat with already-shipped reports):
-
 ```json
 {
   "schemaVersion": "1.1",
@@ -368,12 +366,7 @@ Schema version `1.1` extends `1.0` (legacy fields kept as aliases for backward-c
       ],
       "skippedWorkers": [
         { "worker": "claude-worker", "reason": "no items to verify" }
-      ],
-      "verificationsRequested": 2,
-      "verificationsCompleted": 2,
-      "newConsensus": 3,
-      "remainingInQueue": 0,
-      "earlyExit": true
+      ]
     }
   ],
   "round2SkippedReason": "queue-empty",
@@ -384,12 +377,6 @@ Schema version `1.1` extends `1.0` (legacy fields kept as aliases for backward-c
     "partialConsensus": 1,
     "contested": 0,
     "workerUnique": 1
-  },
-  "summary": {
-    "fullConsensus": 5,
-    "partialConsensus": 1,
-    "contested": 0,
-    "workerUnique": 1
   }
 }
 ```
@@ -408,9 +395,8 @@ Schema rules:
 - `roundHistory[].carriedForwardCount`: queue size at the END of this round — the single definition. In-round insertions into the queue are forbidden, so this always equals `inputQueueSize - resolvedCount`. The pseudocode's per-item `carriedForwardCount += 1` accumulator is a counting convenience that lands on the same value; persist the post-round queue length, not the loop accumulator, if the two ever diverge.
 - `roundHistory[].dispatches[]`: one entry per worker that was actually dispatched in this round. Each entry is `{worker, status, durationMs}`. `status ∈ {completed, timeout, error, not-run}`. `durationMs` is integer milliseconds and is always present, even for terminal-non-result dispatches (use the elapsed time before the wrapper gave up).
 - `roundHistory[].skippedWorkers[]`: per-worker `{worker, reason}` for workers with no items to verify OR with a non-result dispatch.
-- `roundHistory[].verificationsRequested|verificationsCompleted|newConsensus|remainingInQueue|earlyExit`: legacy v1.0 aliases. New runs SHOULD populate them so existing parsers keep working: `verificationsRequested == len(dispatches)`, `verificationsCompleted == len(d for d in dispatches if d.status == "completed")`, `newConsensus == resolvedCount`, `remainingInQueue == carriedForwardCount`, `earlyExit == (round < effectiveMaxRounds AND carriedForwardCount == 0)`.
 - `round2SkippedReason`: literal enum `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped`. Always present. Use `"not-skipped"` when Round 2 actually ran. Use `"max-rounds-1"` when `effectiveMaxRounds == 1` (Round 2 was never attempted). Use `"queue-empty"` when Round 1 fully drained the queue. Use `"all-reverify-non-result"` when all Round 1 dispatches terminated as non-result.
-- `finalClassificationCounts`: post-loop counts. New required field — must equal `summary` 1:1. `summary` is retained as the v1.0 alias.
+- `finalClassificationCounts`: post-loop counts. Required field with keys `fullConsensus`, `partialConsensus`, `contested`, `workerUnique`.
 - `finalState ∈ {converged, max-rounds-reached, aborted-non-result}`. Assigned by the lead at WHILE-loop exit: `converged` when the queue is empty at the end of any round; `max-rounds-reached` when the loop exits because `roundIndex == effectiveMaxRounds` with the queue still non-empty; `aborted-non-result` when the loop exits via the Worker-failure BREAK (Task 3's "Worker failure handling in reverify" rule 4). `aborted-non-result` is the new v1.1 value.
 - `totalRounds`: count of rounds actually executed (not `effectiveMaxRounds`). May be `0` when Round 0 produced no queue items (all findings reached consensus during grouping).
 

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -46,9 +46,11 @@ The prompt MUST include, in this order at the top:
 4. `**Worker Result Path:** runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md` — mandatory validator-checked worker-results audit file
 5. `Assigned worker prompt history path: <absolute-path>`
 6. `**Model:** Report writer worker, <modelExecutionValue>` (resolved per Phase 5.5 anchor-header rules)
-7. The full `[Required reading]` clause (see [okstra-team-contract](../okstra-team-contract/SKILL.md)) including `schemas/final-report-v1.0.schema.json` and `templates/reports/final-report.template.md` (template is read-only — the worker writes the data.json that drives it).
-8. The verbatim `## Available MCP Servers` block from the task brief, if present.
-9. The convergence classifications (Full/Partial/Contested/Worker-Unique), the round history table (`roundHistory[]`), the `round2SkippedReason` value, and pointers to all worker result files under `worker-results/`. The report-writer worker must reproduce a Round History sub-table in Section 1 of the final report so the reader can see which rounds executed, queue sizes, and why Round 2 was (or was not) skipped.
+7. The full `[Required reading]` clause (see [okstra-team-contract](../okstra-team-contract/SKILL.md)) — for Phase 6 it adds two **per-task-type, instruction-set-local** read-only files, both scoped to this run's task-type by `okstra-ctl` at prep time:
+   - `<instruction-set>/final-report-schema.json` — a task-type excerpt of the data.json schema (the other task-types' deliverable blocks and their unreachable `$defs` are stripped; ~38% of the full schema is `$defs` alone). This is your authoring contract for the data.json shape. Do **NOT** pull the full `schemas/final-report-v1.0.schema.json` — it carries all task-types and its `schemas/...` path is not part of the task bundle. (Validation still runs against the full schema post-hoc via the renderer, so the excerpt never relaxes the contract.)
+   - `<instruction-set>/final-report-template.md` — the **phase-stripped** template (every other task-type's §4.x deliverable block removed by `render.py`'s `_strip_phase_blocks`, leaving only your run's §4.x). Do **NOT** also pull the full `templates/reports/final-report.template.md` source (it re-adds ~330 lines of other phases' deliverables and is not in the task bundle).
+8. A one-line MCP pointer instead of the verbatim block — `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).` The brief is already in the report-writer's Required reading (item 7), so the verbatim block is redundant.
+9. The convergence classifications (Full/Partial/Contested/Worker-Unique), the round history data (`roundHistory[]`), the `round2SkippedReason` value, and pointers to all worker result files under `worker-results/`. The report-writer worker populates `crossVerification.roundHistory` in the data.json so Section 1 can show which rounds executed, queue sizes, and why Round 2 was (or was not) skipped. The renderer prints the full per-round table only when more than one round ran; single-round or zero-round histories are auto-collapsed to a one-line summary.
 10. `**Report Language:** <en|ko>` — must be either `en` or `ko`; `auto`
     has been resolved by the lead from project.json / global config
     before the dispatch is constructed. The worker copies this verbatim
@@ -89,7 +91,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    The data.json paths populated: `tokenUsage.lead.{totalTokens,billableTokens,costUsd}`, the `worker` / `grand` rows, `tokenUsage.cli.costUsd`, and each `executionStatus[].{totalTokens,billableTokens,costUsd,durationMs,cliTotalTokens,cliCostUsd}` for rows whose role matches a team-state worker. The data.json MUST already exist (Phase 6 output).
-3. **Phase 7 step 1.5 — Render report views** (BLOCKING). Produces the self-contained HTML view from the now-substituted final-report MD:
+3. **Phase 7 step 1.5 — Render report views** (BLOCKING, conditional output). Always invoke the renderer; it decides whether an html sibling is warranted:
 
    ```bash
    python3 scripts/okstra-render-report-views.py \
@@ -97,9 +99,10 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    Output (idempotent — re-running overwrites):
-   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view. Section 5 `C-*` clarification rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) that the user pastes to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, **generated only when the report has at least one §5 `C-*` clarification row**. Those rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) that the user pastes to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+   - When the report has **no** `C-*` clarification rows, the html carries no interactive forms (it would only duplicate the MD), so the renderer prints `html: skipped (...)` and writes nothing. This is the expected state for clarification-free runs — `validators/validate-report-views.py` treats "no C-* rows + no html" as a pass, not a missing artifact.
 
-   Must run AFTER step 1 (so token placeholders are substituted in the rendered html) and BEFORE step 2 (so the html artifact exists for any validator step that checks it).
+   Must run AFTER step 1 (so token placeholders are substituted in any rendered html) and BEFORE step 2 (so the html artifact, when generated, exists for the validator step that checks it).
 4. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 7 is non-empty). Turns the report's `## 7. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
 
    ```bash
@@ -255,7 +258,7 @@ Skipping this file because "the real report is in `reports/`" is wrong. Both fil
 
 ### Main Body Section
 
-Section numbering follows `templates/reports/final-report.template.md` exactly — that file is the single source of truth. Below is a one-line summary of each section's writer obligation; consult the template for full body structure.
+Section numbering follows `templates/reports/final-report.template.md` exactly — that file is the documentation SSOT for section names and ordering. For full body structure at authoring time, consult your run's **phase-stripped** `final-report-template.md` (the instruction-set copy of the same template, with other task-types' §4.x deliverable blocks removed); the "copy that block verbatim" references below mean the §-block as it appears in that stripped copy, not a re-read of the full source.
 
 **Verdict Card (top-of-report, mandatory).** Render `## Verdict Card` between the report header and the (conditional) Approval block. Its `Verdict Token` / `Direction` / `Next Step` cells MUST byte-match the corresponding cells in `## 2. Final Verdict` and the first item of `## 6.`. Divergence is `contract-violated`.
 
@@ -313,7 +316,7 @@ Persistence steps that must be performed in Phase 7:
 - [ ] 6. **Generate final status file**: `runs/<task-type>/status/final-<task-type>-<seq>.status` (if necessary)
 - [ ] 7. **Save convergence state**: `runs/<task-type>/state/convergence-<task-type>-<seq>.json` (when convergence is enabled)
 - [ ] 8. **Spawn follow-up task stubs**: run `scripts/okstra-spawn-followups.py` against the final-report per the canonical spawn rule defined in "Phase 7 follow-up task spawner" above. Do not restate the trigger condition here — that section is the single source of truth. The script is idempotent across reruns.
-- [ ] 9. **Human HTML report**: `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` (produced by Phase 7 step 1.5 — self-contained, embeds `Export user response` button)
+- [ ] 9. **Human HTML report** (conditional): `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — produced by Phase 7 step 1.5 **only when the report has ≥1 §5 `C-*` clarification row** (self-contained, embeds `Export user response` button). Clarification-free reports legitimately have no html sibling; do not treat its absence as a missing artifact.
 
 ### Response after Persistence
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -80,7 +80,7 @@ The body must include: role name, task type, task key, required bundle paths, as
 
 When a worker reads any project-relative path from the prompt, it MUST resolve it against `Project Root` (e.g. `<Project Root>/<Result Path>`) — never use bare relative paths that depend on cwd.
 
-If the task brief contains an `## Available MCP Servers` section, copy that section verbatim into every analysis worker's prompt (and into the report-writer prompt when it is dispatched in Phase 6). Codex/Gemini workers run external CLIs whose MCP availability is governed by their own CLI configs; still forward the section so they can record `MCP not available in this CLI` cleanly when their CLI lacks the matching server.
+If the task brief contains an `## Available MCP Servers` section, inject only the one-line pointer into every analysis worker's prompt (and into the report-writer prompt when it is dispatched in Phase 6) — the brief is already in every worker's [Required reading], so verbatim copy is redundant: `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).` Codex/Gemini workers run external CLIs whose MCP availability is governed by their own CLI configs; they can record `MCP not available in this CLI` cleanly after reading that section in the brief.
 
 Before dispatching any required worker, lead persists the exact worker prompt to the assigned current-run prompt history path under `runs/<task-type>/prompts/`. Do not use `/tmp/*prompt*.txt` as the canonical artifact path.
 
@@ -100,7 +100,7 @@ Audience-scoped file enumeration (BLOCKING — performance optimization):
 | Recipient | Files the lead lists under `## Inputs` |
 |---|---|
 | Claude / Codex / Gemini analysis workers | task-brief, analysis-profile, analysis-material (if present), reference-expectations, clarification-response (if carry-in) |
-| Report writer worker (Phase 6) | all of the above **plus** `final-report-template.md` |
+| Report writer worker (Phase 6) | all of the above **plus** the instruction-set-local `final-report-template.md` (phase-stripped) and `final-report-schema.json` (per-task-type excerpt) — NOT the full `templates/reports/...` / `schemas/...` sources |
 | Reverify dispatches | none — the lead provides only the items to reverify |
 
 Asymmetry note: `claude-worker` runs in-process and the Agent SDK auto-loads its agent definition; lead's dispatch prompt body for claude-worker can therefore be shorter than for codex/gemini. The Worker Preamble pointer is still emitted for all three so the contract source is identical regardless of dispatch path.
@@ -318,41 +318,33 @@ Every worker result file under `worker-results/` must begin with a standardized
 ```markdown
 # <Role> Analysis — <task-key>
 
-**Task:** <task-type>
 **Target:** <path or scope>   <!-- OPTIONAL: include when the run is scoped to a specific file/module -->
-**Date:** <YYYY-MM-DD>
 **Model:** <Role>, <AI model>
 ```
 
-The `Target:` line is optional. Include it when the run is scoped to a specific path or module; omit it when the run spans the whole project. When included, place it between `Task:` and `Date:` as shown.
+Task-type and date are **not** repeated in this human header — they already live in the YAML frontmatter (`taskType`, `date`), which is the copy Obsidian indexes. Restating them here added a third, un-indexed, machine-unparsed copy with no value; the frontmatter is the single source for both. The `Target:` line is optional — include it when the run is scoped to a specific path or module, omit it for whole-project runs; when present, place it between the title and the `Model:` line.
 
 Examples:
 
 ```markdown
 # Claude Worker Analysis — jobs:tasks:8852
 
-**Task:** error-analysis
 **Target:** server/auth.ts
-**Date:** 2026-04-06
-**Model:** Claude worker, sonnet
+**Model:** Claude worker, opus
 ```
 
 ```markdown
 # Codex Worker Analysis — jobs:tasks:8852
 
-**Task:** error-analysis
 **Target:** server/auth.ts
-**Date:** 2026-04-06
 **Model:** Codex worker, <codex-model-id>
 ```
 
 ```markdown
 # Report Writer Worker Analysis — jobs:tasks:8852
 
-**Task:** error-analysis
 **Target:** server/auth.ts
-**Date:** 2026-04-06
-**Model:** Report writer worker, opus-4-6
+**Model:** Report writer worker, opus
 ```
 
 Use the actual model identifier recorded in team-state (never invent a model ID — read it from `resultContract.requiredWorkerRoles[*].modelExecutionValue` or the tool response metadata).

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

@@ -96,7 +96,9 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 | {{ t("tokenSummary.rowLead") }} | `{{ tokenUsage.lead.totalTokens | format_int }}` | `{{ tokenUsage.lead.billableTokens | format_int }}` | `{{ tokenUsage.lead.costUsd | format_usd }}` |
 | {{ t("tokenSummary.rowWorkerTotal") }} | `{{ tokenUsage.worker.totalTokens | format_int }}` | `{{ tokenUsage.worker.billableTokens | format_int }}` | `{{ tokenUsage.worker.costUsd | format_usd }}` |
 | {{ t("tokenSummary.rowGrandTotal") }} | **`{{ tokenUsage.grand.totalTokens | format_int }}`** | **`{{ tokenUsage.grand.billableTokens | format_int }}`** | **`{{ tokenUsage.grand.costUsd | format_usd }}`** |
+{% if tokenUsage.cli and tokenUsage.cli.costUsd is not none and tokenUsage.cli.costUsd > 0 -%}
 | {{ t("tokenSummary.rowCliExtra") }} |  |  | `{{ tokenUsage.cli.costUsd | format_usd }}` |
+{% endif %}
 
 {# At Phase 6 numeric cells are null and render as `--`.
    Phase 7's okstra-token-usage.py populates tokenUsage in data.json then
@@ -107,6 +109,7 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 {% if crossVerification.roundHistory and not crossVerification.roundHistory.disabled -%}
 ### 1.0 Round History
 
+{% if crossVerification.roundHistory.rounds | length > 1 -%}
 | Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches (worker:status:durationMs) | skippedWorkers (worker:reason) |
 |-------|----------------|---------------|----------------------|----------------------------------------|---------------------------------|
 {% for row in crossVerification.roundHistory.rounds -%}
@@ -114,6 +117,12 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 {% endfor %}
 
 - `round2SkippedReason`: `{{ crossVerification.roundHistory.round2SkippedReason }}`  ← {{ t("roundHistory.round2SkippedReasonNote") }}
+{% elif crossVerification.roundHistory.rounds | length == 1 -%}
+{% set r = crossVerification.roundHistory.rounds[0] -%}
+- {{ t("roundHistory.singleRoundPrefix") }} resolved={{ r.resolvedCount }}, carriedForward={{ r.carriedForwardCount }}, round2SkippedReason=`{{ crossVerification.roundHistory.round2SkippedReason }}`
+{% else -%}
+- {{ t("roundHistory.noRoundsNote") }} round2SkippedReason=`{{ crossVerification.roundHistory.round2SkippedReason }}`
+{% endif %}
 
 {% endif %}
 ### 1.1 Consensus

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

@@ -75,7 +75,9 @@
     "sourceItemsColumnNote": "`Source items` column rule is the same as §1.1."
   },
   "roundHistory": {
-    "round2SkippedReasonNote": "value is one of `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only`"
+    "round2SkippedReasonNote": "value is one of `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only`",
+    "singleRoundPrefix": "Single round —",
+    "noRoundsNote": "No reverify rounds executed (all findings reached consensus at grouping)."
   },
   "implementationPlanning": {
     "optionInterfacesLabel": "Affected interfaces / public contracts / downstream consumers",

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

@@ -75,7 +75,9 @@
     "sourceItemsColumnNote": "`Source items` 컬럼 규칙은 §1.1 과 동일."
   },
   "roundHistory": {
-    "round2SkippedReasonNote": "값은 `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only` 중 하나."
+    "round2SkippedReasonNote": "값은 `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only` 중 하나.",
+    "singleRoundPrefix": "단일 라운드 —",
+    "noRoundsNote": "재검증 라운드 미실행 (그룹핑 단계에서 전부 합의)."
   },
   "implementationPlanning": {
     "optionInterfacesLabel": "영향 인터페이스 / 공개 계약 / 다운스트림 소비자",

package/runtime/templates/worker-prompt-preamble.md

@@ -17,7 +17,7 @@ Different recipients need different files. Do NOT include `final-report-template
 | Recipient | Files included in `[Required reading]` |
 |---|---|
 | Claude / Codex / Gemini analysis workers | task-brief, analysis-profile, analysis-material (if present), reference-expectations, clarification-response (if carry-in) |
-| Report writer worker (Phase 6) | all of the above **plus** `final-report-template.md` |
+| Report writer worker (Phase 6) | all of the above **plus** the instruction-set-local `final-report-template.md` (phase-stripped) and `final-report-schema.json` (per-task-type excerpt) — NOT the full `templates/reports/...` / `schemas/...` sources |
 | Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [okstra-convergence](../skills/okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
 
 ### Reading rules

package/runtime/validators/validate-report-views.py

@@ -80,9 +80,16 @@ def validate(report_path: Path) -> list[str]:
 
     md = report_path.read_text(encoding="utf-8")
     html_path = report_path.with_name(report_path.stem + ".html")
+    md_ids = _md_response_ids(md)
 
-    # (1) sibling artifact exists
+    # (1) sibling artifact exists — conditional on §5 clarification rows.
+    # The html view's sole value over the MD is its embedded form widgets
+    # for §5 C-* rows, so a clarification-free report intentionally has no
+    # html sibling (see report_views.report_has_clarification_items). When
+    # there are no C-* rows and no html, that is the expected skip state.
     if not html_path.is_file():
+        if not md_ids:
+            return []
         return [f"missing html artifact: {html_path}"]
 
     html_text = html_path.read_text(encoding="utf-8")
@@ -119,7 +126,7 @@ def validate(report_path: Path) -> list[str]:
     # (5) Response ID parity: HTML form rows ↔ §5 C-* rows in MD.
     # Bidirectional — catches both "MD has C-* the HTML lost" AND
     # "HTML has stale C-* that the current MD no longer declares".
-    md_ids = _md_response_ids(md)
+    # (md_ids computed once at the top.)
     html_ids = sorted(set(_RESPONSE_ID_ATTR_RE.findall(html_text)))
     if md_ids != html_ids:
         failures.append(

package/runtime/validators/validate-run.py

@@ -1540,9 +1540,11 @@ def _rerender_report_views_after_autofix(report_path: Path) -> str:
         source_report=report_path.name,
     )
     try:
-        render_html_view(report_path, run_meta=meta, css=css, js=js)
+        rendered = render_html_view(report_path, run_meta=meta, css=css, js=js)
     except Exception as exc:  # noqa: BLE001
         return f"report-views re-render failed: {exc}"
+    if rendered is None:
+        return "report-views skipped (no §5 clarification rows)"
     return "report-views re-rendered"
 
 

package/src/install.mjs

@@ -589,11 +589,24 @@ export async function runInstall(args) {
     join(paths.home, "templates"),
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
   );
+  // schemas/ tree — final-report-v1.0.schema.json is loaded at runtime by
+  // okstra_ctl.final_report_schema.load_schema() (parent-walk from the
+  // installed okstra_ctl package finds ~/.okstra/schemas/). It is needed by
+  // (a) prepare_task_bundle to write the per-task-type schema excerpt into
+  // each run's instruction-set, and (b) validate-run's data.json schema
+  // check. Without this step copy-mode installs leave load_schema() unable
+  // to locate the schema. Link mode resolves it through the repo symlink.
+  const schemasResult = await copyTreeIfChanged(
+    join(runtimeRoot, "schemas"),
+    join(paths.home, "schemas"),
+    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
+  );
 
   if (!opts.quiet) {
     summarise("python", pythonResult, paths.pythonpath);
     summarise("bin", binResult, paths.bin);
     summarise("templates", templatesResult, join(paths.home, "templates"));
+    summarise("schemas", schemasResult, join(paths.home, "schemas"));
   }
 
   if (pythonResult.missingSource && binResult.missingSource) {
@@ -606,6 +619,11 @@ export async function runInstall(args) {
       "warning: runtime/templates is empty. report.css / report.js will be missing — re-run the build step.\n",
     );
   }
+  if (schemasResult.missingSource) {
+    process.stderr.write(
+      "warning: runtime/schemas is empty. final-report schema validation + excerpt generation will be unavailable — re-run the build step.\n",
+    );
+  }
 
   const skillResult = await installSkillsCopy(runtimeRoot, opts);
   await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });
@@ -682,6 +700,9 @@ export async function runEnsureInstalled(args) {
   }
   if (!(await dirExists(paths.pythonpath))) reasons.push(`missing ${paths.pythonpath}`);
   if (!(await dirExists(paths.agents))) reasons.push(`missing agents dir ${paths.agents}`);
+  if (!(await fileExists(join(paths.home, "schemas", "final-report-v1.0.schema.json")))) {
+    reasons.push(`missing ${join(paths.home, "schemas", "final-report-v1.0.schema.json")}`);
+  }
   if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
     reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
   }