task-agent 1.0.2__tar.gz → 1.0.5__tar.gz

{task_agent-1.0.2 → task_agent-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: task-agent
-Version: 1.0.2
+Version: 1.0.5
 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.2 → task_agent-1.0.5}/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.5/docs/STATION-MAP.md

@@ -0,0 +1,155 @@
+# 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:**`, `**Subtask of:**`, with legacy `**Depends on:**` read as an alias
+for `blocked_by`.
+
+**Declared (v1):** edge fields move to structured frontmatter (`blocked_by:`,
+`subtask_of:` YAML lists); the prose-line reader remains as an alias-tolerant fallback
+during migration. 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.2 → task_agent-1.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "task-agent"
-version = "1.0.2"
+version = "1.0.5"
 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.2"
+current_version = "1.0.5"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "version = \"{current_version}\""

{task_agent-1.0.2 → task_agent-1.0.5}/src/taskagent/cli.py

@@ -1745,8 +1745,62 @@ def cmd_new(
     interactive: bool = False,
     blocked_by: Optional[str] = None,
     subtask_of: Optional[str] = None,
+    bulk: Optional[str] = None,
 ):
     """Create a new issue."""
+    if bulk:
+        try:
+            if bulk == "-":
+                raw_data = sys.stdin.read()
+            else:
+                raw_data = Path(bulk).read_text(encoding="utf-8")
+
+            tasks = json.loads(raw_data)
+            if not isinstance(tasks, list):
+                raise ValueError("Bulk JSON must be a list/array of task objects.")
+
+            for idx, t in enumerate(tasks):
+                t_title = t.get("title")
+                t_criteria = t.get("completion_criteria")
+                if not t_title:
+                    console.print(
+                        f"[red]Error at task {idx}: 'title' is required.[/red]"
+                    )
+                    continue
+                if not t_criteria:
+                    console.print(
+                        f"[red]Error at task '{t_title}' (index {idx}): 'completion_criteria' is required.[/red]"
+                    )
+                    continue
+
+                t_body = t.get("body", "")
+                t_draft = t.get("draft", draft)
+                t_blocked_by = t.get("blocked_by") or t.get("depends_on")
+                t_subtask_of = t.get("subtask_of")
+                t_as_dir = t.get("as_dir", as_dir)
+
+                issue = manager.create_issue(
+                    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,
+                    subtask_of=t_subtask_of,
+                )
+                console.print(
+                    f"[bold green]Created new issue: {issue.slug}[/bold green]"
+                )
+                issue_file = manager.find_issue_file(issue.slug)
+                console.print(f"File: {issue_file}")
+                if issue.subtask_of:
+                    console.print(f"Subtask of: {issue.subtask_of}")
+            return
+        except Exception as e:
+            console.print(f"[red]Error processing bulk tasks: {e}[/red]")
+            sys.exit(1)
+
     if interactive:
         editor = get_editor()
         slug = manager.slugify(title or "new-task")
@@ -4045,6 +4099,10 @@ Usage:
         "--subtask-of",
         help="Slug of the parent task this task is a subtask of, e.g. 'cli-consolidation'.",
     )
+    new_parser.add_argument(
+        "--bulk",
+        help="Path to a JSON file containing an array of task definitions, or '-' to read JSON from stdin.",
+    )
     version_parser = subparsers.add_parser("version")
     v_sub = version_parser.add_subparsers(dest="version_command")
     p_v = v_sub.add_parser("promote")
@@ -4202,6 +4260,7 @@ Usage:
             interactive=args.interactive,
             blocked_by=args.blocked_by,
             subtask_of=args.subtask_of,
+            bulk=args.bulk,
         )
     elif args.command == "worktree":
         cmd_worktree(console, manager, args)

{task_agent-1.0.2 → task_agent-1.0.5}/src/taskagent/manager.py

@@ -485,7 +485,7 @@ class TaskAgent:
                                 status = issue_file.parent.name
                         else:
                             # Fallback during migration or if file is temporarily gone
-                            status = "pending"
+                            status = "unknown"
 
                         issues.append(
                             Issue(
@@ -538,8 +538,10 @@ class TaskAgent:
             json.dump(datapackage, f, indent=2)
         self._set_writable(dp_path, False)
 
-    def sync_mission(self) -> List[Issue]:
+    def sync_mission(self, ingest: bool = True) -> List[Issue]:
         """Load, sort by status groups, and save back."""
+        if ingest:
+            self.ingest_issues(sync=False)
         issues = self.load_mission()
         if not issues:
             return []
@@ -1428,7 +1430,7 @@ class TaskAgent:
             status="completed",
         )
 
-    def ingest_issues(self) -> Tuple[int, int]:
+    def ingest_issues(self, sync: bool = True) -> Tuple[int, int]:
         """Ingest existing markdown files. Returns (num_new, num_removed)."""
         self.ensure_issues_dir()
 
@@ -1543,7 +1545,8 @@ class TaskAgent:
 
         final_issues = present_issues + new_issues
         self.save_mission(final_issues)
-        self.sync_mission()
+        if sync:
+            self.sync_mission(ingest=False)
 
         return len(new_issues), len(existing_issues) - len(present_issues)
 

{task_agent-1.0.2 → task_agent-1.0.5}/src/taskagent/mcp.py

@@ -455,8 +455,75 @@ def commit_tasks(message: str = "", push: bool = False) -> str:
         return f"Committed: {message}"
     except subprocess.CalledProcessError as e:
         return f"Error: {e.stderr}"
-    except Exception as e:
-        return f"Error: {e}"
+
+
+@mcp.tool()
+def create_tasks(
+    tasks: list[dict],
+) -> str:
+    """Create multiple new tasks in the mission queue at once.
+
+    Args:
+        tasks: A list of task definitions. Each definition is a dictionary that
+            can contain the following keys:
+            - 'title' (str, required): The title of the task.
+            - 'completion_criteria' (str, required): Clear, measurable criteria for task completion.
+            - 'body' (str, optional): Detailed description of the task.
+            - 'draft' (bool, optional): If True, creates the task in 'draft' status. Default is False (pending).
+            - 'blocked_by' (str, optional): Comma-separated list of existing task slugs this task depends on.
+            - 'depends_on' (str, optional): Deprecated alias for blocked_by.
+            - 'subtask_of' (str, optional): Slug of the parent task this task is a subtask of.
+            - 'as_dir' (bool, optional): Create as folder directory. Default is True.
+
+    Returns:
+        A summary report of created task slugs and any errors.
+    """
+    manager = get_manager()
+    created = []
+    errors = []
+
+    for idx, t in enumerate(tasks):
+        title = t.get("title")
+        criteria = t.get("completion_criteria")
+        if not title:
+            errors.append(f"Task at index {idx} is missing required 'title'.")
+            continue
+        if not criteria:
+            errors.append(
+                f"Task '{title}' (index {idx}) is missing required 'completion_criteria'."
+            )
+            continue
+
+        body = t.get("body", "")
+        draft = t.get("draft", False)
+        blocked_by = t.get("blocked_by") or t.get("depends_on")
+        subtask_of = t.get("subtask_of")
+        as_dir = t.get("as_dir", True)
+
+        try:
+            issue = manager.create_issue(
+                title=title,
+                body=body,
+                draft=draft,
+                depends_on=blocked_by,
+                as_dir=as_dir,
+                completion_criteria=criteria,
+                blocked_by=blocked_by,
+                subtask_of=subtask_of,
+            )
+            created.append(f"{issue.slug} (Status: {issue.status})")
+        except Exception as e:
+            errors.append(f"Error creating task '{title}': {e}")
+
+    report = []
+    if created:
+        report.append(
+            "Successfully created tasks:\n" + "\n".join(f"- {c}" for c in created)
+        )
+    if errors:
+        report.append("Errors encountered:\n" + "\n".join(f"- {err}" for err in errors))
+
+    return "\n\n".join(report)
 
 
 def run_mcp_server():

{task_agent-1.0.2 → task_agent-1.0.5}/tests/test_cli.py

@@ -75,6 +75,35 @@ def test_cmd_new_dir(manager, temp_issues_dir):
     assert issues[0].status == "draft"
 
 
+def test_cmd_new_bulk(manager, temp_issues_dir, tmp_path):
+    console = Console()
+    import json
+
+    tasks_data = [
+        {"title": "Bulk 1", "completion_criteria": "CC 1", "body": "Body 1"},
+        {"title": "Bulk 2", "completion_criteria": "CC 2", "draft": True},
+    ]
+
+    json_file = tmp_path / "bulk_tasks.json"
+    json_file.write_text(json.dumps(tasks_data), encoding="utf-8")
+
+    cmd_new(
+        console=console,
+        manager=manager,
+        title=None,
+        body="",
+        draft=False,
+        bulk=str(json_file),
+    )
+
+    issues = manager.load_mission()
+    assert len(issues) == 2
+    assert issues[0].slug == "bulk-1"
+    assert issues[0].status == "pending"
+    assert issues[1].slug == "bulk-2"
+    assert issues[1].status == "draft"
+
+
 def test_cmd_done(manager, temp_issues_dir):
     console = Console()
     cmd_new(console, manager, "Done Task", "Body", draft=False)

{task_agent-1.0.2 → task_agent-1.0.5}/tests/test_manager.py

@@ -187,6 +187,25 @@ def test_api_sync_mission(manager):
     assert issues[1].slug == "task-a"
 
 
+def test_api_sync_mission_auto_ingest(manager):
+    # Create an issue using the manager API (which creates files and adds to mission)
+    manager.create_issue("Task A", draft=False)
+
+    # Simulate a file manually added/created on disk
+    pending_dir = manager.issues_root / "pending" / "task-b"
+    pending_dir.mkdir(parents=True, exist_ok=True)
+    readme = pending_dir / "README.md"
+    readme.write_text("# Task B\n\n## Completion Criteria\n\nCC 2", encoding="utf-8")
+
+    # Sync mission: this should auto-ingest the manually added task-b!
+    issues = manager.sync_mission()
+
+    # Verify both tasks exist and are in the synced issues list
+    slugs = [i.slug for i in issues]
+    assert "task-a" in slugs
+    assert "task-b" in slugs
+
+
 def test_api_demote_issue(manager):
     manager.create_issue("Demote Me")
     # Starts as pending

{task_agent-1.0.2 → task_agent-1.0.5}/tests/test_mcp.py

@@ -44,6 +44,22 @@ def test_mcp_create_task(mock_manager):
     )
 
 
+def test_mcp_create_tasks(mock_manager):
+    mock_manager.create_issue.return_value = Issue(
+        name="Task 1", slug="task-1", status="pending"
+    )
+
+    tasks = [
+        {"title": "Task 1", "completion_criteria": "Must pass tests", "body": "Desc 1"},
+        {"title": "Task 2", "completion_criteria": "Done 2", "draft": True},
+    ]
+
+    result = mcp.create_tasks(tasks)
+    assert "Successfully created tasks:" in result
+    assert "- task-1 (Status: pending)" in result
+    assert mock_manager.create_issue.call_count == 2
+
+
 def test_mcp_mark_task_active(mock_manager):
     mock_manager.slugify.return_value = "task-1"
     result = mcp.mark_task_active("Task 1")
@@ -244,6 +260,7 @@ EXPECTED_TOOLS = {
     "list_tasks",
     "list_active_tasks",
     "create_task",
+    "create_tasks",
     "promote_task",
     "demote_task",
     "mark_task_active",

{task_agent-1.0.2 → task_agent-1.0.5}/uv.lock

@@ -1135,7 +1135,7 @@ wheels = [
 
 [[package]]
 name = "task-agent"
-version = "1.0.2"
+version = "1.0.5"
 source = { editable = "." }
 dependencies = [
     { name = "githubkit" },