docs(flows): name what the flow nodes do, not what they were once meant to do

[yinlianghui]

Fixes #869

#851 / PR #870 corrected the Automation page's flow table and the opportunity_won_alert description. The same claims survived one layer further in — on the nodes themselves, which ship as authored metadata inside dist/objectstack.json, and in a file-header comment that had begun contradicting the description eleven lines below it. Same "write the current behaviour" standard, same wording, no third phrasing.

Premise re-check against the current baseline

Baseline origin/main = 6cd53d2, which contains PR #870 (5868728) and #874. All three sites re-located after #870's edits and all three are still present:

issue says	after #870	still there?
opportunity-won-alert.flow.ts:71 label Notify Management	line 71	yes
case-escalation.flow.ts:87 label Assign to Senior Agent	line 87	yes
opportunity-won-alert.flow.ts:10-12 JSDoc "notify the owner and their manager"	lines 10-12	yes

Node id reference chains, checked before editing (the issue flagged these as load-bearing):

notify_management    -> declared 1x + referenced by edges e1.target, e2.source
assign_senior_agent  -> declared 1x + referenced by edges e2.target, e3.source + one comment cross-ref
notify_team          -> declared 1x + referenced by edges e3.target, e4.source
CaseEscalationOnCreateFlow rewrites the node list via `n.id === 'start'`

No id is touched. Diffing the id: / source: / target: lines against origin/main shows every id string byte-identical; only label: values and comments differ.

The three sites

file	before	after	why
src/flows/opportunity-won-alert.flow.ts	label Notify Management	Notify Owner	recipients: ['{record.owner_id}'] — the owner and nobody else. The comment directly above the node already explained why there is no manager recipient: {record.owner_id.manager} cannot traverse a lookup on the raw trigger snapshot, so it interpolates to the literal undefined and the message goes to a phantom user. The label was contradicted by its own header.
src/flows/case-escalation.flow.ts	label Assign to Senior Agent	Flag as Escalated	the update_record node writes is_escalated, escalation_reason, escalated_date, status. It never touches owner_id; the comment inside it opens with No owner reassignment:.
src/flows/opportunity-won-alert.flow.ts:10-12	JSDoc "notify the owner and their manager"	"notify the owner — the owner alone, not their manager"	verbatim the correction #870 landed in the description eleven lines below, so the two no longer disagree.

Notify Owner is not a new coinage: task-urgent-alert, task-due-reminder, contract-renewal and contract-expiration already label this node exactly that.

One further label in the same file

The dispatch allows same-file labels that are equally untrue to be corrected in the same pass, listed here:

• src/flows/case-escalation.flow.ts — label Notify Support Team -> Notify Case Owner. recipients is the single entry {caseRecord.owner_id}, not a team. The decisive evidence: the identical node in src/flows/case-sla-monitor.flow.ts carries the same notify_team id and the same owner-only recipient, and its label already reads Alert Owner — this one had simply been left behind. A prior pass had already corrected this node's message body ("reassigned" was also false: this flow never changes the owner) without correcting its label.

Why the ids keep their old spellings

notify_management, assign_senior_agent and notify_team now each carry a short comment recording that the id is deliberately stale-looking. After this PR every one of them reads like a drift a future agent might "tidy" — and renaming any would be a behaviour change wearing a wording fix's clothes.

Artifact landing

pnpm build then scanning dist/objectstack.json:

NEW   "Notify Owner"       -> 5 hits  (4 pre-existing flows + this node)
      "Flag as Escalated"  -> 2 hits  (case_escalation + case_escalation_on_create)
      "Notify Case Owner"  -> 2 hits  (same two flows)

OLD   "Notify Management"      -> 0 hits
      "Assign to Senior Agent" -> 0 hits
      "Notify Support Team"    -> 0 hits

IDS   notify_management -> 3   assign_senior_agent -> 6   notify_team -> 8

The 2-hit counts are correct rather than duplicated: CaseEscalationOnCreateFlow builds its node list from CaseEscalationFlow.nodes.map(...), so both flows carry the corrected nodes.

Do any tests pin these labels?

No — confirmed, as the dispatch predicted. test/automation-docs-coverage.test.ts derives its expectations from each flow's own top-level label (labelFor = (flow) => flow.label), plus row sets, trigger cells and counts. Node labels never enter it. test/docs-drift.test.ts extracts only numeric thresholds and cron schedules. A repo-wide grep for the three literals returns the three source lines and nothing else — no test, fixture or doc quotes them.

Re-ran both guards on their own to be sure: 2 passed (2) / 53 passed (53).

A "revert it and watch the tests go red" check is therefore not available for this change, and reporting one would be fabrication: nothing pins node labels, which is precisely why these three drifted unnoticed. The load-bearing evidence here is the artifact scan above (old strings provably gone, ids provably intact) plus the guards staying green in the direction predicted before running them.

Not verified (carried over from the issue, unchanged)

The issue states it did not verify whether the process monitor / flow run detail actually renders node labels, and this PR does not close that gap either. The fix stands on the labels being authored metadata published in the artifact — a false label is worth correcting whether or not that particular surface paints it.

Verification

All six gates run under the shared lock with NODE_OPTIONS=--max-old-space-size=4096:

step	exit	evidence
pnpm validate	0	24 Flows; 5 author-time warnings, all pre-existing (approval staffing, campaign_member field group)
pnpm typecheck	0	clean
pnpm build	0	Build complete (2162ms), Artifact: dist/objectstack.json (1921.4 KB)
pnpm test --maxWorkers=2	0	Test Files 66 passed (66) / `Tests 1587 passed
pnpm lint	0	13 warnings, 14 suggestions — all pre-existing
pnpm hygiene	0	no raw control bytes in first-party files

Control-byte self-scan over the three changed files, beyond the gate's scan surface: 0 hits.

Scope

Labels and comments only. No recipient, condition, field set, edge or id differs, and this takes no position on whether escalation should reassign or should copy a manager — both remain open product questions under #595.

Filed while verifying, not fixed here: #875 (src/docs/crm_sales.md makes the same manager claim twice, and that file ships in the artifact via ADR-0046) and #876 (content/docs/service/sla-and-escalation describes escalation as a reassignment plus a three-way mailout, in three languages).

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 2:31am