okstra 0.201.3 → 0.202.0

package/runtime/python/okstra_ctl/manager_split.py

@@ -0,0 +1,474 @@
+"""트래커 분할 계획을 받아 프로젝트별 범위 지정 브리프를 쓰고 manager 하위 태스크로 등록한다.
+
+Linear 조회와 본문 저작은 에이전트(okstra-manager 스킬)가 한다. 이 모듈은 계획 검증,
+브리프 렌더링, 브리프 검증기 통과 확인, 파일 쓰기, 하위 태스크 등록을 맡는다. 검증이
+하나라도 실패하면 브리프도 manager 상태도 쓰지 않는다.
+
+브리프 계약(EB/PB/EO 형식, Open Questions 접두어, 관계 표 값)은 여기서 다시 구현하지
+않는다. 렌더링 결과를 `validators/validate-brief.py` 로 검사해서 집행한다.
+"""
+from __future__ import annotations
+
+import importlib.util
+import re
+import tempfile
+from pathlib import Path
+from types import ModuleType
+
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+from okstra_ctl.jsonl import append_jsonl
+
+from .ids import slugify_task_segment
+from .manager_paths import children_json_path, events_jsonl_path, split_plan_path, task_manifest_path
+from .manager_store import (
+    ManagerError,
+    _now_iso,
+    _read_json,
+    _write_json,
+    create_task,
+    list_projects,
+    load_manager,
+)
+from .paths import BRIEF_VALIDATOR_RELATIVE, find_asset_root
+
+PLAN_SCHEMA_VERSION = 1
+SOURCE_KINDS = ("project", "issue")
+RECOMMENDED_PHASES = ("requirements-discovery", "error-analysis", "improvement-discovery")
+DEFAULT_PHASE = "requirements-discovery"
+GENERATOR = "okstra-manager"
+SOURCE_TYPE = "linear"
+# 브리프 계약의 필수 서술 필드. 비어 있으면 검증기가 거절하므로 계획 단계에서 먼저 막는다.
+_REQUIRED_TEXT_FIELDS = ("context", "problem", "desiredOutcome")
+_LIST_FIELDS = (
+    "expectedBehavior",
+    "preservedBehavior",
+    "expectedOutcome",
+    "externalGates",
+    "constraints",
+    "openQuestions",
+    "outOfScope",
+)
+# 파일명·하위 task id 로 쓰이므로 경로 구분자나 공백을 받지 않는다.
+_TICKET_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+# okstra-brief-gen Step 2b: 영숫자·공백·한글만 남긴다.
+_FILE_TITLE_DROP = re.compile(r"[^0-9A-Za-z가-힣ㄱ-ㅎㅏ-ㅣ ]+")
+_FILE_TITLE_MAX = 60
+_NONE = "_(none)_"
+
+
+def brief_file_title(title: str) -> str:
+    """okstra-brief-gen Step 2b 의 `<file-title>` 규칙."""
+    slug = re.sub(r" +", "-", _FILE_TITLE_DROP.sub("", title).strip()).lower()
+    if len(slug) > _FILE_TITLE_MAX:
+        cut = slug[:_FILE_TITLE_MAX]
+        boundary = cut.rfind("-")
+        slug = cut[:boundary] if boundary > 0 else cut
+    return slug.strip("-")
+
+
+def _load_brief_validator() -> ModuleType:
+    root = find_asset_root(BRIEF_VALIDATOR_RELATIVE)
+    if root is None:
+        raise ManagerError("brief validator not found: " + "/".join(BRIEF_VALIDATOR_RELATIVE))
+    spec = importlib.util.spec_from_file_location("okstra_validate_brief", root.joinpath(*BRIEF_VALIDATOR_RELATIVE))
+    if spec is None or spec.loader is None:
+        raise ManagerError("brief validator could not be loaded")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _load_plan(path: Path) -> dict:
+    try:
+        return load_owned_object(Path(path), artifact="manager split plan")
+    except JsonBoundaryError as exc:
+        raise ManagerError(str(exc)) from exc
+
+
+def _text(value: object) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _string_list(value: object, where: str, errors: list[str]) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        errors.append(f"{where} must be a list of strings")
+        return []
+    items = []
+    for index, item in enumerate(value, 1):
+        text = _text(item)
+        if not text:
+            errors.append(f"{where}[{index}] must be a non-empty string")
+            continue
+        items.append(text)
+    return items
+
+
+def _require_text(record: dict, key: str, where: str, errors: list[str]) -> str:
+    value = _text(record.get(key))
+    if not value:
+        errors.append(f"{where}.{key} is required")
+    return value
+
+
+def _no_pipe(value: str, where: str, errors: list[str]) -> None:
+    # 관계 표의 셀 구분자라 값에 들어오면 표가 깨진다.
+    if "|" in value:
+        errors.append(f"{where} must not contain '|'")
+
+
+def _normalize_source(raw: object, errors: list[str]) -> dict:
+    if not isinstance(raw, dict):
+        errors.append("source must be an object")
+        return {}
+    source = {key: _require_text(raw, key, "source", errors) for key in ("kind", "ref", "title", "body")}
+    if source["kind"] and source["kind"] not in SOURCE_KINDS:
+        errors.append(f"source.kind must be one of {list(SOURCE_KINDS)}, got {source['kind']!r}")
+    source["fetchedVia"] = _text(raw.get("fetchedVia")) or "user-paste"
+    source["fetchedAt"] = _text(raw.get("fetchedAt"))
+    _no_pipe(source["ref"], "source.ref", errors)
+    _no_pipe(source["title"], "source.title", errors)
+    return source
+
+
+def _normalize_assignment(raw: object, where: str, members: set[str], errors: list[str]) -> dict:
+    if not isinstance(raw, dict):
+        errors.append(f"{where} must be an object")
+        return {}
+    assignment = {"projectId": _require_text(raw, "projectId", where, errors)}
+    if assignment["projectId"] and assignment["projectId"] not in members:
+        errors.append(f"{where}.projectId {assignment['projectId']!r} is not a project of this manager")
+    assignment["scope"] = _string_list(raw.get("scope"), f"{where}.scope", errors)
+    if not assignment["scope"]:
+        errors.append(f"{where}.scope must list at least one item of work for this project")
+    phase = _text(raw.get("recommendedPhase")) or DEFAULT_PHASE
+    if phase not in RECOMMENDED_PHASES:
+        errors.append(f"{where}.recommendedPhase must be one of {list(RECOMMENDED_PHASES)}, got {phase!r}")
+    assignment["recommendedPhase"] = phase
+    for key in _REQUIRED_TEXT_FIELDS:
+        assignment[key] = _require_text(raw, key, where, errors)
+    for key in _LIST_FIELDS:
+        assignment[key] = _string_list(raw.get(key), f"{where}.{key}", errors)
+    return assignment
+
+
+def _normalize_relations(raw: object, where: str, relations: set[str], errors: list[str]) -> list[dict]:
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        errors.append(f"{where}.relations must be a list")
+        return []
+    rows = []
+    for index, item in enumerate(raw, 1):
+        at = f"{where}.relations[{index}]"
+        if not isinstance(item, dict):
+            errors.append(f"{at} must be an object")
+            continue
+        row = {key: _require_text(item, key, at, errors) for key in ("relation", "to", "source", "impact")}
+        if row["relation"] and row["relation"] not in relations:
+            errors.append(f"{at}.relation must be one of {sorted(relations)}, got {row['relation']!r}")
+        for key, value in row.items():
+            _no_pipe(value, f"{at}.{key}", errors)
+        rows.append(row)
+    return rows
+
+
+def _normalize_issue(raw: object, where: str, members: set[str], relations: set[str], errors: list[str]) -> dict:
+    if not isinstance(raw, dict):
+        errors.append(f"{where} must be an object")
+        return {}
+    issue = {key: _require_text(raw, key, where, errors) for key in ("ticketId", "title", "body")}
+    if issue["ticketId"] and not _TICKET_ID.match(issue["ticketId"]):
+        errors.append(f"{where}.ticketId {issue['ticketId']!r} must match {_TICKET_ID.pattern}")
+    issue["url"] = _text(raw.get("url"))
+    _no_pipe(issue["url"], f"{where}.url", errors)
+    issue["fetchedVia"] = _text(raw.get("fetchedVia")) or "user-paste"
+    issue["fetchedAt"] = _text(raw.get("fetchedAt"))
+    issue["relations"] = _normalize_relations(raw.get("relations"), where, relations, errors)
+    raw_assignments = raw.get("assignments")
+    if not isinstance(raw_assignments, list) or not raw_assignments:
+        errors.append(f"{where}.assignments must list at least one project")
+        raw_assignments = []
+    issue["assignments"] = [
+        _normalize_assignment(item, f"{where}.assignments[{index}]", members, errors)
+        for index, item in enumerate(raw_assignments, 1)
+    ]
+    seen = [a.get("projectId") for a in issue["assignments"] if a.get("projectId")]
+    for project_id in sorted({pid for pid in seen if seen.count(pid) > 1}):
+        errors.append(f"{where}.assignments names project {project_id!r} more than once")
+    return issue
+
+
+def normalize_plan(plan: dict, members: set[str], relations: set[str]) -> tuple[dict, list[dict], list[str]]:
+    """계획을 (source, issues, errors) 로 정리한다. errors 가 비어야 쓸 수 있다."""
+    errors: list[str] = []
+    if plan.get("schemaVersion") != PLAN_SCHEMA_VERSION:
+        errors.append(f"schemaVersion must be {PLAN_SCHEMA_VERSION}, got {plan.get('schemaVersion')!r}")
+    source = _normalize_source(plan.get("source"), errors)
+    raw_issues = plan.get("issues")
+    if not isinstance(raw_issues, list) or not raw_issues:
+        errors.append("issues must list at least one issue")
+        raw_issues = []
+    issues = [
+        _normalize_issue(item, f"issues[{index}]", members, relations, errors)
+        for index, item in enumerate(raw_issues, 1)
+    ]
+    ticket_ids = [issue.get("ticketId") for issue in issues if issue.get("ticketId")]
+    for ticket_id in sorted({tid for tid in ticket_ids if ticket_ids.count(tid) > 1}):
+        errors.append(f"issues name ticketId {ticket_id!r} more than once")
+    return source, issues, errors
+
+
+def _bullets(items: list[str]) -> list[str]:
+    return [f"- {item}" for item in items] if items else [_NONE]
+
+
+def _fence(body: str) -> str:
+    longest = max((len(run) for run in re.findall(r"`+", body)), default=0)
+    return "`" * max(3, longest + 1)
+
+
+def _source_block(index: int, ref: str, fetched_via: str, fetched_at: str, body: str) -> list[str]:
+    fence = _fence(body)
+    return [
+        f"### Source {index} — {SOURCE_TYPE}",
+        "",
+        f"- ref: {ref}",
+        f"- fetched-via: {fetched_via}",
+        f"- fetched-at: {fetched_at or '-'}",
+        "- format: as-is",
+        "",
+        fence,
+        body,
+        fence,
+        "",
+    ]
+
+
+def _source_is_issue(source: dict, issue: dict) -> bool:
+    return source["ref"] in {issue["ticketId"], issue["url"]}
+
+
+def _graph_rows(source: dict, issues: list[dict], keys: dict, directed: set[str]) -> list[tuple[str, ...]]:
+    """분할 전체 위상. 모든 브리프에 같은 표가 들어간다(okstra-brief-gen 분할 규칙)."""
+    membership = "Linear project membership" if source["kind"] == "project" else "Linear sub-issue"
+    rows: list[tuple[str, ...]] = []
+    for issue in issues:
+        ticket = issue["ticketId"]
+        if not _source_is_issue(source, issue):
+            rows.append((source["ref"], "parent-of", ticket, "directed", membership,
+                         f"{ticket} is part of {source['title']}"))
+        for assignment in issue["assignments"]:
+            rows.append((keys[(ticket, assignment["projectId"])], "split-from", ticket, "directed",
+                         "okstra manager task split",
+                         f"covers only the {assignment['projectId']} part of {ticket}"))
+        for relation in issue["relations"]:
+            direction = "directed" if relation["relation"] in directed else "undirected"
+            rows.append((ticket, relation["relation"], relation["to"], direction,
+                         relation["source"], relation["impact"]))
+    return rows
+
+
+def _render_brief(
+    *,
+    source: dict,
+    issue: dict,
+    assignment: dict,
+    task_group: str,
+    manager_task: str,
+    stem: str,
+    created: str,
+    key: str,
+    project_root: str,
+    siblings: list[tuple[str, dict, Path]],
+    graph: list[tuple[str, ...]],
+) -> str:
+    ticket = issue["ticketId"]
+    project_id = assignment["projectId"]
+    out_of_scope = list(assignment["outOfScope"])
+    out_of_scope.extend(f"`{sibling_key}` (project `{other['projectId']}`): {'; '.join(other['scope'])}"
+                        for sibling_key, other, _ in siblings)
+    lines = [
+        "---",
+        "type: brief",
+        f"brief-id: {stem}",
+        "parent-id: self",
+        f"ticket-id: {ticket}",
+        f"source-type: {SOURCE_TYPE}",
+        f"task-group: {task_group}",
+        "depth: 0",
+        f"created: {created}",
+        f"generator: {GENERATOR}",
+        "reporter-confirmations: skipped",
+        f"project-id: {project_id}",
+        f"manager-task: {manager_task}",
+        "---",
+        "",
+        f"# Task Brief: {task_group}/{stem}",
+        "",
+        f"> - Generated: {GENERATOR} · {created}",
+        f"> - Source type: {SOURCE_TYPE}",
+        f"> - Tracker key (if any): {ticket}",
+        f"> - Project: `{project_id}` (child task `{key}`)",
+        f"> - Recommended next phase: {assignment['recommendedPhase']}",
+        "> - Handoff contract: see `prompts/profiles/_common-contract.md` § \"Brief handoff contract\"",
+        "",
+        "## Source Material",
+        "",
+        *_source_block(1, issue["url"] or ticket, issue["fetchedVia"], issue["fetchedAt"], issue["body"]),
+    ]
+    if not _source_is_issue(source, issue):
+        lines.extend(_source_block(2, source["ref"], source["fetchedVia"], source["fetchedAt"], source["body"]))
+    lines.extend(
+        [
+            "## Context",
+            "",
+            assignment["context"],
+            "",
+            "## Project Scope",
+            "",
+            f"This brief covers only the part of {ticket} that lands in project `{project_id}` "
+            f"(`{project_root}`). Work outside the in-scope list belongs to the tasks named under out of scope.",
+            "",
+            "### In scope",
+            "",
+            *_bullets(assignment["scope"]),
+            "",
+            "### Out of scope",
+            "",
+            *_bullets(out_of_scope),
+            "",
+            "## Problem / Symptom",
+            "",
+            assignment["problem"],
+            "",
+            "## Desired Outcome",
+            "",
+            assignment["desiredOutcome"],
+            "",
+        ]
+    )
+    for heading, field in (("Expected Behavior", "expectedBehavior"), ("Preserved Behavior", "preservedBehavior"),
+                           ("Expected Outcome", "expectedOutcome"), ("External Gates", "externalGates"),
+                           ("Constraints", "constraints")):
+        lines.extend([f"## {heading}", "", *_bullets(assignment[field]), ""])
+    artifacts = [ref for ref in (issue["url"], source["ref"]) if ref]
+    artifacts.extend(f"`{sibling_key}` brief: {path}" for sibling_key, _, path in siblings)
+    lines.extend(["## Related Artifacts", "", *_bullets(artifacts), "", "## Related Task Graph", ""])
+    lines.append("| From | Relation | To | Direction | Source | Impact |")
+    lines.append("|---|---|---|---|---|---|")
+    lines.extend("| " + " | ".join(row) + " |" for row in graph)
+    lines.extend(
+        [
+            "",
+            "## Open Questions",
+            "",
+            *_bullets(assignment["openQuestions"]),
+            "",
+            "## Reporter Confirmations",
+            "",
+            "_(none — pending or skipped)_",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _validate_rendered(items: list[dict], validator: ModuleType, group_segment: str) -> list[str]:
+    errors: list[str] = []
+    with tempfile.TemporaryDirectory(prefix="okstra-split-") as scratch:
+        for index, item in enumerate(items):
+            briefs_root = Path(scratch) / str(index) / "briefs"
+            path = briefs_root / group_segment / item["briefPath"].name
+            path.parent.mkdir(parents=True)
+            path.write_text(item["text"], encoding="utf-8")
+            errors.extend(f"{item['taskKey']}: {error}" for error in validator.validate_brief(path, briefs_root))
+    return errors
+
+
+def split_task(
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    plan_path: Path,
+    *,
+    overwrite: bool = False,
+    now: str | None = None,
+) -> dict:
+    """분할 계획으로 브리프를 쓰고 하위 태스크를 등록한다. 결과 브리프 목록을 돌려준다."""
+    load_manager(home, manager_id)
+    projects = {str(project.get("projectId")): project for project in list_projects(home, manager_id)}
+    group_segment = slugify_task_segment(task_group)
+    if not group_segment:
+        raise ManagerError(f"task-group {task_group!r} has no usable slug")
+    plan = _load_plan(plan_path)
+    validator = _load_brief_validator()
+    source, issues, errors = normalize_plan(plan, set(projects), set(validator.TASK_RELATIONS))
+    if errors:
+        raise ManagerError("split plan rejected:\n- " + "\n- ".join(errors))
+    when = now or _now_iso()
+    manager_task = f"{manager_id}/{task_group}/{task_id}"
+    keys: dict[tuple[str, str], str] = {}
+    items: list[dict] = []
+    for issue in issues:
+        ticket = issue["ticketId"]
+        stem = "-".join(part for part in (ticket, brief_file_title(issue["title"])) if part)
+        for assignment in issue["assignments"]:
+            project_id = assignment["projectId"]
+            child_task_id = slugify_task_segment(ticket)
+            key = f"{project_id}:{task_group}:{child_task_id}"
+            keys[(ticket, project_id)] = key
+            root = Path(str(projects[project_id].get("projectRoot") or ""))
+            items.append({"issue": issue, "assignment": assignment, "stem": stem, "taskKey": key,
+                          "projectId": project_id, "childTaskId": child_task_id, "projectRoot": str(root),
+                          "briefPath": root / ".okstra" / "briefs" / group_segment / f"{stem}.md"})
+    graph = _graph_rows(source, issues, keys, set(validator.DIRECTED_TASK_RELATIONS))
+    for item in items:
+        siblings = [(other["taskKey"], other["assignment"], other["briefPath"]) for other in items
+                    if other["issue"] is item["issue"] and other is not item]
+        item["text"] = _render_brief(source=source, issue=item["issue"], assignment=item["assignment"],
+                                     task_group=task_group, manager_task=manager_task, stem=item["stem"],
+                                     created=when[:10], key=item["taskKey"], project_root=item["projectRoot"],
+                                     siblings=siblings, graph=graph)
+    errors = _validate_rendered(items, validator, group_segment)
+    if errors:
+        raise ManagerError("rendered briefs failed validate-brief:\n- " + "\n- ".join(errors))
+    for item in items:
+        path = item["briefPath"]
+        if not path.is_file():
+            item["briefStatus"] = "created"
+        elif path.read_text(encoding="utf-8") == item["text"]:
+            item["briefStatus"] = "unchanged"
+        else:
+            item["briefStatus"] = "overwritten"
+    conflicts = [str(item["briefPath"]) for item in items if item["briefStatus"] == "overwritten"]
+    if conflicts and not overwrite:
+        raise ManagerError(
+            "briefs already exist with different content; pass --overwrite to replace them:\n- "
+            + "\n- ".join(conflicts)
+        )
+    for item in items:
+        if item["briefStatus"] != "unchanged":
+            item["briefPath"].parent.mkdir(parents=True, exist_ok=True)
+            item["briefPath"].write_text(item["text"], encoding="utf-8")
+    existing = task_manifest_path(home, manager_id, task_group, task_id).is_file()
+    create_task(home, manager_id, task_group, task_id,
+                [{"projectId": item["projectId"], "taskId": item["childTaskId"]} for item in items],
+                objective="" if existing else source["title"], now=when)
+    children_path = children_json_path(home, manager_id, task_group, task_id)
+    children = _read_json(children_path)
+    by_key = {child.get("taskKey"): child for child in children.get("children", []) if isinstance(child, dict)}
+    for item in items:
+        by_key[item["taskKey"]].update({"ticketId": item["issue"]["ticketId"], "briefPath": str(item["briefPath"]),
+                                        "scope": list(item["assignment"]["scope"]),
+                                        "recommendedPhase": item["assignment"]["recommendedPhase"]})
+    _write_json(children_path, children)
+    _write_json(split_plan_path(home, manager_id, task_group, task_id), plan)
+    briefs = [{"taskKey": item["taskKey"], "projectId": item["projectId"], "ticketId": item["issue"]["ticketId"],
+               "briefPath": str(item["briefPath"]), "briefStatus": item["briefStatus"]} for item in items]
+    append_jsonl(events_jsonl_path(home, manager_id, task_group, task_id),
+                 {"event": "task-split", "createdAt": when, "source": source["ref"],
+                  "taskKeys": [brief["taskKey"] for brief in briefs]})
+    return {"managerId": manager_id, "taskGroup": task_group, "taskId": task_id, "briefs": briefs}

package/runtime/python/okstra_ctl/manager_store.py

@@ -96,6 +96,63 @@ def load_manager(home: Path, manager_id: str) -> dict:
     return _read_json(path)
 
 
+def _task_manifest_paths(home: Path, manager_id: str) -> list[Path]:
+    return sorted(manager_root(home, manager_id).glob("task-groups/*/*/manifest.json"))
+
+
+def list_managers(home: Path) -> list[dict]:
+    """이 홈의 manager 를 id 순으로, 소속 프로젝트 수와 manager task 수와 함께 돌려준다."""
+    base = Path(home) / "managers"
+    if not base.is_dir():
+        return []
+    items: list[dict] = []
+    for path in sorted(base.glob("*/manager.json")):
+        manager = _read_json(path)
+        manager_id = str(manager.get("managerId") or path.parent.name)
+        items.append(
+            {
+                "managerId": manager_id,
+                "createdAt": str(manager.get("createdAt") or ""),
+                "projectCount": len(_load_projects(home, manager_id).get("projects", [])),
+                "taskCount": len(_task_manifest_paths(home, manager_id)),
+            }
+        )
+    return items
+
+
+def list_projects(home: Path, manager_id: str) -> list[dict]:
+    """manager 에 등록된 프로젝트를 등록 파일(projects.json) 순서 그대로 돌려준다."""
+    load_manager(home, manager_id)
+    return [
+        project
+        for project in _load_projects(home, manager_id).get("projects", [])
+        if isinstance(project, dict)
+    ]
+
+
+def list_tasks(home: Path, manager_id: str) -> list[dict]:
+    """manager task 를 task-group, task-id 순으로 하위 task 수와 함께 돌려준다.
+
+    디렉터리 이름은 slug 라 원래 입력값과 다를 수 있으므로 식별자는 manifest 에서 읽는다.
+    """
+    load_manager(home, manager_id)
+    items: list[dict] = []
+    for path in _task_manifest_paths(home, manager_id):
+        manifest = _read_json(path)
+        children = _read_json_default(path.parent / "children.json", {"children": []})
+        items.append(
+            {
+                "taskGroup": str(manifest.get("taskGroup") or ""),
+                "taskId": str(manifest.get("taskId") or ""),
+                "objective": str(manifest.get("objective") or ""),
+                "progressMode": str(manifest.get("progressMode") or ""),
+                "createdAt": str(manifest.get("createdAt") or ""),
+                "childCount": len(children.get("children", [])),
+            }
+        )
+    return sorted(items, key=lambda item: (item["taskGroup"], item["taskId"]))
+
+
 def discover_projects(home: Path) -> list[dict]:
     base = Path(home) / "projects"
     if not base.is_dir():
@@ -174,6 +231,17 @@ def create_task_group(home: Path, manager_id: str, task_group: str, *, now: str
     return {"managerId": manager_id, "taskGroup": task_group, "createdAt": now or _now_iso()}
 
 
+def _merge_manifest(existing: dict, requested: dict) -> None:
+    """이미 있는 manager task 의 manifest 값을 `new task` 가 바꾸지 못하게 한다."""
+    for key, value in requested.items():
+        if value is None or value == "" or existing.get(key) == value:
+            continue
+        raise ManagerError(
+            f"manager task already exists with {key}={existing.get(key)!r}; "
+            f"refusing to change it to {value!r}"
+        )
+
+
 def create_task(
     home: Path,
     manager_id: str,
@@ -183,32 +251,56 @@ def create_task(
     *,
     objective: str = "",
     common_brief_path: str = "",
-    progress_mode: str = "manual",
+    progress_mode: str | None = None,
     now: str | None = None,
 ) -> dict:
+    """manager task 를 만들거나, 이미 있으면 새 하위 task 만 덧붙인다.
+
+    다시 실행해도 기존 하위 task 의 assignment·launch 상태는 지우지 않는다.
+    """
+    load_manager(home, manager_id)
     projects = _load_projects(home, manager_id)
     when = now or _now_iso()
-    manifest = {
-        "managerId": manager_id,
-        "taskGroup": task_group,
-        "taskId": task_id,
-        "progressMode": progress_mode,
-        "commonBriefPath": common_brief_path,
-        "objective": objective,
-        "createdAt": when,
-    }
-    children = []
+    manifest_path = task_manifest_path(home, manager_id, task_group, task_id)
+    existing = manifest_path.is_file()
+    if existing:
+        manifest = _read_json(manifest_path)
+        _merge_manifest(
+            manifest,
+            {
+                "objective": objective,
+                "commonBriefPath": common_brief_path,
+                "progressMode": progress_mode,
+            },
+        )
+    else:
+        manifest = {
+            "managerId": manager_id,
+            "taskGroup": task_group,
+            "taskId": task_id,
+            "progressMode": progress_mode or "manual",
+            "commonBriefPath": common_brief_path,
+            "objective": objective,
+            "createdAt": when,
+        }
+    children = _load_children(home, manager_id, task_group, task_id)
+    known_keys = {child.get("taskKey") for child in children["children"] if isinstance(child, dict)}
+    added = []
     for spec in child_specs:
         project_id = str(spec.get("projectId") or "")
         child_task_id = str(spec.get("taskId") or task_id)
         if _project_entry(projects, project_id) is None:
             raise ManagerError(f"unknown project membership: {project_id}")
-        children.append(
+        task_key = _child_task_key(project_id, task_group, child_task_id)
+        if task_key in known_keys:
+            continue
+        known_keys.add(task_key)
+        added.append(
             {
                 "projectId": project_id,
                 "taskGroup": task_group,
                 "taskId": child_task_id,
-                "taskKey": f"{project_id}:{task_group}:{child_task_id}",
+                "taskKey": task_key,
                 "role": "",
                 "tags": [],
                 "assignment": "",
@@ -219,14 +311,19 @@ def create_task(
                 },
             }
         )
-    payload = {"manifest": manifest, "children": {"children": children}}
-    _write_json(task_manifest_path(home, manager_id, task_group, task_id), manifest)
-    _write_json(children_json_path(home, manager_id, task_group, task_id), payload["children"])
+    children["children"].extend(added)
+    if not existing:
+        _write_json(manifest_path, manifest)
+    _write_json(children_json_path(home, manager_id, task_group, task_id), children)
     append_jsonl(
         events_jsonl_path(home, manager_id, task_group, task_id),
-        {"event": "task-created", "createdAt": when},
+        {
+            "event": "task-children-added" if existing else "task-created",
+            "createdAt": when,
+            "taskKeys": [child["taskKey"] for child in added],
+        },
     )
-    return payload
+    return {"manifest": manifest, "children": children}
 
 
 def _load_children(home: Path, manager_id: str, task_group: str, task_id: str) -> dict:
@@ -286,6 +383,7 @@ def assign_child(
     assignment: str,
     child_task_id: str | None = None,
 ) -> dict:
+    _read_json(task_manifest_path(home, manager_id, task_group, task_id))
     payload = _load_children(home, manager_id, task_group, task_id)
     child = _select_child_for_assignment(payload["children"], project_id, task_group, child_task_id)
     child["role"] = role
@@ -311,6 +409,11 @@ def append_directive(
         raise ManagerError("scope must be shared or project")
     if scope == "project" and not project_id:
         raise ManagerError("project directive requires project-id")
+    _read_json(task_manifest_path(home, manager_id, task_group, task_id))
+    if scope == "project":
+        children = _load_children(home, manager_id, task_group, task_id)["children"]
+        if not any(isinstance(child, dict) and child.get("projectId") == project_id for child in children):
+            raise ManagerError(f"project directive target has no child in this task: {project_id}")
     row = {
         "scope": scope,
         "projectId": project_id if scope == "project" else "",