fix(lint): one-line fix lines for 17 more author-time rule ids (slice 15); os explain RULE_ID carries what they explained

[objectstack-fleet]

Part of #22161
Clause-②: no

Stage 2 of the card, slice 15: the over-long fix: lines, continued in slices 11 to 14's shape. Each finding's hint (the CLI's fix: line, the runtime issue's hint) of 17 more packages/lint rule ids, in eight rule files, is now one remedy line of at most 200 characters, and what the lines used to explain is each id's RULE_EXPLANATIONS entry behind os explain RULE_ID. The card stays open: 41 author-time ids still carry a hint over 200 characters (the last section).

What changes

• One remedy line per finding. The 17 ids, every hint the lint suite fires, before → after (count of distinct hints · length range):

rule id	file	lint suite, before → after	runtime door
react-chart-field-unprovisioned	validate-react-page-props.ts	1 · 362 → 1 · 175	CLI only
react-prop-missing-required	same	2 · 71–277 → 3 · 55–131	CLI only
react-page-source-unparseable	same	1 · 254 → 1 · 105	CLI only
react-block-needs-record-context	same	5 · 138–228 → 5 · 105–195	CLI only
action-body-write-unprovisioned-anchor	validate-action-body-writes.ts	1 · 358 → 1 · 171	CLI only
action-body-write-unknown-field	same	9 · 283–323 → 10 · 51–91	CLI only
action-record-write-discarded	same	3 · 307–309 → 3 · 102–104	CLI only
action-body-source-unparseable	same	1 · 254 → 1 · 105	CLI only
agent-authoring-withdrawn	validate-ai-agent-authoring.ts	7 · 79–363 → 7 · 79–158	CLI only
default-agent-outside-roster	same	1 · 237 → 1 · 118	CLI only
flow-node-write-unprovisioned-anchor	validate-flow-node-writes.ts	1 · 358 → 1 · 171	flow write, 2xx advisory
flow-node-write-unknown-field	same	14 · 233–289 → 15 · 54–110	flow write, 422
validation-rule-json-schema-uncompilable	validate-rule-compilability.ts	1 · 341 → 1 · 124	object write, 422
validation-rule-regex-uncompilable	same	5 · 287–300 → 5 · 122–135	object write, 422
translation-section-name-missing	validate-translatable-sections.ts	9 · 335–359 → 9 · 148–172	CLI only
object/managed-api-method-unaffordable	validate-managed-api-methods.ts	7 · 313–357 → 8 · 110–169	object write, 422
nav-object-unservable	validate-nav-object-servability.ts	3 · 342–348 → 3 · 150–156	CLI only

A count that rises is a case this slice added (a far-miss unknown field on the action and flow rules, every write verb on the managed-object rule, a third required binding fired from the contract).

• The reasoning moves, the remedy stays.
  • The three anchor ids (react-chart-field-unprovisioned, action-body-write-unprovisioned-anchor, flow-node-write-unprovisioned-anchor) print unprovisionedAnchorFix(), slice 14's one-line form: the three ways out in one line. How (columnMap, ownership: 'none', systemFields: { audit: false }) is the shared UNPROVISIONED_ANCHOR_REMEDY paragraph, now in their three entries too.
  • The two parse ids (react-page-source-unparseable, action-body-source-unparseable) print PARSE_FAILURE_FIX. What a partially recovered tree leaves unchecked was already their entries'.
  • action-body-write-unknown-field prints the hook sibling's line. Which shapes ACTION_BODY_WRITE_PATTERNS checks, why ctx.input is not one, and that the warning never blocks a build are a new paragraph of its entry. action-record-write-discarded keeps the updateById remedy; why only a provably dead write is reported was already the entry's, and "never blocks a build" joins it.
  • flow-node-write-unknown-field: why it gates where the body rules advise was already the entry's.
  • The two agent ids: that skills attach to ask / build by surface affinity is one shared paragraph, SKILLS_ATTACH_BY_SURFACE, in both entries. The withdrawn-agent entry also says why dropping the persona loses nothing. The line keeps the count of referenced skills, now in the singular for one.
  • The two compile ids: the escaped regex spellings and the named formats, and the shapes type / required / $ref take, are new paragraphs. The regex line still quotes the source.
  • translation-section-name-missing: that the suggested name is never a key derived from the label is the explanation's.
  • object/managed-api-method-unaffordable: removal first, then the affordance "once a guard enforces the write". The ADR-0092 D4 condition was already the entry's.
  • nav-object-unservable: the line keeps "unless it is API-disabled on purpose". The credential-material reason was already the entry's.
• Two lines come from the spec's text, and stay there.
  • react-block-needs-record-context prints the spec's replacement for the block (REACT_RECORD_BLOCK_ALTERNATIVES) behind the lead-in Instead:, where it used to say On a react page bind the record yourself:. That the replacement binds the record itself is a new paragraph of the entry. The longest, record:related_list's, is 195.
  • react-prop-missing-required quotes the contract's description of the missing binding, now its first sentence. That sentence names the binding and its spelling (Pass data={…}: The object this block binds to, written as the metadata-tier data source: data={{ provider: 'object', object: '…' }}). The cut is the one schemaRefusalHead makes for a forwarded spec refusal. The rest of ListView.data's description (which providers are accepted, why the prop is required) is the contract's, and the published react-blocks reference carries it whole.
  • New pins hold both to the bound across the spec's whole table. Every REACT_RECORD_BLOCK_ALTERNATIVES entry and every required binding in REACT_BLOCKS is fired and held to 200. A spec edit that grows one past it turns the rule's test red.
• Nothing else moves.
  • Every message, rule id, severity and path is unchanged, and so is what each rule accepts or refuses.
  • Every hunk in the eight rule files is a hint expression, a comment, an import swapped to a shared short form, or descriptionHead().
  • No condition, branch, skip or dedupe moved, and no name is added to or removed from a published entry.
• .changeset/22161-lint-slice-15-one-line-fix.md: @objectstack/lint patch, Clause-②: no, with the runtime hint FROM → TO for every id that fires at the runtime gate.

File surface: the claim's

The claim (6133662163) names the eight rule files, rule-explanations.ts, the shared one-line producers where an id converges on them, a text-only test rider and the changeset.

• The edits stay inside it. system-fields.ts and checked-parse.ts needed no edit: the ids converge on slice 14's unprovisionedAnchorFix() and PARSE_FAILURE_FIX as they are.
• packages/cli and packages/metadata-protocol needed no rider: no entry was added, and no test there reads these hints' text.
• After this slice unprovisionedAnchorHint() keeps three callers (validate-widget-bindings.ts, validate-flow-template-paths.ts, validate-page-field-bindings.ts). PARSE_FAILURE_HINT keeps one (lint-startup-registry-verdict.ts).

The runtime wire

Measured at the door with runRuntimeAuthoringRules, on the base dist and on the rebuilt one: a scratch probe of 19 writes across object, flow, action, page, app, agent and view.

• an object write:
  • object/managed-api-method-unaffordable (422 issues[].hint): two refused verbs / every write verb, 335 / 372 → 132 / 169;
  • validation-rule-regex-uncompilable (422): the pattern ([ / a 28-character pattern, 288 / 314 → 123 / 149;
  • validation-rule-json-schema-uncompilable (422): 341 → 124.
• a flow write:
  • flow-node-write-unknown-field (422): with / without a near miss, 271 / 250 → 92 / 71;
  • flow-node-write-unprovisioned-anchor (2xx advisories[].hint): 361 → 174.
• No write reaches the other twelve.
  • The four react-page ids, the four action-body ids, the two agent ids, translation-section-name-missing and nav-object-unservable are reference-suite members on the frozen flow default. A flow snapshot carries none of the collections they read.
  • The action, page, app, agent and view writes in the probe drew no finding at all.

Readers of hint, read-only against objectui main at 1fb1ced3 (the local origin/main, equal to the remote's; git grep for .hint reads, nothing fetched):

• Studio's saveAdvisoryToast.ts formatFinding renders [rule] where — message hint for every 2xx advisory, so the flow-node anchor toast shortens.
• DraftChangesPanel.tsx reads hint only for its in-browser security-posture pass (none of these ids).
• No objectui source reads a 422 issue's hint.
• REST (PUT /api/v1/meta) forwards issues / advisories as JSON (toIssue copies hint verbatim). packages/mcp registers no metadata write tool, so an MCP or AI author reaches the gate through REST.
• No reader in either repository matches on hint text. check:watch-hint-literal guards something else of the same name and ran in the gate set.

Census (taken first, before any edit, at the base abf86554c)

Method: the earlier slices' scratch preload (NODE_OPTIONS=--import, never committed). It patches Array.prototype.push to record every finding-shaped object, deduped by (rule, hint) per process, with its push site. Lengths are the hint alone.

• packages/lint suite: the 17 ids re-measured at the base equal the claim's lengths exactly (362, 277, 254, 228, 358, 323, 309, 254, 363, 237, 358, 289, 341, 300, 359, 357, 348).
  • Base: 240 ids fire, 82 over 200 = 21 fenced + 3 repo-gate + 58 author-time. The 58 are slice 14's remaining list, id for id.
  • After, at c6f65c38a: 240 ids fire, 65 over 200 = 21 fenced + 3 repo-gate + 41 author-time, and every hint of the 17 is at most 200 (the table). The 41 are the 58 less these 17.
• Runtime publish gate, the whole @objectstack/metadata-protocol suite (which reads @objectstack/lint from source), in a base worktree and at the branch: validation-rule-json-schema-uncompilable 341 → 124 at the door, and none of the other 16 fires there. Test Files 228 passed, 3 skipped (231), Tests 28,224 passed, 19 skipped, in both.
• packages/cli unit tier, base worktree and branch: agent-authoring-withdrawn (its zero-skill arm) 196 → 112, and none of the other 16 fires there. Test Files 285 passed (285), Tests 4,280 passed (4,280), in both.
• os validate (the built CLI) on app-crm, app-todo, app-showcase and app-multi-package, base worktree and branch:
  • exit 0 each, and none of the 17 fires;
  • each prints the same 9 / 7 / 70 / 3 rule: lines;
  • the output is byte-identical once the worktree path and the millisecond timings (Load time, Validation passed (…ms)) are normalised. Those are the only differing lines.

Tests

Every heavy run went through scripts/pm/os-verify-lock.sh (slots issue-22161-s15, issue-22161-s15-base). Its VERDICT lines are in the report.

• Each rule's own suite pins the new shape. Each of the eight test files gains a last block. It holds every recorded fix: line of its converted ids to one line of at most 200 characters, behind a coverage control naming each arm:

  • the unknown-field lines with and without a suggestion (a far-miss case added on the action and flow rules);
  • both agent arms, with no, one and several referenced skills;
  • one, several and every refused verb;
  • both nav arms;
  • a record block with a named replacement and with the generic advice.

  A check per id then asserts that explainRule(id) holds what the line stopped saying. Seven recorders now keep hint beside message.

• Moved pins. Pins that read the old hint text moved to the explanation, text-only: the section rule's "never a key derived from the label", and the managed-object rule's ADR-0092 D4. The agent rule's zero-skills negative now names the new wording.

• New pins hold an explanation's spelled-out list to its source: the named regex formats to FormatValidationSchema's format enum, and the JSON Schema primitive types.

• Lint suite at c6f65c38a: Test Files 137 passed (137), Tests 6,646 passed (6,646); VERDICT command-exit 0. At the base: Test Files 137 passed (137), Tests 6,614 passed (6,614).

• Lint build and typecheck at c6f65c38a: pnpm install --frozen-lockfile && pnpm turbo run build --filter=@objectstack/lint... (lint's build script runs check-dts-emitted) and pnpm --filter @objectstack/lint run typecheck (tsc --noEmit + check:test-typecheck OK: 2 files / 6 errors / 2 pinned signatures held), VERDICT command-exit 0 each. The rebuilt dist carries the new text: Instead: , once a guard enforces the write and author skills instead have 1 hit each in index.js and runtime.js, and the new agent paragraph's text is in index.js and rule-explanations.js. The old lines are gone: On a react page bind the record yourself, Do NOT open the API on an object and This gates the build rather than warning: the key is literal have 0 hits in all three.

• The built entries' export closure is unchanged (the Clause-② check): the runtime export keys and the declaration exports of index, runtime and rule-explanations are identical, read from the base dist (abf86554c) and from the branch's rebuilt dist (5aaa606c9): 371 / 553, 6 / 11 and 2 / 3 names, 0 added and 0 removed. Read again at the final head against a main dist (21c86444e): the same counts, 0 added and 0 removed.

• CLI unit tier and metadata-protocol suite: measured before the merge, at 5aaa606c9, against a base worktree at abf86554c, VERDICT command-exit 0 for all four runs. CLI unit tier: Test Files 285 passed (285), Tests 4,280 passed (4,280), in both. metadata-protocol: Test Files 228 passed, 3 skipped (231), Tests 28,224 passed, 19 skipped, in both. Not rerun after the merge: main brought no packages/lint file, and the final lint census equals the pre-merge one id for id.

• Ablation: one-shot, from the committed head 5aaa606c9, through scripts/ablation-replace.mjs under the lock, with a shell trap restoring HEAD by absolute path. The rule suite imports the rule source, so there is no dist leg.

  • Mutation: flow-node-write-unknown-field's pre-slice caveat ("This gates the build rather than warning: …") restored in fixHint().
  • Predicted before the run: exactly the two new slice-15 cases in validate-flow-node-writes.test.ts go red, and every other case stays green.
  • Observed: Tests 2 failed, 42 passed (44), exactly those two, printing the old line.
  • The mutation landed (anchor x1 → x0, replacement x0 → x1, blob 084b6a3acbae → e2b288d993f2) and was restored (blob 084b6a3acbae == HEAD, git diff HEAD empty, git status --porcelain empty). The rule file and its test have the same blobs at the final head.

• ESLint, narrowed: npx eslint --no-inline-config --format json over the 17 changed .ts files at c6f65c38a: 17 files, 0 errors, 0 warnings.

  • The population is eslint.config.mjs's **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} block plus its packages/** blocks.
  • The config never enables type-aware linting (no parserOptions.project), so no untouched file's verdict can move.
  • A control-character scan of every changed file found no match.

• Gates: one merge of origin/main through scripts/pm/os-regen-merge.sh (5aaa606c9 → c6f65c38a, onto 21c86444e). No conflict, and the branch edits no generated artifact. main brought packages/spec, packages/cli and packages/metadata-protocol changes and no packages/lint file.

  • node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, with no paths, at c6f65c38a (18 paths vs the merge base 21c86444e) derived 62 commands.
  • 61 ran, each exit code captured before any pipe, all 0. The longest: check:query-options-erasure 290s, check:slot-lookup 151s, check-comment-mask-corpus 112s.
  • check:dual-build-cjs-loads first refused (exit 3, PREREQUISITE NOT MET: six packages had no dist). After building those six with their closure under the lock (VERDICT command-exit 0) it ran, exit 0 (107 entry points across 66 packages).
  • NOT MEASURED, by the dispatch's order: check:type-check-debt.
  • --ran: 62 derived famil(ies) accounted for — 61 run, 1 NOT-MEASURED.
  • origin/main moved five commits after the merge (240890cfb … e9e10fdab), touching no packages/lint file; not merged again.
  • The artifact-roster and PR-context families are CI's.

Acceptance notes

• A long name can still lengthen a line. The bound holds on every variant the suites, the runtime probe and the four example apps fire. The names in a hint are the author's: the object and field of the anchor lines, the section heading's slug (twice), the regex source, the nav target. The closest measured case is react-block-needs-record-context at 195 (a fixed spec string, record:related_list's replacement). After it comes translation-section-name-missing at 172 (showcase_contact / who_is_this).
• react-prop-missing-required still has no os explain entry. An entry is keyed to a rule id constant the root barrel exports, and this id has none: it is a literal in validate-react-page-props.ts. Exporting one would add a name to @objectstack/lint's published entry, which is Clause-②: yes, against this claim's no. So the route's "an id without an entry gains one" is not applied here. What its line stopped quoting is the contract's own text, which the published react-blocks reference keeps whole.
• A record block's line keeps the spec's sentence verbatim, a trailing period included. record:related_list's replacement is 186 characters on its own, so the lead-in is a word. If the spec's table grows past the bound, the new pin turns red rather than printing a second line.
• The long forms stay for their other callers. unprovisionedAnchorHint() keeps three ids outside this slice and PARSE_FAILURE_HINT one (a repo-gate id). Each converges on the short form when its slice comes.
• A docs transcript predates this card. content/docs/ui/react-pages.mdx quotes an os validate transcript of react-block-needs-record-context whose verdict and fix: line are both pre-[maintainer] validate: the field-no-consumers warning is one 856-character line, printed by validate, build and dev alike — one-line verdict + rule: id + a pointer to the full reasoning (os explain, which today takes only schema names) #22161 wording. The verdict changed in an earlier slice. It is a hand-written example, and check:docs-transcript-drift compares only the registry-derived numbers in a transcript, never finding text. No code path consumes it. Carrier: none named; noted, not filed.

Remaining for this card

41 author-time packages/lint ids still carry a hint over 200 characters in the final lint census (at c6f65c38a: 65 over 200 = 41 + 21 fenced + 3 repo-gate), by file, longest first:

• lint-flow-patterns.ts (2): flow-double-brace-interpolation 1413, flow-bare-dollar-reference 1234
• data-model-rules.ts (6): unique/legacy-organization-composite 578, unique/unscoped-declared-index 380, object/missing-name-field 327, rollup/non-numeric-aggregand 282, unique/double-declaration 279, field/select-missing-options 207
• validate-widget-bindings.ts (11): dashboard-filter-field-unprovisioned 561, chart-field-unknown 415, dashboard-filter-field-unknown 403, chart-measures-missing 369, widget-legacy-analytics-shape 338, widget-measures-missing 330, widget-filter-field-unknown 322, widget-legacy-analytics-unrenderable 320, table-count-only 311, chart-dimensions-missing 291, dashboard-filter-field-not-included 218
• validate-dataset-references.ts (2): dataset-include-unknown 336, dataset-field-unknown 206
• validate-translation-references.ts (1): translation-target-unknown 317
• validate-approval-approvers.ts (3): approval-approver-not-membership-tier 313, approval-expression-no-empty-policy 294, approval-expression-invalid 292
• validate-seed-replay-safety.ts (1): seed-insert-mode-duplicates-on-replay 309
• validate-chart-bindings.ts (1): chart-measure-unknown 285
• validate-object-field-refs.ts (1): object-field-ref-unknown 284
• validate-capability-references.ts (1): capability-reference-unknown 273
• validate-record-title.ts (2): title-format-retired 267, title-unresolvable 237
• validate-list-view-field-refs.ts (2): list-view-field-unknown 258, list-view-field-dotted 233
• validate-view-containers.ts (1): view-container-shape 256
• validate-seed-state-machine.ts (1): seed-value-outside-state-machine 251
• validate-ai-surface-affinity.ts (1): ai-skill-surface-mismatch 235
• validate-page-source-styling.ts (1): page-source-className-tailwind 231
• lint-liveness-properties.ts (1): liveness-planned-property 230
• validate-page-field-bindings.ts (2): page-section-count-not-multi-value 228, page-field-unknown 206
• validate-list-view-mode.ts (1): list-view-filters-in-views-mode 219

Not in the 41: the 26 fenced ids as PR #22448 lists them (21 fire a hint over 200), the 3 repo-gate ids (startup-open-vocabulary-verdict, startup-source-unparseable, startup-verdict-assertive-wording), and the packages/cli ids on #22841.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 13 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/validating-metadata.mdx (via validateRuleCompilability (symbol, a top-level function))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 4 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 bcebd8409d4fa6f962f83fe2d1d32d944c7818bf → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fbf520d2d1c07d27506eeeb1cbf7438464aa49de — the merge of head c6f65c38a267171b94357b7e38d7c68cc74d35ba into base bcebd8409d4fa6f962f83fe2d1d32d944c7818bf, 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 fbf520d2d1c07d27506eeeb1cbf7438464aa49de && git checkout fbf520d2d1c07d27506eeeb1cbf7438464aa49de
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin bcebd8409d4fa6f962f83fe2d1d32d944c7818bf c6f65c38a267171b94357b7e38d7c68cc74d35ba && git checkout -B drift-repro bcebd8409d4fa6f962f83fe2d1d32d944c7818bf && git merge --no-ff c6f65c38a267171b94357b7e38d7c68cc74d35ba

node scripts/docs-audit/affected-docs.mjs --json bcebd8409d4fa6f962f83fe2d1d32d944c7818bf

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs bcebd8409d4fa6f962f83fe2d1d32d944c7818bf → pass the list as
args.docs, on the commit named under Which tree this was computed on.