okstra 0.102.3 → 0.103.0

package/runtime/python/okstra_ctl/render.py

@@ -31,6 +31,7 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
 from . import fix_cycles
 from .paths import okstra_home
 from .lead_runtime import lead_runtime_info
+from .path_hints import compact_active_run_context, hydrate_run_context
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -56,8 +57,8 @@ def _load_ctx(ctx_arg: str) -> dict:
     """
     s = ctx_arg.lstrip()
     if s.startswith("{"):
-        return json.loads(ctx_arg)
-    return json.loads(Path(ctx_arg).read_text(encoding="utf-8"))
+        return hydrate_run_context(json.loads(ctx_arg))
+    return hydrate_run_context(json.loads(Path(ctx_arg).read_text(encoding="utf-8")))
 
 
 def _write_text(path: Path, text: str) -> None:
@@ -434,7 +435,7 @@ def render_active_run_context(active_context_path: str, ctx: dict) -> None:
         "sourceArtifacts": _active_source_artifacts(ctx),
         "lazyReadPlan": _active_lazy_read_plan(),
     }
-    _write_json(Path(active_context_path), payload)
+    _write_json(Path(active_context_path), compact_active_run_context(ctx, payload))
 
 
 def render_team_state(team_state_path: str, ctx: dict) -> None:

package/runtime/python/okstra_ctl/run_context.py

@@ -25,6 +25,7 @@ from typing import Iterator, Optional
 
 from okstra_project.dirs import okstra_home
 
+from .path_hints import compact_run_context, hydrate_run_context
 from .paths import compute_run_paths, task_runs_dir
 
 
@@ -188,7 +189,7 @@ def compute_and_write_run_context(
             str(ctx_path.relative_to(project_root.resolve()))
             if ctx_path.resolve().is_relative_to(project_root.resolve())
             else str(ctx_path))
-        _atomic_write_json(ctx_path, ctx)
+        _atomic_write_json(ctx_path, compact_run_context(ctx))
     return ctx
 
 
@@ -225,7 +226,8 @@ def read_run_context(run_manifests_dir: Path, task_type_segment: str,
     path = Path(run_manifests_dir) / _run_context_filename(task_type_segment, seq)
     if not path.is_file():
         return None
-    return json.loads(path.read_text(encoding="utf-8"))
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return hydrate_run_context(payload)
 
 
 def read_run_inputs(run_manifests_dir: Path, task_type_segment: str,

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.
 
@@ -1053,6 +1083,18 @@ def _opt(value: str, label: str = "", description: str = "") -> Option:
 
 # --- builders ---
 
+def _contract_outcome_suffix(entry: dict) -> str:
+    outcome = entry.get("phaseOutcome")
+    implementation = outcome.get("implementation") if isinstance(outcome, dict) else {}
+    if not isinstance(implementation, dict):
+        return ""
+    if implementation.get("state") != "completed":
+        return ""
+    if entry.get("currentStatus") == "contract-violated":
+        return " · implementation complete; contract warnings"
+    return ""
+
+
 def _build_task_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "task_pick")
     project_root = Path(state.project_root)
@@ -1070,7 +1112,7 @@ def _build_task_pick(state: WizardState) -> Prompt:
         phase = entry.get("currentPhase") or ttype
         nxt = entry.get("nextRecommendedPhase") or ""
         suffix = latest_suffix if key == latest_key else ""
-        label = f"{key}  ·  {phase}  ·  next: {nxt}{suffix}"
+        label = f"{key}  ·  {phase}  ·  next: {nxt}{_contract_outcome_suffix(entry)}{suffix}"
         options.append(_opt(value=key, label=label))
     for value, label in _static_options(t):
         options.append(_opt(value=value, label=label))
@@ -1116,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(
@@ -1156,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.
 
@@ -1169,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():
@@ -1180,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/python/okstra_project/state.py

@@ -1,10 +1,13 @@
-"""Read-only state accessors over okstra's on-disk authority files.
+"""Read-side state accessors over okstra's on-disk authority files.
 
 Skills, okstra.sh, and okstra-ctl all read the same files through this module
 so identity / discovery values are derived from disk on every call instead of
 being passed via process environment. This keeps concurrent claude-code skill
 invocations isolated — each call reads the authoritative state at the moment
 it runs and never sees stale snapshots inherited from a parent process.
+Some accessors also run best-effort reconciliation before returning derived
+phase pointers, so stale catalog entries can be healed from authoritative
+task artifacts.
 
 권위 파일 매핑 (okstra root = <PROJECT_ROOT>/<OKSTRA_DIR_NAME>):
   - <okstra root>/project.json
@@ -78,6 +81,38 @@ def read_task_manifest(task_root: Path) -> Optional[dict]:
     return _load_json(Path(task_root) / "task-manifest.json")
 
 
+def _reconcile_task_root_best_effort(project_root: Path, task_root: Path) -> None:
+    try:
+        from okstra_ctl.implementation_outcome import reconcile_implementation_outcome
+
+        reconcile_implementation_outcome(project_root, task_root)
+    except Exception:
+        return
+
+
+def _entry_with_manifest_state(entry: dict, task_root: Path) -> dict:
+    out = {**entry}
+    manifest = read_task_manifest(task_root) or {}
+    workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
+    for source, target in (
+        ("currentPhase", "currentPhase"),
+        ("currentPhaseState", "currentPhaseState"),
+        ("lastCompletedPhase", "lastCompletedPhase"),
+        ("nextRecommendedPhase", "nextRecommendedPhase"),
+    ):
+        value = workflow.get(source)
+        if isinstance(value, str):
+            out[target] = value
+    for field in ("currentStatus", "latestRunStatus", "latestReportPath"):
+        value = manifest.get(field)
+        if isinstance(value, str):
+            out[field] = value
+    phase_outcome = manifest.get("phaseOutcome")
+    if isinstance(phase_outcome, dict):
+        out["phaseOutcome"] = phase_outcome
+    return out
+
+
 def parse_task_key(task_key: str) -> tuple[str, str, str]:
     """`project-id:task-group:task-id` 를 3-tuple 로 분해.
 
@@ -111,10 +146,12 @@ def find_task_root(project_root: Path, task_key: str) -> Optional[Path]:
         if isinstance(rel, str) and rel:
             abs_path = project_root / rel if not Path(rel).is_absolute() else Path(rel)
             if abs_path.is_dir():
+                _reconcile_task_root_best_effort(project_root, abs_path)
                 return abs_path
 
     slug_path = project_root / TASKS_RELATIVE / slugify(task_group) / slugify(task_id)
     if slug_path.is_dir():
+        _reconcile_task_root_best_effort(project_root, slug_path)
         return slug_path
     return None
 
@@ -180,7 +217,8 @@ def list_project_tasks(
         root = find_task_root(project_root, entry_key)
         if root is None:
             continue
-        out.append({**entry, "_resolvedTaskRoot": str(root)})
+        reconciled_entry = _entry_with_manifest_state(entry, root)
+        out.append({**reconciled_entry, "_resolvedTaskRoot": str(root)})
     if limit is not None and limit >= 0:
         out = out[:limit]
     return out

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: