diff --git a/SCOPE.md b/SCOPE.md index d9d3fb4..d9c1c3a 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -33,10 +33,55 @@ a distributed coordination service. ## Current State -- Version `0.1.0` provides the local queue, endpoint manager, control-mode - client, PTY tap, socket service, history operations, policy profiles, and CLI. -- The local suite contains 50 passing tests as of 2026-08-24. -- Coordination-engine integration is deferred to `TAMQ-WP-0002`. +Version `0.1.0` is a usable local alpha for development and controlled +single-host experiments. It is not yet a dependable unattended coordination +transport. + +| Intent capability | State | Evidence and remaining gap | +| --- | --- | --- | +| Direct repository addressing | Implemented | Exact `gita` validation and `@repo:` parsing are covered by tests. | +| Durable, inspectable local queue | Implemented | SQLite history, leases, endpoint records, inspect/history, JSONL export/replay, acknowledgement, and purge are present. | +| Local socket service | Implemented | Peer-credential checks and structured ping/register/send/history/ack/endpoints/disconnect operations are tested. | +| Tmux endpoint lifecycle and delivery | Implemented, integration confidence limited | The manager, control client, and delivery loop exist, but tests use fakes and CI does not exercise real tmux panes or agent processes. | +| Full-duplex input observation | Implemented, lightly proven | `tamq tap` preserves PTY traffic and observes complete address lines; PTY code coverage is 23%. | +| Bounded retry behavior | Not enforced | Failed injection remains pending and becomes claimable after lease expiry, but no attempt counter or terminal failure state applies the configured cap. | +| Acknowledgement policy | Partially implemented | Explicit acknowledgement and the configuration field exist; delivery always marks a successful tmux injection as `injected`, irrespective of `delivery_ack_mode`. | +| Coordination-engine interoperability | Not implemented | The adapter contract and implementation remain in `TAMQ-WP-0002`. | + +## Practical Usability + +The following operator path was exercised successfully on 2026-08-24 with an +isolated state directory: start the socket service, ping it, inspect status, +queue a message to registered repo `tmux-amq`, inspect history, export one JSONL +record, and stop the service. + +Suitable today: + +- Local queue, history, export/replay, and diagnostic use. +- Controlled experiments with gita-registered repositories and tmux endpoints. +- Developing and testing the future coordination-engine adapter against the + local socket boundary. + +Not yet suitable: + +- Unattended or high-confidence delivery where bounded retries and positive + recipient acknowledgement are required. +- Production-style operation without a real tmux/PTY integration test suite, + crash-recovery evidence, and stronger process supervision evidence. +- Cross-host messaging or use as a general-purpose broker. + +The suite currently has 50 passing tests and 73% statement coverage. Coverage +is strongest in durable storage and registry handling, and weakest in the PTY +tap, control-mode process handling, and CLI orchestration. The Forgejo CI job +runs unit tests and CLI help/version smoke checks on Python 3.11, but does not +install or exercise tmux and gita end to end. + +## Next Usability Gates + +- `TAMQ-WP-0003` owns bounded retry state, acknowledgement enforcement, + lifecycle recovery, and real tmux/PTY integration evidence. +- `TAMQ-WP-0002` owns the coordination-engine adapter after the local delivery + contract is sufficiently reliable. ## Getting Oriented diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index acbed4c..4f184c4 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -8,11 +8,18 @@ | Kind | ID | Status | Lane | Source | | --- | --- | --- | --- | --- | +| workplan | TAMQ-WP-ADHOC-2026-08-24 | finished | — | workplans/ADHOC-2026-08-24.md | | workplan | TAMQ-WP-0001 | finished | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md | -| workplan | TAMQ-WP-0002 | backlog | — | workplans/TAMQ-WP-0002-coordination-engine-adapter.md | +| workplan | TAMQ-WP-0002 | active | — | workplans/TAMQ-WP-0002-coordination-engine-adapter.md | +| workplan | TAMQ-WP-0003 | active | — | workplans/TAMQ-WP-0003-delivery-reliability.md | +| task | TAMQ-WP-ADHOC-2026-08-24-T01 | done | — | workplans/ADHOC-2026-08-24.md | | task | TAMQ-WP-0001-T01 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md | | task | TAMQ-WP-0001-T02 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md | | task | TAMQ-WP-0001-T03 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md | | task | TAMQ-WP-0002-T01 | todo | — | workplans/TAMQ-WP-0002-coordination-engine-adapter.md | | task | TAMQ-WP-0002-T02 | wait | — | workplans/TAMQ-WP-0002-coordination-engine-adapter.md | | task | TAMQ-WP-0002-T03 | wait | — | workplans/TAMQ-WP-0002-coordination-engine-adapter.md | +| task | TAMQ-WP-0003-T01 | todo | — | workplans/TAMQ-WP-0003-delivery-reliability.md | +| task | TAMQ-WP-0003-T02 | wait | — | workplans/TAMQ-WP-0003-delivery-reliability.md | +| task | TAMQ-WP-0003-T03 | todo | — | workplans/TAMQ-WP-0003-delivery-reliability.md | +| task | TAMQ-WP-0003-T04 | wait | — | workplans/TAMQ-WP-0003-delivery-reliability.md | diff --git a/workplans/ADHOC-2026-08-24.md b/workplans/ADHOC-2026-08-24.md new file mode 100644 index 0000000..10fc7f3 --- /dev/null +++ b/workplans/ADHOC-2026-08-24.md @@ -0,0 +1,28 @@ +--- +id: TAMQ-WP-ADHOC-2026-08-24 +type: workplan +title: "Refresh scope and assess practical usability" +domain: communication +repo: tmux-amq +status: finished +owner: codex +topic_slug: coulomb-social +created: "2026-08-24" +updated: "2026-08-24" +--- + +# Refresh scope and assess practical usability + +## Assess implementation against intent and update scope + +```task +id: TAMQ-WP-ADHOC-2026-08-24-T01 +status: done +priority: medium +``` + +Reviewed the implementation and tests against `INTENT.md`, ran the 50-test +suite with coverage, exercised the isolated socket/queue/history/export/shutdown +workflow, and updated `SCOPE.md` with an evidence-based maturity assessment. +Reliability residuals were handed to `TAMQ-WP-0003`; coordination-engine +interoperability remains owned by `TAMQ-WP-0002`. diff --git a/workplans/TAMQ-WP-0003-delivery-reliability.md b/workplans/TAMQ-WP-0003-delivery-reliability.md new file mode 100644 index 0000000..cd8dd15 --- /dev/null +++ b/workplans/TAMQ-WP-0003-delivery-reliability.md @@ -0,0 +1,67 @@ +--- +id: TAMQ-WP-0003 +type: workplan +title: "Delivery reliability and practical integration evidence" +domain: communication +repo: tmux-amq +status: active +owner: codex +topic_slug: coulomb-social +created: "2026-08-24" +updated: "2026-08-24" +--- + +# Delivery reliability and practical integration evidence + +Close the reliability gaps found during the 2026-08-24 intent and usability +assessment before treating tmux-amq as an unattended local transport or as a +stable coordination-engine dependency. + +## Enforce bounded delivery attempts + +```task +id: TAMQ-WP-0003-T01 +status: todo +priority: high +``` + +Persist attempt counts and failure reasons, apply the selected policy profile's +retry cap, define lease-expiry behavior, and introduce an inspectable terminal +failure state. Prove restart-safe behavior and avoid tight retry loops. + +## Enforce acknowledgement semantics + +```task +id: TAMQ-WP-0003-T02 +status: wait +priority: high +``` + +Make `delivery_ack_mode` control whether injection completes delivery or waits +for explicit recipient acknowledgement. Specify timeout, redelivery, duplicate, +and late-acknowledgement behavior. This task follows the state model from T01. + +## Add real tmux and PTY lifecycle coverage + +```task +id: TAMQ-WP-0003-T03 +status: todo +priority: high +``` + +Exercise a real tmux server, managed windows, control-mode injection, `tamq tap`, +service shutdown, endpoint disappearance, and restart recovery without starting +an external coding agent. Keep fast unit tests while adding a bounded integration +suite. + +## Align CI and operator documentation + +```task +id: TAMQ-WP-0003-T04 +status: wait +priority: medium +``` + +Run the integration suite in Forgejo CI with explicit tmux and gita setup. Update +README claims about retries, acknowledgement, prerequisites, and maturity from +verified behavior. This task follows T01-T03.