workbite 0.1.18 → 0.1.20

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

@@ -1,204 +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.
+# 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.