okstra 0.109.0 → 0.111.0

package/runtime/python/okstra_ctl/worktree.py

@@ -105,17 +105,16 @@ DEFAULT_WORKTREE_SYNC_FILES: tuple[str, ...] = (
 DEFAULT_WORKTREE_SNAPSHOT_FILES: tuple[str, ...] = ()
 
 
-# Work-category → short branch prefix. Mirrors the values accepted by
-# `--work-category` (bugfix / feature / refactor / ops / improvement) and
-# falls back to `task` when the category is unset or unrecognised.
-_WORK_CATEGORY_PREFIX = {
-    "feature": "feat",
+# Work-category → branch namespace (slash-prefixed). Mirrors the values
+# accepted by `--work-category` (bugfix / feature / refactor / ops /
+# improvement); `feature` and `improvement` share the `feature/` namespace,
+# and any unset/unrecognised category falls back to `task/`.
+_WORK_CATEGORY_NAMESPACE = {
+    "feature": "feature",
+    "improvement": "feature",
     "bugfix": "fix",
     "refactor": "refactor",
     "ops": "ops",
-    "improvement": "improve",
-    "docs": "doc",
-    "doc": "doc",
 }
 
 
@@ -241,9 +240,9 @@ def _safe_segment(value: str) -> str:
     return _safe_fs_segment(value)
 
 
-def _work_category_prefix(work_category: str) -> str:
+def _work_category_namespace(work_category: str) -> str:
     key = (work_category or "").strip().lower()
-    return _WORK_CATEGORY_PREFIX.get(key, "task")
+    return _WORK_CATEGORY_NAMESPACE.get(key, "task")
 
 
 def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
@@ -663,11 +662,13 @@ def compute_branch_name(
     stage_number: Optional[int] = None,
     group_id: Optional[str] = None,
 ) -> str:
-    """One branch per task-key, or `<prefix>-<task-id>-s<N>` for an
-    implementation stage worktree."""
+    """One branch per task-key as `<namespace>/<task-id>`, or
+    `<namespace>/<task-id>-s<N>` for an implementation stage worktree. The
+    namespace is a controlled constant so its slash is preserved; only the
+    task-id segment is sanitised."""
     if stage_number is not None and group_id is not None:
         raise ValueError("stage_number and group_id are mutually exclusive")
-    name = f"{_work_category_prefix(work_category)}-{_safe_segment(task_id_segment)}"
+    name = f"{_work_category_namespace(work_category)}/{_safe_segment(task_id_segment)}"
     if stage_number is not None:
         name = f"{name}-s{stage_number}"
     if group_id is not None:

package/runtime/python/okstra_project/__init__.py

@@ -38,6 +38,7 @@ from .state import (
     resolve_task_identity,
     resolve_task_reference,
     slugify,
+    task_read_side_snapshot,
 )
 
 __all__ = [
@@ -64,6 +65,7 @@ __all__ = [
     "resolve_task_identity",
     "resolve_task_reference",
     "slugify",
+    "task_read_side_snapshot",
     "tasks_root",
     "upsert_project_json",
 ]

package/runtime/python/okstra_project/state.py

@@ -37,6 +37,10 @@ from .dirs import (
 class StateError(Exception):
     """state file 읽기/파싱 실패 — 호출자가 surface 해야 할 오류."""
 
+    def __init__(self, message: str, *, stage: Optional[str] = None):
+        super().__init__(message)
+        self.stage = stage
+
 
 def _load_json(path: Path) -> Optional[dict]:
     if not path.is_file():
@@ -268,10 +272,16 @@ def resolve_task_identity(project_root: Path, task_key: str) -> dict:
     """
     task_root = find_task_root(project_root, task_key)
     if task_root is None:
-        raise StateError(f"task root not found for {task_key!r}")
+        raise StateError(
+            f"task root not found for {task_key!r}",
+            stage="task_root_missing",
+        )
     manifest = read_task_manifest(task_root)
     if manifest is None:
-        raise StateError(f"task-manifest.json missing under {task_root}")
+        raise StateError(
+            f"task-manifest.json missing under {task_root}",
+            stage="manifest_missing",
+        )
     workflow = manifest.get("workflow") or {}
     if not isinstance(workflow, dict):
         workflow = {}
@@ -292,3 +302,35 @@ def resolve_task_identity(project_root: Path, task_key: str) -> dict:
         "taskBriefPath": manifest.get("taskBriefPath") or "",
         "manifest": manifest,
     }
+
+
+def task_read_side_snapshot(project_root: Path, task_key: str) -> dict:
+    """task-show / inspect 용 curated task 상태 view 를 반환한다.
+
+    resolve_task_identity 가 내부 raw manifest 를 들고 있지만, 이 accessor 는
+    caller 에게 manifest shape 를 노출하지 않는 read-side 계약이다.
+    """
+    identity = resolve_task_identity(project_root, task_key)
+    manifest = identity["manifest"]
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, dict):
+        workflow = {}
+    return {
+        "projectRoot": identity["projectRoot"],
+        "taskKey": manifest.get("taskKey"),
+        "taskType": manifest.get("taskType"),
+        "taskRoot": identity["taskRoot"],
+        "taskBriefPath": manifest.get("taskBriefPath"),
+        "workflow": {
+            "currentPhase": workflow.get("currentPhase"),
+            "currentPhaseState": workflow.get("currentPhaseState"),
+            "lastCompletedPhase": workflow.get("lastCompletedPhase"),
+            "nextRecommendedPhase": workflow.get("nextRecommendedPhase"),
+            "routingStatus": workflow.get("routingStatus"),
+            "phaseStates": workflow.get("phaseStates"),
+        },
+        "resultContract": manifest.get("resultContract"),
+        "artifacts": manifest.get("artifacts"),
+        "modelAssignments": manifest.get("modelAssignments"),
+        "latestRunPath": manifest.get("latestRunPath"),
+    }

package/runtime/skills/okstra-run/SKILL.md

@@ -145,13 +145,30 @@ Output: `{ok: true, text: "선택 확인:\n  task-type     : ...\n  ..."}`. Prin
 
 ## Step 5: Render the task bundle
 
-When `next.kind == "done"`, fetch the final args:
+When `next.kind == "done"`, fetch the public wizard outcome:
 
 ```bash
-okstra wizard render-args --state-file /var/folders/.../okstra-wizard.AbCd.json
+okstra wizard outcome --state-file /var/folders/.../okstra-wizard.AbCd.json
 ```
 
-Output: `{ok: true, args: {"project-root": "...", "task-type": "...", ...}}`. Build the `okstra render-bundle` invocation from `args`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
+Output: `{ok: true, outcome: {renderArgs: {...}, persistActions: [...], confirmationText: "..."}}`.
+
+Run every `outcome.persistActions[]` entry BEFORE `render-bundle`. The only supported action is:
+
+```json
+{"command":"config.set","key":"pr-template-path","scope":"project|global","value":"<path>"}
+```
+
+Execute the matching command for `scope`:
+
+```bash
+okstra config set pr-template-path "<value>" --scope project
+okstra config set pr-template-path "<value>" --scope global
+```
+
+If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
+
+Build the `okstra render-bundle` invocation from `outcome.renderArgs`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
 
 **Empty-value rule (same as Step 3)**: every flag whose value is the empty string MUST still be passed explicitly as `--<key> ""`. For example: `--workers ""`, `--directive ""`, `--related-tasks ""`. Omitting the flag is forbidden — `render-bundle` distinguishes "flag absent" from "flag present with empty value", and the wizard's intent is always the latter.
 
@@ -295,20 +312,7 @@ stale-SHA 재조정(git-reconcile 분기)을 띄우면, **그 stage 에서 연
 
 ## Persisting the PR template scope (release-handoff)
 
-When `wizard render-args` returns a non-empty `pr-template-path` AND the state has `pr_template_scope == "project"` or `"global"`, run the matching config command BEFORE `render-bundle`:
-
-```bash
-# project scope
-okstra config set pr-template-path "<path>" --scope project
-# global scope (must be absolute or ~/-prefixed)
-okstra config set pr-template-path "<path>" --scope global
-```
-
-The scope is held in the wizard state but is not yet exposed by any `okstra wizard` subcommand. Until the subcommand below ships, read the JSON state file directly with the `Read` tool (literal path captured in Step 2) and inspect the `pr_template_scope` field — it is a plain serialized `WizardState`. Do not shell out (`python3 -c`, `jq`, etc.); the literal-token Bash rule rejects them.
-
-## Out-of-scope backlog
-
-- **`okstra wizard pr-template-scope --state-file PATH`**: add a thin subcommand to `scripts/okstra_ctl/wizard.py` that prints `{ok: true, scope: "once" | "project" | "global"}` so this skill can drop the `Read`-the-raw-state-file detour. The subcommand should reuse the existing `load_state_file` path; no schema changes required.
+Do not read the wizard state file directly. `okstra wizard outcome` exposes any release-handoff PR template write as `outcome.persistActions[]`; execute those actions before `render-bundle`.
 
 ## Concurrency
 

package/src/commands/execute/wizard.mjs

@@ -16,6 +16,7 @@ Subcommands:
   step            submit an answer (or fetch the current prompt) and emit next
   render-args     emit the final --flag/value map for 'okstra render-bundle'
   confirmation    emit the multi-line confirmation echo block
+  outcome         emit render args, persistence actions, and confirmation text
 
 Usage:
   okstra wizard new-state-file
@@ -23,6 +24,7 @@ Usage:
   okstra wizard step --state-file <path> [--answer <value>]
   okstra wizard render-args --state-file <path>
   okstra wizard confirmation --state-file <path>
+  okstra wizard outcome --state-file <path>
 
 'init' auto-fills --workspace-root from 'okstra paths --field workspace',
 so callers do not pass it.
@@ -65,7 +67,7 @@ export async function run(args) {
   }
 
   const [sub, ...rest] = args;
-  if (!["new-state-file", "init", "step", "render-args", "confirmation"].includes(sub)) {
+  if (!["new-state-file", "init", "step", "render-args", "confirmation", "outcome"].includes(sub)) {
     process.stderr.write(`error: unknown wizard subcommand '${sub}'\n\n${USAGE}`);
     return 2;
   }

package/src/commands/inspect/task-show.mjs

@@ -40,8 +40,8 @@ const SCRIPT = `
 import json, sys
 from pathlib import Path
 from okstra_project import (
-    resolve_project_root, find_task_root, read_task_manifest,
-    ResolverError,
+    resolve_project_root, task_read_side_snapshot,
+    ResolverError, StateError,
 )
 
 explicit = sys.argv[1]
@@ -55,37 +55,17 @@ except ResolverError as e:
     sys.exit(2)
 
 pr_path = Path(pr)
-task_root = find_task_root(pr_path, task_key)
-if task_root is None:
-    print(json.dumps({"ok": False, "stage": "task_root_missing", "reason": f"no task root for {task_key}"}))
-    sys.exit(1)
-
-manifest = read_task_manifest(task_root)
-if manifest is None:
-    print(json.dumps({"ok": False, "stage": "manifest_missing", "reason": f"task-manifest.json missing in {task_root}"}))
+try:
+    snapshot = task_read_side_snapshot(pr_path, task_key)
+except StateError as e:
+    print(json.dumps({
+        "ok": False,
+        "stage": getattr(e, "stage", None) or "task_snapshot",
+        "reason": str(e),
+    }))
     sys.exit(1)
 
-wf = manifest.get("workflow", {}) or {}
-out = {
-    "ok": True,
-    "projectRoot": str(pr_path),
-    "taskKey": manifest.get("taskKey"),
-    "taskType": manifest.get("taskType"),
-    "taskRoot": str(task_root),
-    "taskBriefPath": manifest.get("taskBriefPath"),
-    "workflow": {
-        "currentPhase": wf.get("currentPhase"),
-        "currentPhaseState": wf.get("currentPhaseState"),
-        "lastCompletedPhase": wf.get("lastCompletedPhase"),
-        "nextRecommendedPhase": wf.get("nextRecommendedPhase"),
-        "routingStatus": wf.get("routingStatus"),
-        "phaseStates": wf.get("phaseStates"),
-    },
-    "resultContract": manifest.get("resultContract"),
-    "artifacts": manifest.get("artifacts"),
-    "modelAssignments": manifest.get("modelAssignments"),
-    "latestRunPath": manifest.get("latestRunPath"),
-}
+out = {"ok": True, **snapshot}
 print(json.dumps(out, ensure_ascii=False, default=str, indent=2))
 `;