npm - okstra - Versions diffs - 0.50.0 → 0.52.0 - Mend

okstra 0.50.0 → 0.52.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/README.kr.md +8 -7
package/README.md +8 -7
package/bin/okstra +2 -0
package/docs/kr/architecture.md +15 -16
package/docs/kr/cli.md +5 -5
package/docs/project-structure-overview.md +10 -6
package/docs/superpowers/specs/2026-06-06-vertical-slice-tdd-planning-design.md +179 -0
package/package.json +1 -1
package/runtime/BUILD.json +2 -2
package/runtime/agents/SKILL.md +15 -11
package/runtime/agents/workers/claude-worker.md +3 -3
package/runtime/agents/workers/codex-worker.md +2 -2
package/runtime/agents/workers/gemini-worker.md +2 -2
package/runtime/bin/lib/okstra/cli.sh +8 -1
package/runtime/bin/lib/okstra/globals.sh +3 -0
package/runtime/bin/lib/okstra/interactive.sh +14 -12
package/runtime/bin/lib/okstra/usage.sh +6 -0
package/runtime/bin/okstra-team-reconcile.sh +28 -0
package/runtime/bin/okstra.sh +2 -0
package/runtime/prompts/launch.template.md +3 -1
package/runtime/prompts/profiles/_common-contract.md +4 -4
package/runtime/prompts/profiles/_implementation-executor.md +2 -2
package/runtime/prompts/profiles/_implementation-verifier.md +1 -1
package/runtime/prompts/profiles/implementation-planning.md +8 -4
package/runtime/prompts/profiles/implementation.md +1 -1
package/runtime/python/okstra_ctl/analysis_packet.py +259 -0
package/runtime/python/okstra_ctl/context_cost.py +308 -0
package/runtime/python/okstra_ctl/migrate.py +2 -12
package/runtime/python/okstra_ctl/paths.py +22 -0
package/runtime/python/okstra_ctl/render.py +284 -125
package/runtime/python/okstra_ctl/render_final_report.py +31 -0
package/runtime/python/okstra_ctl/run.py +507 -245
package/runtime/python/okstra_ctl/sequence.py +2 -5
package/runtime/python/okstra_ctl/team_reconcile.py +131 -0
package/runtime/python/okstra_ctl/wizard.py +129 -133
package/runtime/python/okstra_ctl/worktree.py +13 -5
package/runtime/schemas/final-report-v1.0.schema.json +4 -0
package/runtime/skills/okstra-coding-preflight/SKILL.md +69 -0
package/runtime/skills/okstra-coding-preflight/architecture/hexagonal.md +116 -0
package/runtime/skills/okstra-coding-preflight/clean-code.md +254 -0
package/runtime/skills/okstra-coding-preflight/languages/java.md +64 -0
package/runtime/skills/okstra-coding-preflight/languages/javascript-typescript.md +87 -0
package/runtime/skills/okstra-coding-preflight/languages/kotlin.md +69 -0
package/runtime/skills/okstra-coding-preflight/languages/nodejs.md +66 -0
package/runtime/skills/okstra-coding-preflight/languages/python.md +179 -0
package/runtime/skills/okstra-coding-preflight/languages/rust.md +105 -0
package/runtime/skills/okstra-coding-preflight/languages/sql.md +68 -0
package/runtime/skills/okstra-context-loader/SKILL.md +12 -6
package/runtime/skills/okstra-inspect/SKILL.md +100 -1
package/runtime/skills/okstra-memory/SKILL.md +28 -5
package/runtime/skills/okstra-report-writer/SKILL.md +5 -1
package/runtime/skills/okstra-run/SKILL.md +1 -1
package/runtime/skills/okstra-team-contract/SKILL.md +7 -4
package/runtime/templates/reports/final-report.template.md +1 -0
package/runtime/templates/worker-prompt-preamble.md +3 -3
package/runtime/validators/validate-implementation-plan-stages.py +57 -11
package/src/_python-helper.mjs +3 -3
package/src/context-cost.mjs +27 -0
package/src/install.mjs +1 -0
package/src/memory.mjs +50 -11
package/src/uninstall.mjs +1 -0

package/runtime/python/okstra_ctl/analysis_packet.py ADDED Viewed

@@ -0,0 +1,259 @@
+"""Build the compact analysis-worker input packet for a task run."""
+from __future__ import annotations
+import re
+from pathlib import Path
+BRIEF_SECTIONS = (
+    "Identity",
+    "Request Summary",
+    "Current Context",
+    "Evidence and Source Materials",
+    "Task-Type Focus",
+    "Constraints and Risks",
+    "Out of Scope",
+    "Configuration References and Expected Values",
+    "Deployment Manifests and Expected Values",
+    "Questions for Workers",
+    "Expected Outputs",
+    "Task Continuity Notes",
+    "Available MCP Servers",
+)
+PROFILE_SECTIONS = (
+    "Primary focus areas",
+    "Expected output emphasis",
+    "Non-goals",
+    "Clarification request policy",
+)
+CLARIFICATION_SECTIONS = (
+    "Clarification Items",
+    "Clarification Response Carried In From Previous Run",
+)
+_FRONTMATTER_RE = re.compile(r"\A---\n(?P<body>.*?)\n---\n", re.DOTALL)
+def build_analysis_packet(
+    *,
+    task_key: str,
+    task_type: str,
+    task_brief_path: Path,
+    analysis_profile_path: Path,
+    reference_expectations_path: Path,
+    clarification_response_path: Path | None,
+    directive: str,
+    instruction_set_relative_path: str,
+) -> str:
+    """Return the primary compact input for Claude/Codex/Gemini analysers."""
+    brief_text = task_brief_path.read_text(encoding="utf-8")
+    profile_text = analysis_profile_path.read_text(encoding="utf-8")
+    reference_text = _read_optional(reference_expectations_path)
+    clarification_text = (
+        _read_optional(clarification_response_path)
+        if clarification_response_path else ""
+    )
+    parts = [_packet_frontmatter(brief_text, task_key)]
+    parts.extend(
+        _intro_block(
+            task_key,
+            instruction_set_relative_path,
+            bool(clarification_response_path),
+        )
+    )
+    parts.extend(_brief_block(brief_text))
+    parts.extend(_profile_block(task_type, profile_text))
+    parts.extend(_reference_block(reference_text))
+    parts.extend(_clarification_block(clarification_text))
+    parts.extend(_directive_block(directive))
+    return "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
+def _packet_frontmatter(brief_text: str, task_key: str) -> str:
+    frontmatter = _extract_frontmatter(brief_text)
+    if frontmatter:
+        return (
+            f"---\n{frontmatter}\n"
+            'packetVersion: "1.0"\n'
+            "packetRole: analysis-worker-primary\n---"
+        )
+    return (
+        "---\n"
+        f'title: OKSTRA Analysis Packet - {task_key}\n'
+        'packetVersion: "1.0"\n'
+        "packetRole: analysis-worker-primary\n"
+        "---"
+    )
+def _intro_block(
+    task_key: str,
+    instruction_set: str,
+    has_clarification: bool,
+) -> list[str]:
+    lines = [
+        f"# OKSTRA Analysis Packet - {task_key}",
+        "",
+        "## Packet Role",
+        "",
+        "- This packet is the primary required reading for analysis workers.",
+        "- It extracts task-specific material from the source files listed below.",
+        "- Read source files only for evidence verification or missing detail.",
+        "",
+        "## Source Files",
+        "",
+        f"- Task brief: `{instruction_set}/task-brief.md`",
+        f"- Analysis profile: `{instruction_set}/analysis-profile.md`",
+        f"- Analysis material: `{instruction_set}/analysis-material.md`",
+        f"- Reference expectations: `{instruction_set}/reference-expectations.md`",
+    ]
+    if has_clarification:
+        lines.append(
+            f"- Clarification response: `{instruction_set}/clarification-response.md`"
+        )
+    return lines
+def _brief_block(brief_text: str) -> list[str]:
+    return [
+        "",
+        "## Task-Specific Brief Extract",
+        "",
+        _extract_sections(brief_text, BRIEF_SECTIONS),
+    ]
+def _profile_block(task_type: str, profile_text: str) -> list[str]:
+    profile_sections = _extract_sections(profile_text, PROFILE_SECTIONS)
+    profile_bullets = _extract_bullet_sections(profile_text, PROFILE_SECTIONS)
+    profile_focus = "\n\n".join(
+        part for part in (profile_sections, profile_bullets)
+        if part and not part.startswith("- No matching")
+    )
+    return [
+        "",
+        "## Phase Focus Extract",
+        "",
+        f"- Task Type: `{task_type}`",
+        "",
+        _extract_profile_prelude(profile_text),
+        "",
+        profile_focus or "- No matching source sections were available.",
+    ]
+def _reference_block(reference_text: str) -> list[str]:
+    body = reference_text.strip() or "- No reference expectations content was available."
+    return ["", "## Reference Expectations", "", body]
+def _clarification_block(clarification_text: str) -> list[str]:
+    if not clarification_text.strip():
+        return []
+    return [
+        "",
+        "## Clarification Carry-In Extract",
+        "",
+        _extract_sections(clarification_text, CLARIFICATION_SECTIONS),
+    ]
+def _directive_block(directive: str) -> list[str]:
+    if not directive:
+        return []
+    return ["", "## Directive", "", directive.strip()]
+def _extract_frontmatter(text: str) -> str:
+    match = _FRONTMATTER_RE.match(text)
+    return match.group("body").rstrip() if match else ""
+def _extract_profile_prelude(text: str) -> str:
+    lines = []
+    for line in text.splitlines():
+        if line.startswith(("{{INCLUDE:", "## ", "<!--", "- Team contract")):
+            break
+        if _top_level_bullet_heading(line) in PROFILE_SECTIONS:
+            break
+        if line.strip():
+            lines.append(line)
+    return "\n".join(lines).strip() or "- No profile prelude was available."
+def _extract_sections(text: str, headings: tuple[str, ...]) -> str:
+    sections = _section_map(text)
+    out = []
+    for heading in headings:
+        body = sections.get(heading, "").strip()
+        if body:
+            out.append(f"### {heading}\n\n{body}")
+    return "\n\n".join(out) or "- No matching source sections were available."
+def _extract_bullet_sections(text: str, headings: tuple[str, ...]) -> str:
+    heading_set = set(headings)
+    captured: list[tuple[str, list[str]]] = []
+    current_heading = ""
+    current_lines: list[str] = []
+    def flush_current() -> None:
+        nonlocal current_heading, current_lines
+        if current_heading and current_lines:
+            captured.append((current_heading, current_lines))
+        current_heading = ""
+        current_lines = []
+    for line in _strip_frontmatter(text).splitlines():
+        bullet_heading = _top_level_bullet_heading(line)
+        if bullet_heading:
+            if bullet_heading in heading_set:
+                flush_current()
+                current_heading = bullet_heading
+                current_lines = [line]
+                continue
+            flush_current()
+            continue
+        if current_heading:
+            if line.startswith("  ") or not line.strip():
+                current_lines.append(line)
+            else:
+                flush_current()
+    flush_current()
+    out = []
+    for heading, lines in captured:
+        body = "\n".join(lines).strip()
+        if body:
+            out.append(f"### {heading}\n\n{body}")
+    return "\n\n".join(out)
+def _top_level_bullet_heading(line: str) -> str:
+    if not line.startswith("- ") or ":" not in line:
+        return ""
+    label = line[2:].split(":", 1)[0].strip().strip("*")
+    return label
+def _section_map(text: str) -> dict[str, str]:
+    result: dict[str, list[str]] = {}
+    current = ""
+    for line in _strip_frontmatter(text).splitlines():
+        if line.startswith("## "):
+            current = line[3:].strip()
+            result.setdefault(current, [])
+            continue
+        if current:
+            result[current].append(line)
+    return {key: "\n".join(lines).strip() for key, lines in result.items()}
+def _strip_frontmatter(text: str) -> str:
+    match = _FRONTMATTER_RE.match(text)
+    return text[match.end():] if match else text
+def _read_optional(path: Path | None) -> str:
+    if path and path.is_file():
+        return path.read_text(encoding="utf-8")
+    return ""

package/runtime/python/okstra_ctl/context_cost.py ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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),