okstra 0.102.4 → 0.103.0

package/runtime/python/okstra_ctl/manager_sync.py

@@ -0,0 +1,144 @@
+"""Read project-local okstra state into manager-owned snapshots."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from okstra_project import TASKS_RELATIVE, parse_task_key, read_task_catalog, read_task_manifest, slugify
+
+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
+
+
+def _project_map(home: Path, manager_id: str) -> dict[str, dict]:
+    projects = _read_json_default(projects_json_path(home, manager_id), {"projects": []})
+    return {
+        str(project.get("projectId")): project
+        for project in projects.get("projects", [])
+        if isinstance(project, dict) and project.get("projectId")
+    }
+
+
+def _phase_outcome(manifest: dict) -> dict:
+    value = manifest.get("phaseOutcome")
+    return value if isinstance(value, dict) else {}
+
+
+def _workflow(manifest: dict) -> dict:
+    value = manifest.get("workflow")
+    return value if isinstance(value, dict) else {}
+
+
+def _list_field(payload: dict, field: str) -> list:
+    value = payload.get(field)
+    return list(value) if isinstance(value, list) else []
+
+
+def _resolve_task_root_read_only(project_root: Path, task_key: str) -> Path | None:
+    _, task_group, task_id = parse_task_key(task_key)
+    requested_key = task_key.lower()
+    for entry in read_task_catalog(project_root):
+        entry_key = entry.get("taskKey") or ""
+        if not isinstance(entry_key, str) or entry_key.lower() != requested_key:
+            continue
+        relative_path = entry.get("taskRootPath") or entry.get("taskRoot") or ""
+        if not isinstance(relative_path, str) or not relative_path:
+            continue
+        candidate = project_root / relative_path if not Path(relative_path).is_absolute() else Path(relative_path)
+        if candidate.is_dir():
+            return candidate
+    slug_path = project_root / TASKS_RELATIVE / slugify(task_group) / slugify(task_id)
+    if slug_path.is_dir():
+        return slug_path
+    return None
+
+
+def _snapshot_child(project_root: Path, child: dict) -> dict:
+    task_key = str(child.get("taskKey") or "")
+    base = {
+        "projectId": str(child.get("projectId") or ""),
+        "taskGroup": str(child.get("taskGroup") or ""),
+        "taskId": str(child.get("taskId") or ""),
+        "taskKey": task_key,
+        "exists": False,
+        "taskRoot": "",
+    }
+    task_dir = _resolve_task_root_read_only(project_root, task_key)
+    if task_dir is None:
+        return base
+    manifest = read_task_manifest(task_dir) or {}
+    workflow = _workflow(manifest)
+    outcome = _phase_outcome(manifest)
+    return {
+        **base,
+        "exists": True,
+        "taskRoot": str(task_dir),
+        "taskType": str(manifest.get("taskType") or ""),
+        "currentPhase": str(workflow.get("currentPhase") or ""),
+        "currentPhaseState": str(workflow.get("currentPhaseState") or ""),
+        "lastCompletedPhase": str(workflow.get("lastCompletedPhase") or ""),
+        "nextRecommendedPhase": str(workflow.get("nextRecommendedPhase") or ""),
+        "latestRunStatus": str(manifest.get("latestRunStatus") or manifest.get("currentStatus") or ""),
+        "latestReportPath": str(manifest.get("latestReportPath") or ""),
+        "finalVerdict": str(outcome.get("finalVerdict") or ""),
+        "crossProjectDependencies": _list_field(outcome, "crossProjectDependencies"),
+        "recommendedNextSteps": _list_field(outcome, "recommendedNextSteps"),
+        "openClarifications": _list_field(outcome, "openClarifications"),
+    }
+
+
+def sync_task(home: Path, manager_id: str, task_group: str, task_id: str, *, now: str | None = None) -> dict:
+    _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": []})
+    projects = _project_map(home, manager_id)
+    rows = []
+    for child in children.get("children", []):
+        if not isinstance(child, dict):
+            continue
+        project = projects.get(str(child.get("projectId") or ""))
+        if project is None:
+            rows.append({**child, "exists": False, "error": "unknown project membership"})
+            continue
+        root = Path(str(project.get("projectRoot") or ""))
+        if not root.is_dir():
+            rows.append({**child, "exists": False, "error": f"missing project root: {root}"})
+            continue
+        rows.append(_snapshot_child(root, child))
+    payload = {
+        "managerId": manager_id,
+        "taskGroup": task_group,
+        "taskId": task_id,
+        "syncedAt": now or _now_iso(),
+        "children": rows,
+    }
+    _write_json(snapshots_json_path(home, manager_id, task_group, task_id), payload)
+    return payload
+
+
+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": []})
+    snapshot = _read_json_default(snapshots_json_path(home, manager_id, task_group, task_id), {"children": []})
+    by_key = {row.get("taskKey"): row for row in snapshot.get("children", []) if isinstance(row, dict)}
+    rows = []
+    summary = {"planned": 0, "missing": 0, "running": 0, "done": 0, "blocked": 0}
+    for child in children.get("children", []):
+        if not isinstance(child, dict):
+            continue
+        key = child.get("taskKey")
+        snapshot_row = by_key.get(key)
+        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
+        rows.append(row)
+    return {"manifest": manifest, "summary": summary, "children": rows, "lastSnapshot": snapshot}

package/runtime/python/okstra_ctl/wizard.py

@@ -24,6 +24,7 @@ import math
 import re
 import subprocess
 from dataclasses import asdict, dataclass, field
+from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Optional
 
@@ -228,6 +229,35 @@ def _project_relative_path(path: Path, project_root: Path) -> str:
         return str(path)
 
 
+def _project_relative_value(path_value: str, project_root: Path) -> str:
+    p = Path(path_value)
+    if p.is_absolute():
+        return _project_relative_path(p, project_root)
+    return str(p)
+
+
+def _parse_iso_timestamp(value: Any) -> float:
+    if not isinstance(value, str):
+        return 0.0
+    text = value.strip()
+    if not text:
+        return 0.0
+    if text.endswith("Z"):
+        text = f"{text[:-1]}+00:00"
+    try:
+        return datetime.fromisoformat(text).timestamp()
+    except ValueError:
+        return 0.0
+
+
+def _file_recency(path: Path) -> float:
+    try:
+        stat = path.stat()
+    except OSError:
+        return 0.0
+    return max(stat.st_mtime, float(getattr(stat, "st_birthtime", 0.0) or 0.0))
+
+
 def _accept_brief_path(state: WizardState, path: Path) -> None:
     """Record a validated brief and derive safe identity suggestions.
 
@@ -1128,21 +1158,51 @@ def _submit_task_pick(state: WizardState, value: str) -> Optional[str]:
 def _suggest_recent_task_groups(
     state: WizardState, limit: int = _RECOMMENDATION_CAP
 ) -> list[str]:
-    """프로젝트 catalog 에서 최근 task-group 후보를 limit 개까지 반환."""
+    """최근 task/brief 활동에서 task-group 후보를 limit 개까지 반환."""
     if not state.project_root:
         return []
+    project_root = Path(state.project_root)
+    scores: dict[str, float] = {}
+    orders: dict[str, int] = {}
     try:
-        tasks = list_project_tasks(Path(state.project_root))
+        tasks = list_project_tasks(project_root)
     except (OSError, StateError):
-        return []
-    seen: list[str] = []
-    for entry in tasks:
+        tasks = []
+    for index, entry in enumerate(tasks):
         tg = entry.get("taskGroup") or ""
-        if tg and tg not in seen:
-            seen.append(tg)
-        if len(seen) >= limit:
-            break
-    return seen
+        if not tg:
+            continue
+        scores[tg] = max(
+            scores.get(tg, 0.0),
+            _parse_iso_timestamp(entry.get("updatedAt")),
+        )
+        orders[tg] = min(orders.get(tg, index), index)
+
+    brief_root = project_root / ".okstra" / "briefs"
+    if brief_root.is_dir():
+        next_order = len(orders)
+        for group_dir in brief_root.iterdir():
+            if not group_dir.is_dir():
+                continue
+            latest_brief = max(
+                (
+                    _file_recency(path)
+                    for path in group_dir.rglob("*.md")
+                    if path.is_file()
+                ),
+                default=0.0,
+            )
+            if latest_brief <= 0.0:
+                continue
+            group = group_dir.name
+            scores[group] = max(scores.get(group, 0.0), latest_brief)
+            orders.setdefault(group, next_order)
+            next_order += 1
+
+    return sorted(
+        scores,
+        key=lambda group: (-scores[group], orders[group], group),
+    )[:limit]
 
 
 def _suggest_recent_task_ids(
@@ -1168,6 +1228,37 @@ def _suggest_recent_task_ids(
     return seen
 
 
+def _recently_used_brief_times(state: WizardState) -> dict[str, float]:
+    if not state.project_root or not state.task_group:
+        return {}
+    project_root = Path(state.project_root)
+    try:
+        tasks = list_project_tasks(project_root)
+    except (OSError, StateError):
+        return {}
+    out: dict[str, float] = {}
+    for entry in tasks:
+        if entry.get("taskGroup") != state.task_group:
+            continue
+        task_root = entry.get("_resolvedTaskRoot") or ""
+        manifest = read_task_manifest(Path(task_root)) if task_root else None
+        brief_path = ""
+        if isinstance(manifest, dict):
+            value = manifest.get("taskBriefPath")
+            brief_path = value if isinstance(value, str) else ""
+        if not brief_path:
+            value = entry.get("taskBriefPath")
+            brief_path = value if isinstance(value, str) else ""
+        if not brief_path:
+            continue
+        relpath = _project_relative_value(brief_path, project_root)
+        out[relpath] = max(
+            out.get(relpath, 0.0),
+            _parse_iso_timestamp(entry.get("updatedAt")),
+        )
+    return out
+
+
 def _suggest_group_briefs(state: WizardState, limit: int = 6) -> list[str]:
     """Return recent okstra-brief outputs for the selected task-group.
 
@@ -1181,6 +1272,7 @@ def _suggest_group_briefs(state: WizardState, limit: int = 6) -> list[str]:
     root = project_root / ".okstra" / "briefs" / state.task_group
     if not root.is_dir():
         return []
+    used_at_by_relpath = _recently_used_brief_times(state)
     candidates: list[tuple[float, str]] = []
     for path in root.rglob("*.md"):
         if not path.is_file():
@@ -1192,11 +1284,9 @@ def _suggest_group_briefs(state: WizardState, limit: int = 6) -> list[str]:
                     continue
             except WizardError:
                 continue
-        try:
-            mtime = path.stat().st_mtime
-        except OSError:
-            mtime = 0.0
-        candidates.append((mtime, _project_relative_path(path, project_root)))
+        relpath = _project_relative_path(path, project_root)
+        recency = max(_file_recency(path), used_at_by_relpath.get(relpath, 0.0))
+        candidates.append((recency, relpath))
     candidates.sort(key=lambda item: (-item[0], item[1]))
     return [rel for _, rel in candidates[:limit]]
 

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

@@ -252,9 +252,9 @@ Order of operations:
           unavailable on this repo, network error), **do NOT silently
           continue with full recursion**. Disable the "Generate the full
           tree recursively" option for this branch, default to
-          `Parent only; list children in Related Artifacts`, and surface the
-          GraphQL failure to the user in one line so they can decide whether
-          to paste child bodies manually.
+          `Parent only; list children in Related Artifacts and Related Task
+          Graph`, and surface the GraphQL failure to the user in one line so
+          they can decide whether to paste child bodies manually.
      - Notion: child pages / sub-pages
    - If there is **one or more** child, ask **once at the top parent**:
      - `AskUserQuestion` (single-select)
@@ -263,7 +263,8 @@ Order of operations:
          1. `Full tree` (recommended) — walk children, grandchildren, …
             via BFS/DFS and emit one brief per node.
          2. `Parent only` — single brief. Children are not fetched; their
-            keys/URLs are recorded under Related Artifacts.
+            keys/URLs are recorded under Related Artifacts and as `parent-of`
+            rows in Related Task Graph.
          3. `Selected` — multi-select the direct children; for each chosen
             child, apply option-1 policy recursively to that branch.
    - For options 1 / 3, **recurse into Step 1b sub-steps 3–5** for every
@@ -294,6 +295,25 @@ Order of operations:
        (`sub/<ticket-id>-<file-title>.md`)
      bidirectionally. (Non-direct ancestors/descendants are tracked via the
      frontmatter `parent-id` chain.)
+   - Each generated brief's `Related Task Graph` should contain the same full
+     split topology, not only the current node's direct edges, so downstream
+     phases can start from any child brief without losing order or dependency
+     context. Use one row per source-backed edge with these columns:
+     `From | Relation | To | Direction | Source | Impact`.
+     - `From` / `To` use task key, brief id, tracker id, or URL. The edge
+       direction is `From` → `To`.
+     - `Relation` is one of `parent-of`, `child-of`, `depends-on`, `blocks`,
+       `blocked-by`, `follow-up-of`, `split-from`, `duplicates`, `related-to`.
+     - `Direction` is `directed` for parentage/ordering relations and
+       `undirected` for `duplicates` / `related-to`.
+     - `Source` names the evidence for the edge: tracker linked issue,
+       markdown task-list checkbox, reporter statement, manual split, or prior
+       okstra task.
+     - `Impact` states what the next phase must preserve, such as "run after
+       API contract" or "avoid duplicate implementation".
+     Do not invent graph edges from filename similarity or topic overlap; if a
+     relation is unclear, use `related-to` + `undirected` only when the source
+     explicitly says the items are related.
    - If there are no children, proceed with a single brief (depth 0).
 
 ### 1c. `Link URL`
@@ -680,6 +700,9 @@ Required sections:
 - **Desired Outcome** — success shape, not a solution prescription.
 - **Constraints** — deadlines, compatibility, technical/operational limits.
 - **Related Artifacts** — files, URLs, issues, prior task-keys.
+- **Related Task Graph** — structured task-to-task edges when the work was
+  split, linked, or ordered by the source. Use `_(none)_` when no source-backed
+  edge exists.
 - **Open Questions** — anything the user already flagged as undecided
   (becomes raw material for `requirements-discovery`).
 - **Task Continuity Notes** — if the target task's
@@ -763,7 +786,7 @@ Material).
 
 The installed template `~/.okstra/templates/reports/brief.template.md` is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, and section ordering. The template's inline `<!-- author guidance -->` HTML comments are fill-in scaffolding for the author, NOT part of the artifact: render the file with per-brief values substituted and **strip every `<!-- ... -->` comment** so the final brief carries none. Leave any section's body as `_(none)_` rather than fabricating content.
 
-**Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). For the error-feedback variant (`scope` omitted ⇒ `reporter-input`), use the reporter-input shape: KEEP `## Source Material` (the chosen cluster's anonymized error records) and `## Problem / Symptom`, and OMIT the codebase-only `## Scan Scope` / `## Priority Lenses` sections. The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to all variants.
+**Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). For the error-feedback variant (`scope` omitted ⇒ `reporter-input`), use the reporter-input shape: KEEP `## Source Material` (the chosen cluster's anonymized error records) and `## Problem / Symptom`, and OMIT the codebase-only `## Scan Scope` / `## Priority Lenses` sections. The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Related Task Graph / Open Questions / Reporter Confirmations / Augmentation) apply to all variants.
 
 ### Required sections by variant
 
@@ -775,6 +798,7 @@ The installed template `~/.okstra/templates/reports/brief.template.md` is the by
 | `## Desired Outcome` | Required | Required | Required |
 | `## Constraints` | Required | Required | Required |
 | `## Related Artifacts` | Required | Required | Required |
+| `## Related Task Graph` | Required — `_(none)_` or canonical table | Required — `_(none)_` or canonical table | Required — `_(none)_` or canonical table |
 | `## Open Questions` | Required | Required | Required |
 | `## Scan Scope` | Not applicable — omit | Required — one bullet per `scan-scope` path with a short description of what lives there | Not applicable — omit |
 | `## Priority Lenses` | Not applicable — omit | Required — one bullet per priority lens with a short rationale for why that lens applies to this scope | Not applicable — omit |
@@ -958,8 +982,9 @@ is set (Step 6.5), and **before** printing the Step 7 hand-off message, you
 MUST validate every brief produced this run. The validator enforces the
 labelled-handoff contract — required frontmatter keys, Augmentation labels,
 `intent-inference ↔ intent-check:` auto-mirroring, `parent-id`/`depth`
-consistency, `reporter-confirmations` markers, and the codebase-scan
-`scope`/`Scan Scope`/`Priority Lenses` rules.
+consistency, `reporter-confirmations` markers, `Related Task Graph`
+table shape/relation values, and the codebase-scan `scope`/`Scan Scope`/
+`Priority Lenses` rules.
 
 1. Run the validator over the briefs directory:
 

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

@@ -0,0 +1,44 @@
+---
+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", "여러 프로젝트", "cross-project", "프로젝트 묶어서", "manager task".
+---
+
+# OKSTRA Manager
+
+Thin conversational wrapper over `okstra manager`. Manager state and child launch decisions belong to the CLI JSON/output, not to this skill.
+
+## Bash Invocation Rule
+
+Every command in this skill must begin with the literal token `okstra`. Do not introduce shell variables, command substitution, leading environment assignments, or alternate wrappers around `okstra manager`.
+
+## Command Surface
+
+Use the CLI output as the source of truth.
+
+```bash
+okstra manager init --manager-id <manager-id> --json
+okstra manager discover-projects --json
+okstra manager new project --manager-id <manager-id> --project-id <project-id> --project-root <abs-path> [--role <role>] [--tag <tag>] --json
+okstra manager new task-group --manager-id <manager-id> --task-group <task-group> --json
+okstra manager new task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --task <project-id:task-group:task-id> --json
+okstra manager task status --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --json
+okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --json
+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>] --json
+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> --json
+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>] --json
+```
+
+- 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`.
+
+## Child Launch Rule
+
+For launching child work:
+
+1. Run `okstra manager task sync ... --json` if the manager snapshot must be refreshed first.
+2. Run `okstra manager task run ... --json`.
+3. Read the returned launch packet fields such as `backend`, `projectRoot`, `contextPath`, and `runArgs`.
+4. Use that launch packet for the host-native child lead handoff.
+
+The launch packet remains the source of truth. Do not rebuild child args by hand.

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

@@ -120,9 +120,9 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
 
 That is the entire interactive flow. The wizard handles:
 
-- new-vs-existing task split (남은 작업 — `workStatus != done` — 최신순 3개 추천 + 직접 입력), task-group / task-id slug validation (각각 최근 후보 3개 추천 + 직접 입력),
+- new-vs-existing task split (남은 작업 — `workStatus != done` — 최신순 3개 추천 + 직접 입력), task-group / task-id slug validation (task-group 은 최근 task 사용 + 최근 `.okstra/briefs/<group>/` 생성 활동을 합산한 최신 후보 3개 추천 + 직접 입력, task-id 는 같은 group 의 최근 후보 3개 추천 + 직접 입력),
 - task-type pick (추천 3개 — `nextRecommendedPhase` recommended / 현재 phase 재실행 / 라이프사이클 다음 단계 — + 직접 입력; 직접 입력은 후속 `text` 단계에서 전체 task-type 화이트리스트로 검증),
-- brief path — **entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 질문** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, direct input last; `유지 / 변경` for existing entry tasks). downstream task-type 은 manifest 의 brief 를 자동 carry-in 하고, 등록 brief 가 없으면 `brief_carry` 3-옵션(entry 전환 추천 / 직접 입력 / 중단)이 뜬다. `release-handoff` 는 brief 단계가 아예 없다 — prepare 가 검증 보고서 인용 input 문서를 생성한다,
+- brief path — **entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 질문** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `유지 / 변경` for existing entry tasks). downstream task-type 은 manifest 의 brief 를 자동 carry-in 하고, 등록 brief 가 없으면 `brief_carry` 3-옵션(entry 전환 추천 / 직접 입력 / 중단)이 뜬다. `release-handoff` 는 brief 단계가 아예 없다 — prepare 가 검증 보고서 인용 input 문서를 생성한다,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
 - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick. approved-plan 선택 시 그 run 의 sibling `user-responses/` 에서 plan 과 source-report·seq 가 일치하는, 보고서에서 내보낸 `## APPROVAL` sidecar 를 감지하면 approve-confirm 단계가 3-옵션(`yes_apply` 내보낸 기록대로 승인+옵션 적용 추천 / `yes` 승인만 / `no` 중단)으로 확장된다 — `yes_apply` 는 옵션을 plan 의 `optionCandidates` 에 대해 검증한 뒤 기존 승인·옵션 경로로 적용한다,
 - `release-handoff`-only sub-flow: approved plan 자동 해소 후 `handoff_stage_pick` 멀티선택 — eligible stage 묶음(stage-group) 또는 전체 task(accepted whole-task 검증 보고서 존재 시) 선택; 결과는 render-args 의 `stages` 키(csv, whole-task 면 빈 값)로 나간다,

package/runtime/templates/reports/brief.template.md

@@ -96,6 +96,31 @@ none.>
 
 - <file path / URL / issue / prior task-key>
 
+## Related Task Graph
+
+<!-- author guidance — strip out at fill-in time:
+Use this section when the source ticket / reporter / split operation exposes
+relationships between this task and other tasks. The table is copied into
+every brief generated from the same split so each downstream phase can see
+the whole topology from a single brief.
+
+Columns:
+- From / To: task key, brief id, tracker id, or URL. Direction is encoded by
+  `From` → `To`.
+- Relation: one of `parent-of`, `child-of`, `depends-on`, `blocks`,
+  `blocked-by`, `follow-up-of`, `split-from`, `duplicates`, `related-to`.
+- Direction: `directed` for ordering/parentage relations, `undirected` for
+  `duplicates` / `related-to`.
+- Source: where the edge came from (tracker linked issue, task-list checkbox,
+  reporter statement, manual split, prior okstra task).
+- Impact: what the next phase must preserve about this edge.
+
+Use `_(none)_` when there are no known task relationships. Do not invent
+edges from filename similarity or topic overlap.
+-->
+
+_(none)_
+
 ## Open Questions
 
 <!-- author guidance — strip out at fill-in time:

package/runtime/validators/validate-brief.py

@@ -33,6 +33,8 @@ Checks performed per brief file:
 11. codebase-scan variant (`scope: codebase`): the Scan Scope section is
     non-empty and Priority Lenses lists 1–4 values from the lens whitelist
     (`scripts/okstra_ctl/improvement_lenses.py` SSOT).
+12. When present, `Related Task Graph` is a markdown table with the canonical
+    columns and relation/direction values from the okstra-brief contract.
 
 Exit code 0 on PASS, 1 on FAIL.
 """
@@ -91,6 +93,24 @@ REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
 
 SCOPE_VALUES = {"reporter-input", "codebase"}
 
+TASK_GRAPH_HEADER = ["From", "Relation", "To", "Direction", "Source", "Impact"]
+
+DIRECTED_TASK_RELATIONS = {
+    "parent-of",
+    "child-of",
+    "depends-on",
+    "blocks",
+    "blocked-by",
+    "follow-up-of",
+    "split-from",
+}
+
+UNDIRECTED_TASK_RELATIONS = {"duplicates", "related-to"}
+
+TASK_RELATIONS = DIRECTED_TASK_RELATIONS | UNDIRECTED_TASK_RELATIONS
+
+TASK_RELATION_DIRECTIONS = {"directed", "undirected"}
+
 _HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
 
 
@@ -265,6 +285,112 @@ def check_codebase_scope(text: str, errors: list[str]) -> None:
         )
 
 
+def parse_markdown_table_row(line: str) -> list[str]:
+    """Return markdown table cells without the outer pipes."""
+    stripped = line.strip()
+    if not stripped.startswith("|") or not stripped.endswith("|"):
+        return []
+    return [cell.strip() for cell in stripped.strip("|").split("|")]
+
+
+def is_markdown_table_separator(cells: list[str]) -> bool:
+    return bool(cells) and all(re.fullmatch(r":?-{3,}:?", cell) for cell in cells)
+
+
+def check_related_task_graph(text: str, errors: list[str]) -> None:
+    body = section_body(text, "Related Task Graph")
+    if not body.strip():
+        return
+
+    lines = [line.strip() for line in body.splitlines() if line.strip()]
+    if all(is_placeholder(line) or is_template_example(line) for line in lines):
+        return
+
+    table_lines = [line for line in lines if line.startswith("|")]
+    if not table_lines:
+        errors.append(
+            "Related Task Graph must be a markdown table or the literal _(none)_"
+        )
+        return
+
+    if len(table_lines) < 2:
+        errors.append("Related Task Graph table must include a header and separator")
+        return
+
+    header = parse_markdown_table_row(table_lines[0])
+    if header != TASK_GRAPH_HEADER:
+        errors.append(
+            "Related Task Graph header must be "
+            f"{TASK_GRAPH_HEADER}, got {header}"
+        )
+        return
+
+    separator = parse_markdown_table_row(table_lines[1])
+    if len(separator) != len(TASK_GRAPH_HEADER) or not is_markdown_table_separator(
+        separator
+    ):
+        errors.append("Related Task Graph separator row is malformed")
+        return
+
+    for row_number, line in enumerate(table_lines[2:], start=1):
+        cells = parse_markdown_table_row(line)
+        if len(cells) != len(TASK_GRAPH_HEADER):
+            errors.append(
+                f"Related Task Graph row {row_number} has {len(cells)} cells; "
+                f"expected {len(TASK_GRAPH_HEADER)}"
+            )
+            continue
+
+        row = dict(zip(TASK_GRAPH_HEADER, cells))
+        relation = row["Relation"]
+        direction = row["Direction"]
+        source = row["Source"]
+        impact = row["Impact"]
+        from_ref = row["From"]
+        to_ref = row["To"]
+
+        for key in TASK_GRAPH_HEADER:
+            if not row[key]:
+                errors.append(f"Related Task Graph row {row_number} has empty {key}")
+
+        if from_ref and to_ref and from_ref == to_ref:
+            errors.append(
+                f"Related Task Graph row {row_number} links {from_ref!r} to itself"
+            )
+
+        if relation not in TASK_RELATIONS:
+            errors.append(
+                f"Related Task Graph row {row_number} has unknown relation "
+                f"{relation!r}; allowed: {sorted(TASK_RELATIONS)}"
+            )
+
+        if direction not in TASK_RELATION_DIRECTIONS:
+            errors.append(
+                f"Related Task Graph row {row_number} has unknown Direction "
+                f"{direction!r}; allowed: {sorted(TASK_RELATION_DIRECTIONS)}"
+            )
+
+        if relation in DIRECTED_TASK_RELATIONS and direction != "directed":
+            errors.append(
+                f"Related Task Graph row {row_number} relation {relation!r} "
+                "must use Direction=directed"
+            )
+        elif relation in UNDIRECTED_TASK_RELATIONS and direction != "undirected":
+            errors.append(
+                f"Related Task Graph row {row_number} relation {relation!r} "
+                "must use Direction=undirected"
+            )
+
+        if source in {"-", "_(none)_", "none"}:
+            errors.append(
+                f"Related Task Graph row {row_number} must cite a source for the edge"
+            )
+        if impact in {"-", "_(none)_", "none"}:
+            errors.append(
+                f"Related Task Graph row {row_number} must state the edge impact"
+            )
+
+
 def check_reporter_confirmations(
     rc_status: str | None, reporter_rows: list[str], errors: list[str]
 ) -> None:
@@ -324,6 +450,8 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     if scope == "codebase":
         check_codebase_scope(text, errors)
 
+    check_related_task_graph(text, errors)
+
     # 2. brief-id matches filename stem
     stem = path.stem
     if fm.get("brief-id") and fm["brief-id"] != stem:

package/src/cli-registry.mjs

@@ -159,6 +159,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Manage the okstra container runtime (up/status/logs/stop-watcher/down)"],
   },
+  {
+    name: "manager",
+    module: "./commands/manager.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Manage cross-project okstra tasks"],
+  },
   {
     name: "worktree-lookup",
     module: "./commands/execute/worktree-lookup.mjs",