@pennixrv/trellis 0.7.0-beta.9 → 0.7.1-beta.0

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

@@ -6,7 +6,6 @@ Provides:
     ensure_tasks_dir   - Ensure tasks directory exists
     cmd_create         - Create a new task
     cmd_rename         - Rename a task and every reference to it
-    cmd_archive        - Archive completed task
     cmd_set_branch     - Set git branch for task
     cmd_set_base_branch - Set PR target branch
     cmd_set_scope      - Set scope for PR title
@@ -27,26 +26,18 @@ from pathlib import Path
 from .config import (
     get_codex_dispatch_mode,
     get_packages,
-    get_session_auto_commit,
     is_monorepo,
     resolve_package,
     validate_package,
 )
 from .git import (
-    INDEX_LOCK_RETRY_ATTEMPTS,
-    branch_exists_locally,
-    has_git_remote,
-    index_lock_path,
     resolve_default_branch,
     run_git,
-    run_git_retry_index_lock,
-    stderr_indicates_index_lock,
 )
 from .io import describe_json_read_failure, read_json_checked, write_json
 from .log import Colors, colored
 from .paths import (
     DEVELOPER_HINT,
-    DIR_ARCHIVE,
     DIR_TASKS,
     DIR_WORKFLOW,
     FILE_TASK_JSON,
@@ -55,14 +46,7 @@ from .paths import (
     get_repo_root,
     get_tasks_dir,
 )
-from .safe_commit import (
-    print_gitignore_warning,
-    safe_archive_paths_to_add,
-    safe_git_add,
-)
 from .task_utils import (
-    archive_destination_for,
-    archive_task_complete,
     find_task_by_name,
     is_within_tasks_dir,
     resolve_task_dir,
@@ -81,7 +65,7 @@ from .workflow_selection import DIR_WORKFLOWS, WORKFLOW_ID_RE
 # U+0085 (NEL) and U+001C-U+001F, which JS keeps; JS strips U+FEFF (BOM),
 # which Python keeps. Stripping the union means anything create accepts is
 # still non-empty after either side trims it, so a record cannot pass here and
-# then be refused as empty by a JS pre-archive validator.
+# then fail equivalent validation in a JavaScript consumer.
 BLANK_CHARS = (
     "\t\n\v\f\r"                              # U+0009-U+000D
     "\x1c\x1d\x1e\x1f"                        # U+001C-U+001F separators (Python only)
@@ -114,34 +98,14 @@ def _slugify(title: str) -> str:
 def ensure_tasks_dir(repo_root: Path) -> Path:
     """Ensure tasks directory exists."""
     tasks_dir = get_tasks_dir(repo_root)
-    archive_dir = tasks_dir / "archive"
 
     if not tasks_dir.exists():
         tasks_dir.mkdir(parents=True)
         print(colored(f"Created tasks directory: {tasks_dir}", Colors.GREEN), file=sys.stderr)
 
-    if not archive_dir.exists():
-        archive_dir.mkdir(parents=True)
-
     return tasks_dir
 
 
-def _find_archived_task_by_dir_name(tasks_dir: Path, dir_name: str) -> Path | None:
-    """Find an archived task directory with the exact active-task dir name."""
-    archive_dir = tasks_dir / DIR_ARCHIVE
-    if not archive_dir.is_dir():
-        return None
-
-    for month_dir in sorted(archive_dir.iterdir()):
-        if not month_dir.is_dir():
-            continue
-        candidate = month_dir / dir_name
-        if candidate.is_dir():
-            return candidate
-
-    return None
-
-
 def _repo_relative_path(path: Path, repo_root: Path) -> str:
     """Format a path relative to the repo root when possible."""
     try:
@@ -197,41 +161,30 @@ def _report_write_failure(path: Path) -> None:
     )
 
 
-def _restore_child_links(unlinked: dict[Path, str | None]) -> None:
-    """Put back the parent links this archive attempt already removed.
+def _task_mutation_allowed(repo_root: Path, task_dir: Path, data: dict) -> bool:
+    from .task_continuity import assert_task_mutation_allowed
+    from .task_workflow import TaskWorkflowError
 
-    The unlink loop below walks a parent's children one at a time, so a
-    failure part-way through leaves the earlier children carrying
-    ``parent: null`` while their parent is still in the active tree. That is
-    the mirror image of the dangling reference the same loop already refuses
-    to create, and nothing repairs it later either, so undo it before the
-    failure is reported.
+    try:
+        assert_task_mutation_allowed(repo_root, task_dir, data)
+    except TaskWorkflowError as error:
+        print(colored(f"{error.code}: {error}", Colors.RED), file=sys.stderr)
+        return False
+    return True
 
-    Restoring is best-effort: if a child cannot be written back, name it so
-    the caller can re-link it by hand instead of guessing which one broke.
-    """
-    broken: list[str] = []
-    for child_json, original_parent in unlinked.items():
-        child_data, _ = read_json_checked(child_json)
-        if child_data is None:
-            broken.append(child_json.parent.name)
-            continue
-        child_data["parent"] = original_parent
-        if not write_json(child_json, child_data):
-            broken.append(child_json.parent.name)
-    if broken:
-        print(
-            colored(
-                f"Warning: could not restore the parent link on: {', '.join(broken)}. "
-                "Re-link each one with `python3 .trellis/scripts/task.py "
-                "add-subtask <parent> <child>`.",
-                Colors.RED,
-            ),
-            file=sys.stderr,
-        )
+
+def _task_identity_change_allowed(repo_root: Path, task_dir: Path, data: dict) -> bool:
+    from .task_continuity import assert_task_identity_change_allowed
+    from .task_workflow import TaskWorkflowError
+
+    try:
+        assert_task_identity_change_allowed(repo_root, task_dir, data)
+    except TaskWorkflowError as error:
+        print(colored(f"{error.code}: {error}", Colors.RED), file=sys.stderr)
+        return False
+    return True
 
 
-# =============================================================================
 # Sub-agent platform detection + JSONL context files
 # =============================================================================
 
@@ -266,9 +219,9 @@ def _has_subagent_platform(repo_root: Path) -> bool:
     """Return True if any sub-agent-capable platform is configured.
 
     Detected by probing well-known config directories at the repo root. Codex
-    counts only when ``codex.dispatch_mode: auto`` is explicitly selected
-    (including the legacy ``sub-agent`` alias); the default inline mode loads
-    context through skills, not JSONL.
+    counts by default through ``codex.dispatch_mode: auto`` (including the
+    legacy ``sub-agent`` alias); explicit inline mode loads context through
+    skills, not JSONL.
     """
     for config_dir in _SUBAGENT_CONFIG_DIRS:
         if (repo_root / config_dir).is_dir():
@@ -334,13 +287,13 @@ def cmd_create(args: argparse.Namespace) -> int:
 
     # Title and description are checked first, before ensure_tasks_dir and any
     # other write, so a rejected create leaves the tree untouched. Both are
-    # required non-empty by pre-archive validation; catching that here costs
-    # one retyped command instead of blocking a PR hours later.
+    # required non-empty; catching that here costs one retyped command instead
+    # of discovering the invalid task later.
     if not strip_blank(args.title):
         print(colored("Error: title is required", Colors.RED), file=sys.stderr)
         print(
             'Pass a non-empty <title> (whitespace only does not count): a task '
-            "with an empty title is refused at archive.",
+            "with an empty title cannot be completed.",
             file=sys.stderr,
         )
         return 1
@@ -350,7 +303,7 @@ def cmd_create(args: argparse.Namespace) -> int:
         print(colored("Error: --description is required", Colors.RED), file=sys.stderr)
         print(
             'Pass --description "<what this task delivers>" (whitespace only does '
-            "not count): a task with an empty description is refused at archive.",
+            "not count): a task with an empty description cannot be completed.",
             file=sys.stderr,
         )
         return 1
@@ -486,22 +439,17 @@ def cmd_create(args: argparse.Namespace) -> int:
             _report_read_failure(parent_json_path, parent_reason)
             print("No task was created. Fix the parent task.json, then retry.", file=sys.stderr)
             return 1
+        if not _task_mutation_allowed(repo_root, parent_dir, parent_data):
+            return 1
 
     dir_name = f"{date_prefix}-{slug}"
     task_dir = tasks_dir / dir_name
     task_json_path = task_dir / FILE_TASK_JSON
 
-    archived_task_dir = _find_archived_task_by_dir_name(tasks_dir, dir_name)
-    if archived_task_dir:
-        print(colored(f"Error: Task already archived: {dir_name}", Colors.RED), file=sys.stderr)
-        print(f"Archived at: {_repo_relative_path(archived_task_dir, repo_root)}", file=sys.stderr)
-        print("Use a new slug if you intend to create a new task.", file=sys.stderr)
-        return 1
-
     # Reusing a slug on the same day is an ordinary accident, and continuing
     # would rewrite the existing task.json below — resetting status, children,
     # parent, branch and meta, which nothing else can reconstruct. Fail like
-    # the archived-name collision above unless the caller asks for it.
+    # unless the caller asks for it.
     if task_dir.exists():
         if not getattr(args, "force", False):
             print(colored(f"Error: Task already exists: {dir_name}", Colors.RED), file=sys.stderr)
@@ -518,6 +466,13 @@ def cmd_create(args: argparse.Namespace) -> int:
             ),
             file=sys.stderr,
         )
+        if task_json_path.is_file():
+            existing_data, existing_reason = read_json_checked(task_json_path)
+            if existing_data is None:
+                _report_read_failure(task_json_path, existing_reason)
+                return 1
+            if not _task_mutation_allowed(repo_root, task_dir, existing_data):
+                return 1
         created_dir = False
     else:
         task_dir.mkdir(parents=True)
@@ -887,7 +842,7 @@ def _plan_backrefs(
     unreadable: list[Path] = []
 
     for candidate in sorted(tasks_dir.iterdir()):
-        if not candidate.is_dir() or candidate.name == DIR_ARCHIVE:
+        if not candidate.is_dir():
             continue
         if candidate == task_dir:
             continue
@@ -1017,6 +972,10 @@ def _apply_rename(plan: _RenamePlan, repo_root: Path) -> int:
     finishes; a move-first ordering would instead leave the old name
     unresolvable and the remaining edits to be made by hand.
     """
+    if not _task_mutation_allowed(repo_root, plan.task_dir, plan.task_data):
+        return 1
+    if plan.identity and not _task_identity_change_allowed(repo_root, plan.task_dir, plan.task_data):
+        return 1
     if plan.identity:
         data = dict(plan.task_data)
         for field_name, _old_value, new_value in plan.identity:
@@ -1056,8 +1015,7 @@ def _apply_rename(plan: _RenamePlan, repo_root: Path) -> int:
     # Last, and after the move: a session pointing at the old path would now
     # resolve to a missing directory, so `current` would report the task stale
     # and the context hook would inject nothing until the user ran `start`
-    # again. Archive clears these pointers because the task is leaving; rename
-    # moves them, because the task is still the one being worked on.
+    # again. Rename moves the pointers because the task is still being worked on.
     from .active_task import repoint_task_in_sessions
 
     repoint_task_in_sessions(str(plan.task_dir), str(plan.new_dir), repo_root)
@@ -1076,13 +1034,12 @@ def cmd_rename(args: argparse.Namespace) -> int:
             print(colored(f"Error: Task not found: {args.name}", Colors.RED), file=sys.stderr)
         return 1
 
-    # Narrower than resolve_task_dir's containment: an archived task has left
-    # the active set, so its back-references are no longer maintained here.
+    # Restrict renames to task records directly under the tasks directory.
     if not is_within_tasks_dir(task_dir, repo_root):
         print(
             colored(
                 f"Error: refusing to rename '{args.name}': "
-                f"{task_dir} is not an active task under {tasks_dir}",
+                f"{task_dir} is not a task directly under {tasks_dir}",
                 Colors.RED,
             ),
             file=sys.stderr,
@@ -1114,16 +1071,6 @@ def cmd_rename(args: argparse.Namespace) -> int:
         print("Pick a different slug.", file=sys.stderr)
         return 1
 
-    archived_task_dir = _find_archived_task_by_dir_name(tasks_dir, new_name)
-    if archived_task_dir:
-        print(
-            colored(f"Error: Task already archived: {new_name}", Colors.RED),
-            file=sys.stderr,
-        )
-        print(f"Archived at: {_repo_relative_path(archived_task_dir, repo_root)}", file=sys.stderr)
-        print("Pick a different slug.", file=sys.stderr)
-        return 1
-
     task_json_path = task_dir / FILE_TASK_JSON
     if not task_json_path.is_file():
         print(
@@ -1194,455 +1141,6 @@ def cmd_rename(args: argparse.Namespace) -> int:
         )
     return 0
 
-
-# =============================================================================
-# Command: archive
-# =============================================================================
-
-def _task_branch_field(data: dict, key: str) -> str:
-    """Read a branch field as a trimmed string ("" when unset or not a string)."""
-    value = data.get(key)
-    return strip_blank(value) if isinstance(value, str) else ""
-
-
-def _validate_branch_metadata(
-    data: dict,
-    task_name: str,
-    repo_root: Path,
-    skip: bool,
-) -> bool:
-    """Check branch metadata before the task leaves the active tree.
-
-    Returns False when archiving must stop. Archive is the last gate that sees
-    a task, so metadata nobody can reconstruct afterwards is refused here
-    rather than repaired by hand later (#399 follow-up).
-
-    "PR-backed" is deliberately pragmatic: a task carrying a base_branch in a
-    repo that has a remote was created expecting a PR, so a missing `branch`
-    means the metadata was never recorded — not that the work had no branch.
-    Local-only repos and tasks without a base_branch are left alone.
-
-    A recorded branch that no longer exists locally stays a warning: after a
-    merge the feature branch is normally deleted, and refusing to archive then
-    would be backwards.
-    """
-    branch = _task_branch_field(data, "branch")
-    base_branch = _task_branch_field(data, "base_branch")
-    task_py = f"python3 {DIR_WORKFLOW}/scripts/task.py"
-
-    if branch and not branch_exists_locally(branch, repo_root):
-        print(
-            colored(
-                f"Warning: recorded branch '{branch}' no longer exists locally "
-                "(likely merged and deleted).",
-                Colors.YELLOW,
-            ),
-            file=sys.stderr,
-        )
-
-    if skip:
-        return True
-
-    if branch and base_branch and branch == base_branch:
-        print(
-            colored(
-                f"Error: refusing to archive '{task_name}': branch and base_branch "
-                f"are both '{branch}'. A PR cannot target its own branch, so this "
-                "metadata cannot describe the work that was merged.",
-                Colors.RED,
-            ),
-            file=sys.stderr,
-        )
-        print("Repair whichever field is wrong:", file=sys.stderr)
-        print(f"  {task_py} set-branch {task_name} <feature-branch>", file=sys.stderr)
-        print(f"  {task_py} set-base-branch {task_name} <target-branch>", file=sys.stderr)
-        print(
-            f"  {task_py} archive {task_name} --skip-branch-validation"
-            "   # only if this task was never PR-backed",
-            file=sys.stderr,
-        )
-        return False
-
-    if not branch and base_branch and has_git_remote(repo_root):
-        print(
-            colored(
-                f"Error: refusing to archive '{task_name}': no branch is recorded, "
-                f"but the task targets base_branch '{base_branch}' in a repo with a "
-                "remote — the branch it was built on was never written down.",
-                Colors.RED,
-            ),
-            file=sys.stderr,
-        )
-        print("Repair with:", file=sys.stderr)
-        print(f"  {task_py} set-branch {task_name} <branch>", file=sys.stderr)
-        print(
-            f"  {task_py} archive {task_name} --skip-branch-validation"
-            "   # only if the work landed without a branch of its own",
-            file=sys.stderr,
-        )
-        return False
-
-    return True
-
-
-def cmd_archive(args: argparse.Namespace) -> int:
-    """Archive completed task."""
-    repo_root = get_repo_root()
-    task_name = args.name
-
-    if not task_name:
-        print(colored("Error: Task name is required", Colors.RED), file=sys.stderr)
-        return 1
-
-    tasks_dir = get_tasks_dir(repo_root)
-
-    # Resolve task directory (supports task name, relative path, or absolute path)
-    task_dir = resolve_task_dir(task_name, repo_root)
-
-    if task_dir is None or not task_dir.is_dir():
-        if task_dir is None:
-            # resolve_task_dir already reported why; keep the archive-specific
-            # refusal so it reads the same as the is_within_tasks_dir guard.
-            print(colored(
-                f"Error: refusing to archive '{task_name}': "
-                f"it does not resolve to a task under {tasks_dir}",
-                Colors.RED), file=sys.stderr)
-        else:
-            print(colored(f"Error: Task not found: {task_name}", Colors.RED), file=sys.stderr)
-        print("Active tasks:", file=sys.stderr)
-        # Import lazily to avoid circular dependency
-        from .tasks import iter_active_tasks
-        for t in iter_active_tasks(tasks_dir):
-            print(f"  - {t.dir_name}/", file=sys.stderr)
-        return 1
-
-    # Refuse to archive anything that isn't a real task directly under
-    # .trellis/tasks/. resolve_task_dir keeps the target inside the tasks dir;
-    # this narrows it further to a direct child, so an already-archived task
-    # (.trellis/tasks/archive/<month>/<task>) is not archived a second time.
-    if not is_within_tasks_dir(task_dir, repo_root):
-        print(colored(
-            f"Error: refusing to archive '{task_name}': "
-            f"{task_dir} is not a task under {tasks_dir}",
-            Colors.RED), file=sys.stderr)
-        return 1
-
-    # Check the destination before anything below mutates task state. The
-    # mover refuses a collision too, but by then this command has already
-    # marked the task completed, re-parented its children and cleared the
-    # sessions pointing at it — all of which would have to be undone by hand.
-    archive_dest_check = archive_destination_for(task_dir)
-    if archive_dest_check.exists():
-        print(colored(
-            f"Error: refusing to archive '{task_name}': "
-            f"archive destination already exists: "
-            f"{_repo_relative_path(archive_dest_check, repo_root)}",
-            Colors.RED), file=sys.stderr)
-        print(f"Task remains at: {_repo_relative_path(task_dir, repo_root)}", file=sys.stderr)
-        print("Move or rename the existing archived task, then retry.", file=sys.stderr)
-        return 1
-
-    dir_name = task_dir.name
-    task_json_path = task_dir / FILE_TASK_JSON
-
-    # Update status before archiving
-    today = datetime.now().strftime("%Y-%m-%d")
-    # Names of child task dirs whose task.json gets modified below; passed
-    # into safe_archive_paths_to_add so they're staged in this commit.
-    modified_children: list[str] = []
-    if task_json_path.is_file():
-        data, read_reason = read_json_checked(task_json_path)
-        if data is None:
-            # Archiving is still the right outcome for a task whose task.json
-            # is broken — but say so, or the missing "completed" status looks
-            # like the archive silently did half its job.
-            problem, _ = describe_json_read_failure(task_json_path, read_reason)
-            print(
-                colored(
-                    f"Warning: {problem}; archiving without updating status/children.",
-                    Colors.YELLOW,
-                ),
-                file=sys.stderr,
-            )
-        else:
-            # Before any mutation: branch metadata is unrecoverable once the
-            # task leaves the active tree. Stale branches only warn.
-            if not _validate_branch_metadata(
-                data,
-                task_name,
-                repo_root,
-                getattr(args, "skip_branch_validation", False),
-            ):
-                print(
-                    f"Not archived: {_repo_relative_path(task_dir, repo_root)} is unchanged.",
-                    file=sys.stderr,
-                )
-                return 1
-
-            data["status"] = "completed"
-            data["completedAt"] = today
-            if not write_json(task_json_path, data):
-                _report_write_failure(task_json_path)
-                print(
-                    f"Not archived: {_repo_relative_path(task_dir, repo_root)} is unchanged. "
-                    "Archiving a task still marked in progress would hide it from `list` "
-                    "with the wrong status.",
-                    file=sys.stderr,
-                )
-                return 1
-
-            # Handle subtask relationships on archive.
-            # Keep this task in its parent's children list so progress
-            # counters (children_progress) stay consistent — children
-            # missing from the active set are treated as completed.
-            task_children = data.get("children", [])
-
-            # If this is a parent, clear parent field in all children.
-            # Remember each link removed so a later failure in this loop can
-            # put it back (see _restore_child_links). Keyed by the child's
-            # task.json: a `children` list that names the same child twice
-            # would otherwise record a second, already-cleared snapshot and
-            # the restore would write that `null` back over the real parent.
-            unlinked_children: dict[Path, str | None] = {}
-            if task_children:
-                for child_name in task_children:
-                    child_dir_path = find_task_by_name(child_name, tasks_dir)
-                    if child_dir_path:
-                        child_json = child_dir_path / FILE_TASK_JSON
-                        if child_json.is_file():
-                            child_data, child_reason = read_json_checked(child_json)
-                            if child_data is None:
-                                problem, _ = describe_json_read_failure(child_json, child_reason)
-                                print(
-                                    colored(
-                                        f"Warning: {problem}; child '{child_dir_path.name}' "
-                                        "keeps its parent reference.",
-                                        Colors.YELLOW,
-                                    ),
-                                    file=sys.stderr,
-                                )
-                                continue
-                            # Only the first visit to a child records its original
-                            # parent: a `children` list naming the same child twice
-                            # would otherwise snapshot the already-cleared value and
-                            # the restore would write that `null` back over the link.
-                            first_visit = child_json not in unlinked_children
-                            original_parent = child_data.get("parent")
-                            if first_visit:
-                                unlinked_children[child_json] = original_parent
-                            child_data["parent"] = None
-                            if not write_json(child_json, child_data):
-                                # Stop before the move: a child pointing at a
-                                # parent that has left .trellis/tasks/ is a
-                                # dangling reference nothing repairs later.
-                                # Put back the children already unlinked above —
-                                # their parent is staying, so losing the link the
-                                # other way round is just as unrecoverable.
-                                # Retrying is safe — every step so far is
-                                # idempotent.
-                                if first_visit:
-                                    # The link never came off, so there is nothing
-                                    # to put back for this child.
-                                    del unlinked_children[child_json]
-                                _restore_child_links(unlinked_children)
-                                _report_write_failure(child_json)
-                                print(
-                                    f"Not archived: {_repo_relative_path(task_dir, repo_root)} is "
-                                    f"marked completed but stays in place because child "
-                                    f"'{child_dir_path.name}' could not be unlinked. "
-                                    "Fix the child, then run archive again.",
-                                    file=sys.stderr,
-                                )
-                                return 1
-                            modified_children.append(child_dir_path.name)
-
-    # Clear any session that still points at this task before the path moves.
-    from .active_task import clear_task_from_sessions
-    clear_task_from_sessions(str(task_dir), repo_root)
-
-    # Archive
-    result = archive_task_complete(task_dir, repo_root)
-    if "archived_to" in result:
-        archive_dest = Path(result["archived_to"])
-        year_month = archive_dest.parent.name
-        print(colored(f"Archived: {dir_name} -> archive/{year_month}/", Colors.GREEN), file=sys.stderr)
-
-        # Auto-commit unless --no-commit
-        if not getattr(args, "no_commit", False):
-            if not _auto_commit_archive(dir_name, repo_root, modified_children):
-                print(
-                    colored(
-                        "Archive moved on disk, but git auto-commit did not complete. "
-                        "Resolve `git status` before continuing.",
-                        Colors.RED,
-                    ),
-                    file=sys.stderr,
-                )
-                return 1
-
-        # Return the archive path
-        print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}/{year_month}/{dir_name}")
-
-        # Run hooks with the archived path
-        archived_json = archive_dest / FILE_TASK_JSON
-        run_task_hooks("after_archive", archived_json, repo_root)
-        return 0
-
-    return 1
-
-
-def _auto_commit_archive(
-    task_name: str,
-    repo_root: Path,
-    modified_children: list[str] | None = None,
-) -> bool:
-    """Stage Trellis-owned task paths and commit after archive.
-
-    Scoped narrowly to the archived task's source + destination paths
-    plus any child task dirs whose ``task.json`` was edited (parent →
-    children relationship update). Dirty changes in OTHER active task
-    dirs are NOT bundled into the archive commit.
-
-    If ``.gitignore`` blocks the paths, we warn + skip — we do NOT
-    retry with ``git add -f``. The warning explicitly forbids
-    ``git add -f .trellis/`` (which would fan out to caches/backups)
-    and points users at ``session_auto_commit: false``.
-
-    Honors ``session_auto_commit`` in ``.trellis/config.yaml``: when
-    set to ``false``, this function returns immediately without
-    touching git (the archive directory move on disk is unaffected).
-    """
-    if not get_session_auto_commit(repo_root):
-        print(
-            "[OK] session_auto_commit: false — skipping git stage/commit.",
-            file=sys.stderr,
-        )
-        return True
-
-    source_rel = f"{DIR_WORKFLOW}/{DIR_TASKS}/{task_name}"
-    rc, tracked_out, _ = run_git(
-        ["ls-files", "--", source_rel],
-        cwd=repo_root,
-    )
-    source_was_tracked = rc == 0 and bool(tracked_out.strip())
-
-    paths = safe_archive_paths_to_add(
-        repo_root, task_name=task_name, modified_children=modified_children
-    )
-    if not paths:
-        print("[OK] No task changes to commit.", file=sys.stderr)
-        return True
-
-    success, _, err = safe_git_add(paths, repo_root, retry_on_index_lock=True)
-    if not success:
-        if err and "ignored by" in err.lower():
-            print_gitignore_warning(paths)
-        elif stderr_indicates_index_lock(err):
-            _print_index_lock_warning(
-                "git add", task_name, repo_root, [*paths, source_rel]
-            )
-        else:
-            print(
-                f"[WARN] git add failed: {err.strip() if err else 'unknown error'}",
-                file=sys.stderr,
-            )
-        return not source_was_tracked
-
-    # Belt-and-suspenders for the phantom-delete bug: `safe_git_add` uses
-    # `git add` (no -A) which only stages additions/modifications. The
-    # source task directory was moved away by `shutil.move`, so its files
-    # need an explicit `git rm --cached` to stage the deletions in this
-    # same commit — otherwise they sit as uncommitted "phantom deletes"
-    # against HEAD until something later picks them up.
-    #
-    # `--ignore-unmatch` makes this a no-op when the task was never tracked
-    # (e.g. archiving a task that lived only in working tree).
-    rc, _, err = run_git_retry_index_lock(
-        ["rm", "-r", "--cached", "--ignore-unmatch", "--", source_rel],
-        cwd=repo_root,
-    )
-    if rc != 0 and stderr_indicates_index_lock(err):
-        # Committing now would record the archived copy without the
-        # source-side deletes — a half-archived tree in history.
-        _print_index_lock_warning(
-            "git rm --cached", task_name, repo_root, [*paths, source_rel]
-        )
-        return not source_was_tracked
-
-    commit_paths = [*paths, *([source_rel] if source_was_tracked else [])]
-    rc, _, _ = run_git(
-        ["diff", "--cached", "--quiet", "--", *commit_paths],
-        cwd=repo_root,
-    )
-    if rc == 0:
-        print("[OK] No task changes to commit.", file=sys.stderr)
-        return True
-
-    commit_msg = f"chore(task): archive {task_name}"
-    # Commit with an explicit pathspec: a bare `git commit` would sweep any
-    # unrelated entries the developer had staged before archiving into the
-    # chore commit (#579). Include `source_rel` only when it was tracked, so
-    # the source-side deletions land in that commit without passing an absent,
-    # never-tracked path to git.
-    rc, _, err = run_git_retry_index_lock(
-        ["commit", "-m", commit_msg, "--", *commit_paths], cwd=repo_root
-    )
-    if rc == 0:
-        print(f"[OK] Auto-committed: {commit_msg}", file=sys.stderr)
-        return True
-    elif stderr_indicates_index_lock(err):
-        _print_index_lock_warning(
-            "git commit", task_name, repo_root, [*paths, source_rel]
-        )
-        return not source_was_tracked
-    else:
-        print(f"[WARN] Auto-commit failed: {err.strip()}", file=sys.stderr)
-        return not source_was_tracked
-
-
-def _print_index_lock_warning(
-    action: str, task_name: str, repo_root: Path, paths: list[str]
-) -> None:
-    """Report an archive auto-commit that gave up on a held index.lock.
-
-    The move itself already succeeded, so the state is consistent — the task
-    lives in archive/ and its changes are staged-or-not but never half of
-    both in a commit. Only the commit is outstanding, which the user (or an
-    agent reading the log) has to finish by hand.
-
-    ``paths`` are the paths the auto-commit would have staged, so the manual
-    command keeps the same narrow scope — a blanket ``git add -A -- .trellis/``
-    would sweep dirty changes from other active tasks into the archive commit.
-    """
-    lock = index_lock_path(repo_root)
-    print(
-        f"[WARN] {action} gave up after {INDEX_LOCK_RETRY_ATTEMPTS} attempts: "
-        f"another process is holding {lock}",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] The task was moved into archive/ on disk; only the commit is pending.",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] Close whatever holds the lock (an IDE git integration, a status",
-        file=sys.stderr,
-    )
-    print(
-        f"[WARN] daemon, another session), or delete {lock} if it is stale, then",
-        file=sys.stderr,
-    )
-    print(
-        f'[WARN] commit manually: git add -A -- {" ".join(paths)} && '
-        f'git commit -m "chore(task): archive {task_name}"',
-        file=sys.stderr,
-    )
-
-
-# =============================================================================
-# Command: add-subtask
-# =============================================================================
-
 def cmd_add_subtask(args: argparse.Namespace) -> int:
     """Link a child task to a parent task."""
     repo_root = get_repo_root()
@@ -1679,6 +1177,8 @@ def cmd_add_subtask(args: argparse.Namespace) -> int:
     if child_data is None:
         _report_read_failure(child_json_path, child_reason)
         return 1
+    if not _task_mutation_allowed(repo_root, parent_dir, parent_data) or not _task_mutation_allowed(repo_root, child_dir, child_data):
+        return 1
 
     # Check if child already has a parent
     existing_parent = child_data.get("parent")
@@ -1756,6 +1256,20 @@ def cmd_remove_subtask(args: argparse.Namespace) -> int:
     if child_data is None:
         _report_read_failure(child_json_path, child_reason)
         return 1
+    if not _task_mutation_allowed(repo_root, parent_dir, parent_data) or not _task_mutation_allowed(repo_root, child_dir, child_data):
+        return 1
+    if parent_data.get("status") == "completed":
+        print("Error: A completed parent cannot unlink a child after closeout acceptance.", file=sys.stderr)
+        return 1
+    if parent_data.get("status") == "cancelled":
+        workflow = parent_data.get("meta", {}).get("task_workflow", {})
+        phases = workflow.get("phases", {}) if isinstance(workflow, dict) else {}
+        closeout = phases.get("delivery_review_and_closeout", {}) if isinstance(phases, dict) else {}
+        acceptance = closeout.get("acceptance", {}) if isinstance(closeout, dict) else {}
+        choices = acceptance.get("child_dispositions", {}) if isinstance(acceptance, dict) else {}
+        if child_data.get("parent") != parent_dir.name or not isinstance(choices, dict) or choices.get(child_dir.name) != "independent":
+            print("Error: A cancelled parent can unlink only a child recorded as independently continuing in its accepted closeout.", file=sys.stderr)
+            return 1
 
     # Remove child from parent's children list
     parent_children = _ensure_children_list(parent_data)
@@ -1818,6 +1332,8 @@ def cmd_set_branch(args: argparse.Namespace) -> int:
     if data is None:
         _report_read_failure(task_json, reason)
         return 1
+    if not _task_mutation_allowed(repo_root, target_dir, data):
+        return 1
 
     data["branch"] = branch
     if not write_json(task_json, data):
@@ -1863,6 +1379,8 @@ def cmd_set_base_branch(args: argparse.Namespace) -> int:
     if data is None:
         _report_read_failure(task_json, reason)
         return 1
+    if not _task_mutation_allowed(repo_root, target_dir, data):
+        return 1
 
     data["base_branch"] = base_branch
     if not write_json(task_json, data):
@@ -1906,6 +1424,8 @@ def cmd_set_scope(args: argparse.Namespace) -> int:
     if data is None:
         _report_read_failure(task_json, reason)
         return 1
+    if not _task_mutation_allowed(repo_root, target_dir, data):
+        return 1
 
     data["scope"] = scope
     if not write_json(task_json, data):
@@ -1949,6 +1469,8 @@ def cmd_set_meta(args: argparse.Namespace) -> int:
     if data is None:
         _report_read_failure(task_json, reason)
         return 1
+    if not _task_mutation_allowed(repo_root, target_dir, data):
+        return 1
 
     meta = data.get("meta")
     if not isinstance(meta, dict):