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.

feat(action-center): give the Action Center's own tasks their Done when, how they're checked and their page (AC-010, part 3) (#1564)

Cihan55b49e716501
diff --git a/docs/guides/action-center.mdx b/docs/guides/action-center.mdx
index c07a62c20..a9f8fcfc2 100644
--- a/docs/guides/action-center.mdx
+++ b/docs/guides/action-center.mdx
@@ -81,7 +81,7 @@ Click a row to open the action. Under its title you set **Status**, **Assignee**
### Tasks
-Each action comes with tasks: concrete steps such as "Refresh content for these prompts" or "Add structured data to these pages". Open a task to see its details: **What**, **URL** (the exact page), **Where**, **Why**, **Change** (the text before and after, or the text to add), **How** (one step per line), **Done when**, **How we check** (Automatic: we fetch the page again; Re-run: the prompts run again; Manual: you confirm it), **Type** (Content, On-page, Technical, Outreach, PR or Product), **Effort** and **Role**. Click **Edit** to change any of them.
+Each action comes with tasks: concrete steps such as "Refresh content for these prompts" or "Add structured data to these pages". Open a task to see its details: **What**, **URL** (the exact page), **Where**, **Why**, **Change** (the text before and after, or the text to add), **How** (one step per line), **Done when**, **How we check** (Automatic: we fetch the page again; Re-run: the prompts run again; Manual: you confirm it), **Type** (Content, On-page, Technical, Outreach, PR or Product), **Effort** and **Role**. Click **Edit** to change any of them. A task from the Action Center's own plan comes with its **Done when**, with **How we check** for most of them (not for a task measured over a GA4 or Search Console window), and with its **URL** when it changes a page and the action is about one page.
A task's status is **To Do**, **In Progress**, **Completed** or **Skipped** (with a reason). Skipped tasks leave the count, so they don't hold an action short of done. Use **Add task** for work of your own, and delete tasks you don't need.
diff --git a/server/src/lib/action-center/from-content-draft.js b/server/src/lib/action-center/from-content-draft.js
index 7b9363c95..fdc7ba79c 100644
--- a/server/src/lib/action-center/from-content-draft.js
+++ b/server/src/lib/action-center/from-content-draft.js
@@ -140,6 +140,7 @@ export async function sendContentDraftToActionCenter(brandId, { draftId, userId
permission: item.permission,
depends_on: item.dependsOn,
title_params: item.titleParams,
+ details: item.details,
status: 'todo',
})),
);
diff --git a/server/src/lib/action-center/from-mentions.js b/server/src/lib/action-center/from-mentions.js
index 9eb0f38d5..ae84785b9 100644
--- a/server/src/lib/action-center/from-mentions.js
+++ b/server/src/lib/action-center/from-mentions.js
@@ -195,6 +195,7 @@ export async function sendMentionsToActionCenter(brandId, { resultIds, excerpts
permission: item.permission,
depends_on: item.dependsOn,
title_params: item.titleParams,
+ details: item.details,
status: 'todo',
})),
);
diff --git a/server/src/lib/action-center/from-opportunity.js b/server/src/lib/action-center/from-opportunity.js
index b57133733..d7e67b47e 100644
--- a/server/src/lib/action-center/from-opportunity.js
+++ b/server/src/lib/action-center/from-opportunity.js
@@ -239,6 +239,7 @@ export async function sendToActionCenter(
permission: item.permission,
depends_on: item.dependsOn,
title_params: item.titleParams,
+ details: item.details,
status: initialTaskStatus(item.taskKey, opportunity),
})),
);
diff --git a/server/src/lib/action-center/from-topic-gap.js b/server/src/lib/action-center/from-topic-gap.js
index 927cd53b0..1d3969d17 100644
--- a/server/src/lib/action-center/from-topic-gap.js
+++ b/server/src/lib/action-center/from-topic-gap.js
@@ -200,6 +200,7 @@ export async function sendTopicGapToActionCenter(
permission: item.permission,
depends_on: item.dependsOn,
title_params: item.titleParams,
+ details: item.details,
status: 'todo',
})),
);
diff --git a/server/src/lib/action-center/from-topic-opportunity.js b/server/src/lib/action-center/from-topic-opportunity.js
index 2c55ba6da..ef7ef6c42 100644
--- a/server/src/lib/action-center/from-topic-opportunity.js
+++ b/server/src/lib/action-center/from-topic-opportunity.js
@@ -170,6 +170,7 @@ export async function sendTopicOpportunityToActionCenter(topic, { suggestionIds,
permission: item.permission,
depends_on: item.dependsOn,
title_params: item.titleParams,
+ details: item.details,
status: 'todo',
})),
);
diff --git a/server/src/lib/action-center/from-traffic-pages.js b/server/src/lib/action-center/from-traffic-pages.js
index 83d5a798c..980795c00 100644
--- a/server/src/lib/action-center/from-traffic-pages.js
+++ b/server/src/lib/action-center/from-traffic-pages.js
@@ -265,6 +265,7 @@ export async function sendTrafficPagesToActionCenter(brandId, { pages, reason, f
permission: item.permission,
depends_on: item.dependsOn,
title_params: item.titleParams,
+ details: item.details,
status: 'todo',
})),
);
diff --git a/server/src/lib/action-center/from-traffic-pages.test.js b/server/src/lib/action-center/from-traffic-pages.test.js
index 756ed2034..f37539b3c 100644
--- a/server/src/lib/action-center/from-traffic-pages.test.js
+++ b/server/src/lib/action-center/from-traffic-pages.test.js
@@ -215,6 +215,16 @@ describe('sendTrafficPagesToActionCenter', () => {
expect(keys.length).toBeGreaterThan(0);
expect(keys.every((k) => captureAiTraffic.tasks.includes(k))).toBe(true);
expect(keys).toEqual(captureAiTraffic.tasks.filter((k) => keys.includes(k)));
+ // One page: each change on it carries the page's full URL, and how it's checked (AC-010).
+ const onPage = tasks.filter((t) => t.details?.check === 'auto');
+ expect(onPage.length).toBeGreaterThan(0);
+ for (const task of onPage) {
+ expect(task.details, task.task_key).toEqual({
+ check: 'auto',
+ url: 'https://www.acme-coffee.example.com',
+ source: 'template',
+ });
+ }
});
it('still sends, unmeasured, when the brand has no domain', async () => {
diff --git a/server/src/lib/action-center/generate.js b/server/src/lib/action-center/generate.js
index 11c8c4888..de919fe46 100644
--- a/server/src/lib/action-center/generate.js
+++ b/server/src/lib/action-center/generate.js
@@ -164,6 +164,7 @@ async function openCycle({
permission: item.permission,
depends_on: item.dependsOn,
title_params: item.titleParams,
+ details: item.details,
})),
);
if (tasksErr) throw new Error(tasksErr.message);
diff --git a/server/src/lib/action-center/generate.test.js b/server/src/lib/action-center/generate.test.js
index 040855cab..f9b14fa9d 100644
--- a/server/src/lib/action-center/generate.test.js
+++ b/server/src/lib/action-center/generate.test.js
@@ -155,6 +155,15 @@ describe('generateActionsForBrand', () => {
.rows.map((r) => r.task_key);
expect(keys).toContain('validate_ai_visibility');
expect(keys.at(-1)).toBe('measure_action_outcome');
+ // Each with its template's check (AC-010); the analysis none.
+ const rows = writes.inserted.find((w) => w.table === 'action_tasks').rows;
+ expect(rows.find((r) => r.task_key === 'validate_ai_visibility').details).toEqual({
+ check: 'rerun',
+ source: 'template',
+ });
+ const analysis = rows.find((r) => r.task_key.startsWith('analyze_'));
+ expect(analysis).toBeDefined();
+ expect(analysis.details).toBeNull();
});
/**
diff --git a/server/src/lib/action-center/task-writer/index.js b/server/src/lib/action-center/task-writer/index.js
index 72c25c328..741ec146c 100644
--- a/server/src/lib/action-center/task-writer/index.js
+++ b/server/src/lib/action-center/task-writer/index.js
@@ -190,15 +190,18 @@ function sift(tasks, evidence, kept) {
/**
* Whether anyone has worked on the action's tasks: moved one on, added one,
- * renamed or edited one. The night writes only untouched plans; a person
- * rewrites theirs with "Regenerate tasks".
+ * renamed, edited or sent one. The night writes only untouched plans; a
+ * person rewrites theirs with "Regenerate tasks". A library task's details
+ * from its template (AC-010, tasks/templates.js) aren't anyone's work; an
+ * edit in the drawer drops their mark.
*/
export function isTouched(rows) {
return rows.some(
(row) =>
row.status !== 'todo' ||
(!row.task_key && row.details?.source !== 'ai') ||
- (row.task_key && (row.title || row.details)),
+ (row.task_key &&
+ (row.title || (row.details && (row.details.source !== 'template' || row.details.sent)))),
);
}
diff --git a/server/src/lib/action-center/task-writer/index.test.js b/server/src/lib/action-center/task-writer/index.test.js
index e391eb9cf..781fdf2f5 100644
--- a/server/src/lib/action-center/task-writer/index.test.js
+++ b/server/src/lib/action-center/task-writer/index.test.js
@@ -223,6 +223,13 @@ describe('isTouched', () => {
expect(
isTouched([{ task_key: null, title: 'x', status: 'todo', details: { source: 'ai' } }]),
).toBe(false);
+ // A template's details (AC-010) are no one's work; edited (the mark gone) or sent, they are.
+ const filled = { doneWhen: 'Done', check: 'auto', source: 'template' };
+ expect(isTouched([{ ...template, details: filled }])).toBe(false);
+ expect(isTouched([{ ...template, details: { ...filled, source: undefined } }])).toBe(true);
+ expect(
+ isTouched([{ ...template, details: { ...filled, sent: { webhook: { at: 'x' } } } }]),
+ ).toBe(true);
});
});
diff --git a/server/src/lib/action-center/tasks/plan.js b/server/src/lib/action-center/tasks/plan.js
index d092d1bb1..f32eb43d3 100644
--- a/server/src/lib/action-center/tasks/plan.js
+++ b/server/src/lib/action-center/tasks/plan.js
@@ -25,6 +25,7 @@
*/
import { getTask } from './registry.js';
+import { templateDetails } from './templates.js';
/**
* Payload values a task's text may name, normalised.
@@ -71,7 +72,9 @@ function expand(entry, payload) {
* @param {{ id: string, tasks: readonly (string|object)[] }} definition
* @param {{ sources: Set<string>, payload?: Record<string, unknown> }} context
* @returns {Array<{ taskKey: string, version: number, mode: string, permission: string,
- * dependsOn: string[], titleParams: Record<string, unknown>, position: number }>}
+ * dependsOn: string[], titleParams: Record<string, unknown>, position: number,
+ * details: object|null }>} `details`: the template's Done when, How we check
+ * and page (AC-010, templates.js), null without one
*/
export function planTasks(definition, { sources, payload = {} }) {
const values = titleValues(payload);
@@ -105,6 +108,7 @@ export function planTasks(definition, { sources, payload = {} }) {
? Object.fromEntries(primitive.titleKeys.map((key) => [key, values[key]]))
: {},
position: index + 1,
+ details: templateDetails(primitive.id, payload),
};
});
}
diff --git a/server/src/lib/action-center/tasks/plan.test.js b/server/src/lib/action-center/tasks/plan.test.js
index 579ce4940..edf669c32 100644
--- a/server/src/lib/action-center/tasks/plan.test.js
+++ b/server/src/lib/action-center/tasks/plan.test.js
@@ -20,6 +20,34 @@ const keys = (plan) => plan.map((item) => item.taskKey);
* brands, different plans. Everything else here is the machinery that makes
* that safe to do.
*/
+describe('planTasks: what each task says it is done by (AC-010)', () => {
+ it('gives a task its template’s details, and a change on a page the action’s one page', () => {
+ const definition = {
+ id: 'x',
+ tasks: ['analyze_citations', 'optimize_content', 'validate_citations'],
+ };
+ const payload = {
+ targetEntity: 'pages',
+ targetCount: 1,
+ targets: [{ id: '/pricing', label: '/pricing' }],
+ };
+ const plan = planTasks(definition, { sources: ALL, payload });
+ expect(
+ plan.map((item) => [item.taskKey, item.details?.check ?? null, item.details?.url ?? null]),
+ ).toEqual([
+ ['analyze_citations', null, null],
+ ['optimize_content', 'auto', '/pricing'],
+ ['validate_citations', 'rerun', null],
+ ]);
+ // Two pages: no one page to name.
+ const two = planTasks(definition, {
+ sources: ALL,
+ payload: { ...payload, targetCount: 2, targets: [{ id: '/a' }, { id: '/b' }] },
+ });
+ expect(two[1].details).not.toHaveProperty('url');
+ });
+});
+
describe('planTasks', () => {
const definition = {
id: 'recover_visibility',
diff --git a/server/src/lib/action-center/tasks/templates.js b/server/src/lib/action-center/tasks/templates.js
new file mode 100644
index 000000000..9e0da4cfc
--- /dev/null
+++ b/server/src/lib/action-center/tasks/templates.js
@@ -0,0 +1,95 @@
+/**
+ * How a library task is checked, and the page it is done on (AC-010):
+ * written into its details when the task is planned, so a template's task
+ * carries How we check as a written one does, and the exact page when it
+ * changes a page and its action is about one. Its Done when is its
+ * template's too, in the reader's language (web en.json
+ * actionCenter.taskDoneWhen, by task key).
+ *
+ * - `auto`: the page is fetched again (or a Site Audit runs), for a change
+ * made on the page;
+ * - `rerun`: the prompts are run again, for what AI answers say;
+ * - `manual`: the person confirms it, for work outside the page.
+ *
+ * Analysis Ansvisor does itself (analyze_, identify_, map_) has none: it
+ * shows its findings, and the task writer drops it. A task measured from a
+ * data window (GA4, Search Console) has Done when only: none of the three
+ * checks fits it.
+ */
+
+/** How each task is checked, and whether it is done on the action's page. */
+const TEMPLATES = Object.freeze({
+ // Changes made on a page: a re-fetch, or a Site Audit, finds them.
+ optimize_content: { check: 'auto', page: true },
+ refresh_content: { check: 'auto', page: true },
+ strengthen_reference_asset: { check: 'auto', page: true },
+ strengthen_entity_content: { check: 'auto', page: true },
+ // Its links go on other pages: the action's page is the one they point to.
+ add_internal_links: { check: 'auto', page: false },
+ improve_cta_path: { check: 'auto', page: true },
+ publish_content: { check: 'auto', page: true },
+ fix_crawler_access: { check: 'auto', page: true },
+ fix_structured_data: { check: 'auto', page: true },
+ fix_broken_target: { check: 'auto', page: true },
+ fix_technical_issue: { check: 'auto', page: true },
+ validate_technical_fix: { check: 'auto', page: true },
+ // What AI answers say: the prompts run again.
+ validate_ai_visibility: { check: 'rerun' },
+ validate_mentions: { check: 'rerun' },
+ validate_citations: { check: 'rerun' },
+ validate_topic_sov: { check: 'rerun' },
+ validate_platform_visibility: { check: 'rerun' },
+ validate_country_visibility: { check: 'rerun' },
+ validate_competitive_gap: { check: 'rerun' },
+ validate_third_party_citation: { check: 'rerun' },
+ measure_action_outcome: { check: 'rerun' },
+ // Work outside the page: the person confirms it.
+ create_content_brief: { check: 'manual' },
+ create_content_draft: { check: 'manual' },
+ prepare_outreach: { check: 'manual' },
+ execute_outreach: { check: 'manual' },
+ prepare_contribution: { check: 'manual' },
+ track_third_party_status: { check: 'manual' },
+ validate_third_party_presence: { check: 'manual' },
+});
+
+/** The task ids with a check, for the tests. */
+export const TEMPLATED_TASKS = Object.freeze(Object.keys(TEMPLATES));
+
+const PAGE_ADDRESS = /^(?:https?:\/\/\S+|\/\S*)$/i;
+const isAddress = (value) => typeof value === 'string' && PAGE_ADDRESS.test(value);
+
+/**
+ * The one page an action is about, as its payload names it: its one page's
+ * full URL when it keeps one (a sent action's, a traffic page's), else a page
+ * target counted once (a full URL, or a path from the traffic signals; never
+ * the whole site's sentinel, 'site'). Null for none or several, and for an
+ * opportunity with a new page among its assets: its one existing page isn't
+ * the new one's.
+ */
+export function onePage(payload = {}) {
+ if (Array.isArray(payload.assets) && payload.assets.some((a) => a?.decision === 'create')) {
+ return null;
+ }
+ const pages = Array.isArray(payload.pages) ? payload.pages.filter(Boolean) : [];
+ if (pages.length === 1 && isAddress(pages[0])) return pages[0];
+ if (pages.length > 1) return null;
+ if (payload.targetEntity === 'pages' && Number(payload.targetCount) === 1) {
+ const key = payload.targets?.[0]?.id ?? payload.targetIds?.[0];
+ if (isAddress(key)) return key;
+ }
+ return null;
+}
+
+/**
+ * A library task's details from its template: How we check, and for a
+ * change on a page the action's one page. Marked `source: 'template'`: the
+ * task writer reads a task with only these as untouched (isTouched), and an
+ * edit in the drawer makes them the person's. Null without a template.
+ */
+export function templateDetails(taskKey, payload = {}) {
+ const template = TEMPLATES[taskKey];
+ if (!template) return null;
+ const url = template.page ? onePage(payload) : null;
+ return { check: template.check, ...(url ? { url } : {}), source: 'template' };
+}
diff --git a/server/src/lib/action-center/tasks/templates.test.js b/server/src/lib/action-center/tasks/templates.test.js
new file mode 100644
index 000000000..2a27ef83b
--- /dev/null
+++ b/server/src/lib/action-center/tasks/templates.test.js
@@ -0,0 +1,109 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { TASKS } from './registry.js';
+import { TEMPLATED_TASKS, onePage, templateDetails } from './templates.js';
+import { TASK_CHECKS } from '../task-writer/quality.js';
+
+/** How a library task is checked, and the page it is done on (AC-010). */
+
+describe('templateDetails', () => {
+ it('has a check that exists for library tasks only', () => {
+ for (const id of TEMPLATED_TASKS) {
+ expect(TASKS[id], id).toBeDefined();
+ expect(TASKS[id].legacy, id).toBe(false);
+ const details = templateDetails(id);
+ expect(TASK_CHECKS, id).toContain(details.check);
+ expect(details.source).toBe('template');
+ }
+ // The analysis Ansvisor does itself has none: the writer drops it anyway.
+ expect(templateDetails('analyze_citations')).toBeNull();
+ expect(templateDetails('no_such_task')).toBeNull();
+ });
+
+ it('checks every task a person or an agent does, and every validation but a data window’s', () => {
+ // A data window (GA4, Search Console, AI visits) fits none of the checks;
+ // no plan uses the baseline's.
+ const windows = ['validate_ai_traffic', 'validate_gsc', 'validate_ga4'];
+ const unused = ['define_validation_baseline'];
+ const doing = Object.values(TASKS).filter(
+ (task) =>
+ !task.legacy &&
+ !/^(?:analyze|identify|map|cluster|prioritize)_/.test(task.id) &&
+ ![...windows, ...unused].includes(task.id),
+ );
+ expect(doing.map((task) => task.id).filter((id) => !TEMPLATED_TASKS.includes(id))).toEqual([]);
+ });
+
+ it('has a Done when on the web for every task with a check (en.json actionCenter.taskDoneWhen)', () => {
+ const doneWhen = JSON.parse(
+ readFileSync(new URL('../../../../../web/messages/en.json', import.meta.url), 'utf8'),
+ ).actionCenter.taskDoneWhen;
+ for (const id of TEMPLATED_TASKS) expect(typeof doneWhen[id], id).toBe('string');
+ // And none for a task that isn't one.
+ for (const id of Object.keys(doneWhen)) expect(TASKS[id], id).toBeDefined();
+ });
+
+ it('gives a change on a page its action’s one page, and a re-run or a link task none', () => {
+ const one = { targetEntity: 'pages', targetCount: 1, targets: [{ id: '/pricing' }] };
+ expect(templateDetails('optimize_content', one)).toEqual({
+ check: 'auto',
+ url: '/pricing',
+ source: 'template',
+ });
+ expect(templateDetails('validate_citations', one)).toEqual({
+ check: 'rerun',
+ source: 'template',
+ });
+ // Its links go on other pages.
+ expect(templateDetails('add_internal_links', one)).not.toHaveProperty('url');
+ expect(templateDetails('prepare_outreach', one).check).toBe('manual');
+ });
+});
+
+describe('onePage', () => {
+ it('reads the one page an action is about, never several or the whole site', () => {
+ expect(
+ onePage({
+ targetEntity: 'pages',
+ targetCount: 1,
+ targets: [{ id: 'https://acme.example/a' }],
+ }),
+ ).toBe('https://acme.example/a');
+ expect(onePage({ targetEntity: 'pages', targetCount: 1, targetIds: ['/a'] })).toBe('/a');
+ // A traffic page keeps its full URL beside the path it is counted by.
+ expect(
+ onePage({
+ targetEntity: 'pages',
+ targetCount: 1,
+ targets: [{ id: '/a' }],
+ pages: ['https://acme.example/a'],
+ }),
+ ).toBe('https://acme.example/a');
+ // A sent action's one page (a draft's, an opportunity's).
+ expect(
+ onePage({ targetEntity: 'prompts', targetCount: 3, pages: ['https://acme.example/b'] }),
+ ).toBe('https://acme.example/b');
+ expect(
+ onePage({ targetEntity: 'pages', targetCount: 2, targets: [{ id: '/a' }, { id: '/b' }] }),
+ ).toBeNull();
+ expect(
+ onePage({ targetEntity: 'pages', targetCount: 1, targets: [{ id: 'site' }] }),
+ ).toBeNull();
+ expect(
+ onePage({ targetEntity: 'prompts', targetCount: 1, targets: [{ id: 'p1' }] }),
+ ).toBeNull();
+ expect(onePage({ pages: ['https://acme.example/a', 'https://acme.example/b'] })).toBeNull();
+ expect(onePage({ pages: [null] })).toBeNull();
+ expect(onePage()).toBeNull();
+ // An opportunity with a new page and one to optimize: neither is the other's.
+ expect(
+ onePage({
+ assets: [{ decision: 'create' }, { decision: 'optimize' }],
+ pages: ['https://acme.example/b'],
+ }),
+ ).toBeNull();
+ expect(onePage({ assets: [{ decision: 'optimize' }], pages: ['https://acme.example/b'] })).toBe(
+ 'https://acme.example/b',
+ );
+ });
+});
diff --git a/web/messages/en.json b/web/messages/en.json
index 3a0cc4716..469aa2416 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -2408,6 +2408,39 @@
"notAllowed": "Only admins and managers review tasks.",
"failed": "Couldn't save. Try again."
},
+ "taskDoneWhen": {
+ "optimize_content": "The changes are on the page, or its draft is marked ready in the Content Editor",
+ "refresh_content": "The page has its new facts and date, or its draft is marked ready in the Content Editor",
+ "strengthen_reference_asset": "The page is live with the facts, sources or tables added, and fetched again it has them",
+ "strengthen_entity_content": "The page describes the brand as its profile does, fetched again",
+ "add_internal_links": "The pages that should link to it do, fetched again",
+ "improve_cta_path": "The call to action is live on the page, fetched again",
+ "publish_content": "The page is published at its address and answers when fetched",
+ "fix_crawler_access": "robots.txt and the page let the AI crawlers in, fetched again",
+ "fix_structured_data": "The page has valid structured data (JSON-LD), fetched again",
+ "fix_broken_target": "The page, or its redirect, answers when fetched again",
+ "fix_technical_issue": "A new Site Audit no longer finds the issue",
+ "validate_technical_fix": "A new Site Audit passes the checks that failed",
+ "validate_ai_visibility": "Run again, the prompts show the brand above its baseline",
+ "validate_mentions": "Run again, the prompts mention the brand more than at its baseline",
+ "validate_citations": "Run again, the prompts cite the brand’s pages more than at their baseline",
+ "validate_topic_sov": "Run again, the topic’s prompts give the brand more share of voice than at its baseline",
+ "validate_platform_visibility": "Run again on the platform, the prompts show the brand above its baseline",
+ "validate_country_visibility": "Run again in the country, the prompts show the brand above its baseline",
+ "validate_competitive_gap": "Run again, the prompts show the gap to the competitor narrower than at its baseline",
+ "validate_third_party_citation": "Run again, the prompts cite the third-party page that names the brand",
+ "measure_action_outcome": "Run again after the work, the prompts are measured against the action’s baseline",
+ "create_content_brief": "The brief is written and saved",
+ "create_content_draft": "The draft is written and marked ready in the Content Editor",
+ "prepare_outreach": "The outreach messages are written and approved",
+ "execute_outreach": "The approved messages are sent to every contact",
+ "prepare_contribution": "The contribution is written and approved",
+ "track_third_party_status": "Each placement is marked live, pending or declined",
+ "validate_third_party_presence": "The brand is named on the third-party page",
+ "validate_ai_traffic": "AI-referred visits in the window are above their baseline",
+ "validate_gsc": "Search Console clicks in the window are above their baseline",
+ "validate_ga4": "Key events in the window are above their baseline"
+ },
"taskChecks": {
"auto": "Automatic: we fetch the page again",
"rerun": "Re-run: the prompts run again",
diff --git a/web/src/components/action-center/action-drawer.tsx b/web/src/components/action-center/action-drawer.tsx
index 50a7efdb1..f01605eaf 100644
--- a/web/src/components/action-center/action-drawer.tsx
+++ b/web/src/components/action-center/action-drawer.tsx
@@ -86,7 +86,12 @@ import { getActionDrafts, startDraftFromAction } from '@/lib/actions/content-dra
import { actionPages, draftMethodForTask, type ActionDraft } from '@/lib/content/action-drafts';
import { contentEditorPath } from '@/lib/content/drafts';
import { RegenerateTasks, taskWriterEnabled } from './regenerate-tasks';
-import { hasTaskSpec, type TaskDetailsEdit } from '@/lib/action-center/task-details';
+import {
+ hasTaskSpec,
+ withTemplateDoneWhen,
+ withoutTemplateDoneWhen,
+ type TaskDetailsEdit,
+} from '@/lib/action-center/task-details';
import { ImproveOutcomeCard } from './improve-outcome-card';
import { improvePlatformLabels } from '@/lib/improve-outcome';
import { cn } from '@/lib/utils';
@@ -832,6 +837,11 @@ function TaskRow({
() => !!task.details && !hasTaskSpec(task.details) && !!task.details.body,
);
const [editing, setEditing] = useState(false);
+ // A library task's Done when is its template's until someone writes one (AC-010).
+ const tDoneWhen = useTranslations('actionCenter.taskDoneWhen');
+ const details = withTemplateDoneWhen(task.details, task.taskKey, (key) =>
+ tDoneWhen.has(key) ? tDoneWhen(key) : null,
+ );
// Choosing Skipped opens a reason field rather than committing: a skip
// without a reason cannot be told apart from an abandoned task later.
const [skipDraft, setSkipDraft] = useState<string | null>(null);
@@ -909,17 +919,20 @@ function TaskRow({
(editing ? (
<TaskDetailForm
text={text}
- details={task.details}
+ details={details}
disabled={disabled}
onSave={async (edit) => {
+ // The template's Done when, left as it was, stays the template's.
// The form stays until the save lands, so a failure keeps what was typed.
- if (await onEdit(edit)) setEditing(false);
+ if (await onEdit(withoutTemplateDoneWhen(edit, task.details, details))) {
+ setEditing(false);
+ }
}}
onCancel={() => setEditing(false)}
/>
) : (
<TaskDetailView
- details={task.details}
+ details={details}
disabled={disabled || skipDraft !== null}
onEdit={() => setEditing(true)}
send={send}
diff --git a/web/src/components/action-center/action-export-buttons.tsx b/web/src/components/action-center/action-export-buttons.tsx
index 33b81d514..efdb60ea4 100644
--- a/web/src/components/action-center/action-export-buttons.tsx
+++ b/web/src/components/action-center/action-export-buttons.tsx
@@ -72,6 +72,7 @@ export function ActionExportButtons({
taskStatus: useTranslations(EXPORT_NAMESPACES.taskStatus),
taskTypes: useTranslations(EXPORT_NAMESPACES.taskTypes),
taskChecks: useTranslations(EXPORT_NAMESPACES.taskChecks),
+ taskDoneWhen: useTranslations(EXPORT_NAMESPACES.taskDoneWhen),
signals: useTranslations(EXPORT_NAMESPACES.signals),
signalTexts: useTranslations(EXPORT_NAMESPACES.signalTexts),
signalCategories: useTranslations(EXPORT_NAMESPACES.signalCategories),
diff --git a/web/src/lib/action-center/export-labels.ts b/web/src/lib/action-center/export-labels.ts
index cffe0c2d3..556cdb0e1 100644
--- a/web/src/lib/action-center/export-labels.ts
+++ b/web/src/lib/action-center/export-labels.ts
@@ -49,6 +49,7 @@ export const EXPORT_NAMESPACES = {
taskStatus: 'actionCenter.taskStatus',
taskTypes: 'actionCenter.taskTypes',
taskChecks: 'actionCenter.taskChecks',
+ taskDoneWhen: 'actionCenter.taskDoneWhen',
signals: 'actionCenter.signalsPage',
signalTexts: 'actionCenter.signalTexts',
signalCategories: 'actionCenter.signalCategories',
@@ -304,6 +305,7 @@ export function labelActionExport(input: ActionExportInput, t: ExportTranslators
skipped: (reason) => t.export('skipped', { reason }),
taskType: (type) => t.taskTypes(type),
taskCheck: (check) => t.taskChecks(check),
+ templateDoneWhen: (taskKey) => (t.taskDoneWhen.has?.(taskKey) ? t.taskDoneWhen(taskKey) : ''),
taskChange: ({ before, after }) =>
before
? t.export('taskChangeLine', { before, after })
diff --git a/web/src/lib/action-center/export.test.ts b/web/src/lib/action-center/export.test.ts
index 1ebca2450..d52eb79c0 100644
--- a/web/src/lib/action-center/export.test.ts
+++ b/web/src/lib/action-center/export.test.ts
@@ -1,5 +1,6 @@
// @vitest-environment node
import { describe, expect, it } from 'vitest';
+import { parseTaskDetails } from './task-details';
import type { ActionDetail, ActionItem } from '@/lib/actions/action-center';
import type { Signal } from '@/lib/signals/map';
import {
@@ -139,6 +140,8 @@ const texts: ExportTexts = {
taskType: (type) => ({ content: 'Content', outreach: 'Outreach' })[type] ?? type,
taskCheck: (check) => `check.${check}`,
taskChange: ({ before, after }) => (before ? `${before} → ${after}` : `Add: ${after}`),
+ templateDoneWhen: (taskKey) =>
+ taskKey === 'refresh_content' ? 'The page has its new facts and date' : '',
taskSent: (to) => (to === 'content' ? 'Sent to Content' : 'Sent to the webhook'),
answerSource: 'AI answer',
};
@@ -390,6 +393,27 @@ describe('the Excel file', () => {
});
});
+describe('a library task’s Done when (AC-010)', () => {
+ it('is its template’s until someone writes one', () => {
+ const library = (details: (typeof detail.tasks)[number]['details']) =>
+ buildActionExport(
+ action,
+ {
+ ...detail,
+ tasks: [{ ...detail.tasks[1], taskKey: 'refresh_content', title: null, details }],
+ },
+ texts,
+ { origin: 'https://app.example', timeZone: 'Europe/Istanbul' },
+ ).tasks[0].doneWhen;
+ expect(library(null)).toBe('The page has its new facts and date');
+ // A template's check alone (AC-010 part 3) still takes its Done when.
+ expect(library(parseTaskDetails({ check: 'auto' }))).toBe(
+ 'The page has its new facts and date',
+ );
+ expect(library(parseTaskDetails({ doneWhen: 'Our own check' }))).toBe('Our own check');
+ });
+});
+
describe('a task with AC-004 fields', () => {
const concrete = buildActionExport(
action,
diff --git a/web/src/lib/action-center/export.ts b/web/src/lib/action-center/export.ts
index 2565b4e46..144b99142 100644
--- a/web/src/lib/action-center/export.ts
+++ b/web/src/lib/action-center/export.ts
@@ -154,6 +154,8 @@ export interface ExportTexts {
taskCheck: (check: string) => string;
/** "Before: … → After: …", or "Add: …" (AC-010). */
taskChange: (change: { before: string | null; after: string }) => string;
+ /** A library task's Done when from its template (AC-010); empty without one. */
+ templateDoneWhen: (taskKey: string) => string;
/** "Sent to Content", "Sent to the webhook" (AC-004). */
taskSent: (to: 'content' | 'webhook') => string;
/** What an AI answer a task rests on is called; its id means nothing outside. */
@@ -225,7 +227,10 @@ export function buildActionExport(
why: oneLine(d?.why),
change: d?.change ? oneLine(texts.taskChange(d.change)) : '',
how: (d?.how ?? []).map(oneLine),
- doneWhen: oneLine(d?.doneWhen),
+ // A library task's is its template's until someone writes one (AC-010).
+ doneWhen: oneLine(
+ d?.doneWhen ?? (task.taskKey ? texts.templateDoneWhen(task.taskKey) : ''),
+ ),
check: d?.check ? texts.taskCheck(d.check) : '',
effort: [d?.effort, d?.role].filter(Boolean).join(' · '),
details: details
diff --git a/web/src/lib/action-center/task-details.test.ts b/web/src/lib/action-center/task-details.test.ts
index d62a5b040..89d6b237a 100644
--- a/web/src/lib/action-center/task-details.test.ts
+++ b/web/src/lib/action-center/task-details.test.ts
@@ -4,6 +4,8 @@ import {
cleanTaskDetailsEdit,
isTaskDetailsEdit,
parseTaskDetails,
+ withTemplateDoneWhen,
+ withoutTemplateDoneWhen,
} from './task-details';
const empty = {
@@ -105,6 +107,54 @@ describe('parseTaskDetails', () => {
});
});
+describe('withTemplateDoneWhen', () => {
+ const doneWhenOf = (key: string) => (key === 'refresh_content' ? 'Refreshed and live' : null);
+
+ it("gives a library task its template's Done when until someone writes one (AC-010)", () => {
+ expect(withTemplateDoneWhen(null, 'refresh_content', doneWhenOf)).toEqual({
+ ...empty,
+ doneWhen: 'Refreshed and live',
+ });
+ const own = parseTaskDetails({ doneWhen: 'Our own check', check: 'auto' });
+ expect(withTemplateDoneWhen(own, 'refresh_content', doneWhenOf)).toBe(own);
+ const checked = parseTaskDetails({ check: 'auto' });
+ expect(withTemplateDoneWhen(checked, 'refresh_content', doneWhenOf)).toEqual({
+ ...checked,
+ doneWhen: 'Refreshed and live',
+ });
+ // No template, or a task written by hand: as it is.
+ expect(withTemplateDoneWhen(null, 'analyze_citations', doneWhenOf)).toBeNull();
+ expect(withTemplateDoneWhen(checked, null, doneWhenOf)).toBe(checked);
+ });
+});
+
+describe('withoutTemplateDoneWhen', () => {
+ const edit = {
+ url: '',
+ where: '',
+ why: '',
+ before: '',
+ after: '',
+ how: [],
+ doneWhen: ' Refreshed and live ',
+ check: null,
+ type: null,
+ effort: '~1h',
+ role: '',
+ };
+ const shown = parseTaskDetails({ doneWhen: 'Refreshed and live' });
+
+ it("gives the template's Done when back as none when it's left as it was (AC-010)", () => {
+ expect(withoutTemplateDoneWhen(edit, null, shown).doneWhen).toBe('');
+ // Changed, it's the person's.
+ expect(withoutTemplateDoneWhen({ ...edit, doneWhen: 'Ours' }, null, shown).doneWhen).toBe(
+ 'Ours',
+ );
+ // The task's own, the same words or not, stays its own.
+ expect(withoutTemplateDoneWhen(edit, shown, shown).doneWhen).toBe(' Refreshed and live ');
+ });
+});
+
describe('cleanTaskDetailsEdit', () => {
const edit = {
url: '',
diff --git a/web/src/lib/action-center/task-details.ts b/web/src/lib/action-center/task-details.ts
index 6ee7db377..cd5d1f05b 100644
--- a/web/src/lib/action-center/task-details.ts
+++ b/web/src/lib/action-center/task-details.ts
@@ -147,6 +147,38 @@ export function parseTaskDetails(raw: unknown): ActionTaskDetails | null {
return hasTaskDetails(details) ? details : null;
}
+/**
+ * A library task's details with its template's Done when (AC-010) when it
+ * has none of its own, in the reader's language (en.json
+ * actionCenter.taskDoneWhen): `doneWhenOf` reads it by task key, null
+ * without one.
+ */
+export function withTemplateDoneWhen(
+ details: ActionTaskDetails | null,
+ taskKey: string | null,
+ doneWhenOf: (taskKey: string) => string | null,
+): ActionTaskDetails | null {
+ if (details?.doneWhen || !taskKey) return details;
+ const doneWhen = doneWhenOf(taskKey);
+ if (!doneWhen) return details;
+ return details ? { ...details, doneWhen } : parseTaskDetails({ doneWhen });
+}
+
+/**
+ * An edit with the template's Done when left as it was, given back as none
+ * (AC-010): it stays the template's, in the reader's language, as an
+ * unchanged title does. `stored` is the task's own details, `shown` them
+ * with the template's (withTemplateDoneWhen).
+ */
+export function withoutTemplateDoneWhen<T extends TaskDetailsEdit>(
+ edit: T,
+ stored: ActionTaskDetails | null,
+ shown: ActionTaskDetails | null,
+): T {
+ const template = !stored?.doneWhen ? shown?.doneWhen : null;
+ return template && edit.doneWhen.trim() === template ? { ...edit, doneWhen: '' } : edit;
+}
+
/** Whether any field says something. */
export function hasTaskDetails(details: ActionTaskDetails): boolean {
return (
diff --git a/web/src/lib/actions/action-center.ts b/web/src/lib/actions/action-center.ts
index 2701887d1..ab9f90755 100644
--- a/web/src/lib/actions/action-center.ts
+++ b/web/src/lib/actions/action-center.ts
@@ -494,7 +494,12 @@ export async function updateTaskDetails(
row.details && typeof row.details === 'object' && !Array.isArray(row.details)
? (row.details as Record<string, unknown>)
: {};
- const details = { ...stored, ...cleanTaskDetailsEdit(edit) };
+ const merged = { ...stored, ...cleanTaskDetailsEdit(edit) };
+ // A template's details, edited, are the person's (AC-010): the task writer
+ // reads the task as worked on (task-writer isTouched). An undefined key
+ // isn't written.
+ const fromTemplate = (stored as { source?: unknown }).source === 'template';
+ const details = fromTemplate ? { ...merged, source: undefined } : merged;
const title = edit.title === null ? null : cleanTaskTitle(edit.title);
const { error } = await supabase
diff --git a/web/src/lib/actions/task-details-edit.test.ts b/web/src/lib/actions/task-details-edit.test.ts
index b521af15d..95d32397a 100644
--- a/web/src/lib/actions/task-details-edit.test.ts
+++ b/web/src/lib/actions/task-details-edit.test.ts
@@ -88,6 +88,14 @@ describe('updateTaskDetails', () => {
expect(events[0]).toMatchObject({ event: 'task_edited', data: { taskId: 't1', title: null } });
});
+ it("makes a template's details the person's once edited (AC-010)", async () => {
+ stored = { doneWhen: 'The changed page is live', check: 'auto', source: 'template' };
+ await updateTaskDetails('b1', 'a1', 't1', edit);
+ // As written to the database: an undefined key isn't.
+ expect(JSON.parse(JSON.stringify(updates[0].details))).not.toHaveProperty('source');
+ expect(updates[0].details).toMatchObject({ check: 'rerun', url: '/pricing' });
+ });
+
it('writes a changed text', async () => {
await updateTaskDetails('b1', 'a1', 't1', { ...edit, title: ' Add a table to /pricing ' });
expect(updates[0].title).toBe('Add a table to /pricing');
diff --git a/web/src/lib/mcp/action-priority.test.ts b/web/src/lib/mcp/action-priority.test.ts
index 330d12435..8cfbeadd7 100644
--- a/web/src/lib/mcp/action-priority.test.ts
+++ b/web/src/lib/mcp/action-priority.test.ts
@@ -166,6 +166,39 @@ describe('getActionFor', () => {
}
});
+ it("gives a library task its template's Done when (AC-010)", async () => {
+ taskRows = [
+ {
+ id: 't2',
+ position: 1,
+ task_key: 'refresh_content',
+ title: null,
+ status: 'todo',
+ details: { check: 'auto', source: 'template' },
+ },
+ {
+ id: 't3',
+ position: 2,
+ task_key: 'analyze_citations',
+ title: null,
+ status: 'todo',
+ details: null,
+ },
+ ];
+ try {
+ const action = await getActionFor(auth, 'a1');
+ expect(action?.tasks[0].details).toMatchObject({
+ check: 'auto',
+ done_when:
+ 'The page has its new facts and date, or its draft is marked ready in the Content Editor',
+ });
+ // The analysis has no template.
+ expect(action?.tasks[1].details).toBeNull();
+ } finally {
+ taskRows = [];
+ }
+ });
+
it('gives the action its priority', async () => {
const action = await getActionFor(auth, 'a1');
expect(action?.priority).toEqual({
diff --git a/web/src/lib/mcp/data.ts b/web/src/lib/mcp/data.ts
index 3b25aaf96..6d2a7df4a 100644
--- a/web/src/lib/mcp/data.ts
+++ b/web/src/lib/mcp/data.ts
@@ -1,3 +1,5 @@
+import { createTranslator } from 'next-intl';
+import messages from '../../../messages/en.json';
import { supabaseAdmin } from '@/lib/supabase/admin';
import type { McpAuthContext } from '@/lib/mcp-auth';
import type { Citation } from '@/types';
@@ -29,7 +31,7 @@ import {
withEntityCounts,
withoutTargetIds,
} from '@/lib/action-center/entity-counts';
-import { parseTaskDetails } from '@/lib/action-center/task-details';
+import { parseTaskDetails, withTemplateDoneWhen } from '@/lib/action-center/task-details';
import { locationCode, isValidLocation } from '@/lib/region';
import { promptVolumeEstimate, type EstimateConfidence } from '@/lib/volume-estimate';
import { getOrgLocationUsage, locationLimitMessage } from '@/lib/prompt-locations';
@@ -2987,9 +2989,18 @@ export interface ActionDetailForMcp {
events: Array<{ event: string; data: Record<string, unknown>; created_at: string }>;
}
+/** A library task's Done when from its template (AC-010), in English as the rest of the output. */
+const doneWhenT = createTranslator({
+ locale: 'en',
+ messages,
+ namespace: 'actionCenter.taskDoneWhen' as never,
+});
+const templateDoneWhen = (taskKey: string) =>
+ doneWhenT.has(taskKey as never) ? doneWhenT(taskKey as never) : null;
+
/** A task's details in the snake_case the rest of the MCP output uses. */
-function mcpTaskDetails(raw: unknown) {
- const d = parseTaskDetails(raw);
+function mcpTaskDetails(raw: unknown, taskKey: string | null = null) {
+ const d = withTemplateDoneWhen(parseTaskDetails(raw), taskKey, templateDoneWhen);
if (!d) return null;
return {
// The exact page, the change to make there and how we check it (AC-010).
@@ -3104,7 +3115,7 @@ export async function getActionFor(
depends_on: (t.depends_on ?? []) as string[],
// Where, why, how and done-when (AC-004), the exact page, the change and how
// it's checked (AC-010); an Improve task's body and evidence.
- details: mcpTaskDetails(t.details),
+ details: mcpTaskDetails(t.details, t.task_key ?? null),
})),
// The join that found them is not part of a signal.
signals: ((signalsRes.data ?? []) as Record<string, unknown>[]).map((row) =>