session-end

Session End Skill

Platform Note: State files (STATE.md, wave-scope.json) live in the platform's native directory: .claude/ (Claude Code), .codex/ (Codex CLI), or .cursor/ (Cursor IDE). All references to .claude/ below should use the platform's state directory. Shared metrics live in .orchestrator/metrics/. See skills/_shared/platform-tools.md.

Project-instruction file: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). All references to CLAUDE.md in this skill resolve via that precedence rule.

Phase 0: Bootstrap Gate

Read skills/_shared/bootstrap-gate.md and execute the gate check. If the gate is CLOSED, invoke skills/bootstrap/SKILL.md and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

<HARD-GATE> Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to skills/_shared/bootstrap-gate.md for the full HARD-GATE constraints. </HARD-GATE>

Phase 0.5: Parallel-Aware Preamble

Skip silently when persistence: false in Session Config.

Before Phase 1, run the parallel-aware preamble per skills/_shared/parallel-aware-preamble.md. The preamble detects other active sessions in the worktree-family via findPeers(repoRoot, { mySessionId }), classifies the caller's mode via classifyMode(callerMode) against the exclusivity-matrix, and fires the appropriate AUQ on conflict.

Outcome handling:

• PASS_THROUGH → continue to Phase 1
• EXCLUSIVE_BLOCKED → exit Phase 0 cleanly per the AUQ outcome
• PROMOTION_OFFER → user picks Worktree-Promotion (see parallel-aware-auq.md outcome-handling — calls enterWorktree()), in-place + Deviation, or Abbrechen

For session-end specifically: the preamble is DETECTION-ONLY. The lock-release path in later phases keeps its current behavior — releasing the OWN session's lock requires no matrix consultation.

Implementation reference: skills/_shared/parallel-aware-preamble.md § Implementation. AUQ reference: skills/_shared/parallel-aware-auq.md.

Phase 1: Plan Verification

Read back the session plan that was agreed at the start. For EACH planned item:

1.1 Done Items

• Verify with evidence: read the changed files, check git diff, run relevant test
• Confirm acceptance criteria are met
• Mark as completed

1.2 Partially Done Items

• Document what was completed and what remains
• Create a VCS issue for the remaining work with:
• Title: [Carryover] <original task description>
• Labels: priority:<original>, status:ready
• Description: what's done, what's left, context for next session
• Link to original issue if applicable

1.3 Not Started Items

• Document WHY (blocked? de-scoped? out of time?)
• If still relevant: ensure original issue remains status:ready
• If no longer relevant: close with comment explaining why

1.4 Emergent Work

• Tasks that were NOT in the plan but were done (fixes, discoveries)
• Document and attribute to relevant issues
• If new issues were identified: create them on the VCS platform

1.5 Discovery Scan (if enabled)

Read skills/session-end/discovery-scan.md for embedded discovery dispatch and findings triage.

1.6 Safety Review

Skip if persistence is false in Session Config (STATE.md won't exist).

Review safety metrics from the session. This is informational — it does NOT block the session close.

1. Read <state-dir>/STATE.md to extract:
2. Circuit breaker activations: agents that hit maxTurns (PARTIAL), agents that spiraled (SPIRAL), agents that failed (FAILED)
3. Worktree status: which agents used worktree isolation, any fallbacks or merge conflicts
4. Read enforcement hook logs from stderr (if captured): count of scope violations blocked/warned, command violations blocked/warned
5. Summarize:

``` Safety review:

• Agents: [X] complete, [Y] partial (hit turn limit), [Z] spiral/failed
• Enforcement: [N] scope violations, [M] command blocks
• Isolation: [K] agents in worktrees, [J] fallbacks

```

1. If any agents were SPIRAL or FAILED, ensure carryover issues exist (cross-reference with Phase 1.2)

1. Carryover validation fallback (#261): Walk each Wave History entry in STATE.md. For every agent whose status is SPIRAL or FAILED, check whether the line ends with a → issue #NNN suffix (or → existing #NNN). If the suffix is absent, the auto-create call in wave-executor did not run (e.g. a consumer-project #251 V0.x.y-close incident where the session crashed before dispatch completed, or the CLI was offline at detection time). Retroactively file the carryover via createSpiralCarryoverIssue:

```js import { createSpiralCarryoverIssue } from '${PLUGIN_ROOT}/scripts/lib/spiral-carryover.mjs';

// For each SPIRAL/FAILED agent missing the "→ issue #NNN" suffix: const result = await createSpiralCarryoverIssue({ taskDescription: '<agent task from Wave History>', kind: 'SPIRAL', // or 'FAILED' context: '<Deviations / error context from STATE.md>', priority: 'high', vcs: '<from Session Config>' }); // result.created → note new issue id in Final Report under "New Issues Created" // result.skipped === 'duplicate' → an earlier session already filed one; record the existing id // result.skipped === 'error' → log in Final Report as "⚠ carryover filing failed for <task>: <error>" and continue (do NOT block close) ```

The module is idempotent via its task-hash dedup marker, so re-running the fallback across sessions will not create duplicates.

1.7 Metrics Collection

Read skills/session-end/metrics-collection.md for JSONL schema and conditional field rules.

1.8 Session Review

Dispatch the session-reviewer agent to verify implementation quality before the quality gate:

On Codex CLI, dispatch via the session-reviewer agent role defined in .codex-plugin/agents/session-reviewer.toml.

1. Invoke subagent_type: "session-orchestrator:session-reviewer" with:
2. Scope: all files changed this session (from git diff --name-only against the base branch)
3. Context: the session plan (issues, acceptance criteria) and all wave results from STATE.md
4. Wait for the reviewer's Verdict:
5. PROCEED — continue to Phase 2
6. FIX REQUIRED — disposition each listed item by severity:

| Finding class | Disposition | |---|---| | HIGH+ / blocking review finding | Fix inline if quick (<2 min); else create an issue (priority:high, status:ready) and note it in the Final Report | | MED / LOW review finding | Fold in-session if quick; else record under "Unresolved Review Findings" in the Final Report — DO NOT create an issue (#617) | | Planned-carryover (item was in the plan, not finished) | ALWAYS create a [Carryover] issue per Phase 1.2 — unchanged | | SPIRAL / FAILED agent carryover | ALWAYS file via createSpiralCarryoverIssue per Phase 1.6 — unchanged |

1.9 Mission-Status Classification (when mission-status present in STATE.md)

Skip if persistence is false in Session Config, or if mission-status: is absent from STATE.md frontmatter. When absent, fall back to binary checkbox detection in 1.1–1.4 unchanged — full backward compat.

When STATE.md frontmatter contains a mission-status: array (set by session-plan + wave-executor per #340), use the enum values to classify items into the 1.1–1.4 buckets. Read the array via parseMissionStatus(frontmatter) from scripts/lib/state-md.mjs.

Classification mapping:

• status: completed → 1.1 Done Items (item finished; verify with evidence per 1.1)
• status: testing or status: in-dev → 1.2 Partially Done (carryover; document what remains)
• status: validated or status: brainstormed → 1.3 Not Started (carryover; check if still relevant)
• Items NOT present in the mission-status: array → fall