diff --git a/.custodian-brief.md b/.custodian-brief.md index 8ea802c..d6c066b 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -2,11 +2,19 @@ # Custodian Brief — tmux-amq **Domain:** communication -**Last synced:** 2026-08-24 12:43 UTC +**Last synced:** 2026-08-24 13:30 UTC **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)* ## Active Workstreams +### Coordination-engine adapter boundary +Progress: 0/3 done | workplan_id: `48da5fa7-b7bf-5d13-8edc-b90f266e241c` + +**Open tasks:** +- ! Implement the coordination-engine client adapter `195db613` +- ! Prove interoperability and recovery `23c7f6c7` +- · Specify the adapter contract `a222dab7` + ### Delivery reliability and practical integration evidence Progress: 0/4 done | workplan_id: `7961275b-8f1f-5827-b9fc-46b3ac35fb73` @@ -16,14 +24,6 @@ Progress: 0/4 done | workplan_id: `7961275b-8f1f-5827-b9fc-46b3ac35fb73` - · Enforce bounded delivery attempts `52c43745` - · Add real tmux and PTY lifecycle coverage `9a3d84b4` -### Coordination-engine adapter boundary -Progress: 0/3 done | workplan_id: `48da5fa7-b7bf-5d13-8edc-b90f266e241c` - -**Open tasks:** -- ! Implement the coordination-engine client adapter `195db613` -- ! Prove interoperability and recovery `23c7f6c7` -- · Specify the adapter contract `a222dab7` - --- ## MCP Orientation (when available) diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 4f184c4..0d9d301 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -12,6 +12,7 @@ | workplan | TAMQ-WP-0001 | finished | — | workplans/TAMQ-WP-0001-statehub-bootstrap.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 | +| workplan | TAMQ-WP-0004 | ready | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.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 | @@ -23,3 +24,8 @@ | 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 | +| task | TAMQ-WP-0004-T01 | todo | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md | +| task | TAMQ-WP-0004-T02 | todo | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md | +| task | TAMQ-WP-0004-T03 | todo | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md | +| task | TAMQ-WP-0004-T04 | wait | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md | +| task | TAMQ-WP-0004-T05 | wait | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md | diff --git a/workplans/TAMQ-WP-0004-operator-installable-local-alpha.md b/workplans/TAMQ-WP-0004-operator-installable-local-alpha.md new file mode 100644 index 0000000..b3cc6ea --- /dev/null +++ b/workplans/TAMQ-WP-0004-operator-installable-local-alpha.md @@ -0,0 +1,133 @@ +--- +id: TAMQ-WP-0004 +type: workplan +title: "Operator-installable local alpha session" +domain: communication +repo: tmux-amq +status: ready +owner: codex +topic_slug: coulomb-social +planning_priority: P0 +planning_order: 10 +created: "2026-08-24" +updated: "2026-08-24" +--- + +# Operator-installable local alpha session + +Make tmux-amq directly usable by the operator from a normal local shell without +running it from the source checkout or manually assembling service, tmux, and +agent commands. + +## Alpha user journey + +The completed workflow must be: + +```bash +git clone +cd tmux-amq +make install + +tamq --version +tamq start tmux-amq +``` + +`tamq start tmux-amq` starts or reuses the local service and managed `tamq` +session, opens the `tmux-amq` gita repository in its registered path, launches +Codex behind `tamq tap`, and attaches the operator to the session. The detached +workflow must also work: + +```bash +tamq start --detach tmux-amq +tamq status +tamq attach +``` + +## Acceptance gates + +- `make install` is documented, repeatable, and installs an isolated `tamq` + command into the invoking user's normal executable path. +- Installation and upgrade do not require activating the repository `.venv`. +- Missing `uv`, tmux, gita, Codex, PATH configuration, or repository + registration produces a direct actionable error before a partial session is + left behind. +- The first and subsequent windows start in their exact `gita freeze` paths. +- Default `tamq start` attaches; `--detach` returns to the caller and prints a + useful endpoint/session summary; `tamq attach` attaches later. +- Repeating `tamq start` safely reuses the service/session and does not create + duplicate repository windows or agent processes. +- A real installed-package smoke test proves start, attach/detach, status, + message routing, history visibility, stop, and bounded cleanup on this local + environment. +- The README contains a short install/start/stop/uninstall quickstart and states + the alpha reliability boundaries from `SCOPE.md`. + +## Add the user-level install target + +```task +id: TAMQ-WP-0004-T01 +status: todo +priority: high +``` + +Add a phony `make install` target using uv's isolated tool installation flow, +with an explicit upgrade/reinstall behavior suitable for repeated development +installs. Verify `command -v tamq`, `tamq --version`, and invocation from outside +the checkout. Document the corresponding uninstall command and executable-path +expectation. + +## Make session startup match the CLI contract + +```task +id: TAMQ-WP-0004-T02 +status: todo +priority: high +``` + +Implement the currently unused `--detach` flag. Make non-detached `tamq start` +attach to the managed session after successful endpoint registration and pending +delivery. Ensure the first boot window uses the selected repository's registered +path rather than the caller's current directory, and preserve idempotent reuse of +existing windows. + +## Add installation and startup preflight + +```task +id: TAMQ-WP-0004-T03 +status: todo +priority: high +``` + +Before mutating tmux or service state, check the required commands, exact gita +targets and paths, writable runtime/state locations, agent command availability, +and session conflicts. Return concise remediation for every failure and avoid +leaving boot windows, sockets, pidfiles, or processes behind after a failed +start. + +## Prove the installed local session end to end + +```task +id: TAMQ-WP-0004-T04 +status: wait +priority: high +``` + +Add automated coverage using an isolated uv tool directory, state directory, +socket, and tmux server. Use a deterministic benign agent fixture in automation, +then perform the operator acceptance with the installed `tamq` command and Codex. +Prove attach/detach semantics, correct pane directories, idempotent reuse, +message injection/history, shutdown, and cleanup. This task follows T01-T03. + +## Publish the alpha quickstart and evidence + +```task +id: TAMQ-WP-0004-T05 +status: wait +priority: medium +``` + +Update README and agent workflow documentation with prerequisites, install, +upgrade, start, attach, status, stop, and uninstall commands. Record the exact +local acceptance commands and results. Clearly retain the reliability caveats +owned by `TAMQ-WP-0003` and do not claim coordination-engine integration from +`TAMQ-WP-0002`. This task follows T04.