@gobing-ai/knowledge-kit 0.0.16 → 0.0.18

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

@@ -50,6 +50,10 @@ const VALIDATE_SIDECAR = 'validate-voicescript.ts';
 const WRAP_SIDECAR = 'wrap-voicescript-doc.ts';
 const RENDER_SIDECAR = 'render-md.ts';
 const REVISE_COUNT = '.revise-count';
+// Post-translation title-dedup threshold (task 0138 R3). ponytail: the 2026-09-16 Gemini 3.8 Live
+// pair measures 0.417 zh title-only Jaccard, the nearest distinct pair 0.1 (4x margin). Character
+// bigrams need same-language input — pre-translate dedup over the mixed-language blend cannot work.
+const DEDUP_TITLE_THRESHOLD = 0.4;
 
 function fail(message: string): never {
     console.error(message);
@@ -496,6 +500,16 @@ function metadataOf(value: Record<string, unknown> | null): Record<string, unkno
     return metadata !== null && typeof metadata === 'object' ? (metadata as Record<string, unknown>) : {};
 }
 
+/**
+ * Required stage input: a missing or unparsable file fails the stage naming the path, so a
+ * run-date/path mismatch surfaces as its real cause instead of a downstream "field missing" error.
+ */
+function requireJson(path: string, label: string): Record<string, unknown> {
+    const parsed = readJson(path);
+    if (parsed === null) failWith(1, `${label}: required input not found or unparsable: ${path}`);
+    return parsed;
+}
+
 /** `jq -e '.targets[]? | select(.target == t and .ok == true and .status == "published")'`. */
 function targetPublished(path: string, target: string): boolean {
     const parsed = readJson(path);
@@ -643,6 +657,72 @@ function dailyQcContent(args: string[]): void {
     });
 }
 
+/**
+ * Character-bigram Jaccard over whitespace-normalized, lowercased titles — the twin of
+ * episode-plan-gen's `titleSimilarity`. Duplicated on purpose: this file is node-builtins-only
+ * (no workspace imports), so it cannot reach that module.
+ */
+function titleSimilarity(a: string, b: string): number {
+    const bigrams = (text: string): Set<string> => {
+        const normalized = text.replace(/\s+/g, ' ').trim().toLowerCase();
+        const out = new Set<string>();
+        for (let i = 0; i < normalized.length - 1; i++) out.add(normalized.slice(i, i + 2));
+        return out;
+    };
+    const aGrams = bigrams(a);
+    const bGrams = bigrams(b);
+    if (aGrams.size === 0 || bGrams.size === 0) return 0;
+    let intersection = 0;
+    for (const gram of aGrams) if (bGrams.has(gram)) intersection++;
+    return intersection / (aGrams.size + bGrams.size - intersection);
+}
+
+/**
+ * Post-translation near-duplicate dedup (task 0138 R3): drop any plan item whose title is a
+ * >=DEDUP_TITLE_THRESHOLD bigram match for an EARLIER item, so curated plan order decides the
+ * survivor. It runs on the translated plan because cross-language near-dups are invisible before
+ * plan-translate (the 2026-09-16 Gemini pair measures 0.208 mixed-language, 0.417 all-zh).
+ */
+export function dedupPlanByTitle<T extends { id?: unknown; title?: unknown }>(
+    docs: T[],
+): { kept: T[]; dropped: string[] } {
+    const kept: T[] = [];
+    const dropped: string[] = [];
+    for (const doc of docs) {
+        const title = typeof doc.title === 'string' ? doc.title : '';
+        const duplicate =
+            title !== '' &&
+            kept.some((earlier) => {
+                const earlierTitle = typeof earlier.title === 'string' ? earlier.title : '';
+                return titleSimilarity(earlierTitle, title) >= DEDUP_TITLE_THRESHOLD;
+            });
+        if (duplicate) {
+            dropped.push(typeof doc.id === 'string' && doc.id !== '' ? doc.id : title);
+            continue;
+        }
+        kept.push(doc);
+    }
+    return { kept, dropped };
+}
+
+/**
+ * Run the VoiceScript content validator over a written script and fail the stage when it rejects
+ * (task 0139 R3). `spawnSync` rather than `delegate` on purpose: `delegate` exits the process
+ * directly, which would skip `timed`'s `finally` and lose the step-timing entry the run report
+ * reads. The sidecar's own stderr carries `content check failed: segment <idx> …`; this adds the
+ * stage-level naming so the operator sees which artifact was rejected.
+ */
+function assertScriptContent(scriptPath: string): void {
+    // `spawnSync` + `failWith`, deliberately NOT `delegate`: delegate is `never`-returning (it calls
+    // process.exit), so using it mid-function would abort the calling stage on SUCCESS — dailyWrapDocs
+    // would exit before packaging its docs. A clean exit here falls through to the rest of the stage.
+    const sidecar = requireSidecar('', VALIDATE_SIDECAR, 'validate_script');
+    const runner = spawnSync(process.execPath, [sidecar, '--in', scriptPath], { stdio: 'inherit' });
+    if (runner.status !== 0) {
+        failWith(runner.status ?? 1, `script content check failed: ${scriptPath} was rejected (see above)`);
+    }
+}
+
 function dailyArticle(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = ''] = args;
     const articleMd = join(workDir, '2-article', `${runDate}_06_article_article.md`);
@@ -650,10 +730,6 @@ function dailyArticle(args: string[]): void {
     const planIn = join(workDir, '2-plan', `${runDate}_03_plan_plan.json`);
     const candidates = join(workDir, '2-plan', `${runDate}_04_quality-control-content_candidates.json`);
     timed(workDir, 'article', () => {
-        if (isFile(articleMd)) {
-            console.log(`article cached: ${articleMd}`);
-            return;
-        }
         let planUsable = true;
         const raw = isFile(planIn) ? readFileSync(planIn, 'utf-8') : '';
         try {
@@ -671,6 +747,25 @@ function dailyArticle(args: string[]): void {
             }
         }
         if (!planUsable) failWith(1, 'article: no usable plan input');
+        // R3 (task 0138): dedup runs BEFORE the cache early-return — the script stage reads this same
+        // plan.json and must see one survivor even when the article is already cached. Idempotent:
+        // a no-op once the plan is deduped.
+        const planParsed: unknown = readJson(planIn);
+        if (Array.isArray(planParsed)) {
+            const { kept, dropped } = dedupPlanByTitle(planParsed as Record<string, unknown>[]);
+            if (dropped.length > 0) {
+                sted('write', planIn, () => writeJsonText(planIn, kept));
+                console.error(`article: dropped ${dropped.length} near-duplicate plan item(s): ${dropped.join(', ')}`);
+            }
+        }
+        if (isFile(articleMd)) {
+            console.log(`article cached: ${articleMd}`);
+            return;
+        }
+        // Agent-written prose body (workflow `article-write` state) replaces the mechanical
+        // per-item render when present — the 3-format split: surfdash gets an article,
+        // not a news list (2026-09-16 feedback).
+        const proseBody = join(workDir, '2-article', `${runDate}_06_article-write_body.md`);
         kk(
             [
                 'executor',
@@ -683,7 +778,10 @@ function dailyArticle(args: string[]): void {
                 ...pluginsArgs(pluginsPath),
             ],
             {
-                env: { ARTICLE_DATE: runDate },
+                env: {
+                    ARTICLE_DATE: runDate,
+                    ...(isFile(proseBody) ? { ARTICLE_BODY_FILE: proseBody } : {}),
+                },
             },
         );
         const body = readJson(articleContent)?.body;
@@ -711,7 +809,10 @@ function dailyCoverNormalize(args: string[]): void {
 function coverNormalizeBody(workDir: string, runDate: string): void {
     const png = join(workDir, '2-cover', 'content-cover-01.png');
     const jpg = join(workDir, '2-cover', 'content-cover-01.jpg');
-    const out = join(workDir, '2-cover', `cover-${runDate}.png`);
+    // Must match the name dailyPublishPrep and the article->cover workflow guard read:
+    // `${runDate}_07_cover_cover.png` (a plain `cover-${runDate}.png` left options.coverPath
+    // undefined and silently dropped the cover from both podcast and surfdash — 2026-09-16 run).
+    const out = join(workDir, '2-cover', `${runDate}_07_cover_cover.png`);
     const source = isFile(png) ? png : isFile(jpg) ? jpg : '';
     if (source === '') failWith(1, 'cover normalize: no content-cover-01.{png,jpg} artifact');
     if (source === jpg) {
@@ -734,7 +835,7 @@ function coverNormalizeBody(workDir: string, runDate: string): void {
             // `rm -f` is silent when the file is already gone.
         }
     }
-    console.log(`cover normalized: cover-${runDate}.png`);
+    console.log(`cover normalized: ${runDate}_07_cover_cover.png`);
 }
 
 function dailyScript(args: string[]): void {
@@ -753,6 +854,9 @@ function dailyScript(args: string[]): void {
         const body = readJson(contentOut)?.body;
         if (typeof body !== 'string') failWith(1, `script: ${contentOut} has no string body`);
         sted('write', yamlOut, () => writeRaw(yamlOut, body));
+        // R3 (task 0139): fresh writes are validated here; the script cache path is covered by
+        // wrap-docs, which runs on every path that reaches audio.
+        assertScriptContent(yamlOut);
     });
 }
 
@@ -761,6 +865,9 @@ function dailyWrapDocs(args: string[]): void {
     const scriptPath = join(workDir, '2-script', `${runDate}_08_script_voicescript.yaml`);
     const docsPath = join(workDir, '3-audio', `${runDate}_10_wrap-docs_docs.json`);
     timed(workDir, 'wrap-docs', () => {
+        // R3 (task 0139): the second validator placement — covers a HITL-edited YAML and the
+        // script-stage cache path, neither of which re-enters dailyScript's fresh-write branch.
+        assertScriptContent(scriptPath);
         const url = new URL(scriptPath, `file://${process.cwd()}/`);
         const body = readFileSync(decodeURIComponent(url.pathname), 'utf-8');
         const profile = voiceProfile || process.env.VOICEBOX_DEFAULT_PROFILE || 'robin-news';
@@ -777,7 +884,17 @@ function dailyWrapDocs(args: string[]): void {
 }
 
 function dailyGenerate(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', transcodeMp3 = '', voiceGenerator = ''] = args;
+    const [workDir = '', runDate = '', pluginsPath = '', transcodeMp3 = '', vdriver = ''] = args;
+    // 20260917 review: the workflow picks a voice driver by short name; both drivers' envs are
+    // passed unconditionally so switching `vdriver` needs no shell changes. Unknown -> fail loud.
+    const VOICE_DRIVERS: Record<string, string> = { ominivoice: 'omni-voice-gen', voicebox: 'voice-gen' };
+    const voiceGenerator = VOICE_DRIVERS[vdriver];
+    if (!voiceGenerator) {
+        failWith(
+            1,
+            `generate: unknown vdriver '${vdriver}' (expected one of: ${Object.keys(VOICE_DRIVERS).join(', ')})`,
+        );
+    }
     const docs = join(workDir, '3-audio', `${runDate}_10_wrap-docs_docs.json`);
     const content = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
     timed(workDir, 'generate', () => {
@@ -794,6 +911,111 @@ function dailyGenerate(args: string[]): void {
     });
 }
 
+/**
+ * 20260917 review #7: prepend the show's 8s intro sting to the generated audio.
+ * `intro_music` empty -> skip. Writes `<stem>.intro.wav` (original render kept), points
+ * `audioPath` at the merged file, extends `duration`, marks `introMerged` (idempotent).
+ */
+function dailyIntro(args: string[]): void {
+    const [workDir = '', runDate = '', introSrc = ''] = args;
+    if (!introSrc || introSrc.trim() === '') {
+        console.log('intro-music: intro_music var empty — skip');
+        return;
+    }
+    const contentPath = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
+    timed(workDir, 'intro-music', () => {
+        const content = requireJson(contentPath, 'intro-music');
+        const meta = metadataOf(content);
+        if (meta.introMerged === true) {
+            console.log(`intro-music cached: ${contentPath}`);
+            return;
+        }
+        const rawFile = meta.mp3Path ?? meta.audioPath;
+        if (typeof rawFile !== 'string' || rawFile === '') {
+            failWith(1, 'intro-music: voice content carries no mp3Path/audioPath');
+        }
+        const introPath = resolve(introSrc);
+        if (!existsSync(introPath)) failWith(1, `intro-music: intro file not found: ${introPath}`);
+        const mainPath = resolve(rawFile);
+        if (!existsSync(mainPath)) failWith(1, `intro-music: generated audio not found: ${mainPath}`);
+        const mergedPath = mainPath.replace(/\.wav$/, '.intro.wav');
+        const probe = (file: string, entries: string): string =>
+            spawnSync('ffprobe', [
+                '-v',
+                'error',
+                '-select_streams',
+                'a:0',
+                '-show_entries',
+                entries,
+                '-of',
+                'csv=p=0',
+                file,
+            ])
+                .stdout?.toString()
+                .trim() ?? '';
+        const mainDur = Number.parseFloat(probe(mainPath, 'format=duration'));
+        const introDur = Number.parseFloat(probe(introPath, 'format=duration'));
+        if (!Number.isFinite(mainDur) || !Number.isFinite(introDur)) {
+            failWith(1, `intro-music: ffprobe could not read durations (main=${mainDur} intro=${introDur})`);
+        }
+        const rate = probe(mainPath, 'stream=sample_rate') || '24000'; // match the generated audio's rate; mono s16 both sides
+        const norm = (label: string): string =>
+            `[${label}:a]aresample=${rate},aformat=sample_fmts=s16:channel_layouts=mono[${label}]`;
+        const fc = `${norm('0')};${norm('1')};[0][1]concat=n=2:v=0:a=1[out]`;
+        const conv = spawnSync('ffmpeg', [
+            '-y',
+            '-hide_banner',
+            '-loglevel',
+            'error',
+            '-i',
+            introPath,
+            '-i',
+            mainPath,
+            '-filter_complex',
+            fc,
+            '-map',
+            '[out]',
+            '-c:a',
+            'pcm_s16le',
+            mergedPath,
+        ]);
+        if (conv.status !== 0 || !existsSync(mergedPath)) {
+            failWith(1, `intro-music: ffmpeg concat failed: ${conv.stderr?.toString().trim()}`);
+        }
+        if (meta.mp3Path && typeof meta.mp3Path === 'string') {
+            // transcode_mp3=true: keep the mp3 path honest by re-transcoding the merged wav.
+            const mp3 = spawnSync('ffmpeg', [
+                '-y',
+                '-hide_banner',
+                '-loglevel',
+                'error',
+                '-i',
+                mergedPath,
+                '-codec:a',
+                'libmp3lame',
+                '-qscale:a',
+                '2',
+                resolve(meta.mp3Path),
+            ]);
+            if (mp3.status !== 0) failWith(1, `intro-music: mp3 re-transcode failed: ${mp3.stderr?.toString().trim()}`);
+        }
+        const mergedDur = Number.parseFloat(probe(mergedPath, 'format=duration')) || mainDur + introDur;
+        const updated = {
+            ...content,
+            metadata: {
+                ...meta,
+                audioPath: mergedPath,
+                duration: mergedDur,
+                introMerged: true,
+            },
+        };
+        sted('write', contentPath, () => writeJsonText(contentPath, updated));
+        console.log(
+            `intro-music: merged ${introDur.toFixed(1)}s intro -> ${mergedPath} (${mergedDur.toFixed(1)}s total)`,
+        );
+    });
+}
+
 function dailyQualityReport(args: string[]): void {
     const [workDir = '', runDate = ''] = args;
     const content = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
@@ -817,7 +1039,7 @@ function dailyPublishPrep(args: string[]): void {
     const prepPath = join(workDir, '3-publish', `${runDate}_13_publish-prep_content.json`);
     const coverPath = join(workDir, '2-cover', `${runDate}_07_cover_cover.png`);
     timed(workDir, 'publish-prep', () => {
-        const article = readJson(articlePath) ?? {};
+        const article = requireJson(articlePath, 'publish-prep');
         const audioMeta = metadataOf(readJson(audioPath));
         const rawFile = audioMeta.mp3Path ?? audioMeta.audioPath;
         if (typeof rawFile !== 'string' || rawFile === '') {
@@ -825,13 +1047,21 @@ function dailyPublishPrep(args: string[]): void {
         }
         const audioFile = resolve(rawFile);
         const resolvedCover = resolve(coverPath);
+        const hasCover = existsSync(resolvedCover);
+        // podcast-pub's documented contract reads metadata.coverImage (map.ts); options.coverPath
+        // alone was silently dropped by the mapper — episodes published without a cover.
         const merged = {
             ...article,
-            metadata: { ...metadataOf(article), audioFile, runDate },
+            metadata: {
+                ...metadataOf(article),
+                audioFile,
+                runDate,
+                ...(hasCover ? { coverImage: resolvedCover } : {}),
+            },
             options: {
                 audioFile,
                 durationSec: audioMeta.duration,
-                coverPath: existsSync(resolvedCover) ? resolvedCover : undefined,
+                coverPath: hasCover ? resolvedCover : undefined,
             },
         };
         sted('write', prepPath, () => writeJsonText(prepPath, merged));
@@ -877,6 +1107,9 @@ function dailyShowNotes(args: string[]): void {
     const result = join(workDir, '3-publish', `${runDate}_14_publish-surfdash_result.json`);
     const out = join(workDir, '3-publish', `${runDate}_15_show-notes_show-notes.md`);
     const plan = join(workDir, '2-plan', `${runDate}_03_plan_plan.json`);
+    // Generated-episode content carries `metadata.segments[]` — the source of real
+    // audio offsets for the show-notes timeline (jump-to-item timestamps).
+    const audioContent = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
     timed(workDir, 'show-notes', () => {
         const effective = readJson(article)?.title;
         const titleArg = title !== '' ? title : typeof effective === 'string' ? effective : '';
@@ -887,6 +1120,7 @@ function dailyShowNotes(args: string[]): void {
                 PODCAST_PUB_RUN_DATE: runDate,
                 PODCAST_PUB_BRIEF_MODE: 'true',
                 PODCAST_PUB_ARTICLE_POST_PATH: postPath,
+                ...(isFile(audioContent) ? { PODCAST_PUB_AUDIO_CONTENT: audioContent } : {}),
             },
         });
     });
@@ -917,7 +1151,7 @@ function dailyPublishPodcast(args: string[]): void {
             return;
         }
         try {
-            const content = readJson(prep) ?? {};
+            const content = requireJson(prep, 'publish-podcast');
             const showNotes = readFileSync(notes, 'utf-8');
             const merged = { ...content, metadata: { ...metadataOf(content), showNotes } };
             sted('write', prep, () => writeJsonText(prep, merged));
@@ -997,6 +1231,95 @@ function dailyPublishPartial(args: string[]): void {
     });
 }
 
+/**
+ * 20260917 review #4/#6: after both publishes land, patch the surfdash disk posts —
+ * reuse the podcast-hosted cover URL in frontmatter (image/og_image; no re-upload; fallback:
+ * copy the local cover into assets/) and append a podcast cross-link at the end of zh/en/ja.
+ * Idempotent per post; commits + pushes the surfdash checkout (SURFDASH_AUTO_PUSH=0 keeps commit-only).
+ */
+function dailyPatchSurfdash(args: string[]): void {
+    const [workDir = '', runDate = '', surfdashRoot = ''] = args;
+    if (!surfdashRoot || !existsSync(surfdashRoot)) {
+        console.log(`patch-surfdash: surfdash root '${surfdashRoot}' not found — skip`);
+        return;
+    }
+    timed(workDir, 'patch-surfdash', () => {
+        const sdResult = join(workDir, '3-publish', `${runDate}_14_publish-surfdash_result.json`);
+        const podcastResult = join(workDir, '3-publish', `${runDate}_16_publish-podcast_result.json`);
+        if (!isFile(sdResult) || !isFile(podcastResult)) {
+            failWith(1, 'patch-surfdash: missing surfdash/podcast publish results — run the publish states first');
+        }
+        const targetOf = (path: string): Record<string, unknown> => {
+            const parsed = readJson(path) as { targets?: Array<Record<string, unknown>> };
+            return parsed.targets?.[0] ?? {};
+        };
+        const sd = targetOf(sdResult);
+        const pod = targetOf(podcastResult);
+        const postPath = (sd.metadata as Record<string, unknown> | undefined)?.postPath;
+        if (typeof postPath !== 'string' || postPath === '')
+            failWith(1, 'patch-surfdash: surfdash result carries no postPath');
+        const slugDir = dirname(postPath);
+        const showNotesUrl = typeof pod.url === 'string' ? pod.url : '';
+        const coverUrl = ((pod.metadata as Record<string, unknown> | undefined)?.imageUrl as string | undefined) ?? '';
+        const localCover = join(workDir, '2-cover', `${runDate}_07_cover_cover.png`);
+        const dateIso = `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}`;
+        const crossLink: Record<string, string> = {
+            zh: `🎧 本期已同步制作为播客节目，[点击收听《每日 AI 资讯 · ${dateIso}》](${showNotesUrl})。`,
+            en: `🎧 This episode is also available as a podcast: [listen to the Daily AI Briefing · ${dateIso}](${showNotesUrl}).`,
+            ja: `🎧 本エピソードはポッドキャストでも配信中：[Daily AI Briefing · ${dateIso} を聴く](${showNotesUrl})。`,
+        };
+        let changed = 0;
+        for (const [locale, dir] of [
+            ['zh', slugDir],
+            ['en', join(dirname(slugDir), 'en', basename(slugDir))],
+            ['ja', join(dirname(slugDir), 'ja', basename(slugDir))],
+        ] as const) {
+            const indexMd = join(dir, 'index.md');
+            if (!existsSync(indexMd)) {
+                console.log(`patch-surfdash: ${locale} post not published (${indexMd}) — skip`);
+                continue;
+            }
+            let md = readFileSync(indexMd, 'utf-8');
+            const fmEnd = md.indexOf('---', 3); // frontmatter is `---\n ... \n---\n`
+            if (fmEnd < 0) failWith(1, `patch-surfdash: no frontmatter in ${indexMd}`);
+            if (!/^image:/m.test(md.slice(0, fmEnd))) {
+                let image = coverUrl;
+                if (image === '' && existsSync(localCover)) {
+                    // Fallback for pre-#6 runs: copy the local cover instead of a hosted URL.
+                    const assets = join(dir, 'assets');
+                    mkdirSync(assets, { recursive: true });
+                    copyFileSync(localCover, join(assets, 'cover.png'));
+                    image = './assets/cover.png';
+                }
+                if (image !== '') {
+                    md = md.replace(/^publishDate: .*$/m, (m0) => `${m0}\nimage: '${image}'\nog_image: '${image}'`);
+                }
+            }
+            if (showNotesUrl !== '' && !md.includes(showNotesUrl)) {
+                md = `${md.replace(/\s*$/, '')}\n\n${crossLink[locale]}\n`;
+            }
+            if (md !== readFileSync(indexMd, 'utf-8')) {
+                sted('write', indexMd, () => writeFileSync(indexMd, md));
+                changed++;
+            }
+        }
+        if (changed === 0) {
+            console.log('patch-surfdash: nothing to change');
+            return;
+        }
+        const git = (...a: string[]): void => {
+            const r = spawnSync('git', ['-C', surfdashRoot, ...a]);
+            if (r.status !== 0) failWith(1, `patch-surfdash: git ${a[0]} failed: ${r.stderr?.toString().trim()}`);
+        };
+        git('add', 'content/posts/articles');
+        git('commit', '-m', `feat: cover + podcast cross-link for ${basename(slugDir)} (kk daily patch)`);
+        if (process.env.SURFDASH_AUTO_PUSH !== '0') git('push');
+        console.log(
+            `patch-surfdash: patched ${changed} post(s), committed${process.env.SURFDASH_AUTO_PUSH !== '0' ? ' + pushed' : ' (push skipped: SURFDASH_AUTO_PUSH=0)'}`,
+        );
+    });
+}
+
 function dailyRunReport(args: string[]): void {
     const [
         workDir = '',
@@ -1021,6 +1344,9 @@ function dailyRunReport(args: string[]): void {
             return;
         }
         sted('write', cands, () => writeJqText(cands, metadataOf(readJson(candidates)).docs ?? []));
+        // Plugin env paths must be absolute: spawnPluginEntry runs plugins with cwd = the
+        // plugin package dir, so a relative workDir silently misses every best-effort read.
+        const absWorkDir = resolve(workDir);
         kk(['executor', 'run', 'news-report-gen', '--in', cands, '--out', reportJson, ...pluginsArgs(pluginsPath)], {
             env: {
                 QC_MIN_QUALITY: minQuality,
@@ -1028,11 +1354,19 @@ function dailyRunReport(args: string[]): void {
                 QC_MIN_URGENCY: minUrgency,
                 QC_MIN_IMPACT: minImpact,
                 NEWS_REPORT_REJECTED_FILE: join(
-                    workDir,
+                    absWorkDir,
                     '2-plan',
                     `${runDate}_04_quality-control-content_candidates.rejected.json`,
                 ),
-                NEWS_REPORT_TIMING_FILE: join(workDir, 'step-timing.json'),
+                NEWS_REPORT_TIMING_FILE: join(absWorkDir, 'step-timing.json'),
+                // 0139 R5b: the generate stage's QC audit, read best-effort (absent -> section omitted).
+                NEWS_REPORT_QC_FILE: join(absWorkDir, '3-audio', `${runDate}_11_generate_content.json`),
+                // 20260917 funnel: the plan stage's full selection trail (every fetched title +
+                // scores + disposition), rendered as the 选稿漏斗 section (absent -> omitted).
+                NEWS_REPORT_PLAN_AUDIT_FILE: join(absWorkDir, '2-plan', `${runDate}_03_plan_plan.json.audit.json`),
+                // 20260917 funnel: the blended fan-in input, rendered as the 语料构成
+                // source/category composition (absent -> omitted).
+                NEWS_REPORT_BLENDED_FILE: join(absWorkDir, '1-ingest', `${runDate}_02_collect_blended.json`),
                 NEWS_REPORT_DATE: runDate,
             },
         });
@@ -1043,68 +1377,78 @@ function dailyRunReport(args: string[]): void {
     });
 }
 
-function dailyTranslateEn(args: string[]): void {
+/**
+ * Collapsed translate scaffolding (2026-09-16 feedback): surfdash-pub owns the
+ * deterministic mechanics — `scaffold-locale` for both target locales — while the
+ * workflow `translate` state's agent step owns the LLM translation of the drafts.
+ * Writes one marker file per locale (zh post path + en/ja draft paths); empty
+ * marker = locale absent (callers skip). Reuses an existing on-disk draft as the
+ * cache across run retries — re-scaffolding would erase the agent's translation.
+ */
+function dailyTranslateLocalize(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = ''] = args;
     const result = join(workDir, '3-publish', `${runDate}_17_publish_result.json`);
-    const zhFile = join(workDir, '3-publish', `${runDate}_20_translate-en_zh-post-path.txt`);
-    const enFile = join(workDir, '3-publish', `${runDate}_20_translate-en_en-post-path.txt`);
-    const scaffold = join(workDir, '3-publish', `${runDate}_20_translate-en_scaffold-en.json`);
-    const scaffoldResult = join(workDir, '3-publish', `${runDate}_20_translate-en_scaffold-en-result.json`);
-    timed(workDir, 'translate-en', () => {
+    const zhFile = join(workDir, '3-publish', `${runDate}_20_translate-localize_zh-post-path.txt`);
+    timed(workDir, 'translate-localize', () => {
         const postPath = firstPostPath(readJson(result), 'surfdash-pub');
         const zh = postPath.endsWith('index.md') ? postPath : '';
         sted('write', zhFile, () => writeRaw(zhFile, zh));
-        const en = zh.replace('/zh/', '/en/');
-        sted('write', enFile, () => writeRaw(enFile, en));
-        if (zh === '') {
-            console.log('no zh post path — skip translate-en');
-            return;
-        }
-        if (isFile(en)) {
-            console.log(`en draft cached: ${en}`);
-            return;
-        }
-        sted('write', scaffold, () =>
-            writeJqText(scaffold, { body: '', options: { operation: 'scaffold-locale', postPath: zh, target: 'en' } }),
-        );
-        kk(['executor', 'run', 'surfdash-pub', '--in', scaffold, '--out', scaffoldResult, ...pluginsArgs(pluginsPath)]);
-        const draftPath = metadataOf(readJson(scaffoldResult)).draftPath;
-        sted('write', enFile, () => writeRaw(enFile, typeof draftPath === 'string' ? draftPath : ''));
-    });
-}
-
-function dailyTranslateJa(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = ''] = args;
-    const zhFile = join(workDir, '3-publish', `${runDate}_20_translate-en_zh-post-path.txt`);
-    const jaFile = join(workDir, '3-publish', `${runDate}_22_translate-ja_ja-post-path.txt`);
-    const scaffold = join(workDir, '3-publish', `${runDate}_22_translate-ja_scaffold-ja.json`);
-    const scaffoldResult = join(workDir, '3-publish', `${runDate}_22_translate-ja_scaffold-ja-result.json`);
-    timed(workDir, 'translate-ja', () => {
-        const zh = isFile(zhFile) ? readFileSync(zhFile, 'utf-8') : '';
-        const ja = zh.replace('/zh/', '/ja/');
-        sted('write', jaFile, () => writeRaw(jaFile, ja));
         if (zh === '') {
-            console.log('no zh post path — skip translate-ja');
+            for (const target of ['en', 'ja'] as const) {
+                sted(
+                    'write',
+                    join(workDir, '3-publish', `${runDate}_20_translate-localize_${target}-post-path.txt`),
+                    () =>
+                        writeRaw(
+                            join(workDir, '3-publish', `${runDate}_20_translate-localize_${target}-post-path.txt`),
+                            '',
+                        ),
+                );
+            }
+            console.log('no zh post path — skip localize');
             return;
         }
-        if (isFile(ja)) {
-            console.log(`ja draft cached: ${ja}`);
-            return;
+        for (const target of ['en', 'ja'] as const) {
+            const markerFile = join(workDir, '3-publish', `${runDate}_20_translate-localize_${target}-post-path.txt`);
+            const existing = zh.replace('/zh/', `/${target}/`);
+            if (isFile(existing)) {
+                sted('write', markerFile, () => writeRaw(markerFile, existing));
+                console.log(`${target} draft cached: ${existing}`);
+                continue;
+            }
+            const scaffold = join(workDir, '3-publish', `${runDate}_20_translate-localize_scaffold-${target}.json`);
+            const scaffoldResult = join(
+                workDir,
+                '3-publish',
+                `${runDate}_20_translate-localize_scaffold-${target}-result.json`,
+            );
+            sted('write', scaffold, () =>
+                writeJqText(scaffold, { body: '', options: { operation: 'scaffold-locale', postPath: zh, target } }),
+            );
+            kk([
+                'executor',
+                'run',
+                'surfdash-pub',
+                '--in',
+                scaffold,
+                '--out',
+                scaffoldResult,
+                ...pluginsArgs(pluginsPath),
+            ]);
+            const draftPath = metadataOf(readJson(scaffoldResult)).draftPath;
+            sted('write', markerFile, () => writeRaw(markerFile, typeof draftPath === 'string' ? draftPath : ''));
         }
-        sted('write', scaffold, () =>
-            writeJqText(scaffold, { body: '', options: { operation: 'scaffold-locale', postPath: zh, target: 'ja' } }),
-        );
-        kk(['executor', 'run', 'surfdash-pub', '--in', scaffold, '--out', scaffoldResult, ...pluginsArgs(pluginsPath)]);
-        const draftPath = metadataOf(readJson(scaffoldResult)).draftPath;
-        sted('write', jaFile, () => writeRaw(jaFile, typeof draftPath === 'string' ? draftPath : ''));
     });
 }
 
 function dailyTranslateSync(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', zhPostPath = ''] = args;
+    const [workDir = '', runDate = '', pluginsPath = '', zhPathFile = ''] = args;
     const sync = join(workDir, '3-publish', `${runDate}_24_translate-sync_sync.json`);
     const syncResult = join(workDir, '3-publish', `${runDate}_24_translate-sync_sync-result.json`);
     timed(workDir, 'translate-sync', () => {
+        // Reads the marker file itself — the collapsed `translate` state has no
+        // cross-state var to hand the path through.
+        const zhPostPath = isFile(zhPathFile) ? readFileSync(zhPathFile, 'utf-8') : '';
         if (zhPostPath === '') {
             console.log('no zh post path — skip translate-sync');
             return;
@@ -1118,109 +1462,124 @@ function dailyTranslateSync(args: string[]): void {
 
 const [stage, ...rest] = process.argv.slice(2);
 
-switch (stage) {
-    case 'prepare-itc':
-        prepareItc(rest);
-        break;
-    case 'prepare-solo':
-        prepareSolo(rest);
-        break;
-    case 'prepare-storm':
-        prepareStorm(rest);
-        break;
-    case 'duration':
-        duration(rest);
-        break;
-    case 'validate': {
-        const { override, values } = parseStage(rest, { in: { type: 'string' } });
-        if (!values.in) fail('usage: kk-workflow-stages.ts validate [<override>] --in <voicescript.yaml>');
-        delegate(requireSidecar(override, VALIDATE_SIDECAR, 'validate_script'), ['--in', values.in]);
-        break;
-    }
-    case 'wrap': {
-        const { override, values } = parseStage(rest, {
-            in: { type: 'string' },
-            out: { type: 'string' },
-            profile: { type: 'string' },
-        });
-        if (!values.in || !values.out) {
-            fail(
-                'usage: kk-workflow-stages.ts wrap [<override>] --in <voicescript.yaml> --out <docs.json> [--profile <name>]',
-            );
+// Imported as a module (unit tests reach `dedupPlanByTitle`) → exports only, never a stage run;
+// executed as the entrypoint → dispatch.
+if (import.meta.main)
+    switch (stage) {
+        case 'prepare-itc':
+            prepareItc(rest);
+            break;
+        case 'prepare-solo':
+            prepareSolo(rest);
+            break;
+        case 'prepare-storm':
+            prepareStorm(rest);
+            break;
+        case 'duration':
+            duration(rest);
+            break;
+        case 'validate': {
+            const { override, values } = parseStage(rest, { in: { type: 'string' } });
+            if (!values.in) fail('usage: kk-workflow-stages.ts validate [<override>] --in <voicescript.yaml>');
+            delegate(requireSidecar(override, VALIDATE_SIDECAR, 'validate_script'), ['--in', values.in]);
+            break;
         }
-        delegate(requireSidecar(override, WRAP_SIDECAR, 'wrap_script'), [values.in, values.out, values.profile ?? '']);
-        break;
-    }
-    case 'render-storm': {
-        const { override, values } = parseStage(rest, { in: { type: 'string' }, out: { type: 'string' } });
-        if (!values.in || !values.out) {
-            fail('usage: kk-workflow-stages.ts render-storm [<override>] --in <content.json> --out <content.md>');
+        case 'wrap': {
+            const { override, values } = parseStage(rest, {
+                in: { type: 'string' },
+                out: { type: 'string' },
+                profile: { type: 'string' },
+            });
+            if (!values.in || !values.out) {
+                fail(
+                    'usage: kk-workflow-stages.ts wrap [<override>] --in <voicescript.yaml> --out <docs.json> [--profile <name>]',
+                );
+            }
+            delegate(requireSidecar(override, WRAP_SIDECAR, 'wrap_script'), [
+                values.in,
+                values.out,
+                values.profile ?? '',
+            ]);
+            break;
+        }
+        case 'render-storm': {
+            const { override, values } = parseStage(rest, { in: { type: 'string' }, out: { type: 'string' } });
+            if (!values.in || !values.out) {
+                fail('usage: kk-workflow-stages.ts render-storm [<override>] --in <content.json> --out <content.md>');
+            }
+            delegate(requireSidecar(override, RENDER_SIDECAR, 'render_script'), [
+                '--in',
+                values.in,
+                '--out',
+                values.out,
+            ]);
+            break;
         }
-        delegate(requireSidecar(override, RENDER_SIDECAR, 'render_script'), ['--in', values.in, '--out', values.out]);
-        break;
+        case 'daily-prepare':
+            dailyPrepare(rest);
+            break;
+        case 'daily-collect-facts':
+            dailyCollectFacts(rest);
+            break;
+        case 'daily-plan':
+            dailyPlan(rest);
+            break;
+        case 'daily-qc-content':
+            dailyQcContent(rest);
+            break;
+        case 'daily-article':
+            dailyArticle(rest);
+            break;
+        case 'daily-cover-normalize':
+            dailyCoverNormalize(rest);
+            break;
+        case 'daily-script':
+            dailyScript(rest);
+            break;
+        case 'daily-wrap-docs':
+            dailyWrapDocs(rest);
+            break;
+        case 'daily-generate':
+            dailyGenerate(rest);
+            break;
+        case 'daily-intro':
+            dailyIntro(rest);
+            break;
+        case 'daily-quality-report':
+            dailyQualityReport(rest);
+            break;
+        case 'daily-publish-prep':
+            dailyPublishPrep(rest);
+            break;
+        case 'daily-publish-surfdash':
+            dailyPublishSurfdash(rest);
+            break;
+        case 'daily-show-notes':
+            dailyShowNotes(rest);
+            break;
+        case 'daily-publish-podcast':
+            dailyPublishPodcast(rest);
+            break;
+        case 'daily-publish-classify':
+            dailyPublishClassify(rest);
+            break;
+        case 'daily-patch-surfdash':
+            dailyPatchSurfdash(rest);
+            break;
+        case 'daily-publish-partial':
+            dailyPublishPartial(rest);
+            break;
+        case 'daily-run-report':
+            dailyRunReport(rest);
+            break;
+        case 'daily-translate-localize':
+            dailyTranslateLocalize(rest);
+            break;
+        case 'daily-translate-sync':
+            dailyTranslateSync(rest);
+            break;
+        default:
+            fail(
+                `unknown stage: ${stage ?? '(none)'} (expected prepare-itc|prepare-solo|prepare-storm|validate|wrap|duration|render-storm|daily-*)`,
+            );
     }
-    case 'daily-prepare':
-        dailyPrepare(rest);
-        break;
-    case 'daily-collect-facts':
-        dailyCollectFacts(rest);
-        break;
-    case 'daily-plan':
-        dailyPlan(rest);
-        break;
-    case 'daily-qc-content':
-        dailyQcContent(rest);
-        break;
-    case 'daily-article':
-        dailyArticle(rest);
-        break;
-    case 'daily-cover-normalize':
-        dailyCoverNormalize(rest);
-        break;
-    case 'daily-script':
-        dailyScript(rest);
-        break;
-    case 'daily-wrap-docs':
-        dailyWrapDocs(rest);
-        break;
-    case 'daily-generate':
-        dailyGenerate(rest);
-        break;
-    case 'daily-quality-report':
-        dailyQualityReport(rest);
-        break;
-    case 'daily-publish-prep':
-        dailyPublishPrep(rest);
-        break;
-    case 'daily-publish-surfdash':
-        dailyPublishSurfdash(rest);
-        break;
-    case 'daily-show-notes':
-        dailyShowNotes(rest);
-        break;
-    case 'daily-publish-podcast':
-        dailyPublishPodcast(rest);
-        break;
-    case 'daily-publish-classify':
-        dailyPublishClassify(rest);
-        break;
-    case 'daily-publish-partial':
-        dailyPublishPartial(rest);
-        break;
-    case 'daily-run-report':
-        dailyRunReport(rest);
-        break;
-    case 'daily-translate-en':
-        dailyTranslateEn(rest);
-        break;
-    case 'daily-translate-ja':
-        dailyTranslateJa(rest);
-        break;
-    case 'daily-translate-sync':
-        dailyTranslateSync(rest);
-        break;
-    default:
-        fail(
-            `unknown stage: ${stage ?? '(none)'} (expected prepare-itc|prepare-solo|prepare-storm|validate|wrap|duration|render-storm|daily-*)`,
-        );
-}