Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

fix(content): put a number, name or quote the brief's sources don't have as a placeholder (brief rules 2026, PR 1) (#1535)

Cihan665c8154a257
diff --git a/server/src/lib/content-brief.js b/server/src/lib/content-brief.js
index 64f203ed0..dd08108de 100644
--- a/server/src/lib/content-brief.js
+++ b/server/src/lib/content-brief.js
@@ -14,6 +14,8 @@ import {
stopIfStopped,
} from './content-runs.js';
import { citedPagesLength } from './content-cited-length.js';
+import { guardPeople, knownPeople } from './content-people.js';
+import { knownNumbers, placeholderNumbers, todayText } from './content-sources.js';
import { reserveAiBudget } from './plan-guard.js';
/**
@@ -130,6 +132,19 @@ Rules:
const norm = (text) => text.trim().replace(/\s+/g, ' ').toLowerCase();
+/**
+ * Text cut to `max` characters, never inside a placeholder: one the cut would
+ * split ("[figure, so") goes whole.
+ */
+const clip = (text, max) => {
+ const cut = text.trim().slice(0, max);
+ const open = cut.lastIndexOf('[');
+ return open > cut.lastIndexOf(']') ? cut.slice(0, open).trimEnd() : cut;
+};
+
+/** A question in quotes ("Which machine should I buy?"): one to answer, not a person's words. */
+const QUOTED_QUESTION = /["“„«»]([^"“”„«»\n]{1,300}\?)["”“»«]/gu;
+
/**
* Builds the brief: reads the draft and its brand, keeps the prompts that are
* the brand's, charges the AI usage budget, asks the model, and saves the
@@ -242,13 +257,25 @@ async function briefWithRun({ draft, draftId, brand, prompts, sources, run }) {
// Each H2 matched to the fan-out it answers (mapOutline).
await advanceRun(run, 2);
+ // What it adds beyond what it was built from goes as a placeholder, before the cut.
+ const guard = briefGuard({ brand, draft, prompts, sources });
const brief = {
- goal: object.goal.trim().slice(0, BRIEF_LIMITS.goal),
- audience: object.audience.trim().slice(0, BRIEF_LIMITS.audience),
- outline: mapOutline(object.outline, sources.fanouts),
+ goal: clip(guard.text(object.goal), BRIEF_LIMITS.goal),
+ audience: clip(guard.text(object.audience), BRIEF_LIMITS.audience),
+ outline: mapOutline(
+ object.outline.map((section) => ({
+ ...section,
+ heading: guard.heading(section.heading),
+ keyPoints: (section.keyPoints ?? []).map((point) => guard.text(point)),
+ })),
+ sources.fanouts,
+ ),
keywords: [
...new Set(
- object.keywords.map((k) => k.trim().slice(0, BRIEF_LIMITS.keyword)).filter(Boolean),
+ object.keywords
+ .filter(guard.keeps)
+ .map((k) => k.trim().slice(0, BRIEF_LIMITS.keyword))
+ .filter(Boolean),
),
].slice(0, BRIEF_LIMITS.keywords),
origin: 'rebuild',
@@ -271,6 +298,43 @@ async function briefWithRun({ draft, draftId, brand, prompts, sources, run }) {
return brief;
}
+/**
+ * What a brief may say without a placeholder: the numbers (CE-033), names
+ * and quotes (CE-044) of what it was built from — the brand, the page, the
+ * prompts, searches, queries and headings kept, the length asked for — and
+ * today's year. The writer reads a brief as something it was given, so a
+ * figure or a person made up in one would pass the writer's own guard.
+ * `text` and `heading` put each one added as a placeholder, as a written
+ * page's are, a question in quotes aside; `keeps` drops a keyword that adds
+ * one, as a placeholder can't be searched for.
+ */
+export function briefGuard({ brand, draft, prompts, sources }) {
+ const given = [
+ brand?.name,
+ brand?.industry,
+ brand?.description,
+ draft.title,
+ ...prompts,
+ ...sources.fanouts.map((f) => f.query),
+ ...sources.queries,
+ ...sources.headings,
+ String(sources.length),
+ ];
+ const known = knownNumbers(...given, todayText());
+ const people = knownPeople(...given);
+ const text = (words, heading = false) => {
+ const numbered = placeholderNumbers(words ?? '', known);
+ const questions = [...numbered.matchAll(QUOTED_QUESTION)].map((m) => m[1]);
+ const asked = questions.length ? knownPeople(...given, ...questions) : people;
+ return guardPeople(numbered, asked, { heading }).text;
+ };
+ return {
+ text,
+ heading: (words) => text(words, true),
+ keeps: (keyword) => text(keyword) === String(keyword ?? ''),
+ };
+}
+
/**
* Keeps an H2's fan-out only when it is one the person kept, written as
* listed, and its platform only when that search ran there. Cut to the
@@ -287,9 +351,9 @@ export function mapOutline(outline, fanouts) {
? section.platform
: (fanout?.platforms[0] ?? null);
return {
- heading: (section.heading ?? '').trim().slice(0, BRIEF_LIMITS.heading),
+ heading: clip(section.heading ?? '', BRIEF_LIMITS.heading),
keyPoints: (section.keyPoints ?? [])
- .map((p) => p.trim().slice(0, BRIEF_LIMITS.keyPoint))
+ .map((p) => clip(p, BRIEF_LIMITS.keyPoint))
.filter(Boolean)
.slice(0, BRIEF_LIMITS.keyPoints),
fanout: fanout?.query ?? null,
diff --git a/server/src/lib/content-brief.test.js b/server/src/lib/content-brief.test.js
index e1bd7dee5..73a5ab15c 100644
--- a/server/src/lib/content-brief.test.js
+++ b/server/src/lib/content-brief.test.js
@@ -62,8 +62,10 @@ vi.mock('./content-runs.js', async (importOriginal) => ({
stopIfStopped: (...args) => stopIfStopped(...args),
}));
-const { buildBriefPrompt, mapOutline, rebuildDraftBrief, rebuildSources } =
+const { briefGuard, buildBriefPrompt, mapOutline, rebuildDraftBrief, rebuildSources } =
await import('./content-brief.js');
+const { NAME_PLACEHOLDER, QUOTE_PLACEHOLDER } = await import('./content-people.js');
+const { NUMBER_PLACEHOLDER } = await import('./content-sources.js');
const { PlanLimitError } = await import('./plan-guard.js');
// The real hold: self-hosted here, so it reserves nothing and writes each charge.
const realGuard = await vi.importActual('./plan-guard.js');
@@ -133,6 +135,61 @@ beforeEach(() => {
});
describe('rebuildDraftBrief', () => {
+ it('puts a number, name or quote its sources don\u2019t have as a placeholder, as the writer would', async () => {
+ const year = new Date().getUTCFullYear();
+ generateObject.mockResolvedValue({
+ object: {
+ goal: 'Win 73% of home baristas',
+ audience: 'Home baristas who drink 4 cups a day',
+ outline: [
+ {
+ heading: 'The 12 best espresso machines under $500',
+ keyPoints: [
+ 'Dr. Jane Doe recommends a flat burr',
+ '"Pressure matters far more than price," says the owner',
+ 'Machines under 500 dollars',
+ 'Compare 3 grinders',
+ `The best machines of ${year}`,
+ ],
+ fanout: 'home espresso grinder',
+ platform: 'copilot-web',
+ },
+ ],
+ keywords: ['espresso', 'top 12 espresso machines', 'espresso under 500'],
+ },
+ usage: { inputTokens: 1000, outputTokens: 500 },
+ });
+
+ const brief = await rebuildDraftBrief({ draftId: DRAFT, brandId: BRAND, sources: sources() });
+
+ expect(brief.goal).toBe(`Win ${NUMBER_PLACEHOLDER} of home baristas`);
+ // A lone digit is a count, as on a page.
+ expect(brief.audience).toBe('Home baristas who drink 4 cups a day');
+ expect(brief.outline).toEqual([
+ {
+ // A heading's number as a page's: "$500" is the prompt's.
+ heading: `The ${NUMBER_PLACEHOLDER} best espresso machines under $500`,
+ keyPoints: [
+ `${NAME_PLACEHOLDER} recommends a flat burr`,
+ `${QUOTE_PLACEHOLDER} says the owner`,
+ // The fan-out's number, a count and this year stay.
+ 'Machines under 500 dollars',
+ 'Compare 3 grinders',
+ `The best machines of ${year}`,
+ ],
+ fanout: 'home espresso grinder',
+ platform: 'copilot-web',
+ },
+ ]);
+ // A keyword that adds one goes: a placeholder can't be searched for.
+ expect(brief.keywords).toEqual(['espresso', 'espresso under 500']);
+ expect(draftWrites().at(-1)).toEqual({
+ table: 'content_drafts',
+ op: 'update',
+ value: { brief },
+ });
+ });
+
it('writes the brief from the kept sources, charges AI usage, and saves it on the draft', async () => {
const brief = await rebuildDraftBrief({ draftId: DRAFT, brandId: BRAND, sources: sources() });
@@ -255,18 +312,24 @@ describe('rebuildDraftBrief', () => {
{ heading: ' ', keyPoints: ['Lost'], fanout: null, platform: null },
{
heading: 'h'.repeat(400),
- keyPoints: Array.from({ length: 10 }, (_, i) => `${i}`.repeat(600)),
+ // Letters: a number the sources don't have would go as a placeholder.
+ keyPoints: Array.from({ length: 10 }, (_, i) =>
+ String.fromCharCode(97 + i).repeat(600),
+ ),
fanout: null,
platform: null,
},
...Array.from({ length: 14 }, (_, i) => ({
- heading: `Section ${i}`,
+ heading: `Section ${String.fromCharCode(97 + i)}`,
keyPoints: [],
fanout: null,
platform: null,
})),
],
- keywords: Array.from({ length: 20 }, (_, i) => `${i} ${'k'.repeat(90)}`),
+ keywords: Array.from(
+ { length: 20 },
+ (_, i) => `${String.fromCharCode(97 + i)}${'k'.repeat(90)}`,
+ ),
},
usage: { inputTokens: 1000, outputTokens: 500 },
});
@@ -351,6 +414,88 @@ describe('rebuildSources', () => {
});
});
+describe('the brief guard', () => {
+ const guardFor = (over = {}) =>
+ briefGuard({
+ brand: { name: 'Acme 24', industry: null, description: 'Roasting since 1998' },
+ draft: { title: 'The 2019 espresso guide' },
+ prompts: ['Who is Ada Lovelace?'],
+ sources: sources({ headings: ['Our 7-day trial'] }),
+ ...over,
+ });
+
+ it('knows what the brief was built from: the brand, the page, its sources and the length', () => {
+ const guard = guardFor();
+ for (const text of [
+ 'Acme 24 has roasted since 1998',
+ 'Update the 2019 guide',
+ 'Keep the 7-day trial',
+ 'About 3,000 characters',
+ 'Machines under 500',
+ 'Ask Ada Lovelace',
+ ]) {
+ expect(guard.text(text)).toBe(text);
+ }
+ });
+
+ it('puts what it adds as a placeholder, and drops a keyword that adds one', () => {
+ const guard = guardFor();
+ expect(guard.text('Prices rose 40% in 2021')).toBe(
+ `Prices rose ${NUMBER_PLACEHOLDER} in ${NUMBER_PLACEHOLDER}`,
+ );
+ expect(guard.heading('Why CEO Grace Hopper chose Acme')).toBe(
+ 'Why CEO Grace Hopper chose Acme',
+ );
+ expect(guard.text('Ask CEO Grace Hopper')).toBe(`Ask CEO ${NAME_PLACEHOLDER}`);
+ expect(guard.keeps('espresso under 500')).toBe(true);
+ expect(guard.keeps('espresso 2021')).toBe(false);
+ expect(guard.text(null)).toBe('');
+ });
+
+ it('reads names in a heading by their honorific, and drops a keyword that names someone', () => {
+ const guard = guardFor();
+ expect(guard.heading('Why Dr. Jane Doe pulls short shots')).toBe(
+ `Why ${NAME_PLACEHOLDER} pulls short shots`,
+ );
+ expect(guard.keeps('Dr. Jane Doe espresso')).toBe(false);
+ });
+
+ it('leaves a question in quotes alone: it is one to answer, not a quote', () => {
+ const guard = guardFor();
+ expect(guard.text('Answer "Which espresso machine should I buy first?" up top')).toBe(
+ 'Answer "Which espresso machine should I buy first?" up top',
+ );
+ expect(guard.text('Quote “Pressure matters far more than price for beginners”')).toBe(
+ `Quote ${QUOTE_PLACEHOLDER}`,
+ );
+ });
+
+ it('reads Turkish percentages as the writer does', () => {
+ const guard = guardFor({ prompts: ['Espresso makinelerinde %25 indirim var mı?'] });
+ expect(guard.text('%25 indirimi anlat')).toBe('%25 indirimi anlat');
+ expect(guard.text('Satışlar yüzde 40 arttı')).toBe(
+ `Satışlar yüzde ${NUMBER_PLACEHOLDER} arttı`,
+ );
+ });
+});
+
+describe('the brief\u2019s cut', () => {
+ it('never splits a placeholder: one the cut would reach goes whole', () => {
+ const [section] = mapOutline(
+ [
+ {
+ heading: 'Heading',
+ keyPoints: [`${'a'.repeat(490)} ${NUMBER_PLACEHOLDER}`],
+ fanout: null,
+ platform: null,
+ },
+ ],
+ [],
+ );
+ expect(section.keyPoints).toEqual(['a'.repeat(490)]);
+ });
+});
+
describe('the brief prompt', () => {
afterEach(() => vi.unstubAllEnvs());