docs(campaign): name the metric block's real writers, per site

[os-steve]

Closes #1668

campaign_snapshot_metrics was retired in #597. The campaign metric block is now owned by four refresh hooks — campaign_metrics_refresh, campaign_attribution_refresh, campaign_lead_conversion_refresh (campaign.hook.ts) and campaign_member_metrics_refresh (campaign_member.hook.ts); all four names re-verified as live name: declarations on origin/main.

The count first: nine occurrences, not four

The card listed 4 files. A full-tree grep (git grep -n, plus a raw grep -rn over the working dir including content/, docs/, scripts/ to catch anything untracked) finds nine occurrences across nine files. content/, docs/ and scripts/ are clean — every hit is in src/, test/ or .changeset/.

That is one more file than the dispatch's own count of 8: .changeset/six-readonly-notes-audited-per-writer.md landed with PR #1670 after that grep was taken.

Per-site decision

Read and decided per site, not renamed in bulk — several occurrences narrate what changed and are supposed to keep the old name.

#	site	verdict	why
1	src/flows/campaign-completion.flow.ts:14	(a) name the real writer	Said "the existing campaign_snapshot_metrics afterUpdate hook then snapshots into metrics" — a live claim, and false.
2	src/data/sales.seed.ts:929	(a) name the real writer	"is what campaign_snapshot_metrics counts when a campaign completes" — present-tense data relationship.
3	test/seed-consistency.test.ts:24	(a) name the real writer	A hook→field-block map entry, present tense, claims it is live.
4	test/seed-consistency.test.ts:274	(a) name the real writer	describe block named for the retired hook.
5	test/campaign-member-lifecycle.test.ts:235	(b) past tense	Deliberately historical, but opened with a bare hook name.
6	src/objects/campaign.hook.ts:93	(c) leave	Already "The old campaign_snapshot_metrics fired on → completed and nothing else", followed by "Completion is now simply one of the transitions this catches."
7	src/objects/campaign_member.hook.ts:168	(c) leave	Already "what the removed campaign_snapshot_metrics made everyone wait for."
8	src/objects/campaign.object.ts:169	(c) leave	Corrected by PR #1670 — verified below. Not this card's territory.
9	.changeset/six-readonly-notes-audited-per-writer.md:36	(c) leave	PR #1670's own changeset, recording a landed change; already says "a hook retired long ago". Rewriting it would rewrite the record of what that PR did.

What (a) resolved to

• The flow: the nightly sweep flips in_progress → completed, which is a status transition, so campaign_metrics_refresh recomputes on it. The note now also says this is a refresh, not a snapshot — the block was already current before the sweep ran.
• The seed: the writer that counts attributed opportunities is campaign_attribution_refresh (object: 'crm_opportunity', afterInsert/afterUpdate/afterDelete, computing num_opportunities / num_won_opportunities / summed actual_revenue) — on every opportunity write, not once at completion.
• seed-consistency.test.ts: the map entry and the describe both name the refresh, and a comment above the block carries all four hook names.

One bounded in-place fix, declared

Inside the renamed describe, an it still explained its assertion as a completion-time snapshot ("The hook only fires on the transition INTO completed"). Renaming the block re-points that comment at the four refresh hooks, making it newly false — so it was corrected in the same edit. Same defect class as the card, prose + it name only, no new verification surface.

Verification of the card's own premises

• ✅ PR docs(objects): audit the readonly notes per writer, not per sentence #1670 really did fix campaign.object.ts:166/185. Commit b63e0e76 replaced both notes: line 166's "the campaign_snapshot_metrics hook writes these through the data API, and 16.x drops writes to readonly fields" and line 185's "the campaign_snapshot_metrics hook writes this rollup". One occurrence survives at line 169, and it is correct: "not by the long-retired campaign_snapshot_metrics", followed by all four names. Nothing done here.
• ✅ The four hook names still read as stated on origin/main.
• ✅ test/hook-write-shape.test.ts needed no change — it is in epic Epic: bring this repo's test farm back under the 2026-08-31 ruling — platform-first, os lint --strict first, then retire the local re-implementations by family #1579 family F6 (Retire the local hook / action / flow write-shape tests the platform's *-body-write-* and flow-node-write rules already enforce (epic #1579, step 3, family F6) #1587)'s retirement table, and its occurrence is already exemplary history: "campaign_snapshot_metrics used to sit here alone… it was replaced by a refresh that runs on every input change." Left untouched, so the F6 question never arises.
• ✅ Not touched: src/objects/campaign_member.object.ts (crm_campaign_member.added_date can honestly be declared readonly — its only writers are INSERTs, which the readonly strip never touches #1667, in the decision box), and none of [finding] The 17.3.0 upgrade left 19 comments asserting 17.2.0 is "the pinned" version — third recurrence of #1460 / #1467, and #1669 names only 1 of the 13 files #1676's 13 version-label files.

Acceptance

After this change, a reader who greps campaign_snapshot_metrics gets six hits, and every one is past tense and self-identifying as history: "a hook retired long ago" · "The old …" · "the long-retired … : [all four names]" · "the removed …" · "The RETIRED … gone since #597, replaced by the four refresh hooks" · "used to sit here alone … it was replaced by". Three of the six name the replacement hooks outright. No hit reads as live.

Constraints honoured

• ⛔ Zero assertion changes. The diff contains no expect( line at all, added or removed — including the message arguments. Only comments, one describe name and one it name.
• ⛔ No new gate, no new test (AGENTS.md §3). ⛔ content/docs/releases/ untouched.
• One changeset (patch). The token ratchet is comment-stripped and excludes test/, so the prose is not chargeable: business semantics ~85,032 · interaction layer ~37,963 · authored total ~137,336, all unchanged and clean.

Tests

pnpm verify fully green, exit 0, at 4050ba00 — all eight stages ran (validate, typecheck, lint, lint:i18n-gate, hygiene, hygiene:tokens, build, test):

✓ source token ratchet clean
 Test Files  161 passed (161)
      Tests  3414 passed | 1 skipped (3415)
   Duration  133.43s

🤖 Generated with Claude Code

https://claude.ai/code/session_018xtjdpZFjgWh4Ad9Wcx68J

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 6, 2026 10:52am UTC