@heyramzi/social 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @heyramzi/social
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Content evaluation, written once. CutKit's script check and UpSys's Jev loop are different apps
+with their own weights and contracts, and both import what's the same from here, so a rule
+changes in one place.
+
+| Entry | What it holds | Read by |
+| --- | --- | --- |
+| `./story` | Checks with no model: `openerFault` (greeting, hidden point, scene first), `hedgeScan`, `flatRun`, `HOOK_MAX_WORDS` | CutKit's offline lint, `./shorts` |
+| `./questions` | `storyQuestions({ field, piece, reader })`: the story questions a judge model answers, in the surface's own words | CutKit's check, Jev's `opening`, `linkedin`, `x` and `reddit` surfaces |
+| `./hooks` | One regex per hook-library shape, and the banned shape | `./shorts` |
+| `./shorts` | `matchHook` and `auditShorts`, the skeleton of a Short | `heyramzi-slop --register=shorts` in `@heyramzi/lint` |
+| `./jev` | The wire shape of a question (`questionBody`), the `Answer` type, and `askJev`: one call that takes the key, model, state and questions, and returns the answers | CutKit's check, UpSys's `tools/social` client |
+| `./grade` | A trained model plus Jev's answers to a grade: `gradeAnswers` (grade 0 to 10, confidence, the three weakest answers with their fixes, the nearest winners, the pass gate), `encode`, `predict`, `rankOn`, `letterGrade`, `PASS_GRADE` | UpSys's loop, training and draft grading, CutKit's letter |
+
+`./jev` reads no env and keeps no cache. The caller passes the key, the model and, if it wants
+one, `fetch` and `retries` (a dropped connection, a 429, a 529 or a 5xx waits 0.5s, 1s, 2s and
+on). Every call gives up after 60 seconds. It throws when a question comes back unanswered, so
+nobody grades a partial set. A disk or database cache wraps it in the app, keyed on
+`questionBody`.
+
+`./grade` is pure. Training reads the same `encode` and `predict` that grade a draft, so a model
+grades the way it was fitted.
+
+Every evaluator grades on one scale. `rankOn(ruler, value)` is the share of a sorted corpus
+ruler a value beats, in tenths, and `letterGrade` reads that as A+ to F with 8 as the B- bar.
+So a B- beats 80% of its corpus, whether it's a Short, a LinkedIn post or a Reddit reply. A
+trained model's ruler holds its predicted probabilities. CutKit's check maps answers to
+hand-written items with fixed weights, so its ruler holds the craft scores of its corpus
+scripts (`pnpm eval:ruler` in cutkit). Training (logistic regression, the corpus rows) stays in
+UpSys, because it reads local corpora.
+
+Fix copy never lives here. A question in the bank says what to ask; the app says what to tell
+the person when the answer drags the grade down.
+
+## Adding a question
+
+Add it to `storyQuestions` with its `source`. It earns a place in a surface once
+`pnpm jev train <surface>` in UpSys keeps it, and in CutKit's check once its rating bench
+(`evals/rating`) keeps it. The `script` wording CutKit already ships is pinned in `questions.test.mjs`, because the
+judge's answers move when a word does.
+
+## Calibration
+
+A rule here is measured against the CutKit corpus before an app gates on it. On 14 Oct 2026,
+over 5,089 punctuated Short transcripts from 23 creators, a sentence-rhythm rule (4 sentences in
+a row at one length) fired on 30.5% of winners and 27.9% of the rest, so it isn't here. `flatRun`
+flags 57% of winners and 60% of the rest: CutKit shows it as a nudge, never a fail.
+
+The same day, a Jev discovery round asked every question in the bank on each surface. Only
+`villain` earned a place: on `post` (+0.0020 AUC, coefficient +0.16) and `x` (+0.0025, +0.12).
+`intro_order` helped `opening`'s ranking with a negative coefficient (W-order openings did worse
+there), and `stakes`, `visual_first`, `head_fake` and `atomic_share` added nothing or pointed
+backwards. They stay in the bank to test again. UpSys's `short` surface, whose song-lyric
+transcripts pulled its AUC to 0.52, is gone: CutKit's check grades Shorts.
+
+```
+pnpm test
+```

package/grade.d.ts

@@ -0,0 +1,75 @@
+import type { Answer, JevQuestion } from "#social/jev.js";
+
+export type Question = JevQuestion & {
+  /** Code-only name. Jev never sees it, so the instructions carry the whole meaning. */
+  id: string;
+  /** Where the question came from: a control-tested lever, Kallaway, a hook-library shape, a discovery round. */
+  source?: string;
+  /** Said to the writer when this answer is what's pulling the grade down. */
+  fix?: string;
+  /** Training checks fix direction against the learned coefficient because advice must counter the trait dragging the grade. */
+  fixPushes?: "more" | "less";
+  /** Answered and weighed so the other coefficients aren't skewed by a tactic we ban, but never offered as advice. */
+  control?: true;
+};
+
+export type Fit = {
+  mean: number[];
+  sd: number[];
+  coef: number[];
+  intercept: number;
+};
+
+export type Model<Surface extends string = string> = Fit & {
+  surface: Surface;
+  trainedAt: string;
+  questions: Question[];
+  features: string[];
+  /** Sorted predicted probabilities over the training corpus, the ruler a grade is read off. */
+  ruler: number[];
+  metrics: {
+    cvAuc: number;
+    testAuc: number | null;
+    ownAuc: number | null;
+    rows: number;
+    positives: number;
+  };
+};
+
+export type TrainedModel<Surface extends string = string> = Model<Surface> & {
+  winners: { creator: string; text: string; breakout: number; x: number[] }[];
+};
+
+export type Weak = {
+  question: string;
+  answer: string;
+  pull: number;
+  fix?: string;
+};
+
+export type Grade<Surface extends string = string> = {
+  surface: Surface;
+  grade: number;
+  confidence: number;
+  pass: boolean;
+  /** False when the model failed its held-out test: the grade is advice and can't block a ship. */
+  gates: boolean;
+  testAuc: number | null;
+  weakest: Weak[];
+  winners: { creator: string; text: string; breakout: number }[];
+};
+
+export declare const PASS_GRADE: number;
+export declare const MIN_CONFIDENCE: number;
+export declare const MIN_TEST_AUC: number;
+/** The 0 to 10 grade as A+ to F. 8 is the B- bar. */
+export declare function letterGrade(grade: number): string;
+/** A value's rank on a sorted ruler of corpus scores, as a 0 to 10 grade: the share it beats. */
+export declare function rankOn(ruler: number[], value: number): number;
+export declare function encode(questions: Question[], answers: Record<string, Answer>): number[];
+export declare function predict(fit: Fit, x: number[]): number;
+export declare function contributions(fit: Fit, x: number[]): number[];
+export declare function gradeAnswers<Surface extends string>(
+  model: TrainedModel<Surface>,
+  answers: Record<string, Answer>,
+): Grade<Surface>;

package/grade.js

@@ -0,0 +1,166 @@
+/**
+ * Jev's answers to a grade on a trained model's corpus ruler. Pure. Training reads the same
+ * encode and predict, so a model grades the way it was fitted.
+ */
+
+/** The grade a piece needs before it ships. */
+export const PASS_GRADE = 8;
+/** Under this confidence Jev is closer to guessing, so a gating model won't pass the piece. */
+export const MIN_CONFIDENCE = 0.6;
+/** Only a model that ranks unseen winners above controls can block shipping. The rest advise. */
+export const MIN_TEST_AUC = 0.6;
+
+/**
+ * The grade times ten, so the bar of 8 reads B-. Every grade comes off `rankOn`, so a B-
+ * beats 80% of its corpus on any surface.
+ */
+const LETTERS = [
+  [97, "A+"],
+  [93, "A"],
+  [90, "A-"],
+  [87, "B+"],
+  [83, "B"],
+  [80, "B-"],
+  [77, "C+"],
+  [73, "C"],
+  [70, "C-"],
+  [67, "D+"],
+  [63, "D"],
+  [60, "D-"],
+];
+
+/** @param {number} grade 0 to 10 */
+export function letterGrade(grade) {
+  const score = Math.round(grade * 10);
+  return LETTERS.find(([floor]) => score >= floor)?.[1] ?? "F";
+}
+
+/**
+ * The share of a sorted corpus ruler a value beats, as a 0 to 10 grade.
+ * @param {number[]} ruler sorted ascending
+ * @param {number} value
+ */
+export function rankOn(ruler, value) {
+  if (!ruler.length) return 0;
+  const below = ruler.filter((r) => r < value).length;
+  return Number(((below / ruler.length) * 10).toFixed(1));
+}
+
+/** A score answer as a fraction of the scale; no answer sits mid scale. */
+function encodeScore(levels, a) {
+  return (a?.score ?? (levels - 1) / 2) / (levels - 1);
+}
+
+/** One column per choice past the first (the baseline): its probability, else 1 for the pick. */
+function encodeChoice(criteria, a) {
+  return Object.keys(criteria)
+    .slice(1)
+    .map((k) => a?.probabilities?.[k] ?? (a?.choice === k ? 1 : 0));
+}
+
+function encodeOne(q, a) {
+  if (q.type === "noul") return [a?.noul ?? 0.5];
+  if (q.type === "score") return [encodeScore(q.criteria.length, a)];
+  return encodeChoice(q.criteria, a);
+}
+
+/** One number per feature, in the order a model's `features` lists them. */
+export function encode(questions, answers) {
+  return questions.flatMap((q) => encodeOne(q, answers[q.id]));
+}
+
+const sigmoid = (z) => 1 / (1 + Math.exp(-z));
+const standardized = (f, x, j) => ((x[j] - (f.mean[j] ?? 0)) / (f.sd[j] ?? 1)) * (f.coef[j] ?? 0);
+
+export function predict(f, x) {
+  return sigmoid(f.intercept + x.reduce((sum, _, j) => sum + standardized(f, x, j), 0));
+}
+
+/** Each feature's pull on the logit, against an average corpus row. */
+export function contributions(f, x) {
+  return x.map((_, j) => standardized(f, x, j));
+}
+
+function describe(a, q) {
+  if (!a) return "no answer";
+  if (q.type === "noul") return `yes ${Math.round((a.noul ?? 0) * 100)}%`;
+  if (q.type === "score") {
+    const levels = q.criteria;
+    const i = Math.max(0, Math.min(levels.length - 1, Math.round(a.score ?? 0)));
+    return `level ${i + 1} of ${levels.length}: "${levels[i]}"`;
+  }
+  return `picked "${a.choice}"`;
+}
+
+/** Each question's pull: the sum over its features, against an average corpus row. */
+function pullsOf(model, contrib) {
+  return model.questions.map((q) => {
+    const cols = model.features
+      .map((f, j) => [f, j])
+      .filter(([f]) => f === q.id || f.startsWith(`${q.id}=`));
+    return { q, pull: cols.reduce((sum, [, j]) => sum + (contrib[j] ?? 0), 0) };
+  });
+}
+
+/** Confidence that counts is the confidence on the answers doing the work. */
+function confidenceOf(pulls, answers) {
+  let weight = 0;
+  let sum = 0;
+  for (const { q, pull } of pulls) {
+    const c = answers[q.id]?.confidence;
+    if (c === undefined) continue;
+    weight += Math.abs(pull);
+    sum += Math.abs(pull) * c;
+  }
+  return Number((weight ? sum / weight : 1).toFixed(2));
+}
+
+/** The winners nearest the answers, with distance weighted by each feature's coefficient. */
+function nearestWinners(model, x) {
+  const z = (v, j) =>
+    ((v - (model.mean[j] ?? 0)) / (model.sd[j] ?? 1)) * Math.abs(model.coef[j] ?? 0);
+  const zx = x.map(z);
+  return model.winners
+    .map((w) => ({ w, d: w.x.reduce((sum, v, j) => sum + (z(v, j) - (zx[j] ?? 0)) ** 2, 0) }))
+    .toSorted((a, b) => a.d - b.d)
+    .slice(0, 3)
+    .map(({ w }) => ({ creator: w.creator, text: w.text, breakout: w.breakout }));
+}
+
+/**
+ * Where the answers rank, what drags them down, and the nearest winners. Under `MIN_TEST_AUC`
+ * a model only advises: `gates` false, `pass` true.
+ */
+export function gradeAnswers(model, answers) {
+  const x = encode(model.questions, answers);
+  const fitted = { mean: model.mean, sd: model.sd, coef: model.coef, intercept: model.intercept };
+  const p = predict(fitted, x);
+  const grade = rankOn(model.ruler, p);
+
+  const pulls = pullsOf(model, contributions(fitted, x));
+  const confidence = confidenceOf(pulls, answers);
+  const weakest = pulls
+    .filter((e) => e.pull < 0 && !e.q.control)
+    .toSorted((a, b) => a.pull - b.pull)
+    .slice(0, 3)
+    .map(({ q, pull }) => ({
+      question: q.instructions,
+      answer: describe(answers[q.id], q),
+      pull: Number(pull.toFixed(2)),
+      fix: q.fix,
+    }));
+
+  const testAuc = model.metrics.testAuc;
+  const gates = testAuc !== null && testAuc >= MIN_TEST_AUC;
+  const pass = !gates || (grade >= PASS_GRADE && confidence >= MIN_CONFIDENCE);
+  return {
+    surface: model.surface,
+    grade,
+    confidence,
+    pass,
+    gates,
+    testAuc,
+    weakest,
+    winners: nearestWinners(model, x),
+  };
+}

package/hooks.d.ts

@@ -0,0 +1,10 @@
+export interface HookShape {
+  n: number;
+  family: string;
+  test: RegExp;
+  second?: boolean;
+  maxWords?: number;
+  alone?: boolean;
+}
+export declare const hookShapes: HookShape[];
+export declare const bannedHook: RegExp;

package/hooks.js

@@ -0,0 +1,114 @@
+/** One regex per hook-library shape, keyed by its number. The prose lives in shorts-script. */
+const N = "(?:\\d+|two|three|four|five|six|seven|eight|nine|ten|twelve)";
+
+export const hookShapes = [
+  { n: 1, family: "Promise", test: /^here(?:'s| is) the only\b/i },
+  { n: 2, family: "Promise", test: /^(?:here(?:'s| is)|this is) how (?:to|you|i)\b/i },
+  { n: 3, family: "Promise", test: new RegExp(`^here are ${N}\\b`, "i") },
+  {
+    n: 4,
+    family: "Promise",
+    second: true,
+    test: /\bi (?:use|built|made) (?:a|an|the) [\w ]{1,24}(?:i call|called)\b/i,
+  },
+  { n: 5, family: "Diagnosis", test: /^the (?:real )?reason (?:your|you)\b/i },
+  { n: 6, family: "Diagnosis", test: /^this is the most\b/i },
+  { n: 7, family: "Diagnosis", test: /\bthe fastest way to\b.*\bthe fastest way to\b/i },
+  {
+    n: 8,
+    family: "Received-wisdom break",
+    test: /^(?:everyone|everybody|people)(?: will| keep)? (?:tells?|telling|says?|saying) you\b|, bro[.!?]?$/i,
+  },
+  { n: 9, family: "Received-wisdom break", test: /^you (?:do not|don't) need\b/i },
+  { n: 10, family: "Received-wisdom break", test: /^every \w+ (?:is|are)\b/i },
+  {
+    n: 11,
+    family: "Received-wisdom break",
+    test: /^[^.?!,]{2,50} or [^.?!,]{2,50}[.?]$/i,
+    maxWords: 10,
+  },
+  {
+    n: 12,
+    family: "In medias res",
+    test: /^(?:can't|couldn't|just|still|got|lost|spent|found|watched)\b/i,
+  },
+  { n: 13, family: "In medias res", test: /^i(?:'m| am) (?:processing|realizing|still)\b/i },
+  { n: 14, family: "In medias res", test: /^i regret\b/i },
+  { n: 15, family: "Tribe", test: /^if you want to\b.*\bbut\b/i },
+  {
+    n: 17,
+    family: "Tribe",
+    test: /^if you(?:'re| are) [^,]{2,40}, you (?:gotta|have to|need to|should|must)\b/i,
+  },
+  {
+    n: 18,
+    family: "Tribe",
+    test: /^there are (?:fully grown |grown )?\w+(?: \w+)? (?:out there|who)\b/i,
+  },
+  {
+    n: 19,
+    family: "Artefact",
+    test: /^(?:so )?i (?:saw|got|found) this (?:comment|post|email|message|dm|video|review)\b/i,
+  },
+  { n: 20, family: "Artefact", test: /^(?:open|pull up|go to) (?:your|the)\b/i },
+  { n: 21, family: "Artefact", test: /^pro [\w ]{1,24} tip\b/i },
+  {
+    n: 22,
+    family: "Number",
+    test: new RegExp(`^i (?:spent|tested|tried|ran|used|asked) (?:the last |over )?${N}\\b`, "i"),
+  },
+  { n: 23, family: "Number", test: /^\d[\d,.]*%?\s.*\bso\b/i },
+  { n: 24, family: "Number", test: new RegExp(`^${N} [a-z]+`, "i") },
+  {
+    n: 25,
+    family: "Number",
+    test: /^[\w'-]+(?: [\w'-]+)?, [\w'-]+(?: [\w'-]+)?,? (?:and )?[\w'-]+(?: [\w'-]+)?\.$/i,
+    maxWords: 8,
+  },
+  { n: 26, family: "Number", test: /^every \w+(?: \w+)? (?:does|do|has) this\b/i },
+  {
+    n: 27,
+    family: "Question",
+    test: /^(?:(?:do|does|is|are|can|will|should|did) [^?]{3,80}|what happens when [^?]{3,80})\?$/i,
+  },
+  { n: 28, family: "Question", test: /^(?:you know|do you know) (?:who|what|why|how)\b/i },
+  { n: 29, family: "Confession", test: /^i have a confession\b/i },
+  {
+    n: 31,
+    family: "News",
+    test: /^(?:breaking news\b|[\w.\- ]{1,30} just (?:killed|replaced|ended|dropped|changed|released|launched|did it again)\b)/i,
+  },
+  { n: 32, family: "News", test: /^this is the (?:one|only|new) \w+(?: \w+)? you need\b/i },
+  {
+    n: 33,
+    family: "News",
+    test: /^this (?:has (?:got )?to be|might be|is) the (?:craziest|best|wildest|biggest)\b/i,
+  },
+  {
+    n: 34,
+    family: "Contradiction",
+    test: /^(?:i don't think there's a (?:more|better)\b|[\w.\- ]{2,30} (?:lies|fails|breaks) more than you think\b)/i,
+  },
+  {
+    n: 35,
+    family: "Contradiction",
+    test: /^most people (?:don't|do not) (?:know|realize|realise)\b/i,
+  },
+  {
+    n: 36,
+    family: "Promise",
+    test: new RegExp(`^(?:turn on|add|type|use) (?:these|this) (?:${N} )?\\w+`, "i"),
+  },
+  { n: 37, family: "Promise", test: /^how (?:an?|the) [\w'’ -]{2,40} would\b/i },
+  {
+    n: 38,
+    family: "News",
+    test: /^[\w.$'’ -]{2,40} just (?:turned down|said no to|walked away from|rejected)\b/i,
+  },
+  { n: 39, family: "Diagnosis", test: /^the difference between an? [\w -]{1,30} and an? \w+/i },
+  // Shape 16 qualifies the audience and opens no gap, so it only counts beside another shape.
+  { n: 16, family: "Tribe", alone: false, test: /^if you\b/i },
+];
+
+// Shape 30: our worst post ran 2 views on it.
+export const bannedHook = /^(?:when i (?:first )?started|i used to think|one year ago,? i)\b/i;

package/jev.d.ts

@@ -0,0 +1,29 @@
+/** One answer from Jev. Which fields are set depends on the question's type. */
+export type Answer = {
+  type?: string;
+  noul?: number;
+  score?: number;
+  choice?: string;
+  probabilities?: Record<string, number>;
+  confidence?: number;
+};
+
+export type JevQuestion =
+  | { type: "noul"; instructions: string; criteria?: undefined }
+  /** Ordered low to high, 2 to 10 levels. */
+  | { type: "score"; instructions: string; criteria: string[] }
+  /** Option key to its meaning. */
+  | { type: "choice"; instructions: string; criteria: Record<string, string> };
+
+export declare const JEV_URL: string;
+export declare function questionBody(q: JevQuestion): JevQuestion;
+
+export declare function askJev(request: {
+  key: string;
+  model: string;
+  state: unknown;
+  questions: Record<string, JevQuestion>;
+  url?: string;
+  fetch?: typeof fetch;
+  retries?: number;
+}): Promise<{ answers: Record<string, Answer>; model: string }>;

package/jev.js

@@ -0,0 +1,71 @@
+/**
+ * The wire shape of a Jev question and the one call that answers it. No env reads and no
+ * cache: the app passes its key and model and caches.
+ */
+
+/** TypeSafe's /v1/systemone behind Kilo, which bills our Kilo credits. */
+export const JEV_URL = "https://api.kilo.ai/api/gateway/typesafe/v1/systemone";
+
+/** A dead socket hung a run for 15 hours on 14 Oct 2026, so every call gives up at this. */
+const TIMEOUT_MS = 60_000;
+
+/**
+ * What Jev sees of a question. The app's id, fix and source stay out, so a cache key hashed
+ * from this survives a change to them.
+ */
+export function questionBody(q) {
+  return q.type === "noul"
+    ? { type: "noul", instructions: q.instructions }
+    : { type: q.type, instructions: q.instructions, criteria: q.criteria };
+}
+
+const retryable = (status) => status === 429 || status === 529 || status >= 500;
+const backoff = (attempt) => new Promise((done) => setTimeout(done, 500 * 2 ** attempt));
+
+async function post(request, attempt) {
+  const { key, model, state, questions, url = JEV_URL, fetch: send = fetch, retries = 0 } = request;
+  let res;
+  try {
+    res = await send(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ state, model, questions }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (error) {
+    if (attempt >= retries) throw error;
+    return backoff(attempt).then(() => post(request, attempt + 1));
+  }
+  if (retryable(res.status) && attempt < retries)
+    return backoff(attempt).then(() => post(request, attempt + 1));
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`Jev answered ${res.status}: ${detail.slice(0, 200)}`);
+  }
+  return res.json();
+}
+
+/**
+ * @typedef {{
+ *   key: string,
+ *   model: string,
+ *   state: unknown,
+ *   questions: Record<string, ReturnType<typeof questionBody>>,
+ *   url?: string,
+ *   fetch?: typeof fetch,
+ *   retries?: number,
+ * }} JevCall
+ */
+
+/**
+ * Asks every question about one state. A drop, 429, 529 or 5xx retries after 0.5s, 1s, 2s and
+ * on. A missing answer throws.
+ * @param {JevCall} request
+ */
+export async function askJev(request) {
+  const reply = await post(request, 0);
+  for (const id of Object.keys(request.questions)) {
+    if (!reply.answers?.[id]) throw new Error(`Jev returned no answer for ${id}`);
+  }
+  return { answers: reply.answers, model: reply.model ?? request.model };
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@heyramzi/social",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Content evaluation CutKit and UpSys share: hook shapes, the Shorts audit, story checks with no model, the story question bank, and the Jev call and trained-model grade",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heyramzi/vibe-kit.git",
+    "directory": "packages/social"
+  },
+  "files": [
+    "grade.js",
+    "grade.d.ts",
+    "hooks.js",
+    "hooks.d.ts",
+    "jev.js",
+    "jev.d.ts",
+    "questions.js",
+    "questions.d.ts",
+    "shorts.js",
+    "shorts.d.ts",
+    "story.js",
+    "story.d.ts",
+    "package.json"
+  ],
+  "type": "module",
+  "imports": {
+    "#social/*": "./*"
+  },
+  "exports": {
+    "./grade": {
+      "types": "./grade.d.ts",
+      "default": "./grade.js"
+    },
+    "./hooks": {
+      "types": "./hooks.d.ts",
+      "default": "./hooks.js"
+    },
+    "./jev": {
+      "types": "./jev.d.ts",
+      "default": "./jev.js"
+    },
+    "./questions": {
+      "types": "./questions.d.ts",
+      "default": "./questions.js"
+    },
+    "./shorts": {
+      "types": "./shorts.d.ts",
+      "default": "./shorts.js"
+    },
+    "./story": {
+      "types": "./story.d.ts",
+      "default": "./story.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"*.test.mjs\""
+  }
+}

package/questions.d.ts

@@ -0,0 +1,22 @@
+export type StoryQuestion = { instructions: string; source: string } & (
+  | { type: "noul"; criteria?: undefined }
+  /** Ordered low to high. */
+  | { type: "score"; criteria: string[] }
+);
+
+export type StoryQuestionId =
+  | "opening_speed"
+  | "contrast"
+  | "rehook"
+  | "stakes"
+  | "intro_order"
+  | "visual_first"
+  | "head_fake"
+  | "villain"
+  | "atomic_share";
+
+export declare function storyQuestions(voice: {
+  field: string;
+  piece: string;
+  reader: string;
+}): Record<StoryQuestionId, StoryQuestion>;

package/questions.js

@@ -0,0 +1,70 @@
+/**
+ * The story questions a judge model answers, written once and asked in each surface's words.
+ * Which ones a surface asks, its weights and its fix copy stay in the app.
+ */
+
+const KALLAWAY = "Kallaway, How to Master Storytelling (youtube.com/watch?v=WluuZB_ck9Q)";
+
+/**
+ * @param {{ field: string, piece: string, reader: string }} voice
+ *   `field` is the state key the judge reads ("script"), `piece` what it is ("video"),
+ *   `reader` who meets it ("viewer").
+ */
+export function storyQuestions({ field, piece, reader }) {
+  const f = `\`${field}\``;
+  const keep = reader === "viewer" ? "keep watching" : "keep reading";
+  const once = reader === "viewer" ? "one watch" : "one read";
+  return {
+    opening_speed: {
+      type: "score",
+      instructions: `How fast does the ${f} say what the ${piece} is about and what the ${reader} gets? Judge the first two sentences.`,
+      criteria: [
+        `After more than two sentences the ${reader} still doesn't know the subject or the payoff.`,
+        "The subject shows up in the first two sentences but the payoff stays unclear.",
+        "The subject is clear in the first sentence, the payoff by the second.",
+        "One short sentence of about ten words names both the subject and the outcome.",
+      ],
+      source: "Kallaway interrupt theory: subject, stakes, speed, clarity",
+    },
+    contrast: {
+      type: "noul",
+      instructions: `In its first three sentences, does the ${f} set what the ${reader} already believes or does against something different, stated ('most people do A, this does B') or implied ('this is 8 times faster')?`,
+      source: "Kallaway headfake; vidIQ: statement adds contrast",
+    },
+    rehook: {
+      type: "noul",
+      instructions: `Halfway through, does the ${f} add a new question, a higher stake, a revealed mechanism, or bring back the problem from the opening and show that a better answer is still ahead, giving the ${reader} a new reason to ${keep}? A sentence that only announces what's next ('this is where it gets crazy') doesn't count.`,
+      source: `Kallaway rehook and rebuy; ${KALLAWAY}`,
+    },
+    stakes: {
+      type: "noul",
+      instructions: `Does the ${f} name who it's about, what they could lose, and why now?`,
+      source: "Kallaway addiction loop: a character, something at risk, urgency",
+    },
+    intro_order: {
+      type: "noul",
+      instructions: `In its first two sentences, does the ${f} say what is happening and why it matters to the ${reader} before it says who, when or where? Opening on a time and place ('Last month I was at a conference in Miami') or on the author's credentials counts as no.`,
+      source: `Kallaway W order: what and why, then who and how, then when and where; ${KALLAWAY}`,
+    },
+    visual_first: {
+      type: "noul",
+      instructions: `Does the first sentence of the ${f} name something the ${reader} can picture at once, such as a physical object, a screen, a result or a number, rather than only an idea?`,
+      source: `Kallaway: visual hooks beat audio-only hooks, show while you tell; ${KALLAWAY}`,
+    },
+    head_fake: {
+      type: "noul",
+      instructions: `Does the ${f} lead the ${reader} toward one answer and then give a different one that its earlier details make sense of? A twist with no clues before it counts as no.`,
+      source: `Kallaway addiction loop: prediction error, the head fake; ${KALLAWAY}`,
+    },
+    villain: {
+      type: "noul",
+      instructions: `Does the ${f} set the ${reader} against a named opponent: a person, company, group, tool, habit or belief it paints as the problem?`,
+      source: `Kallaway: a missing villain; ${KALLAWAY}`,
+    },
+    atomic_share: {
+      type: "noul",
+      instructions: `After ${once}, could the ${reader} retell the main point of the ${f} to a friend in one sentence of under 10 words?`,
+      source: `Kallaway atomic shareability, the Paul Revere effect; ${KALLAWAY}`,
+    },
+  };
+}

package/shorts.d.ts

@@ -0,0 +1,9 @@
+export type HookMatch =
+  | { shape: number; banned: true }
+  | { vague: true }
+  | { shape: number; family: string; alone: boolean };
+export declare function matchHook(first: string, second?: string): HookMatch | null;
+export declare function auditShorts(text: string): {
+  hook: HookMatch | null;
+  findings: { kind: "shorts"; id: string; detail: string }[];
+};

package/shorts.js

@@ -0,0 +1,111 @@
+import { bannedHook, hookShapes } from "#social/hooks.js";
+import { HOOK_MAX_WORDS, openerFault } from "#social/story.js";
+
+const SENTENCE = /[^.!?]+(?:[.!?]+["'”’)]*|$)/g;
+const COUNT =
+  /\b(?:no\.? ?\d|number (?:one|two|three|four|five|\d)|step (?:one|two|three|four|\d)|(?:the )?first|second|third|fourth)\b/gi;
+const REPLY_CTA = /\b(?:comment|dm me|type|reply)\b/i;
+
+/** The spoken part of a note: header lines and everything under a `---` divider are notes to self. */
+function spoken(text) {
+  const body = text.split(/^-{3,}\s*$/m)[0];
+  return body
+    .split("\n")
+    .filter((line) => /[.!?]["'”’)]*\s*$/.test(line.trim()))
+    .join(" ")
+    .trim();
+}
+
+const words = (s) => s.split(/\s+/).filter(Boolean).length;
+
+const STOP = new Set(
+  "that this with they them their there then than what when where which your yours from have been were will would could should about into just like more most some such very also only even ever never always because while these those other every thing things people".split(
+    " ",
+  ),
+);
+const content = (s) =>
+  (s.toLowerCase().match(/[a-z']{4,}/g) ?? [])
+    .map((w) => w.replace(/s$/, ""))
+    .filter((w) => !STOP.has(w));
+/** Two short sentences that swap 2 nearby words around a shared frame: "good team, bad plan. good plans, bad teams." */
+function chiasmus(sentences) {
+  for (let i = 0; i + 1 < sentences.length; i++) {
+    const short = (s) => s.split(/\s+/).length <= 18;
+    if (!short(sentences[i]) || !short(sentences[i + 1])) continue;
+    const a = content(sentences[i]),
+      b = content(sentences[i + 1]);
+    const once = (arr, w) => arr.indexOf(w) === arr.lastIndexOf(w);
+    for (let x = 0; x < a.length; x++)
+      for (let y = x + 1; y < a.length; y++) {
+        const p = a[x],
+          q = a[y];
+        if (p === q || y - x > 2) continue;
+        const bp = b.indexOf(p),
+          bq = b.indexOf(q);
+        if (
+          bp !== -1 &&
+          bq !== -1 &&
+          bq < bp &&
+          bp - bq <= 2 &&
+          once(a, p) &&
+          once(a, q) &&
+          once(b, p) &&
+          once(b, q)
+        ) {
+          const kept = a.filter((w) => w !== p && w !== q && b.includes(w));
+          const ordered = kept.every((w, k) => k === 0 || b.indexOf(kept[k - 1]) < b.indexOf(w));
+          if (kept.length >= 1 && ordered) return `${sentences[i]} ${sentences[i + 1]}`;
+        }
+      }
+  }
+  return null;
+}
+
+/** Which library shape the opening runs on, or why it runs on none. */
+export function matchHook(first, second = "") {
+  const hook = first.trim();
+  if (bannedHook.test(hook)) return { shape: 30, banned: true };
+  const fault = openerFault(hook);
+  if (fault === "opaque" || fault === "scene") return { vague: true };
+  for (const s of hookShapes) {
+    const target = s.second ? second.trim() : hook;
+    if (s.maxWords && words(target) > s.maxWords) continue;
+    if (s.test.test(target)) return { shape: s.n, family: s.family, alone: s.alone === false };
+  }
+  return null;
+}
+
+/** The hook and the skeleton of a Short, per the shorts-script skill. */
+export function auditShorts(text) {
+  const findings = [];
+  const sentences = (spoken(text).match(SENTENCE) ?? []).map((s) => s.trim()).filter(Boolean);
+  if (sentences.length === 0) return { hook: null, findings };
+  const [first, second] = sentences;
+  const push = (id, detail) => findings.push({ kind: "shorts", id, detail });
+
+  const hook = matchHook(first, second);
+  if (!hook) push("hook-shape", `"${first}" matches no shape in the hook library`);
+  else if (hook.vague) push("hook-vague", `"${first}" hides the plot or opens on a time and place`);
+  else if (hook.banned) push("hook-banned", `"${first}" is shape 30, banned`);
+  else if (hook.alone)
+    push("hook-alone", `"${first}" is shape 16, which qualifies the audience and opens no gap`);
+  if (words(first) > HOOK_MAX_WORDS)
+    push("hook-length", `the hook is ${words(first)} words, the window takes ${HOOK_MAX_WORDS}`);
+
+  const clefts = sentences.filter(
+    (s) => /^What [^?]{3,60}?\b(?:is|are|was|were)\s/.test(s) && !s.endsWith("?"),
+  );
+  if (clefts.length > 1)
+    push("what-cleft", `${clefts.length} "What X is Y" sentences; 1 per script`);
+  const mirror = chiasmus(sentences);
+  if (mirror) push("chiasmus", `mirrored close: "${mirror}"`);
+
+  const counted = (sentences.slice(1).join(" ").match(COUNT) ?? []).length;
+  if (counted < 2)
+    push("uncounted-steps", `${counted} count markers in the body; name the steps out loud`);
+
+  const close = sentences.slice(-2).join(" ");
+  if (!REPLY_CTA.test(close)) push("cta-reply", "the close carries no reply-trigger CTA");
+
+  return { hook, findings };
+}

package/story.d.ts

@@ -0,0 +1,16 @@
+export declare const HOOK_MAX_WORDS: number;
+export type OpenerFault = "greeting" | "opaque" | "scene";
+export declare function openerFault(text: string): OpenerFault | null;
+export declare function wordCount(text: string): number;
+export declare function firstSentence(text: string): string;
+export declare const HEDGES: string[];
+export declare function hedgeScan(text: string): {
+  pass: boolean;
+  dense: boolean;
+  total: number;
+  found: string[];
+};
+export declare const FLAT_RUN_WORDS: number;
+export declare const FLAT_RUN_MIN_WORDS: number;
+export declare const WORDS_PER_SECOND: number;
+export declare function flatRun(text: string): { words: number; seconds: number; flagged: boolean };

package/story.js

@@ -0,0 +1,127 @@
+/**
+ * The story checks that need no model: how a script or post opens, hedges and turns.
+ * CutKit and the Shorts gate both read these. Fix copy stays in each app.
+ */
+
+/** The window a hook gets: past this the first sentence is still talking when the swipe comes. */
+export const HOOK_MAX_WORDS = 15;
+
+// WHY: every short-form source we read names a greeting opener as the top failure.
+const GREETING =
+  /^(hey|hi|hello|welcome|so basically|in this video|today we're going to|today i'm going to|let me tell you)\b/iu;
+// Kallaway's classroom: hiding the plot loses the swipe.
+const OPAQUE =
+  /^(?:wait (?:till|until) you see|you(?:['’]re| are) (?:never |not )?(?:going to|gonna) believe)/iu;
+// Kallaway's W order: what and why first, who and how next, when and where last. A time and
+// place in the first words is the icing served before the cake.
+const SCENE =
+  /^(?:(?:last|this) (?:week|month|year|summer|winter),? i was\b|it was an? (?:[\w,]+ ){0,3}(?:night|day|morning|evening)\b)/iu;
+
+/** The rule an opening breaks: a greeting, a hidden point or a scene set first. Null when clean. */
+export function openerFault(text) {
+  const opening = text.trim();
+  if (GREETING.test(opening)) return "greeting";
+  if (OPAQUE.test(opening)) return "opaque";
+  if (SCENE.test(opening)) return "scene";
+  return null;
+}
+
+export const wordCount = (text) => text.split(/\s+/u).filter(Boolean).length;
+
+export function firstSentence(text) {
+  return text.trim().split(/(?<=[.!?])(?:\s|$)|\n+/u, 1)[0] ?? "";
+}
+
+// WHY no "if": 6 of the 10 viral scripts in CutKit's REAL_SHORTS say "if you", 2 in their first line.
+export const HEDGES = [
+  "maybe",
+  "might",
+  "could",
+  "probably",
+  "perhaps",
+  "possibly",
+  "hopefully",
+  "kind of",
+  "sort of",
+  "i think",
+  "i guess",
+];
+
+const hedgePattern = (hedge, flags) => new RegExp(`\\b${hedge.replaceAll(" ", "\\s+")}\\b`, flags);
+
+/**
+ * Honest uncertainty is fine, so only a hedge in the first 2 sentences, or more than 1 per
+ * 100 words, fails. `found` names the hedges to cut.
+ */
+export function hedgeScan(text) {
+  const words = wordCount(text);
+  const early = text
+    .trim()
+    .split(/(?<=[.!?])(?:\s|$)/u)
+    .slice(0, 2)
+    .join(" ");
+  const earlyFound = HEDGES.filter((hedge) => hedgePattern(hedge, "iu").test(early));
+  const total = HEDGES.reduce(
+    (sum, hedge) => sum + (text.match(hedgePattern(hedge, "igu")) ?? []).length,
+    0,
+  );
+  const dense = total > Math.max(1, words / 100);
+  const found = earlyFound.length
+    ? earlyFound
+    : dense
+      ? HEDGES.filter((hedge) => hedgePattern(hedge, "iu").test(text))
+      : [];
+  return { pass: earlyFound.length === 0 && !dense, dense, total, found };
+}
+
+// The words that turn a story: a contrast, or a list stepping on.
+const TURNS = new Set([
+  "but",
+  "actually",
+  "except",
+  "however",
+  "yet",
+  "though",
+  "instead",
+  "until",
+  "whereas",
+  // WHY: a list moves on at each step, and 5 of 10 viral scripts in REAL_SHORTS turn only that way.
+  "next",
+  "first",
+  "second",
+  "third",
+  "finally",
+]);
+/** A stretch longer than this with no turn in it drifts. South Park's rule: but or therefore, never and then. */
+export const FLAT_RUN_WORDS = 70;
+/** Below this length a whole script is one breath, so a flat run says nothing. */
+export const FLAT_RUN_MIN_WORDS = 120;
+export const WORDS_PER_SECOND = 2.5;
+
+/** The longest run of words with no turn, a question or a numbered step in it. */
+export function flatRun(text) {
+  const raw = text.split(/\s+/u).filter(Boolean);
+  const words = raw.map((word) => word.toLowerCase().replace(/[^a-z]/gu, ""));
+  let run = 0;
+  let worst = 0;
+  for (let index = 0; index < words.length; index += 1) {
+    // WHY the pair: "turns out" turns on two words, so one token never matches it.
+    if (words[index] === "turns" && words[index + 1] === "out") {
+      run = 0;
+      index += 1;
+      continue;
+    }
+    if (
+      TURNS.has(words[index] ?? "") ||
+      raw[index]?.includes("?") ||
+      /^\d+[.)]$/u.test(raw[index] ?? "")
+    )
+      run = 0;
+    else {
+      run += 1;
+      worst = Math.max(worst, run);
+    }
+  }
+  const flagged = raw.length > FLAT_RUN_MIN_WORDS && worst > FLAT_RUN_WORDS;
+  return { words: worst, seconds: Math.round(worst / WORDS_PER_SECOND), flagged };
+}