Repository navigation
fix(spec): approval node field help opens in business words - #28233
Conversation
The approval node config's describe text is the field help the Studio flow inspector renders. Rewrite every first sentence in approval.zod.ts to say what the setting does to the request, with no decision id, storage column, key or enum literal; the literal an author writes follows it, and the engineer detail moves to the JSDoc. Pin the first-sentence shape across the whole published JSON schema, and update the excludeSubmitter describe pins. Claude-Session: https://claude.ai/code/session_01L9qibyR1YFTVfiVFt8svQ3 Co-Authored-By: Claude <noreply@anthropic.com>
…ibe text Claude-Session: https://claude.ai/code/session_01L9qibyR1YFTVfiVFt8svQ3 Co-Authored-By: Claude <noreply@anthropic.com>
📓 Docs Drift CheckThis PR changes 1 package(s): 3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:
⛔ 4 release-owned page(s) also name something this change touched. These are read-only:
What this run could not see
Coarse fallback — 168 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): Which tree this was computed onThis run read A worktree cut from an older # while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 2cf717ba4396f18b01c45126faf9d384d67e0ca3 && git checkout 2cf717ba4396f18b01c45126faf9d384d67e0ca3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7c3cc889f7c64d465486bb94ded8c8ea558d6945 fc57c5652c4f1a1ed65f0d0126eba42246b5af45 && git checkout -B drift-repro 7c3cc889f7c64d465486bb94ded8c8ea558d6945 && git merge --no-ff fc57c5652c4f1a1ed65f0d0126eba42246b5af45
node scripts/docs-audit/affected-docs.mjs --json 7c3cc889f7c64d465486bb94ded8c8ea558d6945
|
|
domain:spec#2 · os-tesla · session_01L9qibx5r5nhDMwpRs4SL6D 维护者速读
席位核对 · ACCEPT ·
|
|
domain:spec#2 · os-tesla · session_01L9qibw58ehQ2gRHP2h2Puz Contract-review-claim: |
|
domain:spec#2 · os-tesla · session_01L9qibw58ehQ2gRHP2h2Puz Contract reviewServed-tier: Inputs: card #27838 (body, claim 6528717388, os-dev-report 6530217232), PR body, the 5-file diff against merge base 3a2f4c0, the head's check-runs (read 2026-10-30T18:47Z: 51 check-runs, all completed: 42 success, 9 skipped (path-filtered), 0 failed, 0 cancelled. Success: Auto Label, Build & E2E UI, Build Core, Build Docs, Build UI Deps, Check Changeset, Check Documentation Links, Check PR Size, Dogfood Regression Gate, Flag docs affected by code changes, Governed Surface Queue Guard, Lint & Repo Gates, Lint · CI, release & engine gates, Lint · ESLint, Lint · PM dispatch-gates, Lint · docs & code guards, Lint · repo & tooling gates, Lint · scoped · query-options erasure, Lint · scoped · slot lookup & corpus, Lint · scoped · tooling self-tests, Live E2E UI, PR-body guards (claim · duplicate · Part-of · single-writer path), Plan Test Core shards, Spec property liveness, Test Core, Test Core (all 8), Test UI, Type Check UI, Type Check · consumer gates, Type Check · debt ledger, Type Check · source gates, Type Check · workspace, TypeScript Type Check, filter. Skipped: 18.x upgrade harness (opt-in), Dogfood Regression Gate (matrix shard/3), Dogfood Verify CLI, Lint UI, Packed-tarball smoke (opt-in), Schedule gate · skip when a green push run covers the commit, Temporal Conformance (live PG + MySQL), Test UI (matrix shard/16), UI Published Artifacts.). Author ① Derived judgments
② Semver levelpatch. The authored protocol does not move: ③ Boundary flags
④ Design judgmentThe change holds against the surface it is read on and the scenario it is accepted against. The reader is the Studio flow inspector, which renders each property's Implemented-by: VERDICT: PASS |
Requested by Tesla · project thread
Fixes #27838
Clause-②: no
Metadata-protocol: none
维护者速读
pnpm --filter @objectstack/spec exec vitest run src/automation/approval-describe-business-words-27838.test.ts,预期 7 个用例全绿;或在 Studio 打开审批节点,看“Exclude Submitter”下的提示第一句是“Stops people approving their own requests”。What changes
The Studio flow inspector renders the approval node's property form from the engine-published JSON schema (
getApprovalNodeConfigJsonSchema), and each property'sdescriptionis the help line under the field, clamped to two lines behind "Learn more" (FLOW_HELP_CLAMP_CHARS = 120). Several of those descriptions opened with engineer detail:excludeSubmitternamedsubmitter_id,onEmptyApprovers,admin_rescue,fallbackApproversand quoted enum values; the approverorganizationopened with "ADR-0105 D9" and the$root/$parenttokens.packages/spec/src/automation/approval.zod.ts: every.describe()/.meta({ description })in the file now opens with one sentence in business words: what the setting does to the request, with no decision id, storage column, key or enum literal. The key or literal an author has to write (theonEmptyApproverspolicy names,$root/$parent, theescalateToaddress forms, the CEL roots) follows the first sentence, and the engineer detail moved to the JSDoc. Swept: the approver type, value, resolveAs, group and organization; the decision-output key, type, multiple and required; the escalation enabled, timeoutHours, action, escalateTo and notifySubmitter; the node's approvers, excludeSubmitter, behavior, minApprovals, lockRecord, approvalStatusField, onEmptyApprovers, fallbackApprovers, decisionOutputs, escalation and maxRevisions. Refusal messages (strictObjecthistory/guidance, the pairing and escalation-target refusals) are not field help and are unchanged.content/docs/references/automation/approval.mdx: regenerated (check:generated --fix, which namedcheck:docsas the only stale artifact).git grepof the old strings hits only the reference page andui/tests that carry their own fixtures), so no bundle is regenerated.check:authorable-surfaceandcheck:api-surfaceare green on the builtdist.Tests
approval-describe-business-words-27838.test.ts: walks everydescriptionin the published JSON schema (nested approver, escalation and decision-output shapes included, with path controls so a walk that stops at the top level reds) and asserts no first sentence carries a decision id, a backtick, a quoted enum literal, a snake_case or camelCase identifier, or an organization symbol. The prose itself is not pinned.approval-exclude-submitter-25609.test.ts§5: the pins that requiredsubmitter_idin the describe and the "Segregation of duties" opening now assert the first sentence names no key, column or policy literal, thatonEmptyApproversand'auto_approve'are still named, and thatsubmitter_idstays in the JSDoc.ApproverType.describe()still routes toapproval-approvers-may-resolve-emptyand namesonEmptyApprovers;minApprovalsstill states the per-behavior default;onEmptyApproversstill namesfallbackApproversand'fallback'.Acceptance notes
domain:spec): the node descriptor descriptions inpackages/services/service-automation/src/builtin/http-nodes.tsandpackages/plugins/plugin-approvals/src/approval-node.ts. The exact strings and proposed business wording are in the os-dev report for the seat's follow-up card.ui/packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeInspector.escalationOff-11660.test.tsxquotes the oldenableddescribe in its header comment as "the governing text". Its meaning is kept (the engineer reading now sits in a comment aboveenabledinapproval.zod.ts), but the quotation is stale; it is aui/comment, so it is left for aui/touch.flow-node-config.ts) carries its own hand-written help strings for the approval node; it is only used when the engine publishes noconfigSchema, and it is aui/file.Verification
All readings at head
fc57c565on objectstack-ai/objectstack (merge base3a2f4c00;origin/mainhas since moved by 3 commits that touch no file in this diff).Tests
pnpm --filter @objectstack/spec test: Test Files 758/758, Tests 22559 passed, 1 todo; lock VERDICT command-exit 0.pnpm --filter @objectstack/spec typecheck: lock VERDICT command-exit 0.approval.zod.tsrestored from3a2f4c00(on-disk count of the old "ADR-0105 D9 — organization" opening = 1), the two describe test files red 8 failed / 36 (all six first-sentence shapes plus the two new §5 pins); restored withgit checkout HEAD --,git diff HEADempty.Gates
dispatch-gates --commandsatfc57c565: 103 families, each run with stdin from/dev/null, exit codes recorded before any pipe.--ran: 103 derived, 103 run, 0 NOT MEASURED, 0 unrun, 0 red.lint/formula/client/objectqldist, the full workspace dist forcheck:dual-build-cjs-loads, and a shallow clone forcheck-plugin-teardown-shape --self-test). Re-run after a workspace build (turbo run build, 116/116 tasks, lock VERDICT command-exit 0) andgit fetch --unshallow, all exit 0.pnpm --filter @objectstack/spec check:generated: after--fix, every artifact up to date.test:repo, the UI lanes) is CI's.Generated by Claude Code