docs(task): add operator runbook and update tool inventory

Author: emmahyde

CLAUDE.md

@@ -39,7 +39,7 @@ uv run memory-access
 - **`normalizer.py`** — LLM decomposition/classification via Anthropic API (or Bedrock). Uses `DECOMPOSE_PROMPT` and `CLASSIFY_PROMPT`
 - **`embeddings.py`** — Embedding generation (OpenAI or Bedrock Titan), L2-normalized float32 vectors. `create_embedding_engine()` factory selects provider.
 - **`storage.py`** — `InsightStore` class: SQLite persistence, migration system, subject indexing, knowledge graph queries
-- **`server.py`** — `MemoryAccessApp` orchestrator + MCP tool definitions (9 tools: `store_insight`, `search_insights`, `list_insights`, `update_insight`, `forget`, `search_by_subject`, `related_insights`, `add_subject_relation`, `get_subject_relations`)
+- **`server.py`** — `MemoryAccessApp` orchestrator + MCP tool definitions (insights, subject graph, knowledge bases, and task-state orchestration tools)
 
 ### Database
 

README.md

@@ -126,7 +126,7 @@ To use AWS Bedrock instead of OpenAI/Anthropic APIs:
 }
 ```
 
-## MCP Tools (12 tools)
+## MCP Tools (21 tools)
 
 ### Storage
 
@@ -152,6 +152,18 @@ To use AWS Bedrock instead of OpenAI/Anthropic APIs:
 - **`search_knowledge_base`** — Search external documentation by semantic similarity. Optionally filter by KB name.
 - **`list_knowledge_bases`** — List all knowledge bases with descriptions and chunk counts.
 
+### Task orchestration
+
+- **`create_task`** — Create a task with DB-enforced lifecycle state.
+- **`assign_task_locks`** — Acquire active locks for resources (exact + path-prefix conflict detection).
+- **`release_task_locks`** — Release active locks for a task (optionally scoped to resources).
+- **`add_task_dependencies`** — Add dependency edges between tasks.
+- **`transition_task`** — Atomically transition state with optimistic concurrency (`expected_version`).
+- **`append_task_event`** — Append audit/worklog events (append-only at DB level).
+- **`get_task`** — Fetch a task by ID.
+- **`list_tasks`** — List tasks with optional status filter.
+- **`list_task_events`** — List append-only events for a task.
+
 ## Semantic Frames
 
 Insights are normalized into one of six canonical frames:

docs/task-state-runbook.md

@@ -0,0 +1,135 @@
+# Task State Machine Runbook
+
+Operational guide for the SQLite-backed task state machine used by `memory-access`.
+
+## Scope
+
+This runbook covers:
+- Task lifecycle transitions
+- Lock and dependency troubleshooting
+- Validation queries
+- Migration verification
+
+## Lifecycle
+
+Allowed states:
+- `todo`
+- `in_progress`
+- `blocked`
+- `done`
+- `failed`
+- `canceled`
+
+Allowed transitions are DB-enforced by trigger:
+- `todo -> in_progress|blocked|failed|canceled`
+- `in_progress -> done|blocked|failed|canceled`
+- `blocked -> in_progress|failed|canceled`
+- `done|failed|canceled` are terminal
+
+## Locking Rules
+
+Active locks are stored in `task_locks`.
+Conflicts are DB-enforced for both:
+- exact same resource
+- path-prefix overlap (for example, `src` conflicts with `src/a.py`)
+
+## Troubleshooting
+
+### `LockConflict`
+
+Meaning: lock acquisition violated exact or path-prefix overlap rules.
+
+Actions:
+1. List active locks for the resource prefix.
+2. Release stale locks for completed/canceled tasks.
+3. Retry lock assignment.
+
+### `DependencyNotMet`
+
+Meaning: attempted to transition to `in_progress` while at least one dependency is not `done`.
+
+Actions:
+1. Query dependency states.
+2. Complete or fail dependency tasks.
+3. Retry transition.
+
+### `InvalidTransition`
+
+Meaning: transition is not in allowed state graph.
+
+Actions:
+1. Fetch task state/version.
+2. Use a legal transition path.
+
+### `ConcurrencyConflict`
+
+Meaning: optimistic version check failed (`expected_version` stale).
+
+Actions:
+1. Re-read task row.
+2. Retry transition with latest `version`.
+
+## Validation SQL
+
+All examples assume SQLite shell connected to the target DB.
+
+### Show migration version
+
+```sql
+SELECT MAX(version) AS latest_version FROM schema_versions;
+```
+
+### Inspect tasks
+
+```sql
+SELECT task_id, status, owner, retry_count, version, updated_at
+FROM tasks
+ORDER BY updated_at DESC
+LIMIT 50;
+```
+
+### Inspect active locks
+
+```sql
+SELECT id, task_id, resource, active, created_at
+FROM task_locks
+WHERE active = 1
+ORDER BY resource;
+```
+
+### Inspect task dependencies + current dependency state
+
+```sql
+SELECT td.task_id,
+       td.depends_on_task_id,
+       t.status AS depends_on_status
+FROM task_dependencies td
+JOIN tasks t ON t.task_id = td.depends_on_task_id
+ORDER BY td.task_id, td.depends_on_task_id;
+```
+
+### Inspect recent task events
+
+```sql
+SELECT task_id, event_type, actor, payload, created_at
+FROM task_events
+ORDER BY created_at DESC
+LIMIT 100;
+```
+
+## Migration Verification Procedure
+
+1. Back up the DB file.
+2. Start the app once to trigger migrations.
+3. Validate:
+   - `schema_versions` latest includes the task migrations.
+   - Task tables/triggers exist.
+4. Run one smoke transition flow:
+   - create task
+   - `todo -> in_progress`
+   - `in_progress -> done`
+
+## Type Stub Decision
+
+`src/memory_access/orm_models.pyi` is intentionally kept.
+Reason: Peewee field accessors are dynamic; the stub improves static checking and editor hints for `TaskStore` and callers.