CLI-PROPOSAL — Unified `orchestrata` CLI

Design for the single orchestrata entrypoint CLI, derived from specs/000-orchestrata-cli and usage-scenarios/scenario-000-new-project.md through four rounds of user revision (see design-evolution, open-decisions).

Status

Phase: design settled with the user, awaiting "go" for implementation.
Exploratory code: uncommitted on branch feat/orchestrata-cli (wt-QWEN) — kernel/cli_client.py (gateway client helper) + cli_main.py command implementations from the first (request/response) model. Will be reworked to the final model or scrapped per the user's call.
Base spec: SPEC-000 (checklist: 112 REQs across US-001..US-010 + cross-cutting). Entry point already wired: pyproject.toml [project.scripts] orchestrata = "orchestrata_ultimate.kernel.cli_main:main".

Final design (v4)

Identity model

The user never types an ID. Talking to the concierge opens a session; the session ID is generated server-side and embedded in the session object.
A session belongs to a project — a folder in the workspace (~/workspace/*). Git worktrees (wt-*) are NOT projects; they resolve to their parent project (via the .git file's gitdir: pointer — exact, not name-matching).
Context resolution: the CLI walks up from cwd to the project root and maps to its active session. Every command operates on the current project's active session implicitly; --project <name> only as an override.

The agentic workflow the CLI serves

user ──intent──▶ U:Cx Concierge ──clarifying questions──▶ user (respond)
                     │
                     ▼
              agents propose way forward ──▶ user revises / approves / instructs
                     │
                     ▼
              goal + definition-of-done + success criteria set
                     │
                     ▼
              execution ──▶ constant updates on the Redis queue
                     │        ▲ watch (real-time stream)
                     ▼        │
              task done ◀── status via concierge (live queue state)

Commands (all async — nothing blocks, ever)

Command	Behavior
`orchestrata intent "<text>"`	Opens/resumes the project's session, submits, prints ack + session reference, returns immediately. Clarifying questions arrive on the queue.
`orchestrata respond "<text>"`	Answers concierge questions AND carries revision instructions (one verb for the conversation).
`orchestrata review`	Current proposal/goal/DoD from live queue state.
`orchestrata approve`	Releases execution (proposal + DoD approved in one human verdict; no auto-approval).
`orchestrata ask "<question>"`	Concierge status query answered from live Redis queue state.
`orchestrata watch [--session <id>]`	The only attaching command: streams the session's queue updates in real time (gateway `pipeline.<thread>` topic + ring-buffer replay), one line per event, until done or Ctrl-C.
`orchestrata status`	All projects with active sessions: stage, waiting-on-you flags.
`orchestrata init <name> [--template]`	New project folder: context.json, orchestrata.yaml, prolog rules; name validated `[a-z][a-z0-9-]*`.
`orchestrata start` / `stop`	Boot monolith / archive session + SIGTERM gateway+kernel via PID files.
`orchestrata config team --add/--remove <volks>`	Validate 8 volk aliases, persist orchestrata.yaml, regenerate prolog/team.pl `active_volk/1`.
`orchestrata session *`	Wraps the existing session CLI.
`orchestrata governance check/log/policies`	Prolog evaluate / decision history / active rules.
`orchestrata knowledge query "<q>"`	Graph query, terminal-formatted.
`orchestrata version`	Version string.

Cross-cutting

--json on every data command (REQ-000-096).
Clean ClickException errors, no raw tracebacks (REQ-000-097).
Gateway WebSocket JSON-RPC is the single runtime ingress (CXP_WS_URI/GATEWAY_HOST:PORT from .env, never hardcoded; JWT minted from the shared secret, same pattern as scripts/start_test_services.py).
Synchronous by nature only: local file/PID operations and one-shot reads.
@traces on every command (trace-lint stays green).

CLI-PROPOSAL — Unified orchestrata CLI