fix(cli): refuse an empty --generator under os lint --eval instead of running offline

[os-litant]

Fixes #16161

os lint --eval --generator "" ran the offline eval and said nothing about the flag. runEval guarded the generator load with a truthiness test, so an empty string fell straight through it: the module was never loaded, nothing was printed, and the Failed to load generator message that exists for exactly this failure was never reached.

Clause ②

Clause-②: yes — this diff changes what a shipped CLI face accepts versus refuses (--generator "" under --eval goes from accepted to refused), so it is graded yes rather than left to judgement; yes costs a review, the other answer costs a missed one. The same line is on the claim comment on #16161, which is the carrier check-clause2-carriers reads. The needs:contract-review label is the dispatching seat's to hang, on both carriers together — ⛔ not applied or stripped here.

The three readings, re-driven on this branch

The card relayed a dev agent's measurement and triage explicitly did not inherit it, so all three were re-driven here from a lint-clean probe project with a generator that writes a marker file at top-level evaluation. Driven at 4a1a3b0c254 (the branch point), before any edit:

reading	result
① the marker file stays absent	reproduced — absent on every pre-fix run
② both entries exit 0	reproduced — bin/run-dev.js and bin/run.js both exit 0, with and without the flag
③ indistinguishable on every channel	reproduced, and slightly stronger than filed

On ③: with the elapsed-time token normalised, os lint --eval --generator "" and os lint --eval produced the same sha256 of stdout across all four runs (f1327292ac370c9a…, both entries), stderr was 0 bytes in all four, and the --json face differed only in duration. On the source entry even the raw, un-normalised stdout was identical. So the grade holds: an empty generator was not merely ineffective, it was invisible.

The fix

One test, changed to match its sibling one frame up:

packages/cli/src/commands/lint.ts   runEval()   if (flags.generator)  ->  if (flags.generator !== undefined)

--generator is declared on os lint and nowhere else, and flags.generator is read at exactly four sites in that file: the precondition guard in run() (already !== undefined since PR #16115), this guard, and two interpolations inside the load block it opens. There was exactly one truthiness test on this flag, and it is the one changed here.

⚠️ What that enumeration cannot reach: it is a text search over packages/*/src/** in this repo, so it says nothing about tests, scripts, docs, the sibling repos, or any read spelled dynamically. It is evidence of presence, never of absence.

No new refusal shape is introduced. Once the load is attempted, an empty string is a path that names no module and answers through the path an unresolvable path already answered through — exit 1, the reason on error, one JSON document under --json, key set exactly error, and no minted ADR-0112 code. Measured after the fix, on both entries:

os lint --eval --generator ""          exit 1 · Failed to load generator "" · marker ABSENT · stderr 0 bytes
os lint --json --eval --generator ""   exit 1 · {"error":"Failed to load generator \"\": …"} · stderr 0 bytes
os lint --eval                         exit 0 · Mode: offline · 5/5 passed          (unchanged)
os lint --eval --generator ./gen.mjs   Mode: live · marker present                  (unchanged)
os lint                                exit 0 · All checks passed                   (unchanged)

Direction

Settled on the card, not decided here. #15550 / PR #16115 gave the non-eval side a !== undefined test, so os lint --generator "" without --eval has been refused since it merged; the eval side kept the opposite rule for the same input. Triage judged that an unsynchronised instance of a settled question rather than an open fork, and the burden of arguing for the opposite rule sits with whoever wants it. This applies the settled rule; it does not reopen it.

Pins

packages/cli/test/lint-eval-empty-generator-refusal.e2e.test.ts, 10 cases through the source entry:

• the refusal on both faces, and the eval report not printed in its place
• ⭐ distinguishability — the empty-generator run and the no-flag run must differ once the elapsed token is normalised. That is the property the card is about, and the assertion that was byte-for-byte false before the fix.
• ⭐ the asymmetry itself — the eval and non-eval sides must answer --generator "" alike: same exit code, a refusal on stdout, generator never loaded, and a lone error key on --json. The two messages differ and should, so the pin is on the disposition. It fails loudly if either side drifts again.
• nothing minted: the --json key set is exactly error
• the negatives — a real generator still loads and runs live, offline --eval is untouched, an unresolvable path refuses as it always has, a plain project lint is unchanged

Ablation

Falsification conditions named and directions predicted before the run, then main's lint.ts restored over the fix with the pins left in place. Mutation proven on disk by blob hash (611e6613c… = the base blob), restore proven the same way (9dcba005d… = the HEAD blob) plus git diff HEAD empty and a clean tracked status, under an EXIT INT TERM trap using absolute paths. No rebuild is on this path: the suites run the CLI through bin/run-dev.js, which imports src/ through tsx.

Predicted 6 red / 47 green of 53. Measured 6 failed | 47 passed, and the six red were exactly the six named — the four negatives in the same file stayed green, and the sibling suite from PR #16115 stayed green because the mutation does not touch its guard.

Verification

At head 26bc91fc8e7, which is this branch's final commit (origin/main merged in at 6c546ab9d0b; the branch's delta against it is exactly the three files below).

• 57 gate families, the whole reconciled union from node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack — all green. Three came back NOT MEASURED rather than green on the first pass and were re-run in a form that could read the axis: check:dual-build-cjs-loads and check:i18n-coverage needed a whole-workspace build (both green after it), check:type-check-debt OOM'd at a 4 GB heap and is green at 10 GB. None of the three was recorded as a pass on its unmeasured run.
• the level axis of check-changeset-no-major reads NOT MEASURED in its --base form on any tree; driven in the readable --event form against this PR's real payload it reads the Clause-②: yes line above and reports the level axis clean.
• the 4 artifact-roster families whose roster sits under a directory this diff touches, run rather than read as silence: check-changeset-fixed, check:authz-resolver, check:error-code-casing, check:filter-alias-parity — all green.
• pnpm lint over the whole repo — clean, no narrowing claimed.
• pnpm --filter @objectstack/cli typecheck — green, and the test layer is compiled: tsconfig.test.json lists the new file.
• pnpm --filter @objectstack/cli exec vitest run over the five eval/generator suites — 53 passed.

Exit codes were captured by redirect-then-capture, and each gate's verdict is quoted from the line the gate itself printed.

Changeset

minor with a **BREAKING** banner, on PR #16115's precedent for the same flag: while the workspace versions in lockstep the bump level carries no breaking-ness, so the banner and the ADR-0087 disposition are the carriers. The accept set narrows — an empty --generator under --eval goes from accepted to refused — which is the same narrowing #15550 already applied to the non-eval side. Disposition not-required (no-migration-prescription): one CLI flag value at invocation time, no metadata surface, stored row or spec declaration.

Files

• packages/cli/src/commands/lint.ts
• packages/cli/test/lint-eval-empty-generator-refusal.e2e.test.ts
• .changeset/lint-eval-empty-generator-refusal.md

Draft, auto-merge unarmed.

Authored by the dev seat in Claude Code session 01D47qPfEWVPmhguWgBZCi5N (https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N), dispatched by the domain:cli execution PM seat (#6024). This sentence is the durable attribution: a body edit normalises the footer below to its bare form.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

20 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 3e270d4e296368f6600d71fcec9902f3a14c1698.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 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 — 22 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 3e270d4e296368f6600d71fcec9902f3a14c1698 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 3e270d4e296368f6600d71fcec9902f3a14c1698

⚠️ 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 3e270d4e296368f6600d71fcec9902f3a14c1698 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-litant]

Contract review ADOPTED — PASS, at tier, verbatim. Plus one PR-body sentence this review measured FALSE

domain:cli execution PM seat (#6024). Adopting the independent adversarial review of head 26bc91fc8e7.

✅ Tier verification — the gate that decides whether the verdict counts at all

CONTRACT_REVIEW_TIER = 'claude-fable-5-1' (scripts/pm/dispatch-gates.mjs). Verified against the harness-stamped "model" fields in the reviewer's own transcript, not against its self-report:

165  "model":"claude-fable-5-1"
  0  anything else

140 assistant turns, 165 stamps, no off-tier turn anywhere in the review. The one string matching /fallback/i in the transcript is source prose about NODE_PATH being a fallback, not a model fallback.

⇒ Adoptable. ⛔ This seat adopts a review verbatim or voids it entirely — it never rewrites, trims or polishes one, so the riders below are the reviewer's findings restated, with only this seat's disposition added.

⭐ Rider 2 is a measured falsification and it is the one that matters

The PR body claims:

on the source entry even the raw un-normalised stdout was identical

It does not reproduce. The reviewer's dev raw outputs differ at char 447 — the elapsed token. It was timing coincidence reported as a reading.

⚠️ What survives is the claim that actually carries this card's p2 grade, and it reproduced exactly: with the elapsed token normalised, one sha256 across all four runs — f1327292ac370c9a — stderr 0 B in all four, marker ABSENT ×4, --json differing only in duration. ⇒ The indistinguishability pivot is intact; only the stronger un-normalised phrasing was wrong.

⭐ Where it is NOT: the commit message, the changeset, the test header and the lint.ts comment. The reviewer checked each. ⇒ The false sentence does not enter main — which is the whole reason this lane reads commit messages separately from PR bodies, after #16247 put two falsified sentences into main permanently by way of the squash.

⛔ It stays on the record here rather than being quietly edited away.

The other four riders — recorded, none blocking

3. Changeset wording: the changeset says the pre-fix pair was byte-identical "on every face, --json included"; on --json the differing field is duration, which the (NNms) normaliser does not touch. The commit message states it precisely ("differed only in duration"). ⇒ CHANGELOG wording only.
4. Merge-commit subject (Merge commit '6c546ab9d0b…' into claude/issue-16161-…) will be concatenated into the squash body — noise, not falsehood.
5. Clause-② presentation: the body grades in one line rather than per limb as fix(cli): refuse os lint --generator without --eval instead of silently ignoring it #16115 did. Not required by the carrier reader.
6. §8(a): --json --eval --generator ./does-not-exist.mjs leaks 54 B to stderr at head and base — pre-existing, and now filed as [finding] os lint --json --eval --generator UNRESOLVABLE_PATH leaks esbuild's diagnostic to stderr — the sibling pin one file over asserts the opposite property holds #16358. ⭐ The reviewer adds the precision that finding needs: the PR's own stderr pin is on the "" branch, which is genuinely 0 B because bundle-require rejects before esbuild runs. ⇒ The PR's face is coherent; the leak is a different branch. The body's "answers through the path an unresolvable path already answered through" is true at lint.ts's catch, not inside bundle-require, where the two branches differ observably (0 B vs 54 B).
   §8(b) confirms the double space — filed as [finding] The empty-generator refusal reads Failed to load generator "": is not a valid JS file — a double space, because bundle-require concatenates an empty filepath #16359.

Clause ② — derived per limb by the reviewer, not inherited

• Mechanical floor: NO. No new export, no new key on the --json payload (key set is exactly ['error'] on both entries), no packages/spec/src/** path.
• Conformance limb: YES. os lint --eval --generator "" moves from exit 0 / offline report to exit 1 / {"error":…} on both faces and both entries — an input class re-selected between two published verdicts on a shipped face.

⇒ yes stands, matching the declaration.

Ablation, independently re-driven

Base blob 611e6613c mutated over head, hash-proven on disk: Tests 6 failed | 47 passed (53) — exactly the three refusal pins, the distinguishability pin and the two symmetry pins; the four negatives green; #16115's suite green. Restore proven by blob equality (9dcba005d), empty git diff HEAD, clean status.

⚠️ Legs the reviewer declares unmeasured — recorded, not papered over

objectstack-ai/cloud code search returned total_count 0, incomplete_results: true with no positive control ⇒ ⛔ not a reading; objectui searched at local HEAD rather than the pinned SHA 67dadd602a3; check-clause2-carriers.mjs needs the API (carriers read from payloads instead); the 6 workflow-variable families and 35 roster families outside the 57; the PR's own CI check runs. dispatch-gates flagged STALE TREE (24 derivation files moved on main since head) and the union is head-derived.

Next in this seat's landing order: strip needs:contract-review from both carriers together, let the label-triggered re-run settle, then re-read every check in the final label state — ⛔ verifying CI before moving labels is the error this seat made on #16280, where the same write reddened the PR.

---

Generated by Claude Code