@pulsarinteractive/geniustasker 0.1.0-beta.14 → 0.1.0-beta.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.0-beta.15 — 2026-11-17
4
+
5
+ - Add explicit task/run pause and resume commands with a useful reason and resumption point. InProgress now means current identifiable execution; silence, stale leases and unfinished code do not establish activity or a pause. Current service capabilities remain authoritative.
6
+ - Add explicit task-state v2 reads with pause metadata while preserving v1 and legacy response compatibility. Missing, Unknown or incomplete availability never establishes permission to start or finish work.
7
+ - Add bounded per-task checklist reads and typed create, check/uncheck, rename, move and remove commands, including the live-run path. Checkbox progress never completes, resumes or reopens a task, awards XP or requests push. Use separate tickets for independently owned, estimated or scheduled work.
8
+ - Validate generated command data schemas before journaling or sending, including description length and effort limits. Preserve exact saved operations after uncertain replies; no silent rewriting or expanded grants.
9
+
3
10
  ## 0.1.0-beta.14 — 2026-11-17
4
11
 
5
12
  - Add generated task create/update help and task/run lock commands without expanding task permissions. Guides distinguish canonical progress from current availability, preserve dependency locks after manual unlock and require the live run path for a claimed task. Availability and deployment remain server-authoritative.
package/README.md CHANGED
@@ -55,7 +55,7 @@ For a stdio MCP host, use this after signing in:
55
55
  "mcpServers": {
56
56
  "geniustasker": {
57
57
  "command": "npx",
58
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.14", "mcp", "--context", "work"]
58
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.15", "mcp", "--context", "work"]
59
59
  }
60
60
  }
61
61
  }
package/docs/CHATGPT.md CHANGED
@@ -29,6 +29,23 @@ Read current records before changing them. ChatGPT can discover allowed actions,
29
29
 
30
30
  Use **read-only permissions** if you only want summaries. Write access does not grant administration, billing, permission management or access to another person's private data. Existing account limits apply to ChatGPT and the CLI together; connecting another tool does not create a fresh quota.
31
31
 
32
+ When the connected server advertises `tasker_changes`, it can read one bounded
33
+ change page per call using the normal shared read budget. Start with the
34
+ `changeCursor` returned by the final eligible resource page; filtered checklist
35
+ or metric inventories have no change cursor. Preserve the cursor exactly for
36
+ the same scope, collection, archive selection and access context. Apply items
37
+ and removals before saving `nextCursor`. Follow it while `hasMore` is true;
38
+ otherwise respect `pollAfterSeconds` without starting an unbounded polling loop.
39
+ A reset-required refusal means restarting the bounded inventory, not inventing
40
+ a cursor or adding filters.
41
+
42
+ For task availability, explicitly select the capability-advertised `taskState`
43
+ version: v2 only when `taskStateVersions` includes it, otherwise v1 when
44
+ advertised. Omission preserves the legacy response. Absent, Unknown or incomplete
45
+ availability never means a task is available. Any advanced task checkpoint,
46
+ including a removal without a dependent snapshot, invalidates old availability;
47
+ reread the relevant task before starting or completing it.
48
+
32
49
  Disconnecting the plugin in ChatGPT removes its use there. Also revoke its dedicated connection from GeniusTasker's agent settings to invalidate its delegated sessions. Reconnecting requires consent again. This connector never needs your OpenAI API key.
33
50
 
34
51
  ## Language and shared limits
package/docs/CLI.md CHANGED
@@ -128,7 +128,7 @@ launching stdio servers with this entry (adjust environment/context as needed):
128
128
  "mcpServers": {
129
129
  "geniustasker": {
130
130
  "command": "npx",
131
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.14", "mcp", "--context", "work"]
131
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.15", "mcp", "--context", "work"]
132
132
  }
133
133
  }
134
134
  }
@@ -583,14 +583,16 @@ current authorization and semantic validation remain server-side.
583
583
 
584
584
  ## Agent runs
585
585
 
586
- Task create/update and manual lock input schemas are available through
587
- `commands describe --kind task.create` (or `task.update`, `task.lock`,
588
- `task.unlock`, `run.lock`, `run.unlock`). Read
589
- [task locks and current availability](TASK_LOCKS.md) before a lock or unlock.
590
- These source additions are not a claim of npm publication or production rollout.
591
- Use `--task-state v1` on task resource/change/watch reads only after the tasks
592
- collection advertises `taskState: "v1"` in capabilities. Omission preserves the
593
- legacy response shape; the client does not silently request the new projection.
586
+ Task create/update, manual lock and explicit pause input schemas are available
587
+ through `commands describe --kind task.create` (or `task.update`, `task.lock`,
588
+ `task.unlock`, `run.lock`, `run.unlock`, `task.pause`, `task.resume`, `run.pause`,
589
+ `run.resume`). Read [task locks](TASK_LOCKS.md) and [pause/resume](TASK_PAUSES.md)
590
+ before use. Client beta.15 supports pause/v2; check connected-service capabilities.
591
+ Use `--task-state v2` on task resource/change/watch reads only after the tasks
592
+ collection advertises v2 in `taskStateVersions`. Otherwise select v1 only when
593
+ `taskState: "v1"` is advertised. V1 omits the snapshot for Paused tasks; an absent
594
+ snapshot never establishes availability. Omission preserves the legacy response
595
+ shape; the client does not silently request a projection or discover capabilities.
594
596
 
595
597
  Discover the `agentRuns` collection and `run.claim`, `run.checkpoint`, `run.patch`,
596
598
  `run.finish` commands before using them. Inspect each schema with
@@ -620,3 +622,16 @@ window and overlapping instructions without writing. Follow
620
622
  ## Feedback
621
623
 
622
624
  Use [the feedback guide](FEEDBACK.md) for authorized bug reports, feature suggestions, screenshots and final decisions. Availability follows current server capabilities, grants and plan. Preparing a report does not send it; submit after the user’s reporting instruction or agreement.
625
+
626
+ ## Task checklists
627
+
628
+ Read [checklist commands and recovery](TASK_CHECKLISTS.md) before using these
629
+ client beta.15 additions. Discover checklist and commands on the connected
630
+ service first. Read one task with `resources list --scope project:ID --collection
631
+ checklist --task-id TASK_ID`, or one item with `--id ITEM_ID`. Preserve taskId,
632
+ epoch and checkpoint during pagination; filtered lists have no changeCursor.
633
+ The same taskId field is available through local MCP tasker_resources and hosted
634
+ MCP tasker_resources/tasker_read_tasks.
635
+ Inspect exact schemas with `commands describe --kind checklist.create` (also
636
+ update/move/remove or run.checklist under a live claim). Checking is an explicit
637
+ boolean, never a toggle or automatic task completion.
@@ -16,8 +16,8 @@ environment or replace a connection just to get around an access refusal.
16
16
  For example, to connect a production context to a direct Codex MCP server:
17
17
 
18
18
  ```sh
19
- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.14 auth login --environment production --context tasker-beta
20
- codex mcp add geniustasker-production -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.14 mcp --environment production --context tasker-beta
19
+ npx -y @pulsarinteractive/geniustasker@0.1.0-beta.15 auth login --environment production --context tasker-beta
20
+ codex mcp add geniustasker-production -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.15 mcp --environment production --context tasker-beta
21
21
  ```
22
22
 
23
23
  Use either this configuration or the development example below for the intended
@@ -27,8 +27,8 @@ before working. Adding the production example does not retarget a bundled plugin
27
27
  ## Codex: direct MCP
28
28
 
29
29
  ```sh
30
- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.14 auth login --context work
31
- codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.14 mcp --context work
30
+ npx -y @pulsarinteractive/geniustasker@0.1.0-beta.15 auth login --context work
31
+ codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.15 mcp --context work
32
32
  ```
33
33
 
34
34
  Restart the host as needed, then inspect its MCP list. Ask the agent to read its
package/docs/PLANNING.md CHANGED
@@ -6,13 +6,35 @@ Inspect `capabilities` and the current record before preparing a command.
6
6
 
7
7
  ## Progress and effort
8
8
 
9
- Use the task's actual progress: `New` means to do, `InProgress` means work has
10
- started, and `Done` means the intended work and acceptance criteria are verified.
9
+ Use the task's actual progress: `New` means not yet started, `InProgress` means
10
+ current, identifiable execution, `Paused` records a known interruption, and
11
+ `Done` means the intended work and
12
+ acceptance criteria are verified. Partly implemented code, an undelivered lot
13
+ or unfinished acceptance criteria do not by themselves establish active work.
11
14
  Creating a plan, assigning an owner or claiming an agent run does not itself
12
15
  start or finish the task. Update progress when the work changes. A finished
13
16
  process, published protocol or completed run is not proof that a task is done.
14
17
  Never force completion to clear a dependency or make a plan appear finished.
15
18
 
19
+ Keep several tasks InProgress only when people or agents are actually working
20
+ on them concurrently, with identifiable responsibility and current activity.
21
+ For example, one agent implementing a change and another actively running its
22
+ independent verification can justify two active tasks. Twenty partially coded
23
+ lots waiting while one agent works on a different lot cannot. Reconcile only
24
+ the authorized work whose activity is known; do not reset another person's
25
+ tasks because their reports or lease are stale.
26
+
27
+ For a known pause or interruption of work you control, preserve descriptions,
28
+ comments and verified results, and record a useful reason plus the concrete
29
+ point at which work should resume. Read [explicit pause/resume](TASK_PAUSES.md)
30
+ and discover `task.pause/resume` or the live run equivalents before use. Client
31
+ beta.15 supports these commands; the service must advertise them. If it does
32
+ not, retain an authorized note and explain the missing transition.
33
+ Use dedicated commands to pause/resume; never patch status or relabel started
34
+ work as New or Done. Resume explicitly only for actual execution. A manual lock
35
+ requires an actual obstacle, not merely switching to another work item.
36
+ Silence, an absent heartbeat or lease expiry is not proof of interruption.
37
+
16
38
  `estimateDays` measures approximate effort in working days: `0.1` is one tenth
17
39
  of a working day and `1` is one working day. It is not a deadline, elapsed
18
40
  calendar time, time spent waiting, or an AI execution timer. Do not convert it
@@ -37,30 +59,31 @@ When the scope or understanding changes, reassess the effort and explain a
37
59
  proposed or authorized revision. Do not silently replace another person's
38
60
  estimate with elapsed agent time or a faster model's runtime.
39
61
 
40
- The unreleased source accepts finite estimates from `0.1` through `60`, including
41
- optional protocol-step estimates. This is not a claim that installed npm
42
- beta.13 or the connected deployment supports those additions. Inspect current
62
+ Current client schemas accept finite estimates from `0.1` through `60`, including
63
+ optional protocol-step estimates. Installed beta.13 and older services may not
64
+ support those additions. Inspect current
43
65
  command help and capabilities before sending them. An older deployment can
44
66
  reject the new field or values below `0.25`; explain the limitation and retain
45
67
  the intended estimate rather than rounding it or changing transports to bypass
46
- validation. Unreleased task create/update help now includes generated field
68
+ validation. Task create/update help includes generated field
47
69
  schemas: creation requires a title and update preserves omitted fields. Native
48
70
  permissions, live references and lifecycle rules remain server-authoritative.
49
71
 
50
72
  For a blocked task or an authorized manual lock, read
51
73
  [task locks and current availability](TASK_LOCKS.md). Locked is an effective
52
- availability state, not a fourth canonical progress value.
53
-
54
- | Operation | Commands | Required access |
55
- | ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
56
- | New project | `project.create` | `projects:write`, all-resources consent including future projects, available account quota |
57
- | Project settings | `project.update`, `project.features` | `projects:write`, native project administration |
58
- | Delete project | `project.delete` | `projects:write`, project ownership |
59
- | Sprint lifecycle | `sprint.create/update/start/complete/delete` | `tasks:write`, native sprint management |
60
- | Workflow stages | `workflow.create/update/delete` | `tasks:write`, native project administration |
61
- | Recurring tasks | `schedule.create/update/delete` | `tasks:write`, native schedule rights |
62
- | Project documents | `document.create/update/delete`, `folder.create/update/delete` | `tasks:write`, native content rights |
63
- | Memory folders | `memory.page.create/update/delete` with `directory: true` | `memory:write`, Memory content rights |
74
+ availability state, independent of canonical progress and a known pause.
75
+
76
+ | Operation | Commands | Required access |
77
+ | ------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
78
+ | New project | `project.create` | `projects:write`, all-resources consent including future projects, available account quota |
79
+ | Project settings | `project.update`, `project.features` | `projects:write`, native project administration |
80
+ | Agent instructions | `project.configureInstructions` | `projects:write`, actual project owner, agent contributions already enabled |
81
+ | Delete project | `project.delete` | `projects:write`, project ownership |
82
+ | Sprint lifecycle | `sprint.create/update/start/complete/delete` | `tasks:write`, native sprint management |
83
+ | Workflow stages | `workflow.create/update/delete` | `tasks:write`, native project administration |
84
+ | Recurring tasks | `schedule.create/update/delete` | `tasks:write`, native schedule rights |
85
+ | Project documents | `document.create/update/delete`, `folder.create/update/delete` | `tasks:write`, native content rights |
86
+ | Memory folders | `memory.page.create/update/delete` with `directory: true` | `memory:write`, Memory content rights |
64
87
 
65
88
  Existing credentials retain their original permissions. Reconnect and approve
66
89
  `projects:write` to use project administration. A grant restricted to selected
@@ -77,6 +100,27 @@ type and icon; omitted type/icon default to `Details` and `layers`.
77
100
  Keep the returned revision for subsequent edits. Other commands require the
78
101
  latest target revision. Never manufacture a revision from a local timestamp.
79
102
 
103
+ For an explicit request to set up or revise project agent instructions, first
104
+ discover `project.configureInstructions` in the connected service and command
105
+ help. Read `project` to preserve existing guidance, its current revision and
106
+ `agentsEnabled`. Only the actual project owner can use this command; project
107
+ administration alone is insufficient. Existing consent must include
108
+ `projects:write` and this project. A disabled project requires the separate human
109
+ configuration flow; the command cannot enable itself or change any grant.
110
+
111
+ Send the complete intended replacement as `data: {"instructions": "..."}`,
112
+ targeting the project ID with its current epoch and revision. The limit is
113
+ 12,000 characters; tabs and line breaks are allowed, other ASCII controls are
114
+ rejected, and the server trims leading/trailing whitespace. Empty text explicitly
115
+ clears the instructions, so use it only for an intended removal. Preserve
116
+ unrelated human guidance; do not copy credentials or unrelated private context.
117
+ Retain the exact operation after uncertainty. After success, read the same
118
+ project and confirm `agentInstructions` plus unchanged `agentsEnabled`.
119
+ These instructions guide authorized work; they cannot grant new permissions.
120
+ This source addition is pending release/deployment: older clients reject this
121
+ command. If unavailable, explain the gap and keep the prepared text rather than
122
+ using private account APIs or disguising it as an ordinary project update.
123
+
80
124
  `project.features` replaces the planning configuration. Read the project first
81
125
  and map these fields; preserve values unrelated to the user's request:
82
126
 
@@ -0,0 +1,85 @@
1
+ # Small steps within a task
2
+
3
+ Client beta.15 supports checklist commands and bounded reads. Discover the
4
+ connected service's `checklist` collection and supported commands first; client
5
+ installation alone does not establish server rollout.
6
+ Use the normal task read/write grants and current project rights; a checklist
7
+ does not grant access to another task or bypass its agent claim.
8
+
9
+ Use a checklist for small, checkable steps of the same deliverable. Create a
10
+ separate ticket when a step needs an independent owner, dependency, deadline or
11
+ effort estimate. Do not hide independently planned work inside checkbox text.
12
+ Preserve the user's existing breakdown; configure it when requested or within
13
+ the authorized task planning scope, without expanding the deliverable. For
14
+ example, “verify the form” and “check its error state” can be steps of the same
15
+ form fix; a review assigned to a different owner belongs in its own ticket.
16
+ Do not split a checklist into tickets merely to raise task counts or rewards.
17
+
18
+ ## Read the relevant task
19
+
20
+ Read the task, then one bounded checklist page with `collection: "checklist"`
21
+ and `taskId` equal to that task's ID. CLI uses `resources list --scope project:ID
22
+ --collection checklist --task-id TASK_ID`. To inspect one known item, use its
23
+ exact `id`. Follow `nextAfter` with the same taskId, epoch and checkpoint until
24
+ the relevant list is complete; do not crawl every task. A filtered checklist
25
+ list has no changeCursor. Revalidate it normally after changes; do not invent
26
+ an incremental cursor from a checkpoint.
27
+
28
+ Items expose `task`, `title`, `checked`, `order` and author/time metadata. The
29
+ parent task's `checklistCount` and `checklistDoneCount` are server-owned totals.
30
+ Use these current totals for a percentage when present, or compute it only from
31
+ a complete current list. An empty list is no checklist, not proof of 100% or
32
+ completion. A partial page cannot establish the total or final percentage.
33
+
34
+ ## Edit one explicit intent
35
+
36
+ Inspect `commands describe --kind KIND` or `tasker_command_help` first. Commands
37
+ target the **item ID** with null expectedRevision for create and the current
38
+ item revision otherwise. New item IDs are UUIDs. Every command includes the
39
+ unchanged parent `task` in its data.
40
+
41
+ | Command | Data |
42
+ | ------------------ | -------------------------------------------------------- |
43
+ | `checklist.create` | `{task,title}` |
44
+ | `checklist.update` | `{task,title?,checked?}` with at least one changed field |
45
+ | `checklist.move` | `{task,neighborId,neighborRevision}` |
46
+ | `checklist.remove` | `{task}` |
47
+
48
+ The list holds at most 50 items; title is useful text of 1–240 characters,
49
+ nonempty after trimming. Creation appends an unchecked item. Check or uncheck
50
+ by sending the desired boolean `checked`, never a toggle. A move swaps the item
51
+ with one current adjacent neighbor, using both revisions. Reread after a
52
+ neighbor conflict instead of guessing an index or replacing the whole list.
53
+ Remove deletes that item and the server compacts the bounded sibling order.
54
+ Never patch order, authors, parent counters or an array on the task itself.
55
+
56
+ Under your live claim, use **run.checklist**, targeting the run ID and its
57
+ current revision, with `{taskRevision,itemId,itemRevision,change}`. `itemRevision`
58
+ is null for creation and the current item revision otherwise. The nested
59
+ `change` includes the same task and the exact discovered action:
60
+ `createChecklistItem`, `updateChecklistItem`, `moveChecklistItem` or
61
+ `removeChecklistItem`, plus the corresponding fields above. These nested action
62
+ values are required; do not send an internal action at the top level of a
63
+ normal checklist command. Retain current run, parent task, item and neighbor
64
+ revisions as applicable; never bypass a claim with a direct item command.
65
+
66
+ Save one immutable command before sending and replay that same operation after
67
+ an uncertain reply. A new operation after a definitive conflict needs fresh
68
+ reads. A successful checklist edit changes parent totals/revision, so reread
69
+ before the next run operation or parent edit. Respect current authorization,
70
+ storage admission and the 50-item limit.
71
+
72
+ Archived tasks allow authorized reading, but checklist writes are refused. Do
73
+ not restore a task merely to bypass that refusal; restoration must itself belong
74
+ to the requested work. An unarchived Done task can have its checklist corrected
75
+ without reopening it: unchecking leaves Done and its completion history intact.
76
+ If the correction reveals unfinished acceptance work, reconcile the task's
77
+ progress explicitly within the authorized work; never imply the checkbox
78
+ performed a reopening. Paused tasks keep their reason, next steps and pause time
79
+ through checklist edits, even when the checklist reaches 100%.
80
+
81
+ Checking a case records that small step only. It gives no XP or push, and 100%
82
+ does not mark the task Done. Editing, checking, moving or clearing a checklist
83
+ does not start, resume, unlock, reopen or move Paused work to New. Leave actual
84
+ progress and blockers intact; complete the task separately only after verifying
85
+ its intended outcome and acceptance criteria.
@@ -1,13 +1,14 @@
1
1
  # Task locks and current availability
2
2
 
3
- These commands and reads are in unreleased source. They are not evidence of an
4
- npm publication, enabled production deployment or app release. Discover the
5
- connected service's capabilities and command help before using them. Keep the
3
+ Client beta.15 adds pause commands and v2 reads. Client installation does not
4
+ establish an enabled server deployment or app release. Discover the connected
5
+ service's capabilities and command help before using them. Keep the
6
6
  same account, scope and current permission grants.
7
7
 
8
8
  ## Progress is separate from availability
9
9
 
10
- Canonical task progress stays `New`, `InProgress` or `Done`. Follow
10
+ Canonical progress includes `New`, `InProgress`, `Paused` and `Done` in the pause
11
+ extension. Read [explicit pause/resume](TASK_PAUSES.md) before using it. Follow
11
12
  [progress and effort guidance](PLANNING.md#progress-and-effort); never send
12
13
  `status: "Locked"` in `task.update` or `run.patch`.
13
14
 
@@ -15,8 +16,11 @@ An unfinished task is effectively Locked while it has a manual reason, an
15
16
  unfinished live prerequisite, or both. Unlocking manually removes only the
16
17
  manual reason. It does not delete dependencies, finish a prerequisite or grant
17
18
  permission to start blocked work. When the last cause disappears, the retained
18
- New/InProgress progress becomes visible. A lock is not progress, a completion,
19
+ New/InProgress/Paused progress becomes visible. A lock is not progress, a completion,
19
20
  an agent run's Waiting state or a private focus/defer instruction.
21
+ Revealing retained InProgress after unlock does not prove execution resumed;
22
+ check the actual worker's current activity. A known interruption needs its
23
+ reason and resumption point, not an invented blocker or automatic restart.
20
24
 
21
25
  Already Done work remains Done when a prerequisite is reopened. Locking a Done
22
26
  task requires an explicitly intended reopen first. Archived unfinished
@@ -25,20 +29,24 @@ deletion. Do not remove prerequisites or force Done to obtain an available task.
25
29
 
26
30
  ## Read the current source
27
31
 
28
- First read capabilities. Only when the `collections` entry with `id: "tasks"`
29
- advertises `taskState: "v1"`, explicitly select `taskState: "v1"` in MCP task
30
- resource/change/watch reads, or `--task-state v1` with CLI `resources list`,
31
- `changes list` and `changes watch`. This signal works with read-only task grants;
32
+ First read capabilities. When the `collections` entry with `id: "tasks"` lists
33
+ `"v2"` in `taskStateVersions`, explicitly select `taskState: "v2"` in MCP task
34
+ resource/change/watch reads, or `--task-state v2` with CLI `resources list`,
35
+ `changes list` and `changes watch`. Otherwise choose v1 only when that collection
36
+ advertises `taskState: "v1"`. These signals work with read-only task grants;
32
37
  permission to lock is not needed for availability reads. Keep the choice on
33
38
  continuations and bounded watches. The client never adds it automatically.
34
39
  Omit it on older deployments. Without the option the server returns the legacy
35
40
  shape with no availability snapshot, preserving published beta.13 compatibility.
41
+ V1 omits the snapshot entirely for a Paused task, preserving beta.14's strict
42
+ parser. Absence is unknown; never treat it as resumed or available.
36
43
 
37
44
  Task resource entries and task change `upsert` entries can carry a separate
38
45
  `taskAvailability` snapshot. It contains `progress`, effective `status`,
39
46
  `manualReason`, `dependencyCount`, up to 20 `blockingIds`, `blockersTruncated`,
40
47
  `incomplete` and `source: {epoch, authorizationEpoch, head}`. Removal entries
41
- have no snapshot. Other collections do not expose this task projection.
48
+ have no snapshot. V2 also requires nullable `pauseReason`, `pauseNextSteps` and
49
+ `pausedAt`. Other collections do not expose this task projection.
42
50
 
43
51
  `Unknown`, `incomplete: true` or an absent snapshot is not proof of availability.
44
52
  The server bounds dependency resolution to 1000 distinct prerequisites per
@@ -0,0 +1,91 @@
1
+ # Pause and resume known work
2
+
3
+ Client beta.15 supports explicit pause commands and task-state v2. Installed
4
+ beta.14 does not expose these additions. Client support does not establish
5
+ server rollout: discover the connected service's commands and collection
6
+ versions before use. An unavailable transition is a limitation to
7
+ report, not permission to guess a command or reset started work to New.
8
+
9
+ ## Record the actual work state
10
+
11
+ New means work has not started. InProgress requires current identifiable
12
+ execution, not partial implementation or an undelivered lot. Paused records a
13
+ known interruption of started work, with its reason and concrete resumption
14
+ point. Done requires verified intended completion. Multiple InProgress tasks
15
+ require actual parallel activity with attributable workers.
16
+
17
+ When work you control is knowingly interrupted or you switch away from it,
18
+ preserve its description, comments and verified results and use the discovered
19
+ pause operation. Never infer a pause from silence, an absent heartbeat or an
20
+ expired lease. Do not pause somebody else's task merely because its reports
21
+ are old. Until the transition is available, retain a factual authorized note
22
+ and explain the missing capability.
23
+
24
+ Paused is progress; Locked is a separate obstacle. A paused task can also be
25
+ Locked by a manual reason or unfinished prerequisites. Removing a lock does
26
+ not resume it, and pausing/resuming does not remove dependencies or manual
27
+ reasons. Read both `progress` and effective `status`, not one badge alone.
28
+ Unknown/incomplete availability never proves that resuming is allowed.
29
+
30
+ ## Use the explicit command
31
+
32
+ Inspect `commands describe --kind KIND --json` or `tasker_command_help` and use
33
+ the ordinary immutable prepare/execute workflow:
34
+
35
+ | Command | Envelope target and revision | Data |
36
+ | ------------- | ------------------------------------ | --------------------------------- |
37
+ | `task.pause` | Task ID and current task revision | `{reason,nextSteps}` |
38
+ | `task.resume` | Task ID and current task revision | `{}` |
39
+ | `run.pause` | Live run ID and current run revision | `{taskRevision,reason,nextSteps}` |
40
+ | `run.resume` | Live run ID and current run revision | `{taskRevision}` |
41
+
42
+ `reason` is required text of 1–500 characters; `nextSteps` is required text of
43
+ 1–2000 characters. Both must be nonempty after trimming. Give an observed reason
44
+ and the next concrete action needed to resume, without replacing the task's
45
+ existing description or past comments. For example: reason "Switching to the
46
+ requested incident investigation" and nextSteps "Resume the pending migration
47
+ verification from the saved test results" only when those facts are true.
48
+
49
+ Pause applies to InProgress or an already Paused task; repeating it can update
50
+ the reason and next steps while retaining the original pause time. It is not
51
+ a way to label never-started, Done or archived work. Resume applies to Paused
52
+ and requests InProgress: use it only when actual execution is resuming. Current
53
+ locks, dependencies, revisions and permissions can refuse that request. Reread
54
+ the current task and availability before resuming; a receipt is not an automatic
55
+ start signal or proof that an external worker is running.
56
+
57
+ Never enter or leave Paused through `task.update`, `run.patch`, a workflow move
58
+ or a fabricated status. `pauseReason`, `pauseNextSteps` and `pausedAt` are
59
+ server-owned read fields. A Working report is not a substitute for resumption.
60
+
61
+ Under an active agent claim, its owner must use **run.pause/run.resume**, with
62
+ both current run and task revisions. The pause records the run as Waiting and
63
+ the resume records Working; these commands retain the claim and do not extend
64
+ its lease. Read both records after success. A standalone Waiting checkpoint
65
+ does not itself pause the task. Expiry, cancellation or takeover cannot be
66
+ bypassed with direct task commands, profile switching or a guessed fresh lease.
67
+
68
+ Preserve the operation ID, issuedAt, target, revisions, reason, next steps and
69
+ full body after an uncertain reply. Retry that same operation. A definitive
70
+ conflict needs fresh reads and a newly prepared reconciled intent. Do not
71
+ convert a known refusal into automatic retries or claim XP/push delivery.
72
+
73
+ ## Discover and read v2 explicitly
74
+
75
+ Read capabilities. In the `collections` entry with `id: "tasks"`, choose
76
+ `taskState: "v2"` only when `taskStateVersions` includes `"v2"`. For CLI use
77
+ `--task-state v2` on `resources list`, `changes list` or `changes watch`; for MCP
78
+ pass `taskState: "v2"`. Keep the version unchanged across continuations and
79
+ bounded watches. No hidden discovery or automatic opt-in occurs.
80
+
81
+ V2 snapshots retain the existing source and dependency fields and require
82
+ `pauseReason`, `pauseNextSteps` and `pausedAt`, each nullable. `progress` can be
83
+ Paused while effective `status` is Paused, Locked or Unknown. A null pause field
84
+ does not make an incomplete source complete or authorize resumption.
85
+
86
+ Older support is advertised by `taskState: "v1"`; choose v1 only when that
87
+ signal is present. V1 deliberately omits the entire availability snapshot for
88
+ Paused tasks, and it never contains the three new fields. Without either
89
+ advertisement omit the option. Missing snapshots remain unknown, never New or
90
+ available. Follow [source freshness and bounded reads](TASK_LOCKS.md#read-the-current-source)
91
+ before any start, resumption or completion, including after a remove-only delta.
@@ -1,3 +1,3 @@
1
1
  [mcp_servers.geniustasker]
2
2
  command = "npx"
3
- args = ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.14", "mcp", "--context", "work"]
3
+ args = ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.15", "mcp", "--context", "work"]
package/examples/mcp.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "mcpServers": {
3
3
  "geniustasker": {
4
4
  "command": "npx",
5
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.14", "mcp", "--context", "work"]
5
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.15", "mcp", "--context", "work"]
6
6
  }
7
7
  }
8
8
  }
package/mcp.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "geniustasker": {
5
5
  "type": "stdio",
6
6
  "command": "npx",
7
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.14", "mcp", "--context", "work"]
7
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.15", "mcp", "--context", "work"]
8
8
  }
9
9
  }
10
10
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pulsarinteractive/geniustasker",
3
- "version": "0.1.0-beta.14",
3
+ "version": "0.1.0-beta.15",
4
4
  "private": false,
5
5
  "description": "GeniusTasker delegated CLI and local agent tools",
6
6
  "type": "module",
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "geniustasker",
4
- "version": "0.1.0-beta.14",
4
+ "version": "0.1.0-beta.15",
5
5
  "description": "Track project work and independent product memories with your own agents.",
6
6
  "author": {
7
7
  "name": "Pulsar Interactive"