Add inbox test planning guidance

docs/implementation-roadmap.md

@@ -20,6 +20,7 @@ As of now:
 - `inbox` is implemented end-to-end, including send/fetch/claim/renew/update/reply/done/fail/cancel/list/show/watch/wait-reply
 - `inbox` supports blocking waits, lease renewal, unread fetches backed by per-agent read cursors, `--body-file`, artifact attachments, and structured JSON errors with stable exit codes
 - integration tests cover the main inbox lifecycle, wait/watch flows, artifact persistence, and JSON error contracts
+- a human-readable inbox command test-plan set has not been authored yet
 - `orch` currently exists as a command skeleton only
 - no scheduler workflows have been implemented yet
 
@@ -269,12 +270,13 @@ Definition of done:
 
 If a new agent is taking over now, the next concrete step should be:
 
-1. implement `inbox send`
-2. implement `inbox fetch`
-3. implement `inbox claim`
-4. add a small integration test covering `init -> send -> fetch -> claim`
+1. create the inbox test documentation tree under `docs/tests/inbox/`
+2. write the shared testing conventions in `docs/tests/inbox/README.md`
+3. add `_shared/README.md` for common fixtures and assertion rules
+4. add command-level `README.md` files for the implemented inbox commands
+5. add `workflows/README.md` for cross-command cases such as unread, wait, and reply flows
 
-This is the smallest meaningful slice because the project already has a compiling skeleton and working schema initialization.
+This is the smallest meaningful documentation slice because the inbox implementation is already present and stable enough to document in detail before `orch` work begins.
 
 ## Recommended Driver Choices
 
@@ -298,6 +300,72 @@ Add these tests before the codebase grows too much:
 - worktree path generation test
 - council tally grouping test
 
+## Inbox Test Documentation Roadmap
+
+Goal:
+
+- make inbox behavior easy for a new agent to understand and convert into automated tests without re-reading all code paths
+
+Directory layout:
+
+- `docs/tests/inbox/README.md`
+- `docs/tests/inbox/_shared/README.md`
+- `docs/tests/inbox/workflows/README.md`
+- `docs/tests/inbox/<command>/README.md`
+
+Initial command folders:
+
+- `init`
+- `send`
+- `fetch`
+- `claim`
+- `renew`
+- `update`
+- `reply`
+- `done`
+- `fail`
+- `cancel`
+- `list`
+- `show`
+- `watch`
+- `wait-reply`
+
+Documentation rules:
+
+- organize by folder and `README.md`, not one file per test case
+- do not use numeric test case IDs
+- identify cases by file path plus a stable case title or `slug`
+- keep one command per directory, plus `workflows/` for cross-command behavior
+- use `_shared/` for common fixtures, database conventions, exit-code rules, and shared JSON assertions
+
+Required per-case structure:
+
+- `用例意义`
+- `前置条件`
+- `输入`
+- `预期输出`
+- `断言结论`
+
+Recommended case-title pattern:
+
+- `## case: <stable-slug>`
+
+Authoring order:
+
+1. global conventions in `docs/tests/inbox/README.md`
+2. shared fixtures and assertion helpers in `docs/tests/inbox/_shared/README.md`
+3. lifecycle flow in `docs/tests/inbox/workflows/README.md`
+4. core command docs: `send`, `fetch`, `claim`, `reply`, `done`, `show`
+5. secondary command docs: `renew`, `update`, `fail`, `cancel`, `list`
+6. waiting and read-state docs: `watch`, `wait-reply`, unread and mark-read workflow cases
+
+Definition of done:
+
+- every implemented inbox command has a dedicated document directory
+- every documented case contains concrete input and expected output
+- shared assumptions are centralized instead of copied into each command file
+- a new agent can pick any case and implement it as an automated test with minimal additional discovery
+
 ## Out Of Scope For First Pass
 
 Do not block v1 on these:
@@ -314,9 +382,10 @@ Do not block v1 on these:
 - The design phase is complete enough to start coding.
 - Avoid reopening major design questions unless implementation forces it.
 - The repository already has compiling binaries and working schema init.
-- Continue with inbox lifecycle commands before adding advanced orchestration.
+- Finish the inbox test-plan docs before starting broad `orch` implementation.
 - Preserve the separation:
   - `inbox` handles communication
   - `orch` handles scheduling
   - `council-review` is a workflow on top of `orch`
+- When writing inbox test docs, use the folder-per-command structure described above and keep cross-command cases inside `docs/tests/inbox/workflows/`.
 - Treat this file as the implementation entrypoint for new agents.