tasktree-manager 2.15.0__tar.gz → 2.16.1__tar.gz

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/.github/workflows/ci.yml

@@ -31,12 +31,18 @@ jobs:
         run: ruff format --check tasktree_manager tests
 
   test:
-    name: Test (Python ${{ matrix.python-version }})
-    runs-on: ubuntu-latest
+    # Linux jobs keep the names branch protection requires
+    name: ${{ matrix.os == 'macos-latest' && format('Test (macOS, Python {0})', matrix.python-version) || format('Test (Python {0})', matrix.python-version) }}
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
+        os: [ubuntu-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          # Case-insensitive APFS: runs the case-variant epic tests Linux skips
+          - os: macos-latest
+            python-version: "3.13"
 
     steps:
       - name: Checkout code

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/CHANGELOG.md

@@ -15,6 +15,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Git hooks support
 - Custom task metadata
 
+## [2.16.1] - 2026-10-19
+
+### Fixed
+- **epic**: One membership rule and safer marker writes (#12)
+
+
+## [2.16.0] - 2026-10-19
+
+### Added
+- **epic**: Add a managed epic block to task CLAUDE.md files
+
+
 ## [2.15.0] - 2026-10-19
 
 ### Added

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tasktree-manager
-Version: 2.15.0
+Version: 2.16.1
 Summary: TUI application for managing worktree-based tasks
 License-File: LICENSE
 Requires-Python: >=3.10

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/README.md

@@ -102,7 +102,9 @@ tasktree-manager epic mark DIC-2466-pcaps-epic                # turn an existing
 tasktree-manager epic list                                    # epics and their tasks; also --json
 ```
 
-Epics don't nest. `list --json` and `status --json` carry `kind` (`task` or `epic`) and
+Each task's `CLAUDE.md` gets a managed block naming its epic and how to find sibling
+tasks; it follows every epic change and leaves the rest of the file alone. Epics don't
+nest. `list --json` and `status --json` carry `kind` (`task` or `epic`) and
 `epic` (the parent epic or `null`). `delete` and `finish` refuse an epic that still has
 tasks, even with `--force`.
 
@@ -227,11 +229,10 @@ For comprehensive troubleshooting, see the [Troubleshooting Guide](docs/troubles
 Recently shipped: agent dashboard (per-worktree Claude session badges + background dispatch),
 forge-aware merged detection (glab/gh, squash/rebase merges), MR/CI status badges,
 guided `finish` flow that archives the diff and the task-folder files, `status` subcommand
-for scripts and statuslines, Claude session recap in the Info panel, epics in the CLI and
-the task list.
+for scripts and statuslines, Claude session recap in the Info panel, epics in the CLI, the
+task list and each task's CLAUDE.md.
 
-Next: an epic context block in each task's CLAUDE.md, and epic support in the `/wtask`
-skill.
+Ideas and bugs go to [GitHub Issues](https://github.com/ruslanfialkovskii/tasktree-manager/issues).
 
 See [CHANGELOG.md](CHANGELOG.md) for the release history.
 

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/docs/configuration.md

@@ -611,7 +611,8 @@ All 27 customizable keybindings with descriptions:
 | `add_repo`    | `a`     | Add repository to current task         | `add_repo = "ctrl+a"`      |
 | `delete_task` | `d`     | Delete/finish current task             | `delete_task = "delete"`   |
 | `rename_task` | `R`     | Rename task display label (alias only) | `rename_task = "ctrl+r"`   |
-| `set_epic`    | `E`     | Set the task's epic, or make it an epic | `set_epic = "ctrl+e"`     |
+| `set_epic`    | `E`     | Set the task's epic, or make it an epic | `set_epic = "ctrl+shift+e"` |
+| `delete_worktree` | `D` | Remove the selected worktree (the task stays) | `delete_worktree = "ctrl+d"` |
 
 ### Git Operations
 
@@ -632,6 +633,7 @@ All 27 customizable keybindings with descriptions:
 | `open_claude_resume`  | `c`     | Open Claude CLI (resume if session exists, else new) | `open_claude_resume = "ctrl+c"`      |
 | `open_claude_gui_code`| `C`     | Open Claude desktop on Code page in task folder      | `open_claude_gui_code = "ctrl+shift+c"` |
 | `toggle_messages`     | `m`     | Show/hide activity messages panel                    | `toggle_messages = "ctrl+m"`         |
+| `dispatch_agent`      | `b`     | Dispatch a background Claude agent into the worktree | `dispatch_agent = "ctrl+b"`          |
 
 ### Navigation
 

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/docs/user-guide.md

@@ -85,6 +85,10 @@ names their epic, so nothing moves on disk.
 - `enter` or `space` folds an epic. A folded epic row still shows the dirty
   count and the most urgent Claude state of its tasks.
 - Epics don't nest. An epic that still has tasks can't be deleted.
+- Each task's `CLAUDE.md` gets a short block between `<!-- tasktree:epic -->` markers
+  that names the epic folder and how to find sibling tasks, so a Claude session knows
+  the bigger picture. It updates on every epic change; text outside the markers is
+  never touched.
 - From scripts: `tasktree-manager epic create/add/remove/mark/unmark/list`.
 
 ### Worktrees

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/pyproject.toml

@@ -71,7 +71,7 @@ version-file = "tasktree_manager/_version.py"
 # Semantic Release Configuration
 [tool.semantic_release]
 version_toml = ["pyproject.toml:tool.semantic_release.version"]
-version = "2.15.0"
+version = "2.16.1"
 tag_format = "v{version}"
 branch = "main"
 commit_message = "chore(release): {version} [skip ci]"

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/tasktree_manager/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.15.0'
-__version_tuple__ = version_tuple = (2, 15, 0)
+__version__ = version = '2.16.1'
+__version_tuple__ = version_tuple = (2, 16, 1)
 
 __commit_id__ = commit_id = None

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/tasktree_manager/app.py

@@ -366,6 +366,9 @@ class TaskTreeApp(App):
             (kb.get("delete_worktree", "D"), "delete_worktree", "Del WT"),
         ]
 
+        # Every key a configured action uses ("s,space" binds two keys)
+        claimed_keys = {key.strip() for keys in kb.values() for key in keys.split(",")}
+
         yield AppHeader()
         with Horizontal(id="main-container"):
             # Left column: Tasks (top) and Worktrees (bottom)
@@ -382,7 +385,7 @@ class TaskTreeApp(App):
                         id="task-list",
                         context_bindings=task_panel_bindings,
                         # A fold key bound to any action in config stays that action
-                        fold_keys=tuple(k for k in ("enter", "space") if k not in kb.values()),
+                        fold_keys=tuple(k for k in ("enter", "space") if k not in claimed_keys),
                     )
                 with Vertical(id="worktree-panel"):
                     with Horizontal(classes="panel-title-bar"):
@@ -1302,7 +1305,8 @@ class TaskTreeApp(App):
                 initial_base_branch=self.config.default_base_branch,
                 title=f"Clone Task: {self.current_task.name}",
                 epics=self._epic_choices(),
-                initial_epic=self._epic_of(self.current_task),
+                # A clone joins the source task's epic; a clone of an epic joins none
+                initial_epic=self.query_one("#task-list", TaskList).epic_of(self.current_task.name),
             ),
             handle_result,
         )
@@ -1432,7 +1436,7 @@ class TaskTreeApp(App):
                 return
             try:
                 self.task_manager.set_task_display_name(task, new_name)
-            except OSError as e:
+            except (OSError, ValueError) as e:
                 self.notify(escape(f"Rename failed: {e}"), severity="error")
                 return
             label = task.display_label
@@ -1452,6 +1456,7 @@ class TaskTreeApp(App):
             self.notify("Epics don't nest: an epic can't join another epic", severity="warning")
             return
         epics = [(label, name) for label, name in self._epic_choices() if name != task.name]
+        parent = self.query_one("#task-list", TaskList).epic_of(task.name)
 
         def handle_choice(choice: tuple[str, str | None] | None) -> None:
             if choice is None:
@@ -1469,8 +1474,8 @@ class TaskTreeApp(App):
             EpicPickerModal(
                 task.display_label,
                 epics,
-                self.query_one("#task-list", TaskList).epic_of(task.name),
-                task.epic_name is None,
+                parent,
+                parent is None,
             ),
             handle_choice,
         )
@@ -1521,6 +1526,10 @@ class TaskTreeApp(App):
             return
         self.notify(escape(message))
         self._log_activity(message, MessageLevel.INFO, task.name)
+        problem = self.task_manager.sync_epic_block(task)
+        if problem:
+            self.notify(escape(problem), severity="warning")
+            self._log_activity(problem, MessageLevel.WARNING, task.name)
         self._load_tasks(select_task=task.name)
 
     def _finish_task(self, task: Task, force: bool = False) -> None:
@@ -2080,7 +2089,9 @@ class TaskTreeApp(App):
         """
         fresh_task = self.task_manager.get_task(task.name)
         if fresh_task:
-            self.task_manager.ensure_claude_md_files(fresh_task)
+            problem = self.task_manager.ensure_claude_md_files(fresh_task)
+            if problem:
+                self.call_from_thread(self.notify, escape(problem), severity="warning")
             self.task_manager.ensure_worktree_settings(fresh_task)
         ensure_claude_hooks(task.path, self.config.claude_memory_dir)
 

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/tasktree_manager/cli.py

@@ -8,6 +8,7 @@ errors on stderr, exit code 0 on success and 1 on failure.
 
 import argparse
 import json
+import os
 import shutil
 import sys
 from pathlib import Path
@@ -16,7 +17,7 @@ from . import __version__
 from .services import forge
 from .services.config import Config, ConfigError
 from .services.git_ops import GitOps
-from .services.models import EPIC_KIND, TASK_KIND, ArchiveResult, Task
+from .services.models import EPIC_KIND, TASK_KIND, ArchiveResult, Task, parent_epic_name
 from .services.task_manager import ARCHIVE_NOTES_SHOWN, ArchiveIncompleteError, TaskManager
 
 
@@ -213,9 +214,17 @@ def _create(
     if task.epic_name is not None:
         line += f" in epic {task.epic_name}"
     print(line)
+    _warn_epic_block(manager, task)
     return 0
 
 
+def _warn_epic_block(manager: TaskManager, task: Task) -> None:
+    """Print why the task's CLAUDE.md epic block could not follow a change."""
+    problem = manager.sync_epic_block(task)
+    if problem:
+        print(f"warning: {problem}", file=sys.stderr)
+
+
 def _get_tasks(manager: TaskManager, names: list[str]) -> list[Task] | None:
     """Resolve task names, printing an error for each missing one (None if any)."""
     tasks = []
@@ -250,6 +259,7 @@ def cmd_epic_add(manager: TaskManager, config: Config, args: argparse.Namespace)
             print(f"Added {task.name} to epic {epic}")
         else:
             print(f"Moved {task.name} from epic {previous} to epic {epic}")
+        _warn_epic_block(manager, task)
     return code
 
 
@@ -265,6 +275,7 @@ def cmd_epic_remove(manager: TaskManager, config: Config, args: argparse.Namespa
             print(f"Task {task.name} is not in an epic")
         else:
             print(f"Removed {task.name} from epic {previous}")
+        _warn_epic_block(manager, task)
     return 0
 
 
@@ -278,6 +289,7 @@ def cmd_epic_mark(manager: TaskManager, config: Config, args: argparse.Namespace
         return 0
     manager.set_task_kind(task, EPIC_KIND)
     print(f"Marked {args.name} as an epic")
+    _warn_epic_block(manager, task)
     return 0
 
 
@@ -291,6 +303,7 @@ def cmd_epic_unmark(manager: TaskManager, config: Config, args: argparse.Namespa
         return 0
     manager.set_task_kind(task, TASK_KIND)
     print(f"Unmarked {args.name}: it is a plain task now")
+    _warn_epic_block(manager, task)
     return 0
 
 
@@ -342,6 +355,8 @@ def _refuse_epic_with_children(manager: TaskManager, task: Task, verb: str) -> b
 def cmd_list(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
     """List tasks with their repos and dirty state."""
     tasks = manager.list_tasks()
+    # One TASKS_DIR listing for every parent_epic_name lookup below
+    listing = set(os.listdir(config.tasks_dir)) if config.tasks_dir.is_dir() else set()
     dirty: dict[str, bool] = {}
     errored: dict[str, bool] = {}
     for task in tasks:
@@ -357,7 +372,7 @@ def cmd_list(manager: TaskManager, config: Config, args: argparse.Namespace) ->
                 "name": task.name,
                 "display_name": task.display_name,
                 "kind": task.kind,
-                "epic": task.epic_name,
+                "epic": parent_epic_name(task, listing),
                 "path": str(task.path),
                 "repos": [wt.name for wt in task.worktrees],
                 "dirty": dirty[task.name],
@@ -623,7 +638,7 @@ def cmd_status(manager: TaskManager, config: Config, args: argparse.Namespace) -
         payload = {
             "task": task.name,
             "kind": task.kind,
-            "epic": task.epic_name,
+            "epic": parent_epic_name(task),
             "path": str(task.path),
             "claude": claude,
             "worktrees": [

{tasktree_manager-2.15.0 → tasktree_manager-2.16.1}/tasktree_manager/services/models.py

@@ -2,6 +2,7 @@
 
 import os
 import re
+from collections.abc import Collection
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -128,23 +129,60 @@ class Task:
         return value
 
 
-def resolve_epic(task: Task, epics: dict[str, Task]) -> str | None:
-    """The epic in `epics` that the task's marker names, or None.
+def on_disk_name(path: Path, names: Collection[str] | None = None) -> str:
+    """The last path segment as spelled on disk, for an existing path.
 
-    A marker spelled in another case matches only when it opens the same
-    folder, as on a case-insensitive disk.
+    On a case-insensitive disk `epic-1` opens `EPIC-1`; markers, branches and
+    the epic checks must all use the real spelling. `names` is the listing of
+    path.parent when the caller already has it (one listing per scan).
     """
-    parent = task.epic_name
-    if parent is None or parent in epics:
-        return parent
-    for name, epic in epics.items():
-        if name.casefold() == parent.casefold():
-            try:
-                if os.path.samefile(task.path.parent / parent, epic.path):
-                    return name
-            except OSError:
-                pass
-    return None
+    if names is None:
+        try:
+            names = set(os.listdir(path.parent))
+        except OSError:
+            return path.name
+    if path.name in names:
+        return path.name
+    for name in names:
+        if name.casefold() == path.name.casefold() and same_folder(path.parent / name, path):
+            return name
+    return path.name
+
+
+def same_folder(a: Path, b: Path) -> bool:
+    """True when two paths open the same file or folder."""
+    try:
+        return os.path.samefile(a, b)
+    except OSError:
+        return False
+
+
+def parent_epic_name(task: Task, names: Collection[str] | None = None) -> str | None:
+    """The epic a task belongs to, spelled as on disk, or None.
+
+    The one membership rule for the CLI, the TUI, the delete guard and the
+    CLAUDE.md block: the marker must name a real epic folder next to the
+    task. A symlink alias, a missing folder or a plain task makes it an orphan.
+    `names` is the TASKS_DIR listing, passed by callers that resolve many tasks.
+    """
+    marker = task.epic_name
+    if marker is None:
+        return None
+    path = task.path.parent / marker
+    if path.is_symlink() or not path.is_dir():
+        return None
+    name = on_disk_name(path, names)
+    if not Task(name=name, path=path.parent / name).is_epic:
+        return None
+    return name
+
+
+def resolve_epic(
+    task: Task, epics: dict[str, Task], names: Collection[str] | None = None
+) -> str | None:
+    """The epic in `epics` the task belongs to (see parent_epic_name), or None."""
+    parent = parent_epic_name(task, names)
+    return parent if parent in epics else None
 
 
 def group_by_epic(tasks: list[Task]) -> tuple[list[Task], dict[str, list[Task]]]:
@@ -154,11 +192,20 @@ def group_by_epic(tasks: list[Task]) -> tuple[list[Task], dict[str, list[Task]]]
     rule as TaskManager.epic_child_names (the delete guard). Anything else, an
     orphan included, is top-level. Order within both is kept.
     """
-    epics = {task.name: task for task in tasks if task.is_epic}
+    # A symlinked folder never counts as an epic: it would alias a real one
+    epics = {task.name: task for task in tasks if task.is_epic and not task.path.is_symlink()}
     children: dict[str, list[Task]] = {name: [] for name in epics}
     top: list[Task] = []
+    listings: dict[Path, set[str]] = {}
     for task in tasks:
-        parent = None if task.name in epics else resolve_epic(task, epics)
+        folder = task.path.parent
+        if folder not in listings:
+            try:
+                listings[folder] = set(os.listdir(folder))
+            except OSError:
+                listings[folder] = set()
+        names = listings[folder]
+        parent = None if task.name in epics else resolve_epic(task, epics, names)
         if parent is None:
             top.append(task)
         else: