feat(linkedin-studio): N11 — serie-destillat + skjelett-sjekk + specifics-bank bruks-logging [skip-docs]

Every long-form gate agent sees ONE edition, so «the reader has heard this
before» was structurally invisible — and the specifics-bank dedupe actively
encouraged re-surfacing the same material. At series cadence that is the
fastest-growing defect class. N11 makes it visible BEFORE the skeleton is
approved, at two grains:

- Series grain — new scripts/editions package: each locked edition's spent
  anecdotes/arguments/hooks are written to <serie>/linkedin/series-distillate.json
  at Step 8 lock (distil-append), and the next skeleton is checked against it at
  Step 2.5 (distil-check) with the finding folded into the annotation gate the
  operator already reads. Advisory, never blocking: a deliberate callback is a
  legitimate move, an unnoticed retread is not.
- Material grain — specifics-bank usedIn log: record-usage stamps «used in
  edition NN» on the specifics an edition actually consumed (read from the bound
  slot-map, so abstrakt/ekstern stamp nothing). At lock, so it means published;
  idempotent under a pivot re-lock. Additive-optional, schema stays v1.

Placement deviates from the plan text (${DATA}) after premise-verification:
per-series state belongs in the series root beside edition-state.json, where
Step 0 already resolves the path and no slug→path map is needed. Operator
approved. The distillate module also lands in scripts/editions now rather than
at N12, since the AC required a testable roundtrip and N12 planned that package
anyway — N12 extends it instead of creating it.

Similarity is character-trigram Jaccard, not word overlap: the plugin is
language-general and inflection (migrere/migreringen) breaks word tokens.
Calibrated on real paraphrase pairs — retellings 0.44-0.55, unrelated 0.04-0.06,
same-topic-different-story 0.24 — so the default threshold sits in the gap at
0.40. Word-Jaccard scored a shortened hook paraphrase at 0.11.

TDD (Iron Law): tests written first and verified red before implementation, for
both the new package and the bank logging.

Suites: editions 27/0 (new suite line + guard, floor 27) · specifics-bank
28 -> 45 · test-runner 163 -> 173 (Section 16r: 9 unconditional greps +
non-vacuity self-test; anti-erosion floor 146 -> 155) · trends 300/0 ·
brain 134/0 · hooks 140/0 · tests 35/0 · render 60/0. tsc --noEmit clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QxvWAjte7vPcF79QeSRvRJ

scripts/editions/src/cli.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * CLI for the series distillate (N11 — serie-nivå-vern).
+ *
+ *   node --import tsx src/cli.ts distil-append --distillate <path> --series <slug> --extract <extract.json>
+ *   node --import tsx src/cli.ts distil-check  --distillate <path> --skeleton <skeleton.json>
+ *                                              [--threshold <0..1>] [--json]
+ *
+ * `distil-append` runs at Step 8 lock: the command layer writes the AI extract
+ * (the anecdotes/arguments/hooks the edition actually spent) to a JSON file, and
+ * this folds it in deterministically. `distil-check` runs at Step 2.5, before
+ * prose, and reports re-use into the annotation gate.
+ *
+ * Exit code: 0 on success (INCLUDING a REUSE verdict — the check is advisory by
+ * design, unlike the binding gate's BLOCK), 2 on usage error.
+ */
+
+import { readFileSync } from "node:fs";
+
+import {
+  DEFAULT_THRESHOLD,
+  appendEntry,
+  checkSkeleton,
+  loadDistillate,
+  saveDistillate,
+} from "./distillate.js";
+import type { DistillateEntry, SkeletonCandidate } from "./types.js";
+
+function parseFlags(args: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        out[key] = "true";
+      } else {
+        out[key] = next;
+        i++;
+      }
+    }
+  }
+  return out;
+}
+
+function usage(msg: string): never {
+  console.error(`error: ${msg}`);
+  console.error(
+    "usage:\n" +
+      "  distil-append --distillate <path> --series <slug> --extract <extract.json>\n" +
+      "  distil-check  --distillate <path> --skeleton <skeleton.json> [--threshold <0..1>] [--json]",
+  );
+  process.exit(2);
+}
+
+/** A flag that was given a real value (not absent, not a bare boolean flag). */
+function value(flags: Record<string, string>, key: string): string | undefined {
+  const v = flags[key];
+  return v === undefined || v === "true" ? undefined : v;
+}
+
+function readJson(path: string, what: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    usage(`could not read ${what} at ${path}: ${(err as Error).message}`);
+  }
+}
+
+function stringList(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((x): x is string => typeof x === "string" && x.trim().length > 0);
+}
+
+/** Validate the AI extract at the edge — a malformed extract must not become a silent empty entry. */
+function toEntry(raw: unknown): DistillateEntry {
+  const o = (raw ?? {}) as Record<string, unknown>;
+  for (const field of ["editionId", "title", "lockedAt"]) {
+    const v = o[field];
+    if (typeof v !== "string" || v.trim().length === 0) {
+      usage(`extract is missing required string field: ${field}`);
+    }
+  }
+  return {
+    editionId: o.editionId as string,
+    title: o.title as string,
+    lockedAt: o.lockedAt as string,
+    anecdotes: stringList(o.anecdotes),
+    arguments: stringList(o.arguments),
+    hooks: stringList(o.hooks),
+  };
+}
+
+function main(): void {
+  const [command, ...rest] = process.argv.slice(2);
+  const flags = parseFlags(rest);
+  const distillatePath = value(flags, "distillate");
+  const asJson = flags.json === "true";
+
+  if (command === "distil-append") {
+    if (!distillatePath) usage("distil-append needs --distillate <path>");
+    const series = value(flags, "series");
+    if (!series) usage("distil-append needs --series <slug>");
+    const extractPath = value(flags, "extract");
+    if (!extractPath) usage("distil-append needs --extract <extract.json>");
+
+    const entry = toEntry(readJson(extractPath, "extract"));
+    const res = appendEntry(loadDistillate(distillatePath, series), entry);
+    saveDistillate(distillatePath, res.distillate);
+
+    const units = entry.anecdotes.length + entry.arguments.length + entry.hooks.length;
+    console.log(
+      `${res.replaced ? "Replaced" : "Appended"} edition ${entry.editionId} (${units} narrative unit(s)) ` +
+        `in ${distillatePath} — ${res.distillate.editions.length} edition(s) in the series distillate`,
+    );
+    return;
+  }
+
+  if (command === "distil-check") {
+    if (!distillatePath) usage("distil-check needs --distillate <path>");
+    const skeletonPath = value(flags, "skeleton");
+    if (!skeletonPath) usage("distil-check needs --skeleton <skeleton.json>");
+
+    const rawThreshold = value(flags, "threshold");
+    let threshold = DEFAULT_THRESHOLD;
+    if (rawThreshold !== undefined) {
+      threshold = Number(rawThreshold);
+      if (!Number.isFinite(threshold) || threshold <= 0 || threshold > 1) {
+        usage("--threshold must be a number in (0, 1]");
+      }
+    }
+
+    const candidate = (readJson(skeletonPath, "skeleton") ?? {}) as SkeletonCandidate;
+    const report = checkSkeleton(loadDistillate(distillatePath, value(flags, "series") ?? ""), candidate, {
+      threshold,
+    });
+
+    if (asJson) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+
+    if (report.verdict === "CLEAR") {
+      console.log(
+        `CLEAR — nothing in this skeleton resembles the ${report.comparedAgainst} locked edition(s) ` +
+          `(threshold ${report.threshold}).`,
+      );
+      return;
+    }
+    console.log(
+      `REUSE — ${report.hits.length} unit(s) resemble earlier editions (threshold ${report.threshold}, ` +
+        `${report.comparedAgainst} edition(s) checked):`,
+    );
+    for (const hit of report.hits) {
+      console.log(`\n  · ${hit.kind} — ${(hit.score * 100).toFixed(0)}% like edition ${hit.editionId}`);
+      console.log(`    new:  ${hit.candidate}`);
+      console.log(`    then: ${hit.matched}`);
+    }
+    console.log("\nAdvisory: a deliberate callback is fine — an unnoticed retread is not.");
+    return;
+  }
+
+  usage(command ? `unknown command: ${command}` : "no command given");
+}
+
+main();

scripts/editions/src/distillate.ts

@@ -0,0 +1,179 @@
+/**
+ * Deterministic store + reuse check for the series distillate (N11 — C-5).
+ *
+ * Pure where it matters: normalization, similarity and the skeleton check are
+ * side-effect-free and fully testable. Only load/save touch the filesystem.
+ *
+ * Similarity is CHARACTER TRIGRAM Jaccard, not word overlap. The plugin is
+ * language-general, and the languages it is actually used in are inflection-
+ * heavy: "migrere"/"migreringen" and "pipeline"/"pipelinen" are the same unit to
+ * a reader but different word tokens. Calibrated against real paraphrase pairs
+ * (see tests/distillate.test.ts): retellings score 0.44–0.55, unrelated material
+ * 0.04–0.06, and same-topic-different-story 0.24 — so the default threshold sits
+ * in the gap at 0.40. Word-Jaccard scored a shortened hook paraphrase at 0.11
+ * and would have let it through.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { SCHEMA_VERSION } from "./types.js";
+import type {
+  DistillateEntry,
+  NarrativeKind,
+  ReuseHit,
+  ReuseReport,
+  SeriesDistillate,
+  SkeletonCandidate,
+} from "./types.js";
+
+export { SCHEMA_VERSION } from "./types.js";
+
+/** Similarity at or above this counts as re-use. Empirically calibrated — see the header. */
+export const DEFAULT_THRESHOLD = 0.4;
+
+const KINDS: NarrativeKind[] = ["anecdote", "argument", "hook"];
+
+/** Lowercase, strip everything that is not a letter or digit, collapse whitespace. */
+export function normalizeUnit(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+}
+
+/** Character trigrams over the normalized text, space-padded so short units still overlap. */
+function trigrams(text: string): Set<string> {
+  const normalized = normalizeUnit(text);
+  if (normalized.length === 0) return new Set();
+  const padded = ` ${normalized} `;
+  const out = new Set<string>();
+  for (let i = 0; i + 3 <= padded.length; i++) out.add(padded.slice(i, i + 3));
+  return out;
+}
+
+/** Jaccard over character trigrams: 1 = identical after normalization, 0 = nothing shared. */
+export function similarity(a: string, b: string): number {
+  const A = trigrams(a);
+  const B = trigrams(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let intersection = 0;
+  for (const gram of A) if (B.has(gram)) intersection++;
+  return intersection / (A.size + B.size - intersection);
+}
+
+export function emptyDistillate(series: string): SeriesDistillate {
+  return { schemaVersion: SCHEMA_VERSION, series, editions: [] };
+}
+
+/** Read the distillate; a missing file is an empty one (a series' first edition is not an error). */
+export function loadDistillate(path: string, series: string): SeriesDistillate {
+  if (!existsSync(path)) return emptyDistillate(series);
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<SeriesDistillate>;
+  return {
+    schemaVersion: parsed.schemaVersion ?? SCHEMA_VERSION,
+    series: parsed.series ?? series,
+    editions: Array.isArray(parsed.editions) ? parsed.editions : [],
+  };
+}
+
+/** Write as pretty JSON with a trailing newline, creating the parent dir if needed. */
+export function saveDistillate(path: string, distillate: SeriesDistillate): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(distillate, null, 2) + "\n", "utf8");
+}
+
+export interface AppendResult {
+  distillate: SeriesDistillate;
+  /** true iff the edition was new. */
+  appended: boolean;
+  /** true iff an existing edition was overwritten in place (a pivot re-lock). */
+  replaced: boolean;
+}
+
+/**
+ * Fold one locked edition into the distillate. An edition already present is
+ * REPLACED in place, never duplicated: `/linkedin:pivot` re-opens and re-locks
+ * the same edition, and the reader still only ever met it once.
+ */
+export function appendEntry(distillate: SeriesDistillate, entry: DistillateEntry): AppendResult {
+  const stored: DistillateEntry = {
+    editionId: entry.editionId,
+    title: entry.title,
+    lockedAt: entry.lockedAt,
+    anecdotes: [...entry.anecdotes],
+    arguments: [...entry.arguments],
+    hooks: [...entry.hooks],
+  };
+  const at = distillate.editions.findIndex((e) => e.editionId === entry.editionId);
+  if (at >= 0) {
+    distillate.editions[at] = stored;
+    return { distillate, appended: false, replaced: true };
+  }
+  distillate.editions.push(stored);
+  return { distillate, appended: true, replaced: false };
+}
+
+function unitsOf(entry: DistillateEntry, kind: NarrativeKind): string[] {
+  if (kind === "anecdote") return entry.anecdotes;
+  if (kind === "argument") return entry.arguments;
+  return entry.hooks;
+}
+
+function candidateUnits(candidate: SkeletonCandidate, kind: NarrativeKind): string[] {
+  if (kind === "anecdote") return candidate.anecdotes ?? [];
+  if (kind === "argument") return candidate.arguments ?? [];
+  return candidate.hooks ?? [];
+}
+
+export interface CheckOptions {
+  /** Override the calibrated default when a series wants to be stricter or looser. */
+  threshold?: number;
+}
+
+/**
+ * Check a proposed skeleton against everything the series already published.
+ * Units are compared WITHIN their kind — an argument re-used as a hook is a new
+ * move, not a retread. Advisory: the verdict feeds the Step 2.5 annotation gate.
+ */
+export function checkSkeleton(
+  distillate: SeriesDistillate,
+  candidate: SkeletonCandidate,
+  options: CheckOptions = {},
+): ReuseReport {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  const hits: ReuseHit[] = [];
+
+  for (const kind of KINDS) {
+    for (const proposed of candidateUnits(candidate, kind)) {
+      for (const edition of distillate.editions) {
+        for (const published of unitsOf(edition, kind)) {
+          const score = similarity(proposed, published);
+          if (score >= threshold) {
+            hits.push({ kind, candidate: proposed, matched: published, editionId: edition.editionId, score });
+          }
+        }
+      }
+    }
+  }
+
+  hits.sort((a, b) => b.score - a.score);
+
+  return {
+    verdict: hits.length > 0 ? "REUSE" : "CLEAR",
+    hits,
+    threshold,
+    comparedAgainst: distillate.editions.length,
+  };
+}
+
+/**
+ * The distillate sits beside `edition-state.json` in the series root, not in the
+ * per-user data dir: it is series-scoped state, and the series folder is where
+ * the edition's state already lives (`<serie>/linkedin/`), so it travels with
+ * the series and needs no slug→path map.
+ */
+export function defaultDistillatePath(seriesRoot: string): string {
+  return join(seriesRoot, "linkedin", "series-distillate.json");
+}

scripts/editions/src/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Types for the series distillate (N11 — serie-nivå-vern / C-5).
+ *
+ * The gap this closes: every long-form gate agent sees ONE edition. At two
+ * editions a week the fastest-growing defect class is not a bad edition — it is
+ * a *repeated* one: the anecdote, the argument or the hook the reader already
+ * met three editions ago. Structurally invisible today, and the specifics-bank
+ * dedupe actively encourages re-surfacing the same material.
+ *
+ * So each locked edition leaves behind a distillate of the narrative units it
+ * spent, and the Step 2.5 skeleton gate checks the NEXT skeleton against it —
+ * before prose exists, which is the only point where changing course is cheap.
+ *
+ * Deterministic by design: the extraction of units from a locked edition is an
+ * AI job (the command layer), but the store, the comparison and the verdict are
+ * plain code — no model in the loop, no run-to-run variance.
+ *
+ * Scope note: this file is SERIES-scoped memory ("has this reader heard it?").
+ * Cross-series re-use of the operator's raw material is the specifics-bank's
+ * `usedIn` log — a different grain, deliberately a different store.
+ */
+
+export const SCHEMA_VERSION = 1;
+
+/** The three narrative units a reader actually recognizes across editions. */
+export type NarrativeKind = "anecdote" | "argument" | "hook";
+
+/** What one locked edition spent. */
+export interface DistillateEntry {
+  /** Edition id within the series, e.g. "05". */
+  editionId: string;
+  title: string;
+  /** ISO date the edition was locked. Supplied by the caller (CLI edge) — no clock in the pure core. */
+  lockedAt: string;
+  /** Stories told, in the operator's own phrasing. */
+  anecdotes: string[];
+  /** Claims argued. */
+  arguments: string[];
+  /** Opening moves used. */
+  hooks: string[];
+}
+
+export interface SeriesDistillate {
+  schemaVersion: number;
+  /** Series slug — the folder the editions live in. */
+  series: string;
+  editions: DistillateEntry[];
+}
+
+/** The units a NEW skeleton proposes, checked before prose (Step 2.5). */
+export interface SkeletonCandidate {
+  anecdotes?: string[];
+  arguments?: string[];
+  hooks?: string[];
+}
+
+/** One proposed unit that resembles something the series already published. */
+export interface ReuseHit {
+  kind: NarrativeKind;
+  /** The proposed text. */
+  candidate: string;
+  /** The already-published text it resembles. */
+  matched: string;
+  /** Which edition spent it. */
+  editionId: string;
+  /** 0..1 similarity; 1 = verbatim. */
+  score: number;
+}
+
+export type ReuseVerdict = "CLEAR" | "REUSE";
+
+/**
+ * Advisory by design — this reports into the annotation gate the operator
+ * already reads at Step 2.5; it never blocks. Re-use is sometimes the right
+ * call (a deliberate callback); silence about it never is.
+ */
+export interface ReuseReport {
+  verdict: ReuseVerdict;
+  hits: ReuseHit[];
+  threshold: number;
+  /** How many locked editions the skeleton was compared against. */
+  comparedAgainst: number;
+}