@gobing-ai/knowledge-kit 0.1.5 → 0.1.7

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

@@ -74,6 +74,7 @@ import {
     coverBrief,
     coverNormalizeBody,
     dedupPlanByTitle,
+    expandHome,
     fail,
     failWith,
     firstArtifact,
@@ -1317,7 +1318,10 @@ export function dailyIntro(args: string[]): void {
         if (rawFile === undefined) {
             failWith(1, 'intro-music: voice content carries no mp3Path/audioPath');
         }
-        const introPath = resolve(introSrc);
+        // The sting is an operator asset under the config root (ADR-042), not a works artifact:
+        // workflow vars carry it as `~/.config/kk/voices/…`, and a shell does not expand `~` inside
+        // the quoted "${vars.intro_music}" argument, so expansion happens here.
+        const introPath = resolve(expandHome(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}`);
@@ -1981,6 +1985,52 @@ export function dailySafetyGate(args: string[]): void {
     });
 }
 
+/**
+ * `daily-preflight <workflow.yaml>…` — assert the stage runner that `kk stage` just loaded
+ * advertises every `kk stage <name>` these workflow definitions invoke.
+ *
+ * WHY (2026-10-20): the scheduler runs the CHECKOUT's workflow YAML while `kk stage` resolves the
+ * runner from the INSTALLED package (`apps/cli/src/stage.ts`). A commit that adds a stage therefore
+ * outruns the global install silently, and the mismatch only surfaces where the new stage is first
+ * reached. That day's 04:30 run died 29 minutes in at `safety` with `unknown stage:
+ * daily-safety-verdict` (present in the checkout, absent from the installed 0.1.4) and published
+ * nothing. This runs as the first command of the run's `prepare` node, so the same skew costs one
+ * cheap step and names both the missing stages and the refresh command.
+ *
+ * The known-name set is the dispatch switch of the sibling `kk-workflow-stages.ts` — the file beside
+ * this one, i.e. the copy actually in force, never a checkout-vs-install guess.
+ */
+export function dailyPreflight(args: string[]): void {
+    const files = args.filter((arg) => arg !== '');
+    timed('', 'preflight', () => {
+        if (files.length === 0) failWith(2, 'daily-preflight: pass at least one workflow YAML path');
+        const runner = join(import.meta.dir, 'kk-workflow-stages.ts');
+        if (!isFile(runner)) failWith(1, `daily-preflight.runner-missing: ${runner} is not beside this stage body`);
+        const known = new Set(
+            [...readFileSync(runner, 'utf-8').matchAll(/^\s*case '([a-z][a-z0-9-]*)':/gm)].map((match) =>
+                String(match[1]),
+            ),
+        );
+        const missing: string[] = [];
+        for (const file of files) {
+            if (!isFile(file)) failWith(1, `daily-preflight.workflow-missing: ${file}`);
+            for (const match of readFileSync(file, 'utf-8').matchAll(/\bkk stage ([a-z][a-z0-9-]*)/g)) {
+                const name = String(match[1]);
+                if (!known.has(name)) missing.push(`${name} (needed by ${basename(file)})`);
+            }
+        }
+        if (missing.length > 0) {
+            failWith(
+                1,
+                `daily-preflight.runner-stale: the installed stage runner ${runner} does not know ${missing.join(', ')} — refresh it (install the released kk package, or rsync plugins/kk/scripts/ per AGENTS.md) before the scheduled run`,
+            );
+        }
+        console.log(
+            `preflight: stage runner advertises every stage ${files.map((file) => basename(file)).join(' + ')} invokes`,
+        );
+    });
+}
+
 /**
  * Task 0317 R6 — fold the gate's own classification, its stamp and the `kk-safety-verdict` catalog
  * decision into ONE accept/refuse token the `judge -> clean` guard reads as a single predicate

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

@@ -159,6 +159,20 @@ async function loadDailyStages(): Promise<typeof import('./daily-stages.ts')> {
         );
     }
 }
+/**
+ * Load the audio-quality diagnostic lazily: it shells out to ffprobe/ffmpeg and is only needed when an
+ * operator asks for it, so the runner must not pay for it on every stage (and an install without
+ * ffmpeg on PATH still runs every other stage).
+ */
+async function loadAudioQuality(): Promise<typeof import('./audio-quality.ts')> {
+    try {
+        return await import('./audio-quality.ts');
+    } catch {
+        return fail(
+            'audio-quality.ts not found next to kk-workflow-stages.ts — install or refresh the kk package (bun link in a checkout)',
+        );
+    }
+}
 export const ERRNO_REASONS: Record<string, string> = {
     EACCES: 'Permission denied',
     EROFS: 'Read-only file system',
@@ -737,7 +751,7 @@ function formatRunDate(): string {
 }
 
 /** Expand the `~/` and `$HOME/` prefixes the config examples use. */
-function expandHome(p: string): string {
+export function expandHome(p: string): string {
     if (p.startsWith('~/')) return join(homedir(), p.slice(2));
     if (p.startsWith('$HOME/')) return join(homedir(), p.slice('$HOME/'.length));
     return p;
@@ -1638,6 +1652,16 @@ if (import.meta.main)
             dailyScript(rest);
             break;
         }
+        case 'audio-quality': {
+            const { runAudioQuality } = await loadAudioQuality();
+            await runAudioQuality(rest);
+            break;
+        }
+        case 'daily-preflight': {
+            const { dailyPreflight } = await loadDailyStages();
+            dailyPreflight(rest);
+            break;
+        }
         case 'daily-safety-prep': {
             const { dailySafetyPrep } = await loadDailyStages();
             dailySafetyPrep(rest);

package/plugins/kk/workflows/kk-daily-ai-voice.yaml

@@ -30,7 +30,9 @@ vars:
   # env block; smoke render 6.8s). Flip back with vdriver="voicebox".
   vdriver: "gemini"
   # 20260917 review #7: 8s intro sting prepended to every daily output; empty = skip.
-  intro_music: ".works/kk-daily-ai-voice/AI每日资讯_8秒播客片头.mp3"
+  # The sting is an operator asset: it lives under the config root (ADR-042), never in the works
+  # tree. `~` is expanded by the daily-intro stage, so it stays machine-portable.
+  intro_music: "~/.config/kk/voices/AI每日资讯_8秒播客片头.mp3"
   # 20260917 review #4/#6: surfdash checkout the patch stage commits to.
   surfdash_root: "/Users/robin/xprojects/surfdash"
   title: ""

package/plugins/kk/workflows/kk-daily-ai-voice2.yaml

@@ -25,11 +25,17 @@ vars:
   # Voice driver switch — voxcpm (voxcpm-tts) | gemini (gemini-tts) | voicebox (voice-gen)
   # | ominivoice (omni-voice-gen). The generate tier below mirrors the fallback order, and the
   # fit/duration gates take their spoken-char rate from this var — switching drivers here is enough.
-  # 2026-10-15 production test (operator decision): voxcpm first, then gemini, then omni. voxcpm
-  # rendered that episode in 21.8 min at a measured 5.19 字/秒 (fitted at 5.2); if the audio verdict
-  # is good this is the standing order, otherwise revert this default to "gemini".
+  # 2026-10-20 (operator decision): voxcpm STAYS the primary. It is audibly echoey - a 40 ms periodic
+  # reflection on renders longer than ~30 s plus a pause floor only 16-22 dB below speech, measured by
+  # `kk stage audio-quality` on every episode's raw model output since 10-15 (cepstrum 40 ms @ 26-31 dB
+  # / pauseFloor -16..-22 dB, versus gemini's 20-25 ms @ 19-20 dB / -34..-37 dB) - and no exposed knob
+  # (cfg_value, inference_timesteps, normalize, denoise) or usable checkpoint fixes it (VoxCPM1.5:
+  # 80 ms @ 31 dB; VoxCPM-0.5B loses the lattice but measures -15.5 dB at 16 kHz). The operator keeps
+  # the local driver for its speed and cost and will monitor it episode by episode until a proper fix
+  # exists; flipping this one var to "gemini" is the escape hatch (measured dry: 20-25 ms / -34..-37 dB)
+  # at the price of a 1h47m-2h21m remote render.
   vdriver: "voxcpm"
-  intro_music: ".works/kk-daily-ai-voice/AI每日资讯_8秒播客片头.mp3"
+  intro_music: "~/.config/kk/voices/AI每日资讯_8秒播客片头.mp3"
   surfdash_root: "/Users/robin/xprojects/surfdash"
   title: ""
   skip_review: "false"
@@ -113,11 +119,18 @@ nodes:
       the artifact directories and the safety revise budget. `kk ledger sync` records runs that
       already finished without a ledger row (failed ones included) — a fail-fast DAG never reaches
       its own `ledger` node, so the next run's prepare is the backfill (design §7).
+      The `daily-preflight` stage runs FIRST: the scheduler executes this checkout's YAML while
+      `kk stage` resolves its stage runner from the installed package, so a run whose YAML names a
+      stage the installed runner lacks must fail here, naming the stage, instead of 29 minutes later
+      inside the nested safety machine (2026-10-20: `unknown stage: daily-safety-verdict`, nothing
+      published).
     action:
       kind: shell
       options:
         command: >-
-          kk daily prepare --workflow kk-daily-ai-voice2 --run-date "${vars.run_date}" --ledger-sync
+          kk stage daily-preflight plugins/kk/workflows/kk-daily-ai-voice2.yaml
+          plugins/kk/workflows/kk-daily-safety.yaml
+          && kk daily prepare --workflow kk-daily-ai-voice2 --run-date "${vars.run_date}" --ledger-sync
           --run "${vars.__runId}" --definition-digest "${vars.__definitionDigest}"
           --setting window="${vars.window}" --setting language="${vars.language}" --setting vdriver="${vars.vdriver}"
           --setting skip_review="${vars.skip_review}" --setting transcode_mp3="${vars.transcode_mp3}"
@@ -548,7 +561,7 @@ nodes:
           kk stage daily-wrap-docs "${vars.work_dir}" "${vars.run_date}" "${vars.voice_profile}"
 
   - id: generate
-    description: "Voice tier, primary driver (vars.vdriver — voxcpm while the 2026-10-15 production test runs). onError: continue — the fallback siblings below are the loud chain (same pattern as 0238 R2)."
+    description: "Voice tier, primary driver (vars.vdriver — voxcpm; its 40 ms lattice is known and monitored, see the vdriver comment). onError: continue — the fallback siblings below are the loud chain (same pattern as 0238 R2)."
     # wrap-docs is a data dependency, not a sibling: daily-generate reads its _10_wrap-docs_docs.json
     # as the TTS input. Without this edge the two nodes race in the same wave (0212 dogfood finding).
     dependsOn: [script, safety, review, wrap-docs]
@@ -570,7 +583,7 @@ nodes:
   # its plugin id and the cache ignores foreign-driver sections, so a failed attempt can neither be
   # relabeled nor mix voices). Non-final siblings continue on error; the last one is loud.
   - id: generate-fallback
-    description: "Voice tier fallback 1: gemini (gemini-tts) when the primary driver left no valid Content"
+    description: "Voice tier fallback 1: gemini (gemini-tts) when the primary driver left no valid Content — the measured-dry escape hatch from voxcpm's lattice"
     dependsOn: [generate]
     condition:
       kind: shell

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

@@ -12423,6 +12423,10 @@ ${crossLinkFor(locale, request.dateIso, request.showNotesUrl)}
     if (md !== before) {
       await fs.writeFile(indexMd, md);
       written.push(indexMd);
+      const assetsDir = join(dir, "assets");
+      if (await fs.exists(assetsDir) && !written.includes(join(assetsDir, "cover.png"))) {
+        written.push(assetsDir);
+      }
       changed += 1;
     }
   }
@@ -12437,6 +12441,14 @@ var COVER_EXTS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
 function slugify2(str) {
   return str.toLowerCase().replace(/[^\w\s-]/g, "").trim().replace(/[\s_]+/g, "-");
 }
+function normalizeTag(raw) {
+  const match = raw.match(/^\s*sub-category\s*:(.*)$/i);
+  if (match) {
+    const subSlug = slugify2(match[1] ?? "");
+    return subSlug ? `sub-category:${subSlug}` : "";
+  }
+  return slugify2(raw);
+}
 function mapContentToSurfingMarkdown(content, options = {}) {
   let title = content.title;
   if (!title) {
@@ -12452,9 +12464,13 @@ function mapContentToSurfingMarkdown(content, options = {}) {
       description = paragraphs[0];
     }
   }
-  const rawTags = Array.isArray(content.metadata?.tags) ? content.metadata.tags : Array.isArray(content.metadata?.keywords) ? content.metadata.keywords : [];
+  const rawTags = Array.isArray(content.metadata?.tags) ? [...content.metadata.tags] : Array.isArray(content.metadata?.keywords) ? [...content.metadata.keywords] : [];
+  if (typeof content.metadata?.subCategory === "string" && content.metadata.subCategory.trim().length > 0) {
+    const subRaw = content.metadata.subCategory.trim();
+    rawTags.push(/^sub-category\s*:/i.test(subRaw) ? subRaw : `sub-category:${subRaw}`);
+  }
   const tags = [
-    ...new Set(rawTags.filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => slugify2(t)))
+    ...new Set(rawTags.filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => normalizeTag(t)))
   ].filter((tag) => tag.length > 0);
   const isoDate = options.publishDate ?? new Date().toISOString().slice(0, 10);
   const firstRefUrl = content.references?.[0]?.url;
@@ -12743,7 +12759,17 @@ async function patchPost(options) {
   if (outcome.changed === 0)
     echoError(`patch: no post bytes changed for ${outcome.slug}`);
   const synced = await syncPost({ postPath: postPath.postPath });
-  const commit = await commitPostPaths(surfdashRoot, outcome.written.map((path) => relative(surfdashRoot, path)), `feat: cover + podcast cross-link for ${outcome.slug} (kk daily patch)`, process.env.SURFDASH_AUTO_PUSH !== "0");
+  const commitPaths = new Set(outcome.written.map((path) => relative(surfdashRoot, path)));
+  for (const locale of PATCH_LOCALES) {
+    const indexMd = localeIndexPath(postPath.postPath, locale);
+    if (!indexMd)
+      continue;
+    const assetsDir = join2(dirname3(indexMd), "assets");
+    if (existsSync2(assetsDir)) {
+      commitPaths.add(relative(surfdashRoot, assetsDir));
+    }
+  }
+  const commit = await commitPostPaths(surfdashRoot, [...commitPaths], `feat: cover + podcast cross-link for ${outcome.slug} (kk daily patch)`, process.env.SURFDASH_AUTO_PUSH !== "0");
   if (!commit.ok)
     return fail(`patch: ${commit.error}`);
   const metadata = {
@@ -12922,6 +12948,7 @@ export {
   main2 as main,
   mapContentToSurfingMarkdown,
   normalizeLocaleFrontmatter,
+  normalizeTag,
   processPublishIO,
   pushPostGit,
   slugify2 as slugify,

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

@@ -6,7 +6,7 @@ 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';
-import { type PatchPostOutcome, patchPostFiles } from './patch';
+import { localeIndexPath, PATCH_LOCALES, type PatchPostOutcome, patchPostFiles } from './patch';
 
 /** Result target name for this plugin. */
 const TARGET = 'surfdash';
@@ -62,6 +62,19 @@ export function slugify(str: string): string {
         .replace(/[\s_]+/g, '-');
 }
 
+/**
+ * Normalizes a raw tag string for frontmatter: preserves `sub-category:<slug>` prefixes
+ * while slugifying the value portion (or ordinary tags).
+ */
+export function normalizeTag(raw: string): string {
+    const match = raw.match(/^\s*sub-category\s*:(.*)$/i);
+    if (match) {
+        const subSlug = slugify(match[1] ?? '');
+        return subSlug ? `sub-category:${subSlug}` : '';
+    }
+    return slugify(raw);
+}
+
 /**
  * Maps Content object into Surfing frontmatter and body per the publish spec.
  */
@@ -86,18 +99,23 @@ export function mapContentToSurfingMarkdown(content: Content, options: MapConten
     }
 
     const rawTags: unknown[] = Array.isArray(content.metadata?.tags)
-        ? content.metadata.tags
+        ? [...content.metadata.tags]
         : Array.isArray(content.metadata?.keywords)
-          ? content.metadata.keywords
+          ? [...content.metadata.keywords]
           : [];
+    if (typeof content.metadata?.subCategory === 'string' && content.metadata.subCategory.trim().length > 0) {
+        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.
+    // 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 = [
         ...new Set(
             rawTags
                 .filter((t): t is string => typeof t === 'string' && t.trim().length > 0)
-                .map((t: string) => slugify(t)),
+                .map((t: string) => normalizeTag(t)),
         ),
     ].filter((tag) => tag.length > 0);
 
@@ -519,9 +537,18 @@ async function patchPost(options: SurfdashPubOptions): Promise<Result> {
     }
     if (outcome.changed === 0) echoError(`patch: no post bytes changed for ${outcome.slug}`);
     const synced = await syncPost({ postPath: postPath.postPath });
+    const commitPaths = new Set(outcome.written.map((path) => relative(surfdashRoot, path)));
+    for (const locale of PATCH_LOCALES) {
+        const indexMd = localeIndexPath(postPath.postPath, locale);
+        if (!indexMd) continue;
+        const assetsDir = join(dirname(indexMd), 'assets');
+        if (existsSync(assetsDir)) {
+            commitPaths.add(relative(surfdashRoot, assetsDir));
+        }
+    }
     const commit = await commitPostPaths(
         surfdashRoot,
-        outcome.written.map((path) => relative(surfdashRoot, path)),
+        [...commitPaths],
         `feat: cover + podcast cross-link for ${outcome.slug} (kk daily patch)`,
         process.env.SURFDASH_AUTO_PUSH !== '0',
     );

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

@@ -137,6 +137,10 @@ export async function patchPostFiles(request: PatchPostRequest): Promise<PatchPo
         if (md !== before) {
             await fs.writeFile(indexMd, md);
             written.push(indexMd);
+            const assetsDir = join(dir, 'assets');
+            if ((await fs.exists(assetsDir)) && !written.includes(join(assetsDir, 'cover.png'))) {
+                written.push(assetsDir);
+            }
             changed += 1;
         }
     }

package/plugins/kk/workflows/feature-verification.yaml

@@ -1,89 +0,0 @@
-# Feature-scoped verification pass (ADR-119, feature D62, task 0872; D63 task
-# 0915 remediation folds the evidence contract into a workflow-owned script).
-#
-# Owns a lifecycle boundary no per-task graph owns: the repo-wide checks whose
-# invariant spans the repository rather than a single task's diff. They run
-# once per feature, deliberately the slow pass; `feature-lifecycle`'s verifying
-# entry invokes this workflow (task 0880 caller wiring), and its verifying→done
-# guard refuses to complete the feature until this pass records PASS (ADR-119
-# consequence: a feature is not done until it passes).
-#
-# Run: spur workflow run feature-verification.yaml --vars '{"featureId":"D63"}'
-#
-# No project-side override is required (task 1185, A33). Since the pass moved into the
-# application (1176 / efd78f058) the bundled definition owns it end to end, so a
-# project-layer copy of this file (plus a rooted port under `.spur/scripts/`) is a
-# leftover — the port was written against an entry export contract that has since
-# changed. Remove the override so this definition applies, or migrate the port to the
-# current app-owned operation `runFeatureVerification` (the generated inline bundle's
-# export). If a stale consumer is still reached, feature-lifecycle's `verifying` entry
-# names it: the override path, the consumer script, the export it requires that the
-# shipped entry no longer provides, and the entry path. Reinstalling or upgrading the
-# plugin cannot supply a retired export — only the two remedies above can.
-#
-# Shape: verify -> done | failed. The onEnter step runs `spur feature verify`
-# (D63 task 0915; script-absorption PR-5 retired the feature-verification-steps
-# plugin script): it
-# resolves this very definition for the verifier identity (name, source path,
-# layer, definition digest), records the RUNNING receipt (run-scoped +
-# feature-latest copies), registers the run-scoped receipt as a run artifact,
-# runs the configured verification command via the safe launch splitter, and
-# completes the receipt PASS/FAIL with the after-pass proof-input digest. A
-# changed tree during the pass records FAIL.
-#
-# Reliability (aligned with task-pipeline / ADR-043): no agent.run nodes; the
-# verification command comes from `vars.verificationCmd` below and is never
-# interpolated through a shell. The always-exit-0 onEnter means missing,
-# corrupt or FAIL evidence routes to `failed` via the guard (fail-closed),
-# never a silent PASS; infrastructure errors exit nonzero and surface.
-"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
-kind: state-machine
-name: feature-verification
-version: "1"
-description: "Feature-scoped verification pass (ADR-119): runs the repo-wide check set once per feature and records a bound PASS/FAIL evidence receipt. Invoked by feature-lifecycle's verifying entry."
-iterationBound: 2
-initialState: verify
-terminalStates:
-  - done
-  - failed
-failureStates:
-  - failed
-vars:
-  featureId: "X"
-  spurBin: "spur"
-  verificationCmd: "bun run spur-check"
-  __runId: ""
-
-states:
-  - id: verify
-    description: >
-      Run the repo-wide check set via `spur feature verify`, which
-      records the bound evidence receipt (verifier identity, checked-input
-      digest, run identity) and the coarse status file, always exit 0 so the
-      transition guard routes missing/corrupt/FAIL to `failed`.
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            mkdir -p .spur/run; $spurBin feature verify "$featureId" --run-id "$__runId" --no-logo || printf 'FAIL feature-verification failed closed — spur feature verify exited nonzero\n' > ".spur/run/$__runId-feature-verification.status"; exit 0
-
-  - id: done
-    description: Terminal — repo-wide checks passed and the receipt is bound.
-
-  - id: failed
-    description: Terminal — repo-wide checks failed or the evidence is missing/corrupt.
-
-transitions:
-  - from: verify
-    to: done
-    description: Repo-wide checks passed — `spur feature verify` completed the receipt with PASS.
-    guard:
-      kind: shell
-      options:
-        command: 'test "$(cat .spur/run/$__runId-feature-verification.status 2>/dev/null)" = PASS'
-  - from: verify
-    to: failed
-    terminalReason: failed-check
-    description: Repo-wide checks failed (or the evidence is missing/corrupt) — stop at failed.
-    guard:
-      kind: always