@mindfoldhq/trellis 0.6.5 → 0.6.7

package/dist/templates/shared-hooks/inject-workflow-state.py

@@ -53,12 +53,12 @@ if sys.platform.startswith("win"):
             try:
                 _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
             except Exception:
-                pass
+                pass  # Optional Windows stream setup; keep hook startup non-fatal.
         elif hasattr(_stream, "detach"):
             try:
                 setattr(sys, _stream_name, _io.TextIOWrapper(_stream.detach(), encoding="utf-8", errors="replace"))
             except Exception:
-                pass
+                pass  # Optional Windows stream setup; keep hook startup non-fatal.
 from typing import Optional
 
 
@@ -316,12 +316,12 @@ def _load_hook_input() -> dict:
     short daemon read preserves that path while failing closed to `{}` for
     non-piping hosts.
     """
-    result_queue: "queue.Queue[str | BaseException]" = queue.Queue(maxsize=1)
+    result_queue: "queue.Queue[str | Exception]" = queue.Queue(maxsize=1)
 
     def _read() -> None:
         try:
             result_queue.put(sys.stdin.read())
-        except BaseException as exc:
+        except Exception as exc:
             result_queue.put(exc)
 
     reader = threading.Thread(target=_read, daemon=True)
@@ -331,7 +331,7 @@ def _load_hook_input() -> dict:
     except queue.Empty:
         return {}
 
-    if isinstance(raw, BaseException):
+    if isinstance(raw, Exception):
         return {}
     try:
         data = json.loads(raw) if raw.strip() else {}

package/dist/templates/shared-hooks/session-start.py

@@ -87,12 +87,12 @@ if sys.platform.startswith("win"):
             try:
                 _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
             except Exception:
-                pass
+                pass  # Optional Windows stream setup; keep hook startup non-fatal.
         elif hasattr(_stream, "detach"):
             try:
                 setattr(sys, _stream_name, _io.TextIOWrapper(_stream.detach(), encoding="utf-8", errors="replace"))
             except Exception:
-                pass
+                pass  # Optional Windows stream setup; keep hook startup non-fatal.
 
 
 
@@ -249,7 +249,7 @@ def _persist_context_key_for_bash(context_key: str | None) -> None:
         with open(env_file, "a", encoding="utf-8") as handle:
             handle.write(f"export TRELLIS_CONTEXT_ID={shlex.quote(context_key)}\n")
     except OSError:
-        pass
+        pass  # Optional shell bridge; keep session-start non-fatal.
 
 
 def _resolve_active_task(trellis_dir: Path, input_data: dict):
@@ -351,7 +351,7 @@ def _get_task_status(trellis_dir: Path, input_data: dict) -> str:
         try:
             task_data = json.loads(task_json_path.read_text(encoding="utf-8"))
         except (json.JSONDecodeError, PermissionError):
-            pass
+            pass  # Optional task metadata; fall back to generic status.
 
     task_title = task_data.get("title", task_ref)
     task_status = task_data.get("status", "unknown")
@@ -453,7 +453,7 @@ def _load_trellis_config(trellis_dir: Path, input_data: dict) -> tuple:
                         if isinstance(tp, str) and tp:
                             task_pkg = tp
                 except (json.JSONDecodeError, OSError):
-                    pass
+                    pass  # Optional package metadata; fall back to default scope.
 
         default_pkg = get_default_package(repo_root)
         return is_mono, packages, scope, task_pkg, default_pkg
@@ -630,7 +630,7 @@ def _build_compact_current_state(
                 if isinstance(data, dict):
                     status = str(data.get("status") or "unknown")
             except (json.JSONDecodeError, OSError):
-                pass
+                pass  # Optional task metadata; fall back to generic status.
         lines.append(f"Current task: {_repo_relative(repo_root, task_dir)}; status={status}.")
     else:
         lines.append("Current task: none.")
@@ -642,7 +642,7 @@ def _build_compact_current_state(
                 f"Active tasks: {task_count} total. Use `python3 ./.trellis/scripts/task.py list --mine` only if needed."
             )
         except Exception:
-            pass
+            pass  # Optional task summary; keep compact state available.
 
     if get_active_journal_file and count_lines:
         journal = get_active_journal_file(repo_root)

package/dist/templates/trellis/scripts/add_session.py

@@ -14,7 +14,7 @@ Usage:
 
 Branch resolution order:
     1. --branch CLI arg (explicit)
-    2. task.json branch field (from active task)
+    2. task.json branch field (from active task, if still exists)
     3. git branch --show-current (auto-detect)
     4. None (omitted gracefully)
 """
@@ -44,6 +44,7 @@ from common.safe_commit import (
     safe_trellis_paths_to_add,
 )
 from common.tasks import load_task
+from common.types import TaskInfo
 from common.config import (
     get_packages,
     get_session_auto_commit,
@@ -55,6 +56,12 @@ from common.config import (
 )
 
 
+DEFAULT_MAIN_CHANGES = (
+    "- Detailed change bullets were not supplied; see the summary above."
+)
+DEFAULT_TESTING = "- Validation was not recorded for this session."
+
+
 # =============================================================================
 # Helper Functions
 # =============================================================================
@@ -126,6 +133,56 @@ def count_journal_files(dev_dir: Path, active_num: int) -> str:
     return "\n".join(result_lines)
 
 
+def get_current_git_branch(repo_root: Path) -> str | None:
+    """Return the current checkout branch, or None for detached/non-git states."""
+    rc, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+    if rc != 0:
+        return None
+    detected = branch_out.strip()
+    return detected or None
+
+
+def branch_ref_exists(repo_root: Path, branch: str) -> bool:
+    """Return True when branch exists locally or as the local origin ref."""
+    for ref in (f"refs/heads/{branch}", f"refs/remotes/origin/{branch}"):
+        rc, _, _ = run_git(["show-ref", "--verify", "--quiet", ref], cwd=repo_root)
+        if rc == 0:
+            return True
+    return False
+
+
+def resolve_session_branch(
+    repo_root: Path,
+    cli_branch: str | None,
+    task_data: TaskInfo | None,
+) -> str | None:
+    """Resolve journal branch without trusting stale task.json branch fields."""
+    if cli_branch:
+        return cli_branch
+
+    current_branch = get_current_git_branch(repo_root)
+    raw_task_branch = task_data.raw.get("branch") if task_data else None
+    task_branch = raw_task_branch.strip() if isinstance(raw_task_branch, str) else ""
+    if not task_branch:
+        return current_branch
+
+    if branch_ref_exists(repo_root, task_branch):
+        return task_branch
+
+    if current_branch:
+        print(
+            f"Warning: task.json branch '{task_branch}' no longer exists locally or as origin/{task_branch}; using current branch '{current_branch}'.",
+            file=sys.stderr,
+        )
+        return current_branch
+
+    print(
+        f"Warning: task.json branch '{task_branch}' no longer exists locally or as origin/{task_branch}; omitting branch.",
+        file=sys.stderr,
+    )
+    return None
+
+
 def create_new_journal_file(
     dev_dir: Path, num: int, developer: str, today: str, max_lines: int = 2000,
 ) -> Path:
@@ -154,6 +211,7 @@ def generate_session_content(
     today: str,
     package: str | None = None,
     branch: str | None = None,
+    testing_content: str = DEFAULT_TESTING,
 ) -> str:
     """Generate session content."""
     if commit and commit != "-":
@@ -189,7 +247,7 @@ def generate_session_content(
 
 ### Testing
 
-- [OK] (Add test results)
+{testing_content}
 
 ### Status
 
@@ -395,8 +453,8 @@ def _auto_commit_workspace(repo_root: Path) -> None:
 def add_session(
     title: str,
     commit: str = "-",
-    summary: str = "(Add summary)",
-    extra_content: str = "(Add details)",
+    summary: str = "Session summary was not supplied.",
+    extra_content: str = DEFAULT_MAIN_CHANGES,
     auto_commit: bool = True,
     package: str | None = None,
     branch: str | None = None,
@@ -503,7 +561,7 @@ def main() -> int:
     )
     parser.add_argument("--title", required=True, help="Session title")
     parser.add_argument("--commit", default="-", help="Comma-separated commit hashes")
-    parser.add_argument("--summary", default="(Add summary)", help="Brief summary")
+    parser.add_argument("--summary", default="Session summary was not supplied.", help="Brief summary")
     parser.add_argument("--content-file", help="Path to file with detailed content")
     parser.add_argument("--package", help="Package name tag (e.g., cli, docs-site)")
     parser.add_argument("--branch", help="Branch name (auto-detected if omitted)")
@@ -514,7 +572,7 @@ def main() -> int:
 
     args = parser.parse_args()
 
-    extra_content = "(Add details)"
+    extra_content = DEFAULT_MAIN_CHANGES
     if args.content_file:
         content_path = Path(args.content_file)
         if content_path.is_file():
@@ -543,17 +601,7 @@ def main() -> int:
         task_package = task_data.package if task_data else None
         package = resolve_package(task_package, repo_root)
 
-    # Resolve branch: CLI → task.json → git auto-detect → None
-    branch = args.branch
-
-    if not branch:
-        if task_data and task_data.raw.get("branch"):
-            branch = task_data.raw["branch"]
-        else:
-            _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
-            detected = branch_out.strip()
-            if detected:
-                branch = detected
+    branch = resolve_session_branch(repo_root, args.branch, task_data)
 
     return add_session(
         args.title, args.commit, args.summary, extra_content,

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

@@ -55,6 +55,7 @@ Platform = Literal[
     "droid",
     "pi",
     "trae",
+    "omp",
 ]
 
 
@@ -131,6 +132,8 @@ class CLIAdapter:
             return ".pi"
         elif self.platform == "trae":
             return ".trae"
+        elif self.platform == "omp":
+            return ".omp"
         else:
             return ".claude"
 
@@ -188,6 +191,17 @@ class CLIAdapter:
                     filename = filename[:-3]
                 return prompts_dir / f"trellis-{filename}.md"
             return prompts_dir / Path(*parts)
+        if self.platform == "omp":
+            commands_dir = self.get_config_dir(project_root) / "commands"
+            if not parts:
+                return commands_dir
+            if len(parts) >= 2 and parts[0] == "trellis":
+                filename = parts[-1]
+                if filename.endswith(".md"):
+                    filename = filename[:-3]
+                return commands_dir / f"trellis-{filename}.md"
+            return commands_dir / Path(*parts)
+
 
         if self.platform == "devin":
             workflow_dir = self.get_config_dir(project_root) / "workflows"
@@ -272,6 +286,8 @@ class CLIAdapter:
             return f".factory/commands/trellis/{name}.md"
         elif self.platform == "pi":
             return f".pi/prompts/trellis-{name}.md"
+        elif self.platform == "omp":
+            return f".omp/commands/trellis-{name}.md"
         else:
             return f"{self.config_dir_name}/commands/trellis/{name}.md"
 
@@ -311,6 +327,8 @@ class CLIAdapter:
             return {}
         elif self.platform == "trae":
             return {}
+        elif self.platform == "omp":
+            return {}
         else:
             return {"CLAUDE_NON_INTERACTIVE": "1"}
 
@@ -400,6 +418,10 @@ class CLIAdapter:
             raise ValueError(
                 "Trae is IDE-only; CLI agent run is not supported."
             )
+        elif self.platform == "omp":
+            raise ValueError(
+                "OMP uses native task tool for agent runs; CLI agent run is not supported."
+            )
 
         else:  # claude
             cmd = ["claude", "-p"]
@@ -470,6 +492,10 @@ class CLIAdapter:
             raise ValueError(
                 "Trae is IDE-only; CLI resume is not supported."
             )
+        elif self.platform == "omp":
+            raise ValueError(
+                "OMP uses native task tool for agent runs; CLI resume is not supported."
+            )
         else:
             return ["claude", "--resume", session_id]
 
@@ -546,6 +572,8 @@ class CLIAdapter:
             return "pi"
         elif self.platform == "trae":
             return "trae"
+        elif self.platform == "omp":
+            return "omp"
         else:
             return "claude"
 
@@ -642,9 +670,10 @@ def get_cli_adapter(platform: str = "claude") -> CLIAdapter:
         "droid",
         "pi",
         "trae",
+        "omp",
     ):
         raise ValueError(
-            f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'devin', 'qoder', 'codebuddy', 'copilot', 'droid', 'pi', or 'trae')"
+            f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'devin', 'qoder', 'codebuddy', 'copilot', 'droid', 'pi', 'trae', or 'omp')"
         )
 
     return CLIAdapter(platform=platform)  # type: ignore
@@ -668,6 +697,7 @@ _ALL_PLATFORM_CONFIG_DIRS = (
     ".factory",
     ".pi",
     ".trae",
+    ".omp",
 )
 """Platform-specific config directory names used by detect_platform exclusion
 checks. `.agents/skills/` is NOT listed here: it is a shared cross-platform
@@ -737,6 +767,7 @@ def detect_platform(project_root: Path) -> Platform:
         "droid",
         "pi",
         "trae",
+        "omp",
     ):
         return env_platform  # type: ignore
 
@@ -817,6 +848,10 @@ def detect_platform(project_root: Path) -> Platform:
     if (project_root / ".trae").is_dir():
         return "trae"
 
+    # Check for .omp directory (OMP-specific)
+    if (project_root / ".omp").is_dir():
+        return "omp"
+
     # Fallback: checkout only has the Codex shared-skills layer
     # (.agents/skills/trellis-* dirs) and no explicit platform config dir.
     # Happens on fresh clones where .codex/ is gitignored/absent but the

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

@@ -167,6 +167,7 @@ def _next_content_line(lines: list[str], start: int) -> tuple[int, str]:
 DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
 DEFAULT_MAX_JOURNAL_LINES = 2000
 DEFAULT_SESSION_AUTO_COMMIT = True
+DEFAULT_CODEX_DISPATCH_MODE = "inline"
 
 CONFIG_FILE = "config.yaml"
 
@@ -243,6 +244,34 @@ def get_session_auto_commit(repo_root: Path | None = None) -> bool:
     return DEFAULT_SESSION_AUTO_COMMIT
 
 
+def get_codex_dispatch_mode(repo_root: Path | None = None) -> str:
+    """Return Codex dispatch mode.
+
+    Default is ``inline``. ``sub-agent`` is an explicit opt-in because Codex
+    sub-agents do not inherit the parent session context.
+    """
+    config = _load_config(repo_root)
+    codex = config.get("codex")
+    if codex is None:
+        return DEFAULT_CODEX_DISPATCH_MODE
+    if not isinstance(codex, dict):
+        print(
+            f"[WARN] invalid codex config: {codex!r}; using {DEFAULT_CODEX_DISPATCH_MODE}",
+            file=sys.stderr,
+        )
+        return DEFAULT_CODEX_DISPATCH_MODE
+
+    raw = codex.get("dispatch_mode", DEFAULT_CODEX_DISPATCH_MODE)
+    mode = str(raw).strip().lower()
+    if mode in ("inline", "sub-agent"):
+        return mode
+    print(
+        f"[WARN] invalid codex.dispatch_mode value: {raw!r}; using {DEFAULT_CODEX_DISPATCH_MODE}",
+        file=sys.stderr,
+    )
+    return DEFAULT_CODEX_DISPATCH_MODE
+
+
 def get_hooks(event: str, repo_root: Path | None = None) -> list[str]:
     """Get hook commands for a lifecycle event.
 

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

@@ -8,6 +8,8 @@ for JSON file operations across all Trellis scripts.
 from __future__ import annotations
 
 import json
+import os
+import tempfile
 from pathlib import Path
 
 
@@ -25,13 +27,28 @@ def read_json(path: Path) -> dict | None:
 def write_json(path: Path, data: dict) -> bool:
     """Write dict to JSON file with pretty formatting.
 
+    The write is atomic: content goes to a temp file in the same directory
+    and is then renamed over the target. A crash or Ctrl-C mid-write leaves
+    the existing file intact rather than truncated, so a corrupted task.json
+    can never make a task silently vanish from `task.py list`.
+
     Returns True on success, False on error.
     """
+    payload = json.dumps(data, indent=2, ensure_ascii=False)
     try:
-        path.write_text(
-            json.dumps(data, indent=2, ensure_ascii=False),
-            encoding="utf-8",
+        fd, tmp = tempfile.mkstemp(
+            dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
         )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(payload)
+            os.replace(tmp, path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
         return True
     except (OSError, IOError):
         return False

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

@@ -412,7 +412,7 @@ def _get_update_hint(repo_root: Path) -> str | None:
 
     return (
         f"Trellis update available: {current_version} -> {latest_version}, "
-        "run trellis upgrade"
+        "run trellis update"
     )
 
 

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

@@ -23,6 +23,7 @@ from datetime import datetime
 from pathlib import Path
 
 from .config import (
+    get_codex_dispatch_mode,
     get_packages,
     get_session_auto_commit,
     is_monorepo,
@@ -50,6 +51,7 @@ from .safe_commit import (
 from .task_utils import (
     archive_task_complete,
     find_task_by_name,
+    is_within_tasks_dir,
     resolve_task_dir,
     run_task_hooks,
 )
@@ -113,13 +115,13 @@ def _repo_relative_path(path: Path, repo_root: Path) -> str:
 
 # Config directories of platforms that consume implement.jsonl / check.jsonl.
 # Keep in sync with src/types/ai-tools.ts AI_TOOLS entries — these are the
-# platforms listed in workflow.md's "agent-capable" Skill Routing block
-# (Class-1 hook-inject + Class-2 pull-based preludes). Kilo / Antigravity /
-# Devin are NOT in this list: they do not consume JSONL.
+# platforms listed in workflow.md's "agent-capable" Skill Routing block.
+# Codex is checked separately because default inline mode does not consume
+# JSONL. Kilo / Antigravity / Devin are NOT in this list either: they load
+# specs through skills instead of JSONL.
 _SUBAGENT_CONFIG_DIRS: tuple[str, ...] = (
     ".claude",
     ".cursor",
-    ".codex",
     ".kiro",
     ".gemini",
     ".opencode",
@@ -129,7 +131,10 @@ _SUBAGENT_CONFIG_DIRS: tuple[str, ...] = (
     ".github/copilot",
     ".pi",        # Pi Agent
     ".trae",      # Trae IDE
+    ".omp",       # Oh My Pi
+    ".zcode",     # ZCode
 )
+_CODEX_CONFIG_DIR = ".codex"
 
 _SEED_EXAMPLE = (
     "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. "
@@ -142,13 +147,15 @@ _SEED_EXAMPLE = (
 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. Used
-    only to decide whether ``task.py create`` should seed empty
-    ``implement.jsonl`` / ``check.jsonl`` files.
+    Detected by probing well-known config directories at the repo root. Codex
+    only counts when ``codex.dispatch_mode`` explicitly opts into
+    ``sub-agent``; inline mode loads context through skills, not JSONL.
     """
     for config_dir in _SUBAGENT_CONFIG_DIRS:
         if (repo_root / config_dir).is_dir():
             return True
+    if (repo_root / _CODEX_CONFIG_DIR).is_dir():
+        return get_codex_dispatch_mode(repo_root) == "sub-agent"
     return False
 
 
@@ -240,6 +247,34 @@ def cmd_create(args: argparse.Namespace) -> int:
     # Create task directory with MM-DD-slug format
     tasks_dir = get_tasks_dir(repo_root)
     date_prefix = generate_task_date_prefix()
+
+    # Guard against date-prefixed --slug (e.g. a full task dir name pasted in),
+    # which would otherwise produce MM-DD-MM-DD-slug (issue #377). Only an
+    # explicit --slug is guarded; title-derived slugs are left untouched.
+    if args.slug:
+        m = re.match(r"^(\d{2})-(\d{2})-(.+)$", slug)
+        if m and 1 <= int(m.group(1)) <= 12 and 1 <= int(m.group(2)) <= 31:
+            slug_prefix = f"{m.group(1)}-{m.group(2)}"
+            if slug_prefix == date_prefix:
+                slug = m.group(3)
+                print(
+                    colored(
+                        f'warning: --slug should not include the MM-DD prefix; normalized to "{slug}"',
+                        Colors.YELLOW,
+                    ),
+                    file=sys.stderr,
+                )
+            else:
+                print(
+                    colored(
+                        f"Error: --slug starts with a date prefix ({slug_prefix}-), but task.py create always uses today's date ({date_prefix}).",
+                        Colors.RED,
+                    ),
+                    file=sys.stderr,
+                )
+                print(f"Pass only the slug body, e.g. --slug {m.group(3)}", file=sys.stderr)
+                return 1
+
     dir_name = f"{date_prefix}-{slug}"
     task_dir = tasks_dir / dir_name
     task_json_path = task_dir / FILE_TASK_JSON
@@ -262,11 +297,21 @@ def cmd_create(args: argparse.Namespace) -> int:
     _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
     current_branch = branch_out.strip() or "main"
 
+    description = (args.description or "").strip()
+    if not description.strip():
+        print(
+            colored(
+                "warning: task description is empty; pass --description to improve search and later audits.",
+                Colors.YELLOW,
+            ),
+            file=sys.stderr,
+        )
+
     task_data = {
         "id": slug,
         "name": slug,
         "title": args.title,
-        "description": args.description or "",
+        "description": description,
         "status": "planning",
         "dev_type": None,
         "scope": None,
@@ -294,7 +339,7 @@ def cmd_create(args: argparse.Namespace) -> int:
     prd_path = task_dir / "prd.md"
     if not prd_path.exists():
         prd_path.write_text(
-            _default_prd_content(args.title, args.description),
+            _default_prd_content(args.title, description),
             encoding="utf-8",
         )
 
@@ -337,16 +382,31 @@ def cmd_create(args: argparse.Namespace) -> int:
     # outside an AI session) — the task is still created, the user can run
     # task.py start later. Pointer is session-scoped so this never affects
     # other AI sessions.
-    try:
-        from .active_task import resolve_context_key, set_active_task
-        if resolve_context_key():
-            try:
-                rel_dir = task_dir.relative_to(repo_root).as_posix()
-            except ValueError:
-                rel_dir = str(task_dir)
-            set_active_task(rel_dir, repo_root)
-    except Exception:
-        pass
+    if getattr(args, "no_start", False):
+        print(
+            colored(
+                "Skipped session activation (--no-start); run task.py start when ready.",
+                Colors.YELLOW,
+            ),
+            file=sys.stderr,
+        )
+    else:
+        try:
+            from .active_task import resolve_context_key, set_active_task
+            if resolve_context_key():
+                try:
+                    rel_dir = task_dir.relative_to(repo_root).as_posix()
+                except ValueError:
+                    rel_dir = str(task_dir)
+                active = set_active_task(rel_dir, repo_root)
+                if active:
+                    print(
+                        colored(f"Activated task for this session: {active.task_path}", Colors.GREEN),
+                        file=sys.stderr,
+                    )
+                    print(f"Source: {active.source}", file=sys.stderr)
+        except Exception:
+            pass
 
     print(colored(f"Created task: {dir_name}", Colors.GREEN), file=sys.stderr)
     print("", file=sys.stderr)
@@ -396,6 +456,17 @@ def cmd_archive(args: argparse.Namespace) -> int:
             print(f"  - {t.dir_name}/", file=sys.stderr)
         return 1
 
+    # Refuse to archive anything that isn't a real task directly under
+    # .trellis/tasks/. A mistyped name (e.g. "src") resolves to repo_root/src,
+    # which is a dir but not a task — without this guard archive would move the
+    # user's source directory out of the repo.
+    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
+
     dir_name = task_dir.name
     task_json_path = task_dir / FILE_TASK_JSON
 

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

@@ -69,6 +69,28 @@ def is_safe_task_path(task_path: str, repo_root: Path | None = None) -> bool:
     return True
 
 
+def is_within_tasks_dir(task_dir_abs: Path, repo_root: Path | None = None) -> bool:
+    """Check that a resolved task directory really is a task under the tasks dir.
+
+    A real task lives directly at ``.trellis/tasks/<name>``. This returns True
+    only when ``task_dir_abs`` is an immediate child of the tasks directory.
+
+    Guards archive: ``resolve_task_dir`` falls back to ``repo_root/<name>`` for
+    an unknown name, so a mistyped ``task.py archive src`` resolves to the real
+    ``src/`` source directory. Without this check archive would ``shutil.move``
+    it out of the repo. Also rejects the tasks dir itself and anything nested
+    under ``archive/`` (already-archived tasks).
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    try:
+        resolved = task_dir_abs.resolve()
+        tasks_resolved = get_tasks_dir(repo_root).resolve()
+    except (OSError, RuntimeError):
+        return False
+    return resolved.parent == tasks_resolved
+
+
 # =============================================================================
 # Task Lookup
 # =============================================================================