@gobing-ai/knowledge-kit 0.0.12 → 0.0.14

package/plugins/generations/news-report-gen/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@gobing-ai/news-report-gen",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-runtime": "catalog:",
+        "@gobing-ai/ts-utils": "catalog:",
+        "zod": "4.4.3"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    }
+}

package/plugins/generations/news-report-gen/plugin.json

@@ -0,0 +1,7 @@
+{
+    "name": "news-report-gen",
+    "kind": "generator",
+    "entry": "./dist/index.js",
+    "version": "1.0.0",
+    "description": "Assembles the per-run report from existing run artifacts: kept-candidate QC scores + per-dimension min/max/avg aggregates + threshold-rejected counts (rejected audit via NEWS_REPORT_REJECTED_FILE) + per-step wall-clock timing (step-timing.jsonl JSONL via NEWS_REPORT_TIMING_FILE). Output-only — no publish side effect (task 0117)."
+}

package/plugins/generations/news-report-gen/src/index.ts

@@ -0,0 +1,308 @@
+import { dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Content, ContentSchema, type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { atomicWriteJson, createNodeFileSystem, readJsonFile } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+
+/**
+ * news-report-gen: assemble the per-run report from existing run artifacts —
+ * kept-candidate QC scores, per-dimension min/max/avg aggregates, threshold-
+ * rejected counts, and per-step wall-clock timing. Output-only Content (task
+ * 0117): no publish side effect, no engine data channel (# ponytail: step
+ * boundary timing stitched at report time; upgrade path = engine-side ledger
+ * if drift ever matters).
+ *
+ * Inputs:
+ * - `--in` Doc[] — kept candidates (`2-plan/episode-plan.json`, built by the
+ *   workflow from the filter Content's metadata.docs). Scores live in
+ *   `metadata.scores` (quality/importance/urgency/impact 0-5).
+ * - `NEWS_REPORT_REJECTED_FILE` — the filter's rejected audit path
+ *   (`2-plan/candidates.rejected.json`, RejectedDoc[] of {doc, reasons});
+ *   absent or unreadable -> reject counts render as 0, never throw.
+ * - `NEWS_REPORT_TIMING_FILE` — `<work_dir>/step-timing.json` JSONL of
+ *   {step, startedAt, endedAt} appended by the workflow shell steps; missing
+ *   or unreadable -> the timing section is omitted, never throw.
+ * - Threshold consistency: `QC_MIN_*` envs — the exact names the workflow
+ *   already pins (must move in lockstep with episode-plan-gen's
+ *   DEFAULT_FILTER_CONFIG), so one grep shows both sides.
+ * - `NEWS_REPORT_DATE` (YYYYMMDD or ISO), else today (UTC).
+ */
+
+const QC_DIMENSIONS = ['quality', 'importance', 'urgency', 'impact'] as const;
+type QCDimension = (typeof QC_DIMENSIONS)[number];
+
+const QC_MIN_ENVS: Record<QCDimension, string> = {
+    quality: 'QC_MIN_QUALITY',
+    importance: 'QC_MIN_IMPORTANCE',
+    urgency: 'QC_MIN_URGENCY',
+    impact: 'QC_MIN_IMPACT',
+};
+
+interface TimingEntry {
+    step: string;
+    startedAt: string;
+    endedAt: string;
+}
+
+function scoreOf(doc: Doc, dim: QCDimension): number | null {
+    const meta = doc.metadata as Record<string, unknown> | undefined;
+    const value = (meta?.scores as Record<string, unknown> | undefined)?.[dim];
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** Per-dimension min/max/avg/count over the kept candidates' scores. */
+export function scoreAggregates(
+    docs: Doc[],
+): Record<QCDimension, { min: number | null; max: number | null; avg: number | null; count: number }> {
+    const out = {} as Record<
+        QCDimension,
+        { min: number | null; max: number | null; avg: number | null; count: number }
+    >;
+    for (const dim of QC_DIMENSIONS) {
+        const values = docs.map((d) => scoreOf(d, dim)).filter((v): v is number => v !== null);
+        const count = values.length;
+        out[dim] =
+            count === 0
+                ? { min: null, max: null, avg: null, count: 0 }
+                : {
+                      min: Math.min(...values),
+                      max: Math.max(...values),
+                      avg: Math.round((values.reduce((a, b) => a + b, 0) / count) * 10) / 10,
+                      count,
+                  };
+    }
+    return out;
+}
+
+/** Hostname of a URL-ish value; unparseable/absent → '—'. */
+function domainOf(value: unknown): string {
+    if (typeof value !== 'string' || value.trim() === '') return '—';
+    try {
+        return new URL(value).hostname || '—';
+    } catch {
+        return '—';
+    }
+}
+
+/**
+ * Per-source item counts with domain sub-counts from candidate metadata
+ * (`source`/`sourceName`, falling back to the URL hostname).
+ */
+export function sourceBreakdown(
+    docs: Doc[],
+): { source: string; items: number; domains: { domain: string; items: number }[] }[] {
+    const bySource = new Map<string, Map<string, number>>();
+    for (const doc of docs) {
+        const meta = doc.metadata as Record<string, unknown> | undefined;
+        const source = typeof meta?.source === 'string' && meta.source.trim() !== '' ? meta.source : '未知';
+        const domain =
+            typeof meta?.sourceName === 'string' && meta.sourceName.trim() !== ''
+                ? meta.sourceName
+                : domainOf(meta?.originalUrl ?? doc.sourceUri);
+        const domains = bySource.get(source) ?? new Map<string, number>();
+        domains.set(domain, (domains.get(domain) ?? 0) + 1);
+        bySource.set(source, domains);
+    }
+    return [...bySource.entries()]
+        .map(([source, domains]) => ({
+            source,
+            items: [...domains.values()].reduce((sum, count) => sum + count, 0),
+            domains: [...domains.entries()]
+                .map(([domain, count]) => ({ domain, items: count }))
+                .sort((a, b) => b.items - a.items || a.domain.localeCompare(b.domain)),
+        }))
+        .sort((a, b) => b.items - a.items || a.source.localeCompare(b.source));
+}
+
+/** Rejected-count per threshold dimension from the filter's rejection reasons (`dim:<score><<min>`). */
+export function rejectedCounts(
+    rejected: { doc: Doc; reasons: string[] }[],
+): Record<QCDimension, number> & { category: number } {
+    const out = { category: 0 } as Record<QCDimension, number> & { category: number };
+    for (const dim of QC_DIMENSIONS) out[dim] = 0;
+    for (const entry of rejected) {
+        if (entry.reasons.includes('category:not-in-allowlist')) out.category += 1;
+        for (const dim of QC_DIMENSIONS) {
+            if (entry.reasons.some((r) => r.startsWith(`${dim}:`))) out[dim] += 1;
+        }
+    }
+    return out;
+}
+
+export function minimumsFromEnv(): Record<QCDimension, number | null> {
+    const out = {} as Record<QCDimension, number | null>;
+    for (const dim of QC_DIMENSIONS) {
+        const raw = process.env[QC_MIN_ENVS[dim]];
+        const n = raw === undefined || raw.trim() === '' ? Number.NaN : Number.parseInt(raw, 10);
+        out[dim] = Number.isFinite(n) ? n : null;
+    }
+    return out;
+}
+
+interface RejectedAudit {
+    doc: Doc;
+    reasons: string[];
+}
+
+/** Parse the timing JSONL; unreadable/missing -> [] (never throw). Last entry per step wins. */
+export async function readTiming(path: string | undefined): Promise<TimingEntry[]> {
+    if (!path || path.trim() === '') return [];
+    let raw: string;
+    try {
+        raw = await Bun.file(path).text();
+    } catch {
+        return [];
+    }
+    const last = new Map<string, TimingEntry>();
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '') continue;
+        try {
+            const entry = JSON.parse(trimmed) as Partial<TimingEntry>;
+            if (typeof entry.step !== 'string' || entry.step.trim() === '') continue;
+            if (typeof entry.startedAt !== 'string' || typeof entry.endedAt !== 'string') continue;
+            last.set(entry.step, { step: entry.step, startedAt: entry.startedAt, endedAt: entry.endedAt });
+        } catch {
+            // skip malformed JSONL line (# ponytail: report-side tolerance, stamping owns the format)
+        }
+    }
+    return [...last.values()];
+}
+
+function durationMs(entry: TimingEntry): number | null {
+    const start = Date.parse(entry.startedAt);
+    const end = Date.parse(entry.endedAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+    return Math.max(0, end - start);
+}
+
+/** Render the report markdown for a kept-candidate Doc[] (pure — exported for tests). */
+export function renderReportMarkdown(
+    docs: Doc[],
+    date: string,
+    options: { rejected?: { doc: Doc; reasons: string[] }[]; timing?: TimingEntry[] } = {},
+): string {
+    const lines: string[] = [`# 每日 AI 语音运行报告 — ${date}`, ''];
+    lines.push('## 选稿评分（保留候选）', '');
+    if (docs.length === 0) {
+        lines.push('本期无保留候选。', '');
+    } else {
+        lines.push('| # | 候选 | quality | importance | urgency | impact |', '| --- | --- | --- | --- | --- | --- |');
+        docs.forEach((doc, i) => {
+            const cells = QC_DIMENSIONS.map((dim) => scoreOf(doc, dim) ?? '—');
+            lines.push(`| ${i + 1} | ${(doc.title ?? doc.id ?? '').replace(/\|/g, '\\|')} | ${cells.join(' | ')} |`);
+        });
+        lines.push('');
+        const agg = scoreAggregates(docs);
+        lines.push('**维度聚合**（min / max / avg / 样本数）', '');
+        lines.push('| 维度 | min | max | avg | count |', '| --- | --- | --- | --- | --- |');
+        for (const dim of QC_DIMENSIONS) {
+            const a = agg[dim];
+            lines.push(`| ${dim} | ${a.min ?? '—'} | ${a.max ?? '—'} | ${a.avg ?? '—'} | ${a.count} |`);
+        }
+        lines.push('');
+        lines.push('## 来源分布', '');
+        lines.push('| 来源 | 条数 | 域名 |', '| --- | --- | --- |');
+        for (const group of sourceBreakdown(docs)) {
+            const domainCell = group.domains.map((d) => `${d.domain.replace(/\|/g, '\\|')} (${d.items})`).join(', ');
+            lines.push(`| ${group.source} | ${group.items} | ${domainCell || '—'} |`);
+        }
+        lines.push('');
+    }
+
+    const mins = minimumsFromEnv();
+    const counts = rejectedCounts(options.rejected ?? []);
+    lines.push('## 阈值拒绝计数', '');
+    lines.push('| 检查 | 阈值 | 拒绝数 |', '| --- | --- | --- |');
+    for (const dim of QC_DIMENSIONS) {
+        const min = mins[dim];
+        lines.push(`| ${dim} | ${min === null ? '—' : min} | ${counts[dim]} |`);
+    }
+    lines.push(`| category allowlist | — | ${counts.category} |`);
+    lines.push('');
+
+    const timing = options.timing ?? [];
+    if (timing.length > 0) {
+        lines.push('## 步耗时', '');
+        lines.push('| 步骤 | startedAt | endedAt | 耗时 |', '| --- | --- | --- | --- |');
+        let totalMs = 0;
+        let totalKnown = true;
+        for (const entry of timing) {
+            const ms = durationMs(entry);
+            if (ms === null) totalKnown = false;
+            else totalMs += ms;
+            lines.push(`| ${entry.step} | ${entry.startedAt} | ${entry.endedAt} | ${ms === null ? '—' : `${ms} ms`} |`);
+        }
+        lines.push('');
+        if (totalKnown) lines.push(`**总耗时**: ${totalMs} ms（各步相加）`, '');
+    }
+
+    return lines.join('\n');
+}
+
+/** Read the rejected audit; absent/unreadable/malformed -> [] (never throw). */
+export async function readRejectedAudit(path: string | undefined): Promise<RejectedAudit[]> {
+    if (!path || path.trim() === '') return [];
+    try {
+        const parsed = JSON.parse(await Bun.file(path).text());
+        return Array.isArray(parsed) ? (parsed as RejectedAudit[]) : [];
+    } catch {
+        return [];
+    }
+}
+
+/** Build the report Content from a kept-candidate Doc[]. */
+export function docsToContent(
+    docs: Doc[],
+    date: string,
+    options: { rejected?: { doc: Doc; reasons: string[] }[]; timing?: TimingEntry[] },
+): Content {
+    return ContentSchema.parse({
+        title: `每日 AI 语音运行报告 — ${date}`,
+        body: renderReportMarkdown(docs, date, options),
+        format: 'markdown',
+        metadata: { generator: 'kk:news-report', date, doc_count: docs.length },
+    });
+}
+
+function dateFromEnv(): string {
+    const raw = process.env.NEWS_REPORT_DATE ?? new Date().toISOString().slice(0, 10);
+    return raw.length === 8 ? `${raw.slice(0, 4)}-${raw.slice(4, 6)}-${raw.slice(6, 8)}` : raw;
+}
+
+export async function processGeneratorIO(inputPath: string, outputPath: string): Promise<Content> {
+    const docs = DocListSchema.parse(await readJsonFile(inputPath));
+    const rejected = await readRejectedAudit(process.env.NEWS_REPORT_REJECTED_FILE);
+    const timing = await readTiming(process.env.NEWS_REPORT_TIMING_FILE);
+    const content = docsToContent(docs, dateFromEnv(), { rejected, timing });
+    const fs = createNodeFileSystem();
+    const outDir = dirname(outputPath);
+    if (outDir && outDir !== '.') await fs.ensureDir(outDir);
+    await atomicWriteJson(outputPath, content, fs);
+    return content;
+}
+
+export async function main(): Promise<number> {
+    let values: { in?: string; out?: string };
+    try {
+        ({ values } = parseArgs({ options: { in: { type: 'string' }, out: { type: 'string' } } }));
+    } catch (err: unknown) {
+        echoError(`news-report-gen failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    if (!values.in || !values.out) {
+        echoError('news-report-gen failed: Missing required arguments: --in <docs.json> --out <content.json>');
+        return 1;
+    }
+    try {
+        await processGeneratorIO(values.in, values.out);
+        return 0;
+    } catch (err: unknown) {
+        echoError(`news-report-gen failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

package/plugins/generations/news-report-gen/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}

package/plugins/generations/omni-voice-gen/Makefile

@@ -0,0 +1,14 @@
+.PHONY: sync test coverage lint
+
+sync:
+	uv sync
+
+test:
+	uv run pytest -q
+
+coverage:
+	uv run pytest --cov=omni_voice_gen -q
+	uv run python scripts/coverage_gate.py
+
+lint:
+	uv run ruff check src tests scripts

package/plugins/generations/omni-voice-gen/README.md

@@ -0,0 +1,112 @@
+# omni-voice-gen
+
+OmniVoice-backed voice generator plugin for [knowledge-kit](../../../README.md).
+Drop-in replacement for `voice-gen` — same `kk executor run` contract (`--in Doc[] --out Content`),
+same audio metadata shape, same QC pipeline. Swap the backend in `kk-daily-ai-voice` with:
+
+```bash
+spur workflow run plugins/kk/workflows/kk-daily-ai-voice.yaml \
+  --vars '{"voice_generator":"omni-voice-gen"}'   # other vars per your kk config
+```
+
+The default `voice_generator` is `voice-gen` (production behavior unchanged; swap is operator opt-in).
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+make sync          # runs `uv sync` — creates .venv, installs omnivoice from PyPI + dev deps
+```
+
+> **First-run note:** `omnivoice` pulls `k2-fsa/OmniVoice` from Hugging Face on first generate
+> (~2–4 GB depending on device). The Whisper ASR model used for transcription-fidelity QC loads
+> lazily on the first QC transcription (`OMNIVOICE_ASR_MODEL` overrides it). Subsequent runs
+> use the HF cache. `OMNIVOICE_MODEL` overrides the model id or points to a local checkout.
+> GPU (`cuda`) is auto-selected when available; MPS (Apple Silicon) and CPU are fallbacks.
+> Set `OMNIVOICE_DEVICE` to override (e.g. `cpu` for CI).
+
+### 2. Verify
+
+```bash
+make test          # pytest (FakeBackend — no model load, no network)
+make coverage      # pytest + per-file line/function >= 90% gate
+make lint          # ruff check
+```
+
+## Profile registry
+
+Profiles map a name to one of three voice-specification kinds. The registry lives at
+`profiles.json` (override with `OMNIVOICE_PROFILE_REGISTRY`).
+
+### Kinds
+
+| Kind | JSON shape | When to use |
+|------|-----------|-------------|
+| **Clone** | `{ "ref_audio": "<path>", "ref_text": "<transcript>" }` | 3–10 s reference clip + its transcript |
+| **Saved prompt** | `{ "prompt": "<path>.pt" }` | Pre-computed clone prompt via `create_voice_clone_prompt` |
+| **Instruct** | `{ "instruct": "<description>" }` | Text description of the desired voice style |
+
+### Creating a profile (clone example)
+
+1. Record a 3–10 second WAV clip of the target voice.
+2. Transcribe it (the exact words spoken in the clip).
+3. Add an entry to `profiles.json`:
+
+```json
+{
+    "robin-news": {
+        "ref_audio": "/path/to/robin-ref.wav",
+        "ref_text": "This is Robin, bringing you today's AI news."
+    }
+}
+```
+
+> **Never commit private audio paths or real operator clips.** The shipped `profiles.json` contains
+> only documented placeholder entries. Copy and edit locally; the file is operator-private.
+
+### Resolution order
+
+Segment `profile` → speaker `profile` → script `default_profile` → `VOICEBOX_DEFAULT_PROFILE` env
+→ doc `metadata.voiceProfile`. Unknown name → exit 1 naming the profile.
+
+Relative `ref_audio` / `prompt` paths in registry entries resolve against the process working
+directory (they are passed to the backend unmodified) — prefer absolute paths.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VOICEBOX_DEFAULT_PROFILE` | no | — | Fallback profile name (parity with voice-gen) |
+| `VOICE_GEN_MP3` | no | off | `true`/`1`/`yes`/`on` → ffmpeg sibling MP3; missing ffmpeg → exit 1 |
+| `VOICE_GEN_MAX_RUN_MS` | no | unlimited | Total render budget (ms), checked between segments |
+| `VOICE_GEN_FAIL_ON_QC` | no | off | `true` + failing QC → exit 1 |
+| `OMNIVOICE_MODEL` | no | `k2-fsa/OmniVoice` | HF model id or local path |
+| `OMNIVOICE_ASR_MODEL` | no | omnivoice default Whisper | ASR model for transcription-fidelity QC (loads lazily on first QC) |
+| `OMNIVOICE_DEVICE` | no | auto (`cuda`→`mps`→`cpu`) | Torch device |
+| `OMNIVOICE_SPEED` | no | `1.0` | Speaking-rate factor |
+| `OMNIVOICE_PROFILE_REGISTRY` | no | `<plugin>/profiles.json` | Profile registry path override |
+
+**Not honored** (Voicebox-transport knobs): `VOICEBOX_URL`, `VOICEBOX_TIMEOUT_MS`,
+`VOICEBOX_POLL_MS`, `VOICEBOX_MAX_CHUNK_CHARS`, `VOICEBOX_CROSSFADE_MS`. The render budget is
+`VOICE_GEN_MAX_RUN_MS`.
+
+## Make targets
+
+| Target | Description |
+|--------|-------------|
+| `make sync` | `uv sync` — install/update deps into `.venv` |
+| `make test` | `uv run pytest -q` |
+| `make coverage` | pytest + `scripts/coverage_gate.py` (per-file line/function >= 90%) |
+| `make lint` | `uv run ruff check src tests scripts` |
+
+## Usage with kk-solo-podcast
+
+`kk-solo-podcast.yaml` currently uses `voice-gen` directly. It can adopt the same `voice_generator`
+var pattern later — out of F611 scope (one-line change when ready).
+
+## See also
+
+- [Design spec](../../../docs/design/omni-voice-gen.md) — decisions, interfaces, invariants
+- [voice-gen](../voice-gen/) — the Voicebox-backed sibling this plugin replaces
+- [kk-daily-ai-voice.yaml](../../kk/workflows/kk-daily-ai-voice.yaml) — the workflow that selects the generator

package/plugins/generations/omni-voice-gen/bin/omni-voice-gen

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec uv run --project "$(cd "$(dirname "$0")/.." && pwd)" python -m omni_voice_gen "$@"

package/plugins/generations/omni-voice-gen/dist/omni-voice-gen-prr8skpb.

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec uv run --project "$(cd "$(dirname "$0")/.." && pwd)" python -m omni_voice_gen "$@"

package/plugins/generations/omni-voice-gen/dist/omni-voice-gen.js

@@ -0,0 +1,6 @@
+// @bun
+// ../../plugins/generations/omni-voice-gen/bin/omni-voice-gen
+var omni_voice_gen_default = "./omni-voice-gen-prr8skpb.";
+export {
+  omni_voice_gen_default as default
+};

package/plugins/generations/omni-voice-gen/plugin.json

@@ -0,0 +1,6 @@
+{
+    "name": "omni-voice-gen",
+    "kind": "generator",
+    "entry": "./dist/index.js",
+    "version": "1.0.0"
+}

package/plugins/generations/omni-voice-gen/profiles.json

@@ -0,0 +1,12 @@
+{
+    "sample-clone": {
+        "ref_audio": "voices/sample-ref.wav",
+        "ref_text": "Replace with the transcript of your reference clip."
+    },
+    "sample-prompt": {
+        "prompt": "voices/sample-prompt.pt"
+    },
+    "sample-narrator": {
+        "instruct": "Speak in a calm, measured narrator voice."
+    }
+}

package/plugins/generations/omni-voice-gen/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "omni-voice-gen"
+version = "1.0.0"
+description = "OmniVoice-backed voice generator plugin for knowledge-kit"
+requires-python = ">=3.10"
+dependencies = [
+    "omnivoice",
+    "pyyaml",
+    "pydantic",
+]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "coverage",
+    "ruff",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/omni_voice_gen"]

package/plugins/generations/omni-voice-gen/scripts/coverage_gate.py

@@ -0,0 +1,74 @@
+"""Per-file coverage gate: line AND function coverage >= 90% over the .coverage data.
+
+Function coverage has no native coverage.py metric, so the gate derives it: a
+function counts as covered when its `def` line executed AND at least one body
+line executed (def/body line sets from ast; measured lines from the coverage.py
+API). Line coverage uses coverage.py's own per-file analysis. Exit 1 listing
+every offender below threshold.
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+THRESHOLD = 0.90
+
+
+def function_map(path: Path) -> list[tuple[int, set[int]]]:
+    """(def_lineno, {body linenos}) for every function/method in a source file."""
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    out: list[tuple[int, set[int]]] = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            body = {child.lineno for child in ast.walk(node) if hasattr(child, "lineno") and child.lineno != node.lineno}
+            out.append((node.lineno, body))
+    return out
+
+
+def main() -> int:
+    from coverage import Coverage
+
+    cov = Coverage(data_file=".coverage")
+    cov.load()
+    measured = cov.get_data().measured_files()
+    if not measured:
+        print("coverage_gate: no coverage data found; run `make coverage` first", file=sys.stderr)
+        return 1
+
+    offenders: list[str] = []
+    for measured_path in sorted(measured):
+        try:
+            rel = Path(measured_path).relative_to(Path.cwd())
+        except ValueError:
+            continue
+        # Gate scope: package sources only (src/omni_voice_gen/<module>.py).
+        if len(rel.parts) < 3 or rel.parts[-3:-1] != ("src", "omni_voice_gen"):
+            continue
+        executed = set(cov.get_data().lines(measured_path) or [])
+        _, statements, _, missing, _ = cov.analysis2(str(rel))
+        if not statements:
+            continue
+        line_pct = (len(statements) - len(missing)) / len(statements)
+
+        funcs = function_map(rel)
+        func_pct = 1.0
+        if funcs:
+            covered = sum(1 for def_line, body in funcs if def_line in executed and body & executed)
+            func_pct = covered / len(funcs)
+
+        if line_pct < THRESHOLD or func_pct < THRESHOLD:
+            offenders.append(f"{rel}: line {line_pct:.1%}, function {func_pct:.1%} (both must be >= 90%)")
+
+    if offenders:
+        print("coverage_gate: FAIL (threshold 90% line and function, per file)", file=sys.stderr)
+        for line in offenders:
+            print(f"  {line}", file=sys.stderr)
+        return 1
+    print("coverage_gate: PASS (line and function coverage >= 90% per file)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugins/generations/omni-voice-gen/src/omni_voice_gen/__init__.py

@@ -0,0 +1 @@
+"""omni-voice-gen: OmniVoice-backed voice generator plugin (generator kind)."""

package/plugins/generations/omni-voice-gen/src/omni_voice_gen/__main__.py

@@ -0,0 +1,39 @@
+"""CLI entry (kk executor spawn seam): --in Doc[] JSON -> --out Content JSON.
+
+Exit codes mirror voice-gen main(): 0 success; 1 on any failure with
+`omni-voice-gen failed: <msg>` on stderr. IO, cleanup, and the empty-input notice live in
+pipeline.run; torch/omnivoice import only inside OmnivoiceBackend methods, so the
+empty-input notice path never loads the model stack.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def _fail(msg: str) -> int:
+    print(f"omni-voice-gen failed: {msg}", file=sys.stderr)
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="omni-voice-gen")
+    parser.add_argument("--in", dest="in_path")
+    parser.add_argument("--out", dest="out_path")
+    args = parser.parse_args(argv)
+
+    if not args.in_path or not args.out_path:
+        return _fail("Missing required arguments: --in and --out")
+
+    try:
+        from .pipeline import run  # lazy: argument errors never import the render stack
+
+        run(args.in_path, args.out_path)
+    except Exception as exc:  # noqa: BLE001 — every failure maps onto the single fail-loud exit (voice-gen main parity)
+        return _fail(str(exc))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover — `python -m` entry guard
+    sys.exit(main())