maestro-session-manage

<required_reading> @~/.maestro/workflows/run-mode.md @~/.maestro/ref/knowledge-closeout.md @~/.maestro/workflows/codex-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 every required file explicitly before executing any step; for knowledge closeout, Read @~/.maestro/ref/knowledge-closeout.md explicitly before closeout. <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` | Bounded auto mode; never grants knowledge publication approval | 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 closeout** As completion owner, execute `@~/.maestro/ref/knowledge-closeout.md`: Review → Refresh → Present → Authorize → Execute → Verify. Review the exact Session with `--json`; refresh only missing/stale receipts within caller authority. Present candidate IDs/content/evidence/matches/recommendations, obtain explicit human relationship and publication decisions (or verify matching prior authorization), then execute approved adjudication/publication inline with `promote --resolve`, or use `promote --candidate` for already eligible fixed approved IDs, one at a time. Relationship-only authorization uses the deprecated `review --resolve` fallback without publication; material changes require re-presentation and re-confirmation. `-y`, machine advice, and accepted decisions are not publication approval. With `--skip-knowledge`, read the review/backlog counts, report deliberate deferral, and proceed to 2c without refresh/resolution/promotion. Zero candidates, rejection, deferral, or unresolved backlog do not block otherwise valid Session completion. Never fabricate duplicate dispositions to clear rejected/deferred items. **2c. Complete the Session** 1. Use the `orchestration_revision` captured in Step 0 (re-read if any mutation happened since) 2. When the chain is terminal (every Run sealed, every decision terminal), call the complete `maestro session complete` command from `run-mode.md`, supplying the exact `session_id`, `--actor`, `--expected-orchestration-revision`, and `--json` 3. Verify the transition receipt; never mutate Session lifecycle state or edit runtime-owned protocol JSON. The completed Session identity remains durable and may be archived/unarchived later **2d. DAG progression** 1. Read `state.json.sessions[]` — find sessions that became dep-ready (all `depends_on` sealed) 2. If dep-ready sessions exist: ``` question: "Session {slug} 已完成。推荐激活下一个 session: {next-slug}，是否确认？" options: - "激活推荐 session" - "选择其他 session" - "暂不激活" ``` 3. If confirmed → set `active_session_id` to selected session ### Step 3: Archive (`--archive`) — optional freeze 1. Verify status is `completed` or `failed` (an `open` Session must `--complete` or fail first; `archived` is already archived) 2. Call the fenced transition with the current `orchestration_revision`: `maestro session archive --session {session_id} --actor {actor_id} [--evidence <ref> ...] --expected-orchestration-revision {orchestration_revision} --json` 3. Verify the `run-response/1.2` receipt (`status: archived`, revision incremented). Archived Sessions reject all mutations (`create_run`/`advance_chain`/`transition_run`/`add_evidence`/`decide`) until `--unarchive` ### Step 4: Unarchive (`--unarchive`) — return to open 1. Verify status is `archived` 2. Call the fenced transition: `maestro session unarchive --session {session_id} --actor {actor_id} [--evidence <ref> ...] --expected-orchestration-revision {orchestration_revision} --json` 3. Verify the receipt (`status: open`). The Session accepts Runs and chain mutations again; extend it with `maestro session chain insert ...` and `maestro run next` ### Step 5: Knowledge only (`--knowledge`) Run Step 2b and the shared closeout protocol without any lifecycle mutation. Leave the Session status unchanged. If the intent is review-only, do not infer refresh/resolution/publication write authority; present or defer unless separately authorized. </execution> <completion> ``` === SESSION {ACTION RESULT} === Session: {session_id} Action: {inspect|complete|archive|unarchive|knowledge} Status: {open|completed|archived|failed} (orchestration_revision {n}) Knowledge: {promoted_count} promoted, {pending_count} pending, {review_required_count} review required, {suppressed_count} suppressed Next dep-ready: {next_slug or "none (DAG complete)" or "n/a"} --- STATUS --- Status: DONE ``` ### Next-step routing | Condition | Suggestion | |-----------|-----------| | Next session activated | route step `analyze` through `/maestro-next` or the canonical receipt-chained `session open` -> `session chain insert --command analyze --arg "<goal>"` -> `run next` flow | | Session archived, later extension needed | `maestro-session-manage --session {session_id} --unarchive` | | Knowledge candidates pending | `maestro knowledge review {session_id}` | | Knowledge health review needed | `/maestro-knowledge audit` | </completion> <error_codes> | Code | Severity | Condition | Recovery | |------|----------|-----------|----------| | E001 | error | Session not found | Check `state.json.sessions[]` / `maestro session list --json` | | E002 | error | Session already completed / archived | Nothing to do; use inspect or `--unarchive` | | E003 | error | Active runs exist | Complete or seal pending runs first | | E004 | error | Critical gates failed | Run verify/review to resolve | | E005 | error | `ORCHESTRATION_REVISION_CONFLICT` on archive/unarchive | Re-read `session status`, retry with fresh revision and new request-id | | E006 | error | Open decision gate blocks `session complete` | `maestro run decide <point> --verdict proceed\|fix` | | W001 | warning | No knowledge candidates found | Proceed | | W002 | warning | No verify/review run in session — gate check skipped | Consider running verify before completing | | W003 | warning | Candidate backlog left pending | Review later with `maestro knowledge review {session_id}` | | W004 | warning | Reconciliation review remains unresolved | Completion may continue; follow the shared closeout protocol for explicit confirmation before `promote --resolve` (deprecated `review --resolve` only for relationship-only authorization) | </error_codes> <success_criteria> - [ ] Target session resolved; status/orchestration_revision read from `session status` before any mutation - [ ] Action matched the current status (complete only from `open`; archive only from `completed`/`failed`; unarchive only from `archived`) - [ ] Knowledge candidate receipt/backlog and evidence loaded via `maestro knowledge review` (or deliberately skipped) - [ ] Reconciliation dispositions reviewed; unresolved items were explicitly retained or resolved - [ ] User reviewed candidates, or pending backlog was reported and deliberately retained - [ ] Selected knowledge promoted only through `maestro knowledge promote` - [ ] Lifecycle mutations used the fenced v3 command set (`--actor`, `--expected-orchestration-revision`, `--json`) and the transition receipt was verified - [ ] Dep-ready sessions identified and activation offered (on `--complete`) </success_criteria>