okstra 0.82.0 → 0.83.0

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -0,0 +1,126 @@
+"""Shared worker prompt anchor header rendering."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from .paths import okstra_home
+
+
+class WorkerPromptHeaderError(Exception):
+    """Raised when worker prompt anchor headers cannot be rendered."""
+
+
+def worker_prompt_headers(
+    *,
+    project_root: Path,
+    prompt_rel: str,
+    result_rel: str,
+    worker_id: 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)
+    return [
+        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"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}",
+        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)}"
+        ),
+    ]
+
+
+def _worker_preamble_path() -> Path:
+    return okstra_home() / "templates" / "worker-prompt-preamble.md"
+
+
+def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
+    runtime_resources = active_context.get("runtimeResources")
+    if isinstance(runtime_resources, Mapping):
+        value = _string_value(runtime_resources.get("codingPreflightDir"))
+        if value:
+            return Path(value)
+    return okstra_home() / "prompts" / "coding-preflight"
+
+
+def _errors_log_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> Path:
+    error_logs = active_context.get("errorLogs")
+    if isinstance(error_logs, Mapping):
+        value = _string_value(error_logs.get("runErrorsLogPath"))
+        if value:
+            return _resolve_project_path(project_root, value)
+    run_dir = _run_directory_path(project_root, manifest)
+    task_type = _require_string(manifest, "taskType")
+    seq = _sequence(manifest, "state")
+    return run_dir / "logs" / f"errors-{task_type}-{seq}.jsonl"
+
+
+def _worker_errors_sidecar_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+) -> Path:
+    error_logs = active_context.get("errorLogs")
+    if isinstance(error_logs, Mapping):
+        sidecars = error_logs.get("sidecarsByWorkerId")
+        if isinstance(sidecars, Mapping):
+            value = _string_value(sidecars.get(worker_id))
+            if value:
+                return _resolve_project_path(project_root, value)
+    run_dir = _run_directory_path(project_root, manifest)
+    task_type = _require_string(manifest, "taskType")
+    seq = _sequence(manifest, "workerResults")
+    return run_dir / "worker-results" / f"{worker_id}-worker-errors-{task_type}-{seq}.json"
+
+
+def _run_directory_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
+    value = _string_value(manifest.get("runDirectoryPath"))
+    if value:
+        return _resolve_project_path(project_root, value)
+    team_state_path = _resolve_project_path(
+        project_root,
+        _require_string(manifest, "teamStatePath"),
+    )
+    return team_state_path.parent.parent
+
+
+def _sequence(manifest: Mapping[str, Any], key: str) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if isinstance(seqs, Mapping):
+        return _string_value(seqs.get(key)) or _run_seq(manifest)
+    return _run_seq(manifest)
+
+
+def _run_seq(manifest: Mapping[str, Any]) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if not isinstance(seqs, Mapping):
+        raise WorkerPromptHeaderError("run manifest has no runSequencesByCategory object")
+    return _require_string(seqs, "manifests")
+
+
+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 WorkerPromptHeaderError(f"missing required string field: {key}")
+    return value
+
+
+def _string_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""

package/runtime/python/okstra_token_usage/claude.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from .cursor import MAX_NEEDLES, fresh_cache, load_cache, save_cache
 from .paths import claude_project_dir, ts_in_window
 
-# lead 의 단계 체크포인트 라인(agents/SKILL.md "Progress reporting") — phase id 가
+# lead 의 단계 체크포인트 라인(prompts/lead/okstra-lead-contract.md "Progress reporting") — phase id 가
 # `phase-<digit>` 로 시작하는 라인만 마커로 인정해 일반 대화의 오탐을 줄인다.
 _PROGRESS_RE = re.compile(r"^PROGRESS:\s+(phase-\d\S*(?:[ \t].*)?)$", re.MULTILINE)
 _PROGRESS_MARKER_MAX_CHARS = 160

package/runtime/python/okstra_token_usage/collect.py

@@ -159,7 +159,7 @@ def _wall_ms(start_iso: str | None, end_iso: str | None) -> int | None:
 
 
 def phase_timeline(markers: list[dict]) -> dict:
-    """lead 의 PROGRESS 체크포인트(agents/SKILL.md "Progress reporting")로
+    """lead 의 PROGRESS 체크포인트(prompts/lead/okstra-lead-contract.md "Progress reporting")로
     run 내부 단계 경계 wall-clock 을 복원한다 (perf plan v2 P0 계측).
 
     phase id = marker 의 첫 토큰(`phase-5.5-convergence` 등). 같은 phase 의

package/runtime/templates/reports/task-brief.template.md

@@ -112,7 +112,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ### Standing Ticket-Tagging Rule (always applied by every worker)
 
-- 모든 항목 및 표 행에 ticket을 명시한다. 표 형식은 `Ticket ID` 컬럼, bullet/번호목록·섹션 헤더는 `[TICKETID: <id>]` 태그를 사용한다. 채움 우선순위·폴백·다중 ticket 규칙은 `okstra-team-contract` SKILL의 Ticket Tagging 절을 따른다.
+- 모든 항목 및 표 행에 ticket을 명시한다. 표 형식은 `Ticket ID` 컬럼, bullet/번호목록·섹션 헤더는 `[TICKETID: <id>]` 태그를 사용한다. 채움 우선순위·폴백·다중 ticket 규칙은 `team-contract` SKILL의 Ticket Tagging 절을 따른다.
 
 ### Standing Scope-Discipline Questions (always answered by every worker)
 
@@ -138,7 +138,7 @@ taskType: "{{FM_TASK_TYPE}}"
 ## Phase Boundary
 
 - This okstra run executes the lifecycle phase named in `Task Type` and stops there. Outputs that belong to any other phase MUST NOT be produced inside this run.
-- Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`agents/SKILL.md`). The lead and every worker stay inside that boundary.
+- Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`prompts/lead/okstra-lead-contract.md`). The lead and every worker stay inside that boundary.
 - "다음 단계 진행해" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`.
 - For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories.
 - For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or its frontmatter `approved` field is not `true`. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.

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

@@ -18,7 +18,7 @@ Different recipients need different files. Do NOT include `final-report-template
 |---|---|
 | Claude / Codex / Gemini analysis workers | analysis-packet.md as the primary compact input; task-brief, analysis-profile, analysis-material, reference-expectations, and clarification-response remain source/fallback paths, not automatic first-read files |
 | Report writer worker (Phase 6) | all of the above **plus** the instruction-set-local `final-report-template.md` (phase-stripped) and `final-report-schema.json` (per-task-type excerpt) — NOT the full `templates/reports/...` / `schemas/...` sources |
-| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [okstra-convergence](../skills/okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
+| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [convergence](../prompts/lead/convergence.md) "Reverify prompt: required-reading suppression". |
 
 ### Reading rules
 
@@ -112,7 +112,7 @@ Every item in sections 1–5 (and any section 6) MUST carry a worker-internal it
 
 For task types `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items.
 
-See `skills/okstra-team-contract/SKILL.md` "Worker Output Contract" for the full frontmatter schema and section ordering rules. This preamble is consistent with that contract; the team-contract document is authoritative if the two ever diverge.
+See `prompts/lead/team-contract.md` "Worker Output Contract" for the full frontmatter schema and section ordering rules. This preamble is consistent with that contract; the team-contract document is authoritative if the two ever diverge.
 
 ## Return message to the lead (all workers)
 

package/runtime/validators/lib/validate-assets.sh

@@ -57,10 +57,18 @@ else:
             continue
         check(source_path, workers_target / source_path.name)
 
-# 2. Lead agent SKILL.md: agents/SKILL.md -> runtime/agents/SKILL.md
-lead_source = agents_source_root / "SKILL.md"
-if lead_source.is_file():
-    check(lead_source, runtime_root / "agents" / "SKILL.md")
+# 2. Lead contract + internal lead resources: prompts/lead/* + prompts/coding-preflight/*
+#    -> runtime/prompts/*. These ship as runtime resources (okstra install copies
+#    runtime/prompts -> ~/.okstra/prompts), no longer as agent skills.
+prompts_source_root = agents_source_root.parent / "prompts"
+for sub in ("lead", "coding-preflight"):
+    sub_root = prompts_source_root / sub
+    if not sub_root.is_dir():
+        errors.append(f"missing prompts source directory: {sub_root}")
+        continue
+    for source_path in sorted(sub_root.rglob("*.md")):
+        relative = source_path.relative_to(prompts_source_root)
+        check(source_path, runtime_root / "prompts" / relative)
 
 # 3. Skill packages: skills/<name>/SKILL.md -> runtime/skills/<name>/SKILL.md
 if not skills_source_root.is_dir():

package/runtime/validators/validate-run.py

@@ -436,7 +436,7 @@ def validate_team_state(
                     "team-state.teamCreate.attempted must be true once any worker has "
                     "been dispatched (status in completed/timeout/error/in-progress). "
                     "Phase 3 (TeamCreate) was skipped — workers ran in-process without "
-                    "the Teams split-pane surface. See agents/SKILL.md Phase 3. "
+                    "the Teams split-pane surface. See prompts/lead/okstra-lead-contract.md Phase 3. "
                     "(The no-team concurrent-run path is legal ONLY when the "
                     "run-manifest carries prepare-recorded `concurrentRun.detected: "
                     'true` AND team-state records `teamCreate: { attempted: false, '
@@ -1373,7 +1373,7 @@ def _validate_verdict_card_consistency(content: str, failures: list[str]) -> Non
     """Verdict Card is a non-authoritative index of §7. If both blocks
     carry a Verdict Token row, the values MUST byte-match (modulo case
     and surrounding whitespace) — divergence is a contract violation per
-    `okstra-report-writer` SKILL.md "Authoring Contract".
+    `report-writer` SKILL.md "Authoring Contract".
     """
     card_value = _extract_verdict_card_token(content)
     final_value = _extract_final_verdict_token(content)
@@ -1828,7 +1828,7 @@ def _validate_session_conformance(
     claude_projects_dir: str | None,
     failures: list[str],
 ) -> None:
-    """agents/SKILL.md BLOCKING 계약 3종(PROGRESS 체크포인트 / claude-worker
+    """prompts/lead/okstra-lead-contract.md BLOCKING 계약 3종(PROGRESS 체크포인트 / claude-worker
     heartbeat / implementation entry guard)의 post-hoc 검사를 위임하고 실패를
     ``session-conformance: `` 접두로 folding 한다. 설계:
     docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md

package/runtime/validators/validate_session_conformance.py

@@ -1,12 +1,12 @@
-"""agents/SKILL.md BLOCKING 계약 3종의 post-hoc conformance 검사.
+"""prompts/lead/okstra-lead-contract.md BLOCKING 계약 3종의 post-hoc conformance 검사.
 
 설계: docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md
 
 | 검사 | 선언 위치 | 증거 |
 |------|----------|------|
-| 1. lead PROGRESS 체크포인트 라인 | agents/SKILL.md "Progress reporting (BLOCKING)" | lead 세션 jsonl 의 assistant text 블록 |
+| 1. lead PROGRESS 체크포인트 라인 | prompts/lead/okstra-lead-contract.md "Progress reporting (BLOCKING)" | lead 세션 jsonl 의 assistant text 블록 |
 | 2. claude-worker 5분 heartbeat | agents/workers/claude-worker.md "Heartbeat" | audit 사이드카의 `- PROGRESS: <stage> <ISO>` 라인 |
-| 3. implementation sidecar entry guard | agents/SKILL.md "Entry guard (BLOCKING)" | lead 세션 jsonl 의 Read tool_use |
+| 3. implementation sidecar entry guard | prompts/lead/okstra-lead-contract.md "Entry guard (BLOCKING)" | lead 세션 jsonl 의 Read tool_use |
 
 스캔 규칙 (false-pass 방지가 핵심):
 - `type == "assistant"` 레코드만 본다 — Skill 호출 시 SKILL.md 본문(체크포인트
@@ -336,7 +336,7 @@ def _check_worker_checkpoint_lines(
             errors.append(
                 f"PROGRESS checkpoint missing: no `phase-4-dispatch worker=<role>` "
                 f"line names worker `{role}` — one line per dispatched worker, "
-                "agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
         if status == "completed" and not _phase_mentions_worker(
             by_phase.get("phase-5-collect", []), needles
@@ -344,7 +344,7 @@ def _check_worker_checkpoint_lines(
             errors.append(
                 f"PROGRESS checkpoint missing: no `phase-5-collect worker=<role>` "
                 f"line names completed worker `{role}` — one line per collected "
-                "result, agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "result, prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
 
 
@@ -363,19 +363,19 @@ def _check_progress_checkpoints(
         if condition and phase not in by_phase:
             errors.append(
                 f"PROGRESS checkpoint missing: `{phase}` ({detail}) — "
-                "agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
 
     intake = by_phase.get("phase-1-intake", [])
     if not any("complete" not in line.lower() for _ts, line in intake):
         errors.append(
             "PROGRESS checkpoint missing: `phase-1-intake reading task bundle` "
-            "(start-of-Phase-1 line) — agents/SKILL.md 'Progress reporting (BLOCKING)'."
+            "(start-of-Phase-1 line) — prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
         )
     if not any("complete" in line.lower() for _ts, line in intake):
         errors.append(
             "PROGRESS checkpoint missing: `phase-1-intake complete` "
-            "(after all intake reads) — agents/SKILL.md 'Progress reporting (BLOCKING)'."
+            "(after all intake reads) — prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
         )
 
     workers = [w for w in (team_state.get("workers") or []) if isinstance(w, dict)]
@@ -427,7 +427,7 @@ def _check_heartbeat_sidecar(path: Path, errors: list[str]) -> None:
             f"`{rel}` has no `- PROGRESS: <stage> <ISO-8601-UTC>` heartbeat lines — "
             "the claude-worker MUST write `started` immediately and append one "
             "line per stage at <= 5-minute cadence (agents/workers/claude-worker.md "
-            "'Heartbeat', agents/SKILL.md Common Mistakes)."
+            "'Heartbeat', prompts/lead/okstra-lead-contract.md Common Mistakes)."
         )
         return
     if entries[0][0] != "started":
@@ -498,7 +498,7 @@ def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[st
                 f"implementation entry guard: no `Read` of `{basename}` found in "
                 f"the lead session jsonl within this run's window — the sidecar "
                 f"MUST be read fresh at {read_at} every implementation run "
-                "(agents/SKILL.md 'Entry guard (BLOCKING)')."
+                "(prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
             )
             continue
         anchor_ts = anchors.get(anchor_phase)
@@ -507,7 +507,7 @@ def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[st
                 f"implementation entry guard: `{basename}` was first Read at "
                 f"{min(ts_list)}, not before the first `PROGRESS: {anchor_phase}` "
                 f"line ({anchor_ts}) — it must be loaded at {read_at}, before "
-                "that checkpoint (agents/SKILL.md 'Entry guard (BLOCKING)')."
+                "that checkpoint (prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
             )