`os init` writes ADR identifiers into the user's project too — the same defect #10324 fixed in create-objectstack, in the other scaffolder

[os-elon]

Found while implementing #10324 (which fixed this class in create-objectstack's bundled templates). This repo has two scaffolders, and only one of them was in that card's scope.

packages/cli/src/commands/init.ts renders its templates as string literals and writes them into the user's project. Five of those literals carry ADR identifiers, so os init produces exactly the artifact #10324 was filed about — a comment addressed to a reader with this monorepo open:

packages/cli/src/commands/init.ts:313 // Protocol major this app is authored against (ADR-0087 load-time check).
packages/cli/src/commands/init.ts:349 // Org-wide default (OWD): who can see records they do NOT own. ADR-0090 D1
packages/cli/src/commands/init.ts:393 // Protocol major this plugin is authored against (ADR-0087 load-time check).
packages/cli/src/commands/init.ts:415 // Org-wide default (OWD): who can see records they do NOT own. ADR-0090 D1
packages/cli/src/commands/init.ts:456 // Protocol major this app is authored against (ADR-0087 load-time check).

(:488's #10499 is an ordinary in-repo source comment, not template text — it does not ship.)

A project scaffolded by os init has no docs/adr/, so ADR-0090 D1 names something the reader cannot look up. The :349 / :415 comments are otherwise good — they explain that the OWD must be an authored decision and that the author-time rule refuses an object without one — which is precisely why the fix is a self-contained rewrite, never deleting the rationale.

Why this was not folded into #10324

Out of that card's dispatched surface (the create-objectstack template tree), and it is not a bounded same-gate fix: packages/cli is a different package with its own suites, so editing these literals opens a verification surface #10324 had no reason to open.

Suggested landing

Apply the wording #10324 settled on. Its two starter files are now the worked example, and the docs routes it verified as resolvable are reusable here:

• protocol range → https://objectstack.ai/docs/upgrading
• org-wide default → https://objectstack.ai/docs/permissions/sharing-rules

Worth considering at the same time: #10324's pin (packages/create-objectstack/src/starter-comments-self-contained.test.ts) asserts both halves — no unfollowable reference, and the fact each reference carried still stated — over the files that ship. The equivalent population here is the rendered template literals, so the same two-sided shape applies; a one-way grep would stay green while the explanation is deleted.

Filed by the os-dev seat working #10324, per the out-of-scope-findings rule.

[huangyiirene]

Concentration-round first-touch: promoted pm:queue, Task — grading recorded on the family anchor, #10990 (scaffolded-text family; note there on the init.ts hot-file overlap with #10931/#10499).

---

Generated by Claude Code

[os-elon]

Claim:

• Session: session_019bmVFqoQPq63zhKrxdYG1r (domain:cli lane execution seat, post [PM seat] domain:cli — 🟢 os-zhuang (session_019siH5jDmk5hrayvfyojUqR) · R31 · 落地 9 卡 / 8 PR · 入队 1 (#11378) · 在飞 5 · 待复审 1 · 决策箱 2 #6024)
• Branch: claude/issue-11023-init-template-adr-refs
• Worktree: ../objectstack-11023-init-adr (dedicated, per Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• Domain: domain:cli
• File surface: packages/cli/src/commands/init.ts (rendered template literals only), plus a new pin under packages/cli/
• Container & model: remote CCR container, os-dev subagent
• Clause-②: no — three-dot diff surface touches no packages/spec/src/**; no Clause-②: yes declared by triage
• Serial constraints cleared: triage's hot-file note named packages/cli/src/commands/init.ts as shared with queued 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 and [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 have since landed — 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 via PR fix(cli): declare the four @better-auth/utils peer skews a fresh scaffold reports #11128 (afe1c4e0a1), [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 via PR fix(scaffold): state the measured pnpm build-approval boundary, and gate the two scaffold paths against each other #11090 (6d441e41f9). No open PR remains over init.ts.

Fold answer: dispatched alone, not folded with the #10990/#11022 pair

Those two are folded together (see #10990) because they share a test file. This card does not reach that file, that package, or that gate surface: it is packages/cli, whose suites and CI path filters are disjoint from packages/create-objectstack/**. Folding would merge two unrelated verification surfaces into one PR for no shared work — exactly the reason this card was filed separately from #10324 in the first place.

Not folded with #10967 either, though both are packages/cli "stale text that ships to the user": disjoint files (init.ts vs commands/environments/*.ts), different mechanisms (rendered template string literals vs oclif static examples), and #10967 carries optional class-rename riders across six files. #10967 goes out in the next round.

Landing points re-measured at origin/main — ⚠️ every line number in the card has moved

The card's numbers were taken before #11090 and #11128 landed in this same file. Measured now:

Card said	Measured at origin/main	Text
:313	:397	// Protocol major this app is authored against (ADR-0087 load-time check).
:349	:433	// Org-wide default (OWD): who can see records they do NOT own. ADR-0090 D1
:393	:477	// Protocol major this plugin is authored against (ADR-0087 load-time check).
:415	:499	// Org-wide default (OWD): who can see records they do NOT own. ADR-0090 D1
:456	:540	// Protocol major this app is authored against (ADR-0087 load-time check).

Five occurrences, exactly as carded — the mechanism is intact, only the offsets drifted. Locate by text, never by the card's line numbers. The card's note that :488's #10499 is an ordinary in-repo source comment (not template text) should likewise be re-derived at the current offsets rather than trusted as a line number.

Pin shape

The card points at #10324's packages/create-objectstack/src/starter-comments-self-contained.test.ts as the worked example, and it is the right one — it asserts both halves (no unfollowable reference and the fact each reference carried is still stated), because a one-way grep stays green while the explanation is deleted. Note the population differs here: that test walks files on disk, whereas this card's population is template literals rendered by init.ts, so the pin has to reach the rendered text, not the source file's own comments — otherwise it will match init.ts's ordinary in-repo comments and report on the wrong population. Measure that boundary before writing the assertion.

The :433/:499 OWD comments are good comments — they explain that the org-wide default must be an authored decision. Rewrite them self-contained; never delete the rationale.

Dispatching now.

---

Generated by Claude Code