@jahanxu/trellis 0.4.2 → 0.5.1

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

@@ -10,10 +10,11 @@ Provides:
     get_active_journal_file - Get current journal file
 """
 
+from __future__ import annotations
+
 import re
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
 
 
 # =============================================================================
@@ -27,19 +28,23 @@ DIR_TASKS = "tasks"
 DIR_ARCHIVE = "archive"
 DIR_SPEC = "spec"
 DIR_SCRIPTS = "scripts"
+DIR_POOL = "pool"
+DIR_DELIVERABLES = "deliverables"
 
 # File names
 FILE_DEVELOPER = ".developer"
 FILE_CURRENT_TASK = ".current-task"
 FILE_TASK_JSON = "task.json"
 FILE_JOURNAL_PREFIX = "journal-"
+FILE_SOURCE_JSON = "source.json"
+FILE_HANDOFF_MD = "HANDOFF.md"
 
 
 # =============================================================================
 # Repository Root
 # =============================================================================
 
-def get_repo_root(start_path: Optional[Path] = None) -> Path:
+def get_repo_root(start_path: Path | None = None) -> Path:
     """Find the nearest directory containing .trellis/ folder.
 
     This handles nested git repos correctly (e.g., test project inside another repo).
@@ -65,7 +70,7 @@ def get_repo_root(start_path: Optional[Path] = None) -> Path:
 # Developer
 # =============================================================================
 
-def get_developer(repo_root: Optional[Path] = None) -> Optional[str]:
+def get_developer(repo_root: Path | None = None) -> str | None:
     """Get developer name from .developer file.
 
     Args:
@@ -93,7 +98,7 @@ def get_developer(repo_root: Optional[Path] = None) -> Optional[str]:
     return None
 
 
-def check_developer(repo_root: Optional[Path] = None) -> bool:
+def check_developer(repo_root: Path | None = None) -> bool:
     """Check if developer is initialized.
 
     Args:
@@ -109,7 +114,7 @@ def check_developer(repo_root: Optional[Path] = None) -> bool:
 # Tasks Directory
 # =============================================================================
 
-def get_tasks_dir(repo_root: Optional[Path] = None) -> Path:
+def get_tasks_dir(repo_root: Path | None = None) -> Path:
     """Get tasks directory path.
 
     Args:
@@ -127,7 +132,7 @@ def get_tasks_dir(repo_root: Optional[Path] = None) -> Path:
 # Workspace Directory
 # =============================================================================
 
-def get_workspace_dir(repo_root: Optional[Path] = None) -> Optional[Path]:
+def get_workspace_dir(repo_root: Path | None = None) -> Path | None:
     """Get developer workspace directory.
 
     Args:
@@ -149,7 +154,7 @@ def get_workspace_dir(repo_root: Optional[Path] = None) -> Optional[Path]:
 # Journal File
 # =============================================================================
 
-def get_active_journal_file(repo_root: Optional[Path] = None) -> Optional[Path]:
+def get_active_journal_file(repo_root: Path | None = None) -> Path | None:
     """Get the current active journal file.
 
     Args:
@@ -165,7 +170,7 @@ def get_active_journal_file(repo_root: Optional[Path] = None) -> Optional[Path]:
     if workspace_dir is None or not workspace_dir.is_dir():
         return None
 
-    latest: Optional[Path] = None
+    latest: Path | None = None
     highest = 0
 
     for f in workspace_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md"):
@@ -206,7 +211,7 @@ def count_lines(file_path: Path) -> int:
 # Current Task Management
 # =============================================================================
 
-def _get_current_task_file(repo_root: Optional[Path] = None) -> Path:
+def _get_current_task_file(repo_root: Path | None = None) -> Path:
     """Get .current-task file path.
 
     Args:
@@ -220,7 +225,7 @@ def _get_current_task_file(repo_root: Optional[Path] = None) -> Path:
     return repo_root / DIR_WORKFLOW / FILE_CURRENT_TASK
 
 
-def get_current_task(repo_root: Optional[Path] = None) -> Optional[str]:
+def get_current_task(repo_root: Path | None = None) -> str | None:
     """Get current task directory path (relative to repo_root).
 
     Args:
@@ -240,7 +245,7 @@ def get_current_task(repo_root: Optional[Path] = None) -> Optional[str]:
         return None
 
 
-def get_current_task_abs(repo_root: Optional[Path] = None) -> Optional[Path]:
+def get_current_task_abs(repo_root: Path | None = None) -> Path | None:
     """Get current task directory absolute path.
 
     Args:
@@ -258,7 +263,7 @@ def get_current_task_abs(repo_root: Optional[Path] = None) -> Optional[Path]:
     return None
 
 
-def set_current_task(task_path: str, repo_root: Optional[Path] = None) -> bool:
+def set_current_task(task_path: str, repo_root: Path | None = None) -> bool:
     """Set current task.
 
     Args:
@@ -288,7 +293,7 @@ def set_current_task(task_path: str, repo_root: Optional[Path] = None) -> bool:
         return False
 
 
-def clear_current_task(repo_root: Optional[Path] = None) -> bool:
+def clear_current_task(repo_root: Path | None = None) -> bool:
     """Clear current task.
 
     Args:
@@ -307,7 +312,7 @@ def clear_current_task(repo_root: Optional[Path] = None) -> bool:
         return False
 
 
-def has_current_task(repo_root: Optional[Path] = None) -> bool:
+def has_current_task(repo_root: Path | None = None) -> bool:
     """Check if has current task.
 
     Args:
@@ -319,6 +324,51 @@ def has_current_task(repo_root: Optional[Path] = None) -> bool:
     return get_current_task(repo_root) is not None
 
 
+# =============================================================================
+# Pool Directory
+# =============================================================================
+
+def get_pool_dir(repo_root: Path | None = None) -> Path:
+    """Get pool directory path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to pool directory.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return repo_root / DIR_WORKFLOW / DIR_POOL
+
+
+def get_pool_file(pool_name: str, repo_root: Path | None = None) -> Path:
+    """Get pool JSON file path.
+
+    Args:
+        pool_name: Pool name (e.g., 'requirements').
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to pool JSON file.
+    """
+    return get_pool_dir(repo_root) / f"{pool_name}.json"
+
+
+def get_deliverables_dir(repo_root: Path | None = None) -> Path:
+    """Get deliverables directory path (at project root).
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to deliverables directory.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return repo_root / DIR_DELIVERABLES
+
+
 # =============================================================================
 # Task ID Generation
 # =============================================================================

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

@@ -17,13 +17,13 @@ Provides:
     is_current_action     - Check if at specific action
 """
 
+from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Optional
 
 
-def _read_json_file(path: Path) -> Optional[dict]:
+def _read_json_file(path: Path) -> dict | None:
     """Read and parse a JSON file."""
     try:
         return json.loads(path.read_text(encoding="utf-8"))

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

@@ -14,17 +14,17 @@ Provides:
     registry_list_agents     - List all agents
 """
 
+from __future__ import annotations
 
 import json
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
 
 from .paths import get_repo_root
 from .worktree import get_agents_dir
 
 
-def _read_json_file(path: Path) -> Optional[dict]:
+def _read_json_file(path: Path) -> dict | None:
     """Read and parse a JSON file."""
     try:
         return json.loads(path.read_text(encoding="utf-8"))
@@ -45,7 +45,7 @@ def _write_json_file(path: Path, data: dict) -> bool:
 # Registry File Access
 # =============================================================================
 
-def registry_get_file(repo_root: Optional[Path] = None) -> Optional[Path]:
+def registry_get_file(repo_root: Path | None = None) -> Path | None:
     """Get registry file path.
 
     Args:
@@ -63,7 +63,7 @@ def registry_get_file(repo_root: Optional[Path] = None) -> Optional[Path]:
     return None
 
 
-def _ensure_registry(repo_root: Optional[Path] = None) -> Optional[Path]:
+def _ensure_registry(repo_root: Path | None = None) -> Path | None:
     """Ensure registry file exists with valid structure.
 
     Args:
@@ -98,8 +98,8 @@ def _ensure_registry(repo_root: Optional[Path] = None) -> Optional[Path]:
 
 def registry_get_agent_by_id(
     agent_id: str,
-    repo_root: Optional[Path] = None
-) -> Optional[dict]:
+    repo_root: Path | None = None
+) -> dict | None:
     """Get agent by ID.
 
     Args:
@@ -129,8 +129,8 @@ def registry_get_agent_by_id(
 
 def registry_get_agent_by_worktree(
     worktree_path: str,
-    repo_root: Optional[Path] = None
-) -> Optional[dict]:
+    repo_root: Path | None = None
+) -> dict | None:
     """Get agent by worktree path.
 
     Args:
@@ -160,8 +160,8 @@ def registry_get_agent_by_worktree(
 
 def registry_search_agent(
     search: str,
-    repo_root: Optional[Path] = None
-) -> Optional[dict]:
+    repo_root: Path | None = None
+) -> dict | None:
     """Search agent by ID or task_dir containing search term.
 
     Args:
@@ -196,8 +196,8 @@ def registry_search_agent(
 
 def registry_get_task_dir(
     worktree_path: str,
-    repo_root: Optional[Path] = None
-) -> Optional[str]:
+    repo_root: Path | None = None
+) -> str | None:
     """Get task directory for a worktree.
 
     Args:
@@ -217,7 +217,7 @@ def registry_get_task_dir(
 # Agent Modification
 # =============================================================================
 
-def registry_remove_by_id(agent_id: str, repo_root: Optional[Path] = None) -> bool:
+def registry_remove_by_id(agent_id: str, repo_root: Path | None = None) -> bool:
     """Remove agent by ID.
 
     Args:
@@ -246,7 +246,7 @@ def registry_remove_by_id(agent_id: str, repo_root: Optional[Path] = None) -> bo
 
 def registry_remove_by_worktree(
     worktree_path: str,
-    repo_root: Optional[Path] = None
+    repo_root: Path | None = None
 ) -> bool:
     """Remove agent by worktree path.
 
@@ -279,7 +279,7 @@ def registry_add_agent(
     worktree_path: str,
     pid: int,
     task_dir: str,
-    repo_root: Optional[Path] = None,
+    repo_root: Path | None = None,
     platform: str = "claude",
 ) -> bool:
     """Add agent to registry (replaces if same ID exists).
@@ -327,7 +327,7 @@ def registry_add_agent(
     return _write_json_file(registry_file, data)
 
 
-def registry_list_agents(repo_root: Optional[Path] = None) -> list[dict]:
+def registry_list_agents(repo_root: Path | None = None) -> list[dict]:
     """List all agents.
 
     Args:

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

@@ -10,10 +10,10 @@ Provides:
     get_task_stats         - Get P0/P1/P2/P3 counts
 """
 
+from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Optional, List
 
 from .paths import (
     FILE_TASK_JSON,
@@ -23,7 +23,7 @@ from .paths import (
 )
 
 
-def _read_json_file(path: Path) -> Optional[dict]:
+def _read_json_file(path: Path) -> dict | None:
     """Read and parse a JSON file."""
     try:
         return json.loads(path.read_text(encoding="utf-8"))
@@ -36,8 +36,8 @@ def _read_json_file(path: Path) -> Optional[dict]:
 # =============================================================================
 
 def list_tasks_by_status(
-    filter_status: Optional[str] = None,
-    repo_root: Optional[Path] = None
+    filter_status: str | None = None,
+    repo_root: Path | None = None
 ) -> list[dict]:
     """List tasks by status.
 
@@ -91,7 +91,7 @@ def list_tasks_by_status(
     return results
 
 
-def list_pending_tasks(repo_root: Optional[Path] = None) -> list[dict]:
+def list_pending_tasks(repo_root: Path | None = None) -> list[dict]:
     """List pending tasks.
 
     Args:
@@ -105,8 +105,8 @@ def list_pending_tasks(repo_root: Optional[Path] = None) -> list[dict]:
 
 def list_tasks_by_assignee(
     assignee: str,
-    filter_status: Optional[str] = None,
-    repo_root: Optional[Path] = None
+    filter_status: str | None = None,
+    repo_root: Path | None = None
 ) -> list[dict]:
     """List tasks assigned to a specific developer.
 
@@ -167,8 +167,8 @@ def list_tasks_by_assignee(
 
 
 def list_my_tasks(
-    filter_status: Optional[str] = None,
-    repo_root: Optional[Path] = None
+    filter_status: str | None = None,
+    repo_root: Path | None = None
 ) -> list[dict]:
     """List tasks assigned to current developer.
 
@@ -192,7 +192,7 @@ def list_my_tasks(
     return list_tasks_by_assignee(developer, filter_status, repo_root)
 
 
-def get_task_stats(repo_root: Optional[Path] = None) -> dict[str, int]:
+def get_task_stats(repo_root: Path | None = None) -> dict[str, int]:
     """Get task statistics.
 
     Args:

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

@@ -8,12 +8,12 @@ Provides:
     archive_task_dir   - Archive task to monthly directory
 """
 
+from __future__ import annotations
 
 import shutil
 import sys
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
 
 from .paths import get_repo_root
 
@@ -22,7 +22,7 @@ from .paths import get_repo_root
 # Path Safety
 # =============================================================================
 
-def is_safe_task_path(task_path: str, repo_root: Optional[Path] = None) -> bool:
+def is_safe_task_path(task_path: str, repo_root: Path | None = None) -> bool:
     """Check if a relative task path is safe to operate on.
 
     Args:
@@ -69,7 +69,7 @@ def is_safe_task_path(task_path: str, repo_root: Optional[Path] = None) -> bool:
 # Task Lookup
 # =============================================================================
 
-def find_task_by_name(task_name: str, tasks_dir: Path) -> Optional[Path]:
+def find_task_by_name(task_name: str, tasks_dir: Path) -> Path | None:
     """Find task directory by name (exact or suffix match).
 
     Args:
@@ -99,7 +99,7 @@ def find_task_by_name(task_name: str, tasks_dir: Path) -> Optional[Path]:
 # Archive Operations
 # =============================================================================
 
-def archive_task_dir(task_dir_abs: Path, repo_root: Optional[Path] = None) -> Optional[Path]:
+def archive_task_dir(task_dir_abs: Path, repo_root: Path | None = None) -> Path | None:
     """Archive a task directory to archive/{YYYY-MM}/.
 
     Args:
@@ -141,7 +141,7 @@ def archive_task_dir(task_dir_abs: Path, repo_root: Optional[Path] = None) -> Op
 
 def archive_task_complete(
     task_dir_abs: Path,
-    repo_root: Optional[Path] = None
+    repo_root: Path | None = None
 ) -> dict[str, str]:
     """Complete archive workflow: archive directory.
 

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

@@ -10,9 +10,9 @@ Provides:
     get_agents_dir              - Get agents registry directory
 """
 
+from __future__ import annotations
 
 from pathlib import Path
-from typing import Optional
 
 from .paths import (
     DIR_WORKFLOW,
@@ -35,7 +35,7 @@ def parse_simple_yaml(content: str) -> dict:
         Parsed dict.
     """
     result: dict = {}
-    current_list: Optional[list] = None
+    current_list: list | None = None
 
     for line in content.splitlines():
         stripped = line.strip()
@@ -61,7 +61,7 @@ def parse_simple_yaml(content: str) -> dict:
     return result
 
 
-def _yaml_get_value(config_file: Path, key: str) -> Optional[str]:
+def _yaml_get_value(config_file: Path, key: str) -> str | None:
     """Read simple value from worktree.yaml.
 
     Args:
@@ -111,7 +111,7 @@ def _yaml_get_list(config_file: Path, section: str) -> list[str]:
 WORKTREE_CONFIG_PATH = f"{DIR_WORKFLOW}/worktree.yaml"
 
 
-def get_worktree_config(repo_root: Optional[Path] = None) -> Path:
+def get_worktree_config(repo_root: Path | None = None) -> Path:
     """Get worktree.yaml config file path.
 
     Args:
@@ -125,7 +125,7 @@ def get_worktree_config(repo_root: Optional[Path] = None) -> Path:
     return repo_root / WORKTREE_CONFIG_PATH
 
 
-def get_worktree_base_dir(repo_root: Optional[Path] = None) -> Path:
+def get_worktree_base_dir(repo_root: Path | None = None) -> Path:
     """Get worktree base directory.
 
     Args:
@@ -153,7 +153,7 @@ def get_worktree_base_dir(repo_root: Optional[Path] = None) -> Path:
         return Path(worktree_dir)
 
 
-def get_worktree_copy_files(repo_root: Optional[Path] = None) -> list[str]:
+def get_worktree_copy_files(repo_root: Path | None = None) -> list[str]:
     """Get files to copy list.
 
     Args:
@@ -168,7 +168,7 @@ def get_worktree_copy_files(repo_root: Optional[Path] = None) -> list[str]:
     return _yaml_get_list(config, "copy")
 
 
-def get_worktree_post_create_hooks(repo_root: Optional[Path] = None) -> list[str]:
+def get_worktree_post_create_hooks(repo_root: Path | None = None) -> list[str]:
     """Get post_create hooks.
 
     Args:
@@ -187,7 +187,7 @@ def get_worktree_post_create_hooks(repo_root: Optional[Path] = None) -> list[str
 # Agents Registry
 # =============================================================================
 
-def get_agents_dir(repo_root: Optional[Path] = None) -> Optional[Path]:
+def get_agents_dir(repo_root: Path | None = None) -> Path | None:
     """Get agents directory for current developer.
 
     Args: