@startsimpli/ui 0.4.108 → 0.4.110

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.108",
+  "version": "0.4.110",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components/collection/__tests__/review.test.ts

@@ -223,3 +223,64 @@ describe('reviewHostOf / fieldStr', () => {
     expect(fieldStr(undefined, 'x')).toBe('');
   });
 });
+
+// ---- decision vocabulary (bd startsim-b313v) ----
+//
+// THE DEFECT THESE COVER. The three labels were string literals inside
+// `reviewDecisions`, so every tenant's every reviewable type said the same three
+// words. On the OGMC tenant that collided in the customer's hands: approving a
+// TOPIC ("this subject is worth writing") and approving a DRAFT ("this piece is
+// publishable") are different KINDS of decision, and both rendered "Approve".
+// Her question, mid-walkthrough: "so if I go, I click approve now, does it
+// approve all of them?"
+
+describe('decision labels are the consumer’s to name', () => {
+  const type = {
+    id: 't',
+    key: 'topic',
+    label: 'Topic',
+    attributes: [
+      {
+        id: 'a',
+        name: 'status',
+        dataType: 'enum' as const,
+        required: false,
+        config: { choices: ['suggested', 'ready', 'written', 'rejected'] },
+      },
+    ],
+  };
+
+  it('keeps the generic words when a consumer supplies none', () => {
+    expect(reviewDecisions(resolveReviewConfig(type)).map((d) => d.label)).toEqual([
+      'Approve',
+      'Needs work',
+      'Reject',
+    ]);
+  });
+
+  it('lets a consumer name what the decision is ABOUT', () => {
+    const cfg = resolveReviewConfig(type, {
+      decisionLabels: { approve: 'Approve topic', reject: 'Reject topic' },
+    });
+    const byKey = Object.fromEntries(reviewDecisions(cfg).map((d) => [d.key, d.label]));
+    expect(byKey.approve).toBe('Approve topic');
+    expect(byKey.reject).toBe('Reject topic');
+    // Unnamed decisions keep the default rather than going blank.
+    expect(byKey.needs_work).toBe('Needs work');
+  });
+
+  it('ignores a blank override instead of rendering an unlabelled button', () => {
+    const cfg = resolveReviewConfig(type, { decisionLabels: { approve: '   ' } });
+    expect(reviewDecisions(cfg).find((d) => d.key === 'approve')?.label).toBe('Approve');
+  });
+
+  it('leaves every other part of the decision alone — this is copy, not behaviour', () => {
+    const plain = reviewDecisions(resolveReviewConfig(type));
+    const named = reviewDecisions(
+      resolveReviewConfig(type, { decisionLabels: { approve: 'Approve topic' } }),
+    );
+    expect(named.map((d) => [d.key, d.status, d.verdict, d.tone, d.advance, d.shortcut])).toEqual(
+      plain.map((d) => [d.key, d.status, d.verdict, d.tone, d.advance, d.shortcut]),
+    );
+  });
+});

package/src/components/collection/index.ts

@@ -13,6 +13,8 @@ export {
   resolveReviewConfig,
   deriveReviewTransitions,
   reviewDecisions,
+  decisionLabel,
+  DEFAULT_DECISION_LABELS,
   applyDecisionToData,
   type ReviewDecision,
   pickStatusAttr,

package/src/components/collection/review.ts

@@ -169,6 +169,23 @@ export interface ReviewConfig {
   sourceAttrs?: string[];
   /** Drop the middle "Needs work" decision — a binary accept/reject flow (default false). */
   omitNeedsWork?: boolean;
+  /**
+   * What each decision is CALLED, by decision key ('approve' | 'needs_work' |
+   * 'reject'). Anything omitted keeps the generic default.
+   *
+   * WHY THIS EXISTS (bd startsim-b313v). The labels used to be string literals
+   * in `reviewDecisions` below, so every tenant's every reviewable type rendered
+   * the same three words. On OGMC that collided in the customer's hands: a
+   * reviewer approving a TOPIC ("this subject is worth writing") and a reviewer
+   * approving a DRAFT ("this piece is publishable") both pressed a button
+   * labelled "Approve", and she asked, mid-walkthrough, "so if I go, I click
+   * approve now, does it approve all of them?"
+   *
+   * A workspace cannot answer that from here — only the consumer knows what its
+   * records ARE — so the vocabulary is the consumer's to supply. Defaults are
+   * unchanged, so nothing that does not pass this renders differently.
+   */
+  decisionLabels?: Record<string, string>;
 }
 
 export interface ResolvedReview {
@@ -185,6 +202,7 @@ export interface ResolvedReview {
   metaAttrs: string[];
   sourceAttrs: string[];
   omitNeedsWork: boolean;
+  decisionLabels: Record<string, string>;
 }
 
 const DEFAULT_SOURCE_ATTRS = ['source_1', 'source_2', 'source_3', 'sources'];
@@ -216,9 +234,23 @@ export function resolveReviewConfig(
     // Keep source attrs the caller asked for; default to the ones this type declares.
     sourceAttrs: (config.sourceAttrs ?? DEFAULT_SOURCE_ATTRS).filter((a) => declared.has(a)),
     omitNeedsWork: config.omitNeedsWork ?? false,
+    decisionLabels: config.decisionLabels ?? {},
   };
 }
 
+/** The default name of a decision, when the consumer supplies none. */
+export const DEFAULT_DECISION_LABELS: Record<string, string> = {
+  approve: 'Approve',
+  needs_work: 'Needs work',
+  reject: 'Reject',
+};
+
+/** What a decision is called on THIS surface — the consumer's word, else the default. */
+export function decisionLabel(key: string, cfg: Pick<ResolvedReview, 'decisionLabels'>): string {
+  const supplied = cfg.decisionLabels?.[key];
+  return supplied && supplied.trim() ? supplied : DEFAULT_DECISION_LABELS[key] ?? key;
+}
+
 // ---- the single review decision (Approve / Needs work / Reject) ----
 //
 // status and team_verdict are two fields with different consumers (status = the
@@ -262,7 +294,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   if (r.transitions.approve) {
     out.push({
       key: 'approve',
-      label: 'Approve',
+      label: decisionLabel('approve', r),
       status: r.transitions.approve,
       verdict: verdictOf('good'),
       tone: 'good',
@@ -276,7 +308,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   if (!r.omitNeedsWork && entry && (editVerdict || entry !== r.transitions.approve)) {
     out.push({
       key: 'needs_work',
-      label: 'Needs work',
+      label: decisionLabel('needs_work', r),
       status: entry,
       verdict: editVerdict,
       tone: 'neutral',
@@ -289,7 +321,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   if (r.transitions.reject) {
     out.push({
       key: 'reject',
-      label: 'Reject',
+      label: decisionLabel('reject', r),
       status: r.transitions.reject,
       verdict: verdictOf('bad'),
       tone: 'bad',

package/src/components/validation/__tests__/check-policy.test.ts

@@ -0,0 +1,222 @@
+/**
+ * bd startsim-4muob (c)/(d) — check policy resolves per content type and language.
+ *
+ * ONE BLOG BAND WAS APPLIED TO EVERY CONTENT TYPE. `ContentChecksConfig` has
+ * always taken per-call band overrides, but nothing ever resolved them from the
+ * `content_type` the call site had in hand, so a weekly brief and a long-form
+ * evergreen guide were judged against the same 400–500 words.
+ *
+ * THE NUMBERS IN THIS FILE ARE FIXTURES, and must stay fixtures. Which band a
+ * real content type gets is a TENANT's editorial decision (bd startsim-wncr6);
+ * the day one customer's house style is written down in @startsimpli/ui is the
+ * day every other tenant starts shipping it. What this package owns is the
+ * mechanism and the defaults — so these tests prove the mechanism with content
+ * types no tenant has.
+ */
+import {
+  resolveCheckPolicy,
+  type CheckPolicySet,
+} from '../policy';
+import { runContentChecks } from '../checks';
+
+const words = (n: number) => Array.from({ length: n }, (_, i) => `w${i}`).join(' ');
+const blogBandOf = (set: CheckPolicySet, contentType?: string, language?: string) =>
+  resolveCheckPolicy(set, { contentType, language }).blogWords;
+
+/** A fixture tenant's policy. Arbitrary numbers, deliberately not anyone's. */
+const TENANT: CheckPolicySet = [
+  { contentType: 'short_form', policy: { blogWords: [300, 400] } },
+  { contentType: 'long_form', policy: { blogWords: [1200, 2000] } },
+  { contentType: 'plain_form', policy: { blogWords: [600, 800] } },
+];
+
+describe('(c) a content type resolves its own band', () => {
+  it('three content types yield three different blog bands', () => {
+    const short = blogBandOf(TENANT, 'short_form');
+    const long = blogBandOf(TENANT, 'long_form');
+    const plain = blogBandOf(TENANT, 'plain_form');
+
+    expect(short).toEqual([300, 400]);
+    expect(long).toEqual([1200, 2000]);
+    expect(plain).toEqual([600, 800]);
+    // Name the property the bug violated: they are not all the same band.
+    expect(new Set([short, long, plain].map((b) => String(b))).size).toBe(3);
+  });
+
+  it('the resolved band is what the check actually judges against', () => {
+    // 500 words: in band for the long-form type's floor? No — under it. In band
+    // for plain_form? No — under. The point is that ONE draft gets three
+    // different verdicts, which is exactly what a single shared band cannot do.
+    const draft = { blog: words(500) };
+    const verdict = (contentType: string) =>
+      runContentChecks(draft, resolveCheckPolicy(TENANT, { contentType })).find(
+        (c) => c.id === 'blog-words',
+      )!;
+
+    expect(verdict('short_form').status).toBe('warn'); // 100 over 300–400
+    expect(verdict('short_form').detail).toBe('500 words — 100 over (300–400)');
+    expect(verdict('long_form').status).toBe('warn'); // 700 under 1200–2000
+    expect(verdict('plain_form').status).toBe('warn'); // 100 under 600–800
+  });
+});
+
+describe('(d) an unknown or absent content type falls back — it never skips', () => {
+  const DEFAULT_BLOG_BAND = [400, 500];
+
+  it('an empty policy set resolves to the package defaults', () => {
+    expect(resolveCheckPolicy([], { contentType: 'anything' })).toEqual({});
+    const c = runContentChecks({ blog: words(450) }, resolveCheckPolicy([], {}));
+    expect(c.find((x) => x.id === 'blog-words')).toMatchObject({ status: 'pass' });
+  });
+
+  it('an unknown content type resolves exactly what an absent one does', () => {
+    expect(blogBandOf(TENANT, 'a_type_nobody_declared')).toEqual(blogBandOf(TENANT, undefined));
+  });
+
+  it('an unknown content type still RUNS the check, against today’s defaults', () => {
+    // The failure this guards: "we don't know your type, so we won't check" —
+    // a skipped check reads as a passing one on the rail (bd startsim-wncr6).
+    const checks = runContentChecks(
+      { blog: words(506) },
+      resolveCheckPolicy(TENANT, { contentType: 'a_type_nobody_declared' }),
+    );
+    const blog = checks.find((c) => c.id === 'blog-words');
+    expect(blog).toBeDefined();
+    expect(blog!.status).toBe('warn');
+    // Judged against the shared defaults, unchanged from before this bead.
+    expect(blog!.detail).toBe(`506 words — 6 over (${DEFAULT_BLOG_BAND[0]}–${DEFAULT_BLOG_BAND[1]})`);
+  });
+
+  it('does not throw on a null-ish or empty content type', () => {
+    expect(() => resolveCheckPolicy(TENANT, {})).not.toThrow();
+    expect(() => resolveCheckPolicy(TENANT, { contentType: '' })).not.toThrow();
+    expect(() => resolveCheckPolicy(TENANT, { contentType: undefined })).not.toThrow();
+  });
+});
+
+describe('the language dimension (bd startsim-wn2p.29 needs this seam, not its numbers)', () => {
+  const BILINGUAL: CheckPolicySet = [
+    { contentType: 'short_form', policy: { blogWords: [300, 400] } },
+    { language: 'zz', policy: { blogWords: [900, 1000] } },
+    { contentType: 'short_form', language: 'zz', policy: { blogWords: [700, 800] } },
+  ];
+
+  it('a language rule applies across content types', () => {
+    expect(blogBandOf(BILINGUAL, 'other_form', 'zz')).toEqual([900, 1000]);
+  });
+
+  it('matches on the primary subtag, so zz-XX picks up the zz rule', () => {
+    expect(blogBandOf(BILINGUAL, 'other_form', 'zz-XX')).toEqual([900, 1000]);
+  });
+
+  it('a rule naming BOTH beats a rule naming one, whatever the declaration order', () => {
+    expect(blogBandOf(BILINGUAL, 'short_form', 'zz')).toEqual([700, 800]);
+    // and again with the two-matcher rule declared FIRST, where plain
+    // last-one-wins would have let the single-matcher rules override it
+    const reversed: CheckPolicySet = [...BILINGUAL].reverse();
+    expect(blogBandOf(reversed, 'short_form', 'zz')).toEqual([700, 800]);
+  });
+
+  it('two SINGLE-dimension rules rank equal, so the tenant’s declaration order decides', () => {
+    // The case the tenant will actually hit: a Chinese evergreen matches both a
+    // content-type rule and a language rule. They do not combine — one wins
+    // outright — and this package must not be the thing that decides which of a
+    // tenant's two editorial axes outranks the other.
+    const typeThenLang: CheckPolicySet = [
+      { contentType: 'long_form', policy: { blogWords: [1200, 2000] } },
+      { language: 'zz', policy: { blogWords: [500, 620] } },
+    ];
+    expect(blogBandOf(typeThenLang, 'long_form', 'zz')).toEqual([500, 620]);
+
+    const langThenType: CheckPolicySet = [...typeThenLang].reverse();
+    expect(blogBandOf(langThenType, 'long_form', 'zz')).toEqual([1200, 2000]);
+  });
+
+  it('a combination gets its own band only when the tenant declares the combination', () => {
+    // Documented consequence: two independent rules never blend into a third.
+    // The right band for a Chinese evergreen is neither the English evergreen
+    // number nor the Chinese brief number (bd startsim-wn2p.29).
+    const withCross: CheckPolicySet = [
+      { contentType: 'long_form', policy: { blogWords: [1200, 2000] } },
+      { language: 'zz', policy: { blogWords: [500, 620] } },
+      { contentType: 'long_form', language: 'zz', policy: { blogWords: [1500, 2400] } },
+    ];
+    expect(blogBandOf(withCross, 'long_form', 'zz')).toEqual([1500, 2400]);
+    // …and the single-dimension rules still answer on their own.
+    expect(blogBandOf(withCross, 'long_form', 'en')).toEqual([1200, 2000]);
+    expect(blogBandOf(withCross, 'other_form', 'zz')).toEqual([500, 620]);
+  });
+
+  it('a language nobody declared falls back to the content type’s band', () => {
+    expect(blogBandOf(BILINGUAL, 'short_form', 'qq')).toEqual([300, 400]);
+  });
+});
+
+describe('merge semantics — spelled out because an unspoken one skips checks silently', () => {
+  it('a more specific rule overrides only the keys it names', () => {
+    const set: CheckPolicySet = [
+      { policy: { blogWords: [100, 200], headlineWords: [3, 4] } },
+      { contentType: 'short_form', policy: { blogWords: [300, 400] } },
+    ];
+    const resolved = resolveCheckPolicy(set, { contentType: 'short_form' });
+    expect(resolved.blogWords).toEqual([300, 400]);
+    // headlineWords was never mentioned by the specific rule, so it survives.
+    expect(resolved.headlineWords).toEqual([3, 4]);
+  });
+
+  it('an inherited `checks` allow-list CARRIES THROUGH a rule that does not mention it', () => {
+    // Decided, not accidental: a rule leaves untouched every key it does not
+    // name. So a tenant narrowing the check set tenant-wide keeps that narrowing
+    // when it later adds a per-type band. To widen it again, say so explicitly.
+    const set: CheckPolicySet = [
+      { policy: { checks: ['blog-words'] } },
+      { contentType: 'short_form', policy: { blogWords: [300, 400] } },
+    ];
+    expect(resolveCheckPolicy(set, { contentType: 'short_form' }).checks).toEqual(['blog-words']);
+  });
+
+  it('a declared `checks` list REPLACES an inherited one wholesale, it does not union', () => {
+    const set: CheckPolicySet = [
+      { policy: { checks: ['blog-words'] } },
+      { contentType: 'short_form', policy: { checks: ['headline-words'] } },
+    ];
+    expect(resolveCheckPolicy(set, { contentType: 'short_form' }).checks).toEqual(['headline-words']);
+  });
+});
+
+describe('which checks run is configuration too (bd startsim-wncr6 part 2)', () => {
+  const fields = { blog: words(450), headline: words(10), tags: 'a,b,c,d,e' };
+
+  it('with no allow-list, every check the fields support still runs', () => {
+    const ids = runContentChecks(fields, resolveCheckPolicy([], {})).map((c) => c.id).sort();
+    expect(ids).toEqual(['blog-words', 'headline-words', 'no-hype', 'tags-count']);
+  });
+
+  it('a tenant that does not care about word count can say so', () => {
+    // Quinn, 2026-08-25: "Is word count a check that we even care about based on
+    // what we're doing? … They don't have to be blog article checks."
+    const set: CheckPolicySet = [{ policy: { checks: ['no-hype', 'tags-count'] } }];
+    const ids = runContentChecks(fields, resolveCheckPolicy(set, {})).map((c) => c.id).sort();
+    expect(ids).toEqual(['no-hype', 'tags-count']);
+  });
+
+  it('the allow-list is per content type, like the bands', () => {
+    const set: CheckPolicySet = [
+      { policy: { checks: ['blog-words', 'headline-words', 'no-hype', 'tags-count'] } },
+      { contentType: 'short_form', policy: { checks: ['headline-words'] } },
+    ];
+    expect(runContentChecks(fields, resolveCheckPolicy(set, { contentType: 'short_form' })).map((c) => c.id))
+      .toEqual(['headline-words']);
+    expect(runContentChecks(fields, resolveCheckPolicy(set, { contentType: 'other_form' })).map((c) => c.id).sort())
+      .toEqual(['blog-words', 'headline-words', 'no-hype', 'tags-count']);
+  });
+
+  it('an empty allow-list runs NOTHING, and is distinct from an absent one', () => {
+    // `[]` is a tenant saying "no deterministic checks", which is a real answer.
+    // `undefined` is "you decide", which means all of them. They must not be the
+    // same value — the approved-sources check learned that the hard way
+    // (bd startsim-4ipm: `approvedHosts: []` failed every host on earth).
+    expect(runContentChecks(fields, { checks: [] })).toEqual([]);
+    expect(runContentChecks(fields, {}).length).toBeGreaterThan(0);
+  });
+});

package/src/components/validation/__tests__/checks.test.ts

@@ -44,7 +44,7 @@ describe('runContentChecks — field presence', () => {
 describe('word-count bands', () => {
   it('blog: in-band 400–500 passes, outside warns, with a "N words" detail', () => {
     expect(find(runContentChecks({ blog: words(450) }), 'blog-words')).toMatchObject({ status: 'pass', detail: '450 words' });
-    expect(find(runContentChecks({ blog: words(300) }), 'blog-words')).toMatchObject({ status: 'warn', detail: '300 words' });
+    expect(find(runContentChecks({ blog: words(300) }), 'blog-words')).toMatchObject({ status: 'warn', detail: '300 words — 100 under (400–500)' });
     expect(find(runContentChecks({ blog: words(600) }), 'blog-words')!.status).toBe('warn');
     // inclusive edges
     expect(find(runContentChecks({ blog: words(400) }), 'blog-words')!.status).toBe('pass');
@@ -341,3 +341,56 @@ describe('source-overlap check', () => {
     expect(c!.status).toBe('pass');
   });
 });
+
+describe('bd startsim-4muob (a)/(b) — a band check says which way it missed', () => {
+  /**
+   * THE MEETING, 2026-08-25. The rail read "Blog word count — 506 words" as a
+   * notice. In the room Quinn guessed the band was a ~800-word MINIMUM and
+   * offered to lower it; Malin pushed back that briefs are 400–500. The band was
+   * already [400, 500] and the draft was SIX WORDS OVER THE TOP. Nobody present
+   * could tell which direction it had missed — including the author of the check.
+   *
+   * A flag a reviewer cannot act on spends the goodwill the rail runs on.
+   */
+  it('(a) states the overshoot and the band when the count is OVER', () => {
+    expect(find(runContentChecks({ blog: words(506) }), 'blog-words')).toMatchObject({
+      status: 'warn',
+      detail: '506 words — 6 over (400–500)',
+    });
+  });
+
+  it('(a) states the shortfall and the band when the count is UNDER', () => {
+    expect(find(runContentChecks({ blog: words(312) }), 'blog-words')).toMatchObject({
+      status: 'warn',
+      detail: '312 words — 88 under (400–500)',
+    });
+  });
+
+  it('(b) an in-band check does not editorialise — it is still a bare count', () => {
+    // Green rows are read at a glance and never acted on. Spending the narrow
+    // rail column on "450 words — in the 400–500 band" says nothing new.
+    expect(find(runContentChecks({ blog: words(450) }), 'blog-words')!.detail).toBe('450 words');
+    expect(find(runContentChecks({ blog: words(400) }), 'blog-words')!.detail).toBe('400 words');
+    expect(find(runContentChecks({ blog: words(500) }), 'blog-words')!.detail).toBe('500 words');
+  });
+
+  it('(a) applies to EVERY band check, not just the blog one', () => {
+    // headline-words, linkedin-words, tags-count and meta-length all ran the
+    // same bandStatus + bare-detail pattern, so all four missed the same way.
+    expect(find(runContentChecks({ headline: words(5) }), 'headline-words')!.detail)
+      .toBe('5 words — 3 under (8–12)');
+    expect(find(runContentChecks({ linkedin: words(300) }), 'linkedin-words')!.detail)
+      .toBe('300 words — 50 over (150–250)');
+    expect(find(runContentChecks({ tags: 'a,b' }), 'tags-count')!.detail)
+      .toBe('2 tags — 2 under (4–6)');
+    expect(find(runContentChecks({ metaDescription: 'x'.repeat(200) }), 'meta-length')!.detail)
+      .toBe('200 chars — 40 over (150–160)');
+  });
+
+  it('(a) reports the band it was ACTUALLY judged against, not the default', () => {
+    // The bug's other half: a reviewer told "(400–500)" when the tenant configured
+    // something else would be misled twice over.
+    expect(find(runContentChecks({ blog: words(900) }, { blogWords: [1000, 1200] }), 'blog-words')!.detail)
+      .toBe('900 words — 100 under (1000–1200)');
+  });
+});

package/src/components/validation/checks.ts

@@ -69,12 +69,51 @@ export interface ContentFields {
 /** An inclusive `[min, max]` band. */
 export type Band = [min: number, max: number];
 
+/**
+ * Every check this package implements, in the order `runContentChecks` emits
+ * them. Exported so a tenant can name the ones it wants (see `checks` below)
+ * and so a typo in that list is a compile error rather than a silently empty
+ * rail.
+ *
+ * A tenant's OWN checks are not in here and do not belong in here: they are
+ * computed by the tenant and appended to the returned array, the way
+ * marketing-agents already appends its approved-source stand-in.
+ */
+export const CONTENT_CHECK_IDS = [
+  'headline-words',
+  'blog-words',
+  'linkedin-words',
+  'tags-count',
+  'meta-length',
+  'link-placeholder',
+  'no-hype',
+  'approved-sources',
+  'source-overlap',
+] as const;
+
+/** The id of a check implemented by this package. */
+export type ContentCheckId = (typeof CONTENT_CHECK_IDS)[number];
+
 /**
  * Tunable thresholds. Everything has a sensible default EXCEPT `approvedHosts`:
  * the source allow-list is deliberately app-injected (no hardcoded list here),
  * so the approved-sources check is skipped entirely when it is omitted.
  */
 export interface ContentChecksConfig {
+  /**
+   * WHICH checks run. Omitted = every check the supplied fields support (the
+   * behaviour before bd startsim-wncr6, and the right default for a caller that
+   * has no opinion). Present = exactly these, so a tenant can answer "is word
+   * count a check we even care about?" with a list instead of a fork.
+   *
+   * `[]` runs nothing and is deliberately DISTINCT from omitting the key — the
+   * approved-source check learned that lesson the expensive way (bd
+   * startsim-4ipm: `approvedHosts: []` is "fail every host", not "skip").
+   *
+   * Normally resolved per content type and language by `resolveCheckPolicy`
+   * (./policy) rather than written out here.
+   */
+  checks?: readonly ContentCheckId[];
   /** Blog word-count band (default 400–500). */
   blogWords?: Band;
   /** LinkedIn word-count band (default 150–250). */
@@ -227,6 +266,30 @@ function bandStatus(n: number, [min, max]: Band): CheckStatus {
   return n >= min && n <= max ? 'pass' : 'warn';
 }
 
+/**
+ * A band check's `detail`, which now says which way it missed (bd startsim-ztlz7).
+ *
+ * WHY. On 2026-08-25 the quality rail showed "Blog word count — 506 words" as a
+ * notice in front of a customer. The band was already [400, 500] and the draft
+ * was SIX WORDS OVER THE TOP — but the row said only "506 words", so the guess in
+ * the room was that the band was an ~800-word MINIMUM, and an offer was made to
+ * lower it. The author of the check could not read his own check either. A
+ * number without its band is not a finding; it is a number.
+ *
+ * IN-BAND STAYS BARE. A green row is read at a glance and never acted on;
+ * spending the rail's narrow column on "450 words — in the 400–500 band" tells a
+ * reviewer nothing they were about to do something about.
+ *
+ * The band printed is the band the check was ACTUALLY judged against, so a tenant
+ * running its own numbers (./policy) is never shown the package default.
+ */
+function bandDetail(n: number, [min, max]: Band, unit: string): string {
+  const count = `${n} ${unit}`;
+  if (n < min) return `${count} — ${min - n} under (${min}–${max})`;
+  if (n > max) return `${count} — ${n - max} over (${min}–${max})`;
+  return count;
+}
+
 /**
  * `locations` for a whole-field problem (word/char counts, a missing
  * placeholder): the field itself is the finding, so there is no span to
@@ -259,6 +322,7 @@ export function hostOf(url: string): string {
 export function runContentChecks(fields: ContentFields, config: ContentChecksConfig = {}): ContentCheck[] {
   const checks: ContentCheck[] = [];
   const {
+    checks: enabled,
     blogWords = DEFAULTS.blogWords,
     linkedinWords = DEFAULTS.linkedinWords,
     headlineWords = DEFAULTS.headlineWords,
@@ -273,39 +337,52 @@ export function runContentChecks(fields: ContentFields, config: ContentChecksCon
     overlapFailRatio = 0.25,
   } = config;
 
+  /**
+   * Is this check switched on? No allow-list = all of them, so every existing
+   * caller is unaffected.
+   *
+   * Note what this does NOT do: it never drops a check because something about
+   * the draft was unrecognised. A check the tenant did not ask for is absent
+   * because the tenant said so; a check that could not be COMPUTED must be
+   * surfaced by the caller as its own not-checked row, never left out (bd
+   * startsim-4ipm, and the reason `resolveCheckPolicy` falls back rather than
+   * skips on an unknown content type).
+   */
+  const runs = (id: ContentCheckId): boolean => enabled === undefined || enabled.includes(id);
+
   // Word-count bands.
-  if (fields.headline !== undefined) {
+  if (runs('headline-words') && fields.headline !== undefined) {
     const n = wordCount(fields.headline);
     const status = bandStatus(n, headlineWords);
-    checks.push({ id: 'headline-words', label: 'Headline length', status, detail: `${n} words`, ...fieldLocation(status, 'headline') });
+    checks.push({ id: 'headline-words', label: 'Headline length', status, detail: bandDetail(n, headlineWords, 'words'), ...fieldLocation(status, 'headline') });
   }
-  if (fields.blog !== undefined) {
+  if (runs('blog-words') && fields.blog !== undefined) {
     const n = wordCount(fields.blog);
     const status = bandStatus(n, blogWords);
-    checks.push({ id: 'blog-words', label: 'Blog word count', status, detail: `${n} words`, ...fieldLocation(status, 'blog') });
+    checks.push({ id: 'blog-words', label: 'Blog word count', status, detail: bandDetail(n, blogWords, 'words'), ...fieldLocation(status, 'blog') });
   }
-  if (fields.linkedin !== undefined) {
+  if (runs('linkedin-words') && fields.linkedin !== undefined) {
     const n = wordCount(fields.linkedin);
     const status = bandStatus(n, linkedinWords);
-    checks.push({ id: 'linkedin-words', label: 'LinkedIn word count', status, detail: `${n} words`, ...fieldLocation(status, 'linkedin') });
+    checks.push({ id: 'linkedin-words', label: 'LinkedIn word count', status, detail: bandDetail(n, linkedinWords, 'words'), ...fieldLocation(status, 'linkedin') });
   }
 
   // Tag count.
-  if (fields.tags !== undefined) {
+  if (runs('tags-count') && fields.tags !== undefined) {
     const n = tagCount(fields.tags);
     const status = bandStatus(n, tagsCount);
-    checks.push({ id: 'tags-count', label: 'Tag count', status, detail: `${n} tags`, ...fieldLocation(status, 'tags') });
+    checks.push({ id: 'tags-count', label: 'Tag count', status, detail: bandDetail(n, tagsCount, 'tags'), ...fieldLocation(status, 'tags') });
   }
 
   // Meta description length (characters).
-  if (fields.metaDescription !== undefined) {
+  if (runs('meta-length') && fields.metaDescription !== undefined) {
     const len = fields.metaDescription.trim().length;
     const status = bandStatus(len, metaChars);
-    checks.push({ id: 'meta-length', label: 'Meta description length', status, detail: `${len} chars`, ...fieldLocation(status, 'metaDescription') });
+    checks.push({ id: 'meta-length', label: 'Meta description length', status, detail: bandDetail(len, metaChars, 'chars'), ...fieldLocation(status, 'metaDescription') });
   }
 
   // `[link]` placeholder present in the LinkedIn post.
-  if (requireLink && fields.linkedin !== undefined) {
+  if (requireLink && runs('link-placeholder') && fields.linkedin !== undefined) {
     const has = fields.linkedin.includes('[link]');
     const status: CheckStatus = has ? 'pass' : 'warn';
     checks.push({
@@ -326,7 +403,7 @@ export function runContentChecks(fields: ContentFields, config: ContentChecksCon
     ['linkedin', fields.linkedin],
   ];
   const hasProse = proseFields.some(([, text]) => text !== undefined);
-  if (hasProse) {
+  if (hasProse && runs('no-hype')) {
     const haystack = proseFields
       .map(([, text]) => text)
       .filter((s): s is string => typeof s === 'string')
@@ -354,7 +431,7 @@ export function runContentChecks(fields: ContentFields, config: ContentChecksCon
   }
 
   // Approved sources — only when the app supplied an allow-list.
-  if (approvedHosts !== undefined) {
+  if (approvedHosts !== undefined && runs('approved-sources')) {
     const approved = approvedHosts.map((h) => h.toLowerCase().replace(/^www\./, ''));
     /**
      * A host is approved when it IS an approved domain or is a SUBDOMAIN of one.
@@ -400,7 +477,7 @@ export function runContentChecks(fields: ContentFields, config: ContentChecksCon
   // Verbatim overlap — the anti-plagiarism guardrail. Only when the caller supplied
   // the cited source article TEXT. Scans blog + linkedin against the sources and
   // reports the WORST offender (longest copied run / highest copied fraction).
-  if (sourceTexts !== undefined && sourceTexts.length > 0) {
+  if (sourceTexts !== undefined && sourceTexts.length > 0 && runs('source-overlap')) {
     const targets: Array<[keyof ContentFields, string | undefined]> = [
       ['blog', fields.blog],
       ['linkedin', fields.linkedin],

package/src/components/validation/index.ts

@@ -20,6 +20,8 @@ export {
   extractUrls,
   hostOf,
   DEFAULT_HYPE_WORDS,
+  CONTENT_CHECK_IDS,
+  type ContentCheckId,
   type ContentCheck,
   type CheckLocation,
   type ContentFields,
@@ -30,6 +32,19 @@ export {
 
 export { verbatimOverlap, normWords, type OverlapResult } from './overlap';
 
+/**
+ * Which checks run and with what bands, resolved per content type and language.
+ * A tenant declares the policy; this package keeps the implementations and the
+ * defaults (bd startsim-wncr6).
+ */
+export {
+  resolveCheckPolicy,
+  type CheckPolicy,
+  type CheckPolicyRule,
+  type CheckPolicySet,
+  type CheckContext,
+} from './policy';
+
 export { ValidationChecklist } from './ValidationChecklist';
 export type {
   ValidationChecklistProps,

package/src/components/validation/policy.ts

@@ -0,0 +1,197 @@
+/**
+ * Which checks run, and against what thresholds — resolved per content type and
+ * per language (bd startsim-wncr6). Pure + framework-free, like `checks.ts`.
+ *
+ * ── THE BUG THIS EXISTS FOR ──────────────────────────────────────────────────
+ * `ContentChecksConfig` has always taken per-call band overrides, but nothing
+ * ever resolved them from the `content_type` the call site had in hand. So a
+ * weekly brief ("short, current news") and a long-form evergreen guide ("much
+ * more in-depth, much bigger scope") were both judged against one 400–500 word
+ * band, and the same single band was applied to Chinese translations, where a
+ * faithful rendering of a 507-word English brief segments to ~609 words and
+ * therefore fails forever (bd startsim-wn2p.29).
+ *
+ * ── THE REQUIREMENT, WHICH IS BIGGER THAN THRESHOLDS ─────────────────────────
+ * Quinn, 2026-08-25: "Is word count a check that we even care about based on
+ * what we're doing? Or is it something else — rank how sensational we think it
+ * is, or how many source data pieces we have. They don't have to be blog
+ * article checks. They can be OGMC-specific checks that you guys want."
+ *
+ * So the CHECK SET is configuration too, not only its numbers. A rule may name
+ * `checks` as well as bands; this package supplies the implementations and the
+ * defaults, a tenant supplies the policy.
+ *
+ * ── TWO THINGS THIS FILE MUST NOT BECOME ─────────────────────────────────────
+ * 1. A HOME FOR ONE CUSTOMER'S EDITORIAL STANDARDS. There is not a single
+ *    content_type value, locale or band in this file, and there must never be.
+ *    @startsimpli/ui ships to every tenant; OGMC's `weekly_brief` band is
+ *    OGMC's, declared in marketing-agents-web. The mirror of that rule is just
+ *    as binding: a tenant must not fork a private copy of the CHECKS either —
+ *    bd startsim-wn2p.28 cost four PRs because one word count had been written
+ *    in four places.
+ * 2. A WAY TO SKIP A CHECK BY ACCIDENT. An unknown content type resolves to
+ *    whatever the less specific rules said, ending at this package's defaults.
+ *    It never resolves to "no check": a check that silently vanishes reads on
+ *    the rail exactly like a check that passed. The sibling failure mode, from
+ *    the same epic, is a band that CANNOT be satisfied by correct output — a
+ *    permanent red trains reviewers to ignore the whole rail, which is why the
+ *    language dimension exists rather than one band for every script.
+ */
+import type { ContentChecksConfig } from './checks';
+
+/**
+ * A tenant's standing policy for one situation: which checks run, and their
+ * thresholds.
+ *
+ * `approvedHosts` and `sourceTexts` are deliberately NOT part of a policy —
+ * they are facts about the draft in front of you (the tenant's live source
+ * records, the cited articles' text), resolved per render and merged in by the
+ * caller. Standing policy and per-draft evidence are different things and a
+ * tenant that confuses them ends up caching one as the other.
+ */
+export type CheckPolicy = Omit<ContentChecksConfig, 'approvedHosts' | 'sourceTexts'>;
+
+/**
+ * One rule: a policy plus the situations it applies to. Omit both matchers and
+ * the rule is the tenant-wide baseline.
+ *
+ * Matching is deliberately dumb — exact `content_type` values and a language
+ * subtag — because the values are the tenant's own schema enum and its own
+ * locale codes. This package knows none of them and must not pretend to.
+ */
+export interface CheckPolicyRule {
+  /**
+   * The `content_type` value(s) this rule applies to, matched exactly (after a
+   * trim) against the tenant's own enum. Omitted = any content type.
+   */
+  contentType?: string | readonly string[];
+  /**
+   * The language(s) this rule applies to, as BCP-47 tags matched on the primary
+   * subtag: a rule for `zh` applies to `zh`, `zh-CN` and `zh-Hans-CN`; a rule
+   * for `zh-Hans` applies to `zh-Hans-CN` but not to bare `zh`. Case-insensitive.
+   * Omitted = any language.
+   */
+  language?: string | readonly string[];
+  /** What to apply when this rule matches. */
+  policy: CheckPolicy;
+}
+
+/** A tenant's whole policy, as an ordered list of rules. */
+export type CheckPolicySet = readonly CheckPolicyRule[];
+
+/** What is being checked, as far as policy is concerned. */
+export interface CheckContext {
+  /** The draft's `content_type`, straight off the record. Unknown values are fine. */
+  contentType?: string | null;
+  /** The draft's language as a BCP-47 tag (`en`, `zh-CN`). Unknown values are fine. */
+  language?: string | null;
+}
+
+/** Normalise a matcher to a list of non-empty trimmed strings; null = "matches anything". */
+function matcherList(value: string | readonly string[] | undefined): string[] | null {
+  if (value === undefined) return null;
+  const list = Array.isArray(value) ? [...value] : [value as string];
+  return list.map((v) => String(v).trim()).filter(Boolean);
+}
+
+/**
+ * A language tag matches a rule when it IS the rule's tag or is a more specific
+ * form of it. The hyphen is load-bearing for the same reason it is in the
+ * approved-host check: without it `zho` would match a rule written for `zh`.
+ */
+function languageMatches(ruleTag: string, contextTag: string): boolean {
+  const rule = ruleTag.toLowerCase();
+  const ctx = contextTag.toLowerCase();
+  return ctx === rule || ctx.startsWith(`${rule}-`);
+}
+
+/** Does this rule apply? A matcher the context cannot answer simply does not match. */
+function ruleApplies(rule: CheckPolicyRule, context: CheckContext): boolean {
+  const types = matcherList(rule.contentType);
+  if (types !== null) {
+    const contentType = (context.contentType ?? '').trim();
+    if (!contentType || !types.includes(contentType)) return false;
+  }
+  const languages = matcherList(rule.language);
+  if (languages !== null) {
+    const language = (context.language ?? '').trim();
+    if (!language || !languages.some((tag) => languageMatches(tag, language))) return false;
+  }
+  return true;
+}
+
+/**
+ * How specific a rule is: simply HOW MANY dimensions it names. Naming both
+ * outranks naming either, so a tenant can write its rules in whatever order
+ * reads best and still get the answer it meant.
+ *
+ * The two single-dimension rules rank EQUAL on purpose. Ranking content type
+ * above language (or the reverse) would mean that, for a Chinese evergreen
+ * draft, a rule for `lead_magnet` silently swallowed a rule for `zh` — and this
+ * package has no business deciding which of a tenant's two editorial axes is the
+ * more important one. Between equals the later declaration wins, so the tenant
+ * says which, in the order it writes them.
+ */
+function specificity(rule: CheckPolicyRule): number {
+  return (rule.contentType !== undefined ? 1 : 0) + (rule.language !== undefined ? 1 : 0);
+}
+
+/**
+ * Resolve a tenant's policy for one draft into the config `runContentChecks`
+ * takes. Pure. Never throws on an unrecognised content type or language.
+ *
+ * MERGE SEMANTICS, spelled out because leaving them unspoken is how a check goes
+ * missing: matching rules are applied least-specific first, and each one
+ * overrides ONLY the keys it names. A key a rule does not mention keeps whatever
+ * a less specific rule set, ending at this package's defaults.
+ *
+ * TWO SINGLE-DIMENSION RULES DO NOT COMBINE, and this is the sharp edge. A rule
+ * for content type `lead_magnet` and a rule for language `zh` both match a
+ * Chinese evergreen draft, rank equal, and so the LATER one wins outright — the
+ * other's bands are not blended in. A tenant that wants a distinct number for a
+ * combination must declare that combination, which is what the two-matcher rule
+ * is for. Blending would be worse, not better: the right band for a Chinese
+ * evergreen is neither the English evergreen number nor the Chinese brief number,
+ * and quietly synthesising a third from them is how you get a band that correct
+ * output cannot satisfy (bd startsim-wn2p.29).
+ *
+ * That cuts both ways on the `checks` allow-list, and this is the deliberate
+ * half: a tenant that narrows the check set tenant-wide KEEPS that narrowing in
+ * a per-type rule that only adjusts a band. To widen it again, the specific rule
+ * says so — and when it does, its list REPLACES the inherited one outright
+ * rather than being unioned with it, so "these are the checks for evergreen" is
+ * readable as exactly that.
+ *
+ * @example
+ * // In the TENANT, never here — these are its enum values and its numbers.
+ * const POLICY: CheckPolicySet = [
+ *   { contentType: 'weekly_brief', policy: { blogWords: [400, 500] } },
+ *   { language: 'zh', policy: { metaChars: [60, 80] } },
+ *   // A combination needs its own rule — the two above would not merge into it.
+ *   { contentType: 'weekly_brief', language: 'zh', policy: { blogWords: [500, 620] } },
+ * ];
+ * runContentChecks(fields, {
+ *   ...resolveCheckPolicy(POLICY, { contentType, language }),
+ *   ...approvedSourceCheckConfig(basis), // per-draft evidence, not policy
+ * });
+ */
+export function resolveCheckPolicy(
+  policies: CheckPolicySet,
+  context: CheckContext = {},
+): CheckPolicy {
+  const matching = (policies ?? [])
+    .map((rule, index) => ({ rule, index }))
+    .filter(({ rule }) => rule && ruleApplies(rule, context))
+    .sort((a, b) => specificity(a.rule) - specificity(b.rule) || a.index - b.index);
+
+  const resolved: Record<string, unknown> = {};
+  for (const { rule } of matching) {
+    for (const [key, value] of Object.entries(rule.policy ?? {})) {
+      // An absent key means "no opinion", so it must not erase what a less
+      // specific rule decided — otherwise spreading a partial object over a
+      // policy would silently reset half of it.
+      if (value !== undefined) resolved[key] = value;
+    }
+  }
+  return resolved as CheckPolicy;
+}