fix(cli): the scaffolded pnpm-workspace.yaml records the retired @better-auth/scim>better-call rule instead of advertising it

[claude]

Fixes #17093

renderPnpmWorkspaceYaml() wrote a paragraph into every project objectstack init
scaffolds explaining an @better-auth/scim>better-call peer rule that is not in the
map it annotates. The defect is in what ships, so every reading below is taken from
the rendered output, not from the source.

Shipping proof, before the fix — the sentence is inside the published tarball's own
dist (@objectstack/cli publishes files: ["dist","README.md","CHANGELOG.md"]):

$ grep -c "held at a release candidate deliberately" packages/cli/dist/commands/init.js
1
$ grep -c "Re-measured 2026-09-11 on" packages/cli/dist/commands/init.js   # control, same file
1

The three claims, re-measured on this tree

Re-measured here rather than carried from the card — the card's version number was
already stale, and so was this file's own (see The file disagreed with itself).

1. The entry it explains is absent from the rendered map

The rendered peerDependencyRules.allowedVersions block, verbatim:

    'better-auth>better-sqlite3': '13'
    '@better-auth/core>@better-auth/utils': '0.5.0'
    '@better-auth/oauth-provider>@better-auth/utils': '0.5.0'
    '@better-auth/scim>@better-auth/utils': '0.5.0'
    '@better-auth/sso>@better-auth/utils': '0.5.0'

Zero, with two positive controls from the same rendered artifact under the same
grep shape:

reading	count
ZERO — scim>better-call	0
CONTROL — scim>@better-auth/utils (a scim-prefixed key that IS there)	1
CONTROL — better-auth>better-sqlite3	1

The card's cited absence pin is live and passing:
test/init.test.ts → keeps the retired @better-auth/scim>better-call suppression OUT (#3653).

2. @better-auth/scim is NOT "held at a release candidate deliberately"

It is pinned at an exact stable version. pnpm-workspace.yaml:239:

  '@better-auth/scim@<2.0.0': '1.7.3'

and the installed manifest agrees — version string "1.7.3", no prerelease tag
(.includes('-') is false). Exactly one copy resolves in the store.

3. Stable @better-auth/scim@1.7.3 peers better-call at exactly 1.4.0, not 1.3.7

Read off the installed package manifest, not off prose:

peerDependencies: {
  "@better-auth/utils": "0.4.2",
  "better-call": "1.4.0",
  "@better-auth/core": "^1.7.3",
  "better-auth": "^1.7.3"
}

better-auth@1.7.3 itself declares dependencies["better-call"] === "1.4.0", and the
store holds a single better-call copy (better-call@1.4.0_zod@4.6.1). So the skew
the paragraph described does not exist: both sides want the same exact version.

Note better-call appears four times in the rendered file and only two of them are
this defect. The other two are in the @better-auth/utils paragraph, where better-call
is the load-bearing reason those four entries exist (it is the package that depends on
^0.5.0). That paragraph is correct and is untouched — a count would have hidden this;
each hit was read in context.

Rendered output, before and after

Driven through the card's own repro — renderPnpmWorkspaceYaml() out of the built
dist, which is what a scaffolded user receives:

-#   @better-auth/scim (held at a release candidate deliberately) peers an
-#   exact better-call 1.3.7, while better-auth itself depends on 1.4.0. A
-#   better-auth plugin has to share the host's better-call instance, so
-#   the single 1.4.0 copy is the correct resolution.
+#   (The '@better-auth/scim>better-call' entry that used to sit here is
+#   retired. The rc-era scim pin peered an exact better-call 1.3.7 against
+#   better-auth's own 1.4.0 and this map declared that skew away; the pin
+#   is a stable release now, and @better-auth/scim 1.7.3 peers an exact
+#   better-call 1.4.0 — the one copy better-auth depends on. Re-measured
+#   2026-09-12 off the installed manifest: the skew is gone.)

That is the whole rendered delta. No declaration moves: comment-stripped and with
blank lines dropped, the rendered settings are byte-identical across the change —
14 lines both sides, sha256 prefix 9992ee6451e59720 before and after. The
comparison is not vacuous: mutating one character of the map ('13' to '99') is
detected by it.

The shape mirrors the sibling producer, which already recorded the retirement —
packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml. That was the
asymmetry the card named: one path recorded the retirement while the other still
advertised the rule.

This was not an unmaintained block — its neighbour was maintained past it

The paragraph immediately above, in the same rendered block, was re-measured
recently. init.ts:509-:510:

      '#   nothing here goes down that path. Re-measured 2026-09-11 on',
      '#   better-auth 1.7.3: nothing in the published package references',

So someone re-measured better-auth 1.7.3 one day ago, wrote the date into the
neighbouring paragraph, and left this one advertising an rc-era skew. The corrected
paragraph therefore carries its own measurement date, in that neighbour's style.

The file disagreed with itself — and so did the sibling

A finding in its own right, and the reason none of the three numbers in play was
taken on anyone's word. Before this PR init.ts gave two different answers for the
same pin:

site	said	status
init.ts:142-:143	"Stable @better-auth/scim@1.7.1 (the pin since #3653 landed)"	stale — reads as the current pin
init.ts:197	"stable 1.7.1 peers better-call@1.4.0 exactly"	stale
init.ts:178	"Stable @better-auth/scim@1.7.3 ... re-read (2026-09-11)"	matches the pin
the sibling template	"stable @better-auth/scim 1.7.1 peers better-call 1.4.0"	stale

pnpm-workspace.yaml:239 settles it: the pin is 1.7.3. The card's own 1.7.2 was a
third answer, and stale too.

The two stale init.ts comments are the source prose for the very entry this PR
corrects, so leaving them would have manufactured a fresh disagreement with the
paragraph being fixed. Both now name the measured 1.7.3, and so does the sibling
template's note — otherwise the two scaffold paths would have gone on telling a user
two different versions, which is the exact divergence
scaffold-workspace-consistency.test.ts exists to prevent. Each keeps the 1.7.1
reading as history, attributed to when it was measured, rather than deleting it.

What holds the corrected paragraph: nothing. Stated, not invented.

Per triage's binding boundary, no gate was widened to compare prose. Measured rather
than assumed — scaffold-workspace-consistency.test.ts DOES have a prose reader
(keyProse() / versionsNamed()), so "it only compares the map" needed checking.
Replaying that reader verbatim over both rendered files:

keys the gate captures: [ 'allowBuilds', 'onlyBuiltDependencies' ]
  allowBuilds           -> versionsNamed = [10.26]
  onlyBuiltDependencies -> versionsNamed = [10.0, 10.25]
ZERO   : captured prose mentioning "better-call"  -> 0
ZERO   : captured prose mentioning "scim"         -> 0
CONTROL: captured prose mentioning "10.26"        -> 1
CONTROL: whole file  mentioning "better-call"     -> 5
CONTROL: whole file  mentioning "scim"            -> 5

Its reader only opens on a comment line whose first token is allowBuilds or
onlyBuiltDependencies, and its accumulator resets before the peer block is reached,
so peer-block prose never reaches it. Identical capture before and after this change.

So the accounting is:

• the key's absence is pinned — init.test.ts (SCIM: 停在 @better-auth/scim rc.1,等正式版再整体迁移 —— rc.2 换掉了整套模型 #3653), passing;
• the build-approval prose's version claims are cross-compared between the two
  scaffold paths — scaffold-workspace-consistency.test.ts, passing;
• the peer-block prose — this paragraph — is held by nothing, deliberately.
  That is a named, accepted gap, and the card's structural half already rules that
  closing it here would defeat a deliberate exemption.

One thing worth checking, since the corrected note now contains the literal string
'@better-auth/scim>better-call' inside a comment while the absence pin asserts that
string is absent: the pin reads comment-stripped text, so it still measures the
declaration and not this prose.

raw rendered contains the key string:        1
comment-stripped (what the pin asserts on):  0
CONTROL — comment-stripped still contains '@better-auth/scim>@better-auth/utils': 1

Changeset

Required, and present — patch for @objectstack/cli and create-objectstack. Both
publish the changed bytes: @objectstack/cli compiles the rendered string into
dist/commands/init.js, and create-objectstack ships
dist/templates/blank/pnpm-workspace.yaml; both list dist in files[]. Not
skip-changeset — the file a user's project receives changes.

Gates

dispatch-gates.mjs derived 58 families for the delivered change set; all 58 ran
and are reconciled with recorded exit codes:

Run reconciliation — 58 derived, 58 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 58 derived famil(ies) accounted for — 58 run,
  0 NOT-MEASURED (a DERIVED zero — all 58 recorded an exit code and none of them is 3).

Two of them first returned exit 3 — PREREQUISITE NOT MET, an unbuilt workspace,
which is "nothing was measured" and not a finding. Both were re-run green after
building the prerequisites they named, rather than being recorded as passes:
check:i18n-coverage → OK (13 config(s), 621 baselined untranslated string(s), none new),
check:dual-build-cjs-loads → 104 published require entry point(s) across 67 package(s) load.

Also run, all green, all exit codes captured before any pipe:

run	result
pnpm --filter @objectstack/cli exec vitest run --project unit	197 files / 2820 tests passed
pnpm --filter create-objectstack test	16 files / 203 tests passed
pnpm --filter @objectstack/cli --filter create-objectstack typecheck	passed
pnpm lint (whole repo, eslint . --no-inline-config)	exit 0 — full run, no narrowing
pnpm check:nul-bytes + a direct control-character sweep of both files	clean

packages/cli integration tier is declared to CI: the diff touches no integration-tier
file, no bin/ entry and no spawn helper. Heavy runs went through
scripts/pm/os-verify-lock.sh; every verdict above is that script's own
VERDICT command-exit line.

Acceptance notes

• pnpm-workspace.yaml:107-:109 carries the same staleness one layer out: it says
  "measured unchanged on 1.7.2, the version this lockfile now holds", while line
  :239 pins 1.7.3 and the installed tree holds 1.7.3. Out of scope here (repo
  infrastructure, not a scaffold artifact, and nothing a user receives) and not a
  defect class that takes a card — noted for whoever next re-measures the better-auth
  family pins, which is the traffic that reads those lines.
  Clause-②: no

_{Line added by the dispatching domain:cli PM seat (#6024) after the delivering agent finished — the machine-readable carrier only. ⛔ No prose of the author's was altered, ⛔ the changeset was not dropped, ⛔ the package was not regraded, ⛔ nothing was pushed or re-run.}

• Clause-② re-derived from the delivered diff and unchanged at no: the rendered
  declarations are byte-identical, no accept set moves and no published surface shape
  changes. Comments only.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cli, objectstack-blank, touching 3 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/getting-started/examples.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/getting-started/your-first-project.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/plugins/index.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/protocol/kernel/index.mdx (via os init (command, read off packages/cli/src/commands/init.ts))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-1.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/releases/v17/17-4.mdx (via os init (command, read off packages/cli/src/commands/init.ts))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml) — pages documenting those are invisible to this run
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 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 — 23 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 ec739e67192ce686f956cd490b7bc2b9d0d64cac → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json ec739e67192ce686f956cd490b7bc2b9d0d64cac

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

[claude]

Check Changeset red — a PR-BODY declaration that is a near miss, ⛔ not a changeset problem. Clears with no push and no re-run

Posted by the dispatching domain:cli PM seat (#6024, session session_01TSf4DV7ziu4V5j73e46b7c), 2026-09-12T02:49Z, so this red is not re-diagnosed by the next reader. ⛔ No push from this seat — 「PM 永不写代码」; the delivering dev owns the edit and has been told.

What the job said

Read from the job log (103485427528), ⛔ not from the check name. It raises nothing about the changeset file — .changeset/17093-scaffold-scim-retirement-note.md is present and graded. It says:

· carrier: `needs:contract-review` is not on this PR (0 label(s) read)
· declaration line: a near miss, not a declaration —
  - `Clause-②` re-derived from the delivered diff and unchanged at **no**: the rendered …

⇒ the PR body writes the verdict with the label inside backticks and the colon outside them, the verdict in bold. The PR-body reader does not accept that shape, so the declaration limb read near miss, and the gate refuses rather than exiting 0 over a reading that never happened (#16776, #4690 — 「a reading that cannot fail is indistinguishable from one that passed」).

⚠️ Two carriers, two tolerances, and this is the live proof of it. The card-side reader (check-clause2-carriers, judging #17093's claim comment) accepts a line-initial key decorated with bullets, bold or backticks — and it passes there. The PR-body reader does not. ⛔ Never reason from one carrier's tolerance to the other's; that asymmetry is #17680's subject.

The remedy, quoted from the gate

DECLARE IT. One line, at the START of a line in the PR BODY (a - , > or ** prefix is read too):
Clause-②: no

⛔ The remedy is the declaration, never the deletion: dropping the changeset, or regrading the package to dodge this message, changes what ships in order to quiet a gate. And the line is read from the body on the next edited event (pr-automation.yml subscribes to it), so this red clears with no push and no re-run.

⇒ a body edit carrying a line-initial Clause-②: no. ⛔ The changeset is not dropped, ⛔ the package is not regraded, ⛔ no empty commit, ⛔ no job re-run. The patch grade stands on its own measurement and is not this gate's quarrel.

Everything else on this head reads clean

3 paths (.changeset/… +26, packages/cli/src/commands/init.ts +14/−9, packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml +4/−2). No .test.ts ⇒ triage's binding boundary holds — ⛔ no consistency test was widened to compare prose. No packages/spec. No content/docs/releases/. No intersection with the lane files held by PRs #17755, #17725 or #17718. packages/create-objectstack is in this lane (SKILL.md:250).

⚠️ One item from the docs-drift advisory worth carrying rather than skipping: it reports that the template file yielded no anchor, so 「the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files」. ⇒ its silence about the template half proves nothing, and ⛔ the two release-owned pages it lists are read-only.

This PR stays watched until it is green and mergeable or closed.

_{domain:cli execution PM seat · #6024 · session session_01TSf4DV7ziu4V5j73e46b7c · 2026-09-12T02:49Z}

---

Generated by Claude Code

[claude]

Correction to my comment above, and what I did instead

domain:cli execution PM seat (#6024), 2026-09-12T02:51Z. My previous comment said 「the delivering dev owns the edit and has been told」. That is now wrong: the delivering agent reported done and finished, so no one was left to make the body edit. Correcting it rather than leaving it standing.

What this seat edited, and why it is this seat's to edit

The PR body now carries a line-initial Clause-②: no. ⛔ That is not a code change and ⛔ not a push: the clause-② declaration is a two-carrier instrument, and the other carrier — the Clause-②: no on card #17093's claim comment — was written by this seat in the first place, because a dev 「⛔ posts no second claim」. The PR-body half belongs to the same seat; the delivering agent simply wrote it in a shape the PR-body reader does not accept.

Read back after the edit:

declaration is line-initial	✅
attribution footers in the stored body	1
lines of the author's prose missing	0

⛔ Nothing of the author's was altered — the explaining bullet it wrote stays exactly where it was, with the machine-readable line added above it. ⛔ The changeset was not dropped, ⛔ the package was not regraded, ⛔ no empty commit, ⛔ no job re-run. Per the gate's own text the red clears on the next edited event.

⚠️ Footer mechanics, since they are easy to get wrong here: PATCH /pulls appends exactly one bare footer (+58 bytes, measured again on this edit: sent 11,533 → stored 11,591), and it does not preserve one you send. So the safe shape is to strip the existing footer, send a footer-less body, and read back — which yields exactly one. ⛔ Sending a body that already carries a footer is untested on this endpoint.

The lesson this leaves, recorded rather than repeated

A dispatch order should require the PR body's clause-② line in the bare line-initial spelling, because after the delivering agent finishes, nobody else is positioned to fix a near miss — and the two carriers have different tolerances: the card-side reader accepts bullets, bold and backticks around a line-initial key; the PR-body reader does not. ⇒ this lane's future orders will say so, and the asymmetry is #17680's subject.

_{domain:cli execution PM seat · #6024 · session session_01TSf4DV7ziu4V5j73e46b7c · 2026-09-12T02:51Z}

---

Generated by Claude Code

[claude]

ACCEPT — reviewed on head ff04c9559996220362a3528e60bf00f01b75f8e8 by the dispatching domain:cli PM seat

domain:cli execution PM seat (#6024, session session_01TSf4DV7ziu4V5j73e46b7c), 2026-09-12T03:40Z. ⛔ Not a contract review: Clause-②: no, no needs:contract-review, mergeable_state reads clean.

Gates

Collapsed latest-per-name: 30 success · 6 skipped · 0 red · 0 running. ⭐ Check Changeset went red and cleared at 02:51:09Z on a body edit alone — no push, no re-run, no changeset dropped, no regrade (recorded above at 5642966690 / 5642975623).

The defect is fixed where it actually shipped

The paragraph a scaffolded user receives now reads as a dated retirement note with provenance, replacing three falsehoods with one measured statement: the entry 「used to sit here is retired」 (it is absent from the map), the pin 「is a stable release now」 (⛔ no longer 「held at a release candidate deliberately」), and `@better-auth/scim 1.7.3 peers an exact better-call 1.4.0 — the one copy better-auth depends on … Re-measured 2026-09-12 off the installed manifest: the skew is gone.」 ⇒ all three of the card's claims corrected, and ⭐ the new text carries a date and a source where the old one carried neither.

Verified by this seat on the branch, ⛔ not on the report

claim	reading
the rendered declarations do not move	SCAFFOLD_ALLOWED_PEER_VERSIONS and every 'x>y': entry are absent from the diff — the probe over added/removed lines returns empty
triage's boundary holds	no .test.ts in the diff ⇒ ⛔ no consistency test was widened to compare prose, exactly as ruled
the sibling template was corrected, not overwritten	1.7.1 → 1.7.3 keeps the historical reading: 「First measured on 1.7.1 when the entry retired; re-read 2026-09-12 on the 1.7.3 pin, off the installed manifest」
scope	3 paths; no packages/spec, no content/docs/releases/, no intersection with the lane files other open PRs hold. packages/create-objectstack is in this lane (SKILL.md:250)

⭐⭐ The risk the dev found on its own, and the trap it set for the reviewer

The corrected note contains the literal '@better-auth/scim>better-call' — the very string init.test.ts:348 asserts is absent:

expect(settings).not.toMatch(/'@better-auth\/scim>better-call'/);

From the assertion's shape alone that reads as a guaranteed failure, and this seat nearly filed it as one. It is not: settings is defined at :138, :264 and :323 as renderPnpmWorkspaceYaml().replace(/^\s*#.*$/gm, '') — comment-stripped. ⇒ the dev's measurement (raw rendered 1, comment-stripped 0, control declaration still 1) is exactly right, and the pin passes.

⛔ Never infer an assertion's INPUT from the assertion's shape — read the input's definition. Two things are worth naming: the dev identified this as the one non-obvious risk and measured it instead of assuming, and the reviewer who did not read settings's definition would have published a defect that does not exist.

Gate discipline

58 command families derived mechanically from the delivered change set, reconciled 「58 derived, 58 run, 0 NOT-MEASURED, 0 UNRUN」. Two returned exit 3 PREREQUISITE NOT MET and were re-run green after building what they named rather than recorded as passes. pnpm lint whole-repo at exit 0, no narrowing claimed. Nine git-sensitive gates re-run at the final commit because the first pass ran while the changeset was untracked.

Flipping out of draft and enqueueing now.

_{domain:cli execution PM seat · #6024 · session session_01TSf4DV7ziu4V5j73e46b7c · 2026-09-12T03:40Z}

---

Generated by Claude Code