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
• all planned global, shared, workflow, and command-level Markdown test-plan documents have been authored

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

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

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	done
docs/tests/inbox/_shared/README.md	Shared fixtures, JSON assertions, exit-code rules	0	0	done
docs/tests/inbox/workflows/README.md	Cross-command scenarios	8	8	done
docs/tests/inbox/init/README.md	init command cases	2	2	done
docs/tests/inbox/send/README.md	send command cases	6	6	done
docs/tests/inbox/fetch/README.md	fetch command cases	4	4	done
docs/tests/inbox/claim/README.md	claim command cases	4	4	done
docs/tests/inbox/renew/README.md	renew command cases	3	3	done
docs/tests/inbox/update/README.md	update command cases	5	5	done
docs/tests/inbox/reply/README.md	reply command cases	4	4	done
docs/tests/inbox/done/README.md	done command cases	4	4	done
docs/tests/inbox/fail/README.md	fail command cases	4	4	done
docs/tests/inbox/cancel/README.md	cancel command cases	3	3	done
docs/tests/inbox/list/README.md	list command cases	4	4	done
docs/tests/inbox/show/README.md	show command cases	4	4	done
docs/tests/inbox/watch/README.md	watch command cases	3	3	done
docs/tests/inbox/wait-reply/README.md	wait-reply command cases	3	3	done

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

Path	Case Slug	Coverage Note	Status
docs/tests/inbox/workflows/README.md	thread-lifecycle-happy-path	end-to-end happy path from send to show after done	done
docs/tests/inbox/workflows/README.md	blocked-question-reply-resume-to-done	blocked thread receives answer and resumes to done	done
docs/tests/inbox/workflows/README.md	fail-lifecycle-from-claim-to-terminal	claimed thread transitions to failed terminal state	done
docs/tests/inbox/workflows/README.md	cancel-lifecycle-after-worker-claim	claimed thread can be cancelled by initiator	done
docs/tests/inbox/workflows/README.md	watch-wakes-then-fetch-sees-new-thread	watch wake-up remains consistent with unread fetch visibility	done
docs/tests/inbox/workflows/README.md	artifact-visible-through-send-and-show	body-file and artifact data survive send and show	done
docs/tests/inbox/workflows/README.md	unread-clears-after-mark-read-and-reappears-on-new-message	read cursor clears unread and new message restores it	done
docs/tests/inbox/workflows/README.md	wait-reply-clears-blocked-unread-for-agent	wait-reply consumes reply and clears blocked unread view	done
docs/tests/inbox/init/README.md	init-creates-schema-on-empty-db	initializes an empty database path and returns initialized status	done
docs/tests/inbox/init/README.md	init-is-idempotent-on-existing-db	repeated init succeeds on the same database path	done
docs/tests/inbox/send/README.md	send-creates-new-thread	creates a pending thread with an initial task message	done
docs/tests/inbox/send/README.md	send-appends-message-to-existing-thread	appends a message to an existing non-terminal thread	done
docs/tests/inbox/send/README.md	send-reads-body-from-body-file	reads message body from a file path	done
docs/tests/inbox/send/README.md	send-attaches-artifact-with-metadata	persists artifact path, kind, and metadata on send	done
docs/tests/inbox/send/README.md	send-rejects-invalid-payload-json	rejects malformed payload JSON with invalid_input	done
docs/tests/inbox/send/README.md	send-rejects-invalid-artifact-metadata-json	rejects malformed artifact metadata JSON	done
docs/tests/inbox/fetch/README.md	fetch-returns-pending-thread-for-target-agent	returns pending candidate work for the target agent	done
docs/tests/inbox/fetch/README.md	fetch-respects-status-and-limit-filters	enforces status filtering and max row count	done
docs/tests/inbox/fetch/README.md	fetch-unread-uses-read-cursor	unread filtering depends on per-agent read cursor state	done
docs/tests/inbox/fetch/README.md	fetch-returns-no-matching-work-when-empty	empty fetch result returns no_matching_work	done
docs/tests/inbox/claim/README.md	claim-acquires-thread-lease	claims a pending thread and records a claim event message	done
docs/tests/inbox/claim/README.md	claim-rejects-when-thread-missing	missing thread returns not_found	done
docs/tests/inbox/claim/README.md	claim-rejects-when-thread-already-claimed	active lease conflict returns lease_conflict	done
docs/tests/inbox/claim/README.md	claim-records-requested-lease-duration	claim event payload records requested lease duration	done
docs/tests/inbox/renew/README.md	renew-extends-active-lease	owner renews an active lease and gets a renewal event	done
docs/tests/inbox/renew/README.md	renew-rejects-non-owner	non-owner renew attempt returns lease_conflict	done
docs/tests/inbox/renew/README.md	renew-rejects-without-active-lease	missing active lease returns invalid_state	done
docs/tests/inbox/update/README.md	update-moves-thread-to-in-progress	owner moves a thread into in_progress with a progress message	done
docs/tests/inbox/update/README.md	update-moves-thread-to-blocked-with-payload	blocked update writes a question message and payload JSON	done
docs/tests/inbox/update/README.md	update-accepts-body-file-and-artifact	update supports body-file input and artifact attachments	done
docs/tests/inbox/update/README.md	update-rejects-invalid-payload-json	malformed update payload returns invalid_input	done
docs/tests/inbox/update/README.md	update-rejects-non-owner	non-owner update attempt returns lease_conflict	done
docs/tests/inbox/reply/README.md	reply-adds-answer-message	default reply kind is answer and thread stays non-terminal	done
docs/tests/inbox/reply/README.md	reply-supports-control-kind	reply can explicitly send control messages	done
docs/tests/inbox/reply/README.md	reply-attaches-artifact	reply persists artifact data on the message	done
docs/tests/inbox/reply/README.md	reply-rejects-invalid-payload-json	malformed reply payload returns invalid_input	done
docs/tests/inbox/done/README.md	done-marks-thread-terminal	owner completes a thread into done terminal state	done
docs/tests/inbox/done/README.md	done-persists-result-body-and-artifact	result body and artifacts remain visible after done	done
docs/tests/inbox/done/README.md	done-rejects-non-owner	non-owner done attempt returns lease_conflict	done
docs/tests/inbox/done/README.md	done-rejects-on-terminal-thread	terminal threads reject repeated done calls	done
docs/tests/inbox/fail/README.md	fail-marks-thread-failed	owner completes a thread into failed terminal state	done
docs/tests/inbox/fail/README.md	fail-persists-failure-body-and-artifact	failure body and artifacts remain visible after fail	done
docs/tests/inbox/fail/README.md	fail-rejects-non-owner	non-owner fail attempt returns lease_conflict	done
docs/tests/inbox/fail/README.md	fail-rejects-on-terminal-thread	terminal threads reject repeated fail calls	done
docs/tests/inbox/cancel/README.md	cancel-marks-thread-cancelled	cancel moves a non-terminal thread to cancelled	done
docs/tests/inbox/cancel/README.md	cancel-persists-reason-and-artifact	cancel records its reason text and attachments	done
docs/tests/inbox/cancel/README.md	cancel-rejects-when-thread-missing	missing thread returns not_found on cancel	done
docs/tests/inbox/list/README.md	list-filters-by-status	status filter limits listed threads	done
docs/tests/inbox/list/README.md	list-filters-by-created-by	created-by filter limits listed threads	done
docs/tests/inbox/list/README.md	list-filters-by-assigned-to	assigned-to filter limits listed threads	done
docs/tests/inbox/list/README.md	list-respects-limit	list returns at most the requested number of rows	done
docs/tests/inbox/show/README.md	show-returns-thread-and-message-history	show returns thread metadata and ordered history	done
docs/tests/inbox/show/README.md	show-includes-artifacts-per-message	show expands message artifacts in detail view	done
docs/tests/inbox/show/README.md	show-mark-read-advances-read-cursor	mark-read changes subsequent unread visibility	done
docs/tests/inbox/show/README.md	show-rejects-when-thread-missing	missing thread returns not_found on show	done
docs/tests/inbox/watch/README.md	watch-wakes-on-matching-thread	watch wakes on a new matching thread event	done
docs/tests/inbox/watch/README.md	watch-respects-status-filter	watch only wakes on events whose resulting thread status matches	done
docs/tests/inbox/watch/README.md	watch-times-out-with-no-activity	watch timeout returns no_matching_work	done
docs/tests/inbox/wait-reply/README.md	wait-reply-wakes-on-answer-after-message	wait-reply resumes from a known message boundary	done
docs/tests/inbox/wait-reply/README.md	wait-reply-can-start-from-after-event	wait-reply resumes from a known event cursor	done
docs/tests/inbox/wait-reply/README.md	wait-reply-times-out-when-no-reply	wait-reply timeout returns no_matching_work	done

Pending Case Backlog

No pending case slugs remain in the current plan.

When a new CLI contract or workflow needs coverage:

1. add the new case to the relevant README.md
2. add the new slug to Authored Case Register
3. update Current Snapshot and Document Progress

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