docs: assess scope and practical usability

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc

SCOPE.md

@@ -33,10 +33,55 @@ a distributed coordination service.
 
 ## Current State
 
-- Version `0.1.0` provides the local queue, endpoint manager, control-mode
+Version `0.1.0` is a usable local alpha for development and controlled
-  client, PTY tap, socket service, history operations, policy profiles, and CLI.
+single-host experiments. It is not yet a dependable unattended coordination
-- The local suite contains 50 passing tests as of 2026-08-24.
+transport.
-- Coordination-engine integration is deferred to `TAMQ-WP-0002`.
+
+| 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
 

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 |

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`.

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.