okstra 0.201.3 → 0.202.0

package/runtime/python/okstra_ctl/manager_sync.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from okstra_project import TASKS_RELATIVE, StateError, parse_task_key, read_task_catalog, read_task_manifest, slugify
 
 from . import next_phase
+from .next_phase import STATUS_BLOCKED, STATUS_TERMINAL
 from .manager_paths import children_json_path, projects_json_path, snapshots_json_path, task_manifest_path
 from .manager_store import _now_iso, _read_json, _read_json_default, _write_json
 
@@ -89,6 +90,7 @@ def _snapshot_child(project_root: Path, child: dict) -> dict:
             workflow.get("nextRecommendedPhase")
         ),
         "latestRunStatus": str(manifest.get("latestRunStatus") or manifest.get("currentStatus") or ""),
+        "workStatus": str(manifest.get("workStatus") or ""),
         "latestReportRecordPath": str(manifest.get("latestReportRecordPath") or ""),
         "finalVerdict": str(outcome.get("finalVerdict") or ""),
         "crossProjectDependencies": _list_field(outcome, "crossProjectDependencies"),
@@ -125,6 +127,34 @@ def sync_task(home: Path, manager_id: str, task_group: str, task_id: str, *, now
     return payload
 
 
+# 사용자가 `okstra set-work-status` 로 적은 값이 파생 포인터보다 우선한다.
+# 그룹 큐(group_context.catalog_progress)와 같은 순서다. `latestRunStatus` 는
+# phase 한 번의 실행 결과(`completed` / `contract-violated` / `in-progress` …)라
+# task 가 끝났는지 말해 주지 않으므로 요약 분류에 쓰지 않는다.
+_WORK_STATUS_BUCKETS = {
+    "done": "done",
+    "blocked": "blocked",
+    "in-progress": "running",
+    "todo": "planned",
+}
+_POINTER_STATUS_BUCKETS = {
+    STATUS_TERMINAL: "done",
+    STATUS_BLOCKED: "blocked",
+}
+
+
+def summary_bucket(row: dict) -> str:
+    """스냅샷이 있는 하위 task 한 줄을 요약 칸 하나로 분류한다."""
+    if not row.get("exists", False):
+        return "missing"
+    work_status = str(row.get("workStatus") or "")
+    if work_status in _WORK_STATUS_BUCKETS:
+        return _WORK_STATUS_BUCKETS[work_status]
+    pointer = row.get("nextRecommendedPhase")
+    pointer_status = pointer.get("status") if isinstance(pointer, dict) else ""
+    return _POINTER_STATUS_BUCKETS.get(pointer_status, "running")
+
+
 def status_task(home: Path, manager_id: str, task_group: str, task_id: str) -> dict:
     manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
     children = _read_json_default(children_json_path(home, manager_id, task_group, task_id), {"children": []})
@@ -135,21 +165,9 @@ def status_task(home: Path, manager_id: str, task_group: str, task_id: str) -> d
     for child in children.get("children", []):
         if not isinstance(child, dict):
             continue
-        key = child.get("taskKey")
-        snapshot_row = by_key.get(key)
+        snapshot_row = by_key.get(child.get("taskKey"))
         row = {**child, **(snapshot_row or {})}
-        status = str(row.get("latestRunStatus") or row.get("launch", {}).get("status") or "planned")
-        if snapshot_row is None:
-            summary["planned"] += 1
-        elif not row.get("exists", False):
-            summary["missing"] += 1
-        elif status == "done":
-            summary["done"] += 1
-        elif status in {"running", "started", "in-progress"}:
-            summary["running"] += 1
-        elif status == "blocked":
-            summary["blocked"] += 1
-        else:
-            summary["planned"] += 1
+        row["summaryBucket"] = "planned" if snapshot_row is None else summary_bucket(row)
+        summary[row["summaryBucket"]] += 1
         rows.append(row)
     return {"manifest": manifest, "summary": summary, "children": rows, "lastSnapshot": snapshot}

package/runtime/python/okstra_ctl/manager_view.py

@@ -0,0 +1,216 @@
+"""manager 상태를 한 장짜리 HTML 로 그린다.
+
+manager 가 이미 저장한 파일(projects / task manifest / children / snapshots /
+directives / events)만 읽는다. 하위 프로젝트는 읽지 않는다 — 최신 상태가 필요하면
+먼저 `okstra manager task sync` 를 돌리고, 페이지는 각 task 의 마지막 sync 시각을
+보여 준다.
+"""
+from __future__ import annotations
+
+import html
+import re
+import shlex
+from datetime import datetime, timezone
+from pathlib import Path
+
+from okstra_ctl.jsonl import read_jsonl
+
+from .manager_paths import directives_jsonl_path, events_jsonl_path, view_html_path
+from .manager_store import ManagerError, list_projects, list_tasks, load_manager
+from .manager_sync import status_task
+from .paths import find_asset_root
+
+TEMPLATE_RELATIVE = ("templates", "manager", "view.template.html")
+_MARKER = re.compile(r"\{\{([A-Z]+)\}\}")
+BUCKETS = ("planned", "missing", "running", "done", "blocked")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _e(value: object) -> str:
+    return html.escape("" if value is None else str(value))
+
+
+def _chip(bucket: str) -> str:
+    return f'<span class="chip {_e(bucket)}">{_e(bucket)}</span>'
+
+
+def _table(headers: tuple[str, ...], rows: list[list[str]], empty: str) -> str:
+    if not rows:
+        return f'<p class="empty">{_e(empty)}</p>'
+    head = "".join(f"<th>{_e(header)}</th>" for header in headers)
+    body = "".join("<tr>" + "".join(f"<td>{cell}</td>" for cell in row) + "</tr>" for row in rows)
+    return f'<div class="scroll"><table><thead><tr>{head}</tr></thead><tbody>{body}</tbody></table></div>'
+
+
+def _file_link(project_root: str, path: str) -> str:
+    """하위 프로젝트 기준 상대 경로를 절대 file 링크로 바꾼다. 빈 값은 `-`."""
+    if not path:
+        return "-"
+    target = Path(path)
+    if not target.is_absolute() and project_root:
+        target = Path(project_root) / target
+    if not target.is_absolute():
+        return f"<code>{_e(path)}</code>"
+    return f'<a href="{_e(target.as_uri())}"><code>{_e(path)}</code></a>'
+
+
+def _command(*args: str) -> str:
+    return shlex.join(["okstra", "manager", *args])
+
+
+def _summary_tiles(totals: dict[str, int]) -> str:
+    tiles = "".join(
+        f'<div class="tile"><div class="count">{totals[bucket]}</div>'
+        f'<div class="label">{_e(bucket)}</div></div>'
+        for bucket in BUCKETS
+    )
+    return f'<div class="tiles">{tiles}</div>'
+
+
+def _projects_table(projects: list[dict]) -> str:
+    rows = [
+        [
+            f"<code class=\"id\">{_e(project.get('projectId'))}</code>",
+            f"<code>{_e(project.get('projectRoot'))}</code>",
+            _e(project.get("role") or "-"),
+            _e(", ".join(project.get("tags") or []) or "-"),
+            _e(project.get("linkedAt") or "-"),
+        ]
+        for project in projects
+    ]
+    return _table(("Project", "Root", "Role", "Tags", "Linked at"), rows, "No projects registered.")
+
+
+def _child_rows(children: list[dict], roots: dict[str, str]) -> list[list[str]]:
+    rows = []
+    for child in children:
+        launch = child.get("launch") if isinstance(child.get("launch"), dict) else {}
+        phase = child.get("currentPhase") or ""
+        phase_state = child.get("currentPhaseState") or ""
+        assignment = " — ".join(part for part in (child.get("role"), child.get("assignment")) if part)
+        # `task split` 하위 태스크는 assignment 대신 범위 목록을 가진다.
+        assignment = assignment or "; ".join(child.get("scope") or [])
+        rows.append(
+            [
+                f"<code>{_e(child.get('taskKey'))}</code>",
+                _e(child.get("ticketId") or "-"),
+                _chip(str(child.get("summaryBucket") or "planned")),
+                _e(child.get("workStatus") or "-"),
+                _e(f"{phase} ({phase_state})" if phase and phase_state else phase or "-"),
+                _e(child.get("finalVerdict") or "-"),
+                _e(launch.get("status") or "-"),
+                f'<span class="wrap">{_e(assignment or "-")}</span>',
+                _e(child.get("error") or "-"),
+                _file_link("", str(child.get("briefPath") or "")),
+                _file_link(
+                    roots.get(str(child.get("projectId") or ""), ""),
+                    str(child.get("latestReportRecordPath") or ""),
+                ),
+            ]
+        )
+    return rows
+
+
+def _directive_list(directives: list[dict]) -> str:
+    if not directives:
+        return '<p class="empty">No directives.</p>'
+    items = "".join(
+        f"<li><strong>{_e(row.get('scope'))}"
+        f"{' · ' + _e(row.get('projectId')) if row.get('projectId') else ''}</strong>: "
+        f"{_e(row.get('body'))} <span class=\"meta\">{_e(row.get('createdAt'))}</span></li>"
+        for row in directives
+    )
+    return f'<ul class="plain">{items}</ul>'
+
+
+def _event_list(events: list[dict]) -> str:
+    if not events:
+        return '<p class="empty">No events.</p>'
+    items = "".join(
+        f"<li><code>{_e(row.get('createdAt'))}</code> {_e(row.get('event'))}"
+        f"{' · ' + _e(row.get('taskKey')) if row.get('taskKey') else ''}</li>"
+        for row in events
+    )
+    return f'<ul class="plain">{items}</ul>'
+
+
+def _task_panel(home: Path, manager_id: str, task: dict, status: dict, roots: dict[str, str]) -> str:
+    group, task_id = task["taskGroup"], task["taskId"]
+    synced_at = status["lastSnapshot"].get("syncedAt") or ""
+    sync_command = _command(
+        "task", "sync", "--manager-id", manager_id, "--task-group", group, "--task-id", task_id
+    )
+    counts = "".join(
+        f"{_chip(bucket)} {status['summary'][bucket]}"
+        for bucket in BUCKETS
+        if status["summary"][bucket]
+    )
+    head = (
+        f'<div class="task-head"><h3><code>{_e(group)} / {_e(task_id)}</code></h3>'
+        f'<div class="counts">{counts or "<span class=empty>no children</span>"}</div></div>'
+    )
+    meta = (
+        f'<div class="meta">Objective: {_e(task["objective"] or "-")} · '
+        f'Common brief: {_e(status["manifest"].get("commonBriefPath") or "-")} · '
+        f'Progress mode: {_e(task["progressMode"] or "-")}</div>'
+        f'<p class="hint">Last sync: {_e(synced_at or "never")} — refresh with '
+        f"<code>{_e(sync_command)}</code>, then re-run the view command.</p>"
+    )
+    children = _table(
+        ("Child", "Ticket", "Summary", "Work status", "Phase", "Verdict", "Launch", "Assignment", "Error",
+         "Brief", "Latest report"),
+        _child_rows(status["children"], roots),
+        "No child tasks.",
+    )
+    directives = read_jsonl(directives_jsonl_path(home, manager_id, group, task_id))
+    events = read_jsonl(events_jsonl_path(home, manager_id, group, task_id))
+    details = (
+        f"<details><summary>Directives ({len(directives)})</summary>{_directive_list(directives)}</details>"
+        f"<details><summary>Events ({len(events)})</summary>{_event_list(events)}</details>"
+    )
+    return f'<div class="panel">{head}{meta}{children}{details}</div>'
+
+
+def render_view(home: Path, manager_id: str, *, now: str | None = None) -> str:
+    """manager 한 개의 HTML 페이지 본문을 돌려준다."""
+    manager = load_manager(home, manager_id)
+    root = find_asset_root(TEMPLATE_RELATIVE)
+    if root is None:
+        raise ManagerError("manager view template not found: " + "/".join(TEMPLATE_RELATIVE))
+    template = root.joinpath(*TEMPLATE_RELATIVE).read_text(encoding="utf-8")
+    projects = list_projects(home, manager_id)
+    roots = {str(project.get("projectId")): str(project.get("projectRoot") or "") for project in projects}
+    tasks = list_tasks(home, manager_id)
+    totals = dict.fromkeys(BUCKETS, 0)
+    panels = []
+    for task in tasks:
+        status = status_task(home, manager_id, task["taskGroup"], task["taskId"])
+        for bucket in BUCKETS:
+            totals[bucket] += status["summary"][bucket]
+        panels.append(_task_panel(home, manager_id, task, status, roots))
+    meta = (
+        f"Created {_e(manager.get('createdAt') or '-')} · Generated {_e(now or _now_iso())} · "
+        f"{len(projects)} projects · {len(tasks)} manager tasks"
+    )
+    replacements = {
+        "TITLE": _e(f"Okstra manager · {manager.get('managerId') or manager_id}"),
+        "META": meta,
+        "SUMMARY": _summary_tiles(totals),
+        "PROJECTS": _projects_table(projects),
+        "TASKS": "".join(panels) or '<p class="empty">No manager tasks.</p>',
+    }
+    # 한 번에 치환한다. 차례로 바꾸면 앞에서 넣은 사용자 값 속 `{{TASKS}}` 같은
+    # 문자열이 뒤 치환에 다시 걸린다.
+    return _MARKER.sub(lambda match: replacements[match.group(1)], template)
+
+
+def write_view(home: Path, manager_id: str, *, now: str | None = None) -> dict:
+    """페이지를 `managers/<id>/view/index.html` 에 쓰고 경로를 돌려준다."""
+    page = render_view(home, manager_id, now=now)
+    path = view_html_path(home, manager_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(page, encoding="utf-8")
+    return {"managerId": manager_id, "viewPath": str(path), "viewUrl": path.as_uri()}

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -26,6 +26,7 @@ from .convergence_store import write_json_atomic
 from .incremental_carry import sync_prepared_dispatch_queue
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .report_finalize import task_manifest_path
+from .qa_commands import split_verification_command
 from .plan_derivations import extract_tokens, find_derivations
 from .plan_items import (
     NextDispatch,
@@ -577,7 +578,11 @@ def _render_scalar_or_list(key: str, value: object, indent: str = "") -> list[st
     if isinstance(value, Mapping):
         raise PlanItemContractError(f"plan item {key} must be scalar")
     if key in {"command", "commandOrObservation"} and isinstance(value, str):
-        return _render_literal(_label(key), value, indent)
+        command, annotation = split_verification_command(value)
+        rows = _render_literal(_label(key), command, indent)
+        if annotation is not None:
+            rows.append(indent + line("Command annotation (not executable)", annotation))
+        return rows
     return [indent + line(_label(key), value)]
 
 

package/runtime/python/okstra_ctl/qa_commands.py

@@ -98,6 +98,21 @@ def find_unfrozen_installs(cmd: str) -> list[str]:
     return found
 
 
+def split_verification_command(command: str) -> tuple[str, str | None]:
+    """기존 계획의 파일 인용 설명만 분리하며 일반 셸 구문은 보존한다."""
+    match = re.search(r";\s*(existing helper:\s*[^;&|<>$`\n]+:\d+(?:-\d+)?)\s*$", command)
+    if match is None:
+        return command, None
+    executable = command[:match.start()].rstrip()
+    try:
+        words = shlex.split(executable)
+    except ValueError:
+        return command, None
+    if not words:
+        return command, None
+    return executable, match.group(1).strip()
+
+
 def verification_command_defects(command: str) -> list[str]:
     """선언된 작업 폴더를 셸에서 다른 체크아웃으로 바꾸는 명령을 거부한다."""
     try:

package/runtime/python/okstra_ctl/report_finalize.py

@@ -737,6 +737,8 @@ def _closeout_report_paths(ctx: FinalizeContext) -> dict[str, Any]:
     답장을 마크다운으로 그리므로 괄호 안에 경로가 들어간 형태만 클릭되고,
     백틱으로 감싼 경로는 글자로만 남아 사용자가 직접 옮겨 적어야 한다. 리드가
     그 형태를 매번 다시 만들면 어긋날 자리가 생기므로 완성된 문자열을 준다.
+    링크 목적지는 절대 경로다 — 프로젝트 기준 상대 경로는 호스트 cwd 가 다르거나
+    외부 프로그램으로 열 때 해석되지 않는다. 공백이 든 경로는 `<...>` 로 감싼다.
     """
     def rel(path: Path) -> str:
         try:
@@ -744,17 +746,22 @@ def _closeout_report_paths(ctx: FinalizeContext) -> dict[str, Any]:
         except ValueError:
             return str(path)
 
-    paths = {
-        "humanReport": rel(html_view_path(ctx.data_path)),
-        "reportRecord": rel(ctx.data_path),
-        "teamState": rel(ctx.team_state_path),
+    def link_target(path: Path) -> str:
+        target = path.resolve().as_posix()
+        return f"<{target}>" if " " in target else target
+
+    sources = {
+        "humanReport": html_view_path(ctx.data_path),
+        "reportRecord": ctx.data_path,
+        "teamState": ctx.team_state_path,
     }
+    paths = {key: rel(path) for key, path in sources.items()}
     return {
         **paths,
         "renderFullCopy": f"okstra render-final-report {paths['reportRecord']}",
         "markdown": {
-            key: f"[{Path(value).name}]({value})"
-            for key, value in paths.items()
+            key: f"[{path.name}]({link_target(path)})"
+            for key, path in sources.items()
         },
     }
 

package/runtime/python/okstra_ctl/report_html/view_models/final_verification.py

@@ -3,8 +3,7 @@ from __future__ import annotations
 
 from ...release_gate import release_handoff_allowed
 from ..common import evidence_index
-from ..models import HumanReportView, VisualNode
-from ..visualizations import coverage_figure
+from ..models import HumanReportView
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.
@@ -17,25 +16,8 @@ ANCHORED_FIELDS = (
 )
 
 
-def _coverage_nodes(final: dict) -> tuple[VisualNode, ...]:
-    return tuple(
-        VisualNode(
-            row["id"],
-            row["requirement"],
-            "requirement",
-            row["status"],
-            row["artifact"],
-            note=row["status"],
-        )
-        for row in final["validationEvidence"]
-    )
-
-
 def build_final_verification_view(data: dict) -> HumanReportView:
     final = data["finalVerification"]
-    figure = coverage_figure(
-        rows=_coverage_nodes(final), title="Requirement verification coverage"
-    )
     verdict_token = data["finalVerdict"]["verdictToken"]
     context = {
         "humanSummary": data["humanSummary"],
@@ -44,7 +26,6 @@ def build_final_verification_view(data: dict) -> HumanReportView:
         "finalVerdict": data["finalVerdict"],
         "final": final,
         "narrative": final["userNarrative"],
-        "coverageFigure": figure,
         "releaseAllowed": release_handoff_allowed(data),
         "evidenceIndex": evidence_index(data, ANCHORED_FIELDS),
     }
@@ -52,6 +33,6 @@ def build_final_verification_view(data: dict) -> HumanReportView:
         "final-verification",
         "html/tasks/final-verification.template.html",
         context,
-        (figure,),
+        (),
         anchored_fields=ANCHORED_FIELDS,
     )

package/runtime/python/okstra_ctl/report_html/visualizations.py

@@ -356,11 +356,6 @@ def matrix_figure(*, items: Iterable[VisualNode], title: str, x_label: str, y_la
     return replace(dependency_figure(nodes=nodes, edges=(), title=title), kind="matrix", figure_id="matrix", summary=summary)
 
 
-def coverage_figure(*, rows: Iterable[VisualNode], title: str) -> FigureModel:
-    nodes = tuple(rows)
-    return replace(dependency_figure(nodes=nodes, edges=(), title=title), kind="coverage", figure_id="coverage")
-
-
 def timeline_figure(*, events: Iterable[VisualNode], title: str) -> FigureModel:
     nodes = tuple(events)
     edges = tuple(VisualEdge(nodes[i].id, nodes[i + 1].id, "next", "sequence") for i in range(len(nodes) - 1))

package/runtime/python/okstra_ctl/verification_target.py

@@ -13,13 +13,14 @@ import hashlib
 import argparse
 import json
 import re
+import shlex
 import subprocess
 from pathlib import Path
 
 from .execution_mutation_audit import source_content_snapshot
 from .json_boundary import load_owned_object
 from .path_hints import hydrate_active_run_context
-from .qa_commands import verification_command_defects
+from .qa_commands import split_verification_command, verification_command_defects
 
 TARGET_FIELD_RES = {
     "scope": re.compile(r"\*\*Verification scope:\*\*\s*`([^`]*)`"),
@@ -95,6 +96,13 @@ def capture_verification_target(
     if not target or not Path(target).is_absolute():
         raise ValueError("active run context has no absolute verification worktree")
     worktree = Path(target).resolve()
+    declared_command = command
+    command, annotation = split_verification_command(command)
+    prefix = re.match(r"^\s*cd\s+('[^']*'|\"[^\"]*\"|[^\s;&|]+)\s*&&\s*", command)
+    if prefix is not None:
+        directory = shlex.split(prefix.group(1))[0]
+        if Path(directory).is_absolute() and Path(directory).resolve() == worktree:
+            command = command[prefix.end():]
     defects = verification_command_defects(command)
     if defects:
         raise ValueError("; ".join(defects))
@@ -105,11 +113,14 @@ def capture_verification_target(
         raise ValueError(f"verification target mismatch: expected HEAD {expected_head}, actual {head}, root {actual_root}")
     files = source_content_snapshot(worktree, frozenset({".okstra"}))
     digest = hashlib.sha256(json.dumps(files, sort_keys=True).encode()).hexdigest()
-    return {
+    result = {
         "schemaVersion": "1.0", "runManifest": str(manifest_path),
         "taskKey": manifest["taskKey"], "cwd": str(worktree),
         "head": head, "sourceDigest": digest, "command": command,
     }
+    if declared_command != command:
+        result.update(declaredCommand=declared_command, commandAnnotation=annotation)
+    return result
 
 
 def main(argv: list[str] | None = None) -> int:

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

@@ -1,6 +1,6 @@
 ---
 name: okstra-manager
-description: Use when the user wants to manage okstra work across multiple project roots, register or discover projects under a manager, create or update a shared manager task, sync project child-task status into manager state, or launch a child task from manager context. Trigger words include "okstra manager", "okstra-manager", "multiple projects", "cross-project", "group projects together", "manager task".
+description: Use when the user wants to manage okstra work across multiple project roots, register or discover projects under a manager, create or update a shared manager task, sync project child-task status into manager state, split a Linear project or issue into per-project scoped briefs, or launch a child task from manager context. Trigger words include "okstra manager", "okstra-manager", "multiple projects", "cross-project", "group projects together", "manager task", "split this Linear project", "brief per project".
 ---
 
 # OKSTRA Manager
@@ -28,19 +28,68 @@ okstra manager task sync --manager-id <manager-id> --task-group <task-group> --t
 okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>]
 okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text>
 okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>]
+okstra manager task split --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
+okstra manager list managers
+okstra manager list projects --manager-id <manager-id>
+okstra manager list tasks --manager-id <manager-id>
+okstra manager view --manager-id <manager-id>
 ```
 
 - Public child task identity is `project-id:task-group:task-id`.
 - `okstra manager new task --task ...` should prefer the full child key form above. The CLI also accepts shorthand under the command's `--task-group`, but the full key is the public form to show users.
 - When a manager task id differs from the actual child task id for a specific project, pass `--child-task-id <child-task-id>` to `task assign` and `task run`.
 
+## Tracker Split
+
+Use this when one Linear project, or one parent issue, covers work in several registered projects and each project needs its own brief. A Linear project can point at several projects, and one issue can too; every (issue, project) pair gets its own brief and child task.
+
+1. Run `okstra manager list projects --manager-id <manager-id>`. These are the only valid targets. Register a missing repo with `okstra manager new project ...` first.
+2. Fetch from the Linear MCP: the project (`get_project`) and its issues (`list_issues` filtered by that project), then each issue with `get_issue`, including sub-issues and blocking or related links. If the Linear tools are missing, load them once with `ToolSearch`; if they are still missing, ask the user to paste the bodies. Never invent ticket content.
+3. For each issue, propose target projects from evidence: labels, team, repository names or paths in the body. Confirm with `AskUserQuestion` (multi-select, recommended projects first, reason in each description).
+4. For each (issue, project) pair, draft the scope: the part of the issue this project implements. Confirm it with `AskUserQuestion` offering one or two drafts plus a custom-input option. A pair without scope is rejected by the CLI.
+5. Author each pair's brief fields under the okstra-brief-gen brief contract: bodies verbatim, `EB-NNN` / `PB-NNN` / `EO-NNN` items as `<id> <observable condition> — verify: <how>`, anything without an observation method under `externalGates`, and `openQuestions` rows prefixed `general:`, `terminology:`, `intent-check:`, `conversion-block:` or `adr-candidate:`.
+6. Write the plan JSON below with the Write tool to a scratch path outside the project roots, then run `okstra manager task split ... --plan <path>`.
+   - `split plan rejected` or `rendered briefs failed validate-brief`: fix the named fields and run it again. Nothing was written.
+   - `briefs already exist with different content`: show the listed paths and ask before adding `--overwrite`, which replaces hand edits. Adding issues to an earlier split changes every brief's Related Task Graph, so existing briefs are listed too.
+7. Each `Brief N task key` is `<project-id>:<task-group>:<child-task-id>`. Start one with `okstra manager task run ... --project-id <project-id> --child-task-id <child-task-id>` and follow the Child Launch Rule. The packet already carries `--task-brief`, and `--task-type` until the child task exists.
+
+Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommendedPhase` is `requirements-discovery` (default), `error-analysis` or `improvement-discovery`; `relations[].relation` uses the brief Related Task Graph values; list fields may be omitted.
+
+```json
+{
+  "schemaVersion": 1,
+  "source": {"kind": "project", "ref": "<Linear URL>", "title": "<title>", "fetchedVia": "<tool>", "fetchedAt": "YYYY-MM-DD HH:MM", "body": "<verbatim>"},
+  "issues": [
+    {
+      "ticketId": "LIN-12", "title": "<title>", "url": "<Linear URL>", "fetchedVia": "<tool>", "fetchedAt": "YYYY-MM-DD HH:MM", "body": "<verbatim>",
+      "relations": [{"relation": "blocked-by", "to": "LIN-11", "source": "<where the link came from>", "impact": "<what the next phase must keep>"}],
+      "assignments": [
+        {
+          "projectId": "<registered project id>", "scope": ["<work in this project>"], "outOfScope": [],
+          "recommendedPhase": "requirements-discovery",
+          "context": "<text>", "problem": "<text>", "desiredOutcome": "<text>",
+          "expectedBehavior": [], "preservedBehavior": [], "expectedOutcome": [],
+          "externalGates": [], "constraints": [], "openQuestions": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+The CLI writes each brief to `<projectRoot>/.okstra/briefs/<task-group>/<ticketId>-<file-title>.md` with a `## Project Scope` section: this project's scope, `outOfScope`, and the scope of every other project the same issue went to. It validates every brief with the brief validator before writing any file, registers the child tasks, and keeps the plan at `split-plan.json` in the manager task directory.
+
+## Overview Page
+
+When the user wants to see a manager at a glance, run `okstra manager task sync ...` for each task listed by `okstra manager list tasks ...` whose snapshot must be current, then run `okstra manager view --manager-id <manager-id>` and give the user the returned `View URL`. The page reads manager files only, so each task shows the state of its last sync and prints its own sync command.
+
 ## Child Launch Rule
 
 For launching child work:
 
 1. Run `okstra manager task sync ...` if the manager snapshot must be refreshed first.
 2. Run `okstra manager task run ...`.
-3. Read the returned fixed fields `Backend`, `Worker dispatch backend`, `Project root`, `Context path`, and every numbered `Run arg N`.
-4. Use that launch packet for the host-native child lead handoff.
+3. Read the returned fixed fields `Backend`, `Worker dispatch backend`, `Project root`, `Context path`, `Run command`, every numbered `Run arg N`, and `Shell command`.
+4. Give the user the `Shell command` line verbatim and tell them to run it in a new terminal. It starts the installed launcher in the child project: the launcher fills the task type and brief from the child task manifest or asks for them, prepares the run with the manager context directive, and starts the child lead as a separate host process (`Backend` `spawn-process`).
 
-The launch packet remains the source of truth. Do not rebuild child args by hand.
+Do not run the `Shell command` through this session's Bash tool: it opens an interactive host session. Do not rebuild it from `Run arg N` or swap in `okstra run`, which drops the task inputs and the directive for a lead host.

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

@@ -491,6 +491,6 @@ Follow the rendered launch prompt's "Progress, remaining work, and recommendatio
 ## Output Rules
 
 - Echo each captured answer (`result.echo`) on one short line so the user sees what was registered.
-- Name every file you show the user as a markdown link — `[<what it is>](<path>)`, with the path inside the parentheses. That is the only form the host renders as clickable; a path in backticks is text the user has to copy out. The `report-finalize` result's `reportPaths.markdown` carries the run's report, report record, and team state already in that form. Commands stay in backticks — a link is for a file, not for something to run.
+- Name every file you show the user as a markdown link — `[<short label>](<absolute path>)`, with the absolute path inside the parentheses and a short label naming what the file is. A relative destination does not open from an external program. That is the only form the host renders as clickable; a path in backticks is text the user has to copy out. The `report-finalize` result's `reportPaths.markdown` carries the run's report, report record, and team state already in that form. Commands stay in backticks — a link is for a file, not for something to run.
 - Never invent identity; if a `text` prompt returns an empty answer where the wizard rejects it, the user must retry.
 - After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, finish after Step 6 and any same-run recovery, unless the user has already authorized continuing the task through further phases. In an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When `report-finalize` returns `recovery.mode: same-run`, continue the authorized corrections in this run and execute `recovery.resumeCommand` before closeout; preserve approvals and model choices without reopening the wizard. The command and owner issues are supplied by `report_finalize._finalize_recovery`. When the lead (or this skill, after the lead returns) reports a successfully finalized run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered, and do not say `/okstra-inspect`; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed with `recovery.mode: phase-reentry` → name the cause and use `nextCommand` for the recorded earlier phase; otherwise `/okstra-inspect status`.

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

@@ -140,6 +140,15 @@ Then create the file — paste the literal `projectRoot` from Step 2 and the lit
 okstra setup --yes --project-root /abs/path/to/projectRoot --project-id my-project-id
 ```
 
+`okstra setup` also refreshes the okstra-managed citation-guidance block in
+`<PROJECT_ROOT>/CLAUDE.md` and `AGENTS.md` when those files already exist (it never
+creates them). The block tells agents not to carry okstra-internal references — report
+section numbers, `C-NNN` clarification ids, run/stage ids, `.okstra/...` paths — into
+writing that is not an okstra report, where the reader cannot resolve them. The command
+reports the files it touched in its JSON `citationGuidance` array; a failure there is a
+`warning:` line, not a non-zero exit. Tell the user which guidance files were updated so
+they can review the appended block.
+
 ## Step 3.5 (optional): project customisation
 
 The built-in defaults work for most projects — skip straight to Step 4