okstra 0.206.0 → 0.206.1

package/runtime/python/okstra_ctl/phases/implementation_planning/boundary.json

@@ -0,0 +1,12 @@
+{
+  "allowed": "  - pre-planning context exploration notes (files/interfaces inspected, recent commits scanned, ambiguities flagged)\n  - selected-direction planning: realize the one validated selected direction without reopening candidate comparison, with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n  - legacy candidate-comparison planning only: at least two implementation option candidates, each with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n  - legacy candidate-comparison planning only: a trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n  - bite-sized stepwise execution order for the selected direction or legacy recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `5.5.x` — the unified table is the single home)\n  - report record `frontmatter.approved: false` awaiting `--approve` or the in-session wizard\n  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)\n  - one endStateCoverage row per brief end-state id, each mapped to the R-NNN row that carries it",
+  "forbidden": [
+    "source code edits of any kind (Edit/Write on project source files is forbidden)",
+    "file writes outside the run`s artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`), including task-root QA scripts, manifest, and tsconfig (planning declares conformance commands and required dependencies; implementation writes these files); in particular, do not write to `docs/superpowers/specs/` or `docs/superpowers/plans/`",
+    "executing builds, migrations, deployments, or any state-mutating command",
+    "starting `implementation` inside this run (must be a separate run authorised by an approved deliverable from this phase), even if the user says \"다음 단계 진행해\"",
+    "dispatching parallel sub-agents beyond the required worker roster (okstra owns worker fan-out)",
+    "leaving placeholders such as TBD / TODO / \"handle edge cases\" / \"similar to Option N\" in the report",
+    "delegating the self-review pass — the Okstra lead must run it"
+  ]
+}

package/runtime/python/okstra_ctl/phases/implementation_planning/entry.py

@@ -0,0 +1,161 @@
+"""구현 계획의 신규 진입·재실행 입력을 검증한다."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Protocol
+
+from okstra_ctl.prepare_error import PrepareError
+from okstra_ctl.incremental_scope import ReverifyScopeError, parse_user_reverify_scope
+from okstra_ctl.implementation_direction import (
+    DirectionSelectionError,
+    SelectedDirection,
+    lexical_absolute_path,
+    resolve_selected_direction,
+    validate_task_artifact_path,
+)
+
+class PlanningInputs(Protocol):
+    """공통 준비 입력 중 계획 진입 정책이 읽는 필드."""
+
+    project_root: str | Path
+    project_id: str
+    task_group: str
+    task_id: str
+    task_type: str
+    selected_direction_path: str
+    clarification_response_path: str
+    reverify_scope: str
+
+
+_PLANNING_REPORT_RE = re.compile(
+    r"^final-report-implementation-planning-\d{3,}\.(?:md|data\.json)$"
+)
+
+
+def _resolve_planning_input_path(path_value: str, project_root: Path) -> Path | None:
+    """Resolve cwd-first planning inputs without following symbolic links."""
+    raw_path = Path(path_value).expanduser()
+    cwd_candidate = lexical_absolute_path(raw_path)
+    if cwd_candidate.is_file():
+        return cwd_candidate
+    if not raw_path.is_absolute():
+        project_candidate = lexical_absolute_path(project_root / raw_path)
+        if project_candidate.is_file():
+            return project_candidate
+    return None
+
+
+def _is_existing_planning_report(
+    path_value: str, project_root: Path, inp: PlanningInputs
+) -> bool:
+    from okstra_ctl.paths import task_dir
+
+    try:
+        report = lexical_absolute_path(Path(path_value))
+        task_root = lexical_absolute_path(
+            task_dir(project_root, inp.task_group, inp.task_id)
+        )
+        relative = report.relative_to(task_root)
+    except ValueError:
+        return False
+    has_planning_layout = (
+        _PLANNING_REPORT_RE.fullmatch(report.name) is not None
+        and relative.parts[:3]
+        == (
+            "runs",
+            "implementation-planning",
+            "reports",
+        )
+        and len(relative.parts) == 4
+    )
+    if not has_planning_layout:
+        return False
+    try:
+        validate_task_artifact_path(report, task_root, "planning report")
+    except DirectionSelectionError:
+        return False
+    return True
+
+
+def _validate_planning_entry_inputs(project_root: Path, inp: PlanningInputs) -> None:
+    if inp.task_type != "implementation-planning":
+        if inp.selected_direction_path:
+            raise PrepareError(
+                "--selected-direction is only meaningful with --task-type "
+                f"implementation-planning; got {inp.task_type}"
+            )
+        return
+    if inp.selected_direction_path and inp.clarification_response_path:
+        raise PrepareError(
+            "implementation-planning accepts either --selected-direction for a "
+            "new plan or --clarification-response for a rerun, not both"
+        )
+    if inp.selected_direction_path:
+        return
+    if inp.clarification_response_path:
+        if not _is_existing_planning_report(
+            inp.clarification_response_path, project_root, inp
+        ):
+            raise PrepareError(
+                "implementation-planning rerun --clarification-response must point "
+                "to an existing implementation-planning report for the same task"
+            )
+        return
+    raise PrepareError(
+        "implementation-planning requires --selected-direction for a new plan or "
+        "--clarification-response to an existing implementation-planning report"
+    )
+
+
+def _resolve_planning_direction(inp: PlanningInputs) -> SelectedDirection | None:
+    if inp.task_type != "implementation-planning" or not inp.selected_direction_path:
+        return None
+    from okstra_ctl.paths import task_dir
+
+    try:
+        report = lexical_absolute_path(Path(inp.selected_direction_path))
+        expected_task_root = lexical_absolute_path(
+            task_dir(Path(inp.project_root), inp.task_group, inp.task_id)
+        )
+        report.relative_to(expected_task_root)
+    except ValueError as exc:
+        raise PrepareError(
+            "selected direction report must belong to the same task"
+        ) from exc
+    try:
+        validate_task_artifact_path(
+            report, expected_task_root, "selected direction report"
+        )
+        return resolve_selected_direction(
+            report,
+            expected_task_key=(f"{inp.project_id}:{inp.task_group}:{inp.task_id}"),
+        )
+    except DirectionSelectionError as exc:
+        raise PrepareError(str(exc)) from exc
+
+
+def _validate_reverify_scope(inp: PlanningInputs) -> None:
+    """A pinned re-verification scope is only actionable on a planning re-run.
+
+    Every other phase renders the tokens too (the template always reads them),
+    but nothing consumes them there — so a value outside the one phase that
+    acts on it is a caller mistake, not a preference to honour silently.
+    """
+    if not (inp.reverify_scope or "").strip():
+        return
+    if inp.task_type != "implementation-planning":
+        raise PrepareError(
+            "--reverify-scope is only meaningful with --task-type "
+            f"implementation-planning; got {inp.task_type}"
+        )
+    if not inp.clarification_response_path:
+        raise PrepareError(
+            "--reverify-scope needs --clarification-response: there is no prior "
+            "report to narrow re-verification against"
+        )
+    try:
+        parse_user_reverify_scope(inp.reverify_scope)
+    except ReverifyScopeError as exc:
+        raise PrepareError(str(exc)) from exc

package/runtime/python/okstra_ctl/phases/implementation_planning/guidance.py

@@ -0,0 +1,178 @@
+"""구현 계획의 의존·결정 기록과 사용자 승인 안내 규칙."""
+
+from __future__ import annotations
+
+import re
+
+from okstra_ctl.clarification_items import APPROVAL_BLOCKS, progress_blocking_ids
+from okstra_ctl.plan_approval import plan_is_approved
+
+
+def _validate_implementation_planning_cross_project(
+    data: dict, failures: list[str]
+) -> None:
+    """타 프로젝트 의존을 DM 행(`kind == 'cross-project'`)으로 선언했다면
+    `crossProjectDependencies` 에 `direction == 'upstream-precondition'` 행이
+    반드시 있어야 한다 — 실제 선행 필수 의존이 soft `recommendedNextSteps`
+    추천으로 새어나가지 못하게 강제한다. 각 XP 행의 필드 비-빈은 스키마가
+    보장하고, 이 검사는 cross-project DM 신호가 있을 때 XP 행이 *존재*하는지를 본다.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    dm_rows = ip.get("dependencyMigrationRisk") or []
+    has_cross_project_dm = any(
+        isinstance(r, dict) and r.get("kind") == "cross-project" for r in dm_rows
+    )
+    if not has_cross_project_dm:
+        return
+    xp_rows = ip.get("crossProjectDependencies") or []
+    has_upstream = any(
+        isinstance(r, dict) and r.get("direction") == "upstream-precondition"
+        for r in xp_rows
+    )
+    if not has_upstream:
+        failures.append(
+            "final-report data.json: a dependencyMigrationRisk row has "
+            "kind='cross-project' but crossProjectDependencies carries no "
+            "direction='upstream-precondition' entry. Record the cross-project "
+            "dependency as a mandatory precondition (concrete requiredWork / "
+            "verificationSignal / howToStart) — not a soft Recommended Next Step."
+        )
+
+
+def _validate_implementation_planning_decision_drafts(
+    data: dict, failures: list[str]
+) -> None:
+    """`decisionDrafts` 가 비어있지 않으면 어느 stage 의 stepwiseExecution step 이
+    `.okstra/decisions/` 파일을 생성하는 materialization step 을 포함해야 한다.
+    프로파일 Decision-record evaluation 의 "approved plan stepwise MUST include
+    Create .okstra/decisions/<NNNN>-<slug>.md" 를 실제 강제한다. draft 존재 자체가
+    trigger 이므로 self-contained 하다.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    if not (ip.get("decisionDrafts") or []):
+        return
+    has_materialization = any(
+        ".okstra/decisions/" in (step.get("files") or "")
+        or ".okstra/decisions/" in (step.get("action") or "")
+        for stage in (ip.get("stages") or [])
+        if isinstance(stage, dict)
+        for step in (stage.get("stepwiseExecution") or [])
+        if isinstance(step, dict)
+    )
+    if not has_materialization:
+        failures.append(
+            "final-report data.json: implementationPlanning.decisionDrafts is "
+            "non-empty but no stage's stepwiseExecution creates a "
+            "`.okstra/decisions/<NNNN>-<slug>.md` file. The approved plan must "
+            "materialize each decision draft via a stepwise step (profile "
+            "Decision-record evaluation)."
+        )
+
+
+_RERUN_FLAG = "--answered-clarifications"
+_USER_RESPONSE_HINT = re.compile(r"okstra-user-response", re.IGNORECASE)
+_APPROVE_HINT = re.compile(r"--approve|\bapprov", re.IGNORECASE)
+
+
+def _next_step_texts(steps: object) -> list[str]:
+    """Every reader-visible string in `recommendedNextSteps`, prose and command."""
+    texts: list[str] = []
+    for step in steps if isinstance(steps, list) else []:
+        if not isinstance(step, dict):
+            continue
+        texts.append(str(step.get("text") or ""))
+        for command in step.get("commands") or []:
+            if isinstance(command, dict):
+                texts.append(str(command.get("claudeCode") or ""))
+                texts.append(str(command.get("terminal") or ""))
+    return texts
+
+
+def _has_unresolved_approval_blocker(data: dict) -> bool:
+    return bool(
+        progress_blocking_ids(
+            data.get("clarificationItems"),
+            APPROVAL_BLOCKS,
+            report_data=data,
+        )
+    )
+
+
+def _planning_gate_blocks_approval(data: dict) -> bool:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return False
+    verification = planning.get("planBodyVerification")
+    if not isinstance(verification, dict):
+        return False
+    gate = str(verification.get("gateResult") or "").strip().lower()
+    if gate == "aborted-non-result":
+        return True
+    if gate != "blocked-by-disagreement":
+        return False
+    return _has_unresolved_approval_blocker(data) or not any(
+        isinstance(row, dict) and row.get("blocks") == "approval"
+        for row in data.get("clarificationItems") or []
+    )
+
+
+def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
+    """A report that withholds approval must say how to come back from it.
+
+    The way forward — answer the blockers, then re-run carrying those ids —
+    lived only in the lead prompt, which is read *after* the next run has
+    already started. The person who has to act reads the report instead, and it
+    told them nothing about the next command. Requiring the flag by name is a
+    low bar deliberately: it does not check that the rest of the step is right,
+    only that the report stops leaving the reader to work the mechanics out.
+    """
+    if (data.get("header") or {}).get("taskType") != "implementation-planning":
+        return
+    if not _has_unresolved_approval_blocker(data):
+        return
+    texts = _next_step_texts(data.get("recommendedNextSteps"))
+    if any(_RERUN_FLAG in text for text in texts) and any(
+        _USER_RESPONSE_HINT.search(text) for text in texts
+    ):
+        return
+    failures.append(
+        "final-report data.json: this plan withholds approval on an unresolved "
+        "`blocks: approval` clarification, but no `recommendedNextSteps` entry "
+        "tells the reader the command to run now — name `/okstra-user-response` "
+        f"and the `{_RERUN_FLAG}` re-run in a step's `text` or one of its "
+        "`commands`. `okstra recap assemble` prints the exact ids and flag "
+        "value once the answers are recorded."
+    )
+
+
+def _validate_approval_guidance(data: dict, failures: list[str]) -> None:
+    """승인 가능한 plan-ready 는 사용자에게 승인하라고 말해야 한다.
+
+    포인터가 implementation/ready 여도 승인은 사용자만 뒤집는다. 다음 단계
+    안내가 계획 재실행이면 승인 칸을 건너뛰고 같은 단계를 다시 돈다.
+    """
+    if (data.get("header") or {}).get("taskType") != "implementation-planning":
+        return
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict) or planning.get("outcome") != "plan-ready":
+        return
+    if _has_unresolved_approval_blocker(data) or _planning_gate_blocks_approval(data):
+        return
+    if plan_is_approved(data):
+        return
+    if any(
+        _APPROVE_HINT.search(text)
+        for text in _next_step_texts(data.get("recommendedNextSteps"))
+    ):
+        return
+    failures.append(
+        "final-report data.json: this plan is ready for the user to approve, "
+        "but no `recommendedNextSteps` entry tells the reader to approve — "
+        "name `--approve` or the in-session wizard in a step's `text` or "
+        "one of its `commands`. Do not recommend another "
+        "implementation-planning run."
+    )