[maintainer] create-objectstack: the blank template's pnpm-workspace.yaml is 85 lines, 66 of them peer-dependency commentary — the third-largest file in a "clean slate" project; keep the file minimal and move the rationale out

Filing gate: ③ task dispatched by the maintainer, quoted verbatim below; measurements class (a), this session.
reach: npm create objectstack@latest my-app (17.7.0) writes pnpm-workspace.yaml at 4,700 bytes: 85 lines, 66 comment lines, 5 blank, 14 lines of configuration. By size it is the third file in the project after README.md (6,491) and AGENTS.md (5,514), ahead of objectstack.config.ts (4,032).
Reader: domain:cli seat (packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml; os init renders the same file).
Dedup: search_issues "blank template pnpm-workspace.yaml long comments peerDependencyRules scaffold minimal file" → 5 hits, all closed; #17093 is the only one about this file (a retired comment that no gate reads — it shows the commentary already drifts); none asks for the file to shrink.
Filed on the maintainer's instruction in this session (category ③, quoted verbatim): 「空白模板的 pnpm-workspace.yaml 有约 90 行 peer-dependency 考据注释。对"clean slate"项目来说这是第一眼看到的最长文件。建议文件保持最小,理由搬到文档或脚手架源码注释。」

What the newcomer opens

The scaffolded project's README calls itself "a clean slate for building". The workspace file they open beside it explains, over 66 comment lines: which pnpm versions parse packages: before engines; why allowBuilds and onlyBuiltDependencies are both needed and which pnpm versions read which; a behavioural measurement of better-auth on better-sqlite3 13 vs 12 ("Re-measured on the pinned 1.7.2 and now structural…"); a retired @better-auth/scim>better-call entry and the date it retired; four @better-auth/*>@better-auth/utils skews and the pnpm version at which they self-resolve. All of it is true, none of it is the newcomer's decision, and #17093 showed it drifts because no gate reads it.

Asked for

Keep the 14 configuration lines, each with at most one comment line naming its reason, e.g.:

packages: []            # settings-only; this project is not a workspace root

allowBuilds:            # native/prebuilt installs pnpm must be allowed to run
  better-sqlite3: true
  esbuild: true
onlyBuiltDependencies:  # same list, for pnpm < 10.26
  - better-sqlite3
  - esbuild

peerDependencyRules:    # declared-vs-resolved peer skews measured harmless; see <docs page>
  allowedVersions:
    'better-auth>better-sqlite3': '13'
    …

The measurements and version-history move to where they are maintained: the scaffolder source (template-consistency.test.ts / pkg-utils.ts already own the version pins) or a short docs page the comment links to. The two consistency tests keep asserting the configuration, which is all they assert today.

Generated by Claude Code

Path: the road — start: a clean-slate project looks clean | 缺项 | P3

Triage: first grade, `enhancement` · `priority:p3` · `domain:cli` · `area:devpath` · `pm:queue` (`finding` removed). The maintainer's direction, as dispatched

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-08T05:11Z. ⛔ Not a claim, ⛔ not a dispatch.

Triage: lands in packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml (and os init's copy) ⇒ domain:cli; rationale: create-objectstack is that lane's. Read on main ec8f37c890.

Why p3: the scaffold works; 66 comment lines crowd a clean-slate file (measured).
Direction:
- keep the configuration lines; move the rationale to a docs page or one link line
- both scaffolders render the same file
Clause-②: no. Patch changeset for create-objectstack.

Claim: PM loop round 9
Session: session_01RWZbGvPFcRKvUqASZtunCU
Account: os-warren (the seat's linked user as get_me answers it; the card's assignee)
Branch: claude/issue-22162-scaffold-workspace-minimal
Worktree: objectstack-issue-22162
Domain: domain:cli
Seat: domain:cli#1
File surface, per the card body and triage 6052789956, read on origin/main 7d7943dd:

packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml: keep the configuration lines, each with at most one comment line naming its reason, and move the 66 lines of measurements and version history out.
packages/cli/src/commands/init.ts: renderPnpmWorkspaceYaml (:493), which os init and os create render the same file from.
Where the rationale moves: scaffolder source comments beside the pins that own it (packages/create-objectstack/src/template-consistency.test.ts, pkg-utils.ts; packages/cli/test/scaffold-workspace-consistency.test.ts). ⛔ Not a new docs page: that would be a domain:devx file, so stop and report if a link target is needed.
.changeset/*.md: create-objectstack patch (and @objectstack/cli patch if init.ts's rendered output changes).
⛔ The configuration itself (packages, allowBuilds, onlyBuiltDependencies, peerDependencyRules) is unchanged, and so are both consistency tests' assertions on it. (Stop on breach and explain in the report.)
Container & model: S, mode:subagent, model: default (opus). dispatch-gates --tier over the path gives no path-derived mandate.
Clause-②: no
Comment text in a scaffolded file; no accepted input or published shape changes.
Responsibility: n/a — not a defect card
Thread-read: 6052789956
Serial constraints cleared: read 2026-10-08T06:45Z:
Open PRs (each file list read by filename): none touches pnpm-workspace.yaml, commands/init.ts, commands/create.ts or the two consistency tests. This seat's PR fix(create-objectstack): the scaffolded Dockerfile installs from the project's own lockfile #22217 ([finding] create-objectstack: the scaffolded Dockerfile runs npm ci, but a pnpm-scaffolded project ships only pnpm-lock.yaml — docker build fails at the build stage #22150) edits the template's Dockerfile and copies pnpm-workspace.yaml* into the image, but does not edit it.
In-flight claims: spec(v18): move PROTOCOL_VERSION 17 → 18 in an ordinary pull request with full CI: regenerate spec-changes.json and the 17 → 18 upgrade-guide section, rewrite the in-repo ^17 handshakes, and give the lockstep test one pre-mode exception (#22085 Q1) #22130 (6051334172) writes the template's objectstack.config.ts ^17 handshake, not these files. This seat's [maintainer] dev-mode noise budget: a blank project written verbatim from the tutorial boots with 4 WARN lines and only one needs the author's hand — expected degradations to info, stacks only at debug, the actionable line highlighted with a one-line fix #22160 holds packages/cli/src/utils/format.ts, not these files.

_{domain:cli seat · session_01RWZbGvPFcRKvUqASZtunCU · 2026-10-08T06:45Z}

os-dev-report

{
  "issue": 22162,
  "status": "done",
  "branch": "claude/issue-22162-scaffold-workspace-minimal",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/22229",
  "session": "session_01RWZbGvPFcRKvUqASZtunCU",
  "premise_still_valid": true,
  "summary": "Both scaffold paths now write the same 21-line, 722-byte pnpm-workspace.yaml. The create-objectstack template was 85 lines / 4,700 bytes with 66 comment lines; renderPnpmWorkspaceYaml() for os init and a standalone os create was 74 lines / 3,762 bytes with 57. The configuration is unchanged (keys, values and order; comment-stripped sha256 prefix 9992ee6451e59720 on both sides before and after), and each of the four blocks has one comment line naming its reason. Every fact the old files carried now sits beside its value in init.ts docblocks; two facts were missing there and were added: esbuild's role and better-sqlite3 as driver-sql's optional dependency on SCAFFOLD_BUILT_DEPENDENCIES, and the 2026-09-11 re-read on 1.7.3 on SCAFFOLD_ALLOWED_PEER_VERSIONS. scaffold-workspace-consistency.test.ts gains a byte-identity limb and a per-producer comment-budget limb (one full-line comment directly above each top-level key, at most 80 columns), and both were ablated red. One PM reading is partly false: that test's version-boundary limb asserted PROSE, not configuration only. Its reader was adapted to the one-line shape; the assertion itself is unchanged.",
  "tests": "All at head e95920e0. Heavy runs went through os-verify-lock; the VERDICT lines are quoted. (1) pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2: 'Test Files 2 failed | 261 passed (263)', 'Tests 3848 passed | 29 skipped'. The 2 failed files (published-subpath-console.pin, published-subpath-hook-body.pin) threw 'packages/cli is not built', a prerequisite and not a verdict. After pnpm --filter @objectstack/cli build they re-ran: 'Test Files 2 passed (2)', 'Tests 29 passed (29)', VERDICT command-exit 0. So the unit tier is 263/263 files. The integration tier is left to CI: the diff touches no integration file and no spawn entry point. (2) pnpm --filter create-objectstack test: 'Test Files 16 passed (16)', 'Tests 249 passed (249)'. (3) pnpm --filter @objectstack/cli typecheck (tsc --noEmit plus check:test-typecheck over tsconfig.test.json, which covers test/): exit 0, 'check:test-typecheck: OK ... 3 file(s) / 28 error(s) / 6 pinned signature(s) held', unchanged. (4) pnpm --filter create-objectstack typecheck: exit 0; its include is src, so it covers the edited test. The batch wrapper printed 'VERDICT batch-last-exit 2'; that number comes from my own malformed trailing test over unassigned variables, and the per-part EXIT= lines above are the readings. (5) Verbose run of scaffold-workspace-consistency.test.ts: all 6 limbs ran by name in the unit tier and passed. ABLATION (one-time, from the committed fix e95920e0; no permanent file). Each leg wrote BASE bytes with git show BASE:path and checked that the write landed: on-disk blob equal to the BASE blob (template ef9209b7, renderer 929642fb), old anchor 'An explicit EMPTY workspace' counted 1 and new anchor 'Older pnpm needs this key' counted 0. Restore was git checkout HEAD -- path under an EXIT INT TERM trap, checked by the on-disk blob equalling the HEAD blob (ef629642 / ccd65107), git diff HEAD empty and status clean. Both subjects resolve to src (template read with fs from src/templates; renderer imported from ../src), so no dist is in the path and no rebuild was owed. The direction was predicted before each run and observed as predicted. Template leg: 3 failed | 3 passed. Red: byte identity; 'npx create-objectstack carries at most one short comment line per block' with 66 breaches (65 lines not directly above a key, plus old line 17 at 81 columns); version boundary (blank line above each approval key). Green: grants, peer map, objectstack init budget. Renderer leg: 3 failed | 3 passed. Red: byte identity; objectstack init budget with 54 breaches; version boundary. Green: the rest. In both legs the old line directly above packages: [] was correctly not flagged.",
  "gates": {
    "head": "e95920e0",
    "derivation": "node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands over the delivered change set (5 paths vs merge base 7d7943dd0): 68 commands, the same list as the order (diff empty)",
    "reconciliation": "dispatch-gates --ran: 'Run reconciliation — 68 derived, 68 run, 0 NOT-MEASURED, 0 UNRUN.' / 'a DERIVED zero — all 68 recorded an exit code and none of them is 3'; pnpm lint recorded as outside the derivation",
    "lint": "pnpm lint (eslint . --no-inline-config, the whole repo): exit 0, no findings printed",
    "first_pass_refusals_rerun": "check:dual-build-cjs-loads, check:i18n, check:i18n-coverage and check:i18n-walk-parity exited 3 (PREREQUISITE NOT MET, unbuilt workspace) on the first pass. After turbo run build (VERDICT command-exit 0) all four exit 0: '106 published require entry point(s) across 66 package(s) load'; 'OK (9 package(s) — all bundles in sync, no undeclared authoring keys)'; 'OK (13 config(s), 621 baselined untranslated string(s), none new)'; '11 declared group(s), 9 walked, 2 exempted'. check:published-files, check:dts-closure, check:lean-entry-closure and check:sourcemap-no-sources-content were re-run on the fresh dist: exit 0",
    "added_by_rederivation": "none; the derivation equals the order list"
  },
  "line_budget": {
    "new_file": "21 lines, 722 bytes (4 comment, 3 blank, 14 config), identical for both producers",
    "before": "template 85 lines / 4,700 bytes (66 comment); renderer 74 lines / 3,762 bytes (57 comment)",
    "ranking": "Scaffolded with --skip-install --skip-skills, 22 files. Before: README.md 6,491 · AGENTS.md 5,514 · .github/copilot-instructions.md 5,514 (a byte copy of AGENTS.md) · pnpm-workspace.yaml 4,700 · objectstack.config.ts 4,032. That is rank 4 by bytes, or 3rd as the card counted it with the copy folded in. After: pnpm-workspace.yaml 722 bytes, rank 10 of 22",
    "pin": "at most one full-line comment per top-level block, directly above its key, at most 80 columns (scaffold-workspace-consistency.test.ts)"
  },
  "files_changed": [
    "packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml",
    "packages/cli/src/commands/init.ts",
    "packages/cli/test/scaffold-workspace-consistency.test.ts",
    "packages/create-objectstack/src/template-consistency.test.ts",
    ".changeset/22162-scaffold-workspace-minimal.md"
  ],
  "deviations": [
    "Card sketch versus the delivered file: the comments sit on their own line above each key, not inline. Every configuration reader in init.test.ts, template-consistency.test.ts and the consistency test strips only full-line comments, so an inline 'packages: []  # ...' would fail 'declares it EMPTY' and the '^allowBuilds:\\n' block readers. The order stays packages, onlyBuiltDependencies, allowBuilds, peerDependencyRules (the sketch swapped the middle two), because 'adds no other top-level setting' pins it in both packages.",
    "PM reading falsified in part: 'the consistency tests keep asserting the configuration, which is what they assert today'. The limb 'states the same pnpm version boundary for each key' asserted prose. I kept the assertion and adapted only its reader (the comment line directly above each approval key). That is why the two approval lines name 10.0–10.25 and 10.26.",
    "File surface: the claim named pkg-utils.ts as a candidate home. It only syncs the @objectstack/* ranges and owns none of these facts, so it was not touched. init.test.ts and create.test.ts were not edited; their comment-stripped assertions pass unchanged. No docs page or link was added.",
    "Dropped from the user's file and not relocated: the template's 'Both ship prebuilt binaries, so an unapproved build degrades rather than breaks'. It contradicts the renderer's prose and the SCAFFOLD_BUILT_DEPENDENCIES docblock ('Could not locate the bindings file'). I did not re-measure it. Dropped as history only, still held in source and in #17093: the scim>better-call retirement and its dates, and the dated re-reads.",
    "Commit trailers: the model-free pair (Co-authored-by: Claude, Claude-Session). The harness asked for a model-named Co-Authored-By; I did not follow it, per AGENTS.md and the order.",
    "origin/main gained 4 commits since 7d7943dd (b8feb550, 35396b5e, 3b493184, 7b926f76). None touches packages/cli or packages/create-objectstack (empty diff on this surface), so no merge was taken."
  ],
  "mcp_calls": "0 — no MCP GitHub tool was called",
  "api_writes": "3 — all through the fleet-write relay as objectstack-fleet[bot], each POST /repos/objectstack-ai/objectstack/dispatches: (1) pr_create, which executed POST /repos/objectstack-ai/objectstack/pulls (draft) and created #22229, read back with 13427 bytes stored identical; (2) assign via label-write.mjs, which executed POST /repos/objectstack-ai/objectstack/issues/22229/assignees with os-warren, read back MATCHES, zero label writes; (3) this os-dev-report comment via post-stamped.mjs, POST /repos/objectstack-ai/objectstack/issues/22162/comments. Not REST writes: 2 git pushes (the empty branch probe, then e95920e0).",
  "open_questions": [],
  "out_of_scope_findings": [
    "carrier: none · noted, not filed (Acceptance notes of #22229): the old template claimed better-sqlite3 and esbuild 'degrade rather than break' without an approved build, while the renderer and the SCAFFOLD_BUILT_DEPENDENCIES docblock say serve fails with 'Could not locate the bindings file'. The contradicting claim no longer ships, so nothing user-visible remains, and nothing was re-measured."
  ]
}

Generated by Claude Code

ACCEPT — PR #22229 at `e95920e0`, pending CI

_{domain:cli seat · session_01RWZbGvPFcRKvUqASZtunCU · read on GitHub 2026-10-08T07:38Z}

Checked on GitHub and in the diff, not from the report:

Shape:
- draft, base main;
- line 1 is Fixes #22162, line 2 is Clause-②: no;
- assignee os-warren;
- 5 files, +158 / −154.
The configuration is unchanged. With comment and blank lines stripped, the template on origin/main and at e95920e0 diff empty. The renderer's array keeps the same keys, values and order. Only the comment strings changed.
The new file is 21 lines with one full-line comment above each of the four blocks. Each comment checks against the per-version table in the renderPnpmWorkspaceYaml docblock:
- 10.0–10.25 read only onlyBuiltDependencies;
- 10.26 and later read allowBuilds, and pnpm 11 reads only that key;
- pnpm 9.x and 10.0–10.4 refuse the file without packages: (init.ts:265 at head).
Every fact the old comments carried is in source at head. Grepped in init.ts:
- ERR_PNPM_IGNORED_BUILDS (:489);
- the packages: ['.'] member warning (:475);
- the utils 0.4.2 → 0.5.0 skews and the symbols measured (:186–:201);
- the retired @better-auth/scim>better-call entry (:177);
- the byte-identical lockfile (:230).
- Two facts are newly added there: esbuild's and better-sqlite3's roles, and the 2026-09-11 1.7.3 re-read.
The pins (scaffold-workspace-consistency.test.ts): the two producers render the same bytes, and each producer stays within one comment line per block, directly above its key and at most 80 columns wide.
- Both are non-vacuous: the budget limb first requires a top-level key.
- The dev's ablation reddens both limbs with either old file put back.
- The version-boundary limb keeps its assertion; only its reader moved to the one-line shape. The dev reported that as a falsified PM reading, correctly: that limb asserted prose.
Departures from the card's sketch (comments on their own line, not inline; key order kept): both are forced by existing full-line-comment readers and the "no other top-level setting" pins. They stand.
No mkdtemp site in the diff, so the seat's dispatch-gates --self-test is not owed.

Changeset: create-objectstack patch and @objectstack/cli patch (os init / os create render different bytes). Each sentence checks against the diff: the settings are unchanged, all three doors write the same 21-line file, and projects already scaffolded are not touched.

Evidence (the dev's, at e95920e0):

@objectstack/cli unit tier: 263 files (two after a build);
create-objectstack: 16 files, 249 tests;
both typechecks exit 0;
pnpm lint exit 0;
68 of 68 gates reconciled.

Not carried: the old template's "an unapproved build degrades rather than breaks" contradicted the measured docblock. It no longer ships, so no card is filed.

Next: CI on e95920e0 (10 runs still in progress at this read), then the landing pre-checks and the queue.

Landed: PR #22229 → `31cd2104dc`, a single-parent queue squash

_{domain:cli seat · session_01RWZbGvPFcRKvUqASZtunCU · 2026-10-08T09:01Z}

Landing shape:
- 31cd2104dc has one parent.
- It is an ancestor of origin/main; the pre-merge head e95920e0 is not.
- It entered the merge queue 2026-10-08T07:58:27Z and merged 2026-10-08T09:01:31Z on that first entry.
- Fixes #22162 closed this card as completed.
Content on origin/main:
- the blank template's pnpm-workspace.yaml is 21 lines;
- renderPnpmWorkspaceYaml in packages/cli/src/commands/init.ts renders the same one-comment-per-block file;
- scaffold-workspace-consistency.test.ts carries the byte-identity and comment-budget limbs;
- .changeset/22162-scaffold-workspace-minimal.md is present (create-objectstack and @objectstack/cli patch).
Review of record: ACCEPT 6055094185 at e95920e0, in one round. Clause-②: no; no contract review was owed. CI on the head was green (37 runs) before the PR was armed, and no temp-directory site was added.
Delivered: a new project's pnpm-workspace.yaml is a 21-line settings file with one comment line per block. npm create objectstack, objectstack init and a standalone objectstack create write the same bytes. The measurements behind each value live in init.ts's docblocks, beside the values they explain. The settings are unchanged, so a project installs exactly as before.

fix(create-objectstack,cli): the scaffolded pnpm-workspace.yaml is on…

Navigation Menu

Repository navigation

[maintainer] create-objectstack: the blank template's `pnpm-workspace.yaml` is 85 lines, 66 of them peer-dependency commentary — the third-largest file in a "clean slate" project; keep the file minimal and move the rationale out #22162

What the newcomer opens

Asked for

Triage: first grade, `enhancement` · `priority:p3` · `domain:cli` · `area:devpath` · `pm:queue` (`finding` removed). The maintainer's direction, as dispatched

ACCEPT — PR #22229 at `e95920e0`, pending CI

Landed: PR #22229 → `31cd2104dc`, a single-parent queue squash

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[maintainer] create-objectstack: the blank template's pnpm-workspace.yaml is 85 lines, 66 of them peer-dependency commentary — the third-largest file in a "clean slate" project; keep the file minimal and move the rationale out #22162

Description

What the newcomer opens

Asked for

Activity

objectstack-fleet commented on Oct 8, 2026

Triage: first grade, enhancement · priority:p3 · domain:cli · area:devpath · pm:queue (finding removed). The maintainer's direction, as dispatched

objectstack-fleet commented on Oct 8, 2026

objectstack-fleet commented on Oct 8, 2026

objectstack-fleet commented on Oct 8, 2026

ACCEPT — PR #22229 at e95920e0, pending CI

objectstack-fleet commented on Oct 8, 2026

Landed: PR #22229 → 31cd2104dc, a single-parent queue squash

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[maintainer] create-objectstack: the blank template's `pnpm-workspace.yaml` is 85 lines, 66 of them peer-dependency commentary — the third-largest file in a "clean slate" project; keep the file minimal and move the rationale out #22162

Triage: first grade, `enhancement` · `priority:p3` · `domain:cli` · `area:devpath` · `pm:queue` (`finding` removed). The maintainer's direction, as dispatched

ACCEPT — PR #22229 at `e95920e0`, pending CI

Landed: PR #22229 → `31cd2104dc`, a single-parent queue squash