@gobing-ai/knowledge-kit 0.1.8 → 0.1.10

package/plugins/publishings/surfdash-pub/src/digest-check.ts

@@ -0,0 +1,218 @@
+/**
+ * Post-refine digest contract check (2026-10-24).
+ *
+ * The surfdash refine step (scripts/lib/seo-digest.ts) owns the daily-digest title, description
+ * and key_points (ADR-008). `requireRefined` only proves refine *ran*; this module re-verifies the
+ * values against the site's published contract (exact `<series> · <date>：h1、h2` title shape,
+ * `title | Surfing` ≤ 60 code points, description length window + terminal punctuation, no
+ * ellipsis, `label — sentence` key_points) so a regressed derivation fails the publish loud
+ * instead of shipping broken SEO metadata.
+ *
+ * Pure, line-based frontmatter parsing — no YAML dependency (same stance as
+ * {@link normalizeLocaleFrontmatter} and the site's own check-digest script). Handles `"..."`,
+ * `'...'`, plain and `>-`-folded scalars, flow arrays and `  - "..."` block lists.
+ */
+import { SERIES_NAMES } from './patch';
+
+/** Locales the digest series publishes in (zh primary; en/ja translated siblings). */
+export type DigestLocale = keyof typeof SERIES_NAMES;
+
+/** The tag that marks a post as one of the daily digest series (site DIGEST_TAG). */
+export const DIGEST_TAG = 'sub-category:ai-daily';
+
+/** Podcast-intro openings a digest description must not start with (case-insensitive). */
+const PODCAST_INTROS = ['这里是由Robin', '咸话咸说', 'This is Robin', 'Robin がお届け'] as const;
+
+/** Rendered `<title>` budget: title + " | Surfing" must fit (site SEO_TITLE_LIMIT). */
+const SEO_TITLE_LIMIT = 60;
+
+/** One parsed frontmatter entry: a scalar string or a block/flow list of strings. */
+type FrontmatterValue = string | string[];
+
+/** Opening `key:` line: bare key, no leading whitespace (frontmatter is never indented). */
+const KEY_LINE = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/;
+
+const escapeRe = (token: string): string => token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Unquotes a YAML scalar: `"…"` via JSON (mapContent writes JSON.stringify), `'…'` with '' unescape. */
+function unquote(value: string): string {
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        try {
+            return JSON.parse(value) as string;
+        } catch {
+            return value.slice(1, -1);
+        }
+    }
+    if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+        return value.slice(1, -1).replaceAll("''", "'");
+    }
+    return value;
+}
+
+/**
+ * Line-based frontmatter parse: scalars (plain/quoted/folded) and string lists (block `- item`
+ * or flow `[a, b]`). Unknown shapes degrade to the raw text; a missing frontmatter yields {}.
+ */
+export function parseFrontmatterScalars(markdown: string): Map<string, FrontmatterValue> {
+    const out = new Map<string, FrontmatterValue>();
+    const lines = markdown.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---') return out;
+    const end = lines.findIndex((line, i) => i > 0 && line.trim() === '---');
+    if (end < 0) return out;
+    for (let i = 1; i < end; i++) {
+        const line = lines[i];
+        if (!line) continue;
+        const match = line.match(KEY_LINE);
+        if (!match?.[1] || match[2] === undefined) continue;
+        const key = match[1];
+        const value = match[2].trim();
+        if (value === '>-' || value === '>' || value === '>+' || value === '|-' || value === '|') {
+            // Folded scalar: indented continuation lines, joined with spaces (block scalars too —
+            // descriptions are prose, a stray newline matters less than losing the text).
+            const parts: string[] = [];
+            let j = i + 1;
+            while (j < end) {
+                const continuation = lines[j];
+                if (!continuation || !/^[ \t]+\S/.test(continuation)) break;
+                parts.push(continuation.trim());
+                j++;
+            }
+            out.set(key, parts.join(' '));
+            i = j - 1;
+            continue;
+        }
+        if (value === '') {
+            // Block list: `key:` followed by `  - item` lines; an empty key stays ''.
+            const items: string[] = [];
+            let j = i + 1;
+            while (j < end) {
+                const itemLine = lines[j];
+                if (!itemLine || !/^\s*-\s+/.test(itemLine)) break;
+                items.push(unquote(itemLine.replace(/^\s*-\s+/, '').trim()));
+                j++;
+            }
+            if (items.length > 0) {
+                out.set(key, items);
+                i = j - 1;
+            } else {
+                out.set(key, '');
+            }
+            continue;
+        }
+        if (value.startsWith('[') && value.endsWith(']')) {
+            out.set(
+                key,
+                value
+                    .slice(1, -1)
+                    .split(',')
+                    .map((item) => unquote(item.trim()))
+                    .filter((item) => item !== ''),
+            );
+            continue;
+        }
+        out.set(key, unquote(value));
+    }
+    return out;
+}
+
+/** The scalar at `key`: a list joins with ' ' (never a shape the digest contract accepts). */
+function scalar(frontmatter: Map<string, FrontmatterValue>, key: string): string | undefined {
+    const value = frontmatter.get(key);
+    if (value === undefined) return undefined;
+    return Array.isArray(value) ? value.join(' ') : value;
+}
+
+/** Terminal punctuation per locale: terminator, optionally followed by closing quotes/brackets. */
+function endsAsSentence(text: string, locale: DigestLocale): boolean {
+    return locale === 'en' ? /[.!?]["')”’]*$/u.test(text.trimEnd()) : /[。！？][」』”）]*$/u.test(text.trimEnd());
+}
+
+/**
+ * Validates a refined post's frontmatter against the digest contract. Returns the problems
+ * (empty = ok); non-digest posts (no `sub-category:ai-daily` tag) return [] unchecked.
+ */
+export function checkDigestFrontmatter(markdown: string, locale: DigestLocale): string[] {
+    const frontmatter = parseFrontmatterScalars(markdown);
+    const tags = frontmatter.get('tags');
+    const tagList = Array.isArray(tags) ? tags : typeof tags === 'string' && tags !== '' ? [tags] : [];
+    if (!tagList.some((tag) => tag.includes(DIGEST_TAG))) return [];
+
+    const problems: string[] = [];
+    const series = SERIES_NAMES[locale];
+    const titleSep = locale === 'en' ? ': ' : '：';
+    const listSep = locale === 'en' ? ', ' : '、';
+
+    const title = scalar(frontmatter, 'title');
+    if (title === undefined || title === '') {
+        problems.push('title: missing');
+    } else {
+        const match = title.match(
+            new RegExp(`^${escapeRe(series)} · (\\d{4}-\\d{2}-\\d{2})${escapeRe(titleSep)}(.+)$`),
+        );
+        if (!match) {
+            problems.push(
+                `title: expected "<series> · YYYY-MM-DD${titleSep}<h1>${listSep}<h2>" for ${series}, got "${title}"`,
+            );
+        } else {
+            const rest = match[2] ?? '';
+            const heads = locale === 'en' ? rest.split(', ') : rest.split('、');
+            const seps = locale === 'en' ? (rest.match(/, /g) ?? []).length : (rest.match(/、/g) ?? []).length;
+            if (seps !== 1 || heads.some((head) => head.trim() === '')) {
+                problems.push(`title: expected exactly two non-empty headlines joined "${listSep}", got "${rest}"`);
+            }
+        }
+        const seoTitle = `${title} | Surfing`;
+        const seoLength = Array.from(seoTitle).length;
+        if (seoLength > SEO_TITLE_LIMIT) {
+            problems.push(`title: "${seoTitle}" is ${seoLength} code points (max ${SEO_TITLE_LIMIT})`);
+        }
+        if (title.includes('…') || title.includes('...')) problems.push('title: contains "…" or "..."');
+    }
+
+    const description = scalar(frontmatter, 'description');
+    const [min, max] = locale === 'en' ? [120, 155] : [70, 100];
+    if (description === undefined || description === '') {
+        problems.push('description: missing');
+    } else {
+        const length = Array.from(description).length;
+        if (length < min || length > max) {
+            problems.push(`description: ${length} code points (expected ${min}–${max} for ${locale})`);
+        }
+        if (!endsAsSentence(description, locale)) {
+            problems.push('description: does not end with sentence punctuation');
+        }
+        const lower = description.toLowerCase();
+        const intro = PODCAST_INTROS.find((candidate) => lower.startsWith(candidate.toLowerCase()));
+        if (intro) problems.push(`description: starts with the podcast intro ("${intro}")`);
+        if (description.includes('…') || description.includes('...')) {
+            problems.push('description: contains "…" or "..."');
+        }
+    }
+
+    const points = frontmatter.get('key_points');
+    if (!Array.isArray(points) || points.length === 0) {
+        problems.push('key_points: missing');
+    } else {
+        const labelMax = locale === 'en' ? 28 : 14;
+        points.forEach((point, index) => {
+            const sep = point.indexOf(' — ');
+            if (sep < 0) {
+                problems.push(`key_points[${index}]: missing " — " separator`);
+                return;
+            }
+            const label = point.slice(0, sep);
+            const text = point.slice(sep + 3);
+            const labelLength = Array.from(label).length;
+            if (labelLength === 0 || labelLength > labelMax) {
+                problems.push(`key_points[${index}]: label "${label}" is ${labelLength} code points (max ${labelMax})`);
+            }
+            if (!endsAsSentence(text, locale)) {
+                problems.push(`key_points[${index}]: text does not end with sentence punctuation`);
+            }
+            if (point.includes('…') || point.includes('...')) {
+                problems.push(`key_points[${index}]: contains "…" or "..."`);
+            }
+        });
+    }
+    return problems;
+}

package/plugins/publishings/surfdash-pub/src/index.ts

@@ -6,8 +6,12 @@ import { type Content, ContentSchema, type Result, ResultSchema } from '@gobing-
 import type { PublishTransport, PublishTransportPayload } from '@gobing-ai/publish-harness';
 import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import { echoError } from '@gobing-ai/ts-utils';
+// The plugin's public digest-contract surface (2026-10-24).
+import { checkDigestFrontmatter, DIGEST_TAG, type DigestLocale } from './digest-check';
 import { localeIndexPath, PATCH_LOCALES, type PatchPostOutcome, patchPostFiles } from './patch';
 
+export { checkDigestFrontmatter, DIGEST_TAG, type DigestLocale } from './digest-check';
+
 /** Result target name for this plugin. */
 const TARGET = 'surfdash';
 
@@ -76,28 +80,14 @@ export function normalizeTag(raw: string): string {
 }
 
 /**
- * Maps Content object into Surfing frontmatter and body per the publish spec.
+ * The content's tag sources (metadata.tags, keywords, subCategory) as normalized frontmatter tags.
+ *
+ * `slugify` drops non-ASCII, so a Chinese tag (`硬件发布`) collapsed to '' and shipped as an empty
+ * YAML tag — the site renders it as a blank chip (seen on 20261011-ai-2026-10-11). Case variants
+ * also collapsed to the same slug twice (`AI` + `ai`), so the set dedupes. `normalizeTag` preserves
+ * `sub-category:<slug>` colon prefixes so sub-category series tags survive into frontmatter.
  */
-export function mapContentToSurfingMarkdown(content: Content, options: MapContentOptions = {}): string {
-    let title = content.title;
-    if (!title) {
-        const match = content.body.match(/^#\s+(.+)$/m);
-        title = match?.[1] ? match[1].trim() : 'Untitled Post';
-    }
-
-    let description: string | undefined;
-    if (typeof content.metadata?.description === 'string') {
-        description = content.metadata.description;
-    } else {
-        const paragraphs = content.body
-            .split(/\n\s*\n/)
-            .map((p) => p.replace(/^#+\s+.*$/, '').trim())
-            .filter((p) => p.length > 0);
-        if (paragraphs.length > 0) {
-            description = paragraphs[0];
-        }
-    }
-
+export function contentTags(content: Content): string[] {
     const rawTags: unknown[] = Array.isArray(content.metadata?.tags)
         ? [...content.metadata.tags]
         : Array.isArray(content.metadata?.keywords)
@@ -107,36 +97,51 @@ export function mapContentToSurfingMarkdown(content: Content, options: MapConten
         const subRaw = content.metadata.subCategory.trim();
         rawTags.push(/^sub-category\s*:/i.test(subRaw) ? subRaw : `sub-category:${subRaw}`);
     }
-    // `slugify` drops non-ASCII, so a Chinese tag (`硬件发布`) collapsed to '' and shipped as an empty
-    // YAML tag — the site renders it as a blank chip (seen on 20261011-ai-2026-10-11). Case variants
-    // also collapsed to the same slug twice (`AI` + `ai`), so the set dedupes. `normalizeTag` preserves
-    // `sub-category:<slug>` colon prefixes so sub-category series tags survive into frontmatter.
-    const tags = [
+    return [
         ...new Set(
             rawTags
                 .filter((t): t is string => typeof t === 'string' && t.trim().length > 0)
                 .map((t: string) => normalizeTag(t)),
         ),
     ].filter((tag) => tag.length > 0);
+}
+
+/**
+ * Maps Content object into Surfing frontmatter and body per the publish spec.
+ */
+export function mapContentToSurfingMarkdown(content: Content, options: MapContentOptions = {}): string {
+    let title = content.title;
+    if (!title) {
+        const match = content.body.match(/^#\s+(.+)$/m);
+        title = match?.[1] ? match[1].trim() : 'Untitled Post';
+    }
+
+    // ADR-008: the site's refine step owns the digest/SEO description; the generator's
+    // first-paragraph fallback shipped the raw lede as SEO metadata before refine existed.
+    const description =
+        typeof content.metadata?.description === 'string' && content.metadata.description.length > 0
+            ? content.metadata.description
+            : '';
+
+    const tags = contentTags(content);
 
     const isoDate = options.publishDate ?? new Date().toISOString().slice(0, 10);
-    const firstRefUrl = content.references?.[0]?.url;
-    const canonical =
-        typeof firstRefUrl === 'string'
-            ? firstRefUrl
-            : typeof content.metadata?.canonicalUrl === 'string'
-              ? content.metadata.canonicalUrl
-              : undefined;
     const draft = typeof content.metadata?.published === 'boolean' ? !content.metadata.published : false;
 
     // Strict surfdash PostSchema (surfdash/src/content/schema.ts): publishDate (ISO date) is
     // required; unknown keys (`date`, `canonical_url`, `published`) are rejected.
+    //
+    // `canonical` is deliberately NOT written here. The canonical URL is the site's own route
+    // for this slug, which only the site can compute (locale prefix + collection segment); the
+    // previous `references[0].url` fallback pointed the canonical at an unrelated *external*
+    // source and would have dropped the post out of the sitemap if surfdash's refine step had
+    // not overwritten it. See docs/00_ADR.md ADR-008: the generator supplies content, the site
+    // supplies identity.
     const frontmatterObj: Record<string, unknown> = {
         title,
-        description: description ?? '',
+        description,
         tags,
         publishDate: isoDate,
-        ...(canonical ? { canonical } : {}),
         draft,
         ...(options.image ? { image: options.image, og_image: options.image } : {}),
     };
@@ -145,6 +150,11 @@ export function mapContentToSurfingMarkdown(content: Content, options: MapConten
     return `${yamlLines.join('\n')}\n\n${content.body.trim()}\n`;
 }
 
+/** True when the content's tag sources (contentTags) mark it as a daily digest post. */
+function isDigestContent(content: Content): boolean {
+    return contentTags(content).some((tag) => tag.includes(DIGEST_TAG));
+}
+
 /** `Result` failure helper: ok false + error (podcast-pub pattern). */
 function fail(error: string): Result {
     return ResultSchema.parse({ ok: false, target: TARGET, error });
@@ -251,6 +261,7 @@ async function spawnCli(cmd: string[], cwd: string): Promise<CliSpawnResult> {
         cwd,
         stdout: 'pipe',
         stderr: 'pipe',
+        env: process.env,
     });
     const [exitCode, stdout, stderr] = await Promise.all([
         proc.exited,
@@ -273,6 +284,64 @@ export function withEmdashTokenHint(errText: string): string {
         : errText;
 }
 
+/**
+ * Post-conditions the site guarantees after its publishing pipeline ran.
+ *
+ * The publisher does not derive SEO metadata any more (ADR-008): surfdash's refine step owns
+ * `refined`, `seo_title`, `canonical` and the digest title/description. Verifying the marker
+ * here turns a silently-regressed site pipeline into a loud publisher failure instead of a post
+ * that ships with a date-only title — which is exactly how the 2026-10-21 regression went
+ * unnoticed.
+ */
+export interface RefinedSnapshot {
+    title?: string;
+    seoTitle?: string;
+    description?: string;
+    canonical?: string;
+}
+
+/** Reads the frontmatter scalar fields the site owns; undefined when refine never ran. */
+export function readRefinedSnapshot(filePath: string): RefinedSnapshot | undefined {
+    if (!existsSync(filePath)) return undefined;
+    const raw = readFileSync(filePath, 'utf-8');
+    const block = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const fm = block?.[1] ?? '';
+    if (!fm || !/^refined:\s*true$/m.test(fm)) return undefined;
+    const read = (key: string): string | undefined => {
+        const m = fm.match(new RegExp(`^${key}:\\s*(?:>-?\n((?:[ \\t]+.*\n?)+)|(.*))$`, 'm'));
+        if (!m) return undefined;
+        const value = (m[1] ?? m[2] ?? '').replace(/\n[ \t]+/g, ' ').trim();
+        return value.replace(/^["']|["']$/g, '') || undefined;
+    };
+    return {
+        title: read('title'),
+        seoTitle: read('seo_title'),
+        description: read('description'),
+        canonical: read('canonical'),
+    };
+}
+
+/** Error text when the site pipeline did not mark the post refined, else undefined. */
+export function requireRefined(filePath: string): string | undefined {
+    if (readRefinedSnapshot(filePath)) return undefined;
+    return `surfdash refine step did not run for ${filePath} (no \`refined: true\`): the publishing pipeline is broken — the post would ship with generator-supplied SEO metadata`;
+}
+
+/**
+ * Post-refine digest contract gate (2026-10-24): `requireRefined` proves refine ran; this proves
+ * the refined values still satisfy the digest contract. Returns the fail-loud error text, or
+ * undefined when ok / downgraded. `SURFDASH_DIGEST_CHECK=warn` echoes each problem and continues.
+ */
+export function digestCheckGate(filePath: string, locale: DigestLocale): string | undefined {
+    const problems = checkDigestFrontmatter(readFileSync(filePath, 'utf-8'), locale);
+    if (problems.length === 0) return undefined;
+    if (process.env.SURFDASH_DIGEST_CHECK === 'warn') {
+        for (const problem of problems) echoError(`digest check (warn): ${problem}`);
+        return undefined;
+    }
+    return `digest frontmatter check failed: ${problems.join('; ')}`;
+}
+
 /** Outcome of {@link pushPostGit} — the union keeps fail-loud errors typed at the call site. */
 export type GitPushOutcome = { ok: true; hash: string } | { ok: false; error: string };
 
@@ -300,6 +369,41 @@ async function assertMainBranch(surfdashRoot: string): Promise<{ ok: true } | {
     return { ok: true };
 }
 
+/**
+ * Fast-forward the checkout onto `origin/main` before anything is written (2026-10-22).
+ *
+ * Three consecutive publish days failed with `! [rejected] main -> main (fetch first)`: this
+ * checkout sat behind a remote another machine had pushed to, so the publish commit landed on a
+ * stale base and the push was rejected — after the article had already been written and committed,
+ * and after the podcast episode had already published, so the run closed `partial`/`failed` while a
+ * real episode was live. A fast-forward is lossless (HEAD moves only when local carries no commit of
+ * its own), which is exactly the case here; a DIVERGED checkout is the operator's call and fails
+ * loud with both counts. An unreachable remote is not fatal: the fetch error is swallowed so the
+ * push below reports the real reason.
+ */
+export async function fastForwardToOrigin(surfdashRoot: string): Promise<{ ok: true } | { ok: false; error: string }> {
+    const fetched = await spawnCli(['git', 'fetch', '--quiet', 'origin', 'main'], surfdashRoot);
+    if (fetched.exitCode !== 0) return { ok: true };
+    const counts = await spawnCli(['git', 'rev-list', '--left-right', '--count', 'origin/main...HEAD'], surfdashRoot);
+    if (counts.exitCode !== 0) return { ok: true };
+    const [behindRaw = '0', aheadRaw = '0'] = counts.stdout.trim().split(/\s+/);
+    const behind = Number(behindRaw);
+    const ahead = Number(aheadRaw);
+    if (!Number.isFinite(behind) || !Number.isFinite(ahead) || behind === 0) return { ok: true };
+    if (ahead > 0) {
+        return {
+            ok: false,
+            error: `surfdash checkout diverged from origin/main (${ahead} local, ${behind} remote commit(s)): reconcile it by hand before publishing`,
+        };
+    }
+    const merged = await spawnCli(['git', 'merge', '--ff-only', '--quiet', 'origin/main'], surfdashRoot);
+    if (merged.exitCode !== 0) {
+        return { ok: false, error: `surfdash fast-forward to origin/main failed: ${cliErrorText(merged)}` };
+    }
+    echoError(`surfdash: fast-forwarded ${behind} commit(s) to origin/main before writing`);
+    return { ok: true };
+}
+
 /**
  * Commits several paths of the surfdash checkout and pushes them to `main` — the plural form of
  * {@link pushPostGit} the post-patch needs (it writes the posts and any copied cover). Same
@@ -315,6 +419,8 @@ export async function commitPostPaths(
     if (relPaths.length === 0) return { ok: true, hash: 'unchanged' };
     const branch = await assertMainBranch(surfdashRoot);
     if (!branch.ok) return branch;
+    const base = await fastForwardToOrigin(surfdashRoot);
+    if (!base.ok) return base;
     const add = await spawnCli(['git', 'add', '--', ...relPaths], surfdashRoot);
     if (add.exitCode !== 0) return { ok: false, error: `surfdash git add failed: ${cliErrorText(add)}` };
     const staged = await spawnCli(['git', 'diff', '--cached', '--quiet', '--', ...relPaths], surfdashRoot);
@@ -484,6 +590,13 @@ async function syncPost(options: SurfdashPubOptions): Promise<Result> {
                 `publish-orchestrator sync failed (exit ${spawned.exitCode}): ${withEmdashTokenHint(cliErrorText(spawned))}`,
             );
         }
+        // Digest contract (2026-10-24): verify the synced post's frontmatter for its own locale;
+        // paths outside content/posts/articles/<zh|en|ja>/ carry no digest series to check.
+        const localeInPath = postPath.postPath.match(/[\\/]content[\\/]posts[\\/]articles[\\/](zh|en|ja)[\\/]/);
+        if (localeInPath) {
+            const digestProblem = digestCheckGate(postPath.postPath, localeInPath[1] as DigestLocale);
+            if (digestProblem) return fail(digestProblem);
+        }
         return ResultSchema.parse({
             ok: true,
             target: TARGET,
@@ -621,16 +734,26 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
         return fail(`post path escapes ${articlesRoot}`);
     }
     const coverPath = payload.content.metadata?.coverImage;
-    if (typeof coverPath === 'string' && existsSync(coverPath) && !COVER_EXTS.has(extname(coverPath).toLowerCase())) {
+    // R4 + 2026-10-24: a coverImage that does not exist must fail before anything is written —
+    // the old silent skip published a coverless post while the run believed it had one.
+    if (typeof coverPath === 'string' && !existsSync(coverPath)) {
+        return fail(`metadata.coverImage not found: ${coverPath}`);
+    }
+    if (typeof coverPath === 'string' && !COVER_EXTS.has(extname(coverPath).toLowerCase())) {
         return fail(`metadata.coverImage must be one of ${[...COVER_EXTS].join(', ')}`);
     }
+    // Daily digest posts are the series' public face: a missing cover ships a blank OG card.
+    // The check uses the same tag sources as mapContentToSurfingMarkdown (contentTags).
+    if (isDigestContent(payload.content) && typeof coverPath !== 'string') {
+        return fail('digest post has no cover image (metadata.coverImage)');
+    }
 
     await createNodeFileSystem().ensureDir(postDir);
 
     // Cover image: metadata.coverImage (absolute local path) is copied into the post's
     // assets dir and referenced relatively — the surfdash PostSchema accepts ./assets/<file>.
     let imageFrontmatter: string | undefined;
-    if (typeof coverPath === 'string' && existsSync(coverPath)) {
+    if (typeof coverPath === 'string') {
         const assetsDir = join(postDir, 'assets');
         await createNodeFileSystem().ensureDir(assetsDir);
         const coverName = `cover${extname(coverPath).toLowerCase()}`;
@@ -653,6 +776,14 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
             );
         }
 
+        // Contract check (ADR-008): the site, not this plugin, owns SEO metadata.
+        const notRefined = requireRefined(filePath);
+        if (notRefined) return fail(notRefined);
+        // Digest contract (2026-10-24): the refined values themselves must hold, before any push.
+        const digestProblem = digestCheckGate(filePath, locale as DigestLocale);
+        if (digestProblem) return fail(digestProblem);
+        const refined = readRefinedSnapshot(filePath);
+
         // Deploy seam: commit + push the post so deploy.yml builds it, then wait for
         // the live URL — downstream show-notes advertise a real page, not a 404.
         // Tests (and offline runs) opt out via SURFDASH_AUTO_PUSH=0.
@@ -669,7 +800,7 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
                 message: 'Published via postsurfing CLI (auto-push disabled)',
                 // Absolute post path lets downstream steps (locale translation + CMS sync)
                 // derive the surfdash checkout root without extra configuration.
-                metadata: { postPath: filePath },
+                metadata: { postPath: filePath, refinedTitle: refined?.title, refinedCanonical: refined?.canonical },
             });
         }
         const relPostDir = join('content', 'posts', 'articles', locale, slug);
@@ -684,7 +815,7 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
             message: live
                 ? 'Published, committed, pushed, and live on the site'
                 : 'Published and pushed; URL not live within the verify window — check the surfdash deploy workflow',
-            metadata: { postPath: filePath, gitCommit: pushed.hash, live },
+            metadata: { postPath: filePath, gitCommit: pushed.hash, live, refinedTitle: refined?.title },
         });
     } catch (err: unknown) {
         return fail(`Postsurfing transport error: ${err instanceof Error ? err.message : String(err)}`);

package/plugins/publishings/surfdash-pub/src/patch.ts

@@ -60,13 +60,23 @@ export function localeIndexPath(postPath: string, locale: PatchLocale): string |
 
 /**
  * The podcast cross-link line per locale (task 0189 R4: the column's episode-title pattern, not the
- * retired news-bulletin name).
+ * retired news-bulletin name). The series names are fixed per-locale product identity (2026-10-23:
+ * the translate agent had been inventing them) and must agree with the pipeline's single table in
+ * plugins/kk/scripts/series-names.ts — the two packages cannot import each other, so tests assert
+ * the agreement. digest-check.ts imports this table as the title-contract series names.
  */
+export const SERIES_NAMES: Record<PatchLocale, string> = {
+    zh: '每日AI乱炖',
+    en: 'Daily AI Stew',
+    ja: 'デイリーAIシチュー',
+};
+
 export function crossLinkFor(locale: PatchLocale, dateIso: string, showNotesUrl: string): string {
+    const series = SERIES_NAMES[locale];
     const links: Record<PatchLocale, string> = {
-        zh: `🎧 本期已同步制作为播客节目，[点击收听《每日AI乱炖 · ${dateIso}》](${showNotesUrl})。`,
-        en: `🎧 This episode is also available as a podcast: [listen to 每日AI乱炖 · ${dateIso}](${showNotesUrl}).`,
-        ja: `🎧 本エピソードはポッドキャストでも配信中：[每日AI乱炖 · ${dateIso} を聴く](${showNotesUrl})。`,
+        zh: `🎧 本期已同步制作为播客节目，[点击收听《${series} · ${dateIso}》](${showNotesUrl})。`,
+        en: `🎧 This episode is also available as a podcast: [listen to ${series} · ${dateIso}](${showNotesUrl}).`,
+        ja: `🎧 本エピソードはポッドキャストでも配信中：[${series} · ${dateIso} を聴く](${showNotesUrl})。`,
     };
     return links[locale];
 }
@@ -118,11 +128,23 @@ export async function patchPostFiles(request: PatchPostRequest): Promise<PatchPo
         const end = frontmatterEnd(md);
         const fm = end < 0 ? md : md.slice(0, end);
         if (request.coverUrl !== '') {
+            // A relative or http:// cover would ship an unservable OG card — the deployed worker
+            // only serves absolute https URLs (prod feedback 2026-09-29).
+            if (!/^https:\/\//.test(request.coverUrl)) {
+                throw new Error(`coverUrl must be an absolute https:// URL, got: ${request.coverUrl}`);
+            }
             md = upsertFrontmatterKey(md, 'image', request.coverUrl);
             md = upsertFrontmatterKey(md, 'og_image', request.coverUrl);
             images[locale] = request.coverUrl;
-        } else if (!/^image:/m.test(fm) && (await fs.exists(request.localCover))) {
+        } else if (!/^image:/m.test(fm)) {
             // Fallback for a run without a podcast cover: ship the rendered cover with the post.
+            // A locale with no cover anywhere must fail naming the locale, not silently skip —
+            // the CMS card would carry no servable image at all.
+            if (!(await fs.exists(request.localCover))) {
+                throw new Error(
+                    `${locale} post has no cover: coverUrl is empty, the frontmatter has no image key, and localCover does not exist (${request.localCover})`,
+                );
+            }
             const asset = join(dir, 'assets', 'cover.png');
             await fs.ensureDir(dirname(asset));
             await fs.copy(request.localCover, asset);
@@ -131,8 +153,23 @@ export async function patchPostFiles(request: PatchPostRequest): Promise<PatchPo
             md = upsertFrontmatterKey(md, 'og_image', './assets/cover.png');
             images[locale] = './assets/cover.png';
         }
-        if (request.showNotesUrl !== '' && !md.includes(request.showNotesUrl)) {
-            md = `${md.replace(/\s*$/, '')}\n\n${crossLinkFor(locale, request.dateIso, request.showNotesUrl)}\n`;
+        if (request.showNotesUrl !== '') {
+            // 2026-10-23: a previous run may have left a 🎧 cross-link line carrying a retired
+            // series name — refresh that line in place instead of keeping it forever (the URL it
+            // carries made a fresh append a no-op). A non-cross-link line mentioning the URL is
+            // left alone; the fresh link is only appended when no line carries the URL at all.
+            const link = crossLinkFor(locale, request.dateIso, request.showNotesUrl);
+            const lines = md.split('\n');
+            const carriesUrl = lines.some((line) => line.includes(request.showNotesUrl));
+            if (!carriesUrl) {
+                md = `${md.replace(/\s*$/, '')}\n\n${link}\n`;
+            } else {
+                md = lines
+                    .map((line) =>
+                        line.includes(request.showNotesUrl) && line.trimStart().startsWith('🎧') ? link : line,
+                    )
+                    .join('\n');
+            }
         }
         if (md !== before) {
             await fs.writeFile(indexMd, md);

package/plugins/publishings/threads-pub/dist/index.js

@@ -12254,6 +12254,10 @@ init_config();
 
 // ../../packages/kk-core/src/render-md.ts
 if (false) {}
+// ../../packages/kk-core/src/sentences.ts
+var CJK_TERMINATORS = new Set(["\u3002", "\uFF01", "\uFF1F"]);
+var LATIN_TERMINATORS = new Set([".", "!", "?"]);
+var ATTACHED_CLOSERS = new Set(["\u201D", "\u2019", "\u300D", "\u300F", "\uFF09", ")", '"', "'"]);
 // ../../packages/publish-harness/src/index.ts
 class FakeTransportCore {
   callLogs = [];

package/plugins/publishings/wechatmp-pub/dist/index.js

@@ -20162,6 +20162,10 @@ init_runtime_node_bun();
 
 // ../../packages/kk-core/src/render-md.ts
 if (false) {}
+// ../../packages/kk-core/src/sentences.ts
+var CJK_TERMINATORS = new Set(["\u3002", "\uFF01", "\uFF1F"]);
+var LATIN_TERMINATORS = new Set([".", "!", "?"]);
+var ATTACHED_CLOSERS = new Set(["\u201D", "\u2019", "\u300D", "\u300F", "\uFF09", ")", '"', "'"]);
 // ../../packages/publish-harness/src/index.ts
 import { homedir } from "os";
 import { join, resolve } from "path";

package/plugins/publishings/wechatmp-pub/dist/profile-check.js

@@ -20682,6 +20682,10 @@ var PluginManifestSchema = PluginManifestSchemaBase.superRefine((manifest, ctx)
 });
 // ../../packages/kk-core/src/render-md.ts
 if (false) {}
+// ../../packages/kk-core/src/sentences.ts
+var CJK_TERMINATORS = new Set(["\u3002", "\uFF01", "\uFF1F"]);
+var LATIN_TERMINATORS = new Set([".", "!", "?"]);
+var ATTACHED_CLOSERS = new Set(["\u201D", "\u2019", "\u300D", "\u300F", "\uFF09", ")", '"', "'"]);
 // ../../plugins/publishings/wechatmp-pub/src/cgi.ts
 var MP_ORIGIN = "https://mp.weixin.qq.com";
 var FILETRANSFER_URL = `${MP_ORIGIN}/cgi-bin/filetransfer`;