okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -74,6 +74,11 @@ class WorktreeEntry:
     stage: Optional[int] = None
     implementation_base_commit: str = ""
     stages: Optional[list] = None
+    # 프로비저닝 시점에 공유 sync 파일이 갖고 있던 **키 이름** 집합
+    # ({relative path: [name, ...]}). 값은 담지 않는다. 다음 런에서 대조해
+    # `.env` 키 개명을 알린다 — 그 파일은 worktree 마다 심링크로 공유돼
+    # 브랜치 격리가 통하지 않는다.
+    sync_file_keys: Optional[dict] = None
 
 
 def _registry_lock():
@@ -122,6 +127,7 @@ def reserve(
     stage_number: Optional[int] = None,
     group_id: Optional[str] = None,
     stages: Optional[list] = None,
+    sync_file_keys: Optional[dict] = None,
 ) -> WorktreeEntry:
     """Atomically insert a new entry. Raises RuntimeError if the
     task-key already exists or the branch is already owned by a
@@ -158,6 +164,7 @@ def reserve(
             "status": "active",
             "stage": stage_number,
             "stages": stages,
+            "sync_file_keys": sync_file_keys,
         }
         # Re-reserving a released task-key must not drop the anchor: the
         # implementation base commit is task-lifetime state, not per-reservation,

package/runtime/python/okstra_ctl/worktree_status_cli.py

@@ -0,0 +1,53 @@
+"""`okstra worktree-status` 의 진입점. 핸들러는 [worktree_cli.status] 에 있다."""
+from __future__ import annotations
+
+import argparse
+
+from .worktree_cli import status
+
+_CLI_EPILOG = r"""Usage:
+  okstra worktree-status [--path <dir>] [--check-clean]
+
+okstra provisions `.okstra` plus the configured sync entries (`.project-docs`,
+`.claude`, …) into every task worktree, and an `implementation` stage worktree
+sits inside its task worktree. A bare `git status --porcelain` therefore never
+comes back empty there, so a plan step asserting a clean tree with one fails on
+okstra's scaffolding rather than on the stage's own work. This command asks the
+same question against source paths only — the exact gate okstra's own handoff
+and stage-integration steps use.
+
+Use it as the assertion in a plan step:
+  okstra worktree-status --check-clean
+
+Do not chain a `git tag stage-<N>-exit` onto it. okstra writes that tag when it
+settles the stage, at the commit the carry evidence records; a step that tags
+while the stage is still running puts it on an earlier commit.
+
+Output: JSON { ok, path, clean, entries, excluded }. `entries` holds the
+`git status --short` rows that made it dirty; `excluded` lists the paths left
+out of the question.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra worktree-status",
+        description="Clean-worktree check that ignores okstra's own scaffolding.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--path", default=".",
+        help="directory to inspect (default: the current directory). There is "
+             "no --project-root: point --path at the stage or task worktree "
+             "you mean, or run it from inside one.",
+    )
+    parser.add_argument(
+        "--check-clean", action="store_true",
+        help="exit 1 when the tree is dirty (default: always exit 0)",
+    )
+    return status(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/write_policy.py

@@ -9,75 +9,26 @@ from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
 from typing import Any, Literal
 
+from .domain.write_policy import (  # noqa: F401 — 재노출(값 코어는 도메인 소유)
+    BoundaryPrecision,
+    WriteEnforcement,
+    WritePolicy,
+    WritePolicyError,
+    _absolute_text,
+    _mapping,
+    _PRECISION_RANK,
+    _relative_paths,
+    _text_sequence,
+    validate_write_enforcement_payload,
+    validate_write_policy_payload,
+    write_enforcement_from_payload,
+    write_policy_digest,
+    write_policy_from_payload,
+)
+from .final_report_paths import final_report_data_path
 from .json_boundary import JsonBoundaryError, load_owned_object
-
-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),
-        }
-
+from .path_hints import hydrate_active_run_context
+from .paths import task_conformance_manifest_file, task_qa_dir
 
 def build_write_policy(
     invocation: Mapping[str, Any],
@@ -125,12 +76,55 @@ def build_write_policy(
     return policy
 
 
+def _role_qa_artifact_paths(role: str, task_root: Path | None) -> tuple[Path, ...]:
+    """The task `qa/` writes a role's own contract makes mandatory.
+
+    `qa/` is a sibling of `runs/` under the task root, so the orchestrator
+    allowance — which carries the run directory tree and the task manifest FILE
+    — never reached it, and no worker artifact path names it. In a worktree run
+    the artifact root is the project root while the source root is the
+    worktree, so `_artifact_policy_failures` is live and every such write read
+    as `artifact-root change exceeds batch policy union`: a role following its
+    own profile could not pass the audit.
+
+    Split by role because ownership is split. The executor writes the Tier 3
+    conformance script, its `tsconfig.json` and any real-IO qa spec under
+    `qa/scripts/`, plus the manifest entry naming them
+    (`_implementation-executor.md` §"Stage conformance script", §"Real-IO test
+    isolation"). Everything else under `qa/` — the self-mock sidecar and its
+    diff, the conformance run's `result-*.json` — is written while the verifier
+    runs its own gates. Keeping the executor's grant to those two entries is
+    what leaves the audit able to catch an executor that runs the verifier's
+    self-mock gate (`_implementation-executor.md` §"Verifier gates are not
+    yours to run"); widening it to `qa/` would silence that.
+
+    The verifier's grant is the tree because the filenames are not knowable
+    here — the sidecar carries the run's stage name and a conformance script
+    names its own `result-*.json`. `qa/self-mock-waivers.json` is inside that
+    grant and stays forbidden to it, enforced where the acknowledgement is read
+    rather than where the byte is written: `validate-run.py::_validate_selfmock`
+    fails a report whose waived entries came from anywhere but the user's file,
+    or lack a `reason` / `acknowledgedBy`.
+    """
+    if task_root is None:
+        return ()
+    if role == "implementer":
+        return (
+            task_qa_dir(task_root) / "scripts",
+            task_conformance_manifest_file(task_root),
+        )
+    if role == "verifier":
+        return (task_qa_dir(task_root),)
+    return ()
+
+
 def build_invocation_write_contract(
     *,
     role: str,
     project_root: Path,
     worktree: Path | None,
     artifact_paths: Sequence[Path],
+    task_root: Path | None,
     maximum_precision: BoundaryPrecision,
     planned_paths: Sequence[str] = (),
     planned_paths_declared: bool = True,
@@ -142,7 +136,13 @@ def build_invocation_write_contract(
     """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
+        dict.fromkeys(
+            _relative_to_root(path, root, "artifact")
+            for path in (
+                *artifact_paths,
+                *_role_qa_artifact_paths(role, task_root),
+            )
+        )
     )
     invocation: dict[str, Any] = {
         "role": role,
@@ -173,6 +173,22 @@ def build_invocation_write_contract(
     return policy, derive_write_enforcement(policy, maximum_precision, role=role)
 
 
+def task_root_from_run_manifest(
+    project_root: Path, manifest: Mapping[str, Any]
+) -> Path | None:
+    """The task root this run belongs to, read from the manifest's own pointer.
+
+    Derived from `taskManifestPath` rather than by counting directories up from
+    the run directory: an `implementation` run carries an extra `stage-<N>`
+    level, so one fixed index cannot reach the task root for every task type.
+    """
+    value = manifest.get("taskManifestPath")
+    if not isinstance(value, str) or not value:
+        return None
+    candidate = Path(value)
+    return (candidate if candidate.is_absolute() else project_root / candidate).parent
+
+
 def planned_paths_from_run_manifest(
     project_root: Path, manifest: Mapping[str, Any]
 ) -> tuple[str, ...]:
@@ -183,8 +199,6 @@ def planned_paths_from_run_manifest(
     # hints instead; the hydrator is what puts the block back. Reading the file
     # raw always saw `None` here and reported the run as having no approved
     # stage authority, which blocked every implementer dispatch.
-    from .path_hints import hydrate_active_run_context
-
     active = hydrate_active_run_context(
         _read_json(_rooted(project_root, active_value), "active run context")
     )
@@ -274,111 +288,6 @@ def derive_write_enforcement(
     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]:
@@ -483,7 +392,11 @@ def _planned_paths_from_report(
 ) -> tuple[tuple[str, ...], bool]:
     """(paths, declared). `declared` is False for a plan written before the
     structured `plannedPaths` column existed."""
-    payload = _read_json(report_path.with_suffix(".data.json"), "approved plan data")
+    # `--approved-plan` 은 레코드(`.data.json`)만 받는다(`require_approved_plan_record`).
+    # 손으로 접미사를 붙이면 `.data.json` 에 한 번 더 붙어 `.data.data.json` 이 되고,
+    # 그 파일은 없으므로 implementer 디스패치가 전부 막혔다. 정본 헬퍼는 이미
+    # 레코드인 경로를 그대로 돌려주고 `.md` 만 짝으로 바꾼다.
+    payload = _read_json(final_report_data_path(report_path), "approved plan data")
     planning = payload.get("implementationPlanning")
     stages = planning.get("stages") if isinstance(planning, Mapping) else None
     selected = next(
@@ -548,36 +461,6 @@ def _read_json(path: Path, label: str) -> Mapping[str, Any]:
     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():
@@ -585,12 +468,6 @@ def _required_text(payload: Mapping[str, Any], key: str) -> str:
     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()

package/runtime/python/okstra_project/__init__.py

@@ -28,7 +28,6 @@ from .resolver import (
 )
 from .state import (
     StateError,
-    code_review_target_snapshot,
     find_task_root,
     list_project_tasks,
     parse_task_key,
@@ -40,7 +39,6 @@ from .state import (
     resolve_task_identity,
     resolve_task_reference,
     slugify,
-    stage_map_read_side_snapshot,
     task_read_side_snapshot,
 )
 
@@ -54,7 +52,6 @@ __all__ = [
     "StateError",
     "TASKS_RELATIVE",
     "TASK_CATALOG_RELATIVE",
-    "code_review_target_snapshot",
     "discovery_dir",
     "find_task_root",
     "list_project_tasks",
@@ -70,7 +67,6 @@ __all__ = [
     "resolve_task_identity",
     "resolve_task_reference",
     "slugify",
-    "stage_map_read_side_snapshot",
     "task_read_side_snapshot",
     "tasks_root",
     "upsert_project_json",

package/runtime/python/okstra_project/dirs.py

@@ -42,8 +42,8 @@ TASK_MANIFEST_FILENAME = "task-manifest.json"
 """task root 안의 lifecycle manifest 파일명.
 
 `okstra_ctl.paths.task_manifest_path` 와 `okstra_project.state.read_task_manifest`
-양쪽이 이 상수를 쓴다 — paths 가 state 를 import 하므로 역방향 import 는 순환이고,
-두 계층이 공유할 수 있는 자리는 여기뿐이다."""
+양쪽이 이 상수를 쓴다. 어느 한쪽에 두면 반대쪽이 그 모듈 전체를 끌어오게 되므로
+의존 0인 이 자리가 두 계층의 공유 지점이다."""
 DISCOVERY_RELATIVE = OKSTRA_RELATIVE / "discovery"
 TASK_CATALOG_RELATIVE = DISCOVERY_RELATIVE / "task-catalog.json"
 LATEST_TASK_RELATIVE = DISCOVERY_RELATIVE / "latest-task.json"

package/runtime/python/okstra_project/phase_pointer.py

@@ -0,0 +1,84 @@
+"""다음 Phase 포인터 값의 shape · 승격 규칙.
+
+`{phase, status, rationale}` 구조체를 만들고, 판별하고, 구형 문자열에서
+승격시키는 것까지만 소유한다. 다음 phase 를 **계산**하는 일은 이 모듈이
+하지 않는다 — 그것은 `okstra_ctl.next_phase` 의 몫이고, 그 모듈이 여기의
+심볼을 재노출한다.
+
+왜 okstra_ctl 이 아니라 여기 있는가:
+
+읽기측 상태 접근자 `okstra_project.state` 가 매니페스트를 돌려줄 때마다
+포인터를 승격시켜야 한다. 그런데 `okstra_ctl` 의 어느 모듈을 import 하든
+`okstra_ctl/__init__.py` 가 먼저 실행되고, 그 `__init__` 은 `.ids` 를 거쳐
+`okstra_project.state` 의 `slugify` 를 도로 끌어온다. 즉 이 값 타입을
+`okstra_ctl` 안에 두면 leaf 로 만들어도 패키지 `__init__` 을 통해 순환이
+되살아난다. 그래서 하위 계층이 소유하고 상위 계층이 재노출한다.
+
+이 모듈은 okstra 안의 어떤 것도 import 하지 않는다. 그 성질이 위 설명의
+전제이므로 import 를 추가하기 전에 순환이 되살아나지 않는지 확인할 것.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+STATUS_READY = "ready"
+STATUS_PENDING = "pending"
+STATUS_BLOCKED = "blocked"
+STATUS_TERMINAL = "terminal"
+
+POINTER_STATUSES = frozenset(
+    {STATUS_READY, STATUS_PENDING, STATUS_BLOCKED, STATUS_TERMINAL}
+)
+
+# 구형 문자열 포인터가 쓰던 센티널 → status. 이 표는 승격에만 쓰이며
+# 새 포인터를 만드는 데는 절대 쓰지 않는다.
+LEGACY_SENTINELS = {
+    "": STATUS_PENDING,
+    "unknown": STATUS_PENDING,
+    "pending-routing-decision": STATUS_PENDING,
+    "pending-release-handoff": STATUS_PENDING,
+    "done-or-follow-up": STATUS_TERMINAL,
+}
+
+
+def make(
+    phase: str = "", status: str = STATUS_PENDING, rationale: str = ""
+) -> dict[str, str]:
+    """포인터 구조체 하나를 만든다. status 가 허용 집합 밖이면 거부한다."""
+    if status not in POINTER_STATUSES:
+        raise ValueError(f"unknown next-phase status: {status!r}")
+    return {"phase": phase, "status": status, "rationale": rationale}
+
+
+def is_pointer(value: Any) -> bool:
+    """value 가 유효한 포인터 구조체인지."""
+    return (
+        isinstance(value, Mapping)
+        and isinstance(value.get("phase"), str)
+        and value.get("status") in POINTER_STATUSES
+        and isinstance(value.get("rationale"), str)
+    )
+
+
+def promote(value: Any) -> dict[str, str]:
+    """구형 문자열·None 을 포인터로 올린다.
+
+    이미 포인터인 입력은 같은 값을 담은 새 dict 로 돌려준다 — 입력을 그대로
+    돌려주지 않는다. 호출부가 반환값을 그 자리에서 변형해도 manifest 원본이
+    오염되지 않아야 하기 때문이다.
+
+    pre-v1 무호환 원칙의 의도적 예외다. 근거는 업그레이드를 가로지르는
+    진행 중 태스크가 영구히 막히는 기존 사례 — ADR-0004 Consequences.
+    """
+    if is_pointer(value):
+        return {
+            "phase": value["phase"],
+            "status": value["status"],
+            "rationale": value["rationale"],
+        }
+    if not isinstance(value, str):
+        return make()
+    text = value.strip()
+    if text in LEGACY_SENTINELS:
+        return make(status=LEGACY_SENTINELS[text])
+    return make(phase=text, status=STATUS_READY)

package/runtime/python/okstra_project/slug.py

@@ -0,0 +1,24 @@
+"""디스크 경로 세그먼트 slug 규칙.
+
+`okstra_ctl.ids` 와 `okstra_ctl.paths` 가 경로를 조립할 때마다 쓰는 순수 규칙이다.
+이 규칙이 `okstra_project.state`(622줄짜리 상태 접근자) 안에 있던 동안에는
+`okstra_ctl/__init__.py` → `.ids` → `okstra_project.state` 경로가 생겨,
+`state` 가 okstra_ctl 을 되짚는 모든 호출을 함수 본문 지연 import 로 밀어냈다.
+그 쐐기를 뽑기 위해 규칙만 leaf 로 분리한다.
+
+이 모듈은 표준 라이브러리 외에 아무것도 import 하지 않는다. 그 성질이 위
+설명의 전제이므로 import 를 추가하기 전에 순환이 되살아나지 않는지 확인할 것.
+"""
+from __future__ import annotations
+
+import re
+
+def slugify(value: str) -> str:
+    """task-group / task-id segment 를 디스크 경로용 slug 로 정규화한다.
+
+    소문자화 + 알파넘 외 문자 → '-' 로 collapse.
+    okstra.sh 의 path-resolve.sh slug 규칙과 일치해야 한다.
+    """
+    value = (value or "").lower()
+    value = re.sub(r"[^a-z0-9]+", "-", value).strip("-")
+    return value