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), .cursor/ (Cursor IDE), or .pi/ (Pi). 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. 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 0.6: Skill-Invocation Self-Report (#724, C4)

Emit an L1 skill-invocation record for session-end itself. The PreToolUse Skill-matcher hook only captures skills dispatched via the Skill tool — a prose-invoked skill like this one is invisible to it (verified gap: zero session-end rows in skill-invocations.jsonl despite many closed sessions). This self-report closes that gap so L2/L3 skill-health has a session-end selection signal. Best-effort, try/catch-silent — it never blocks the close.

try {
  const { appendSkillInvocation, DEFAULT_SKILL_INVOCATIONS_PATH } =
    await import('${PLUGIN_ROOT}/scripts/lib/skill-invocations-schema.mjs');
  const nodePath = await import('node:path');
  await appendSkillInvocation(nodePath.join(process.cwd(), DEFAULT_SKILL_INVOCATIONS_PATH), {
    timestamp: new Date().toISOString(),
    event: 'selected',
    skill: 'session-orchestrator:session-end',
    session_id: sessionId ?? null,   // from session.lock `session_id`, when available
    phase: null,
  });
} catch { /* self-report is advisory — never block the close */ }

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
• Do NOT file the carryover issue here (#769). Collect a carryover candidate instead — append it to the in-memory candidate list that the Phase 1.65 Handover Alignment Gate consumes. The issue is filed (only if the gate confirms it) in Phase 5 Step 3. Candidate record (JS keys as routeCandidates / normalizeCandidate read them — source-phase→sourcePhase, origin-issue→originIssue; see plan-verification.md § Candidate Record Format):
  • { task: '<original task description>', sourcePhase: '1.2', originIssue: <IID or null>, priority: '<original>', bucket: 'partially-done' }
• The eventual issue keeps the source-specific [Carryover] template — Title [Carryover] <original task description>, Labels priority::<original> + status:ready, Description = what's done / what's left / context for next session.
• Link to the original issue when applicable (record its IID as originIssue; a candidate with no origin issue auto-carries per the gate's routing, so nothing planned is silently forgotten).

1.3 Not Started Items

• Document WHY (blocked? de-scoped? out of time?)
• If no longer relevant: close the original issue with a comment explaining why. This is a pre-gate disposition — it files nothing and adds no candidate.
• If still relevant: do NOT touch the original issue here. Append a carryover candidate so the Phase 1.65 gate surfaces it — { task: '<item>', sourcePhase: '1.3', originIssue: <original IID>, priority: '<original>', bucket: 'not-started' }. Phase 1.3 files no NEW [Carryover] issue; the candidate's disposition IS the keep-vs-carry decision on the ORIGINAL issue. If the gate carries it → ensure the original remains status:ready; a dropped middle-band 1.3 candidate leaves the original issue unchanged and open (no auto-close in v1).

1.3a Optional /goal Backlog-Drain (opt-in — #636)

Advisory-only continuation anchor at the session-end backlog seam. Never auto-invokes /goal, never blocks the close. /goal is a user slash-command; the operator decides whether to drain now or carry over.

Gate conditions — ALL must be true for this nudge to surface:

1. goal-integration.enabled: true in Session Config (default: false).
2. session-end-backlog is listed in goal-integration.seams.

When any gate condition is false, skip this step silently — no surfaced suggestion, no STATE.md write, no AUQ.

What it does — when the gate fires AND ≥1 still-relevant Not-Started (§1.3) or Partially-Done (§1.2) item exists AND the operator would rather drain the backlog now than carry it to a future session, surface ONE suggested /goal command as an advisory bullet. Example:

/goal Drain the remaining backlog items <list>; done when each item's acceptance check passes as shown by 'npm test' output in this turn AND 'npm run typecheck' prints 0 errors in this turn, or stop after 20 turns.

Advisory-only contract: this step never auto-invokes /goal, never blocks the close, raises no AskUserQuestion, and writes nothing to STATE.md. It is informational prose only — the operator copies the command if they want it. The deterministic Phase 2 Quality Gate of session-end remains the completion authority: /goal keeps the loop alive across turns, but npm test / npm run typecheck / npm run lint and their exit codes decide whether the drained work is correct.

The /goal evaluator reads the transcript only and runs NO tools — it anchors CONTINUATION, never JUDGMENT. The suggested condition therefore references freshly-run gate output "in this turn's output" and embeds a bound ("or stop after N turns"). Cross-reference .claude/rules/loop-and-monitor.md § LM-008 for the full /goal continuation-vs-judgment contract rather than restating it here.

One goal per session: only ONE /goal can be active at a time. This backlog seam and the inter-wave fix-loop seam (wave-loop.md § /goal Continuation Anchor) cannot both hold an active goal simultaneously — the operator picks one.

1.4 Emergent Work

• Tasks that were NOT in the plan but were done (fixes, discoveries)
• Completed emergent work (finished, or already dispositioned into an issue): document and attribute to the relevant issues exactly as today — this path is NOT gated. If a completed emergent fix warrants a follow-up/doc issue, create it immediately (unchanged behavior).
• Unfinished / undispositioned emergent work (at close, neither finished nor already filed as an issue): do NOT file it here. Append a carryover candidate — { task: '<emergent item>', sourcePhase: '1.4', originIssue: <IID or null>, priority: '<assessed>', bucket: 'emergent' }. The Phase 1.65 gate decides whether it is filed; a confirmed 1.4 candidate is filed in Phase 5 Step 3 as a normal issue (NOT the [Carryover] template).

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:

   • Circuit breaker activations: agents that hit maxTurns (PARTIAL), agents that spiraled (SPIRAL), agents that failed (FAILED)
   • Worktree status: which agents used worktree isolation, any fallbacks or merge conflicts

2. Read enforcement hook logs from stderr (if captured): count of scope violations blocked/warned, command violations blocked/warned

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

4. If any agents were SPIRAL or FAILED, ensure a carryover candidate is collected for each (they auto-carry; filed via the Phase 1.65 gate → Phase 5 Step 3 — cross-reference with Phase 1.2)

5. Carryover validation fallback (#261) — collect, do NOT file yet (#769): 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). Do NOT call createSpiralCarryoverIssue here — since #769 its firing moves behind the Phase 1.65 Handover Alignment Gate so that NO [Carryover] issue is created before the gate. Instead append an auto-carry candidate (SPIRAL/FAILED is a non-deselectable auto-carry class — the gate only surfaces it in the status count, never as a deselectable option; consistent with the Critical Rule at SKILL.md:853), carrying the payload the deferred createSpiralCarryoverIssue call will need:

   // #769: collect, don't file. The actual createSpiralCarryoverIssue() call
   // fires in Phase 5 Step 3 (behind the gate). bucket 'spiral-failed' → auto-carry,
   // so it is ALWAYS carried; the operator never sees it as a triage option.
   // For each SPIRAL/FAILED agent missing the "→ issue #NNN" suffix:
   candidates.push({
     task: '<agent task from Wave History>',
     sourcePhase: '1.6',
     originIssue: null,           // SPIRAL/FAILED safety-net items carry no origin issue
     priority: 'high',
     bucket: 'spiral-failed',
     // Filing payload retained on the coordinator's original candidate object,
     // consumed in Phase 5 Step 3 (routeCandidates only classifies — it returns
     // normalized copies and does not carry this annotation):
     _spiral: { kind: 'SPIRAL' /* or 'FAILED' */, context: '<Deviations / error context from STATE.md>' },
   });
   

   The deferred Phase-5.3 call imports createSpiralCarryoverIssue from ${PLUGIN_ROOT}/scripts/lib/spiral-carryover.mjs; it is idempotent via its task-hash dedup marker, so re-running the fallback across sessions will not create duplicates.

1.6.6 Record "What Not To Retry" entries (#623)

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

For every SPIRAL or FAILED agent surfaced in the walk above, ALSO append a cross-session "What Not To Retry" entry to STATE.md. This is the durable, human-readable continuity slot that the NEXT session-start surfaces as a forced-read block (session-start Phase 6.5.1) so a future session does not re-attempt the same failed approach. Unlike a carryover issue (which captures unfinished work), this captures the approach that should not be repeated.

import { appendWhatNotToRetryOnDisk } from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';

// `parsed` = parseStateMd(STATE.md); session id from the `session:` frontmatter field.
const sessionId = parsed.frontmatter.session ?? 'unknown-session';
const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD

// For each SPIRAL/FAILED agent from the Wave History walk:
await appendWhatNotToRetryOnDisk(repoRoot, {
  approach: '<agent task description from Wave History>',
  why_failed: '<SPIRAL|FAILED> — <one-line context> (evidence: <file:line or path>)',
  session_id: sessionId,
  date: today,
});

why_failed MUST cite at least one concrete file (and line, if applicable) that grounds the failure — a bare narrative reason without a file reference is not acceptable.

The helper is lock-guarded (PSA-005) and prunes the section FIFO to the 10 most-recent entries on each append. Optional coordinator entry: if the session abandoned an approach for reasons NOT captured by a SPIRAL/FAILED agent (e.g. a design that proved unworkable mid-session), the coordinator MAY add a free-text entry through the SAME appendWhatNotToRetryOnDisk helper with a descriptive approach + why_failed. Recording is informational and does NOT block the close.

1.65 Handover Alignment Gate (#769)

Opt-in-by-default interactive gate. Reads handover-gate.enabled (default true) and handover-gate.max-open-questions (default 3) from parsed Session Config (cfg['handover-gate'], produced by scripts/lib/config.mjs → scripts/lib/config/handover-gate.mjs). Position is load-bearing: it runs AFTER Phase 1.6.6 — so all four candidate sources (1.2 Partially Done, 1.3 Not Started still-relevant, 1.4 unfinished Emergent, 1.6 SPIRAL/FAILED walk) are computed and NOTHING has been filed yet — and BEFORE Phase 1.7, so the gate's carry/drop decision feeds the Phase 1.7 carryover count. This is the ONLY place [Carryover] filing is authorized to originate; Phase 5 Step 3 merely executes the gate's carry-list.

Skill-prose-first, minimal mechanical core — same pattern as Phase 3.6.3 memory-proposals: the coordinator runs the AskUserQuestion interaction (per .claude/rules/ask-via-tool.md AUQ-003); the pure scripts/lib/handover-gate.mjs lib does only the deterministic classification. No hook, no agent, no new event schema.

Fail-open skip (FA5 — the load-bearing safety decision)

Skip the gate entirely — treat EVERY candidate as carry (byte-identical to the pre-#769 status quo), emitting a single stderr WARN — when ANY of:

• cfg['handover-gate'].enabled === false.
• session-end runs in an embedded / autopilot context OR headless claude -p (no operator at the keyboard; AskUserQuestion is unavailable per AUQ-004 — the same embedded-mode precedent as discovery suppressing its AUQ).
• AskUserQuestion is unavailable or throws at call time (wrap the calls; on error, fail-open — never surface a half-rendered gate).
• The candidate list is empty AND STATE.md ## Open Questions has no unanswered entry — Zero-Friction clean close: emit NO AUQ and continue unchanged.

Fail-open NEVER hangs the close on an unanswerable AUQ and NEVER loses data — it degrades exactly to today's silent-carryover behavior. Log e.g. ⚠ handover-gate: skipped (<reason>) — all candidates carry (status quo).

Telemetry on skip (#773): even when the gate is skipped, emit the orchestrator.handover.gated event ONCE with path: "fail_open" so this never-interactive path is still measurable (the carryover=0 blind spot #773 closed was invisible precisely because skipped closes emitted nothing). Every candidate carries, so auto_carry = candidates_total, asked = 0, dropped = 0, and the three question counts are 0:

node scripts/emit-event.mjs --type orchestrator.handover.gated --payload \
  "$(node -e "process.stdout.write(JSON.stringify({candidates_total: CT, auto_carry: CT, asked: 0, dropped: 0, questions_asked: 0, questions_answered: 0, questions_deferred: 0, path: 'fail_open'}))")"

(CT = the in-memory candidate-list length. The Zero-Friction clean-close variant — empty candidates AND no open questions — emits with all counts 0 and path: "fail_open" too, so even the quietest close leaves a breadcrumb.)

Step 1 — Assemble candidates + open questions

1. The in-memory candidate list is the union of the candidates appended by Phases 1.2 / 1.3 (still-relevant) / 1.4 (unfinished emergent) / 1.6 (SPIRAL/FAILED). Each candidate object carries { task, sourcePhase, originIssue, priority, bucket } (plus any filing payload, e.g. the SPIRAL/FAILED _spiral kind/context). See plan-verification.md § Candidate Record Format.

2. Classify via the pure helper:

   import { routeCandidates } from '${PLUGIN_ROOT}/scripts/lib/handover-gate.mjs';
   const { autoCarry, ask } = routeCandidates(candidates);
   

   autoCarry = priority::critical|high OR bucket === 'spiral-failed' OR originIssue === null — non-deselectable (dropping any of these would be real forgetting; consistent with the Critical Rule at SKILL.md:853). ask = the middle-band (priority medium/low/none WITH an origin issue, buckets not-started/emergent/partially-done) plus any malformed record. routeCandidates returns NORMALIZED copies for gate rendering; the coordinator retains its ORIGINAL candidate objects (with filing payloads) for Phase 5 Step 3.

3. Read STATE.md contents and extract the open questions via the sibling helper:

   import { readOpenQuestions } from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
   const openQuestions = readOpenQuestions(stateMdContents); // Array<{question, source, priority, answered, answer?}>
   const unanswered = openQuestions.filter((q) => !q.answered);
   

4. Zero-Friction check: if autoCarry.length === 0 && ask.length === 0 && unanswered.length === 0, skip per Fail-open above (no AUQ, no WARN needed beyond an info log — clean close).

Step 2 — AUQ Call 1 (Status-Gate)

Render ONE AskUserQuestion. The question text NAMES the candidate counts by class and the open-question count, e.g. "<A> auto-carry + <M> triage candidate(s), <U> open question(s). Close and triage now?". Options (Recommendation first, AUQ-003):

• "Closen + Triage (Recommended)" — proceed to AUQ Call 2 (triage the middle-band + answer the top open questions), then file the resulting carry-list in Phase 5 Step 3.

• "Alle carryoven (ohne Triage)" — fast-path: carry ALL candidates (autoCarry ∪ ask) with no triage; SKIP AUQ Call 2; unanswered questions stay - [ ] and roundtrip to the next session. Equivalent to the status quo for filing, minus the friction.

• "Weiterarbeiten (Close abbrechen)" — abort session-end cleanly: NO commit, NO lock-release, NO issue creation; STATE.md stays status: active; the session remains open and the coordinator continues working the open points. Before stopping, emit orchestrator.handover.gated ONCE with path: "weiterarbeiten" (#773) — the gate WAS rendered (AUQ Call 1 happened) and the operator chose to keep working, which is a distinct, previously-unmeasured outcome. Nothing is filed, so report auto_carry = autoCarry.length, asked = ask.length, dropped = 0, and all three question counts 0:

  node scripts/emit-event.mjs --type orchestrator.handover.gated --payload \
    "$(node -e "process.stdout.write(JSON.stringify({candidates_total: CT, auto_carry: AC, asked: ASK, dropped: 0, questions_asked: 0, questions_answered: 0, questions_deferred: 0, path: 'weiterarbeiten'}))")"
  

  Then print session-end aborted at Phase 1.65 by user choice (Weiterarbeiten). Session stays open. and STOP the close (do not fall through to Phase 1.7).

(Codex CLI / Cursor IDE: same three options as a numbered Markdown list.)

Step 3 — AUQ Call 2 (Triage + Open Questions) — only after "Closen + Triage"

Combine the Middle-Band triage multiSelect AND up to max-open-questions open-question single-questions, honoring AUQ-003 (≤4 questions/call, ≤4 options/multiSelect):

1. Middle-Band multiSelect — one multiSelect over the ask candidates, EVERY option preselected (= carry; one Enter keeps the sensible default). Option label: [<bucket>] <task-truncated> — <priority|—> (origin #<IID|none>). multiSelect: true. Deselected = drop.

   • Batching (Phase 3.6.3 precedent): 0 → no multiSelect; 1–4 → a single multiSelect that rides in the SAME first call alongside the open questions; 5+ → sequential Batch N of M multiSelects in FIFO batches of 4 (header: "Handover — Triage Middle-Band (Batch N of M)").

     const BATCH_SIZE = 4;
     const batches = [];
     for (let i = 0; i < ask.length; i += BATCH_SIZE) batches.push(ask.slice(i, i + BATCH_SIZE));
     

     When ask.length ≤ 4: the single triage multiSelect + up to max-open-questions open-question single-questions all ride in ONE call (1 + 3 = 4 questions max — AUQ-003-safe). When ask.length > 4: emit the open questions in the FIRST call and the middle-band as ⌈M/4⌉ dedicated Batch N of M calls.

2. Open questions — up to max-open-questions (default 3; effectively capped at 3 in the first call = the 4-question limit minus the 1 triage multiSelect) highest-priority unanswered questions, each a single-select with 2–4 options (Recommendation first). Derive options from the agent-supplied answer-candidates when present; otherwise offer Answer: <A> / Answer: <B> / Defer (keep open). Questions beyond the cap stay untouched (- [ ]) and roundtrip (FA3-Semantik).

Step 4 — Apply the gate outcome

1. carry-list = autoCarry (always) ∪ the middle-band ask items the operator LEFT SELECTED. drop-list = the middle-band ask items the operator DESELECTED. ("Alle carryoven" → carry-list = autoCarry ∪ ask, drop-list = ∅.) Store both for Phase 5 Step 3 (filing) and Phase 6 (report). NOTHING is filed in this phase.

2. Answered open questions — decide + enqueue in-memory only; do NOT mark [x] yet (#769): for each open question answered in AUQ Call 2, capture the outcome in an in-memory answeredQuestions list — one record per answered question: { question, answer, impliesWork: <bool> }. Do NOT call markOpenQuestionAnsweredOnDisk in this phase.

   The durable STATE.md - [x] write is deliberately deferred to Phase 5 Step 3 so that it lands on the SAME side of the Quality Gate (Phase 3) as the carryover-issue filing — either a completed close marks the question [x] AND files its implied work, or a Quality-Gate abort does neither. Marking [x] here (at gate time) would silently forget the answer if the Quality Gate later aborts the close: the now-[x] question no longer re-surfaces via readOpenQuestions().filter(!answered) on re-close, so any implied work would be dropped ticketless — exactly the silent-forget this feature exists to prevent.

   If the chosen answer implies NEW work (impliesWork: true), ALSO enqueue it now onto the carry-list as a carry-candidate (originIssue: null → auto-carry), carrying the answer as body context, so Phase 5 Step 3 files the issue AND marks the question [x] atomically. Pure decisions with no to-do (impliesWork: false) carry no candidate; they are recorded only by the Phase 5.3 STATE.md [x] mark + the Final Report. Unanswered / over-cap questions stay - [ ] and roundtrip to the next session (FA4).

3. The gate's carry/drop split feeds the Phase 1.7 carryover count.

Step 5 — Emit gate telemetry (#773)

After the carry/drop split is settled, emit orchestrator.handover.gated exactly once for the interactive path taken. This is the mechanical producer that makes the gate observable — before #773 the gate decided carry/drop entirely in coordinator prose, so effectiveness.carryover had no mechanical anchor and 41/41 records read carryover: 0 despite real filtering. Derive the payload from the in-memory gate state:

• candidates_total = autoCarry.length + ask.length
• auto_carry = autoCarry.length (non-deselectable)
• asked = ask.length (middle-band candidates surfaced for triage)
• dropped = drop-list length (middle-band items the operator DESELECTED; 0 on the "Alle carryoven" fast-path since AUQ Call 2 is skipped)
• questions_asked / questions_answered / questions_deferred = the open-question counts from AUQ Call 2 (surfaced / answered / left - [ ] and roundtripped). All 0 on the fast-path.
• path = "triage" (after "Closen + Triage") or "fast_path" (after "Alle carryoven ohne Triage")

node scripts/emit-event.mjs --type orchestrator.handover.gated --payload \
  "$(node -e "process.stdout.write(JSON.stringify({candidates_total: CT, auto_carry: AC, asked: ASK, dropped: DROP, questions_asked: QA, questions_answered: QAN, questions_deferred: QD, path: PATH}))")"

The questions_asked / questions_answered / questions_deferred values here are the SAME three counts recorded as the top-level open_questions_asked / open_questions_answered / open_questions_deferred session fields in Phase 1.7 (see metrics-collection.md). Emit the event with the exact scripts/emit-event.mjs --type … --payload … flag signature (NOT a positional argument — see the CLI header).

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:
   • Scope: all files changed this session (from git diff --name-only against the base branch)
   • Context: the session plan (issues, acceptance criteria) and all wave results from STATE.md
2. Wait for the reviewer's Verdict:

   • PROCEED — continue to Phase 2

   • 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)	Route as a carryover candidate per Phase 1.2 → the Phase 1.65 gate files it. Never forgotten: a no-origin/critical/high item auto-carries as a [Carryover] issue; a middle-band item with an origin issue is preselected=carry (and its origin issue stays open even if dropped).
     SPIRAL / FAILED agent carryover	Route as an auto-carry candidate per Phase 1.6 → filed via createSpiralCarryoverIssue in Phase 5 Step 3 (non-deselectable; exempt from the issue-budget cap — the [Carryover] [SPIRAL|FAILED] title and the type::carryover label bypass it, so a full budget can never swallow this filing)

Override-ratio telemetry (#730/H5): whenever one or more MED/LOW review findings are routed to "Unresolved Review Findings" (rather than fixed), additionally emit a single event capturing how many findings were absorbed rather than resolved — feeding the override_ratio metric:

node scripts/emit-event.mjs --type orchestrator.finding.overridden --payload '{"phase":"1.8","kind":"med-low-review-finding","count":N}'

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 back to binary checkbox detection per 1.1–1.4 unchanged

Backward compat: When mission-status: is absent from STATE.md (pre-#340 STATE.md files, or sessions where session-plan did not emit the block), behave exactly as before — enum classification is skipped entirely and 1.1–1.4 binary checkbox logic runs as the sole classification mechanism.

1.10 Mission Status Breakdown (when mission-status present)

Skip if mission-status: is absent from STATE.md frontmatter (backward compat — no breakdown emitted).

After classifying items in Phase 1.9, produce a Mission Status breakdown subsection as part of the closed/carryover summary output. Count the number of tasks at each enum value across ALL waves:

### Mission Status Breakdown
- completed:    <N> tasks
- testing:      <N> tasks
- in-dev:       <N> tasks
- validated:    <N> tasks
- brainstormed: <N> tasks
- Total:        <N> tasks across <W> waves

Rules:

• Count each task-id entry from the mission-status: frontmatter array by its current status value.
• completed maps to Phase 1.1 (Done). testing + in-dev map to Phase 1.2 (Partial). validated + brainstormed map to Phase 1.3 (Not Started).
• Include this block in the Phase 6 Final Report under ### Carried Over or as a standalone subsection immediately after the Completed/Carried Over/New Issues lists.
• When all tasks are completed, the breakdown still appears (confirms clean session state).

Phase 2: Quality Gate

Verification Reference: See verification-checklist.md in this skill directory for the full quality gate checklist.

Run ALL checks listed in the verification checklist. If any check fails: fix if quick (<2 min), otherwise create a priority::high issue. Do NOT commit broken code.

Phase 2.0a: Echo-Stub Detection (GH #42)

gate-full.mjs emits a top-level stubbed: {} map in its JSON result, keyed by check name (typecheck, test, lint); value is { kind: 'echo'|'noop' }. When any check was short-circuited as a stub, runCheck() already returned status: 'pass' — so the overall gate verdict is green, but the result is meaningless.

Detection: immediately after parsing the gate-full JSON result, evaluate:

const stubbedEntries = Object.entries(result.stubbed ?? {});

If stubbedEntries.length > 0, surface a HIGH WARN block in the close summary:

⚠ QUALITY GATE STUBBED — <N> command(s) are echo/noop stubs, not real checks:
  - <check-name>: <kind> stub  (configured: "<command string>")
Re-configure with a real test command in CLAUDE.md Session Config before /close,
OR document this exception in /close --reason.

Behavior by enforcement mode:

• enforcement: strict — block /close. Treat as a Phase 2 failure. Present the WARN block and exit without committing.
• enforcement: warn (default) — continue, but write quality-gate-stubbed: true to STATE.md Deviations so the metrics writer captures it.
• enforcement: off — silent. Emit a single-line stderr log only (echo-stub detected: <check-name>).

Recipe: for container-based test runners (e.g. EspoCRM PHPUnit) where an echo-stub was the historical workaround, see docs/recipes/quality-gate-container-pattern.md.

Source issue: GH #42 (root cause: a consumer-project #251 V0.15.7-close incident — silent false-positive close-verdicts from echo-stub test commands).

2.1 Vault Validation (if configured)

Read skills/session-end/vault-operations.md for validator bash contract and reporting matrix.

2.2 CLAUDE.md (or AGENTS.md) Drift Check (if configured)

Read skills/session-end/drift-operations.md for checker bash contract and reporting matrix. Complements 2.1: vault-sync validates frontmatter inside the vault tree; drift-check validates narrative claims (paths, counts, issue refs, session-file refs) in top-level repo docs.

2.3 Vault Staleness Check (if configured)

Skip this subsection if vault-staleness.enabled is not true (default: false).

Step 1 — Resolve mode

Read vault-staleness.mode from $CONFIG (default: warn). Valid values: off | warn | strict.

If mode === 'off', skip Phase 2.3 entirely.

Step 2 — Invoke staleness probes

Both probes already ship in skills/discovery/probes/. Invoke each via Node import (no shell-out):

import { runProbe as runStaleness } from '$REPO_ROOT/skills/discovery/probes/vault-staleness.mjs';
import { runProbe as runNarrative }  from '$REPO_ROOT/skills/discovery/probes/vault-narrative-staleness.mjs';

const projectStaleness = await runStaleness(projectRoot, config);
const narrativeStaleness = await runNarrative(projectRoot, config);

Each probe returns { findings: Array, metrics: Object, duration_ms: Number } and auto-appends a JSONL summary record to its respective metrics file.

Step 3 — Aggregate and route by mode

totalFindings = projectStaleness.findings.length + narrativeStaleness.findings.length

• mode === 'warn' (default): report findings to closing report Docs Health line. Never block close.
• mode === 'strict':
  • If totalFindings === 0: continue, log Vault staleness: clean (mode=strict).
  • If totalFindings > 0: do NOT block the close. Present the findings list and surface an AskUserQuestion whose Recommended default is warn + carryover + continue:
    • On Claude Code: AskUserQuestion with options:
      1. "Warn + carryover and close (Recommended)" — file a carryover issue (labels carryover, priority::high) titled [Carryover] Vault staleness (strict) — <count> findings documenting the stale projects/narratives for a follow-up session, log a Deviation entry in STATE.md ## Deviations, then continue the close: - [<ISO timestamp>] Phase 2.3: Vault staleness strict-mode findings carried over. Findings: <count> (projects: <N>, narratives: <M>) → issue #<IID>.
      2. "Override and close" — proceed without a carryover issue, log a Deviation entry in STATE.md ## Deviations: - [<ISO timestamp>] Phase 2.3: Vault staleness strict-mode findings overridden by user. Findings: <count> (projects: <N>, narratives: <M>). In addition to the Deviation entry, emit an override-ratio event so the override feeds the override_ratio metric (#730/H5): node scripts/emit-event.mjs --type orchestrator.finding.overridden --payload '{"phase":"2.3","kind":"vault-staleness-strict","count":N}'.
    • On Codex CLI / Cursor IDE: same options as numbered Markdown list.

Step 4 — Surface to closing report

Pass the aggregated counts and mode forward to Phase 6 Final Report (Docs Health line — see Phase 6 below).

Phase 2.5: Custom Phases (#637)

Opt-in. Skip this phase entirely if custom-phases in $CONFIG is absent or [] (the default).

Repos declare deterministic close/housekeeping phases as a contract (not the freeform special: convention): each phase runs a command with exit-code gating and Final-Report reporting. The block is parsed by scripts/lib/config/custom-phases.mjs; each record is { name, when, command, mode, review } (already validated — unsafe records were dropped at parse time).

Step 1 — Read + filter by when

Read custom-phases from $CONFIG and the session-type from STATE.md frontmatter (feature | deep | housekeeping | none):

• If session-type === 'housekeeping': keep phases with when ∈ {housekeeping, both}.
• Otherwise (feature/deep/any other): keep phases with when ∈ {session-end, both}.

If no phases remain after filtering, skip to Phase 3.

Step 2 — Run each phase in declaration order

For each kept phase:

• mode === 'off' ⇒ skip silently (do not run the command).
• Otherwise run command via Bash. Capture the exit code and the last ~10 lines of stdout (these become the report summary — do NOT inline the full output).
• If review is set, read that file after the command as the review step and note its path in the report.

Step 3 — Route by mode

• mode === 'warn' (default): record the result (name, exit code, summary) for the Phase 6 Final Report "Custom Phases" line. Never block the close — even on a non-zero exit.
• mode === 'hard':
  • exit code 0 ⇒ continue; record <name>: pass (mode=hard).
  • exit code ≠ 0 ⇒ BLOCK the close using the same routing pattern as Phase 2.3 strict-mode. mode: hard here is an operator-declared repo contract (the repo deliberately chose mode: hard), so the block semantics are preserved — but the AUQ now ALSO offers a warn + carryover escape hatch. Present the phase name + captured summary and offer:
    • On Claude Code: AskUserQuestion with options:
      1. "Fix and retry Phase 2.5" (Recommended) — exit close, let the user investigate.
      2. "Warn + carryover and close" — file a carryover issue (labels carryover, priority::high) titled [Carryover] custom-phase '<name>' (mode=hard) exited <code> capturing the phase name + captured summary for a follow-up session, log the Deviation entry, then continue the close.
      3. "Override and close" — proceed, log a Deviation entry in STATE.md ## Deviations: - [<ISO timestamp>] Phase 2.5: custom-phase '<name>' (mode=hard) exited <code>, overridden by user. In addition to the Deviation entry, emit an override-ratio event so the override feeds the override_ratio metric (#730/H5): node scripts/emit-event.mjs --type orchestrator.finding.overridden --payload '{"phase":"2.5","kind":"custom-phase-hard","count":N}'.
      4. "Abort close" — exit close without writing.
    • On Codex CLI / Cursor IDE: same options as a numbered Markdown list.

A hard-fail (whether overridden or not) ALWAYS appends its result line to STATE.md ## Deviations; warn-mode results do not.

Step 4 — Surface to closing report

Pass each phase result (name, mode, exitCode, summary, review?) forward to the Phase 6 Final Report "Custom Phases" line (see Phase 6 below).

Phase 2.6: Broken-Window Budget (#730/H5)

Opt-in via broken-window-budget.enabled in Session Config (default false). Skip silently when disabled.

Assemble the in-memory "knowingly-broken shipment" list from THIS session's already-computed results — no new detection logic, only aggregation:

1. Phase 2.0a stub findings (result.stubbed) that shipped anyway under enforcement: warn.
2. Phase 2.3 / 2.5 "Override and close" choices (reuse each entry's Deviation-log payload verbatim).
3. Phase 1.8 MED/LOW findings routed to "Unresolved Review Findings" (#617).
4. Wave-level reviewer findings overridden without a fix task (## Deviations entries matching reviewer finding overridden — written by wave-executor §5/5a).

For EACH item: file a hard-terminated closure issue via createBrokenWindowIssue() from scripts/lib/spiral-carryover.mjs — labels broken-window + priority::high, due-date = today + broken-window-budget.due-days (default 7; glab native --due-date, gh fallback: Due: <date> as first body line — GitHub has no native due-date field). Idempotent per task-hash — re-running a close never duplicates issues.

Emit ONE event per filed issue (note: event-name segments use underscores, never hyphens):

node scripts/emit-event.mjs --type orchestrator.broken_window.filed --payload \
  "$(node -e "process.stdout.write(JSON.stringify({source:'<2.0a|2.3|2.5|1.8|wave-override>', issue:<IID>, due:'<YYYY-MM-DD>'}))")"

Non-blocking: a filing failure is a WARN, never blocks the close (same fail-open discipline as createSpiralCarryoverIssue).

Phase 3: Documentation Updates

Final heartbeat (#590-3) — at Phase 3 entry, refresh the session-lock heartbeat BEFORE the multi-minute close-out chain (vault-mirror, dialectic, durable-commit, metrics). A long-idle deep session may not have had PostToolBatch activity for >4h; without a refresh the 4h-TTL lock would lapse mid-close and appear stale to a concurrent session. Place this call BEFORE Phase 3.8 Session Lock Release (which deletes the lock — refreshing a deleted lock is a no-op). Best-effort: a failure must NOT block the close.

// Final heartbeat (#590-3) — refresh before the multi-minute close-out (vault-mirror, dialectic, durable-commit)
// so a long-idle deep session's 4h-TTL lock does not lapse mid-close.
// BEFORE Phase 3.8 lock-release (which deletes the lock).
import { updateHeartbeat } from 'scripts/lib/session-lock.mjs';
updateHeartbeat({ sessionId, repoRoot: process.cwd() });

Skip silently if persistence: false in Session Config (no session.lock exists in that mode).

3.0 Defensive Cleanup

Delete <state-dir>/wave-scope.json if it still exists:

rm -f <state-dir>/wave-scope.json

This should have been cleaned up by wave-executor after the final wave, but crashed sessions or interrupted executions may leave it behind. A stale scope manifest from a previous session could incorrectly restrict the next session's enforcement hooks.

3.1 SSOT Files

• Update STATUS.md / STATE.md if they exist (metrics, dates, status)
• Update CLAUDE.md (or AGENTS.md on Codex CLI) if patterns or conventions changed during this session
• Check <state-dir>/rules/ — if a new pattern was established, suggest a new rule file

3.2 Docs Verification (docs-orchestrator integration)

Skip this subsection if docs-orchestrator.enabled config is not true (default: false). Also skip entirely if docs-orchestrator.mode is off.

Reads docs-tasks from STATE.md frontmatter (written by wave-executor Pre-Wave 1b), computes CHANGED_FILES via git diff --name-only "$SESSION_START_REF..HEAD", and runs a per-task verification loop (outcome: ok/partial/gap). In warn mode logs results non-blocking; in strict mode blocks on any gap and presents an AskUserQuestion override prompt. Emits a ### Documentation Coverage (docs-orchestrator) block for inclusion in the Phase 6 Final Report.

See phase-3-2-docs-verification.md for full details.

3.2a Session Handover (for significant sessions)

If this session made substantial changes, create or update:

• <state-dir>/session-handover/ doc with: tasks completed, resume point, metrics changed, issues opened/closed
• Or update <state-dir>/STATE.md with session digest

3.3 Claude Rules Freshness

Review <state-dir>/rules/ files that are relevant to this session's work:

• Are the rules still accurate after this session's changes?
• Should any rule be updated with new patterns?
• Should a new path-scoped rule be created?
• Suggest changes but DO NOT modify without user confirmation

3.4 Update STATE.md

Ownership Reference: See skills/_shared/state-ownership.md. session-end is authorized to set status: completed plus the optional updated timestamp (#184), and — as of Phase A of Epic #271 — the 5 Recommendation fields written by Phase 3.7a. No other fields.

Runtime Ordering Note (Epic #271 Phase A): Phase 3.4's status: completed write executes LAST in Phase 3, AFTER Phase 3.7 (sessions.jsonl) and Phase 3.7a (Compute and Write Recommendations). The ordinal position here (3.4) is kept for historical compatibility; the canonical runtime order is 3.1 → 3.2 → 3.3 → 3.4a → 3.5 → 3.5a → 3.6 → 3.6.3 → 3.6.4 → 3.6.5 → 3.6.6 → 3.6.7 → 3.6.8 → 3.7 → 3.45 → 3.7a → 3.7b → 3.7c → 3.7d → 3.4 (3.6.3/3.6.4/3.6.6 were missing from this note pre-#724; the Tail-Diät skip-plan dispatcher now dispatches the full six-phase tail mechanically, so the note is corrected to list all six). Rationale: Phase 3.7a reads in-memory session metrics and writes the 5 Recommendation fields via updateFrontmatterFields; that write must complete BEFORE the STATE.md frontmatter is finalized with status: completed so the Recommendation fields are visible to the next session-start while STATE.md is still status: active. Crash-resilience: if /close aborts between 3.7a and 3.4, STATE.md carries status: active + Recommendations; session-start Phase 1.5 offers resume (and the banner renders). If the reverse ordering were used (status: completed first), a crash would leave status: completed without Recommendations — the Reader would silently no-op the banner, losing the handoff. Phase 3.45 (Telemetry Flush, #844) sits AFTER Phase 3.7 because it drains the send-queue with the just-written sessions.jsonl record already included, and BEFORE Phase 3.7a because it is a fire-and-forget side-effect with no dependency on the Recommendation-write ordering below it. Phase 3.7d (Session-Eval, #803) sits AFTER Phase 3.7 because it scores the sessions.jsonl record that phase just wrote — the record must exist first — and BEFORE Phase 3.4 because its eval.jsonl output is advisory and must never block the close.

Gate: Only run if persistence is enabled in Session Config and <state-dir>/STATE.md exists.

1. Set frontmatter status: completed
2. Record final wave count and completion time in the frontmatter
3. Touch updated: <ISO 8601 UTC> in the frontmatter (issue #184). Use scripts/lib/state-md.mjs → touchUpdatedField for safety:

   node --input-type=module -e "
   import {readFileSync, writeFileSync} from 'node:fs';
   import {touchUpdatedField} from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
   const p = '<state-dir>/STATE.md';
   writeFileSync(p, touchUpdatedField(readFileSync(p, 'utf8'), new Date().toISOString()));
   "
   

   Silent no-op if the file has no frontmatter.
4. Keep the file as a record — do NOT delete it (next session-start reads it)

If STATE.md doesn't exist, skip this subsection.

3.4a Coordinator Snapshot Cleanup (#196)

Pre-dispatch snapshots (refs/so-snapshots/<sessionId>/wave-*) are created by wave-executor before each wave dispatch so that session-start can offer recovery if a session is interrupted mid-wave. On a clean close those snapshots are no longer needed and should be deleted. In addition, orphaned refs from older sessions that were never cleaned up (e.g. after a hard crash) are garbage-collected using an age-based policy (14 days).

Gate: Only run if persistence is true in Session Config. Skip entirely when persistence is off (snapshots are never written in that mode).

node --input-type=module -e "
import { listSnapshots, deleteSnapshot, gcSnapshots } from '${PLUGIN_ROOT}/scripts/lib/coordinator-snapshot.mjs';

// Step A: delete this session's snapshots (clean close → we don't need them)
const mine = await listSnapshots({ sessionId: '${SESSION_ID}' });
for (const s of mine) {
  const r = await deleteSnapshot({ refName: s.ref });
  if (!r.ok) console.error('snapshot cleanup:', r.error);
}

// Step B: GC orphans older than 14 days (non-fatal)
const gc = await gcSnapshots({ olderThanDays: 14 });
console.log(\`snapshot cleanup: deleted \${mine.length} from this session + \${gc.deletedCount} expired orphans (scanned \${gc.scanned}).\`);
"

Failures in either step are logged to stderr but do not block session close — a missed cleanup is self-healing via the 14-day GC on the next session.

This cleanup is the counterpart to the session-start Phase 1.5 recovery prompt: once a session closes cleanly, future sessions must not be offered recovery for its snapshots.

3.45: Telemetry Flush (advisory, #844)

Skip silently when persistence: false in Session Config. There is no dedicated config key for this phase — the send-gate is resolveConsent() inside sync.mjs itself (fail-closed: a disabled / no-consent / headless posture makes flush() a no-op in <5ms, sending nothing). This phase runs late in the close, after Phase 3.7 has written sessions.jsonl, so any session-summary event enqueued at metrics-write time is included in the drain; the ordinal position 3.45 is kept for readability (mirrors the Phase 3.4 Runtime Ordering Note idiom of ordinal ≠ runtime order).

Drain the host-local telemetry send-queue once, fire-and-forget. The flush is advisory — the close must never fail, stall, or surface an error because of telemetry:

import { flush } from '${PLUGIN_ROOT}/scripts/lib/telemetry/sync.mjs';

// Fire-and-forget. flush() is contractually never-throw + internally gated (resolveConsent)
// + 3s-timeout-bounded; the try/catch is defense-in-depth, never a real failure path.
try { await flush(); } catch { /* nie blockierend — der Close darf durch Telemetrie nie scheitern */ }

Semantics. flush() is fire-and-forget with an internal ~3s timeout. When the ingest endpoint is unreachable (offline), events stay in the bounded host-local queue (oldest-dropped on overflow) and are retried on a later close — nothing is lost or blocked. A one-line result MAY be surfaced in the Phase 6 close summary (Telemetry: sent / queued / gated), but a failure NEVER renders an error banner: under no circumstances may telemetry make /close fail or take materially longer than ~3s. The gate lives in the module (fail-closed via resolveConsent), so this phase carries no config-key check of its own beyond the persistence: false skip above.

Cross-reference: GitLab #844 (Epic #841); docs/prd/2026-07-20-anonymous-usage-telemetry.md FA3; docs/telemetry.md; flush API in scripts/lib/telemetry/sync.mjs (flush — fire-and-forget, gated, never-throw).

3.5 Session Memory

Gate: Only run if persistence is enabled in Session Config AND platform is Claude Code (session memory at ~/.claude/projects/ is Claude Code-only). Learnings (Phase 3.5a) and metrics (Phase 3.7) still write to .orchestrator/metrics/ on all platforms.

1. Create ~/.claude/projects/<project>/memory/session-<YYYY-MM-DD>.md with:
   • Frontmatter: name, description (1-line summary), type: project
   • ## Outcomes — per-issue status (completed / partial / not started) with evidence
   • ## Learnings — patterns discovered, architectural insights, gotchas
   • ## Next Session — priority recommendations, suggested session type, blockers
2. Update ~/.claude/projects/<project>/memory/MEMORY.md:
   • Under a ## Sessions heading (create if missing), add: - [Session <date>](session-<date>.md) — <one-line summary>

3.5a Learning Extraction + 3.6 Memory Cleanup & Learnings Write

Read skills/session-end/learning-patterns.md for extraction heuristics, confidence updates, passive decay, and JSONL write procedure.

Phase 3.6.x Tail — Mechanical Skip-Plan (#724)

The Phase 3.6.x tail (3.6.3 Memory-Proposals, 3.6.4 Expired-Sweep, 3.6.5 Auto-Dream, 3.6.6 Skill-Judge, 3.6.7 Auto-Dialectic, 3.6.8 Reconcile) is the historical close-out abort-attractor: six phases that in the overwhelming majority of sessions do nothing (no proposals queued, nothing expired, under cadence, judge off, reconcile off). Each already ships a mechanical fast-path in its own lib. This dispatcher computes — side-effect-free — WHICH of the six actually need to run, so you load ONLY the detail procedure for the run: true phases and emit a one-line skip report for the rest.

Run the aggregator ONCE. Config gates short-circuit FIRST (no disk touch); the input-detection helpers run only when the config gate passed. It NEVER throws — a per-phase probe error fail-opens to run: true (run the phase rather than silently lose it):

import { planTailPhases } from '${PLUGIN_ROOT}/scripts/lib/session-end/phase-skip.mjs';

const { plan, skippedReport } = await planTailPhases({
  repoRoot: process.cwd(),
  config,        // parsed Session Config (from $CONFIG)
  sessionId,     // session.lock `session_id` / STATE.md `session:` field (or null)
  platform,      // 'claude' | 'codex' | 'cursor'
});
// plan: Array<{ phase, run, reason, inputSource }>, already in ascending phase order.

Then:

1. For every entry with run: true — load its detail procedure from phase-3-6-tail.md (the phase headings there match the phase id) and execute it exactly as written. The aggregator only DECIDES; the sub-file holds the full unabridged procedure.
2. For every entry with run: false — do nothing for that phase; its reason is already captured for the report.
3. Execute run: true phases in ascending phase order (3.6.3 → 3.6.4 → 3.6.5 → 3.6.6 → 3.6.7 → 3.6.8), matching the Phase 3.4 Runtime Ordering Note. The returned plan is already in that order.
4. Emit skippedReport as a single line in the Phase 6 Final Report (under the Learnings/metrics block), e.g. Tail-Diät: 3.6.3 skipped (proposals empty) · 3.6.5 skipped (under-threshold) · 3.6.7 RUN (2 new sessions) · ….

Full detail procedures: phase-3-6-tail.md.

3.7 Write Session Metrics

Read skills/session-end/session-metrics-write.md for JSONL append, vault-mirror invocation, and behavior matrix.

Token Rollup (#644): Before emitting the JSONL record (step 2 of session-metrics-write.md), step 1a calls rollupSessionTokens({ parentSessionId }) from scripts/lib/session-token-rollup.mjs and merges three optional fields onto the in-memory record: total_token_input, total_token_output, and subagents_with_tokens (coverage count). Null totals mean "no token data captured" — not zero cost. The rollup is non-blocking: a missing subagents.jsonl or all-null session still writes cleanly with null/0 values.

3.7a Compute and Write Recommendations (Epic #271 Phase A)

Gate: Only run if persistence is true in Session Config AND <state-dir>/STATE.md exists. Skip silently otherwise.

Ownership Reference: See skills/_shared/state-ownership.md. session-end is the ONLY writer of the 5 Recommendation fields (recommended-mode, top-priorities, carryover-ratio, completion-rate, rationale). No other skill may write these keys.

Ordering: Runs AFTER Phase 3.7 (sessions.jsonl is just-written — reads in-memory session metrics, NOT JSONL) and BEFORE Phase 3.4 status: completed setting. See the Phase 3.4 Runtime Ordering Note for rationale.

Calls computeV0Recommendation({completionRate, carryoverRatio, carryoverIssues}) from in-memory session metrics and writes 5 fields to STATE.md frontmatter via updateFrontmatterFields. Inputs MUST come from in-memory metrics, NOT re-read from sessions.jsonl. On any exception writes recommendation-compute-failed to sweep.log and does NOT block Phase 3.4.

See phase-3-7a-recommendations.md for full details.

3.7b Durable-Commit Session Telemetry (#490 AC2)

Gate: Always runs when persistence is enabled. Local execution is a no-op (enabled: false).

Ordering: Runs AFTER Phase 3.7a (Recommendations written to STATE.md) and BEFORE Phase 3.4 (status: completed). See the Phase 3.4 Runtime Ordering Note canonical order.

Wraps the already-completed Phase 3.7 + 3.7a writes with withDurableCommit (from scripts/lib/autopilot/durable-telemetry.mjs) for the two session-end-owned files: .orchestrator/metrics/sessions.jsonl and <state-dir>/STATE.md. enabled: false keeps local closes a no-op ({ok: true, skipped: true}); the flag flips true only in cloud Routines execution so telemetry survives ephemeral-clone reclamation. autopilot.jsonl is NOT in scope here — scripts/lib/autopilot/loop.mjs owns its commit (#490 Wave-2).

See phase-3-7a-recommendations.md § Phase 3.7b for the full withDurableCommit invocation.

Phase 3.7c: Vault Board → Closed (#674)

Gate: Skip silently when vault-integration.enabled is not true in Session Config (the underlying helper also self-no-ops, so this is defense-in-depth, not the sole gate).

Ordering: Runs AFTER Phase 3.7b (durable-commit) and BEFORE Phase 3.7d (Session-Eval, #803), Phase 3.4 (status: completed) and Phase 3.8 (Session Lock Release). See the Phase 3.4 Runtime Ordering Note canonical order. Running before lock-release is deliberate — the session-lock lease still exists when the board is finalized, so the board's in-progress → closed transition is derived against a live lock rather than a phantom one. This mirrors the #490 durableCommit ordering discipline: persist/finalize the cross-repo status while the lease is still held, then release.

Transition THIS repo's live-status board row to closed so a cross-repo observer sees the session has ended. Invoke mirrorBoard from scripts/lib/vault-status/board-writer.mjs with an explicit closed status for the current repo:

import { mirrorBoard } from 'scripts/lib/vault-status/board-writer.mjs';

const boardResult = await mirrorBoard({
  repoRoot: process.cwd(),
  explicitStatus: 'closed',        // force THIS repo's row to `closed`
});
// boardResult.action ∈ { 'written', 'skipped-noop', 'skipped-handwritten', 'skipped-vault-disabled', 'dry-run' }

Note (single-repo close path): with repos omitted, mirrorBoard builds the repo descriptor itself as [{ repoRoot, status: explicitStatus }] — this is the supported single-repo shape, so explicitStatus: 'closed' lands on THIS repo's row. (When a caller DOES pass repos, each element must be a { repoRoot, repoName?, status? } object, NOT a bare path string — bare strings are silently skipped by collectRows.) The board at <vault-dir>/01-projects/_active-sessions.md is generator-owned: mirrorBoard refuses to touch any file lacking the session-orchestrator-active-sessions@1 marker, hard-refuses _overview.md, and is idempotent (a re-run after the row is already closed returns skipped-noop). Rows for repos NOT in this update are preserved verbatim by the idempotent merge.

Non-blocking: a mirrorBoard failure (any non-written/skipped-* outcome, thrown error, or unreachable vault) MUST NOT block the close. Log a single WARNING: vault board → closed failed — <reason>; continuing close line and proceed to Phase 3.4 / 3.8. The board is an observability convenience, not a close-out invariant.

Phase 3.7d: Session-Eval (opt-in — #803)

Gate: Run ONLY when Session Config has eval.enabled: true AND eval.mode is not off (the eval: block is parsed by scripts/lib/config/eval.mjs; defaults are enabled:false / mode:warn / judge:off / report:html / handle:null). With no eval: block at all, skip silently — zero overhead and byte-identical close behaviour to a repo that never adopted eval (FA6 Gherkin 2).

Ordering: Runs AFTER Phase 3.7 (sessions.jsonl) and Phase 3.7c (vault board) and BEFORE Phase 3.4 (status: completed) and Phase 4 (commit). The position AFTER Phase 3.7 is load-bearing: the eval scores the session record that Phase 3.7 just appended to sessions.jsonl, so that record MUST already exist. The position BEFORE Phase 3.4 keeps the resulting eval.jsonl record inside the same session commit — but the record is purely advisory, so a failure here NEVER blocks the close. See the Phase 3.4 Runtime Ordering Note canonical order.

Evaluate the just-closed session deterministically and, when configured, with an advisory LLM judge. This phase is a thin hook — the full evaluation flow lives in skills/eval/SKILL.md; only the close-out integration is described here.

1. Deterministic run. Invoke node scripts/eval-session.mjs --json — with no --session, the cascade (resolveSession, revised #822) walks records newest-to-oldest (source order) and evaluates the first one that is either status:'completed' or non-abandoned with evidence of completed work (typically the record Phase 3.7 just appended). Model capture: the coordinator passes --model-id <id> --model-source self-report; the $ANTHROPIC_MODEL env var wins automatically when set. Pass the configured pseudonym through with --handle <eval.handle> (omit when null). The CLI appends the eval record to .orchestrator/metrics/eval.jsonl (appendEvalRecord is never-throw).
2. Advisory judge (opt-in). When eval.judge is not off, run the judge flow per skills/eval/SKILL.md § Phase 3: the coordinator dispatches the read-only eval-judge agent (DI'd dispatch, untrusted-data nonce fence), merges the advisory judge dimensions (method: "judge", advisory: true, calibration_status: "uncalibrated") into the record, and appends the merged record. When eval.judge: off, no agent is dispatched and no judge dimensions are produced.
3. HTML report (opt-in). When eval.report: html (the default), call writeEvalReport(record, …) from scripts/lib/eval/report.mjs to emit the self-contained run report under .orchestrator/eval/reports/<run-id>.html (gitignored, regenerable from the record). When eval.report: none, skip the report.

Advisory — never blocks the close (FA6): an eval failure — a non-zero eval-session.mjs exit, a judge-dispatch error, or a report-write error — MUST NOT abort /close. Under mode: warn, log a single WARNING: session-eval failed — <reason>; continuing close line to stderr and proceed to Phase 3.8 / Phase 4. There is NO exit-code gate on this phase. See skills/eval/SKILL.md for the full deterministic-engine + judge + report detail flow.

Phase 3.8: Session Lock Release (#330)

Gate: Only run if persistence is true in Session Config. Skip silently otherwise.

After STATE.md is finalized with status: completed (Phase 3.4) and Recommendations are written (Phase 3.7a), release the distributed session-lock so the next session can acquire it cleanly:

import { release } from 'scripts/lib/session-lock.mjs';
// sessionId = the session identifier established by session-start Phase 1.2 acquire()
//   and stored in .orchestrator/session.lock (session_id field); matches the
//   STATE.md frontmatter `session:` field written during Pre-Wave 1b initialization.
const result = release({ sessionId, repoRoot: process.cwd() });
// result.ok is always true unless a filesystem error occurred.
// result.deleted === true  → lock file removed successfully.
// result.deleted === false → lock was absent or belonged to a different session_id (silent-OK).

If result.deleted === false, log info: session-lock not released — already absent or session_id mismatch (no action needed) and continue. This is a non-error state.

If result.ok === false (rare filesystem error), log ⚠ session-lock: release failed — <result.reason> and continue. Do NOT block the close for a lock-release failure — the TTL provides automatic expiry for the next session.

The lock is released here — AFTER all STATE.md writes are complete and BEFORE the commit is staged in Phase 4.1. This ordering ensures a clean handover: the lock file is absent from the working tree when the commit is assembled, so it is not accidentally staged.

Phase 4: Commit & Push

4.1 Stage Changes

• Stage files individually: git add <file> — NEVER git add . or git add -A
• Always stage these session artifacts (if modified):
  • .orchestrator/metrics/sessions.jsonl (session summary from Phase 3.7)
  • .orchestrator/metrics/learnings.jsonl (learnings from Phase 3.6)
  • .orchestrator/metrics/eval.jsonl (eval record from Phase 3.7d, if modified — note: in repos where metrics are gitignored this is a no-op)
  • <state-dir>/STATE.md (session state, if persistence enabled)
  • Any files created or modified by wave agents
• Review staged changes: git diff --cached — verify every change is from THIS session
• If you see changes you did NOT make, ask the user (parallel session awareness)

4.2 Commit

Use Conventional Commits format:

type(scope): description

- [bullet points of what changed]
- Closes #IID1, #IID2 (if applicable)

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

For sessions with many changes, prefer ONE commit per logical unit (not one mega-commit).

4.3 Push

git push origin HEAD

4.4 GitHub Mirror (if configured in Session Config)

# Only attempt if 'mirror: github' is in Session Config AND remote exists
git remote get-url github 2>/dev/null && git push github HEAD 2>/dev/null || echo "GitHub mirror: not configured"

Phase 4a: Auto-Promoted Worktree Cleanup (#575 P3.2)

Skip if persistence: false in Session Config. Skip silently if the current worktree is NOT an Auto-promoted sibling (the common case).

After Phase 4 commit+push has durably persisted sessions.jsonl + STATE.md to origin, check whether the current session ran in an Auto-promoted sibling worktree (created via the P3.1 PROMOTION_OFFER path). If yes, apply Hybrid Cleanup-Pattern: clean → auto-remove, dirty → AUQ.

Ordering rationale (#490 durableCommit dependency): Phase 4a runs AFTER Phase 4 commit+push, NOT before. Removing the promoted worktree before commit+push would lose the worktree's STATE.md before Phase 3.4 metrics writes (sessions.jsonl) are committed, violating the #490 durableCommit ordering invariant. Once Phase 4 has pushed all metrics + STATE.md to origin, the promoted worktree can be safely removed without data loss.

Detection: is the current worktree an Auto-promoted sibling?

Auto-promoted sibling worktrees are created by enterWorktree() during the Phase 0.5 PROMOTION_OFFER path. Their path layout is <basePath>/<repo-name>-<sessionId>/. Detection uses parseSessionId() from scripts/lib/session-id.mjs (#572) — never custom regex.

Authoritative impl: scripts/lib/session-end/worktree-cleanup.mjs — detectAutoPromotedWorktree(repoRoot, sessionId, opts). Import and call; do NOT re-implement from this doc.

Algorithm: parse sessionId via parseSessionId(); return null immediately for UUID-format sessions (never auto-promoted). Derive the MAIN checkout root from the first worktree entry of git worktree list --porcelain (NOT path.basename(repoRoot) — the promoted worktree's basename IS the comparison target). If repoRoot resolves to the main checkout, return null. Otherwise compare path.basename(repoRoot) against <main-repo-name>-<sessionId>; on match return { wtPath, sessionId, branch }, else null. All git invocation is via the injection-safe opts.execFileFn (default execFileSync with an args array — #577 HARDEN-001).

Clean-check

A worktree is clean iff ALL three conditions hold:

1. No uncommitted changes: git status --porcelain is empty
2. No untracked files: implicit in #1 (porcelain includes ?? entries)
3. No unpushed commits: git status --short --branch does NOT contain ahead indicator

Authoritative impl: scripts/lib/session-end/worktree-cleanup.mjs — isWorktreeClean(wtPath, opts). Import and call; do NOT re-implement from this doc.

Algorithm: run git status --porcelain; if non-empty → dirty (false). Else run git status --short --branch; if it matches /\bahead\b/ → unpushed (false). Otherwise true. On ANY git error → false (conservative PSA-003 default: never auto-remove a worktree we could not verify). Git invocation is via the injection-safe opts.execFileFn (default execFileSync with an args array — #577 HARDEN-001).

Clean path: auto-remove + WARN (PRD §3 P3 Gherkin row 2)

When detection returns a worktree object AND isWorktreeClean() returns true, auto-remove via git worktree remove (NO --force) and log a WARN line. The main checkout's git dir (repoMainRoot) is derived via the first entry of git worktree list --porcelain.

Authoritative impl: import detectAutoPromotedWorktree + isWorktreeClean from scripts/lib/session-end/worktree-cleanup.mjs. All git invocation MUST go through the injection-safe arg-array form (execFileSync('git', ['-C', dir, …]), #577 HARDEN-001) — never the legacy execSync(\git -C ${var} …`)` template-literal shell form.

import { execFileSync } from 'node:child_process';
import { detectAutoPromotedWorktree, isWorktreeClean } from '${PLUGIN_ROOT}/scripts/lib/session-end/worktree-cleanup.mjs';

const promoted = detectAutoPromotedWorktree(process.cwd(), sessionId);
if (!promoted) {
  // Not auto-promoted — skip Phase 4a entirely. Continue to Phase 5.
} else {
  // Derive main checkout root from first worktree-list entry (arg-array, no shell)
  const wtList = execFileSync('git', ['-C', promoted.wtPath, 'worktree', 'list', '--porcelain'], { encoding: 'utf8' });
  const mainLine = wtList.split('\n').find((l) => l.startsWith('worktree '));
  const repoMainRoot = mainLine ? mainLine.slice('worktree '.length).trim() : null;

  if (isWorktreeClean(promoted.wtPath)) {
    // Clean path: PRD §3 P3 Gherkin row 2 — auto-remove
    console.warn(`session-end Phase 4a: auto-promoted worktree ${promoted.wtPath} is clean — removing via 'git worktree remove'`);
    execFileSync('git', ['-C', repoMainRoot, 'worktree', 'remove', promoted.wtPath], { encoding: 'utf8' });
  } else {
    // Dirty path: PRD §3 P3 Gherkin row 3 — AUQ before any destructive action
    // [AUQ block — see Dirty path subsection below]
  }
}

Dirty path: AUQ before destructive action (PRD §3 P3 Gherkin row 3)

When the worktree is dirty (uncommitted, untracked, OR unpushed), render this AUQ via the coordinator's AskUserQuestion tool. The AUQ is coordinator-only — per .claude/rules/ask-via-tool.md AUQ-004, dispatched agents cannot call AUQ. Calling git worktree remove --force without explicit operator confirmation would violate PSA-003 (destructive action safeguards) — the dirty state may contain another session's work-in-progress or unmerged commits.

AskUserQuestion({
  questions: [{
    question: `Auto-promoted worktree at ${promoted.wtPath} has uncommitted/untracked/unpushed changes. How should I proceed?`,
    header: "Worktree-Cleanup",
    multiSelect: false,
    options: [
      { label: "Behalten (Recommended)", description: "Keep the worktree as-is. No cleanup. Review and remove manually later." },
      { label: "Löschen", description: "I confirm the changes are handled or expendable. Run 'git worktree remove --force' on the worktree." },
      { label: "Manuell", description: "Exit /close. I will inspect the worktree before re-running /close." },
    ],
  }],
});

Codex CLI / Cursor IDE fallback (numbered Markdown list):

Worktree cleanup options:
1. **Behalten (Recommended)** — Keep the worktree as-is. No cleanup. Review and remove manually later.
2. **Löschen** — I confirm the changes are handled or expendable. Run 'git worktree remove --force'.
3. **Manuell** — Exit /close. I will inspect the worktree before re-running /close.
Reply with the number of your choice.

On user choice:

• Behalten → log session-end Phase 4a: auto-promoted worktree retained (dirty); operator chose Behalten. Continue to Phase 5.
• Löschen → execFileSync('git', ['-C', repoMainRoot, 'worktree', 'remove', '--force', promoted.wtPath]) (arg-array, no shell — #577 HARDEN-001). Log WARN: session-end Phase 4a: auto-promoted worktree force-removed by user choice. Continue to Phase 5.
• Manuell → exit /close cleanly. Print: session-end aborted at Phase 4a by user choice. Re-run /close after handling the worktree manually.

Cross-references

• PRD: "Parallel-Aware Sessions" (#568; archived in the private Meta-Vault) §3 P3 Gherkin rows 2-3 + §3.A P3 EARS event-driven clauses
• PSA-003: .claude/rules/parallel-sessions.md — destructive action safeguards (git worktree remove --force requires explicit user authorization)
• #490 durableCommit dependency: Phase 4a runs AFTER Phase 4 commit+push to guarantee sessions.jsonl + STATE.md are persisted to origin BEFORE worktree removal
• Detection helper: parseSessionId() from scripts/lib/session-id.mjs (#572)
• AUQ rule: .claude/rules/ask-via-tool.md AUQ-004 — coordinator-only invocation
• Companion phases: P3.1 PROMOTION_OFFER (enterWorktree() in parallel-aware-auq.md) creates the worktree; this phase removes it.

Phase 4b: Worktree-Orphan Sweep (#831/B5)

Skip if persistence: false in Session Config. Skip silently unless worktree-orphans.enabled: true (opt-in; default false).

Sweep the repo's worktree set for branches with 0 commits ahead of the base branch — orphans left behind by finished sessions. Distinct from Phase 4a: 4a asks "did this session run in a promoted worktree?", 4b asks "which worktrees from past sessions have nothing left in them?".

Ordering rationale (#490 durableCommit dependency): Phase 4b runs AFTER the Phase 4 commit+push, NOT before — the same invariant that governs Phase 4a. Removing a worktree before commit+push would lose its STATE.md before the Phase 3.4 sessions.jsonl metrics writes are committed. See docs/adr/0008-worktree-cleanup-ordering.md.

The module proposes; the coordinator disposes

Authoritative impl: scripts/lib/session-end/worktree-orphan-sweep.mjs — checkWorktreeOrphans({ repoRoot, mainCheckoutRoot, config, execFileFn }). Import and call; do NOT re-implement from this doc.

checkWorktreeOrphans() executes zero mutating commands. Its complete argv set is four read-only shapes — worktree list --porcelain, rev-list --count --end-of-options <base>..<branch>, and (via the reused Phase 4a helper isWorktreeClean) status --porcelain and status --short --branch — all via the injection-safe arg-array form (execFileSync('git', ['-C', dir, …]), #577 HARDEN-001), never a template-literal shell string. It returns null (silent no-op) or ONE object { severity: 'warn', message, candidates: [{ wtPath, branch, sessionId, aheadCount: 0 }] }.

--end-of-options is load-bearing, not decoration. base-branch comes from Session Config, and a value shaped like a git flag (e.g. --glob=refs/heads/*) is otherwise parsed by rev-list as an OPTION rather than a revision range — which exits 0 and prints 0, silently marking EVERY worktree as a 0-ahead orphan and offering the operator "Löschen" for worktrees full of live work. That is not an error path the conservative default catches, because 0 parses fine. --end-of-options turns the payload into a hard git error that DOES fall into the conservative continue, and _isSafeBaseBranch in the config parser rejects leading-dash values at the source. No attacker is needed for this — a typo reaches the same outcome.

The gate is opt-in and fails CLOSED: the module returns null unless enabled === true. It accepts either the full config object or the already-indexed worktree-orphans block, so neither call shape can accidentally open the gate.

A dirty worktree is never a candidate. Orphan-ness is not decided by commit count alone — isWorktreeClean() is consulted first, and any uncommitted, staged or untracked work (or any git error while checking) excludes the worktree entirely. A worktree that is 0-ahead but holds live work is exactly the case where a deletion prompt would cost real data.

The return field is named candidates, not orphans or removals, and the name is load-bearing: the coordinator decides, the module never does. Grounding: .claude/rules/parallel-sessions.md § PSA-003 — "Did I create this file/commit/change? If not, it is not mine to touch." A sweep probe created none of the worktrees it inspects.

Nothing is removed without explicit operator confirmation. The rendered banner always ends with the literal clause nothing was removed. — the operator-visible proof of the invariant.

Conservative default (safety-critical): any git error, unparseable rev-list output, detached HEAD, unresolvable branch, or ambiguity of any kind → that worktree is NOT reported as a candidate. A failing sibling never suppresses a healthy finding, and silence is never to be read as "safe to delete".

The AUQ is rendered by the coordinator, never by the module

AskUserQuestion is unavailable inside dispatched subagents (.claude/rules/ask-via-tool.md AUQ-004), so the module returns data only and the coordinator renders the picker — one call per candidate.

Option order is locked and is itself a safety property (#580-AUQ-001): the non-destructive option goes FIRST and is marked (Recommended), so an accidental Enter keypress can never destroy a worktree.

[ Behalten (Recommended) / Löschen / Manuell ]

• Behalten (Recommended) — leave the worktree in place; re-surfaces next session.
• Löschen — operator explicitly authorises removal; the coordinator performs it, subject to PSA-003.
• Manuell — operator handles it outside the session; no further prompting this session.

import { checkWorktreeOrphans } from '${PLUGIN_ROOT}/scripts/lib/session-end/worktree-orphan-sweep.mjs';

const sweep = checkWorktreeOrphans({
  repoRoot: process.cwd(),
  config: config['worktree-orphans'],
});

if (sweep) {
  console.warn(sweep.message);
  // → coordinator renders the AUQ per sweep.candidates entry.
  //   [ Behalten (Recommended) / Löschen / Manuell ]
  //   Nothing is removed unless the operator picks "Löschen".
}

Phase 5: Issue Cleanup

VCS Reference: Use CLI commands per the "Common CLI Commands" section of the gitlab-ops skill.

1. Close resolved issues: Before closing each issue, strip status:* workflow labels using stripStatusLabels from scripts/lib/issue-close-strip-labels.mjs (#308). A closed issue carrying status:in-progress or status:ready skews dashboard filters and discovery heuristics. Then close and add a note using the issue close and note commands per the "Common CLI Commands" section of the gitlab-ops skill. Note: some VCS platforms require separate note and close commands.

   import { stripStatusLabels } from '${PLUGIN_ROOT}/scripts/lib/issue-close-strip-labels.mjs';
   
   // For each resolved issue IID:
   const { stripped, error } = await stripStatusLabels({ issueId: iid, vcs: '<from Session Config>' });
   if (error) {
     console.warn(`⚠ label strip failed for #${iid}: ${error} — proceeding with close`);
   } else if (stripped.length) {
     console.log(`Stripped ${stripped.join(', ')} from #${iid}`);
   }
   // then: glab issue close <iid> / gh issue close <iid>
   

   The call is idempotent: if the issue has no status:* labels, no update CLI call is made. Failures from stripStatusLabels are non-fatal — log and proceed with close.

2. Update in-progress issues: ensure labels reflect actual state using the issue update command

3. Create carryover issues — from the Phase 1.65 gate's carry-list ONLY (#769): file an issue for each item on the carry-list produced by the Handover Alignment Gate — i.e. the non-deselectable auto-carry class (priority::critical|high, SPIRAL/FAILED, or no-origin-issue candidates) PLUS the middle-band items the operator LEFT SELECTED in triage. Do NOT file anything the gate dropped, and do NOT file directly from Phase 1.2/1.3/1.4/1.6 — those phases only collected candidates.

   • Template stays source-specific: 1.2 Partially-Done → [Carryover] <task> (labels priority::<original>, status:ready); 1.4 unfinished Emergent → a normal issue (NOT the [Carryover] template); 1.6 SPIRAL/FAILED → fire the deferred createSpiralCarryoverIssue({ taskDescription, kind, context, priority: 'high', vcs }) (idempotent task-hash dedup — payload comes from the candidate's _spiral annotation set in Phase 1.6 step 5). 1.3 files no NEW issue: a carried 1.3 candidate simply keeps its ORIGINAL issue status:ready.

   • Dropped middle-band items: file NO [Carryover] duplicate; the origin issue stays open and unchanged. Record each drop in the Phase 6 Final Report under ### Dropped at Handover Gate with its origin-issue reference and a reason slot.

   • Fail-open / gate skipped: when Phase 1.65 skipped fail-open, the carry-list is ALL candidates (status quo) and there is no drop-list.

   • Mark answered open questions [x] durably — atomic with the filing above (#769): now, on the completed side of the Quality Gate, persist each answered open question captured in-memory at Phase 1.65 Step 4 to STATE.md via the lock-guarded sibling helper (PSA-005). Co-locating this write with the carryover-issue filing is the load-bearing correctness invariant: an earlier Quality-Gate abort leaves every question - [ ] on disk, so it correctly re-surfaces via readOpenQuestions().filter(!answered) on re-close — the [x] mark now reflects a COMPLETED handover, never a mid-close state a later abort would invalidate. Any implied-work candidate an answered question enqueued in Phase 1.65 is filed by the carry-list step above, so the mark and its issue land together:

     import { markOpenQuestionAnsweredOnDisk } from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
     // answeredQuestions captured in Phase 1.65 Step 4 (in-memory, un-persisted until now)
     for (const { question, answer } of answeredQuestions) {
       await markOpenQuestionAnsweredOnDisk(repoRoot, question, answer); // "- [ ] Q" → "- [x] Q → Antwort: <answer>"
     }
     

     Fail-open: a markOpenQuestionAnsweredOnDisk failure is non-fatal — log a WARN and proceed with the close; the question simply stays - [ ] and roundtrips to the next session.

3b. Drain the issue-budget overflow — exactly ONE collector artefact (issue-budget): when .orchestrator/runtime/issue-budget.json has a non-empty overflow[], the session hit its issue-budget.max-per-session cap and every over-cap creation was PARKED rather than filed. Fold the whole list into a single artefact so nothing is silently dropped.

**Ordering (load-bearing):** run this as the LAST issue-creating action of Phase 5 — after step 3, after "Discovery Issue Creation", after step 4 — and re-read the counter file at that moment. Those steps can themselves push new entries into `overflow[]`; draining early would leave them unfiled.

```js
import { readBudgetState, budgetStatePath } from '${PLUGIN_ROOT}/scripts/lib/issue-budget.mjs';
const state = readBudgetState(repoRoot, sessionId);   // { sessionId, count, exempt, overflow: [...] }
```

- **`issue-budget.overflow: collect-issue` (default)** — create exactly ONE issue:
  - Title: `[Backlog-Sammel] <session-id>, <N> zurückgestellte Punkte`
  - Labels: `type::backlog`, `priority::low`
  - Body: a Markdown checklist with one `- [ ]` line per `overflow[]` entry (`title` when present, otherwise the truncated `command`, plus its `at` timestamp).
  - This collector issue is itself EXEMPT from the cap (`[Backlog-Sammel]` is in the exemption list in `scripts/lib/issue-budget.mjs`), so it always lands even at count == max.
- **`issue-budget.overflow: vault-note`** — create NO issue. Write one Markdown file `vault/00-inbox/<session-id>-backlog-sammel.md` (path relative to `vault-integration.vault-dir`) with valid vault frontmatter and the same checklist body.
- After the artefact exists, reset `overflow` to `[]` in the counter file and record the collector issue ID / note path in the Phase 6 Final Report under `### Zurückgestellt (issue-budget)`.
- **Never exempt-by-accident:** the cap never applied to `priority::critical`, the carryover class (`[Carryover]`, SPIRAL/FAILED, `type::carryover`), or `broken-window` closure issues, so nothing on the Phase 1.65 carry-list can ever appear in `overflow[]`. The promises at Phase 1.8 ("SPIRAL / FAILED agent carryover … non-deselectable") and the Critical Rule "ALWAYS create issues for unfinished PLANNED work" stay intact by construction.
- Fail-open: a missing or malformed counter file means "no overflow" — log a WARN and continue the close.

Discovery Issue Creation (if discovery ran in Phase 1.5)

For each finding with severity critical or high from Phase 1.5:

1. Create a VCS issue using the detected platform CLI:

   • Title: [Discovery] <description> (truncated to 70 chars)
   • Body: **Probe:** <probe>\n**File:** <file>:<line>\n**Severity:** <severity>\n**Confidence:** <confidence>%\n**Recommendation:** <recommendation>
   • Labels: type:discovery, priority::<severity> (critical→critical, high→high)

2. Log each created issue ID for the Final Report

3. Update discovery_stats.issues_created count

4. Create gap issues for HIGH+/blocking newly-discovered problems only — MED/LOW review findings are recorded in the Final Report, not filed as issues (#617; see the Phase 1.8 severity-disposition table). This mirrors the Phase 5 "Discovery Issue Creation" gate (critical/high only).

5. Update milestones: if milestone progress changed

Phase 6: Final Report

Present to the user:

## Session Summary

### Completed
- [x] Issue #N: [description] — [evidence: tests passing, files changed]
- [x] Issue #M: [description]

### Carried Over
- [ ] Issue #P: [what's left] — new issue #Q created
- [ ] [description] — blocked by [reason]

### Dropped at Handover Gate (deselected in triage — origin issue left open) [#769]
- [ ] [middle-band item] — origin #<IID> — reason: [operator deselected in Phase 1.65 triage; no [Carryover] duplicate filed]

### New Issues Created
- #R: [title] (priority: [X], status: ready)
- #S: [title] (priority: [X], status: ready)

### Unresolved Review Findings (MED/LOW — recorded, not ticketed) [#617]
- [MED] <finding> — <file:line> — <why deferred / fold decision>
- [LOW] <finding> — <file:line>

### Metrics
- Duration: [total wall-clock time]
- Waves: [N completed]
- Agents: [total dispatched] ([X complete, Y partial, Z failed])
- Files changed: [N]
- Per-wave breakdown:
  - Wave 1 (Discovery): [duration] — [N agents] — [K files]
  - Wave 2 (Impl-Core): [duration] — [N agents] — [K files]
  - ...
- Tests: [passing/total]
- TypeScript: 0 errors
- Commits: [N] pushed to [branch]
- Mirror: [synced/skipped]
- Docs Health: Vault staleness — [render one of the three cases below based on Phase 2.3 result]
  - Findings present (warn mode): `[N stale projects, M stale narratives] (mode=warn). See .orchestrator/metrics/vault-staleness.jsonl.`
  - Skipped (disabled or mode=off): `skipped (disabled | mode=off).`
  - Clean run: `clean (mode=<mode>).`
- Custom Phases: [render based on Phase 2.5 result — omit the line entirely if `custom-phases` was absent/empty]
  - Per phase: `<name>: <pass|FAIL> (exit <code>, mode=<mode>)[ — review: <path>]`
  - None ran (all filtered out by `when`): `none applicable for session-type=<type>.`
- Enforcement: [N violations blocked / M warnings] (or "N/A" if enforcement off)
- Circuit breaker: [N agents hit limits, M spirals detected] (or "none")
- Metrics written to: `.orchestrator/metrics/sessions.jsonl`
- Learnings: [N] new, [M] confirmed, [K] contradicted/expired — written to `.orchestrator/metrics/learnings.jsonl`

### Next Session Recommendations
- Priority: [what should be tackled next]
- Type: [housekeeping/feature/deep recommended]
- Notes: [any context for next session]

Documentation Coverage anchor: If Phase 3.2 ran and produced task verification results (i.e. docs-orchestrator.enabled: true and docs-tasks were found), the results appear here as a ### Documentation Coverage (docs-orchestrator) subsection emitted by Phase 3.2 Step 7. The content is written dynamically — it is not pre-populated in this template. When docs-orchestrator.enabled is false or docs-tasks were absent, this subsection is omitted entirely.

Sub-File Reference

File	Purpose
plan-verification.md	Phase 1 plan verification and metrics collection
verification-checklist.md	Phase 2 quality gate checklist and checks
discovery-scan.md	Phase 1.5 embedded discovery dispatch and findings triage
metrics-collection.md	Phase 1.7 JSONL schema and conditional field rules
vault-operations.md	Phase 2.1 validator bash contract and reporting matrix
drift-operations.md	Phase 2.2 drift-checker bash contract and reporting matrix
phase-3-2-docs-verification.md	Phase 3.2 full procedural body — docs-tasks load, SESSION_START_REF, per-task loop, mode-gated report, Documentation Coverage block
learning-patterns.md	Phases 3.5a + 3.6 extraction heuristics, confidence updates, passive decay, and JSONL write procedure
phase-3-6-tail.md	Phase 3.6.x tail — full unabridged detail procedures for all six tail phases: 3.6.3 Memory-Proposals Collection (collectProposals + AUQ multiSelect + promoteAndClear, composing writeApproved + clearProposalsJsonl behind a mechanical write-before-clear guard, #828), 3.6.4 Expired-Learnings Sweep (Epic #723 B4), 3.6.5 Auto-Dream nudge (shouldDispatchAutoDream, #614), 3.6.6 Skill-Applied Judge (#645 L3 — runSkillJudge, coordinator-writes), 3.6.7 Auto-Dialectic nudge (shouldDispatchAutoDialectic, #614), 3.6.8 Reconciliation Rule Proposals (#696 FA3 — runReconcile + AUQ + writeApprovedRules). Loaded on demand by the SKILL.md skip-plan dispatcher (#724) — only phases with run: true in the planTailPhases() plan execute
scripts/lib/session-end/phase-skip.mjs	Phase 3.6.x tail skip-plan aggregator (#724) — planTailPhases({repoRoot, config, sessionId, platform}) → {plan, skippedReport}; side-effect-free (reconcile/sweep via dry-run — no writes), never-throws (per-phase probe error fail-opens to run: true); wraps the six existing signal helpers with config gates first, then input detection
(inline) Phase 3.45	Telemetry Flush (advisory, #844) — flush() from scripts/lib/telemetry/sync.mjs drains the host-local send-queue fire-and-forget; no config key (send-gate is resolveConsent() inside the module, fail-closed); skip when persistence: false; never-throw + ~3s-bounded, offline → bounded oldest-dropped queue, optional Telemetry: sent/queued/gated close-summary line, NEVER an error banner; runs late in the close after Phase 3.7
session-metrics-write.md	Phase 3.7 JSONL append, vault-mirror invocation, durable narrative mirror (mirrorNarrative, #675), and behavior matrix
phase-3-7a-recommendations.md	Phase 3.7a full procedural body — computeV0Recommendation call, STATE.md field write, data source guarantee, error mode
phase-3-7a-recommendations.md § 3.7b	Phase 3.7b full procedural body — withDurableCommit invocation for sessions.jsonl + STATE.md (#490 AC2), enabled:false local no-op, autopilot.jsonl exclusion note
(inline) Phase 3.7c	Vault Board → Closed (#674) — mirrorBoard({ explicitStatus: 'closed' }) transitions this repo's board row to closed; gated on vault-integration.enabled, generator-marked + idempotent, non-blocking, ordered after 3.7b and before 3.7d/3.4/3.8
(inline) Phase 3.7d	Session-Eval (opt-in — #803) — node scripts/eval-session.mjs --json scores the just-closed session; gated on eval.enabled + eval.mode != off (parsed by scripts/lib/config/eval.mjs), optional eval-judge dispatch + writeEvalReport, advisory/never-blocks-close, ordered after 3.7 (record must exist) and before 3.4/Phase 4 (record committed with the session). Full flow in skills/eval/SKILL.md
(inline) Phase 3.8	Session Lock Release — release() call, silent-OK on mismatch/absent, non-fatal on fs-error, ordering note (after STATE.md writes, before Phase 4 commit staging)

Anti-Patterns

• DO NOT commit before running quality gates — a "clean commit" with TypeScript errors is not clean
• DO NOT mark issues as closed without verifying the implementation actually addresses them
• DO NOT skip creating tracking issues for unfinished work — "I'll remember for next session" always fails
• DO NOT use git add . or git add -A — parallel sessions may have uncommitted work in the tree
• DO NOT push to mirrors before verifying origin push succeeded — broken state propagates

Critical Rules

• NEVER claim work is done without running verification — evidence before assertions
• NEVER commit with TypeScript errors — 0 errors is non-negotiable
• NEVER use git add . — stage files individually to avoid capturing parallel session work
• NEVER skip issue updates — VCS must reflect reality after every session
• ALWAYS create issues for unfinished PLANNED work — SPIRAL/FAILED agent carryover and partially-done plan items (Phase 1.2 / 1.6) ALWAYS get a ticket; nothing planned-but-unfinished is "remembered" without one. The issue-budget per-session cap does NOT weaken this: priority::critical, the carryover class ([Carryover], [SPIRAL]/[FAILED], type::carryover, bare carryover) and broken-window closure issues are exempt from the cap by construction (scripts/lib/issue-budget.mjs EXEMPT_RULES). Non-exempt over-cap creations are not dropped either — they are parked and folded into one [Backlog-Sammel] collector in Phase 5 Step 3b.
• DO NOT auto-file MED/LOW review findings as issues — newly-surfaced reviewer findings (Phase 1.8 / W4 panel) at MED or LOW severity are folded in-session or recorded in the Final Report under "Unresolved Review Findings". Only HIGH+/blocking review findings get an issue. (Issue #617 — stops the self-referential low-priority backlog.)
• ALWAYS push to origin — local-only work is lost work
• ALWAYS mirror to GitHub if configured — keep mirrors in sync
• ALWAYS review git diff --cached before committing — verify only YOUR changes are staged