@pulsarinteractive/geniustasker 0.1.0-beta.13 → 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.
Files changed (44) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +5 -1
  3. package/docs/CHATGPT.md +17 -0
  4. package/docs/CLI.md +46 -1
  5. package/docs/FEEDBACK.md +96 -0
  6. package/docs/INTEGRATIONS.md +4 -4
  7. package/docs/PLANNING.md +149 -10
  8. package/docs/TASK_CHECKLISTS.md +85 -0
  9. package/docs/TASK_LOCKS.md +99 -0
  10. package/docs/TASK_PAUSES.md +91 -0
  11. package/examples/codex.toml +1 -1
  12. package/examples/mcp.json +1 -1
  13. package/mcp.json +1 -1
  14. package/package.json +1 -1
  15. package/plugin.json +1 -1
  16. package/remote/tool-catalog.json +735 -2
  17. package/remote/workflows.json +62 -6
  18. package/skills/geniustasker/SKILL.md +37 -0
  19. package/skills/geniustasker/references/agent-runs.md +33 -2
  20. package/skills/geniustasker/references/collaboration.md +15 -2
  21. package/skills/geniustasker/references/host-events.md +9 -0
  22. package/skills/geniustasker/references/incremental-reads.md +11 -0
  23. package/skills/geniustasker/references/protocols.md +29 -3
  24. package/skills/geniustasker-feedback/SKILL.md +44 -0
  25. package/skills/geniustasker-feedback/agents/openai.yaml +4 -0
  26. package/skills/geniustasker-planning/SKILL.md +48 -0
  27. package/src/changes.mjs +5 -1
  28. package/src/cli.mjs +134 -7
  29. package/src/client.mjs +16 -0
  30. package/src/command-catalog.mjs +156 -1
  31. package/src/command-input-schemas.mjs +924 -0
  32. package/src/commands.mjs +250 -20
  33. package/src/feedback-contract.mjs +629 -0
  34. package/src/feedback-image.mjs +123 -0
  35. package/src/feedback-media-transfer.mjs +61 -0
  36. package/src/feedback.mjs +152 -0
  37. package/src/intents.mjs +111 -0
  38. package/src/mcp.mjs +126 -3
  39. package/src/protocols.mjs +1 -0
  40. package/src/resources.mjs +26 -3
  41. package/src/task-availability-contract.mjs +166 -0
  42. package/src/task-availability.mjs +35 -0
  43. package/src/task-state-legacy-contract.mjs +121 -0
  44. package/src/transport.mjs +10 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,26 @@
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
+
10
+ ## 0.1.0-beta.14 — 2026-11-17
11
+
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.
13
+ - Read task availability only through explicit `taskState: "v1"` / `--task-state v1` after capability discovery. Legacy reads retain their old response shape. Validate optional task snapshots without treating an absent or incomplete source as available.
14
+
15
+ - Preserve optional protocol effort in command help and preview, including `0.1` working day and null for unknown. Teach truthful New/InProgress/Done progress, effort distinct from deadlines or AI runtime, and preservation of human estimates. Older deployments remain authoritative.
16
+
17
+ - Add private feedback to CLI, local MCP and the hosted tool catalogue: immutable bug/suggestion submission, receipts and final decision tracking without chat. Current grants, account plan and deployment activation remain authoritative.
18
+ - Add authorized local screenshot preparation, reservation, bounded binary transfer and exact retry. Hosted ChatGPT screenshot import is not implemented. A focused feedback skill requires the user's reporting instruction or agreement before submission.
19
+
20
+ - Leave default browser/device login scopes to the selected server's consent proposal so a newer CLI can connect to an earlier deployment. Explicit `--scope` remains unchanged; existing connections and profiles are never expanded automatically.
21
+ - Add bounded personal focus/defer reads and replacement previews to CLI, local MCP and the hosted tool catalogue. Explicit `intent.change` commands reuse current revisions and the immutable command journal; they do not change shared task dates, status or rewards.
22
+ - Document whole-selection replacement, cancellation, target invalidation and the connected owner boundary. Use only when `intent.change` is advertised by the deployment capabilities.
23
+
3
24
  ## 0.1.0-beta.13 — 2026-11-16
4
25
 
5
26
  - Add personal and project custom metrics with scoped discovery, exact aggregation, observation history, corrections and voids.
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.13", "mcp", "--context", "work"]
58
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.15", "mcp", "--context", "work"]
59
59
  }
60
60
  }
61
61
  }
@@ -88,3 +88,7 @@ cover included components. The GeniusTasker application and backend are separate
88
88
  ## ChatGPT
89
89
 
90
90
  Connect the hosted service with OAuth: [setup and examples](docs/CHATGPT.md). Your computer does not need to run the CLI. Account permissions and quotas still apply. [Official directory publication](docs/OPENAI_PUBLICATION.md) is a separate review.
91
+
92
+ ## Feedback
93
+
94
+ Use [the feedback guide](docs/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.
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
@@ -100,6 +100,14 @@ and approve it, or uncheck “All” to choose individual projects and memories
100
100
  remove any permissions you do not need. Opening the page grants nothing, and
101
101
  existing connections keep their approved permissions.
102
102
 
103
+ Without `--scope`, browser and device login leave the permission proposal to the
104
+ selected server. A newer CLI can therefore connect before that environment has
105
+ deployed every permission in its bundled command catalogue. The human still
106
+ reviews and approves the visible selection; login never updates an existing
107
+ connection or profile. Features absent from the deployment remain unavailable.
108
+ An explicit `--scope` is sent unchanged: unsupported permissions are rejected,
109
+ not silently removed or retried with different access.
110
+
103
111
  To narrow the permissions offered by the browser, pass `--scope`, for example:
104
112
 
105
113
  ```sh
@@ -120,7 +128,7 @@ launching stdio servers with this entry (adjust environment/context as needed):
120
128
  "mcpServers": {
121
129
  "geniustasker": {
122
130
  "command": "npx",
123
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.13", "mcp", "--context", "work"]
131
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.15", "mcp", "--context", "work"]
124
132
  }
125
133
  }
126
134
  }
@@ -575,6 +583,17 @@ current authorization and semantic validation remain server-side.
575
583
 
576
584
  ## Agent runs
577
585
 
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.
596
+
578
597
  Discover the `agentRuns` collection and `run.claim`, `run.checkpoint`, `run.patch`,
579
598
  `run.finish` commands before using them. Inspect each schema with
580
599
  `geniustasker commands describe --kind run.claim --json`, then use the normal
@@ -590,3 +609,29 @@ Add `--prepare` to journal it without sending. Keep its stable `eventId` and
590
609
  `tasker_run_event`. A `process_exited` event only requests review, with explicit
591
610
  next steps. See [host event fields, examples and recovery](../skills/geniustasker/references/host-events.md)
592
611
  before connecting a host callback; no host hook is installed automatically.
612
+
613
+ ### Personal focus and temporary deferral
614
+
615
+ `intents read --scope project:ID` returns the connected owner's bounded
616
+ instructions. `intents preview --file selection.json` checks exact tasks, time
617
+ window and overlapping instructions without writing. Follow
618
+ [the planning guide](PLANNING.md#temporary-personal-focus-and-deferral) and
619
+ `workflow show --topic intents`, then use the ordinary immutable
620
+ `intent.change` command flow. Availability is determined by service capabilities.
621
+
622
+ ## Feedback
623
+
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.
@@ -0,0 +1,96 @@
1
+ # Private feedback
2
+
3
+ Feedback reports a problem or suggestion about GeniusTasker itself. It does not
4
+ create a project ticket. Availability depends on the connected deployment,
5
+ account admission, plan and current consent. Installing this source does not
6
+ activate the backend or expand an existing connection.
7
+
8
+ Free accounts can report bugs and recover delivery receipts with `feedback:write`.
9
+ Starter/Pro can also suggest features and read their feedback with `feedback:read`.
10
+ Capabilities reflect both the plan and the current connection/profile grants.
11
+ Start with `feedback capabilities`; do not infer rights from an old receipt.
12
+ If a new grant is needed, the human reconnects in the relevant host. CLI consent
13
+ does not change a ChatGPT connection. Login without `--scope` leaves the proposed
14
+ permissions to that server; an explicit `--scope` remains strict.
15
+
16
+ ## Prepare and submit
17
+
18
+ Use the same context and environment throughout. These examples target an
19
+ already connected production context; production remains limited to admitted
20
+ accounts. Supply the title and observed description in a local JSON draft:
21
+
22
+ ```json
23
+ {
24
+ "type": "BugReport",
25
+ "category": "sync",
26
+ "title": "The task title stayed unchanged on the other device",
27
+ "description": "The web page showed the saved title. The phone still showed its previous title after reopening the project.",
28
+ "attachments": []
29
+ }
30
+ ```
31
+
32
+ ```sh
33
+ geniustasker feedback capabilities --environment production --context work --json
34
+ geniustasker feedback prepare --file draft.json --environment production --context work --json
35
+ geniustasker feedback submit --file command.json --environment production --context work --json
36
+ ```
37
+
38
+ Save the exact `data.command` returned by prepare as `command.json`. Preparation
39
+ reads the current epoch if omitted and saves a private local journal; it does not
40
+ submit. The command contains `commandId`, `issuedAt`, `draftId`, `expectedEpoch`
41
+ and the complete report. Show the content and selected attachments, then submit
42
+ after agreement. A direct instruction to report already authorizes that report.
43
+ Never silently send every tool error or attach private context automatically.
44
+
45
+ After an uncertain response, use `feedback receipt --id COMMAND_ID` or
46
+ `commands retry --operation COMMAND_ID` with the same context and environment.
47
+ `commands inspect --operation COMMAND_ID` reads the local journal. Retry reuses
48
+ the exact saved body and original connection/profile/session. A confirmed local
49
+ receipt avoids another request; it does not prove current status. Never edit
50
+ the command or generate a fresh ID to retry.
51
+
52
+ ## Screenshots
53
+
54
+ Choose one draft UUID and current epoch first. Before submitting, prepare a
55
+ selected local file with `feedback media-prepare --draft-id DRAFT_UUID --epoch
56
+ CURRENT_EPOCH --file screenshot.png`. Save the returned metadata, then use
57
+ `feedback media-open --file upload.json`. Reserve only user-authorized images;
58
+ this step consumes storage admission. Upload with `feedback media-upload
59
+ --operation UPLOAD_UUID --file screenshot.png` and retain the same bytes and ID
60
+ after uncertainty. Confirmed upload replay does not reread the file.
61
+
62
+ Put ready asset IDs in `attachments` and use the same `draftId` when preparing
63
+ the final report. Up to three static PNG/JPEG/WebP images can accompany the
64
+ initial request. Source bytes are capped at 4,000,000; the server normalizes to
65
+ WebP, at most 1080 px on the longest side and 1,000,000 stored bytes. Feedback and
66
+ global account storage quotas both apply. Local source inspection does not
67
+ replace server validation. Text-only reporting remains available if image
68
+ storage is refused. Existing reports cannot receive additional images.
69
+
70
+ `feedback media-download --id ASSET_ID --file new-image.webp` downloads an
71
+ authorized image without overwriting a local file. `feedback media-remove --id
72
+ ASSET_ID` removes only an explicitly selected image at the user's request. Both
73
+ accept the usual context/environment options. Retrying removal uses the same ID.
74
+
75
+ ## Decision tracking and MCP
76
+
77
+ `feedback list` accepts `--status`, `--type` and a returned `--after` cursor.
78
+ `feedback show --id REQUEST_ID` reads an exact decision. Read only requested
79
+ pages; do not poll. `feedback mark-read --file read.json` accepts
80
+ `{"id":"REQUEST_UUID","request":{"expectedEpoch":"CURRENT_EPOCH","revision":"VIEWED_REVISION"}}`
81
+ and requires `feedback:write` in addition to plan eligibility.
82
+
83
+ The team records a status, resolution and optional final message. There is no
84
+ conversation or reply command; the `messages` array has at most one final team
85
+ message. “Saved for later” does not promise delivery. A closure can send a push
86
+ according to the user's notification settings; intermediate changes do not.
87
+ Private administrative notes and duplicate targets are not exposed.
88
+
89
+ Local MCP exposes `tasker_feedback_*` tools for the same workflow, plus local
90
+ image preparation/upload/download. Hosted MCP exposes capabilities, prepare,
91
+ submit, list, detail, receipt, mark-read and image removal. Hosted preparation
92
+ returns an immutable object without a local journal: retain and resubmit the
93
+ exact object after uncertainty. It never accepts arbitrary URLs or filesystem
94
+ paths. Hosted ChatGPT attachment import is not implemented; a visible chat
95
+ attachment is not an uploaded feedback image. Use text-only feedback there
96
+ unless an authorized ready asset already exists.
@@ -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.13 auth login --environment production --context tasker-beta
20
- codex mcp add geniustasker-production -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.13 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.13 auth login --context work
31
- codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.13 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
@@ -4,16 +4,86 @@ Use `geniustasker workflow show --topic planning --json` or `tasker_workflow`
4
4
  with `topic: planning` for the same guide in CLI, local MCP and ChatGPT.
5
5
  Inspect `capabilities` and the current record before preparing a command.
6
6
 
7
- | Operation | Commands | Required access |
8
- | ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
9
- | New project | `project.create` | `projects:write`, all-resources consent including future projects, available account quota |
10
- | Project settings | `project.update`, `project.features` | `projects:write`, native project administration |
11
- | Delete project | `project.delete` | `projects:write`, project ownership |
12
- | Sprint lifecycle | `sprint.create/update/start/complete/delete` | `tasks:write`, native sprint management |
13
- | Workflow stages | `workflow.create/update/delete` | `tasks:write`, native project administration |
14
- | Recurring tasks | `schedule.create/update/delete` | `tasks:write`, native schedule rights |
15
- | Project documents | `document.create/update/delete`, `folder.create/update/delete` | `tasks:write`, native content rights |
16
- | Memory folders | `memory.page.create/update/delete` with `directory: true` | `memory:write`, Memory content rights |
7
+ ## Progress and effort
8
+
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.
14
+ Creating a plan, assigning an owner or claiming an agent run does not itself
15
+ start or finish the task. Update progress when the work changes. A finished
16
+ process, published protocol or completed run is not proof that a task is done.
17
+ Never force completion to clear a dependency or make a plan appear finished.
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
+
38
+ `estimateDays` measures approximate effort in working days: `0.1` is one tenth
39
+ of a working day and `1` is one working day. It is not a deadline, elapsed
40
+ calendar time, time spent waiting, or an AI execution timer. Do not convert it
41
+ to hours without the user's working-day convention. Deadlines and protocol
42
+ `dueAfterDays` are separate scheduling choices, never automatic conversions of
43
+ estimated effort.
44
+
45
+ Whenever creating a task or taking charge of existing work, actively check
46
+ `estimateDays`; do not wait for a separate request to consider effort. Supply
47
+ an estimate within the authorized work when the scope and known assumptions
48
+ support one. Apply the same check to each step of a new or explicitly revised
49
+ protocol. Preserve an existing human estimate or deliberate choice unless its
50
+ revision is within the user's request.
51
+
52
+ Use `null` when the effort is unknown. Explain the useful missing assumption in
53
+ the planning response or an authorized progress note, then reassess after that
54
+ uncertainty is clarified. There is no separate estimate-reason API field. Do
55
+ not manufacture a value to fill a task, convert elapsed AI time into effort,
56
+ or silently replace unknown with a default day. A request to reuse a published
57
+ protocol does not authorize rewriting its steps, digest or saved retries.
58
+ When the scope or understanding changes, reassess the effort and explain a
59
+ proposed or authorized revision. Do not silently replace another person's
60
+ estimate with elapsed agent time or a faster model's runtime.
61
+
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
65
+ command help and capabilities before sending them. An older deployment can
66
+ reject the new field or values below `0.25`; explain the limitation and retain
67
+ the intended estimate rather than rounding it or changing transports to bypass
68
+ validation. Task create/update help includes generated field
69
+ schemas: creation requires a title and update preserves omitted fields. Native
70
+ permissions, live references and lifecycle rules remain server-authoritative.
71
+
72
+ For a blocked task or an authorized manual lock, read
73
+ [task locks and current availability](TASK_LOCKS.md). Locked is an effective
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 |
17
87
 
18
88
  Existing credentials retain their original permissions. Reconnect and approve
19
89
  `projects:write` to use project administration. A grant restricted to selected
@@ -30,6 +100,27 @@ type and icon; omitted type/icon default to `Details` and `layers`.
30
100
  Keep the returned revision for subsequent edits. Other commands require the
31
101
  latest target revision. Never manufacture a revision from a local timestamp.
32
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
+
33
124
  `project.features` replaces the planning configuration. Read the project first
34
125
  and map these fields; preserve values unrelated to the user's request:
35
126
 
@@ -77,3 +168,51 @@ keep stable page and block IDs. Folder cycles are rejected by the server.
77
168
  Prepare then execute one immutable operation. Retain its ID, timestamp and body
78
169
  for uncertain retries. Read back affected collections after success. Open apps
79
170
  receive the same realtime changes as edits made in the native UI.
171
+
172
+ ## Temporary personal focus and deferral
173
+
174
+ Read workflow `intents` before using this capability. It is available only when
175
+ `intent.change` appears in the connected deployment's capabilities. It needs
176
+ `tasks:read` for reads/previews, `tasks:write` for commands and the project's
177
+ existing human-controlled agent opt-in.
178
+
179
+ ```sh
180
+ geniustasker workflow show --topic intents --json
181
+ geniustasker intents read --scope project:PROJECT_ID --json
182
+ geniustasker intents preview --file preview.json --json
183
+ geniustasker commands describe --kind intent.change --json
184
+ ```
185
+
186
+ A preview file contains `scope` and `selection`: kind `focus` or `defer`, its
187
+ objective, 1–20 exact open `taskIds`, `startsAt` (null means commit time), and an
188
+ explicit `endsAt`. Duration and advance scheduling are each bounded to 14 days.
189
+ Focus objectives are `finish`, `unblock`, `consistency`; defer uses `pause`.
190
+ Resolve a user's local timezone before selecting dates. No recursive selector
191
+ implicitly includes descendants.
192
+
193
+ Local MCP exposes `tasker_intents` and `tasker_intent_preview`; the hosted
194
+ connector has the same tools. A preview makes no changes. Review its full
195
+ replacement list: overlap with part of an earlier group retires that whole
196
+ instruction, not just the overlapping task. Ask for clarification when that
197
+ would exceed the requested change.
198
+
199
+ The command's outer `id` is the **connected human's ID** from identity. Its
200
+ `expectedRevision` is the preview's `intentRevision`, including null only for
201
+ an initially absent instruction aggregate. The separate `data.id` is a new
202
+ instruction UUID. Copy `expectedIntentRevision`, `selection`, `sourceVersion`
203
+ and `replaces` exactly from the preview and use `decision: set`. The server
204
+ owns attribution; never include internal action or author fields.
205
+
206
+ For `decision: cancel`, use the existing instruction's UUID, the latest
207
+ aggregate revision in both revision fields, `selection: null`,
208
+ `sourceVersion: null`, and `replaces: []`. It never revives a superseded focus.
209
+ Use the ordinary immutable command journal on CLI/local MCP or the exact
210
+ prepared command with `tasker_edit_tasks` in the hosted connector. Retry the
211
+ same operation after uncertainty. A definitive conflict requires a fresh read
212
+ and preview, not a forced overwrite.
213
+
214
+ Read back through `tasker_intents`; private command receipts deliberately have
215
+ no public changed items. These instructions do not change shared deadlines,
216
+ status, importance, XP or agent execution claims. Reassignment, deletion and
217
+ access changes make affected instructions stale. They belong only to the
218
+ connected owner; another collaborator's instructions are not exposed.
@@ -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.
@@ -0,0 +1,99 @@
1
+ # Task locks and current availability
2
+
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
+ same account, scope and current permission grants.
7
+
8
+ ## Progress is separate from availability
9
+
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
12
+ [progress and effort guidance](PLANNING.md#progress-and-effort); never send
13
+ `status: "Locked"` in `task.update` or `run.patch`.
14
+
15
+ An unfinished task is effectively Locked while it has a manual reason, an
16
+ unfinished live prerequisite, or both. Unlocking manually removes only the
17
+ manual reason. It does not delete dependencies, finish a prerequisite or grant
18
+ permission to start blocked work. When the last cause disappears, the retained
19
+ New/InProgress/Paused progress becomes visible. A lock is not progress, a completion,
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.
24
+
25
+ Already Done work remains Done when a prerequisite is reopened. Locking a Done
26
+ task requires an explicitly intended reopen first. Archived unfinished
27
+ prerequisites still block; absence from a page or cache does not establish
28
+ deletion. Do not remove prerequisites or force Done to obtain an available task.
29
+
30
+ ## Read the current source
31
+
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;
37
+ permission to lock is not needed for availability reads. Keep the choice on
38
+ continuations and bounded watches. The client never adds it automatically.
39
+ Omit it on older deployments. Without the option the server returns the legacy
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.
43
+
44
+ Task resource entries and task change `upsert` entries can carry a separate
45
+ `taskAvailability` snapshot. It contains `progress`, effective `status`,
46
+ `manualReason`, `dependencyCount`, up to 20 `blockingIds`, `blockersTruncated`,
47
+ `incomplete` and `source: {epoch, authorizationEpoch, head}`. Removal entries
48
+ have no snapshot. V2 also requires nullable `pauseReason`, `pauseNextSteps` and
49
+ `pausedAt`. Other collections do not expose this task projection.
50
+
51
+ `Unknown`, `incomplete: true` or an absent snapshot is not proof of availability.
52
+ The server bounds dependency resolution to 1000 distinct prerequisites per
53
+ page. For a task needing a current decision, request that exact `tasks` ID
54
+ through the normal bounded resource read; if its source remains incomplete,
55
+ explain the uncertainty. Do not scan the entire project to reconstruct a graph.
56
+ A truncated blocker list is not an exhaustive list of reasons.
57
+
58
+ Use the snapshot's source epoch, authorization epoch and **task-module head**
59
+ for freshness. A prerequisite change invalidates older availability even if
60
+ the dependent task's row revision does not change and no dependent delta is
61
+ sent. The snapshot head can be newer than a change page's historical checkpoint.
62
+ Keep those values separate; never rewrite one from the other. Discard older
63
+ availability decisions when the source changes and reread the relevant task.
64
+ Any advanced task-module head or checkpoint invalidates older availability,
65
+ including a delta containing only `remove` with no dependent snapshot. There
66
+ is no dependent fanout. Before starting or completing work, reread that exact
67
+ task with the advertised opt-in and use its current availability.
68
+ The client revalidates cached resource reads with the server; historical output
69
+ and a command receipt are not a present permission or availability grant.
70
+
71
+ ## Apply only the authorized manual change
72
+
73
+ Inspect `commands describe --kind KIND --json` or `tasker_command_help` for the
74
+ exact schema, then use the ordinary immutable prepare/execute workflow:
75
+
76
+ | Command | Envelope target and revision | Data |
77
+ | ------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- |
78
+ | `task.lock` | Task ID and current task revision | `{"reason":"The required test device is unavailable."}` |
79
+ | `task.unlock` | Task ID and current task revision | `{}` |
80
+ | `run.lock` | Live run ID and current run revision | `{"taskRevision":"CURRENT_TASK_REVISION","reason":"The required test device is unavailable."}` |
81
+ | `run.unlock` | Live run ID and current run revision | `{"taskRevision":"CURRENT_TASK_REVISION"}` |
82
+
83
+ Reasons are required plain text, 1–500 characters and nonempty after trimming.
84
+ Use an observed, useful reason; the example is not a reason to invent a blocker.
85
+ The server owns attribution and time. Do not patch `manualLockReason`, include
86
+ an internal `action`, or use another field to simulate locking.
87
+
88
+ The owner of an active agent claim must use **run.lock/run.unlock**, with both
89
+ current revisions. Direct task commands are not a workaround for a claim,
90
+ expired lease, takeover or revision refusal. Read the run and reconcile current
91
+ authority; never switch profiles to evade it. Read both run and task after a
92
+ successful run command because their revisions can change.
93
+
94
+ Preserve operation ID, issuedAt, target, revisions, reason and full body for
95
+ uncertain retry. A definitive conflict requires fresh reads and a new operation
96
+ only for reconciled intent. A refused start/completion under current lock rules
97
+ does not justify automatic retries; explain the cause and continue independent
98
+ authorized work where useful. Read availability after unlocking before saying
99
+ the task is available. No lock receipt proves completion, XP or push delivery.