update backlog

- Move ~35 completed tasks from backlog/tasks/ to backlog/completed/
- Add ordinal fields to remaining in-progress task files
- Mark task-255 (playlist browser modal) as Done with final notes

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "subminer-local",
+  "interface": {
+    "displayName": "SubMiner Local"
+  },
+  "plugins": [
+    {
+      "name": "subminer-workflow",
+      "source": {
+        "source": "local",
+        "path": "./plugins/subminer-workflow"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

.agents/skills/subminer-change-verification/SKILL.md

@@ -1,127 +1,22 @@
 ---
-name: "subminer-change-verification"
-description: "Use when working in the SubMiner repo and you need to verify code changes actually work. Covers targeted regression checks during debugging and pre-handoff verification, with cheap-first lane selection for config, docs, launcher/plugin, runtime-compat, and optional real-runtime escalation."
+name: 'subminer-change-verification'
+description: 'Compatibility shim. Canonical SubMiner change verification workflow now lives in the repo-local subminer-workflow plugin.'
 ---
 
-# SubMiner Change Verification
+# Compatibility Shim
 
-Use this skill for SubMiner code changes. Default to cheap, repo-native verification first. Escalate only when the changed behavior actually depends on Electron, mpv, overlay/window tracking, or other GUI-sensitive runtime behavior.
+Canonical source:
 
-## Scripts
+- `plugins/subminer-workflow/skills/subminer-change-verification/SKILL.md`
 
-- `scripts/classify_subminer_diff.sh`
-  - Emits suggested lanes and flags from explicit paths or current git changes.
-- `scripts/verify_subminer_change.sh`
-  - Runs selected lanes, captures artifacts, and writes a compact summary.
+Canonical helper scripts:
 
-If you need an explicit installed path, use the directory that contains this `SKILL.md`. The helper scripts live under:
+- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh`
+- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh`
 
-```bash
-export SUBMINER_VERIFY_SKILL="<path-to-skill>"
-```
+When this shim is invoked:
 
-## Default workflow
-
-1. Inspect the changed files or user-requested area.
-2. Run the classifier unless you already know the right lane.
-3. Run the verifier with the cheapest sufficient lane set.
-4. If the classifier emits `flag:real-runtime-candidate`, do not jump straight to runtime verification. First run the non-runtime lanes.
-5. Escalate to explicit `--lane real-runtime --allow-real-runtime` only when cheaper lanes cannot validate the behavior claim.
-6. Return:
-   - verification summary
-   - exact commands run
-   - artifact paths
-   - skipped lanes and blockers
-
-## Quick start
-
-Repo-source quick start:
-
-```bash
-bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
-```
-
-Installed-skill quick start:
-
-```bash
-bash "$SUBMINER_VERIFY_SKILL/scripts/classify_subminer_diff.sh"
-```
-
-Classify explicit files:
-
-```bash
-bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh \
-  launcher/main.ts \
-  plugin/subminer/lifecycle.lua \
-  src/main/runtime/mpv-client-runtime-service.ts
-```
-
-Run automatic lane selection:
-
-```bash
-bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
-```
-
-Installed-skill form:
-
-```bash
-bash "$SUBMINER_VERIFY_SKILL/scripts/verify_subminer_change.sh"
-```
-
-Run targeted lanes:
-
-```bash
-bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh \
-  --lane launcher-plugin \
-  --lane runtime-compat
-```
-
-Dry-run to inspect planned commands and artifact layout:
-
-```bash
-bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh \
-  --dry-run \
-  launcher/main.ts \
-  src/main.ts
-```
-
-## Lane guidance
-
-- `docs`
-  - For `docs-site/`, `docs/`, and doc-only edits.
-- `config`
-  - For `src/config/` and config-template-sensitive edits.
-- `core`
-  - For general source changes where `typecheck` + `test:fast` is the best cheap signal.
-- `launcher-plugin`
-  - For `launcher/`, `plugin/subminer/`, plugin gating scripts, and wrapper/mpv routing work.
-- `runtime-compat`
-  - For `src/main*`, runtime/composer wiring, mpv/overlay services, window trackers, and dist-sensitive behavior.
-- `real-runtime`
-  - Only after deliberate escalation.
-
-## Real Runtime Escalation
-
-Escalate only when the change claim depends on actual runtime behavior, for example:
-
-- overlay appears, hides, or tracks a real mpv window
-- mpv launch flags or pause-until-ready behavior
-- plugin/socket/auto-start handshake under a real player
-- macOS/window-tracker/focus-sensitive behavior
-
-If the environment cannot support authoritative runtime verification, report the blocker explicitly. Do not silently downgrade a runtime-required claim to a pass.
-
-## Artifact contract
-
-The verifier writes under `.tmp/skill-verification/<timestamp>/`:
-
-- `summary.json`
-- `summary.txt`
-- `classification.txt`
-- `env.txt`
-- `lanes.txt`
-- `steps.tsv`
-- `steps/*.stdout.log`
-- `steps/*.stderr.log`
-
-On failure, quote the exact failing command and point at the artifact directory.
+1. Read the canonical plugin-owned skill.
+2. Follow the plugin-owned skill as the source of truth.
+3. Use the wrapper scripts in this shim directory only for compatibility with existing commands, docs, and backlog history.
+4. Do not duplicate workflow changes here; update the plugin-owned skill and scripts instead.

.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh

@@ -1,163 +1,13 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-usage() {
-  cat <<'EOF'
-Usage: classify_subminer_diff.sh [path ...]
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+REPO_ROOT=$(cd "$SCRIPT_DIR/../../../.." && pwd)
+TARGET="$REPO_ROOT/plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh"
 
-Emit suggested verification lanes for explicit paths or current local git changes.
-
-Output format:
-  lane:<name>
-  flag:<name>
-  reason:<text>
-EOF
-}
-
-has_item() {
-  local needle=$1
-  shift || true
-  local item
-  for item in "$@"; do
-    if [[ "$item" == "$needle" ]]; then
-      return 0
-    fi
-  done
-  return 1
-}
-
-add_lane() {
-  local lane=$1
-  if ! has_item "$lane" "${LANES[@]:-}"; then
-    LANES+=("$lane")
-  fi
-}
-
-add_flag() {
-  local flag=$1
-  if ! has_item "$flag" "${FLAGS[@]:-}"; then
-    FLAGS+=("$flag")
-  fi
-}
-
-add_reason() {
-  REASONS+=("$1")
-}
-
-collect_git_paths() {
-  local top_level
-  if ! top_level=$(git rev-parse --show-toplevel 2>/dev/null); then
-    return 0
-  fi
-
-  (
-    cd "$top_level"
-    if git rev-parse --verify HEAD >/dev/null 2>&1; then
-      git diff --name-only --relative HEAD --
-      git diff --name-only --relative --cached --
-    else
-      git diff --name-only --relative --
-      git diff --name-only --relative --cached --
-    fi
-    git ls-files --others --exclude-standard
-  ) | awk 'NF' | sort -u
-}
-
-if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
-  usage
-  exit 0
+if [[ ! -x "$TARGET" ]]; then
+  echo "Missing canonical script: $TARGET" >&2
+  exit 1
 fi
 
-declare -a PATHS=()
-declare -a LANES=()
-declare -a FLAGS=()
-declare -a REASONS=()
-
-if [[ $# -gt 0 ]]; then
-  while [[ $# -gt 0 ]]; do
-    PATHS+=("$1")
-    shift
-  done
-else
-  while IFS= read -r line; do
-    [[ -n "$line" ]] && PATHS+=("$line")
-  done < <(collect_git_paths)
-fi
-
-if [[ ${#PATHS[@]} -eq 0 ]]; then
-  add_lane "core"
-  add_reason "no changed paths detected -> default to core"
-fi
-
-for path in "${PATHS[@]}"; do
-  specialized=0
-
-  case "$path" in
-    docs-site/*|docs/*|changes/*|README.md)
-      add_lane "docs"
-      add_reason "$path -> docs"
-      specialized=1
-      ;;
-  esac
-
-  case "$path" in
-    src/config/*|src/generate-config-example.ts|src/verify-config-example.ts|docs-site/public/config.example.jsonc|config.example.jsonc)
-      add_lane "config"
-      add_reason "$path -> config"
-      specialized=1
-      ;;
-  esac
-
-  case "$path" in
-    launcher/*|plugin/subminer/*|plugin/subminer.conf|scripts/test-plugin-*|scripts/get-mpv-window-*|scripts/configure-plugin-binary-path.mjs)
-      add_lane "launcher-plugin"
-      add_reason "$path -> launcher-plugin"
-      add_flag "real-runtime-candidate"
-      add_reason "$path -> real-runtime-candidate"
-      specialized=1
-      ;;
-  esac
-
-  case "$path" in
-    src/main.ts|src/main-entry.ts|src/preload.ts|src/main/*|src/core/services/mpv*|src/core/services/overlay*|src/renderer/*|src/window-trackers/*|scripts/prepare-build-assets.mjs)
-      add_lane "runtime-compat"
-      add_reason "$path -> runtime-compat"
-      add_flag "real-runtime-candidate"
-      add_reason "$path -> real-runtime-candidate"
-      specialized=1
-      ;;
-  esac
-
-  if [[ "$specialized" == "0" ]]; then
-    case "$path" in
-      src/*|package.json|tsconfig*.json|scripts/*|Makefile)
-        add_lane "core"
-        add_reason "$path -> core"
-        ;;
-    esac
-  fi
-
-  case "$path" in
-    package.json|src/main.ts|src/main-entry.ts|src/preload.ts)
-      add_flag "broad-impact"
-      add_reason "$path -> broad-impact"
-      ;;
-  esac
-done
-
-if [[ ${#LANES[@]} -eq 0 ]]; then
-  add_lane "core"
-  add_reason "no lane-specific matches -> default to core"
-fi
-
-for lane in "${LANES[@]}"; do
-  printf 'lane:%s\n' "$lane"
-done
-
-for flag in "${FLAGS[@]}"; do
-  printf 'flag:%s\n' "$flag"
-done
-
-for reason in "${REASONS[@]}"; do
-  printf 'reason:%s\n' "$reason"
-done
+exec "$TARGET" "$@"

.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh

@@ -1,566 +1,13 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-usage() {
-  cat <<'EOF'
-Usage: verify_subminer_change.sh [options] [path ...]
-
-Options:
-  --lane <name>             Force a verification lane. Repeatable.
-  --artifact-dir <dir>      Use an explicit artifact directory.
-  --allow-real-runtime      Allow explicit real-runtime execution.
-  --allow-real-gui          Deprecated alias for --allow-real-runtime.
-  --dry-run                 Record planned steps without executing commands.
-  --help                    Show this help text.
-
-If no lanes are supplied, the script classifies the provided paths. If no paths are
-provided, it classifies the current local git changes.
-
-Authoritative real-runtime verification should be requested with explicit path
-arguments instead of relying on inferred local git changes.
-EOF
-}
-
-timestamp() {
-  date +%Y%m%d-%H%M%S
-}
-
-timestamp_iso() {
-  date -u +%Y-%m-%dT%H:%M:%SZ
-}
-
-generate_session_id() {
-  local tmp_dir
-  tmp_dir=$(mktemp -d "${TMPDIR:-/tmp}/subminer-verify-$(timestamp)-XXXXXX")
-  basename "$tmp_dir"
-  rmdir "$tmp_dir"
-}
-
-has_item() {
-  local needle=$1
-  shift || true
-  local item
-  for item in "$@"; do
-    if [[ "$item" == "$needle" ]]; then
-      return 0
-    fi
-  done
-  return 1
-}
-
-normalize_lane_name() {
-  case "$1" in
-    real-gui)
-      printf '%s' "real-runtime"
-      ;;
-    *)
-      printf '%s' "$1"
-      ;;
-  esac
-}
-
-add_lane() {
-  local lane
-  lane=$(normalize_lane_name "$1")
-  if ! has_item "$lane" "${SELECTED_LANES[@]:-}"; then
-    SELECTED_LANES+=("$lane")
-  fi
-}
-
-add_blocker() {
-  BLOCKERS+=("$1")
-  BLOCKED=1
-}
-
-append_step_record() {
-  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
-    "$1" "$2" "$3" "$4" "$5" "$6" "$7" "$8" >>"$STEPS_TSV"
-}
-
-record_env() {
-  {
-    printf 'repo_root=%s\n' "$REPO_ROOT"
-    printf 'session_id=%s\n' "$SESSION_ID"
-    printf 'artifact_dir=%s\n' "$ARTIFACT_DIR"
-    printf 'path_selection_mode=%s\n' "$PATH_SELECTION_MODE"
-    printf 'dry_run=%s\n' "$DRY_RUN"
-    printf 'allow_real_runtime=%s\n' "$ALLOW_REAL_RUNTIME"
-    printf 'session_home=%s\n' "$SESSION_HOME"
-    printf 'session_xdg_config_home=%s\n' "$SESSION_XDG_CONFIG_HOME"
-    printf 'session_mpv_dir=%s\n' "$SESSION_MPV_DIR"
-    printf 'session_logs_dir=%s\n' "$SESSION_LOGS_DIR"
-    printf 'session_mpv_log=%s\n' "$SESSION_MPV_LOG"
-    printf 'pwd=%s\n' "$(pwd)"
-    git rev-parse --short HEAD 2>/dev/null | sed 's/^/git_head=/' || true
-    git status --short 2>/dev/null || true
-    if [[ ${#PATH_ARGS[@]} -gt 0 ]]; then
-      printf 'requested_paths=\n'
-      printf '  %s\n' "${PATH_ARGS[@]}"
-    fi
-  } >"$ARTIFACT_DIR/env.txt"
-}
-
-run_step() {
-  local lane=$1
-  local name=$2
-  local command=$3
-  local note=${4:-}
-  local slug=${name//[^a-zA-Z0-9_-]/-}
-  local stdout_rel="steps/${slug}.stdout.log"
-  local stderr_rel="steps/${slug}.stderr.log"
-  local stdout_path="$ARTIFACT_DIR/$stdout_rel"
-  local stderr_path="$ARTIFACT_DIR/$stderr_rel"
-  local status exit_code
-
-  COMMANDS_RUN+=("$command")
-  printf '%s\n' "$command" >"$ARTIFACT_DIR/steps/${slug}.command.txt"
-
-  if [[ "$DRY_RUN" == "1" ]]; then
-    printf '[dry-run] %s\n' "$command" >"$stdout_path"
-    : >"$stderr_path"
-    status="dry-run"
-    exit_code=0
-  else
-    if bash -lc "cd \"$REPO_ROOT\" && $command" >"$stdout_path" 2>"$stderr_path"; then
-      status="passed"
-      exit_code=0
-      EXECUTED_REAL_STEPS=1
-    else
-      exit_code=$?
-      status="failed"
-      FAILED=1
-    fi
-  fi
-
-  append_step_record "$lane" "$name" "$status" "$exit_code" "$command" "$stdout_rel" "$stderr_rel" "$note"
-  printf '%s\t%s\t%s\n' "$lane" "$name" "$status"
-
-  if [[ "$status" == "failed" ]]; then
-    FAILURE_STEP="$name"
-    FAILURE_COMMAND="$command"
-    FAILURE_STDOUT="$stdout_rel"
-    FAILURE_STDERR="$stderr_rel"
-    return "$exit_code"
-  fi
-}
-
-record_nonpassing_step() {
-  local lane=$1
-  local name=$2
-  local status=$3
-  local note=$4
-  local slug=${name//[^a-zA-Z0-9_-]/-}
-  local stdout_rel="steps/${slug}.stdout.log"
-  local stderr_rel="steps/${slug}.stderr.log"
-  printf '%s\n' "$note" >"$ARTIFACT_DIR/$stdout_rel"
-  : >"$ARTIFACT_DIR/$stderr_rel"
-  append_step_record "$lane" "$name" "$status" "0" "" "$stdout_rel" "$stderr_rel" "$note"
-  printf '%s\t%s\t%s\n' "$lane" "$name" "$status"
-}
-
-record_skipped_step() {
-  record_nonpassing_step "$1" "$2" "skipped" "$3"
-}
-
-record_blocked_step() {
-  add_blocker "$3"
-  record_nonpassing_step "$1" "$2" "blocked" "$3"
-}
-
-record_failed_step() {
-  FAILED=1
-  FAILURE_STEP=$2
-  FAILURE_COMMAND=${FAILURE_COMMAND:-"(validation)"}
-  FAILURE_STDOUT="steps/${2//[^a-zA-Z0-9_-]/-}.stdout.log"
-  FAILURE_STDERR="steps/${2//[^a-zA-Z0-9_-]/-}.stderr.log"
-  add_blocker "$3"
-  record_nonpassing_step "$1" "$2" "failed" "$3"
-}
-
-find_real_runtime_helper() {
-  local candidate
-  for candidate in \
-    "$SCRIPT_DIR/run_real_runtime_smoke.sh" \
-    "$SCRIPT_DIR/run_real_mpv_smoke.sh"; do
-    if [[ -x "$candidate" ]]; then
-      printf '%s' "$candidate"
-      return 0
-    fi
-  done
-  return 1
-}
-
-acquire_real_runtime_lease() {
-  local lease_root="$REPO_ROOT/.tmp/skill-verification/locks"
-  local lease_dir="$lease_root/exclusive-real-runtime"
-  mkdir -p "$lease_root"
-  if mkdir "$lease_dir" 2>/dev/null; then
-    REAL_RUNTIME_LEASE_DIR="$lease_dir"
-    printf '%s\n' "$SESSION_ID" >"$lease_dir/session_id"
-    return 0
-  fi
-
-  local owner=""
-  if [[ -f "$lease_dir/session_id" ]]; then
-    owner=$(cat "$lease_dir/session_id")
-  fi
-  add_blocker "real-runtime lease already held${owner:+ by $owner}"
-  return 1
-}
-
-release_real_runtime_lease() {
-  if [[ -n "$REAL_RUNTIME_LEASE_DIR" && -d "$REAL_RUNTIME_LEASE_DIR" ]]; then
-    if [[ -f "$REAL_RUNTIME_LEASE_DIR/session_id" ]]; then
-      local owner
-      owner=$(cat "$REAL_RUNTIME_LEASE_DIR/session_id")
-      if [[ "$owner" != "$SESSION_ID" ]]; then
-        return 0
-      fi
-    fi
-    rm -rf "$REAL_RUNTIME_LEASE_DIR"
-  fi
-}
-
-compute_final_status() {
-  if [[ "$FAILED" == "1" ]]; then
-    FINAL_STATUS="failed"
-  elif [[ "$BLOCKED" == "1" ]]; then
-    FINAL_STATUS="blocked"
-  elif [[ "$EXECUTED_REAL_STEPS" == "1" ]]; then
-    FINAL_STATUS="passed"
-  else
-    FINAL_STATUS="skipped"
-  fi
-}
-
-write_summary_files() {
-  local lane_lines
-  lane_lines=$(printf '%s\n' "${SELECTED_LANES[@]}")
-  printf '%s\n' "$lane_lines" >"$ARTIFACT_DIR/lanes.txt"
-  printf '%s\n' "${BLOCKERS[@]}" >"$ARTIFACT_DIR/blockers.txt"
-  printf '%s\n' "${PATH_ARGS[@]}" >"$ARTIFACT_DIR/requested-paths.txt"
-
-  ARTIFACT_DIR_ENV="$ARTIFACT_DIR" \
-  SESSION_ID_ENV="$SESSION_ID" \
-  FINAL_STATUS_ENV="$FINAL_STATUS" \
-  PATH_SELECTION_MODE_ENV="$PATH_SELECTION_MODE" \
-  ALLOW_REAL_RUNTIME_ENV="$ALLOW_REAL_RUNTIME" \
-  SESSION_HOME_ENV="$SESSION_HOME" \
-  SESSION_XDG_CONFIG_HOME_ENV="$SESSION_XDG_CONFIG_HOME" \
-  SESSION_MPV_DIR_ENV="$SESSION_MPV_DIR" \
-  SESSION_LOGS_DIR_ENV="$SESSION_LOGS_DIR" \
-  SESSION_MPV_LOG_ENV="$SESSION_MPV_LOG" \
-  STARTED_AT_ENV="$STARTED_AT" \
-  FINISHED_AT_ENV="$FINISHED_AT" \
-  FAILED_ENV="$FAILED" \
-  FAILURE_COMMAND_ENV="${FAILURE_COMMAND:-}" \
-  FAILURE_STDOUT_ENV="${FAILURE_STDOUT:-}" \
-  FAILURE_STDERR_ENV="${FAILURE_STDERR:-}" \
-  bun -e '
-    const fs = require("fs");
-    const path = require("path");
-
-    function readLines(filePath) {
-      if (!fs.existsSync(filePath)) return [];
-      return fs.readFileSync(filePath, "utf8").split(/\r?\n/).filter(Boolean);
-    }
-
-    const artifactDir = process.env.ARTIFACT_DIR_ENV;
-    const reportsDir = path.join(artifactDir, "reports");
-    const lanes = readLines(path.join(artifactDir, "lanes.txt"));
-    const blockers = readLines(path.join(artifactDir, "blockers.txt"));
-    const requestedPaths = readLines(path.join(artifactDir, "requested-paths.txt"));
-    const steps = readLines(path.join(artifactDir, "steps.tsv")).map((line) => {
-      const [lane, name, status, exitCode, command, stdout, stderr, note] = line.split("\t");
-      return {
-        lane,
-        name,
-        status,
-        exitCode: Number(exitCode || 0),
-        command,
-        stdout,
-        stderr,
-        note,
-      };
-    });
-    const summary = {
-      sessionId: process.env.SESSION_ID_ENV || "",
-      artifactDir,
-      reportsDir,
-      status: process.env.FINAL_STATUS_ENV || "failed",
-      selectedLanes: lanes,
-      failed: process.env.FAILED_ENV === "1",
-      failure:
-        process.env.FAILED_ENV === "1"
-          ? {
-              command: process.env.FAILURE_COMMAND_ENV || "",
-              stdout: process.env.FAILURE_STDOUT_ENV || "",
-              stderr: process.env.FAILURE_STDERR_ENV || "",
-            }
-          : null,
-      blockers,
-      pathSelectionMode: process.env.PATH_SELECTION_MODE_ENV || "git-inferred",
-      requestedPaths,
-      allowRealRuntime: process.env.ALLOW_REAL_RUNTIME_ENV === "1",
-      startedAt: process.env.STARTED_AT_ENV || "",
-      finishedAt: process.env.FINISHED_AT_ENV || "",
-      env: {
-        home: process.env.SESSION_HOME_ENV || "",
-        xdgConfigHome: process.env.SESSION_XDG_CONFIG_HOME_ENV || "",
-        mpvDir: process.env.SESSION_MPV_DIR_ENV || "",
-        logsDir: process.env.SESSION_LOGS_DIR_ENV || "",
-        mpvLog: process.env.SESSION_MPV_LOG_ENV || "",
-      },
-      steps,
-    };
-
-    const summaryJson = JSON.stringify(summary, null, 2) + "\n";
-    fs.writeFileSync(path.join(artifactDir, "summary.json"), summaryJson);
-    fs.writeFileSync(path.join(reportsDir, "summary.json"), summaryJson);
-
-    const lines = [];
-    lines.push(`session_id: ${summary.sessionId}`);
-    lines.push(`artifact_dir: ${artifactDir}`);
-    lines.push(`selected_lanes: ${lanes.join(", ") || "(none)"}`);
-    lines.push(`status: ${summary.status}`);
-    lines.push(`path_selection_mode: ${summary.pathSelectionMode}`);
-    if (requestedPaths.length > 0) {
-      lines.push(`requested_paths: ${requestedPaths.join(", ")}`);
-    }
-    if (blockers.length > 0) {
-      lines.push(`blockers: ${blockers.join(" | ")}`);
-    }
-    for (const step of steps) {
-      lines.push(`${step.lane}/${step.name}: ${step.status}`);
-      if (step.command) lines.push(`  command: ${step.command}`);
-      lines.push(`  stdout: ${step.stdout}`);
-      lines.push(`  stderr: ${step.stderr}`);
-      if (step.note) lines.push(`  note: ${step.note}`);
-    }
-    if (summary.failed) {
-      lines.push(`failure_command: ${process.env.FAILURE_COMMAND_ENV || ""}`);
-    }
-    const summaryText = lines.join("\n") + "\n";
-    fs.writeFileSync(path.join(artifactDir, "summary.txt"), summaryText);
-    fs.writeFileSync(path.join(reportsDir, "summary.txt"), summaryText);
-  '
-}
-
-cleanup() {
-  release_real_runtime_lease
-}
-
-CLASSIFIER_OUTPUT=""
-ARTIFACT_DIR=""
-ALLOW_REAL_RUNTIME=0
-DRY_RUN=0
-FAILED=0
-BLOCKED=0
-EXECUTED_REAL_STEPS=0
-FINAL_STATUS=""
-FAILURE_STEP=""
-FAILURE_COMMAND=""
-FAILURE_STDOUT=""
-FAILURE_STDERR=""
-REAL_RUNTIME_LEASE_DIR=""
-STARTED_AT=""
-FINISHED_AT=""
-
-declare -a EXPLICIT_LANES=()
-declare -a SELECTED_LANES=()
-declare -a PATH_ARGS=()
-declare -a COMMANDS_RUN=()
-declare -a BLOCKERS=()
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --lane)
-      EXPLICIT_LANES+=("$(normalize_lane_name "$2")")
-      shift 2
-      ;;
-    --artifact-dir)
-      ARTIFACT_DIR=$2
-      shift 2
-      ;;
-    --allow-real-runtime|--allow-real-gui)
-      ALLOW_REAL_RUNTIME=1
-      shift
-      ;;
-    --dry-run)
-      DRY_RUN=1
-      shift
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    --)
-      shift
-      while [[ $# -gt 0 ]]; do
-        PATH_ARGS+=("$1")
-        shift
-      done
-      ;;
-    *)
-      PATH_ARGS+=("$1")
-      shift
-      ;;
-  esac
-done
-
 SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
-SESSION_ID=$(generate_session_id)
-PATH_SELECTION_MODE="git-inferred"
-if [[ ${#PATH_ARGS[@]} -gt 0 ]]; then
-  PATH_SELECTION_MODE="explicit"
+REPO_ROOT=$(cd "$SCRIPT_DIR/../../../.." && pwd)
+TARGET="$REPO_ROOT/plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh"
+
+if [[ ! -x "$TARGET" ]]; then
+  echo "Missing canonical script: $TARGET" >&2
+  exit 1
 fi
 
-if [[ -z "$ARTIFACT_DIR" ]]; then
-  mkdir -p "$REPO_ROOT/.tmp/skill-verification"
-  ARTIFACT_DIR="$REPO_ROOT/.tmp/skill-verification/$SESSION_ID"
-fi
-
-SESSION_HOME="$ARTIFACT_DIR/home"
-SESSION_XDG_CONFIG_HOME="$ARTIFACT_DIR/xdg"
-SESSION_MPV_DIR="$ARTIFACT_DIR/mpv"
-SESSION_LOGS_DIR="$ARTIFACT_DIR/logs"
-SESSION_MPV_LOG="$SESSION_LOGS_DIR/mpv.log"
-
-mkdir -p "$ARTIFACT_DIR/steps" "$ARTIFACT_DIR/reports" "$SESSION_HOME" "$SESSION_XDG_CONFIG_HOME" "$SESSION_MPV_DIR" "$SESSION_LOGS_DIR"
-STEPS_TSV="$ARTIFACT_DIR/steps.tsv"
-: >"$STEPS_TSV"
-
-trap cleanup EXIT
-STARTED_AT=$(timestamp_iso)
-
-if [[ ${#EXPLICIT_LANES[@]} -gt 0 ]]; then
-  local_lane=""
-  for local_lane in "${EXPLICIT_LANES[@]}"; do
-    add_lane "$local_lane"
-  done
-  printf 'reason:explicit lanes supplied\n' >"$ARTIFACT_DIR/classification.txt"
-else
-  if [[ ${#PATH_ARGS[@]} -gt 0 ]]; then
-    CLASSIFIER_OUTPUT=$(bash "$SCRIPT_DIR/classify_subminer_diff.sh" "${PATH_ARGS[@]}")
-  else
-    CLASSIFIER_OUTPUT=$(bash "$SCRIPT_DIR/classify_subminer_diff.sh")
-  fi
-  printf '%s\n' "$CLASSIFIER_OUTPUT" >"$ARTIFACT_DIR/classification.txt"
-  while IFS= read -r line; do
-    case "$line" in
-      lane:*)
-        add_lane "${line#lane:}"
-        ;;
-    esac
-  done <<<"$CLASSIFIER_OUTPUT"
-fi
-
-record_env
-
-printf 'artifact_dir=%s\n' "$ARTIFACT_DIR"
-printf 'selected_lanes=%s\n' "$(IFS=,; echo "${SELECTED_LANES[*]}")"
-
-for lane in "${SELECTED_LANES[@]}"; do
-  case "$lane" in
-    docs)
-      run_step "$lane" "docs-test" "bun run docs:test" || break
-      [[ "$FAILED" == "1" ]] && break
-      run_step "$lane" "docs-build" "bun run docs:build" || break
-      ;;
-    config)
-      run_step "$lane" "test-config" "bun run test:config" || break
-      ;;
-    core)
-      run_step "$lane" "typecheck" "bun run typecheck" || break
-      [[ "$FAILED" == "1" ]] && break
-      run_step "$lane" "test-fast" "bun run test:fast" || break
-      ;;
-    launcher-plugin)
-      run_step "$lane" "launcher-smoke-src" "bun run test:launcher:smoke:src" || break
-      [[ "$FAILED" == "1" ]] && break
-      run_step "$lane" "plugin-src" "bun run test:plugin:src" || break
-      ;;
-    runtime-compat)
-      run_step "$lane" "build" "bun run build" || break
-      [[ "$FAILED" == "1" ]] && break
-      run_step "$lane" "test-runtime-compat" "bun run test:runtime:compat" || break
-      [[ "$FAILED" == "1" ]] && break
-      run_step "$lane" "test-smoke-dist" "bun run test:smoke:dist" || break
-      ;;
-    real-runtime)
-      if [[ "$PATH_SELECTION_MODE" != "explicit" ]]; then
-        record_blocked_step \
-          "$lane" \
-          "real-runtime-guard" \
-          "real-runtime lane requires explicit paths; inferred local git changes are non-authoritative"
-        break
-      fi
-
-      if [[ "$ALLOW_REAL_RUNTIME" != "1" ]]; then
-        record_blocked_step \
-          "$lane" \
-          "real-runtime-guard" \
-          "real-runtime lane requested but --allow-real-runtime was not supplied"
-        break
-      fi
-
-      if ! acquire_real_runtime_lease; then
-        record_blocked_step \
-          "$lane" \
-          "real-runtime-lease" \
-          "real-runtime lease already held; rerun after the active runtime verification finishes"
-        break
-      fi
-
-      if ! REAL_RUNTIME_HELPER=$(find_real_runtime_helper); then
-        record_blocked_step \
-          "$lane" \
-          "real-runtime-helper" \
-          "real-runtime helper not implemented yet"
-        break
-      fi
-
-      printf -v REAL_RUNTIME_COMMAND \
-        'SESSION_ID=%q HOME=%q XDG_CONFIG_HOME=%q SUBMINER_MPV_LOG=%q bash %q' \
-        "$SESSION_ID" \
-        "$SESSION_HOME" \
-        "$SESSION_XDG_CONFIG_HOME" \
-        "$SESSION_MPV_LOG" \
-        "$REAL_RUNTIME_HELPER"
-
-      run_step "$lane" "real-runtime-smoke" "$REAL_RUNTIME_COMMAND" || break
-      ;;
-    *)
-      record_failed_step "$lane" "lane-validation" "unknown lane: $lane"
-      break
-      ;;
-  esac
-
-  if [[ "$FAILED" == "1" || "$BLOCKED" == "1" ]]; then
-    break
-  fi
-done
-
-FINISHED_AT=$(timestamp_iso)
-compute_final_status
-write_summary_files
-
-printf 'status=%s\n' "$FINAL_STATUS"
-printf 'artifact_dir=%s\n' "$ARTIFACT_DIR"
-
-case "$FINAL_STATUS" in
-  failed)
-    printf 'result=failed\n'
-    printf 'failure_command=%s\n' "$FAILURE_COMMAND"
-    exit 1
-    ;;
-  blocked)
-    printf 'result=blocked\n'
-    exit 2
-    ;;
-  *)
-    printf 'result=ok\n'
-    exit 0
-    ;;
-esac
+exec "$TARGET" "$@"

.agents/skills/subminer-scrum-master/SKILL.md

@@ -1,146 +1,18 @@
 ---
-name: "subminer-scrum-master"
-description: "Use in the SubMiner repo when a request should be turned into planned work and driven through execution. Assesses whether backlog tracking is warranted, creates or updates tasks when needed, records a plan, dispatches one or more subagents, and requires verification before handoff."
+name: 'subminer-scrum-master'
+description: 'Compatibility shim. Canonical SubMiner scrum-master workflow now lives in the repo-local subminer-workflow plugin.'
 ---
 
-# SubMiner Scrum Master
+# Compatibility Shim
 
-Own workflow, not code by default.
+Canonical source:
 
-Use this skill when the user gives a feature request, bug report, issue, refactor, or implementation ask and the agent should manage intake, planning, backlog hygiene, worker dispatch, and verification through completion.
+- `plugins/subminer-workflow/skills/subminer-scrum-master/SKILL.md`
 
-## Core Rules
+When this shim is invoked:
 
-1. Decide first whether backlog tracking is warranted.
-2. If backlog is needed, search first. Update existing work when it clearly matches.
-3. If backlog is not needed, keep the process light. Do not invent ticket ceremony.
-4. Record a plan before dispatching coding work.
-5. Use parent + subtasks for multi-part work when backlog is used.
-6. Dispatch conservatively. Parallelize only disjoint write scopes.
-7. Require verification before handoff, typically via `subminer-change-verification`.
-8. Report backlog actions, dispatched workers, verification, blockers, and remaining risks.
+1. Read the canonical plugin-owned skill.
+2. Follow the plugin-owned skill as the source of truth.
+3. Do not duplicate workflow changes here; update the plugin-owned skill instead.
 
-## Backlog Decision
-
-Skip backlog when the request is:
-- question only
-- obvious mechanical edit
-- tiny isolated change with no real planning
-
-Use backlog when the work:
-- needs planning or scope decisions
-- spans multiple phases or subsystems
-- is likely to need subagent dispatch
-- should remain traceable for handoff/resume
-
-If backlog is used:
-- search existing tasks first
-- create/update a standalone task for one focused deliverable
-- create/update a parent task plus subtasks for multi-part work
-- record the implementation plan in the task before implementation begins
-
-## Intake Workflow
-
-1. Parse the request.
-   Classify it as question, mechanical edit, bugfix, feature, refactor, investigation, or follow-up.
-2. Decide whether backlog is needed.
-3. If backlog is needed:
-   - search first
-   - update existing task if clearly relevant
-   - otherwise create the right structure
-   - write the implementation plan before dispatch
-4. If backlog is skipped:
-   - write a short working plan in-thread
-   - proceed without fake ticketing
-5. Choose execution mode:
-   - no subagents for trivial work
-   - one worker for focused work
-   - parallel workers only for disjoint scopes
-6. Run verification before handoff.
-
-## Dispatch Rules
-
-The scrum master orchestrates. Workers implement.
-
-- Do not become the default implementer unless delegation is unnecessary.
-- Do not parallelize overlapping files or tightly coupled runtime work.
-- Give every worker explicit ownership of files/modules.
-- Tell every worker other agents may be active and they must not revert unrelated edits.
-- Require each worker to report:
-  - changed files
-  - tests run
-  - blockers
-
-Use worker agents for implementation and explorer agents only for bounded codebase questions.
-
-## Verification
-
-Every nontrivial code task gets verification.
-
-Preferred flow:
-1. use `subminer-change-verification`
-2. start with the cheapest sufficient lane
-3. escalate only when needed
-4. if worker verification is sufficient, accept it or run one final consolidating pass
-
-Never hand off nontrivial work without stating what was verified and what was skipped.
-
-## Pre-Handoff Policy Checks (Required)
-
-Before handoff, always ask and answer both of these questions explicitly:
-
-1. **Docs update required?**
-2. **Changelog fragment required?**
-
-Rules:
-- Do not assume silence implies "no." Record an explicit yes/no decision for each item.
-- If the answer is yes, either complete the update or report the blocker before handoff.
-- Include the final answers in the handoff summary even when both answers are "no."
-
-## Failure / Scope Handling
-
-- If a worker hits ambiguity, pause and ask the user.
-- If verification fails, either:
-  - send the worker back with exact failure context, or
-  - fix it directly if it is tiny and clearly in scope
-- If new scope appears, revisit backlog structure before silently expanding work.
-
-## Representative Flows
-
-### Trivial no-ticket work
-
-- decide backlog is unnecessary
-- keep a short plan
-- implement directly or with one worker if helpful
-- run targeted verification
-- report outcome concisely
-
-### Single-task implementation
-
-- search/create/update one task
-- record plan
-- dispatch one worker
-- integrate
-- verify
-- update task and report outcome
-
-### Parent + subtasks execution
-
-- search/create/update parent task
-- create subtasks for distinct deliverables/phases
-- record sequencing in the plan
-- dispatch workers only where scopes are disjoint
-- integrate
-- run consolidated verification
-- update task state and report outcome
-
-## Output Expectations
-
-At the end, report:
-- whether backlog was used and what changed
-- which workers were dispatched and what they owned
-- what verification ran
-- explicit answers to:
-  - docs update required?
-  - changelog fragment required?
-- blockers, skips, and risks
+This shim exists so existing repo references and prompts keep resolving during the migration to the repo-local plugin workflow.

.github/workflows/ci.yml

@@ -61,6 +61,16 @@ jobs:
       - name: Test suite (source)
         run: bun run test:fast
 
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 

.github/workflows/release.yml

@@ -49,6 +49,16 @@ jobs:
       - name: Test suite (source)
         run: bun run test:fast
 
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 
@@ -399,33 +409,64 @@ jobs:
         id: version
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
-      - name: Validate AUR SSH secret
+      - name: Check AUR publish prerequisites
+        id: aur_prereqs
         env:
           AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
         run: |
           set -euo pipefail
           if [ -z "${AUR_SSH_PRIVATE_KEY}" ]; then
-            echo "Missing required secret: AUR_SSH_PRIVATE_KEY"
-            exit 1
+            echo "::warning::Missing AUR_SSH_PRIVATE_KEY; skipping automated AUR publish."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
           fi
+          echo "skip=false" >> "$GITHUB_OUTPUT"
 
       - name: Configure SSH for AUR
+        id: aur_ssh
+        if: steps.aur_prereqs.outputs.skip != 'true'
         env:
           AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
         run: |
           set -euo pipefail
-          install -dm700 ~/.ssh
-          printf '%s\n' "${AUR_SSH_PRIVATE_KEY}" > ~/.ssh/aur
-          chmod 600 ~/.ssh/aur
-          ssh-keyscan aur.archlinux.org >> ~/.ssh/known_hosts
-          chmod 644 ~/.ssh/known_hosts
+          if install -dm700 ~/.ssh \
+            && printf '%s\n' "${AUR_SSH_PRIVATE_KEY}" > ~/.ssh/aur \
+            && chmod 600 ~/.ssh/aur \
+            && ssh-keyscan aur.archlinux.org >> ~/.ssh/known_hosts \
+            && chmod 644 ~/.ssh/known_hosts; then
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "::warning::Unable to configure SSH for AUR; skipping automated AUR publish."
+          echo "skip=true" >> "$GITHUB_OUTPUT"
 
       - name: Clone AUR repo
+        id: aur_clone
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true'
         env:
           GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
-        run: git clone ssh://aur@aur.archlinux.org/subminer-bin.git aur-subminer-bin
+        run: |
+          set -euo pipefail
+          attempts=3
+          for attempt in $(seq 1 "$attempts"); do
+            if git clone ssh://aur@aur.archlinux.org/subminer-bin.git aur-subminer-bin; then
+              echo "skip=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+
+            rm -rf aur-subminer-bin
+
+            if [ "$attempt" -lt "$attempts" ]; then
+              sleep $((attempt * 15))
+            fi
+          done
+
+          echo "::warning::Unable to clone subminer-bin from AUR after ${attempts} attempts; skipping automated AUR publish."
+          echo "skip=true" >> "$GITHUB_OUTPUT"
 
       - name: Download release assets for AUR
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -439,6 +480,7 @@ jobs:
             --pattern "subminer-assets.tar.gz"
 
       - name: Update AUR packaging metadata
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
         run: |
           set -euo pipefail
           version_no_v="${{ steps.version.outputs.VERSION }}"
@@ -453,6 +495,7 @@ jobs:
             --assets ".tmp/aur-release-assets/subminer-assets.tar.gz"
 
       - name: Commit and push AUR update
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
         working-directory: aur-subminer-bin
         env:
           GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
@@ -466,4 +509,16 @@ jobs:
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add PKGBUILD .SRCINFO
           git commit -m "Update to ${{ steps.version.outputs.VERSION }}"
-          git push origin HEAD:master
+
+          attempts=3
+          for attempt in $(seq 1 "$attempts"); do
+            if git push origin HEAD:master; then
+              exit 0
+            fi
+
+            if [ "$attempt" -lt "$attempts" ]; then
+              sleep $((attempt * 15))
+            fi
+          done
+
+          echo "::warning::Unable to push the AUR update after ${attempts} attempts; GitHub release is published, but subminer-bin needs manual follow-up."

.gitignore

@@ -9,6 +9,7 @@ out/
 dist/
 release/
 build/yomitan/
+coverage/
 
 # Launcher build artifact (produced by make build-launcher)
 /subminer

AGENTS.md

@@ -83,7 +83,6 @@ This project uses Backlog.md MCP for all task and project management activities.
 - **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work
 
 These guides cover:
-
 - Decision framework for when to create tasks
 - Search-first workflow to avoid duplicates
 - Links to detailed guides for task creation, execution, and finalization

Backlog.md

@@ -0,0 +1,266 @@
+# Backlog
+
+Purpose: lightweight repo-local task board. Seeded with current testing / coverage work.
+
+Status keys:
+
+- `todo`: not started
+- `doing`: in progress
+- `blocked`: waiting
+- `done`: shipped
+
+Priority keys:
+
+- `P0`: urgent / release-risk
+- `P1`: high value
+- `P2`: useful cleanup
+- `P3`: nice-to-have
+
+## Active
+
+| ID     | Pri | Status | Area           | Title                                               |
+| ------ | --- | ------ | -------------- | --------------------------------------------------- |
+| SM-013 | P1  | done   | review-followup | Address PR #36 CodeRabbit action items              |
+
+## Ready
+
+| ID     | Pri | Status | Area              | Title                                                            |
+| ------ | --- | ------ | ----------------- | ---------------------------------------------------------------- |
+| SM-001 | P1  | todo   | launcher          | Add tests for CLI parser and args normalizer                     |
+| SM-002 | P1  | todo   | immersion-tracker | Backfill tests for uncovered query exports                       |
+| SM-003 | P1  | todo   | anki              | Add focused field-grouping service + merge edge-case tests       |
+| SM-004 | P2  | todo   | tests             | Extract shared test utils for deps factories and polling helpers |
+| SM-005 | P2  | todo   | tests             | Strengthen weak assertions in app-ready and IPC tests            |
+| SM-006 | P2  | todo   | tests             | Break up monolithic youtube-flow and subtitle-sidebar tests      |
+| SM-007 | P2  | todo   | anilist           | Add tests for AniList rate limiter                               |
+| SM-008 | P3  | todo   | subtitles         | Add core subtitle-position persistence/path tests                |
+| SM-009 | P3  | todo   | tokenizer         | Add tests for JLPT token filter                                  |
+| SM-010 | P1  | todo   | immersion-tracker | Refactor storage + immersion-tracker service into focused modules    |
+| SM-011 | P1  | done   | tests             | Add coverage reporting for maintained test lanes                 |
+| SM-012 | P2  | done   | config/runtime    | Replace JSON serialize-clone helpers with structured cloning     |
+
+## Icebox
+
+None.
+
+## Ticket Details
+
+### SM-001
+
+Title: Add tests for CLI parser and args normalizer
+Priority: P1
+Status: done
+Scope:
+
+- `launcher/config/cli-parser-builder.ts`
+- `launcher/config/args-normalizer.ts`
+  Acceptance:
+- root options parsing covered
+- subcommand routing covered
+- invalid action / invalid log level / invalid backend cases covered
+- target classification covered: file, directory, URL, invalid
+
+### SM-002
+
+Title: Backfill tests for uncovered query exports
+Priority: P1
+Status: todo
+Scope:
+
+- `src/core/services/immersion-tracker/query-*.ts`
+  Targets:
+- headword helpers
+- anime/media detail helpers not covered by existing wrapper tests
+- lexical detail / appearance helpers
+- maintenance helpers beyond `deleteSession` and `upsertCoverArt`
+  Acceptance:
+- every exported query helper either directly tested or explicitly justified as covered elsewhere
+- at least one focused regression per complex SQL branch / aggregation branch
+
+### SM-003
+
+Title: Add focused field-grouping service + merge edge-case tests
+Priority: P1
+Status: todo
+Scope:
+
+- `src/anki-integration/field-grouping.ts`
+- `src/anki-integration/field-grouping-merge.ts`
+  Acceptance:
+- auto/manual/disabled flow branches covered
+- duplicate-card preview failure path covered
+- merge edge cases covered: empty fields, generated media fallback, strict grouped spans, audio synchronization
+
+### SM-004
+
+Title: Extract shared test utils for deps factories and polling helpers
+Priority: P2
+Status: todo
+Scope:
+
+- common `makeDeps` / `createDeps` helpers
+- common `waitForCondition`
+  Acceptance:
+- shared helper module added
+- at least 3 duplicated polling helpers removed
+- at least 5 duplicated deps factories consolidated or clearly prepared for follow-up migration
+
+### SM-005
+
+Title: Strengthen weak assertions in app-ready and IPC tests
+Priority: P2
+Status: todo
+Scope:
+
+- `src/core/services/app-ready.test.ts`
+- `src/core/services/ipc.test.ts`
+  Acceptance:
+- replace broad `assert.ok(...)` presence checks with exact value / order assertions where expected value known
+- handler registration tests assert channel-specific behavior, not only existence
+
+### SM-006
+
+Title: Break up monolithic youtube-flow and subtitle-sidebar tests
+Priority: P2
+Status: todo
+Scope:
+
+- `src/main/runtime/youtube-flow.test.ts`
+- `src/renderer/modals/subtitle-sidebar.test.ts`
+  Acceptance:
+- reduce single-test breadth
+- split largest tests into focused cases by behavior
+- keep semantics unchanged
+
+### SM-007
+
+Title: Add tests for AniList rate limiter
+Priority: P2
+Status: todo
+Scope:
+
+- `src/core/services/anilist/rate-limiter.ts`
+  Acceptance:
+- capacity-window wait behavior covered
+- `x-ratelimit-remaining` + reset handling covered
+- `retry-after` handling covered
+
+### SM-008
+
+Title: Add core subtitle-position persistence/path tests
+Priority: P3
+Status: todo
+Scope:
+
+- `src/core/services/subtitle-position.ts`
+  Acceptance:
+- save/load persistence covered
+- fallback behavior covered
+- path normalization behavior covered for URL vs local target
+
+### SM-009
+
+Title: Add tests for JLPT token filter
+Priority: P3
+Status: todo
+Scope:
+
+- `src/core/services/jlpt-token-filter.ts`
+  Acceptance:
+- excluded term membership covered
+- ignored POS1 membership covered
+- exported list / entry consistency covered
+
+### SM-010
+
+Title: Refactor storage + immersion-tracker service into focused layers without API changes
+Priority: P1
+Status: todo
+Scope:
+
+- `src/core/database/storage/storage.ts`
+- `src/core/database/storage/schema.ts`
+- `src/core/database/storage/cover-blob.ts`
+- `src/core/database/storage/records.ts`
+- `src/core/database/storage/write-path.ts`
+- `src/core/services/immersion-tracker/youtube.ts`
+- `src/core/services/immersion-tracker/youtube-manager.ts`
+- `src/core/services/immersion-tracker/write-queue.ts`
+- `src/core/services/immersion-tracker/immersion-tracker-service.ts`
+
+Acceptance:
+
+- behavior and public API remain unchanged for all callers
+- `storage.ts` responsibilities split into DDL/migrations, cover blob helpers, record CRUD, and write-path execution
+- `immersion-tracker-service.ts` reduces to session state, media change orchestration, query proxies, and lifecycle
+- YouTube code split into pure utilities, a stateful manager (`YouTubeManager`), and a dedicated write queue (`WriteQueue`)
+- removed `storage.ts` is replaced with focused modules and updated imports
+- no API or migration regressions; existing tests for trackers/storage coverage remain green or receive focused updates
+
+### SM-011
+
+Title: Add coverage reporting for maintained test lanes
+Priority: P1
+Status: done
+Scope:
+
+- `package.json`
+- CI workflow files under `.github/`
+- `docs/workflow/verification.md`
+  Acceptance:
+- at least one maintained test lane emits machine-readable coverage output
+- CI surfaces coverage as an artifact, summary, or check output
+- local contributor path for coverage is documented
+- chosen coverage path works with Bun/TypeScript lanes already maintained by the repo
+Implementation note:
+- Added `bun run test:coverage:src` for the maintained source lane via a sharded coverage runner, with merged LCOV output at `coverage/test-src/lcov.info` and CI/release artifact upload as `coverage-test-src`.
+
+### SM-012
+
+Title: Replace JSON serialize-clone helpers with structured cloning
+Priority: P2
+Status: todo
+Scope:
+
+- `src/runtime-options.ts`
+- `src/config/definitions.ts`
+- `src/config/service.ts`
+- `src/main/controller-config-update.ts`
+  Acceptance:
+- runtime/config clone helpers stop using `JSON.parse(JSON.stringify(...))`
+- replacement preserves current behavior for plain config/runtime objects
+- focused tests cover clone/merge behavior that could regress during the swap
+- no new clone helper is introduced in these paths without a documented reason
+
+Done:
+
+- replaced JSON serialize-clone call sites in runtime/config/controller update paths with `structuredClone`
+- updated focused tests and fixtures to cover detached clone behavior and guard against regressions
+
+### SM-013
+
+Title: Address PR #36 CodeRabbit action items
+Priority: P1
+Status: done
+Scope:
+
+- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh`
+- `scripts/subminer-change-verification.test.ts`
+- `src/core/services/immersion-tracker/query-sessions.ts`
+- `src/core/services/immersion-tracker/query-trends.ts`
+- `src/core/services/immersion-tracker/maintenance.ts`
+- `src/main/boot/services.ts`
+- `src/main/character-dictionary-runtime/zip.test.ts`
+Acceptance:
+- fix valid open CodeRabbit findings on PR #36
+- add focused regression coverage for behavior changes where practical
+- verify touched tests plus typecheck stay green
+
+Done:
+
+- hardened `--artifact-dir` validation in the verification script
+- fixed trend aggregation rounding and monthly ratio bucketing
+- preserved unwatched anime episodes in episode queries
+- restored seconds-based aggregate timestamps in shared maintenance
+- fixed the startup refactor compile break by making the predicates local at the call site
+- verified with `bun test src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts` and `bun run typecheck`

CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+- AniList: Stopped post-watch tracking from sending a second progress update when the current episode was already satisfied by a ready retry item in the same watch-completion pass.
+- Playback: Fixed managed local playback so duplicate startup-ready retries no longer unpause media after a later manual pause on the same file.
+- Playback: Fixed managed local subtitle auto-selection so local files reuse configured primary/secondary subtitle language priorities instead of staying on mpv's initial `sid=auto` guess.
+
+## v0.10.0 (2026-03-29)
+
+### Changed
+- Integrations: Replaced the deprecated Discord Rich Presence wrapper with the maintained `@xhayper/discord-rpc` package.
+
+### Fixed
+- Stats: Fixed stats startup so the immersion tracker can run when `Bun.serve` is unavailable.
+- Stats: Stats server now falls back to a Node `http` listener in Electron/runtime paths that do not expose Bun.
+- Overlay: Fixed the macOS visible-overlay toggle path so manual hides stay hidden and the plugin uses the explicit visible-overlay toggle command.
+- Subtitle Sidebar: Restored macOS mpv passthrough while the overlay subtitle sidebar is open so clicks outside the sidebar can refocus mpv and keep native keybindings working.
+
+### Internal
+- Release: Added a maintained source coverage lane that shards Bun coverage one test file at a time and merges LCOV output into `coverage/test-src/lcov.info`.
+- Release: CI and release quality-gate now upload the merged source-lane LCOV artifact for inspection.
+- Runtime: Extracted remaining inline runtime logic from `src/main.ts` into dedicated runtime modules and composer helpers.
+- Runtime: Added focused regression tests for the extracted runtime/composer boundaries.
+- Runtime: Updated task tracking notes to mark TASK-238.6 complete and confirm follow-on boot-phase split can be deferred.
+- Runtime: Split `src/main.ts` boot wiring into dedicated `src/main/boot/services.ts`, `src/main/boot/runtimes.ts`, and `src/main/boot/handlers.ts` modules.
+- Runtime: Added focused tests for the new boot-phase seams and kept the startup/typecheck/build verification lanes green.
+- Runtime: Updated internal architecture/task docs to record the boot-phase split and new ownership boundary.
+
+## v0.9.3 (2026-03-25)
+
+### Changed
+- Launcher: Moved YouTube primary subtitle language defaults to `youtube.primarySubLanguages`.
+- Launcher: Removed the placeholder YouTube subtitle retime step and now uses downloaded primary subtitle tracks directly, so there is no fake path rewrite before playback/sidebar loading.
+- YouTube: Removed the `src/core/services/youtube/retime` helper and its tests after retiring the internal retime strategy.
+- Docs: Clarified optional `alass` / `ffsubsync` subtitle-sync requirements and setup steps, including fallback behavior when sync tools are absent.
+- Launcher: Removed the old `youtubeSubgen.primarySubLanguages` config path from the generated config and docs.
+
 ## v0.9.2 (2026-03-25)
 
 ### Fixed

README.md

@@ -21,6 +21,8 @@ Look up words with Yomitan, export to Anki in one key, track your immersion —
 
 SubMiner runs as an invisible Electron overlay on top of mpv. Subtitles render as an interactive layer. Move your cursor over any word and trigger a [Yomitan](https://github.com/yomidevs/yomitan) lookup. Press one key to snapshot the sentence, audio, and screenshot into Anki via AnkiConnect.
 
+First-run setup requires the mpv plugin before it can finish. On Windows, the optional `SubMiner mpv` shortcut created during setup is the recommended playback entry point because it launches `mpv` with SubMiner's defaults directly, so you do not need an `mpv.conf` profile just to use it.
+
 ## Features
 
 ### Dictionary Lookups
@@ -63,12 +65,20 @@ Local stats dashboard — watch time, anime library, vocabulary growth, mining t
 
 <br>
 
+### Playlist Browser
+
+Browse sibling episode files and the active mpv queue in one overlay modal. Open it with `Ctrl+Alt+P` to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback.
+
+Managed local playback now reapplies your configured subtitle language priorities after mpv loads track metadata, so mixed subtitle sets can settle onto the expected primary and secondary tracks instead of staying on mpv's initial `sid=auto` guess.
+
+<br>
+
 ### Integrations
 
 <table>
   <tr>
     <td><b>YouTube</b></td>
-    <td>Auto-loaded yt-dlp subtitle tracks at startup with a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
+    <td>Auto-loaded yt-dlp subtitle tracks at startup with config-driven primary/secondary language priorities and a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
   </tr>
   <tr>
     <td><b>AniList</b></td>
@@ -84,7 +94,7 @@ Local stats dashboard — watch time, anime library, vocabulary growth, mining t
   </tr>
   <tr>
     <td><b>alass / ffsubsync</b></td>
-    <td>Automatic subtitle retiming</td>
+    <td>Automatic subtitle retiming — requires <code>alass</code> or <code>ffsubsync</code> on your <code>PATH</code> (optional; subtitle syncing is disabled without them)</td>
   </tr>
   <tr>
     <td><b>WebSocket</b></td>
@@ -102,12 +112,12 @@ Local stats dashboard — watch time, anime library, vocabulary growth, mining t
 
 ## Requirements
 
-|                | Required                                | Optional                               |
-| -------------- | --------------------------------------- | -------------------------------------- |
-| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                      |
-| **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic`      | `guessit` (AniSkip)                    |
-| **Media**      | —                                       | `yt-dlp`, `chafa`, `ffmpegthumbnailer` |
-| **Selection**  | —                                       | `fzf` / `rofi`                         |
+|                | Required                                | Optional                                                   |
+| -------------- | --------------------------------------- | ---------------------------------------------------------- |
+| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                                          |
+| **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic`      | `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
+| **Media**      | —                                       | `yt-dlp`, `chafa`, `ffmpegthumbnailer`                     |
+| **Selection**  | —                                       | `fzf` / `rofi`                                             |
 
 > [!NOTE]
 > [`bun`](https://bun.sh) is required if building from source or using the CLI wrapper: `subminer`. Pre-built releases (AppImage, DMG, installer) do not require it.
@@ -125,6 +135,8 @@ Local stats dashboard — watch time, anime library, vocabulary growth, mining t
 paru -S --needed mpv ffmpeg mecab-git mecab-ipadic
 # Optional
 paru -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo
+# Optional: subtitle sync (install at least one for subtitle syncing to work)
+paru -S --needed alass python-ffsubsync
 # X11 / XWAYLAND
 paru -S --needed xdotool xorg-xwininfo
 ```
@@ -138,6 +150,9 @@ paru -S --needed xdotool xorg-xwininfo
 brew install mpv ffmpeg mecab mecab-ipadic
 # Optional
 brew install yt-dlp fzf rofi chafa ffmpegthumbnailer
+# Optional: subtitle sync (install at least one for subtitle syncing to work)
+brew install alass
+pip install ffsubsync
 ```
 
 Grant Accessibility permission to SubMiner in **System Settings > Privacy & Security > Accessibility**.
@@ -213,7 +228,7 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
 
 ### 2. First Launch
 
-Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to install the mpv plugin and configure Yomitan dictionaries.
+Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to finish config, install the mpv plugin, and configure Yomitan dictionaries.
 
 ### 3. Mine
 
@@ -225,8 +240,6 @@ subminer stats -b           # stats daemon in background
 subminer stats -s           # stop background stats daemon
 ```
 
----
-
 ## Documentation
 
 Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: **[docs.subminer.moe](https://docs.subminer.moe)**