okstra 0.166.1 → 0.166.2

package/docs/cli.md

@@ -130,7 +130,7 @@ For standard values and phase-specific responsibilities, see [Task type](#--task
   - `out-of-scope`: optional.
   - `candidate-cap`: 1–12; default 8.
 - Output: the `## 5.9 Improvement Candidates` table with 11 columns: Cand ID / Lens / Title / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence.
-- Verdict Token: `candidates-ready` / `no-candidates` / `blocked`.
+- Verdict Token: `analysis-complete` / `analysis-partial` / `blocked` — the shared analysis enum, which is what `schemas/final-report-v2.0.schema.json` admits. Finding no candidates is not a verdict: the run stays `analysis-complete` and records an empty candidate set with a `no-candidate` row per lens. (`candidates-ready` / `no-candidates` appear only in a schema-v1 legacy report's `## 7. Final Verdict`.)
 - Routing: there is no automatic spin-off. The user selects candidates and starts each under a new task ID with `requirements-discovery`, `implementation-planning`, or `error-analysis`.
 - Workers: claude + codex + antigravity + report-writer are all required.
 - Primary-pass assignment: selected analyser instances are enumerated in `requiredWorkerRoles` order, then the lead rotates the primary pass across the resolved priority lenses. Provider/model names do not affect the order, and every analyser still covers every resolved lens after its primary pass.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.166.1",
+  "version": "0.166.2",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.166.1",
-  "builtAt": "2026-08-11T12:28:22.915Z",
+  "package": "0.166.2",
+  "builtAt": "2026-08-11T13:40:27.396Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/improvement-discovery.md

@@ -54,7 +54,7 @@
   - v1 legacy branch: when validating or rerendering an existing schema-v1 report, preserve its `## 5.9 Improvement Candidates` table and legacy Markdown contract; do not rewrite that historical data into v2 implicitly.
   - the `## 5.9 Improvement Candidates` table populated with rows that obey the 11-column schema from `validators/validate_improvement_report.py` (Cand ID `I-NNN`, Lens from whitelist, Title, Scope ⊆ scan-scope, Severity, Effort, Consensus, Source workers `<worker>:<id>` from {claude, codex, antigravity}, Recommended next-phase ∈ {requirements-discovery, implementation-planning, error-analysis}, Expected behavior after, Evidence as path:line list). `Expected behavior after` states, in one observable sentence, what becomes different once the candidate is applied — it is the seed of the downstream brief's `EB-NNN` / `EO-NNN`. A candidate you cannot write this cell for is a preference, not a finding: drop it rather than filling the cell with a restatement of the title.
   - `Consensus` cells in `## 5.9 Improvement Candidates` use the table enum exactly: `full`, `partial`, `contested`, `worker-unique`. Map convergence's `full-consensus` / `partial-consensus` labels to `full` / `partial` before writing the table.
-  - `## 7. Final Verdict` Verdict Token ∈ {`candidates-ready`, `no-candidates`, `blocked`}; Direction `routing`; Next Step "ask the user to select K candidates (see the ## 5.9 table)"
+  - Verdict Token — **branch-specific, and the two branches do not share a vocabulary.** On the current v2 branch use the shared analysis enum: `analysis-complete` when every resolved lens was examined, `analysis-partial` when one could not be, `blocked` when the scan itself could not run. `schemas/final-report-v2.0.schema.json` admits only those three for `verdictCard.verdictToken` / `finalVerdict.verdictToken`, so a v2 report carrying `candidates-ready` fails Phase 7. **Finding no candidates is not a verdict**: it is an empty `candidates[]` plus a `lensCoverage[]` row per lens with `status: no-candidate` and its evidence-backed rationale — the verdict stays `analysis-complete`. `candidates-ready` / `no-candidates` belong to the v1 legacy `## 7. Final Verdict` Markdown alone, where `validators/validate_improvement_report.py` enforces them. Both branches: Direction `routing`; Next Step "ask the user to select K candidates (see the ## 5.9 table)".
   - `## 3. Recommended Next Steps` first entry summarises per-candidate routing and proposes new task-key names of the form `<task-group>/imp-<Cand-ID>`
   - author the shared schema-v2 report fields plus `improvementDiscovery.candidates[]`, `improvementDiscovery.lensCoverage[]`, `improvementDiscovery.selectionLimit`, and `improvementDiscovery.userNarrative` in data.json. `candidates[]` carries the same 11 logical fields described above; `lensCoverage[]` records either candidate IDs or an evidence-backed no-candidate rationale for every resolved lens. `schemas/final-report-v2.0.schema.json` and `validators/validate_improvement_report.py` enforce this contract. The renderers independently derive AI handoff Markdown and human HTML; never author a free-form report.
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -44,7 +44,13 @@ PROFILE_SECTIONS = (
     "Non-goals",
 )
 WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
+    # `Brief consumption` carries the reporter-confirmation rules — do not infer an
+    # unconfirmed `intent-check:` / `conversion-block:`, carry it forward as a
+    # blocker instead. Those bind the analysis worker, and the packet is the only
+    # profile text a worker receives, so a phase that omits the section ships a
+    # worker that can turn an unconfirmed intent into a settled requirement.
     "requirements-discovery": (
+        "Brief consumption",
         "Worker discovery procedure",
     ),
     "error-analysis": (
@@ -52,6 +58,7 @@ WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
         "Worker diagnosis procedure",
     ),
     "implementation-planning": (
+        "Brief consumption",
         "Worker planning procedure",
         "Pre-planning context exploration",
         "Design principles applied when scoring options",
@@ -60,7 +67,13 @@ WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
         "Worker verification procedure",
     ),
     "improvement-discovery": (
+        "Brief consumption",
         "Worker candidate procedure",
+        # Every analyser examines every resolved lens but leads with its own, and
+        # keeps duplicate / conflicting relations. Held only in the lead's profile,
+        # the workers converge on the same easy lens and the cross-check thins out
+        # while the aggregate still looks complete.
+        "Worker diversity rule",
     ),
 }
 CLARIFICATION_SECTIONS = (

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

@@ -726,9 +726,10 @@
       "type": "object",
       "description": "RENDER_IF taskType == release-handoff. §5.6 deliverables.",
       "required": [
-        "sourceVerificationReport",
+        "handoffScope",
         "featureBranchState",
         "userSelections",
+        "localCheckoutOutcome",
         "executedCommands",
         "commitList",
         "mergeConflictProbe",
@@ -737,6 +738,37 @@
         "userNarrative"
       ],
       "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "handoffScope": {
+                "properties": {
+                  "mode": {
+                    "const": "stage-group"
+                  }
+                },
+                "required": [
+                  "mode"
+                ]
+              }
+            },
+            "required": [
+              "handoffScope"
+            ]
+          },
+          "then": {
+            "required": [
+              "sourceVerificationReports"
+            ]
+          },
+          "else": {
+            "required": [
+              "sourceVerificationReport"
+            ]
+          }
+        }
+      ],
       "properties": {
         "handoffScope": {
           "type": "object",
@@ -761,11 +793,25 @@
             },
             "collectorBranch": {
               "type": "string"
+            },
+            "mergeCommits": {
+              "type": "array",
+              "description": "Assemble's merge commit SHAs, in the order the stages were merged into the collector branch. Without them the collector branch's contents cannot be traced back to the stages that produced them once the branch moves on.",
+              "items": {
+                "type": "string",
+                "minLength": 7
+              }
+            },
+            "dependencyClosureVerdict": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Whether the selected stages are closed under their dependencies, and on what basis. A stage-group PR that ships a stage without its predecessor is the failure this records."
             }
           }
         },
         "sourceVerificationReport": {
           "type": "object",
+          "description": "whole-task mode: the one final-verification report this handoff ships. Required unless handoffScope.mode is stage-group.",
           "required": [
             "path",
             "verdictTokenQuote"
@@ -782,6 +828,59 @@
             }
           }
         },
+        "sourceVerificationReports": {
+          "type": "array",
+          "description": "stage-group mode: one row per selected stage, because that handoff ships several verified stages and a single report path cannot say which stage each verdict belongs to.",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": [
+              "stage",
+              "path",
+              "verdictTokenQuote"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "stage": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "path": {
+                "type": "string",
+                "minLength": 1
+              },
+              "verdictTokenQuote": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "localCheckoutOutcome": {
+          "type": "object",
+          "description": "What the `local checkout` action did, including when it was not taken. `removedWorktree` is the command's own field: a non-empty path means the okstra worktree was removed, an empty string means it was already gone and the branch survived. Recording a removal that did not happen is the error this shape exists to prevent.",
+          "required": [
+            "status"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "status": {
+              "enum": [
+                "not-run",
+                "checked-out"
+              ]
+            },
+            "branch": {
+              "type": "string"
+            },
+            "mainWorktreePath": {
+              "type": "string"
+            },
+            "removedWorktree": {
+              "type": "string"
+            }
+          }
+        },
         "featureBranchState": {
           "type": "object",
           "required": [
@@ -835,7 +934,9 @@
               ]
             },
             "h3": {
+              "description": "The PR title/body confirmation. `not-run` when H1 was `local checkout` or `skip` — those routes never reach the question, and inventing an answer for a question that was never asked is the failure this value prevents.",
               "enum": [
+                "not-run",
                 "use as-is",
                 "edit then proceed",
                 "cancel"

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

@@ -544,13 +544,22 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 - Mode: `{{ releaseHandoff.handoffScope.mode | mdcell }}`
 {% if releaseHandoff.handoffScope.stages %}- Stages: {{ releaseHandoff.handoffScope.stages | join(', ') | mdcell }}
 {% endif %}{% if releaseHandoff.handoffScope.collectorBranch %}- Collector branch: `{{ releaseHandoff.handoffScope.collectorBranch | mdcell }}`
+{% endif %}{% if releaseHandoff.handoffScope.mergeCommits %}- Assemble merge commits: {{ releaseHandoff.handoffScope.mergeCommits | join(', ') | mdcell }}
+{% endif %}{% if releaseHandoff.handoffScope.dependencyClosureVerdict %}- Dependency closure: {{ releaseHandoff.handoffScope.dependencyClosureVerdict | mdcell }}
 {% endif %}
 {% endif %}
 ### 5.6.1 Source Verification Report
-
+{% if releaseHandoff.sourceVerificationReports %}
+| Stage | Report path (project-relative) | Quoted `Verdict Token` row |
+|-------|--------------------------------|----------------------------|
+{% for row in releaseHandoff.sourceVerificationReports -%}
+| {{ row.stage | mdcell }} | `{{ row.path | mdcell }}` | {{ row.verdictTokenQuote | mdcell }} |
+{% endfor %}
+{%- else %}
 - Path (project-relative): `{{ releaseHandoff.sourceVerificationReport.path }}`
 - Quoted `Verdict Token` row from that report's `## 7.` table:
   > {{ releaseHandoff.sourceVerificationReport.verdictTokenQuote | mdquote(2) }}
+{% endif %}
 
 ### 5.6.2 Feature Branch & Working-Tree State{% if t("releaseHandoff.branchStateAside") != "captured at run start" %} ({{ t("releaseHandoff.branchStateAside") }}){% endif %}
 
@@ -571,7 +580,7 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 {% endif %}
 | H2 | {{ t("releaseHandoff.h2Body") }} | `{{ (releaseHandoff.userSelections.h2 or t("releaseHandoff.h2DefaultLabel")) | mdcell }}` | {{ t("releaseHandoff.h2OptionsLabel") }} |
 | H2b | Merge conflict probe | `{{ (releaseHandoff.userSelections.h2b or releaseHandoff.mergeConflictProbe.kind) | mdcell }}` | `not-run` / `clean` / `proceed anyway` / `change base branch` / `cancel` |
-| H3 | {{ t("releaseHandoff.h3Body") }} | `{{ releaseHandoff.userSelections.h3 | mdcell }}` | `use as-is` / `edit then proceed` / `cancel` |
+| H3 | {{ t("releaseHandoff.h3Body") }} | `{{ releaseHandoff.userSelections.h3 | mdcell }}` | `not-run` / `use as-is` / `edit then proceed` / `cancel` |
 
 ### 5.6.4 Executed Commands
 
@@ -623,6 +632,12 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 {{ releaseHandoff.routingRecommendation }}
 
+### 5.6.9 Local Checkout Outcome
+
+- Status: `{{ releaseHandoff.localCheckoutOutcome.status | mdcell }}`
+{% if releaseHandoff.localCheckoutOutcome.status == 'checked-out' %}- Checked out `{{ releaseHandoff.localCheckoutOutcome.branch | mdcell }}` into `{{ releaseHandoff.localCheckoutOutcome.mainWorktreePath | mdcell }}`
+- okstra worktree: {% if releaseHandoff.localCheckoutOutcome.removedWorktree %}`{{ releaseHandoff.localCheckoutOutcome.removedWorktree | mdcell }}` removed{% else %}none removed — already torn down, so the branch survived{% endif %}
+{% endif %}
 {% endif %}
 {% if header.taskType == 'implementation' %}
 ## 5.7 Implementation Deliverables

package/runtime/templates/reports/html/tasks/release-handoff.template.html

@@ -39,7 +39,8 @@
   <h2>{{ t('tasks.release-handoff.commits-delivered') }}</h2>
   {% if handoff.commitList is mapping %}<p>{{ t('tasks.release-handoff.there-are-no-commits') }}</p>{% else %}
   <table><thead><tr><th>{{ t('tasks.release-handoff.commit') }}</th><th>{{ t('tasks.release-handoff.subject') }}</th><th>{{ t('tasks.release-handoff.files') }}</th></tr></thead><tbody>{% for row in handoff.commitList %}<tr>{{ row_key(pairs=[("SHA", row.shortSha), ("Order", loop.index)]) }}<td>{{ row.subject | inline_code }}</td><td>{% for file in row.files %}<code>{{ file }}</code>{% if not loop.last %} {% endif %}{% endfor %}</td></tr>{% endfor %}</tbody></table>{% endif %}
-  <p data-report-field="releaseHandoff.sourceVerificationReport"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong> — <code>{{ handoff.sourceVerificationReport.path }}</code> · {{ handoff.sourceVerificationReport.verdictTokenQuote | inline_code }}</p>
+  {% if handoff.sourceVerificationReports %}<p data-report-field="releaseHandoff.sourceVerificationReports"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong>{% for row in handoff.sourceVerificationReports %} — stage {{ row.stage }}: <code>{{ row.path }}</code> · {{ row.verdictTokenQuote | inline_code }}{% endfor %}</p>
+  {% else %}<p data-report-field="releaseHandoff.sourceVerificationReport"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong> — <code>{{ handoff.sourceVerificationReport.path }}</code> · {{ handoff.sourceVerificationReport.verdictTokenQuote | inline_code }}</p>{% endif %}
 </section>
 
 <section data-report-section="next-action">