docs(spec): state the measured dependsOn spelling facts in the option-description docblock

[claude]

Fixes #13916
Fixes #14583

Clause ②: no — path limb fires (packages/spec/src/data/field.zod.ts, comment text); content limb no: no accept-set or surface change

Comment text plus one rotted doc anchor. No schema member moves and no expect() changes: the option shape accepts and refuses exactly what it did before this branch.

Files

• packages/spec/src/data/field.zod.ts — the option-description docblock
• packages/spec/src/data/field-rows-option-description.test.ts — the file-header docblock and the inline comment inside the refusal pin
• content/docs/permissions/system-context.mdx — one line anchor, rewritten by check-system-context-census.mjs --fix (see "Anchor rot" below). This page is cross-lane shared and is re-dirtied by every landing on it, so origin/main was merged into the branch (no rebase) right before the final union and the census re-run after that merge.

The ruling this states

Maintainer, 2026-09-02, recorded on objectstack-ai/objectui#6153 (comment 5510108593, decision batch item 4, recommendation A, verbatim 「同意」): the contract's field-level cascade key is the camelCase dependsOn; objectui's BaseFieldMetadata mirrors it and its widgets lose their casts; objectui's snake_case twin retires on its own card under enforce-or-remove. That amends the 2026-09-01 ruling, whose premise had been inherited from the very comment this PR corrects — the sentence claiming a snake_case field-level key that this package has never declared.

Independently measured here against the built schema before the wording was written: FieldSchema accepts dependsOn and refuses the snake_case spelling with a rename hint to dependsOn; SelectOptionSchema refuses both spellings and accepts description. Prose and ruling agree, so nothing in the comments rests on a citation alone.

Before / after — the three prose sites

1. field.zod.ts, the option-description docblock

before

Per the same inherited ruling, `dependsOn` is NOT declared here — the canonical
spelling (snake_case) already exists at the field level, and a camelCase twin
would be a second spelling for a declared concept.

after

Per the same inherited ruling this option shape declares `description` and no
cascade key of its own — `field-rows-option-description.test.ts` pins that
refusal. The cascade key this package declares is the camelCase `dependsOn`,
the `FieldSchema` member below; objectui mirrors that spelling on its own
metadata type (maintainer ruling 2026-09-02 on objectui#6153).

2. The pin file's header docblock

before

honest. Per the same inherited ruling, `dependsOn` is deliberately NOT
declared (the canonical snake_case spelling already exists at the field level).

after

honest. Per the same inherited ruling the option shape declares
`description` and no cascade key of its own; the cascade key lives on
`FieldSchema` as the camelCase `dependsOn`, which objectui mirrors
(maintainer ruling 2026-09-02 on objectui#6153).

3. The inline comment inside the refusal pin (a third site triage did not list)

before

`dependsOn`: the inherited #6153 ruling resolves it objectui-side (the widget
reads the canonical field-level snake_case spelling); declaring a camelCase
twin here is explicitly not licensed.

after

`dependsOn`: this option shape carries no cascade key of its own, per the
inherited #6140 / #6153 ruling. The cascade key is `FieldSchema`'s camelCase
`dependsOn`, which refuses the snake_case `depends_on` with a rename hint, and
objectui mirrors that spelling (maintainer ruling 2026-09-02 on objectui#6153).

The before-blocks above spell the snake_case token out in words where quoting it verbatim would defeat the grep below; the diff carries the literal text. No justification sentence replaces the falsified one — the conclusion is stated as what the shape does, with the inherited ruling cited and nothing invented.

Acceptance

#14583's criterion is that grep -n depends_on packages/spec/src/data/field.zod.ts return zero lines. At daf2fd30:

$ grep -n depends_on packages/spec/src/data/field.zod.ts
$ echo $?
1
$ grep -c dependsOn packages/spec/src/data/field.zod.ts   # instrument control
4

Repo-wide under packages/spec/src, git grep -n depends_on now returns three lines and none of them is in field.zod.ts:

packages/spec/src/data/field-rows-option-description.test.ts:208:    // which refuses the snake_case `depends_on` with a rename hint, and
packages/spec/src/ui/view.test.ts:234:      dependenciesField: 'depends_on',
packages/spec/src/ui/view.test.ts:434:        dependenciesField: 'depends_on',

The first is the single permitted mention — the spelling FieldSchema refuses, named where the refusal is pinned. The two view.test.ts lines are dependenciesField: 'depends_on': a gantt fixture naming a user field whose machine name is snake_case, which is correct for a data value (Prime Directive #3) and was never part of the false claim.

Anchor rot

Lint & Repo Gates went red on the previous head in the check:doc-anchors step, at node scripts/check-system-context-census.mjs: the docblock's new height moved the readonly declaration, so content/docs/permissions/system-context.mdx cited a line the census no longer calls an elevation read while the ledger row excusing the real line went unused. Repaired by the fixer the gate names, not by hand:

node scripts/check-system-context-census.mjs --fix
  re-anchored content/docs/permissions/system-context.mdx:199  `field.zod.ts:1537` -> `field.zod.ts:1540`
check-system-context-census --fix: 1 anchor(s) rewritten

All three legs the CI step runs are green at daf2fd30, the census re-run after the origin/main merge: pnpm check:doc-anchors ("298 internal fragment links across 409 source files all resolve"), check-system-context-census.mjs --self-test, and the census itself ("OK — 106 elevation read sites in 20 packages across 45 files, all anchored; 140 anchors resolve, 27 declared non-read").

Changeset

pnpm --filter @objectstack/spec run check:generated (no --fix), after rebuilding dist from the edited source: "✓ All 15 generated artifacts are up to date." The JSDoc is not the JSON-Schema projection (.describe() is, and none changed), and the docs page is not a published package artifact. No changeset; the skip-changeset label stays on this PR.

Verification record — everything below at daf2fd30

• pnpm --filter '@objectstack/spec^...' build + pnpm --filter @objectstack/spec build — VERDICT command-exit 0
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 — 465 files / 12396 tests passed
• pnpm --filter @objectstack/spec run typecheck — clean, including check:test-typecheck ("OK — @objectstack/spec's test layer compiles under packages/spec/tsconfig.test.json"), so the edited test file sits inside a program that was really checked
• pnpm --filter @objectstack/spec run check:generated — 15/15 up to date
• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack re-derived on the post-merge diff (which now includes the docs page, and pulled in the docs family it adds), then 46 gate invocations, all exit 0: spec check:docs check:api-surface check:authorable-surface check:export-origins check:liveness check:llms-txt check:skill-refs check:strictness-ledger check:variant-docs check:yaml-examples check:empty-state check:exported-any check:dual-source-exports check:entry-nameability check:browser-reachable-entries check:skill-examples; repo check:nul-bytes check:merge-driver check:published-files check:doc-authoring check:cross-package-test-inputs check:test-source-alias check:spec-parsed-alias check:partof-closing-keyword check:changeset-gate-self-tests check:objectql-double-limit check:where-matcher check:page-declaration-shape check:slot-lookup check:type-source-resolution check:logger-receiver-detach check:engine-double-contract check:doc-anchors check:corpus-claim-drift check:docs-audit-scope check:docs-redirects check:docs-single-h1 check:published-readme-links check:react-page-adapter-contract check:role-word check:skill-identifier-liveness check:vendor-version-stamps; @objectstack/lint check:doc-formula-expressions and check:doc-security-posture; and the census self-test plus the census

Three gates first exited on their own PREREQUISITE paths (nothing measured, never recorded as findings) and went green after the build they name: check:doc-formula-expressions needed @objectstack/formula and @objectstack/lint built, and check:skill-examples needed @objectstack/client-react built with its dependency closure. Naming note: the dispatch's check:closing-keyword-parity is spelled check:partof-closing-keyword here. Declared narrowing: the repo-wide pnpm lint sweep and the remaining families of the 204 discovered are left to CI, which runs the farm.

Still open elsewhere

#15058 — the pending .changeset/field-rows-and-option-description-declared.md carries a fourth copy of the same false sentence and is release-notes input. It is filed unassigned and stays out of this PR: editing .changeset/** pulls in gate families (check:objectui-changeset, check:pm-half-states) outside this card's verification surface.

🤖 Generated with Claude Code

https://claude.ai/code/session_0174WZTU6XcFcS7g2kykC53i

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 9827f714d5e1f8dcde89b7a5213fccd863c7ebd3 — the merge of head daf2fd30d62d402649c72c15e12ff0e28bef8323 into base 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 9827f714d5e1f8dcde89b7a5213fccd863c7ebd3 && git checkout 9827f714d5e1f8dcde89b7a5213fccd863c7ebd3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 daf2fd30d62d402649c72c15e12ff0e28bef8323 && git checkout -B drift-repro 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 && git merge --no-ff daf2fd30d62d402649c72c15e12ff0e28bef8323

node scripts/docs-audit/affected-docs.mjs --json 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[zhuangjianguo]

CI note (PM seat domain:spec, session_0174WZTU6XcFcS7g2kykC53i, 2026-09-03T19:28Z) — Lint & Repo Gates is red on head 9300bca5 at the check:doc-anchors step: check-system-context-census reports [anchor-is-not-a-read-site] for packages/spec/src/data/field.zod.ts:1537 and [ledger-row-unused] for :1542 (job 100779705679). Root cause: this PR's docblock rewrite adds net lines above the readonly declaration that content/docs/permissions/system-context.mdx anchors, so the citation shifted from :1537 to :1542 — pure line rot, repaired by the gate's own --fix.

This PR is already in a patch round (REWORK verdict on #13916, 5530907654: wording moves to the 2026-09-02 ruling A on objectui#6153, Fixes #14583 added). The dev has been told to fold the census --fix into that same push and to declare the rewritten permissions page in the file list. No separate push for the red; the next head carries both.

---

Generated by Claude Code

[zhuangjianguo]

Landing provenance (PM seat domain:spec, session_0174WZTU6XcFcS7g2kykC53i, 2026-09-03T20:24Z) — flipping to ready and enabling auto-merge (squash).

• Contract review: not applicable (Clause ② no on both carriers, check-clause2-carriers.mjs --pair 15055 exit 0 at 19:59Z); review verdict ACCEPT (round 2) on the chain head — [finding] field.zod.ts option-description docblock 与 field-rows-option-description.test.ts:25 断言「canonical 拼写 depends_on 已存在于字段级」——对 spec 自身为假(字段级现行声明键是 camelCase dependsOn) #13916 comment 5531377372, family pointer on spec field.zod.ts option-shape comment claims a field-level depends_on the spec does not declare — correct the comment (objectui#6153 ruling A follow-up) #14583 (5531378158).
• CI on head daf2fd30: 37 check runs, 34 success + 3 skipped, 0 red, 0 in progress (20:24Z) — including Lint & Repo Gates (the system-context census green after the --fix) and TypeScript Type Check at success.
• Governed-surface test on the 3 changed paths: NOT governed (0 of 3, 19:59Z) — queue landing applies. skip-changeset stands (no published artifact moves).
• mergeable_state: clean (20:24Z). Body first lines Fixes #13916 / Fixes #14583 — one closing line per family member, no other closing keyword in the body.
• Next reading: the added_to_merge_queue timeline event; on MERGED both cards close via Fixes, pm:dispatched is stripped on each in the same action, and the docblock plus the permissions-page anchor are probed on origin/main.

---

Generated by Claude Code