docs: add inbox markdown test plans

2026-03-19 10:54:39 +08:00
parent dab0506c5a
commit 9beb7e93eb
18 changed files with 2091 additions and 135 deletions
@@ -0,0 +1,70 @@
+# Inbox Markdown Test Plan
+
+## Purpose
+
+This directory contains the human-readable Markdown test plan for the `inbox` CLI.
+
+It complements automated Go tests. The goal is not to restate implementation details, but to preserve the user-visible CLI contract in a form that can be reviewed, extended, and executed manually when needed.
+
+## Directory Rules
+
+- one folder per command or shared area
+- one `README.md` per folder
+- no one-file-per-case sprawl
+- no numeric test IDs
+- each case is identified by `path + case slug`
+
+Recommended case heading pattern:
+
+```md
+  ## case: send-rejects-invalid-payload-json
+```
+
+## Authoring Principles
+
+- focus on externally visible behavior of the CLI
+- prefer stable command examples that a new agent can replay against a temp database
+- describe both success shape and failure contract
+- when a case already exists in automated Go tests, reuse its scenario rather than inventing a new one
+- keep terminology consistent with command flags and JSON fields exposed by the CLI
+
+## Common Execution Model
+
+Most cases in this directory assume the same baseline:
+
+1. create an isolated temporary directory
+2. choose a database path such as `TMPDIR/coord.db`
+3. run `inbox --db TMPDIR/coord.db --json init`
+4. run the target command sequence against that database
+
+Unless a case says otherwise:
+
+- commands should use `--json`
+- assertions should check both exit code and JSON payload
+- examples may use explicit `--agent`, or rely on the root `--agent` flag when that is the behavior under test
+
+## Folder Map
+
+- `README.md`: global conventions and glossary
+- `_shared/README.md`: reusable fixtures, JSON assertions, exit codes, payload rules
+- `workflows/README.md`: cross-command end-to-end scenarios
+- per-command folders: command-specific cases and edge conditions
+
+## Glossary
+
+- `thread`: the durable coordination unit tracked by `thread_id`
+- `message`: an event-bearing entry appended to a thread
+- `artifact`: a file attachment associated with a message
+- `read cursor`: the per-agent marker used by unread flows
+- `lease`: the temporary ownership granted by `claim` and extended by `renew`
+- `terminal state`: a thread state such as `done`, `failed`, or `cancelled`
+
+## Relationship To Automated Tests
+
+The current best executable reference is [internal/cli/inbox/integration_test.go](../../../internal/cli/inbox/integration_test.go).
+
+When this Markdown plan is expanded:
+
+- prefer matching an existing automated scenario first
+- record any additional manual-only contract coverage explicitly in the relevant command document
+- keep `docs/tests/inbox/ROADMAP.md` synchronized with authored files and case slugs