@gobing-ai/knowledge-kit 0.0.29 → 0.0.30

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     },
     "plugins": [
         {
-            "version": "0.0.29",
+            "version": "0.0.30",
             "name": "kk",
             "source": "./plugins/kk",
             "description": "knowledge-kit — a set of toolkit for knowledge management"

package/dist/index.js

@@ -26530,6 +26530,11 @@ function killSubtree(pid) {
   } catch {}
 }
 async function killProcessTree(pid) {
+  if (process.platform !== "win32") {
+    try {
+      process.kill(-pid, "SIGKILL");
+    } catch {}
+  }
   const sweep = () => {
     for (const child of listChildren(pid)) {
       killSubtree(child);
@@ -26549,7 +26554,8 @@ async function spawnPluginEntryAsync(opts) {
     cwd: opts.cwd,
     env: pluginEntryEnv(opts),
     stdout: "pipe",
-    stderr: "pipe"
+    stderr: "pipe",
+    detached: process.platform !== "win32"
   });
   if (opts.timeoutMs !== undefined) {
     timer = setTimeout(() => {
@@ -27021,41 +27027,70 @@ function aggregate(entries) {
   }
   return { ok: summary.failed === 0, summary, targets: entries };
 }
-async function fanout(content, targets, dispatch) {
-  const entries = [];
-  for (const target of targets) {
-    const started = Date.now();
-    let entry;
-    try {
-      const result = await dispatch(target);
-      const durationMs = Date.now() - started;
-      entry = result.ok ? {
-        target,
-        ok: true,
-        status: "published",
-        ...result.url !== undefined ? { url: result.url } : {},
-        ...result.id !== undefined ? { id: result.id } : {},
-        ...result.metadata !== undefined ? { metadata: result.metadata } : {},
-        durationMs
-      } : {
-        target,
-        ok: false,
-        status: "failed",
-        error: result.error ?? result.message ?? "publish failed",
-        durationMs
-      };
-    } catch (err) {
-      entry = {
-        target,
-        ok: false,
-        status: "failed",
-        error: err instanceof Error ? err.message : String(err),
-        durationMs: Date.now() - started
-      };
-    }
-    entries.push(entry);
+async function dispatchOne(target, dispatch, timeoutMs) {
+  const started = Date.now();
+  try {
+    const result = timeoutMs === undefined ? await dispatch(target) : await withTimeout(dispatch(target), timeoutMs, target);
+    const durationMs = Date.now() - started;
+    return result.ok ? {
+      target,
+      ok: true,
+      status: "published",
+      ...result.url !== undefined ? { url: result.url } : {},
+      ...result.id !== undefined ? { id: result.id } : {},
+      ...result.metadata !== undefined ? { metadata: result.metadata } : {},
+      durationMs
+    } : {
+      target,
+      ok: false,
+      status: "failed",
+      error: result.error ?? result.message ?? "publish failed",
+      durationMs
+    };
+  } catch (err) {
+    return {
+      target,
+      ok: false,
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+      durationMs: Date.now() - started
+    };
   }
-  return aggregate(entries);
+}
+function withTimeout(promise2, timeoutMs, target) {
+  let timer;
+  const budget = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`target '${target}' exceeded its ${timeoutMs}ms budget`)), timeoutMs);
+  });
+  return Promise.race([promise2, budget]).finally(() => clearTimeout(timer));
+}
+async function fanout(content, targets, dispatch, options = {}) {
+  const outcomes = new Map;
+  const runOne = async (target) => {
+    outcomes.set(target, await dispatchOne(target, dispatch, options.timeoutMs));
+  };
+  if (options.mode === "serial") {
+    for (const target of targets)
+      await runOne(target);
+  } else {
+    const serial = new Set(options.serialTargets ?? []);
+    const parallel = targets.filter((target) => !serial.has(target));
+    const solo = targets.filter((target) => serial.has(target));
+    const jobs = options.jobs !== undefined && options.jobs > 0 ? options.jobs : parallel.length;
+    let cursor2 = 0;
+    const worker = async () => {
+      while (cursor2 < parallel.length) {
+        const target = parallel[cursor2++];
+        if (target === undefined)
+          return;
+        await runOne(target);
+      }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(jobs, parallel.length)) }, worker));
+    for (const target of solo)
+      await runOne(target);
+  }
+  return aggregate(targets.map((target) => outcomes.get(target)).filter((entry) => entry !== undefined));
 }
 async function readContent(fs2, path3) {
   if (!await fs2.exists(path3)) {
@@ -27139,10 +27174,14 @@ async function readAggregateResult(fs2, path3) {
 function parseArgs2(argv) {
   const targets = [];
   const pluginsPath = [];
+  const serialTargets = [];
   let contentPath;
   let outPath;
   let retryFromPath;
   let pluginsRoot;
+  let serial = false;
+  let jobs;
+  let targetTimeoutMs;
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--content") {
@@ -27193,6 +27232,34 @@ function parseArgs2(argv) {
         throw new Error("--plugins-path requires a directory path");
       }
       pluginsPath.push(value);
+    } else if (arg === "--serial") {
+      serial = true;
+    } else if (arg === "--jobs") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--jobs requires a positive integer");
+      }
+      const parsed = Number(value);
+      if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`--jobs requires a positive integer, got '${value}'`);
+      }
+      jobs = parsed;
+    } else if (arg === "--serial-target") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--serial-target requires a plugin name");
+      }
+      serialTargets.push(value);
+    } else if (arg === "--target-timeout") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--target-timeout requires milliseconds");
+      }
+      const parsed = Number(value);
+      if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`--target-timeout requires a positive integer in milliseconds, got '${value}'`);
+      }
+      targetTimeoutMs = parsed;
     } else {
       throw new Error(`Unknown argument: ${arg}`);
     }
@@ -27212,7 +27279,11 @@ function parseArgs2(argv) {
     outPath,
     ...retryFromPath !== undefined ? { retryFromPath } : {},
     ...pluginsRoot !== undefined ? { pluginsRoot } : {},
-    ...pluginsPath.length > 0 ? { pluginsPath } : {}
+    ...pluginsPath.length > 0 ? { pluginsPath } : {},
+    ...serial ? { serial } : {},
+    ...jobs !== undefined ? { jobs } : {},
+    ...serialTargets.length > 0 ? { serialTargets } : {},
+    ...targetTimeoutMs !== undefined ? { targetTimeoutMs } : {}
   };
 }
 async function pluginDispatch(target, contentPath, discovery) {
@@ -27315,7 +27386,12 @@ async function runFanout(argv, deps = {}) {
   if (deps.dispatch === undefined && !validateTargets(targets, discovery)) {
     return EXIT_INPUT2;
   }
-  const fresh = await fanout(content, targets, dispatch);
+  const fresh = await fanout(content, targets, dispatch, {
+    ...opts.serial === true ? { mode: "serial" } : {},
+    ...opts.jobs !== undefined ? { jobs: opts.jobs } : {},
+    ...opts.serialTargets !== undefined ? { serialTargets: opts.serialTargets } : {},
+    ...opts.targetTimeoutMs !== undefined ? { timeoutMs: opts.targetTimeoutMs } : {}
+  });
   const result = prior !== undefined ? aggregate([...skipped, ...retainedFailed, ...fresh.targets]) : fresh;
   try {
     await fs2.writeFile(resolve4(opts.outPath), `${JSON.stringify(result, null, 2)}
@@ -27399,7 +27475,7 @@ function withFaninOptions(cmd) {
   return cmd.option("--in <path>", "Input Doc[] JSON file (repeatable)", collectRepeatable, []).option("--source <plugin>:<file>", "Ingestion source to spawn concurrently: plugin name and its input file (repeatable)", collectRepeatable, []).option("--source-timeout <ms>", "Per-source timeout in milliseconds (default 1800000)").option("--source-timeout-override <plugin>:<ms>", "Per-source timeout override for one named --source plugin, e.g. horizon-ingest:2700000 (repeatable; wins over --source-timeout/default)", collectRepeatable, []).requiredOption("--out <path>", "Output merged Doc[] JSON file path").option("--plugins-root <dir>", "Exclusive root containing plugins (isolation/tests only)").option("--plugins-path <dir>", "Extra plugin root to union with defaults (repeatable)", collectRepeatable, []);
 }
 function withFanoutOptions(cmd) {
-  return cmd.requiredOption("--content <path>", "Source ContentSchema JSON file path").option("--target <plugin>", "Target publish plugin name (repeatable)", collectRepeatable, []).requiredOption("--out <path>", "Aggregate Result JSON file path").option("--retry-from <path>", "Prior Result JSON file to retry only previously failed targets").option("--plugins-root <dir>", "Exclusive root containing plugins (isolation/tests only)").option("--plugins-path <dir>", "Extra plugin root to union with defaults (repeatable)", collectRepeatable, []);
+  return cmd.requiredOption("--content <path>", "Source ContentSchema JSON file path").option("--target <plugin>", "Target publish plugin name (repeatable)", collectRepeatable, []).requiredOption("--out <path>", "Aggregate Result JSON file path").option("--retry-from <path>", "Prior Result JSON file to retry only previously failed targets").option("--serial", "Dispatch the parallel batch one target at a time (pre-2026-10-03 behaviour)").option("--jobs <n>", "Concurrent-start bound for the parallel batch (default: every target at once)").option("--serial-target <plugin>", "Target kept out of the parallel batch and run alone afterwards, e.g. a headed browser channel or a shared checkout (repeatable)", collectRepeatable, []).option("--target-timeout <ms>", "Per-target wall-clock budget; an overrun is recorded failed and siblings continue").option("--plugins-root <dir>", "Exclusive root containing plugins (isolation/tests only)").option("--plugins-path <dir>", "Extra plugin root to union with defaults (repeatable)", collectRepeatable, []);
 }
 function registerExecutorCommand(program2) {
   const executor = program2.command("executor").description("Run knowledge-kit plugin steps (invoke, fan-in, fan-out)");

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/knowledge-kit",
-    "version": "0.0.29",
+    "version": "0.0.30",
     "description": "An ingest → create → publish content pipeline CLI (Bun).",
     "repository": {
         "type": "git",

package/plugins/generations/daily-article-gen/dist/index.js

@@ -22035,17 +22035,15 @@ ${metaLine ? `${metaLine}
 
 ` : ""}${stripScaffold(doc2.body ?? "").trim()}`;
 }
-function episodeTitle(docs, date6) {
-  const lead = docs[0]?.title?.trim() ?? "";
-  const theme = lead !== "" ? lead : "\u5DE5\u5177\u3001\u8BBA\u6587\u4E0E\u5B9E\u8DF5";
-  return `AI \u4E71\u7096\uFF5C${theme} \xB7 ${date6}`;
+function episodeTitle(date6) {
+  return `AI \u4E71\u7096 \xB7 ${date6}`;
 }
 function renderDailyArticle(docs, date6) {
   const items = docs.map(renderDoc).join(`
 
 `);
   const intro = docs.length > 0 ? `\u300CAI \u4E71\u7096\u300D\u662F\u300C\u54B8\u8BDD\u54B8\u8BF4\u300D\u7684 AI \u6280\u672F\u5206\u4EAB\u680F\u76EE\uFF1A\u5DE5\u5177\u3001\u8BBA\u6587\u4E0E\u5B9E\u8DF5\u968F\u804A\u3002\u672C\u671F\u5171 ${docs.length} \u6761\u5185\u5BB9\uFF0C\u5747\u9644\u53EF\u70B9\u51FB\u6765\u6E90\u94FE\u63A5\u3002` : "\u300CAI \u4E71\u7096\u300D\u662F\u300C\u54B8\u8BDD\u54B8\u8BF4\u300D\u7684 AI \u6280\u672F\u5206\u4EAB\u680F\u76EE\uFF1A\u5DE5\u5177\u3001\u8BBA\u6587\u4E0E\u5B9E\u8DF5\u968F\u804A\u3002\u672C\u671F\u6CA1\u6709\u8DB3\u591F\u624E\u5B9E\u7684\u53EF\u804A\u5185\u5BB9\u3002";
-  return `# ${episodeTitle(docs, date6)}
+  return `# ${episodeTitle(date6)}
 
 ${intro}
 
@@ -22061,8 +22059,24 @@ function tagsFor(docs) {
   return [AI_NEWS_TAG, ...existing.filter((t) => t !== AI_NEWS_TAG)];
 }
 var LEADING_H1_RE = /^#(?!#)\s*[^\n]+\n+/.source;
+var NOTE_EXCLUDED_RE = /\u672A\u5199\u5165[\uFF1A:](.*)/g;
+var HEX_ID_RE = /(?:[a-zA-Z0-9_-]+:)?[0-9a-f]{16}/g;
+function excludedIdsFromNote(body) {
+  const ids = new Set;
+  if (!body)
+    return ids;
+  for (const note of body.matchAll(NOTE_EXCLUDED_RE)) {
+    for (const id of (note[1] ?? "").matchAll(HEX_ID_RE)) {
+      ids.add(id[0]);
+      const colon = id[0].indexOf(":");
+      if (colon !== -1)
+        ids.add(id[0].slice(colon + 1));
+    }
+  }
+  return ids;
+}
 function docsToContent(docs, date6, bodyOverride) {
-  const title = episodeTitle(docs, date6);
+  const title = episodeTitle(date6);
   let body = renderDailyArticle(docs, date6);
   if (bodyOverride) {
     const stripped = stripScaffold(bodyOverride.trim()).trim().replace(new RegExp(LEADING_H1_RE), "");
@@ -22096,7 +22110,9 @@ async function processGeneratorIO(inputPath, outputPath) {
     if (bodyOverride.trim() === "")
       bodyOverride = undefined;
   }
-  const content = docsToContent(docs, date6, bodyOverride);
+  const excluded = excludedIdsFromNote(bodyOverride);
+  const kept = excluded.size === 0 ? docs : docs.filter((d) => !excluded.has(d.id) && !(d.id.includes(":") && excluded.has(d.id.slice(d.id.indexOf(":") + 1))));
+  const content = docsToContent(kept, date6, bodyOverride);
   const fs = createNodeFileSystem();
   const outDir = dirname2(outputPath);
   if (outDir && outDir !== ".")
@@ -22132,6 +22148,7 @@ export {
   renderDailyArticle,
   processGeneratorIO,
   main2 as main,
+  excludedIdsFromNote,
   episodeTitle,
   docsToContent
 };

package/plugins/generations/daily-article-gen/src/index.ts

@@ -103,16 +103,14 @@ function renderDoc(doc: Doc, index: number): string {
 }
 
 /**
- * Episode title for the 「AI 乱炖」 column (task 0189 R1/R4): `AI 乱炖｜<本期实际技术主题> · YYYY-MM-DD`.
- * The deterministic proxy for 本期实际技术主题 is the lead plan item's title — the same doc the
- * cover brief and XHS cards already treat as the episode's lead story. Pure function so the
- * agent-written and template article paths, ID3, RSS and show notes all derive one identical
- * title; never re-introduces the retired news-bulletin positioning (task 0189 R4).
+ * Episode title for the 「AI 乱炖」 column: fixed `AI 乱炖 · YYYY-MM-DD` (2026-10-02 operator
+ * simplification, superseding the 0189 R1/R4 `AI 乱炖｜<lead item> · date` pattern). The date
+ * alone identifies the episode; the day's stories live in the show notes, cards and post body.
+ * Pure function so the agent-written and template article paths, ID3, RSS and show notes all
+ * derive one identical title.
  */
-export function episodeTitle(docs: Doc[], date: string): string {
-    const lead = docs[0]?.title?.trim() ?? '';
-    const theme = lead !== '' ? lead : '工具、论文与实践';
-    return `AI 乱炖｜${theme} · ${date}`;
+export function episodeTitle(date: string): string {
+    return `AI 乱炖 · ${date}`;
 }
 
 /** Render the article markdown for a merged Doc[] (pure — exported for tests). */
@@ -122,7 +120,7 @@ export function renderDailyArticle(docs: Doc[], date: string): string {
         docs.length > 0
             ? `「AI 乱炖」是「咸话咸说」的 AI 技术分享栏目：工具、论文与实践随聊。本期共 ${docs.length} 条内容，均附可点击来源链接。`
             : '「AI 乱炖」是「咸话咸说」的 AI 技术分享栏目：工具、论文与实践随聊。本期没有足够扎实的可聊内容。';
-    return `# ${episodeTitle(docs, date)}\n\n${intro}\n\n${items}\n`;
+    return `# ${episodeTitle(date)}\n\n${intro}\n\n${items}\n`;
 }
 
 /** Single-source daily tag: stamped on every Content this generator emits (task 0119). */
@@ -140,9 +138,27 @@ function tagsFor(docs: Doc[]): string[] {
 /** A leading H1 line — agent bodies used to carry their own title; the canonical title is computed (task 0189 R4). */
 const LEADING_H1_RE = /^#(?!#)\s*[^\n]+\n+/.source;
 
+/** ids the article-write note marks as dropped on the topic boundary, e.g. 「…未写入：<id>（原因）、<id>（原因）」. */
+const NOTE_EXCLUDED_RE = /未写入[：:](.*)/g;
+const HEX_ID_RE = /(?:[a-zA-Z0-9_-]+:)?[0-9a-f]{16}/g;
+
+/** Parse the boundary-note ids out of an article body so references/metadata never cite excluded docs (judge finding 2026-10-02). */
+export function excludedIdsFromNote(body: string | undefined): Set<string> {
+    const ids = new Set<string>();
+    if (!body) return ids;
+    for (const note of body.matchAll(NOTE_EXCLUDED_RE)) {
+        for (const id of (note[1] ?? '').matchAll(HEX_ID_RE)) {
+            ids.add(id[0]);
+            const colon = id[0].indexOf(':');
+            if (colon !== -1) ids.add(id[0].slice(colon + 1));
+        }
+    }
+    return ids;
+}
+
 /** Build the article Content from a merged Doc[]; `bodyOverride` replaces the mechanical render (agent-written prose), still scaffold-stripped as a safety net. */
 export function docsToContent(docs: Doc[], date: string, bodyOverride?: string): Content {
-    const title = episodeTitle(docs, date);
+    const title = episodeTitle(date);
     let body = renderDailyArticle(docs, date);
     if (bodyOverride) {
         // The canonical episode title is computed from the lead item; a leading H1 the agent may
@@ -174,7 +190,15 @@ export async function processGeneratorIO(inputPath: string, outputPath: string):
         bodyOverride = await Bun.file(bodyFile).text();
         if (bodyOverride.trim() === '') bodyOverride = undefined;
     }
-    const content = docsToContent(docs, date, bodyOverride);
+    const excluded = excludedIdsFromNote(bodyOverride);
+    const kept =
+        excluded.size === 0
+            ? docs
+            : docs.filter(
+                  (d) =>
+                      !excluded.has(d.id) && !(d.id.includes(':') && excluded.has(d.id.slice(d.id.indexOf(':') + 1))),
+              );
+    const content = docsToContent(kept, date, bodyOverride);
     const fs = createNodeFileSystem();
     const outDir = dirname(outputPath);
     if (outDir && outDir !== '.') await fs.ensureDir(outDir);

package/plugins/generations/dailynews-gen/dist/index.js

@@ -22344,11 +22344,16 @@ var ScriptPlanItemSchema = exports_external.object({
   lead: exports_external.string().min(1),
   insight: exports_external.string().min(1)
 });
+var ScriptPlanExclusionSchema = exports_external.object({
+  id: exports_external.string().min(1),
+  reason: exports_external.string().min(1)
+});
 var ScriptPlanSchema = exports_external.object({
   version: exports_external.literal(1),
   intro: exports_external.string().min(1),
   outro: exports_external.string().min(1),
-  items: exports_external.array(ScriptPlanItemSchema)
+  items: exports_external.array(ScriptPlanItemSchema),
+  excluded: exports_external.array(ScriptPlanExclusionSchema).optional()
 });
 var StyleContractSchema = exports_external.object({
   caps: exports_external.object({
@@ -22386,8 +22391,15 @@ function validateScriptPlan(plan, docs, style) {
       errors5.push({ itemId: item.id, rule: "unknown-id" });
   }
   const plannedIds = new Set(valid.items.map((item) => item.id));
+  const excludedIds = new Set((valid.excluded ?? []).map((ex) => ex.id));
+  for (const ex of valid.excluded ?? []) {
+    if (!docIds.has(ex.id))
+      errors5.push({ itemId: ex.id, rule: "unknown-id" });
+    if (plannedIds.has(ex.id))
+      errors5.push({ itemId: ex.id, rule: "conflict-id" });
+  }
   for (const doc2 of docs) {
-    if (!plannedIds.has(doc2.id))
+    if (!plannedIds.has(doc2.id) && !excludedIds.has(doc2.id))
       errors5.push({ itemId: doc2.id, rule: "missing-item" });
   }
   if (valid.intro.length > style.caps.intro)
@@ -22493,6 +22505,11 @@ async function processGeneratorIO(inputPath, outputPath, options) {
   }
   const isZh = (options?.language || "zh").toLowerCase() === "zh";
   const planOutcome = isZh ? await resolveScriptPlan(fs, docs) : { scriptSource: "template", scriptPlanErrors: [] };
+  const excludedIds = new Set(planOutcome.scriptPlan?.excluded?.map((ex) => ex.id) ?? []);
+  if (excludedIds.size > 0) {
+    echoError(`dailynews-gen: topic boundary excludes ${excludedIds.size} doc(s): ${[...excludedIds].join(", ")}`);
+    docs = docs.filter((doc2) => !excludedIds.has(doc2.id));
+  }
   const date6 = options?.date ?? broadcastDateFromEnv(process.env.DAILYNEWS_DATE);
   const script = buildNewsVoiceScript(docs, { ...options, date: date6, scriptPlan: planOutcome.scriptPlan });
   const yamlBody = formatVoiceScriptToYaml(script);

package/plugins/generations/dailynews-gen/src/index.ts

@@ -127,6 +127,13 @@ export async function processGeneratorIO(
     const planOutcome = isZh
         ? await resolveScriptPlan(fs, docs)
         : { scriptSource: 'template' as const, scriptPlanErrors: [] as ScriptPlanError[] };
+    // Topic boundary (task 0189): docs the plan declares excluded are not spoken, not counted,
+    // and not referenced — title, storyCount, and references must match what is actually said.
+    const excludedIds = new Set(planOutcome.scriptPlan?.excluded?.map((ex) => ex.id) ?? []);
+    if (excludedIds.size > 0) {
+        echoError(`dailynews-gen: topic boundary excludes ${excludedIds.size} doc(s): ${[...excludedIds].join(', ')}`);
+        docs = docs.filter((doc) => !excludedIds.has(doc.id));
+    }
     // Explicit option wins; else DAILYNEWS_DATE (workflow backfill/retry); else the builder's now.
     const date = options?.date ?? broadcastDateFromEnv(process.env.DAILYNEWS_DATE);
     const script = buildNewsVoiceScript(docs, { ...options, date, scriptPlan: planOutcome.scriptPlan });

package/plugins/generations/dailynews-gen/src/script-plan.ts

@@ -12,6 +12,12 @@ export interface ScriptPlan {
     intro: string;
     outro: string;
     items: { id: string; lead: string; insight: string }[];
+    /**
+     * Docs deliberately not spoken (topic-boundary exclusions, task 0189). An id here is
+     * exempt from `missing-item`; listing an id in both `items` and `excluded` is a
+     * `conflict-id` error, and an unknown id is `unknown-id` like any plan item.
+     */
+    excluded?: { id: string; reason: string }[];
 }
 
 /**
@@ -41,11 +47,17 @@ const ScriptPlanItemSchema = z.object({
     insight: z.string().min(1),
 });
 
+const ScriptPlanExclusionSchema = z.object({
+    id: z.string().min(1),
+    reason: z.string().min(1),
+});
+
 const ScriptPlanSchema = z.object({
     version: z.literal(1),
     intro: z.string().min(1),
     outro: z.string().min(1),
     items: z.array(ScriptPlanItemSchema),
+    excluded: z.array(ScriptPlanExclusionSchema).optional(),
 });
 
 const StyleContractSchema = z.object({
@@ -86,8 +98,9 @@ export function parseStyleContract(markdown: string): StyleContract {
  * one warn line names every violation, so a rejected plan is diagnosable in one read:
  *
  * - `schema`: wrong shape or version (`itemId: episode`)
- * - `unknown-id`: a plan item id that is not a doc
- * - `missing-item`: a doc with no plan item
+ * - `unknown-id`: a plan item (or exclusion) id that is not a doc
+ * - `missing-item`: a doc with no plan item and no exclusion
+ * - `conflict-id`: an id listed in both `items` and `excluded`
  * - `cap:<field>`: a field over its cap (`intro`/`outro` report `itemId: episode`)
  * - `banned:<phrase>`: a field containing a banned phrase
  * - `duplicate-insight`: the same insight text on two items in one episode
@@ -107,8 +120,13 @@ export function validateScriptPlan(plan: unknown, docs: Doc[], style: StyleContr
         if (!docIds.has(item.id)) errors.push({ itemId: item.id, rule: 'unknown-id' });
     }
     const plannedIds = new Set(valid.items.map((item) => item.id));
+    const excludedIds = new Set((valid.excluded ?? []).map((ex) => ex.id));
+    for (const ex of valid.excluded ?? []) {
+        if (!docIds.has(ex.id)) errors.push({ itemId: ex.id, rule: 'unknown-id' });
+        if (plannedIds.has(ex.id)) errors.push({ itemId: ex.id, rule: 'conflict-id' });
+    }
     for (const doc of docs) {
-        if (!plannedIds.has(doc.id)) errors.push({ itemId: doc.id, rule: 'missing-item' });
+        if (!plannedIds.has(doc.id) && !excludedIds.has(doc.id)) errors.push({ itemId: doc.id, rule: 'missing-item' });
     }
 
     if (valid.intro.length > style.caps.intro) errors.push({ itemId: 'episode', rule: 'cap:intro' });

package/plugins/generations/episode-plan-gen/dist/index.js

@@ -22430,7 +22430,8 @@ var DEFAULT_FILTER_CONFIG = {
   minQuality: 2,
   minImportance: 3,
   minUrgency: 2,
-  minImpact: 1
+  minImpact: 1,
+  minEpisodeItems: 8
 };
 function parseFilterThreshold(raw, name, fallback) {
   if (raw === undefined || raw.trim() === "")
@@ -22443,6 +22444,17 @@ function parseFilterThreshold(raw, name, fallback) {
     throw new Error(`${name}=${parsed} is outside 0\u20135 (fail loud, no clamping)`);
   return parsed;
 }
+function parseFloorCount(raw, name, fallback) {
+  if (raw === undefined || raw.trim() === "")
+    return fallback;
+  const value = raw.trim();
+  if (!/^\d+$/.test(value))
+    throw new Error(`${name}='${raw}' is not a positive integer (fail loud, no clamping)`);
+  const parsed = Number.parseInt(value, 10);
+  if (parsed < 1)
+    throw new Error(`${name}=${parsed} must be >= 1 (a 0 floor disables the gate \u2014 drop the env instead)`);
+  return parsed;
+}
 function parseFilterCategories(raw) {
   if (raw === undefined || raw.trim() === "")
     return [...DEFAULT_FILTER_CONFIG.categories];
@@ -22460,7 +22472,8 @@ function filterConfigFromEnv(env2 = process.env) {
     minQuality: parseFilterThreshold(env2.QC_MIN_QUALITY, "QC_MIN_QUALITY", DEFAULT_FILTER_CONFIG.minQuality),
     minImportance: parseFilterThreshold(env2.QC_MIN_IMPORTANCE, "QC_MIN_IMPORTANCE", DEFAULT_FILTER_CONFIG.minImportance),
     minUrgency: parseFilterThreshold(env2.QC_MIN_URGENCY, "QC_MIN_URGENCY", DEFAULT_FILTER_CONFIG.minUrgency),
-    minImpact: parseFilterThreshold(env2.QC_MIN_IMPACT, "QC_MIN_IMPACT", DEFAULT_FILTER_CONFIG.minImpact)
+    minImpact: parseFilterThreshold(env2.QC_MIN_IMPACT, "QC_MIN_IMPACT", DEFAULT_FILTER_CONFIG.minImpact),
+    minEpisodeItems: parseFloorCount(env2.QC_MIN_EPISODE_ITEMS, "QC_MIN_EPISODE_ITEMS", DEFAULT_FILTER_CONFIG.minEpisodeItems)
   };
 }
 function requireAnnotation(doc2) {
@@ -22505,6 +22518,39 @@ function filterAnnotated(docs, config3) {
   }
   return { kept, rejected };
 }
+function importanceOf(doc2) {
+  const scores = asRecord(asRecord(doc2.metadata).scores);
+  return typeof scores.importance === "number" ? scores.importance : 0;
+}
+function planScoreOf(doc2) {
+  const value = asRecord(doc2.metadata).planScore;
+  return typeof value === "number" ? value : 0;
+}
+function backfillToFloor(kept, rejected, config3) {
+  if (kept.length >= config3.minEpisodeItems)
+    return { kept, rejected, admitted: [] };
+  const eligible = rejected.map((entry, index) => ({ entry, index })).filter(({ entry }) => entry.reasons.length > 0 && entry.reasons.every((r) => r.startsWith("importance:")));
+  eligible.sort((a, b) => {
+    const byImportance = importanceOf(b.entry.doc) - importanceOf(a.entry.doc);
+    if (byImportance !== 0)
+      return byImportance;
+    const byPlanScore = planScoreOf(b.entry.doc) - planScoreOf(a.entry.doc);
+    if (byPlanScore !== 0)
+      return byPlanScore;
+    return a.index - b.index;
+  });
+  const taken = eligible.slice(0, config3.minEpisodeItems - kept.length);
+  const takenIds = new Set(taken.map(({ entry }) => entry.doc.id));
+  const admitted = taken.map(({ entry }) => ({
+    ...entry.doc,
+    metadata: { ...asRecord(entry.doc.metadata), backfilled: true }
+  }));
+  return {
+    kept: [...kept, ...admitted],
+    rejected: rejected.filter((entry) => !takenIds.has(entry.doc.id)),
+    admitted
+  };
+}
 function rejectedOutPath(outputPath) {
   return outputPath.endsWith(".json") ? `${outputPath.slice(0, -".json".length)}.rejected.json` : `${outputPath}.rejected.json`;
 }
@@ -22530,9 +22576,13 @@ async function processFilterIO(inputPath, outputPath) {
   const config3 = filterConfigFromEnv();
   const docs = DocListSchema.parse(await readJsonFile(inputPath));
   const { kept, rejected } = filterAnnotated(docs, config3);
-  const content = planContent(kept, resolvePlanDate());
+  const filled = backfillToFloor(kept, rejected, config3);
+  if (filled.admitted.length > 0) {
+    echoError(`episode floor backfill: admitted ${filled.admitted.length} importance-only reject(s) to reach ${config3.minEpisodeItems} items (${filled.admitted.map((d) => d.id).join(", ")})`);
+  }
+  const content = planContent(filled.kept, resolvePlanDate());
   await atomicWrite(outputPath, content);
-  await atomicWrite(rejectedOutPath(outputPath), { rejected, config: config3, total: docs.length });
+  await atomicWrite(rejectedOutPath(outputPath), { rejected: filled.rejected, config: config3, total: docs.length });
   return content;
 }
 async function main2() {
@@ -22581,5 +22631,6 @@ export {
   docsToContent,
   cleanBody,
   classifyCategory,
+  backfillToFloor,
   DEFAULT_FILTER_CONFIG
 };