refactor(spec): strip internal tracker ids from customer-facing zod refusal messages, and gate their return (#12527)

* refactor(spec): strip internal issue-ids from customer-facing zod refusal messages

15 refusal messages across 9 files under packages/spec/src rendered a tracker
id verbatim to an author running `os validate` / hitting a parse refusal. The
reader of those strings cannot open the tracker, so the id is a citation-shaped
token resolving to nothing.

Where the reference is genuinely load-bearing for an internal reader it moves
to an adjacent // comment (4 sites); elsewhere it is removed outright — git
history keeps the anchor.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E5LFCYBJ3q2s6yW6oMLxwy

* feat(gates): hold the no-tracker-ids convention over spec refusal messages

Rule 3 in check-doc-authoring: an AST scan of packages/spec/src for internal
issue ids in customer-facing zod refusal messages, inheriting the same ruling
Rule 2 applies to the published skill catalog.

It parses rather than scanning lines because refusal prose here is written as
multi-line string concatenation: the commissioning card's own single-line
census command found 1 of the 16 literals in the population. Recognises both
the `message:` property and the positional validator-message argument, and
asserts it saw message strings at all so a blinded detector reds instead of
reporting a clean population it never located.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E5LFCYBJ3q2s6yW6oMLxwy

* test(spec): pin the refusal substance, not the tracker id

Three twins asserted the id as a bare toContain('#7113' / 'objectui#5933' /
'#5055'). Each now pins the sentence that carries the claim, plus a negative
pin that the message contains no issue id at all.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E5LFCYBJ3q2s6yW6oMLxwy

* chore: changeset for the spec refusal-message id strip

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E5LFCYBJ3q2s6yW6oMLxwy

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: huangyiirene

.changeset/spec-refusal-message-issue-ids.md

@@ -0,0 +1,39 @@
+---
+"@objectstack/spec": patch
+---
+
+Strip internal tracker ids from the refusal messages an author actually reads (#12124)
+
+Fifteen zod refusal messages across nine `packages/spec/src` files ended a sentence with
+an internal issue id. Those strings are printed **at** the author, verbatim, the moment
+their metadata is refused — by `os validate`, by a publish gate, by a parse — and the
+reader has no tracker to open. A `#NNNN` there is a citation-shaped token that resolves to
+nothing, in the one place the sentence most needs to be actionable.
+
+```text
+before: A field condition's keys are field names, never $-prefixed operators (#7711).
+after:  A field condition's keys are field names, never $-prefixed operators.
+
+before: ... refused at authoring time because the query path refuses it too
+        (400 INVALID_FILTER, #5869).
+after:  ... refused at authoring time because the query path refuses it too
+        (400 INVALID_FILTER).
+```
+
+Where a customer-resolvable anchor already carried the meaning it was kept and the id
+dropped beside it: the second example above keeps `400 INVALID_FILTER`, which is the token
+an author can actually match their query-path error against. Where the reference is
+load-bearing for an *internal* reader only, it moved to an adjacent `//` comment (four
+sites: the endpoint publish gate's two `#5040` section pointers, the summary-field rule's
+founding incident, and the interim renderer precedence behind the doubled-redirect
+refusal). Elsewhere it is simply gone — git history keeps the anchor.
+
+Text only. **No accept/reject behaviour changes**: the same inputs are refused on the same
+schemas with the same issue `code`, `path` and error shape; only the sentence changes.
+Test twins that pinned the old wording now pin the new text plus a negative assertion that
+the message carries no issue id at all.
+
+The convention is held mechanically from here — `check:doc-authoring` gained a third rule
+that parses `packages/spec/src` and reds on an id in any refusal-message string. It parses
+rather than scanning lines because refusal prose here is written as multi-line string
+concatenation: a single-line `message:.*#[0-9]{3,5}` grep sees 1 of the 16 literals.

packages/spec/src/ai/skill-trigger-condition-value-shape.test.ts

@@ -65,7 +65,10 @@ describe('#7113 — the reported shape is refused at authoring time', () => {
   it('names the consumer-side coercion as the thing being replaced', () => {
     const issue = valueIssue(parse({ field: 'userRole', operator: 'not_in', value: 'admin' }));
     expect(issue.message).toContain('coerces the scalar today');
-    expect(issue.message).toContain('#7113');
+    // The claim is carried by the SENTENCE, not by a tracker id: this string is
+    // printed at an author who has no tracker to open.
+    expect(issue.message).toContain('the contract never declared that spelling');
+    expect(issue.message).not.toMatch(/(?<![#&])#[0-9]{3,5}(?![0-9A-Za-z])/);
   });
 });
 

packages/spec/src/ai/skill.zod.ts

@@ -159,7 +159,7 @@ function checkSkillTriggerConditionValueShape(
         + `${value === undefined ? '["…"]' : previewConditionValue([value])} for a single value, `
         + `or use "${operator === 'in' ? 'eq' : 'neq'}" to compare against it. `
         + `An empty list [] is allowed and is a real predicate. The cloud agent runtime `
-        + `coerces the scalar today; the contract never declared that spelling (#7113).`,
+        + `coerces the scalar today; the contract never declared that spelling.`,
     });
     return;
   }
@@ -174,7 +174,7 @@ function checkSkillTriggerConditionValueShape(
       + `Received ${describeConditionValue(value)} (${previewConditionValue(value)}). `
       + `"${operator}" is an identity comparison, so an array can never match a context `
       + `field and the condition would ${operator === 'eq' ? 'never' : 'always'} fire — `
-      + `use "${operator === 'eq' ? 'in' : 'not_in'}" to test membership of that list (#7113).`,
+      + `use "${operator === 'eq' ? 'in' : 'not_in'}" to test membership of that list.`,
   });
 }
 

packages/spec/src/api/endpoint-publish-gate.ts

@@ -354,6 +354,9 @@ function targetGate(
         return undefined;
     }
 
+    // Internal anchor for the `proxy` half: the egress/SSRF ruling this defers to
+    // is #5040 §7-3. It stays in this comment rather than in the message — the
+    // message is printed to a customer who cannot open the tracker.
     return {
         path: at('type'),
         message:
@@ -362,8 +365,8 @@ function targetGate(
             + 'no path in this repo verifies that a script target is reachable through the automation '
             + 'service — express the logic as a flow (`type: \'flow\'`) whose script node runs your '
             + 'registered function. `proxy` is refused because forwarding to an arbitrary outbound URL is '
-            + 'a new egress/SSRF surface that needs its own security ruling before it can be served '
-            + '(#5040 §7-3); call the third-party system from a flow instead, where the outbound call is '
+            + 'a new egress/SSRF surface that needs its own security ruling before it can be served; '
+            + 'call the third-party system from a flow instead, where the outbound call is '
             + 'made by a declared connector. Both stay in the vocabulary and are rejected here rather '
             + 'than parsed and ignored.',
     };
@@ -559,11 +562,13 @@ function policyGate(
     }
 
     if (cacheTtl !== undefined && endpoint.method !== 'GET') {
+        // Internal anchor for the GET-only rule: #5040 §3.3. Kept out of the
+        // message, which is printed to a customer with no tracker access.
         return {
             path: at('cacheTtl'),
             message:
-                `${named} declares \`cacheTtl\` on a ${endpoint.method} endpoint. \`cacheTtl\` is GET-only `
-                + '(#5040 §3.3): it becomes a `Cache-Control` header on a successful response, and a '
+                `${named} declares \`cacheTtl\` on a ${endpoint.method} endpoint. \`cacheTtl\` is GET-only: `
+                + 'it becomes a `Cache-Control` header on a successful response, and a '
                 + 'non-GET answer is not a cacheable representation, so the key would be parsed and never '
                 + 'take effect. Remove `cacheTtl`, or declare the endpoint as GET if it really is a read.',
         };

packages/spec/src/data/filter.zod.ts

@@ -1451,7 +1451,7 @@ const normalizedFieldConditionSchema = () =>
   z.record(z.string(), FieldOperatorsSchema).refine(
     (condition) => !Object.keys(condition).some((key) => key.startsWith('$')),
     {
-      message: 'A field condition\'s keys are field names, never $-prefixed operators (#7711).',
+      message: 'A field condition\'s keys are field names, never $-prefixed operators.',
       // `abort` so this branch cannot become the union's spokesman. Measured on
       // zod 4.4.3: a union whose other options all abort returns a lone
       // CONTINUABLE failure verbatim, which made `{ $not: { c: <bad> } }` — a

packages/spec/src/integration/connector.zod.ts

@@ -935,7 +935,7 @@ export const DeclarativeConnectorEntrySchema = lazySchema(() =>
         path: ['authentication'],
         message: isInstance
           ? `Provider-bound connector instance '${entry.name}' must not inline secrets via \`authentication\`; reference credentials with \`auth: { type, credentialRef }\` instead (ADR-0097 §3).`
-          : `Connector '${entry.name}' must not inline secrets via \`authentication\` — a published connector row is stored whole in \`sys_metadata\`, so the credential would land in cleartext (#7990). A catalog descriptor holds no live credentials: drop \`authentication\` (or set \`{ type: 'none' }\`) and describe the auth scheme in \`description\`. A dispatchable instance declares \`provider\` and references its credential with \`auth: { type, credentialRef }\` (ADR-0097 §3).`,
+          : `Connector '${entry.name}' must not inline secrets via \`authentication\` — a published connector row is stored whole in \`sys_metadata\`, so the credential would land in cleartext. A catalog descriptor holds no live credentials: drop \`authentication\` (or set \`{ type: 'none' }\`) and describe the auth scheme in \`description\`. A dispatchable instance declares \`provider\` and references its credential with \`auth: { type, credentialRef }\` (ADR-0097 §3).`,
       });
     }
     if (!isInstance) {

packages/spec/src/kernel/functional-completeness.ts

@@ -121,6 +121,9 @@ export function checkFieldCompleteness(def: unknown): CompletenessFinding[] {
   const out: CompletenessFinding[] = [];
 
   if (type === 'summary' && !isRec(def.summaryOperations)) {
+    // Internal anchor: the founding incident for this rule is cloud#687. It sits
+    // here rather than in the message — the message is printed to a customer who
+    // has neither repo's tracker; ADR-0078 is the reference that travels.
     out.push({
       rule: FIELD_SUMMARY_WITHOUT_OPERATIONS,
       severity: 'error',
@@ -129,7 +132,7 @@ export function checkFieldCompleteness(def: unknown): CompletenessFinding[] {
         'A `summary` field with no `summaryOperations` computes nothing: the engine\'s '
         + 'summary index skips it (`engine.ts` — `if (!d.summaryOperations) continue`), so it '
         + 'reads 0/null everywhere and anything derived from it is stuck at 0 — while every '
-        + 'authoring surface reports success. This is the cloud#687 shape ADR-0078 was written for.',
+        + 'authoring surface reports success. This is the shape ADR-0078 was written for.',
       fix: "summaryOperations: { object: '<child_object>', field: '<child_field>', function: 'sum' }",
     });
   }
@@ -278,7 +281,7 @@ export function checkWebhookCompleteness(webhook: unknown): CompletenessFinding[
     message:
       'A webhook with no `triggers` never fires on any path. The auto-enqueuer drops it while '
       + 'building its subscription cache (`auto-enqueuer.ts` — `if (triggers.size === 0) … return '
-      + 'null`), and there is no manual fire path to reach it either: `webhook.zod.ts` (#3196) '
+      + 'null`), and there is no manual fire path to reach it either: `webhook.zod.ts` '
       + 'records that the `api` trigger was removed because "no manual fire path exists — the only '
       + 'webhook HTTP surface re-queues already-failed deliveries". The webhook materializes into '
       + '`sys_webhook`, looks armed in Setup, and delivers nothing. To disable a webhook use '

packages/spec/src/system/auth-config.zod.ts

@@ -417,7 +417,7 @@ export const AudienceConfigSchema = lazySchema(() => z.object({
         message:
           `posture '${posture}' permits self-registration, so the permission set a self-registrant receives ` +
           'must be DECLARED (selfRegistrationPermissionSet) — the implicit member_default fallback is retired ' +
-          '(#11739; declaring member_default explicitly is allowed).',
+          '(declaring member_default explicitly is allowed).',
       });
     } else if (value.selfRegistrationPermissionSet === 'admin_full_access') {
       ctx.addIssue({

packages/spec/src/ui/action-doubled-redirect.test.ts

@@ -47,9 +47,14 @@ describe('ActionSchema — doubled post-success navigation (#11519)', () => {
       // The remedy: one destination, declared in one place.
       expect(msg).toMatch(/drop|remove|keep/i);
       // The interim renderer precedence this refusal supersedes at authoring
-      // time (declared wins, objectui#5933) is recorded so an author hitting
-      // the error understands what happens to metadata published before it.
-      expect(msg).toContain('objectui#5933');
+      // time is recorded so an author hitting the error understands what
+      // happens to metadata published before it. Pinned as the SUBSTANCE —
+      // which channel wins and which is dropped — rather than as the tracker id
+      // that used to stand in for it: the id resolved to nothing for the author
+      // this message is printed at, while the sentence tells them the outcome.
+      expect(msg).toContain('interim precedence');
+      expect(msg).toContain('silently ignored');
+      expect(msg).not.toMatch(/(?<![#&])#[0-9]{3,5}(?![0-9A-Za-z])/);
     });
 
     it('is refused through the registered `action` metadata schema too (the parsing door)', () => {

packages/spec/src/ui/action.zod.ts

@@ -1509,8 +1509,8 @@ export const ActionSchema = lazySchema(() => actionObject().refine((data) => {
     'An action that declares `confirmText` beside a non-empty `params` shows the user TWO dialogs '
     + 'for one decision — the confirm, then the param prompt, with nothing sent until the second. '
     + "Carry the confirm question in the action's top-level `description` instead (it renders under "
-    + 'the param dialog\'s title) and drop `confirmText`: one condition, one wording, one dialog '
-    + '(#7278). Not `ai.description` — that is the LLM-facing tool contract. `confirmText` stays '
+    + 'the param dialog\'s title) and drop `confirmText`: one condition, one wording, one dialog. '
+    + 'Not `ai.description` — that is the LLM-facing tool contract. `confirmText` stays '
     + 'correct for a param-LESS action, where the confirm IS the only dialog, and for a view\'s '
     + '`bulkActionDefs`, where the pair renders one dialog by that schema\'s own contract.',
   path: ['confirmText'],
@@ -1555,6 +1555,10 @@ export const ActionSchema = lazySchema(() => actionObject().refine((data) => {
   // Scoped to `type: 'script'` — the ruled sentence. `opensInNewTab: false`
   // is not the marker (it declares the channel is NOT in use). The corpus was
   // measured at zero doubled producers (#11519), so nothing legal breaks.
+  //
+  // Internal anchor for the "interim precedence" the message names: objectui#5933
+  // is where the renderer-side precedence was ruled. It lives here rather than in
+  // the message, which is printed to a customer who has neither repo's tracker.
   if (data.type === 'script' && data.onSuccess && data.opensInNewTab === true) {
     return false;
   }
@@ -1564,9 +1568,9 @@ export const ActionSchema = lazySchema(() => actionObject().refine((data) => {
     "A `type: 'script'` action declaring BOTH `onSuccess` and `opensInNewTab: true` carries two "
     + 'post-success destinations for one success: `opensInNewTab` pre-opens a tab for the '
     + 'HANDLER-RETURNED `{ redirectUrl }`, while `onSuccess.navigate` declares the hop in '
-    + 'metadata. A renderer can perform only one — under the interim precedence (objectui#5933) '
+    + 'metadata. A renderer can perform only one — under the interim precedence '
     + "the declared `onSuccess` wins and the handler's `redirectUrl` is silently ignored — so the "
-    + 'doubled declaration is refused at authoring time (#11519). Keep `onSuccess` and drop '
+    + 'doubled declaration is refused at authoring time. Keep `onSuccess` and drop '
     + '`opensInNewTab` (and stop returning `redirectUrl` from the handler), or keep '
     + '`opensInNewTab` + the handler redirect and drop `onSuccess`. There is no `precedence` '
     + 'field, by ruling: one destination, declared in one place.',
@@ -1602,7 +1606,7 @@ export const ActionSchema = lazySchema(() => actionObject().refine((data) => {
     + 'otherwise, so without the flag it would parse clean and never run (ADR-0078). If a '
     + 'pre-opened tab is intended, add `opensInNewTab: true`; otherwise drop `newTabUrl` '
     + '(behavior is unchanged — the lone key was never read). For a STATIC url action, new-tab '
-    + 'behavior is `openIn: "new-tab"`, not this pair (#11842).',
+    + 'behavior is `openIn: "new-tab"`, not this pair.',
   path: ['newTabUrl'],
 }).transform((data, ctx) => lowerRequiresFeature(data, ctx)));