@bumpyclock/pi-tasque 0.1.0 → 0.2.0

package/README.md

@@ -1,15 +1,15 @@
 # pi-tasque
 
-Pi extension package for Tasque durable tasks plus branch-replayed in-session todos.
+Pi extension for durable project tasks plus in-session todos.
 
 ## What this package provides
 
 `pi-tasque` gives agents two task layers:
 
-- **Session todos**: current-session execution checklist for inspect/edit/verify/handoff steps.
-- **Durable Tasque tasks**: repo-local backlog, specs, dependencies, notes, and ownership through `tsq --format json`.
+- **Session todos**: current-session execution checklist for inspect, edit, verify, and handoff steps.
+- **Durable tasks**: repo-local backlog, specs, dependencies, notes, and ownership.
 
-The bridge between the layers is explicit. `pi-tasque` can link, promote, or import tasks, but it does **not** automatically sync lifecycle state between todos and Tasque.
+The bridge between the layers is explicit. `pi-tasque` can link, promote, or import tasks, but it does **not** automatically sync lifecycle state between todos and durable tasks.
 
 ## Install
 
@@ -33,52 +33,23 @@ edit TypeScript files -> /reload -> test behavior
 
 Pi loads the extension entrypoint from the installed package path, so TypeScript source edits do not require reinstalling the local package. Use `/reload` in the Pi session after changing files under `src/`.
 
-### Remove `@juicesharp/rpiv-todo`
-
-Remove or disable `@juicesharp/rpiv-todo` before enabling `pi-tasque`:
-
-```bash
-pi remove npm:@juicesharp/rpiv-todo
-```
-
-`pi-tasque` owns the same user-facing session todo surface:
-
-- `todo` tool
-- `/todos` command
-- above-editor todo overlay
-
-Running both packages together can register duplicate tools, commands, or widgets.
-
 ## Agent guidance
 
-Use the smallest task layer that matches the work:
-
-- Use `todo` for tactical steps inside the current session: inspect, edit, verify, and handoff.
-- Use `tsq_query` for fresh read-only Tasque state.
-- Use `tsq_change` for explicit durable Tasque mutations, including lifecycle changes and block/order edges.
-- Use `block`/`unblock` for hard dependency edges and `order`/`unorder` for sequencing edges via `tsq_change`.
-- Use `tsq_claim` when taking ownership of a named durable Tasque task.
-- Pass an explicit `assignee` when the agent has a role/name, such as `developer`, `oracle`, or a worker name.
-- If no `assignee` is provided, `tsq_claim` defaults to `pi`.
-- `tsq_claim` defaults `start` to true. Use `requireSpec` when the durable task must have an attached spec before work begins.
-- Use `tsq_claim` with `createTodo: true` when claiming durable work should also create one linked session todo.
-- Use `task_bridge promote_todo` when a session todo should become durable Tasque work.
-- Use `task_bridge import_tsq` when a durable Tasque task should become current-session todo work.
-- Do not create durable Tasque tasks for every session todo.
-- Do not mark a Tasque task done just because linked todos are completed; durable completion requires explicit verification and an explicit Tasque mutation.
+Use `todo` for current-session checklists; use `task` for durable project work, ownership, notes, specs, dependencies, and explicit todo links.
 
 ## Lifecycle boundaries
 
-There is no automatic lifecycle sync between session todos and Tasque:
+There is no automatic lifecycle sync between session todos and durable tasks:
 
-- Completing a `todo` does not mark a Tasque task done.
-- Marking a Tasque task done does not complete linked todos.
-- `task_bridge link` records a relationship only.
-- `task_bridge promote_todo` creates a Tasque task, links it, and completes the source todo as part of the explicit promotion flow.
-- `task_bridge import_tsq` creates or reuses session todos for Tasque tasks, but later status changes remain explicit.
+- Completing a `todo` does not mark a durable task done.
+- Marking a durable task done does not complete linked todos.
+- `task` link actions record relationships only.
+- `task` promote/import actions are explicit bridge operations.
 
 ## Example workflow
 
+Create a session todo:
+
 ```json
 {
   "action": "create",
@@ -87,43 +58,51 @@ There is no automatic lifecycle sync between session todos and Tasque:
 }
 ```
 
+Claim durable work and create one linked todo:
+
 ```json
-{ "id": "tsq-349aqgsj.12", "assignee": "developer", "createTodo": true }
+{
+  "action": "claim",
+  "task": "task-123",
+  "for": "developer",
+  "todo": true
+}
 ```
 
+List links:
+
 ```json
 { "action": "list_links" }
 ```
 
+Finish durable work after verification:
+
 ```json
 {
-  "action": "done",
-  "id": "tsq-349aqgsj.12",
-  "note": "Verified docs and package checks."
+  "action": "finish",
+  "task": "task-123",
+  "because": "Docs and package checks passed."
 }
 ```
 
-## v1 tool and command reference
+## Tool and command reference
 
-| Surface              | Purpose                                       | Notes                                                           |
-| -------------------- | --------------------------------------------- | --------------------------------------------------------------- |
-| `todo`               | Manage current-session tactical todos.        | Session-local; branch-replayed from successful tool results.    |
-| `/todos`             | Show grouped current-session todos.           | Interactive UI only.                                            |
-| `tsq_query`          | Read fresh Tasque state.                      | Read-only; does not mutate Tasque.                              |
-| `tsq_change`         | Run explicit durable Tasque mutations.        | Mutations are queued per cwd.                                   |
-| `tsq_claim`          | Claim a named durable Tasque task.            | `id` required; `assignee` defaults `pi`; `start` defaults true. |
-| `task_bridge`        | Link/promote/import between todos and Tasque. | Explicit bridge only; no automatic lifecycle sync.              |
-| Todo overlay         | Show active session todos above the editor.   | Completed todos hide on next turn.                              |
-| Tasque status footer | Show cached durable-task status.              | Display-only; agents should call `tsq_query` for fresh data.    |
+| Surface            | Purpose                                      | Notes                                                              |
+| ------------------ | -------------------------------------------- | ------------------------------------------------------------------ |
+| `todo`             | Manage current-session tactical todos.       | Session-local; replayed from successful `todo` and `task` results. |
+| `/todos`           | Show grouped current-session todos.          | Interactive UI only.                                               |
+| `task`             | Manage durable project tasks and todo links. | Resolves operations to the current git project root.               |
+| Todo overlay       | Show active session todos above the editor.  | Completed todos hide on the next turn.                             |
+| Task status footer | Show cached durable-task status.             | Display-only; agents should call `task` for fresh data.            |
 
 ### `todo`
 
-Manage current-session tactical todos. Todos are branch-replayed from previous successful `todo` results in the current session branch.
+Manage current-session todos. Todos are branch-replayed from previous successful `todo` results in the current session branch.
 
 Actions:
 
-- `create`: add a todo.
-- `update`: change status, text, owner, metadata, or dependencies.
+- `create`: add a todo, with optional description, owner, metadata, and blockers.
+- `update`: change status, text, owner, metadata, or dependencies with `blockedBy`, `addBlockedBy`, and `removeBlockedBy`.
 - `list`: list visible todos; deleted tombstones are hidden unless `includeDeleted` is true.
 - `get`: fetch one todo by id.
 - `delete`: tombstone one todo.
@@ -160,151 +139,200 @@ Example:
 
 ### Above-editor todo overlay
 
-Shows active session todos above the editor. The overlay rebuilds from branch replay on session lifecycle events and updates after successful `todo`, `task_bridge`, and `tsq_claim` executions that affect todo state.
+Shows active session todos above the editor. The overlay rebuilds on session start, compaction, and tree switches, then updates after successful `todo` and `task` executions that affect todo state.
 
 Completed todos remain visible until the next turn, then hide from the overlay.
 
-### `tsq_query`
+### `task`
 
-Run read-only Tasque queries through `tsq --format json`. Use this for fresh durable task state without mutating Tasque.
+Manage durable project tasks. Most durable task operations run from the current git project root; `handoff_check` resolves the root only when linked todos exist.
 
-Actions:
+Read actions:
 
-- `doctor`
-- `find_ready`
-- `find_open`
-- `show`
-- `show_with_spec`
-- `deps`
-- `notes`
-- `find_tree`
-- `similar`
+- `doctor`: check task-system health.
+- `find`: find `ready` or `open` tasks. `lane` applies only to `ready`; use `view: "tree"` for an open-task tree. With `view: "tree"`, `task` filters the tree to a parent task.
+- `show`: show one task. Use `with: ["spec"]` to include spec content in the display.
+- `deps`: show dependency tree for one task.
+- `notes`: show notes for one task.
+- `similar`: search for similar tasks by text.
+- `handoff_check`: check whether current-session todos and linked durable tasks are ready for final handoff. Not-ready returns `ok: true, ready: false`; internal failures return `ok: false`.
+- `spec`: operate on the spec attached to a task. `mode` is required and must be `show`, `check`, `set`, or `update`.
+  - `show` returns the attached spec content.
+  - `check` validates the attached spec against the task. Returns `ok: true` when validation passes; returns `ok: false` with `error.code: "spec_check_failed"` and diagnostics when validation fails.
+  - `set` attaches a new spec using the `text` field. Overwrites any existing spec.
+  - `update` updates the existing spec using the `text` field.
+  - `text` is required for `set` and `update`; rejected for `show` and `check`.
+  - `show` and `check` are read-only. `set` and `update` are mutations serialized through the per-project queue.
 
-Examples:
+**`show` with `with:["spec"]` vs `spec` action:** `show` with `with:["spec"]` includes spec content as extra context in the task display — useful for reading the spec alongside other task fields. The `spec` action with `mode:"show"` returns spec content alone; `spec` action with `mode:"check"` validates the attached spec and reports pass/fail with diagnostics. Use `show` for display context, `spec check` for validation.
 
-```json
-{ "action": "find_ready", "lane": "coding", "assignee": "developer" }
-```
+**Failed check semantics:** When `spec check` reports validation failures, the tool result has `details.ok: false`, `error.code: "spec_check_failed"`, and a `details.diagnostics` object with the issues. The CLI process exits successfully (no thrown error); the failure is reported in structured details so agents can inspect and react to individual check failures without catching exceptions.
 
-```json
-{ "action": "show_with_spec", "id": "tsq-349aqgsj.12" }
-```
+**Handoff check semantics:** `handoff_check` is read-only. It checks pending/in-progress/blocked todos plus linked durable task status. `closed` linked tasks are ready; `open`, `in_progress`, `blocked`, `deferred`, and unknown statuses block handoff; `canceled` is a warning. Missing/invalid linked tasks are reported as `readErrors` with `ready:false`.
 
-### `tsq_change`
+Mutation actions:
 
-Run approved durable Tasque mutations. Mutations are queued per working directory so concurrent agents do not race `tsq` writes.
+- `create`: create a durable task, with optional `description`, `under`, `planned`, or `needsPlan`.
+- `note`: add a note.
+- `finish`: mark done.
+- `reopen`: reopen a task.
+- `defer`: defer a task.
+- `start`: mark started.
+- `claim`: assign ownership; `start` defaults to true, `requireSpec` enforces an attached spec, and `todo: true` creates one linked session todo.
+- `block` / `unblock`: manage hard blocker edges.
+- `order` / `unorder`: manage sequencing edges.
 
-Actions:
+Lifecycle mutation actions:
 
-- `create`
-- `note`
-- `done`
-- `reopen`
-- `defer`
-- `start`
-- `claim_assign_only`
-- `block`: make `child` blocked by `blocker`.
-- `unblock`: remove a block edge between `child` and `blocker`.
-- `order`: make `later` start after `earlier`.
-- `unorder`: remove an order edge between `later` and `earlier`.
+- `mark_planned`: mark an existing task as planned. Requires `task` (non-empty id). Runs through the mutation queue.
 
-Use `block` for hard blockers and `order` for sequencing. Use `tsq_query` with `deps` or `show` to inspect durable graph state. Edge actions cannot create self-edges.
+Batch actions:
+
+- `bulk`: run multiple lifecycle/note mutations sequentially with fail-fast semantics. Requires `items` — an array of `{ action, task, because? }` objects. Supported item actions: `start`, `finish`, `reopen`, `defer`, `note`, `mark_planned`. `because` is required for `note`, optional for `finish`/`defer`. On first failure, remaining items are skipped. No rollback of completed mutations. Result details contain `completed` (task ids), optional `failed` (task + error), and `skipped` (task ids).
+- `create_tree`: create a nested tree of durable tasks in one call. Requires `root` — a node object `{ title, kind, priority, description?, planned?, needsPlan?, children? }`. Children are recursive nodes. Creates parent before children, wiring generated parent ids. On first failure, remaining subtree is skipped — no orphan children are created. No rollback. Result details contain `created` (id + title), optional `failed` (title + error), and `skipped` (titles).
+
+Bridge actions:
+
+- `link`: associate an existing todo with an existing durable task via todo metadata.
+- `list_links`: inspect current todo ↔ durable task associations.
+- `promote`: create a durable task from an existing todo, add a promotion note, link metadata, and complete the source todo.
+- `import`: import a durable task, or an open-tree task plus children when available, into session todos with metadata links. `to` currently accepts only `"todo"`.
 
 Examples:
 
 ```json
-{
-  "action": "note",
-  "id": "tsq-349aqgsj.12",
-  "note": "README docs updated; running verification."
-}
+{ "action": "find", "tasks": "ready", "lane": "coding", "for": "developer" }
 ```
 
 ```json
-{
-  "action": "done",
-  "id": "tsq-349aqgsj.12",
-  "note": "Docs and typecheck/test verification passed."
-}
+{ "action": "find", "view": "tree", "task": "task-parent" }
 ```
 
 ```json
-{ "action": "block", "child": "tsq-abc123.2", "blocker": "tsq-abc123.1" }
+{ "action": "show", "task": "task-123", "with": ["spec"] }
 ```
 
 ```json
-{ "action": "order", "later": "tsq-abc123.3", "earlier": "tsq-abc123.2" }
+{ "action": "spec", "task": "task-123", "mode": "show" }
 ```
 
-### `tsq_claim`
-
-Claim a named durable Tasque task. This never auto-selects work; callers must provide the task id. `start` defaults to true, `assignee` defaults to `pi`, and `createTodo` optionally creates one linked session todo for the claimed task.
-
-Example:
+```json
+{ "action": "spec", "task": "task-123", "mode": "check" }
+```
 
 ```json
 {
-  "id": "tsq-349aqgsj.12",
-  "assignee": "developer",
-  "requireSpec": true,
-  "createTodo": true
+  "action": "spec",
+  "task": "task-123",
+  "mode": "set",
+  "text": "# Spec\n\nAcceptance criteria..."
 }
 ```
 
-### `task_bridge`
-
-Explicitly connect session todos and durable Tasque tasks. Bridge actions do not create implicit lifecycle sync.
-
-Actions:
+```json
+{
+  "action": "spec",
+  "task": "task-123",
+  "mode": "update",
+  "text": "## Updated section\n\nRevised details..."
+}
+```
 
-- `link`: associate an existing todo with an existing Tasque task via todo metadata.
-- `list_links`: inspect current session todo ↔ Tasque associations.
-- `promote_todo`: create a Tasque task from an existing todo, add a promotion note, link metadata, and complete the source todo.
-- `import_tsq`: import a Tasque task, or an open-tree task plus children when available, into session todos with `tsqId` metadata links.
+```json
+{ "action": "mark_planned", "task": "task-456" }
+```
 
-Link example:
+```json
+{
+  "action": "bulk",
+  "items": [
+    { "action": "finish", "task": "task-1", "because": "Verified" },
+    { "action": "start", "task": "task-2" },
+    { "action": "mark_planned", "task": "task-3" }
+  ]
+}
+```
 
 ```json
-{ "action": "link", "todoId": 3, "tsqId": "tsq-349aqgsj.12" }
+{
+  "action": "create_tree",
+  "root": {
+    "title": "Add auth module",
+    "kind": "task",
+    "priority": 2,
+    "planned": true,
+    "children": [
+      {
+        "title": "Design auth API",
+        "kind": "task",
+        "priority": 2,
+        "needsPlan": true
+      },
+      { "title": "Implement token refresh", "kind": "task", "priority": 3 }
+    ]
+  }
+}
 ```
 
-Promote example:
+```json
+{ "action": "handoff_check" }
+```
 
 ```json
 {
-  "action": "promote_todo",
-  "todoId": 4,
+  "action": "create",
+  "task": "Add cwd guard tests",
   "kind": "task",
   "priority": 2,
-  "assignee": "developer",
-  "parent": "tsq-349aqgsj"
+  "under": "task-parent",
+  "planned": true
 }
 ```
 
-Import example:
+```json
+{ "action": "block", "task": "task-child", "by": "task-blocker" }
+```
 
 ```json
-{ "action": "import_tsq", "tsqId": "tsq-349aqgsj.12", "owner": "developer" }
+{ "action": "order", "task": "task-later", "after": "task-earlier" }
 ```
 
-List links example:
+```json
+{ "action": "link", "todo": 3, "task": "task-123" }
+```
 
 ```json
-{ "action": "list_links" }
+{
+  "action": "promote",
+  "todo": 4,
+  "kind": "task",
+  "priority": 2,
+  "under": "task-parent",
+  "for": "developer"
+}
+```
+
+```json
+{
+  "action": "import",
+  "task": "task-123",
+  "to": "todo",
+  "for": "developer"
+}
 ```
 
-### Tasque status footer
+### Task status footer
 
-The status footer shows cached Tasque status in interactive UI:
+The status footer shows cached durable-task status in interactive UI:
 
 - ready coding count
 - ready planning count
-- `mine` count for tasks assigned to `pi`
+- `mine` count for in-progress tasks assigned to `pi`
 - loading, stale, and error states
 
-It refreshes on session start, periodically, and after successful durable mutations from `tsq_change`, `tsq_claim`, or `task_bridge`.
+It refreshes on session start, periodically, and after successful durable mutations from `task`.
 
-The footer is display-only. Refreshed status is not injected into the model context; agents should use `tsq_query` for fresh durable task data. If agents claim with a non-`pi` assignee, those tasks may not appear in the footer's `mine` count.
+The footer is display-only. Refreshed status is not injected into the model context; agents should use `task` for fresh durable task data. If agents claim with a non-`pi` assignee, those tasks may not appear in the footer's `mine` count.
 
 ## Verification
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bumpyclock/pi-tasque",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi extension package for Tasque durable tasks plus in-session todos.",
   "type": "module",
   "license": "MIT",
@@ -12,18 +12,35 @@
     "url": "https://github.com/BumpyClock/pi-tasque/issues"
   },
   "homepage": "https://github.com/BumpyClock/pi-tasque#readme",
-  "keywords": ["pi-package", "pi-extension", "tasque", "tsq", "todo"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "tasque",
+    "tsq",
+    "todo"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "bump:patch": "node scripts/bump-version.js patch",
+    "bump:minor": "node scripts/bump-version.js minor",
+    "bump:major": "node scripts/bump-version.js major",
+    "bump:set": "node scripts/bump-version.js"
   },
-  "files": ["src/", "README.md", "LICENSE", "NOTICE.md"],
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "pi": {
-    "extensions": ["./src/index.ts"]
+    "extensions": [
+      "./src/index.ts"
+    ]
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -35,5 +52,6 @@
     "@types/node": "latest",
     "typescript": "latest",
     "vitest": "latest"
-  }
+  },
+  "packageManager": "npm@11.12.0"
 }

package/src/bridge/bridge-tool.ts

@@ -4,6 +4,10 @@ import {
 	type ExtensionAPI,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import {
+	TASK_TODO_BRIDGE_PROMPT_GUIDELINES,
+	TASK_TODO_BRIDGE_PROMPT_SNIPPET,
+} from "../guidelines/internal-tools.js";
 import {
 	errorToolDetails,
 	okToolDetails,
@@ -32,18 +36,11 @@ export function registerTaskBridgeTool(
 	pi.registerTool(
 		defineTool({
 			name: TASK_BRIDGE_TOOL_NAME,
-			label: "Task Bridge",
+			label: "Task Todo Bridge",
 			description:
-				"Explicitly link, list, promote, or import between session todos and durable Tasque tasks. No automatic lifecycle sync.",
-			promptSnippet:
-				"task_bridge links, lists, promotes, and imports between session todos and durable Tasque tasks; it never auto-completes one layer from the other.",
-			promptGuidelines: [
-				"Use link to associate an existing todo with an existing Tasque task via todo metadata tsqId.",
-				"Use list_links to inspect current session todo ↔ Tasque associations.",
-				"Use promote_todo to create a Tasque task from a todo and link the promoted todo explicitly.",
-				"Use import_tsq to create or reuse session todos from Tasque task state and link them explicitly.",
-				"Todo completion does not mark Tasque done; durable completion stays explicit.",
-			],
+				"Link session todos and durable tasks. No automatic lifecycle sync.",
+			promptSnippet: TASK_TODO_BRIDGE_PROMPT_SNIPPET,
+			promptGuidelines: TASK_TODO_BRIDGE_PROMPT_GUIDELINES,
 			parameters: TaskBridgeParamsSchema,
 			executionMode: "sequential",
 
@@ -83,7 +80,7 @@ export async function executeTaskBridge(
 		default:
 			return errorResult(
 				"validation_error",
-				"action must be a supported task_bridge action",
+				"action must be a supported task/todo bridge action",
 			);
 	}
 }
@@ -160,7 +157,7 @@ function notImplementedResult(
 ): AgentToolResult<TaskBridgeDetails> {
 	return errorResult(
 		"not_implemented",
-		`task_bridge action ${action} handler is not configured`,
+		`task/todo bridge action ${action} handler is not configured`,
 	);
 }
 

package/src/bridge/types.ts

@@ -23,61 +23,60 @@ export const TaskBridgeParamsSchema = Type.Object(
 	{
 		action: StringEnum(TASK_BRIDGE_ACTIONS, {
 			description:
-				"Explicit bridge operation between session todo state and durable Tasque tasks.",
+				"Explicit bridge operation between session todo state and durable tasks.",
 		}),
 		todoId: Type.Optional(
 			Type.Integer({
 				description:
-					"Session todo id. Required for link and promote_todo actions.",
+					"Session todo id. Required when linking or promoting a todo.",
 				minimum: 1,
 			}),
 		),
 		tsqId: Type.Optional(
 			Type.String({
 				description:
-					"Durable Tasque task id. Required for link and import_tsq actions.",
+					"Durable task id. Required when linking or importing a task.",
 			}),
 		),
 		assignee: Type.Optional(
 			Type.String({
 				description:
-					"Agent/owner name used by promote_todo/import_tsq bridge actions.",
+					"Agent/owner name used when creating or importing linked task todos.",
 			}),
 		),
 		owner: Type.Optional(
 			Type.String({
-				description: "Todo owner used by import_tsq bridge action.",
+				description: "Todo owner used when importing a durable task.",
 			}),
 		),
 		kind: Type.Optional(
 			Type.String({
-				description: "Tasque task kind used by promote_todo bridge action.",
+				description: "Durable task kind used when promoting a todo.",
 			}),
 		),
 		priority: Type.Optional(
 			Type.Integer({
-				description: "Tasque priority used by promote_todo bridge action.",
+				description: "Durable task priority used when promoting a todo.",
 			}),
 		),
 		description: Type.Optional(
 			Type.String({
-				description: "Description override used by promote_todo bridge action.",
+				description: "Description override used when promoting a todo.",
 			}),
 		),
 		parent: Type.Optional(
 			Type.String({
-				description:
-					"Parent Tasque task id used by promote_todo bridge action.",
+				description: "Parent durable task id used when promoting a todo.",
 			}),
 		),
 		planned: Type.Optional(
 			Type.Boolean({
-				description: "Planning flag used by promote_todo bridge action.",
+				description: "Planning flag used when promoting a todo.",
 			}),
 		),
 		needsPlan: Type.Optional(
 			Type.Boolean({
-				description: "Planning flag used by promote_todo bridge action.",
+				description: "Planning flag used when promoting a todo.",
 			}),
 		),
 	},