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

{tasktree_manager-2.16.1 → tasktree_manager-2.17.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.17.0] - 2026-10-20
+
+### Added
+- **epic**: Add an epic log for notes shared across task sessions (#13)
+
+
 ## [2.16.1] - 2026-10-19
 
 ### Fixed

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

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

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

@@ -22,7 +22,7 @@
 - 🛰️ **Agent Dashboard** - Live Claude Code session state per worktree (from `claude agents`), plus one-key background-agent dispatch — the multi-repo agent view Claude Code lacks natively
 - ✻ **Session Recap** - The Info panel shows each task's latest Claude Code session: title, last turn duration, and Claude's own idle recap of what was done and what comes next — read straight from the transcript, no CLI call
 - 🔀 **Forge-Aware Safety** - MR/PR and CI state via `glab`/`gh`; squash- and rebase-merged branches count as merged instead of blocking deletion forever
-- 🗂️ **Epics** - Group related tasks under an epic: a foldable row with rolled-up dirty and Claude state, `E` to attach tasks
+- 🗂️ **Epics** - Group related tasks under an epic: a foldable row with rolled-up dirty and Claude state, `E` to attach tasks, and an epic log where the Claude sessions of one epic share notes
 - 📦 **Finish Flow with Archives** - Ending a task saves its combined diff (committed-but-unmerged + uncommitted) and the task-folder files outside the worktrees (plans, ADRs, notes) to an archive before deleting
 
 ## 📊 Status Indicators
@@ -100,10 +100,20 @@ tasktree-manager epic add DIC-2466-pcaps-epic DIC-2862-pcaps-s3  # attach or mov
 tasktree-manager epic remove DIC-2862-pcaps-s3                # detach
 tasktree-manager epic mark DIC-2466-pcaps-epic                # turn an existing task into an epic; unmark reverts
 tasktree-manager epic list                                    # epics and their tasks; also --json
+tasktree-manager epic note "chose layout A for the S3 keys"   # add a note to this task's file in the epic log
+tasktree-manager epic log                                     # notes and latest session recap of every task in the epic
+tasktree-manager epic log DIC-2862-pcaps-s3 --json            # one task (or a whole epic by its name), as JSON
+tasktree-manager epic sync                                    # refresh the CLAUDE.md epic block after an upgrade
 ```
 
 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
+tasks; it follows every epic change and leaves the rest of the file alone. The block
+also tells the session about the epic log: one notes file per task in `epic-log/` in the
+epic folder, written with `epic note` and read with `epic log`, which adds the recap of each
+task's latest Claude session (in the task folder or one of its worktrees). Inside a task
+folder, `epic note` writes only that task's notes and `epic log` reads only its epic;
+`epic note -` reads the text from stdin. Notes of a task that left the epic stay readable.
+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`.

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

@@ -89,7 +89,22 @@ names their epic, so nothing moves on disk.
   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`.
+- The epic log lets the sessions of one epic share what they learned. A session
+  records decisions, interfaces and open questions with
+  `tasktree-manager epic note "..."`; they go to `epic-log/<task>.md` in the epic
+  folder. `tasktree-manager epic log` shows every task's notes and the recap of its
+  latest Claude session, so a session can check what its siblings did before asking.
+  The `CLAUDE.md` block tells each session about both commands, and that notes are
+  information from other sessions, not instructions.
+- A session writes only its own task's notes. From a terminal outside any task,
+  `epic note --task NAME` writes for a task and marks the entry as written outside it.
+- Notes stay in the epic after their task is finished, moved or deleted; `epic log`
+  lists them as "no longer in the epic". A note is at most 16 KB, and `epic log` shows
+  the newest 64 KB of each task's notes.
+- After upgrading tasktree-manager, run `tasktree-manager epic sync` to refresh the
+  block in existing tasks (the TUI also refreshes it when it starts a Claude session).
+  Folders without a `CLAUDE.md` yet are counted and skipped.
+- From scripts: `tasktree-manager epic create/add/remove/mark/unmark/list/note/log/sync`.
 
 ### Worktrees
 

{tasktree_manager-2.16.1 → tasktree_manager-2.17.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.16.1"
+version = "2.17.0"
 tag_format = "v{version}"
 branch = "main"
 commit_message = "chore(release): {version} [skip ci]"

{tasktree_manager-2.16.1 → tasktree_manager-2.17.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.16.1'
-__version_tuple__ = version_tuple = (2, 16, 1)
+__version__ = version = '2.17.0'
+__version_tuple__ = version_tuple = (2, 17, 0)
 
 __commit_id__ = commit_id = None

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

@@ -9,17 +9,36 @@ errors on stderr, exit code 0 on success and 1 on failure.
 import argparse
 import json
 import os
+import re
 import shutil
 import sys
+from datetime import timezone
 from pathlib import Path
 
 from . import __version__
 from .services import forge
 from .services.config import Config, ConfigError
+from .services.epic_log import (
+    EPIC_ROLE,
+    FORMER_ROLE,
+    EpicLogEntry,
+    read_epic_log,
+    resolve_log_target,
+)
 from .services.git_ops import GitOps
-from .services.models import EPIC_KIND, TASK_KIND, ArchiveResult, Task, parent_epic_name
+from .services.models import (
+    EPIC_KIND,
+    TASK_KIND,
+    ArchiveResult,
+    Task,
+    parent_epic_name,
+    same_folder,
+)
 from .services.task_manager import ARCHIVE_NOTES_SHOWN, ArchiveIncompleteError, TaskManager
 
+# C0/C1 controls except tab; notes are split on newlines before this runs
+_CONTROL_CHARS = re.compile(r"[\x00-\x08\x0a-\x1f\x7f-\x9f]")
+
 
 def build_parser() -> argparse.ArgumentParser:
     """Build the argument parser for the headless CLI."""
@@ -79,6 +98,31 @@ def build_parser() -> argparse.ArgumentParser:
     epic_list.add_argument("--json", action="store_true", dest="as_json", help="Output JSON")
     epic_list.set_defaults(func=cmd_epic_list)
 
+    epic_note = epic_sub.add_parser("note", help="Add a note to this task's file in the epic log")
+    epic_note.add_argument("text", help='Note text ("-" reads it from stdin)')
+    epic_note.add_argument(
+        "--task", default=None, help="Task that writes the note (default: inferred from $PWD)"
+    )
+    epic_note.set_defaults(func=cmd_epic_note)
+
+    epic_log = epic_sub.add_parser(
+        "log", help="Show the notes and latest session recap of tasks in an epic"
+    )
+    epic_log.add_argument(
+        "task",
+        nargs="?",
+        default=None,
+        help="One task of the epic (default: the epic of $PWD and all its tasks)",
+    )
+    epic_log.add_argument("--json", action="store_true", dest="as_json", help="Output JSON")
+    epic_log.set_defaults(func=cmd_epic_log)
+
+    epic_sync = epic_sub.add_parser(
+        "sync", help="Refresh the epic block in the CLAUDE.md of epics and their tasks"
+    )
+    epic_sync.add_argument("name", nargs="?", default=None, help="Epic name (default: all)")
+    epic_sync.set_defaults(func=cmd_epic_sync)
+
     list_parser = sub.add_parser("list", help="List tasks with their repos and dirty state")
     list_parser.add_argument("--json", action="store_true", dest="as_json", help="Output JSON")
     list_parser.set_defaults(func=cmd_list)
@@ -335,6 +379,142 @@ def cmd_epic_list(manager: TaskManager, config: Config, args: argparse.Namespace
     return 0
 
 
+def cmd_epic_note(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Append a note to the task's file in its epic log.
+
+    Inside a task folder a session writes only its own notes; from outside
+    any task, `--task` writes and the heading records that.
+    """
+    caller = _find_task_by_cwd(manager)
+    source = None
+    if args.task:
+        task = manager.get_task(args.task)
+        if task is None:
+            return _error(f"no such task: {args.task}")
+        if caller is None:
+            source = "written outside the task folder"
+        elif not same_folder(caller.path, task.path):
+            return _error(f"inside task {caller.name}: notes go to its own file, not {task.name}")
+    elif caller is None:
+        return _error("not inside a task directory; pass --task")
+    else:
+        task = caller
+    text = sys.stdin.read() if args.text == "-" else args.text
+    path = manager.append_epic_note(task, text, source=source)
+    print(f"Noted in {path}")
+    return 0
+
+
+def cmd_epic_log(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Show notes and the latest session recap of one task or a whole epic."""
+    epic, only = resolve_log_target(manager, _find_task_by_cwd(manager), args.task)
+    entries = read_epic_log(manager, epic, only)
+    for entry in entries:
+        if entry.problem:
+            print(f"warning: {entry.task}: {entry.problem}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps([_epic_log_json(entry) for entry in entries], indent=2))
+        return 0
+    for index, entry in enumerate(entries):
+        if index:
+            print()
+        _print_epic_log_entry(entry)
+    return 0
+
+
+def _epic_log_json(entry: EpicLogEntry) -> dict:
+    session = None
+    if entry.session is not None:
+        recap = entry.recap
+        session = {
+            "id": entry.session.session_id,
+            "cwd": str(entry.session.cwd),
+            "title": recap.title if recap else None,
+            "finished_at": recap.finished_at.isoformat() if recap and recap.finished_at else None,
+            "summary": recap.summary if recap else None,
+            # The typed prompt only stands in for a missing recap, as in the TUI
+            "last_prompt": recap.last_prompt if recap and not recap.summary else None,
+        }
+    return {
+        "task": entry.task,
+        "role": entry.role,
+        "notes_path": str(entry.notes_path),
+        "notes": entry.notes,
+        "notes_truncated": entry.notes_truncated,
+        "session": session,
+        "problem": entry.problem,
+    }
+
+
+def _print_epic_log_entry(entry: EpicLogEntry) -> None:
+    role = {EPIC_ROLE: " (epic)", FORMER_ROLE: " (no longer in the epic)"}.get(entry.role, "")
+    print(f"== {entry.task}{role} ==")
+    recap = entry.recap
+    if entry.role == FORMER_ROLE:
+        pass
+    elif recap is None:
+        print("Last session: none recorded")
+    else:
+        when = "time unknown"
+        if recap.finished_at:
+            when = recap.finished_at.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+        print(f"Last session: {recap.title} ({when})")
+        if recap.summary:
+            print(f"  Recap: {recap.summary}")
+        elif recap.last_prompt:
+            print(f"  Last prompt: {recap.last_prompt}")
+    if not entry.notes:
+        print("Notes: none yet")
+        return
+    cut = ", older notes cut" if entry.notes_truncated else ""
+    print(f"Notes ({entry.notes_path}{cut}):")
+    # Indented, so a note cannot forge a "== task ==" line; controls dropped
+    for line in _safe_lines(entry.notes.rstrip()):
+        print(f"  {line}" if line else "")
+
+
+def _safe_lines(text: str) -> list[str]:
+    return [_CONTROL_CHARS.sub("", line) for line in text.split("\n")]
+
+
+def cmd_epic_sync(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Refresh the CLAUDE.md epic block of epics and their tasks."""
+    if args.name:
+        epic = manager.get_task(args.name)
+        if epic is None:
+            return _error(f"no such epic: {args.name}")
+        if manager.epic_of(epic) != epic.name:
+            return _error(f"{epic.name} is not an epic")
+        epics = [epic.name]
+    else:
+        epics = [task.name for task in manager.list_tasks() if manager.epic_of(task) == task.name]
+    synced = missing = failed = 0
+    for name in epics:
+        for member in [name, *manager.epic_child_names(name)]:
+            try:
+                task = manager.get_task(member)
+            except (OSError, ValueError) as e:
+                print(f"warning: {member}: {e}", file=sys.stderr)
+                failed += 1
+                continue
+            if task is None:
+                continue
+            if not (task.path / "CLAUDE.md").is_file():
+                missing += 1
+                continue
+            problem = manager.sync_epic_block(task)
+            if problem:
+                print(f"warning: {problem}", file=sys.stderr)
+                failed += 1
+            else:
+                synced += 1
+    print(
+        f"Synced {synced} folder(s); {missing} without CLAUDE.md "
+        f"(written when a Claude session starts there from the TUI); {failed} failed"
+    )
+    return 1 if failed else 0
+
+
 def _refuse_epic_with_children(manager: TaskManager, task: Task, verb: str) -> bool:
     """Print an error and return True if `task` is an epic that still has tasks.
 
@@ -545,7 +725,8 @@ def cmd_add_repo(manager: TaskManager, config: Config, args: argparse.Namespace)
 def _find_task_by_cwd(manager: TaskManager) -> Task | None:
     """Find the task whose directory contains the current working directory."""
     cwd = Path.cwd().resolve()
-    for task in manager.list_tasks():
+    # A symlink alias resolves to the same folder: the real folder wins
+    for task in sorted(manager.list_tasks(), key=lambda task: task.path.is_symlink()):
         task_path = task.path.resolve()
         if cwd == task_path or cwd.is_relative_to(task_path):
             return task

{tasktree_manager-2.16.1 → tasktree_manager-2.17.0}/tasktree_manager/services/claude_sessions.py

@@ -14,6 +14,7 @@ costs one bounded read regardless of its length.
 import json
 import os
 import re
+from collections.abc import Iterable
 from dataclasses import dataclass
 from datetime import datetime, tzinfo
 from pathlib import Path
@@ -23,6 +24,8 @@ from .claude_hooks import project_dir_candidates
 RECAP_SUFFIX = "(disable recaps in /config)"
 TAIL_WINDOW = 1 << 20
 TAIL_WINDOW_RETRY = 4 << 20
+# Most a session-folder lookup reads from the start of a transcript
+HEAD_BUDGET = 16 << 20
 # Turns that span a laptop sleep report days of "duration"; anything above
 # an hour is noise rather than work time
 DURATION_CAP_MS = 3_600_000
@@ -56,13 +59,22 @@ class ClaudeRecap:
     last_prompt: str | None
 
 
-def transcript_key(folder: Path) -> tuple[Path, int, int] | None:
-    """Return ``(path, mtime_ns, size)`` of the newest transcript for a folder.
+@dataclass(frozen=True)
+class SessionRef:
+    """A transcript and the folder its session was started in."""
 
-    One ``scandir`` per candidate project dir and no file reads, so callers
-    can poll it to detect changes cheaply.
-    """
-    newest: tuple[int, int, Path] | None = None
+    path: Path
+    cwd: Path
+    mtime_ns: int
+
+    @property
+    def session_id(self) -> str:
+        return self.path.stem
+
+
+def _transcripts(folder: Path) -> list[tuple[int, int, Path]]:
+    """``(mtime_ns, size, path)`` of every transcript in a folder's project dirs."""
+    found = []
     for project_dir in project_dir_candidates(folder):
         try:
             entries = list(os.scandir(project_dir))
@@ -77,15 +89,76 @@ def transcript_key(folder: Path) -> tuple[Path, int, int] | None:
                 # Claude prunes old transcripts at startup; one can vanish
                 # between the scandir and the stat
                 continue
-            candidate = (stat.st_mtime_ns, stat.st_size, Path(entry.path))
-            if newest is None or candidate[0] > newest[0]:
-                newest = candidate
+            found.append((stat.st_mtime_ns, stat.st_size, Path(entry.path)))
+    return found
+
+
+def transcript_key(folder: Path) -> tuple[Path, int, int] | None:
+    """Return ``(path, mtime_ns, size)`` of the newest transcript for a folder.
+
+    One ``scandir`` per candidate project dir and no file reads, so callers
+    can poll it to detect changes cheaply.
+    """
+    newest = max(_transcripts(folder), key=lambda found: found[0], default=None)
     if newest is None:
         return None
     mtime_ns, size, path = newest
     return path, mtime_ns, size
 
 
+def transcript_cwd(path: Path) -> Path | None:
+    """The folder a session started in: the first ``cwd`` in its transcript.
+
+    Whole records are read, since ``cwd`` follows the message body; a first
+    prompt bigger than HEAD_BUDGET leaves the cwd unknown.
+    """
+    try:
+        with open(path, "rb") as f:
+            budget = HEAD_BUDGET
+            while budget > 0:
+                line = f.readline(budget)
+                if not line:
+                    return None
+                budget -= len(line)
+                if b'"cwd"' not in line:
+                    continue
+                try:
+                    record = json.loads(line)
+                except ValueError:
+                    continue
+                cwd = record.get("cwd") if isinstance(record, dict) else None
+                if isinstance(cwd, str) and cwd:
+                    return Path(cwd)
+    except OSError:
+        return None
+    return None
+
+
+def latest_session(folders: Iterable[Path]) -> SessionRef | None:
+    """The newest session started in one of `folders` (a task and its worktrees).
+
+    Project dir names fold every non-alphanumeric character, so `X/1` and `X-1`
+    share one dir; a transcript counts only when its recorded cwd is the folder.
+    """
+    candidates = [
+        (mtime_ns, str(path), path, folder)
+        for folder in folders
+        for mtime_ns, _size, path in _transcripts(folder)
+    ]
+    for mtime_ns, _key, path, folder in sorted(candidates, reverse=True):
+        cwd = transcript_cwd(path)
+        if cwd is not None and _same_dir(cwd, folder):
+            return SessionRef(path=path, cwd=folder, mtime_ns=mtime_ns)
+    return None
+
+
+def _same_dir(a: Path, b: Path) -> bool:
+    try:
+        return os.path.samefile(a, b)
+    except OSError:
+        return os.path.realpath(a) == os.path.realpath(b)
+
+
 def read_claude_recap(path: Path) -> ClaudeRecap | None:
     """Read the recap from one transcript (see ``transcript_key`` to pick it)."""
     try:

tasktree_manager-2.17.0/tasktree_manager/services/epic_log.py

@@ -0,0 +1,105 @@
+"""The epic log: each task's notes plus the recap of its latest Claude session.
+
+Sessions of one epic read it to learn what the other tasks decided. The scope
+rule lives here so every reader applies it the same way: from inside a task of
+an epic, only that epic can be read.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .claude_sessions import ClaudeRecap, SessionRef, latest_session, read_claude_recap
+from .models import Task
+from .task_manager import TaskManager
+
+EPIC_ROLE = "epic"
+MEMBER_ROLE = "task"
+# A notes file left by a task that is no longer in the epic (finished, moved)
+FORMER_ROLE = "former"
+
+
+@dataclass(frozen=True)
+class EpicLogEntry:
+    """One task's part of the epic log."""
+
+    task: str
+    role: str
+    notes_path: Path
+    notes: str | None
+    notes_truncated: bool
+    session: SessionRef | None
+    recap: ClaudeRecap | None
+    problem: str | None = None  # why the task's sessions could not be read
+
+
+def caller_epic(manager: TaskManager, caller: Task | None) -> str | None:
+    """The epic of the task the command runs in, or None outside an epic."""
+    return manager.epic_of(caller) if caller is not None else None
+
+
+def resolve_log_target(
+    manager: TaskManager, caller: Task | None, name: str | None
+) -> tuple[str, str | None]:
+    """``(epic, task)`` to read: `task` None means the whole epic.
+
+    Raises ValueError for a task outside any epic, or outside the caller's.
+    """
+    scope = caller_epic(manager, caller)
+    if name is None:
+        if scope is None:
+            raise ValueError("not inside a task of an epic; pass a task name")
+        return scope, None
+    target = manager.get_task(name)
+    if target is None:
+        # Notes outlive their task: read them by name from inside the epic
+        if scope is not None and name in manager.epic_note_names(scope):
+            return scope, name
+        raise ValueError(f"no such task: {name}")
+    epic = manager.epic_of(target)
+    if scope is not None and epic != scope and target.name in manager.epic_note_names(scope):
+        # It left the caller's epic: its notes there are still readable
+        return scope, target.name
+    if epic is None:
+        raise ValueError(f"task {target.name} is not in an epic")
+    if scope is not None and epic != scope:
+        raise ValueError(f"task {target.name} is in epic {epic}, not in {scope}")
+    return epic, None if target.is_epic else target.name
+
+
+def task_session(task: Task) -> SessionRef | None:
+    """The newest session of a task, run in its folder or one of its worktrees."""
+    return latest_session([task.path, *(wt.path for wt in task.worktrees)])
+
+
+def read_epic_log(manager: TaskManager, epic: str, only: str | None = None) -> list[EpicLogEntry]:
+    """The log of the whole epic, or of the one task `only`."""
+    members = [epic, *manager.epic_child_names(epic)]
+    roles = {name: MEMBER_ROLE for name in members}
+    roles[epic] = EPIC_ROLE
+    for name in manager.epic_note_names(epic):
+        roles.setdefault(name, FORMER_ROLE)
+    names = [only] if only is not None else [*members, *sorted(set(roles) - set(members))]
+    return [_entry(manager, epic, name, roles.get(name, FORMER_ROLE)) for name in names]
+
+
+def _entry(manager: TaskManager, epic: str, name: str, role: str) -> EpicLogEntry:
+    session = recap = problem = None
+    if role != FORMER_ROLE:
+        try:
+            task = manager.get_task(name)
+        except (OSError, ValueError) as e:
+            task, problem = None, str(e)
+        if task is not None:
+            session = task_session(task)
+            recap = read_claude_recap(session.path) if session else None
+    notes = manager.read_epic_note(epic, name)
+    return EpicLogEntry(
+        task=name,
+        role=role,
+        notes_path=manager.epic_note_path(epic, name),
+        notes=notes[0] if notes else None,
+        notes_truncated=bool(notes and notes[1]),
+        session=session,
+        recap=recap,
+        problem=problem,
+    )