okstra 0.64.1 → 0.66.0

package/runtime/skills/okstra-coding-preflight/clean-code.md

@@ -253,6 +253,21 @@ Good:
 cache.invalidate(user.id);
 ```
 
+**A comment is not a change log.** Never record change history in code — ticket IDs (`FU-003`, `DEV-9185`), verification logs (`verified parity-neutral on the real DB`), `retained from …`, or the reason something *changed*. That belongs to git blame, the commit message, and the PR; the code reader six months later does not have those tickets open. A comment earns its place only by stating a constraint or invariant that is **still true and load-bearing for someone reading the code cold, with zero knowledge of the diff that introduced it**. If it stops making sense once that diff is forgotten, delete it.
+
+Bad (change-log noise — delete):
+```javascript
+// FU-003 read-path deltas — verified parity-neutral against the publish grid
+// on the real DB (DEV-9185 Stage 1). Retained as read-side display alignment.
+applyYearlyMultiplier(rows);
+```
+
+Good (constraint a cold reader needs):
+```javascript
+// Publish callers omit both fields, so the 0 multiplier is intentional here.
+applyYearlyMultiplier(rows);
+```
+
 Default to writing **no comment**. Only add one when removing it would confuse a future reader.
 
 ## Boy Scout Rule

package/runtime/skills/okstra-inspect/SKILL.md

@@ -524,25 +524,29 @@ Parse the JSON and report these fields:
 | Current run | `totals.currentRunFileCount`, `totals.currentRunBytes`, `currentRunPath` |
 | Legacy timestamp artifacts | `totals.legacyTimestampFileCount` |
 | Instruction set | `instructionSet.fileCount`, `instructionSet.bytes`, `instructionSet.analysisPacketBytes`, `instructionSet.legacyTaskPacketBytes` |
-| Lead Phase 1 | `leadPhase1.mode`, `leadPhase1.fileCount`, `leadPhase1.bytes` |
-| Analysis worker | `analysisWorker.mode`, `analysisWorker.fileCount`, `analysisWorker.bytesPerWorker`, `analysisWorker.legacyFullContractBytesPerWorker`, `analysisWorker.estimatedPacketModeBytesPerWorker`, `analysisWorker.estimatedReductionPercent` |
-| Report writer | `reportWriter.fileCount`, `reportWriter.bytes` |
+| Lead Phase 1 | `leadPhase1.mode`, `leadPhase1.fileCount`, `leadPhase1.bytes`, `leadPhase1.estimatedTokens` |
+| Analysis worker | `analysisWorker.mode`, `analysisWorker.fileCount`, `analysisWorker.bytesPerWorker`, `analysisWorker.estimatedTokensPerWorker`, `analysisWorker.legacyFullContractBytesPerWorker`, `analysisWorker.estimatedPacketModeBytesPerWorker`, `analysisWorker.estimatedReductionPercent` |
+| Report writer | `reportWriter.fileCount`, `reportWriter.bytes`, `reportWriter.estimatedTokens` |
+| Skill assets (hot path) | `skillAssets.fileCount`, `skillAssets.bytes`, `skillAssets.estimatedTokens`, top entries of `skillAssets.files[]` |
 
 Format bytes as both raw bytes and rounded KB/MB where useful. Use `analysisWorker.estimatedReductionPercent` for the worker-input reduction. Do not recompute it from `bytesPerWorker` when `analysisWorker.mode == "analysis-packet-primary"` because `bytesPerWorker` is already the packet-primary cost.
 
+`estimatedTokens*` fields are a static heuristic (~4 ASCII chars/token, non-ASCII ≈ 1 token/char) for ranking instruction surfaces — actual billable cost is the token-usage collector's domain; never present these as billing numbers. `skillAssets` measures the per-run hot-path instruction assets loaded OUTSIDE the task bundle (lifecycle skill bodies + worker agent specs, installed copy preferred) — the prompt-diet target list, sorted by size descending.
+
 ### cost.4 — Output template
 
 ```markdown
 ## okstra Context Cost — <task-key>
 
-| Surface | Files | Size |
-|---|---:|---:|
-| Task bundle | <N> | <bytes> (<human>) |
-| Current run | <N> | <bytes> (<human>) |
-| Instruction set | <N> | <bytes> (<human>) |
-| Lead Phase 1 (`<mode>`) | <N> | <bytes> (<human>) |
-| Analysis worker / worker (`<mode>`) | <N> | <bytes> (<human>) |
-| Report writer synthesis | <N> | <bytes> (<human>) |
+| Surface | Files | Size | ~Tokens |
+|---|---:|---:|---:|
+| Task bundle | <N> | <bytes> (<human>) | - |
+| Current run | <N> | <bytes> (<human>) | - |
+| Instruction set | <N> | <bytes> (<human>) | <estimatedTokens> |
+| Lead Phase 1 (`<mode>`) | <N> | <bytes> (<human>) | <estimatedTokens> |
+| Analysis worker / worker (`<mode>`) | <N> | <bytes> (<human>) | <estimatedTokensPerWorker> |
+| Report writer synthesis | <N> | <bytes> (<human>) | <estimatedTokens> |
+| Skill assets (hot path) | <N> | <bytes> (<human>) | <estimatedTokens> |
 
 - Current run: `<currentRunPath-or-->`
 - Legacy timestamp artifacts: `<N>`
@@ -562,6 +566,7 @@ Interpretation rules:
 - `analysisWorker.mode == "analysis-packet-primary"` means new workers should read `analysis-packet.md` first and open full source inputs only for evidence checks or missing detail.
 - If `analysisWorker.mode == "full-input-contract"` and `estimatedReductionPercent` is low, the next target is worker prompt/input contract slimming.
 - If `reportWriter.bytes` dominates, the next target is a compact `synthesis-input` artifact.
+- If `skillAssets.estimatedTokens` dominates the per-run fixed cost, the next target is slimming the largest `skillAssets.files[]` entries (prompt diet — perf plan v2 P2), e.g. thin-core + lazy-sidecar split.
 - If `legacyTimestampFileCount` is high, recommend current-view/cold-artifact separation or retention cleanup, not destructive deletion by default.
 
 ---

package/runtime/skills/okstra-run/templates/pr-body.template.md

@@ -1,28 +1,25 @@
 <!--
-okstra release-handoff 기본 PR 본문 템플릿.
+okstra release-handoff default PR body template.
 
-이 파일은 사용자 정의 PR 템플릿이 없을 때 사용됩니다. 우선순위:
-  1. okstra-run Step 6 에서 입력한 per-run override 경로
-  2. <project-root>/.okstra/project.json 의 `prTemplatePath`
-  3. ~/.okstra/config.json 의 `prTemplatePath`
-  4. 이 디폴트 파일
+This file is used when there is no custom PR template. Priority:
+    1. The per-run override path entered in okstra-run Step 6
+    2. `prTemplatePath` of <project-root>/.okstra/project.json
+    3. `prTemplatePath` of ~/.okstra/config.json
+    4. This default file
 
-프로젝트 또는 전역 설정으로 자체 템플릿을 쓰려면 위 경로 중 하나에
-`prTemplatePath` 키를 추가하세요. (절대경로 또는 project_root 기준 상대경로)
-
-플레이스홀더는 release-handoff 의 Claude lead 가 다음 입력을 근거로
-직접 채웁니다:
-  - run brief 의 의도/스코프
-  - 인용된 final-verification 리포트의 verdict 근거
-  - `git log --oneline <base>..HEAD` 의 commit 범위
-  - `git diff <base>..HEAD --stat` 의 변경 파일 통계
+To use your own templates in project or global settings, add the `prTemplatePath` key to one of the paths above. (Absolute path or relative path based on `project_root`)
 
+The placeholder is filled in directly by the Claude lead for the release-handoff based on the following inputs:
+  - The intent and scope of the run brief
+  - The grounds for the verdict in the referenced final-verification report
+  - The commit range from `git log --oneline <base>..HEAD`
+  - The file change statistics from `git diff <base>..HEAD --stat`
 -->
 
 ## **Please check if the PR fulfills these requirements**
 - [ ] Commits have a single intent
 - [ ] Tests for the changes have been added (for bug fixes / features)
-- [ ] I reviewed my own code
+- [x] I reviewed my own code
 - [ ] I tested the changes (if not, explain why in the "Other information" section)
 - [ ] Docs have been added / updated
 

package/runtime/skills/okstra-schedule/SKILL.md

@@ -56,15 +56,15 @@ Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this ski
 
 This skill performs cross-task synthesis (multi-task classification, dependency reasoning, phase placement, Gantt/timeline assembly) which benefits substantially from Opus-class reasoning. The frontmatter `model: opus` field above instructs supporting Claude Code harness versions to switch automatically; if the harness ignores it, this gate catches the case explicitly.
 
-1. Inspect the active session model. The model is shown in the status line, accessible via `/model`, and embedded in the runtime context as the model name (e.g. `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5-*`).
-2. If the active model is **Opus-class** (`claude-opus-*`): proceed to Step 1.
+1. Inspect the active session model. The model is shown in the status line, accessible via `/model`, and embedded in the runtime context as the model name (e.g. `claude-fable-5`, `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5-*`).
+2. If the active model is **Opus-class or above** (`claude-opus-*`, `claude-fable-*`): proceed to Step 1.
 3. If the active model is **Sonnet or Haiku-class**: STOP and output the following message verbatim, then wait for user response:
    ```
    okstra-schedule는 Opus-class 모델에서 실행하는 것을 권장합니다 (현재: <active-model>).
    /model opus 로 전환 후 다시 호출하시거나, 'sonnet으로 진행' 이라고 명시하시면 그대로 실행합니다.
    ```
 4. If the user explicitly insists on the lower model ("sonnet으로 진행", "그대로 진행", "force", or similar): proceed to Step 1, but prepend a single-line warning at the top of the generated schedule file: `> ⚠️ Generated with <model> (not Opus). Cross-task synthesis quality may be reduced.`
-5. Skip this gate ONLY when the harness has clearly enforced `model: opus` from the frontmatter — verifiable by the active model already being Opus-class without manual switching.
+5. Skip this gate ONLY when the harness has clearly enforced `model: opus` from the frontmatter — verifiable by the active model already being Opus-class or above without manual switching.
 
 ### Step 1: Resolve task-group and collect tasks
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -38,7 +38,7 @@ okstra tasks are always operated using the `Claude lead` + required worker team
 1. `resultContract.requiredWorkerRoles` in `task-manifest.json` (and the lead model metadata) is the canonical source. There is no role-level fallback — a missing assignment is a manifest defect, not a license to invent one.
 2. If `modelExecutionValue` differs from `model`, use `modelExecutionValue` during execution.
 3. **Spawn-time enforcement for in-process Claude subagents (BLOCKING).** `Claude worker` and `Report writer worker` are in-process Claude subagents whose agent definitions declare `model: inherit` (`agents/workers/claude-worker.md`, `agents/workers/report-writer-worker.md`). `inherit` follows the **lead's** runtime model, NOT the role's assignment — so an opus assignment silently runs on a sonnet lead. To make the assignment binding (not merely declared), lead MUST pass an explicit `model:` parameter on every `Agent(...)` dispatch for these two roles, derived from that role's `modelExecutionValue`. The dispatch `model:` parameter overrides the `inherit` frontmatter; the frontmatter remains only as the fallback when no parameter is supplied. Omitting `model:` on a Claude-side dispatch is a contract violation that reproduces the assigned-vs-actual model deviation.
-4. **`modelExecutionValue` → Agent `model:` family token.** The Agent tool's `model` parameter accepts family tokens only — `opus` / `sonnet` / `haiku` (an exact version such as `claude-opus-4-7` is NOT a valid value). Map by prefix: a `modelExecutionValue` of `opus*` / `claude-opus*` → `"opus"`, `sonnet*` / `claude-sonnet*` → `"sonnet"`, `haiku*` / `claude-haiku*` → `"haiku"`. This enforces the assignment at **family granularity** (opus vs sonnet vs haiku); the exact version within a family is still inherited from the lead session and cannot be pinned via this parameter.
+4. **`modelExecutionValue` → Agent `model:` family token.** The Agent tool's `model` parameter accepts family tokens only — `fable` / `opus` / `sonnet` / `haiku` (an exact version such as `claude-opus-4-7` is NOT a valid value). Map by prefix: a `modelExecutionValue` of `fable*` / `claude-fable*` → `"fable"`, `opus*` / `claude-opus*` → `"opus"`, `sonnet*` / `claude-sonnet*` → `"sonnet"`, `haiku*` / `claude-haiku*` → `"haiku"`. This enforces the assignment at **family granularity** (fable vs opus vs sonnet vs haiku); the exact version within a family is still inherited from the lead session and cannot be pinned via this parameter.
 5. **Codex / Gemini wrappers are out of scope for the Agent `model:` rule.** `Codex worker` / `Gemini worker` subagents are Claude wrappers that shell out to an external CLI; the role's `modelExecutionValue` is already applied via the CLI's own `--model <modelExecutionValue>` argument (see `agents/workers/_cli-wrapper-template.md`). The Agent `model:` parameter for these wrappers would only set the wrapper's own orchestration model, not the external CLI's model — leave it at `inherit` and do NOT map it from `modelExecutionValue`.
 
 ### Dynamic Worker Role Determination

package/runtime/validators/lib/fixtures.sh

@@ -147,6 +147,7 @@ prepare_run_validator_fixture() {
   expected_task_manifest_relative_path="$(task_manifest_relative_path "$task_group" "$task_id")"
 
   python3 - "$PROJECT_ROOT" "$expected_task_manifest_relative_path" "$omitted_worker_id" <<'PY'
+from datetime import datetime, timezone
 from pathlib import Path
 import json
 import sys
@@ -258,20 +259,33 @@ for worker in team_state.get("workers", []):
         result_stem = result_path.stem  # e.g. claude-worker-error-analysis-001
         audit_stem = result_stem.replace("-worker-", "-worker-audit-", 1)
         audit_path = result_path.with_name(f"{audit_stem}{result_path.suffix}")
-        audit_path.write_text(
-            "\n".join(
-                [
-                    f"# {worker.get('role', worker_id)} Audit",
-                    "",
-                    "- Read task-brief.md end-to-end (validation fixture).",
-                ]
-            )
-            + "\n"
-        )
+        audit_lines = [
+            f"# {worker.get('role', worker_id)} Audit",
+            "",
+            "- Read task-brief.md end-to-end (validation fixture).",
+        ]
+        if worker_id == "claude":
+            # Heartbeat 계약 (agents/workers/claude-worker.md "Heartbeat") —
+            # validate_session_conformance 가 claude-worker audit 사이드카의
+            # `- PROGRESS:` cadence 를 검사하므로 fixture 도 계약을 준수한다.
+            hb_ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+            audit_lines += [
+                "",
+                f"- PROGRESS: started {hb_ts}",
+                f"- PROGRESS: read-task-brief.md {hb_ts}",
+                f"- PROGRESS: analysis-start {hb_ts}",
+                f"- PROGRESS: findings-draft-complete {hb_ts}",
+                f"- PROGRESS: write-result-start {hb_ts}",
+            ]
+        audit_path.write_text("\n".join(audit_lines) + "\n")
 
 lead = team_state.get("lead")
 if isinstance(lead, dict):
     lead["status"] = "completed"
+    # render-only fixture 에는 실 Claude 세션이 없어 sessionId 가 비어 있을 수
+    # 있다 — session-conformance fixture jsonl 의 파일명과 맞춘 고정 id 를 부여.
+    if not str(lead.get("sessionId") or "").strip():
+        lead["sessionId"] = "fixture-lead-session-0001"
 team_state["workflowState"] = "worker-results-collected"
 
 # validate-run.py requires team-state.teamCreate.attempted=true with a
@@ -436,6 +450,55 @@ if WORKSPACE_ROOT:
 if final_status_path.exists():
     final_status_path.unlink()
 
+# session-conformance fixture — validate_session_conformance 는 lead 세션
+# jsonl 에서 run 윈도우 내 PROGRESS 체크포인트를 스캔한다. 계약을 준수한
+# 합성 jsonl 을 주입 시드 디렉터리(.claude-projects-fixture)에 만들어 두고,
+# 러너(run_validator_expectation)가 --claude-projects-dir 로 넘긴다.
+lead_sid = str((team_state.get("lead") or {}).get("sessionId") or "").strip()
+if lead_sid:
+    now_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+    progress_lines = [
+        "PROGRESS: phase-1-intake reading task bundle",
+        "PROGRESS: phase-1-intake complete",
+        f"PROGRESS: phase-2-prompts preparing {len(team_state.get('workers') or [])} worker prompts",
+        "PROGRESS: phase-3-team-create attempting TeamCreate",
+    ]
+    for worker in team_state.get("workers", []):
+        if not isinstance(worker, dict):
+            continue
+        worker_id = str(worker.get("workerId", "")).strip()
+        status = str(worker.get("status", "")).strip()
+        if not worker_id or worker_id == "report-writer":
+            continue
+        if status in ("completed", "timeout", "error"):
+            progress_lines.append(
+                f"PROGRESS: phase-4-dispatch worker={worker_id}-worker model=fixture"
+            )
+        if status == "completed":
+            progress_lines.append(
+                f"PROGRESS: phase-5-collect worker={worker_id}-worker status=completed"
+            )
+    progress_lines.append("PROGRESS: phase-6-synthesis dispatching report-writer-worker")
+    progress_lines.append("PROGRESS: phase-7-persist updating manifests")
+    records = [
+        {
+            "type": "assistant",
+            "timestamp": now_iso,
+            "message": {"content": [{"type": "text", "text": line}]},
+        }
+        for line in progress_lines
+    ]
+    # 인코딩 기준은 validator 가 쓰는 task-manifest.projectRoot — macOS 의
+    # /tmp 심링크 때문에 셸의 $PROJECT_ROOT(/tmp/...)와 manifest 의
+    # projectRoot(/private/tmp/...)가 다른 문자열일 수 있다.
+    manifest_project_root = str(task_manifest.get("projectRoot") or project_root)
+    encoded_cwd = "-" + manifest_project_root.strip("/").replace("/", "-")
+    session_dir = project_root / ".claude-projects-fixture" / encoded_cwd
+    session_dir.mkdir(parents=True, exist_ok=True)
+    (session_dir / f"{lead_sid}.jsonl").write_text(
+        "".join(json.dumps(r, ensure_ascii=False) + "\n" for r in records)
+    )
+
 write_json(team_state_path, team_state)
 write_json(run_manifest_path, run_manifest)
 write_json(task_manifest_path, task_manifest)

package/runtime/validators/lib/runners.sh

@@ -87,6 +87,10 @@ process = subprocess.run(
         str(task_manifest_path),
         "--final-status",
         str(final_status_path),
+        # session-conformance 주입 시드 — prepare_run_validator_fixture 가
+        # 만든 합성 lead jsonl 디렉터리 (실제 ~/.claude/projects 미오염).
+        "--claude-projects-dir",
+        str(project_root / ".claude-projects-fixture"),
     ],
     capture_output=True,
     text=True,

package/runtime/validators/validate-run.py

@@ -1681,6 +1681,41 @@ def _validate_improvement_discovery(
             failures.append(f"improvement-discovery: {err}")
 
 
+def _validate_session_conformance(
+    team_state: dict,
+    team_state_path: Path,
+    project_root: Path,
+    report_path: Path,
+    task_type: str,
+    claude_projects_dir: str | None,
+    failures: list[str],
+) -> None:
+    """agents/SKILL.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
+    """
+    _validators_dir = Path(__file__).resolve().parent
+    if str(_validators_dir) not in sys.path:
+        sys.path.insert(0, str(_validators_dir))
+    try:
+        from validate_session_conformance import validate_session_conformance  # noqa: E402
+    except ImportError as exc:
+        failures.append(
+            f"session-conformance: validate_session_conformance import failed — {exc}"
+        )
+        return
+    result = validate_session_conformance(
+        team_state=team_state,
+        team_state_path=team_state_path,
+        project_root=project_root,
+        report_path=report_path,
+        task_type=task_type,
+        claude_projects_dir=Path(claude_projects_dir) if claude_projects_dir else None,
+    )
+    failures.extend(f"session-conformance: {err}" for err in result.errors)
+
+
 def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
     """requirements-discovery run 에 fan-out/ 이 있으면 packet+index 를 검증해
     실패를 ``requirements-discovery: `` 접두로 folding 한다. fan-out 이 없으면 no-op.
@@ -1993,6 +2028,15 @@ def main() -> int:
     parser.add_argument(
         "--final-status", required=False, help="Optional final status file to write."
     )
+    parser.add_argument(
+        "--claude-projects-dir",
+        required=False,
+        default=None,
+        help=(
+            "Override the Claude Code projects root used for session-conformance "
+            "jsonl lookup (test/diagnostic seam; default: ~/.claude/projects)."
+        ),
+    )
     args = parser.parse_args()
 
     run_manifest_path = Path(args.run_manifest).resolve()
@@ -2043,6 +2087,15 @@ def main() -> int:
     validate_phase_boundary(task_type, report_path, failures)
     if task_type:
         validate_worker_results_audit(report_path, task_type, failures)
+        _validate_session_conformance(
+            team_state,
+            team_state_path,
+            project_root,
+            report_path,
+            task_type,
+            args.claude_projects_dir,
+            failures,
+        )
     if task_type in ("implementation", "final-verification"):
         _sp = None
         _pj = project_json_path(project_root)