finding(plugin-gantt): `GanttConfigRestated`'s “kept for ONE reason: their JSDoc” rationale does not hold for `parentField`, which has none

[claude]

Measured while writing standalone prose for the flat gantt face (objectui#6547, PR objectui#6561). Filed unassigned, observational.

The fact

GanttConfigRestated in packages/plugin-gantt/src/ObjectGantt.tsx carries a docblock stating why its restated members are kept rather than deleted:

Ten are RESTATEMENTS: GanttConfig already declares them (nine of the ten arrive from the spec's GanttConfigSchema, which declares 19 keys), and the type written here is mutually assignable with the twin. They are kept, not deleted, for ONE reason — their JSDoc is the only prose in this repo describing what this renderer DOES with each key.

Measured against the type on main @ 0235ce7c1, four of its twelve members carry no JSDoc of their own:

member	prose?
parentField	none anywhere — bare parentField?: string;
baselineEndField	covered by baselineStartField's shared docblock
assigneeField	described inside resourceView's docblock
effortField	described inside resourceView's docblock

Three of those four are fine — the prose exists, it just lives on a neighbour. parentField is the real one: it has no prose in that type at all, so the stated sole rationale does not hold for it.

Why it is worth recording

The rationale is load-bearing for anyone deciding whether a restatement may be deleted, and it is incomplete in a way that reads as complete. There is a second reason those members exist, stated a few lines further down in the same docblock: naming the local half gives ObjectGantt.configPin.test.ts two independent operands, so a spec bump that re-types one of the ten breaks the build at the pin. parentField serves that pin purpose and only that one — it is not dead weight, but a reader applying the "ONE reason" test literally would conclude it is deletable, and deleting it would silently remove a pin operand.

The concrete cost is already recorded: objectui#6547 asserted, on the strength of this docblock, that the renderer prose for the spec-sourced keys "is in plugin-gantt's package-private GanttConfigEx (now GanttConfigRestated)". For three of the four keys that card turned out to be about, that was not so — colorField and tooltipFields are not members of GanttConfigRestated at all, and parentField is the bare one above. The prose had to be read off the renderer's actual read sites instead.

What a fix might look like

Deliberately left open, and it may well be "nothing":

• reword the docblock so both reasons are stated as reasons (documentation and the pin operand), so the deletability test is the right one;
• or give parentField its own one-liner there, which makes the stated rationale true as written.

Note that PR objectui#6561 has since written standalone prose for parentField in @object-ui/types, which is a consumer-visible face — so the documentation half of the rationale is now weaker for that key specifically, and the pin half is what actually keeps it.

No behaviour change either way, and no urgency.

Related: objectui#6471, objectui#6547.

Generated by Claude Code

---

Generated by Claude Code

[os-support-ai]

Triage: leveled finding → pm:queue / domain:ui / Task. Rationale: the docblock's "ONE reason" deletability test is load-bearing and false for parentField — that member's real keep-reason is the configPin operand, not JSDoc — and the cost already fired once (#6547's wrong assertion about where the renderer prose lives), so this grades queue over close. The fix is a two-line doc edit: state both reasons (documentation AND pin operand) so the deletability test reads right, and either give parentField its one-liner or note its pin-only status. Dispatch note: PR #6561 is writing standalone parentField prose in @object-ui/types — land this after it, on the merged ref; folding into another small plugin-gantt doc card is the ui seat's call. Size: S, mechanical.

---

Generated by Claude Code

[os-support-ai]

Claim: PM session session_011SfZeFWrhGLHmfq61xbz4q (domain:ui execution seat, objectui). Branch claude/issue-6563-ganttconfigrestated-rationale. Dispatched this round to one os-dev agent, in its own worktree.

Picked as a Task rather than a Bug for a reason worth stating, since this lane's standing order is Bugs first: the Bug tier has 2 cards left and neither is dispatchable — #6457 lands in packages/plugin-grid/src/ObjectGrid.tsx, serialized on #6458's active claim, and #6424 has just been marked pm:retriage because both of its dispositions sit on the human floor. The order says an exhausted tier falls back to Tasks rather than idling a slot, so it does.

Why this card is worth an agent even though it changes no behaviour. The docblock says the restated members are kept for "ONE reason — their JSDoc", and parentField has no JSDoc. Its actual reason for existing is stated further down the same docblock: it is a pin operand for ObjectGantt.configPin.test.ts, giving that pin two independent halves so a spec bump that re-types one breaks the build. So a reader applying the "ONE reason" test literally would conclude parentField is deletable — and deleting it would silently remove a pin operand. That is a comment that makes a gate quietly deletable, which is worth more than its size suggests.

There is already a recorded cost: #6547 asserted, on the strength of this docblock, that the renderer prose for the spec-sourced keys lives in this type. For three of the four keys it turned out to be about, it did not.

⛔ Out of scope, stated to the agent: deleting any GanttConfigRestated member (that is the outcome this card exists to prevent, not to perform), and any change to ObjectGantt.configPin.test.ts's operands. The agent is also told to verify the pin claim against the test rather than trust this card for it — if parentField turns out not to be an operand, the whole framing changes and that is a stop-and-report.

Hot-file note: packages/plugin-gantt/src/ObjectGantt.tsx is serialized on this claim. It is free — #6305 and #6303 both landed on it and are merged; nothing else in flight touches plugin-gantt.

---

Generated by Claude Code

[os-support-ai]

Re-dispatched. The agent claimed above was killed by a container restart at ~15:12Z before it pushed anything.

Diagnosed from the branch rather than from the agent's absence: claude/issue-6563-ganttconfigrestated-rationale existed but its HEAD was 6a7893d57 — a main commit, the base it was cut from — with no commit on top and no PR.

Same claim, same branch, same scope, including the step-1 requirement to verify the pin claim against ObjectGantt.configPin.test.ts rather than take it from the card, and the ⛔ on deleting any GanttConfigRestated member.

---

Generated by Claude Code

[os-support-ai]

os-dev-report

{
"issue": 6563,
"status": "done",
"branch": "claude/issue-6563-ganttconfigrestated-rationale",
"pr": "#6589",
"premise_still_valid": true,
"summary": "The pin claim HOLDS, verified by ablation rather than by reading: deleting parentField from GanttConfigRestated takes tsc -p tsconfig.test.json from exit 0 to exit 2 with three errors — the RESTATED census (StaleCensusEntry, line 125), the pin's own non-vacuity control #4 which names the literal 'parentField' (line 149), and the cfg fixture (line 202); it is additionally a derived operand of Diverged, which maps over keyof GanttConfigRestated. Mutation was confirmed on disk (anchored grep 1 to 0, blob e39b5b07 to 99259398) and the tree restored byte-identical to HEAD. Picked the card's option 1 (reword so both reasons are stated as reasons) because measurement RULES OUT option 2 rather than merely disfavouring it: giving parentField a one-liner would not make 'their JSDoc is the only prose in this repo' true, since ObjectGanttSchema in @object-ui/types documents all twelve members, and baselineEndField/assigneeField/effortField would still be bare. Deliberately did NOT duplicate parentField prose here — the authoritative consumer-visible copy landed on ObjectGanttSchema.parentField in objectui#6561, and a second copy in a package-private type is the fork the objectui#6051 lift existed to prevent. One bounded in-place fix declared in the PR body: the neighbouring 'Two are NARROWINGS and load-bearing ... precision the intersection would otherwise lose' claim, which ObjectGantt.configPin.test.ts already records as measured-false ('on current main they narrow nothing') — same docblock, same defect class, correct form already pinned by existing evidence. Also restated the spec-origin count from measurement (eleven of the twelve arrive from GanttConfigSchema, not 'nine of the ten'), since the taxonomy had to be restated once all twelve are described as restatements. Comment-only: no declaration, type or behaviour changed, and no GanttConfigRestated member was deleted or added.",
"census": "Re-measured on 6a7893d, not the card's 0235ce7. Bare here (4 of 12): parentField (no prose anywhere in that type), baselineEndField (covered by baselineStartField's shared 'start/end' docblock), assigneeField and effortField (both described inside resourceView's docblock). Own JSDoc here (8 of 12): typeField, baselineStartField, groupByField, resourceView, capacity, quickFilters, autoZoomToFilter, timeSegments. Separately measured and NOT in the card: ObjectGanttSchema on the flat face in @object-ui/types carries renderer-behaviour prose for ALL TWELVE (0 of 12 lacking), so the 'only prose in this repo' half of the rationale is false for every member, not just parentField. Commit timeline shows it was false on arrival, not weakened later: 75bd83d (objectui#6472) declared the flat face with per-member JSDoc at 02:55 on 2026-08-26; 64e32e6 (objectui#6546) wrote the 'ONE reason ... only prose' docblock at 10:24, 7.5h later; f20dcf0 (objectui#6561) expanded four of those pointers at 12:17. Positive controls for both zero columns: my first census script was WRONG (it recognised only multi-line JSDoc and so reported false zeros for baselineStartField and capacity) — the table above is from the corrected query. For 'bare here', the same query on the same type returns non-zero for the other 8 members. For '0 of 12 lack flat-face prose', the same query over all 310 optional members of objectql.ts also returns 0, so that file cannot control itself; the query was instead re-run against a scratchpad COPY of the same file with exactly one JSDoc line removed and reported exactly ObjectGanttSchema.typeField. The repo copy was never mutated.",
"deletability_test_check": "Checked mechanically, not asserted. The docblock now states: 'Delete a member here only when its twin on GanttConfig goes with it', with reason 2 (pin operand) given as reaching every member. Applying it to parentField: its twin is GanttConfigSchema.parentField, present in the spec's shipped view.zod-.d.ts as 'parentField: z.ZodOptional(z.ZodString)' among the 19 keys — twin has not gone, therefore KEEP. The old test ('does this member carry its own JSDoc') returns 'deletable' on the same input, which the ablation proves wrong. Both tests are stated adjacently and parentField is named as the worked example, so the wrong one cannot be applied by accident.",
"tests": "Gate union re-run on the FINAL commit 8ceafdf with a clean tree; every exit code captured before any pipe, every verdict quoted from the gate's own output. pnpm --filter @object-ui/plugin-gantt run type-check EXIT=0 (echoed 'tsc --noEmit && tsc -p tsconfig.test.json', so not the zero-match false-green). vitest run packages/plugin-gantt/src/ObjectGantt.configPin.test.ts EXIT=0, 'Test Files 1 passed (1)' / 'Tests 6 passed (6)'. Full affected-package suite vitest run packages/plugin-gantt EXIT=0, 'Test Files 50 passed (50)' / 'Tests 420 passed (420)'. check-changeset-presence.mjs EXIT=1 BEFORE the changeset ('1 source file(s) of 1 released package(s) changed, and this change adds no changeset') and EXIT=0 after, with its own verdict 'Every one of them has an EMPTY frontmatter — declared as releasing nothing, which is the explicit exemption and a complete answer to this gate'. check-changeset-no-major EXIT=0, check-changeset-fixed EXIT=0, check-changeset-overwrite EXIT=0, check-control-bytes EXIT=0 ('scanned 5444 tracked text file(s)'), check-doc-fence-languages EXIT=0. eslint . in packages/plugin-gantt EXIT=0, 0 errors, edited file present in the 80-file population at 0 errors. Tests run from the repo root, never pnpm --filter test (objectui#3378). Dependency closure built first (pnpm --filter '@object-ui/plugin-gantt^...' build, EXIT=0) because tsconfig.test.json sets paths:{} and resolves @object-ui/ through built .d.ts; tsc --listFiles confirms ObjectGantt.configPin.test.ts and ObjectGantt.tsx are both in that program and 41 files resolve from packages/types/dist. ABLATION: both legs are source-relative (the pin test imports GanttConfigRestated from './ObjectGantt'), so no dist rebuild sits between mutation and reading — the mutation leg was proven on disk by anchored grep count 1 to 0 plus a blob-hash change, and the restore leg by 'git diff HEAD' empty AND the hash returning to the HEAD blob e39b5b07, not by the restore command's exit code. The script carried a trap on EXIT/INT/TERM restoring via 'git checkout HEAD -- path' with a repo-root-absolute path. LINT NARROWING, DECLARED: eslint was run for the affected package rather than repo-wide. Population read from eslint's own config (80 files selected), count read from --format json, and invariance holds because eslint.config.js declares no projectService/parserOptions.project, so there is no cross-file type program a comment edit could move. The edited file's 85 warnings are all pre-existing code-shape rules (no-explicit-any x73 plus react-hooks), none line-count-sensitive (no max-len/max-lines) and none inside the edited range 108-158. An earlier run with --no-inline-config showed 2 errors in demo/main.tsx; that flag is objectstack's lint spelling, not objectui's, and the package's real lint script exits 0.",
"files_touched": [
"packages/plugin-gantt/src/ObjectGantt.tsx +36 / -12 (comment lines only)",
".changeset/gantt-restated-keep-rationale.md +13 / -0 (new, empty frontmatter)"
],
"open_questions": [],
"contradicting_the_order": [
"The order said the branch sits at a stale base 6a7893d. origin/main IS 6a7893d — the base was current, not stale. The required check 'git log origin/main..origin/branch' was empty as specified, so nothing was discarded, and the branch was re-cut from origin/main anyway.",
"The card and the dispatch both say deleting parentField 'silently removes a pin operand'. Measured, deletion is NOT silent: it fails three assertions and exits 2, and one error names the key. The defect is still real but its shape differs — all three failures land INSIDE the pin test, which advertises itself as a self-maintaining census and is the file a reader edits to turn a red build green, so the three errors read as 'update the census'. The reworded docblock states this shape rather than the 'silent' one.",
"The dispatch says objectui#6561 weakened the documentation half 'for that key specifically'. Measurement is stronger: objectui#6472 gave all twelve members flat-face prose 7.5 hours BEFORE the 'ONE reason ... only prose' docblock was written, so that half was false for all twelve on arrival. objectui#6561 only made it visible on the one key with no local prose to fall back on."
],
"out_of_scope_findings": []
}

---

Generated by Claude Code