task-agent 1.0.3__tar.gz → 1.0.9__tar.gz

task_agent-1.0.9/.gemini/settings.json

@@ -0,0 +1,22 @@
+{
+  "mcpServers": {
+    "task-agent": {
+      "command": "ta",
+      "args": [
+        "mcp"
+      ],
+      "trust": true
+    },
+    "task_agent": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--project",
+        "/home/mstouffer/repos/task-agent",
+        "ta",
+        "mcp"
+      ],
+      "trust": true
+    }
+  }
+}

{task_agent-1.0.3 → task_agent-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: task-agent
-Version: 1.0.3
+Version: 1.0.9
 Summary: A prioritized, file-based task queue for autonomous agentic workers
 Author-email: Mark Stouffer <1802850+InTEGr8or@users.noreply.github.com>
 License: MIT

{task_agent-1.0.3 → task_agent-1.0.9}/docs/README.md

@@ -12,6 +12,8 @@ Welcome to the comprehensive documentation for **Task Agent**, a prioritized, fi
   - Best practices for managing tasks from draft to completion.
 - [**Development**](./development/README.md)
   - Information on project setup, testing, and release processes.
+- [**Station Map**](./STATION-MAP.md)
+  - Formal declaration of task-agent as a typed file-path station system: stations, transitions, edge roles, and conformance gaps.
 
 ## 🚀 Quick Start
 

task_agent-1.0.9/docs/STATION-MAP.md

@@ -0,0 +1,154 @@
+# task-agent Station Map
+
+> **Status: RATIFIED — installed at `docs/STATION-MAP.md` on 2026-07-15.**
+>
+> This document declares task-agent as an instance of the typed file-path-queue substrate
+> ("a typed state machine where the states are portable file paths") whose vocabulary is
+> owned by the library design spec in the cocli repo (task:
+> `design-spec-for-reusable-typed-file-path-queue-transformer-library-extracted-from-cocli`;
+> thesis: cocli `docs/DESCRIPTION.md`). Do not fork terminology here — if a term is missing,
+> add it to the spec, then use it.
+>
+> Sections marked **observed** describe the implementation as found on 2026-07-12.
+> Sections marked **declared (v1)** are proposals ratified on 2026-07-15.
+
+## 1. Record type (observed)
+
+One task = one directory, named by **slug**, containing `README.md`
+(Markdown body + YAML frontmatter, currently `created_at` only). The runtime model is
+`Issue` (`src/taskagent/models/issue.py`): `name`, `slug`, `blocked_by: List[str]`,
+`subtask_of: Optional[str]`, with `priority` and `status` derived at runtime.
+Serialization to the index is USV (`\x1f`-delimited).
+
+Edge fields are persisted as **body prose**, regex-extracted (`manager.py` ~582):
+`**Blocked by:**` for ordering dependencies, `**Subtask of:**` for hierarchy.
+
+**Declared (v1):** edge fields move to structured frontmatter (`blocked_by:`,
+`subtask_of:` YAML lists); prose-line reader extracts values at runtime.
+Frontmatter is the schema; prose is presentation.
+
+## 2. Stations (observed)
+
+Root: `.task-agent/tasks/` (symlinked at `docs/tasks/`).
+
+| Station | Record state | Sharding | Notes |
+| :--- | :--- | :--- | :--- |
+| `draft/` | intention, not yet actionable | flat | |
+| `pending/` | actionable, unclaimed | flat | |
+| `active/` | claimed by a worker | flat | |
+| `completed/` | terminal fact | by year (`2026/`) | month-sharding is a pending task |
+| `deleted/` | terminal, rejected | flat | tombstone station |
+| `mr/` | merge request datagram | by year | **Declared (v1):** task-machine station (see §2a) |
+| `strategy/`, `plan.md` | mission-level records | — | not task records; out of scope of the task state machine |
+
+**Declared (v1):** every station binds `(path template, record type, serialization)`.
+`strategy/` and `plan.md` are explicitly **out of scope of the task state machine** —
+they are mission-level documents with their own lifecycle, not task records.
+
+### §2a. `mr/` station (ratified)
+
+**Record type:** Solution datagram — a text file (`<slug>.md`) containing the solution
+explanation written by a worker agent.
+
+**Inbound transition:** A worker that cannot directly commit writes its solution to
+`mr/<slug>.md` instead of calling `ta done`. This is the handoff from the worker's
+isolated environment.
+
+**Outbound transition:** `ta merge <slug>` reads the datagram, calls `complete_issue`,
+moves the task to `completed/`, and unlinks the MR file. This is a full task-machine
+transition (`active/` → `completed/`) mediated by the datagram.
+
+**Conclusion:** `mr/` is a **station of the task machine**, not a separate machine.
+Its records are ephemeral (deleted on merge); they do not need their own durability
+contract beyond the filesystem.
+
+## 3. Transitions (observed)
+
+Typed from-station→to-station moves, all implemented as directory renames:
+
+| Transition | From → To | Notes |
+| :--- | :--- | :--- |
+| `create` | ∅ → `pending/` (or `draft/` with flag) | assigns slug from title |
+| `promote` | `draft/` → `pending/` | cascades along edges |
+| `demote` | reverse of promote | |
+| `start` / mark-active | `pending/` → `active/` | **this is the claim** |
+| `complete` | `active/` → `completed/YYYY/` | terminal |
+| `restore` | `completed/` → active tree | |
+| `delete` | → `deleted/` | tombstone, not erasure |
+| `merge` (via `mr/`) | `mr/<slug>.md` → `complete` | worker handoff path |
+
+**Declared (v1):** each transition is a pure typed transform on the record
+(from-model-to-model); a transition never partially rewrites a record it isn't moving.
+
+## 4. Edge roles: queue / WAL / index (observed + declared)
+
+Roles attach to *consumer edges*, not to directories. Current reading:
+
+- **Queue (future):** `pending/` → worker edge. `start` is the claim; `active/` holds the
+  lease; `completed/`, `deleted/` are terminal states. Single-worker today, so the claim
+  protocol is trivially safe; multi-agent use makes atomic-rename claiming load-bearing.
+- **WAL (past):** `completed/YYYY/` is the fact log of the task machine — append-only,
+  year-partitioned segments, source of truth for history. The pending
+  month-sharding+WAL+compaction task extends exactly this role.
+- **Index (present):** the USV issues index (with `datapackage` field declarations in
+  `manager.py`) is a fold over the station tree; blocked-state computation is a derived
+  view over `blocked_by` edges. Both must be rebuildable by rescanning stations —
+  **stations are the source of truth; the index is disposable.**
+- **Event log:** `AuditLog` (`src/taskagent/audit.py`) writes JSONL lifecycle events to
+  `.task-agent/logs/YYYY-MM-DD.jsonl`, pruned after 30 days.
+  **Ratified:** `AuditLog` is **telemetry**, not a WAL. The station directories are the
+  single source of truth for task state; the JSONL log is observability data only. Pruning
+  after 30 days is correct and intentional. No compaction policy is needed.
+
+## 5. Identity (ratified)
+
+The **directory name (slug)** is the immutable unique identifier of a task, assigned at
+creation from the title and never subsequently derived from mutable fields.
+
+- Editing the `# Title` heading in `README.md` changes the task's *display name* only;
+  the slug (and therefore its station path) is unchanged.
+- Direct directory renaming is **forbidden** as an end-user operation — it breaks the
+  index, `blocked_by`/`subtask_of` references in other tasks, and `completed/` history.
+- A future `ta rename <slug> <new-title>` command is the only supported path for slug
+  migration. It must: rename the directory, update `mission.usv`, and rewrite all
+  `blocked_by`/`subtask_of` references that point to the old slug.
+
+## 6. Conformance gaps (the migration backlog)
+
+Each accepted gap becomes one follow-up task. Written as typed defects against the
+substrate's invariants:
+
+1. **Identity derived from mutable content.** Slug comes from the *original* title;
+   retitling a task changes its display name but not its identity, and lookups by new
+   title fail. Invariant: identity is assigned at creation and never derived from
+   mutable fields. Fix: add a `ta rename` command (see §5).
+2. **Schema data outside the schema.** `blocked_by`/`subtask_of` live as regex-matched
+   prose lines. Move to frontmatter (§1 declared); keep the alias reader through migration.
+3. **Non-atomic record updates.** Content updates (`update_task`) rewrite the body and
+   silently drop edges — a read-modify-write that loses fields the writer didn't know
+   about. Invariant: a record update is a whole-record typed transform; unknown fields
+   round-trip. (This is the bug that repeatedly wiped dependencies on the cocli epic.)
+4. **Station store excluded from its own durability.** `.task-agent` is gitignored in
+   consumer repos, so `commit_tasks` fails and task state stays uncommitted. Declare the
+   durability contract: either the station tree is committed (un-ignore) or durability is
+   explicitly delegated elsewhere.
+5. **Edge-type conflation cleanup.** `blocked_by` (ordering) vs `subtask_of` (hierarchy)
+   are now separate in the `Issue` model with a legacy alias — finish the migration:
+   stored prose lines, docstrings (`create_task` still describes deps as parent-of
+   promotion cascade), and historical records under `completed/`.
+6. **Undeclared station resolved.** `mr/` declared in §2a.
+7. **Log role declared.** `AuditLog` is telemetry (§4).
+8. **Index rebuildability unproven.** No command exists to rebuild the USV index from a
+   station rescan and verify it matches. This is also the seed of the conformance tool:
+   `taskagent audit --conformance` = validate station tree against this map + rebuild
+   index and diff. That tool, once built, becomes the executable `done_check` for every
+   subsequent conformance transform (the portable-task acceptance predicate).
+
+## 7. Relationship to the library spec
+
+task-agent is **dogfood consumer #2** (after cocli). The library spec owns: station/
+transition/edge-role vocabulary, the claim protocol, WAL/compaction semantics,
+fold/watermark semantics, and schema versioning. This map owns only: which stations
+exist here, their record types, and this repo's conformance state. When the library's
+Protocol interfaces land, task-agent's `manager.py` should be refactorable to implement
+them with no on-disk change — that refactor being cheap is the test that this map is true.

{task_agent-1.0.3 → task_agent-1.0.9}/docs/architecture/README.md

@@ -35,7 +35,7 @@ Task Agent supports two ways to store task content:
 
 ## 🔗 Dependencies
 
-Tasks can depend on one or more other tasks using the `**Depends on:** slug1, slug2` syntax within their Markdown descriptions. Task Agent uses this to provide a hierarchical view in `ta list`.
+Tasks can specify ordering dependencies using the `**Blocked by:** slug1, slug2` syntax within their Markdown descriptions. Task Agent uses this to provide a hierarchical view in `ta list`.
 
 ## 🔒 File Protection
 

task_agent-1.0.9/opencode.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "task_agent": {
+      "type": "local",
+      "command": [
+        "uv",
+        "run",
+        "--project",
+        "/home/mstouffer/repos/task-agent",
+        "ta",
+        "mcp"
+      ]
+    }
+  }
+}

{task_agent-1.0.3 → task_agent-1.0.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "task-agent"
-version = "1.0.3"
+version = "1.0.9"
 description = "A prioritized, file-based task queue for autonomous agentic workers"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -39,7 +39,7 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "1.0.3"
+current_version = "1.0.9"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "version = \"{current_version}\""

{task_agent-1.0.3 → task_agent-1.0.9}/src/taskagent/cli.py

@@ -586,31 +586,10 @@ def cmd_search(console: Console, manager: TaskAgent, pattern: str):
             matches.append(i)
 
     # Always search completed tasks too
-    completed_root = manager.issues_root / "completed"
-    if completed_root.exists():
-        for year_dir in sorted(completed_root.iterdir(), reverse=True):
-            if year_dir.is_dir():
-                for f in year_dir.glob("*.md"):
-                    if fuzzy_match(f.stem, pat_norm):
-                        name = manager.extract_title(f)
-                        matches.append(
-                            Issue(
-                                name=name, slug=f.stem, status="completed", priority=0
-                            )
-                        )
-                for d in year_dir.iterdir():
-                    if d.is_dir():
-                        readme = d / "README.md"
-                        if readme.exists() and fuzzy_match(d.name, pat_norm):
-                            name = manager.extract_title(readme)
-                            matches.append(
-                                Issue(
-                                    name=name,
-                                    slug=d.name,
-                                    status="completed",
-                                    priority=0,
-                                )
-                            )
+    for f, slug in manager.walk_completed():
+        if fuzzy_match(slug, pat_norm):
+            name = manager.extract_title(f)
+            matches.append(Issue(name=name, slug=slug, status="completed", priority=0))
 
     if not matches:
         console.print(f"[yellow]No issues match pattern '{pattern}'.[/yellow]")
@@ -703,46 +682,20 @@ def cmd_search(console: Console, manager: TaskAgent, pattern: str):
                         issues = manager.load_mission()
                         matches = [i for i in issues if fuzzy_match(i.slug, pat_norm)]
                         # Also re-search completed
-                        completed_root = manager.issues_root / "completed"
                         new_matches: List[Issue] = list(matches)
-                        if completed_root.exists():
-                            for year_dir in sorted(
-                                completed_root.iterdir(), reverse=True
+                        for f, slug in manager.walk_completed():
+                            if fuzzy_match(slug, pat_norm) and not any(
+                                m.slug == slug for m in new_matches
                             ):
-                                if year_dir.is_dir():
-                                    for f in year_dir.glob("*.md"):
-                                        if fuzzy_match(f.stem, pat_norm) and not any(
-                                            m.slug == f.stem for m in new_matches
-                                        ):
-                                            name = manager.extract_title(f)
-                                            new_matches.append(
-                                                Issue(
-                                                    name=name,
-                                                    slug=f.stem,
-                                                    status="completed",
-                                                    priority=0,
-                                                )
-                                            )
-                                    for d in year_dir.iterdir():
-                                        if d.is_dir():
-                                            readme = d / "README.md"
-                                            if (
-                                                readme.exists()
-                                                and fuzzy_match(d.name, pat_norm)
-                                                and not any(
-                                                    m.slug == d.name
-                                                    for m in new_matches
-                                                )
-                                            ):
-                                                name = manager.extract_title(readme)
-                                                new_matches.append(
-                                                    Issue(
-                                                        name=name,
-                                                        slug=d.name,
-                                                        status="completed",
-                                                        priority=0,
-                                                    )
-                                                )
+                                name = manager.extract_title(f)
+                                new_matches.append(
+                                    Issue(
+                                        name=name,
+                                        slug=slug,
+                                        status="completed",
+                                        priority=0,
+                                    )
+                                )
                         matches = new_matches
                         if cursor >= len(matches):
                             cursor = max(0, len(matches) - 1)
@@ -766,23 +719,7 @@ def cmd_search(console: Console, manager: TaskAgent, pattern: str):
 
 def cmd_history(console: Console, manager: TaskAgent, limit: int = 20):
     """Show completed tasks in reverse chronological order."""
-    completed_root = manager.issues_root / "completed"
-    if not completed_root.exists():
-        console.print("[yellow]No completed tasks found.[/yellow]")
-        return
-
-    all_completed: List[Tuple[Path, str]] = []
-
-    for year_dir in completed_root.iterdir():
-        if not year_dir.is_dir():
-            continue
-        for f in year_dir.glob("*.md"):
-            all_completed.append((f, f.stem))
-        for d in year_dir.iterdir():
-            if d.is_dir():
-                readme = d / "README.md"
-                if readme.exists():
-                    all_completed.append((readme, d.name))
+    all_completed = manager.walk_completed()
 
     if not all_completed:
         console.print("[yellow]No completed tasks found.[/yellow]")
@@ -1739,7 +1676,6 @@ def cmd_new(
     title: Optional[str],
     body: str,
     draft: bool,
-    depends_on: Optional[str] = None,
     as_dir: bool = True,
     completion_criteria: Optional[str] = None,
     interactive: bool = False,
@@ -1775,7 +1711,7 @@ def cmd_new(
 
                 t_body = t.get("body", "")
                 t_draft = t.get("draft", draft)
-                t_blocked_by = t.get("blocked_by") or t.get("depends_on")
+                t_blocked_by = t.get("blocked_by")
                 t_subtask_of = t.get("subtask_of")
                 t_as_dir = t.get("as_dir", as_dir)
 
@@ -1783,7 +1719,6 @@ def cmd_new(
                     title=t_title,
                     body=t_body,
                     draft=t_draft,
-                    depends_on=t_blocked_by,
                     as_dir=t_as_dir,
                     completion_criteria=t_criteria,
                     blocked_by=t_blocked_by,
@@ -1809,7 +1744,7 @@ def cmd_new(
         temp_file = temp_dir / "README.md"
 
         # Resolve relations for the template
-        final_blocked_by = blocked_by if blocked_by is not None else (depends_on or "")
+        final_blocked_by = blocked_by or ""
         final_subtask_of = subtask_of or ""
 
         created_at = datetime.now().astimezone().isoformat()
@@ -1856,7 +1791,6 @@ created_at: {created_at}
             title=title,
             body=body,
             draft=draft,
-            depends_on=depends_on,
             as_dir=as_dir,
             completion_criteria=completion_criteria,
             blocked_by=blocked_by,
@@ -2142,7 +2076,6 @@ def cmd_update(
     console: Console,
     manager: TaskAgent,
     slug_part: str,
-    depends_on: Optional[str] = None,
     blocked_by: Optional[str] = None,
     subtask_of: Optional[str] = None,
 ):
@@ -2159,10 +2092,9 @@ def cmd_update(
 
     updated = False
     try:
-        # Handle blocked_by / depends_on
-        final_blocked_by = blocked_by if blocked_by is not None else depends_on
-        if final_blocked_by is not None:
-            manager.update_dependencies(target.slug, final_blocked_by)
+        # Handle blocked_by
+        if blocked_by is not None:
+            manager.update_dependencies(target.slug, blocked_by)
             console.print(
                 f"[bold green]Successfully updated prerequisites for task '{target.slug}'.[/bold green]"
             )
@@ -3258,28 +3190,11 @@ def cmd_triage(
         if completed:
             # Load completed issues from disk since they aren't in mission.usv
             all_issues = []
-            completed_root = manager.issues_root / "completed"
-            if completed_root.exists():
-                for year_dir in sorted(completed_root.iterdir(), reverse=True):
-                    if year_dir.is_dir():
-                        # File-based
-                        for f in sorted(year_dir.glob("*.md")):
-                            slug = f.stem
-                            name = manager.extract_title(f)
-                            all_issues.append(
-                                Issue(
-                                    name=name, slug=slug, status="completed", priority=0
-                                )
-                            )
-                        # Directory-based
-                        for d in sorted(year_dir.glob("*/README.md")):
-                            slug = d.parent.name
-                            name = manager.extract_title(d)
-                            all_issues.append(
-                                Issue(
-                                    name=name, slug=slug, status="completed", priority=0
-                                )
-                            )
+            for f, slug in manager.walk_completed():
+                name = manager.extract_title(f)
+                all_issues.append(
+                    Issue(name=name, slug=slug, status="completed", priority=0)
+                )
             issues = all_issues
         else:
             issues = manager.sync_mission()
@@ -3864,11 +3779,6 @@ def main():
         "update", help="Update task properties (e.g. relationships)"
     )
     update_parser.add_argument("slug", help="Slug of the task to update")
-    update_parser.add_argument(
-        "-d",
-        "--depends-on",
-        help="Comma-separated list of task slugs this task depends on (use empty string to clear). Deprecated: use --blocked-by instead.",
-    )
     update_parser.add_argument(
         "--blocked-by",
         help="Comma-separated list of prerequisite task slugs that block this task (use empty string to clear)",
@@ -4087,10 +3997,6 @@ Usage:
     new_parser.add_argument(
         "-i", "--interactive", action="store_true", help="Open editor to fill in task"
     )
-    new_parser.add_argument(
-        "--depends-on",
-        help="Comma-separated slugs this task depends on. Deprecated: use --blocked-by instead.",
-    )
     new_parser.add_argument(
         "--blocked-by",
         help="Comma-separated slugs of prerequisite tasks that block this task, e.g. 'setup-ci,build-artifacts'.",
@@ -4183,7 +4089,6 @@ Usage:
             console,
             manager,
             args.slug,
-            depends_on=args.depends_on,
             blocked_by=args.blocked_by,
             subtask_of=args.subtask_of,
         )
@@ -4254,7 +4159,6 @@ Usage:
             title=args.title,
             body=args.body,
             draft=args.draft,
-            depends_on=args.depends_on,
             as_dir=not args.file,
             completion_criteria=args.criteria,
             interactive=args.interactive,