session-orchestrator 3.16.0

package/skills/session-end/plan-verification.md

@@ -0,0 +1,288 @@
+# Phase 1: Plan Verification
+
+> Sub-file of the session-end skill. Executed as the first phase of session close-out.
+> For quality gates, documentation, commit, and reporting, see `SKILL.md`.
+
+Read back the session plan that was agreed at the start. For EACH planned item:
+
+### SESSION_START_REF accessor
+
+> Referenced by Phase 3.2 (Docs Verification) and Phase 1.1a (File-Level Grounding). Canonical definition lives here.
+
+Read `session-start-ref` from STATE.md frontmatter. If the field is missing (older session or persistence disabled), fall back to `git diff --name-only origin/main...HEAD` (compares current HEAD against origin/main rather than a pinned SHA). The fallback is less precise but functional. Always prefer the pinned SHA when available.
+
+```bash
+SESSION_START_REF=$(node --input-type=module -e "
+import {readFileSync} from 'node:fs';
+import {parseFrontmatter} from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
+const fm = parseFrontmatter(readFileSync('<state-dir>/STATE.md', 'utf8'));
+process.stdout.write(fm['session-start-ref'] ?? '');
+" 2>/dev/null)
+# Fallback when field absent
+[ -z "$SESSION_START_REF" ] && SESSION_START_REF="origin/main"
+```
+
+### 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.1a File-Level Grounding
+
+> Gate: skip this entire sub-phase if `grounding-check: false` in Session Config (default: `true`). Informational — does NOT block the session close on its own.
+
+Compare the files the plan said would be touched against the files actually changed in the session. Catches both **scope creep** (files changed that were not in any agent's prompt scope) and **incomplete coverage** (files in the plan that were never edited).
+
+1. **Planned files** = union of all file paths from agent prompt scopes across all waves. Source: STATE.md Wave History, falling back to the original session plan's per-agent "Files:" specs. Glob patterns are expanded against the working tree at session-start time.
+2. **Actual files** = `git diff --name-only $SESSION_START_REF..HEAD`, where `$SESSION_START_REF` comes from the `session-start-ref` field in STATE.md frontmatter. If the field is missing (older session), fall back to `git diff --name-only origin/main...HEAD`.
+3. **Compute discrepancies:**
+   - **Touched** = files in both Planned and Actual
+   - **Unplanned (scope creep)** = files in Actual but not in Planned
+   - **Untouched (incomplete coverage)** = files in Planned but not in Actual
+4. **Noise reduction filters** (apply before reporting):
+   - Test files (`*.test.*`, `*.spec.*`, `**/__tests__/**`) corresponding to a touched production file are reclassified as expected (not scope creep)
+   - Generated/lock files (`pnpm-lock.yaml`, `*.lock`, `dist/**`, `node_modules/**`) are excluded from both planned and actual sets
+   - The `.claude/`, `.codex/`, and `.cursor/` state directories are excluded — they are session artifacts, not code
+5. **Report** in the verification output:
+   ```
+   File-level grounding:
+   - Planned: N files
+   - Touched: N files (X% coverage)
+   - Unplanned (scope creep): N files [list first 5]
+   - Untouched (planned but not edited): N files [list first 5]
+   ```
+6. **Append to session metrics** (`grounding` field in the Phase 1.7 JSONL entry):
+   ```json
+   "grounding": {
+     "planned": N,
+     "touched": N,
+     "unplanned": N,
+     "untouched": N
+   }
+   ```
+   The metrics field is conditional on `grounding-check: true` — when the gate is off, omit the field entirely (do not write `null`).
+
+### 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.3a Optional /goal Backlog-Drain (opt-in — #636)
+
+When `goal-integration.enabled: true` with seam `session-end-backlog`, the close may surface ONE advisory `/goal` command to drain still-relevant §1.2/§1.3 items in-session instead of carrying them over. See `SKILL.md § 1.3a Optional /goal Backlog-Drain` for the full gate conditions, advisory-only contract, and the LM-008 cross-reference — the two files mirror each other; the prose lives in SKILL.md.
+
+### 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
+
+### Candidate Record Format (#769)
+
+> Since #769, Phases 1.2 / 1.3 (still-relevant) / 1.4 (unfinished emergent) / 1.6 (SPIRAL/FAILED walk) **no longer file `[Carryover]` issues immediately** — they append **carryover candidates** to an in-memory list that the Phase 1.65 Handover Alignment Gate routes, and Phase 5 Step 3 files the gate's carry-list. The authoritative gate prose (routing, AUQ shapes, fail-open) lives in `SKILL.md § 1.65 Handover Alignment Gate` — this subsection documents only the record shape the phases produce.
+
+Each candidate is a plain object with these fields (JS keys are the ones `routeCandidates` / `normalizeCandidate` in `scripts/lib/handover-gate.mjs` read):
+
+| Concept | JS key | Type | Notes |
+|---|---|---|---|
+| task | `task` | `string` | Task text. Missing/empty → `normalizeCandidate` flags `malformed: true` and routes it to `ask`. |
+| source-phase | `sourcePhase` | `'1.2' \| '1.3' \| '1.4' \| '1.6'` | The Phase-1 bucket that emitted the candidate; used to infer `bucket` when absent. |
+| origin-issue | `originIssue` | `number \| null` | Origin issue IID, or `null` when there is none. **`null` → auto-carry** (dropping a candidate with no origin issue would be real forgetting; keeps `SKILL.md:853` intact). |
+| priority | `priority` | `'critical' \| 'high' \| 'medium' \| 'low' \| null` | `critical`/`high` → auto-carry. `medium`/`low`/`null` (with an origin issue) → middle-band `ask`. |
+| bucket | `bucket` | `'partially-done' \| 'not-started' \| 'emergent' \| 'spiral-failed'` | Maps 1.2→`partially-done`, 1.3→`not-started`, 1.4→`emergent`, 1.6→`spiral-failed`. `spiral-failed` → auto-carry. |
+
+**Routing (deterministic, `routeCandidates`):** a candidate lands in `autoCarry` (non-deselectable, gate-summary only) when `priority ∈ {critical, high}` OR `bucket === 'spiral-failed'` OR `originIssue === null`; otherwise it lands in `ask` (the preselected middle-band multiSelect). SPIRAL/FAILED candidates additionally carry a non-schema `_spiral: { kind, context }` annotation on the coordinator's original object — consumed by the deferred `createSpiralCarryoverIssue` call in Phase 5 Step 3 (`routeCandidates` strips it from its normalized copies).
+
+### 1.5 Discovery Scan (if enabled)
+
+Check if `discovery-on-close` is `true` in Session Config. If not configured or `false`, skip this section.
+
+When enabled, invoke the discovery skill in **embedded mode** by dispatching an Explore agent:
+```
+Agent({
+  description: "Discovery embedded scan",
+  prompt: "Run discovery probes in embedded mode. Scope: session probes + discovery-probes config. Return findings and stats as a JSON object in a markdown code fence. Do NOT run Phase 4 (triage) or Phase 5 (issue creation) — return after Phase 3.",
+  subagent_type: "Explore",
+  run_in_background: false
+})
+```
+On Codex CLI / Cursor IDE: execute probes sequentially within the current context (no Agent dispatch).
+- Collect verified findings from the discovery output
+- Parse the discovery output for the **findings** array and **stats** object (see Parsing callout below)
+- Store the stats object for Phase 1.7 metrics collection (`discovery_stats` field)
+
+> **Parsing discovery output:** Search for the first ` ```json ` block in the discovery output. The JSON contains: (1) a **findings** array — objects with `probe`, `category`, `severity`, `confidence`, `file`, `line`, `description`, `recommendation` fields; (2) a **stats** object — with `probes_run`, `findings_raw`, `findings_verified`, `false_positives`, `user_dismissed`, `issues_created`, `by_category`. If JSON parsing fails, log a warning and skip Phase 1.5 — do NOT fail the session close. Store stats as `discovery_stats` in session metrics (Phase 1.7).
+- Incorporate findings into issue management:
+  - Findings with severity `critical` or `high` → create issues immediately (Phase 5)
+  - Findings with severity `medium` or `low` → list in the Final Report under "Discovery Findings (deferred)"
+- Report: "Discovery scan: [N] findings ([X] critical/high → issues, [Y] medium/low → deferred)"
+
+### 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 carryover issues exist (cross-reference with Phase 1.2)
+
+### 1.7 Metrics Collection
+
+> Gate: Only run if `persistence` is enabled in Session Config.
+
+Finalize session metrics by reading the wave data accumulated during execution:
+
+1. Read `<state-dir>/STATE.md` Wave History to extract per-wave data: agent counts, statuses, files changed
+
+> **Graceful degradation:** If STATE.md is missing expected fields (no Wave History, missing frontmatter keys, malformed YAML), degrade gracefully: report what is available, skip metrics fields that cannot be parsed. Do NOT fail the session close because STATE.md is incomplete — a crashed session may leave partial STATE.md behind.
+
+2. Compute session totals:
+   - `total_duration_seconds`: from `started_at` to now (ISO 8601 diff)
+   - `total_waves`: count of completed waves
+   - `total_agents`: sum of agents across all waves
+   - `total_files_changed`: unique files changed across entire session (from `git diff --stat`)
+   - `agent_summary`: `{complete: N, partial: N, failed: N, spiral: N}`
+3. Prepare the JSONL entry (written in Phase 3.7) by **constructing it programmatically** — DO NOT manually hand-compose ISO timestamp strings. The `completed_at` value MUST come from `new Date().toISOString()` to prevent issue #540-class corruption (e.g., `.3NZ` malformed-fraction inputs). The validator at `scripts/lib/session-schema/validator.mjs` rejects any timestamp that does not match the canonical `YYYY-MM-DDTHH:MM:SS[.SSS]Z` regex.
+
+   Use this snippet pattern (adapt the field values from the session's in-memory state, but keep `new Date().toISOString()` for `completed_at` literally):
+
+   ```bash
+   # Issue #540: completed_at is constructed programmatically — DO NOT manually
+   # edit the ISO timestamp string. Use the snippet as-is to prevent .3NZ-class
+   # corruption.
+   METRICS_ENTRY=$(node --input-type=module -e "
+   const entry = {
+     session_id: '<branch>-<YYYY-MM-DD>-<HHmm>',
+     session_type: '<type>',
+     platform: '<claude|codex>',
+     started_at: '<ISO 8601 from STATE.md frontmatter started_at — already canonical>',
+     completed_at: new Date().toISOString(),  // canonical YYYY-MM-DDTHH:MM:SS.SSSZ
+     duration_seconds: <N>,
+     total_waves: <N>,
+     total_agents: <N>,
+     total_files_changed: <N>,
+     agent_summary: {complete: <N>, partial: <N>, failed: <N>, spiral: <N>},
+     waves: [/* {wave, role, agent_count, files_changed, quality} */],
+     // effectiveness is CONSTRUCTED EXPLICITLY (#773) — never left as an
+     // optional field for the coordinator to remember, which is how the
+     // carryover=0 blind spot recurred. `carryover` is the Phase 1.65 gate
+     // carry-list length (see Effectiveness counting rules below), NOT the raw
+     // 1.2+1.3 candidate count.
+     effectiveness: {
+       planned_issues: <N>,
+       completed: <N>,
+       carryover: <N>,   // = Phase 1.65 gate carry-list length (see rules below)
+       emergent: <N>,
+       completion_rate: <0.0-1.0>,
+     },
+     // Handover-gate open-question telemetry (#773) — top-level, additive,
+     // non-negative integers. OMIT (do not write 0) when the gate did not run
+     // (fail-open skip / headless): absent = "not measured", 0 = "measured zero".
+     open_questions_asked: <N>,      // surfaced in AUQ Call 2
+     open_questions_answered: <N>,   // operator answered
+     open_questions_deferred: <N>,   // left `- [ ]`, roundtripped to next session
+     // Other optional fields populated per the Conditional Fields rules below.
+   };
+   process.stdout.write(JSON.stringify(entry));
+   ")
+   ```
+
+   **Canonical JSONL schema** (for field reference — populated by the snippet above):
+   ```json
+   {
+     "session_id": "<branch>-<YYYY-MM-DD>-<HHmm>",
+     "session_type": "<type>",
+     "platform": "<claude|codex>",
+     "started_at": "<canonical ISO 8601 from STATE.md>",
+     "completed_at": "<canonical ISO 8601 from new Date().toISOString()>",
+     "duration_seconds": N,
+     "total_waves": N,
+     "total_agents": N,
+     "total_files_changed": N,
+     "agent_summary": {"complete": N, "partial": N, "failed": N, "spiral": N},
+     "waves": [
+       {"wave": 1, "role": "Discovery", "agent_count": N, "files_changed": N, "quality": "pass|fail|skip"},
+       ...
+     ],
+     "discovery_stats": {
+       "probes_run": N,
+       "findings_raw": N,
+       "findings_verified": N,
+       "false_positives": N,
+       "user_dismissed": N,
+       "issues_created": N,
+       "by_category": {
+         "code": {"findings": N, "actioned": N},
+         "infra": {"findings": N, "actioned": N},
+         "ui": {"findings": N, "actioned": N},
+         "arch": {"findings": N, "actioned": N},
+         "session": {"findings": N, "actioned": N}
+       }
+     },
+     "review_stats": {
+       "total_findings": N,
+       "high_confidence": N,
+       "auto_fixed": N,
+       "manual_required": N
+     },
+     "effectiveness": {
+       "planned_issues": N,
+       "completed": N,
+       "carryover": N,
+       "emergent": N,
+       "completion_rate": 0.0
+     },
+     "open_questions_asked": N,
+     "open_questions_answered": N,
+     "open_questions_deferred": N
+   }
+   ```
+
+   > **ISO-8601 canonical format (#540):** `started_at`, `completed_at`, and `lease_acquired_at` MUST match the regex `/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/`. The validating writer (`scripts/emit-session.mjs`) rejects any non-canonical form. Use `new Date().toISOString()` (Node-native, always canonical) — never hand-edit fractional digits or timezone suffixes.
+
+> **Effectiveness counting rules** (extract from Phase 1 verification results):
+> - `planned_issues`: count of issue numbers listed in `<state-dir>/STATE.md` frontmatter `issues:` array. If the `issues` array is empty (e.g., lifecycle simulation sessions that don't target VCS issues), `planned_issues` = 0 — this is expected, not a bug.
+> - `completed`: count of items verified as Done in Phase 1.1 (acceptance criteria met, evidence confirmed)
+> - `carryover`: the **length of the Phase 1.65 gate carry-list**, NOT the raw Phase 1.2 + 1.3 candidate count (#773). Concretely: `autoCarry` ∪ the middle-band `ask` items the operator LEFT SELECTED ∪ the answered-question `impliesWork: true` candidates the gate enqueued. On the fail-open skip (gate disabled / headless / AUQ unavailable) EVERY candidate carries, so `carryover` = the full candidate-list length (autoCarry ∪ ask). This is the count that actually reaches Phase 5 Step 3 filing. **Why this changed:** the old rule counted Phase 1.2 + 1.3 candidates BEFORE the #769 gate could drop any — but since #769 the gate (Phase 1.65) decides carry vs. drop, and the pre-#773 rule was never re-anchored to it, so 41/41 records read `carryover: 0` despite real filtering. Count the gate's OUTPUT, not its INPUT.
+> - `emergent`: count of items documented in Phase 1.4 (work done that was NOT in the original plan)
+> - `completion_rate`: `completed / planned_issues`. If `planned_issues` is 0, set `completion_rate` to 1.0 (vacuously complete — no planned work means nothing was left undone).
+>
+> **Note on lifecycle simulation sessions:** Sessions that perform codebase-wide analysis (lifecycle sims, architecture audits) typically have `planned_issues: 0` because they don't target specific VCS issues. These sessions may produce dozens of fixes but will show `planned_issues: 0, completed: 0` in effectiveness tracking. This is correct behavior — effectiveness tracks issue-level planning accuracy, not session productivity. Session productivity is captured by `total_files_changed` and `total_agents`.
+
+> The `session_id` uses `<HHmm>` from the `started_at` timestamp to ensure uniqueness when multiple sessions run on the same branch in one day.
+
+> **Conditional fields:**
+> - `discovery_stats`: populated ONLY when `discovery-on-close: true` in Session Config AND Phase 1.5 executed successfully. Source: the stats object returned by the discovery skill (see discovery skill Phase 3.6 for schema). When discovery runs in **embedded mode** (Phases 0-3 only), `user_dismissed`, `issues_created`, and `actioned` per category will always be `0` — embedded mode does not perform user triage (Phase 4) or issue creation (Phase 5).
+> - `review_stats`: populated ONLY when Phase 1.8 dispatched the session-reviewer agent AND it returned findings. Source: the session-reviewer's output summary.
+> - `effectiveness`: ALWAYS populated from Phase 1 plan verification results. `completion_rate` = `completed / planned_issues` (0.0-1.0, where 0.0 means nothing was completed). Construct it EXPLICITLY in the METRICS_ENTRY snippet (#773) — do not defer it to a "remember to add" optional-field step; that omission is exactly how `carryover: 0` went unnoticed across 41 records.
+> - `open_questions_asked` / `open_questions_answered` / `open_questions_deferred` (#773): the three open-question counts from the Phase 1.65 gate's AUQ Call 2 (identical to the `questions_*` fields on the `orchestrator.handover.gated` event). Top-level, additive, non-negative integers. Populate ONLY when the gate actually ran an interactive triage (the "Closen + Triage" path). OMIT all three (do NOT write `0`) when the gate was skipped (fail-open / headless / disabled) or took the fast-path — absent = "not measured", `0` = "measured, zero questions". The schema validator accepts absent/null/non-negative-integer.
+
+### 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** — address each listed item before proceeding. For quick fixes (<2 min each), fix inline. For larger items, create carryover issues (same as Phase 1.2) and note them as unresolved review findings in the Final Report

package/skills/session-end/session-metrics-write.md

@@ -0,0 +1,223 @@
+# Phase 3.7: Write Session Metrics
+
+> Sub-file of the session-end skill. Executed as part of Phase 3 (Documentation Updates) when `persistence` is enabled.
+> For the full session close-out flow, see `SKILL.md`.
+
+### 3.7 Write Session Metrics
+
+> Gate: Only run if `persistence` is enabled in Session Config.
+>
+> This step writes the session JSONL entry, verifies it, then optionally mirrors the session summary to the configured Obsidian vault via `scripts/vault-mirror.mjs`.
+
+> **MANDATORY WRITE PATH (#400):** ALL session closes — including coord-direct sessions, housekeeping, express-path, and autopilot runs — MUST write the JSONL metrics entry exclusively via `node scripts/emit-session.mjs`. **Hand-composing JSON and appending it directly to `sessions.jsonl` is forbidden.** `emit-session.mjs` calls `validateSession` from `scripts/lib/session-schema.mjs` (the schema authority) before appending and stamps `schema_version: 1`. Entries that bypass this path skip validation and produce malformed records with missing required fields (`waves[]`, `agent_summary`) or unresolved legacy field names (`waves_completed`, `files_changed`, `planned_issues` at top-level instead of under `effectiveness`).
+>
+> Minimal invocation:
+> ```bash
+> printf '%s' "$METRICS_ENTRY" | node "$PLUGIN_ROOT/scripts/emit-session.mjs" --file .orchestrator/metrics/sessions.jsonl
+> ```
+> See step 2 below for the full invocation including exit-code handling.
+
+1. Ensure `.orchestrator/metrics/` directory exists: `mkdir -p .orchestrator/metrics`
+
+1-pre. **`memory_cleanup_at` always-stamp (#699)** — Before emitting the record, if `/memory-cleanup` ran THIS session in any mode (dry-run, apply-pending, OR healthy no-op), stamp `memory_cleanup_at = completed_at` on the record using `stampMemoryCleanup()` from `scripts/lib/memory-cleanup-stamp.mjs`:
+
+   ```js
+   import { stampMemoryCleanup } from '../../scripts/lib/memory-cleanup-stamp.mjs';
+
+   // ranCleanup: true when /memory-cleanup ran this session (ANY outcome)
+   metricsEntry = stampMemoryCleanup(metricsEntry, {
+     ranCleanup: ranMemoryCleanupThisSession, // boolean
+     completedAt: metricsEntry.completed_at,
+   });
+   ```
+
+   **Contract:** A no-op run (MEMORY.md already healthy, no files mutated) is still a cleanup — `memory_cleanup_at` MUST be stamped. This advances `readDreamSignals` → `lastCleanupAt` in `auto-dream.mjs` so `shouldDispatchAutoDream` does not fire a false nudge. When `/memory-cleanup` did not run, omit the field entirely (do NOT set null). The helper is no-throw and pure — it returns the record unchanged on bad inputs.
+
+   > **#701.2 DOC NOTE — `completed_at >= started_at` guard:** This invariant is enforced mechanically by `scripts/emit-session.mjs`. The writer applies `clampTimestampsMonotonic()` (from `scripts/lib/session-schema/timestamps.mjs`) before `validateSession()`, clamping any inversion of `completed_at < started_at` to `started_at` and recording forensics in `_clamped: true` / `_original_completed_at`. Previously-inverted entries (e.g. `main-2026-06-21-session-4`) are already corrected. **No per-session coordinator action is needed** — the writer enforces the invariant at write time. Do not add defensive clamping logic here; the canonical guard lives in `emit-session.mjs`.
+
+1a. **Token Rollup (#644)** — before emitting the JSONL record, aggregate token usage from `subagents.jsonl` and merge the three token fields onto the in-memory `$METRICS_ENTRY` JSON object. The join key is the session's UUID (`session_id` / `parent_session_id` on subagents.jsonl — the UUID form, not the semantic slug).
+
+   **Semantics:** `null` totals mean "no token data was captured for this session" — this is NOT the same as zero cost. Do NOT coerce null to 0 when displaying or summing across sessions.
+
+   Example (coordinator pseudo-code — adapt to your shell/JS context):
+
+   ```js
+   // Available from scripts/lib/session-token-rollup.mjs
+   import { rollupSessionTokens } from '../../scripts/lib/session-token-rollup.mjs';
+
+   const rollup = rollupSessionTokens({ parentSessionId: SESSION_UUID });
+   // rollup: { total_token_input, total_token_output, subagents_with_tokens, matched_records }
+   // Merge into the record — all three fields are optional in schema v1 (additive).
+   metricsEntry.total_token_input   = rollup.total_token_input;   // number | null
+   metricsEntry.total_token_output  = rollup.total_token_output;  // number | null
+   metricsEntry.subagents_with_tokens = rollup.subagents_with_tokens; // number (0 when no coverage)
+   ```
+
+   Or, from a bash context, call the rollup via a helper node invocation and `jq`-merge the three fields into `$METRICS_ENTRY` before step 2:
+
+   ```bash
+   ROLLUP_JSON=$(node -e "
+     import('$(dirname "$0")/../scripts/lib/session-token-rollup.mjs').then(m => {
+       const r = m.rollupSessionTokens({ parentSessionId: process.env.SESSION_UUID });
+       process.stdout.write(JSON.stringify(r));
+     });
+   " 2>/dev/null) || ROLLUP_JSON='{}'
+
+   # Merge token fields into METRICS_ENTRY (null for fields absent from rollup)
+   METRICS_ENTRY=$(printf '%s' "$METRICS_ENTRY" | jq \
+     --argjson r "${ROLLUP_JSON:-{}}" \
+     '. + {
+       total_token_input:    ($r.total_token_input // null),
+       total_token_output:   ($r.total_token_output // null),
+       subagents_with_tokens: ($r.subagents_with_tokens // 0)
+     }')
+   ```
+
+   **If the rollup call fails** (e.g., `subagents.jsonl` absent, parse error), set all three fields to `null` / `0` and continue — the rollup is non-blocking. A session without token data still writes cleanly.
+
+2. Append the prepared JSONL entry (from Phase 1.7, now including token fields from step 1a) via the validating writer `scripts/emit-session.mjs` (issue #249):
+   ```bash
+   printf '%s' "$METRICS_ENTRY" | node "$PLUGIN_ROOT/scripts/emit-session.mjs" --file .orchestrator/metrics/sessions.jsonl
+   EMIT_EXIT=$?
+   if [[ $EMIT_EXIT -eq 1 ]]; then
+     echo "ERROR: session-end validation failed — entry rejected by scripts/emit-session.mjs. See stderr above. Session metrics NOT written." >&2
+     exit 1
+   elif [[ $EMIT_EXIT -ne 0 ]]; then
+     echo "ERROR: scripts/emit-session.mjs failed with exit $EMIT_EXIT. Session metrics NOT written." >&2
+     exit 1
+   fi
+   ```
+   `scripts/emit-session.mjs` calls `validateSession` from `scripts/lib/session-schema.mjs` before appending, stamps `schema_version: 1` if absent, and uses `appendJsonl` (atomic for lines < PIPE_BUF). Exit 1 on validation error, exit 2 on I/O error — block session close in both cases so malformed metrics can never reach disk.
+
+   **`autopilot_run_id` (additive, optional, #300):** when this session was launched by `/autopilot`, the wave-executor `sessionRunner` callback passes `args.autopilotRunId` from `runLoop`. session-end MUST persist that value as a top-level field on the JSONL record:
+
+   ```json
+   {"schema_version":1,"session_id":"…","autopilot_run_id":"main-2026-04-25-1432-autopilot",...}
+   ```
+
+   Manual sessions either omit the field or write `null` — both are treated identically per the v1 additive convention. Readers must NOT distinguish "missing" from "null" semantically. `validateSession` does not require this field; it passes through unknown keys unchanged.
+3. The writer creates the file if it does not exist.
+4. Verify: read back the last line to confirm valid JSON (sanity check; validation already ran):
+   ```bash
+   tail -1 .orchestrator/metrics/sessions.jsonl | jq . > /dev/null || {
+     echo "ERROR: last sessions.jsonl line is not valid JSON — manual fix required" >&2; exit 1;
+   }
+   ```
+5. **Vault Mirror** — mirror the session entry to the Obsidian vault (if configured):
+
+   ```bash
+   VM_ENABLED=$(echo "$CONFIG" | jq -r '."vault-integration".enabled // false')
+   VM_MODE=$(echo "$CONFIG" | jq -r '."vault-integration".mode // "warn"')
+
+   if [[ "$VM_ENABLED" == "true" && "$VM_MODE" != "off" ]]; then
+     # Resolve vault directory: config field takes precedence, env var as fallback
+     VM_DIR=$(echo "$CONFIG" | jq -r '."vault-integration"."vault-dir" // empty')
+     : "${VM_DIR:=$VAULT_DIR}"
+
+     # Quality-gate thresholds (PRD F1.2). Defaults match
+     # scripts/vault-mirror.mjs (400 chars / 0.5 confidence). The nested key
+     # path `vault-mirror.quality.*` is owned by the I6 config parser; this
+     # site is a read-only consumer.
+     VM_QUALITY_NARRATIVE=$(echo "$CONFIG" | jq -r '."vault-mirror".quality."min-narrative-chars" // 400')
+     VM_QUALITY_CONFIDENCE=$(echo "$CONFIG" | jq -r '."vault-mirror".quality."min-confidence" // 0.5')
+     VM_VAULT_NAME=$(echo "$CONFIG" | jq -r '."vault-integration"."vault-name" // empty')
+
+     VM_OUTPUT=$(node "$PLUGIN_ROOT/scripts/vault-mirror.mjs" \
+       --vault-dir "$VM_DIR" \
+       --source .orchestrator/metrics/sessions.jsonl \
+       --kind session \
+       --session-id "$SESSION_ID" \
+       ${VM_VAULT_NAME:+--vault-name "$VM_VAULT_NAME"} \
+       --quality-min-narrative-chars "$VM_QUALITY_NARRATIVE" \
+       --quality-min-confidence "$VM_QUALITY_CONFIDENCE" 2>&1)
+     VM_EXIT=$?
+
+     # Surface script output so user can see skipped-handwritten results
+     if [[ -n "$VM_OUTPUT" ]]; then
+       echo "$VM_OUTPUT"
+     fi
+
+     if [[ $VM_EXIT -ne 0 ]]; then
+       if [[ "$VM_MODE" == "strict" ]]; then
+         echo "ERROR: vault-mirror failed (exit $VM_EXIT) — session close blocked (vault-integration.mode=strict)"
+         echo "Fix the vault mirror issue or set vault-integration.mode: warn to downgrade to a warning."
+         exit 1
+       else
+         # mode: warn (default) — surface warning but do not block
+         echo "WARNING: vault-mirror exited $VM_EXIT — session metrics were NOT mirrored to the vault. Set vault-integration.mode: strict to block on this error."
+       fi
+     else
+       # Parse the destination path from the script's JSON output (one JSON line per action)
+       VM_DEST=$(echo "$VM_OUTPUT" | jq -r 'select(.action == "created" or .action == "updated") | .path' 2>/dev/null | head -1)
+       if [[ -n "$VM_DEST" ]]; then
+         echo "Mirrored session summary to $VM_DEST"
+       fi
+
+       # Quality gate summary (PRD F1.2): count entries skipped because they
+       # failed the quality filter, so the operator can tune thresholds.
+       VM_QUALITY_SKIP=$(echo "$VM_OUTPUT" | jq -rc 'select(.action == "skipped-quality-low")' 2>/dev/null | wc -l | tr -d ' ')
+       if [[ "${VM_QUALITY_SKIP:-0}" -gt 0 ]]; then
+         echo "vault-mirror: ${VM_QUALITY_SKIP} entry/entries skipped by quality gate (set vault-mirror.quality.min-narrative-chars / min-confidence to tune)"
+       fi
+     fi
+
+     # ── Durable Narrative Mirror (#675) ────────────────────────────────────
+     # Sibling of the session-mirror above, gated on the SAME vault-integration
+     # gate ($VM_ENABLED / $VM_MODE checked at the top of this block). Reads this
+     # repo's `.claude/STATE.md`, extracts the DURABLE narrative — `## Wave History`,
+     # `## Deviations`, `## What Not To Retry`, plus the mission-status rollup — and
+     # idempotently writes a generator-owned per-repo file at
+     # `<vault-dir>/01-projects/<repo-slug>/_session-narrative.md`, so a reviewer
+     # or stand-in can read PER REPO what was done, what failed, and what not to
+     # retry WITHOUT opening the repo.
+     #
+     # Idempotent + safe: NEVER touches `_overview.md` or any hand-authored file
+     # (marker-guarded via `session-orchestrator-vault-status-narrative@1`). A
+     # re-run with no STATE.md change returns `skipped-noop`; an existing
+     # non-generator file returns `skipped-handwritten`; absent STATE.md returns
+     # `skipped-no-statemd`. The helper ALSO self-no-ops (`skipped-vault-disabled`)
+     # when vault-integration is off — this gate is defense-in-depth, not the sole
+     # gate. Non-blocking: a failure surfaces a warning and never blocks close,
+     # using the same strict/warn degradation idiom as the vault-mirror step above.
+     NM_OUTPUT=$(node -e "
+       import('$PLUGIN_ROOT/scripts/lib/vault-status/narrative-mirror.mjs').then(async (m) => {
+         const r = await m.mirrorNarrative({ repoRoot: process.cwd() });
+         process.stdout.write(JSON.stringify(r));
+       }).catch((e) => { process.stderr.write(String(e && e.message || e)); process.exit(3); });
+     " 2>&1)
+     NM_EXIT=$?
+
+     if [[ $NM_EXIT -ne 0 ]]; then
+       if [[ "$VM_MODE" == "strict" ]]; then
+         echo "ERROR: narrative-mirror failed (exit $NM_EXIT) — session close blocked (vault-integration.mode=strict): $NM_OUTPUT"
+         echo "Fix the narrative mirror issue or set vault-integration.mode: warn to downgrade to a warning."
+         exit 1
+       else
+         # mode: warn (default) — surface warning but do not block
+         echo "WARNING: narrative-mirror exited $NM_EXIT — durable per-repo narrative was NOT mirrored to the vault. Set vault-integration.mode: strict to block on this error."
+       fi
+     else
+       # Surface the JSON result so the operator can see skipped-* / written outcomes.
+       NM_ACTION=$(echo "$NM_OUTPUT" | jq -r '.action // empty' 2>/dev/null)
+       NM_PATH=$(echo "$NM_OUTPUT" | jq -r '.path // empty' 2>/dev/null)
+       if [[ "$NM_ACTION" == "written" && -n "$NM_PATH" ]]; then
+         echo "Mirrored durable session narrative to $NM_PATH"
+       elif [[ -n "$NM_ACTION" ]]; then
+         echo "narrative-mirror: $NM_ACTION${NM_PATH:+ ($NM_PATH)}"
+       fi
+     fi
+   fi
+   ```
+
+   > **Repo name** is derived internally: `mirrorNarrative` defaults the per-repo slug + frontmatter `repo:` field to `path.basename(repoRoot)` when `repo` is omitted, so the call needs only `repoRoot: process.cwd()` — no shell-var plumbing. (Pass an explicit `repo:` only to override the derived basename.) The narrative mirror shares vault-dir resolution with `mirrorNarrative` itself (it reads Session Config internally), so no separate `--vault-dir` plumbing is needed here.
+
+   **Behaviour matrix:**
+
+   | `enabled` | `mode`  | Result |
+   |-----------|---------|--------|
+   | `false` or missing | any | Skip entirely — no-op, no output |
+   | `true` | `off`   | Skip entirely — no-op, no output |
+   | `true` | `warn`  | Run mirror; on failure surface a warning but do NOT block close |
+   | `true` | `strict` | Run mirror; on failure block session close with an error message |
+
+   > **Hand-written note protection:** `vault-mirror.mjs` checks for a `_generator: session-orchestrator-vault-mirror@1` marker before overwriting any existing file. When it skips an existing hand-written note it emits a JSON line `{"action":"skipped-handwritten","path":"<path>","kind":"<kind>","id":"<id>"}` — the step above surfaces this output so the user can see the result. Action names: `created`, `updated`, `skipped-noop`, `skipped-handwritten`, `skipped-collision-resolved`, `skipped-invalid` (entry failed required-field validation, or the mapper crashed rendering an otherwise-parseable record — the latter case carries `reason: "mapper-crash"`, #718), `skipped-quality-low` (entry failed quality gate — PRD F1.2; line carries a `reason` field).

package/skills/session-end/vault-operations.md

@@ -0,0 +1,50 @@
+# Phase 2.1: Vault Validation
+
+> Sub-file of the session-end skill. Executed as part of Phase 2 (Quality Gate) when `vault-sync.enabled` is `true`.
+> For the full session close-out flow, see `SKILL.md`.
+
+### 2.1 Vault Validation (if configured)
+
+Projects that maintain an Obsidian-style markdown vault can opt-in to a frontmatter + wiki-link validation gate at session close. This is gated on the `vault-sync.enabled` config flag (default `false`) — projects without a vault are unaffected. When enabled, the gate reads three more config fields (`vault-sync.mode`, `vault-sync.vault-dir`, `vault-sync.exclude`) and invokes the `vault-sync` validator. See `docs/session-config-reference.md` for field semantics, and `skills/vault-sync/SKILL.md` for the validator contract.
+
+**Gate:** Only run this subsection if `$CONFIG | jq -r '."vault-sync".enabled // false'` is `true`. If `false` or missing, skip silently.
+
+**Invocation pattern** (exact bash contract — keep in sync with `skills/vault-sync/validator.sh`):
+
+```bash
+# Read config (defaults: mode=warn, vault-dir=$PWD, exclude=[])
+VS_ENABLED=$(echo "$CONFIG" | jq -r '."vault-sync".enabled // false')
+if [[ "$VS_ENABLED" == "true" ]]; then
+  VS_MODE=$(echo "$CONFIG" | jq -r '."vault-sync".mode // "warn"')
+  VS_DIR=$(echo "$CONFIG" | jq -r '."vault-sync"."vault-dir" // empty')
+  : "${VS_DIR:=$PWD}"
+
+  # Build --exclude args from the config array (one flag per entry)
+  VS_EXCLUDE_ARGS=()
+  while IFS= read -r pat; do
+    [[ -z "$pat" ]] && continue
+    VS_EXCLUDE_ARGS+=(--exclude "$pat")
+  done < <(echo "$CONFIG" | jq -r '."vault-sync".exclude // [] | .[]')
+
+  # Invoke validator; capture JSON on stdout and exit code
+  VS_JSON=$(VAULT_DIR="$VS_DIR" bash "$PLUGIN_ROOT/skills/vault-sync/validator.sh" \
+    --mode "$VS_MODE" "${VS_EXCLUDE_ARGS[@]}" 2>/dev/null) || VS_EXIT=$?
+  VS_EXIT="${VS_EXIT:-0}"
+
+  VS_STATUS=$(echo "$VS_JSON" | jq -r '.status')
+  VS_ERR_COUNT=$(echo "$VS_JSON" | jq -r '.errors | length')
+  VS_WARN_COUNT=$(echo "$VS_JSON" | jq -r '.warnings | length')
+fi
+```
+
+**Reporting rules:**
+
+- **`mode: off`** — validator reports `status: skipped-mode-off`; include a single line "Vault validation: skipped (mode=off)" in the quality gate report and move on. Never blocks.
+- **`mode: warn`** — validator always exits 0. If `.errors | length > 0`, surface the error list in the report under "Vault validation warnings (mode=warn)" with file + path + message for each entry. Also list any `.warnings` (dangling wiki-links) in the same section. Never blocks close, but remind the user that flipping to `mode: hard` would have blocked on N files.
+- **`mode: hard`** — validator exits 1 on errors. On exit 1: do NOT block the close. Surface the full error list in the quality gate report, then default to **warn + carryover + continue** (Recommended): file a carryover issue (labels `carryover`, `priority:high`) titled `[Carryover] Vault validation (hard) — <N> frontmatter errors` capturing the offending files for a follow-up session, log a Deviation entry in STATE.md `## Deviations`, then continue the close. Offer "Override and close" (continue without a carryover issue; log the Deviation) as an alternative via AskUserQuestion. The user can also (a) fix the offending frontmatter, (b) add the file pattern to `vault-sync.exclude` if it is a legitimate index file (e.g. `_MOC.md`, `_overview.md`), or (c) temporarily set `vault-sync.mode: warn` while backfilling frontmatter across the vault. On exit 0 with warnings: include them in the report but do not block.
+- **Exit 2** (infra error — missing `node`, `pnpm`, or `validator.mjs`) — treat as a skipped gate with a loud warning ("Vault validation: infrastructure error — <reason>"). Do NOT block the session close on infra failures; the goal is to surface configuration problems, not to wedge sessions when Node is unavailable.
+
+**Success line format** (when `errors: [] && warnings: []`):
+```
+Vault validation: ok (N files checked, M excluded, mode=<mode>)
+```

package/skills/session-end/verification-checklist.md

@@ -0,0 +1,20 @@
+# Phase 2: Quality Gate — Verification Checklist
+
+> Extracted from `SKILL.md` Phase 2 to reduce skill file size. This is the authoritative source for session-end quality gate checks.
+
+Run ALL checks — do NOT skip any:
+
+> **Quality Reference:** Run Full Gate quality checks per the quality-gates skill. Read `test-command`, `typecheck-command`, and `lint-command` from Session Config (defaults: `npm test`, `npm run typecheck`, `npm run lint`).
+
+1. **Full Gate checks**: TypeScript (0 errors), tests (must pass), lint (must pass, warnings OK)
+   Alternatively, run `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/run-quality-gate.mjs" --variant full-gate --config "$CONFIG"` for deterministic quality gate execution with structured JSON output.
+   - **Stub detection:** if `result.stubbed` is non-empty, emit WARN per SKILL.md Phase 2.0a. Refer to `docs/recipes/quality-gate-container-pattern.md` for the container-PHPUnit pattern.
+2. **Git status**: `git status` → understand all changes
+3. **Uncommitted changes**: everything should be staged for commit
+4. **No debug artifacts**: search for `console.log`, `debugger`, `TODO: remove` in changed files
+5. **Vault validation** (opt-in via `vault-sync.enabled`): run the `vault-sync` validator per SKILL.md Phase 2.1. In `hard` mode, validation errors block the session close; in `warn` mode they are surfaced in the quality gate report but do not block; in `off` mode the gate is bypassed. Dangling wiki-links are always warnings only.
+
+If any check fails:
+- Fix it if quick (<2 min)
+- Otherwise create a `priority:high` issue for immediate follow-up
+- Do NOT commit broken code