khabotcli 1.0.0

package/.OLD/STEP-5/audit-prompt.md

@@ -0,0 +1,114 @@
+# KhaBotCLI Plan Audit — Fresh Context Review
+
+## Your Role
+You are a senior software architect performing a **cold audit** of a technical specification. You have **zero prior context** — this is intentional. Your fresh perspective is the value.
+
+## Scope
+Read **ONLY** the files inside the `PLAN/` folder (14 files). Do NOT read any other files in the project (STEP-1/, STEP-2/, STEP-3/, STEP-4/, PLAN.md, FACTS.md, etc.). Those contain iterative drafts and will pollute your context.
+
+### Files to read (in this order):
+```
+PLAN/README.md
+PLAN/01-vision.md
+PLAN/02-tech-stack.md
+PLAN/03-agents.md
+PLAN/04-runtime.md
+PLAN/05-tools.md
+PLAN/06-communication.md
+PLAN/07-storage.md
+PLAN/08-api-cli.md
+PLAN/09-permissions.md
+PLAN/10-ably.md
+PLAN/11-file-formats.md
+PLAN/12-folder-structure.md
+PLAN/13-operations.md
+```
+
+## What to Look For
+
+After reading ALL 14 files, produce a structured report covering:
+
+### 1. Contradictions
+Find any place where two files say different things about the same concept. Examples:
+- A field name spelled differently across files
+- A default value stated as X in one file and Y in another
+- A behavior described differently (e.g., "blocks" in one file, "async" in another for the same tool)
+- Mode names inconsistent (e.g., "sub-agent" vs "subagent")
+- Logic
+- Flows
+
+### 2. Mismatches Between Files
+Find references that don't line up:
+- A tool mentioned in one file but missing from the tools list in another
+- A config field used in examples but not documented in the field tables, or the opposite
+- A folder/file path in the folder structure that doesn't match what's described in file formats
+- SQLite tables referenced in behavior docs but not defined in the storage schema
+- API endpoints referenced but not listed in the API spec
+
+### 3. Missing Pieces
+Identify anything that feels incomplete or undefined:
+- A feature described but never explained how it actually works
+- A config field with no documented default
+- An edge case mentioned but not resolved
+- A flow (like "agent spawns sub-agent") that's described at a high level but missing concrete steps
+- Any "TODO" or placeholder language left in
+
+### 4. Ambiguities
+Find areas where the spec is unclear enough that two developers could interpret it differently:
+- Vague language like "may", "could", "optionally" without clear defaults
+- Undocumented interaction between two features
+- Unclear precedence/priority rules
+
+### 5. Dead References
+Find anything that references something that doesn't exist in the spec:
+- Mentions of features not covered by any file
+- References to removed concepts (e.g., "commands/", old file locations)
+- Links or cross-references to nonexistent sections
+
+## Output Format
+
+Structure your report as:
+
+```markdown
+# KhaBotCLI Plan Audit Report
+
+## 🔴 Contradictions
+1. **[Short title]** — [File A] says X, but [File B] says Y.
+   - File A: `exact quote or reference`
+   - File B: `exact quote or reference`
+   - Recommendation: [which one is correct / how to resolve]
+
+## 🟡 Mismatches
+1. **[Short title]** — [description of mismatch]
+   - Where: [file(s)]
+   - Recommendation: [fix]
+
+## ⚪ Missing Pieces
+1. **[Short title]** — [what's missing]
+   - Where it should be: [file]
+   - Recommendation: [what to add]
+
+## 🔵 Ambiguities
+1. **[Short title]** — [what's unclear]
+   - Where: [file(s)]
+   - Recommendation: [how to clarify]
+
+## 💀 Dead References
+1. **[Short title]** — [what's referenced but doesn't exist]
+   - Where: [file]
+   - Recommendation: [remove or add the missing thing]
+
+## ✅ Summary
+- Total issues: X
+- Critical (contradictions): X
+- Medium (mismatches/missing): X
+- Low (ambiguities/dead refs): X
+```
+
+## Rules
+- Be thorough. Read every line of every file.
+- Be specific. Quote exact field names, file paths, section headers.
+- Do NOT suggest new features. Only report problems with what's already written, unless required.
+- Do NOT rewrite sections. Just flag the issue and recommend a fix direction.
+- If something looks intentional but unusual, flag it as an ambiguity rather than an error.
+- Group related issues together (e.g., if the same field is wrong in 3 files, that's one issue with 3 locations).

package/.OLD/STEP-6/AUDIT.md

@@ -0,0 +1,468 @@
+# KhaBotCLI Specification Audit Report
+
+**Scope:** PLAN/ folder (14 specification files)
+**Date:** Cold audit — zero prior context
+
+---
+
+## 1. CONTRADICTIONS
+
+### 1.1 Field Naming: CamelCase vs Snake_Case
+
+| File | Field | Casing |
+|------|-------|--------|
+| `03-agents.md` (agent.json example) | `maxDurationSeconds` | CamelCase |
+| `07-storage.md` (tasks table) | `max_duration_seconds` | snake_case |
+| `03-agents.md` (agent.json example) | `maxIterations` | CamelCase |
+| `07-storage.md` (tasks table) | `max_iterations` | snake_case |
+
+**Issue:** The JSON configuration uses camelCase (`maxDurationSeconds`) but the SQLite schema uses snake_case (`max_duration_seconds`). This inconsistency will cause mapping bugs when reading/writing task records.
+
+**Fix Direction:** Standardize on one convention. Recommend camelCase for JSON configs and snake_case for SQL columns (common pattern), but document the mapping explicitly in the storage layer.
+
+### 1.2 `allowedAgents`/`disallowedAgents` vs `allowed_agents`/`disallowed_agents`
+
+Similar issue in agent.json schema - if SQLite stores these, the casing must be consistent.
+
+### 1.3 `followup` Field Type
+
+| File | Field | Type |
+|------|-------|------|
+| `06-communication.md` | `followup` in `agent_send` | boolean (`true`/`false`) |
+| `07-storage.md` | `followup` in `agent_messages` table | INTEGER (0/1) |
+
+**Issue:** Boolean in API/JSON but INTEGER in SQLite schema. Acceptable if documented, but should be explicit.
+
+---
+
+## 2. MISMATCHES BETWEEN FILES
+
+### 2.1 Missing `priority` Field in tasks Table
+
+**Location:** `06-communication.md` Task Fields table (line 170-188)
+
+**Issue:** The Task Fields table lists `priority` as a field, but `07-storage.md` tasks table schema (lines 50-73) has `priority` column. This is actually CORRECT — both have it. No issue here.
+
+**Actual Issue:** The `tags` field (string[]) in Task Fields table — is it stored as TEXT JSON in SQLite? Need to verify column exists.
+
+### 2.2 `compaction_count` in sessions Table
+
+**Location:** `07-storage.md` line 34
+
+**Issue:** `compaction_count` column exists in sessions table, but:
+- No corresponding setting in `settings.json` to configure this
+- No documentation of what triggers incrementing this counter
+- No mention in file formats section about compaction analytics
+
+### 2.3 `agent_message` "Busy" Behavior Inconsistency
+
+| File | Description |
+|------|-------------|
+| `03-agents.md` (line 146) | "If Agent B is busy: Message queued... injected at next safe injection point" |
+| `06-communication.md` (lines 17-19) | "If Agent B is busy: Message queued... injected at next safe injection point (between tool calls)" |
+| `06-communication.md` (lines 224-226) | "injected at the next safe injection point (between tool calls). Once the target agent processes it and produces a response, that response is returned to the caller" |
+
+**Issue:** `03-agents.md` says B's response is "returned to Agent A as tool output" when B is idle, but for busy case it says "B's response returned" without clarifying that the caller blocks. The flow is confusing between sync (idle) vs sync (busy) cases.
+
+### 2.4 `task_respond` Mode Restriction
+
+**Location:** `05-tools.md` line 34
+
+**Issue:** "`task_respond` only available in task mode" — but the Task Lifecycle in `06-communication.md` shows `waiting` status can transition to `finished` or `failed`. The restriction is clear, but there's no API endpoint documented for `task_respond` in `08-api-cli.md`.
+
+Actually, `08-api-cli.md` line 48 shows `POST /tasks/:id/respond` — this is documented. No issue.
+
+### 2.5 Tool Names: `web_fetch` vs `WebFetch`
+
+| File | Reference |
+|------|-----------|
+| `05-tools.md` line 14 | Tool named `web_fetch` (snake_case) |
+| `09-permissions.md` line 16 | Permission example `WebFetch(https://api.*)` (CamelCase) |
+
+**Issue:** Permission system examples use CamelCase tool names but the actual tool names are snake_case. This is a critical mismatch — permissions won't match if the casing differs.
+
+**Fix Direction:** Standardize tool naming convention. All built-in tools use snake_case (`web_fetch`, `read_file`, `write_file`). Permission examples must match exactly.
+
+### 2.6 `onExhausted` Values
+
+**Location:** `11-file-formats.md` line 361
+
+**Issue:** "`onExhausted` valid values: `"fail"` (default) or `"wait"`" — but in `04-runtime.md` line 37, the compaction/limits section says "max_iterations reached? → fail" without mentioning the "wait" option.
+
+The "wait" option for `onExhausted` is documented in settings.json schema but the runtime behavior description doesn't mention how "wait" mode works for iteration/duration limits vs LLM retry exhaustion.
+
+### 2.7 `skillDiscovery` Default Value
+
+| File | Default |
+|------|---------|
+| `03-agents.md` line 97 | "Default: `true`" |
+| `11-file-formats.md` line 75 | "(default: true)" |
+
+These match. No issue.
+
+### 2.8 `memory.enabled` Default Value
+
+| File | Default |
+|------|---------|
+| `03-agents.md` line 98 | "Default: `true`" |
+| `03-agents.md` line 99 | "Default: 200 (from settings.json)" for maxLines |
+| `11-file-formats.md` line 73 | "(default: true)" |
+
+These match. No issue.
+
+### 2.9 `maxLines` Source
+
+| File | Description |
+|------|-------------|
+| `03-agents.md` line 99 | "Default: 200 (from settings.json). Per-agent override." |
+| `11-file-formats.md` line 74 | "(default: 200 from settings.json)" |
+
+These match. No issue.
+
+### 2.10 `heartbeatFile` Default Path
+
+| File | Path |
+|------|------|
+| `03-agents.md` line 102 | ".khabot/heartbeats/<agentName>.md" |
+| `03-agents.md` line 138 | "from `.khabot/heartbeats/<agentName>.md` or custom path" |
+| `11-file-formats.md` line 90 | "(default: `.khabot/heartbeats/<name>.md`)" |
+
+These match. No issue.
+
+### 2.11 `observationMaskingTurns` Setting
+
+**Location:** `04-runtime.md` line 86
+
+**Issue:** "Configurable via `settings.json` → `compaction.observationMaskingTurns` (default: 10)" — but in `11-file-formats.md` settings.json example (lines 324-328), it's `compaction.observationMaskingTurns`.
+
+Wait, `11-file-formats.md` shows:
+```json
+"compaction": {
+  "threshold": 0.85,
+  "enabled": true,
+  "observationMaskingTurns": 10
+}
+```
+
+This is correct. The field exists in the example. No issue.
+
+---
+
+## 3. MISSING PIECES
+
+### 3.1 `version.json` for Global Tools
+
+**Location:** `12-folder-structure.md` Global section (lines 47-69)
+
+**Issue:** The global tools folder structure shows:
+```
+tools/
+└── <toolName>/
+    ├── tool.json
+    ├── index.js
+    └── version.json        ← SHA256 hash for registry version checking
+```
+
+But `11-file-formats.md` (lines 376-393) only documents `version.json` for "global cached agents/tools" — the file format section shows the schema, but it's not clear if project-level tools also have this or only global cached ones.
+
+**Fix Direction:** Clarify that `version.json` only exists for globally cached agents/tools from KhaBot.com registry. Project-level tools don't need it (user owns them).
+
+### 3.2 `disable-model-invocation` Skill Field
+
+**Location:** `11-file-formats.md` line 197
+
+**Issue:** SKILL.md frontmatter includes `disable-model-invocation: false` field, but `05-tools.md` skills section (lines 142-203) never mentions this field or how it affects skill invocation.
+
+**Fix Direction:** Document this field in `05-tools.md` skills section, explaining when skills can be auto-invoked by agents vs. only user/API triggered.
+
+### 3.3 `instance_folder` in sessions Table
+
+**Location:** `07-storage.md` line 25
+
+**Issue:** `instance_folder` column is documented as "Project folder path (tracks which directory the session was started from, used to resolve project-level agents/settings)" — but there's no API endpoint to query/filter sessions by instance folder, and no documentation of how this interacts with the global SQLite database (`~/.khabot/data.db`) when multiple projects exist.
+
+**Ambiguity:** If all sessions go to one global DB, how does the runtime handle agents with the same name in different projects? The `instance_folder` suggests project scoping, but the spec doesn't clarify the isolation model.
+
+### 3.4 `task_subscriptions` Delivery Semantics
+
+**Location:** `06-communication.md` lines 123-146
+
+**Issue:** The durable subscription mechanism is described, but missing:
+- What happens if the subscriber session is closed and reopening fails?
+- Is there a delivery timeout (how long does runtime wait for session to become active)?
+- What if multiple subscriptions exist for the same task — does each get notified or only first?
+- No mention of subscription expiration/cleanup
+
+### 3.5 `agent_send` with `followup: true` in Task Mode
+
+**Location:** `06-communication.md` lines 25-49
+
+**Issue:** The `agent_send` tool works across all modes, but `followup: true` says "only inject after agent fully finishes current task." However:
+- Chat mode has no "task" concept — is followup still meaningful?
+- Daemon mode runs continuously — when is "current work" considered finished?
+
+**Fix Direction:** Clarify followup behavior per mode, or restrict it to specific modes.
+
+### 3.6 `returnMode` for `agent_spawn`
+
+**Location:** `05-tools.md` line 44
+
+**Issue:** `returnMode` options are "summary" / "raw" / "lastMessage" — but:
+- No documentation of what each mode actually returns
+- No examples of the output format for each mode
+- In `06-communication.md` line 76, only "summary" is shown in the example
+
+### 3.7 `triggers` in Daemon Mode
+
+**Location:** `03-agents.md` line 137
+
+**Issue:** "System-wide event triggers: task.completed, task.failed, agent.error" — but:
+- The full list of triggerable events is not documented
+- No schema for what payload the daemon receives when triggered
+- No example of how a daemon accesses the trigger event info (via heartbeat file? injected message?)
+
+### 3.8 MCP Tool Permissions
+
+**Location:** `05-tools.md` line 113
+
+**Issue:** "MCP tools subject to the same deny/ask/allow permission system" — but MCP tools are discovered dynamically. How are they referenced in permissions? By the full tool name? By MCP server name?
+
+**Fix Direction:** Document the naming convention for MCP tool permissions (e.g., `McpTool(serverName.toolName)` or similar).
+
+### 3.9 `alertRouting` Options
+
+**Location:** `03-agents.md` line 139
+
+**Issue:** `alertRouting` supports "log / webhook URL / another agent / Ably channel" — but:
+- The syntax for each option isn't documented (e.g., `agent:<name>` format shown in `11-file-formats.md` line 89)
+- No webhook payload schema documented
+- No retry logic for failed webhook deliveries
+
+### 3.10 `conflictPolicy` Behavior
+
+**Location:** `03-agents.md` line 78, `11-file-formats.md` line 88
+
+**Issue:** `conflictPolicy` options are "skip / queue / restart" — but the behavior of "queue" and "restart" is not documented:
+- "Queue": Is there a max queue size? FIFO or priority-based?
+- "Restart": Does it cancel the running tick or wait for it to finish?
+
+### 3.11 `task_events` Table `data` Field Schema
+
+**Location:** `07-storage.md` lines 75-83
+
+**Issue:** The `task_events` table has a `data` column (TEXT, JSON payload), but there's no schema documented for what goes in this JSON for each event type (iteration.start, tool.start, tool.end, status.change, custom).
+
+---
+
+## 4. AMBIGUITIES
+
+### 4.1 Permission Inheritance for `ask` Level
+
+**Location:** `09-permissions.md` lines 41-43
+
+**Ambiguity:** "Per-agent, per-mode permissions in agent.json support `allow` and `deny` only. The `ask` level is only available in settings.json because it requires interactive user approval"
+
+But what happens if:
+- settings.json has `ask: ["Bash(*)"]`
+- agent.json task mode has `allow: ["Bash(npm *)"]`
+- User runs in task mode (non-interactive)
+
+Does the agent.json `allow` override the settings.json `ask`? Or does `ask` at global level + non-interactive mode = deny? The resolution order says "last wins" but doesn't clarify level interaction.
+
+**Fix Direction:** Document that agent-level permissions completely replace (not merge with) the inherited permission set for that mode.
+
+### 4.2 `agent_spawn` Fallback Behavior
+
+**Location:** `03-agents.md` line 150
+
+**Ambiguity:** "If `modes.subagent` is not defined or not enabled, the runtime falls back to chat-like behavior using `modes.chat` config."
+
+Questions:
+- Does this fallback happen silently or is there a warning?
+- If `modes.chat` is also not enabled, what happens?
+- Does the spawned agent still get isolated context (subagent key property) or does it share context?
+
+### 4.3 `skillDiscovery: false` + `autoLoadSkills`
+
+**Location:** `03-agents.md` lines 97, 103
+
+**Ambiguity:** When `skillDiscovery: false`, "no skill names/descriptions listed in system prompt. Agent is skill-blind unless given via `autoLoadSkills`."
+
+But `autoLoadSkills` are skills "whose full content is always in the system prompt" — does this mean:
+- Agent can still USE the auto-loaded skills (they're in context)
+- But doesn't know about OTHER skills (not in autoLoadSkills)
+- Or agent doesn't know about ANY skills including auto-loaded ones?
+
+### 4.4 `tools` + `disallowedTools` Mutual Exclusivity
+
+**Location:** `03-agents.md` lines 93-95
+
+**Ambiguity:** "`tools` and `disallowedTools` are mutually exclusive — setting both is a validation error."
+
+But what about empty arrays?
+- `tools: []` + `disallowedTools: []` — is this an error or "all tools allowed"?
+- `tools: []` alone = all tools allowed
+- `disallowedTools: []` alone = all tools allowed
+- Both empty = ?
+
+### 4.5 Task "Waiting" Status Transitions
+
+**Location:** `06-communication.md` lines 163-168
+
+**Ambiguity:** The lifecycle shows `processing → [waiting] → finished`, but:
+- Can a waiting task go to `failed` or `canceled` directly?
+- Can a waiting task go back to `processing` without `task_respond` (e.g., timeout)?
+- Is there a max wait time for tasks in `waiting` status?
+
+### 4.6 `sleep` Tool Availability
+
+**Location:** `05-tools.md` line 29
+
+**Ambiguity:** The `sleep` tool is listed as a built-in tool, but:
+- No parameters documented
+- Is it available in all modes including daemon?
+- Does it count against `maxIterations` or `maxDurationSeconds`?
+
+### 4.7 `log_write` vs Progress Events
+
+**Location:** `05-tools.md` line 30, `04-runtime.md` lines 132-150
+
+**Ambiguity:** `log_write` tool writes "entry to task log / push progress event" — but `04-runtime.md` distinguishes between:
+- Automatic events (type: "iteration")
+- Agent-driven events (type: "custom", via `log_write`)
+
+Is `log_write` the ONLY way to emit custom events? Can agents emit "iteration" type events?
+
+### 4.8 `KHABOT_AGENT_FOLDER` Environment Variable
+
+**Location:** `03-agents.md` line 118, `09-permissions.md` line 87
+
+**Ambiguity:** The variable is available in:
+- Custom tool execution
+- Hooks
+- Template variable `$AGENT_FOLDER` in AGENT.md, SKILL.md, heartbeat files
+
+But is it available in:
+- Skill scripts referenced in SKILL.md?
+- MCP tool execution context?
+
+### 4.9 `maxConcurrentTasks` and `agent_spawn(wait: false)`
+
+**Location:** `06-communication.md` line 121
+
+**Ambiguity:** "`wait: false` spawns count against `maxConcurrentTasks` limit" — but:
+- Does `task_create` also count against this limit?
+- Does the parent task itself count as 1, meaning max 4 sub-agents can be spawned concurrently if limit is 5?
+- What happens when limit is hit — error, queue, or block?
+
+### 4.10 Observation Masking vs Tool Result Clearing
+
+**Location:** `04-runtime.md` lines 84-88
+
+**Ambiguity:** Two separate mechanisms:
+1. Observation masking — replaces old tool outputs with `[output hidden]`
+2. Tool result clearing — truncates raw outputs to ~500 chars
+
+The description says these are "independent, sequential steps" — but it's unclear:
+- Does clearing happen BEFORE or AFTER masking?
+- If masking replaces with placeholder, what is there to truncate?
+
+**Fix Direction:** Clarify the order: Observation masking (turns 11+) → Tool result clearing (turns older than masking threshold, if different threshold) → Compaction.
+
+---
+
+## 5. DEAD REFERENCES
+
+### 5.1 `commands/` Folder
+
+**Location:** `01-vision.md` line 13
+
+**Dead Reference:** "Not a UI application — REST API only, UIs built separately" mentions avoiding "commands/" pattern, but this folder doesn't exist anywhere in the folder structure.
+
+This is actually a non-goal statement, not a dead reference. No issue.
+
+### 5.2 `disable-model-invocation` Implementation
+
+**Location:** `11-file-formats.md` line 197
+
+**Dead Reference:** The field exists in SKILL.md schema but no implementation logic is described in `05-tools.md` skills section.
+
+### 5.3 `PreToolUse`/`PostToolUse` in Tool Loop
+
+**Location:** `04-runtime.md` lines 16-25
+
+**Check:** The agentic loop diagram shows:
+1. Run PreToolUse hook
+2. Validate args
+3. Execute tool
+4. Run PostToolUse hook
+
+This matches `09-permissions.md` hooks documentation. No dead reference.
+
+### 5.4 `tool_search` Implementation
+
+**Location:** `05-tools.md` lines 28, 137-140
+
+**Check:** `tool_search` is listed as a built-in tool and described in Tool Discovery section. This is documented.
+
+### 5.5 `task_subscribe` in Task Fields Table
+
+**Location:** `06-communication.md` lines 170-188
+
+**Check:** Task Fields table doesn't list `subscriberCount` or similar — but that's fine, it's not needed in the task table.
+
+### 5.6 `memory_search` Scope
+
+**Location:** `05-tools.md` line 18
+
+**Dead Reference:** `memory_search` description says "Search across all memory files (project-wide + agent-specific)" — but does it include global (`~/.khabot/memory/`)? The folder structure shows memory at both project and global levels.
+
+**Fix Direction:** Clarify that `memory_search` searches project-level memory only, or extend it to global memory with a scope parameter.
+
+### 5.7 `khabot import` References
+
+**Location:** `13-operations.md` lines 72-99
+
+**Check:** Claude Code compatibility and import adapters are documented. This is complete.
+
+### 5.8 `ably.enabled: true` Startup Behavior
+
+**Location:** `10-ably.md` lines 59-65
+
+**Check:** Authentication flow is documented. No dead reference.
+
+---
+
+## SUMMARY: CRITICAL ISSUES (Must Fix Before Implementation)
+
+### Priority 1 (Will Cause Bugs)
+1. **Tool name casing in permissions:** `WebFetch` vs `web_fetch` — permissions won't match
+2. **Field naming inconsistency:** camelCase in JSON vs snake_case in SQLite needs explicit mapping
+3. **MCP tool permission naming:** Undocumented how to reference MCP tools in permissions
+
+### Priority 2 (Will Cause Confusion)
+4. **`agent_spawn` fallback behavior:** Unclear what happens when both subagent and chat modes disabled
+5. **`returnMode` options:** No documentation of what "summary" / "raw" / "lastMessage" actually return
+6. **`disable-model-invocation` skill field:** Exists in schema but no behavior documented
+7. **`followup` behavior per mode:** Unclear in daemon and chat modes
+
+### Priority 3 (Should Document)
+8. **`task_subscriptions` edge cases:** Delivery failures, multiple subscribers cleanup
+9. **`conflictPolicy` "queue" and "restart" behavior:** Undocumented implementation details
+10. **`triggers` payload schema:** Daemons need to know what event triggered them
+11. **`task_events.data` schema:** Need event-specific JSON schemas
+
+---
+
+## RECOMMENDED FIX PRIORITY
+
+1. Standardize permission tool name casing (Priority 1)
+2. Document SQLite ↔ JSON field mapping convention (Priority 1)
+3. Define MCP tool permission naming (Priority 1)
+4. Document `returnMode` output formats (Priority 2)
+5. Clarify `agent_spawn` fallback chain (Priority 2)
+6. Document `disable-model-invocation` behavior (Priority 2)
+7. Add `followup` mode-specific behavior (Priority 2)
+8. Document daemon trigger payload schema (Priority 3)
+9. Define event-specific schemas for `task_events.data` (Priority 3)
+10. Document `conflictPolicy` implementation (Priority 3)