fix(spec): the object-grid page-size migration entry states that a stored page still saves, with an advisory CLI finding - #20884

📓 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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 6a6b641a4b9dc447ed8f5facaa02a1d35ec7f179 && git checkout 6a6b641a4b9dc447ed8f5facaa02a1d35ec7f179
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9905e61ca2fddb43d266c23cdb12ced5019c1a74 a3fd6c8aef0f9696f736ad32fa1d516f6c900a1b && git checkout -B drift-repro 9905e61ca2fddb43d266c23cdb12ced5019c1a74 && git merge --no-ff a3fd6c8aef0f9696f736ad32fa1d516f6c900a1b

node scripts/docs-audit/affected-docs.mjs --json 9905e61ca2fddb43d266c23cdb12ced5019c1a74

Contract review

PR #20884 (card #20860) — fix(spec): the object-grid page-size migration entry states that a stored page still saves, with an advisory CLI finding.

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: a3fd6c8aef0f9696f736ad32fa1d516f6c900a1b
Local-runs: none

Inputs: the card body and its three comments (triage 5912835288, the dispatch claim 5913355847, the os-dev-report 5914065022); the PR body, its file list and the net diff origin/main...refs/review/pr20884 (merge-base 6c96b37be8); the check-runs on the head. Every factual claim below was checked against origin/main at 0803a8b871 with git show / git grep, never the shared working tree. The one merge probe is the sanctioned driverless merge-tree --write-tree from a bare probe clone in scratch that shares the object store and registers no merge driver.

① Derived judgments

The diff. Three files, 39/6. (1) packages/spec/src/migrations/entries/semantic/18.ui-object-grid-page-size-positive-integer-refused.ts: one sentence of acceptanceCriteria replaced; id, surface, replacement, reason untouched. (2) packages/spec/src/migrations/registry.ts: one hunk in the step-18 region. Read independently: with leading whitespace stripped, the registry hunk's +/- lines are byte-identical to the entry hunk's (cmp exit 0, 10 lines each), which is what gen:migration-registry produces from the entry. (3) .changeset/20860-page-size-entry-advisory.md. No Zod schema, no conversion, no export, no matching logic and no test moves.

• Accept set: unchanged — right. The diff touches string literals only. Nothing an author can write parses differently at head than at base.
• Public surface: unchanged — right. No export added, removed or renarrowed; the dev's check:api-surface reading ("unchanged") is consistent with the file list.

The corrected sentence, claim by claim, against origin/main:

• "still saves and loads — properties on a page component is not parsed on the metadata save path" — right. PageComponentSchema.properties is z.record(z.string(), z.unknown()).optional().default({}) (packages/spec/src/ui/page.zod.ts:324). validateComponentProps / ComponentPropsMap have 0 non-test hits under packages/metadata-protocol/src, packages/objectql/src, packages/metadata/src, packages/rest/src and packages/runtime/src; the control hit is packages/lint/src/authoring-rules.ts:113. The route the card names, PUT /api/v1/meta/:type/:name, hands its body to p.saveMetaItem(saveRequest) with writeFace: 'meta-envelope' (packages/rest/src/rest-server.ts:7008, :7018), the call the dev drove on both faces. The rule's own hint says the same thing: "the props bag is not parsed on the storage path either" (packages/lint/src/validate-component-props.ts:325-326).
• "the component-props gate reports it as an advisory component-props-invalid finding at pagination.pageSize on os validate, os build and os lint" — right. The rule row validateComponentProps (authoring-rules.ts:1021-1030) carries tier: 'advisory', commands: ALL, surfaces: CLI_ONLY. The finding's rule id is COMPONENT_PROPS_INVALID = 'component-props-invalid' (validate-component-props.ts:115) and its message is built as the path relative to the props bag, so it reads pagination.pageSize: Too small … (:322). The three commands each call the rule runner: validate.ts:461 runAuthoringRules('validate', …), compile.ts:494 ('build', …), lint.ts:680 ('lint', …).
• "a pageSizeOptions entry and the flat pageSize shorthand are reported the same way at their own paths" — right. ObjectGridPropsSchema declares pagination: z.looseObject({ pageSize: GridPageSizeSchema.optional(), pageSizeOptions: z.array(GridPageSizeSchema).optional() }) and the flat pageSize: GridPageSizeSchema.optional(), with GridPageSizeSchema = z.number().int().positive() (packages/spec/src/ui/component.zod.ts:3405, :3612-3618). One schema, one rule, three paths.
• "the author deletes the key or writes the page size they meant, and os validate then reports no component-props-invalid finding for that node" — right. Both members are optional and the pagination bag is looseObject, so an emptied bag and a positive integer both parse clean.
• The sentence is text os migrate meta shows an author as verify:; packages/cli/test/migrate-meta-engine-guidance.test.ts pins that every entry's acceptanceCriteria carries no tracker number. The new text carries none — right; that pin runs in Test Core, in progress at this reading.

Scope held. Triage's direction was the sentence and nothing on the save path; the diff changes no judgment. surface, replacement and reason state no save-path refusal at head, so leaving them is right. The sibling 18.object-grid-default-filters-rule-array.ts is unchanged on both origin/main and the head, and its reason already says the key's door "refuses such a value only as the component-props gate's advisory finding … since a re-save through the metadata API is not refused there" — leaving it is right. The exact old phrase survives on the head only in the two ui-list-view-*-padded-refused entries, which are view-arm entries outside this card's surface and not judged here.

Generated copy against a moved main. registry.ts is not a merge=os-regen path (read off .gitattributes), so the queue text-merges it. Since the base, origin/main brought 35 insertions to registry.ts (the step-18 region PR #20868 added) and did not touch either entry file. The old sentence occurs exactly once in origin/main's registry.ts, and the driverless merge-tree --write-tree of 0803a8b871 with a3fd6c8aef wrote tree e9c6c611 with no conflicted path. The byte-exact confirmation is the queue's check:migration-registry on the merge ref — a gate the dev read green at head, and the Lint & Repo Gates run on the merge ref is what settles it.

Governance and shape. No path in the file list is a register row (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, docs/NORTH-STAR.md); Governed Surface Queue Guard is success. Head repo equals base repo. Draft, no auto-merge armed. The PR body's Clause-②: no line is present.

Check-runs on the head, read at 2026-09-30T15:18Z — 33 runs: 20 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke — opt-in), 10 in progress, none failed. Required-set readings: Build Core success; Dogfood Regression Gate success (all three shards); Governed Surface Queue Guard success; Lint & Repo Gates in progress; Temporal Conformance (live PG + MySQL) in progress; Test Core (1/6 through 6/6) in progress; Type Check · source gates and · debt ledger success, · workspace and · consumer gates in progress. Also success: Check Changeset, Check PR Size, Spec property liveness, the claim/branch/single-writer guards. These conclusions are the gate verdicts; this record judges the diff, and enqueue still waits on every required check reaching success.

② Semver level

@objectstack/spec patch — right. The entry text ships inside the package's dist and is printed to authors by os migrate meta, so the diff publishes from a released package and skip-changeset would be wrong; it changes no accept set and no export, so patch is the level and nothing higher is owed.

Clause-②: no — right, and consistent across the dispatch claim, the PR body and the changeset. Not breaking, so no ADR-0087 disposition marker is owed; the dev's check:adr-0087-registration reading ("no declared-breaking changeset") matches. The changeset body carries the migration-entry id, the measured outcome and no model identifier. The commit at head ends with the model-free trailer pair (Claude-Session: plus a plain Co-authored-by: Claude), and the PR body ends with the session-URL footer.

③ Boundary flags

Dev open_questions: none. Dev deviations, each answered:

1. Stale tree (origin/main six commits ahead, not merged). Answered above: entry files unchanged on main; registry.ts moved in a disjoint region; driverless merge-tree clean; the queue measures the merge ref. Accepted.
2. HTTP door not booted; save measured through saveMetaItem. The PUT handler's write is that call with writeFace: 'meta-envelope' (rest-server.ts:7008-7018), and the probe ran both faces with the runtime authoring gate live. The sentence claims the metadata save path, which is what was measured. Accepted.
3. vitest bare -- relaunch, self-corrected. Process hygiene, no bearing on the diff or on the green numbers, which come from the relaunch. Accepted.
4. Scratchpad file moved. No bearing. Accepted.
5. Attribution conflict resolved in favour of AGENTS.md. Verified at head: commit trailers are the model-free pair, PR body footer is the session-URL form. Accepted.

Dev out_of_scope_findings — the released @objectstack/spec CHANGELOG entry for 9bb059d ("the object-grid page-component door now refuses a page size of 0 …"). Read at packages/spec/CHANGELOG.md:4763-4769: the "door" it names is the ComponentPropsMap schema, which does refuse 0 (GridPageSizeSchema), and its body attributes the earlier success: true to "this schema". It states no save-path outcome, so it is not class (a) false text; the CHANGELOG is release-owned. The dev's disposition (noted, not filed) is accepted; nothing to escalate.

The card's own ⛔ "not measured" (a save through the route) is discharged by the two measurements in the PR body; triage's ⛔ "not a change to what the save path judges" holds — the diff changes no judgment. The PR body's "owed before enqueue" flag is this record.

Implemented-by: claude/issue-20860-page-size-entry-advisory
Reviewed-by: session_018fxqvRJW12TaHC7DUQ89Y6

VERDICT: PASS

Generated by Claude Code