okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/write_policy.py

@@ -0,0 +1,571 @@
+"""Canonical invocation write policy and truthful runner enforcement."""
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+BoundaryPrecision = Literal["exact-path", "directory-boundary", "none"]
+
+_PRECISION_RANK = {"none": 0, "directory-boundary": 1, "exact-path": 2}
+_POLICY_KEYS = {
+    "artifactPolicy",
+    "sourcePolicy",
+    "gitPolicy",
+    "auxiliaryPolicy",
+}
+_ENFORCEMENT_KEYS = {
+    "boundaryPrecision",
+    "mutationAudit",
+    "attribution",
+    "auditedRoots",
+    "observationCoverage",
+    "unobservedWriteSurfaces",
+}
+
+
+class WritePolicyError(ValueError):
+    """Raised when a write policy cannot be made canonical or trustworthy."""
+
+
+@dataclass(frozen=True)
+class WritePolicy:
+    artifact_policy: Mapping[str, Any]
+    source_policy: Mapping[str, Any]
+    git_policy: Mapping[str, Any]
+    auxiliary_policy: Mapping[str, Any]
+    maximum_boundary_precision: BoundaryPrecision = "none"
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "artifactPolicy": dict(self.artifact_policy),
+            "sourcePolicy": dict(self.source_policy),
+            "gitPolicy": dict(self.git_policy),
+            "auxiliaryPolicy": dict(self.auxiliary_policy),
+        }
+
+    @property
+    def digest(self) -> str:
+        return write_policy_digest(self.to_payload())
+
+    @property
+    def source_mode(self) -> str:
+        return str(self.source_policy["mode"])
+
+
+@dataclass(frozen=True)
+class WriteEnforcement:
+    boundary_precision: BoundaryPrecision
+    mutation_audit: Literal["none", "batch"]
+    attribution: Literal["call", "batch-unattributed"]
+    audited_roots: tuple[Path, ...]
+    observation_coverage: Literal["complete", "scoped", "partial"]
+    unobserved_write_surfaces: tuple[str, ...]
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "boundaryPrecision": self.boundary_precision,
+            "mutationAudit": self.mutation_audit,
+            "attribution": self.attribution,
+            "auditedRoots": [str(path) for path in self.audited_roots],
+            "observationCoverage": self.observation_coverage,
+            "unobservedWriteSurfaces": list(self.unobserved_write_surfaces),
+        }
+
+
+def build_write_policy(
+    invocation: Mapping[str, Any],
+    assignment: Mapping[str, Any],
+    worktree: Path | None,
+) -> WritePolicy:
+    """Build one provider-neutral policy from invocation and adapter authority."""
+    role = _required_text(invocation, "role")
+    project_root = Path(_required_text(invocation, "projectRoot")).resolve()
+    source_root = _trusted_root(invocation, worktree)
+    artifact_paths = _relative_paths(invocation.get("artifactPaths", ()))
+    if not artifact_paths:
+        raise WritePolicyError("artifactPaths must contain standard worker artifacts")
+    source_mode = "project-mutation" if role == "implementer" else "source-readonly"
+    source_policy: dict[str, Any] = {
+        "mode": source_mode,
+        "allowedRoot": str(source_root),
+        "plannedPaths": list(_relative_paths(invocation.get("plannedPaths", ()))),
+        "protectedPaths": list(
+            _relative_paths(invocation.get("protectedPaths", (".okstra", ".git")))
+        ),
+    }
+    git_policy = _git_policy(invocation, source_root, source_mode)
+    external_roots = _validated_auxiliary_roots(invocation, assignment)
+    auxiliary_policy = {
+        "scratchRoots": [
+            str(path) for path in _absolute_roots(invocation.get("scratchRoots", ()))
+        ],
+        "generatedPaths": list(
+            _relative_paths(invocation.get("generatedPaths", ()))
+        ),
+        "externalRoots": [str(path) for path in external_roots],
+    }
+    policy = WritePolicy(
+        artifact_policy={
+            "allowedRoot": str(project_root),
+            "allowedPaths": list(artifact_paths),
+        },
+        source_policy=source_policy,
+        git_policy=git_policy,
+        auxiliary_policy=auxiliary_policy,
+        maximum_boundary_precision=_assignment_precision(assignment),
+    )
+    validate_write_policy_payload(policy.to_payload())
+    return policy
+
+
+def build_invocation_write_contract(
+    *,
+    role: str,
+    project_root: Path,
+    worktree: Path | None,
+    artifact_paths: Sequence[Path],
+    maximum_precision: BoundaryPrecision,
+    planned_paths: Sequence[str] = (),
+    scratch_roots: Sequence[Path] = (),
+    generated_paths: Sequence[str] = (),
+    auxiliary_roots: Sequence[Path] = (),
+    validated_auxiliary_roots: Sequence[Path] = (),
+) -> tuple[WritePolicy, WriteEnforcement]:
+    """Build the single canonical contract used by every v2 dispatcher."""
+    root = project_root.resolve()
+    relative_artifacts = tuple(
+        _relative_to_root(path, root, "artifact") for path in artifact_paths
+    )
+    invocation: dict[str, Any] = {
+        "role": role,
+        "projectRoot": str(root),
+        "artifactPaths": list(relative_artifacts),
+        "plannedPaths": list(planned_paths),
+        "protectedPaths": [".okstra", ".git"],
+        "generatedPaths": list(generated_paths),
+        "scratchRoots": [str(path) for path in scratch_roots],
+        "auxiliaryRoots": [str(path) for path in auxiliary_roots],
+    }
+    source_root = worktree.resolve() if worktree is not None else root
+    if role == "implementer":
+        invocation.update({
+            "expectedBaseCommit": _git_output(source_root, "rev-parse", "HEAD"),
+            "allowedBranchRef": _git_output(
+                source_root, "symbolic-ref", "-q", "HEAD"
+            ),
+        })
+    assignment = {
+        "workerWriteCapability": {
+            "maxBoundaryPrecision": maximum_precision,
+        },
+        "validatedAuxiliaryRoots": [str(path) for path in validated_auxiliary_roots],
+    }
+    policy = build_write_policy(invocation, assignment, source_root)
+    return policy, derive_write_enforcement(policy, maximum_precision, role=role)
+
+
+def planned_paths_from_run_manifest(
+    project_root: Path, manifest: Mapping[str, Any]
+) -> tuple[str, ...]:
+    active_value = manifest.get("activeRunContextPath")
+    if not isinstance(active_value, str) or not active_value:
+        raise WritePolicyError("implementer write policy has no active run context")
+    active = _read_json(_rooted(project_root, active_value), "active run context")
+    source = active.get("sourceArtifacts")
+    run_inputs_value = source.get("runInputsPath") if isinstance(source, Mapping) else None
+    run = active.get("run")
+    stage_value = run.get("stage") if isinstance(run, Mapping) else None
+    if not isinstance(run_inputs_value, str) or not str(stage_value).isdigit():
+        raise WritePolicyError("implementer write policy has no approved stage authority")
+    inputs_payload = _read_json(_rooted(project_root, run_inputs_value), "run inputs")
+    inputs = inputs_payload.get("inputs")
+    approved = inputs.get("approvedPlanPath") if isinstance(inputs, Mapping) else None
+    if not isinstance(approved, str) or not approved:
+        raise WritePolicyError("implementer write policy has no approved plan path")
+    return _planned_paths_from_report(Path(approved), int(stage_value))
+
+
+def derive_write_enforcement(
+    policy: WritePolicy,
+    maximum_precision: BoundaryPrecision,
+    *,
+    role: str | None = None,
+) -> WriteEnforcement:
+    """Lower runner capability when policy paths cannot be enforced exactly."""
+    if role == "leader":
+        enforcement = WriteEnforcement(
+            boundary_precision="none",
+            mutation_audit="none",
+            attribution="batch-unattributed",
+            audited_roots=_audited_roots(policy),
+            observation_coverage="partial",
+            unobserved_write_surfaces=(
+                "lead-session-host-writes",
+                "other-stage-refs",
+                "shared-git-object-store",
+            ),
+        )
+        validate_write_enforcement_payload(enforcement.to_payload())
+        return enforcement
+    if maximum_precision not in _PRECISION_RANK:
+        raise WritePolicyError("worker write capability is invalid")
+    exact_policy = (
+        policy.source_mode == "source-readonly"
+        and not policy.auxiliary_policy.get("externalRoots")
+        and not policy.auxiliary_policy.get("scratchRoots")
+        and not policy.auxiliary_policy.get("generatedPaths")
+    )
+    if maximum_precision == "exact-path" and exact_policy:
+        boundary: BoundaryPrecision = "exact-path"
+    elif _PRECISION_RANK[maximum_precision] >= _PRECISION_RANK["directory-boundary"]:
+        boundary = "directory-boundary"
+    else:
+        boundary = "none"
+    exact = boundary == "exact-path" and exact_policy
+    external_roots = tuple(policy.auxiliary_policy.get("externalRoots", ()))
+    unobserved: list[str] = []
+    if boundary == "none":
+        unobserved.append("provider-process-outside-audited-roots")
+    if external_roots:
+        unobserved.append("shared-tool-cache")
+    if policy.source_mode == "project-mutation":
+        unobserved.extend(("other-stage-refs", "shared-git-object-store"))
+    coverage: Literal["complete", "scoped", "partial"]
+    if exact:
+        coverage = "complete"
+    elif unobserved:
+        coverage = "partial"
+    else:
+        coverage = "scoped"
+    enforcement = WriteEnforcement(
+        boundary_precision=boundary,
+        mutation_audit="none" if exact else "batch",
+        attribution="call" if exact else "batch-unattributed",
+        audited_roots=_audited_roots(policy),
+        observation_coverage=coverage,
+        unobserved_write_surfaces=tuple(unobserved),
+    )
+    validate_write_enforcement_payload(enforcement.to_payload())
+    return enforcement
+
+
+def write_policy_from_payload(payload: Mapping[str, Any]) -> WritePolicy:
+    validate_write_policy_payload(payload)
+    return WritePolicy(
+        artifact_policy=dict(payload["artifactPolicy"]),
+        source_policy=dict(payload["sourcePolicy"]),
+        git_policy=dict(payload["gitPolicy"]),
+        auxiliary_policy=dict(payload["auxiliaryPolicy"]),
+    )
+
+
+def write_enforcement_from_payload(
+    payload: Mapping[str, Any],
+) -> WriteEnforcement:
+    validate_write_enforcement_payload(payload)
+    return WriteEnforcement(
+        boundary_precision=payload["boundaryPrecision"],
+        mutation_audit=payload["mutationAudit"],
+        attribution=payload["attribution"],
+        audited_roots=tuple(Path(value) for value in payload["auditedRoots"]),
+        observation_coverage=payload["observationCoverage"],
+        unobserved_write_surfaces=tuple(payload["unobservedWriteSurfaces"]),
+    )
+
+
+def write_policy_digest(payload: Mapping[str, Any]) -> str:
+    validate_write_policy_payload(payload)
+    encoded = json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def validate_write_policy_payload(payload: Mapping[str, Any]) -> None:
+    if set(payload) != _POLICY_KEYS:
+        raise WritePolicyError("writePolicy must contain four canonical policy sections")
+    artifact = _mapping(payload.get("artifactPolicy"), "artifactPolicy")
+    source = _mapping(payload.get("sourcePolicy"), "sourcePolicy")
+    git = _mapping(payload.get("gitPolicy"), "gitPolicy")
+    auxiliary = _mapping(payload.get("auxiliaryPolicy"), "auxiliaryPolicy")
+    if set(artifact) != {"allowedRoot", "allowedPaths"}:
+        raise WritePolicyError("artifactPolicy is incomplete")
+    _absolute_text(artifact.get("allowedRoot"), "artifactPolicy.allowedRoot")
+    _relative_paths(artifact.get("allowedPaths", ()))
+    if source.get("mode") not in {"source-readonly", "project-mutation"}:
+        raise WritePolicyError("sourcePolicy mode is invalid")
+    if set(source) != {"mode", "allowedRoot", "plannedPaths", "protectedPaths"}:
+        raise WritePolicyError("sourcePolicy is incomplete")
+    _absolute_text(source.get("allowedRoot"), "sourcePolicy.allowedRoot")
+    _relative_paths(source.get("plannedPaths", ()))
+    _relative_paths(source.get("protectedPaths", ()))
+    if git.get("mode") not in {"disabled", "fast-forward-descendant-chain"}:
+        raise WritePolicyError("gitPolicy mode is invalid")
+    if git.get("mode") == "disabled" and set(git) != {"mode"}:
+        raise WritePolicyError("disabled gitPolicy must not grant Git paths")
+    required_git = {
+        "mode", "worktreeGitDir", "gitCommonDir", "expectedBaseCommit",
+        "allowedBranchRef", "commitMode",
+    }
+    if git.get("mode") != "disabled" and set(git) != required_git:
+        raise WritePolicyError("project mutation gitPolicy is incomplete")
+    if set(auxiliary) != {"scratchRoots", "generatedPaths", "externalRoots"}:
+        raise WritePolicyError("auxiliaryPolicy is incomplete")
+    _relative_paths(auxiliary.get("generatedPaths", ()))
+    for key in ("scratchRoots", "externalRoots"):
+        for value in _text_sequence(auxiliary.get(key), f"auxiliaryPolicy.{key}"):
+            _absolute_text(value, f"auxiliaryPolicy.{key}")
+
+
+def validate_write_enforcement_payload(payload: Mapping[str, Any]) -> None:
+    if set(payload) != _ENFORCEMENT_KEYS:
+        raise WritePolicyError("writeEnforcement is incomplete")
+    boundary = payload.get("boundaryPrecision")
+    mutation_audit = payload.get("mutationAudit")
+    attribution = payload.get("attribution")
+    coverage = payload.get("observationCoverage")
+    if boundary not in _PRECISION_RANK:
+        raise WritePolicyError("writeEnforcement boundaryPrecision is invalid")
+    if mutation_audit not in {"none", "batch"}:
+        raise WritePolicyError("writeEnforcement mutationAudit is invalid")
+    if attribution not in {"call", "batch-unattributed"}:
+        raise WritePolicyError("writeEnforcement attribution is invalid")
+    if coverage not in {"complete", "scoped", "partial"}:
+        raise WritePolicyError("writeEnforcement observationCoverage is invalid")
+    if (boundary, mutation_audit, attribution) == ("exact-path", "none", "call"):
+        if coverage != "complete":
+            raise WritePolicyError("exact enforcement must have complete coverage")
+    elif (boundary, mutation_audit, attribution) == (
+        "none",
+        "none",
+        "batch-unattributed",
+    ):
+        if coverage != "partial":
+            raise WritePolicyError("host-session enforcement must be partial")
+    elif mutation_audit != "batch" or attribution != "batch-unattributed":
+        raise WritePolicyError("non-exact enforcement must use batch attribution")
+    elif boundary == "exact-path" or coverage == "complete":
+        raise WritePolicyError("batch enforcement cannot claim exact coverage")
+    for root in _text_sequence(payload.get("auditedRoots"), "auditedRoots"):
+        _absolute_text(root, "auditedRoots")
+    _text_sequence(payload.get("unobservedWriteSurfaces"), "unobservedWriteSurfaces")
+
+
+def _git_policy(
+    invocation: Mapping[str, Any], root: Path, source_mode: str
+) -> dict[str, Any]:
+    if source_mode == "source-readonly":
+        return {"mode": "disabled"}
+    git_dir = _git_path(root, "--git-dir")
+    common_dir = _git_path(root, "--git-common-dir")
+    expected_base = _required_text(invocation, "expectedBaseCommit")
+    allowed_ref = _required_text(invocation, "allowedBranchRef")
+    _require_commit(root, expected_base)
+    current_ref = _git_output(root, "symbolic-ref", "-q", "HEAD")
+    if current_ref != allowed_ref or not allowed_ref.startswith("refs/heads/"):
+        raise WritePolicyError("allowedBranchRef does not match assigned worktree")
+    return {
+        "mode": "fast-forward-descendant-chain",
+        "worktreeGitDir": str(git_dir),
+        "gitCommonDir": str(common_dir),
+        "expectedBaseCommit": expected_base,
+        "allowedBranchRef": allowed_ref,
+        "commitMode": "fast-forward-descendant-chain",
+    }
+
+
+def _audited_roots(policy: WritePolicy) -> tuple[Path, ...]:
+    values = [
+        Path(str(policy.source_policy["allowedRoot"])),
+        Path(str(policy.artifact_policy["allowedRoot"])),
+    ]
+    values.extend(Path(value) for value in policy.auxiliary_policy.get("scratchRoots", ()))
+    git_dir = policy.git_policy.get("worktreeGitDir")
+    if isinstance(git_dir, str) and git_dir:
+        values.append(Path(git_dir))
+    seen: set[Path] = set()
+    roots: list[Path] = []
+    for value in values:
+        resolved = value.resolve()
+        if resolved not in seen:
+            roots.append(resolved)
+            seen.add(resolved)
+    return tuple(roots)
+
+
+def _trusted_root(invocation: Mapping[str, Any], worktree: Path | None) -> Path:
+    raw = worktree if worktree is not None else Path(_required_text(invocation, "projectRoot"))
+    if not raw.is_absolute() or not raw.is_dir():
+        raise WritePolicyError("assigned worktree must be an existing absolute path")
+    return raw.resolve()
+
+
+def _validated_auxiliary_roots(
+    invocation: Mapping[str, Any], assignment: Mapping[str, Any]
+) -> tuple[Path, ...]:
+    requested = _absolute_roots(invocation.get("auxiliaryRoots", ()))
+    declared = set(_absolute_roots(assignment.get("validatedAuxiliaryRoots", ())))
+    if any(path not in declared for path in requested):
+        raise WritePolicyError("auxiliary root is not adapter-validated")
+    return requested
+
+
+def _assignment_precision(assignment: Mapping[str, Any]) -> BoundaryPrecision:
+    capability = assignment.get("workerWriteCapability")
+    if not isinstance(capability, Mapping):
+        raise WritePolicyError("workerWriteCapability is required")
+    value = capability.get("maxBoundaryPrecision")
+    if value not in _PRECISION_RANK:
+        raise WritePolicyError("workerWriteCapability is invalid")
+    return value
+
+
+def _absolute_roots(value: object) -> tuple[Path, ...]:
+    roots: list[Path] = []
+    for text in _text_sequence(value, "absolute roots"):
+        path = Path(text)
+        if not path.is_absolute() or not path.exists():
+            raise WritePolicyError("auxiliary root must be an existing absolute path")
+        if path.absolute() != path.resolve():
+            raise WritePolicyError("auxiliary root contains a symlink component")
+        roots.append(path.resolve())
+    if len(set(roots)) != len(roots):
+        raise WritePolicyError("auxiliary roots must be unique")
+    return tuple(roots)
+
+
+def _relative_to_root(path: Path, root: Path, label: str) -> str:
+    absolute = path if path.is_absolute() else root / path
+    try:
+        relative = absolute.absolute().relative_to(root).as_posix()
+    except ValueError as exc:
+        raise WritePolicyError(f"{label} path is outside project root") from exc
+    if not relative or relative == ".":
+        raise WritePolicyError(f"{label} path must name a file")
+    current = root
+    for part in PurePosixPath(relative).parts:
+        current /= part
+        if current.is_symlink():
+            raise WritePolicyError(f"{label} path contains a symlink component")
+    return relative
+
+
+def _planned_paths_from_report(report_path: Path, stage: int) -> tuple[str, ...]:
+    payload = _read_json(report_path.with_suffix(".data.json"), "approved plan data")
+    planning = payload.get("implementationPlanning")
+    stages = planning.get("stages") if isinstance(planning, Mapping) else None
+    selected = next(
+        (
+            row for row in stages
+            if isinstance(row, Mapping) and row.get("stage") == stage
+        ),
+        None,
+    ) if isinstance(stages, list) else None
+    steps = selected.get("stepwiseExecution") if isinstance(selected, Mapping) else None
+    paths = {
+        part.strip().strip("`")
+        for step in steps if isinstance(step, Mapping)
+        for part in str(step.get("files") or "").replace("<br>", ",").split(",")
+        if part.strip()
+    } if isinstance(steps, list) else set()
+    if not paths:
+        raise WritePolicyError("implementer write policy stage has no planned paths")
+    return _relative_paths(tuple(sorted(paths)))
+
+
+def _rooted(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def _read_json(path: Path, label: str) -> Mapping[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise WritePolicyError(f"{label} is invalid: {path}") from exc
+    if not isinstance(value, Mapping):
+        raise WritePolicyError(f"{label} must be an object: {path}")
+    return value
+
+
+def _relative_paths(value: object) -> tuple[str, ...]:
+    paths: list[str] = []
+    for raw in _text_sequence(value, "relative paths"):
+        candidate = PurePosixPath(raw)
+        if candidate.is_absolute() or not candidate.parts or ".." in candidate.parts:
+            raise WritePolicyError("policy paths must be normalized relative paths")
+        normalized = candidate.as_posix()
+        if normalized in {"", "."} or normalized != raw:
+            raise WritePolicyError("policy paths must be normalized relative paths")
+        paths.append(normalized)
+    if len(set(paths)) != len(paths):
+        raise WritePolicyError("policy paths must be unique")
+    return tuple(paths)
+
+
+def _mapping(value: object, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise WritePolicyError(f"{label} must be an object")
+    return value
+
+
+def _text_sequence(value: object, label: str) -> tuple[str, ...]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise WritePolicyError(f"{label} must be an array")
+    rows = tuple(value)
+    if any(not isinstance(row, str) or not row for row in rows):
+        raise WritePolicyError(f"{label} must contain non-empty strings")
+    return rows
+
+
+def _required_text(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise WritePolicyError(f"{key} must be a non-empty string")
+    return value
+
+
+def _absolute_text(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value or not Path(value).is_absolute():
+        raise WritePolicyError(f"{label} must be an absolute path")
+    return value
+
+
+def _git_path(root: Path, flag: str) -> Path:
+    raw = _git_output(root, "rev-parse", "--path-format=absolute", flag)
+    path = Path(raw).resolve()
+    if not path.exists():
+        raise WritePolicyError(f"Git projection path does not exist: {path}")
+    return path
+
+
+def _require_commit(root: Path, commit: str) -> None:
+    result = subprocess.run(
+        ["git", "-C", str(root), "cat-file", "-e", f"{commit}^{{commit}}"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise WritePolicyError(result.stderr.strip() or "expected base is not a commit")
+
+
+def _git_output(root: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        detail = result.stderr.strip() or "Git command returned no value"
+        raise WritePolicyError(detail)
+    return result.stdout.strip()

package/runtime/python/okstra_project/state.py

@@ -53,6 +53,20 @@ def _load_json(path: Path) -> Optional[dict]:
         raise StateError(f"failed to parse {path}: {exc}") from exc
 
 
+def _next_phase():
+    """`okstra_ctl.next_phase` 를 호출 시점에 가져온다.
+
+    모듈 최상단에서 import 하면 순환이 된다 — `okstra_ctl/__init__.py` 가
+    `.ids` 를 거쳐 이 모듈의 `slugify` 를 도로 import 하기 때문에, 여기서
+    okstra_ctl 을 먼저 끌어오면 아직 정의되지 않은 이름을 찾다가 ImportError 로
+    죽는다. 같은 파일의 `_reconcile_task_root_best_effort` 도 같은 이유로 지연
+    import 를 쓴다.
+    """
+    from okstra_ctl import next_phase
+
+    return next_phase
+
+
 def slugify(value: str) -> str:
     """task-group / task-id segment 를 디스크 경로용 slug 로 정규화한다.
 
@@ -83,8 +97,32 @@ def read_latest_task(project_root: Path) -> Optional[dict]:
 
 
 def read_task_manifest(task_root: Path) -> Optional[dict]:
-    """<task-root>/task-manifest.json 을 dict 로. 파일 없으면 None."""
-    return _load_json(Path(task_root) / TASK_MANIFEST_FILENAME)
+    """<task-root>/task-manifest.json 을 dict 로. 파일 없으면 None.
+
+    구형 문자열 포인터는 반환값에서 승격한다. 읽는 곳이 여럿이므로 승격을 seam
+    하나에 두지 않으면 형태가 갈라진다 (ADR-0004).
+
+    **디스크는 건드리지 않는다.** 승격한 값을 여기서 되적으면 lock 없는
+    read-modify-write 가 되어, 파싱과 쓰기 사이에 다른 프로세스가 적은
+    `currentPhase` · `phaseStates` · `latestReportPath` 를 되돌린다
+    (`os.replace` 는 찢어진 읽기만 막고 갱신 유실은 못 막는다). 이 분기는
+    디스크 포인터가 아직 문자열일 때 — 즉 업그레이드 직후 진행 중인 task 가
+    살아 있을 때 — 만 발화하므로 되돌릴 수 있는 값이 바로 phase 진행 상태다.
+    그래서 디스크 형태는 다음 writer 가 손댈 때까지 구형으로 남는다. 모든
+    읽기가 여기서 승격하므로 소비자는 그 차이를 보지 않는다.
+    """
+    manifest = _load_json(Path(task_root) / TASK_MANIFEST_FILENAME)
+    if not isinstance(manifest, dict):
+        return manifest
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, dict):
+        return manifest
+    workflow["nextRecommendedPhase"] = _next_phase().promote(
+        workflow.get("nextRecommendedPhase")
+    )
+    # routingStatus 는 포인터 status 로 흡수됐다 — 승격과 같은 자리에서 지운다.
+    workflow.pop("routingStatus", None)
+    return manifest
 
 
 def read_task_key(task_root: Path) -> str:
@@ -146,11 +184,18 @@ def _entry_with_manifest_state(entry: dict, task_root: Path) -> dict:
         ("currentPhase", "currentPhase"),
         ("currentPhaseState", "currentPhaseState"),
         ("lastCompletedPhase", "lastCompletedPhase"),
-        ("nextRecommendedPhase", "nextRecommendedPhase"),
     ):
         value = workflow.get(source)
         if isinstance(value, str):
             out[target] = value
+    # 포인터는 구조체라 위 루프의 str 검사에 걸리지 않는다 — 그 검사에 남겨두면
+    # 값이 예외도 로그도 없이 버려진다. 매니페스트가 값을 가질 때만 카탈로그
+    # 항목을 덮는 규칙은 위 세 필드와 같게 유지하고, 덮지 않을 때는 카탈로그에
+    # 남아 있던 구형 문자열을 승격해 내보낸다.
+    raw = workflow.get("nextRecommendedPhase")
+    if raw is None:
+        raw = entry.get("nextRecommendedPhase")
+    out["nextRecommendedPhase"] = _next_phase().promote(raw)
     out.update(derived_task_status(manifest))
     return out
 
@@ -334,7 +379,9 @@ def resolve_task_identity(project_root: Path, task_key: str) -> dict:
         "taskType": manifest.get("taskType") or "",
         "currentPhase": workflow.get("currentPhase") or "",
         "currentPhaseState": workflow.get("currentPhaseState") or "",
-        "nextRecommendedPhase": workflow.get("nextRecommendedPhase") or "",
+        "nextRecommendedPhase": _next_phase().promote(
+            workflow.get("nextRecommendedPhase")
+        ),
         "lastCompletedPhase": workflow.get("lastCompletedPhase") or "",
         "awaitingApproval": bool(workflow.get("awaitingApproval", False)),
         "taskBriefPath": manifest.get("taskBriefPath") or "",
@@ -363,8 +410,9 @@ def task_read_side_snapshot(project_root: Path, task_key: str) -> dict:
             "currentPhase": workflow.get("currentPhase"),
             "currentPhaseState": workflow.get("currentPhaseState"),
             "lastCompletedPhase": workflow.get("lastCompletedPhase"),
-            "nextRecommendedPhase": workflow.get("nextRecommendedPhase"),
-            "routingStatus": workflow.get("routingStatus"),
+            "nextRecommendedPhase": _next_phase().promote(
+                workflow.get("nextRecommendedPhase")
+            ),
             "phaseStates": workflow.get("phaseStates"),
         },
         "status": derived_task_status(manifest),