workbite 0.1.12 → 0.1.14

package/lib/transfer.js

@@ -0,0 +1,113 @@
+'use strict';
+// Files only: the native client/owner owns all transfer HTTP, graph validation and commits.
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { constants } = require('node:fs');
+const { randomBytes } = require('node:crypto');
+const { fail, UUID } = require('./common');
+
+const MAX_TRANSFER_BYTES = 1024 * 1024;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+function localPath(filename) {
+  if (typeof filename !== 'string' || !filename || /[\x00-\x1f]/.test(filename)
+      || /^[a-z][a-z0-9+.-]*:\/\//i.test(filename) || /^(?:\\\\|\/\/)/.test(filename)) fail('Transfer files must be local filesystem paths');
+  return path.resolve(filename);
+}
+// Fail closed on links in the requested path. Do not create missing output directories.
+async function realDirectory(directory, io = fs) {
+  const parent = path.dirname(directory);
+  if (parent !== directory) await realDirectory(parent, io);
+  const info = await io.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) fail('Transfer path contains a link or non-directory');
+}
+async function outputPath(filename, io = fs) {
+  const target = localPath(filename);
+  await realDirectory(path.dirname(target), io);
+  try { await io.lstat(target); } catch (error) { if (error.code === 'ENOENT') return target; throw error; }
+  fail('Transfer output already exists; choose a new file (overwrite is not supported)');
+}
+function archive(value, workspaceUid) {
+  if (!plain(value) || value.format !== 'workbite.task-transfer.v1'
+      || typeof value.source_workspace_uid !== 'string' || !UUID.test(value.source_workspace_uid)
+      || typeof value.source_digest !== 'string' || !DIGEST.test(value.source_digest)
+      || !Array.isArray(value.tasks) || !value.tasks.every(plain)
+      || !Array.isArray(value.objectives) || !value.objectives.every(plain)) fail('Invalid workbite.task-transfer.v1 archive');
+  if (workspaceUid !== undefined && value.source_workspace_uid !== workspaceUid) fail('Export archive does not match the bound source workspace');
+  if (Buffer.byteLength(JSON.stringify(value)) > MAX_TRANSFER_BYTES) fail(`Transfer archive exceeds ${MAX_TRANSFER_BYTES} bytes`);
+  return value;
+}
+async function readArchive(filename, io = fs) {
+  const target = localPath(filename);
+  await realDirectory(path.dirname(target), io);
+  const before = await io.lstat(target);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_TRANSFER_BYTES) fail('Transfer input must be a regular file of at most 1048576 bytes');
+  const handle = await io.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > MAX_TRANSFER_BYTES || info.ino !== before.ino || info.dev !== before.dev) fail('Transfer input changed while opening');
+    // Read at most the bound plus one byte, even if another process grows the file.
+    const bytes = Buffer.alloc(MAX_TRANSFER_BYTES + 1);
+    let size = 0;
+    while (size < bytes.length) {
+      const read = await handle.read(bytes, size, bytes.length - size, null);
+      if (!read.bytesRead) break;
+      size += read.bytesRead;
+    }
+    if (size > MAX_TRANSFER_BYTES) fail(`Transfer archive exceeds ${MAX_TRANSFER_BYTES} bytes`);
+    let text, value;
+    try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, size)); value = JSON.parse(text); }
+    catch { fail('Transfer input must contain valid UTF-8 JSON'); }
+    archive(value);
+    return text;
+  } finally { await handle.close(); }
+}
+// Publish with an atomic hard link: rename would overwrite an existing destination on POSIX.
+// The private temporary file is in the same directory; an unsupported link is a safe refusal.
+async function writePrivate(filename, value, io = fs) {
+  const target = await outputPath(filename, io);
+  const bytes = Buffer.from(JSON.stringify(value));
+  if (bytes.length > MAX_TRANSFER_BYTES) fail(`Transfer output exceeds ${MAX_TRANSFER_BYTES} bytes`);
+  const temporary = path.join(path.dirname(target), `.workbite-transfer-${randomBytes(16).toString('hex')}.tmp`);
+  let handle;
+  try {
+    handle = await io.open(temporary, 'wx', 0o600);
+    await handle.writeFile(bytes);
+    await handle.sync();
+    await handle.close(); handle = null;
+    // Recheck the directory before publishing; link refuses even a raced-in destination.
+    await realDirectory(path.dirname(target), io);
+    await io.link(temporary, target);
+  } finally {
+    if (handle) await handle.close();
+    await io.unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  }
+  return target;
+}
+function resultData(result, command, uid, intent) {
+  if (typeof result.stdout !== 'string' || Buffer.byteLength(result.stdout) > MAX_TRANSFER_BYTES + 8192) fail('Invalid native transfer output');
+  let envelope;
+  try { envelope = JSON.parse(result.stdout); } catch { fail('Invalid native transfer envelope'); }
+  if (!plain(envelope) || envelope.contract !== 'workstack.cli.v1' || !plain(envelope.data)
+      || envelope.error !== undefined || envelope.meta?.command !== `agent.${command}` || envelope.meta?.workspace_uid !== uid
+      || (intent !== undefined && envelope.meta?.intent_id !== intent)) fail('Native transfer output does not match this workspace, command and intent');
+  return envelope.data;
+}
+function idMap(value) {
+  // The owner emits maps by source authority ID; values are generated target display IDs.
+  if (!plain(value) || Object.keys(value).some(key => !['tasks', 'task_uids', 'objectives', 'key_results'].includes(key))) fail('Invalid native transfer id_map');
+  for (const [kind, mapping] of Object.entries(value)) {
+    if (!plain(mapping)) fail('Invalid native transfer id_map');
+    for (const [source, target] of Object.entries(mapping)) {
+      if (!source || /[\x00-\x1f]/.test(source)) fail(`Invalid native transfer ${kind} mapping`);
+      if (kind === 'key_results') {
+        if (!plain(target) || Object.entries(target).some(([key, id]) => !key || /[\x00-\x1f]/.test(key)
+            || typeof id !== 'string' || !id || /[\x00-\x1f]/.test(id))) fail('Invalid native transfer key_results mapping');
+      } else if (typeof target !== 'string' || !target || /[\x00-\x1f]/.test(target)
+          || (kind === 'task_uids' && !UUID.test(target))) fail(`Invalid native transfer ${kind} mapping`);
+    }
+  }
+  if (!plain(value.tasks)) fail('Native transfer id_map requires tasks');
+  return value;
+}
+module.exports = { MAX_TRANSFER_BYTES, DIGEST, readArchive, archive, outputPath, writePrivate, resultData, idMap };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workbite",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "WorkBite (Work Stack + StackBite) verified native suite installer and launcher",
   "license": "UNLICENSED",
   "engines": {

package/release.json

@@ -1,24 +1,17 @@
 {
   "schema": "workbite.release.v1",
   "product": "WorkBite",
-  "version": "0.1.12",
-  "launcherVersion": "0.1.12",
   "repository": "Shinick-Han/WorkBite-releases",
-  "tag": "v0.1.12",
+  "tag": "v0.1.14",
+  "version": "0.1.14",
+  "launcherVersion": "0.1.14",
   "platforms": {
     "windows-x64": {
-      "asset": "workbite-0.1.12-windows-x64.zip",
-      "sha256": "ac0d1670e2d297d2e15536a2367305707da64160aee69c08c226db6700c1659f",
-      "size": 97572683,
-      "bundleSha256": "75ae1ce02f0a7721020d8b589be293b870515dd77374c7bdd40aa8f9a14385ad",
-      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.12/workbite-0.1.12-windows-x64.zip"
-    },
-    "linux-x64": {
-      "asset": "workbite-0.1.12-linux-x64.tar.gz",
-      "sha256": "36630e7c11096df8dc5ef720ecfdada286037c696fe61d787903c8922c23c5ce",
-      "size": 81937308,
-      "bundleSha256": "d83eeea345571a02ef1f54c0b2eef1a50b7c711d176d52beaff13470dbfe31f8",
-      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.12/workbite-0.1.12-linux-x64.tar.gz"
+      "asset": "workbite-0.1.14-windows-x64.zip",
+      "sha256": "3cac949c2b9d5135dfa195425581b7f731d1e28eb6712069781f0f82f6adcdfd",
+      "bundleSha256": "459ae8b6667a13613824729e8b35c1df13c8d9fa77f757fbbcdc312f2c224742",
+      "size": 136146372,
+      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.14/workbite-0.1.14-windows-x64.zip"
     }
   }
 }

package/skills/workbite-native/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workbite-native
-description: Read and record WorkBite Tasks through the installed `workbite agent` CLI or `workbite mcp` tools - check the bound workspace, list Tasks, read a Task's context, and, when the user asks for it (including a standing request made mid-work), create Tasks, update a Task's detail/status and append observable checkpoints with stable intent IDs. Use for WorkBite / Work Stack task and context requests in a WorkBite install; never route them to a separately installed `workstack`.
+description: Read and record WorkBite Tasks through the installed `workbite agent` CLI or `workbite mcp` tools - check the bound workspace, list Tasks, read a Task's context, and, when the user asks for it (including a standing request made mid-work), create Tasks, update advertised Task fields and append observable checkpoints with stable intent IDs. Use advertised export/import for explicitly requested Task graph transfers. Use for WorkBite / Work Stack task and context requests in a WorkBite install; never route them to a separately installed `workstack`.
 ---
 
 # WorkBite native Tasks
@@ -14,6 +14,11 @@ install, the Store files, or raw HTTP instead.
 
 Exact argv, packets, envelopes and refusals: [references/commands.md](references/commands.md).
 Read it before the first write in a session, and for MCP tool use.
+For field types, nested-array replacement and create/update examples, read
+[references/task-fields.md](references/task-fields.md). For an explicitly
+requested cross-workspace Task transfer, read
+[references/transfer.md](references/transfer.md). Transfer is capability-gated
+unreleased source; this Skill does not upgrade an installed bundle.
 
 ## Bind: one workspace, path + UUID
 
@@ -46,8 +51,17 @@ the default binding.
   intent exists, perform the writes it covers without asking again per write.
   It does not extend to other Tasks, other workspaces or other kinds of
   change.
+- Probe `workbite agent capabilities` before writes. The installed command's
+  `packet_schema` is authoritative for every field and type, including
+  `changes.properties` for update. A command name alone does not prove field
+  support. If the schema is absent, use only that command's documented
+  original fields; report unavailable additions. Never use legacy `apply`,
+  another install or direct Store access to bypass an unavailable field.
 - Create as many Tasks as the user's intent calls for, each with its own
-  intent ID. `follows_task_id` is optional provenance only.
+  intent ID. There is no five-Task reapproval cap; a transport size limit is
+  not a limit on the number of user-requested Tasks. `follows_task_id` is
+  optional provenance only. Existing targets must be named by the user or
+  unambiguously covered by the standing request; do not pick unrelated Tasks.
 - Never mark a Task `done` or `dropped` on your own judgement; set status only
   when the user asked for that status or the requested outcome is that status.
 
@@ -67,7 +81,8 @@ the default binding.
 
 - One logical write = one stable intent ID (`[A-Za-z0-9._:-]{8,128}`), chosen
   before sending and kept with its packet, e.g. `wb.create.20261013.login-bug`.
-  A replay of the same ID + identical packet returns the original result; a
+  Receipt lookup precedes revision CAS: a replay of the same ID + identical
+  packet returns the original result even after later edits; a
   different packet under a used ID is `idempotency_conflict`.
 - `revision_conflict`: re-read context; re-issue against the current revision
   with a new intent ID only if the change still fits what the user asked and

package/skills/workbite-native/references/commands.md

@@ -21,8 +21,8 @@ workbite agent [--workspace ABS --workspace-uid UUID] <command> ...
 - `--workspace` (absolute path) and `--workspace-uid` (the workspace's UUID)
   are given together or not at all.
 - Without them, a read binds the workspace saved by the last successful
-  `workbite open`. Writes (`tasks create`, `tasks update`, `checkpoint`)
-  refuse without the explicit pair. Use the default only for discovery
+  `workbite open`. Writes (`tasks create`, `tasks update`, `checkpoint`,
+  import apply/rollback) refuse without the explicit pair. Use the default only for discovery
   (`capabilities`, the first `status`, `tasks list`); once `status` has
   named the workspace, pass the pair on `context` and `operation-status` too.
 - The binding is checked before every call: the workspace descriptor must
@@ -59,12 +59,21 @@ workbite agent [--workspace ABS --workspace-uid UUID] <command> ...
   entries. `--view` is `core-v1` (default), `planning-v1`, `planning-v2` or
   `resume-v1`, when the native client lists it.
 
+## Advertised fields and transfer commands
+
+Probe `workbite agent capabilities` before using new fields or transfer
+commands. Task fields require the exact command's `packet_schema`; MCP
+`tools/list` must agree. See [task-fields.md](task-fields.md) for field types
+and full packets, and [transfer.md](transfer.md) for unreleased,
+capability-gated export/import preview/apply/status/rollback. A refusal never
+authorizes legacy apply, raw HTTP or another install.
+
 ## Packets
 
 Exactly one JSON object from `--input-file FILE` or `--stdin` (one is
 required; they are exclusive), valid UTF-8 of at most 32768 bytes, with only
-the keys listed below. Write it without a BOM. A packet never names a
-workspace. The launcher checks size and UTF-8 and hands the text to the native
+the keys admitted by the advertised `packet_schema`. Write it without a BOM.
+A packet never names a workspace. The launcher checks size and UTF-8 and hands the text to the native
 client as stdin; the packet never travels in argv.
 
 `tasks create`:
@@ -73,9 +82,10 @@ client as stdin; the packet never travels in argv.
 {"title": "Fix login redirect loop", "detail": "Seen on /settings after token refresh.", "follows_task_id": "T-0004"}
 ```
 
-`title` is required and non-empty; `detail` and `follows_task_id` are
-optional. `follows_task_id` is provenance in the receipt only (no parent or
-dependency). One intent ID creates at most one Task.
+`title` is required and nonblank; `detail` and `follows_task_id` are
+original optional fields. Additional fields require `packet_schema`; see
+[task-fields.md](task-fields.md). `follows_task_id` is receipt provenance only
+(no parent or dependency). One intent ID creates at most one Task.
 
 `tasks update`:
 
@@ -84,8 +94,9 @@ dependency). One intent ID creates at most one Task.
 ```
 
 `expected_revision` is the integer from a fresh `context`. `changes` is a
-non-empty subset of `detail` (string) and `status` (`open`, `started`, `done`,
-`dropped`). Title, priority, due date and relations are not writable.
+non-empty object matching the advertised schema. The original subset is
+`detail`/`status`; additions require explicit field/type advertisement.
+See [task-fields.md](task-fields.md).
 
 `checkpoint`:
 
@@ -113,7 +124,8 @@ apart later, for example `wb.create.20261013.login-bug`,
   and `meta.replayed`. `tasks create` / `tasks update` add `data.receipt`
   (`operation`, `result` `created` / `applied` / `no_change`, `task_id`,
   `before_revision`, `after_revision`, `committed_at`) and `data.task`. A
-  replay returns the original snapshot: read `context` for current state.
+  receipt lookup precedes revision CAS. A replay returns the original snapshot
+  even after later edits: read `context` for current state.
   If `data.omitted` names `task` or `receipt`, they were dropped for size;
   `commit_state` still settles the write.
 - A write whose answer was lost or timed out exits 1 with a stderr message
@@ -181,8 +193,8 @@ or mistyped arguments are refused before anything runs.
 | `workbite_status` | no | `workspace_uid` |
 | `workbite_tasks_list` | no | `workspace_uid`, `status`, `limit`, `offset` |
 | `workbite_context` | no | `workspace_uid`, **`task_id`**, `view`, `fingerprint`, `if_fingerprint` |
-| `workbite_tasks_create` | yes | **`workspace_uid`**, **`intent_id`**, **`title`**, `detail`, `follows_task_id` |
-| `workbite_tasks_update` | yes | **`workspace_uid`**, **`intent_id`**, **`task_id`**, **`expected_revision`**, **`changes`** (`{detail?, status?}`) |
+| `workbite_tasks_create` | yes | **`workspace_uid`**, **`intent_id`**, **`title`**, `detail`, `follows_task_id`, other advertised create fields |
+| `workbite_tasks_update` | yes | **`workspace_uid`**, **`intent_id`**, **`task_id`**, **`expected_revision`**, **`changes`** (advertised update fields) |
 | `workbite_checkpoint` | yes | **`workspace_uid`**, **`intent_id`**, **`task_id`**, **`date`**, **`done`**, **`next`**, **`blockers`** |
 | `workbite_operation_status` | no | `workspace_uid`, **`intent_id`** |
 
@@ -196,4 +208,6 @@ or mistyped arguments are refused before anything runs.
   `commit_unknown` (with `meta.commit_state: "unknown"` and the `intent_id`
   for `workbite_operation_status`). Calls run one at a time and are never
   retried.
+- Transfer tool names and exact preview/apply/status/rollback argument rules:
+  [transfer.md](transfer.md). They require actual native capability support.
 - No tool runs shells, raw RPC, deletes or policy changes.

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

@@ -0,0 +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.