@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.
Files changed (40) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +14 -1
  3. package/docs/ARCHITECTURE.md +15 -13
  4. package/docs/CHATGPT.md +6 -0
  5. package/docs/CLI.md +153 -5
  6. package/docs/INTEGRATIONS.md +25 -2
  7. package/docs/MEMORY.md +9 -0
  8. package/docs/WORKFLOWS.md +14 -0
  9. package/examples/codex.toml +1 -1
  10. package/examples/mcp.json +1 -1
  11. package/mcp.json +1 -1
  12. package/package.json +2 -2
  13. package/plugin.json +1 -1
  14. package/remote/tool-catalog.json +296 -1
  15. package/remote/workflows.json +53 -2
  16. package/skills/geniustasker/SKILL.md +15 -1
  17. package/skills/geniustasker/references/agent-runs.md +144 -0
  18. package/skills/geniustasker/references/host-events.md +116 -0
  19. package/skills/geniustasker/references/importance.md +90 -0
  20. package/skills/geniustasker/references/metric-goals.md +143 -0
  21. package/skills/geniustasker/references/metrics-observations.md +184 -0
  22. package/skills/geniustasker/references/metrics.md +136 -0
  23. package/skills/geniustasker/references/protocols.md +156 -0
  24. package/skills/geniustasker/references/updates.md +31 -0
  25. package/skills/geniustasker-graph/SKILL.md +10 -0
  26. package/skills/geniustasker-memory/SKILL.md +19 -6
  27. package/skills/geniustasker-memory/references/knowledge-workflows.md +42 -0
  28. package/skills/geniustasker-planning/SKILL.md +6 -1
  29. package/src/changes.mjs +3 -5
  30. package/src/cli.mjs +108 -14
  31. package/src/command-catalog.mjs +849 -562
  32. package/src/command-input-schemas.d.mts +8 -0
  33. package/src/command-input-schemas.mjs +1021 -0
  34. package/src/commands.mjs +78 -25
  35. package/src/mcp.mjs +48 -20
  36. package/src/protocols.mjs +122 -0
  37. package/src/resources.mjs +98 -0
  38. package/src/run-events.mjs +145 -0
  39. package/src/update-runtime.mjs +169 -0
  40. 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.