finding(cli): `validate` / `check` print only TOP-LEVEL zod issues, so every union-shaped schema reports a bare "Invalid input" and the per-arm guidance is never seen

[os-sam]

Filed unassigned by the dev seat working #6931 (branch claude/issue-6931-tombstone-guidance), from a measurement taken there. Out of that card's scope — recorded rather than fixed on its PR.

What was measured

packages/cli/src/commands/validate.ts renders parse failures with:

result.error.issues.forEach((issue, index) => {
 console.error(chalk.red(`\n${index + 1}. ${issue.message}`));
 if (issue.path && issue.path.length > 0) { /* Path: … */ }
 if (issue.code) { /* Code: … */ }
});

check.ts prints the same three fields the same way. That reads only the top level of error.issues.

For a z.union(...) schema zod 4 reports ONE top-level issue: code: "invalid_union", path: [], message: "Invalid input". Everything that says which arm failed and why hangs off that issue's errors array, which nothing here walks. Measured against MenuItemSchema (packages/types/src/zod/overlay.zod.ts), authoring { label: 'New Tab', type: 'separator' }:

channel	what it carries
top-level issue (the ONLY thing printed)	invalid_union · path [] · Invalid input
arm 0 issue (not printed)	invalid_type · path ['type'] · the full #6523 remediation text
arm 1 issue (not printed)	invalid_type · path ['type'] · RETIRED (objectui#6523) — see the command-item arm above.

So the author gets 1. Invalid input with no path and no remedy, for a document whose defect the schema diagnosed precisely.

Why it is worth a card

The path/code suppression is the sharper half: with path: [] the printer's if (issue.path.length > 0) guard also drops the Path: line, so the author is not even told which node failed. On a large page schema that is a bare "Invalid input" against the whole document.

It also silently caps work done elsewhere. #6931 converted eleven ADR-0049 tombstones to retirementTombstone() so each refusal carries its remediation text; for the two that live on a union (MenuItemSchema's arms) the improved text lands in the arm issues and therefore never reaches this printer. Any future guidance written into a union member has the same fate, and nothing currently signals that.

Scope is wider than menus: the same suppression applies to every union in the mirror (for example TableSchema.footer, and any discriminated union added later).

Suggested direction, not a decision

Walk the union's errors when a top-level issue is invalid_union and print the arm issues (or, for a discriminated union, the arm that matched the discriminator) instead of the placeholder. Worth deciding deliberately: printing every arm for a wide union can be noisier than one line, and picking a single arm is a heuristic. A maintainer call on which shape to print belongs on this card, not in a drive-by patch — hence unassigned and unlabelled for triage.

Evidence and probe live on claude/issue-6931-tombstone-guidance; related: #6931, #6523, #6105.

[os-sam]

Triage: p2, queued — and it splits into a mechanical half and a ruling

Filed out of #6931 / PR #7005, where it was found the honest way: two of that PR's eleven tombstone conversions land on MenuItemSchema, which is a union, so the improved guidance rides the per-arm issues while the top-level issue stays invalid_union / Invalid input at path []. The CLI prints only top-level issues, so for those two members the improvement never reaches the author's screen. The implementer stated that in the PR, pinned it in the tests, and filed it here rather than letting the conversion look like a win it is not.

⚠️ The filing note says "unassigned and unlabelled, since which arm to print is a maintainer call". That is true of one half of this card, and it should not stop the other half being dispatched.

Mechanically decidable, no ruling needed: the printer drops the Path line whenever path is [], because of a length guard. A path-less issue is exactly the case a reader most needs oriented, and printing Path: (root) — or simply not suppressing the line — decides nothing about union semantics. Whoever takes this can close that on measurement alone.

Genuinely a ruling, and not the seat's to make: which arm's diagnosis to surface when a union fails. Printing every arm's issues is noisy by construction (a 2-arm union doubles, an n-arm union multiplies); printing one arm means picking a heuristic for which arm the author "meant". That is an author-facing diagnostic contract, so it goes to the maintainer.

⇒ Dispatchable today for the root-path half; the arm-selection half waits. Anyone picking this up should say which half they are doing, and ⛔ must not invent an arm-selection heuristic under cover of fixing the path line.

Scope note carried from the finding: this is not MenuItemSchema-specific — it is every union-shaped schema in the repo. MenuItemSchema is just where it was measured.

---

Seat session: https://claude.ai/code/session_013hfmP9hoMd3dJwTh85J4yB

---

Generated by Claude Code

[os-sam]

Claim — the MECHANICAL half only (root-path line)

Session: https://claude.ai/code/session_013hfmP9hoMd3dJwTh85J4yB
Branch: claude/issue-7004-cli-root-path-line

Per the triage split in the comment above, I am doing only the mechanically decidable half: the issue.path.length > 0 guard in packages/cli/src/commands/validate.ts and packages/cli/src/commands/check.ts suppresses the Path line for a root-level issue (path: []), so an author sees 1. Invalid input with no indication of which node failed — not even that it is the document root.

⛔ I am NOT touching the arm-selection half. No walk of issue.errors, no arm issues printed, no discriminator heuristic. invalid_union will print exactly what any other issue prints. Which arm's diagnosis to surface remains open for a maintainer ruling and this card should stay open after my PR merges — my PR will say Part of #7004, not Fixes.

---

Generated by Claude Code

[os-sam]

os-dev-report

{
 "issue": 7004,
 "half_done": "root-path",
 "branch": "claude/issue-7004-cli-root-path-line",
 "pr_url": "https://github.com/objectstack-ai/objectui/pull/7038",
 "status": "done",
 "premise_still_valid": "partly — the defect is real and fixed; two stated premises were falsified, see premise_corrections",
 "files_changed": [
 "packages/cli/src/commands/validate.ts",
 "packages/cli/src/__tests__/validate-root-path-line.test.ts",
 ".changeset/7004-cli-root-path-line.md"
 ],
 "both_printers_updated": false,
 "both_printers_updated_note": "Reported false against the template on purpose. There is only ONE printer. check.ts has no zod-issue printer at all: it calls safeValidateSchema(content).success purely as a boolean recogniser (the marker gate from #5127 / #6075) and never reads .issues. git log -S confirms a Path: printer has never existed in that file. Nothing in check.ts needed changing, and nothing was changed there — so the two files cannot drift.",
 "premise_corrections": [
 "check.ts does NOT print the three fields. It is a boolean recogniser, not a printer. Making it print issues was considered and rejected: its safeValidateSchema call answers 'is this file ours?', so printing issues behind a negative recognition would flood the report with diagnoses of non-ObjectUI files — the exact failure #5127 and #6075 exist to prevent.",
 "The card's repro recipe does not reach the CLI as written. { label: 'New Tab', type: 'separator' } at the DOCUMENT ROOT validates and exits 0, because the CLI validates the root against AnyComponentSchema, not MenuItemSchema. The card's measurement was taken against MenuItemSchema directly, where its description is exactly right. The CLI-level fixture has to nest the item in a menu."
 ],
 "shared_renderer_decision": "No shared renderer created, and the reason is the premise correction: only one printer exists, so there is no duplication to converge and nothing matching the 'one contract, several hand-written copies' pattern of #5040 / #5596 / #6247 / #6887 / #7014. Extracting a renderer for a single call site would be speculative generality, and the only plausible second consumer (check.ts) must not print issues at all. If the arm-selection ruling adds a second issue-rendering surface, that is when a shared renderer earns its keep — with a real second caller to shape it.",
 "arm_walk_added": false,
 "arm_walk_note": "issue.errors is not read anywhere. invalid_union prints exactly what any other issue prints. A dedicated case pins that boundary (one numbered entry, no per-arm #6523 remediation text, no 'Path: items') so the maintainer's ruling lands as a deliberate edit rather than a silent widening. That case is EXPECTED to change when the ruling lands.",
 "defect_reproduced_before_fix": {
 "how": "Probe run against unmodified base 350509b53 before any edit, driving the real validate() command over tmpdir fixtures; then re-run as a proper ablation after committing — validate.ts reverted to the base blob, mutation confirmed on disk by blob-hash equality to the base blob and by '(root)' occurrences dropping 2 to 0, restore afterwards proven by on-disk blob == HEAD blob and an empty git diff HEAD.",
 "observed": "Root case { type: 'dropdown-menu', items: [{ label: 'New Tab', type: 'separator' }] } printed '1. Invalid input' then 'Code: invalid_union' with NO Path line between them. Same for a foreign document { type: 'module' }. Against the shipped test file the base implementation fails 3 of 6 cases: two 'expected ... to contain Path: (root)' and one 'issue \"1. Invalid input\" printed no Path line'; the 3 control cases pass on base, which is what makes them controls.",
 "after_fix": "1. Invalid input / Path: (root) / Code: invalid_union"
 },
 "non_root_path_still_correct": true,
 "non_root_evidence": "{ type: 'form', fields: [{ name: 'pw', widget: 'ui:password' }] } still prints 'Path: fields -> 0 -> widget', and the whole output is asserted to contain no '(root)' anywhere — the guard against a fix that prints (root) for everything. A valid document still prints no Path line and exits 0. The pre-existing validate-widget-namespace.test.ts (which pins 'Path: fields -> 1 -> widget') also still passes.",
 "checks_run": [
 { "name": "cli package tests", "command": "pnpm exec vitest run packages/cli/", "result": "Test Files 15 passed (15) · Tests 236 passed (236)" },
 { "name": "reverse verification (ablation)", "command": "same suite with validate.ts reverted to base blob", "result": "Tests 3 failed / 3 passed of 6 — the 3 root cases red, the 3 controls green; direction as predicted" },
 { "name": "typecheck", "command": "pnpm --filter @object-ui/cli run type-check", "result": "exit 0, script name echoed; tsc --listFiles confirms both changed files are in the program (1 hit each), so this is measured coverage not an exclude-silenced pass" },
 { "name": "eslint", "command": "pnpm --filter @object-ui/cli run lint", "result": "exit 0 — 11 problems (0 errors, 11 warnings), all pre-existing in untouched files, none in the changed files" },
 { "name": "changeset presence", "command": "node scripts/check-changeset-presence.mjs", "result": "OK — 1 source file of 1 released package changed, 1 changeset declared; independently confirms merge-base 350509b53" },
 { "name": "changeset no-major", "command": "node scripts/check-changeset-no-major.mjs", "result": "OK — No changeset declares a major bump" },
 { "name": "check:control-bytes", "command": "pnpm check:control-bytes", "result": "OK (scanned 5844 tracked text files); plus a manual grep -naP over the three changed files, no matches" },
 { "name": "check:shell-escape-residue", "command": "pnpm check:shell-escape-residue", "result": "OK (4/4 roots resolved)" },
 { "name": "check:vi-mock-specifiers", "command": "pnpm check:vi-mock-specifiers", "result": "OK" },
 { "name": "check:vi-mock-inherit", "command": "pnpm check:vi-mock-inherit", "result": "OK" },
 { "name": "lint:coverage", "command": "pnpm lint:coverage", "result": "OK — 46/46 packages linted, 0 with outstanding errors" },
 { "name": "check:doc-fences", "command": "pnpm check:doc-fences", "result": "OK" },
 { "name": "check:phantom-deps", "command": "pnpm check:phantom-deps", "result": "OK" },
 { "name": "check:self-import", "command": "pnpm check:self-import", "result": "OK" }
 ],
 "checks_scope_note": "Union run at final commit 8641b8cd, tree clean. eslint narrowed to the affected package, declared as a measurement: this repo's root lint is turbo run lint (each package running eslint src), so the package run IS the job CI runs for these files; and eslint.config.js configures no type-aware linting (no projectService, no project:), so this diff cannot move the verdict on any untouched file. Gate family derived by hand from root package.json plus the workflows — scripts/pm/dispatch-gates.mjs is objectstack-only and would have answered about the wrong tree. CI convergence not awaited, per dispatch contract.",
 "mcp_calls": 8,
 "claim_comment_url": "https://github.com/objectstack-ai/objectui/issues/7004#issuecomment-5479766041",
 "blockers": [],
 "open_questions": [],
 "out_of_scope_findings": [],
 "notes": [
 "This card must STAY OPEN. The PR says 'Part of #7004', never a closing keyword, so the arm-selection ruling survives the merge.",
 "PR body sanitizer: the trailing attribution footer is stripped on every PATCH edit (measured 3x on PR #7038 — present on create, gone after each edit). Not re-pasted in a loop; the durable session URL sits in the body's opening prose and the footer is carried in a PR comment. Also caught and fixed a self-inflicted markdown defect: an unescaped pipe inside a table cell broke a row.",
 "PR is behind main (base moved to a7807b41 during the run). Left for the PM to land."
 ]
}

---

Generated by Claude Code

[os-sam]

⚠️ Two premises in this card's body are FALSE — measured during the root-path implementation (PR #7038). Correcting them here so the arm-selection half is not planned against them.

PM seat, domain:ui. The root-path half is delivered; this card stays open for the arm-selection ruling, and the PR is deliberately worded "Part of #7004" with no closing keyword so it survives the merge.

Both corrections came from the implementing dev, verified rather than argued. I had passed both claims into the dispatch order as if measured — they were not, and that is my error to record, not the dev's.

❌ Premise 1: "check.ts prints the same three fields the same way"

False. check.ts has no zod-issue printer at all. It calls safeValidateSchema(content).success purely as a boolean recogniser — the marker gate from #5127 / #6075 — and never reads .issues. git log -S confirms a Path: printer has never existed in that file.

⭐ And making it print issues was considered and rejected with a reason, which is the part worth keeping: that call answers "is this file ours?", so printing issues behind a negative recognition would flood the report with diagnoses of non-ObjectUI files — precisely the failure #5127 and #6075 exist to prevent.

⇒ There is exactly one printer. Nothing in check.ts needed changing and nothing was changed there, so the two files cannot drift. ⛔ A future round must not "fix check.ts for parity".

⇒ Consequently no shared renderer was extracted: with a single call site there is no duplication to converge, so this is not an instance of the #5040 / #5596 / #6247 / #6887 / #7014 "one contract, several hand-written copies" family. If the arm-selection ruling adds a second issue-rendering surface, that is when a shared renderer earns its keep — shaped by a real second caller.

❌ Premise 2: the reproduction recipe does not reproduce at the CLI

The body's recipe — { label: 'New Tab', type: 'separator' } — validates and exits 0 when fed to the CLI as a document. The CLI validates the root against AnyComponentSchema, not MenuItemSchema.

The card's measurement was taken against MenuItemSchema directly, where its description is exactly right. But a CLI-level fixture must nest the item in a menu, e.g. { type: 'dropdown-menu', items: [{ label: 'New Tab', type: 'separator' }] }.

⇒ Anyone reproducing this from the body alone will see a clean exit and conclude the defect is gone. It is not.

⭐ What the root-path half deliberately pinned for the ruling

invalid_union now prints exactly what any other issue prints — one numbered entry, a Path: (root) line, and its code. issue.errors is not read anywhere, and a dedicated test case pins that boundary (no per-arm remediation text, no Path: items).

⇒ That pin is expected to change when the ruling lands — it exists so the arm-selection decision arrives as a deliberate edit against a red test, not as a silent widening. Whoever implements the ruling should expect to update it and say so.

Still open — the ruling

Which arm's diagnosis to surface when a union fails. Printing every arm is noisy by construction (an n-arm union multiplies); printing one means picking a heuristic for the arm the author "meant". That is an author-facing diagnostic contract and remains the maintainer's call.

⛔ Also unchanged: this is every union-shaped schema in the repo, not MenuItemSchema — that is merely where it was measured. And the CLI validates against AnyComponentSchema, a union over every component arm, so any document matching no arm takes this path. It is the common case, not an edge.

---

Generated by Claude Code