@pulsarinteractive/geniustasker 0.1.0-beta.11 → 0.1.0-beta.13
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 +22 -0
- package/README.md +14 -1
- package/docs/ARCHITECTURE.md +15 -13
- package/docs/CHATGPT.md +6 -0
- package/docs/CLI.md +153 -5
- package/docs/INTEGRATIONS.md +25 -2
- package/docs/MEMORY.md +9 -0
- package/docs/WORKFLOWS.md +14 -0
- package/examples/codex.toml +1 -1
- package/examples/mcp.json +1 -1
- package/mcp.json +1 -1
- package/package.json +2 -2
- package/plugin.json +1 -1
- package/remote/tool-catalog.json +296 -1
- package/remote/workflows.json +53 -2
- package/skills/geniustasker/SKILL.md +15 -1
- package/skills/geniustasker/references/agent-runs.md +144 -0
- package/skills/geniustasker/references/host-events.md +116 -0
- package/skills/geniustasker/references/importance.md +90 -0
- package/skills/geniustasker/references/metric-goals.md +143 -0
- package/skills/geniustasker/references/metrics-observations.md +184 -0
- package/skills/geniustasker/references/metrics.md +136 -0
- package/skills/geniustasker/references/protocols.md +156 -0
- package/skills/geniustasker/references/updates.md +31 -0
- package/skills/geniustasker-graph/SKILL.md +10 -0
- package/skills/geniustasker-memory/SKILL.md +19 -6
- package/skills/geniustasker-memory/references/knowledge-workflows.md +42 -0
- package/skills/geniustasker-planning/SKILL.md +6 -1
- package/src/changes.mjs +3 -5
- package/src/cli.mjs +108 -14
- package/src/command-catalog.mjs +849 -562
- package/src/command-input-schemas.d.mts +8 -0
- package/src/command-input-schemas.mjs +1021 -0
- package/src/commands.mjs +78 -25
- package/src/mcp.mjs +48 -20
- package/src/protocols.mjs +122 -0
- package/src/resources.mjs +98 -0
- package/src/run-events.mjs +145 -0
- package/src/update-runtime.mjs +169 -0
- package/src/update.mjs +306 -0
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Coordinate an agent run
|
|
2
|
+
|
|
3
|
+
Use a run for an actual agent working on a tracked task, especially when another
|
|
4
|
+
agent or person may work on it too. A run is a temporary collaboration claim and
|
|
5
|
+
an attributed record of real checkpoints. It neither starts an agent nor proves
|
|
6
|
+
that an external process is alive. Tasker does not monitor an uninstrumented
|
|
7
|
+
agent; silence is unknown activity.
|
|
8
|
+
|
|
9
|
+
## Read before claiming
|
|
10
|
+
|
|
11
|
+
1. Read identity, capabilities, the relevant Details project and its current task.
|
|
12
|
+
Discover `agentRuns` and `run.claim`, `run.checkpoint`, `run.patch`, `run.finish`.
|
|
13
|
+
They require the usual project access and task permissions; delegated writes
|
|
14
|
+
require `tasks:write` and project agent contributions to be enabled.
|
|
15
|
+
2. Inspect a relevant existing run with a bounded `resources` read. Preserve its
|
|
16
|
+
epoch/revision. An active claim is not permission to take over another agent.
|
|
17
|
+
Current grant/profile restrictions apply even when the task belongs to you.
|
|
18
|
+
3. Read `tasker_command_help` for the chosen command, or
|
|
19
|
+
`geniustasker commands describe --kind run.claim --json`. The local help is
|
|
20
|
+
offline schema guidance, not evidence that the account has access.
|
|
21
|
+
4. Claim only work the user authorized. Keep one new UUID as the run's command
|
|
22
|
+
target, the current task ID and task revision, and the current project epoch.
|
|
23
|
+
A create command uses `expectedRevision: null`.
|
|
24
|
+
|
|
25
|
+
Example **data** for `run.claim` (replace task identity and revision from reads):
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"task": "TASK_ID_FROM_CURRENT_READ",
|
|
30
|
+
"taskRevision": "7",
|
|
31
|
+
"summary": "Check the requested behavior and its acceptance criteria.",
|
|
32
|
+
"leaseSeconds": 300
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Use the normal immutable command prepare/execute workflow. A confirmed claim
|
|
37
|
+
returns the run's revision; read `agentRuns` to obtain its current lease and
|
|
38
|
+
attribution. Another actor may win the claim between your read and write. On a
|
|
39
|
+
claim conflict, inspect the current run and choose independent authorized work;
|
|
40
|
+
never change profiles, overwrite the claim or infer human approval.
|
|
41
|
+
|
|
42
|
+
## Report actual work and keep the fence
|
|
43
|
+
|
|
44
|
+
`run.checkpoint` targets the run UUID and its current revision. Use `Working`,
|
|
45
|
+
`Waiting` or `NeedsReview`, a factual summary and the useful next steps. Waiting
|
|
46
|
+
and review checkpoints need an actionable `nextSteps`. Evidence links must be
|
|
47
|
+
labeled HTTPS URLs without credentials or private signed links. Do not upload
|
|
48
|
+
full conversations, terminal output or secret-bearing diagnostics.
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"state": "Working",
|
|
53
|
+
"summary": "The regression is reproduced; the targeted correction is under test.",
|
|
54
|
+
"nextSteps": "Verify the correction and the unchanged neighboring behavior.",
|
|
55
|
+
"evidence": [],
|
|
56
|
+
"leaseSeconds": 300
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Adapt this text to observations; do not copy it as invented progress. A checkpoint
|
|
61
|
+
may renew a live lease. Schedule bounded updates around real work and respect
|
|
62
|
+
retry times, not a polling loop that invents movement. The saved lease is the
|
|
63
|
+
server authority; a local timer alone never authorizes another write.
|
|
64
|
+
|
|
65
|
+
Only the creating user/profile may report on the run. A new profile is a new
|
|
66
|
+
identity, not a way to resume an uncertain write. Original immutable operations
|
|
67
|
+
retain their original connection/session identity for retries.
|
|
68
|
+
|
|
69
|
+
For task changes while holding a claim, use `run.patch` with the current **run**
|
|
70
|
+
revision in the envelope and current **task** revision in `data.taskRevision`:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"taskRevision": "8",
|
|
75
|
+
"patch": { "description": "Updated with the verified acceptance criteria." }
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The patch accepts only fields supported by `task.update`. It preserves ordinary
|
|
80
|
+
permissions, human-owned importance, dependencies and task lifecycle rules.
|
|
81
|
+
Do not send internal fields, arbitrary mutations or a stale task snapshot.
|
|
82
|
+
A human edit changes the revision; reread and reconcile instead of overwriting.
|
|
83
|
+
|
|
84
|
+
## Distinguish silence, waiting and completion
|
|
85
|
+
|
|
86
|
+
- `Waiting` is an explicit agent report requiring information or another action.
|
|
87
|
+
- `NeedsReview` is an explicit request to inspect a real result.
|
|
88
|
+
- An expired `leaseUntil` means the signal is stale. It does not prove failure,
|
|
89
|
+
blockage, cancellation or task completion. Do not generate a failure report
|
|
90
|
+
just because a heartbeat was absent.
|
|
91
|
+
- `cancelRequestedAt` asks the agent to stop. Stop new task changes and safely
|
|
92
|
+
finish as `Cancelled` when still authorized. Human cancellation/takeover is an
|
|
93
|
+
app control, not a command agents may impersonate or bypass.
|
|
94
|
+
- `TakenOver` or `Superseded` means the prior run cannot continue writing. Reread
|
|
95
|
+
the task and current authority; do not silently recreate a claim to defeat a
|
|
96
|
+
person's decision.
|
|
97
|
+
|
|
98
|
+
After lease expiry, do not forge the clock or renew an expired command under a
|
|
99
|
+
fresh ID. Read the task/run again. A fresh claim is a new explicit operation for
|
|
100
|
+
still-authorized open work, not a replay of the old run. Preserve any uncertain
|
|
101
|
+
operation and establish its outcome before issuing a conflicting new command.
|
|
102
|
+
|
|
103
|
+
`run.finish` records `Completed`, `Failed` or `Cancelled`, with an honest summary,
|
|
104
|
+
next steps when needed and actual evidence. Finishing the run does **not** mark
|
|
105
|
+
the task Done. If the requested work is verified and task completion is intended,
|
|
106
|
+
apply that task transition through the live run first, then finish the run.
|
|
107
|
+
Do not award yourself progress, XP or successful delivery from an exit code alone.
|
|
108
|
+
|
|
109
|
+
If the lease expired while you were disconnected, a final result may still close
|
|
110
|
+
the unchanged claim under its original user/profile. This does not renew the
|
|
111
|
+
lease or permit another task patch. A superseding claim or human takeover blocks
|
|
112
|
+
that late result. If the task was deleted, only `Failed` or `Cancelled` can close
|
|
113
|
+
the run, under current project permissions; never restore it to report success.
|
|
114
|
+
|
|
115
|
+
Finishing a run or human takeover changes the task's server revision without
|
|
116
|
+
changing its content. Reread both task and run before any later task edit;
|
|
117
|
+
an earlier task revision is deliberately stale, regardless of your local clock.
|
|
118
|
+
|
|
119
|
+
`Expired` is a server-ended abandoned run; it does not certify that the external
|
|
120
|
+
work failed. Run checkpoint history is bounded. `checkpointCount` can exceed the number of
|
|
121
|
+
retained checkpoints; absence of an older detail is not evidence it never
|
|
122
|
+
occurred. Read the confirmed task and run before reporting a final outcome.
|
|
123
|
+
Use `changes` or a bounded `watch` for a known cursor if needed. A successful API
|
|
124
|
+
response does not certify that another device has already displayed it.
|
|
125
|
+
|
|
126
|
+
## CLI and hosted recovery
|
|
127
|
+
|
|
128
|
+
```sh
|
|
129
|
+
geniustasker workflow show --topic runs --json
|
|
130
|
+
geniustasker commands describe --kind run.claim --json
|
|
131
|
+
geniustasker commands prepare --file claim-draft.json --context work --json
|
|
132
|
+
geniustasker commands execute --file prepared-command.json --context work --json
|
|
133
|
+
geniustasker resources list --scope project:PROJECT_ID --collection agentRuns --id RUN_ID --context work --json
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
These are individually requested calls. For a host that can explicitly report
|
|
137
|
+
real lifecycle events, use the [opt-in host event adapter](host-events.md). It
|
|
138
|
+
does not observe an uninstrumented process or run a background daemon.
|
|
139
|
+
Local preparation saves a private operation journal; retry
|
|
140
|
+
an uncertain operation unchanged with `commands retry --operation ID`.
|
|
141
|
+
Hosted ChatGPT preparation returns an immutable object instead; retain it for
|
|
142
|
+
the exact same retry using the authorized edit tool. Both use the same server
|
|
143
|
+
permissions, quota and concurrency rules. Never clear the journal to suppress
|
|
144
|
+
an uncertain result or create an untracked replacement operation.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Connect explicit host lifecycle events
|
|
2
|
+
|
|
3
|
+
Use this adapter only when the user has enabled reporting for an actual task and
|
|
4
|
+
your host can explicitly invoke the CLI or local MCP at known work events. It
|
|
5
|
+
does not install a hook into Codex, Claude or another agent host, observe an
|
|
6
|
+
unmodified process, launch commands, capture logs or run a background timer.
|
|
7
|
+
|
|
8
|
+
Before enabling it, discover the four `run.*` commands and read the project/task.
|
|
9
|
+
Ordinary account permissions, project agent contributions, quotas, leases and
|
|
10
|
+
run/task revisions still apply. The host must retain the current run identity and
|
|
11
|
+
confirmed revision; each event is one normal command, not a batch or bypass.
|
|
12
|
+
|
|
13
|
+
## Map facts to the right event
|
|
14
|
+
|
|
15
|
+
| Actual host event | Event `type` | Command and state |
|
|
16
|
+
| ------------------------------------------------------- | ---------------- | ------------------------------ |
|
|
17
|
+
| Authorized work starts on a current open task | `started` | `run.claim` → Working |
|
|
18
|
+
| A factual progress checkpoint is available | `checkpoint` | `run.checkpoint` → Working |
|
|
19
|
+
| The agent explicitly needs an input or dependency | `waiting` | `run.checkpoint` → Waiting |
|
|
20
|
+
| A concrete result awaits review | `review` | `run.checkpoint` → NeedsReview |
|
|
21
|
+
| Only the process exit is known | `process_exited` | `run.checkpoint` → NeedsReview |
|
|
22
|
+
| The agent explicitly reports its verified work finished | `finished` | `run.finish` → Completed |
|
|
23
|
+
| The agent explicitly reports failure | `failed` | `run.finish` → Failed |
|
|
24
|
+
| The agent actually stopped the work after cancellation | `cancelled` | `run.finish` → Cancelled |
|
|
25
|
+
|
|
26
|
+
`waiting`, `review` and `process_exited` require actionable `nextSteps`. An exit
|
|
27
|
+
code, silence or elapsed time cannot prove acceptance, failure or task completion.
|
|
28
|
+
No hook edits the task or awards XP. A `finished` run still does not mark its task
|
|
29
|
+
Done. A cancelled/replaced/expired lease may refuse a checkpoint; keep the real
|
|
30
|
+
event and report that refusal rather than starting an unauthorized replacement.
|
|
31
|
+
|
|
32
|
+
## Save the event before sending
|
|
33
|
+
|
|
34
|
+
For each actual event, the host persists one UUID `eventId` and its original
|
|
35
|
+
millisecond `occurredAt`. They become the command's `operationId` and `issuedAt`.
|
|
36
|
+
Save the complete event before invoking the adapter and reuse it unchanged on
|
|
37
|
+
retry. Do not create a new UUID/timestamp each time a shell hook is restarted.
|
|
38
|
+
|
|
39
|
+
The following fixtures show the file shape. Replace their IDs, timestamp and
|
|
40
|
+
revision with actual observations before saving your event; do not send the
|
|
41
|
+
example as claimed progress. `runId` is one UUID for the run, distinct from each
|
|
42
|
+
event's UUID. Starting uses a null run revision and the current task revision.
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"eventId": "11111111-1111-4111-8111-111111111111",
|
|
47
|
+
"occurredAt": 1794823200000,
|
|
48
|
+
"type": "started",
|
|
49
|
+
"scope": "project:PROJECT_ID_FROM_CURRENT_READ",
|
|
50
|
+
"epoch": "EPOCH_FROM_CURRENT_READ",
|
|
51
|
+
"runId": "22222222-2222-4222-8222-222222222222",
|
|
52
|
+
"expectedRevision": null,
|
|
53
|
+
"task": "TASK_ID_FROM_CURRENT_READ",
|
|
54
|
+
"taskRevision": "7",
|
|
55
|
+
"summary": "Starting the authorized recovery check.",
|
|
56
|
+
"leaseSeconds": 300
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
geniustasker runs event --file started.json --prepare --context work --json
|
|
62
|
+
geniustasker runs event --file started.json --context work --json
|
|
63
|
+
geniustasker commands inspect --operation EVENT_UUID --context work --json
|
|
64
|
+
geniustasker commands retry --operation EVENT_UUID --context work --json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`--prepare` persists the exact command locally and sends no API request. Repeating
|
|
68
|
+
preparation preserves any existing uncertainty, cooldown or receipt. Sending the
|
|
69
|
+
same event uses the normal immutable journal; it cannot replace a different
|
|
70
|
+
request under that ID. A local receipt replay is explicitly labeled
|
|
71
|
+
`local_receipt`, not a fresh server observation.
|
|
72
|
+
|
|
73
|
+
A later event uses the same run ID but its latest revision from a confirmed
|
|
74
|
+
receipt/read and a distinct event ID. For example, if the host only knows its
|
|
75
|
+
process stopped:
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"eventId": "33333333-3333-4333-8333-333333333333",
|
|
80
|
+
"occurredAt": 1794823220000,
|
|
81
|
+
"type": "process_exited",
|
|
82
|
+
"scope": "project:PROJECT_ID_FROM_CURRENT_READ",
|
|
83
|
+
"epoch": "EPOCH_FROM_CURRENT_READ",
|
|
84
|
+
"runId": "22222222-2222-4222-8222-222222222222",
|
|
85
|
+
"expectedRevision": "8",
|
|
86
|
+
"summary": "The host process exited; acceptance has not been checked.",
|
|
87
|
+
"nextSteps": "Inspect the produced changes and run the agreed checks."
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Host integration and recovery
|
|
92
|
+
|
|
93
|
+
For a Codex or Claude host integration you control, configure an **opt-in**
|
|
94
|
+
callback to invoke `geniustasker runs event --file` on the host's saved, sanitized
|
|
95
|
+
event. If no supported callback exists, have the agent explicitly call the local
|
|
96
|
+
MCP tool at meaningful checkpoints. Do not claim that installing this skill or
|
|
97
|
+
adding an MCP connection automatically instruments that host.
|
|
98
|
+
|
|
99
|
+
Local MCP exposes `tasker_run_event` with `{ "event": EVENT_OBJECT,
|
|
100
|
+
"prepareOnly": true }` to prepare, or `{ "event": EVENT_OBJECT }` to send. It
|
|
101
|
+
uses the same journal as `tasker_retry_command`. Hosted ChatGPT uses the existing
|
|
102
|
+
prepared `run.*` command and task edit tool; it has no local event adapter or
|
|
103
|
+
filesystem access.
|
|
104
|
+
|
|
105
|
+
Only send the allowed structured fields. `summary` is bounded to 2,000 characters,
|
|
106
|
+
`nextSteps` to 4,000 and evidence to eight labeled HTTPS links. Do not send raw
|
|
107
|
+
stdout/stderr, environment, arguments, prompts, transcripts, credentials or
|
|
108
|
+
signed private links. Unknown fields are refused rather than forwarded.
|
|
109
|
+
|
|
110
|
+
Serialize events for a run and keep confirmed revisions. An uncertain result
|
|
111
|
+
requires replay of the original operation before conflicting follow-up work.
|
|
112
|
+
Respect `retryAfterSeconds` and the saved cooldown; the adapter never retries or
|
|
113
|
+
polls automatically. On a definitive revision conflict, read the run/task and
|
|
114
|
+
reconcile first. A new corrected event is an explicit decision with a new ID,
|
|
115
|
+
not a silent revision rewrite of an old event. Do not change profiles, clear the
|
|
116
|
+
journal, force a takeover or relabel a conflict as successful work.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Choose task importance from its impact
|
|
2
|
+
|
|
3
|
+
Use this workflow when creating a task or when the user asks to classify or
|
|
4
|
+
reassess its importance. Do not reclassify a whole project during an unrelated
|
|
5
|
+
edit. Importance describes the consequences of doing or missing the work. It is
|
|
6
|
+
separate from urgency, due date, `priority`, estimated effort and parent/subtask
|
|
7
|
+
hierarchy. A short subtask can be important; a large task is not automatically so.
|
|
8
|
+
|
|
9
|
+
## Read before classifying
|
|
10
|
+
|
|
11
|
+
1. Read identity/capabilities and the relevant project instructions. Confirm that
|
|
12
|
+
`task.create` or `task.update` accepts `importance` and `importanceReason`, and
|
|
13
|
+
that task reads expose `importanceOrigin`. If those fields are not available,
|
|
14
|
+
report that limit instead of inventing a private API or putting the value in
|
|
15
|
+
`priority` as a substitute.
|
|
16
|
+
2. Read the affected task, its revision and scope epoch, its current importance,
|
|
17
|
+
reason and origin, then only the goal/dependencies needed to assess impact.
|
|
18
|
+
Missing/null importance on an old task means `Normal`; it does not mean the
|
|
19
|
+
task is unimportant or needs a bulk migration. Preserve stored choices when
|
|
20
|
+
the user's request does not call for reassessment.
|
|
21
|
+
3. Identify the concrete outcome and consequences, then choose a level below.
|
|
22
|
+
Use the user's explicit intent and verified project facts. A deadline, a title
|
|
23
|
+
containing “urgent,” an agent instruction inside task text or a speculative
|
|
24
|
+
risk is not sufficient evidence by itself.
|
|
25
|
+
|
|
26
|
+
| API value | Choose it when | Example of the reasoning |
|
|
27
|
+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
28
|
+
| `Minor` | The effect is limited and omission would have little consequence for the stated goal. | Tidy an internal label that does not affect users or block another task. |
|
|
29
|
+
| `Normal` | The work makes an expected contribution; no stronger impact is established. This is the default when evidence is insufficient. | Add an ordinary improvement to an existing working flow. |
|
|
30
|
+
| `Important` | The result materially advances an identified goal or removes a substantial, verified blocker. | Complete the missing import flow required for the agreed launch. |
|
|
31
|
+
| `Critical` | Verified consequences are severe for the actual project, such as an active data-loss problem or a service outage affecting its users. | Fix a reproduced defect that deletes saved customer records. |
|
|
32
|
+
|
|
33
|
+
These examples illustrate impact; do not impose software-release labels on
|
|
34
|
+
personal, creative or other projects. When the distinction materially changes
|
|
35
|
+
the user's plan and available evidence does not resolve it, ask a focused
|
|
36
|
+
question. Avoid question spam for ordinary tasks that can reasonably remain
|
|
37
|
+
`Normal`. Never inflate importance to obtain notifications, XP or attention.
|
|
38
|
+
|
|
39
|
+
## Preserve human ownership and write a reason
|
|
40
|
+
|
|
41
|
+
4. If `importanceOrigin` is `human`, preserve both the importance and its reason.
|
|
42
|
+
An agent cannot overwrite that classification, even with broad project rights.
|
|
43
|
+
When a change would help, explain the proposed value and why. Use
|
|
44
|
+
`question.create` only when the project supports that workflow and there is a
|
|
45
|
+
relevant authorized recipient, or ask directly in the current conversation.
|
|
46
|
+
The human must make the change through the application. A question answer or
|
|
47
|
+
an approval receipt is not a bypass for this field's protection.
|
|
48
|
+
5. When an agent creates or changes a task to `Important` or `Critical`, provide
|
|
49
|
+
a short `importanceReason` of at most 400 characters. State the concrete
|
|
50
|
+
consequence or goal and the evidence available, not merely “important” or
|
|
51
|
+
“urgent.” Example: “This import flow is required for the launch agreed in the
|
|
52
|
+
project goal; the current onboarding cannot complete without it.” Only use
|
|
53
|
+
that reason when the referenced goal/blocker really exists. Reasons for
|
|
54
|
+
`Minor`/`Normal` are optional; keep an existing useful reason when appropriate.
|
|
55
|
+
Never submit `importanceOrigin`: the server owns the attribution. Do not copy
|
|
56
|
+
private credentials or unrelated personal information into the reason.
|
|
57
|
+
|
|
58
|
+
## Apply and verify
|
|
59
|
+
|
|
60
|
+
6. Use the ordinary immutable command workflow. For a task already read, create
|
|
61
|
+
a `task.update` draft with its real scope, epoch, ID and current revision. The
|
|
62
|
+
relevant `data` can be:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"importance": "Important",
|
|
67
|
+
"importanceReason": "The approved launch depends on this import flow working."
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
This is only the data fragment, not a complete executable command. Populate
|
|
72
|
+
the envelope from the live read and confirm that the reason fits the task.
|
|
73
|
+
Local CLI: `geniustasker commands prepare --file importance-draft.json --json`,
|
|
74
|
+
then `geniustasker commands retry --operation OPERATION_ID --json` using the
|
|
75
|
+
returned operation ID. Hosted MCP: prepare the command, then pass that exact
|
|
76
|
+
command object to the permitted edit tool. Retry an uncertain outcome with
|
|
77
|
+
the same operation; do not generate a replacement request blindly.
|
|
78
|
+
|
|
79
|
+
7. Read back the task. `task_importance_human_review_required` is a final conflict
|
|
80
|
+
requiring human action, not a transient error. Do not clear the origin,
|
|
81
|
+
recreate the task, switch transport/profile or repeatedly retry to get around
|
|
82
|
+
it. For an ordinary revision conflict, reread and reconcile the intent before
|
|
83
|
+
preparing a new operation. For `task_importance_reason_required`, add a real
|
|
84
|
+
justification to a newly prepared command only after confirming the request
|
|
85
|
+
was rejected and the task's current state.
|
|
86
|
+
|
|
87
|
+
The change can appear in the task audit. It does not by itself establish that a
|
|
88
|
+
push was sent, XP was awarded or an overlay was displayed. Notification thresholds
|
|
89
|
+
and Flutter presentation are separate capabilities; discover them rather than
|
|
90
|
+
promising a future interface from these fields alone.
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Link a goal to measured evidence
|
|
2
|
+
|
|
3
|
+
Use this workflow only for a requested goal and when live capabilities advertise
|
|
4
|
+
`metric.goal.create`, `metric.goal.update` and `metric.goal.delete`. A definition
|
|
5
|
+
or observation command never creates a goal implicitly. Read the
|
|
6
|
+
[definition](metrics.md) and [observation](metrics-observations.md) workflows first.
|
|
7
|
+
Existing recurring task goals and YouTube/Spotify goals remain separate.
|
|
8
|
+
|
|
9
|
+
## Read and explain the source
|
|
10
|
+
|
|
11
|
+
Use `metrics:read` / `metrics:write`; task and ordinary goal grants do not include
|
|
12
|
+
these permissions. Configuration also requires current project owner/admin
|
|
13
|
+
rights or the connected personal owner. Use `actor.ownerId` from identity for
|
|
14
|
+
`personal:<owner>`, never another account or a profile ID. The source definition
|
|
15
|
+
must exist in the **same scope** and express the intended unit and aggregation.
|
|
16
|
+
Creation and reactivation require an unarchived source; existing goals can still
|
|
17
|
+
be paused or archived while their source is archived, as explained below.
|
|
18
|
+
`metricId` cannot change on an existing goal.
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
geniustasker metrics list --scope project:PROJECT --id METRIC_UUID --json
|
|
22
|
+
geniustasker metrics list --scope project:PROJECT --collection metricGoals --json
|
|
23
|
+
geniustasker metrics list --scope personal:OWNER --collection personalMetricGoals --id GOAL_UUID --json
|
|
24
|
+
geniustasker commands describe --kind metric.goal.create --json
|
|
25
|
+
geniustasker workflow show --topic metrics --json
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
In MCP use `tasker_read_metrics` and `tasker_edit_metrics`. Read one bounded page
|
|
29
|
+
at a time; preserve the returned epoch, checkpoint and continuation. Goal
|
|
30
|
+
collections accept an exact goal `id`; `metricId` filtering is reserved for
|
|
31
|
+
observation/correction history. Do not scan all history to recompute progress.
|
|
32
|
+
|
|
33
|
+
## Choose the target and period
|
|
34
|
+
|
|
35
|
+
`target` is a decimal **string** in the source metric's unit, with a dot and at
|
|
36
|
+
most its configured precision. No exponent, thousands separator, percentage
|
|
37
|
+
symbol or JSON number. For a Ratio with `ratioScale:100`, target `"75"` means
|
|
38
|
+
75 percent; for scale 1 use `"0.75"` if the precision supports it. Preserve exact
|
|
39
|
+
decimal arithmetic instead of converting the threshold through floating point.
|
|
40
|
+
`AtLeast` means greater than or equal; `AtMost` means less than or equal.
|
|
41
|
+
|
|
42
|
+
`window:null` uses the recorded lifetime. A fixed window has explicit
|
|
43
|
+
timezone-qualified `start` and `end`, with start **included** and end **excluded**.
|
|
44
|
+
Choose boundaries in the user's intended timezone, then retain those instants.
|
|
45
|
+
It is not a recurring or rolling period. A goal called “This week” does not
|
|
46
|
+
advance itself next week. Date membership uses the observation's `observedAt`,
|
|
47
|
+
including late arrivals, corrections and voids, not its ingestion time.
|
|
48
|
+
|
|
49
|
+
Choose `OnReach` for completion as soon as a complete eligible result satisfies
|
|
50
|
+
the target. Choose `AtEnd` to wait for the fixed window's end; it requires a
|
|
51
|
+
non-null window. An upper-bound budget often needs `AtEnd`, since being below
|
|
52
|
+
the limit early does not establish the final result. Later evidence can still
|
|
53
|
+
correct a window's result after its end.
|
|
54
|
+
|
|
55
|
+
## Persist explicit configuration
|
|
56
|
+
|
|
57
|
+
This `data` example assumes a EUR Counter/Sum source with precision 2. The UUID
|
|
58
|
+
is illustrative: use the actual definition ID and the agreed dates and target.
|
|
59
|
+
Notification and coach options are off because the example does not request
|
|
60
|
+
either. Titles and explanations may use the user's language; API names and enum
|
|
61
|
+
values stay unchanged.
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"configuration": {
|
|
66
|
+
"metricId": "00000000-0000-4000-8000-000000000001",
|
|
67
|
+
"title": "Budget de novembre",
|
|
68
|
+
"description": "Dépenses vérifiées en euros sur novembre, clôture au terme de la période.",
|
|
69
|
+
"target": "500.00",
|
|
70
|
+
"comparison": "AtMost",
|
|
71
|
+
"window": {
|
|
72
|
+
"start": "2026-11-01T00:00:00+01:00",
|
|
73
|
+
"end": "2026-12-01T00:00:00+01:00"
|
|
74
|
+
},
|
|
75
|
+
"completion": "AtEnd",
|
|
76
|
+
"notifyCompleted": false,
|
|
77
|
+
"coachSignal": false,
|
|
78
|
+
"paused": false,
|
|
79
|
+
"archived": false
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Create with a new stable goal UUID, the scope's current epoch and
|
|
85
|
+
`expectedRevision:null`. For update, reread the goal and use its current revision
|
|
86
|
+
with the complete configuration, preserving unchanged choices. `metric.goal.delete`
|
|
87
|
+
takes empty `data` and a current revision; it does not delete the source metric
|
|
88
|
+
or its evidence. Never send the internal action, progress, scan cursor,
|
|
89
|
+
generation, attribution or completion fields.
|
|
90
|
+
|
|
91
|
+
Keep configuration concise: the current service limits it to 2,048 UTF-8 bytes
|
|
92
|
+
and admits at most 12 goals per metric, 128 per scope. These bounds apply in
|
|
93
|
+
addition to individual field limits. A refusal is not a reason to clone the
|
|
94
|
+
metric, split the same goal or rotate an agent profile.
|
|
95
|
+
|
|
96
|
+
Use the normal immutable command journal: prepare, then execute/retry the exact
|
|
97
|
+
operation. A lost acknowledgment is not a reason to create a second goal.
|
|
98
|
+
Revision conflicts require rereading before a new intentional edit. Hosted MCP
|
|
99
|
+
does not retain a local journal, so preserve the prepared request yourself.
|
|
100
|
+
Each read/write uses normal permissions and budgets; no bulk loop is implied.
|
|
101
|
+
|
|
102
|
+
## Report trustworthy progress
|
|
103
|
+
|
|
104
|
+
- `phase:"Pending"` means historical evaluation is incomplete. A bounded server
|
|
105
|
+
scan may already expose partial summary data; do not present it as the final
|
|
106
|
+
total, failure or success. Do not busy-poll or try to advance `scanAfter` yourself.
|
|
107
|
+
- `phase:"Ready"` means the summary is complete for the recorded evidence.
|
|
108
|
+
Use the server's `reached` result; comparison uses exact unrounded arithmetic.
|
|
109
|
+
`summary.value` is a nullable, rounded display string and can appear equal to
|
|
110
|
+
a threshold that the exact result has not reached. Summary integer fields
|
|
111
|
+
follow the [same scaling rules](metrics-observations.md#read-the-consolidated-result)
|
|
112
|
+
as the source; a goal's summary is restricted to its configured window.
|
|
113
|
+
- No active evidence yields `summary.value:null`, not a measured zero, even for
|
|
114
|
+
an `AtMost` target. Ready does not itself prove recent or complete external
|
|
115
|
+
data: inspect `latest.observedAt` and the definition's freshness configuration.
|
|
116
|
+
- `completedAt` records the first verified eligible completion. It is retained
|
|
117
|
+
through corrections, edits and retries. The current `reached` value can later
|
|
118
|
+
become false without erasing that historical fact. Do not recreate a goal to
|
|
119
|
+
repeat a reward, or confuse a completion record with confirmed push delivery.
|
|
120
|
+
|
|
121
|
+
`paused:true` retains progress tracking while suppressing automatic completion
|
|
122
|
+
reactions. `archived:true` stops tracking; restoration rebuilds progress before
|
|
123
|
+
reacting. Neither option discards evidence or clears prior completion.
|
|
124
|
+
|
|
125
|
+
Archiving the **source metric** also parks its goals’ pending scans and scheduled
|
|
126
|
+
checks without discarding progress. You can pause or archive an existing goal,
|
|
127
|
+
and clarify its title or description while keeping it paused/archived. You
|
|
128
|
+
cannot create a new goal, reactivate an archived goal, or change its target,
|
|
129
|
+
comparison, completion rule or window until the source is restored. A
|
|
130
|
+
`metric_paused` refusal is not a reason to reactivate the source without the
|
|
131
|
+
user’s request.
|
|
132
|
+
|
|
133
|
+
Restoring the source resumes a retained scan cursor or an outstanding `AtEnd`
|
|
134
|
+
boundary. A partial scan cannot complete early, and an `AtEnd` goal waits until
|
|
135
|
+
its boundary. Explicit goal pauses and archives remain in effect; restoration
|
|
136
|
+
does not clear them or reset `completedAt`.
|
|
137
|
+
|
|
138
|
+
`notifyCompleted` and `coachSignal` are explicit opt-ins; leave them false unless
|
|
139
|
+
requested, and preserve existing choices on update. They describe eligibility,
|
|
140
|
+
not evidence that a message was delivered or XP awarded. Recipient preferences
|
|
141
|
+
and the live service still apply. `coachSignal` does not issue an LLM request,
|
|
142
|
+
invoke an external agent, execute code or install a collector. Report saved
|
|
143
|
+
configuration, calculated progress and observed delivery as separate facts.
|