tmux-amq/workplans/TAMQ-WP-0016-structured-protocol-capture.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated
TAMQ-WP-0016	workplan	Structured communication protocol capture	communication	tmux-amq	finished	codex	structured-protocol-capture	2026-08-25	2026-08-25

Structured communication protocol capture

Retain reviewable evidence of TAMQ exchanges so agent onboarding and protocol friction can be assessed without recording arbitrary terminal sessions.

Define the evidence and privacy boundary

id: TAMQ-WP-0016-T01
status: done
priority: high

Capture only TAMQ protocol facts: addressed messages, provenance, worker block boundaries, allowlisted commands, line-limit decisions, endpoint lifecycle, and delivery outcomes. Do not capture unrelated pane output or ordinary shell input. Retain a message body once at acceptance rather than duplicating it at each lifecycle event.

Add an append-only protocol ledger

id: TAMQ-WP-0016-T02
status: done
priority: high

Add structured protocol events to SQLite schema version 5. Make acceptance events atomic with message admission, represent existing message lifecycle history during migration, and retain stable message/endpoint/repository links for filtering.

Instrument onboarding-sensitive transitions

id: TAMQ-WP-0016-T03
status: done
priority: high

Record operator versus worker origin, worker block start and close reason, invalid targets, limit blocks, operator-only command results, delivery mode, attempt, success, and failure class. Never store unrecognized command text or raw terminal output in event details.

Provide a review and analysis path

id: TAMQ-WP-0016-T04
status: done
priority: medium

Add tamq capture with repository, endpoint, message, event-type, and bounded event-count filters. Render a summarized Markdown review by default and stable JSONL for analysis. Document the workflow and retention/privacy boundary in the agent introduction, README, CLI help, and scope assessment.

Evidence

• Schema migration backfills existing acceptance/display/injection/ack events without duplicating newly captured events on later opens.
• Focused store, broker, service, renderer, and CLI tests cover atomic capture, worker termination evidence, provenance, failure classes, filtering, and Markdown/JSONL output.
• make check passes the complete suite.

Residuals

The capture deliberately describes transport behavior, not recipient comprehension or authorization. Long-term event retention and automated protocol-quality recommendations can be added after real captures show which summaries are useful.