session-orchestrator 3.17.0 → 3.19.0

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

@@ -8,11 +8,13 @@
 Resolve the effective `discovery-on-close` value:
 
 ```
-effectiveDiscoveryOnClose = config.discoveryOnClose ?? (sessionType === 'housekeeping' ? false : true)
+effectiveDiscoveryOnClose = config.discoveryOnClose ?? 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 the field is absent (not configured), the default is `true` for **every** session type.
+
+**Why this is no longer session-type aware (2026-07-29).** The previous default was `false` for `housekeeping` and `true` for `feature`/`deep`, on the theory that housekeeping is lightweight and does not need a scan. Measurement inverted that theory: a read-only diagnostic run of the housekeeping flow across six real consumer repos found the discovery probes are the only substantial project-hygiene surface in the whole system — session-start Phase 4 runs 13 probes, of which exactly two (`ci-status`, `project-hygiene`) inspect the project rather than this tool's own substrate. Defaulting the scan OFF for housekeeping meant the one session type whose entire purpose is cleanup was also the only one running without hygiene diagnostics. Repos that genuinely want the faster close still set `discovery-on-close: false` explicitly, which continues to win.
 
 If `effectiveDiscoveryOnClose` is `false`, skip this section.
 

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

@@ -55,8 +55,8 @@ fi
 **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.
+- **`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: strict` would have routed the same errors through the carryover path below.
+- **`mode: strict`** (legacy alias `hard`, normalized to `strict` at parse time — #217) — 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 (strict) — <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`:
@@ -64,8 +64,8 @@ fi
 ```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" && ( "$DC_MODE" == "strict" || "$DC_MODE" == "hard" ) ]]; then
+  # strict-mode (legacy alias `hard`): surface + warn + carryover + continue (no hard block — #724)
 elif [[ "$DC_STATUS" == "invalid" ]]; then
   # warn-mode report
 else

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

@@ -169,6 +169,19 @@ Finalize session metrics by reading the wave data accumulated during execution:
 > - `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).
+> - `waves[].suite_passed` / `waves[].suite_failed` / `waves[].suite_platform` (#944): OPTIONAL per-wave fields. Omit all three when absent — absent = "not measured", `suite_failed: 0` = "measured, zero failures".
+>   **`suite_passed` / `suite_failed`: read the event FIRST, the STATE.md header only as fallback (#966 step 3).** Since #954/#967 the between-waves gate wrapper `scripts/run-quality-gate.mjs` emits `orchestrator.quality_gate.{passed,failed}` with a machine-measured `counts: {passed, failed, total}` AND the `wave_number` it resolved from the `wave-scope.json` sidecar, so per-wave attribution needs no wall-clock window join. Payload fields are flat at the record's top level; for each wave `N` of this session:
+>
+>   ```bash
+>   jq -c --argjson w N --arg s "<semantic_session_id>" '
+>     select(.event | startswith("orchestrator.quality_gate."))
+>     | select(.semantic_session_id == $s and .wave_number == $w and .counts != null)
+>     | .counts' .orchestrator/metrics/events.jsonl | tail -1
+>   ```
+>
+>   Filtering by `semantic_session_id` is mandatory — `events.jsonl` accumulates across sessions and every past session also had a wave `N`. Take the LAST matching record (the wave's final gate run); `counts.passed` → `suite_passed`, `counts.failed` → `suite_failed`. No match = the field was not measured for that wave → omit, never zero-fill (the producer already omits `counts` rather than zero-filling when a run fail-fast'd before the test gate).
+>   **Fallback, still live:** when no event matches, fall back to the STATE.md Wave History header `— suite <passed>/<failed> on <platform>` (written by wave-executor §3a since #944). Three cases genuinely need it: pre-#954 sessions, a gate run outside the `run-quality-gate.mjs` wrapper, and the `verification-auto-fix` producer in `scripts/lib/quality-gate.mjs`, which emits `counts` but no `wave_number` (its records are mid-wave retries, so not matching the selector is correct).
+>   **`suite_platform` has no event source at all** and is read from the STATE.md header, unchanged. **Remaining work to retire the prose path fully:** (1) carry the platform on the gate event payload; (2) once a session has landed with the event path green and no fallback hits, drop the hand-written trio from `wave-loop.md` step 7. Until both hold, the trio stays written — deleting the writer before the reader is proven loses the numbers for sessions in flight.
 > - `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.

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

@@ -110,7 +110,7 @@ Read `docs-orchestrator.mode` from Session Config (default: `warn`).
 
     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 "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>.

package/skills/session-end/phase-3-6-tail.md

@@ -241,7 +241,7 @@ After the auto-dialectic nudge decision is made (Phase 3.6.7), and when the reco
 
 #### Coordinator-direct procedure
 
-1. Read Session Config: `reconcile.enabled` (default `false`), `reconcile['rule-expiry-days']` (default `null` — falls back to per-type TTL in the engine), `reconcile['confidence-floor']` (default `0.5`), `reconcile['min-rule-days']` (default `7` — floor window (days) applied to a proposed rule's `expires-at` so a near-dead or already-elapsed natural expiry never produces a born-dead rule, issue #741.1), `reconcile['min-insight-chars']` (default `24` — opt-in minimum insight length gating the eligibility placeholder-insight check, issue #741.2). If `reconcile.enabled` is not `true`, log `reconcile: disabled (reconcile.enabled=false)` and skip all remaining steps.
+1. Read Session Config: `reconcile.enabled` (default `false`), `reconcile['rule-expiry-days']` (default `null` — falls back to per-type TTL in the engine), `reconcile['confidence-floor']` (default `0.5`), `reconcile['min-rule-days']` (default `7` — floor window (days) applied to a proposed rule's `expires-at` so a near-dead or already-elapsed natural expiry never produces a born-dead rule, issue #741.1), `reconcile['min-insight-chars']` (default `24` — opt-in minimum insight length gating the eligibility placeholder-insight check, issue #741.2), `reconcile['max-proposals-per-run']` (default `10` — volume brake, issue #900 D; the engine sorts eligible learnings by confidence DESC and proposes at most this many per run). If `reconcile.enabled` is not `true`, log `reconcile: disabled (reconcile.enabled=false)` and skip all remaining steps.
 
 2. Invoke `runReconcile` from `scripts/lib/reconcile/engine.mjs`:
 
@@ -252,6 +252,7 @@ After the auto-dialectic nudge decision is made (Phase 3.6.7), and when the reco
      ruleExpiryDays: config.reconcile['rule-expiry-days'] ?? undefined,
      minRuleDays: config.reconcile['min-rule-days'] ?? undefined,
      minInsightChars: config.reconcile['min-insight-chars'] ?? undefined,
+     maxProposalsPerRun: config.reconcile['max-proposals-per-run'] ?? undefined,
      now: new Date(),
    });
    ```

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

@@ -43,13 +43,16 @@ Compare the files the plan said would be touched against the files actually chan
    - 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:
+
+   > **Scope-drift cross-reference:** the S2 warn-only drift tripwire (below) uses its own separately-maintained filter list — `DRIFT_EXCLUDE_PATTERNS` in `scripts/lib/scope-baseline.mjs` — and is NOT derived from the filters above. That list is the shared filter source for both sides of its ratio IN CODE: `writeBaseline()`'s denominator (`countPlannedFiles()`) and `computeDrift()`'s numerator both call the same internal `filterExcluded()` helper (#894 review finding F1 — previously only the numerator was code-filtered; the denominator relied on a coordinator prose instruction to pre-filter before calling `writeBaseline()`, which is why three earlier PRD revisions shipped a tripwire that read a wrong ratio).
+5. **Report** in the verification output. Also call `computeDrift({ repoRoot, threshold: 2.0 })` (`scripts/lib/scope-baseline.mjs`) and append its result — warn-only, informational, never blocks close:
    ```
    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]
+   - Scope drift: filesRatio X.X (Y actual / Z planned, threshold 2.0) — [breached | ok | skipped: <reason>]
    ```
 6. **Append to session metrics** (`grounding` field in the Phase 1.7 JSONL entry):
    ```json
@@ -66,7 +69,7 @@ Compare the files the plan said would be touched against the files actually chan
 - 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`
+  - Labels: `priority::<original>`, `status:ready`
   - Description: what's done, what's left, context for next session
 - Link to original issue if applicable
 

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

@@ -41,7 +41,7 @@ fi
 
 - **`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.
+- **`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: []`):

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

@@ -16,5 +16,5 @@ Run ALL checks — do NOT skip any:
 
 If any check fails:
 - Fix it if quick (<2 min)
-- Otherwise create a `priority:high` issue for immediate follow-up
+- Otherwise create a `priority::high` issue for immediate follow-up
 - Do NOT commit broken code

package/skills/session-plan/SKILL.md

@@ -180,7 +180,7 @@ For each task from Step 1, assign exactly one role. Use these signal-to-role map
 **Disambiguation rules:**
 - If a task involves BOTH exploration AND implementation → split it: Discovery agent reads/validates, Impl-Core agent implements. Create two separate task entries.
 - If a task is "fix something from a previous session" (not from this session's Impl-Core) → classify as **Impl-Core** (it is new work for this session).
-- If a task is "write tests for new feature code being built this session" → classify as **Quality** (not Impl-Core). Tests run after implementation.
+- A "write tests for new feature code being built this session" task is created ONLY when Discovery or a qa-strategist run reported a **named gap** — a concrete bug or regression the current suite would let through, stated as such. When that gap exists, classify the task as **Quality** (not Impl-Core); tests run after implementation. "Feature X was built" is NOT by itself evidence of test demand: with no named gap, no Quality task is created — do not synthesize one to give the role something to do. A dispatched `test-writer` may correspondingly report `no-tests-needed` as a SUCCESS status, not a failure.
 - If unsure between Impl-Core and Impl-Polish → if the task is on the critical path (other tasks depend on it), it is **Impl-Core**. If independent polish, it is **Impl-Polish**.
 - **Docs role** is only active when `docs-orchestrator.enabled: true` in Session Config. When disabled (default), documentation-update tasks fall into **Impl-Polish** (inline doc changes alongside code) or **Finalization** (standalone doc/SSOT updates) as today.
 
@@ -359,7 +359,7 @@ When `docs-orchestrator.enabled: true`, apply the following concrete dispatch ru
 - Output: Validated understanding, updated task scope if discoveries warrant it
 - Tools: Read, Grep, Glob, Bash (read-only commands only) — do NOT use Edit or Write
 - Scope enforcement: set `allowedPaths` to `[]` (empty) for Discovery waves. Include in agent prompts: "You are READ-ONLY. Do NOT use Edit or Write tools."
-- Distributional claims MUST follow `.claude/rules/parallel-sessions.md` § PSA-006 — quote the executed grep pattern + file scope + count. Coordinators REJECT Discovery outputs that assert "N of M" or "100% of X" without a quoted grep transcript (deep-1647 W1-D3 incident class).
+- Distributional claims AND bare repo-state numbers MUST follow `.claude/rules/parallel-sessions.md` § PSA-006 — quote the executed command + file scope + count + WHEN it was measured. Coordinators REJECT Discovery outputs that assert "N of M" / "100% of X" (deep-1647 W1-D3 incident class) or a bare count like "14 commits" / "92 learnings" (#908) without that evidence. Discovery facts age: re-verify a count before re-briefing it into a later wave.
 
 **Impl-Core**
 - Full implementation agents with Write/Edit/Bash access
@@ -422,6 +422,10 @@ Score the session scope to determine optimal agent counts per wave. Skip for hou
 
 > Housekeeping sessions skip Discovery (tasks are predefined) and use fixed agent counts regardless of complexity.
 
+> **The Quality column is a CAP, not a target.** Every other column sizes to briefed work; the Quality column historically sized to the tier alone, so capacity went looking for work (tests written because a slot existed, not because a gap was measured). Quality capacity must be EARNED by measured demand. Compute the effective count as `min(<tier cap>, ceil((HIGH + MED gaps from the most recent qa-strategist run) / 3))`.
+> - **0 HIGH and 0 MED gaps → the Quality role has 0 test-writing tasks**, and its wave is skipped by the Step 2 empty-role rule. This does NOT touch the read-only review panel (security-reviewer / qa-strategist / architect-reviewer) — that panel reviews, it does not write tests, and it keeps running as configured.
+> - **No qa-strategist signal at all** (no prior measurement this session): allocate a conservative 1-2 test-writers. Never spend the full tier cap blind — an unmeasured tier cap is a guess, and the guess has historically been too high.
+
 The `agents-per-wave` Session Config value caps the maximum regardless of tier.
 
 If project intelligence (learnings) suggests different sizing based on historical data, prefer the historical recommendation over the formula.

package/skills/session-plan/wave-template.md

@@ -32,6 +32,8 @@ For each wave, define agents with:
 
 Read `agents-per-wave` from Session Config to cap the maximum.
 
+> **The Quality column is a CAP, not a target.** Quality capacity is need-gated: the effective count is `min(<column cap>, ceil((HIGH + MED gaps from the most recent qa-strategist run) / 3))`. 0 gaps → 0 test-writing tasks and the wave is skipped (the read-only review panel is unaffected); no qa-strategist signal at all → a conservative 1-2, never the blind cap. Full rule: `SKILL.md` § Agent Count by Tier footnote.
+
 > **Note:** For feature and deep sessions, prefer the complexity-based agent counts from Step 3. This table provides defaults when complexity scoring is skipped (housekeeping) or as a fallback.
 
 > \* Housekeeping sessions use single-wave serial execution (see wave-executor). Agent counts are for the single consolidated wave, not per-role.

package/skills/session-start/SKILL.md

@@ -339,6 +339,7 @@ Reset rules — applies ONLY on the `completed` branch. Do NOT perform this rese
    ```
 
    Omit individual bullets for null-valued fields. If all 5 are null (i.e., `parseRecommendations` returned non-null but every field is null after type-coercion), skip the archival block entirely.
+7. **Scope-baseline key deletion (Epic #894 S5, #898):** If ANY of the 5 `scope-baseline-*` frontmatter keys (`scope-baseline-intent`, `scope-baseline-owner-boundary`, `scope-baseline-planned-files`, `scope-baseline-session`, `scope-baseline-frozen-at`) is present, remove them via the same `updateFrontmatterFields(contents, {field: null, ...})` mechanism as rule 6 (null value deletes the key). Rule 5 leaves unknown frontmatter fields intact and no other rule removes these five — without this step they survive into session N+1 and silently corrupt the next session's drift-baseline denominator. This is a hygiene layer only: the primary defense is mechanical — `scripts/lib/scope-baseline.mjs` compares `scope-baseline-session` against the canonical `session` field, so a stale baseline self-invalidates (`readBaseline()` returns `{stale: true, …}`) even if this rule were skipped. Delete exactly these five keys; do not remove any other unknown key.
 
 Rationale: `/close` intentionally keeps STATE.md as a record so the next session-start can read it. This reset completes that contract by demoting the record before new session state is written, so a fresh session never appears "already completed". The Recommendation archival (rule 6) preserves the session-to-session handoff in a human-readable form after the Recommendations Banner has rendered — Phase B's Mode-Selector will read the LIVE frontmatter of the current session and does not need the archived copy, so this is purely informational for humans browsing STATE.md history.
 
@@ -489,22 +490,36 @@ This is **best-effort**, exactly like the Phase 4 banners: a board-write failure
 Run these checks as ONE parallel Bash block — background the independent git ops with `&` and `wait`:
 
 ```bash
+# Refresh remote-tracking refs BEFORE reading them. Without this, `origin/main`
+# is a snapshot from the last fetch or clone, and every ahead/behind derivation
+# below silently compares against stale data — a repo can read "in sync" while
+# the real remote is many commits ahead. Best-effort and non-blocking: connect
+# timeouts are bounded (no `timeout(1)` — it is absent on macOS by default) and
+# any failure (offline, no remote, auth prompt) falls through to `|| true`,
+# leaving the previous behaviour of reading whatever refs are on disk.
+GIT_SSH_COMMAND='ssh -o ConnectTimeout=5 -o BatchMode=yes' \
+  git -c http.lowSpeedLimit=1000 -c http.lowSpeedTime=5 \
+  fetch --quiet --prune 2>/dev/null || true
+
 # Independent ops — launch in parallel, collect output via tmpfiles
 git branch -a > /tmp/so-branches.$$ &
 git log --oneline -N > /tmp/so-commits.$$ &        # N from Session Config `recent-commits` (default 20)
 git status --short > /tmp/so-status.$$ &
-git log origin/main..HEAD --oneline > /tmp/so-ahead.$$ &
+# `--left-right --count A...B` emits "<behind>\t<ahead>": commits reachable only
+# from origin/main, then only from HEAD. The older `git log origin/main..HEAD`
+# form could express ahead ONLY, so "behind" was structurally unreportable.
+git rev-list --left-right --count origin/main...HEAD > /tmp/so-divergence.$$ 2>/dev/null &
 wait
 # Then read the 4 tmpfiles in a single step and derive: branch state, recent commits,
 # unpushed/uncommitted, open branches. Clean up tmpfiles once derivations are done:
-rm -f /tmp/so-branches.$$ /tmp/so-commits.$$ /tmp/so-status.$$ /tmp/so-ahead.$$
+rm -f /tmp/so-branches.$$ /tmp/so-commits.$$ /tmp/so-status.$$ /tmp/so-divergence.$$
 ```
 
 Checks to run (derived from the collected output):
 
-1. **Branch state**: current branch (from `branch -a`), ahead/behind origin (from `ahead` tmpfile)
+1. **Branch state**: current branch (from `branch -a`), ahead/behind origin (from the `divergence` tmpfile — field 1 is behind, field 2 is ahead). Report BOTH directions. A non-zero behind count means the local branch is missing remote work: surface it, because agents reading repo instructions from a stale checkout will follow superseded guidance. An empty `divergence` tmpfile means no `origin/main` ref resolved (no remote, or a differently-named default branch) — report that as unknown, never as zero.
 2. **Recent commits**: parse `commits` tmpfile — identify last session's work by commit patterns
-3. **Unpushed/uncommitted**: `status` tmpfile + `ahead` tmpfile combined
+3. **Unpushed/uncommitted**: `status` tmpfile + the ahead field of the `divergence` tmpfile combined
 4. **Open branches**: parse `branch -a` tmpfile, identify which are mergeable to develop/main
 5. **Stale branches**: run AFTER the parallel block — requires iterating over branches (depends on `branch -a` output). Use `git log -1 --format=%ct <branch>` per branch; flag those with no commits in more than `stale-branch-days` (default: 7) days.
 
@@ -635,7 +650,7 @@ Using the detected VCS CLI, query (reading `issue-limit` from Session Config, de
 5. **Pipeline/CI status** — is CI green?
 
 Group issues by:
-- `priority:critical` / `priority:high` — must-address
+- `priority::critical` / `priority::high` — must-address
 - `status:ready` — ready to work on
 - Session-type relevance (housekeeping tasks vs feature tasks vs deep-work tasks)
 
@@ -667,7 +682,8 @@ Group issues by:
 
    Additionally, if the current repo has a configured `origin` remote and `glab` (GitLab) or `gh` (GitHub) is available, invoke the CI-status probe (`scripts/lib/ci-status-banner.mjs`) via `checkCiStatus({ repoRoot: process.cwd() })`. The helper returns `null` (silent no-op) when no VCS remote, no CLI tool, parse failure, or CLI timeout (8s default). When `result.status === 'red'`, render a banner alongside the bootstrap-lock and vault-staleness warnings:
    - **Red** (`status === 'red'`): `"🚨 CI RED on HEAD (pipeline #<currentPipelineId>) — last green: #<lastGreen.pipelineId> (commit <SHA-7>, <redCount> pipelines ago). Failing job: <failingJobName>"`
-   - **Green** or **unknown**: silent (no banner) — informational only.
+   - **Green with soft failures** (`status === 'green'` AND `result.allowFailureJobs` is present): `"⚠ CI green on HEAD, but <N> allow_failure job(s) FAILED: <names>. A pipeline reports success regardless of these — a job red on every run stays invisible at the pipeline level."` Render this even though the pipeline passed: the whole point is that pipeline status cannot express it.
+   - **Green** (no `allowFailureJobs`) or **unknown**: silent (no banner) — informational only.
 
    The banner is non-blocking — display in the Session Overview, do not halt the session. If `ci-status-banner.mjs` is absent (pre-#369 plugin install), skip silently.
 
@@ -707,6 +723,23 @@ Group issues by:
 
    Non-blocking. Cross-reference: `scripts/lib/session-lock.mjs` (`readLock`, `DEFAULT_TTL_HOURS` — the current session's lock `started_at` is the self-exclusion cutoff), `scripts/backfill-abandoned-sessions.mjs` (the backfill CLI the message recommends) and issue #724.
 
+   **The backfill is mechanical since #926 — the banner's CLI hint is a fallback, not the primary path.** `hooks/on-session-start.mjs` calls `backfillOnSessionStart()` from `scripts/backfill-abandoned-sessions.mjs` on every SessionStart, which **applies** (writes) the reconstructed stubs rather than only previewing them. This decouples recovery from `/close`: `hooks/on-session-end.mjs` also backfills, but SessionEnd fires only on a REGULAR close, so a session killed by Ctrl-C, a timeout, or a crash left no ledger record until the NEXT clean close — which may never come (observed: this repo's ledger 18.9h behind events.jsonl across 8 commits). Running at start means the *next* session recovers the previous one, whatever killed it.
+
+   Four properties make that safe to run unattended on every start:
+   - **Idempotent.** Dedupe against sessions.jsonl plus an atomic `wx` marker file; repeated starts write nothing new. Synthetic ids are derived from the session's own `started_at` + a sha256 of its UUID, so they are stable across runs.
+   - **Self-excluding.** It runs BEFORE this session emits `orchestrator.session.started`, so the starting session is not a candidate at all. On a clear/compact/resume re-fire (where an earlier started-event *is* present) the core's `skipped-own-live-lock` guard catches it against the lock bootstrapped moments earlier.
+   - **Foreign-safe.** Lock ownership is evaluated against the CANDIDATE, not the running process: a candidate holding a live lock returns `skipped-own-live-lock` before the `relaxDeadByAge` (#731) relaxation is consulted. A running foreign session is therefore never recorded as `abandoned`. Residual, accepted: a live session that does NOT hold the lock (it lost the acquire race) AND has emitted no event for longer than `DEFAULT_TTL_HOURS` (4h) can still be relaxed past — a candidate the system's own liveness model already treats as dead.
+   - **Bounded + non-blocking.** Capped at `SESSION_START_LIMIT` (25) core calls, walked newest-first so the budget reaches the recent abandoned sessions rather than being spent on ancient already-recorded ones; **measured median 845ms** (5 steady-state runs: 713/835/845/921/984) on a 1.7MB events.jsonl / 187-candidate store, coordinator-verified 2026-07-30. Treat that as the cost this adds to every session start — it is roughly a second, not a rounding error, and it scales with the events ledger rather than the candidate count. Every failure is swallowed — a backfill error can never block a session start. Operator escape hatch: `SO_DISABLE_STARTUP_BACKFILL=1`.
+
+   When the run reports `truncated: true` (more candidates than the per-start budget), the remainder is picked up by subsequent starts; `node scripts/backfill-abandoned-sessions.mjs --dry-run` remains the way to inspect the full backlog, and `--apply` the way to drain it in one pass.
+
+   Additionally, invoke the sessions-integrity probe (`scripts/lib/sessions-integrity-banner.mjs`) via `checkSessionsIntegrity({ repoRoot })` (synchronous — no await). Where sessions-staleness above detects records that were never written, this detects records that WERE written but are schema-invalid — appended by a path that bypassed `scripts/emit-session.mjs` (which validates and would have refused). The loss is otherwise silent: `scripts/vault-mirror.mjs` reports such a record as `{"action":"skipped-invalid"}` on stdout and still exits 0, so the affected sessions simply have no vault note and nobody is told. Deliberately un-gated by Session Config (like `project-hygiene`) — a check nobody enables finds nothing. It returns `null` (silent no-op) when `.orchestrator/metrics/sessions.jsonl` is absent, empty, unreadable, or holds no parseable JSON line, and when every parseable record satisfies both validators; unparseable lines are skipped rather than reported (this probe judges schema integrity, not file corruption). The probe reports TWO populations, because measurement showed neither validator's failure set contains the other (this repo, 2026-07-31, 203 records: 3 vs 12, overlapping in only 2) — `validateSession()` treats `effectiveness` as optional while vault-mirror requires it, so reporting one alone would hide the other. The vault-mirror population is measured by invoking the real render path in a try/catch, never by re-deriving its field list. When a non-null result is returned (`{ severity, message, total, schemaInvalid, mirrorSkipped }`), render `result.message` alongside the other banners:
+   - **warn** (records fail `validateSession()` but all still mirror — corruption without loss): `"⚠ sessions-integrity: <N> of <M> records fail validateSession (<ids>) — records were appended without passing scripts/emit-session.mjs …"`
+   - **alert** (at least one record is dropped by vault-mirror — those sessions have no vault note right now): same message with a `🚨` prefix and an appended `"; <N> are dropped by vault-mirror as skipped-invalid — those sessions have NO vault note (<ids>)"` clause.
+   - **Fully valid ledger**: silent (no banner).
+
+   Non-blocking. Note the remedy is a re-emit of the affected records through `scripts/emit-session.mjs`, not an edit of the ledger by hand. Cross-reference: `scripts/lib/session-schema/validator.mjs` (`validateSession` — the canonical write-path schema), `scripts/lib/vault-mirror/render-sessions.mjs` (the render path whose throw becomes `skipped-invalid`), `skills/session-end/session-metrics-write.md` (the prose prohibition this banner backstops), `hooks/pre-bash-sessions-ledger-guard.mjs` (the write-guard half) and GitLab issue #958.
+
    Additionally, invoke the owner-config probe (`scripts/lib/owner-config-banner.mjs`) via `checkOwnerConfig()` (synchronous — no await, no `repoRoot` argument: the probe reads the host-wide `owner.yaml`, not a per-repo file). The helper returns `null` (silent no-op) on a clean load, when `owner.yaml` is simply absent, or on any internal read/parse error. When a non-null result is returned (`{ severity: 'warn', message, droppedSections?, sectionWarnings?, discarded? }`), render `result.message` alongside the other banners:
    - **Optional section(s) dropped to defaults** (`droppedSections` present): an OPTIONAL object section (`paths`, `dispatcher`) was malformed and replaced by its default value.
    - **Whole file discarded** (`discarded: true`): a REQUIRED section (`owner`, `tone`, `efficiency`, `hardware-sharing`) was invalid, so the entire file was discarded and defaults are in effect.
@@ -726,7 +759,31 @@ Group issues by:
 
    Non-blocking. Cross-reference: `scripts/lib/gitlab-portfolio/vcs-detect.mjs` (`discoverVaultRepos` — the canonical "registered" definition), `scripts/lib/config/context-coverage.mjs` (`_parseContextCoverage`), and issue #831.
 
-   All banners are non-blocking — display in the Session Overview, do not halt the session. If `bootstrap-lock-freshness.mjs` is absent (pre-#186 plugin install) or `peer-cards/staleness-banner.mjs` is absent (pre-#503 plugin install) or `loop-readiness-banner.mjs` is absent (pre-#633 plugin install) or `instruction-budget-guard.mjs` is absent (pre-#687 plugin install) or `reconcile-nudge-banner.mjs` is absent (pre-#723 plugin install) or `sessions-staleness-banner.mjs` is absent (pre-#724 plugin install) or `owner-config-banner.mjs` is absent (pre-#820 plugin install) or `moc-staleness-banner.mjs` / `context-coverage-banner.mjs` are absent (pre-#831 plugin install), skip silently.
+   Additionally, invoke the CLAUDE.md budget-lint probe (`scripts/lib/claude-md-budget-lint.mjs`) via `checkClaudeMdBudgetLint({ repoRoot })` (synchronous — no await). This is a **warn-only** probe — its result is rendered, never gated; the underlying `lintClaudeMd()`/CLI exit-code contract (0/1/2, `--mode hard` by default) belongs to the standalone bootstrap-time lint (`skills/bootstrap/SKILL.md` § Step 2c) and is NEVER invoked here. The helper returns `null` (silent no-op) when no CLAUDE.md/AGENTS.md resolves under `repoRoot`, when the resolved file has zero violations, or on any read/parse failure. When a non-null result is returned (`{ severity: 'warn', message }`), render `result.message` alongside the other banners:
+   - **Violations found**: `"⚠ CLAUDE.md budget lint: <N> violation(s) (<rule names>) in <file> — run \`node scripts/lib/claude-md-budget-lint.mjs --mode warn\` for details."` — `<rule names>` is the de-duplicated set of violated rule ids (`max-lines`, `max-line-chars`, `provenance-header`) present in the file.
+   - **Clean file / no instruction file**: silent (no banner).
+
+   Non-blocking. Cross-reference: `scripts/lib/instruction-budget-guard.mjs` (sibling directive-COUNT probe over `.claude/rules/*.md` — this probe measures raw-file PROPERTIES of CLAUDE.md/AGENTS.md itself, a distinct dimension) and issue #878 (FA2b).
+
+   Additionally, invoke the tests:src-ratio probe (`scripts/lib/tests-src-ratio.mjs`) via `checkTestsSrcRatio({ repoRoot })` (synchronous — no await). It returns `null` (silent no-op) when the ratio is inside the TV-003 corridor, when `repoRoot` is missing, or on any measurement failure. When a non-null result is returned (`{ severity: 'warn', message, ratio, ceiling }`), render `result.message` alongside the other banners.
+
+   **Why this is a banner and not a gate.** `.claude/rules/test-value.md` § TV-003 names the ceiling as the trigger for a CONSOLIDATION wave — the rule's operative instrument. Before this wiring the trigger fired into a void: the only references were two rule files asking a human to run the command, so the condition could be true for months with nothing saying so (it was true, at 1.70, on the commit that introduced the script). The rule's refusal of a bidirectional ratchet stands unchanged — this surfaces the trigger, it does not block on it. `--check` remains deliberately unwired from CI.
+
+   Non-blocking. Cross-reference: `.claude/rules/test-value.md` § TV-003 (the corridor rule and why a ratchet was rejected), `.claude/rules/testing.md` § Coverage Enforcement (the 70% floor that binds independently), and issue #930.
+
+   Additionally, invoke the project-hygiene probe family (`scripts/lib/project-hygiene.mjs`) via `checkProjectHygiene({ repoRoot })` (synchronous — no await). **This is the only probe in Phase 4 besides `ci-status` that inspects the PROJECT rather than the orchestrator's own substrate** — every other probe above measures vault, peer-cards, loop readiness, instruction budget, or this tool's own ledger. It is deliberately NOT config-gated: a hygiene check nobody enables finds nothing, which is how the equivalent coverage was lost before (see `skills/session-end/discovery-scan.md` — the discovery scan defaults OFF for exactly the `housekeeping` session type that most needs it).
+
+   The helper returns `null` (silent no-op) when `repoRoot` is missing/non-string, when the path is not a git repository, or when every check passes. When a non-null result is returned (`{ severity: 'warn', message, findings, mechanical }`), render `result.message` alongside the other banners:
+   - **Findings present**: render the message verbatim. It already leads with the count and the mechanically-fixable subset, then names the top 3 and summarises the remainder — this shape was chosen because a flat list stops being read past roughly 25 findings.
+   - **Healthy repo**: silent (no banner).
+
+   Use `result.mechanical` when proposing session scope: findings with `fixable: true` (aged artifacts, ignored ballast, a missing CI audit step) are safe batch work, while the rest (release cadence, absent CI, undocumented configuration) need an operator decision and belong in the Q&A, not in an auto-fix batch.
+
+   The checks are: release-tag/CHANGELOG distance from HEAD, ignored working-tree ballast plus files that are neither tracked nor ignored, aged `.orchestrator/` artifacts, CI pipeline presence and dependency-audit coverage, and `.env.example` presence. Two high-yield checks are intentionally NOT here: **docs-drift** is already covered by `claude-md-drift-check` (it only runs at session-END, so the gap is scheduling, not implementation), and **env completeness** is omitted because diffing `process.env` reads against `.env.example` produced a 100% false-positive rate against code that reads configuration through a central schema module.
+
+   Non-blocking. Cross-reference: `scripts/lib/ci-status-banner.mjs` (the sibling project-facing probe) and `.claude/rules/test-value.md` § TV-005 (why structural gates beat unit-test volume).
+
+   All banners are non-blocking — display in the Session Overview, do not halt the session. If `bootstrap-lock-freshness.mjs` is absent (pre-#186 plugin install) or `peer-cards/staleness-banner.mjs` is absent (pre-#503 plugin install) or `loop-readiness-banner.mjs` is absent (pre-#633 plugin install) or `instruction-budget-guard.mjs` is absent (pre-#687 plugin install) or `reconcile-nudge-banner.mjs` is absent (pre-#723 plugin install) or `sessions-staleness-banner.mjs` is absent (pre-#724 plugin install) or `sessions-integrity-banner.mjs` is absent (pre-#958 plugin install) or `owner-config-banner.mjs` is absent (pre-#820 plugin install) or `moc-staleness-banner.mjs` / `context-coverage-banner.mjs` are absent (pre-#831 plugin install) or `claude-md-budget-lint.mjs` is absent (pre-#878 plugin install), skip silently.
 
 ## Phase 4.5: Resource Health (v3.1.0)
 
@@ -1028,6 +1085,15 @@ Cross-reference: GitLab #845 (Epic #841); `docs/prd/2026-07-20-anonymous-usage-t
 - Focus on git cleanup, documentation currency, CI health
 - Skip deep research — prioritize operational tasks
 - Run token efficiency check: `bash "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/token-audit.sh"` and include findings in Session Overview. Flag any HIGH/WARN items as recommended housekeeping tasks.
+- **Run the drift check as a work-list, not as a gate:**
+  ```bash
+  node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/skills/claude-md-drift-check/checker.mjs" --mode warn
+  ```
+  `--mode warn` always exits 0 and returns findings as JSON — it must never block session-start. Summarise `errors[]` and `warnings[]` by check name in the Session Overview and offer them as candidate scope in the Phase 8 Q&A.
+
+  **Why here and not only at close.** The same checker already runs at session-end (`skills/session-end/SKILL.md` Phase 2), where it verifies the work just done. That is the wrong moment to *discover* drift: doc-vs-reality drift was the single most frequently confirmed finding in the six-repo diagnostic run (6 of 6 repos), and a housekeeping session that only learns about it at close cannot act on it. Running it at the start turns it into the session's work-list. It is deliberately scoped to `housekeeping` — for `feature`/`deep` sessions this list is a distraction from the agreed scope, and the close-time run still covers them.
+
+  **Read the output critically.** In a consumer repo the checker reported 69 errors of which zero concerned that repo — all were dangling `## See Also` citations inside vendored, never-curated baseline rule copies. Before proposing any of it as scope, check whether a finding points at repo-owned content or at vendored files; report the split rather than the raw count.
 
 ## Phase 7.1: Issue Premise Verification (#730/H3)
 

package/skills/session-start/phase-4-5-resource-health.md

@@ -10,7 +10,10 @@ Read `.orchestrator/host.json` (written by `hooks/on-session-start.mjs`) and run
 // Conceptual — the wave-executor and session-plan skills call these directly.
 import { probe, evaluate } from '$PLUGIN_ROOT/scripts/lib/resource-probe.mjs';
 const snapshot = await probe();
-const verdict = evaluate(snapshot, config['resource-thresholds']);
+const verdict = evaluate(snapshot, config['resource-thresholds'], {
+  heavyRepo: config['heavy-repo'],
+  agentsPerWave: config['agents-per-wave'],
+});
 ```
 
 The `evaluate()` result has three fields:
@@ -18,16 +21,20 @@ The `evaluate()` result has three fields:
 - `reasons`: array of human-readable explanations
 - `recommended_agents_per_wave_cap`: integer cap (0 = coordinator-direct) or null
 
+The third `options` argument is optional (HR-003/HR-004, baseline #60) — when `config['heavy-repo']` is `true`, the cap is forced to at most `config['agents-per-wave']` regardless of the live verdict (static preflight ceiling; more-restrictive-wins against whatever the resource signals already computed). Omitting `options` entirely preserves pre-#60 behaviour.
+
 ## Adaptive Rules (default thresholds; configurable via `resource-thresholds`)
 
 | Signal | Threshold | Action |
 |--------|-----------|--------|
 | RAM free below `ram-free-min-gb` (default 4) | warn | Cap `agents-per-wave` at 2 |
 | RAM free below `ram-free-critical-gb` (default 2) | critical | Recommend coordinator-direct (0 agents) |
-| CPU load above `cpu-load-max-pct` (default 80) sustained | warn | Cap `agents-per-wave` at 2 |
+| CPU load above `cpu-load-max-pct` (default 80) sustained — judged on **min(1m, 5m)** load average (#943) | warn | Cap `agents-per-wave` at 2 |
 | Claude processes ≥ `concurrent-sessions-warn` (default 5) | warn | Warn; suggest sequencing or waiting |
 | SSH session detected AND `ssh-no-docker: true` | info | Append note: host is SSH-attached, Docker-dependent steps should run on a local dev host |
 
+**CPU methodology (#943):** the gate/probe runs right after the coordinator's own CPU-saturating quality-gate run by construction, so the 1-minute load average systematically carries that decaying tail (observed: 96% → 75% within 36s). `probe()` therefore also emits `cpu_load_5m` / `cpu_load_5m_pct`, and `evaluate()` + `evaluateWaveResourceGate()` judge the CPU threshold on **min(1m, 5m)**: only-1m-high is reported as an informational "decaying transient" reason without capping; both-high (genuine sustained load) still caps. When `cpu_load_5m_pct` is `null` (Windows, zero-load), judging falls back to the 1m-derived `cpu_load_pct` alone.
+
 ## Presentation
 
 Print a one-line Resource Health verdict immediately after Phase 4's output:
@@ -36,6 +43,12 @@ Print a one-line Resource Health verdict immediately after Phase 4's output:
 Resource Health: ⚠ warn — RAM free 3.1 GB below threshold 4 GB; capping agents-per-wave at 2.
 ```
 
+When `config['heavy-repo']` is `true` and the HR-004 preflight ceiling actually reduces `recommended_agents_per_wave_cap` below what the live verdict alone would have produced, print an additional banner line right after the verdict line:
+
+```
+⚠ Heavy-repo mode active — agents-per-wave capped to 4 (Session Config heavy-repo: true)
+```
+
 When verdict is `warn` or `critical`, use the AskUserQuestion tool to present:
 1. **Proceed as recommended** (apply the cap) — Recommended
 2. **Proceed as originally planned** (user accepts the risk)

package/skills/test-runner/SKILL.md

@@ -201,8 +201,8 @@ If the glab query fails, log the error and proceed with an empty fingerprint set
 
 | Severity | Action |
 |----------|--------|
-| `critical` | Auto-create issue — no AUQ. Label: `from:test-runner,priority:critical` |
-| `high` | Auto-create issue — no AUQ. Label: `from:test-runner,priority:high` |
+| `critical` | Auto-create issue — no AUQ. Label: `from:test-runner,priority::critical` |
+| `high` | Auto-create issue — no AUQ. Label: `from:test-runner,priority::high` |
 | `medium` | Batched AUQ triage (see below) |
 | `low` | Batched AUQ triage (see below) |
 

package/skills/vault-sync/validator.mjs

@@ -62,6 +62,7 @@ import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import YAML from 'yaml';
 import { resolveInstructionFile } from '../../scripts/lib/common.mjs';
+import { findSessionConfigBlock } from '../../scripts/lib/config/section-extractor.mjs';
 import {
   computeSchemaHash,
   writeBaseline,
@@ -296,18 +297,38 @@ function isExcluded(relPath) {
 // Returns true if dir contains at least one recognized vault marker:
 //   1. _meta/ directory
 //   2. CLAUDE.md or AGENTS.md (alias — see skills/_shared/instruction-file-resolution.md)
-//      containing both "## Session Config" and "vault-sync:". The instruction
-//      file is resolved via resolveInstructionFile() so CLAUDE.md wins ties and
-//      AGENTS.md is accepted on Codex CLI repos.
+//      whose `## Session Config` block declares a `vault-sync:` key. The
+//      instruction file is resolved via resolveInstructionFile() so CLAUDE.md
+//      wins ties and AGENTS.md is accepted on Codex CLI repos.
 //   3. .obsidian/ directory
+//
+// Marker 2 was two whole-file substring tests until #968:
+//   content.includes('## Session Config') && content.includes('vault-sync:')
+// A substring test is the wrong instrument for "does this directory look like
+// a vault" in three independent ways, all reachable:
+//   (a) `'### Session Config'.includes('## Session Config')` is TRUE (from
+//       index 1), so an H3 — or any deeper heading — passed the marker.
+//       HTML comment matched. Any document ABOUT session-orchestrator config
+//       reads as a vault marker.
+//   (b) A `## Session Config` mention in ordinary prose (not at line start)
+//       matched, e.g. "see the ## Session Config block" mid-sentence.
+//   (c) `vault-sync:` was accepted ANYWHERE in the file — a prose sentence or
+//       a doc-comment sufficed; it never had to be a config key, let alone one
+//       inside the Session Config block.
+// Misclassifying a directory as a vault is not cosmetic: it makes the
+// validator crawl and enforce vault frontmatter over an arbitrary tree, and
+// (via the cwd branch below) silently adopt it as VAULT_DIR.
+//
+// The fix uses the SSOT block extractor, so the heading must be a real
+// heading LINE and `vault-sync:` must be a key INSIDE that block.
 function isVaultDir(dir) {
   if (existsSync(join(dir, '_meta')) && statSync(join(dir, '_meta')).isDirectory()) return true;
   if (existsSync(join(dir, '.obsidian')) && statSync(join(dir, '.obsidian')).isDirectory()) return true;
   const instr = resolveInstructionFile(dir);
   if (instr) {
     try {
-      const content = readFileSync(instr.path, 'utf8');
-      if (content.includes('## Session Config') && content.includes('vault-sync:')) return true;
+      const block = findSessionConfigBlock(readFileSync(instr.path, 'utf8'));
+      if (block && /^\s*(?:-\s+)?(?:\*\*)?vault-sync(?:\*\*)?\s*:/m.test(block.body)) return true;
     } catch {
       // unreadable instruction file — not a vault marker
     }
@@ -446,7 +467,85 @@ function parseFrontmatter(raw) {
 }
 
 // ── Wiki-link regex — captures link body for target parsing ─────────────────
-const WIKILINK_RE = /\[\[([^\]]+)\]\]/g;
+// NOTE: intentionally NOT module-level. A shared `/g` regex driven by
+// `.exec()` in a loop carries `lastIndex` state across calls; the previous
+// module-level `WIKILINK_RE` was safe only because the loop always ran to
+// exhaustion (never an early return/continue). Constructing a fresh regex
+// per `extractWikiLinks()` call removes that hazard structurally rather than
+// relying on "the loop happens to always finish" (#852).
+function wikilinkRegex() {
+  return /\[\[([^\]]+)\]\]/g;
+}
+
+// ── Code-span stripping (#852, hardened post-review) ────────────────────────
+// A wikilink written as inline code (`` `[[target]]` ``) or inside a fenced /
+// indented code block is pedagogical prose ABOUT the Obsidian wiki-link
+// convention (#159 pattern: keep named invariants in backticks), not a real
+// link, and must never surface a dangling-wiki-link warning. All span kinds
+// are blanked out (non-newline chars -> space, newlines preserved) BEFORE the
+// wikilink regex runs, so their `[[...]]` content is invisible to
+// extractWikiLinks() while line count / offsets stay stable for any future
+// position-aware consumer.
+//
+// NOTE: intentionally functions, not module-level `/g` regex constants. Every
+// call below builds a fresh RegExp so no shared `lastIndex` state can leak
+// across calls (same rationale as wikilinkRegex() above, #852).
+//
+// Order: fenced blocks (multi-line) -> indented code blocks (line-based) ->
+// inline spans (single/double backtick, same line only). Fenced blocks run
+// first because they are the only multi-line shape; the other two are
+// line-local and their relative order does not change the result (a line
+// already blanked by an earlier pass is all-spaces and matches idempotently
+// under either later pass).
+//
+// Fenced-block fix (post-#852 QA review): the ORIGINAL `/```[\s\S]*?```/g`
+// paired ANY two ``` runs in the whole file — including a ``` merely
+// MENTIONED mid-sentence in prose — which silently blanked (and hid dangling
+// links inside) everything between an unrelated mention and the next real
+// fence. Real CommonMark fences must open at the START of a line (up to 3
+// leading spaces); this regex is now line-anchored so a mid-line mention can
+// never open a fence. The closing fence must reuse the SAME fence character
+// (backtick vs tilde) with a run of at least 3 — `(?:\1){3,}` repeats the
+// single captured fence character, so a backtick fence cannot be closed by a
+// tilde run or vice versa. Also handles `~~~` fences and fenced blocks that
+// carry an info string (e.g. ```` ```md ````) — the info string is just the
+// rest of the opening line, already consumed by `[^\n]*`.
+function fencedCodeRegex() {
+  return /^ {0,3}(`|~)\1{2,}[^\n]*\n[\s\S]*?^ {0,3}(?:\1){3,}[ \t]*$/gm;
+}
+
+// Indented code blocks (4+ leading spaces, or a leading tab) are CommonMark
+// code too. Required to be flanked by a blank line (or start/end of text) on
+// both sides — mirrors CommonMark's "separated from surrounding paragraph
+// text" rule closely enough to avoid blanking ordinary 4-space-indented list
+// continuation text that isn't actually a code block, while still catching
+// the FP shape this fixes.
+function indentedCodeRegex() {
+  return /(?<=^|\n\n)(?: {4,}|\t)[^\n]*(?:\n(?: {4,}|\t)[^\n]*)*/g;
+}
+
+// Inline code spans: single-backtick (`` ` `` ... `` ` ``) or double-backtick
+// (`` `` `` ... `` `` ``, used when the wrapped content itself contains a
+// backtick) delimiters, same line only. The closing delimiter must be the
+// SAME LENGTH as the opening one (`\1` backreference on the captured 1-2
+// backtick run) so a double-backtick span isn't mis-closed by the first lone
+// backtick inside its own content — the over-strip hazard called out in
+// #852. A lone/stray backtick with no same-length partner on the same line
+// therefore matches nothing and is left as plain text.
+function inlineCodeRegex() {
+  return /(`{1,2})[^\n]*?\1(?!`)/g;
+}
+
+function blank(match) {
+  return match.replace(/[^\n]/g, ' ');
+}
+
+function stripCodeSpans(text) {
+  let out = text.replace(fencedCodeRegex(), blank);
+  out = out.replace(indentedCodeRegex(), blank);
+  out = out.replace(inlineCodeRegex(), blank);
+  return out;
+}
 
 function findAliasSeparatorIndex(linkBody) {
   for (let i = 0; i < linkBody.length; i++) {
@@ -463,9 +562,11 @@ function extractWikiLinkTarget(linkBody) {
 }
 
 function extractWikiLinks(content) {
+  const stripped = stripCodeSpans(content);
   const targets = new Set();
+  const re = wikilinkRegex();
   let m;
-  while ((m = WIKILINK_RE.exec(content)) !== null) {
+  while ((m = re.exec(stripped)) !== null) {
     const target = extractWikiLinkTarget(m[1]);
     if (target.length > 0) targets.add(target);
   }

package/skills/wave-executor/SKILL.md

@@ -246,7 +246,7 @@ Each agent prompt MUST include:
 2. **Full context**: file paths, current code structure, issue description. If a bite-sized executable plan exists at `docs/plans/<feature>.md` for the wave's tasks (see `skills/write-executable-plan/SKILL.md`), include the path in each agent's prompt and instruct the agent to follow the plan's 5-step structure verbatim.
 3. **Acceptance criteria**: measurable definition of done
 4. **Rule references**: the wave's applicable rules are injected automatically as the `<APPLICABLE-RULES>` block produced by `scripts/print-applicable-rules.mjs` (see `wave-loop.md` § "Pre-Dispatch: Glob-Scoped Rule Injection (#336/#694)"). The block is computed once per wave from the wave's `allowedPaths` and prepended to every agent prompt — do not hand-copy rule paths into the prompt.
-5. **Testing expectation**: "Write tests for your changes" or "Run existing tests"
+5. **Testing expectation** (need-gated): "Before writing any test, name the concrete bug a NEW test would catch that the existing suite does not. No nameable bug → write NO test and report `no-tests-needed: <reason>` — that is a SUCCESS outcome, not a gap. With a nameable bug: exactly one test for it. Running existing tests is always mandatory."
 6. **Commit instruction**: "Do NOT commit. The coordinator handles commits."
 7. **Turn limit**: Include the maxTurns instruction from `circuit-breaker.md`
 8. **Verification before completion**: Before claiming any task done, run the verification command and quote the evidence inline. See `.claude/rules/verification-before-completion.md`.
@@ -272,10 +272,13 @@ During this wave, you may propose a learning to the session's memory via the CLI
       --subject "one-line title (max 100 chars, no newlines)" \
       --insight "your discovery paragraph (max 2000 chars)" \
       --evidence "concrete proof: code citation / log excerpt / commit ref (max 5000 chars)" \
-      --confidence <0.5 to 1.0>
+      --confidence <0.5 to 1.0> \
+      --file-paths "scripts/lib/a.mjs,scripts/lib/b.mjs"
 
 MUST prefix with `SO_WAVE_AGENT=1` — without it the CLI returns exit 3 `rejected-wrong-context`. The env-var is the per-process guard that distinguishes wave-executor agents from coordinator-context invocations.
 
+`--file-paths` is optional but strongly encouraged: repo-relative path(s) this learning applies to (repeatable and/or comma-separated, deduped; rejects absolute paths, `..` segments, embedded newlines, entries over 256 chars, and more than 20 entries). Without `--file-paths` this learning can never become `/reconcile`-eligible — the reconciliation engine can only convert a learning into a conditional `.claude/rules/*.md` rule when it carries a non-empty scope (issue #900).
+
 Exit code 0 = queued (the coordinator will present at session-end via AskUserQuestion); 1 = quota-exceeded; 2 = rejected-low-confidence (below floor 0.5); 3 = rejected-wrong-context (STATE.md not active OR SO_WAVE_AGENT != "1"); 4 = error (arg validation or internal).
 
 Use ONLY when you find a recurring pattern, anti-pattern, or constraint worth carrying into future sessions. The coordinator confirms each proposal before it lands in learnings.jsonl. Do NOT over-propose — quota is bounded per wave.