From 71d9a78f54e878ae50a3517bff3ecbe46ae74acd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Aug 2026 03:25:41 +0000 Subject: [PATCH] fix(spec): correct HookSchema.condition @example from SQL to canonical CEL The @example on HookSchema.condition ("status = 'active' AND amount > 1000") was SQL where the slot is canonical CEL (ADR-0058 D1) -- it does not compile, uses bare `status`/`amount` refs instead of the `record` namespace, and contradicts the .describe() one line below, which already spells the correct form. Fixed the @example to match the .describe()'s own illustration (`record.status == 'closed' && record.amount > 1000`), picking `closed` over the issue's `active` for consistency with the .describe(). Also deletes the now-unnecessary HookSchema.condition entry from EXEMPT_EXAMPLES in packages/lint/scripts/check-doc-formula-expressions.mjs -- the gate treats an exemption sitting over a now-clean example as an error, so leaving it would go red. Cross-surface waiver for this touch: domain:spec-tooling seat, issue #7175 comment at 2026-08-10T02:03Z. Fixes #7175 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016R9de1FqP7NvwKvqXi92Gh --- .../scripts/check-doc-formula-expressions.mjs | 19 +++---------------- packages/spec/src/data/hook.zod.ts | 2 +- 2 files changed, 4 insertions(+), 17 deletions(-) diff --git a/packages/lint/scripts/check-doc-formula-expressions.mjs b/packages/lint/scripts/check-doc-formula-expressions.mjs index b3b5704f7a..316132300c 100644 --- a/packages/lint/scripts/check-doc-formula-expressions.mjs +++ b/packages/lint/scripts/check-doc-formula-expressions.mjs @@ -490,22 +490,9 @@ const EXPRESSION_SLOT_TYPES = * reflow while dying with the example it excuses. */ const EXEMPT_EXAMPLES = [ - { - file: 'packages/spec/src/data/hook.zod.ts', - slot: 'HookSchema.condition', - source: "status = 'active' AND amount > 1000", - // NOT a partial snippet — a real defect, of exactly the #6641 class, found by - // this gate's own stock pass (#6763). It is SQL where the slot is CEL, and it - // contradicts the `.describe()` on the very next line, which spells the same - // idea as P`record.status == "closed" && record.amount > 1000`. Bare `status` - // and `amount` would resolve to nothing even after the operators were fixed. - // Exempted rather than corrected only because `packages/spec/src/**` belongs - // to the spec-surface seat and #6763 landed in spec-tooling; filed for - // transfer as #7175. Delete this entry with that fix — leaving it behind is - // itself an error (the "unnecessary" direction above), so the cleanup cannot - // be forgotten silently. - reason: 'REAL DEFECT pending cross-seat fix (#7175) — SQL `=`/`AND` and bare refs in a record-scoped CEL slot', - }, + // Empty: the HookSchema.condition entry (#7175) was deleted once the example + // was corrected to canonical CEL — leaving it would itself be an error (an + // exemption over a now-clean example is the "unnecessary" direction above). ]; /** `packages/spec/src/**` sources, sorted. */ diff --git a/packages/spec/src/data/hook.zod.ts b/packages/spec/src/data/hook.zod.ts index dd826cbca4..10143a13f4 100644 --- a/packages/spec/src/data/hook.zod.ts +++ b/packages/spec/src/data/hook.zod.ts @@ -233,7 +233,7 @@ export const HookSchema = lazySchema(() => strictObject( * If provided and evaluates to FALSE, the hook is skipped entirely. * Useful for filtering by record data without writing handler code. * - * @example "status = 'active' AND amount > 1000" + * @example "record.status == 'closed' && record.amount > 1000" */ condition: ExpressionInputSchema.optional().describe('Predicate (CEL); hook runs only when TRUE. e.g. P`record.status == "closed" && record.amount > 1000`'),