@gobing-ai/knowledge-kit 0.1.11 → 0.1.12

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/explain-things/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   "how does X work", "ELI5", "like I'm 5", or "show me". Normal explanations are
   concise inline views; the ELI5 register is opt-in. This is not for content authoring,
   research, judging, publishing, or package/code review workflows.
+requires: [local-fs]
 ---
 
 # explain-things

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

@@ -7,6 +7,7 @@ description: >-
   "list the image formats and styles". Three operations — generate,
   extract-style, list-presets — over named format and style presets, with a
   confirmation gate before any paid generation.
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # image-authoring — image generation agent surface (generate | extract-style | list-presets)

package/plugins/kk/skills/itc-generating/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   writing method", "generate an IT technical draft on X", "create a technical
   article for WeChat/English platforms". Orchestrates topic (outline + draft),
   optional storm-research, and optional content-judge without enlarging those skills.
+requires: [cli:kk, local-fs]
 ---
 
 # itc-generating — IT technical draft generation (method + orchestration)

package/plugins/kk/skills/publish/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   `kk executor run` / `kk fanout` for file-cli and script channels; sequences
   agent-default CMS channels as workflow `agent.run` steps. Does not own
   transport.
+requires: [cli:kk, local-fs]
 ---
 
 # publish — leftover channel operator surface