okstra 0.176.1 → 0.177.1

package/runtime/python/okstra_ctl/write_policy.py

@@ -175,7 +175,15 @@ def planned_paths_from_run_manifest(
     active_value = manifest.get("activeRunContextPath")
     if not isinstance(active_value, str) or not active_value:
         raise WritePolicyError("implementer write policy has no active run context")
-    active = _read_json(_rooted(project_root, active_value), "active run context")
+    # `compact_active_run_context` drops `sourceArtifacts` and stores path
+    # hints instead; the hydrator is what puts the block back. Reading the file
+    # raw always saw `None` here and reported the run as having no approved
+    # stage authority, which blocked every implementer dispatch.
+    from .path_hints import hydrate_active_run_context
+
+    active = hydrate_active_run_context(
+        _read_json(_rooted(project_root, active_value), "active run context")
+    )
     source = active.get("sourceArtifacts")
     run_inputs_value = source.get("runInputsPath") if isinstance(source, Mapping) else None
     run = active.get("run")

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

@@ -230,10 +230,9 @@
     },
     "verdictCard": {
       "type": "object",
-      "description": "Top-of-report at-a-glance card. Values MUST byte-match finalVerdict and recommendedNextSteps[0]; renderer fills both from this data structure so divergence is impossible.",
+      "description": "Top-of-report at-a-glance card. It carries no verdict token — the token lives once, in finalVerdict. `direction` and `nextStep` MUST byte-match finalVerdict and recommendedNextSteps[0].",
       "required": [
         "finalConclusion",
-        "verdictToken",
         "direction",
         "approvalRequired",
         "nextStep"
@@ -245,9 +244,6 @@
           "minLength": 1,
           "description": "Conclusion SSOT for the whole report: at most 3 sentences. Other prose blocks reference this instead of restating it."
         },
-        "verdictToken": {
-          "$ref": "#/$defs/VerdictToken"
-        },
         "direction": {
           "$ref": "#/$defs/Direction"
         },
@@ -1406,6 +1402,7 @@
       "description": "RENDER_IF taskType == final-verification. §5.8 deliverables.",
       "required": [
         "sourceImplementationReport",
+        "addedSurfaceAudit",
         "acceptanceBlockers",
         "residualRisk",
         "validationEvidence",
@@ -1475,6 +1472,13 @@
             }
           }
         },
+        "addedSurfaceAudit": {
+          "type": "array",
+          "description": "Over-delivery axis. One row per identifier / module / configuration entry the merged diff ADDS, each traced to the brief requirement it serves. An empty array states the diff added no such surface; it is not a licence to skip the enumeration.",
+          "items": {
+            "$ref": "#/$defs/AddedSurfaceRow"
+          }
+        },
         "acceptanceBlockers": {
           "type": "array",
           "items": {
@@ -2049,17 +2053,6 @@
       },
       "then": {
         "properties": {
-          "verdictCard": {
-            "properties": {
-              "verdictToken": {
-                "enum": [
-                  "analysis-complete",
-                  "analysis-partial",
-                  "blocked"
-                ]
-              }
-            }
-          },
           "finalVerdict": {
             "not": {
               "required": [
@@ -7006,7 +6999,9 @@
           "enum": [
             "Claude Code",
             "Codex",
-            "Antigravity"
+            "Antigravity",
+            "Grok",
+            "Kimi"
           ]
         },
         "role": {
@@ -9576,6 +9571,51 @@
         }
       }
     },
+    "AddedSurfaceRow": {
+      "type": "object",
+      "description": "One surface the merged diff added, and what requirement it serves.",
+      "required": [
+        "id",
+        "surface",
+        "callers",
+        "requirement",
+        "disposition",
+        "note"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^AS-\\d{3,}$"
+        },
+        "surface": {
+          "type": "string",
+          "minLength": 1,
+          "description": "path:line plus the added identifier / module / configuration key."
+        },
+        "callers": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The caller found by searching the whole repository, or `none`. A declaration, its own test, or a commented-out line is not a caller."
+        },
+        "requirement": {
+          "type": "string",
+          "description": "The brief requirement this surface serves. Empty unless disposition is `traced`."
+        },
+        "disposition": {
+          "enum": [
+            "traced",
+            "exempt",
+            "over-delivery"
+          ]
+        },
+        "note": {
+          "type": "string",
+          "minLength": 1,
+          "description": "`traced`: how the surface serves the requirement. `exempt`: which exit applies and its cited evidence. `over-delivery`: the `AB-NNN` or `CA-NNN` row this became."
+        }
+      }
+    },
     "AcceptanceBlockerRow": {
       "type": "object",
       "required": [
@@ -9594,8 +9634,7 @@
         "severity": {
           "enum": [
             "critical",
-            "major",
-            "minor"
+            "major"
           ]
         },
         "statement": {

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

@@ -239,9 +239,9 @@ okstra config set pr-template-path "<value>" --scope global
 
 If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
 
-Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — reclaim the prior round's completed teammate panes so they do not accumulate, in two passes and adding `--keep report-writer-worker` to **both** whenever the report writer is still in flight. First source the count: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` never kills and prints one `<pane_id>\t<pane_title>` line per pane it would reclaim — count those lines as `<n>`. Then run the same command **without** `--list` to perform the reclaim, and emit `PROGRESS: phase-batch-cleanup panes=<n>` with that count at the batch boundary. Call both passes after collecting results and before the next dispatch so no in-flight worker pane is caught. This `tmux kill-pane`s the harness teammate panes; `shutdown_request` alone only idles the agent and never frees the pane, so it stays part of the run-end sequence for roster/token hygiene. `<RUN_DIR>` is the current (or just-finished) run's directory; its recorded `state/lead-pane.id` scopes the lead's session and the lead pane is never killed. In a non-tmux session there are no panes and the script is a silent no-op.
+Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate, in two passes. First count: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH> --dry-run` closes nothing and prints one `<paneId>\t<kind>` line per pane it would close — count those lines as `<n>`. Then run the same command **without** `--dry-run` to close them, and emit `PROGRESS: phase-batch-cleanup panes=<n>` with that count at the batch boundary. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. `shutdown_request` alone only idles the agent and frees no pane, so it stays part of the run-end sequence for roster/token hygiene. A `cli-wrapper` run holds no pane at all, so `<n>` is `0` — still emit the checkpoint.
 
-Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same reclaim first: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` to count the panes, then the same command without `--list` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `trace-cleanup` call is what actually closes it. This keeps a user gate from being shown while finished worker panes remain; in-flight workers and an in-flight report writer are preserved.
+Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same two passes first: `okstra team reclaim … --dry-run` to count the panes, then the same command without `--dry-run` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `team reclaim` call is what closes it. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes.
 
 Build the `okstra render-bundle` invocation from `outcome.renderArgv`, passing every token verbatim and in order (including empty strings — they are intentional `use phase default` markers).
 
@@ -359,7 +359,7 @@ Queue = the topologically-sorted stage list from splitting `orchestration.chainS
 
 1. Call Step 5's `render-bundle` with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand). Step 5's blocking local conformance waiver offer·concurrent-run detection·git-reconcile gates apply identically to each stage's `render-bundle`.
 2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead post-stage persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` (per the implementation profile directive).
-3. After confirming that `done` row was written, reclaim the completed teammate panes of the stage you just finished: run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<the run dir of the stage you just completed>"` (add `--keep report-writer-worker` if the report writer is still in flight). Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — reclaim the panes the same way, then stop the queue per "Stage ended FAIL" above.
+3. After confirming that `done` row was written, close the panes of the stage you just finished: run `okstra team teardown --project-root <projectRoot> --run-manifest <that stage's RUN_MANIFEST_PATH>`. That stage's run is over, so this is the run-end command rather than the round-boundary one. Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — close the panes the same way, then stop the queue per "Stage ended FAIL" above.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion to the user.

package/runtime/templates/reports/html/base.template.html

@@ -121,8 +121,7 @@
     "seq": runMeta.seq,
     "source-report": runMeta.source_report,
     "source-data": sourceData,
-    "source-data-sha256": dataSha256,
-    "source-md-sha256": markdownSha256
+    "source-data-sha256": dataSha256
   } | tojson }}</script>
   <script>{{ js | safe }}</script>
 </body>

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

@@ -239,6 +239,10 @@
     "final-verification": {
       "verification-verdict": "Verification verdict",
       "result-per-requirement": "Result per requirement",
+      "what-the-change-added": "What the change added",
+      "traced-to": "Serves",
+      "callers": "Callers",
+      "the-change-added-no-new-surface": "The change added no new identifier, module, or configuration entry.",
       "what-blocks-acceptance": "What blocks acceptance",
       "nothing-is-holding-acceptance": "Nothing is holding acceptance.",
       "residual-risk": "Residual risk",

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

@@ -239,6 +239,10 @@
     "final-verification": {
       "verification-verdict": "검증 판정",
       "result-per-requirement": "요구사항별 결과",
+      "what-the-change-added": "이 변경이 추가한 것",
+      "traced-to": "봉사하는 요구사항",
+      "callers": "호출자",
+      "the-change-added-no-new-surface": "이 변경이 새로 추가한 식별자·모듈·설정 항목은 없습니다.",
       "what-blocks-acceptance": "수용을 막는 것",
       "nothing-is-holding-acceptance": "수용을 막는 것이 없습니다.",
       "residual-risk": "남은 위험",

package/runtime/templates/reports/html/tasks/final-verification.template.html

@@ -5,7 +5,7 @@
 {% block human_content %}
 <section data-report-section="verification-verdict">
   <h2>{{ t('tasks.final-verification.verification-verdict') }}</h2>
-  <p><span class="status status-{{ verdict.verdictToken }}">{{ verdict.verdictToken }}</span></p>
+  <p><span class="status status-{{ verdictToken }}">{{ verdictToken }}</span></p>
   {{ render_narrative(narrative.verdictExplanation, "finalVerification.userNarrative.verdictExplanation") }}
 </section>
 
@@ -15,6 +15,12 @@
   {{ figure(coverageFigure, anchor_nodes=true) }}
 </section>
 
+<section data-report-section="added-surface" data-report-field="finalVerification.addedSurfaceAudit">
+  <h2>{{ t('tasks.final-verification.what-the-change-added') }}</h2>
+  <div class="table-scroll"><table><thead><tr><th>ID</th><th>{{ t('tasks.final-verification.what-the-change-added') }}</th><th>{{ t('tasks.final-verification.callers') }}</th><th>{{ t('tasks.final-verification.traced-to') }}</th><th>{{ t('tasks.final-verification.result-per-requirement') }}</th></tr></thead>
+  <tbody>{% for row in final.addedSurfaceAudit %}<tr id="id-{{ row.id }}"><td>{{ row.id }}</td><td>{{ row.surface | inline_code }}</td><td>{{ row.callers | inline_code }}</td><td>{{ row.requirement | inline_code }}</td><td><span class="status status-{{ row.disposition }}">{{ row.disposition }}</span> {{ row.note | inline_code }}</td></tr>{% else %}<tr><td colspan="5">{{ t('tasks.final-verification.the-change-added-no-new-surface') }}</td></tr>{% endfor %}</tbody></table></div>
+</section>
+
 <section data-report-section="blockers" data-report-field="finalVerification.acceptanceBlockers">
   <h2>{{ t('tasks.final-verification.what-blocks-acceptance') }}</h2>
   {{ render_narrative(narrative.blockerExplanation, "finalVerification.userNarrative.blockerExplanation") }}

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

@@ -2,20 +2,26 @@
 """Validate the self-contained HTML view produced by Phase 7 step 1.5
 (``scripts/okstra-render-report-views.py``).
 
-Checks, for a given final-report MD path:
-  1. ``*.html`` sibling exists when the report has clarification rows,
-     an analysis-review contract, or a plan-approval contract.
-  2. HTML's ``source-sha256`` in run-meta matches the current MD body —
-     stale html detection.
-  3. HTML's §5.6 / §5.7 / §5.8 deliverable regions contain no
-     ``<textarea>`` / ``<input>`` / ``<select>`` (form-attach is
-     restricted to §1 clarification rows).
-  4. HTML has no external URLs in ``<script src=>`` / ``<link href=>`` /
-     ``<img src=>`` — self-contained guarantee.
-  5. Every Response ID in HTML matches the §1 Clarification Items table
-     of the source MD (1:1).
-  6. Analysis reports contain all three Analysis Review decisions and an
-     affected-ID selector exactly matching the structured IDs in data.json.
+Takes the report's Markdown path as its handle and branches on schema.
+
+A schema-v2 report is checked against its ``.data.json`` — the record the
+HTML was rendered from — and never against the Markdown sibling, which is a
+second rendering of that same record:
+  1. the ``*.html`` sibling exists;
+  2. the document carries the task type's own template;
+  3. every human field the task type requires is present, and no audit field
+     leaked into the human main;
+  4. each visualization's svg node ids match its fallback ids;
+  5. the Response IDs in the HTML match ``clarificationItems[]`` 1:1;
+  6. no external URL appears in ``<script src=>`` / ``<link href=>`` /
+     ``<img src=>`` — the self-contained guarantee.
+
+A schema-v1 report keeps the Markdown as its source, so its checks read the
+§1 Clarification Items table (fail-closed when the heading is present but the
+table will not parse), require the HTML sibling only when the report carries
+clarification rows or an analysis-review / plan-approval contract, forbid form
+controls in the §5.6 / §5.7 / §5.8 deliverable regions, and enforce the same
+Response-ID parity and self-contained rules.
 
 Exit codes: 0 on success, 1 on any failure. Failures are printed one
 per line to stderr.
@@ -179,14 +185,21 @@ def _validate_analysis_review_html(
 
 
 def validate(report_path: Path) -> list[str]:
+    """Validate the html view of the report named by *report_path*.
+
+    A schema-v2 report is checked against its data.json and the rendered html;
+    the AI-handoff markdown is a sibling rendering of the same record and is
+    never read here, so it does not have to exist. Schema-v1 reports keep the
+    markdown as their source and still require it.
+    """
     failures: list[str] = []
+    v2 = _load_v2_data(report_path)
+    if v2 is not None:
+        return _validate_v2(report_path, v2[0], v2[1])
     if not report_path.is_file():
         return [f"final-report not found: {report_path}"]
 
     md = report_path.read_text(encoding="utf-8")
-    v2 = _load_v2_data(report_path)
-    if v2 is not None:
-        return _validate_v2(report_path, v2[0], v2[1])
     html_path = html_view_path(report_path)
     # §1 헤딩이 있는데 파싱이 실패하면 md_ids 가 빈 []이 되어 "clarification 없음
     # → skip" 으로 흘러 HTML form parity 게이트가 조용히 열린다. fail-closed.