okstra 0.128.0 → 0.129.1

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -5,6 +5,12 @@ from pathlib import Path
 from typing import Any, Mapping
 
 from .paths import okstra_home
+from .worker_prompt_policy import (
+    PromptPlan,
+    WORKER_ERROR_CONTRACT_FILENAME,
+    WORKER_PREAMBLE_FILENAME_BY_AUDIENCE,
+    resolve_prompt_plan_for_manifest,
+)
 
 
 class WorkerPromptHeaderError(Exception):
@@ -36,30 +42,42 @@ def worker_prompt_headers(
     prompt_rel: str,
     result_rel: str,
     worker_id: str,
+    dispatch_kind: str,
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
 ) -> list[str]:
     """Render the team-contract worker prompt anchor headers."""
     prompt_path = _resolve_project_path(project_root, prompt_rel)
+    errors_log_path = _errors_log_path(project_root, manifest, active_context)
+    errors_sidecar_path = _worker_errors_sidecar_path(
+        project_root,
+        manifest,
+        active_context,
+        worker_id,
+    )
+    plan = _prompt_plan(manifest, worker_id, dispatch_kind)
     headers = [
         f"**Project Root:** {project_root}",
         f"**Prompt History Path:** {prompt_rel}",
         f"**Result Path:** {result_rel}",
         f"Assigned worker prompt history path: {prompt_path}",
-        f"**Worker Preamble Path:** {_worker_preamble_path()}",
+        f"**Worker Preamble Path:** {_worker_preamble_path(plan, active_context)}",
+        f"**Worker Error Contract Path:** {_worker_error_contract_path(active_context)}",
     ]
-    if _string_value(manifest.get("taskType")) == "implementation":
+    if plan.allow_coding_preflight:
         headers.append(
             f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}"
         )
     headers.extend([
-        f"**Errors log path:** {_errors_log_path(project_root, manifest, active_context)}",
-        (
-            f"**Errors sidecar path:** "
-            f"{_worker_errors_sidecar_path(project_root, manifest, active_context, worker_id)}"
-        ),
+        f"**Errors log path:** {errors_log_path}",
+        f"**Errors sidecar path:** {errors_sidecar_path}",
         READ_SCOPE_HEADER,
     ])
+    if _string_value(manifest.get("taskType")) == "improvement-discovery":
+        headers.append(
+            f"**Phase 1.5 Grilling Log:** "
+            f"{_improvement_grilling_log_path(project_root, manifest)}"
+        )
     if _string_value(manifest.get("taskType")) == "final-verification":
         headers.extend(_final_verification_target_headers(active_context))
     return headers
@@ -86,8 +104,31 @@ def _final_verification_target_headers(
     ]
 
 
-def _worker_preamble_path() -> Path:
-    return okstra_home() / "templates" / "worker-prompt-preamble.md"
+def _worker_preamble_path(
+    plan: PromptPlan,
+    active_context: Mapping[str, Any],
+) -> Path:
+    runtime_resources = active_context.get("runtimeResources")
+    if isinstance(runtime_resources, Mapping):
+        paths = runtime_resources.get("workerPreamblePathByAudience")
+        if isinstance(paths, Mapping):
+            value = _string_value(paths.get(plan.audience))
+            if value:
+                return Path(value)
+    filename = WORKER_PREAMBLE_FILENAME_BY_AUDIENCE.get(
+        plan.audience,
+        WORKER_PREAMBLE_FILENAME_BY_AUDIENCE["analysis"],
+    )
+    return okstra_home() / "templates" / filename
+
+
+def _worker_error_contract_path(active_context: Mapping[str, Any]) -> Path:
+    runtime_resources = active_context.get("runtimeResources")
+    if isinstance(runtime_resources, Mapping):
+        value = _string_value(runtime_resources.get("workerErrorContractPath"))
+        if value:
+            return Path(value)
+    return okstra_home() / "templates" / WORKER_ERROR_CONTRACT_FILENAME
 
 
 def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
@@ -99,6 +140,35 @@ def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
     return okstra_home() / "prompts" / "coding-preflight"
 
 
+def _prompt_plan(
+    manifest: Mapping[str, Any],
+    worker_id: str,
+    dispatch_kind: str,
+) -> PromptPlan:
+    try:
+        return resolve_prompt_plan_for_manifest(
+            manifest=manifest,
+            worker_id=worker_id,
+            dispatch_kind=dispatch_kind,
+        )
+    except ValueError as exc:
+        raise WorkerPromptHeaderError(str(exc)) from exc
+
+
+def _improvement_grilling_log_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+) -> Path:
+    path = (
+        _run_directory_path(project_root, manifest)
+        / "state"
+        / "phase-1.5-grilling.md"
+    )
+    if not path.is_file():
+        raise WorkerPromptHeaderError(f"Phase 1.5 grilling log not found: {path}")
+    return path
+
+
 def _errors_log_path(
     project_root: Path,
     manifest: Mapping[str, Any],

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -0,0 +1,158 @@
+"""Resolve worker prompt requirements from functional audience."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Mapping
+
+
+PromptAudience = Literal[
+    "analysis",
+    "implementation-executor",
+    "implementation-verifier",
+    "report-writer",
+    "reverify",
+    "lead-only",
+]
+
+FINAL_VERIFICATION_HEADERS = (
+    "**Worktree:**",
+    "**Verification scope:**",
+    "**Verification base ref:**",
+    "**Verification head ref:**",
+    "**Verification target path:**",
+    "**Verification target digest:**",
+)
+SUPPORTED_TASK_TYPES = frozenset({
+    "requirements-discovery",
+    "error-analysis",
+    "implementation-planning",
+    "improvement-discovery",
+    "implementation",
+    "final-verification",
+    "release-handoff",
+})
+WORKER_PREAMBLE_FILENAME_BY_AUDIENCE = {
+    "analysis": "worker-prompt-preamble.md",
+    "implementation-executor": "implementation-worker-preamble.md",
+    "implementation-verifier": "implementation-worker-preamble.md",
+    "report-writer": "report-writer-prompt-preamble.md",
+}
+WORKER_ERROR_CONTRACT_FILENAME = "worker-error-contract.md"
+
+
+@dataclass(frozen=True)
+class PromptPlan:
+    audience: PromptAudience
+    equality_group: str | None
+    packet_only: bool
+    allow_coding_preflight: bool
+    required_headers: tuple[str, ...]
+    max_body_lines: int | None
+    max_directive_lines: int | None
+
+
+def resolve_prompt_plan(
+    *,
+    task_type: str,
+    worker_id: str,
+    executor_worker_id: str | None,
+    dispatch_kind: str,
+) -> PromptPlan:
+    """Resolve prompt policy without consulting provider or model identity."""
+    if task_type not in SUPPORTED_TASK_TYPES:
+        raise ValueError(f"unsupported task type: {task_type}")
+    if task_type == "release-handoff":
+        return _plan("lead-only")
+    if not worker_id.strip():
+        raise ValueError("worker ID is required")
+    if dispatch_kind.startswith("reverify-r"):
+        return _plan("reverify")
+    if task_type == "implementation" and not executor_worker_id:
+        raise ValueError("implementation executor worker ID is required")
+    if worker_id == "report-writer":
+        return _plan("report-writer")
+    if task_type == "implementation" and worker_id == executor_worker_id:
+        return _plan(
+            "implementation-executor",
+            allow_coding_preflight=True,
+            required_headers=("**Worktree:**",),
+        )
+    if task_type == "implementation":
+        return _plan(
+            "implementation-verifier",
+            equality_group="implementation-verifier-core",
+            allow_coding_preflight=True,
+            required_headers=("**Worktree:**",),
+        )
+    if task_type == "final-verification":
+        return _plan(
+            "analysis",
+            equality_group="analysis-core",
+            packet_only=True,
+            required_headers=FINAL_VERIFICATION_HEADERS,
+            max_body_lines=96,
+            max_directive_lines=40,
+        )
+    if task_type == "improvement-discovery":
+        return _plan(
+            "analysis",
+            equality_group="analysis-core",
+            packet_only=True,
+            required_headers=("**Phase 1.5 Grilling Log:**",),
+        )
+    return _plan("analysis", equality_group="analysis-core", packet_only=True)
+
+
+def resolve_prompt_plan_for_manifest(
+    *,
+    manifest: Mapping[str, Any],
+    worker_id: str,
+    dispatch_kind: str,
+) -> PromptPlan:
+    """Resolve policy from canonical task and executor manifest fields."""
+    task_type = _required_string(manifest, "taskType")
+    return resolve_prompt_plan(
+        task_type=task_type,
+        worker_id=worker_id,
+        executor_worker_id=_executor_worker_id(manifest),
+        dispatch_kind=dispatch_kind,
+    )
+
+
+def _plan(
+    audience: PromptAudience,
+    *,
+    equality_group: str | None = None,
+    packet_only: bool = False,
+    allow_coding_preflight: bool = False,
+    required_headers: tuple[str, ...] = (),
+    max_body_lines: int | None = None,
+    max_directive_lines: int | None = None,
+) -> PromptPlan:
+    return PromptPlan(
+        audience=audience,
+        equality_group=equality_group,
+        packet_only=packet_only,
+        allow_coding_preflight=allow_coding_preflight,
+        required_headers=required_headers,
+        max_body_lines=max_body_lines,
+        max_directive_lines=max_directive_lines,
+    )
+
+
+def _executor_worker_id(manifest: Mapping[str, Any]) -> str | None:
+    team_contract = manifest.get("teamContract")
+    if not isinstance(team_contract, Mapping):
+        return None
+    executor = team_contract.get("executor")
+    if not isinstance(executor, Mapping):
+        return None
+    provider = executor.get("provider")
+    return provider.strip() if isinstance(provider, str) and provider.strip() else None
+
+
+def _required_string(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"missing required string field: {key}")
+    return value.strip()

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

@@ -0,0 +1,51 @@
+# Implementation Worker Prompt Preamble (canonical)
+
+This file is shared by the `implementation-executor` and `implementation-verifier` audiences. Read it end-to-end, then read the role sidecar enumerated by the prompt. Before work, also read the shared file named by `**Worker Error Contract Path:**`; error rules live only there.
+
+## Operating standard (read before any output)
+
+Work like a senior engineer who owns this result, not a commentator on it.
+- Evidence over assertion — back every claim with a file:line, or mark it an explicit assumption. Never state the unverified as fact.
+- Read before you reason — read each required input end to end; when you lack basis, write "insufficient evidence" instead of filling the gap plausibly.
+- Shortest sound path — chase the most likely cause first; don't re-verify what is settled or pad with restatement.
+- Decide, don't survey — when options exist, give the trade-off and one recommendation, not an exhaustive list.
+- Fit what's here — match the surrounding code and prose; size the response to the request.
+- Hold your own line — reason from your independent angle; do not drift toward the other workers' likely answers or echo the user. Triangulation fails if your view isn't genuinely yours.
+
+## Required reading
+
+- Read the implementation role sidecar named by the prompt end-to-end. The executor sidecar owns mutation behavior; the verifier sidecar owns read-only review behavior.
+- Read `overview.md` and `clean-code.md` under `**Coding preflight pack:**`, then follow every matching language, framework, and architecture route before editing or verification.
+- Read the approved implementation deliverable and any effective design-preparation block enumerated by the prompt.
+
+## Worktree and command discipline
+
+- `**Worktree:**` is the canonical checkout. Project commands run with that directory as cwd.
+- `.okstra/**` artifacts remain anchored at `**Project Root:**`; the worktree may not contain them.
+- Only the executor may mutate source files. Verifiers remain read-only except for okstra result/audit artifacts and project-declared QA commands.
+- Execute the role sidecar's pre-write, post-write, QA, and return gates without substituting analysis Sections 1–6 or report-authoring instructions.
+
+## Anchor headers
+
+Every initial implementation prompt begins with these generated common anchors in this exact order, before its implementation-specific body:
+
+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>`
+6. `**Worker Error Contract Path:** <absolute-path>`
+7. `**Coding preflight pack:** <absolute-path>`
+8. `**Errors log path:** <absolute-path>`
+9. `**Errors sidecar path:** <absolute-path>`
+10. `**Read scope:** <allowlist>`
+
+The implementation body additionally carries `**Worktree:**` and its role-sidecar inputs. Do not synthesize any missing path.
+
+## Return message to the lead
+
+Begin the inline return with the exact `**Model:** <Role>, <modelExecutionValue>` line from the prompt, followed by the role-sidecar status summary. Never invent or abbreviate the model.
+
+## Writing style
+
+Use concise evidence-backed prose. Keep identifiers, paths, symbols, model names, CLI flags, and status tokens in English. Translate meaning rather than dictionary words.

package/runtime/templates/operating-standard.md

@@ -1,10 +1,10 @@
 # Operating Standard (canonical)
 
 This file is the single source of truth for the operating standard injected into
-every okstra agent. The "Common core" block below is inlined verbatim into
-`templates/worker-prompt-preamble.md` (workers) and
-`prompts/lead/okstra-lead-contract.md` (lead). A unit test asserts both inlined
-copies match this core — update all three together.
+every okstra agent. The "Common core" block below is inlined verbatim into the
+three audience preambles under `templates/` and
+`prompts/lead/okstra-lead-contract.md` (lead). A unit test asserts every inlined
+copy matches this core — update all copies together.
 
 ## Common core
 

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

@@ -0,0 +1,37 @@
+# Report Writer Prompt Preamble (canonical)
+
+This file is the audience-specific contract for `report-writer`. Read it end-to-end. Before work, also read the shared file named by `**Worker Error Contract Path:**`; error rules live only there.
+
+## Operating standard (read before any output)
+
+Work like a senior engineer who owns this result, not a commentator on it.
+- Evidence over assertion — back every claim with a file:line, or mark it an explicit assumption. Never state the unverified as fact.
+- Read before you reason — read each required input end to end; when you lack basis, write "insufficient evidence" instead of filling the gap plausibly.
+- Shortest sound path — chase the most likely cause first; don't re-verify what is settled or pad with restatement.
+- Decide, don't survey — when options exist, give the trade-off and one recommendation, not an exhaustive list.
+- Fit what's here — match the surrounding code and prose; size the response to the request.
+
+## Required reading
+
+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:**`.
+
+## Report authoring handoff
+
+- Author the data.json at `**Result Path:**` and the audit file at `**Worker Result 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:**`.
+
+## Return message to the lead
+
+Begin the inline return with the exact `**Model:** Report writer worker, <modelExecutionValue>` line from the prompt, followed by the artifact status. Never invent or abbreviate the model.
+
+## Writing style
+
+Use concise reader-facing prose and honor the report language. Keep identifiers, paths, symbols, model names, CLI flags, and status tokens in English. Translate meaning rather than dictionary words.

package/runtime/templates/worker-error-contract.md

@@ -0,0 +1,46 @@
+# Worker Error Contract (canonical)
+
+This audience-neutral file is the single source of truth for every initial worker's error path, sidecar schema, and write protocol. Read it end-to-end from `**Worker Error Contract Path:**` before work.
+
+## Error reporting
+
+Record a tool call only when its failure blocked the step you intended. A non-zero exit code is NOT by itself a failure to record. Do not record an entry when:
+
+- a search/probe exits non-zero solely because it found no matches and work proceeds unaffected;
+- an optional / expected-absent path is absent and detecting absence was the purpose;
+- output was truncated but a later read covered the content end-to-end.
+
+If the non-zero exit changed nothing about what you could do next, it is normal. When in doubt, record the real blocker: under-recording a real blocker is worse than one noisy entry.
+
+If the sidecar does not exist when a real failure occurs, create `{"schemaVersion": 1, "errors": []}` and append one entry.
+
+### Entry schema
+
+```json
+{
+  "ts": "<ISO 8601 UTC>",
+  "phase": "<current okstra phase>",
+  "errorType": "tool-failure",
+  "command": "<failed command/tool signature>",
+  "commandKind": "bash | tool:Read | tool:Edit | mcp | ...",
+  "exitCode": null,
+  "durationMs": null,
+  "message": "<one-line human summary>",
+  "stderrExcerpt": null,
+  "context": null
+}
+```
+
+### Rules
+
+- Do not add `source`, `recordedAt`, `agent`, `agentRole`, `model`, or `taskKey`; the lead supplies them when merging the sidecar.
+- The sidecar accepts only `errorType: "tool-failure"`. CLI wrappers write `cli-failure` directly to the run log; the lead records `contract-violation`.
+- Continue after recording unless the failure makes the task impossible.
+
+### Path extraction (BLOCKING)
+
+Extract `**Errors log path:**` and `**Errors sidecar path:**` verbatim from the dispatch prompt. If either is absent, return the worker-specific `<SENTINEL_PREFIX>_ERRORS_PATH_MISSING` sentinel and stop. Never synthesize a path from a run-directory pattern.
+
+## Path anchoring
+
+Every `.okstra/...` path is anchored at `**Project Root:**`, never at cwd. A task or stage worktree does **not** contain the project's `.okstra/` directory. Mutating project commands may use `**Worktree:**`, but okstra artifact reads and error writes use absolute paths resolved from Project Root. If a relative read fails in a worktree, re-anchor it to `<Project Root>` instead of retrying the same path.