workbite 0.1.18 → 0.1.20

package/skills/workbite-native/references/task-fields.md

@@ -1,208 +1,208 @@
-# Advertised Task packet fields
-
-Use a field only when the exact installed command's `packet_schema` admits
-it: create's `properties`, or update's `properties.changes.properties`.
-Probe the launcher and running owner selected by the Skill. A command key,
-version, this reference or an MCP tool name alone does not prove support.
-MCP `tools/list` must expose matching types too. With no schema, retain only
-the documented original subset (create: title/detail/follows_task_id;
-update: detail/status). Report missing requested fields; never silently omit
-them or use legacy apply, another install or direct Store access.
-
-These additive fields are unreleased source work, not a claim about any
-installed bundle. The nested extension below is the NESTED FIELDS CONTRACT;
-the native domain source implements these structures. Matching
-Python/client/MCP completion and advertisements remain required before
-claiming cross-implementation support. A working-source edit alone is not a
-completed capability.
-
-## Normal fields
-
-| Field | JSON value and meaning |
-|---|---|
-| `title` | Nonblank string; required on create. No string coercion. |
-| `detail` | String, including empty string; no null or coercion. |
-| `status` | `open`, `started`, `done`, `dropped`; only the status the user requested. |
-| `priority` | `P0`, `P1`, `P2`, `P3`. |
-| `due`, `scheduled` | Real ISO calendar date `YYYY-MM-DD`, or null to clear. |
-| `estimate_minutes` | Integer 1–1440, or null to clear; booleans/fractions are invalid. |
-| `tags` | Array of strings, normalized by the owner; `[]` clears. |
-| `parent_id` | Existing Task ID, or null to clear; no self-parenting/cycles. |
-| `dependencies` | Array of existing Task IDs, with graph validation; `[]` clears. |
-| `objective_ids` | Array of existing Objective IDs; `[]` clears Task links. |
-| `key_result_refs` | Array of exact `{objective_id, key_result_id}` string pairs, each an existing valid pair; `[]` clears. |
-| `follows_task_id` | Optional existing Task ID on create only: receipt provenance, never a parent/dependency. |
-
-Omission leaves a field unchanged on update and uses owner defaults on
-create. Null clears only nullable fields; arrays use `[]`, never null.
-Owner validation and normalization decide valid references, deduplication
-and relationships. Task linking does not authorize Objective/Key Result CRUD.
-
-`id`, `uid`, `created`, `created_at`, `updated_at`, `revision`, `status_fact_id`, actor
-identity, audit and status facts are generated/protected. Do not inject them
-or source history through ordinary packets. An explicitly requested create
-status bootstraps fresh local status facts and audit; it cannot forge old
-history. Normalized values appear in the committed `data.task` projection
-when advertised, subject to the envelope's `data.omitted` size reporting.
-
-## Complete create example
-
-Only send this when all fields are advertised and the referenced records
-exist in the verified workspace. Replace example values with the user's
-requested values. Choose one stable intent ID before sending.
-
-```json
-{
-  "title": "Verify login redirect",
-  "detail": "Cover refresh and return-to behavior.",
-  "status": "started",
-  "priority": "P1",
-  "due": "2026-10-20",
-  "scheduled": "2026-10-16",
-  "estimate_minutes": 45,
-  "tags": ["auth", "regression"],
-  "parent_id": "T-0001",
-  "dependencies": ["T-0002"],
-  "objective_ids": ["O-0001"],
-  "key_result_refs": [{"objective_id": "O-0001", "key_result_id": "KR-0001"}],
-  "follows_task_id": "T-0002"
-}
-```
-
-One intent creates at most one Task. A user-requested batch has one logical
-write/intent per Task, with no five-Task reapproval cap. This is not an atomic
-multi-Task import: use an advertised transfer operation for a whole graph.
-
-## Complete update example
-
-Read context for `T-0003` first and use its actual revision. This example
-updates every normal field and demonstrates clearing nullable/array fields.
-
-```json
-{
-  "task_id": "T-0003",
-  "expected_revision": 4,
-  "changes": {
-    "title": "Verify login return-to behavior",
-    "detail": "Add a regression for the reported redirect.",
-    "status": "open",
-    "priority": "P2",
-    "due": null,
-    "scheduled": "2026-10-17",
-    "estimate_minutes": null,
-    "tags": [],
-    "parent_id": null,
-    "dependencies": [],
-    "objective_ids": [],
-    "key_result_refs": []
-  }
-}
-```
-
-`changes` is nonempty. Never put `follows_task_id` in update. The ordinary
-packet limit stays 32768 UTF-8 bytes, without BOM or duplicate JSON keys.
-The transfer archive limit does not enlarge ordinary Task packets.
-
-## Notes and subtasks extension
-
-These fields require explicit intent to replace the entire array, plus the
-same Task revision CAS and durable receipt as other fields. Each array has
-at most 128 items; `[]` clears it, null is invalid, and omission leaves it
-unchanged on update (empty arrays by default on create). These are replacement
-arrays, not append operations or partial child patches: include every note
-or subtask the user wants retained. Read the current array before replacing
-it; a bounded view that omitted it cannot establish what must be preserved.
-
-| Field/item | Exact admitted structure |
-|---|---|
-| `notes` | Array of objects with required `text` and optional `date`; no other keys. |
-| note `text` | Nonblank string without NUL, trimmed by the owner. |
-| note `date` | Real ISO calendar date `YYYY-MM-DD`; omitted means the owner's current civil day. Null is invalid. |
-| `subtasks` | Array of objects with required `title` and optional `id`, `priority`, `status`; no other keys. |
-| subtask `title` | Nonblank string without NUL, trimmed by the owner. |
-| subtask `id` | Optional canonical `S-[1-9][0-9]*`, numeric suffix at most 9007199254740991; no leading zeros, unique within this parent's replacement array. |
-| subtask `priority` | Optional `P0`/`P1`/`P2`/`P3`, default `P2`. |
-| subtask `status` | Optional `open`/`started`/`done`/`dropped`, default `open`. |
-
-Omitted Subtask IDs allocate deterministically, in input order, above the
-maximum of IDs in the parent's existing array and explicitly supplied IDs.
-Keep a retained subtask's ID explicitly; omitting it requests allocation,
-not title matching. This is a parent-scoped display ID, not permission to
-supply a Task ID/UUID, status fact or audit identity. Exhaustion refuses.
-There is no claim of a separate durable Subtask high-water beyond that
-existing/supplied-array rule.
-
-A supplied note date is user note data, never evidence of when the local
-system performed an action. Defaults resolve only after durable receipt
-lookup: an identical same-intent replay on another day retains the original
-note dates and allocated IDs. Normalized arrays appear in new committed
-Task projections; older stored receipts can lack the new arrays.
-
-When the user requested this content, a small create packet is:
-
-```json
-{
-  "title": "Check redirect behavior",
-  "notes": [{"text": "User reported the refresh case."}],
-  "subtasks": [{"title": "Reproduce refresh"}]
-}
-```
-
-After reading `T-0003` and its actual revision, a whole-array replacement is:
-
-```json
-{
-  "task_id": "T-0003",
-  "expected_revision": 4,
-  "changes": {
-    "notes": [{"text": "Confirmed the reported case.", "date": "2026-10-15"}],
-    "subtasks": [
-      {"id": "S-2", "title": "Reproduce refresh", "priority": "P1", "status": "done"},
-      {"title": "Verify return-to URL", "priority": "P2", "status": "open"}
-    ]
-  }
-}
-```
-
-Here an omitted ID is above both existing IDs and `S-2`; it is not necessarily
-`S-3` if the current parent already has a higher ID. A subtask marked done
-does not change the parent Task status. Code completion, dates, or child
-statuses never authorize an automatic parent done transition.
-
-## Observable field-change audit extension
-
-The NESTED contract also requires bounded `field_changes` on the existing
-`task.created`/`task.updated` activity event types for normal and nested
-fields: each changed field has `before` and `after` observations. The owner
-creates audit identity/time and status facts; callers never send those fields
-in a Task packet. Large values may be represented by bounded digest/truncation
-evidence instead of full content. Do not claim arbitrary historical values
-can be recovered from such an event. A normalized no-change write still has
-its own durable receipt and must not be presented as a new status transition.
-This describes the extension contract, not completed cross-implementation
-proof until the corresponding owner candidates pass review/integration.
-
-## CAS, replay and uncertain receipts
-
-An update's `expected_revision` is compare-and-swap (CAS). On a definite
-`revision_conflict`, re-read; if the intended change remains valid without
-overwriting someone else's change, send a new revision/packet with a new
-intent ID. Existing user intent continues to apply.
-
-Receipt lookup precedes CAS. Same intent + identical packet returns the
-original committed snapshot even after later edits. Read context for current
-state. Different content under that intent is `idempotency_conflict`.
-
-A fresh intent is a distinct logical operation, not replay or content-based
-deduplication. A fresh create can create another Task with identical text.
-A fresh update rechecks CAS and recomputes omitted dates/IDs against current
-state; it can be rejected or change values. Do not assume identical content
-under different intents must yield no_change. Never use a fresh intent to
-force an unresolved same-intent write through.
-
-On response loss or `commit_unknown`, retain the same intent and packet
-bytes, stop writing and read `operation-status`. `committed` settles it;
-`unknown` never means not written. Only `reason: no_receipt` permits an
-identical resend under the same intent. Never change its packet or switch to
-a new intent to force an unknown write through. A checkpoint's unknown
-outcome is reported without appending a replacement checkpoint.
+# Advertised Task packet fields
+
+Use a field only when the exact installed command's `packet_schema` admits
+it: create's `properties`, or update's `properties.changes.properties`.
+Probe the launcher and running owner selected by the Skill. A command key,
+version, this reference or an MCP tool name alone does not prove support.
+MCP `tools/list` must expose matching types too. With no schema, retain only
+the documented original subset (create: title/detail/follows_task_id;
+update: detail/status). Report missing requested fields; never silently omit
+them or use legacy apply, another install or direct Store access.
+
+These additive fields are unreleased source work, not a claim about any
+installed bundle. The nested extension below is the NESTED FIELDS CONTRACT;
+the native domain source implements these structures. Matching
+Python/client/MCP completion and advertisements remain required before
+claiming cross-implementation support. A working-source edit alone is not a
+completed capability.
+
+## Normal fields
+
+| Field | JSON value and meaning |
+|---|---|
+| `title` | Nonblank string; required on create. No string coercion. |
+| `detail` | String, including empty string; no null or coercion. |
+| `status` | `open`, `started`, `done`, `dropped`; only the status the user requested. |
+| `priority` | `P0`, `P1`, `P2`, `P3`. |
+| `due`, `scheduled` | Real ISO calendar date `YYYY-MM-DD`, or null to clear. |
+| `estimate_minutes` | Integer 1–1440, or null to clear; booleans/fractions are invalid. |
+| `tags` | Array of strings, normalized by the owner; `[]` clears. |
+| `parent_id` | Existing Task ID, or null to clear; no self-parenting/cycles. |
+| `dependencies` | Array of existing Task IDs, with graph validation; `[]` clears. |
+| `objective_ids` | Array of existing Objective IDs; `[]` clears Task links. |
+| `key_result_refs` | Array of exact `{objective_id, key_result_id}` string pairs, each an existing valid pair; `[]` clears. |
+| `follows_task_id` | Optional existing Task ID on create only: receipt provenance, never a parent/dependency. |
+
+Omission leaves a field unchanged on update and uses owner defaults on
+create. Null clears only nullable fields; arrays use `[]`, never null.
+Owner validation and normalization decide valid references, deduplication
+and relationships. Task linking does not authorize Objective/Key Result CRUD.
+
+`id`, `uid`, `created`, `created_at`, `updated_at`, `revision`, `status_fact_id`, actor
+identity, audit and status facts are generated/protected. Do not inject them
+or source history through ordinary packets. An explicitly requested create
+status bootstraps fresh local status facts and audit; it cannot forge old
+history. Normalized values appear in the committed `data.task` projection
+when advertised, subject to the envelope's `data.omitted` size reporting.
+
+## Complete create example
+
+Only send this when all fields are advertised and the referenced records
+exist in the verified workspace. Replace example values with the user's
+requested values. Choose one stable intent ID before sending.
+
+```json
+{
+  "title": "Verify login redirect",
+  "detail": "Cover refresh and return-to behavior.",
+  "status": "started",
+  "priority": "P1",
+  "due": "2026-10-20",
+  "scheduled": "2026-10-16",
+  "estimate_minutes": 45,
+  "tags": ["auth", "regression"],
+  "parent_id": "T-0001",
+  "dependencies": ["T-0002"],
+  "objective_ids": ["O-0001"],
+  "key_result_refs": [{"objective_id": "O-0001", "key_result_id": "KR-0001"}],
+  "follows_task_id": "T-0002"
+}
+```
+
+One intent creates at most one Task. A user-requested batch has one logical
+write/intent per Task, with no five-Task reapproval cap. This is not an atomic
+multi-Task import: use an advertised transfer operation for a whole graph.
+
+## Complete update example
+
+Read context for `T-0003` first and use its actual revision. This example
+updates every normal field and demonstrates clearing nullable/array fields.
+
+```json
+{
+  "task_id": "T-0003",
+  "expected_revision": 4,
+  "changes": {
+    "title": "Verify login return-to behavior",
+    "detail": "Add a regression for the reported redirect.",
+    "status": "open",
+    "priority": "P2",
+    "due": null,
+    "scheduled": "2026-10-17",
+    "estimate_minutes": null,
+    "tags": [],
+    "parent_id": null,
+    "dependencies": [],
+    "objective_ids": [],
+    "key_result_refs": []
+  }
+}
+```
+
+`changes` is nonempty. Never put `follows_task_id` in update. The ordinary
+packet limit stays 32768 UTF-8 bytes, without BOM or duplicate JSON keys.
+The transfer archive limit does not enlarge ordinary Task packets.
+
+## Notes and subtasks extension
+
+These fields require explicit intent to replace the entire array, plus the
+same Task revision CAS and durable receipt as other fields. Each array has
+at most 128 items; `[]` clears it, null is invalid, and omission leaves it
+unchanged on update (empty arrays by default on create). These are replacement
+arrays, not append operations or partial child patches: include every note
+or subtask the user wants retained. Read the current array before replacing
+it; a bounded view that omitted it cannot establish what must be preserved.
+
+| Field/item | Exact admitted structure |
+|---|---|
+| `notes` | Array of objects with required `text` and optional `date`; no other keys. |
+| note `text` | Nonblank string without NUL, trimmed by the owner. |
+| note `date` | Real ISO calendar date `YYYY-MM-DD`; omitted means the owner's current civil day. Null is invalid. |
+| `subtasks` | Array of objects with required `title` and optional `id`, `priority`, `status`; no other keys. |
+| subtask `title` | Nonblank string without NUL, trimmed by the owner. |
+| subtask `id` | Optional canonical `S-[1-9][0-9]*`, numeric suffix at most 9007199254740991; no leading zeros, unique within this parent's replacement array. |
+| subtask `priority` | Optional `P0`/`P1`/`P2`/`P3`, default `P2`. |
+| subtask `status` | Optional `open`/`started`/`done`/`dropped`, default `open`. |
+
+Omitted Subtask IDs allocate deterministically, in input order, above the
+maximum of IDs in the parent's existing array and explicitly supplied IDs.
+Keep a retained subtask's ID explicitly; omitting it requests allocation,
+not title matching. This is a parent-scoped display ID, not permission to
+supply a Task ID/UUID, status fact or audit identity. Exhaustion refuses.
+There is no claim of a separate durable Subtask high-water beyond that
+existing/supplied-array rule.
+
+A supplied note date is user note data, never evidence of when the local
+system performed an action. Defaults resolve only after durable receipt
+lookup: an identical same-intent replay on another day retains the original
+note dates and allocated IDs. Normalized arrays appear in new committed
+Task projections; older stored receipts can lack the new arrays.
+
+When the user requested this content, a small create packet is:
+
+```json
+{
+  "title": "Check redirect behavior",
+  "notes": [{"text": "User reported the refresh case."}],
+  "subtasks": [{"title": "Reproduce refresh"}]
+}
+```
+
+After reading `T-0003` and its actual revision, a whole-array replacement is:
+
+```json
+{
+  "task_id": "T-0003",
+  "expected_revision": 4,
+  "changes": {
+    "notes": [{"text": "Confirmed the reported case.", "date": "2026-10-15"}],
+    "subtasks": [
+      {"id": "S-2", "title": "Reproduce refresh", "priority": "P1", "status": "done"},
+      {"title": "Verify return-to URL", "priority": "P2", "status": "open"}
+    ]
+  }
+}
+```
+
+Here an omitted ID is above both existing IDs and `S-2`; it is not necessarily
+`S-3` if the current parent already has a higher ID. A subtask marked done
+does not change the parent Task status. Code completion, dates, or child
+statuses never authorize an automatic parent done transition.
+
+## Observable field-change audit extension
+
+The NESTED contract also requires bounded `field_changes` on the existing
+`task.created`/`task.updated` activity event types for normal and nested
+fields: each changed field has `before` and `after` observations. The owner
+creates audit identity/time and status facts; callers never send those fields
+in a Task packet. Large values may be represented by bounded digest/truncation
+evidence instead of full content. Do not claim arbitrary historical values
+can be recovered from such an event. A normalized no-change write still has
+its own durable receipt and must not be presented as a new status transition.
+This describes the extension contract, not completed cross-implementation
+proof until the corresponding owner candidates pass review/integration.
+
+## CAS, replay and uncertain receipts
+
+An update's `expected_revision` is compare-and-swap (CAS). On a definite
+`revision_conflict`, re-read; if the intended change remains valid without
+overwriting someone else's change, send a new revision/packet with a new
+intent ID. Existing user intent continues to apply.
+
+Receipt lookup precedes CAS. Same intent + identical packet returns the
+original committed snapshot even after later edits. Read context for current
+state. Different content under that intent is `idempotency_conflict`.
+
+A fresh intent is a distinct logical operation, not replay or content-based
+deduplication. A fresh create can create another Task with identical text.
+A fresh update rechecks CAS and recomputes omitted dates/IDs against current
+state; it can be rejected or change values. Do not assume identical content
+under different intents must yield no_change. Never use a fresh intent to
+force an unresolved same-intent write through.
+
+On response loss or `commit_unknown`, retain the same intent and packet
+bytes, stop writing and read `operation-status`. `committed` settles it;
+`unknown` never means not written. Only `reason: no_receipt` permits an
+identical resend under the same intent. Never change its packet or switch to
+a new intent to force an unknown write through. A checkpoint's unknown
+outcome is reported without appending a replacement checkpoint.