okstra 0.27.0 → 0.29.0

package/runtime/python/okstra_token_usage/cli.py

@@ -6,7 +6,7 @@ import json
 import sys
 from pathlib import Path
 from .collect import collect
-from .report import substitute_final_report
+from .report import SubstituteRefusedError, substitute_final_report
 
 
 def main() -> int:
@@ -60,7 +60,14 @@ def main() -> int:
         print(f"sessions={s.get('sessionsFound', 0)} team={s.get('teamName', '')}", file=sys.stderr)
 
     if args.substitute_final_report is not None:
-        replaced = substitute_final_report(args.substitute_final_report, updated)
+        try:
+            replaced = substitute_final_report(args.substitute_final_report, updated)
+        except SubstituteRefusedError as exc:
+            print(
+                f"final-report substitution REFUSED: {exc}",
+                file=sys.stderr,
+            )
+            return 2
         if replaced < 0:
             print(
                 f"final-report substitution skipped: file not found at {args.substitute_final_report}",

package/runtime/python/okstra_token_usage/report.py

@@ -18,19 +18,48 @@ def _format_usd(v) -> str:
         return "$0.00"
 
 
+class SubstituteRefusedError(RuntimeError):
+    """Raised when substitution would write a zero-only Token Usage Summary.
+
+    Shipping `0` / `$0.00` in the Lead / Worker / Grand rows is the
+    observed silent-failure mode where the collector ran but every
+    session jsonl was empty (or the writer fabricated zeros). The
+    validator catches it post-hoc, but raising here at the substitution
+    boundary surfaces the failure at the exact step where it can still
+    be retried with a re-collection.
+    """
+
+
 def substitute_final_report(report_path: Path, state: dict) -> int:
     """Replace token-usage placeholders in the final report file with concrete
     values from the freshly computed usageSummary.
 
     Returns the number of placeholder occurrences replaced. If the report file
-    does not exist, returns -1 without raising. If any required placeholder is
-    still present after substitution attempts (e.g. usageSummary missing), the
-    function still writes what it can and returns the count.
+    does not exist, returns -1 without raising.
+
+    Raises ``SubstituteRefusedError`` when ``usageSummary.grandTotalTokens``
+    is zero — substituting zeros into the report bakes in the most common
+    silent failure mode (collector ran but found nothing). Callers that
+    want to suppress the refusal (e.g. unit-test fixtures) can pass a
+    summary with ``grandTotalTokens`` > 0 or remove the summary entirely
+    so substitution is skipped.
     """
     if not report_path.is_file():
         return -1
 
     summary = state.get("usageSummary") or {}
+    grand_total = summary.get("grandTotalTokens", 0)
+    if isinstance(grand_total, (int, float)) and grand_total == 0 and summary:
+        raise SubstituteRefusedError(
+            "Refusing to substitute zero-only usageSummary into the final "
+            f"report at {report_path}. grandTotalTokens=0 means the "
+            "collector ran but every session jsonl was empty (or absent). "
+            "Re-run `python3 scripts/okstra-token-usage.py <team-state> "
+            "--write --summary --substitute-final-report <report-path>` "
+            "after locating the missing session jsonls. To intentionally "
+            "ship zeros (test fixtures only), omit `usageSummary` from the "
+            "team-state JSON before calling substitute_final_report."
+        )
     cost = summary.get("estimatedCostUsd") or {}
     lead_cost = cost.get("lead") or 0
     worker_cost = cost.get("claudeWorkers") or 0

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

@@ -73,7 +73,7 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
    - For bullet/numbered findings, parse `[TICKETID: <id>]` from the item title.
    - Items with multiple tickets (e.g. `TICKET-123, TICKET-456`) expand to a set of ticket keys.
    - Items tagged `unknown` keep the literal `unknown` as their ticket key.
-2. For each finding, record the summary, evidence (file path, line number, basis), the worker who identified it, and the parsed ticket set.
+2. For each finding, record the summary, evidence (file path, line number, basis), the worker who identified it, **the worker-internal item ID assigned by that worker** (e.g. `F-001`, `1.1`, `F-3` — see `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT), and the parsed ticket set. The item ID is persisted on the finding record as `findings[].discoveredBy.<worker>.itemId` and on each cross-worker confirmation as `findings[].sourceItems[]` (one entry per contributing `<worker>:<item-id>` pair). The final-report's `## 1.1 Consensus` / `## 1.2 Differences` / `## 3.1 Primary Evidence` tables read this list verbatim into their `Source items` columns — without this, the synthesised `C-NNN` row has no traceable link back to the original worker wording.
 3. Claude Lead groups findings based on semantic similarity AND ticket-set equality:
   - Same semantics + same ticket set across 2+ workers → immediately reach `full consensus`.
   - Same semantics but disjoint ticket sets → keep as separate groups (do NOT over-merge across tickets).
@@ -521,7 +521,7 @@ Plan-body verification only supports **lightweight mode** (defined in §"Verific
    - all dispatches non-result → `aborted-non-result`
    - any `partial-consensus` / `dissent-isolated` present, no `majority-disagree` → `passed-with-dissent`
    - all items `full-consensus` → `passed`
-6. Lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below) and populates `### 4.5.9 Plan Body Verification` in the final report (template at `templates/reports/final-report.template.md`).
+6. Lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below) and populates `### 4.5.9 Plan Body Verification` in the final report (template at `templates/reports/final-report.template.md`). The §4.5.9 body in the template is split into two tables: a narrow `#### Verdict summary` (`Plan item / Ticket ID / Section / Classification` only — one row per plan item) and a tall `#### Verdict details` (`Plan item / Worker / Verdict / Breakage kind / Note` — one row per plan-item × worker pair). The older wide `| Plan item | <worker1> | <worker2> | … | Classification |` matrix is removed — it scaled horizontally with the worker count and lost readability past 3 workers. Lead MUST emit both tables (the validator's `Plan Body Verification` + `Gate result:` substring checks still pass either layout, but reviewers depend on the split form).
 7. For every `majority-disagree` item, lead adds a row to `## 5. Clarification Items` with:
    - new `C-<N>` ID (numbering continues from any existing rows)
    - `Statement` summarising the disagreement and the worker breakage `<kind>`

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

@@ -83,7 +83,19 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    The 10 substituted placeholders: `{{LEAD_TOTAL_TOKENS}}`, `{{LEAD_BILLABLE_TOKENS}}`, `{{LEAD_COST_USD}}`, `{{WORKER_TOTAL_TOKENS}}`, `{{WORKER_BILLABLE_TOKENS}}`, `{{WORKER_COST_USD}}`, `{{GRAND_TOTAL_TOKENS}}`, `{{GRAND_BILLABLE_TOKENS}}`, `{{GRAND_COST_USD}}`, `{{CLI_COST_USD}}`. The final-report file MUST already exist (Phase 6 output).
-3. **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.
+3. **Phase 7 step 1.5 — Render report views** (BLOCKING). Produces two derived artifacts from the now-substituted final-report MD:
+
+   ```bash
+   python3 scripts/okstra-render-report-views.py \
+     <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md
+   ```
+
+   Outputs (idempotent — re-running overwrites):
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.slim.md` — token-saving AI-consumption copy.
+   - `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 `<textarea>` controls; 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.
+
+   Must run AFTER step 1 (so token placeholders are substituted in both derived views) and BEFORE step 2 (so the slim/html artifacts exist for any validator step that checks them).
+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
    python3 scripts/okstra-spawn-followups.py \
@@ -98,7 +110,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    - Rows with `Auto-spawn? != yes` are reported as `skipped` and never written; surface them in Section 6 if manual action is still needed.
    - An invalid `Origin`, `Suggested task-type`, missing `Title`, or missing `Reason / Why deferred` exits `1`. The report-writer MUST refuse to ship a Section 7 with such rows.
    - **Canonical spawn rule (single source of truth):** the spawner runs when `task-type` ∈ {`implementation`, `final-verification`, `release-handoff`}, OR when Section 7 is non-empty for any other task-type. For the listed task-types Section 7 must be present in the report; an empty section renders as `- 후속 작업 없음.`. Missing / empty sections are no-ops (exit `0`). All other references to this rule (including the Persistence Checklist) defer to this statement.
-4. **Phase 7 step 3 — Update Section 6** after the spawner. The report-writer MUST append one row per newly spawned task-key with its entry command:
+5. **Phase 7 step 3 — Update Section 6** after the spawner. The report-writer MUST append one row per newly spawned task-key with its entry command:
 
    ```
    - Follow-up: `<task-group>/<new-task-id>` — Claude Code 세션 안 `/okstra-run task-key=<task-group>/<new-task-id> task-type=<suggested>` / 별도 터미널 `scripts/okstra.sh --task-key <task-group>/<new-task-id> --task-type <suggested>`
@@ -117,7 +129,8 @@ The final report follows the structure below. If `instruction-set/final-report-t
 - Date: <ISO 8601 timestamp>
 - Task Key: <task-key>
 - Task Type: <task-type>
-- Author: `<Report writer worker if in roster, else Claude lead>`
+- Report Owner: `Claude lead`
+- Report Author: `<Report writer worker if in roster, else Claude lead (release-handoff or recorded-fallback only)>`
 - Lead model: `<lead-model>`
 - Preparation Method: Final report authored by Report writer worker (or lead-authored fallback — record the documented dispatch failure reason here when applicable)
 ```
@@ -185,8 +198,8 @@ When the run's `task-type` is `implementation-planning`, the final report MUST c
 | 5 | `Dependency` | `### Dependency / Migration Risk (의존성·마이그레이션 위험)` |
 | 6 | `Validation Checklist` | `### Validation Checklist (검증 체크리스트)` |
 | 7 | `Rollback` | `### Rollback Strategy (롤백 전략)` |
-| 8 | `User Approval Request` | `### User Approval Request (사용자 승인 요청)` |
-| 9 | `Plan Body Verification` + `Gate result:` | `### Plan Body Verification (계획 본문 검증)` containing a `Gate result:` line — copy `okstra-final-report.template.md §4.5.9` verbatim. Validator (`validators/validate-run.py` lines 531, 548) checks both substrings. |
+| 8 | `User Approval Request` | Satisfied by the top-of-report `## User Approval Request (사용자 승인 게이트)` block. Do NOT recreate a `### 4.5.8 User Approval Request` body stub — the validator now fails reports that contain one. |
+| 9 | `Plan Body Verification` + `Gate result:` | `### Plan Body Verification (계획 본문 검증)` containing a `Gate result:` line — copy `okstra-final-report.template.md §4.5.9` verbatim. Validator checks both substrings. |
 
 The Korean translation in parentheses is optional but the English keyword is mandatory. The body of each section is written in Korean per the writing rules below. For non-`implementation-planning` runs, omit this entire block — these headings are NOT validator-checked for other task-types.
 
@@ -208,7 +221,7 @@ The final-report template `okstra-final-report.template.md` Section 2 already en
 
 ### Release-handoff section contract (release-handoff runs only)
 
-When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all eight sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Merge Conflict Probe, `4.6.7` Pull Request Outcome, `4.6.8` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
 
 **Single-lead authorship (release-handoff only):** release-handoff has no worker roster (no `Report writer worker`, no `Claude worker` drafter). The Claude lead authors the final-report file directly — there is no `Report writer worker` dispatch to perform in Phase 6, no resume-safe dispatch concern, and no mandatory worker-results file for a report-writer role. The rest of this skill's dispatch / resume / fallback machinery applies ONLY when `Report writer worker` is in the roster (i.e. every task-type other than `release-handoff`).
 
@@ -232,12 +245,14 @@ Skipping this file because "the real report is in `reports/`" is wrong. Both fil
 
 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.
 
-0. **Clarification Response Carried In** — if `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty, walk every `C-*` row of the prior report's `## 5. Clarification Items` table, reconcile each one against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. Legacy `4.5.9 / 5.1 / 5.2` carry-in mapping is documented in the template's Section 0.
+**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`.
+
+0. **Clarification Response Carried In** — render this `## 0.` heading ONLY when `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty. Walk every `C-*` row of the prior report's `## 5. Clarification Items` table, reconcile against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. When no carry-in path was provided, OMIT the `## 0.` heading entirely — the validator fails an empty Section 0 stub.
 1. **Cross Verification Results** — 4 categories (Full / Partial / Contested / Worker-Unique) when convergence is enabled, per `okstra-convergence`. Prepend the Round History sub-table (columns: `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches | skippedWorkers`) plus a `round2SkippedReason: <value>` note, pulled verbatim from `convergence-<task-type>-<seq>.json`. Empty contested list renders as `- 합의 미달 항목 없음.`. Convergence-disabled runs use the legacy Consensus/Differences format and omit the round table.
 2. **Final Verdict** — `Direction` ∈ `continue-investigation` / `begin-implementation` / `approve` / `reject` / `hold`. **Verdict Token** is `not-applicable` for every task-type except `final-verification` — see "Final-verification verdict token contract" below for that case.
 3. **Evidence and Detailed Analysis** — primary evidence rows (file path, line, snippet); secondary evidence / alternate interpretations. If `reference-expectations.md` lists explicit expected values, record match/gap per row.
 4. **Missing Information and Risks** — uncertain / "I don't know" items. `implementation-planning` adds §4.5 (see heading contract below); `release-handoff` adds §4.6.
-5. **Clarification Items** — single unified `C-*` table; column schema, ID convention, and rerun behaviour are owned by `_common-contract.md §Clarification request policy` (8-column SSOT). Never recreate the deprecated `4.5.9 Open Questions` / `5.1` / `5.2` sub-sections.
+5. **Clarification Items** — single unified `C-*` table; column schema, ID convention, and rerun behaviour are owned by `_common-contract.md §Clarification request policy` (8-column SSOT). The deprecated `4.5.9 Open Questions` / `5.1 추가 자료 요청` / `5.2 사용자 확인 질문` sub-sections are removed; the validator fails reports that reintroduce them.
 6. **Recommended Next Steps** — prioritized actions. After Phase 7's follow-up spawner runs, append a row per newly created task-key (see "Phase 6 → Phase 7 execution sequence" above).
 7. **Follow-up Tasks** — auto-spawn-eligible table. Each row drives `okstra-spawn-followups.py`; see template §7 for the row schema.
 
@@ -276,6 +291,8 @@ 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. **Slim AI report**: `runs/<task-type>/reports/final-report-<task-type>-<seq>.slim.md` (produced by Phase 7 step 1.5 — see "Phase 6 → Phase 7 execution sequence" above)
+- [ ] 10. **Human HTML report**: `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` (same step 1.5; self-contained, embeds `Export user response` button)
 
 ### Response after Persistence
 

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

@@ -132,19 +132,23 @@ Reading rules:
     large for one read; if you must page, you MUST cover the entire file
     before moving on, and you MUST state the page boundaries you used in your
     Findings section.
-  - For the carry-in clarification response, read sub-section 0 and every
-    row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full,
+  - For the carry-in clarification response, read the conditional
+    `## 0. Clarification Response Carried In From Previous Run` section
+    (rendered only when carry-in is non-empty) and every row of
+    `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full,
     including rows whose `User input` cell is blank. The fact that you
     will write your output into a file with a structurally similar
     section 5 is NOT an excuse to skim — the prior `C-*` rows carry
-    context you cannot reconstruct from the new run alone. If the prior
-    report uses the deprecated `4.5.9 Open Questions` / `5.1` / `5.2`
-    layout with `OQ-*` / `A*` / `Q*` IDs, walk all three blocks the
-    same way (legacy carry-in transitional rule).
-  - Before writing any Findings, state in one sentence per file that you
-    read it end-to-end. Example: "Read task-brief.md end-to-end (147 lines)."
-    If you cannot truthfully say this for a file, do not produce Findings —
-    record a `tool-failure` in the errors sidecar instead.
+    context you cannot reconstruct from the new run alone.
+  - Write the Reading Confirmation block to your **audit sidecar** at
+    `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`
+    (sibling to the main worker-results file). One short line per input
+    file confirming end-to-end reading, e.g. "Read task-brief.md
+    end-to-end (147 lines)." Do NOT include a `## 0. Reading Confirmation`
+    heading in the main worker-results file — the validator now fails
+    worker-results that contain one. If you cannot truthfully confirm a
+    file end-to-end, record a `tool-failure` in the errors sidecar
+    instead of fabricating Findings.
   - Do not collapse multiple input files into a single mental summary before
     reading them all individually. Each file has its own canonical role
     (brief = the user's request, profile = the lead's rules for this phase,
@@ -209,7 +213,7 @@ Terminal statuses that can be recorded for a worker:
 
 **Authoritative source.** If other documents (SKILL.md, worker agent definitions) disagree with this section, this section wins.
 
-### Result Frontmatter (mandatory, precedes Section 0)
+### Result Frontmatter (mandatory, precedes Section 1)
 
 Every worker result file MUST begin with a YAML frontmatter block. The values are sourced from the corresponding fields of the input files' frontmatter (e.g. `analysis-material.md`, `task-brief.md`) — copy them verbatim; do NOT regenerate them. Only `workerId` and `title` are worker-specific.
 
@@ -256,11 +260,8 @@ The same frontmatter contract applies to the `Report writer worker`'s final-repo
 
 A successful worker result must include the following sections in this exact order, beneath the frontmatter block:
 
-0. **Reading Confirmation** — one short line per input file stating that the worker read it end-to-end. Each line takes the form `- Read <file-name> end-to-end (<line-count> lines).`. The enumerated files are audience-scoped — they MUST match the recipient's row in the "Audience-scoped enumeration" table above:
-   - **Claude / Codex / Gemini analysis workers**: `task-brief.md`, `analysis-profile.md`, `analysis-material.md` (if present), `reference-expectations.md`, `clarification-response.md` (if a carry-in was provided). Analysis workers MUST NOT include `final-report-template.md` — it is not in their `[Required reading]` block.
-   - **Report writer worker (Phase 6)**: all of the above **plus** `final-report-template.md`.
+> **Reading Confirmation lives in the audit sidecar, NOT in the main worker result.** Section 0 is intentionally absent from the main file. The worker writes Reading Confirmation to `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md` per the dispatch-prompt clause above; the validator FAILS any main worker-result file that contains a `## 0. Reading Confirmation` heading. If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5 — instead it records a `tool-failure` in the errors sidecar and stops.
 
-   If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5; instead it records a `tool-failure` in the errors sidecar and stops. This section exists specifically to counteract the common failure mode where workers skim long inputs because they share structure with the file the run will eventually write into.
 1. Findings
 2. Missing Information or Assumptions
 3. Safe or Reasonable Areas