Skip to content

docs(spec,lint): record the intentional code divergence between the two name-like sets (#6734) - #7368

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-6734-name-like-sets-note
Aug 10, 2026
Merged

docs(spec,lint): record the intentional code divergence between the two name-like sets (#6734)#7368
os-zhuang merged 1 commit into
mainfrom
claude/issue-6734-name-like-sets-note

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

Closes #6734

The ruling this executes

Maintainer ruling on #6734, comment 5237222790 (2026-08-10), quoted verbatim:

Maintainer ruling (2026-08-10, directed in session session_01BPWqbmEFU8gJepBJTHESXd): document the gap, no behavior change.

The two "name-like" sets (lint R9's title faces, spec's ADR-0079 derivation keys) stay as they are; the undocumented difference — code counting for one and not the other — gets written down where both sets are defined, each pointing at the other. R9 is suggestion-severity, so the stakes do not justify moving either set; the defect was that the divergence was invisible, not that it exists.

needs-user-decisionpm:queue (docs-note card).

Premise check — both sets still diverge by exactly code

Verified on origin/main @ f188ed6, before any edit. Both definitions quoted as they stand (and as they still stand after this PR — neither moves):

packages/lint/src/data-model-rules.ts:36

const NAME_LIKE_FIELDS = ['name', 'title', 'subject', 'label', 'full_name', 'display_name', 'code'];

packages/spec/src/data/display-name.ts:134-136

const NAME_ISH_EXACT: ReadonlySet<string> = new Set([
  'name', 'title', 'subject', 'label', 'full_name', 'display_name',
]);

Set difference is exactly {'code'}, in the lint direction. The premise holds.

The three notes

1. packages/lint/src/data-model-rules.ts — above NAME_LIKE_FIELDS. States that R9 asks the looser "will records be anonymous?" question, that code therefore deliberately counts here and deliberately does not count in spec's derivation set, and points at display-name.ts. Records that a code-only object can still be derived — but at tier 3 ("first title-eligible field by declaration order"), by a different rule and a different priority, so the two are not equivalent even where they agree on the outcome.

2. packages/spec/src/data/display-name.ts — above NAME_ISH_EXACT. The mirror: derivation asks "what IS the title?", an identifier is not a title, code is deliberately absent, points back at the lint set, and notes the divergence is intentional per the 2026-08-10 ruling on #6734.

3. skills/objectstack-data/SKILL.md — the rules table row for object/missing-name-field (the card cited :1091; re-anchored by content, it is :1104 on current main) taught the lint spelling as the contract, so the drift was being taught, not merely implemented. It gains the same distinction as a callout under the table, ending with the actionable form: don't read the R9 list as the derivation contract — set nameField explicitly when the title matters.

Both code comments carry the same closing line: do not "fix" either set into the other without a ruling that supersedes this one.

Zero behavior change

git diff --stat — 3 files, 64 insertions, 1 deletion (the one deletion is the single-line docblock above NAME_ISH_EXACT, replaced by the longer one):

 packages/lint/src/data-model-rules.ts  | 26 ++++++++++++++++++++++++++
 packages/spec/src/data/display-name.ts | 25 ++++++++++++++++++++++++-
 skills/objectstack-data/SKILL.md       | 14 ++++++++++++++

Filtering the diff's added lines to those that are not comment or blockquote prose returns nothing — no executable line is added, removed or moved, no test file is touched, no generated output changes. Both sets are byte-identical to main.

Gates

Gate Result
packages/lintpnpm test 70 files / 1852 tests passed
packages/specpnpm test 362 files / 9468 tests passed
tsc --noEmit (lint + spec) clean
pnpm check:changeset-gate-self-tests pass (118 + 142 + 117 assertions)
pnpm check:skill-frame-sync / -freshness / check:skill-compatibility pass
pnpm check:doc-authoring pass — 374 files clean
pnpm check:role-word, pnpm check:nul-bytes pass

Untouched-test-file proof: the diff touches exactly the three files listed above; no *.test.ts appears in it, so the two green suites ran against unmodified test code.

Changeset

None — skip-changeset applies. AGENTS.md §1018 requires a changeset for feature or functional work; pure bug fixes do not need one, and this PR is neither — it ships no behavior and therefore declares no release of its own, which is the exemption's own wording in pr-automation.yml ("this PR declares no release of its own"). The gate has no path-based auto-exemption, so the skip-changeset label is the mechanism; the gate's self-tests were run and pass, confirming which branch applies.

ADR boundary — deliberately not touched

docs/adr/** is untouched. ADR-0079 records this divergence as its open question 4, and closing that ledger entry is a maintainer-merged ADR edit (PD #14) — not something this PR may do. The maintainer can update ADR-0079's open-question ledger separately; these three notes stand on their own and do not presuppose how that entry is eventually closed.

Also untouched, per the binding rules: content/docs/releases/.


Generated by Claude Code

… two name-like sets (#6734)

Two sets answer "is this field name record-title-ish", and they differ by
exactly one entry, `code`:

  packages/lint/src/data-model-rules.ts   NAME_LIKE_FIELDS  — has 'code'
  packages/spec/src/data/display-name.ts  NAME_ISH_EXACT    — does not

Per the maintainer's 2026-08-10 ruling on #6734 ("document the gap, no
behavior change"), both sets stay exactly as they are. What was defective
was that the divergence was invisible, not that it exists — so it is now
written down where both sets are defined, each pointing at the other:

- lint R9 (`object/missing-name-field`) asks the looser "will records be
  anonymous?" question — any readable face counts, so `code` counts;
- ADR-0079 derivation (`resolveDisplayField`) asks "what IS the title?" —
  an identifier is not a title, so `code` is deliberately absent from
  tier 1/2 and a `code`-only object derives at tier 3 instead.

`skills/objectstack-data/SKILL.md` taught the lint spelling as the
contract, so the drift was being taught; it gains the same distinction
note.

Nothing user-visible turns on the gap (R9 is `severity: 'suggestion'` and
the `Record #<id>` floor guarantees a title regardless).

ZERO behavior change: the diff is comments and prose only — no code path,
no test file, no generated output moves.

`docs/adr/**` is deliberately untouched: ADR-0079 records this as its open
question 4, and closing that ledger entry is a maintainer-merged ADR edit.

Closes #6734
@vercel

vercel Bot commented Aug 10, 2026

Copy link
Copy Markdown

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

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
objectstack Ignored Ignored Aug 10, 2026 8:05am

Request Review

@os-zhuang os-zhuang added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Aug 10, 2026 — with Claude
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/lint, @objectstack/spec.

106 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

  • content/docs/ai/agents.mdx (via @objectstack/spec)
  • content/docs/ai/skills-reference.mdx (via @objectstack/spec)
  • content/docs/ai/skills.mdx (via @objectstack/spec)
  • content/docs/api/client-sdk.mdx (via @objectstack/spec)
  • content/docs/api/environment-routing.mdx (via @objectstack/spec)
  • content/docs/api/error-catalog.mdx (via @objectstack/spec)
  • content/docs/api/error-handling-client.mdx (via @objectstack/spec)
  • content/docs/api/error-handling-server.mdx (via @objectstack/spec)
  • content/docs/api/index.mdx (via @objectstack/spec)
  • content/docs/automation/approvals.mdx (via @objectstack/spec)
  • content/docs/automation/connectors.mdx (via @objectstack/spec)
  • content/docs/automation/flows.mdx (via @objectstack/spec)
  • content/docs/automation/hook-bodies.mdx (via @objectstack/lint, packages/spec)
  • content/docs/automation/hooks.mdx (via @objectstack/spec)
  • content/docs/automation/index.mdx (via @objectstack/spec)
  • content/docs/automation/webhooks.mdx (via @objectstack/spec)
  • content/docs/automation/workflows.mdx (via @objectstack/spec)
  • content/docs/concepts/architecture.mdx (via @objectstack/spec)
  • content/docs/concepts/design-principles.mdx (via packages/spec)
  • content/docs/concepts/index.mdx (via @objectstack/spec)
  • content/docs/concepts/metadata-driven.mdx (via @objectstack/spec)
  • content/docs/concepts/metadata-lifecycle.mdx (via packages/spec)
  • content/docs/concepts/north-star.mdx (via @objectstack/spec)
  • content/docs/data-modeling/analytics.mdx (via @objectstack/spec)
  • content/docs/data-modeling/drivers.mdx (via @objectstack/spec)
  • content/docs/data-modeling/external-datasources.mdx (via @objectstack/spec)
  • content/docs/data-modeling/field-types.mdx (via @objectstack/spec)
  • content/docs/data-modeling/fields.mdx (via @objectstack/spec)
  • content/docs/data-modeling/formulas.mdx (via @objectstack/spec)
  • content/docs/data-modeling/index.mdx (via @objectstack/spec)
  • content/docs/data-modeling/objects.mdx (via @objectstack/spec)
  • content/docs/data-modeling/queries.mdx (via @objectstack/spec)
  • content/docs/data-modeling/schema-design.mdx (via @objectstack/spec)
  • content/docs/data-modeling/seed-data.mdx (via @objectstack/spec)
  • content/docs/data-modeling/validation-rules.mdx (via @objectstack/spec)
  • content/docs/data-modeling/validation.mdx (via @objectstack/spec)
  • content/docs/deployment/cli.mdx (via @objectstack/spec)
  • content/docs/deployment/tenancy-modes.mdx (via @objectstack/spec)
  • content/docs/deployment/troubleshooting.mdx (via @objectstack/spec)
  • content/docs/deployment/validating-metadata.mdx (via @objectstack/spec)
  • content/docs/getting-started/build-with-claude-code.mdx (via @objectstack/spec)
  • content/docs/getting-started/common-patterns.mdx (via @objectstack/spec)
  • content/docs/getting-started/examples.mdx (via @objectstack/spec)
  • content/docs/getting-started/quick-reference.mdx (via @objectstack/spec)
  • content/docs/getting-started/quick-start.mdx (via @objectstack/spec)
  • content/docs/getting-started/your-first-project.mdx (via @objectstack/spec)
  • content/docs/kernel/cluster.mdx (via @objectstack/spec)
  • content/docs/kernel/contracts/auth-service.mdx (via packages/spec)
  • content/docs/kernel/contracts/cache-service.mdx (via packages/spec)
  • content/docs/kernel/contracts/data-engine.mdx (via @objectstack/spec)
  • content/docs/kernel/contracts/index.mdx (via @objectstack/spec)
  • content/docs/kernel/contracts/metadata-service.mdx (via packages/spec)
  • content/docs/kernel/contracts/storage-service.mdx (via @objectstack/spec)
  • content/docs/kernel/index.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/data-service.mdx (via @objectstack/spec)
  • content/docs/kernel/runtime-services/email-service.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/examples.mdx (via @objectstack/spec)
  • content/docs/kernel/runtime-services/index.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/queue-service.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/sharing-service.mdx (via @objectstack/spec)
  • content/docs/kernel/runtime-services/sms-service.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/storage-service.mdx (via @objectstack/spec)
  • content/docs/kernel/services-checklist.mdx (via @objectstack/spec)
  • content/docs/kernel/services.mdx (via @objectstack/spec)
  • content/docs/permissions/authorization.mdx (via @objectstack/lint, @objectstack/spec)
  • content/docs/permissions/permission-sets.mdx (via @objectstack/spec)
  • content/docs/permissions/permissions-matrix.mdx (via @objectstack/spec)
  • content/docs/permissions/positions.mdx (via @objectstack/spec)
  • content/docs/permissions/rls.mdx (via @objectstack/spec)
  • content/docs/permissions/sharing-rules.mdx (via @objectstack/spec)
  • content/docs/permissions/system-context.mdx (via packages/spec)
  • content/docs/plugins/adding-a-metadata-type.mdx (via @objectstack/spec)
  • content/docs/plugins/development.mdx (via @objectstack/spec)
  • content/docs/plugins/index.mdx (via @objectstack/spec)
  • content/docs/plugins/packages.mdx (via @objectstack/spec)
  • content/docs/protocol/backward-compatibility.mdx (via @objectstack/spec)
  • content/docs/protocol/diagram.mdx (via packages/spec)
  • content/docs/protocol/kernel/config-resolution.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/i18n-standard.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/index.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/plugin-spec.mdx (via @objectstack/spec)
  • content/docs/protocol/knowledge.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/index.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/schema.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/security.mdx (via packages/spec)
  • content/docs/protocol/objectql/state-machine.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/actions.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/concept.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/index.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/layout-dsl.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/record-alert.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/widget-contract.mdx (via @objectstack/spec)
  • content/docs/ui/actions.mdx (via @objectstack/spec)
  • content/docs/ui/apps.mdx (via @objectstack/spec)
  • content/docs/ui/create-vs-edit-form.mdx (via @objectstack/spec)
  • content/docs/ui/dashboards.mdx (via @objectstack/spec)
  • content/docs/ui/field-grouping-and-order.mdx (via @objectstack/spec)
  • content/docs/ui/forms.mdx (via @objectstack/spec)
  • content/docs/ui/index.mdx (via @objectstack/spec)
  • content/docs/ui/public-data-collection.mdx (via @objectstack/spec)
  • content/docs/ui/setup-app.mdx (via @objectstack/spec)
  • content/docs/ui/translations.mdx (via @objectstack/spec)
  • content/docs/ui/views.mdx (via @objectstack/spec)

7 release-owned page(s) also reference the affected code. These are read-only:

  • content/docs/releases/implementation-status.mdx (via @objectstack/spec)
  • content/docs/releases/index.mdx (via @objectstack/spec)
  • content/docs/releases/v12.mdx (via @objectstack/spec)
  • content/docs/releases/v13.mdx (via @objectstack/spec)
  • content/docs/releases/v16.mdx (via @objectstack/spec)
  • content/docs/releases/v17.mdx (via @objectstack/lint, @objectstack/spec)
  • content/docs/releases/v9.mdx (via @objectstack/spec)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

@github-actions github-actions Bot added documentation Improvements or additions to documentation protocol:data labels Aug 10, 2026
@os-zhuang
os-zhuang marked this pull request as ready for review August 10, 2026 08:59
@os-zhuang
os-zhuang added this pull request to the merge queue Aug 10, 2026
Merged via the queue into main with commit 9157cc5 Aug 10, 2026
30 checks passed
@os-zhuang
os-zhuang deleted the claude/issue-6734-name-like-sets-note branch August 10, 2026 09:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation protocol:data size/s skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

2 participants