@blxzer/cursor-trellis 0.3.4 → 0.3.5

package/dist/templates/trellis/scripts/common/task_map.py

@@ -1,614 +1,638 @@
-#!/usr/bin/env python3
-"""
-Parent/Child task-map helpers.
-
-task-map.md is the Parent Supervisor's orchestration authority. This module
-parses and writes only the small YAML frontmatter subset generated here.
-"""
-
-from __future__ import annotations
-
-from datetime import datetime, timezone
-from pathlib import Path
-
-
-TASK_MAP = "task-map.md"
-
-CHILD_STATES = {
-    "open",
-    "working",
-    "blocked",
-    "review",
-    "changes",
-    "accepted",
-    "integrating",
-    "integrated",
-    "cancelled",
-}
-
-PARENT_TERMINAL_STATES = {"integrated", "cancelled"}
-PARENT_CONTROLLED_STATES = {
-    "changes",
-    "accepted",
-    "integrating",
-    "integrated",
-    "cancelled",
-}
-CHILD_REPORT_STATES = CHILD_STATES - PARENT_CONTROLLED_STATES
-REF_REQUIRED_STATES = {"accepted", "integrating", "integrated"}
-HANDOFF_REQUIRED_STATES = {"accepted", "integrating", "integrated"}
-
-
-def utc_now() -> str:
-    """Return a compact UTC timestamp for task-map event log entries."""
-    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace(
-        "+00:00", "Z"
-    )
-
-
-def load_task_map(parent_dir: Path) -> tuple[dict | None, str]:
-    """Load task-map.md frontmatter and body."""
-    path = parent_dir / TASK_MAP
-    if not path.is_file():
-        return None, ""
-
-    try:
-        content = path.read_text(encoding="utf-8")
-    except OSError:
-        return None, ""
-
-    frontmatter, body = _split_frontmatter(content)
-    if frontmatter is None:
-        return None, content
-    return _parse_frontmatter(frontmatter), body
-
-
-def ensure_task_map(
-    parent_dir: Path,
-    parent_data: dict,
-    child_names: list[str],
-    event: str | None = None,
-) -> dict:
-    """Ensure task-map.md exists and contains entries for all child_names."""
-    data, body = load_task_map(parent_dir)
-    if data is None:
-        data = {
-            "parent_id": parent_data.get("id") or parent_dir.name,
-            "contract_epoch": 1,
-            "execution_topology": "serial",
-            "merge_limit": 1,
-            "children": [],
-            "integration_queue": [],
-        }
-        body = _default_body()
-
-    data.setdefault("parent_id", parent_data.get("id") or parent_dir.name)
-    data.setdefault("contract_epoch", 1)
-    data.setdefault("execution_topology", "serial")
-    data.setdefault("merge_limit", 1)
-    data.setdefault("children", [])
-    data.setdefault("integration_queue", [])
-
-    existing = {
-        child.get("id"): child
-        for child in data.get("children", [])
-        if isinstance(child, dict)
-    }
-    for child_name in child_names:
-        if child_name not in existing:
-            child = _default_child(child_name)
-            data["children"].append(child)
-            existing[child_name] = child
-
-    write_task_map(parent_dir, data, body, event)
-    return data
-
-
-def remove_child_from_task_map(
-    parent_dir: Path,
-    parent_data: dict,
-    child_name: str,
-) -> None:
-    """Remove a child entry from task-map.md when structural links are removed."""
-    data, body = load_task_map(parent_dir)
-    if data is None:
-        return
-
-    children = data.get("children")
-    if isinstance(children, list):
-        data["children"] = [
-            child
-            for child in children
-            if not isinstance(child, dict) or child.get("id") != child_name
-        ]
-    data.setdefault("parent_id", parent_data.get("id") or parent_dir.name)
-    write_task_map(parent_dir, data, body, f"Unlinked Child `{child_name}`.")
-
-
-def set_child_state(
-    parent_dir: Path,
-    parent_data: dict,
-    child_name: str,
-    state: str,
-    evidence: str,
-    reason: str | None = None,
-) -> tuple[bool, list[str]]:
-    """Set a child state inside Parent task-map.md."""
-    errors: list[str] = []
-    if state not in CHILD_STATES:
-        errors.append(f"unknown child state: {state}")
-    if not _short_text(evidence):
-        errors.append("evidence must be a short reference")
-    if reason and not _short_text(reason, 500):
-        errors.append("reason must be short and single-line")
-    if errors:
-        return False, errors
-
-    structural_children = parent_data.get("children", [])
-    if child_name not in structural_children:
-        errors.append(f"child is not linked to parent: {child_name}")
-        return False, errors
-
-    data = ensure_task_map(parent_dir, parent_data, list(structural_children))
-    child = get_child_entry(data, child_name)
-    if child is None:
-        errors.append(f"child missing from task-map.md: {child_name}")
-        return False, errors
-
-    child["state"] = state
-    child["evidence"] = evidence
-    if reason:
-        child["reason"] = reason
-
-    event = f"Set Child `{child_name}` state to `{state}`. Evidence: {evidence}."
-    if reason:
-        event = f"{event} Reason: {reason}."
-    _, body = load_task_map(parent_dir)
-    write_task_map(parent_dir, data, body, event)
-    return True, []
-
-
-def validate_parent_child_integration(
-    parent_dir: Path,
-    parent_data: dict,
-    child_dir: Path,
-    child_data: dict,
-    state: str,
-    evidence: str,
-    ref: str | None = None,
-    reason: str | None = None,
-    current_state_override: str | None = None,
-) -> list[str]:
-    """Validate a Parent-controlled Child integration state transition."""
-    errors: list[str] = []
-    child_name = child_dir.name
-    if state not in PARENT_CONTROLLED_STATES:
-        errors.append(f"state is not Parent-controlled: {state}")
-    if not _short_text(evidence):
-        errors.append("evidence must be a short reference")
-    if reason and not _short_text(reason, 500):
-        errors.append("reason must be short and single-line")
-    if state in {"changes", "cancelled"} and not reason:
-        errors.append(f"{state} requires --reason")
-    if state in REF_REQUIRED_STATES and not _short_text(ref):
-        errors.append(f"{state} requires --ref")
-
-    if child_data.get("parent") != parent_dir.name:
-        errors.append(f"child is not linked to parent: {child_name}")
-
-    structural_children = parent_data.get("children", [])
-    if child_name not in structural_children:
-        errors.append(f"child is not linked to parent: {child_name}")
-
-    data, _ = load_task_map(parent_dir)
-    if data is None:
-        errors.append(f"{TASK_MAP}")
-        return errors
-
-    child = get_child_entry(data, child_name)
-    if child is None:
-        errors.append(f"child missing from task-map.md: {child_name}")
-        return errors
-
-    current_state = (
-        current_state_override
-        if current_state_override is not None
-        else child.get("state")
-    )
-    if state in {"accepted", "changes"} and current_state != "review":
-        errors.append(f"{state} requires current Child state 'review', got {current_state!r}")
-    if state == "integrating" and current_state != "accepted":
-        errors.append(f"integrating requires current Child state 'accepted', got {current_state!r}")
-    if state == "integrated" and current_state != "integrating":
-        errors.append(f"integrated requires current Child state 'integrating', got {current_state!r}")
-
-    if state in HANDOFF_REQUIRED_STATES:
-        errors.extend(_required_child_evidence(child_dir, ["verify.md", "handoff.md"]))
-
-    if state == "integrating":
-        merge_limit = data.get("merge_limit", 1)
-        if not isinstance(merge_limit, int) or merge_limit < 1:
-            errors.append("merge_limit must be a positive integer")
-        else:
-            integrating = [
-                item.get("id")
-                for item in data.get("children", [])
-                if isinstance(item, dict)
-                and item.get("id") != child_name
-                and item.get("state") == "integrating"
-            ]
-            if len(integrating) >= merge_limit:
-                errors.append(
-                    f"merge_limit {merge_limit} blocks integrating {child_name}; already integrating: {', '.join(str(item) for item in integrating)}"
-                )
-
-    if state == "accepted":
-        from .task_gates import task_closeout_profile, validate_transition_readiness
-
-        profile = task_closeout_profile(child_dir, child_data)
-        if profile == "full":
-            errors.extend(
-                validate_transition_readiness(
-                    child_dir,
-                    child_data,
-                    "child-review",
-                    mode="complete",
-                )
-            )
-        elif profile == "parent":
-            errors.extend(
-                validate_transition_readiness(
-                    child_dir,
-                    child_data,
-                    "parent-integrated",
-                    mode="complete",
-                )
-            )
-
-    return errors
-
-
-def set_parent_child_integration_state(
-    parent_dir: Path,
-    parent_data: dict,
-    child_dir: Path,
-    child_data: dict,
-    state: str,
-    evidence: str,
-    ref: str | None = None,
-    reason: str | None = None,
-    merge_ref: str | None = None,
-) -> tuple[bool, list[str]]:
-    """Set a Parent-controlled Child integration state."""
-    errors = validate_parent_child_integration(
-        parent_dir,
-        parent_data,
-        child_dir,
-        child_data,
-        state,
-        evidence,
-        ref,
-        reason,
-    )
-    if errors:
-        return False, errors
-
-    data = ensure_task_map(parent_dir, parent_data, list(parent_data.get("children", [])))
-    child = get_child_entry(data, child_dir.name)
-    if child is None:
-        return False, [f"child missing from task-map.md: {child_dir.name}"]
-
-    child["state"] = state
-    child["evidence"] = evidence
-    if ref:
-        child["ref"] = ref
-    if merge_ref:
-        child["merged_ref"] = merge_ref
-    if reason:
-        child["reason"] = reason
-    elif "reason" in child:
-        del child["reason"]
-
-    queue = data.get("integration_queue")
-    if not isinstance(queue, list):
-        queue = []
-        data["integration_queue"] = queue
-    if state == "integrating":
-        if child_dir.name not in queue:
-            queue.append(child_dir.name)
-    elif child_dir.name in queue:
-        data["integration_queue"] = [item for item in queue if item != child_dir.name]
-
-    event = f"Parent set Child `{child_dir.name}` integration state to `{state}`. Evidence: {evidence}."
-    if ref:
-        event = f"{event} Ref: {ref}."
-    if merge_ref:
-        event = f"{event} Merge executed: git merge --no-ff --no-commit {merge_ref}."
-    if reason:
-        event = f"{event} Reason: {reason}."
-    _, body = load_task_map(parent_dir)
-    write_task_map(parent_dir, data, body, event)
-    return True, []
-
-
-def record_child_worktree(
-    parent_dir: Path,
-    parent_data: dict,
-    child_name: str,
-    branch: str,
-    worktree_path: str,
-    base_ref: str,
-) -> tuple[bool, list[str]]:
-    """Record a Child git worktree checkout in Parent task-map.md."""
-    errors: list[str] = []
-    if not _short_text(branch):
-        errors.append("branch must be a short reference")
-    if not _short_text(worktree_path):
-        errors.append("worktree_path must be a short path reference")
-    if not _short_text(base_ref):
-        errors.append("base_ref must be a short reference")
-
-    structural_children = parent_data.get("children", [])
-    if child_name not in structural_children:
-        errors.append(f"child is not linked to parent: {child_name}")
-    if errors:
-        return False, errors
-
-    data = ensure_task_map(parent_dir, parent_data, list(structural_children))
-    child = get_child_entry(data, child_name)
-    if child is None:
-        return False, [f"child missing from task-map.md: {child_name}"]
-
-    child["isolation"] = "git-worktree"
-    child["branch"] = branch
-    child["worktree_path"] = worktree_path
-    child["base_ref"] = base_ref
-    child["ref"] = f"refs/heads/{branch}"
-
-    event = (
-        f"Prepared Child `{child_name}` git worktree. "
-        f"Branch: {branch}. Path: {worktree_path}. Base: {base_ref}."
-    )
-    _, body = load_task_map(parent_dir)
-    write_task_map(parent_dir, data, body, event)
-    return True, []
-
-
-def get_child_entry(data: dict | None, child_name: str) -> dict | None:
-    """Return a child map entry by id."""
-    if not data:
-        return None
-    children = data.get("children")
-    if not isinstance(children, list):
-        return None
-    for child in children:
-        if isinstance(child, dict) and child.get("id") == child_name:
-            return child
-    return None
-
-
-def get_child_state(parent_dir: Path, child_name: str) -> str | None:
-    """Return child state from a Parent task-map.md."""
-    data, _ = load_task_map(parent_dir)
-    child = get_child_entry(data, child_name)
-    if not child:
-        return None
-    state = child.get("state")
-    return state if isinstance(state, str) else None
-
-
-def validate_parent_children_complete(parent_dir: Path, child_names: list[str]) -> list[str]:
-    """Validate every structural child is integrated or cancelled."""
-    errors: list[str] = []
-    data, _ = load_task_map(parent_dir)
-    if data is None:
-        return [f"{TASK_MAP}"]
-
-    for child_name in child_names:
-        child = get_child_entry(data, child_name)
-        if child is None:
-            errors.append(f"{TASK_MAP} missing child entry: {child_name}")
-            continue
-        state = child.get("state")
-        if state not in PARENT_TERMINAL_STATES:
-            errors.append(
-                f"child {child_name} must be integrated or cancelled before parent archive, got {state!r}"
-            )
-    return errors
-
-
-def validate_child_archive_state(parent_dir: Path, child_name: str) -> list[str]:
-    """Validate the Parent has marked a Child terminal before child archive."""
-    state = get_child_state(parent_dir, child_name)
-    if state is None:
-        return [f"{TASK_MAP} missing child entry: {child_name}"]
-    if state not in PARENT_TERMINAL_STATES:
-        return [
-            f"Parent task-map.md must mark child {child_name} integrated or cancelled before archive, got {state!r}"
-        ]
-    return []
-
-
-def write_task_map(
-    parent_dir: Path,
-    data: dict,
-    body: str,
-    event: str | None = None,
-) -> None:
-    """Write task-map.md from structured snapshot and Markdown body."""
-    normalized_body = body if body.strip() else _default_body()
-    if event:
-        normalized_body = _append_event(normalized_body, event)
-    content = f"---\n{_format_frontmatter(data)}---\n{normalized_body.lstrip()}"
-    (parent_dir / TASK_MAP).write_text(content, encoding="utf-8")
-
-
-def _default_child(child_name: str) -> dict:
-    return {
-        "id": child_name,
-        "state": "open",
-        "depends_on": [],
-        "touches": [],
-        "isolation": "git-worktree",
-        "ref": None,
-    }
-
-
-def _default_body() -> str:
-    return (
-        "# Task Map\n\n"
-        "## Orchestration notes\n\n"
-        "- `execution_topology: parallel` — children with empty `depends_on` may run concurrently; "
-        "Parent integrates serially up to `merge_limit`.\n"
-        "- Child-reported states: `open` → `working` → `blocked` | `review`.\n"
-        "- Parent-controlled states: `review` → `changes` | `accepted` → `integrating` → "
-        "`integrated` | `cancelled`.\n"
-        "- Declare `touches` per child before dispatch to reduce merge conflicts.\n"
-        "- `isolation: git-worktree` — run `prepare-child-worktree` from the **git package root** "
-        "(not a non-git harness root).\n\n"
-        "## Event Log\n\n"
-    )
-
-
-def _append_event(body: str, event: str) -> str:
-    stripped = body.rstrip()
-    if "## Event Log" not in stripped:
-        stripped = f"{stripped}\n\n## Event Log"
-    return f"{stripped}\n\n- {utc_now()} - {event}\n"
-
-
-def _split_frontmatter(content: str) -> tuple[str | None, str]:
-    lines = content.splitlines(keepends=True)
-    if not lines or lines[0].strip() != "---":
-        return None, content
-
-    for idx in range(1, len(lines)):
-        if lines[idx].strip() == "---":
-            frontmatter = "".join(lines[1:idx])
-            body = "".join(lines[idx + 1 :])
-            return frontmatter, body
-    return None, content
-
-
-def _parse_frontmatter(frontmatter: str) -> dict:
-    data: dict = {"children": []}
-    current_child: dict | None = None
-    in_children = False
-
-    for raw_line in frontmatter.splitlines():
-        if not raw_line.strip():
-            continue
-
-        if raw_line.startswith("children:"):
-            in_children = True
-            data["children"] = []
-            current_child = None
-            continue
-
-        if in_children and raw_line.startswith("  - "):
-            current_child = {}
-            data["children"].append(current_child)
-            item = raw_line[4:].strip()
-            if ":" in item:
-                key, value = item.split(":", 1)
-                current_child[key.strip()] = _parse_value(value.strip())
-            continue
-
-        if in_children and raw_line.startswith("    ") and current_child is not None:
-            item = raw_line.strip()
-            if ":" in item:
-                key, value = item.split(":", 1)
-                current_child[key.strip()] = _parse_value(value.strip())
-            continue
-
-        in_children = False
-        if ":" in raw_line:
-            key, value = raw_line.split(":", 1)
-            data[key.strip()] = _parse_value(value.strip())
-
-    return data
-
-
-def _parse_value(value: str):
-    if value == "null":
-        return None
-    if value == "[]":
-        return []
-    if value.startswith("[") and value.endswith("]"):
-        inner = value[1:-1].strip()
-        if not inner:
-            return []
-        return [item.strip().strip("'\"") for item in inner.split(",") if item.strip()]
-    if value.isdigit():
-        return int(value)
-    return value.strip("'\"")
-
-
-def _format_frontmatter(data: dict) -> str:
-    lines = [
-        f"parent_id: {_format_value(data.get('parent_id'))}",
-        f"contract_epoch: {_format_value(data.get('contract_epoch', 1))}",
-        f"execution_topology: {_format_value(data.get('execution_topology', 'serial'))}",
-        f"merge_limit: {_format_value(data.get('merge_limit', 1))}",
-        "children:",
-    ]
-    children = data.get("children", [])
-    if isinstance(children, list):
-        for child in children:
-            if not isinstance(child, dict):
-                continue
-            lines.append(f"  - id: {_format_value(child.get('id'))}")
-            lines.append(f"    state: {_format_value(child.get('state', 'open'))}")
-            lines.append(f"    depends_on: {_format_value(child.get('depends_on', []))}")
-            lines.append(f"    touches: {_format_value(child.get('touches', []))}")
-            lines.append(f"    isolation: {_format_value(child.get('isolation', 'git-worktree'))}")
-            lines.append(f"    ref: {_format_value(child.get('ref'))}")
-            if child.get("branch"):
-                lines.append(f"    branch: {_format_value(child.get('branch'))}")
-            if child.get("worktree_path"):
-                lines.append(f"    worktree_path: {_format_value(child.get('worktree_path'))}")
-            if child.get("base_ref"):
-                lines.append(f"    base_ref: {_format_value(child.get('base_ref'))}")
-            if child.get("merged_ref"):
-                lines.append(f"    merged_ref: {_format_value(child.get('merged_ref'))}")
-            if child.get("evidence"):
-                lines.append(f"    evidence: {_format_value(child.get('evidence'))}")
-            if child.get("reason"):
-                lines.append(f"    reason: {_format_value(child.get('reason'))}")
-    lines.append(f"integration_queue: {_format_value(data.get('integration_queue', []))}")
-    return "\n".join(lines) + "\n"
-
-
-def _format_value(value) -> str:
-    if value is None:
-        return "null"
-    if isinstance(value, list):
-        if not value:
-            return "[]"
-        return "[" + ", ".join(str(item) for item in value) + "]"
-    return str(value)
-
-
-def _short_text(value: str | None, max_len: int = 240) -> bool:
-    if not value or not isinstance(value, str):
-        return False
-    if len(value) > max_len:
-        return False
-    if "\n" in value or "\r" in value:
-        return False
-    return True
-
-
-def _required_child_evidence(child_dir: Path, names: list[str]) -> list[str]:
-    errors: list[str] = []
-    for name in names:
-        path = child_dir / name
-        if not path.is_file():
-            errors.append(name)
-            continue
-        try:
-            if not path.read_text(encoding="utf-8").strip():
-                errors.append(f"{name} is empty")
-        except OSError:
-            errors.append(f"{name} could not be read")
-    return errors
+#!/usr/bin/env python3
+"""
+Parent/Child task-map helpers.
+
+task-map.md is the Parent Supervisor's orchestration authority. This module
+parses and writes only the small YAML frontmatter subset generated here.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+TASK_MAP = "task-map.md"
+
+CHILD_STATES = {
+    "open",
+    "working",
+    "blocked",
+    "review",
+    "changes",
+    "accepted",
+    "integrating",
+    "integrated",
+    "cancelled",
+}
+
+PARENT_TERMINAL_STATES = {"integrated", "cancelled"}
+PARENT_CONTROLLED_STATES = {
+    "changes",
+    "accepted",
+    "integrating",
+    "integrated",
+    "cancelled",
+}
+CHILD_REPORT_STATES = CHILD_STATES - PARENT_CONTROLLED_STATES
+REF_REQUIRED_STATES = {"accepted", "integrating", "integrated"}
+HANDOFF_REQUIRED_STATES = {"accepted", "integrating", "integrated"}
+
+
+def utc_now() -> str:
+    """Return a compact UTC timestamp for task-map event log entries."""
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace(
+        "+00:00", "Z"
+    )
+
+
+def load_task_map(parent_dir: Path) -> tuple[dict | None, str]:
+    """Load task-map.md frontmatter and body."""
+    path = parent_dir / TASK_MAP
+    if not path.is_file():
+        return None, ""
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        return None, ""
+
+    frontmatter, body = _split_frontmatter(content)
+    if frontmatter is None:
+        return None, content
+    return _parse_frontmatter(frontmatter), body
+
+
+def ensure_task_map(
+    parent_dir: Path,
+    parent_data: dict,
+    child_names: list[str],
+    event: str | None = None,
+) -> dict:
+    """Ensure task-map.md exists and contains entries for all child_names."""
+    data, body = load_task_map(parent_dir)
+    if data is None:
+        data = {
+            "parent_id": parent_data.get("id") or parent_dir.name,
+            "contract_epoch": 1,
+            "execution_topology": "serial",
+            "merge_limit": 1,
+            "children": [],
+            "stages": [],
+            "integration_queue": [],
+        }
+        body = _default_body()
+
+    data.setdefault("parent_id", parent_data.get("id") or parent_dir.name)
+    data.setdefault("contract_epoch", 1)
+    data.setdefault("execution_topology", "serial")
+    data.setdefault("merge_limit", 1)
+    data.setdefault("children", [])
+    data.setdefault("stages", [])
+    data.setdefault("integration_queue", [])
+
+    existing = {
+        child.get("id"): child
+        for child in data.get("children", [])
+        if isinstance(child, dict)
+    }
+    for child_name in child_names:
+        if child_name not in existing:
+            child = _default_child(child_name)
+            data["children"].append(child)
+            existing[child_name] = child
+
+    write_task_map(parent_dir, data, body, event)
+    return data
+
+
+def remove_child_from_task_map(
+    parent_dir: Path,
+    parent_data: dict,
+    child_name: str,
+) -> None:
+    """Remove a child entry from task-map.md when structural links are removed."""
+    data, body = load_task_map(parent_dir)
+    if data is None:
+        return
+
+    children = data.get("children")
+    if isinstance(children, list):
+        data["children"] = [
+            child
+            for child in children
+            if not isinstance(child, dict) or child.get("id") != child_name
+        ]
+    data.setdefault("parent_id", parent_data.get("id") or parent_dir.name)
+    write_task_map(parent_dir, data, body, f"Unlinked Child `{child_name}`.")
+
+
+def set_child_state(
+    parent_dir: Path,
+    parent_data: dict,
+    child_name: str,
+    state: str,
+    evidence: str,
+    reason: str | None = None,
+) -> tuple[bool, list[str]]:
+    """Set a child state inside Parent task-map.md."""
+    errors: list[str] = []
+    if state not in CHILD_STATES:
+        errors.append(f"unknown child state: {state}")
+    if not _short_text(evidence):
+        errors.append("evidence must be a short reference")
+    if reason and not _short_text(reason, 500):
+        errors.append("reason must be short and single-line")
+    if errors:
+        return False, errors
+
+    structural_children = parent_data.get("children", [])
+    if child_name not in structural_children:
+        errors.append(f"child is not linked to parent: {child_name}")
+        return False, errors
+
+    data = ensure_task_map(parent_dir, parent_data, list(structural_children))
+    child = get_child_entry(data, child_name)
+    if child is None:
+        errors.append(f"child missing from task-map.md: {child_name}")
+        return False, errors
+
+    child["state"] = state
+    child["evidence"] = evidence
+    if reason:
+        child["reason"] = reason
+
+    event = f"Set Child `{child_name}` state to `{state}`. Evidence: {evidence}."
+    if reason:
+        event = f"{event} Reason: {reason}."
+    _, body = load_task_map(parent_dir)
+    write_task_map(parent_dir, data, body, event)
+    return True, []
+
+
+def validate_parent_child_integration(
+    parent_dir: Path,
+    parent_data: dict,
+    child_dir: Path,
+    child_data: dict,
+    state: str,
+    evidence: str,
+    ref: str | None = None,
+    reason: str | None = None,
+    current_state_override: str | None = None,
+) -> list[str]:
+    """Validate a Parent-controlled Child integration state transition."""
+    errors: list[str] = []
+    child_name = child_dir.name
+    if state not in PARENT_CONTROLLED_STATES:
+        errors.append(f"state is not Parent-controlled: {state}")
+    if not _short_text(evidence):
+        errors.append("evidence must be a short reference")
+    if reason and not _short_text(reason, 500):
+        errors.append("reason must be short and single-line")
+    if state in {"changes", "cancelled"} and not reason:
+        errors.append(f"{state} requires --reason")
+    if state in REF_REQUIRED_STATES and not _short_text(ref):
+        errors.append(f"{state} requires --ref")
+
+    if child_data.get("parent") != parent_dir.name:
+        errors.append(f"child is not linked to parent: {child_name}")
+
+    structural_children = parent_data.get("children", [])
+    if child_name not in structural_children:
+        errors.append(f"child is not linked to parent: {child_name}")
+
+    data, _ = load_task_map(parent_dir)
+    if data is None:
+        errors.append(f"{TASK_MAP}")
+        return errors
+
+    child = get_child_entry(data, child_name)
+    if child is None:
+        errors.append(f"child missing from task-map.md: {child_name}")
+        return errors
+
+    current_state = (
+        current_state_override
+        if current_state_override is not None
+        else child.get("state")
+    )
+    if state in {"accepted", "changes"} and current_state != "review":
+        errors.append(f"{state} requires current Child state 'review', got {current_state!r}")
+    if state == "integrating" and current_state != "accepted":
+        errors.append(f"integrating requires current Child state 'accepted', got {current_state!r}")
+    if state == "integrated" and current_state != "integrating":
+        errors.append(f"integrated requires current Child state 'integrating', got {current_state!r}")
+
+    if state in HANDOFF_REQUIRED_STATES:
+        errors.extend(_required_child_evidence(child_dir, ["verify.md", "handoff.md"]))
+
+    if state == "integrating":
+        merge_limit = data.get("merge_limit", 1)
+        if not isinstance(merge_limit, int) or merge_limit < 1:
+            errors.append("merge_limit must be a positive integer")
+        else:
+            integrating = [
+                item.get("id")
+                for item in data.get("children", [])
+                if isinstance(item, dict)
+                and item.get("id") != child_name
+                and item.get("state") == "integrating"
+            ]
+            if len(integrating) >= merge_limit:
+                errors.append(
+                    f"merge_limit {merge_limit} blocks integrating {child_name}; already integrating: {', '.join(str(item) for item in integrating)}"
+                )
+
+    if state == "accepted":
+        from .task_gates import task_closeout_profile, validate_transition_readiness
+
+        profile = task_closeout_profile(child_dir, child_data)
+        if profile == "full":
+            errors.extend(
+                validate_transition_readiness(
+                    child_dir,
+                    child_data,
+                    "child-review",
+                    mode="complete",
+                )
+            )
+        elif profile == "parent":
+            errors.extend(
+                validate_transition_readiness(
+                    child_dir,
+                    child_data,
+                    "parent-integrated",
+                    mode="complete",
+                )
+            )
+
+    return errors
+
+
+def set_parent_child_integration_state(
+    parent_dir: Path,
+    parent_data: dict,
+    child_dir: Path,
+    child_data: dict,
+    state: str,
+    evidence: str,
+    ref: str | None = None,
+    reason: str | None = None,
+    merge_ref: str | None = None,
+) -> tuple[bool, list[str]]:
+    """Set a Parent-controlled Child integration state."""
+    errors = validate_parent_child_integration(
+        parent_dir,
+        parent_data,
+        child_dir,
+        child_data,
+        state,
+        evidence,
+        ref,
+        reason,
+    )
+    if errors:
+        return False, errors
+
+    data = ensure_task_map(parent_dir, parent_data, list(parent_data.get("children", [])))
+    child = get_child_entry(data, child_dir.name)
+    if child is None:
+        return False, [f"child missing from task-map.md: {child_dir.name}"]
+
+    child["state"] = state
+    child["evidence"] = evidence
+    if ref:
+        child["ref"] = ref
+    if merge_ref:
+        child["merged_ref"] = merge_ref
+    if reason:
+        child["reason"] = reason
+    elif "reason" in child:
+        del child["reason"]
+
+    queue = data.get("integration_queue")
+    if not isinstance(queue, list):
+        queue = []
+        data["integration_queue"] = queue
+    if state == "integrating":
+        if child_dir.name not in queue:
+            queue.append(child_dir.name)
+    elif child_dir.name in queue:
+        data["integration_queue"] = [item for item in queue if item != child_dir.name]
+
+    event = f"Parent set Child `{child_dir.name}` integration state to `{state}`. Evidence: {evidence}."
+    if ref:
+        event = f"{event} Ref: {ref}."
+    if merge_ref:
+        event = f"{event} Merge executed: git merge --no-ff --no-commit {merge_ref}."
+    if reason:
+        event = f"{event} Reason: {reason}."
+    _, body = load_task_map(parent_dir)
+    write_task_map(parent_dir, data, body, event)
+    return True, []
+
+
+def record_child_worktree(
+    parent_dir: Path,
+    parent_data: dict,
+    child_name: str,
+    branch: str,
+    worktree_path: str,
+    base_ref: str,
+) -> tuple[bool, list[str]]:
+    """Record a Child git worktree checkout in Parent task-map.md."""
+    errors: list[str] = []
+    if not _short_text(branch):
+        errors.append("branch must be a short reference")
+    if not _short_text(worktree_path):
+        errors.append("worktree_path must be a short path reference")
+    if not _short_text(base_ref):
+        errors.append("base_ref must be a short reference")
+
+    structural_children = parent_data.get("children", [])
+    if child_name not in structural_children:
+        errors.append(f"child is not linked to parent: {child_name}")
+    if errors:
+        return False, errors
+
+    data = ensure_task_map(parent_dir, parent_data, list(structural_children))
+    child = get_child_entry(data, child_name)
+    if child is None:
+        return False, [f"child missing from task-map.md: {child_name}"]
+
+    child["isolation"] = "git-worktree"
+    child["branch"] = branch
+    child["worktree_path"] = worktree_path
+    child["base_ref"] = base_ref
+    child["ref"] = f"refs/heads/{branch}"
+
+    event = (
+        f"Prepared Child `{child_name}` git worktree. "
+        f"Branch: {branch}. Path: {worktree_path}. Base: {base_ref}."
+    )
+    _, body = load_task_map(parent_dir)
+    write_task_map(parent_dir, data, body, event)
+    return True, []
+
+
+def get_child_entry(data: dict | None, child_name: str) -> dict | None:
+    """Return a child map entry by id."""
+    if not data:
+        return None
+    children = data.get("children")
+    if not isinstance(children, list):
+        return None
+    for child in children:
+        if isinstance(child, dict) and child.get("id") == child_name:
+            return child
+    return None
+
+
+def get_child_state(parent_dir: Path, child_name: str) -> str | None:
+    """Return child state from a Parent task-map.md."""
+    data, _ = load_task_map(parent_dir)
+    child = get_child_entry(data, child_name)
+    if not child:
+        return None
+    state = child.get("state")
+    return state if isinstance(state, str) else None
+
+
+def validate_parent_children_complete(parent_dir: Path, child_names: list[str]) -> list[str]:
+    """Validate every structural child is integrated or cancelled."""
+    errors: list[str] = []
+    data, _ = load_task_map(parent_dir)
+    if data is None:
+        return [f"{TASK_MAP}"]
+
+    for child_name in child_names:
+        child = get_child_entry(data, child_name)
+        if child is None:
+            errors.append(f"{TASK_MAP} missing child entry: {child_name}")
+            continue
+        state = child.get("state")
+        if state not in PARENT_TERMINAL_STATES:
+            errors.append(
+                f"child {child_name} must be integrated or cancelled before parent archive, got {state!r}"
+            )
+    return errors
+
+
+def validate_child_archive_state(parent_dir: Path, child_name: str) -> list[str]:
+    """Validate the Parent has marked a Child terminal before child archive."""
+    state = get_child_state(parent_dir, child_name)
+    if state is None:
+        return [f"{TASK_MAP} missing child entry: {child_name}"]
+    if state not in PARENT_TERMINAL_STATES:
+        return [
+            f"Parent task-map.md must mark child {child_name} integrated or cancelled before archive, got {state!r}"
+        ]
+    return []
+
+
+def write_task_map(
+    parent_dir: Path,
+    data: dict,
+    body: str,
+    event: str | None = None,
+) -> None:
+    """Write task-map.md from structured snapshot and Markdown body."""
+    normalized_body = body if body.strip() else _default_body()
+    if event:
+        normalized_body = _append_event(normalized_body, event)
+    content = f"---\n{_format_frontmatter(data)}---\n{normalized_body.lstrip()}"
+    (parent_dir / TASK_MAP).write_text(content, encoding="utf-8")
+
+
+def _default_child(child_name: str) -> dict:
+    return {
+        "id": child_name,
+        "state": "open",
+        "depends_on": [],
+        "touches": [],
+        "isolation": "git-worktree",
+        "ref": None,
+    }
+
+
+def _default_body() -> str:
+    return (
+        "# Task Map\n\n"
+        "## Orchestration notes\n\n"
+        "- `execution_topology: parallel` — children with empty `depends_on` may run concurrently; "
+        "Parent integrates serially up to `merge_limit`.\n"
+        "- Child-reported states: `open` → `working` → `blocked` | `review`.\n"
+        "- Parent-controlled states: `review` → `changes` | `accepted` → `integrating` → "
+        "`integrated` | `cancelled`.\n"
+        "- Declare `touches` per child before dispatch to reduce merge conflicts.\n"
+        "- `isolation: git-worktree` — run `prepare-child-worktree` from the **git package root** "
+        "(not a non-git harness root).\n\n"
+        "## Event Log\n\n"
+    )
+
+
+def _append_event(body: str, event: str) -> str:
+    stripped = body.rstrip()
+    if "## Event Log" not in stripped:
+        stripped = f"{stripped}\n\n## Event Log"
+    return f"{stripped}\n\n- {utc_now()} - {event}\n"
+
+
+def _split_frontmatter(content: str) -> tuple[str | None, str]:
+    lines = content.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return None, content
+
+    for idx in range(1, len(lines)):
+        if lines[idx].strip() == "---":
+            frontmatter = "".join(lines[1:idx])
+            body = "".join(lines[idx + 1 :])
+            return frontmatter, body
+    return None, content
+
+
+def _parse_frontmatter(frontmatter: str) -> dict:
+    """Parse the small YAML subset written by this module.
+
+    Supports top-level scalars plus list-of-maps for ``children:`` and optional
+    ``stages:`` (same indentation style).
+    """
+    data: dict = {"children": [], "stages": []}
+    current_item: dict | None = None
+    list_key: str | None = None
+
+    for raw_line in frontmatter.splitlines():
+        if not raw_line.strip():
+            continue
+
+        if raw_line.startswith("children:"):
+            list_key = "children"
+            data["children"] = []
+            current_item = None
+            continue
+
+        if raw_line.startswith("stages:"):
+            list_key = "stages"
+            data["stages"] = []
+            current_item = None
+            continue
+
+        if list_key and raw_line.startswith("  - "):
+            current_item = {}
+            data[list_key].append(current_item)
+            item = raw_line[4:].strip()
+            if ":" in item:
+                key, value = item.split(":", 1)
+                current_item[key.strip()] = _parse_value(value.strip())
+            continue
+
+        if list_key and raw_line.startswith("    ") and current_item is not None:
+            item = raw_line.strip()
+            if ":" in item:
+                key, value = item.split(":", 1)
+                current_item[key.strip()] = _parse_value(value.strip())
+            continue
+
+        list_key = None
+        current_item = None
+        if ":" in raw_line:
+            key, value = raw_line.split(":", 1)
+            data[key.strip()] = _parse_value(value.strip())
+
+    return data
+
+
+def _parse_value(value: str):
+    if value == "null":
+        return None
+    if value == "[]":
+        return []
+    if value.startswith("[") and value.endswith("]"):
+        inner = value[1:-1].strip()
+        if not inner:
+            return []
+        return [item.strip().strip("'\"") for item in inner.split(",") if item.strip()]
+    if value.isdigit():
+        return int(value)
+    return value.strip("'\"")
+
+
+def _format_frontmatter(data: dict) -> str:
+    lines = [
+        f"parent_id: {_format_value(data.get('parent_id'))}",
+        f"contract_epoch: {_format_value(data.get('contract_epoch', 1))}",
+        f"execution_topology: {_format_value(data.get('execution_topology', 'serial'))}",
+        f"merge_limit: {_format_value(data.get('merge_limit', 1))}",
+        "children:",
+    ]
+    children = data.get("children", [])
+    if isinstance(children, list):
+        for child in children:
+            if not isinstance(child, dict):
+                continue
+            lines.append(f"  - id: {_format_value(child.get('id'))}")
+            lines.append(f"    state: {_format_value(child.get('state', 'open'))}")
+            lines.append(f"    depends_on: {_format_value(child.get('depends_on', []))}")
+            lines.append(f"    touches: {_format_value(child.get('touches', []))}")
+            lines.append(f"    isolation: {_format_value(child.get('isolation', 'git-worktree'))}")
+            lines.append(f"    ref: {_format_value(child.get('ref'))}")
+            if child.get("branch"):
+                lines.append(f"    branch: {_format_value(child.get('branch'))}")
+            if child.get("worktree_path"):
+                lines.append(f"    worktree_path: {_format_value(child.get('worktree_path'))}")
+            if child.get("base_ref"):
+                lines.append(f"    base_ref: {_format_value(child.get('base_ref'))}")
+            if child.get("merged_ref"):
+                lines.append(f"    merged_ref: {_format_value(child.get('merged_ref'))}")
+            if child.get("evidence"):
+                lines.append(f"    evidence: {_format_value(child.get('evidence'))}")
+            if child.get("reason"):
+                lines.append(f"    reason: {_format_value(child.get('reason'))}")
+    stages = data.get("stages") or []
+    if isinstance(stages, list) and stages:
+        lines.append("stages:")
+        for stage in stages:
+            if not isinstance(stage, dict):
+                continue
+            lines.append(f"  - id: {_format_value(stage.get('id'))}")
+            if stage.get("title"):
+                lines.append(f"    title: {_format_value(stage.get('title'))}")
+            lines.append(f"    units: {_format_value(stage.get('units', []))}")
+    lines.append(f"integration_queue: {_format_value(data.get('integration_queue', []))}")
+    return "\n".join(lines) + "\n"
+
+
+def _format_value(value) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, list):
+        if not value:
+            return "[]"
+        return "[" + ", ".join(str(item) for item in value) + "]"
+    return str(value)
+
+
+def _short_text(value: str | None, max_len: int = 240) -> bool:
+    if not value or not isinstance(value, str):
+        return False
+    if len(value) > max_len:
+        return False
+    if "\n" in value or "\r" in value:
+        return False
+    return True
+
+
+def _required_child_evidence(child_dir: Path, names: list[str]) -> list[str]:
+    errors: list[str] = []
+    for name in names:
+        path = child_dir / name
+        if not path.is_file():
+            errors.append(name)
+            continue
+        try:
+            if not path.read_text(encoding="utf-8").strip():
+                errors.append(f"{name} is empty")
+        except OSError:
+            errors.append(f"{name} could not be read")
+    return errors