workbite 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workbite",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "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",
+  "launcherVersion": "0.1.13",
   "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.13-windows-x64.zip",
+      "bundleSha256": "61886b62c848d3342580b27eb6ca76acac4bd2c608b67684139434893602d7d1",
+      "sha256": "061fb2b08470c9f39afc5d109abb2521e4ba137455aaebd75a7b2b1b8ccc36f5",
+      "size": 97782408,
+      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.13/workbite-0.1.13-windows-x64.zip"
     }
-  }
+  },
+  "product": "WorkBite",
+  "repository": "Shinick-Han/WorkBite-releases",
+  "schema": "workbite.release.v1",
+  "tag": "v0.1.13",
+  "version": "0.1.13"
 }

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.

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

@@ -0,0 +1,204 @@
+# Task graph transfer (unreleased source)
+
+Use this workflow only for an explicitly requested cross-workspace Task
+transfer, and only when the installed native client advertises each exact
+command and flag. This reference describes additive source work; it is not
+a release or installation claim. An unavailable command, owner route or
+required proof stops that operation. Do not emulate it with per-Task writes,
+raw HTTP, file copies or legacy apply. Never start an owner or backend to
+make a transfer command work.
+
+## Bind and preview
+
+Read source and destination status separately. Record each absolute workspace
+path and independently verified UID; Task display IDs alone do not identify
+a workspace. The source and destination each need their already running,
+verified WorkBite owner. Bind the explicit pair on every command below.
+`SOURCE_ABS`, `SOURCE_UUID`, `TARGET_ABS`, `TARGET_UUID` and digest placeholders
+must be replaced with the verified values. Files contain private workspace
+data; choose a private local destination and do not publish them.
+
+```text
+workbite agent --workspace SOURCE_ABS --workspace-uid SOURCE_UUID export --output tasks-transfer.json
+workbite agent --workspace TARGET_ABS --workspace-uid TARGET_UUID import --input-file tasks-transfer.json --mode new --dry-run
+```
+
+Export options `--include-history` and `--redact` are used only when
+advertised and appropriate to the requested result. Check the actual export
+projection before claiming redacted content can reproduce an unredacted
+workspace. Current `--redact` replaces Task titles, Objective text/quarter,
+and Key Result text/target, clears Task detail/tags/notes/subtasks, and keeps
+IDs, graph links, statuses and numeric progress. It refuses
+`--include-history` together with `--redact`. The remaining graph and IDs may
+still identify the source. `--include-history` projects observable event
+IDs/types/Task IDs/timestamps and planning-status facts, excluding the private
+idempotency ledger and opaque event details. Default export does not promise
+full history. Output is validated and published privately/atomically; an existing output file is refused,
+not overwritten. Without `--output`, inspect the advertised stdout form.
+
+The UTF-8 envelope format is `workbite.task-transfer.v1`, containing
+`source_workspace_uid`, `tasks`, `objectives` (including Key Results), optional
+`source_history` and `source_digest`. The source digest binds the canonical
+payload with its own `source_digest` member excluded. Do not hand-edit an
+archive and assume its digest remains valid.
+The entire archive AND HTTP import body must fit the advertised transfer
+limit (at most 1 MiB); wrapper overhead counts. The archive admits at most
+1000 Tasks and at most 1000 Objectives, with validated Key Results.
+The whole graph is one atomic batch, with no silent chunking or partial
+imports. Ordinary Task packets remain limited to 32768 bytes.
+
+`--dry-run` is read-only: it records no intent and changes no Task, Objective
+or authority document. Inspect its mapping, conflicts and normalized plan,
+including `source_digest`, `plan_digest` and `expected_snapshot_digest`.
+The target snapshot digest covers every canonical authority document,
+excluding only transfer receipt rows (`method: TRANSFER`) from
+`activity.json`'s idempotency list to avoid hashing the receipt into itself.
+It retains activity events, planning facts, allocator state, other intents
+and authority timestamps; it is not a transport/time-based freshness token.
+Never invent these proofs. Re-preview after a target change.
+
+- `--mode new` requires an empty target Task collection. Preservation of
+  display IDs (`--preserve-ids`) is permitted only in that empty target;
+  local UUIDs and status/audit facts are still generated afresh. Retained
+  display-ID high-water can also refuse preservation in an empty roster.
+- `--mode merge` appends distinct Tasks with generated target IDs through the
+  reviewed mappings and reports conflicts; it never silently overwrites
+  existing records. Review Objective and Key Result mapping as well as
+  parent/dependency links. An unresolved mapping
+  or conflict must be resolved by a supported plan, not guessed by the agent.
+  The current source appends fresh Objectives and Key Results with its
+  generated ID map. It does not reconcile them with existing target
+  Objectives, support caller-supplied mappings, or deduplicate repeat
+  archives under a new intent. Do not claim those features are implemented.
+
+## Apply exactly the previewed plan
+
+Explicit user intent for the transfer authorizes its preview/apply sequence;
+there is no extra per-Task approval or five-Task cap. If preview exposes an
+ambiguity outside that intent, resolve it before applying. Keep the archive,
+mode and `--preserve-ids` choice identical between preview and apply.
+
+```text
+workbite agent --workspace TARGET_ABS --workspace-uid TARGET_UUID import --input-file tasks-transfer.json --mode new --intent-id wb.import.20261015.demo --plan-digest sha256:PLAN_HEX --expected-snapshot-digest sha256:TARGET_HEX --id-map imported-ids.json
+```
+
+Use the actual preview's 64-hex digests, not these placeholders. `--id-map`
+requests a private validated output artifact, not an input mapping or
+permission to overwrite an existing file. A failed local output publication
+does not prove the authority write failed; preserve the intent and inspect
+import status. Never re-import under a new intent just to regenerate a file.
+
+Apply binds one stable intent to the archive's `source_digest`, mode,
+`plan_digest` and expected target snapshot. Full Task/Objective/Key Result
+schema and the complete graph must be validated before effects, including
+late cycles and unresolved references. Two-pass ID remapping occurs only in
+a staged/private reducer snapshot. All authority changes, batch receipt and
+source provenance commit in one native owner transaction. A partial external
+per-Task commit is not an admitted implementation of this workflow.
+
+## Status, replay and rollback
+
+```text
+workbite agent --workspace TARGET_ABS --workspace-uid TARGET_UUID import-status --intent-id wb.import.20261015.demo
+```
+
+Import status is read-only and bound to that workspace and intent. A
+committed receipt, rather than similar-looking Tasks or process exit alone,
+settles the outcome. Preserve the returned import ID, ID map and resulting
+`receipt.after_snapshot_digest` for observation and a possible separately
+requested rollback. Receipt lookup precedes snapshot CAS: an identical replay returns the original
+receipt even after later edits. Changed content under the same intent is an
+idempotency conflict. A fresh intent is a new operation: importing the same
+archive under another intent can append another mapped graph. The ordinary
+same-intent idempotency guarantee is not arbitrary fresh-intent deduplication.
+Never change intent merely to retry a lost answer or regenerate an output file.
+
+On timeout, lost, unreadable or oversized bounded response, `commit_unknown`
+or an unknown import status, stop writes and retain the exact intent, archive
+and proof values. Recover by reading `import-status` with that original intent;
+a response bound can hide a successful commit. Unknown never means not
+committed. Do not resend automatically or choose a fresh intent.
+Only retry the identical operation if the advertised recovery contract
+explicitly permits it for the observed reason. Task `operation-status` is not
+a substitute for `import-status`.
+
+Rollback needs explicit user intent for undoing the exact owned import, its
+`import_id`, and the expected current snapshot digest from that receipt or
+an advertised read. Use a separate stable rollback intent:
+
+```text
+workbite agent --workspace TARGET_ABS --workspace-uid TARGET_UUID import-rollback --intent-id wb.rollback.20261015.demo --import-id IMPORT_ID --expected-snapshot-digest sha256:CURRENT_HEX
+```
+
+Rollback requires the unique retained import receipt bound to its original
+intent and workspace, complete source archive/digest and ID map evidence,
+and the retained pre-import graph/status snapshot. The current authority
+snapshot must exactly match that import receipt's `after_snapshot_digest`
+under snapshot CAS: even an unrelated authority edit prevents rollback.
+Missing or incomplete proofs refuse rollback. Do not manually delete imported
+records or restore raw files. Successful rollback preserves display-ID
+high-water and idempotency fences, and appends a durable
+rollback receipt. It does not erase evidence or rewind authority history.
+The native source status route also observes retained rollback receipts by
+rollback intent; verify `receipt.operation` is `tasks.import-rollback`:
+
+```text
+workbite agent --workspace TARGET_ABS --workspace-uid TARGET_UUID import-status --intent-id wb.rollback.20261015.demo
+```
+
+Use this only when the installed status contract supports rollback receipts.
+Otherwise report the uncertainty and keep the intent; do not invent a
+recovery command or retry the mutation.
+
+## Data fidelity and authority
+
+Transfer preserves admitted normal Task metadata, Task graph relationships,
+Objective/Key Result links and explicit source-to-target ID mappings. Target
+UUIDs, actor identities, status facts and audit records belong to the target
+owner and must not be blindly injected from source records. Source timestamps
+and provenance remain source-only evidence. Optional `source_history` is an
+archived source record, never a claim that those actions occurred locally.
+The current transfer source validates and preserves nonempty Task notes and
+subtasks using the same nested-array rules as ordinary Task writes (at most
+128 items per array). Supplied note dates remain user data. Supplied Subtask
+display IDs remain scoped to each newly generated target parent; omitted IDs
+are allocated within that parent. No source Task UUID or status fact is
+installed as target authority. This source behavior still requires reviewed
+integration and matching installed capability proof before use. Use official
+backup/restore when required fidelity is outside the transfer schema. Source
+evidence enters only through that closed schema.
+Do not import arbitrary Capture, worklog, attachment or runtime state unless
+a future advertised schema explicitly supports it.
+
+A Task transfer is not a full-fidelity workspace relocation or backup restore.
+For full workspace/history recovery, use the component's official backup /
+restore procedure appropriate to its storage format, under separate explicit
+operator authorization and its owner-stop/lease/identity requirements. This
+Skill does not run restore or copy SSOT files. Moving a folder, installing a
+new bundle or refreshing a Skill is not part of transfer.
+
+## MCP and native transport
+
+For MCP, use a transfer tool only if the running server's `tools/list`
+advertises it, with exactly its input schema and bound workspace UID. The
+source tool names are `workbite_export`, `workbite_import`,
+`workbite_import_status` and `workbite_import_rollback`. Import takes the
+archive object and `mode`, `dry_run`, optional `preserve_ids`; apply adds
+`intent_id`, `plan_digest`, `expected_snapshot_digest`. Keep those values
+identical to preview. Preview takes no intent/proofs. Tool names in source
+alone do not prove that the installed native client or
+running owner implements them. There is no raw HTTP or shell workaround.
+
+The npm launcher owns bounded input-file reads and private output files; the
+native client consumes the archive via its existing stdin envelope. Only the
+native owner implements the authority HTTP routes:
+
+| Route | Method and body/query |
+|---|---|
+| `/api/v1/agent/tasks/export` | GET: `workspace_uid`, `include_history`, `redact` |
+| `/api/v1/agent/tasks/import` | POST: `workspace_uid`, `archive`, `mode`, `dry_run`, `preserve_ids`, `plan_digest`, `expected_snapshot_digest`; preview proofs may be null |
+| `/api/v1/agent/tasks/import-status` | GET: `workspace_uid`, `intent_id` |
+| `/api/v1/agent/tasks/import-rollback` | POST: exactly `workspace_uid`, `import_id`, `expected_snapshot_digest`; the new rollback intent is only the idempotency header |
+
+`Idempotency-Key` is present only on import apply and rollback. These are
+implementation seams, not instructions to call HTTP from the Skill.