ai-workflow-skill/docs/tests/inbox/ROADMAP.md

Inbox Test Documentation Roadmap

Purpose

This roadmap tracks the human-readable Markdown test plan for inbox.

It exists so a new agent can immediately answer four questions without re-reading the whole codebase:

• which test-plan documents already exist
• which cases have already been written down
• which cases are still missing
• what file should be updated next

This roadmap is for the Markdown test-plan set under docs/tests/inbox/. It is not a replacement for automated Go tests.

Current Snapshot

Snapshot date:

• 2026-03-19

Current state:

• inbox CLI is implemented end-to-end
• automated Go integration tests already exist for the main lifecycle, wait flows, unread behavior, artifacts, and JSON error contracts
• this roadmap now exists under docs/tests/inbox/ROADMAP.md
• the command, workflow, and shared Markdown test-plan documents have not been authored yet

Progress summary for planned test-plan documents, excluding ROADMAP.md:

• planned document files: 16
• authored document files: 0
• planned case slugs in this roadmap: 61
• authored case slugs in this roadmap: 0

Scope

In scope:

• inbox init
• inbox send
• inbox fetch
• inbox claim
• inbox renew
• inbox update
• inbox reply
• inbox done
• inbox fail
• inbox cancel
• inbox list
• inbox show
• inbox watch
• inbox wait-reply
• cross-command workflows
• shared test conventions for JSON output, exit codes, fixtures, and assertions

Out of scope:

• orch
• council-review
• implementation details that are not visible through the CLI contract

Tracking Rules

Directory model:

• one folder per command or shared area
• one README.md per folder
• no one-file-per-case sprawl

Case identity:

• do not use numeric IDs
• identify a case by path + case slug
• recommended heading pattern inside the command document:

## case: send-rejects-invalid-payload-json

Per-case structure inside the command document:

• 用例意义
• 前置条件
• 输入
• 预期输出
• 断言结论

How to update this roadmap when a new case is written:

1. add the case content to the target README.md
2. move the case slug from Pending Case Backlog to Authored Case Register
3. update the authored counts in Current Snapshot
4. if a whole command document is created, update Document Progress

Allowed status values in this roadmap:

• pending
• in_progress
• done
• deferred

Existing Automated Coverage Reference

The Markdown test-plan set starts at zero, but these automated tests already exist and should be used as source material when writing the docs:

• integration_test.go TestInboxLifecycle
• integration_test.go TestInboxFailLifecycle
• integration_test.go TestInboxRenewWaitReplyAndCancel
• integration_test.go TestInboxWatchListUnreadAndAppend
• integration_test.go TestInboxUnreadReadCursor
• integration_test.go TestInboxJSONErrorsAndExitCodes

These tests do not remove the need for the Markdown plan. They only reduce discovery work.

Planned Directory Tree

docs/tests/inbox/
  ROADMAP.md
  README.md
  _shared/
    README.md
  workflows/
    README.md
  init/
    README.md
  send/
    README.md
  fetch/
    README.md
  claim/
    README.md
  renew/
    README.md
  update/
    README.md
  reply/
    README.md
  done/
    README.md
  fail/
    README.md
  cancel/
    README.md
  list/
    README.md
  show/
    README.md
  watch/
    README.md
  wait-reply/
    README.md

Document Progress

Path	Purpose	Planned Cases	Authored Cases	Status
docs/tests/inbox/README.md	Global testing conventions and glossary	0	0	pending
docs/tests/inbox/_shared/README.md	Shared fixtures, JSON assertions, exit-code rules	0	0	pending
docs/tests/inbox/workflows/README.md	Cross-command scenarios	8	0	pending
docs/tests/inbox/init/README.md	init command cases	2	0	pending
docs/tests/inbox/send/README.md	send command cases	6	0	pending
docs/tests/inbox/fetch/README.md	fetch command cases	4	0	pending
docs/tests/inbox/claim/README.md	claim command cases	4	0	pending
docs/tests/inbox/renew/README.md	renew command cases	3	0	pending
docs/tests/inbox/update/README.md	update command cases	5	0	pending
docs/tests/inbox/reply/README.md	reply command cases	4	0	pending
docs/tests/inbox/done/README.md	done command cases	4	0	pending
docs/tests/inbox/fail/README.md	fail command cases	4	0	pending
docs/tests/inbox/cancel/README.md	cancel command cases	3	0	pending
docs/tests/inbox/list/README.md	list command cases	4	0	pending
docs/tests/inbox/show/README.md	show command cases	4	0	pending
docs/tests/inbox/watch/README.md	watch command cases	3	0	pending
docs/tests/inbox/wait-reply/README.md	wait-reply command cases	3	0	pending

Authoring Order

Recommended order:

1. docs/tests/inbox/README.md
2. docs/tests/inbox/_shared/README.md
3. docs/tests/inbox/workflows/README.md
4. docs/tests/inbox/send/README.md
5. docs/tests/inbox/fetch/README.md
6. docs/tests/inbox/claim/README.md
7. docs/tests/inbox/reply/README.md
8. docs/tests/inbox/done/README.md
9. docs/tests/inbox/show/README.md
10. the remaining command documents

Reason:

• the workflow file captures the highest-value end-to-end behavior first
• the command documents can then reuse shared conventions and already-fixed terminology

Authored Case Register

No Markdown test cases have been authored yet.

When the first case is written, add rows in this format:

Path	Case Slug	Coverage Note	Status
docs/tests/inbox/send/README.md	send-creates-new-thread	minimal happy path for new thread creation	done

Pending Case Backlog

docs/tests/inbox/workflows/README.md

• pending thread-lifecycle-happy-path
• pending blocked-question-reply-resume-to-done
• pending fail-lifecycle-from-claim-to-terminal
• pending cancel-lifecycle-after-worker-claim
• pending watch-wakes-then-fetch-sees-new-thread
• pending artifact-visible-through-send-and-show
• pending unread-clears-after-mark-read-and-reappears-on-new-message
• pending wait-reply-clears-blocked-unread-for-agent

docs/tests/inbox/init/README.md

• pending init-creates-schema-on-empty-db
• pending init-is-idempotent-on-existing-db

docs/tests/inbox/send/README.md

• pending send-creates-new-thread
• pending send-appends-message-to-existing-thread
• pending send-reads-body-from-body-file
• pending send-attaches-artifact-with-metadata
• pending send-rejects-invalid-payload-json
• pending send-rejects-invalid-artifact-metadata-json

docs/tests/inbox/fetch/README.md

• pending fetch-returns-pending-thread-for-target-agent
• pending fetch-respects-status-and-limit-filters
• pending fetch-unread-uses-read-cursor
• pending fetch-returns-no-matching-work-when-empty

docs/tests/inbox/claim/README.md

• pending claim-acquires-thread-lease
• pending claim-rejects-when-thread-missing
• pending claim-rejects-when-thread-already-claimed
• pending claim-records-requested-lease-duration

docs/tests/inbox/renew/README.md

• pending renew-extends-active-lease
• pending renew-rejects-non-owner
• pending renew-rejects-without-active-lease

docs/tests/inbox/update/README.md

• pending update-moves-thread-to-in-progress
• pending update-moves-thread-to-blocked-with-payload
• pending update-accepts-body-file-and-artifact
• pending update-rejects-invalid-payload-json
• pending update-rejects-non-owner

docs/tests/inbox/reply/README.md

• pending reply-adds-answer-message
• pending reply-supports-control-kind
• pending reply-attaches-artifact
• pending reply-rejects-invalid-payload-json

docs/tests/inbox/done/README.md

• pending done-marks-thread-terminal
• pending done-persists-result-body-and-artifact
• pending done-rejects-non-owner
• pending done-rejects-on-terminal-thread

docs/tests/inbox/fail/README.md

• pending fail-marks-thread-failed
• pending fail-persists-failure-body-and-artifact
• pending fail-rejects-non-owner
• pending fail-rejects-on-terminal-thread

docs/tests/inbox/cancel/README.md

• pending cancel-marks-thread-cancelled
• pending cancel-persists-reason-and-artifact
• pending cancel-rejects-when-thread-missing

docs/tests/inbox/list/README.md

• pending list-filters-by-status
• pending list-filters-by-created-by
• pending list-filters-by-assigned-to
• pending list-respects-limit

docs/tests/inbox/show/README.md

• pending show-returns-thread-and-message-history
• pending show-includes-artifacts-per-message
• pending show-mark-read-advances-read-cursor
• pending show-rejects-when-thread-missing

docs/tests/inbox/watch/README.md

• pending watch-wakes-on-matching-thread
• pending watch-respects-status-filter
• pending watch-times-out-with-no-activity

docs/tests/inbox/wait-reply/README.md

• pending wait-reply-wakes-on-answer-after-message
• pending wait-reply-can-start-from-after-event
• pending wait-reply-times-out-when-no-reply

Definition Of Done

This roadmap is complete only when all of the following are true:

• every implemented inbox command has a corresponding document folder
• each planned command document exists
• each pending case slug has been either authored or explicitly deferred
• the authored-case register matches the actual Markdown files on disk
• a new agent can pick any pending case and know exactly where it should be written