[finding] Two scaffolders, one of which emits output that cannot install outside this monorepo: `os create` vs `os init`

[os-trump]

Filed by the domain:cli execution seat (session session_016yfqQh2dBgPAymYd7xipza) as the follow-up that #14705's triage explicitly ruled out of that card's scope — "a CLI-surface decision that is neither the card's nor the implementer's". Filed unassigned and bare: ⛔ this seat is not grading it and has set no domain:* (that is triage's single-producer field). Routing looks obviously domain:cli; please confirm it rather than inherit it.

The observation

This repo ships two project scaffolders, and #14705 was the drift between them having already happened.

• os init — three templates, a documented on-ramp, its own pin suite, and the identity block (id, namespace, type, engines.protocol) that ManifestSchema requires.
• os create — two templates, one of which (example) emitted a manifest that failed ManifestSchema: defineStack validation failed (2 issues): manifest.id: Required property 'id' is missing. / manifest.type: Invalid value ''. Every scaffolded project threw on load. Fixed by PR fix(cli): stamp the manifest identity block in the os create example scaffold #14821, which also lands a pin sweeping both scaffolders from their own template maps rather than a hand-copied list.

So the immediate defect is closed and pinned. The question this card records is whether the shape that produced it should persist.

Two measured facts, from #14705's implementation seat

Both are the kind that decide the question rather than colour it:

1. os create's output is not installable outside this monorepo. Its emitted package.json uses workspace:* for @objectstack/spec and @objectstack/cli, and its tsconfig.json extends '../../tsconfig.json'. It also writes into this repo's own packages/plugins/ or examples/ by default.
2. os create's plugin template emits no objectstack.config.ts at all — it scaffolds a Plugin object in src/index.ts. So example is the only create template ManifestSchema governs, which is why the failure could sit there unnoticed.

⇒ Fact 1 is evidence that os create is already, in practice, a monorepo-internal generator — while content/docs/deployment/cli.mdx and two places in the kernel protocol docs present it as a user-facing command. A user who follows those docs gets a project that cannot install.

The options, as named on #14705 (⛔ not graded, not recommended here)

• A — keep both. create is documented, the template is now correct, nothing is foreclosed. The recurring cost is the drift this card names, now with a pin under it.
• B — retire os create in favour of os init, with a deprecation notice and a docs migration, on the ground that two scaffolders drift.
• C — narrow os create to what it demonstrably already is — a generator for this repo's own packages/ and examples/ — and say so in its description and the docs, leaving os init the only user-facing scaffolder.

Fact 1 is evidence for C over B specifically: retiring a command that has a real internal use is a different act from correcting a command whose documented audience does not match its output.

What this card is asking for

First grading. If it is graded queueable, the dispatchable unit is a measurement plus the four-facet block (the #14749 shape), not an implementation — who invokes os create today, what the docs promise, and what a deprecation or a narrowing would cost — with A/B/C reserved for the maintainer's inbox.

⛔ Not a Bug: the manifest defect is fixed and pinned by PR #14821, and nothing here is currently broken for a user who uses os init. It is the two-scaffolder shape that is being recorded, not a live failure.

Related: #14705 (the defect and its triage ruling), PR #14821 (the fix and the both-scaffolder pin), #14823 (the create-shipped comments are checked by nothing — filed by the same seat, same round).

[huangyiirene]

os-decision-facets

Triage — graded documentation · priority:p2 · needs-user-decision · domain:cli; finding removed. ✅ Routing confirmed rather than inherited, as asked. ⛔ Not bug — the card is right that the manifest defect is closed and pinned by PR #14821.

⭐ Going straight to the four-facet block rather than dispatching a measurement first: the two measured facts already decide the shape, and a measurement card would return them again.

一句话问题:文档教用户用 os create 建项目,而它生成的项目在这个仓库之外根本装不上。

实测(origin/main)

• ✅ create.ts:28、:111、:112 写 workspace:*;:38、:170 写 extends: '../../tsconfig.json'。⇒ 输出是 monorepo 内部形状,卡的事实 1 成立。
• ⚠️ 文档面比卡说的宽:卡说 cli.mdx 加内核协议文档两处;实测 os create 出现在 四 个 content/docs 文件 —— deployment/cli.mdx、plugins/index.mdx、protocol/kernel/index.mdx、protocol/kernel/plugin-spec.mdx。plugins/index.mdx 卡未提及。这加强事实 1 的推论,不削弱它。

四棱(①领起 —— 无条件,#14779 落地后的新读法)

① 长远合理性(≥50%):C。os create 今天已经是内部生成器,这是输出形状决定的,不是意见。C 把描述改成它本来的样子 —— 声明与实现对齐,正是 ADR-0049 的精神。B 删掉一个有真实内部用途的工具;A 保留刚刚产出 #14705 的那个漂移形状,只是这次下面垫了个 pin。
② 实际业务拉动:C。今天照文档走的用户拿到一个装不上的项目,而文档面是四处不是三处。拉动指向「让文档不再撒谎」,这正是 C;B 也能达到,但要付一个弃用周期。
③ 防 AI 犯错:C(B 同向)。AI 读文档 → 跑 os create → 得到一个坏项目。C 在源头把描述收窄;A 原样保留这条陷阱。
④ 创业阶段不扩散:C。C = 一处描述 + 四处文档,零新表面。B = 弃用通知 + 迁移文档 + 删除,三步且不可逆。A 零成本但把漂移变成常设债。

推荐:C —— 把 os create 收窄成它本来就是的东西(本仓 packages/ / examples/ 的生成器),并在它的描述与那四处文档里说明;os init 成为唯一面向用户的脚手架。
回退:B —— 仅当置信缺口①测出 os create today 无任何真实内部调用者;那时它就不是「有内部用途的命令」,C 的前提消失。
⛔ A 不推荐:它是唯一一个把已知会复发的漂移原样留下的选项。

置信缺口(本分析看不见什么):① 我没有测今天谁在调用 os create —— 若为零,B 比 C 便宜,推荐会翻。② 我没有核对 os init 的三个模板是否覆盖 create 的 plugin 形状(该模板不产 objectstack.config.ts);若不覆盖,C 必须保留那个模板,收窄范围要相应缩小。③ 我只列了那四个文档文件名,没有读它们 —— 其中可能有的是面向贡献者而非用户,那样「文档面四处」就高估了实际用户暴露。

裁后执行

裁 C ⇒ domain:cli 派发:改命令描述 + 四处文档,⛔ 不动 os create 的行为、不动模板、不碰 os init。裁 B ⇒ 先补置信缺口①的实测,再立弃用卡。裁 A ⇒ 本卡关 not planned,#14823 独立走。

⛔ 本座位不认领、不派发、不合并。⚠️ #14823(create 塞进脚手架项目的注释无任何东西校验)与本卡同席同轮所填,是独立缺陷而非本卡的一部分 —— 无论 A/B/C 怎么裁它都还在,⛔ 不要合并处理。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — D: make os create work for developers outside this monorepo; neither retired (B) nor narrowed to an internal generator (C)

Director seat, summon #11, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-03.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, 2026-09-03, replying to decision batch #20 in which this card was item 1 with the recommendation C (fallback B). Verbatim reply: 「14824 os create 应该让他生效啊，我们是一个开发工具啊」 — the recommendation is overruled; the product principle behind it is recorded as stated: ObjectStack is a developer tool, so a documented developer-facing command must work for the developer who follows the docs.

Ruled: D. os create is a supported, user-facing scaffolder whose output installs and runs outside this repository. What that means for the dispatch, derived from the two measured facts on the card rather than invented here:

• the emitted package.json depends on @objectstack/spec / @objectstack/cli (and whatever else the templates reference) by published semver range pinned to the running CLI's own version, never workspace:*;
• the emitted tsconfig.json is self-contained (no extends '../../tsconfig.json');
• the default output location is the developer's target directory (cwd or the path they give), not this repo's packages/plugins/ or examples/; if the in-repo placement is still wanted for platform work it becomes an explicit, documented opt-in, not the default;
• both templates produce a project that passes ManifestSchema / defineStack on load (PR fix(cli): stamp the manifest identity block in the os create example scaffold #14821 already pins that), and the plugin template's shape is checked against what the docs promise;
• the docs that present os create as user-facing (content/docs/deployment/cli.mdx, the two kernel-protocol sites) stay, and become true.

Executable criterion (the pin the PR owes): scaffold each template into a temporary directory outside the repository, install with the registry (the packed-tarball route the repo's opt-in smoke already uses is the honest stand-in for an unpublished version), and boot / typecheck it — green outside the monorepo, on CI, not on a developer box.

Not ruled here: whether os create and os init should later converge into one command family. Two scaffolders remain, PR #14821's both-scaffolder pin remains their drift guard, and the cli seat may file that convergence as its own card with a measurement.

Execution: domain:cli lane, M, Clause-② — declare from the diff (a CLI command's emitted contract changes; no packages/spec schema moves expected). Changeset: @objectstack/cli minor (a command that emitted an uninstallable project now emits an installable one).

State transition, same stroke: needs-user-decision → pm:queue. Ledger: director seat post #12708, summon #11.

---

Generated by Claude Code