okstra 0.128.0 → 0.129.1

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

@@ -14,6 +14,11 @@
   - before deciding whether to fan out, read `Related Task Graph`. Use `depends-on`, `blocks` / `blocked-by`, parent/child, follow-up, and split edges as seed ordering constraints. Do not flatten a directed graph into unrelated tasks.
   - `intent-inference` augmentations whose paired `intent-check:` row carries `[CONFIRMED …]` are treated as **confirmed**; trust the confirmation text in `## Reporter Confirmations` over the original inference if they differ. Unconfirmed `intent-inference` rows under `reporter-confirmations: skipped` follow the precondition's `skipped` branch above.
   - `conversion-block:` rows are explicit "translation failed" signals — never attempt to resolve them by inference here; the precondition above already handled them.
+- Worker discovery procedure:
+  - classify the request and cite the evidence that determines both its work category and safest next phase
+  - identify independently startable decomposition candidates without publishing or rendering fan-out artifacts; preserve every directed dependency from `Related Task Graph`
+  - resolve codebase-answerable ambiguity by inspection and record file:line evidence; return only human-owned decisions as clarification candidates with the evidence already checked
+  - state the reporter's rejection criteria, missing routing inputs, and the evidence boundary behind each recommendation
 - Primary focus areas:
   - classify the work as bugfix, feature, improvement, refactor, or ops
   - determine whether `error-analysis` or `implementation-planning` is the next safe step. Direct `implementation` handoff is never a valid routing target — implementation requires an approved `implementation-planning` report
@@ -49,7 +54,9 @@
   - evidence-backed routing decision
   - uncertainty boundaries and missing inputs
   - next recommended phase and safe resume guidance
-  - canonical-term resolution for every `terminology:*` brief item, written as a one-line `<term> = <definition>` line in a new `Domain Alignment` subsection of the final report; alongside each, propose whether `<PROJECT_ROOT>/.okstra/glossary.md` should be updated (proposal only — actual writes happen via `okstra-brief-gen` Step 4.5 on a subsequent run)
+  - canonical-term resolution for every `terminology:*` brief item as `<term> = <definition>`, plus whether `<PROJECT_ROOT>/.okstra/glossary.md` should be updated
+- Report assembly instructions:
+  - write canonical-term resolutions in a new `Domain Alignment` subsection of the final report; actual glossary writes happen via `okstra-brief-gen` Step 4.5 on a subsequent run
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if any blocking input is missing at the time of writing the final report, populate `## 1. Clarification Items` in `final-report-template.md` (a single unified table; `Blocks=next-phase` for items the next run cannot start without)
   - prefer concrete questions whose answers map directly to a routing decision (`bugfix` vs `feature`, `error-analysis` vs `implementation-planning`, etc.). State each option in plain language with one sentence describing what choosing it would mean for the next phase.

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -24,29 +24,23 @@ PROFILE_SECTIONS = (
     "Primary focus areas",
     "Expected output emphasis",
     "Non-goals",
-    "Clarification request policy",
 )
-PROFILE_SECTIONS_BY_TASK_TYPE = {
+WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
     "requirements-discovery": (
-        "Fan-out",
-        "Decision-tree walk",
+        "Worker discovery procedure",
     ),
     "error-analysis": (
-        "Diagnosis loop",
+        "Worker diagnosis procedure",
     ),
     "implementation-planning": (
-        "Section heading contract",
-        "Required deliverable shape",
-        "No-placeholder rule",
-        "Self-review pass before finalising the report",
+        "Worker planning procedure",
+        "Design principles applied when scoring options",
     ),
     "final-verification": (
         "Worker verification procedure",
     ),
     "improvement-discovery": (
-        "Phase 1.5 — Lead reflect-back grilling",
-        "Worker diversity rule",
-        "Decision-tree walk",
+        "Worker candidate procedure",
     ),
 }
 CLARIFICATION_SECTIONS = (
@@ -156,7 +150,7 @@ def _brief_block(brief_text: str) -> list[str]:
 def _profile_block(task_type: str, profile_text: str) -> list[str]:
     section_names = (
         PROFILE_SECTIONS
-        + PROFILE_SECTIONS_BY_TASK_TYPE.get(task_type, ())
+        + WORKER_PROFILE_SECTIONS_BY_TASK_TYPE.get(task_type, ())
     )
     profile_sections = _extract_sections(profile_text, section_names)
     profile_bullets = _extract_bullet_sections(profile_text, section_names)

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -24,10 +24,32 @@ from .final_report_paths import (
 )
 from .lead_events import LeadEvent, append_lead_event
 from .path_hints import hydrate_active_run_context
+from .report_finalize import (
+    STEP_VALIDATE_RUN,
+    FinalizeContext,
+    FinalizeError,
+    project_relative_path as _project_relative_path,
+    require_string as _require_string,
+    resolve_optional_path as _resolve_optional_path,
+    resolve_project_path as _resolve_project_path,
+    run_finalize,
+    run_seq as _run_seq,
+    string_value as _string_value,
+)
 from .wrapper_status import status_path_for_prompt
-from .paths import task_dir
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
-from .worker_prompt_contract import validate_final_verification_prompt_paths
+from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
+from .worker_prompt_body import (
+    analysis_input_lines as _analysis_input_lines,
+    analysis_prompt_body as _analysis_prompt_body,
+    existing_input_lines as _existing_input_lines,
+    instruction_path as _instruction_path,
+    mcp_pointer_line as _mcp_pointer_line,
+)
+from .worker_prompt_policy import (
+    PromptPlan,
+    resolve_prompt_plan_for_manifest,
+)
 
 
 SUPPORTED_CLI_WORKERS = {
@@ -39,10 +61,6 @@ BACKEND_MIXED = "mixed"
 MAX_WORKER_ATTEMPTS = 2
 REPORT_WRITER_WORKER_ID = "report-writer"
 REPORT_LANGUAGE_VALUES = {"en", "ko", "auto"}
-ANALYSIS_WORKER_LABELS = {
-    "codex": "Codex worker",
-    "antigravity": "Antigravity worker",
-}
 
 
 class DispatchError(Exception):
@@ -183,7 +201,7 @@ def build_dispatch_plan(
         )
         for worker_id in selected_workers
     )
-    _validate_initial_final_verification_prompts(manifest, workers)
+    _validate_initial_prompts(manifest, workers)
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root,
@@ -195,21 +213,18 @@ def build_dispatch_plan(
     )
 
 
-def _validate_initial_final_verification_prompts(
+def _validate_initial_prompts(
     manifest: Mapping[str, Any],
     workers: Sequence[WorkerDispatch],
 ) -> None:
-    if manifest.get("taskType") != "final-verification":
-        return
-    prompt_paths = {
-        worker.worker_id: worker.prompt_path
+    records = [
+        PromptRecord(worker.worker_id, "initial", worker.prompt_path)
         for worker in workers
-        if worker.worker_id != REPORT_WRITER_WORKER_ID
-        and "-reverify-r" not in worker.prompt_path.name
-    }
-    errors = validate_final_verification_prompt_paths(prompt_paths)
+    ]
+    errors = validate_initial_prompt_records(manifest=manifest, records=records)
     if errors:
-        raise DispatchError("final-verification prompt contract: " + "; ".join(errors))
+        task_type = _require_string(manifest, "taskType")
+        raise DispatchError(f"{task_type} prompt contract: " + "; ".join(errors))
 
 
 def dispatch_plan(plan: DispatchPlan) -> int:
@@ -344,8 +359,6 @@ def _worker_dispatch_record(
     }
 
 
-
-
 def main(argv: Sequence[str] | None = None) -> int:
     parser = _parser()
     args = parser.parse_args(argv)
@@ -367,7 +380,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         code = dispatch_plan(plan)
         _print_json({**plan.to_payload(dry_run=False), "exitCode": code})
         return code
-    except DispatchError as exc:
+    except (DispatchError, FinalizeError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
 
@@ -460,6 +473,7 @@ def _render_missing_analysis_worker_prompt(
     prompt_rel = _worker_prompt_path(manifest, worker_id)
     model = _require_string(worker_state, "modelExecutionValue")
     role = _analysis_pane_role(manifest, active_context, worker_id)
+    plan = _initial_prompt_plan(manifest, worker_id)
     lines = _base_prompt_headers(
         project_root=project_root,
         manifest=manifest,
@@ -469,7 +483,16 @@ def _render_missing_analysis_worker_prompt(
         result_rel=result_rel,
     )
     lines.extend(_worktree_headers(manifest, active_context, role))
-    lines.extend(_analysis_prompt_body(manifest, active_context, worker_id, model, role))
+    lines.extend(
+        _analysis_prompt_body(
+            manifest,
+            active_context,
+            worker_id,
+            model,
+            role,
+            plan,
+        )
+    )
     executor_tail = _implementation_executor_tail(
         manifest,
         active_context,
@@ -614,43 +637,6 @@ def _build_report_writer_dispatch(
     )
 
 
-def _analysis_prompt_body(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    worker_id: str,
-    model: str,
-    role: str,
-) -> list[str]:
-    label = ANALYSIS_WORKER_LABELS[worker_id]
-    return [
-        f"**Model:** {label}, {model}",
-        f"**Pane role:** {role}",
-        "",
-        f"# {label} Dispatch",
-        "",
-        "## Role",
-        (
-            f"You are the {label} for okstra cross-verification. "
-            "Produce an independent worker result."
-        ),
-        "",
-        "## Task",
-        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
-        f"- Task type: `{_require_string(manifest, 'taskType')}`",
-        "",
-        "## Inputs",
-        *_analysis_input_lines(manifest, active_context),
-        "",
-        _mcp_pointer_line(),
-        "",
-        "## Output Contract",
-        "- Read the Worker Preamble Path end-to-end before analysis.",
-        "- Write the worker result to Result Path and no other canonical result path.",
-        "- Write the audit sidecar and any tool-failure entries as the preamble requires.",
-        "- Cite evidence with file paths and line numbers whenever you make a claim.",
-    ]
-
-
 def _report_writer_prompt_body(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
@@ -688,13 +674,6 @@ def _report_writer_prompt_body(
     ]
 
 
-def _mcp_pointer_line() -> str:
-    return (
-        '**MCP servers:** follow the task brief\'s "## Available MCP Servers" '
-        "section (already in your Required reading)."
-    )
-
-
 def _base_prompt_headers(
     *,
     project_root: Path,
@@ -710,6 +689,7 @@ def _base_prompt_headers(
             prompt_rel=prompt_rel,
             result_rel=result_rel,
             worker_id=worker_id,
+            dispatch_kind="initial",
             manifest=manifest,
             active_context=active_context,
         )
@@ -717,26 +697,18 @@ def _base_prompt_headers(
         raise DispatchError(str(exc)) from exc
 
 
-def _analysis_input_lines(
+def _initial_prompt_plan(
     manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> list[str]:
-    if manifest.get("taskType") == "final-verification":
-        packet_path = _instruction_path(
-            manifest,
-            active_context,
-            "analysisPacketPath",
+    worker_id: str,
+) -> PromptPlan:
+    try:
+        return resolve_prompt_plan_for_manifest(
+            manifest=manifest,
+            worker_id=worker_id,
+            dispatch_kind="initial",
         )
-        return _existing_input_lines((("Primary analysis packet", packet_path),))
-    inputs = [
-        ("Primary analysis packet", _instruction_path(manifest, active_context, "analysisPacketPath")),
-        ("Task brief", _instruction_path(manifest, active_context, "taskBriefPath")),
-        ("Analysis profile", _instruction_path(manifest, active_context, "analysisProfilePath")),
-        ("Analysis material", _instruction_path(manifest, active_context, "analysisMaterialPath")),
-        ("Reference expectations", _instruction_path(manifest, active_context, "referenceExpectationsPath")),
-        ("Clarification response", _instruction_path(manifest, active_context, "clarificationResponsePath")),
-    ]
-    return _existing_input_lines(inputs)
+    except ValueError as exc:
+        raise DispatchError(str(exc)) from exc
 
 
 def _report_writer_input_lines(
@@ -759,11 +731,6 @@ def _report_writer_input_lines(
     return lines or ["- No report-writer inputs were recorded in active-run-context."]
 
 
-def _existing_input_lines(inputs: Sequence[tuple[str, str]]) -> list[str]:
-    lines = [f"- {label}: `{path}`" for label, path in inputs if path]
-    return lines or ["- No input paths were recorded in active-run-context."]
-
-
 def _analysis_worker_result_lines(team_state: Mapping[str, Any]) -> list[str]:
     lines = []
     workers = team_state.get("workers")
@@ -781,19 +748,6 @@ def _analysis_worker_result_lines(team_state: Mapping[str, Any]) -> list[str]:
     return lines
 
 
-def _instruction_path(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    key: str,
-) -> str:
-    instruction_set = active_context.get("instructionSet")
-    if isinstance(instruction_set, Mapping):
-        value = _string_value(instruction_set.get(key))
-        if value:
-            return value
-    return _string_value(manifest.get(key))
-
-
 def _analysis_pane_role(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
@@ -875,13 +829,6 @@ def _implementation_executor_tail(
     return "\n\n".join(parts)
 
 
-def _project_relative_path(project_root: Path, path: Path) -> str:
-    try:
-        return path.relative_to(project_root).as_posix()
-    except ValueError:
-        return str(path)
-
-
 def _resolve_report_language(
     project_root: Path,
     manifest: Mapping[str, Any],
@@ -930,12 +877,6 @@ def _infer_report_language(
     return "ko" if hangul_count >= 10 else "en"
 
 
-def _string_value(value: Any) -> str:
-    if not isinstance(value, str):
-        return ""
-    return value.strip()
-
-
 def _validate_codex_manifest(manifest: Mapping[str, Any], path: Path) -> None:
     if manifest.get("leadRuntime") != "codex":
         raise DispatchError(f"run manifest is not a Codex lead run: {path}")
@@ -1121,190 +1062,25 @@ def _post_process_report_writer_result(
 ) -> dict[str, Any]:
     if worker.worker_id != REPORT_WRITER_WORKER_ID:
         return {"ok": True, "reason": "", "steps": []}
-    steps = []
     try:
-        commands = _report_post_process_commands(plan, worker)
-    except DispatchError as exc:
-        return {"ok": False, "reason": str(exc), "steps": steps}
-    for name, command in commands:
-        if name == "validate-run":
-            _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
-        result = subprocess.run(
-            command,
-            cwd=plan.project_root,
-            text=True,
-            capture_output=True,
+        ctx = FinalizeContext.from_manifest(
+            project_root=plan.project_root,
+            workspace_root=plan.workspace_root,
+            manifest_path=plan.manifest_path,
+            team_state_path=plan.team_state_path,
+            data_path=worker.result_path,
+            manifest=plan.manifest,
         )
-        step = _post_process_step_payload(name, command, result)
-        steps.append(step)
-        if result.returncode != 0:
-            return {
-                "ok": False,
-                "reason": f"{name} failed with exit code {result.returncode}",
-                "steps": steps,
-            }
-    return {"ok": True, "reason": "", "steps": steps}
-
-
-def _report_post_process_commands(
-    plan: DispatchPlan,
-    worker: WorkerDispatch,
-) -> list[tuple[str, list[str]]]:
-    markdown_path = _final_report_markdown_path(worker.result_path)
-    commands = [
-        (
-            "token-usage",
-            [
-                sys.executable,
-                str(_resolve_workspace_script(plan.workspace_root, "okstra-token-usage.py")),
-                str(plan.team_state_path),
-                "--project-root",
-                str(plan.project_root),
-                "--write",
-                "--substitute-data",
-                str(worker.result_path),
-            ],
-        ),
-        (
-            "render-views",
-            [
-                sys.executable,
-                str(_resolve_workspace_script(plan.workspace_root, "okstra-render-report-views.py")),
-                str(markdown_path),
-                "--task-key",
-                _require_string(plan.manifest, "taskKey"),
-                "--task-type",
-                _require_string(plan.manifest, "taskType"),
-                "--seq",
-                _run_seq(plan.manifest),
-                "--source-report",
-                _project_relative_path(plan.project_root, markdown_path),
-            ],
-        ),
-        (
-            "spawn-followups",
-            [
-                sys.executable,
-                str(_resolve_workspace_script(plan.workspace_root, "okstra-spawn-followups.py")),
-                str(worker.result_path),
-                "--project-root",
-                str(plan.project_root),
-                "--task-group",
-                _task_group(plan.manifest),
-                "--parent-task-key",
-                _require_string(plan.manifest, "taskKey"),
-            ],
-        ),
-    ]
-    commands.append(("validate-run", _validate_run_command(plan, markdown_path)))
-    return commands
-
-
-def _validate_run_command(plan: DispatchPlan, markdown_path: Path) -> list[str]:
-    task_manifest_path = _task_manifest_path(plan.project_root, plan.manifest)
-    command = [
-        sys.executable,
-        str(_resolve_workspace_validator(plan.workspace_root, "validate-run.py")),
-        "--team-state",
-        str(plan.team_state_path),
-        "--report",
-        str(markdown_path),
-        "--run-manifest",
-        str(plan.manifest_path),
-        "--task-manifest",
-        str(task_manifest_path),
-    ]
-    final_status_path = _resolve_optional_path(
-        plan.project_root, plan.manifest.get("finalStatusPath")
-    )
-    if final_status_path is not None:
-        command.extend(["--final-status", str(final_status_path)])
-    return command
-
-
-def _task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
-    value = _string_value(manifest.get("taskManifestPath"))
-    if value:
-        return _resolve_project_path(project_root, value)
-    task_root = _string_value(manifest.get("taskRootPath"))
-    if task_root:
-        return _resolve_project_path(project_root, task_root) / "task-manifest.json"
-    return (
-        task_dir(project_root, _task_group(manifest), _task_id(manifest))
-        / "task-manifest.json"
-    )
-
-
-def _post_process_step_payload(
-    name: str,
-    command: Sequence[str],
-    result: subprocess.CompletedProcess[str],
-) -> dict[str, Any]:
-    return {
-        "name": name,
-        "command": list(command),
-        "exitCode": result.returncode,
-        "stdoutTail": _tail(result.stdout),
-        "stderrTail": _tail(result.stderr),
-    }
-
-
-def _resolve_workspace_script(workspace_root: Path, script_name: str) -> Path:
-    candidates = [
-        workspace_root / "scripts" / script_name,
-        workspace_root / script_name,
-    ]
-    for candidate in candidates:
-        if candidate.is_file():
-            return candidate.resolve()
-    searched = ", ".join(str(candidate) for candidate in candidates)
-    raise DispatchError(f"{script_name} not found (searched: {searched})")
-
-
-def _resolve_workspace_validator(workspace_root: Path, validator_name: str) -> Path:
-    candidates = [
-        workspace_root / "validators" / validator_name,
-        workspace_root / validator_name,
-    ]
-    for candidate in candidates:
-        if candidate.is_file():
-            return candidate.resolve()
-    searched = ", ".join(str(candidate) for candidate in candidates)
-    raise DispatchError(f"{validator_name} not found (searched: {searched})")
-
-
-def _task_group(manifest: Mapping[str, Any]) -> str:
-    value = _string_value(manifest.get("taskGroup"))
-    if value:
-        return value
-    task_key = _require_string(manifest, "taskKey")
-    colon_parts = task_key.split(":")
-    if len(colon_parts) >= 3 and colon_parts[-2].strip():
-        return colon_parts[-2].strip()
-    slash_parts = task_key.split("/")
-    if len(slash_parts) >= 2 and slash_parts[0].strip():
-        return slash_parts[0].strip()
-    raise DispatchError(f"cannot infer task group from taskKey: {task_key}")
-
-
-def _task_id(manifest: Mapping[str, Any]) -> str:
-    value = _string_value(manifest.get("taskId"))
-    if value:
-        return value
-    task_key = _require_string(manifest, "taskKey")
-    colon_parts = task_key.split(":")
-    if len(colon_parts) >= 3 and colon_parts[-1].strip():
-        return colon_parts[-1].strip()
-    slash_parts = task_key.split("/")
-    if len(slash_parts) >= 2 and slash_parts[-1].strip():
-        return slash_parts[-1].strip()
-    raise DispatchError(f"cannot infer task id from taskKey: {task_key}")
+    except FinalizeError as exc:
+        return {"ok": False, "reason": str(exc), "steps": []}
 
+    def settle_before(step_name: str) -> None:
+        # validate-run reads team-state; the writer is done by the time its
+        # artifacts pass the earlier steps.
+        if step_name == STEP_VALIDATE_RUN:
+            _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
 
-def _tail(text: str, *, limit: int = 4000) -> str:
-    if len(text) <= limit:
-        return text
-    return text[-limit:]
+    return run_finalize(ctx, before_step=settle_before)
 
 
 def _append_event(
@@ -1466,37 +1242,12 @@ def _resolve_required_path(
     return _resolve_project_path(project_root, _require_string(manifest, key))
 
 
-def _resolve_optional_path(project_root: Path, value: Any) -> Path | None:
-    if not isinstance(value, str) or not value.strip():
-        return None
-    return _resolve_project_path(project_root, value)
-
-
-def _resolve_project_path(project_root: Path, value: str) -> Path:
-    path = Path(value)
-    return path if path.is_absolute() else project_root / path
-
-
-def _require_string(payload: Mapping[str, Any], key: str) -> str:
-    value = payload.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise DispatchError(f"missing required string field: {key}")
-    return value
-
-
 def _string_list(value: Any) -> list[str]:
     if not isinstance(value, list):
         return []
     return [str(item).strip() for item in value if str(item).strip()]
 
 
-def _run_seq(manifest: Mapping[str, Any]) -> str:
-    seqs = manifest.get("runSequencesByCategory")
-    if not isinstance(seqs, Mapping):
-        raise DispatchError("run manifest has no runSequencesByCategory object")
-    return _require_string(seqs, "manifests")
-
-
 def _failure_reason(exit_code: int, missing_paths: Sequence[Path]) -> str:
     if exit_code != 0:
         return f"wrapper exited with code {exit_code}"