docs(mt#1529): Inbox CLI UX spec — post-v1 verbs (mt#1529 research)

[minsky-ai]

Summary

Research-only document specifying the post-v1 CLI surface for the Agent Inbox (mt#454). Covers
multi-operator concurrency verbs (claim, release), lifecycle recovery verbs (close, reopen),
deadline and priority management (extend-deadline, set-priority, assign), batch operations,
and a v2 verb backlog with 7 deferred entries. No code changes — docs only.

Motivation and Context

mt#1456 + mt#1458 shipped the v1 asks CLI (list, create, respond, reconcile). This brief
designs the next layer of verbs that multi-operator inbox workflows require, grounding each verb in
the existing AskRepository interface and state-machine.ts transition table.

Design Approach

• Anchored every verb against src/domain/ask/state-machine.ts — no verb violates the existing
  transition table without an explicit flag marking it as a new transition required by mt#1528.
• Borrowed the Agent Inbox UX taxonomy from mt#1526 (accept/reject/edit/respond) and mapped it
  onto Minsky verbs in §2.
• Applied the project dry-run-first policy: every state-mutating verb defaults to --dry-run and
  requires --execute to apply. Each verb section specifies exactly what dry-run previews.
• Kept option naming consistent with v1 (hyphen-separated lowercase, same --json output shapes).

Key Changes

• docs/research/mt1529-inbox-cli-ux-spec.md — new file (924 lines)
  • §3: Full command reference for claim, release, close, reopen, extend-deadline,
    set-priority, assign, batch-close, batch-assign
  • §4: Post-v1 asks list filter extensions (--task, --deadline-before, --overdue, etc.)
  • §5: Complete state-transition table mapping each verb to AskRepository method(s)
  • §6: Composition notes ensuring v1 surface stays coherent
  • §7: v2 verb backlog (7 entries: bulk-reassign, watch, snooze, delegate, filter-save, export, merge)
  • §8: Explicit dependency table listing every provisional decision pending mt#1528

Dependencies on mt#1528

The following items in this spec are provisional and require mt#1528 finalization:

Decision	Provisional assumption	mt#1528 may change
Claim/release primitive	metadata.claimedBy field	Dedicated DB column with advisory lock
reopen transition	New closed → suspended in state machine	Alternative reopened state
Deadline update	New repo.setDeadline() method	Folded into repo.update()
Reassign	New repo.reassign() method	Folded into repo.update()
Priority storage	metadata.priority field	Dedicated priority column

asks reopen cannot be implemented until mt#1528 adds closed → suspended to the state machine.
All other verbs work with the current state machine and repository interface.

Acceptance Test Verification

1. Command reference exists with one section per verb, each following the consistent template
   (signature, params, exit codes, JSON shape, examples, errors, dry-run). Covered in §3.
2. Every verb mapped to AskRepository method(s) + AskState transitions; transitions verified
   against src/domain/ask/state-machine.ts (asks reopen flagged as requiring new transition).
   Covered in §5.
3. Dry-run sections explicitly state what the verb would do and what it preserves; matches
   --execute flag pattern. Covered in each verb's dry-run subsection in §3.
4. v2 backlog has 7 entries (exceeds the 5-entry minimum), each with a one-sentence justification.
   Covered in §7.
5. Cross-links to mt#1458 asks.respond and mt#1456 asks.list surfaces maintained. Covered
   in §6 and §9.

Testing

Docs-only PR — no runnable tests. Prettier was run and confirmed clean before commit.

[minsky-reviewer]

Independent adversarial review (Chinese-wall)
Reviewer: minsky-reviewer[bot] via openai:gpt-5
Tier: unknown

---

Comprehensive docs-only spec with clear dry-run patterns and state-machine references. However, there is a fundamental semantic mismatch in §3.4/§5: the spec defines asks close as transitioning to cancelled while citing repo.close(), but the repository’s close() transitions to closed. This contradiction risks misimplementation and user confusion and must be corrected. Additional non-blocking notes: the claim/release sections suggest a metadata patch via transition("suspended") despite no repo API for metadata updates; extend-deadline assumes a setDeadline method not present (provisionally noted but could be clearer); and priority-in-metadata combined with asks list --priority would have performance/feasibility implications unless a dedicated column is introduced. Please address the blocking state mismatch and tighten repo-API references for clarity.

Findings

• [BLOCKING] docs/research/mt1529-inbox-cli-ux-spec.md:260 — asks close: documented transition/state contradicts repository semantics (repo.close() sets state "closed", not "cancelled")
  In §3.4 "asks close" the spec defines the verb as operator-driven cancellation that transitions the Ask to cancelled, and in the Repository + state transition table it lists repo.close() as the method and "Current state → cancelled" as the effect. However, the actual repository contract AskRepository.close() transitions the Ask to "closed" and explicitly sets state: "closed" (see src/domain/ask/repository.ts: the close implementation calls guardTransition(existing.state, "closed") and updates state: "closed" alongside closedAt and respondedAt). There is no repository method that results in cancelled, and close is semantically bound to closed throughout the codebase. This contradiction will mislead implementers and users about terminal semantics. Please align the verb semantics and transition table: either (a) define a dedicated cancel path (e.g., repo.transition(..., "cancelled") with payload conventions) and stop referencing repo.close(), or (b) change the CLI verb/description to reflect that asks close results in closed, not cancelled. The state-transition summary in §5 also repeats this mismatch and should be corrected accordingly.
• [NON-BLOCKING] docs/research/mt1529-inbox-cli-ux-spec.md:118 — Claim/release implementation sketch suggests metadata patch via repo.transition even though no such metadata update API exists
  In §3.2 asks claim the Repo + state transition table proposes repo.transition(id, "suspended") + metadata patch for recording claimedBy/claimedAt. The repository interface exposes no general "metadata patch" operation; only specific field updaters exist (updateRoutingTarget, updateWindowMissedCount, updateForceImmediate). Similarly for asks release. Calling transition("suspended") as a no-op write to enable metadata persistence seems like an anti-pattern and might be unnecessary. Consider documenting a dedicated repo.updateMetadata(id, patch) or repo.claim(id, operator)/repo.releaseClaim(id, force?) provisional methods in §5/§8, or clarify that implementations will perform a direct metadata update without a state transition. This avoids implying an API that doesn’t exist and reduces risk of consumers misusing transition for non-state updates.
• [NON-BLOCKING] docs/research/mt1529-inbox-cli-ux-spec.md:585 — asks extend-deadline assumes a repo.setDeadline() method not present in the current repository interface
  Section 3.6 specifies updating deadlines via a new repo.setDeadline() method, and §5 repeats this. The current AskRepository (src/domain/ask/repository.ts) has no such method; only state transitions and a few targeted field updaters exist. While §8 marks this as provisional, it would help to explicitly list setDeadline in the "New repository methods required" block with a concrete signature (you do list it later in §5 bullets) and/or acknowledge the alternative of using a general repo.update() patch method if that lands in mt#1528. Minor clarity improvement, but the doc is internally mostly consistent.
• [NON-BLOCKING] docs/research/mt1529-inbox-cli-ux-spec.md:732 — asks set-priority stores priority in metadata but list filters later treat it as canonical; call out indexing/filter implications
  Section 3.7 defines priority in metadata.priority and §4 proposes asks list --priority <level>. Given the repo has no first-class priority field and list filters currently operate in-memory in asks.ts (gatherAsks fetches by state then filters), clarifying that --priority would be implemented either via client-side filtering (and thus non-performant) or requires a schema change (mt#1528 dedicated column + indexed) would set expectations. §8 mentions a possible dedicated column; referencing that from §4 would keep the spec coherent about performance and feasibility.