@gobing-ai/knowledge-kit 0.1.11 → 0.1.13

package/plugins/kk/scripts/kk-workflow-stages.ts

@@ -1442,6 +1442,180 @@ function dailyPublishPartial(args: string[]): void {
  * `KK_SURFDASH_PATCH_OFFLINE=1` keeps fixture tests hermetic — the plugin would otherwise write to,
  * commit and push a real checkout.
  */
+/**
+ * `publish-matrix-partial` (0333): a partial/none window leaves an explicit recovery marker.
+ *
+ * Reads the window's receipt-derived outcome (written by `publish-matrix-classify`) — the legacy
+ * `_17_publish_result.json` aggregate is never an input — names the exact failed target ids, and
+ * points at the matrix rerun contract (`kk stage run publish-matrix-send <work_dir> --window <w>
+ * --retry`). The rerun is receipt-scoped: `--retry` resends only effect-none failures, never a
+ * succeeded or live-uncertain row, so there is no `--retry-from`/`_17` style file replay. A full
+ * window deletes any stale marker from a previous attempt, so the report never re-flags recovered
+ * targets.
+ */
+function publishMatrixPartial(args: string[]): void {
+    const flag = (name: string): string | undefined => {
+        const i = args.indexOf(name);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const workDir = args[0] ?? '';
+    const window = flag('--window');
+    if (workDir === '' || window === undefined || window === '') {
+        failWith(1, 'usage: publish-matrix-partial <work_dir> --window <w>');
+    }
+    const outcomePath = join(workDir, '4-publish', `outcome.${window}.json`);
+    const outcome = requireJson(outcomePath, 'publish-matrix-partial') as {
+        status?: string;
+        rows?: Array<{ id?: string; status?: string; dummy?: boolean }>;
+    };
+    const marker = join(workDir, '4-publish', `partial-marker.${window}.txt`);
+    timed(workDir, 'publish-matrix-partial', () => {
+        if (outcome.status === 'full') {
+            if (isFile(marker)) sted('rm', marker, () => unlinkSync(marker));
+            return;
+        }
+        const failed = (outcome.rows ?? [])
+            .filter((row) => row.dummy !== true && row.status !== 'succeeded')
+            .map((row) => row.id ?? '(unknown)')
+            .join(',');
+        sted('mkdir', dirname(marker), () => mkdirSync(dirname(marker), { recursive: true }));
+        sted('write', marker, () =>
+            writeRaw(
+                marker,
+                `window ${window} ended ${outcome.status ?? 'unknown'}: failed targets: ${failed === '' ? '(unparsed)' : failed}\n` +
+                    `recovery: kk stage run publish-matrix-send ${workDir} --window ${window} --retry (resends effect-none failures only; receipts scope the retry)\n`,
+            ),
+        );
+        console.error(`WARNING: partial publish — failed targets: ${failed === '' ? '(unparsed)' : failed}`);
+    });
+}
+
+/**
+ * `publish-matrix-patch-surfdash` (0333): patch podcast links into a real surfdash post.
+ *
+ * The patch payload is derived from the window's own receipts, not from legacy aggregate files and
+ * not from a `KK_SURFDASH_ROOT` argument — the plugin resolves its checkout itself. Evidence rules:
+ * the surfdash row must have a real (non-dummy) succeeded receipt whose aggregate metadata carries
+ * an absolute `postPath`; without that there is nothing to patch and the stage records an explicit
+ * skip result instead of fabricating one. Podcast links ride along only when the podcast row is
+ * real too — a dummy or missing episode yields explicit empty `coverUrl`/`showNotesUrl`, never a
+ * fabricated link. `KK_SURFDASH_PATCH_OFFLINE=1` keeps rehearsal runs hermetic the same way the
+ * legacy voice2 stage does.
+ */
+function publishMatrixPatchSurfdash(args: string[]): void {
+    const flag = (name: string): string | undefined => {
+        const i = args.indexOf(name);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const workDir = args[0] ?? '';
+    const window = flag('--window');
+    if (workDir === '' || window === undefined || window === '') {
+        failWith(1, 'usage: publish-matrix-patch-surfdash <work_dir> --window <w>');
+    }
+    const publishDir = join(workDir, '4-publish');
+    const resultPath = join(publishDir, 'patch-surfdash.result.json');
+    const writeResult = (value: Record<string, unknown>): void => {
+        sted('write', resultPath, () => writeJqText(resultPath, value));
+    };
+    const receipt = (id: string): Record<string, unknown> | null =>
+        readJson(join(publishDir, 'receipts', `${id}.json`));
+    const aggregateTarget = (receiptPath: string | undefined): Record<string, unknown> => {
+        const aggregate = receiptPath === undefined ? null : readJson(receiptPath);
+        const targets = aggregate?.targets;
+        if (!Array.isArray(targets) || targets.length === 0 || targets[0] === null || typeof targets[0] !== 'object') {
+            return {};
+        }
+        return targets[0] as Record<string, unknown>;
+    };
+    timed(workDir, 'publish-matrix-patch-surfdash', () => {
+        const outcome = readJson(join(publishDir, `outcome.${window}.json`)) as {
+            rows?: Array<{ id?: string }>;
+        } | null;
+        const rowId = (prefix: string): string | undefined =>
+            (outcome?.rows ?? []).map((row) => row.id ?? '').find((id) => id.startsWith(prefix));
+        const sdId = rowId('surfdash-pub');
+        const podId = rowId('podcast-pub');
+        if (sdId === undefined) {
+            const error = 'skipped: no surfdash target in this window — nothing to patch';
+            writeResult({ ok: false, target: 'surfdash-pub', error });
+            console.error(`patch-surfdash: ${error}`);
+            return;
+        }
+        const sdReceipt = receipt(sdId);
+        const sdReal = sdReceipt !== null && sdReceipt?.dummy !== true && sdReceipt?.status === 'succeeded';
+        const sdTarget = aggregateTarget(
+            typeof sdReceipt?.aggregatePath === 'string' ? sdReceipt.aggregatePath : undefined,
+        );
+        const postPath = (sdTarget.metadata as Record<string, unknown> | undefined)?.postPath;
+        if (!sdReal || typeof postPath !== 'string' || postPath === '') {
+            const error =
+                sdReceipt === null
+                    ? 'skipped: no surfdash publish receipt — nothing to patch'
+                    : typeof postPath !== 'string' || postPath === ''
+                      ? 'skipped: surfdash receipt carries no real postPath — nothing to patch'
+                      : 'skipped: surfdash receipt is dummy — nothing to patch';
+            writeResult({ ok: false, target: 'surfdash-pub', error });
+            console.error(`patch-surfdash: ${error}`);
+            return;
+        }
+        // Links ride along only from real podcast evidence; dummy/missing episodes patch as
+        // explicit empty strings — the patch must never fabricate a link.
+        const podReceipt = podId === undefined ? null : receipt(podId);
+        const podReal = podReceipt !== null && podReceipt?.dummy !== true && podReceipt?.status === 'succeeded';
+        const podTarget = aggregateTarget(
+            typeof podReceipt?.aggregatePath === 'string' ? podReceipt.aggregatePath : undefined,
+        );
+        const podMeta = (podTarget.metadata ?? {}) as Record<string, unknown>;
+        const runDate = String(readJson(join(publishDir, `outcome.${window}.json`))?.runDate ?? '');
+        const payload = join(publishDir, 'patch-surfdash.payload.json');
+        sted('write', payload, () =>
+            writeJqText(payload, {
+                body: '',
+                options: {
+                    operation: 'patch',
+                    postPath,
+                    coverUrl: podReal && typeof podMeta.imageUrl === 'string' ? podMeta.imageUrl : '',
+                    showNotesUrl: podReal && typeof podTarget.url === 'string' ? podTarget.url : '',
+                    ...(runDate.length === 8
+                        ? { dateIso: `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}` }
+                        : runDate.length === 10
+                          ? { dateIso: runDate }
+                          : {}),
+                },
+            }),
+        );
+        if (process.env.KK_SURFDASH_PATCH_OFFLINE === '1') {
+            // Offline rehearsals still derive the payload (evidence), but never invoke the plugin.
+            writeResult({ ok: false, target: 'surfdash-pub', error: 'skipped: offline (KK_SURFDASH_PATCH_OFFLINE=1)' });
+            console.error(
+                'patch-surfdash: offline — payload derived, plugin patch skipped (KK_SURFDASH_PATCH_OFFLINE=1)',
+            );
+            return;
+        }
+        const status = kk(['executor', 'run', 'surfdash-pub', '--in', payload, '--out', resultPath], {
+            unset: NESTED_SPUR_UNSET,
+            soft: true,
+        });
+        const result = readJson(resultPath);
+        if (result?.ok === true) {
+            const meta = (result.metadata ?? {}) as Record<string, unknown>;
+            console.error(
+                `patch-surfdash: ${String(result.message ?? 'patched')} — cms-resync ${String(meta.cmsResync ?? 'ok')}`,
+            );
+            return;
+        }
+        const meta = (result?.metadata ?? {}) as Record<string, unknown>;
+        if (meta.cmsResync === 'failed') {
+            // The posts are patched and committed; only the CMS re-sync (a soft channel) failed.
+            console.error(
+                `patch-surfdash: WARNING: cms re-sync failed — ${String(result?.error ?? `exit ${status}`)}; fix: kk executor run surfdash-pub --in ${payload} --out ${resultPath}`,
+            );
+            return;
+        }
+        failWith(1, `patch-surfdash: ${String(result?.error ?? `surfdash-pub patch exited ${status}`)}`);
+    });
+}
+
 function dailyPatchSurfdash(args: string[]): void {
     const [workDir = '', runDate = '', surfdashRoot = '', pluginsPath = ''] = args;
     if (!surfdashRoot || !existsSync(surfdashRoot)) {
@@ -1718,6 +1892,11 @@ if (import.meta.main)
             dailyPreflight(rest);
             break;
         }
+        case 'daily-safety-manifest': {
+            const { dailySafetyManifest } = await loadDailyStages();
+            dailySafetyManifest(rest);
+            break;
+        }
         case 'daily-safety-prep': {
             const { dailySafetyPrep } = await loadDailyStages();
             dailySafetyPrep(rest);
@@ -1768,6 +1947,11 @@ if (import.meta.main)
             dailyQualityReport(rest);
             break;
         }
+        case 'daily-quality-verdict': {
+            const { dailyQualityVerdict } = await loadDailyStages();
+            dailyQualityVerdict(rest);
+            break;
+        }
         case 'daily-publish-prep': {
             const { dailyPublishPrep } = await loadDailyStages();
             dailyPublishPrep(rest);
@@ -1820,6 +2004,12 @@ if (import.meta.main)
         case 'daily-publish-partial':
             dailyPublishPartial(rest);
             break;
+        case 'publish-matrix-partial':
+            publishMatrixPartial(rest);
+            break;
+        case 'publish-matrix-patch-surfdash':
+            publishMatrixPatchSurfdash(rest);
+            break;
         case 'daily-run-report':
             dailyRunReport(rest);
             break;

package/plugins/kk/scripts/safety-artifact-check.ts

@@ -41,8 +41,10 @@ function readJson(path: string): JsonObject | null {
     }
 }
 
-function safetyPath(workDir: string, runDate: string, name: string): string {
-    return join(workDir, '24-script', `${runDate}_09_${name}`);
+/** 0331: scope-aware artifact root — `24-script` (or empty) keeps the drafts paths byte-identical. */
+function safetyPath(workDir: string, scopeDir: string, runDate: string, name: string): string {
+    const dir = scopeDir.trim() === '' || scopeDir.trim() === '24-script' ? '24-script' : scopeDir.trim();
+    return join(workDir, dir, `${runDate}_09_${name}`);
 }
 
 function nonEmptyString(value: unknown): value is string {
@@ -59,9 +61,9 @@ function sortedUnique(values: string[]): string[] | null {
     return unique.length === values.length ? unique.sort() : null;
 }
 
-function reportValid(workDir: string, runDate: string): string | null {
-    const request = readJson(safetyPath(workDir, runDate, 'safety-review_request.json'));
-    const report = readJson(safetyPath(workDir, runDate, 'safety-review_report.json'));
+function reportValid(workDir: string, scopeDir: string, runDate: string): string | null {
+    const request = readJson(safetyPath(workDir, scopeDir, runDate, 'safety-review_request.json'));
+    const report = readJson(safetyPath(workDir, scopeDir, runDate, 'safety-review_report.json'));
     if (request === null || report === null) return 'review request or report is missing/invalid JSON';
 
     const requested = stringList(request.platforms);
@@ -100,8 +102,8 @@ function reportValid(workDir: string, runDate: string): string | null {
     return null;
 }
 
-function judgeValid(workDir: string, runDate: string): string | null {
-    const verdict = readJson(safetyPath(workDir, runDate, 'safety-judge_verdict.json'));
+function judgeValid(workDir: string, scopeDir: string, runDate: string): string | null {
+    const verdict = readJson(safetyPath(workDir, scopeDir, runDate, 'safety-judge_verdict.json'));
     if (verdict === null) return 'judge verdict is missing/invalid JSON';
     if (!VERDICTS.has(String(verdict.verdict))) return 'judge verdict value is invalid';
     if (!CONFIDENCE.has(String(verdict.confidence))) return 'judge confidence is missing/invalid';
@@ -149,10 +151,10 @@ function judgeValid(workDir: string, runDate: string): string | null {
  * Only the gate's persisted status represents a real content-safety escalation, so unattended mode
  * rejects that status while attended mode leaves it for the caller's pause node.
  */
-function publishValid(workDir: string, runDate: string, unattendedArg: string): string | null {
+function publishValid(workDir: string, scopeDir: string, runDate: string, unattendedArg: string): string | null {
     if (unattendedArg !== 'true' && unattendedArg !== 'false') return 'unattended must be true or false';
-    const verdictToken = safetyPath(workDir, runDate, 'safety-verdict.status');
-    const gateStatusPath = safetyPath(workDir, runDate, 'safety-judge_status.txt');
+    const verdictToken = safetyPath(workDir, scopeDir, runDate, 'safety-verdict.status');
+    const gateStatusPath = safetyPath(workDir, scopeDir, runDate, 'safety-judge_status.txt');
     let token = '';
     let gateStatus = '';
     try {
@@ -171,27 +173,62 @@ function publishValid(workDir: string, runDate: string, unattendedArg: string):
     return null;
 }
 
-function draftDigest(workDir: string, runDate: string): string | null {
-    const article = join(workDir, '22-article', `${runDate}_06_article_content.json`);
-    const script = join(workDir, '24-script', `${runDate}_08_script_voicescript.yaml`);
+function draftDigest(workDir: string, scopeDir: string, runDate: string): string | null {
+    const hash = createHash('sha256');
+    if (scopeDir.trim() === '' || scopeDir.trim() === '24-script') {
+        const article = join(workDir, '22-article', `${runDate}_06_article_content.json`);
+        const script = join(workDir, '24-script', `${runDate}_08_script_voicescript.yaml`);
+        try {
+            hash.update(readFileSync(article)).update('\0');
+            hash.update(readFileSync(script)).update('\0');
+            return hash.digest('hex');
+        } catch {
+            return null;
+        }
+    }
+    // Variants scope: digest over the manifest's sorted keys + current bytes (mirrors the
+    // daily-stages scopeDigest algorithm, so request/guard/verdict all bind the same bytes).
     try {
-        const hash = createHash('sha256');
-        hash.update(readFileSync(article)).update('\0');
-        hash.update(readFileSync(script)).update('\0');
+        const manifest = readJson(join(workDir, '4-safety-variants', 'manifest.json')) as {
+            variants?: Record<string, { path?: unknown }>;
+        } | null;
+        if (manifest === null || !isObject(manifest.variants)) return null;
+        for (const key of Object.keys(manifest.variants).sort()) {
+            const path = join(workDir, String(manifest.variants[key].path));
+            hash.update(key).update('\0').update(readFileSync(path)).update('\0');
+        }
         return hash.digest('hex');
     } catch {
         return null;
     }
 }
 
-function revisionValid(workDir: string, runDate: string): string | null {
-    const request = readJson(safetyPath(workDir, runDate, 'safety-review_request.json'));
+function revisionValid(workDir: string, scopeDir: string, runDate: string): string | null {
+    const request = readJson(safetyPath(workDir, scopeDir, runDate, 'safety-review_request.json'));
+    if (request === null || !nonEmptyString(request.digest)) return 'review request digest is missing';
+    const isVariants = scopeDir.trim() !== '' && scopeDir.trim() !== '24-script';
+    const digest = draftDigest(workDir, scopeDir, runDate);
+    if (digest === null) {
+        return isVariants
+            ? 'a manifest-listed variant is missing/unreadable'
+            : 'revised article or VoiceScript is missing/unreadable';
+    }
+    if (digest === request.digest) return isVariants ? 'variant digest is unchanged' : 'draft digest is unchanged';
+    if (isVariants) {
+        const manifest = readJson(join(workDir, '4-safety-variants', 'manifest.json')) as {
+            variants?: Record<string, { path?: unknown }>;
+        } | null;
+        if (manifest === null || !isObject(manifest.variants)) return 'variants manifest is missing/malformed';
+        for (const entry of Object.values(manifest.variants)) {
+            const value = readJson(join(workDir, String(entry.path)));
+            if (value === null || !nonEmptyString(value.title) || !nonEmptyString(value.body)) {
+                return 'revised variant title/body is missing';
+            }
+        }
+        return null;
+    }
     const articlePath = join(workDir, '22-article', `${runDate}_06_article_content.json`);
     const scriptPath = join(workDir, '24-script', `${runDate}_08_script_voicescript.yaml`);
-    if (request === null || !nonEmptyString(request.digest)) return 'review request digest is missing';
-    if (draftDigest(workDir, runDate) === null) return 'revised article or VoiceScript is missing/unreadable';
-    if (draftDigest(workDir, runDate) === request.digest) return 'draft digest is unchanged';
-
     const article = readJson(articlePath);
     if (article === null || !nonEmptyString(article.title) || !nonEmptyString(article.body)) {
         return 'revised article title/body is missing';
@@ -207,22 +244,27 @@ function revisionValid(workDir: string, runDate: string): string | null {
 }
 
 function main(): number {
-    const [kind = '', workDir = '', runDate = '', unattended = 'false'] = process.argv.slice(2);
+    // 0331: an optional trailing scope dir re-roots every artifact path (variants review reads
+    // 4-safety-variants); publish-valid keeps `unattended` in the 4th slot it has always had.
+    const [kind = '', workDir = '', runDate = '', fourth = '', fifth = ''] = process.argv.slice(2);
+    const isPublish = kind === 'publish-valid';
+    const unattended = isPublish ? fourth : 'false';
+    const scopeDir = isPublish ? fifth : fourth;
     if (!kind || !workDir || !runDate) {
         console.error(
-            'usage: safety-artifact-check.ts <report-valid|judge-valid|revision-valid|publish-valid> <work_dir> <run_date> [unattended]',
+            'usage: safety-artifact-check.ts <report-valid|judge-valid|revision-valid|publish-valid> <work_dir> <run_date> [unattended] [scope_dir]',
         );
         return 2;
     }
     const reason =
         kind === 'report-valid'
-            ? reportValid(workDir, runDate)
+            ? reportValid(workDir, scopeDir, runDate)
             : kind === 'judge-valid'
-              ? judgeValid(workDir, runDate)
+              ? judgeValid(workDir, scopeDir, runDate)
               : kind === 'revision-valid'
-                ? revisionValid(workDir, runDate)
+                ? revisionValid(workDir, scopeDir, runDate)
                 : kind === 'publish-valid'
-                  ? publishValid(workDir, runDate, unattended)
+                  ? publishValid(workDir, scopeDir, runDate, unattended)
                   : 'unknown predicate';
     if (reason !== null) {
         console.error(`safety-artifact-check: ${kind}: ${reason}`);

package/plugins/kk/scripts/voice3-publish-window.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env bun
+/**
+ * voice3-publish-window — cron-safe launcher for the voice3 shadow publish window (task 0334).
+ *
+ * WHY a launcher (audit F08/F09/F10, docs/design/kk-daily-ai-voice3.md):
+ * - cron ends a command at the first UNESCAPED % and feeds the rest to stdin, so any inline
+ *   `$(date +%Y%m%d)` shell in a crontab entry silently truncates the command. Date math and
+ *   flag assembly live here, in plain TypeScript, behind zero percent signs.
+ * - the publish window must read the GENERATION bundle (`<works>/kk-daily-ai-voice2/<date>/
+ *   bundle.json` — voice3 prepares under the voice2 namespace until the operator's cutover
+ *   changes it), never the publish3 output directory that earlier entries pointed at.
+ * - the CN consent token list is validated against the pinned preset's WINDOW rows before any
+ *   spur process starts; the old baked `wechatmp-pub,xhs-pub,…` list (tokens that have no
+ *   cn-peak row) is refused up front.
+ *
+ * Contract: everything before `spur workflow run plugins/kk/workflows/kk-daily-publish3.yaml`
+ * is preparation and refusal; the only side effects are refusal messages and, on success, the
+ * single spur exec. `KK_SPUR_BIN` pins the spur binary (same convention as board/capture.ts and
+ * decision-hub.ts); `--dry-run` prints the forwarded vars and stops (rehearsal aid).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const USAGE =
+    'usage: voice3-publish-window.ts --window <after-generate|cn-peak|overseas-rss> [--run-date <YYYY-MM-DD|YYYYMMDD>] ' +
+    '[--preset <slug>] [--live-channels a,b] [--work-dir <dir>] [--dummy] [--dry-run]';
+
+const WINDOWS = new Set(['after-generate', 'cn-peak', 'overseas-rss']);
+
+function failWith(code: number, message: string): never {
+    console.error(message);
+    process.exit(code);
+}
+
+function expandHome(raw: string): string {
+    return raw === '~' || raw.startsWith('~/') ? join(homedir(), raw.slice(1)) : raw;
+}
+
+/** KK_WORKS_DIR env > config works_dir > <cwd>/.works — the kk-workflow-stages precedence. */
+function resolveWorksDir(): string {
+    const fromEnv = process.env.KK_WORKS_DIR;
+    if (fromEnv) return expandHome(fromEnv);
+    const configPath = process.env.KK_CONFIG || join(homedir(), '.config/kk/config.yaml');
+    if (existsSync(configPath)) {
+        try {
+            const parsed = Bun.YAML.parse(readFileSync(configPath, 'utf-8')) as Record<string, unknown> | null;
+            const worksDir = parsed !== null && typeof parsed === 'object' ? parsed.works_dir : undefined;
+            if (typeof worksDir === 'string' && worksDir !== '') return expandHome(worksDir);
+        } catch {
+            // fall through to the compiled default
+        }
+    }
+    return resolve(process.cwd(), '.works');
+}
+
+/** A real calendar day as `YYYY-MM-DD`, or undefined (mirrors publish-matrix normalizeRunDate). */
+function normalizeRunDate(raw: string): string | undefined {
+    const match = /^(\d{4})-?(\d{2})-?(\d{2})$/.exec(raw.trim());
+    if (match === null) return undefined;
+    const iso = `${match[1]}-${match[2]}-${match[3]}`;
+    const parsed = new Date(`${iso}T00:00:00Z`);
+    if (
+        Number.isNaN(parsed.getTime()) ||
+        parsed.getUTCFullYear() !== Number(match[1]) ||
+        parsed.getUTCMonth() + 1 !== Number(match[2]) ||
+        parsed.getUTCDate() !== Number(match[3])
+    ) {
+        return undefined;
+    }
+    return iso;
+}
+
+/** Today (offset 0) or yesterday (offset -1) in America/Los_Angeles — the episodes' own day. */
+function losAngelesDate(offsetDays: number): string {
+    const instant = new Date(Date.now() + offsetDays * 24 * 60 * 60 * 1000);
+    // en-CA renders YYYY-MM-DD; Intl does the zone math cron cannot do inline.
+    return new Intl.DateTimeFormat('en-CA', { timeZone: 'America/Los_Angeles' }).format(instant);
+}
+
+/** `--flag value`, or undefined. */
+function flagValue(args: string[], flag: string): string | undefined {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+
+function main(): void {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    const window = flagValue(args, '--window');
+    if (window === undefined || !WINDOWS.has(window))
+        failWith(1, `${USAGE}\nvoice3-publish-window: --window must be one of ${[...WINDOWS].join('|')}`);
+    const dummy = args.includes('--dummy');
+    const dryRun = args.includes('--dry-run');
+    const preset = flagValue(args, '--preset');
+    const liveChannelsRaw = flagValue(args, '--live-channels');
+    const workDirOverride = flagValue(args, '--work-dir');
+
+    // R1: run date = explicit flag, else window-derived LA day (overseas reads the episode that
+    // landed after the 07:00 tick, i.e. yesterday).
+    const runDateRaw = flagValue(args, '--run-date');
+    let runDate: string | undefined;
+    if (runDateRaw !== undefined && runDateRaw.trim() !== '') {
+        runDate = normalizeRunDate(runDateRaw);
+        if (runDate === undefined)
+            failWith(1, `voice3-publish-window: '${runDateRaw}' is not a valid calendar day (YYYY-MM-DD or YYYYMMDD)`);
+    } else {
+        runDate = losAngelesDate(window === 'overseas-rss' ? -1 : 0);
+    }
+    const digits = runDate.replaceAll('-', '');
+
+    if (dummy && liveChannelsRaw !== undefined) {
+        failWith(1, 'voice3-publish-window: --dummy and --live-channels are mutually exclusive');
+    }
+
+    // R3/F10: live tokens validate against the pinned preset's WINDOW rows before any spawn.
+    const liveChannels =
+        liveChannelsRaw !== undefined && liveChannelsRaw.trim() !== ''
+            ? liveChannelsRaw
+                  .split(',')
+                  .map((token) => token.trim())
+                  .filter((token) => token !== '')
+            : [];
+    if (liveChannels.length > 0 && preset === undefined) {
+        failWith(1, 'voice3-publish-window: --live-channels requires an explicit --preset to validate the window');
+    }
+    if (liveChannels.length > 0) {
+        const scriptDir = dirname(fileURLToPath(import.meta.url));
+        const presetPath = join(dirname(scriptDir), 'publish-presets', `${preset}.json`);
+        if (!existsSync(presetPath))
+            failWith(1, `voice3-publish-window: preset '${preset}' not found at ${presetPath}`);
+        const parsed = JSON.parse(readFileSync(presetPath, 'utf-8')) as {
+            targets?: Array<{ plugin: string; id?: string; mode?: string; window?: string }>;
+        };
+        const targets = parsed.targets ?? [];
+        const inWindow = targets.filter((target) => (target.window ?? 'after-generate') === window);
+        const refused = liveChannels.filter((token) => {
+            const row = inWindow.find((target) => target.plugin === token || target.id === token);
+            return row === undefined || (row.mode ?? 'draft') === 'off';
+        });
+        if (refused.length > 0) {
+            failWith(
+                1,
+                `voice3-publish-window: live token(s) ${refused.join(', ')} have no active row in window '${window}' of preset '${preset}'` +
+                    ` (send-confirm resumes are consent-scoped per window; see docs/design/kk-daily-ai-voice3.md)`,
+            );
+        }
+    }
+
+    // R1/F08: the bundle is the GENERATION artifact under the voice2 namespace, never a publish3
+    // output dir. Mismatched/missing bundles refuse before spur starts.
+    const genDir =
+        workDirOverride !== undefined && workDirOverride.trim() !== ''
+            ? resolve(workDirOverride)
+            : join(resolveWorksDir(), 'kk-daily-ai-voice2', digits);
+    const bundlePath = join(genDir, 'bundle.json');
+    if (!existsSync(bundlePath)) failWith(1, `voice3-publish-window: no generation bundle at ${bundlePath}`);
+    let bundleRunDate: string | undefined;
+    try {
+        const bundle = JSON.parse(readFileSync(bundlePath, 'utf-8')) as { runDate?: string };
+        bundleRunDate = typeof bundle.runDate === 'string' ? normalizeRunDate(bundle.runDate) : undefined;
+    } catch {
+        failWith(1, `voice3-publish-window: unreadable generation bundle at ${bundlePath}`);
+    }
+    if (bundleRunDate !== runDate) {
+        failWith(
+            1,
+            `voice3-publish-window: bundle at ${bundlePath} is dated ${bundleRunDate ?? 'unknown'}, not the requested ${runDate}`,
+        );
+    }
+
+    const vars: Record<string, string> = {
+        work_dir: genDir,
+        run_date: digits,
+        window,
+    };
+    if (preset !== undefined && preset.trim() !== '') vars.preset = preset;
+    if (liveChannels.length > 0) vars.live_channels = liveChannels.join(',');
+    if (dummy) vars.dummy = 'true';
+
+    if (dryRun) {
+        console.log(JSON.stringify(vars, null, 2));
+        process.exit(0);
+    }
+
+    const proc = spawnSync(
+        process.env.KK_SPUR_BIN || 'spur',
+        ['workflow', 'run', 'plugins/kk/workflows/kk-daily-publish3.yaml', '--vars', JSON.stringify(vars)],
+        {
+            stdio: 'inherit',
+        },
+    );
+    // node spawnSync surfaces the child's code as `status` (exitCode is the async-API field).
+    process.exit(proc.status ?? 1);
+}
+
+main();

package/plugins/kk/skills/article-adapt/SKILL.md

@@ -3,6 +3,7 @@ name: article-adapt
 # Description rules: front-load the leading identity phrase; one trigger per genuine
 # branch (collapse synonym triggers into one); never restate the body's identity line.
 description: This skill should be used when a kk-itc publish plan contains variants with adapt=true and per-variant Content files must be written — "adapt the article", "translate for the target profile", "write content.zh-article.json", or when a spur workflow agent.run step invokes kk:article-adapt. Translates title and body to the variant locale, applies the plan limits, and preserves code blocks, URLs and references; it holds no platform table.
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # article-adapt

package/plugins/kk/skills/audio-authoring/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   "outline options for audio", "author a VoiceScript", "revise the script".
   Runs briefing → outline → script with explicit operator gates; solo mode
   ships first, dialogue/interview/narration are named extension points.
+requires: [local-fs]
 ---
 
 # audio-authoring — spoken-audio authoring (create | briefing | outline | script)

package/plugins/kk/skills/content-judge/SKILL.md

@@ -2,6 +2,7 @@
 name: content-judge
 description: This skill should be used when an LLM evaluation gate is needed in a knowledge-kit pipeline — "judge this content", "evaluate against rubric", "quality gate before publish", "check technical accuracy", "review brand tone", "compliance check", or when a spur workflow step of type `agent.run` targets the content-judge skill to emit a PASS/FAIL/NEEDS_REVISION verdict. Centralizes evaluation rubrics, prompt templates, and structured verdict emission for generated Content.
 version: 0.1.0
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # content-judge — LLM-as-judge evaluation skill

package/plugins/kk/skills/content-safety/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: content-safety
 description: This skill should be used when a knowledge-kit pipeline or operator needs a content-safety / platform-admission review before publishing — "check this before publishing", "小宇宙/公众号/网易云/苹果播客 审核风险", "desensitize personal info", "verify disclosure and sourcing before publish". Detects admission risk per distribution platform, proposes honest revisions or exclusion, and escalates what it cannot verify. Quality scoring is content-judge's job.
+requires: [local-fs]
 ---
 
 # content-safety — pre-publication content-safety review

package/plugins/kk/skills/content-safety/references/platforms/podcast-salty.md

@@ -0,0 +1,41 @@
+# Salty Podcast (podcast-salty) — platform reference
+
+`podcast.salty.vip` 是本项目自有的播客站点（Robin Min 自有域名，microfeed 实例，节目「每日AI乱炖」，RSS `/rss/`）。
+这是**自有渠道**，不是第三方分发平台：没有平台审核队列、字级词表或收听量干预可引用。
+本文件存在的意义是把「自有播客宿主没有平台规则」这件事写清楚，避免审核流程把「无三方平台规则」
+误判成证据缺口并默认 BLOCK。
+
+| Field | Value |
+|-------|-------|
+| Official source | 自有站点，无第三方协议页；本文件由站点维护者（Robin Min）本人核定 |
+| Scope | `podcast.salty.vip` 节目标题、音频、show notes、封面（RSS 输出随 item 状态变化） |
+| Effective date | 本文件创建日即生效（自有平台规则由维护者裁定） |
+| Last verified | 2026-11-05（创建） |
+| Evidence status | 维护者本人口径，非三方引用；无字级禁用词表 |
+
+## Evidence distinctions
+
+- **维护者裁定（本文件的权威来源）**：播客节目是自有域名下的小型日更节目，采用与本项目其他
+  渠一致的通用内容纪律；没有平台方提供的可引用条款。
+- **与 apple-podcasts 的边界（AP-06 不在此生效）**：Apple Podcasts 目录收录是第三方目录的准入
+  问题，由维护者人工决定，不由本 pipeline 控制；本 host 的 RSS 只是自有分发的出口。对未核实
+  的估值/数字，节目文案应保持项目既有的 hedging 与出处注明（这是事实纪律，不是平台准入规则），
+  但**不要**因为「聚合页转述未读原文」而 block——那属于 sourcing note，由维护者自行复核。
+- **通用纪律（沿用技能默认）**：AI 声明、来源可靠性、隐私/PII、医疗/投资类内容红线全部沿用
+  技能 default；本文件不新增平台规则。
+
+## Review items
+
+| ID | Item | Grade |
+|----|------|-------|
+| PS-01 | 来源诚实性：show notes 中的对外引用（媒体/论文/Blog）须给出真实出处；转述链保持既有 hedging；未读原文的聚合转述记 note，不 push block。 | note |
+| PS-02 | 数字与事实核对：与源链接一致的数字/日期/机构名冲突时按技能通用规则处理（correctable → revise；冲突无解 → block）。 | note→judge |
+| PS-03 | 可识别个人信息（听众或第三方的私人信息） | desensitize→block if unfixable |
+| PS-04 | 医疗/投资劝诱内容技能默认红线不变（未核实估值→保持 hedging 并注明出处，而非删除条目）。 | default |
+
+## Open questions / escalation
+
+- 自有播客无第三方审核 → 本文件不应产生 `evidenceGap: true` 类 BLOCK；任何「podcast-salty 无
+  reference 文件」的发现都指向本文件缺失，而不是内容风险。
+- 若未来节目上线商业化、赞助或接入第三方目录（Apple/小宇宙实际分配），本文件需要为相应渠道
+  追加准入条款。