feat(import): expose ticket store migration surfaces

README.md

@@ -7,7 +7,9 @@ Agent ticket system for coding agents. `ticket-flow` owns ticket lifecycle state
 
 The source-of-truth boundary is the `ticket-flow` CLI, MCP server, and TypeScript
 store API. All ticket creation, mutation, status changes, logs, links, and
-checkpoints should go through those surfaces.
+checkpoints should go through those surfaces. Migration/import is also a
+ticket-flow mutation and should use `ticket-flow import`, `ticket_import`, or
+`importTicketStore`.
 
 The filesystem is the current storage implementation, not the public SSOT
 contract:
@@ -20,7 +22,8 @@ contract:
 
 Existing external ticket data should be migrated into the `ticket-flow` store
 before use. Do not share another product's ticket directory in place as the live
-ticket state.
+ticket state. Import copies parsed ticket records into the configured
+`ticket-flow` store and leaves the source directory as a source artifact only.
 
 ## Usage
 
@@ -29,13 +32,14 @@ bun install
 bun run cli create --title "Fix compaction session recovery" --source discord:123
 bun run cli list
 bun run cli show T-20260707-001
+bun run cli import /path/to/legacy-ticket-store
 bun run cli checkpoint T-20260707-001 --phase qa --next-type agent_action --next-command "finish verification"
 bun run mcp
 ```
 
 The MCP server exposes the same ticket mutations as tools, including
-`ticket_create`, `ticket_update_status`, `ticket_checkpoint`, and
-`ticket_agent_actions`.
+`ticket_create`, `ticket_import`, `ticket_update_status`, `ticket_checkpoint`,
+and `ticket_agent_actions`.
 
 ## macmini Setup
 

biome.jsonc

@@ -1,5 +1,13 @@
 {
   "$schema": "https://biomejs.dev/schemas/2.5.1/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": ["**", "!.omo", "!rust-ticket-flow/target"]
+  },
   "assist": {
     "actions": {
       "source": {

docs/CLAWHIP-INTEGRATION.md

@@ -2,14 +2,17 @@
 
 `ticket-flow` can emit compact `ticket.*` events to a running
 [`clawhip`](https://github.com/Yeachan-Heo/clawhip) daemon. The integration keeps
-the local ticket JSON store as the source of truth and uses `clawhip` only as
-the event routing layer.
+the `ticket-flow` CLI/MCP/store API boundary as the source of truth and uses
+`clawhip` only as the event routing layer. The local filesystem is the current
+storage implementation behind ticket-flow, not a shared state contract for
+clawhip or other tools.
 
 ## Responsibilities
 
 `ticket-flow` owns:
 
-- ticket creation, status changes, checkpoints, and the active/archive JSON store
+- ticket creation, import/migration, status changes, checkpoints, and the
+  active/archive storage implementation
 - projection from a ticket record into a compact event payload
 - best-effort delivery to the configured `clawhip` daemon
 
@@ -22,6 +25,8 @@ the event routing layer.
 
 The integration intentionally does not persist `clawhip` delivery state in ticket
 JSON, and it does not send raw logs, artifacts, goals, or acceptance criteria.
+`clawhip` must consume `ticket.*` events; it must not create, import, or mutate
+ticket state directly.
 
 ## Event Sources
 

docs/VERIFICATION.md

@@ -26,6 +26,7 @@ Commands exercised:
 
 ```bash
 TICKET_FLOW_HOME=/tmp/ticket-flow-qa bun run src/cli.ts create --title 'QA ticket' --type feature --priority high --goal 'prove CLI surface' --acceptance 'ticket json exists' --tag qa,mcp --source discord:999
+TICKET_FLOW_HOME=/tmp/ticket-flow-import-dest bun run src/cli.ts import /tmp/ticket-flow-import-source
 TICKET_FLOW_HOME=/tmp/ticket-flow-qa bun run src/cli.ts status T-20260701-001 doing --note 'start QA'
 TICKET_FLOW_HOME=/tmp/ticket-flow-qa bun run src/cli.ts link T-20260701-001 --thread 123456
 TICKET_FLOW_HOME=/tmp/ticket-flow-qa bun run src/cli.ts log T-20260701-001 'manual QA note'
@@ -36,6 +37,7 @@ TICKET_FLOW_HOME=/tmp/ticket-flow-qa bun run src/cli.ts agent-actions
 Observed output included:
 
 ```text
+imported 3 ticket(s): active=1 archived=2
 T-20260701-001: open -> doing
 T-20260701-001: linked threads -> 123456
 T-20260701-001: logged
@@ -53,14 +55,17 @@ printf '%s\n' \
   '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
   '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
   '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ticket_create","arguments":{"title":"MCP QA ticket","priority":"low","type":"chore","source":"qa:mcp"}}}' \
+  '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"ticket_import","arguments":{"sourceRoot":"/tmp/ticket-flow-import-source"}}}' \
   | TICKET_FLOW_HOME=/tmp/ticket-flow-mcp-qa bun run src/mcp.ts
 ```
 
 Observed:
 
 - `initialize` returned protocol version `2025-06-18`.
-- `tools/list` returned all eight ticket tools.
+- `tools/list` returned `ticket_import` with the other ticket tools.
 - `ticket_create` returned `T-20260701-001` with existing JSON contract fields.
+- `ticket_import` returned an import summary and wrote parsed source tickets into
+  the configured destination store.
 - `ticket_agent_actions` returned an empty JSON array on an empty active-action store.
 - stdout contained JSON-RPC messages only.
 

rust-ticket-flow/.gitignore

@@ -0,0 +1 @@
+target/