session-orchestrator 3.16.0

package/skills/session-end/discovery-scan.md

@@ -0,0 +1,37 @@
+# Phase 1.5: Discovery Scan
+
+> Sub-file of the session-end skill. Executed as part of Phase 1 plan verification when `discovery-on-close` is enabled.
+> For the full session close-out flow, see `SKILL.md`.
+
+### 1.5 Discovery Scan (if enabled)
+
+Resolve the effective `discovery-on-close` value:
+
+```
+effectiveDiscoveryOnClose = config.discoveryOnClose ?? (sessionType === 'housekeeping' ? false : true)
+```
+
+- If the user has set `discovery-on-close` explicitly in Session Config, that value always wins (backward compatible).
+- If the field is absent (not configured), the default is **session-type aware**: `false` for `housekeeping`, `true` for `feature` and `deep`.
+
+If `effectiveDiscoveryOnClose` is `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 5 (triage) or Phase 6 (issue creation) — return after Phase 4.",
+  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)"

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

@@ -0,0 +1,97 @@
+# Phase 2.2: CLAUDE.md (or AGENTS.md) Drift Check
+
+> Sub-file of the session-end skill. Executed as part of Phase 2 (Quality Gate) when `drift-check.enabled` is `true`.
+> For the full session close-out flow, see `SKILL.md`. For validator contract, see `skills/claude-md-drift-check/SKILL.md`.
+> Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). All references to `CLAUDE.md` below resolve via that precedence rule; the drift checker accepts either filename.
+
+### 2.2 CLAUDE.md (or AGENTS.md) Drift Check (if configured)
+
+Projects can opt-in to a narrative-drift gate at session close. This is gated on the `drift-check.enabled` config flag (default `false`) — projects without `CLAUDE.md`/`AGENTS.md` or `_meta/` narrative are unaffected. When enabled, the gate reads the `drift-check.mode`, `drift-check.include-paths`, and all `drift-check.check-*` flags and invokes the `claude-md-drift-check` validator. See `docs/session-config-reference.md` for field semantics, and `skills/claude-md-drift-check/SKILL.md` for the validator contract.
+
+The checks are complementary to `vault-sync` (Phase 2.1): vault-sync validates frontmatter and wiki-links inside the vault tree; drift-check validates narrative claims, surface counts, generated-rule freshness, and rule-scoping contracts in top-level repo docs.
+
+**Gate:** Only run this subsection if `$CONFIG | jq -r '."drift-check".enabled // false'` is `true`. If `false` or missing, skip silently.
+
+**Invocation pattern** (exact bash contract — keep in sync with `skills/claude-md-drift-check/checker.sh`):
+
+```bash
+DC_ENABLED=$(echo "$CONFIG" | jq -r '."drift-check".enabled // false')
+if [[ "$DC_ENABLED" == "true" ]]; then
+  DC_MODE=$(echo "$CONFIG" | jq -r '."drift-check".mode // "warn"')
+
+  # Build --include-path args from the config array (one flag per entry)
+  DC_INCLUDE_ARGS=()
+  while IFS= read -r pat; do
+    [[ -z "$pat" ]] && continue
+    DC_INCLUDE_ARGS+=(--include-path "$pat")
+  done < <(echo "$CONFIG" | jq -r '."drift-check"."include-paths" // [] | .[]')
+
+  # Build per-check skip flags (checks default to true; add --skip-* when false)
+  DC_SKIP_ARGS=()
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-path-resolver" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-path-resolver)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-project-count-sync" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-project-count)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-issue-reference-freshness" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-issue-refs)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-session-file-existence" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-session-files)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-command-count" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-command-count)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-session-config-parity" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-session-config-parity)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-vault-dir-parity" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-vault-dir-parity)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-generated-rule-staleness" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-generated-rule-staleness)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-rule-scoping" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-rule-scoping)
+  [[ "$(echo "$CONFIG" | jq -r '."drift-check"."check-docs-parity" // true')" == "false" ]] && DC_SKIP_ARGS+=(--skip-docs-parity)
+
+  # Invoke checker; capture JSON on stdout and exit code
+  DC_EXIT=0
+  DC_JSON=$(VAULT_DIR="$PWD" bash "$PLUGIN_ROOT/skills/claude-md-drift-check/checker.sh" \
+    --mode "$DC_MODE" "${DC_INCLUDE_ARGS[@]}" "${DC_SKIP_ARGS[@]}" 2>/dev/null) || DC_EXIT=$?
+
+  DC_STATUS=$(echo "$DC_JSON" | jq -r '.status // "infra-error"')
+  DC_ERR_COUNT=$(echo "$DC_JSON" | jq -r '.errors // [] | length')
+  DC_WARN_COUNT=$(echo "$DC_JSON" | jq -r '.warnings // [] | length')
+fi
+```
+
+`$PLUGIN_ROOT` resolution follows the same fallback chain as `skills/_shared/config-reading.md`.
+
+**Reporting rules:**
+
+- **`mode: off`** — checker reports `status: skipped-mode-off`; include a single line "CLAUDE.md drift: skipped (mode=off)" in the quality gate report. Never blocks.
+- **`mode: warn`** — checker always exits 0. If `.errors | length > 0`, surface the list in the report under "CLAUDE.md drift warnings (mode=warn)" with check + file:line + message for each entry. Also list any `.warnings` (e.g. `#NN` the checker could not resolve via glab). Never blocks close; note that `mode: hard` would have routed the same errors through the carryover path below.
+- **`mode: hard`** — checker exits 1 on errors. On exit 1: do NOT block the close. Surface the full error list, then default to **warn + carryover + continue** (Recommended): file a carryover issue (labels `carryover`, `priority:high`) titled `[Carryover] CLAUDE.md drift (hard) — <E> errors` capturing the drift items 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 drift directly in `CLAUDE.md` (or `AGENTS.md` on Codex CLI) / `_meta/`, or (b) temporarily set `mode: warn` while backfilling, or (c) disable a specific check via its `check-*` flag if it reports false positives on this codebase.
+- **Exit 2** (infra error — missing `node`, unreadable `VAULT_DIR`, malformed args) — treat as a skipped gate with a loud warning ("CLAUDE.md drift: infrastructure error — <reason>"). Do NOT block the session close on infra failures.
+
+**Exit-code dispatch:** The checker writes infra-error JSON to stderr (suppressed by `2>/dev/null` above), so `DC_JSON` is empty when `DC_EXIT == 2`. Always branch on `DC_EXIT` first, then `DC_STATUS`:
+
+```bash
+if [[ "$DC_EXIT" == "2" ]]; then
+  # infra error — DC_JSON is empty, stderr was suppressed. Surface loud warning, do not block.
+elif [[ "$DC_STATUS" == "invalid" && "$DC_MODE" == "hard" ]]; then
+  # hard-mode: surface + warn + carryover + continue (no hard block — #724)
+elif [[ "$DC_STATUS" == "invalid" ]]; then
+  # warn-mode report
+else
+  # ok / skipped — emit success line
+fi
+```
+
+**Partial-skip awareness:** The checker may report `checks_skipped` in its JSON output even on successful runs. Common causes: `glab` not on PATH (Check 3 degrades gracefully), no `01-projects/` directory (Check 2 inapplicable). Surface these in the report as informational lines, not errors:
+
+```
+CLAUDE.md drift: ok (N files scanned, mode=<mode>)
+  - Skipped: issue-reference-freshness (glab not found in PATH)
+```
+
+**Success line format** (when `errors: [] && warnings: []`):
+
+```
+CLAUDE.md drift: ok (N files scanned, mode=<mode>)
+```
+
+**Error line format** (hard mode, carryover):
+
+```
+CLAUDE.md drift: INVALID (mode=hard) — E errors, W warnings across N files
+  [path-resolver]       CLAUDE.md:L — <message>
+  [project-count-sync]  CLAUDE.md:L — <message>
+  [issue-reference-freshness] CLAUDE.md:L — <message>
+  [session-file-existence]    _meta/foo.md:L — <message>
+```

package/skills/session-end/learning-patterns.md

@@ -0,0 +1,78 @@
+# Phases 3.5a + 3.6: Learning Extraction and Memory Cleanup
+
+> 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.5a Learning Extraction
+
+> Gate: Only run if `persistence` is enabled in Session Config.
+
+Analyze the completed session to extract reusable learnings for future sessions.
+
+**What to extract:**
+- **Fragile files**: use `git log --name-only --format="" $SESSION_START_REF..HEAD | sort | uniq -c | sort -rn | head -10` to find files changed most frequently across commits this session. Files appearing in 3+ commits are candidates for fragile-file learnings. Cross-reference with `<state-dir>/STATE.md` Wave History to correlate with specific waves.
+- **Effective sizing**: actual agent count vs. planned — what worked for this complexity level
+- **Recurring issues**: same issue type appearing across waves (e.g., type errors, missing imports)
+- **Scope guidance**: was the scope too large/small? How many issues fit comfortably in one session?
+- **Deviation patterns**: read the `## Deviations` section from `<state-dir>/STATE.md` — were there plan adaptations? What triggered them? Extract as `deviation-pattern` type if a pattern emerges across sessions (e.g., "scope expansion during Impl-Core is common for this project")
+
+**Learning format** (append each as one JSONL line to `.orchestrator/metrics/learnings.jsonl`):
+```json
+{
+  "schema_version": 1,
+  "id": "<uuid-v4>",
+  "type": "fragile-file|effective-sizing|recurring-issue|scope-guidance|deviation-pattern|stagnation-class-frequency",
+  "subject": "<what the learning is about>",
+  "insight": "<the actionable insight>",
+  "evidence": "<what happened this session>",
+  "confidence": 0.5,
+  "source_session": "<session_id>",
+  "created_at": "<ISO 8601>",
+  "expires_at": "<ISO 8601 + learning-expiry-days (default: 30)>"
+}
+```
+
+**Schema versioning** (`schema_version`, introduced 2026-04):
+- All new records MUST carry `schema_version: 1`. `scripts/lib/learnings.mjs` auto-stamps missing values on append/rewrite so callers can omit the field safely.
+- Records without `schema_version` are treated as `schema_version: 0` (pre-versioning legacy). They are read and validated successfully for backward compat, but the reader emits a one-line WARN to stderr flagging the missing tag.
+- Both `schema_version: 0` and `schema_version: 1` pass `validateLearning`. Any other value is rejected.
+
+**Confidence updates for existing learnings:**
+Before writing new learnings, read `.orchestrator/metrics/learnings.jsonl` and check for existing entries with the same `type` + `subject` (exact string match on both fields):
+- If this session **confirms** an existing learning: note the update — increment `confidence` by +0.15 (cap at 1.0) and reset `expires_at` to current date + `learning-expiry-days` (default: 30)
+- If this session **contradicts** an existing learning: note the update — decrement `confidence` by -0.2
+- If no existing match: note as a new learning with confidence 0.5
+
+**File I/O strategy:** Track all updates in memory during extraction. Do NOT modify `learnings.jsonl` here — Phase 3.6 handles the actual file write. Pass these data structures to Phase 3.6:
+- `confidence_updates`: list of `{id: "<existing_learning_id>", operation: "confirm"|"contradict"}`
+- `new_learnings`: list of complete learning objects (all JSONL fields per the format above)
+
+> ⚠️ **NEVER point a validating writer at the live store to "test" it.** `rewriteLearnings` performs an atomic, destructive replace — validating the input does NOT protect the file that is being overwritten. On 2026-07-02 a coordinator probe ran the validator against the live `learnings.jsonl` and the subsequent atomic rewrite replaced 107 entries with 3; because the store is gitignored there was no VCS restore (recovered only via the `.bak` sidecar + vault-mirror). To probe a live store safely, use the dry-run path — `rewriteLearnings(file, entries, { dryRun: true })` validates the batch and returns the validated entries but writes NOTHING (no rewrite, no `.bak`). Since #721, a real `rewriteLearnings` also snapshots the current file to `${file}.bak-<ISO>` (keep 3) before the rename, so an accidental overwrite is recoverable — but the dry-run path is still the correct tool for a probe.
+
+**Subject matching:** Match on exact `type` + `subject` string equality. For `fragile-file`, `subject` is the file path. For other types, use a short canonical identifier (e.g., `type-errors-in-api`, `scope-too-large`, `missing-imports`).
+
+### 3.6 Memory Cleanup & Learnings Write
+
+> Gate: Only run if `persistence` is enabled in Session Config.
+
+1. Count session memory files matching `session-*.md` in the memory directory
+2. If count exceeds `memory-cleanup-threshold` (default: 5), suggest:
+   "You have [N] session memory files. Consider running `/memory-cleanup` to consolidate."
+3. This is a suggestion only — not blocking
+4. **Write learnings** to `.orchestrator/metrics/learnings.jsonl` (if file exists or new learnings were extracted):
+   a. Read all existing lines from `learnings.jsonl` (if exists)
+   b. Apply confidence updates from Phase 3.5a (confirmed: +0.15 capped at 1.0 AND reset `expires_at` to current date + `learning-expiry-days` (default: 30); contradicted: -0.2)
+   c. Append new learnings from Phase 3.5a (those with no existing match)
+   d. **Passive decay (#89)** — for every existing learning NOT touched this session (i.e., not in the set of learnings confirmed or contradicted in Phase 3.5a, and not newly appended in step c), subtract `learning-decay-rate` (from Session Config, default `0.05`) from its `confidence`. Clamp to 0.0 (do not produce negative values). The prune step in `e` will remove any entry that fell to `confidence <= 0.0`. Decay does NOT reset `expires_at` — let decayed entries continue to age naturally. If `learning-decay-rate` is `0.0`, skip this step entirely (opt-out).
+
+      | Sessions since last touch | Confidence (starting 0.5, decay 0.05) | Status |
+      |---|---|---|
+      | 0 | 0.50 | active |
+      | 5 | 0.25 | active |
+      | 9 | 0.05 | active |
+      | 10 | 0.00 | pruned next write |
+
+   e. Prune: remove entries where `expires_at` < current date OR `confidence` <= 0.0
+   f. Consolidate duplicates (same `type` + `subject`): keep the one with highest confidence
+   g. Write the entire result back to `learnings.jsonl` (atomic rewrite with `>`, not append with `>>`)
+   h. If no existing file and no new learnings: skip

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

@@ -0,0 +1,175 @@
+# Phase 1.7: Metrics Collection
+
+> Sub-file of the session-end skill. Executed as part of Phase 1 when `persistence` is enabled.
+> For the full session close-out flow, see `SKILL.md`.
+
+### 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. Read `.orchestrator/metrics/events.jsonl` **once** and build both event aggregates in a single pass. If the file does not exist, treat both aggregates as zero events (omit both fields per the rules below) — do NOT fail the session close.
+
+   Filter all lines where `session == <session_id>`, then partition by `event` value:
+
+   ```bash
+   jq -s --arg sid "$SESSION_ID" '
+     [.[] | select(.session == $sid)]
+     | {
+         stagnation: [.[] | select(.event == "stagnation_detected")],
+         grounding:  [.[] | select(.event == "orchestrator.grounding.injected")]
+       }
+   ' .orchestrator/metrics/events.jsonl
+   ```
+
+   From the `stagnation` array, aggregate into `stagnation_events`:
+   - `total`: count of entries in the array
+   - `by_pattern`: count by `pattern` value (omit zero-valued keys)
+   - `by_error_class`: count by `error_class` value (omit zero-valued keys; omit entire sub-object if all entries lack `error_class`)
+   - `files`: unique list of non-null `file` values (deduplicated)
+   - **Omit the entire `stagnation_events` field if `total == 0`** (keeps historical entries clean).
+
+   From the `grounding` array, aggregate into `grounding_injections`:
+   - `count`: total number of entries in the array
+   - `files`: deduplicated list of unique file paths from the entries (sort alphabetically)
+   - `total_lines`: sum of `lines` field across all entries
+   - **Omit the entire `grounding_injections` field if `count == 0`** (matches stagnation_events pattern to keep historical entries clean).
+
+   > **Per-category zero-match rule:** If the `stagnation` array is empty but the `grounding` array is non-empty (or vice versa), omit only the zero-match field — the other field is still populated normally. The single read handles both cases; no second file read is needed.
+4. 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 that bypass `Date.parse`-only validators). 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, planned_files_count?, over_delivery_ratio?} */],
+     // effectiveness is CONSTRUCTED EXPLICITLY (#773) — NOT left as an optional
+     // field for the coordinator to remember. Leaving it optional is exactly how
+     // the carryover=0 blind spot recurred (41/41 records read carryover:0).
+     // `carryover` = the Phase 1.65 gate carry-list length (see counting rules
+     // below), NOT the raw Phase 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>,
+       // override_ratio: <0.0-1.0>,  // OPTIONAL (#730/H5) — add ONLY when Phase 2.6 ran; OMIT otherwise (absent = "not measured")
+     },
+     // Handover-gate open-question telemetry (#773) — top-level, additive,
+     // non-negative integers. OMIT (do not write 0) when the gate did not run an
+     // interactive triage (fail-open skip / headless / fast-path): absent = "not
+     // measured", 0 = "measured zero".
+     open_questions_asked: <N>,      // surfaced in Phase 1.65 AUQ Call 2
+     open_questions_answered: <N>,   // operator answered
+     open_questions_deferred: <N>,   // left `- [ ]`, roundtripped to next session
+     // Other optional fields below — populate per the Conditional Fields rules at
+     // the bottom of this file; OMIT (do not write null) when the gating
+     // condition is not met.
+   };
+   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", "planned_files_count": N, "over_delivery_ratio": 0.0},
+       ...
+     ],
+     "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,
+       "override_ratio": 0.0
+     },
+     "open_questions_asked": N,
+     "open_questions_answered": N,
+     "open_questions_deferred": N,
+     "grounding_injections": {
+       "count": N,
+       "files": ["..."],
+       "total_lines": M
+     },
+     "stagnation_events": {
+       "total": N,
+       "by_pattern": {"error-echo": N, "turn-key-repetition": N, "pagination-spiral": N},
+       "by_error_class": {"edit-format-friction": N, "scope-denied": N, "command-blocked": N, "other": N},
+       "files": ["<relative path>", "..."]
+     }
+   }
+   ```
+
+   > **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.
+
+> 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 4.6 for schema). When discovery runs in **embedded mode** (Phases 0-4 only), `user_dismissed`, `issues_created`, and `actioned` per category will always be `0` — embedded mode does not perform user triage (Phase 5) or issue creation (Phase 6).
+> - `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, and CONSTRUCTED EXPLICITLY in the METRICS_ENTRY snippet (#773) — never deferred to a "remember to add" optional step (that omission is how `carryover: 0` slipped past 41 records). `completion_rate` = `completed / planned_issues` (0.0-1.0, where 0.0 means nothing was completed). **`carryover` counting rule (#773):** `carryover` is the **length of the Phase 1.65 gate carry-list** — `autoCarry` ∪ the middle-band `ask` items the operator LEFT SELECTED ∪ the answered-question `impliesWork: true` candidates — NOT the raw Phase 1.2+1.3 candidate count. On the fail-open skip (gate disabled / headless / AUQ unavailable), EVERY candidate carries, so `carryover` = the full candidate-list length. Count the gate's OUTPUT (what reaches Phase 5 Step 3 filing), not its INPUT.
+> - `effectiveness.override_ratio` (#730/H5): OPTIONAL nested field = `overridden_findings / max(total_findings_surfaced, 1)` (float 0.0-1.0). Populate ONLY when Phase 2.6 (Broken-Window Budget) ran this session (`broken-window-budget.enabled: true`). OMIT (do NOT write null/0) otherwise — **absent = "not measured"**, `0.0` = "measured, nothing overridden". `overridden_findings` = the summed `count` of the `orchestrator.finding.overridden` events emitted this session; `total_findings_surfaced` = every MED/LOW+ finding surfaced across Phase 1.8 + wave reviewers.
+> - `waves[].planned_files_count` / `waves[].over_delivery_ratio` (#730/H4): OPTIONAL per-wave fields, populated from STATE.md Wave History headers of the form `(planned <P> files → actual <A>, over-delivery <R>)` (written by wave-executor §3a since #730/H4); omit when absent (pre-#730 sessions / grounding-check: false).
+> - `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_*` payload fields on the `orchestrator.handover.gated` event). Top-level, additive, non-negative integers. Populate ONLY when the gate ran an interactive triage ("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". Validator accepts absent/null/non-negative-integer.
+> - `stagnation_events`: populated ONLY when ≥1 stagnation event was logged to `events.jsonl` during this session. When `total == 0`, the field is omitted from the JSONL entry.
+> - `grounding_injections`: populated ONLY when ≥1 `orchestrator.grounding.injected` event was logged to `events.jsonl` during this session. When `count == 0`, the field is omitted from the JSONL entry.
+> - `memory_cleanup_at`: populated whenever `/memory-cleanup` ran **THIS session** in ANY mode — dry-run, apply-pending, OR healthy no-op (MEMORY.md already healthy, no files mutated). Set `memory_cleanup_at = completed_at` so the auto-dream cadence marker (`readDreamSignals` → `lastCleanupAt`) advances and `shouldDispatchAutoDream` does not fire a false nudge. **A no-op is still a cleanup; the cadence marker MUST advance.** Use `stampMemoryCleanup(record, { ranCleanup: true, completedAt: record.completed_at })` from `scripts/lib/memory-cleanup-stamp.mjs` — this is the testable, no-throw seam that applies the stamp. Omit the field (do NOT set it to null) when `/memory-cleanup` did not run this session. (#699)

package/skills/session-end/phase-3-2-docs-verification.md

@@ -0,0 +1,148 @@
+# Phase 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`.
+
+> Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). The Dev audience target listed below resolves to whichever file the repo uses.
+
+## Step 1 — Load docs-tasks SSOT
+
+Read `docs-tasks` from STATE.md frontmatter. This field is written by wave-executor Pre-Wave 1b when `docs-orchestrator.enabled: true` and session-plan emitted a `### Docs Tasks (machine-readable)` block.
+
+Use `scripts/lib/state-md.mjs` to parse the frontmatter safely — do NOT re-implement YAML parsing inline. Example accessor:
+
+```bash
+node --input-type=module -e "
+import {readFileSync} from 'node:fs';
+import {parseFrontmatter} from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
+const raw = readFileSync('<state-dir>/STATE.md', 'utf8');
+const fm = parseFrontmatter(raw);
+const tasks = fm['docs-tasks'];
+if (!Array.isArray(tasks)) { process.stdout.write('ABSENT'); process.exit(0); }
+process.stdout.write(JSON.stringify(tasks));
+"
+```
+
+**Fallback — missing field:** If `docs-tasks` is absent from frontmatter, attempt to re-parse the session-plan output's `### Docs Tasks (machine-readable)` YAML fenced block from conversation context. This is degraded but functional.
+
+**No tasks found at all:** Log `"ℹ docs-orchestrator enabled but no docs-tasks persisted — skipping verification"` in the session report and skip Phase 3.2 entirely. This is NOT an error.
+
+**Silent-failure guard:** If STATE.md is unreadable, if frontmatter YAML is malformed, or if `docs-tasks` is present but not a list — these MUST produce an explicit error entry in the session final report. Do NOT skip silently:
+```
+⚠ Phase 3.2: docs-tasks parse error — <reason>. Manual docs verification required.
+```
+
+## Step 2 — Read SESSION_START_REF
+
+Read `session-start-ref` from STATE.md frontmatter. Full accessor and fallback chain are documented in `plan-verification.md § SESSION_START_REF accessor`. Summary:
+- Primary: `session-start-ref` field in STATE.md frontmatter.
+- Fallback: `git diff --name-only origin/main...HEAD` (no specific base SHA).
+
+If `git diff` itself fails (network issue, corrupt repo), log:
+```
+⚠ Phase 3.2: git diff failed — <stderr>. Docs verification skipped.
+```
+and skip Phase 3.2. This is an explicit error, not a silent skip.
+
+## Step 3 — Compute changed files
+
+```bash
+CHANGED_FILES=$(git diff --name-only "$SESSION_START_REF..HEAD")
+```
+
+Cache this list for the per-task loop below. If the command exits non-zero, surface the error per the guard above and skip Phase 3.2.
+
+## Step 4 — Audience → file-pattern reference
+
+The following mini-table mirrors `skills/docs-orchestrator/audience-mapping.md` (authoritative source — consult it for updates):
+
+| Audience | Target file patterns |
+|----------|----------------------|
+| `user` | `README.md`, `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md` |
+| `dev` | `CLAUDE.md` (or `AGENTS.md` on Codex CLI), `docs/dev/**/*.md`, `docs/adr/**/*.md` |
+| `vault` | `<vault>/01-projects/<slug>/context.md`, `<vault>/01-projects/<slug>/decisions.md`, `<vault>/01-projects/<slug>/people.md` |
+
+Each `docs-task` carries its own `target-pattern` field (set during session-plan Step 1.8, derived from the audience-mapping table above). Use `task.target-pattern` as the primary match target; the table above is for human reference and fallback when `target-pattern` is absent.
+
+## Step 5 — Per-task verification loop
+
+For each `task` in `docs-tasks`:
+
+1. **Resolve target:** glob-match `task.target-pattern` against the cached `CHANGED_FILES` list.
+
+2. **Not matched → GAP:**
+   - No file matching `task.target-pattern` appears in the diff.
+   - Record outcome: `gap`.
+
+3. **Matched → inspect diff:**
+   ```bash
+   git diff "$SESSION_START_REF..HEAD" -- <matched-file>
+   ```
+   - **Substantive content change** (non-whitespace, non-comment-only lines added/removed): outcome `ok`.
+   - **Whitespace-only or structural-only diff** (no prose or code content changed): outcome `gap`.
+   - **File contains `<!-- REVIEW: source needed -->` markers within changed regions:** outcome `partial`. This means content was written but requires human review before release. `partial` does NOT block in strict mode — it is always a warning, by policy choice. Document both the `ok` content and the markers in the report.
+
+4. Record `{id, audience, target-pattern, wave, status: ok|partial|gap}` for the aggregate report.
+
+## Step 6 — Aggregate and report per mode
+
+Read `docs-orchestrator.mode` from Session Config (default: `warn`).
+
+**`mode: warn`** (default, non-blocking):
+- Append a subsection to the Phase 6 Final Report (see below).
+- `/close` proceeds regardless of gap count.
+
+**`mode: strict`** (surfaces an AUQ on any gap; default = warn + carryover + continue — never hard-blocks):
+- If ALL tasks are `ok` or `partial`: proceed — append report, continue close.
+- If ANY task is `gap`:
+  - **Claude Code:** use `AskUserQuestion` with these options (mark Recommended):
+    ```
+    Phase 3.2 found documentation gaps. How would you like to proceed?
+    1. Warn + carryover and close (Recommended)
+    2. Override — close session with gaps (deviations logged)
+    ```
+  - **Codex CLI / Cursor fallback:** render a numbered Markdown list:
+    ```markdown
+    ## Phase 3.2: Documentation Gaps Detected (mode=strict)
+
+    Choose one:
+    1. **Warn + carryover and close** *(Recommended)*
+    2. Override — close session with gaps (deviations will be logged)
+
+    Gap tasks: <list task IDs and target-patterns>
+    ```
+  - On "Warn + carryover and close": file a carryover issue (labels `carryover`, `priority:high`) titled `[Carryover] Documentation gaps (strict) — <gap-count> tasks` listing the gap task IDs + target-patterns for a follow-up session, log the deviation (below), then append the report and continue the close.
+  - On "Override": log a deviation in the `## Deviations` section of STATE.md:
+    ```
+    - [Phase 3.2] docs-orchestrator strict-mode gaps overridden by user. Tasks: <ids>. Timestamp: <ISO 8601>.
+    ```
+    Then append the report and proceed with close.
+
+**`mode: off`:** This path is not reached because the Phase gate at the top of 3.2 exits early for `mode: off`. Documented here for completeness.
+
+## Step 7 — Documentation Coverage report block
+
+Emit the following block to be included in Phase 6 Final Report under `### Documentation Coverage (docs-orchestrator)`:
+
+```
+### Documentation Coverage (docs-orchestrator)
+
+Mode: <warn|strict>
+Tasks verified: <total>
+
+| Task ID | Audience | Target pattern | Wave | Status |
+|---------|----------|----------------|------|--------|
+| <id>    | <user|dev|vault> | <pattern> | <N> | ✅ ok / ⚠ partial / ❌ gap |
+...
+
+Summary: <N> ok, <N> partial (REVIEW markers present — human review needed before release), <N> gap
+```
+
+For `partial` tasks, append a note per task:
+```
+⚠ <target-pattern>: contains <!-- REVIEW: source needed --> markers — content written but not fully source-cited. Review before release.
+```
+
+For `gap` tasks in warn mode, append:
+```
+ℹ Gap tasks were not addressed. No docs-writer output found for these patterns. Consider scheduling in a follow-up session.
+```