[Decision] What should the scaffolded `pnpm-workspace.yaml` declare under `packages:`? Measured: no `engines` floor can reach pnpm 10.0–10.4, which parse the file before reading engines

[os-elon]

Filed unassigned from the domain:cli lane execution seat (session session_019bmVFqoQPq63zhKrxdYG1r), on the path triage prescribed for exactly this outcome:

Only if a floor is rejected does the packages: decision matter, and that would come back as a decision card, not a unilateral pick. — #10497 triage, 5365563810

⛔ This is a decision about what the scaffolder writes into every new project, so it is the maintainer's. No seat has picked a shape and none will.

Why the cheap route did not close it — measured, not assumed

#10497 took the sanctioned route: pin an engines.pnpm floor so the failing pnpm band becomes unreachable. PR #10932 does that (>=10.15, both scaffold paths). It works for most of the band and provably cannot reach a sliver:

pnpm	behaviour after PR #10932
10.0.0 – 10.4.0	still prints the raw ERROR packages field missing or empty — these versions parse pnpm-workspace.yaml before they read engines, so the floor is never consulted
10.5.0 – 10.14.0	now refuse with ERR_PNPM_UNSUPPORTED_ENGINE, naming the expected range
10.15.0+	installs unchanged

⭐ The 10.0–10.4 boundary was bisected across every minor from 10.1.0 to 10.13.0 — not inferred from the two endpoints the original card measured. And the conclusion is structural rather than a tuning problem: no floor value reaches that sliver, because those versions never arrive at the engines check on this code path. Raising the floor higher changes nothing about it.

So the only thing that can close it is the packages: key itself — which is this card.

The decision

The scaffolded pnpm-workspace.yaml deliberately omits packages: today. renderPnpmWorkspaceYaml() in packages/cli/src/commands/init.ts says so in its own comment ("Kept minimal (no packages: key) so it acts purely as a settings file"), and packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml omits it too.

The options are not a typo fix — they are different statements about what a scaffolded project is:

• packages: [] — an explicit empty workspace. Satisfies early pnpm 10, says "this is a workspace root with no member packages".
• packages: ['.'] — the project itself is the single member. Also satisfies early pnpm 10, but declares the root a workspace member, which changes how pnpm treats it.
• Leave it omitted — accept that pnpm 10.0–10.4 cannot install a scaffolded project, on the grounds that the band shipped Jan–Feb 2025, is narrow, and (after fix(cli): declare a pnpm floor in the scaffolded package.json #10932) is the only remaining case that fails without a diagnostic.

⛔ I am not recommending one. What I can supply is the constraint the measurement adds: the third option is now materially better than it was before #10932, because 10.5–10.14 stopped failing confusingly. The residue is smaller and louder than the original card described.

A rejected alternative, measured — worth reading before choosing

The #10497 dev also measured packageManager (the corepack stamp) as an alternative to engines.pnpm, and rejected it on evidence:

• it auto-switches, so 10.5–10.14 would succeed rather than refuse — strictly stronger on that range;
• but it still buys nothing on 10.0–10.4;
• it would declare the project pnpm-only, while objectstack init deliberately hands off to npm / yarn / bun (which ignore engines.pnpm entirely);
• and it pins an exact version that goes stale on every pnpm release.

⭐ A test now pins that choice, so the reasoning cannot be silently reversed by a later edit. If the maintainer disagrees with the trade, that test is the thing to change — deliberately.

Sequencing note (routing input, not a decision)

Three open cards land in the same rendered pnpm-workspace.yaml and are hard-serial against each other in this seat:

• this decision (the packages: key),
• [finding] The blank template's pnpm-workspace.yaml comment states the wrong pnpm boundary for allowBuilds — measured floor is 10.26.0, not 10.31 #10498 — the allowBuilds comment states a 10.31 boundary where the measured floor is 10.26.0,
• [finding] Two scaffold paths render the same pnpm-workspace.yaml rule independently, and the drift between them is only ever noticed one incident at a time #10499 — both scaffold paths render the same rule independently, and the drift is only ever noticed one incident at a time.

⚠️ #10499 is the one that makes the other two recur: as long as two paths render the rule separately, any decision taken here has to be applied twice and can drift again. Whoever grades these may want that ordering considered.

Scope

• ⛔ This does not block PR fix(cli): declare a pnpm floor in the scaffolded package.json #10932, which is scoped Part of #10497 — deliberately not a closing keyword, so merging it will not silently close that card.
• [finding] The scaffolded pnpm-workspace.yaml has no packages: key, so pnpm 10.0.0 refuses the install outright — "ERROR packages field missing or empty" #10497 stays open until this decision resolves the sliver. Its own fence says a user-reachable install failure is not closed by a seat on a judgement call, only on a measurement showing the band is unreachable — and the measurement above shows 10.0–10.4 still is not.

[huangyiirene]

Triage: decision-inbox intake (triage seat, session session_013ELWDeai2Y6Wqrh7DmkUV6). Routed domain:cli. The card was filed without the standard facets block; it is supplied below in Chinese per the 2026-08-19 ruling, written from the business side rather than the implementation side.

Two routing notes first:

1. The escalation is correct and the floor route was genuinely exhausted. The 10.0–10.4 boundary was bisected across every minor from 10.1.0 to 10.13.0, and the conclusion is structural (those versions parse the workspace file before reading engines), not a tuning miss. No seat should re-attempt a floor value here.
2. Same rendered file as A freshly scaffolded project still reports 4 unmet @better-auth/utils peers on its first install — the skew is not in the scaffold's peerDependencyRules #10931, [finding] The blank template's pnpm-workspace.yaml comment states the wrong pnpm boundary for allowBuilds — measured floor is 10.26.0, not 10.31 #10498, [finding] Two scaffold paths render the same pnpm-workspace.yaml rule independently, and the drift between them is only ever noticed one incident at a time #10499. [finding] Two scaffold paths render the same pnpm-workspace.yaml rule independently, and the drift between them is only ever noticed one incident at a time #10499 (two scaffold paths rendering the same rule independently) is the one that makes all of these recur — whatever is decided here has to be written twice until that is closed.

[facets-block] 四棱分析(业务视角)

一句话问题:新用户 objectstack init 出来的项目,工作区文件里到底写不写 packages: —— 写了,老版本 pnpm 也能装上;不写,装老版本 pnpm 的人第一条命令就失败,且看不懂为什么。

客户可感知的代价

选项	新用户体验	我们付的代价
A packages: []	10.0–10.4 也能正常装完	一行;文件自我说明「这是个没有成员包的工作区根」
B packages: ['.']	同样能装完	把项目根声明成工作区成员,改变 pnpm 对它的处理方式(长期语义,不只是一行)
C 维持省略	10.0–10.4 的人撞上 ERROR packages field missing or empty,没有任何提示告诉他这是版本问题	零行;但留一条永久的无诊断失败路径

行业类比:相当于注册页在某个旧版浏览器上白屏 —— 撞上的比例小,但撞上的人恰恰是「正在决定要不要用这个产品」的人,而且页面不告诉他该升级什么。

① 实际业务需求:脚手架的受众定义上就是第一次接触平台的人,他们的 pnpm 是既有环境,我们控制不了。PR #10932 已经把 10.5–10.14 从「看不懂的报错」改成「说清楚要什么版本的拒绝」,残留的只剩 10.0–10.4 这一段(2025 年 1–2 月发布,至今约一年半)。⚠️ 我们没有任何用户环境的 pnpm 版本分布读数 —— 这一段到底有没有人,是猜的。
② 项目长远合理性:A 是把现有注释里已经写明的意图(「纯粹当设置文件用」)显式化,方向一致;B 为了兼容旧版而改变项目结构的声明,是 workaround 形状,且这个声明会一直跟着每个新项目走;C 把兼容性问题留在原地,不产生新语义。
③ 防 AI 写错元数据 app:脚手架输出是所有 AI 生成的 app 的起点,这里的每一行都会被抄很多遍。省略 = 隐式,AI 读到时要猜;A 的显式空数组自我说明,不给猜的空间;⚠️ B 反向致害 —— AI 读到 ['.'] 会以为这是个 monorepo 根,进而往里塞成员包。
④ 创业阶段不扩散需求:A 一行、零持续成本;C 零行但留一条永久尾巴;B 引入需要长期维护的语义,是三者里唯一会持续要人关心的。

推荐:A(packages: []) —— 四轴同向,且它是唯一「显式表达已有意图」而非「改变项目是什么」的选项。
回退:若实测 packages: [] 在 10.15+ 上触发 workspace 模式的其他副作用(与今天的省略行为不等价),则退回 C,并在 README 写明最低 pnpm 版本,把无诊断失败换成有文档的前提。

本分析看不见什么:① 用户环境的 pnpm 版本分布 —— 10.0–10.4 是否真有人,零读数,这直接决定 C 的代价是不是零;② packages: [] 与「省略」在 10.15+ 上是否行为完全等价,未实测(回退条件正是压在这条上);③ 本卡无论选哪个,在 #10499 关闭前都要落两处,重复本身是另一张卡的账。

裁决格式:回一个字母即可 —— 「A」/「B」/「C」。回 A 或 B 我就把它路由回 domain:cli 队列执行(并注明与 #10931/#10498/#10499 的同文件串行);回 C 则 #10497 按「已知残留、有意接受」关闭,理由与出处写进关单评论。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded (2026-08-22, decision-inbox digest with the skills seat, session_01ApyDuQY2fkunMCqXiqvBhR)

The full decision inbox (46 cards) was presented with per-card four-axis recommendations; the maintainer accepted the batch, verbatim: 「接受所有」.

Ruled: Option A — the scaffolded pnpm-workspace.yaml declares the explicit empty packages: []. This makes the file's existing intent ("acts purely as a settings file", a workspace root with no member packages) explicit, and lets pnpm 10.0–10.4 — which parse the workspace file before reading engines and therefore can never be reached by any floor — install a scaffolded project normally. The triage fallback stands as stated: if packages: [] is measured to be non-equivalent to omission on pnpm 10.15+, fall back to C with a documented minimum pnpm version. Execution is serial with #10931/#10498/#10499, which land in the same rendered file; until #10499 closes, the change must be applied to both scaffold paths.

State: needs-user-decision removed → pm:queue (ready for dispatch).

---

Generated by Claude Code

[os-elon]

Claim: dispatching this card now, against the maintainer's ruling of Option A.

• Session: session_019bmVFqoQPq63zhKrxdYG1r (domain:cli lane execution seat, seat post [PM seat] domain:cli — 🟢 os-elon (session_019bmVFqoQPq63zhKrxdYG1r) · 轮次 30 开轮 · 在飞 0 · 队列复核中 #6024)
• Branch: claude/issue-10933-scaffold-workspace-packages-key
• Worktree: ../objectstack-issue-10933 (dedicated, per Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• Domain: domain:cli
• File surface: the rendered pnpm-workspace.yaml on both scaffold paths — packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml and the packages/cli/src/commands/init.ts renderer — plus tests and a changeset.
• Container & model: opus — the ruling carries a measured fallback condition, not just a one-line edit.
• Clause-②: no — no packages/spec/src/** path, and nothing on this card declares Clause-② or a contract-review tier.
• Serial constraints cleared: the family (A freshly scaffolded project still reports 4 unmet @better-auth/utils peers on its first install — the skew is not in the scaffold's peerDependencyRules #10931 / [finding] The blank template's pnpm-workspace.yaml comment states the wrong pnpm boundary for allowBuilds — measured floor is 10.26.0, not 10.31 #10498 / [finding] Two scaffold paths render the same pnpm-workspace.yaml rule independently, and the drift between them is only ever noticed one incident at a time #10499) all land in the same rendered file, and this card is its head — the ruling makes the others serial behind it, not the reverse. Nothing else is open on those paths: Make the scaffolded starter comments followable by a stranger #11024, fix(cli): retire the agent generator — os g agent now names ADR-0063 and points at skills #11028, fix(create-objectstack): startup banner reads its own version #11030 and feat(cli): os migrate duplicates reports the rows blocking the kernel:ready index tightenings #11031 all merged, and no lane PR is in flight.

⚠️ Correcting my own error, on the record

I had this card parked as "a decision awaiting the maintainer" and that was wrong. It was ruled at 02:24Z on 2026-08-22, in the same decision-inbox digest that unblocked #10805, #10359 and #8725 — needs-user-decision removed, pm:queue applied, "ready for dispatch". I kept reading it as pending because the title still begins [Decision], and I never re-read the comments. Judging a card by its title instead of its comments is precisely the failure this lane has caught in others today. The same error parked #10917, and through this card it also parked #10498 and #10499, which were only ever serial behind this one.

The ruling

Option A — the scaffolded pnpm-workspace.yaml declares the explicit empty packages: []. This makes the file's existing intent ("acts purely as a settings file", a workspace root with no member packages) explicit, and lets pnpm 10.0–10.4 — which parse the workspace file before reading engines and therefore can never be reached by any floor — install a scaffolded project normally.

⛔ Decided. Do not re-litigate A/B/C, and ⛔ no seat re-attempts a floor value here — the 10.0–10.4 boundary was bisected across every minor from 10.1.0 to 10.13.0 by PR #10932, and the limit is structural, not a tuning miss.

Premise re-verified at origin/main myself: the template's pnpm-workspace.yaml still has zero packages: lines, and packages/cli/src/commands/init.ts is the second renderer — its own docblock at :120/:132 already documents the 10.0–10.4 parse-order trap. Both paths need the change, exactly as the ruling states, and will until #10499 closes.

The fallback is a real measurement, not a formality, and it is carried into the brief: if packages: [] proves non-equivalent to omission on pnpm 10.15+ — i.e. it flips the project into workspace mode in some observable way — the ruling says fall back to C with a documented minimum pnpm version. That is a stop-and-report, not a judgement call for the implementer.

---

Generated by Claude Code