catlog22/maestro-session-seal

<required_reading> @~/.maestro/workflows/run-mode.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 it explicitly before executing any step.

<purpose> Complete the current Session after verifying all Runs are immutable and terminal, review the durable knowledge candidate backlog, and recommend the next dep-ready Session from the DAG.

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 flags.

Flags: | Flag | Effect | Default | |------|--------|---------| | --session <id> | Target session (slug or full ID) | active_session_id | | -y / --yes | Auto mode — skip confirmations | false | | --skip-knowledge | Leave candidate backlog pending and continue sealing | false | </context>

<execution>

Step 1: Session Readiness Check

Note: maestro-next suggests session-seal when 'Tests green + active session'. This command additionally requires verify/review gates (or W002 if absent). Both conditions should be met for clean seal.

1. Resolve target session from --session flag or active_session_id
2. Read maestro session status --session {session_id} --json — verify status is open (a completed/archived Session is terminal)
3. Verify no active runs (all runs completed or sealed)
4. 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.
5. If not ready → display blockers, suggest next action (e.g., "run the review step first")

Step 2: Knowledge Reconciliation

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 continue. The backlog and reconciliation receipts remain durable after seal.
5. Otherwise resolve review-required candidates before promotion with maestro knowledge review {session_id} --resolve <candidate-id> --as duplicate|related|conflict|supersede|unique [--target <knowledge-id>] --reason "<reason>". A target must come from that candidate's evidence-backed matches.
6. Present eligible pending candidates via request_user_input:

question: "以下知识候选项值得晋升到项目知识库吗？" options:

• "晋升全部合格项" (promote all eligible candidates)
• "逐个选择" (review each candidate)
• "暂不晋升" (leave backlog pending)

1. Promote only through the receipt-aware CLI:

• Bulk selection → maestro knowledge promote {session_id} --all
• Explicit selection → repeat maestro knowledge promote {session_id} --candidate <candidate-id> for each selection (comma-separated compatibility remains supported)
• -y may run --all, which promotes all eligible candidates (observed-only emits a warning) and skips review-required and suppressed candidates. It MUST NOT auto-resolve a candidate without explicit user selection.

1. For a replacement candidate, confirm --as supersede and then promote it; promotion creates the successor and links the evolution chain. For coexisting valid rules, confirm related or conflict as appropriate. Never direct-write a candidate that was already promoted successfully.

Step 3: Complete the Session

1. Resolve the exact Session and current orchestration_revision from the retained run-response/1.2 state.
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, --participant, --actor, --request-id, --reason, --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 unarchived later.

Step 4: 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} 已 sealed。推荐激活下一个 session: {next-slug}，是否确认？" options:

• "激活推荐 session"
• "选择其他 session"
• "暂不激活"

1. If confirmed → set active_session_id to selected session

</execution>

<completion>

=== SESSION SEALED ===
Session: {session_id}
Knowledge: {promoted_count} promoted, {pending_count} pending, {review_required_count} review required, {suppressed_count} suppressed
Next dep-ready: {next_slug or "none (DAG complete)"}
--- STATUS ---
Status: DONE

Next-step routing

| Condition | Suggestion | |-----------|-----------| | Next session activated | step analyze — open a v3 Session (maestro session open "<goal>" --id YYYYMMDD-analyze-{next-slug} --chain analyze --participant {p} --actor {a} --request-id {r} --reason "<reason>" --json → fenced maestro run next --session {session_id} ... --json), or route via /maestro-next | | 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[] | | E002 | error | Session already completed | Nothing to do | | E003 | error | Active runs exist | Complete or seal pending runs first | | E004 | error | Critical gates failed | Run verify/review to resolve | | W001 | warning | No knowledge candidates found | Proceed to seal | | W002 | warning | No verify/review run in session — gate check skipped | Consider running verify before seal | | W003 | warning | Candidate backlog left pending | Review later with maestro knowledge review {session_id} | | W004 | warning | Reconciliation review remains unresolved | Seal may continue; promotion stays blocked until maestro knowledge review --resolve | </error_codes>

<success_criteria>

• ] Target session resolved and verified as ready for completion
• ] Knowledge candidate receipt/backlog and evidence loaded via maestro knowledge review
• ] 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
• ] Session completed via maestro session complete (transition receipt verified; status completed)
• ] Dep-ready sessions identified and activation offered to user

</success_criteria>