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

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

@@ -15,6 +15,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Git hooks support
 - Custom task metadata
 
+## [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.0}/PKG-INFO

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

{tasktree_manager-2.15.0 → tasktree_manager-2.16.0}/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.0}/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.0}/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.0"
 tag_format = "v{version}"
 branch = "main"
 commit_message = "chore(release): {version} [skip ci]"

{tasktree_manager-2.15.0 → tasktree_manager-2.16.0}/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.0'
+__version_tuple__ = version_tuple = (2, 16, 0)
 
 __commit_id__ = commit_id = None

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

@@ -1521,6 +1521,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:

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

@@ -213,9 +213,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 +258,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 +274,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 +288,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 +302,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
 
 

{tasktree_manager-2.15.0 → tasktree_manager-2.16.0}/tasktree_manager/services/task_manager.py

@@ -5,6 +5,7 @@ import os
 import re
 import shutil
 import subprocess
+import tempfile
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime
 from pathlib import Path
@@ -84,6 +85,37 @@ _STUB_ENTRY = re.compile(r"- \*\*(?P<name>[^*]+)\*\*: `(?P<path>[^`]+)`")
 _STUB_BRANCH = re.compile(r"  - Branch: `[^`]+`")
 
 
+# Managed block in a task CLAUDE.md that tells a session about its epic
+EPIC_BLOCK_START = "<!-- tasktree:epic -->"
+EPIC_BLOCK_END = "<!-- /tasktree:epic -->"
+
+
+def _epic_block_span(text: str) -> tuple[int, int] | None:
+    """(start, end) of the one managed epic block, or None.
+
+    Raises ValueError when the markers are unbalanced, repeated or out of
+    order: the file was edited by hand and must be left alone.
+    """
+    starts, ends = text.count(EPIC_BLOCK_START), text.count(EPIC_BLOCK_END)
+    if starts == ends == 0:
+        return None
+    start, end = text.find(EPIC_BLOCK_START), text.find(EPIC_BLOCK_END)
+    if starts != 1 or ends != 1 or end < start:
+        raise ValueError("mismatched tasktree:epic markers")
+    return start, end + len(EPIC_BLOCK_END)
+
+
+def _without_epic_block(text: str) -> str:
+    """CLAUDE.md text with the managed epic block cut out (unchanged if malformed)."""
+    try:
+        span = _epic_block_span(text)
+    except ValueError:
+        return text
+    if span is None:
+        return text
+    return text[: span[0]] + text[span[1] :]
+
+
 def _without_worktree_entries(text: str, task_path: Path) -> list[str]:
     """CLAUDE.md lines minus the generated entries of its Worktrees section.
 
@@ -648,9 +680,13 @@ class TaskManager:
         elif marker.exists():
             marker.unlink()
 
-    @staticmethod
-    def _write_marker(task: Task, marker: str, value: str | None) -> None:
-        """Write <task>/<marker>, or remove it when value is None."""
+    def _write_marker(self, task: Task, marker: str, value: str | None) -> None:
+        """Write <task>/<marker>, or remove it when value is None.
+
+        Every epic change passes through here, so the CLAUDE.md epic block
+        follows it. That sync never raises: callers that report problems run
+        sync_epic_block again and show what it returns.
+        """
         path = task.path / marker
         if path.is_symlink():
             # Never write through a planted link to a file outside the task
@@ -659,6 +695,100 @@ class TaskManager:
             path.write_text(value + "\n", encoding="utf-8")
         else:
             path.unlink(missing_ok=True)
+        self.sync_epic_block(task)
+
+    def _render_epic_block(self, task: Task) -> str | None:
+        """The managed CLAUDE.md block for an epic or a child task, else None."""
+        tasks_dir = self.config.tasks_dir.absolute()
+        if task.is_epic:
+            body = [
+                f"This folder is the epic `{task.name}`. Its tasks are the folders in",
+                f"`{tasks_dir}` whose `.tasktree_epic` file names `{task.name}`; list them",
+                "with `tasktree-manager epic list`.",
+            ]
+        elif task.epic_name is not None:
+            epic = task.epic_name
+            body = [
+                f"This task belongs to the epic `{epic}` at `{tasks_dir / epic}`.",
+                "The epic folder holds the shared notes and plans. Its worktrees belong",
+                "to the epic, not to this task: read them for context, change code here.",
+                f"Sibling tasks are the folders in `{tasks_dir}` whose `.tasktree_epic`",
+                f"file names `{epic}`; list them with `tasktree-manager epic list`.",
+            ]
+        else:
+            return None
+        return "\n".join([EPIC_BLOCK_START, "## Epic", "", *body, EPIC_BLOCK_END])
+
+    def sync_epic_block(self, task: Task) -> str | None:
+        """Insert, update or remove the epic block in <task>/CLAUDE.md.
+
+        Returns a problem to show the user, or None; never raises. Text outside
+        the markers keeps its bytes and line endings, and the file is replaced
+        atomically. A missing CLAUDE.md is left for ensure_claude_md_files; a
+        read-only one or one with mismatched markers is not touched.
+        """
+        path = task.path / "CLAUDE.md"
+        if not path.is_file() or path.is_symlink():
+            return None
+        try:
+            # surrogateescape round-trips bytes that are not UTF-8
+            text = path.read_bytes().decode("utf-8", "surrogateescape")
+            span = _epic_block_span(text)
+        except OSError as e:
+            return f"could not read {path}: {e}"
+        except ValueError:
+            return f"{path} has mismatched tasktree:epic markers; the epic block was not updated"
+        new = self._with_epic_block(text, span, self._render_epic_block(task))
+        if new == text:
+            return None
+        if not os.access(path, os.W_OK):
+            return f"{path} is read-only; the epic block was not updated"
+        try:
+            self._replace_file(path, new.encode("utf-8", "surrogateescape"))
+        except OSError as e:
+            return f"could not update the epic block in {path}: {e}"
+        return None
+
+    @staticmethod
+    def _with_epic_block(text: str, span: tuple[int, int] | None, block: str | None) -> str:
+        """`text` with the block inserted, replaced or removed (in the file's line endings)."""
+        nl = "\r\n" if "\r\n" in text else "\n"
+        if block is not None:
+            block = block.replace("\n", nl)
+        if span is not None:
+            before, after = text[: span[0]], text[span[1] :]
+            if block is not None:
+                return before + block + after
+            # Drop the line break after the block and the blank line added before it
+            after = after.removeprefix(nl)
+            if before.endswith(nl + nl):
+                before = before[: -len(nl)]
+            return before + after
+        if block is None:
+            return text
+        if not text:
+            return block + nl
+        sep = "" if text.endswith(nl + nl) else nl if text.endswith(nl) else nl + nl
+        return text + sep + block + nl
+
+    @staticmethod
+    def _replace_file(path: Path, data: bytes) -> None:
+        """Write `data` to `path` via a temp file and an atomic rename.
+
+        A failed write leaves the old file whole; the hidden temp name keeps
+        a leftover out of the archive.
+        """
+        fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(data)
+                f.flush()
+                os.fsync(f.fileno())
+            shutil.copymode(path, tmp)
+            os.replace(tmp, path)
+        except BaseException:
+            Path(tmp).unlink(missing_ok=True)
+            raise
 
     def _require_epic(self, epic_name: str, task_name: str) -> str:
         """Return the epic's name as spelled on disk, or raise ValueError.
@@ -754,9 +884,10 @@ class TaskManager:
             children = self.epic_child_names(task.name) if task.is_epic else []
             if children:
                 raise ValueError(self._epic_has_children_message(task, children))
-            self._write_marker(task, ".tasktree_kind", None)
-            # A parent marker the epic carried was hidden; never let it surface
+            # A parent marker the epic carried was hidden; drop it before the
+            # kind, or the CLAUDE.md sync would briefly treat it as real
             self._write_marker(task, ".tasktree_epic", None)
+            self._write_marker(task, ".tasktree_kind", None)
         else:
             raise ValueError(f"Unknown task kind: {kind}")
 
@@ -980,9 +1111,10 @@ class TaskManager:
         except (OSError, UnicodeDecodeError):
             return False
         stub = self._render_task_claude_md(task.name, [])
-        return _without_worktree_entries(text, task.path) == _without_worktree_entries(
-            stub, task.path
-        )
+        # The managed epic block is generated too
+        return _without_worktree_entries(
+            _without_epic_block(text), task.path
+        ) == _without_worktree_entries(stub, task.path)
 
     def _resolve_archive_base(self, worktree: Worktree, recorded_base: str | None) -> str:
         """Pick a base branch for the archive diff that actually resolves.
@@ -1362,6 +1494,7 @@ class TaskManager:
         task_claude_md = task.path / "CLAUDE.md"
         if not task_claude_md.exists():
             self._create_task_claude_md(task)
+        self.sync_epic_block(task)
 
         for worktree in task.worktrees:
             wt_claude_md = worktree.path / "CLAUDE.md"

tasktree_manager-2.16.0/tests/test_epic_claude_md.py

@@ -0,0 +1,176 @@
+"""Tests for the managed epic block in task CLAUDE.md files."""
+
+import os
+
+import pytest
+
+from tasktree_manager.cli import run_cli
+from tasktree_manager.services.task_manager import EPIC_BLOCK_END, EPIC_BLOCK_START
+
+
+@pytest.fixture
+def tm(task_manager):
+    task_manager.create_task("E-1", [], kind="epic")
+    task_manager.create_task("E-2", [], kind="epic")
+    return task_manager
+
+
+def claude_md(tm, name):
+    return (tm.config.tasks_dir / name / "CLAUDE.md").read_text()
+
+
+def prepare(tm, name):
+    tm.ensure_claude_md_files(tm.get_task(name))
+    return tm.get_task(name)
+
+
+class TestEpicBlock:
+    def test_child_block_backfilled(self, tm):
+        tm.create_task("T-1", [], epic="E-1")
+        prepare(tm, "T-1")
+        text = claude_md(tm, "T-1")
+        assert text.startswith("# Task: T-1")
+        assert text.count(EPIC_BLOCK_START) == 1
+        assert "belongs to the epic `E-1`" in text
+        assert str(tm.config.tasks_dir / "E-1") in text
+
+    def test_epic_block(self, tm):
+        prepare(tm, "E-1")
+        assert "This folder is the epic `E-1`" in claude_md(tm, "E-1")
+
+    def test_sync_twice_changes_nothing(self, tm):
+        tm.create_task("T-1", [], epic="E-1")
+        task = prepare(tm, "T-1")
+        first = claude_md(tm, "T-1")
+        tm.sync_epic_block(task)
+        tm.ensure_claude_md_files(task)
+        assert claude_md(tm, "T-1") == first
+
+    def test_move_and_detach_keep_user_text(self, tm):
+        task = tm.create_task("T-1", [], epic="E-1")
+        path = task.path / "CLAUDE.md"
+        path.write_text("# My notes\n\nkeep this\n")
+        tm.sync_epic_block(task)
+        path.write_text(path.read_text() + "\n## After\n\nand this\n")
+        tm.set_task_epic(task, "E-2")
+        text = path.read_text()
+        assert "epic `E-2`" in text and "epic `E-1`" not in text
+        assert text.startswith("# My notes\n\nkeep this\n")
+        assert text.endswith("## After\n\nand this\n")
+        tm.set_task_epic(task, None)
+        assert path.read_text() == "# My notes\n\nkeep this\n\n## After\n\nand this\n"
+
+    def test_unmark_removes_epic_block(self, tm):
+        epic = prepare(tm, "E-2")
+        tm.set_task_kind(epic, "task")
+        assert EPIC_BLOCK_START not in claude_md(tm, "E-2")
+
+    @pytest.mark.parametrize(
+        "broken",
+        [
+            EPIC_BLOCK_START + "\nhalf",
+            EPIC_BLOCK_END + "\n" + EPIC_BLOCK_START,
+            (EPIC_BLOCK_START + "\nx\n" + EPIC_BLOCK_END + "\n") * 2,
+        ],
+    )
+    def test_mismatched_markers_left_alone(self, tm, broken):
+        task = tm.create_task("T-1", [], epic="E-1")
+        path = task.path / "CLAUDE.md"
+        path.write_text("notes\n" + broken)
+        tm.sync_epic_block(task)
+        assert path.read_text() == "notes\n" + broken
+
+    def test_stub_with_block_is_not_archived(self, tm):
+        tm.create_task("T-1", [], epic="E-1")
+        task = prepare(tm, "T-1")
+        assert tm.archive_task(task) is None
+
+    def test_edited_file_with_block_is_archived(self, tm):
+        tm.create_task("T-1", [], epic="E-1")
+        task = prepare(tm, "T-1")
+        path = task.path / "CLAUDE.md"
+        path.write_text(path.read_text() + "\nmy plan\n")
+        result = tm.archive_task(task)
+        assert result is not None and "CLAUDE.md" in result.files
+
+    def test_missing_file_not_created_by_epic_change(self, tm):
+        task = tm.create_task("T-1", [])
+        tm.set_task_epic(task, "E-1")
+        assert not (task.path / "CLAUDE.md").exists()
+
+    def test_cli_epic_add_updates_block(self, tm, config, capsys):
+        tm.create_task("T-1", [])
+        prepare(tm, "T-1")
+        assert run_cli(["epic", "add", "E-1", "T-1"], config=config) == 0
+        assert "epic `E-1`" in claude_md(tm, "T-1")
+
+
+class TestEpicBlockRobustness:
+    def test_crlf_file_round_trips(self, tm):
+        task = tm.create_task("T-1", [])
+        path = task.path / "CLAUDE.md"
+        original = b"# Notes\r\n\r\nline\r\n"
+        path.write_bytes(original)
+        tm.set_task_epic(task, "E-1")
+        data = path.read_bytes()
+        assert data.startswith(original)
+        assert b"\n" not in data.replace(b"\r\n", b"")
+        tm.set_task_epic(task, None)
+        assert path.read_bytes() == original
+
+    def test_non_utf8_file_keeps_bytes_and_prep_runs(self, tm):
+        task = tm.create_task("T-1", [], epic="E-1")
+        path = task.path / "CLAUDE.md"
+        path.write_bytes(b"caf\xe9 notes\n")
+        tm.ensure_claude_md_files(task)  # must not raise
+        data = path.read_bytes()
+        assert data.startswith(b"caf\xe9 notes\n")
+        assert b"epic `E-1`" in data
+
+    def test_read_only_file_is_reported_not_raised(self, tm):
+        task = tm.create_task("T-1", [])
+        path = task.path / "CLAUDE.md"
+        path.write_text("notes\n")
+        os.chmod(path, 0o444)
+        try:
+            tm.set_task_epic(task, "E-1")
+            problem = tm.sync_epic_block(task)
+            tm.ensure_claude_md_files(task)
+        finally:
+            os.chmod(path, 0o644)
+        assert "read-only" in problem
+        assert path.read_text() == "notes\n"
+
+    def test_failed_write_keeps_original(self, tm, monkeypatch):
+        task = tm.create_task("T-1", [])
+        path = task.path / "CLAUDE.md"
+        path.write_text("notes\n" * 50)
+
+        def full_disk(src, dst):
+            raise OSError(28, "No space left on device")
+
+        monkeypatch.setattr(os, "replace", full_disk)
+        tm.set_task_epic(task, "E-1")
+        assert path.read_text() == "notes\n" * 50
+        assert "No space left" in tm.sync_epic_block(task)
+        assert [p.name for p in task.path.iterdir() if p.name.endswith(".tmp")] == []
+
+    def test_unmark_with_planted_parent_marker(self, tm):
+        epic = prepare(tm, "E-2")
+        (epic.path / ".tasktree_epic").write_text("E-1\n")
+        tm.set_task_kind(epic, "task")
+        assert EPIC_BLOCK_START not in claude_md(tm, "E-2")
+
+    def test_broken_markers_count_as_edited_for_archive(self, tm):
+        tm.create_task("T-1", [], epic="E-1")
+        task = prepare(tm, "T-1")
+        path = task.path / "CLAUDE.md"
+        path.write_text(path.read_text() + EPIC_BLOCK_START + "\n")
+        result = tm.archive_task(task)
+        assert result is not None and "CLAUDE.md" in result.files
+
+    def test_cli_warns_on_mismatched_markers(self, tm, config, capsys):
+        task = tm.create_task("T-1", [])
+        (task.path / "CLAUDE.md").write_text(EPIC_BLOCK_START + "\n")
+        assert run_cli(["epic", "add", "E-1", "T-1"], config=config) == 0
+        assert "mismatched tasktree:epic markers" in capsys.readouterr().err