Matrix Coder Phase 2 — Observability: Kanban audit mirror

[Interstellar-code]

Epic: #76 · Phase 2 of 6

Goal

Make Matrix Coder delegations auditable and live-visible on the Switch UI by mirroring them as Hermes Kanban tasks. Observability layer — not control flow.

Depends on

Phase 1 (roles dispatch the work being mirrored).

Scope / Deliverables

• kanban_audit wiring (in hermes_bridge.py or a dedicated module) using hermes_cli.kanban_db directly — never raw SQL.
• Mapping: 1 invocation = parent card; each specialist dispatch = child card. Single-specialist invocation collapses to one card.
• Audit-mirror discipline: create cards status=running (never ready) with no dispatcher-actionable assignee, so the Kanban dispatcher cannot claim and re-execute the work.
• complete_task(summary, metadata, created_cards) carries findings; block_task on failure; add_comment for interim results.
• Spike: confirm complete_task/block_task behave on a card with no dispatcher-opened run.
• Verify live update on Switch UI (WebSocket events, ~300ms).

Ships when

A matrix invocation appears as a parent card with child cards transitioning running→done/blocked, visible live on Switch UI, with findings in the drawer — and the dispatcher never double-executes.

References

#76 Kanban Integration comment; body Non-Goals clarification.

Revisions (post advisory review)

• Remove the spike — already supported by code. complete_task/block_task accept never-claimed cards via expected_run_id=None (hermes_cli/kanban_db.py:3144-3161, 3570-3596). Just call with the default.
• Add test: an MC running card with no run/claim is never claimed by claim_task (CAS WHERE status=ready, :2544) nor promoted to ready by the stale-claim reaper (reaper only touches cards with claim_expires/worker_pid, which MC cards lack).

[Interstellar-code]

Advisory Plan Review — opus critic (code-verified, pre-implementation)

• [HIGH] The flagged spike is already answered by the code — remove it. complete_task accepts a never-claimed card via the expected_run_id is None branch (hermes_cli/kanban_db.py:3144-3161), works on status IN (running,ready,blocked), and synthesizes a zero-duration run so handoff fields persist. block_task does the same (:3570-3596). → Drop the spike; call complete_task/block_task with the default expected_run_id=None. Saves effort.

• [MED] Audit-mirror "create as running, no assignee" is sound — CONFIRMED. Dispatcher claims only status=ready (kanban_db.py:2544 CAS), create_task defaults running (:101,1760). Caveat: stale-claim reapers reset to ready only for cards with claim_expires/worker_pid (:2806+), which MC running cards won't have. → Add a test asserting an MC running card with no run is never claimed by claim_task and never promoted by the reaper.

• [LOW] WebSocket path real; token rides in ?token= URL (plugin_api.py:2145-2149, security note :31). MC adds no new exposure but its cards are visible to anyone with the URL. → Don't log the tokened WS URL in MC telemetry.

[Interstellar-code]

✅ Phase 2 complete — Kanban audit-mirror

Built via opus executor → opus code-review (APPROVE, no critical/high). Commit 4ef8efd62, branch feat/matrix-coder (PR #119).

Delivered

• core/kanban_audit.py — each matrix … invocation mirrors as ONE Kanban card via hermes_cli.kanban_db (open running on trigger → close done on completion). Live on Switch UI via the existing WebSocket feed.
• Audit-mirror invariants (code-verified vs real kanban_db): initial_status="running", no assignee, created_by="matrix_coder", complete_task with default expected_run_id → the dispatcher (claims only status='ready') never claims/re-runs mirror cards; the stale-claim reaper skips them (no claim_expires/worker_pid). No raw SQL.
• Lifecycle / no orphan leak: open on trigger; close on post_llm_call with the assistant response as summary; a non-trigger turn closes an orphan card (interrupted turn); a new trigger supersedes a stale card. No in-session orphan leak; double-close is a CAS no-op.
• Defensive + optional: try/except import of kanban_db + KANBAN_AUDIT_ENABLED flag + per-call guards → a kanban failure can NEVER break the persona hot path.
• One card per invocation (parent/child hierarchy deferred to Phase 3 fan-out). plugin.yaml → 0.3.0.

Verification

py_compile OK. 10 audit-mirror tests + 4 module suites green (stdlib runners; no venv). Added a signature-drift guard (inspect.signature(...).bind(...) against the real kanban_db) — passes, so our calls bind to the actual API; protects the most fragile area against future kanban_db changes.

Note

Cross-session edge (LOW, deferred): if the process exits mid-trigger-turn, the running card stays open until the next invocation supersedes it — inherent to a hook-driven mirror; kanban_db.detect_stale_running could reap later.

Next: Phase 3 (#115) — workflow/loop skills (Ralph, autopilot, ultrawork, ultraqa) — where parent/child Kanban hierarchy becomes real.