okstra 0.50.0 → 0.51.0

package/runtime/python/okstra_ctl/context_cost.py

@@ -0,0 +1,308 @@
+"""Read-side context cost estimator for prepared okstra task bundles.
+
+The estimator answers a narrow operational question: how much file/context
+surface does the current task bundle ask the lead, analysis workers, and
+report-writer to absorb? It does not mutate task artifacts.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+from okstra_project import ResolverError, find_task_root, resolve_project_root
+
+
+INPUT_FILES = (
+    "task-brief.md",
+    "analysis-profile.md",
+    "analysis-material.md",
+    "reference-expectations.md",
+    "clarification-response.md",
+)
+TIMESTAMPED_ARTIFACT_RE = re.compile(r"\d{4}-\d{2}-\d{2}[_T]\d{2}-\d{2}-\d{2}")
+
+
+def _file_size(path: Path) -> int:
+    return path.stat().st_size if path.is_file() else 0
+
+
+def _count_files(paths: Iterable[Path]) -> tuple[int, int]:
+    file_count = 0
+    byte_count = 0
+    for path in paths:
+        if path.is_file():
+            file_count += 1
+            byte_count += path.stat().st_size
+    return file_count, byte_count
+
+
+def _all_files(root: Path) -> list[Path]:
+    if not root.exists():
+        return []
+    return [path for path in root.rglob("*") if path.is_file()]
+
+
+def _load_json(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _resolve_task_root(target: str, project_root: str, cwd: str) -> tuple[Path, Path]:
+    target_path = Path(target).expanduser()
+    if target_path.exists():
+        task_root = target_path.resolve()
+        return task_root, _infer_project_root(task_root)
+
+    try:
+        resolved_project = Path(
+            resolve_project_root(explicit_root=project_root, cwd=cwd)
+        ).resolve()
+    except ResolverError as exc:
+        raise SystemExit(f"project root resolution failed: {exc}") from exc
+
+    task_root = find_task_root(resolved_project, target)
+    if task_root is None:
+        raise SystemExit(f"no task root for task key: {target}")
+    return task_root.resolve(), resolved_project
+
+
+def _infer_project_root(task_root: Path) -> Path:
+    parts = task_root.parts
+    if ".okstra" not in parts:
+        return task_root
+    idx = parts.index(".okstra")
+    return Path(*parts[:idx]).resolve()
+
+
+def _project_rel(path: Path, project_root: Path) -> str:
+    try:
+        return str(path.resolve().relative_to(project_root.resolve()))
+    except ValueError:
+        return str(path)
+
+
+def _find_current_run_dir(
+    task_root: Path, manifest: dict, project_root: Path
+) -> Path | None:
+    artifacts = manifest.get("artifacts", {})
+    prompt_dir = artifacts.get("workerPromptsDirectoryPath")
+    if isinstance(prompt_dir, str) and prompt_dir:
+        path = project_root / prompt_dir
+        if path.is_dir():
+            return path.parent
+
+    task_type = manifest.get("workflow", {}).get("currentPhase") or manifest.get("taskType")
+    if not isinstance(task_type, str) or not task_type:
+        return None
+    candidate = task_root / "runs" / task_type
+    return candidate if candidate.is_dir() else None
+
+
+def _latest_matching_file(directory: Path, pattern: str) -> Path | None:
+    matches = sorted(directory.glob(pattern))
+    if not matches:
+        return None
+    return max(matches, key=lambda path: path.stat().st_mtime)
+
+
+def _is_timestamped_legacy_artifact(path: Path) -> bool:
+    return bool(TIMESTAMPED_ARTIFACT_RE.search(path.name))
+
+
+def _instruction_set_metric(task_root: Path, project_root: Path) -> dict:
+    instruction_set = task_root / "instruction-set"
+    files = _all_files(instruction_set)
+    file_count, byte_count = _count_files(files)
+    packet = instruction_set / "analysis-packet.md"
+    legacy_packet = instruction_set / "task-packet.md"
+    return {
+        "path": _project_rel(instruction_set, project_root),
+        "fileCount": file_count,
+        "bytes": byte_count,
+        "analysisPacketBytes": _file_size(packet),
+        "legacyTaskPacketBytes": _file_size(legacy_packet),
+    }
+
+
+def _lead_phase1_metric(
+    task_root: Path, run_dir: Path | None, manifest: dict, project_root: Path
+) -> dict:
+    active_path = None
+    artifacts = manifest.get("artifacts", {})
+    active_rel = artifacts.get("activeRunContextPath")
+    if isinstance(active_rel, str) and active_rel:
+        active_path = project_root / active_rel
+
+    if active_path and active_path.is_file():
+        instruction_set = task_root / "instruction-set"
+        packet = instruction_set / "analysis-packet.md"
+        files = [
+            task_root / "task-manifest.json",
+            active_path,
+            instruction_set / "analysis-profile.md",
+            packet if packet.is_file() else instruction_set / "task-brief.md",
+        ]
+        mode = "active-run-context"
+    else:
+        current_phase = manifest.get("workflow", {}).get("currentPhase") or manifest.get("taskType", "")
+        run_manifest = None
+        team_state = None
+        if run_dir is not None:
+            manifests_dir = run_dir / "manifests"
+            state_dir = run_dir / "state"
+            run_manifest = _latest_matching_file(
+                manifests_dir, f"run-manifest-{current_phase}-*.json"
+            )
+            team_state = _latest_matching_file(
+                state_dir, f"team-state-{current_phase}-*.json"
+            )
+        files = [
+            task_root / "task-manifest.json",
+            task_root / "instruction-set" / "task-brief.md",
+            task_root / "instruction-set" / "analysis-profile.md",
+        ]
+        if run_manifest:
+            files.append(run_manifest)
+        if team_state:
+            files.append(team_state)
+        mode = "legacy-five-file"
+
+    file_count, byte_count = _count_files(files)
+    return {
+        "mode": mode,
+        "fileCount": file_count,
+        "bytes": byte_count,
+        "files": [_project_rel(path, project_root) for path in files if path.is_file()],
+    }
+
+
+def _analysis_worker_metric(task_root: Path, project_root: Path) -> dict:
+    instruction_set = task_root / "instruction-set"
+    full_contract_files = [instruction_set / name for name in INPUT_FILES]
+    preamble = Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
+    if not preamble.is_file():
+        repo_preamble = (
+            Path(__file__).resolve().parents[2]
+            / "templates"
+            / "worker-prompt-preamble.md"
+        )
+        preamble = repo_preamble
+    full_contract_files.append(preamble)
+    full_file_count, full_byte_count = _count_files(full_contract_files)
+
+    packet = instruction_set / "analysis-packet.md"
+    legacy_packet = instruction_set / "task-packet.md"
+    primary_packet = packet if packet.is_file() else legacy_packet
+    has_packet = primary_packet.is_file()
+    packet_files = [primary_packet, preamble] if has_packet else []
+    packet_file_count, packet_byte_count = _count_files(packet_files)
+    mode = "analysis-packet-primary" if packet.is_file() else "full-input-contract"
+    byte_count = packet_byte_count if packet.is_file() else full_byte_count
+    file_count = packet_file_count if packet.is_file() else full_file_count
+    current_files = packet_files if packet.is_file() else full_contract_files
+    reduction_percent = 0
+    if full_byte_count and has_packet:
+        reduction_percent = round((1 - packet_byte_count / full_byte_count) * 100)
+
+    return {
+        "mode": mode,
+        "fileCount": file_count,
+        "bytesPerWorker": byte_count,
+        "legacyFullContractBytesPerWorker": full_byte_count,
+        "legacyFullContractFileCount": full_file_count,
+        "estimatedPacketModeBytesPerWorker": packet_byte_count,
+        "estimatedReductionPercent": reduction_percent,
+        "files": [_project_rel(path, project_root) for path in current_files if path.is_file()],
+        "legacyFullContractFiles": [
+            _project_rel(path, project_root)
+            for path in full_contract_files
+            if path.is_file()
+        ],
+    }
+
+
+def _report_writer_metric(run_dir: Path | None, task_root: Path, project_root: Path) -> dict:
+    instruction_set = task_root / "instruction-set"
+    files = [instruction_set / name for name in INPUT_FILES]
+    files.extend([
+        instruction_set / "final-report-template.md",
+        instruction_set / "final-report-schema.json",
+    ])
+    if run_dir is not None:
+        worker_results = run_dir / "worker-results"
+        files.extend(
+            path for path in worker_results.glob("*.md")
+            if "-audit-" not in path.name and "report-writer" not in path.name
+        )
+        convergence = _latest_matching_file(
+            run_dir / "state", f"convergence-{run_dir.name}-*.json"
+        )
+        if convergence:
+            files.append(convergence)
+    file_count, byte_count = _count_files(files)
+    return {
+        "mode": "raw-synthesis-inputs",
+        "fileCount": file_count,
+        "bytes": byte_count,
+        "files": [_project_rel(path, project_root) for path in files if path.is_file()],
+    }
+
+
+def analyze_task_bundle(task_root: Path, project_root: Path) -> dict:
+    manifest = _load_json(task_root / "task-manifest.json")
+    run_dir = _find_current_run_dir(task_root, manifest, project_root)
+    all_task_files = _all_files(task_root)
+    task_file_count, task_bytes = _count_files(all_task_files)
+    current_run_file_count, current_run_bytes = _count_files(_all_files(run_dir)) if run_dir else (0, 0)
+    legacy_timestamp_files = [
+        path for path in (task_root / "runs").rglob("*")
+        if path.is_file() and _is_timestamped_legacy_artifact(path)
+    ]
+
+    return {
+        "ok": True,
+        "taskRoot": _project_rel(task_root, project_root),
+        "projectRoot": str(project_root),
+        "taskKey": manifest.get("taskKey", ""),
+        "taskType": manifest.get("taskType", ""),
+        "currentRunPath": _project_rel(run_dir, project_root) if run_dir else "",
+        "totals": {
+            "taskFileCount": task_file_count,
+            "taskBytes": task_bytes,
+            "currentRunFileCount": current_run_file_count,
+            "currentRunBytes": current_run_bytes,
+            "legacyTimestampFileCount": len(legacy_timestamp_files),
+        },
+        "instructionSet": _instruction_set_metric(task_root, project_root),
+        "leadPhase1": _lead_phase1_metric(task_root, run_dir, manifest, project_root),
+        "analysisWorker": _analysis_worker_metric(task_root, project_root),
+        "reportWriter": _report_writer_metric(run_dir, task_root, project_root),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Estimate context/file-read cost for an okstra task bundle."
+    )
+    parser.add_argument("target", help="task root path or task-key")
+    parser.add_argument("--project-root", default="", help="project root for task-key lookup")
+    parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
+    args = parser.parse_args(argv)
+
+    task_root, project_root = _resolve_task_root(args.target, args.project_root, args.cwd)
+    result = analyze_task_bundle(task_root, project_root)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/migrate.py

@@ -23,6 +23,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Optional
 
+from okstra_ctl.worktree import is_git_work_tree
 from okstra_project.dirs import (
     LEGACY_OKSTRA_DIR_NAME,
     LEGACY_OKSTRA_RELATIVE,
@@ -112,7 +113,7 @@ def prepare_migration_plan(
             f"Remove it manually if you intend to overwrite, then re-run."
         )
 
-    use_git = _is_git_worktree(project_root)
+    use_git = is_git_work_tree(project_root)
     parent = source.parent  # <project>/.project-docs
     remove_empty_parent = _would_be_empty_after_remove(parent, source)
 
@@ -194,17 +195,6 @@ def _resolve_okstra_home(override: Optional[Path]) -> Path:
     return Path.home() / ".okstra"
 
 
-def _is_git_worktree(project_root: Path) -> bool:
-    try:
-        rc = subprocess.run(
-            ["git", "rev-parse", "--show-toplevel"],
-            cwd=str(project_root), capture_output=True, text=True, check=False,
-        )
-    except (OSError, FileNotFoundError):
-        return False
-    return rc.returncode == 0 and bool(rc.stdout.strip())
-
-
 def _would_be_empty_after_remove(parent: Path, child: Path) -> bool:
     """Return True if `parent` would be empty after `child` is moved out."""
     if not parent.is_dir():

package/runtime/python/okstra_ctl/paths.py

@@ -31,9 +31,25 @@ __all__ = [
     "DISCOVERY_RELATIVE",
     "compute_run_paths",
     "next_run_seq",
+    "task_dir",
+    "task_runs_dir",
 ]
 
 
+def task_dir(project_root: Path, task_group: str, task_id: str) -> Path:
+    """task root 경로: ``<project>/.okstra/tasks/<group-seg>/<id-seg>``.
+
+    raw group/id 를 받아 내부에서 slugify 한다 — compute_run_paths 가 쓰는 것과
+    동일한 segment 규칙이다. 과거 sequence/wizard 가 이 구조를 손으로 재유도해
+    silent drift 위험이 있던 것을 이 SSOT 로 모은다."""
+    return Path(project_root) / TASKS_RELATIVE / slugify(task_group) / slugify(task_id)
+
+
+def task_runs_dir(project_root: Path, task_group: str, task_id: str) -> Path:
+    """task 의 runs 디렉터리: ``task_dir/runs``."""
+    return task_dir(project_root, task_group, task_id) / "runs"
+
+
 def next_run_seq(run_seq_dir: Path, task_type_segment: str) -> int:
     """run_seq_dir 안에서 `*-<task-type>-NNN.<ext>` 파일을 스캔해 다음 seq 번호를
     돌려준다. 디렉터리 부재 시 1.
@@ -100,6 +116,7 @@ def compute_run_paths(
     task_manifest = task_root / "task-manifest.json"
     task_index = task_root / "task-index.md"
     instruction_set = task_root / "instruction-set"
+    analysis_packet = instruction_set / "analysis-packet.md"
     runs_dir = task_root / "runs"
     history_dir = task_root / "history"
     timeline_file = history_dir / "timeline.json"
@@ -143,6 +160,7 @@ def compute_run_paths(
     final_report = run_reports / f"final-report{suffixes['reports']}.md"
     final_status = run_status / f"final{suffixes['status']}.status"
     team_state = run_state / f"team-state{suffixes['state']}.json"
+    active_run_context = run_state / f"active-run-context{suffixes['state']}.json"
     final_report_template = instruction_set / "final-report-template.md"
     final_report_schema = instruction_set / "final-report-schema.json"
     reference_expectations = instruction_set / "reference-expectations.md"
@@ -183,6 +201,7 @@ def compute_run_paths(
         "TASK_MANIFEST_PATH": str(task_manifest),
         "TASK_INDEX_PATH": str(task_index),
         "INSTRUCTION_SET_PATH": str(instruction_set),
+        "ANALYSIS_PACKET_PATH": str(analysis_packet),
         "RUNS_DIR": str(runs_dir),
         "HISTORY_DIR": str(history_dir),
         "TIMELINE_PATH": str(timeline_file),
@@ -205,6 +224,7 @@ def compute_run_paths(
         "FINAL_REPORT_PATH": str(final_report),
         "FINAL_STATUS_PATH": str(final_status),
         "TEAM_STATE_PATH": str(team_state),
+        "ACTIVE_RUN_CONTEXT_PATH": str(active_run_context),
         "FINAL_REPORT_TEMPLATE_PATH": str(final_report_template),
         "FINAL_REPORT_SCHEMA_PATH": str(final_report_schema),
         "REFERENCE_EXPECTATIONS_FILE": str(reference_expectations),
@@ -244,6 +264,7 @@ def compute_run_paths(
         ("TASK_MANIFEST_RELATIVE_PATH", task_manifest),
         ("TASK_INDEX_RELATIVE_PATH", task_index),
         ("INSTRUCTION_SET_RELATIVE_PATH", instruction_set),
+        ("ANALYSIS_PACKET_RELATIVE_PATH", analysis_packet),
         ("RUNS_RELATIVE_PATH", runs_dir),
         ("HISTORY_RELATIVE_PATH", history_dir),
         ("TIMELINE_RELATIVE_PATH", timeline_file),
@@ -263,6 +284,7 @@ def compute_run_paths(
         ("FINAL_REPORT_RELATIVE_PATH", final_report),
         ("FINAL_STATUS_RELATIVE_PATH", final_status),
         ("TEAM_STATE_RELATIVE_PATH", team_state),
+        ("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", active_run_context),
         ("WORKER_RESULTS_RELATIVE_PATH", worker_results),
         ("RUN_CARRY_RELATIVE_PATH", run_carry),
         ("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", final_report_template),