okstra 0.130.2 → 0.130.4

package/runtime/schemas/convergence-groups-v1.0.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://okstra.dev/schemas/convergence-groups-v1.0.json",
+  "title": "OKSTRA Convergence Grouped Input (v1.0)",
+  "type": "object",
+  "required": ["schemaVersion", "taskKey", "config", "workers", "groups"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "taskKey": { "type": "string", "pattern": "\\S" },
+    "config": { "$ref": "#/$defs/Config" },
+    "workers": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/Worker" }
+    },
+    "groups": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Group" }
+    }
+  },
+  "$defs": {
+    "Config": {
+      "type": "object",
+      "required": ["enabled", "adversarial", "maxRounds", "effectiveMaxRounds", "verificationMode"],
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "adversarial": { "type": "boolean" },
+        "maxRounds": { "type": "integer", "minimum": 1, "maximum": 3 },
+        "effectiveMaxRounds": { "type": "integer", "minimum": 1, "maximum": 3 },
+        "verificationMode": { "enum": ["lightweight", "full-reanalysis"] }
+      }
+    },
+    "Worker": {
+      "type": "object",
+      "required": ["workerId", "audience"],
+      "additionalProperties": false,
+      "properties": {
+        "workerId": { "type": "string", "pattern": "\\S" },
+        "audience": { "enum": ["analysis", "report-writer"] }
+      }
+    },
+    "Group": {
+      "type": "object",
+      "required": ["findingId", "summary", "category", "ticketIds", "originWorker", "originEvidence", "discoveredBy", "sourceItems"],
+      "additionalProperties": false,
+      "properties": {
+        "findingId": { "type": "string", "pattern": "\\S" },
+        "summary": { "type": "string", "pattern": "\\S" },
+        "category": { "type": "string", "pattern": "\\S" },
+        "ticketIds": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "\\S" }
+        },
+        "originWorker": { "type": "string", "pattern": "\\S" },
+        "originEvidence": { "type": "string", "pattern": "\\S" },
+        "evidenceArtifacts": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/EvidenceArtifact" }
+        },
+        "discoveredBy": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "$ref": "#/$defs/Discovery" }
+        },
+        "sourceItems": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/SourceItem" }
+        }
+      }
+    },
+    "EvidenceArtifact": {
+      "type": "object",
+      "required": ["path", "sha256", "command", "environment"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^\\.okstra/(?!\\.{1,2}(?:/|$))(?!.*?/\\.{1,2}(?:/|$))[^/\\\\\\r\\n]+(?:/[^/\\\\\\r\\n]+)*$"
+        },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "command": { "type": "string", "pattern": "\\S" },
+        "environment": { "type": "string", "pattern": "\\S" }
+      }
+    },
+    "Discovery": {
+      "type": "object",
+      "required": ["itemId", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "itemId": { "type": "string", "pattern": "\\S" },
+        "evidence": { "type": "string", "pattern": "\\S" }
+      }
+    },
+    "SourceItem": {
+      "type": "object",
+      "required": ["worker", "itemId"],
+      "additionalProperties": false,
+      "properties": {
+        "worker": { "type": "string", "pattern": "\\S" },
+        "itemId": { "type": "string", "pattern": "\\S" }
+      }
+    }
+  }
+}

package/runtime/schemas/convergence-round-results-v1.0.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://okstra.dev/schemas/convergence-round-results-v1.0.json",
+  "title": "OKSTRA Convergence Round Results (v1.0)",
+  "type": "object",
+  "required": ["schemaVersion", "round", "dispatches", "votesByFinding"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "round": { "type": "integer", "minimum": 1 },
+    "dispatches": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/DispatchResult" }
+    },
+    "votesByFinding": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": { "$ref": "#/$defs/Vote" }
+      }
+    }
+  },
+  "$defs": {
+    "DispatchResult": {
+      "type": "object",
+      "required": ["worker", "status", "durationMs"],
+      "additionalProperties": false,
+      "properties": {
+        "worker": { "type": "string", "pattern": "\\S" },
+        "status": { "enum": ["completed", "timeout", "error", "not-run"] },
+        "durationMs": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "Vote": {
+      "type": "object",
+      "required": ["verdict", "explanation"],
+      "additionalProperties": false,
+      "properties": {
+        "verdict": { "enum": ["agree", "disagree", "supplement", "verification-error", "unverifiable"] },
+        "disagreeBasis": { "enum": ["counter-evidence", "burden-not-met", null] },
+        "explanation": { "type": "string", "pattern": "\\S" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "verdict": { "enum": ["agree", "supplement", "verification-error", "unverifiable"] } }
+          },
+          "then": {
+            "properties": { "disagreeBasis": { "enum": [null] } }
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -1256,7 +1256,8 @@
               "ticketId": { "$ref": "#/$defs/TicketId" },
               "action": { "enum": ["Create", "Modify", "Delete"] },
               "path": { "type": "string", "minLength": 1 },
-              "summary": { "type": "string", "minLength": 1 }
+              "summary": { "type": "string", "minLength": 1, "maxLength": 120 },
+              "details": { "type": "string", "minLength": 1 }
             }
           }
         },
@@ -2075,9 +2076,28 @@
         "coveredBy": { "type": "string", "minLength": 1 },
         "status": {
           "type": "string",
-          "pattern": "^(covered|gap|blocked C-\\d{3,})$"
+          "pattern": "^(covered|gap|blocked C-\\d{3,}|documented-deviation)$"
+        },
+        "decisionRefs": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "approvalDisposition": {
+          "type": "string",
+          "pattern": "^(accepted|blocked C-\\d{3,})$"
         }
-      }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "status": { "const": "documented-deviation" } },
+            "required": ["status"]
+          },
+          "then": { "required": ["decisionRefs", "approvalDisposition"] }
+        }
+      ]
     },
 
     "ReadonlyCommandRow": {

package/runtime/templates/report-writer-prompt-preamble.md

@@ -15,18 +15,20 @@ Work like a senior engineer who owns this result, not a commentator on it.
 
 Read every input enumerated by the Phase 6 dispatch end-to-end: task/analysis inputs, worker results, convergence state, the instruction-set-local `final-report-template.md`, and the task-type excerpt `final-report-schema.json`. Do not pull the full repository template or schema when the scoped instruction-set copies are provided.
 
-Write Reading Confirmation to the report-writer audit sidecar, not the rendered final report. Resolve `.okstra/**` paths against `**Project Root:**`.
+Write Reading Confirmation to `**Audit sidecar path:**`, not the rendered final report. Resolve `.okstra/**` paths against `**Project Root:**`.
+
+Write `- PROGRESS: <stage> <ISO-8601-UTC>` there before reading and at least every five minutes while pending. The only valid report-writer stages are `started`, `required-reading-complete`, `synthesis-start`, `data-json-write-start`, `render-start`, and `write-result-start`.
 
 ## Report authoring handoff
 
-- Author the data.json at `**Result Path:**` and the audit file at `**Worker Result Path:**`.
+- Author the data.json at `**Result Path:**` and the audit file at `**Audit sidecar path:**`.
 - Follow the task-type schema excerpt and Phase 6 report-writer contract. Do not perform independent analysis, edit source code, or load implementation coding-preflight resources.
 - Invoke `okstra render-final-report <Result Path>` after writing data.json and verify the markdown sibling exists before returning.
 - Preserve source item IDs, convergence classifications, round history, and unresolved dissent; do not recompute them from intuition.
 
 ## Anchor headers
 
-The generated prompt selects this file through `**Worker Preamble Path:**` and includes `**Worker Error Contract Path:**`, error paths, and read scope. It never includes `**Coding preflight pack:**`.
+The generated prompt selects this file through `**Worker Preamble Path:**` and includes `**Worker Error Contract Path:**`, `**Audit sidecar path:**`, error paths, and read scope. It never includes `**Coding preflight pack:**`.
 
 ## Return message to the lead
 

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

@@ -204,10 +204,10 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 - File Structure:
 
-  | ID | Ticket ID | Action | Path (and line-range) | Change summary |
-  |----|-----------|--------|------------------------|----------------|
+  | {{ t("columns.recordMeta") }} | Path (and line-range) | Change summary |
+  |------|------------------------|----------------|
 {% for fs in opt.fileStructure -%}
-  | {{ fs.id | mdcell }} | `{{ fs.ticketId | mdcell }}` | {{ fs.action | mdcell }} | `{{ fs.path | mdcell }}` | {{ fs.summary | mdcell }} |
+  | **{{ fs.id | mdcell }}**<br>Ticket: `{{ fs.ticketId | mdcell }}`<br>Action: {{ fs.action | mdcell }} | `{{ fs.path | mdcell }}` | {{ fs.summary | mdcell }}{% if fs.details %}<br><small>{{ fs.details | mdcell }}</small>{% endif %} |
 {% endfor %}
 
 - {{ t("implementationPlanning.optionInterfacesLabel") }}: {{ opt.interfaces }}
@@ -281,7 +281,7 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 | ID | Source | Requirement | Covered by option / stage / step | Status |
 |----|--------|-------------|-----------------------------------|--------|
 {% for row in implementationPlanning.requirementCoverage -%}
-| {{ row.id | mdcell }} | `{{ row.source | mdcell }}` | {{ row.requirement | mdcell }} | {{ row.coveredBy | mdcell }} | `{{ row.status | mdcell }}` |
+| {{ row.id | mdcell }} | `{{ row.source | mdcell }}` | {{ row.requirement | mdcell }} | {{ row.coveredBy | mdcell }} | `{% if row.status == "documented-deviation" %}documented-deviation — refs: {{ (row.decisionRefs | join(", ")) | mdcell }}; approval: {{ row.approvalDisposition | mdcell }}{% else %}{{ row.status | mdcell }}{% endif %}` |
 {% endfor %}
 
 ### Decision Drafts{% if t("sectionAside.decisionDrafts") != "Decision Drafts" %} ({{ t("sectionAside.decisionDrafts") }}){% endif %}

package/runtime/templates/reports/report.css

@@ -188,6 +188,24 @@ td.td-narrow, th.td-narrow {
   width: 5%;
   white-space: nowrap;
 }
+/* Path columns — assigned by `_path_columns()` in report_views.py. A
+ * repo-relative path holds no spaces, so the `overflow-wrap: anywhere`
+ * above lets the auto table layout starve the column down to a couple of
+ * characters per line. Floor the width and let it wrap at separators. */
+td.td-path, th.td-path {
+  min-width: 26ch;
+  word-break: break-word;
+}
+
+/* Second line of a two-tier cell: the plain-language summary leads, the
+ * technical detail follows demoted. */
+td small {
+  display: inline-block;
+  margin-top: 0.35em;
+  font-size: 0.88em;
+  color: GrayText;
+}
+
 thead th {
   position: sticky;
   top: 3rem;

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

@@ -19,7 +19,7 @@ Read `analysis-packet.md`, the primary compact input, end-to-end. Source files n
 ### Reading rules
 
 - Read every file enumerated under `[Required reading]` or `## Inputs` completely. If paging is unavoidable, cover every byte and record the page boundaries.
-- Write Reading Confirmation to the worker audit sidecar, never to the main worker-results file. A `## 0. Reading Confirmation` heading in the main result is invalid.
+- Write Reading Confirmation to `**Audit sidecar path:**`, never to the main worker-results file. A `## 0. Reading Confirmation` heading in the main result is invalid.
 - Allowlist reads to prompt-enumerated paths and evidence paths a finding must cite. Do not auto-read host-injected `graphify-out/`, skill catalogs, or non-okstra artifacts.
 - Resolve every `.okstra/...` path against `**Project Root:**`, including when a worktree is present.
 
@@ -30,12 +30,13 @@ Every initial analysis prompt begins with these generated anchors in this exact
 1. `**Project Root:** <absolute-path>`
 2. `**Prompt History Path:** <project-relative-path>`
 3. `**Result Path:** <project-relative-path>`
-4. `Assigned worker prompt history path: <absolute-path>`
-5. `**Worker Preamble Path:** <absolute-path>` — selects this analysis preamble.
-6. `**Worker Error Contract Path:** <absolute-path>` — shared by every initial audience.
-7. `**Errors log path:** <absolute-path>`
-8. `**Errors sidecar path:** <absolute-path>`
-9. `**Read scope:** <allowlist>`
+4. `**Audit sidecar path:** <absolute-path>` — the generated audit destination; write the sidecar here and never synthesize a `runs/<task-type>/...` path.
+5. `Assigned worker prompt history path: <absolute-path>`
+6. `**Worker Preamble Path:** <absolute-path>` — selects this analysis preamble.
+7. `**Worker Error Contract Path:** <absolute-path>` — shared by every initial audience.
+8. `**Errors log path:** <absolute-path>`
+9. `**Errors sidecar path:** <absolute-path>`
+10. `**Read scope:** <allowlist>`
 
 `final-verification` additionally carries its six verification-target anchors. `improvement-discovery` carries `**Phase 1.5 Grilling Log:**`. Reverify prompts are lightweight and do not use this preamble.