/maestro-session-manage

name: maestro-session-manage
disable-model-invocation: true
description: Manage a v3 Session — inspect status/resume-view, review knowledge candidates, complete, archive/unarchive
argument-hint: "[--session <session_id>] [--complete|--archive|--unarchive|--knowledge] [-y] [--skip-knowledge]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
session-mode: run
contract:
  discovery: self-described
  consumes: []
  produces: []

<required_reading> @~/.maestro/workflows/run-mode.md </required_reading>

If any required file above was not expanded into context by the host, or its content is no longer in context, Read it explicitly before executing any step.

<purpose> Manage the lifecycle of a v3 Session (`session/3.0`) through its read-only projections, knowledge governance, and explicit lifecycle transitions.

Session completion (`maestro session complete`) is part of the default Run loop — Ralph S_DONE, the orchestrator run loop, and Companion all execute it when the chain turns terminal. This command is the **management surface**: inspection, knowledge candidate review/promotion, and the explicit transitions the default loop does not perform (`--complete` for manual pipelines, `--archive`/`--unarchive` for optional freezing).

Run completion already stages accepted decisions, locked constraints, and explicit `maestro knowledge stage` entries. This command reviews those receipts; it does not re-extract the same artifacts or write project knowledge through a second path. </purpose>

<context> $ARGUMENTS -- optional session ID and action flags.

**Actions (first match wins; default = inspect):** | Flag | Effect | |------|--------| | *(none)* | Inspect: `session status` + `session resume-view` projection | | `--complete` | Readiness check → knowledge reconciliation → fenced `maestro session complete` → DAG progression | | `--archive` | Fenced `maestro session archive` (only from `completed`/`failed`; optional freeze) | | `--unarchive` | Fenced `maestro session unarchive` (only from `archived`; returns to `open`) | | `--knowledge` | Knowledge review/promotion only — no lifecycle mutation |

**Shared flags:** | Flag | Effect | Default | |------|--------|---------| | `--session <id>` | Target session (slug or full ID) | `active_session_id` | | `-y` / `--yes` | Auto mode — skip confirmations | false | | `--skip-knowledge` | With `--complete`: leave candidate backlog pending | false | </context>

<v3_lifecycle_reference>

open ──complete──> completed ──archive──> archived ──unarchive──> open
  │                                             
  └──fail──> failed ──archive──> archived

Permissions: open = all mutations; completed/failed/archived = none.

• `--complete` requires: no running Run, every chain step completed/skipped with evidence, no open decision gate (escalated gates pass as recorded concerns).
• `--archive` is optional: a completed Session identity stays durable either way; archived Sessions cannot host new Runs until `--unarchive`.
• Every mutation returns a `run-response/1.2` envelope with an immutable transition receipt; never edit runtime-owned protocol JSON.

</v3_lifecycle_reference>

<execution>

Step 0: Resolve Target

1. Resolve target session from `--session` flag or `active_session_id` 2. Read `maestro session status --session {session_id} --json` — capture `status`, `orchestration_revision`, `activity_revision`, `active_run_ids` 3. Route to the selected action below; default (no action flag) → Step 1 (Inspect)

Step 1: Inspect (default)

1. Run `maestro session status --session {session_id} --json` and `maestro session resume-view --session {session_id} --json` 2. Report: status, orchestration/activity revision, active runs, open decisions (`openDecisions` from the ResumeMap), pending publications, and `nextActions` 3. Suggest the matching action: open decision gates → `maestro run decide`; active runs → let the Run loop finish; `completed` → offer `--archive`; `archived` → offer `--unarchive`; `open` with terminal chain → offer `--complete`

Step 2: Complete (`--complete`) — manual-pipeline terminal step

Note: maestro-next suggests `--complete` when 'Tests green + active session'. Orchestrated flows (Ralph/orchestrator/Companion) complete the Session themselves; use this action only when driving the pipeline manually.

**2a. Readiness check**

1. Verify status is `open` (a completed/archived Session needs no completion; `archived` requires `--unarchive` first) 2. Verify no active runs (`active_run_ids` empty; all runs sealed) 3. Verify critical gates passed (entry/exit gates from last verify/review run). If no verify/review run exists in this session, treat gate check as not applicable (pass) but emit W002 4. Verify no open decision gates (`session status` → `decisions[]`; open gates block `session complete` with `DECISION_GATE_BLOCKED`). If open gates exist → run `maestro run decide <point> --verdict proceed|fix` first 5. If not ready → display blockers, suggest next action (e.g., "run the `review` step first")

**2b. Knowledge reconciliation** (skip to 2c with `--skip-knowledge`)

1. Run `maestro knowledge review {session_id} --json`. Treat its Run ledgers, reconciliation policies, diversified matches, and candidate IDs as authoritative; do not rescan outputs to recreate candidates. Use `--refresh` only when the review reports missing or stale source receipts 2. Explain signal semantics when relevant: search/injection is exposure only; explicit loads are consumed; `cited`, `validated`, and `contradicted` are explicit Run relations 3. Report exact/semantic duplicates, related/extends candidates, potential conflicts, supersession candidates, missing receipts, and promotion eligibility separately. Exact duplicates are suppressed automatically; unresolved `review_required` candidates cannot be promoted 4. If `--skip-knowledge`, report the pending/promoting/review-required/suppressed counts and continu