refactor(cli): render the ADR-0087 conversion notice from one source, and gate it there

[os-trump]

Fixes#13743

The ADR-0087 D2 conversion notice now has one source in packages/cli, and the parity
guard holds it there. Output is byte-for-byte unchanged.

Which of triage's three options, and why

Option 1 — extract a shared formatter — carrying the smallest useful half of option 2.
Triage required this to be stated rather than defaulted, and the deciding input was a
measurement rather than a preference.

⭐ Option 3's supporting argument is falsified. Its case was that validate.ts folds
its copy into a warnings list --strict judges while the other two print directly, so
"the three call sites are not fully interchangeable, and forcing an extraction may need a
parameter for the difference." The first clause is true and I verified it; the second does
not follow. The asymmetry is entirely in the disposition of the string, never in the
string:

command	what it does with the sentence	the sentence itself
os build (compile.ts)	printWarning(...) behind !flags.json	identical
os lint (lint.ts)	printWarning(...) behind !flags.json	identical
os validate (validate.ts)	warnings.push(...), which --strict then judges	identical

Measured at the branch point d17f352b1b: extracting the template literal from each of the
three lines and hashing it gives one distinct value, 124 bytes, sha256 prefix
7197b905060762c3. A pure formatConversionNotice(notice) therefore serves all three and
costs no parameter for the difference — the extraction option's stated price does not
materialise.

Why not option 2 alone. A comparator locks today's three copies together and detects a
reword only after someone has written it; one source makes the divergence impossible to
write. It is also the disposition this file already reached for the same problem:
printTruncationNotice in the same module carries the note "ONE implementation of that
sentence, deliberately … nine copies of the wording would be nine chances for them to drift
apart." House precedent, not a new idea.

What option 2 still buys, and is kept. Extraction does not stop a copy coming back.
The rule added to validate-build-gate-parity.test.ts is therefore structural rather than
comparative: every authoring command renders through the one formatter, and none spells the
sentence out inline.

Re-derived the count — and the probe returned more than three

The release comment required a bound with a control that could have returned a fourth. It
did. A whole-repo git grep (no pathspec) for the prose fragment converted at load —
tuned to the sentence, not to the three known sites — finds a rendering the card does not
mention, in packages/spec/src/stack.zod.ts:

packages/cli/src/commands/compile.ts:238 the three the card counts
packages/cli/src/commands/lint.ts:580
packages/cli/src/commands/validate.ts:409
packages/spec/src/stack.zod.ts:2310 NOT in the card — defineStack's own face

and reading that seam turns up a fifth prose form on ConversionNotice.message
(packages/spec/src/conversions/apply.ts), which is what the --json payloads publish.

⇒ The card's "three" is correct as a count of the three authoring commands, and wrong as
a bound on the wording. Four renderings, three distinct sentences. The two in
packages/spec are fenced read-only on this card and cannot import the CLI's formatter
anyway (@objectstack/cli depends on @objectstack/spec, not the reverse), so they are
filed separately as #15095 and pinned here as a recorded fact rather than left for the next
reader to discover and "fix" in one command only.

The change

• packages/cli/src/utils/format.ts — formatConversionNotice(notice), a formatter and
  deliberately not a printer.
• compile.ts / lint.ts / validate.ts — render through it; the three inline literals
  are gone (grep -c for the prose in each command source: 0, 0, 0).
• packages/cli/test/validate-build-gate-parity.test.ts — the rule the old guard could not
  see, with a positive control that fails if the formatter stops carrying the sentence.
• packages/cli/src/utils/format.conversion-notice.test.ts — the value pin on the rendered
  sentence, plus the recorded form-1 / form-3 split.
• .changeset/cli-conversion-notice-one-source.md — patch. Measured from this package's
  own files field: @objectstack/cli publishes dist, compiled from the edited src, so
  the diff changes the published package even though it changes nothing an author can
  observe. skip-changeset would have been wrong.

Red-first — four arms, each naming a different assertion

Every mutation was committed-first, proved on disk by blob hash, and restored by blob-hash
equality against the HEAD blob under trap ... EXIT INT TERM on absolute paths. The guard
is a source-text scanner, so no build or dist step participates in any arm.

arm	mutation	expected	measured
A	reword lint.ts's copy, dropping the shared formatter	red on the "renders through ONE formatter" assertion	vitest exit 1 — lint.ts must render its ADR-0087 D2 conversion notices with formatConversionNotice(); 1 failed / 8 passed
B	keep the call, add a verbatim inline copy beside it	red on the "no inline copy" assertion	vitest exit 1 — lint.ts spells the ADR-0087 D2 conversion notice out inline; 1 failed / 8 passed
C	reword the ONE source in format.ts	red on the positive control AND on the value pin	vitest exit 1 — control fires, and the pin reports converted while loading where converted at load was expected; 2 failed / 10 passed
D	unmutated tree	green	vitest exit 0 — 2 files, 12 tests passed

Blob evidence, arm by arm: lint.ts HEAD blob 43ace89d…; mutated to 82ef231d… (A) and
a25e93f7… (B); restored to 43ace89d… with git diff HEAD empty each time. format.ts
HEAD blob 53d51fe1…; mutated to 80839a7e… (C); restored to 53d51fe1…. Final
git status --porcelain -- packages/cli was empty.

Arm A is precisely the check the dispatch asked for — reword one copy and show the guard
redden — and arms B and C exist because A alone would not have told you which assertion
fired.

Verification

At final HEAD 9fc66faf on a clean tree, after merging origin/main (which brought in
PR #15062, the armed sibling the dispatch warned about, plus four others):

• pnpm --filter @objectstack/cli typecheck — exit 0. Both halves: tsc --noEmit over
  src (which is where the new value pin lives, so it is type-checked), and
  check:test-typecheck over tsconfig.test.json, whose verdict line reads
  OK — @objectstack/cli's test layer compiles … 3 file(s) / 28 error(s) / 6 pinned signature(s) held — the pre-existing ledger, unmoved.
• Targeted vitest, 6 files / 53 tests passed: the two new/edited guards, the three
  conversion-notice e2e suites (lint-conversion-notices,
  validate-json-failure-conversions, build-json-failure-conversions — these drive the
  real CLI over a live conversion via tsx, so they are the behavioural proof the output
  did not move), and i18n-check-help-surface-parity from the merged sibling PR.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
  at that HEAD: 42 families (33 by path, 6 by change kind, 5 declared whole-tree).
  40 green. Two are NOT MEASURED and say so themselves: check-test-completeness.mjs
  grades a saved turbo run test log this box cannot produce ("the local reading for this
  gate is NOT MEASURED"), and check-half-states.mjs needs repo-scoped GitHub REST, which
  this container is refused (GET /repos/... returns 403 with no rate-limit headers while
  GET /rate_limit reports 15000 left). Five others first exited 3 on an unbuilt closure
  and went green after a full pnpm build: check:dual-build-cjs-loads, check:i18n,
  check:i18n-coverage, check:type-check-debt (which had also hit a local 300s cap), and
  the two named above stayed 3 for the reasons given.

Declared narrowing. The repo-wide pnpm lint sweep was not run locally; CI owns it and
runs it once regardless. Everything else in the derived union was run.

What this deliberately does not do

ConversionNotice.message and defineStack's warnConversionNotice are untouched. Whether
all of the renderings should descend from one source is a real question with a real cost on
either side, and it is #15095, not this card.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s).

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 22 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 ab47816914fd39709f4e9645370729ce1f4f9826 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 48aac740974ea994794664b7dce221ed4dfb15b1 — the merge of head 9fc66fafafab958e3ae03b0f43bf8989c9b72699 into base ab47816914fd39709f4e9645370729ce1f4f9826, 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 48aac740974ea994794664b7dce221ed4dfb15b1 && git checkout 48aac740974ea994794664b7dce221ed4dfb15b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ab47816914fd39709f4e9645370729ce1f4f9826 9fc66fafafab958e3ae03b0f43bf8989c9b72699 && git checkout -B drift-repro ab47816914fd39709f4e9645370729ce1f4f9826 && git merge --no-ff 9fc66fafafab958e3ae03b0f43bf8989c9b72699
node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826

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

[os-trump]

Fixes#13743

The ADR-0087 D2 conversion notice now has one source in packages/cli, and the parity
guard holds it there. Output is byte-for-byte unchanged.

Which of triage's three options, and why

Option 1 — extract a shared formatter — carrying the smallest useful half of option 2.
Triage required this to be stated rather than defaulted, and the deciding input was a
measurement rather than a preference.

⭐ Option 3's supporting argument is falsified. Its case was that validate.ts folds
its copy into a warnings list --strict judges while the other two print directly, so
"the three call sites are not fully interchangeable, and forcing an extraction may need a
parameter for the difference." The first clause is true and I verified it; the second does
not follow. The asymmetry is entirely in the disposition of the string, never in the
string:

command	what it does with the sentence	the sentence itself
os build (compile.ts)	printWarning(...) behind !flags.json	identical
os lint (lint.ts)	printWarning(...) behind !flags.json	identical
os validate (validate.ts)	warnings.push(...), which --strict then judges	identical

Measured at the branch point d17f352b1b: extracting the template literal from each of the
three lines and hashing it gives one distinct value, 124 bytes, sha256 prefix
7197b905060762c3. A pure formatConversionNotice(notice) therefore serves all three and
costs no parameter for the difference — the extraction option's stated price does not
materialise.

Why not option 2 alone. A comparator locks today's three copies together and detects a
reword only after someone has written it; one source makes the divergence impossible to
write. It is also the disposition this file already reached for the same problem:
printTruncationNotice in the same module carries the note "ONE implementation of that
sentence, deliberately … nine copies of the wording would be nine chances for them to drift
apart." House precedent, not a new idea.

What option 2 still buys, and is kept. Extraction does not stop a copy coming back.
The rule added to validate-build-gate-parity.test.ts is therefore structural rather than
comparative: every authoring command renders through the one formatter, and none spells the
sentence out inline.

Re-derived the count — and the probe returned more than three

The release comment required a bound with a control that could have returned a fourth. It
did. A whole-repo git grep (no pathspec) for the prose fragment converted at load —
tuned to the sentence, not to the three known sites — finds a rendering the card does not
mention, in packages/spec/src/stack.zod.ts:

packages/cli/src/commands/compile.ts:238 the three the card counts
packages/cli/src/commands/lint.ts:580
packages/cli/src/commands/validate.ts:409
packages/spec/src/stack.zod.ts:2310 NOT in the card — defineStack's own face

and reading that seam turns up a fifth prose form on ConversionNotice.message
(packages/spec/src/conversions/apply.ts), which is what the --json payloads publish.

⇒ The card's "three" is correct as a count of the three authoring commands, and wrong as
a bound on the wording. Four renderings, three distinct sentences. The two in
packages/spec are fenced read-only on this card and cannot import the CLI's formatter
anyway (@objectstack/cli depends on @objectstack/spec, not the reverse), so they are
filed separately as #15095 and pinned here as a recorded fact rather than left for the next
reader to discover and "fix" in one command only.

The change

• packages/cli/src/utils/format.ts — formatConversionNotice(notice), a formatter and
  deliberately not a printer.
• compile.ts / lint.ts / validate.ts — render through it; the three inline literals
  are gone (grep -c for the prose in each command source: 0, 0, 0).
• packages/cli/test/validate-build-gate-parity.test.ts — the rule the old guard could not
  see, with a positive control that fails if the formatter stops carrying the sentence.
• packages/cli/src/utils/format.conversion-notice.test.ts — the value pin on the rendered
  sentence, plus the recorded form-1 / form-3 split.
• .changeset/cli-conversion-notice-one-source.md — patch. Measured from this package's
  own files field: @objectstack/cli publishes dist, compiled from the edited src, so
  the diff changes the published package even though it changes nothing an author can
  observe. skip-changeset would have been wrong.

Red-first — four arms, each naming a different assertion

Every mutation was committed-first, proved on disk by blob hash, and restored by blob-hash
equality against the HEAD blob under trap ... EXIT INT TERM on absolute paths. The guard
is a source-text scanner, so no build or dist step participates in any arm.

arm	mutation	expected	measured
A	reword lint.ts's copy, dropping the shared formatter	red on the "renders through ONE formatter" assertion	vitest exit 1 — lint.ts must render its ADR-0087 D2 conversion notices with formatConversionNotice(); 1 failed / 8 passed
B	keep the call, add a verbatim inline copy beside it	red on the "no inline copy" assertion	vitest exit 1 — lint.ts spells the ADR-0087 D2 conversion notice out inline; 1 failed / 8 passed
C	reword the ONE source in format.ts	red on the positive control AND on the value pin	vitest exit 1 — control fires, and the pin reports converted while loading where converted at load was expected; 2 failed / 10 passed
D	unmutated tree	green	vitest exit 0 — 2 files, 12 tests passed

Blob evidence, arm by arm: lint.ts HEAD blob 43ace89d…; mutated to 82ef231d… (A) and
a25e93f7… (B); restored to 43ace89d… with git diff HEAD empty each time. format.ts
HEAD blob 53d51fe1…; mutated to 80839a7e… (C); restored to 53d51fe1…. Final
git status --porcelain -- packages/cli was empty.

Arm A is precisely the check the dispatch asked for — reword one copy and show the guard
redden — and arms B and C exist because A alone would not have told you which assertion
fired.

Verification

At final HEAD 9fc66faf on a clean tree, after merging origin/main (which brought in
PR #15062, the armed sibling the dispatch warned about, plus four others):

• pnpm --filter @objectstack/cli typecheck — exit 0. Both halves: tsc --noEmit over
  src (which is where the new value pin lives, so it is type-checked), and
  check:test-typecheck over tsconfig.test.json, whose verdict line reads
  OK — @objectstack/cli's test layer compiles … 3 file(s) / 28 error(s) / 6 pinned signature(s) held — the pre-existing ledger, unmoved.
• Targeted vitest, 6 files / 53 tests passed: the two new/edited guards, the three
  conversion-notice e2e suites (lint-conversion-notices,
  validate-json-failure-conversions, build-json-failure-conversions — these drive the
  real CLI over a live conversion via tsx, so they are the behavioural proof the output
  did not move), and i18n-check-help-surface-parity from the merged sibling PR.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
  at that HEAD: 42 families (33 by path, 6 by change kind, 5 declared whole-tree).
  40 green. Two are NOT MEASURED and say so themselves: check-test-completeness.mjs
  grades a saved turbo run test log this box cannot produce ("the local reading for this
  gate is NOT MEASURED"), and check-half-states.mjs needs repo-scoped GitHub REST, which
  this container is refused (GET /repos/... returns 403 with no rate-limit headers while
  GET /rate_limit reports 15000 left). Five others first exited 3 on an unbuilt closure
  and went green after a full pnpm build: check:dual-build-cjs-loads, check:i18n,
  check:i18n-coverage, check:type-check-debt (which had also hit a local 300s cap), and
  the two named above stayed 3 for the reasons given.

Declared narrowing. The repo-wide pnpm lint sweep was not run locally; CI owns it and
runs it once regardless. Everything else in the derived union was run.

What this deliberately does not do

ConversionNotice.message and defineStack's warnConversionNotice are untouched. Whether
all of the renderings should descend from one source is a real question with a real cost on
either side, and it is #15095, not this card.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s).

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 22 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 ab47816914fd39709f4e9645370729ce1f4f9826 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 48aac740974ea994794664b7dce221ed4dfb15b1 — the merge of head 9fc66fafafab958e3ae03b0f43bf8989c9b72699 into base ab47816914fd39709f4e9645370729ce1f4f9826, 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 48aac740974ea994794664b7dce221ed4dfb15b1 && git checkout 48aac740974ea994794664b7dce221ed4dfb15b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ab47816914fd39709f4e9645370729ce1f4f9826 9fc66fafafab958e3ae03b0f43bf8989c9b72699 && git checkout -B drift-repro ab47816914fd39709f4e9645370729ce1f4f9826 && git merge --no-ff 9fc66fafafab958e3ae03b0f43bf8989c9b72699
node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826

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

[os-trump]

Fixes#13743

The ADR-0087 D2 conversion notice now has one source in packages/cli, and the parity
guard holds it there. Output is byte-for-byte unchanged.

Which of triage's three options, and why

Option 1 — extract a shared formatter — carrying the smallest useful half of option 2.
Triage required this to be stated rather than defaulted, and the deciding input was a
measurement rather than a preference.

⭐ Option 3's supporting argument is falsified. Its case was that validate.ts folds
its copy into a warnings list --strict judges while the other two print directly, so
"the three call sites are not fully interchangeable, and forcing an extraction may need a
parameter for the difference." The first clause is true and I verified it; the second does
not follow. The asymmetry is entirely in the disposition of the string, never in the
string:

command	what it does with the sentence	the sentence itself
os build (compile.ts)	printWarning(...) behind !flags.json	identical
os lint (lint.ts)	printWarning(...) behind !flags.json	identical
os validate (validate.ts)	warnings.push(...), which --strict then judges	identical

Measured at the branch point d17f352b1b: extracting the template literal from each of the
three lines and hashing it gives one distinct value, 124 bytes, sha256 prefix
7197b905060762c3. A pure formatConversionNotice(notice) therefore serves all three and
costs no parameter for the difference — the extraction option's stated price does not
materialise.

Why not option 2 alone. A comparator locks today's three copies together and detects a
reword only after someone has written it; one source makes the divergence impossible to
write. It is also the disposition this file already reached for the same problem:
printTruncationNotice in the same module carries the note "ONE implementation of that
sentence, deliberately … nine copies of the wording would be nine chances for them to drift
apart." House precedent, not a new idea.

What option 2 still buys, and is kept. Extraction does not stop a copy coming back.
The rule added to validate-build-gate-parity.test.ts is therefore structural rather than
comparative: every authoring command renders through the one formatter, and none spells the
sentence out inline.

Re-derived the count — and the probe returned more than three

The release comment required a bound with a control that could have returned a fourth. It
did. A whole-repo git grep (no pathspec) for the prose fragment converted at load —
tuned to the sentence, not to the three known sites — finds a rendering the card does not
mention, in packages/spec/src/stack.zod.ts:

packages/cli/src/commands/compile.ts:238 the three the card counts
packages/cli/src/commands/lint.ts:580
packages/cli/src/commands/validate.ts:409
packages/spec/src/stack.zod.ts:2310 NOT in the card — defineStack's own face

and reading that seam turns up a fifth prose form on ConversionNotice.message
(packages/spec/src/conversions/apply.ts), which is what the --json payloads publish.

⇒ The card's "three" is correct as a count of the three authoring commands, and wrong as
a bound on the wording. Four renderings, three distinct sentences. The two in
packages/spec are fenced read-only on this card and cannot import the CLI's formatter
anyway (@objectstack/cli depends on @objectstack/spec, not the reverse), so they are
filed separately as #15095 and pinned here as a recorded fact rather than left for the next
reader to discover and "fix" in one command only.

The change

• packages/cli/src/utils/format.ts — formatConversionNotice(notice), a formatter and
  deliberately not a printer.
• compile.ts / lint.ts / validate.ts — render through it; the three inline literals
  are gone (grep -c for the prose in each command source: 0, 0, 0).
• packages/cli/test/validate-build-gate-parity.test.ts — the rule the old guard could not
  see, with a positive control that fails if the formatter stops carrying the sentence.
• packages/cli/src/utils/format.conversion-notice.test.ts — the value pin on the rendered
  sentence, plus the recorded form-1 / form-3 split.
• .changeset/cli-conversion-notice-one-source.md — patch. Measured from this package's
  own files field: @objectstack/cli publishes dist, compiled from the edited src, so
  the diff changes the published package even though it changes nothing an author can
  observe. skip-changeset would have been wrong.

Red-first — four arms, each naming a different assertion

Every mutation was committed-first, proved on disk by blob hash, and restored by blob-hash
equality against the HEAD blob under trap ... EXIT INT TERM on absolute paths. The guard
is a source-text scanner, so no build or dist step participates in any arm.

arm	mutation	expected	measured
A	reword lint.ts's copy, dropping the shared formatter	red on the "renders through ONE formatter" assertion	vitest exit 1 — lint.ts must render its ADR-0087 D2 conversion notices with formatConversionNotice(); 1 failed / 8 passed
B	keep the call, add a verbatim inline copy beside it	red on the "no inline copy" assertion	vitest exit 1 — lint.ts spells the ADR-0087 D2 conversion notice out inline; 1 failed / 8 passed
C	reword the ONE source in format.ts	red on the positive control AND on the value pin	vitest exit 1 — control fires, and the pin reports converted while loading where converted at load was expected; 2 failed / 10 passed
D	unmutated tree	green	vitest exit 0 — 2 files, 12 tests passed

Blob evidence, arm by arm: lint.ts HEAD blob 43ace89d…; mutated to 82ef231d… (A) and
a25e93f7… (B); restored to 43ace89d… with git diff HEAD empty each time. format.ts
HEAD blob 53d51fe1…; mutated to 80839a7e… (C); restored to 53d51fe1…. Final
git status --porcelain -- packages/cli was empty.

Arm A is precisely the check the dispatch asked for — reword one copy and show the guard
redden — and arms B and C exist because A alone would not have told you which assertion
fired.

Verification

At final HEAD 9fc66faf on a clean tree, after merging origin/main (which brought in
PR #15062, the armed sibling the dispatch warned about, plus four others):

• pnpm --filter @objectstack/cli typecheck — exit 0. Both halves: tsc --noEmit over
  src (which is where the new value pin lives, so it is type-checked), and
  check:test-typecheck over tsconfig.test.json, whose verdict line reads
  OK — @objectstack/cli's test layer compiles … 3 file(s) / 28 error(s) / 6 pinned signature(s) held — the pre-existing ledger, unmoved.
• Targeted vitest, 6 files / 53 tests passed: the two new/edited guards, the three
  conversion-notice e2e suites (lint-conversion-notices,
  validate-json-failure-conversions, build-json-failure-conversions — these drive the
  real CLI over a live conversion via tsx, so they are the behavioural proof the output
  did not move), and i18n-check-help-surface-parity from the merged sibling PR.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
  at that HEAD: 42 families (33 by path, 6 by change kind, 5 declared whole-tree).
  40 green. Two are NOT MEASURED and say so themselves: check-test-completeness.mjs
  grades a saved turbo run test log this box cannot produce ("the local reading for this
  gate is NOT MEASURED"), and check-half-states.mjs needs repo-scoped GitHub REST, which
  this container is refused (GET /repos/... returns 403 with no rate-limit headers while
  GET /rate_limit reports 15000 left). Five others first exited 3 on an unbuilt closure
  and went green after a full pnpm build: check:dual-build-cjs-loads, check:i18n,
  check:i18n-coverage, check:type-check-debt (which had also hit a local 300s cap), and
  the two named above stayed 3 for the reasons given.

Declared narrowing. The repo-wide pnpm lint sweep was not run locally; CI owns it and
runs it once regardless. Everything else in the derived union was run.

What this deliberately does not do

ConversionNotice.message and defineStack's warnConversionNotice are untouched. Whether
all of the renderings should descend from one source is a real question with a real cost on
either side, and it is #15095, not this card.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s).

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 22 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 ab47816914fd39709f4e9645370729ce1f4f9826 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 48aac740974ea994794664b7dce221ed4dfb15b1 — the merge of head 9fc66fafafab958e3ae03b0f43bf8989c9b72699 into base ab47816914fd39709f4e9645370729ce1f4f9826, 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 48aac740974ea994794664b7dce221ed4dfb15b1 && git checkout 48aac740974ea994794664b7dce221ed4dfb15b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ab47816914fd39709f4e9645370729ce1f4f9826 9fc66fafafab958e3ae03b0f43bf8989c9b72699 && git checkout -B drift-repro ab47816914fd39709f4e9645370729ce1f4f9826 && git merge --no-ff 9fc66fafafab958e3ae03b0f43bf8989c9b72699
node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826

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

[os-trump]

Fixes#13743

The ADR-0087 D2 conversion notice now has one source in packages/cli, and the parity
guard holds it there. Output is byte-for-byte unchanged.

Which of triage's three options, and why

Option 1 — extract a shared formatter — carrying the smallest useful half of option 2.
Triage required this to be stated rather than defaulted, and the deciding input was a
measurement rather than a preference.

⭐ Option 3's supporting argument is falsified. Its case was that validate.ts folds
its copy into a warnings list --strict judges while the other two print directly, so
"the three call sites are not fully interchangeable, and forcing an extraction may need a
parameter for the difference." The first clause is true and I verified it; the second does
not follow. The asymmetry is entirely in the disposition of the string, never in the
string:

command	what it does with the sentence	the sentence itself
os build (compile.ts)	printWarning(...) behind !flags.json	identical
os lint (lint.ts)	printWarning(...) behind !flags.json	identical
os validate (validate.ts)	warnings.push(...), which --strict then judges	identical

Measured at the branch point d17f352b1b: extracting the template literal from each of the
three lines and hashing it gives one distinct value, 124 bytes, sha256 prefix
7197b905060762c3. A pure formatConversionNotice(notice) therefore serves all three and
costs no parameter for the difference — the extraction option's stated price does not
materialise.

Why not option 2 alone. A comparator locks today's three copies together and detects a
reword only after someone has written it; one source makes the divergence impossible to
write. It is also the disposition this file already reached for the same problem:
printTruncationNotice in the same module carries the note "ONE implementation of that
sentence, deliberately … nine copies of the wording would be nine chances for them to drift
apart." House precedent, not a new idea.

What option 2 still buys, and is kept. Extraction does not stop a copy coming back.
The rule added to validate-build-gate-parity.test.ts is therefore structural rather than
comparative: every authoring command renders through the one formatter, and none spells the
sentence out inline.

Re-derived the count — and the probe returned more than three

The release comment required a bound with a control that could have returned a fourth. It
did. A whole-repo git grep (no pathspec) for the prose fragment converted at load —
tuned to the sentence, not to the three known sites — finds a rendering the card does not
mention, in packages/spec/src/stack.zod.ts:

packages/cli/src/commands/compile.ts:238 the three the card counts
packages/cli/src/commands/lint.ts:580
packages/cli/src/commands/validate.ts:409
packages/spec/src/stack.zod.ts:2310 NOT in the card — defineStack's own face

and reading that seam turns up a fifth prose form on ConversionNotice.message
(packages/spec/src/conversions/apply.ts), which is what the --json payloads publish.

⇒ The card's "three" is correct as a count of the three authoring commands, and wrong as
a bound on the wording. Four renderings, three distinct sentences. The two in
packages/spec are fenced read-only on this card and cannot import the CLI's formatter
anyway (@objectstack/cli depends on @objectstack/spec, not the reverse), so they are
filed separately as #15095 and pinned here as a recorded fact rather than left for the next
reader to discover and "fix" in one command only.

The change

• packages/cli/src/utils/format.ts — formatConversionNotice(notice), a formatter and
  deliberately not a printer.
• compile.ts / lint.ts / validate.ts — render through it; the three inline literals
  are gone (grep -c for the prose in each command source: 0, 0, 0).
• packages/cli/test/validate-build-gate-parity.test.ts — the rule the old guard could not
  see, with a positive control that fails if the formatter stops carrying the sentence.
• packages/cli/src/utils/format.conversion-notice.test.ts — the value pin on the rendered
  sentence, plus the recorded form-1 / form-3 split.
• .changeset/cli-conversion-notice-one-source.md — patch. Measured from this package's
  own files field: @objectstack/cli publishes dist, compiled from the edited src, so
  the diff changes the published package even though it changes nothing an author can
  observe. skip-changeset would have been wrong.

Red-first — four arms, each naming a different assertion

Every mutation was committed-first, proved on disk by blob hash, and restored by blob-hash
equality against the HEAD blob under trap ... EXIT INT TERM on absolute paths. The guard
is a source-text scanner, so no build or dist step participates in any arm.

arm	mutation	expected	measured
A	reword lint.ts's copy, dropping the shared formatter	red on the "renders through ONE formatter" assertion	vitest exit 1 — lint.ts must render its ADR-0087 D2 conversion notices with formatConversionNotice(); 1 failed / 8 passed
B	keep the call, add a verbatim inline copy beside it	red on the "no inline copy" assertion	vitest exit 1 — lint.ts spells the ADR-0087 D2 conversion notice out inline; 1 failed / 8 passed
C	reword the ONE source in format.ts	red on the positive control AND on the value pin	vitest exit 1 — control fires, and the pin reports converted while loading where converted at load was expected; 2 failed / 10 passed
D	unmutated tree	green	vitest exit 0 — 2 files, 12 tests passed

Blob evidence, arm by arm: lint.ts HEAD blob 43ace89d…; mutated to 82ef231d… (A) and
a25e93f7… (B); restored to 43ace89d… with git diff HEAD empty each time. format.ts
HEAD blob 53d51fe1…; mutated to 80839a7e… (C); restored to 53d51fe1…. Final
git status --porcelain -- packages/cli was empty.

Arm A is precisely the check the dispatch asked for — reword one copy and show the guard
redden — and arms B and C exist because A alone would not have told you which assertion
fired.

Verification

At final HEAD 9fc66faf on a clean tree, after merging origin/main (which brought in
PR #15062, the armed sibling the dispatch warned about, plus four others):

• pnpm --filter @objectstack/cli typecheck — exit 0. Both halves: tsc --noEmit over
  src (which is where the new value pin lives, so it is type-checked), and
  check:test-typecheck over tsconfig.test.json, whose verdict line reads
  OK — @objectstack/cli's test layer compiles … 3 file(s) / 28 error(s) / 6 pinned signature(s) held — the pre-existing ledger, unmoved.
• Targeted vitest, 6 files / 53 tests passed: the two new/edited guards, the three
  conversion-notice e2e suites (lint-conversion-notices,
  validate-json-failure-conversions, build-json-failure-conversions — these drive the
  real CLI over a live conversion via tsx, so they are the behavioural proof the output
  did not move), and i18n-check-help-surface-parity from the merged sibling PR.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
  at that HEAD: 42 families (33 by path, 6 by change kind, 5 declared whole-tree).
  40 green. Two are NOT MEASURED and say so themselves: check-test-completeness.mjs
  grades a saved turbo run test log this box cannot produce ("the local reading for this
  gate is NOT MEASURED"), and check-half-states.mjs needs repo-scoped GitHub REST, which
  this container is refused (GET /repos/... returns 403 with no rate-limit headers while
  GET /rate_limit reports 15000 left). Five others first exited 3 on an unbuilt closure
  and went green after a full pnpm build: check:dual-build-cjs-loads, check:i18n,
  check:i18n-coverage, check:type-check-debt (which had also hit a local 300s cap), and
  the two named above stayed 3 for the reasons given.

Declared narrowing. The repo-wide pnpm lint sweep was not run locally; CI owns it and
runs it once regardless. Everything else in the derived union was run.

What this deliberately does not do

ConversionNotice.message and defineStack's warnConversionNotice are untouched. Whether
all of the renderings should descend from one source is a real question with a real cost on
either side, and it is #15095, not this card.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s).

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 22 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 ab47816914fd39709f4e9645370729ce1f4f9826 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 48aac740974ea994794664b7dce221ed4dfb15b1 — the merge of head 9fc66fafafab958e3ae03b0f43bf8989c9b72699 into base ab47816914fd39709f4e9645370729ce1f4f9826, 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 48aac740974ea994794664b7dce221ed4dfb15b1 && git checkout 48aac740974ea994794664b7dce221ed4dfb15b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ab47816914fd39709f4e9645370729ce1f4f9826 9fc66fafafab958e3ae03b0f43bf8989c9b72699 && git checkout -B drift-repro ab47816914fd39709f4e9645370729ce1f4f9826 && git merge --no-ff 9fc66fafafab958e3ae03b0f43bf8989c9b72699
node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826

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

[os-trump]

Fixes#13743

The ADR-0087 D2 conversion notice now has one source in packages/cli, and the parity
guard holds it there. Output is byte-for-byte unchanged.

Which of triage's three options, and why

Option 1 — extract a shared formatter — carrying the smallest useful half of option 2.
Triage required this to be stated rather than defaulted, and the deciding input was a
measurement rather than a preference.

⭐ Option 3's supporting argument is falsified. Its case was that validate.ts folds
its copy into a warnings list --strict judges while the other two print directly, so
"the three call sites are not fully interchangeable, and forcing an extraction may need a
parameter for the difference." The first clause is true and I verified it; the second does
not follow. The asymmetry is entirely in the disposition of the string, never in the
string:

command	what it does with the sentence	the sentence itself
os build (compile.ts)	printWarning(...) behind !flags.json	identical
os lint (lint.ts)	printWarning(...) behind !flags.json	identical
os validate (validate.ts)	warnings.push(...), which --strict then judges	identical

Measured at the branch point d17f352b1b: extracting the template literal from each of the
three lines and hashing it gives one distinct value, 124 bytes, sha256 prefix
7197b905060762c3. A pure formatConversionNotice(notice) therefore serves all three and
costs no parameter for the difference — the extraction option's stated price does not
materialise.

Why not option 2 alone. A comparator locks today's three copies together and detects a
reword only after someone has written it; one source makes the divergence impossible to
write. It is also the disposition this file already reached for the same problem:
printTruncationNotice in the same module carries the note "ONE implementation of that
sentence, deliberately … nine copies of the wording would be nine chances for them to drift
apart." House precedent, not a new idea.

What option 2 still buys, and is kept. Extraction does not stop a copy coming back.
The rule added to validate-build-gate-parity.test.ts is therefore structural rather than
comparative: every authoring command renders through the one formatter, and none spells the
sentence out inline.

Re-derived the count — and the probe returned more than three

The release comment required a bound with a control that could have returned a fourth. It
did. A whole-repo git grep (no pathspec) for the prose fragment converted at load —
tuned to the sentence, not to the three known sites — finds a rendering the card does not
mention, in packages/spec/src/stack.zod.ts:

packages/cli/src/commands/compile.ts:238 the three the card counts
packages/cli/src/commands/lint.ts:580
packages/cli/src/commands/validate.ts:409
packages/spec/src/stack.zod.ts:2310 NOT in the card — defineStack's own face

and reading that seam turns up a fifth prose form on ConversionNotice.message
(packages/spec/src/conversions/apply.ts), which is what the --json payloads publish.

⇒ The card's "three" is correct as a count of the three authoring commands, and wrong as
a bound on the wording. Four renderings, three distinct sentences. The two in
packages/spec are fenced read-only on this card and cannot import the CLI's formatter
anyway (@objectstack/cli depends on @objectstack/spec, not the reverse), so they are
filed separately as #15095 and pinned here as a recorded fact rather than left for the next
reader to discover and "fix" in one command only.

The change

• packages/cli/src/utils/format.ts — formatConversionNotice(notice), a formatter and
  deliberately not a printer.
• compile.ts / lint.ts / validate.ts — render through it; the three inline literals
  are gone (grep -c for the prose in each command source: 0, 0, 0).
• packages/cli/test/validate-build-gate-parity.test.ts — the rule the old guard could not
  see, with a positive control that fails if the formatter stops carrying the sentence.
• packages/cli/src/utils/format.conversion-notice.test.ts — the value pin on the rendered
  sentence, plus the recorded form-1 / form-3 split.
• .changeset/cli-conversion-notice-one-source.md — patch. Measured from this package's
  own files field: @objectstack/cli publishes dist, compiled from the edited src, so
  the diff changes the published package even though it changes nothing an author can
  observe. skip-changeset would have been wrong.

Red-first — four arms, each naming a different assertion

Every mutation was committed-first, proved on disk by blob hash, and restored by blob-hash
equality against the HEAD blob under trap ... EXIT INT TERM on absolute paths. The guard
is a source-text scanner, so no build or dist step participates in any arm.

arm	mutation	expected	measured
A	reword lint.ts's copy, dropping the shared formatter	red on the "renders through ONE formatter" assertion	vitest exit 1 — lint.ts must render its ADR-0087 D2 conversion notices with formatConversionNotice(); 1 failed / 8 passed
B	keep the call, add a verbatim inline copy beside it	red on the "no inline copy" assertion	vitest exit 1 — lint.ts spells the ADR-0087 D2 conversion notice out inline; 1 failed / 8 passed
C	reword the ONE source in format.ts	red on the positive control AND on the value pin	vitest exit 1 — control fires, and the pin reports converted while loading where converted at load was expected; 2 failed / 10 passed
D	unmutated tree	green	vitest exit 0 — 2 files, 12 tests passed

Blob evidence, arm by arm: lint.ts HEAD blob 43ace89d…; mutated to 82ef231d… (A) and
a25e93f7… (B); restored to 43ace89d… with git diff HEAD empty each time. format.ts
HEAD blob 53d51fe1…; mutated to 80839a7e… (C); restored to 53d51fe1…. Final
git status --porcelain -- packages/cli was empty.

Arm A is precisely the check the dispatch asked for — reword one copy and show the guard
redden — and arms B and C exist because A alone would not have told you which assertion
fired.

Verification

At final HEAD 9fc66faf on a clean tree, after merging origin/main (which brought in
PR #15062, the armed sibling the dispatch warned about, plus four others):

• pnpm --filter @objectstack/cli typecheck — exit 0. Both halves: tsc --noEmit over
  src (which is where the new value pin lives, so it is type-checked), and
  check:test-typecheck over tsconfig.test.json, whose verdict line reads
  OK — @objectstack/cli's test layer compiles … 3 file(s) / 28 error(s) / 6 pinned signature(s) held — the pre-existing ledger, unmoved.
• Targeted vitest, 6 files / 53 tests passed: the two new/edited guards, the three
  conversion-notice e2e suites (lint-conversion-notices,
  validate-json-failure-conversions, build-json-failure-conversions — these drive the
  real CLI over a live conversion via tsx, so they are the behavioural proof the output
  did not move), and i18n-check-help-surface-parity from the merged sibling PR.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
  at that HEAD: 42 families (33 by path, 6 by change kind, 5 declared whole-tree).
  40 green. Two are NOT MEASURED and say so themselves: check-test-completeness.mjs
  grades a saved turbo run test log this box cannot produce ("the local reading for this
  gate is NOT MEASURED"), and check-half-states.mjs needs repo-scoped GitHub REST, which
  this container is refused (GET /repos/... returns 403 with no rate-limit headers while
  GET /rate_limit reports 15000 left). Five others first exited 3 on an unbuilt closure
  and went green after a full pnpm build: check:dual-build-cjs-loads, check:i18n,
  check:i18n-coverage, check:type-check-debt (which had also hit a local 300s cap), and
  the two named above stayed 3 for the reasons given.

Declared narrowing. The repo-wide pnpm lint sweep was not run locally; CI owns it and
runs it once regardless. Everything else in the derived union was run.

What this deliberately does not do

ConversionNotice.message and defineStack's warnConversionNotice are untouched. Whether
all of the renderings should descend from one source is a real question with a real cost on
either side, and it is #15095, not this card.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s).

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 22 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 ab47816914fd39709f4e9645370729ce1f4f9826 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 48aac740974ea994794664b7dce221ed4dfb15b1 — the merge of head 9fc66fafafab958e3ae03b0f43bf8989c9b72699 into base ab47816914fd39709f4e9645370729ce1f4f9826, 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 48aac740974ea994794664b7dce221ed4dfb15b1 && git checkout 48aac740974ea994794664b7dce221ed4dfb15b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ab47816914fd39709f4e9645370729ce1f4f9826 9fc66fafafab958e3ae03b0f43bf8989c9b72699 && git checkout -B drift-repro ab47816914fd39709f4e9645370729ce1f4f9826 && git merge --no-ff 9fc66fafafab958e3ae03b0f43bf8989c9b72699
node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826

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

[os-trump]

Fixes#13743

The ADR-0087 D2 conversion notice now has one source in packages/cli, and the parity
guard holds it there. Output is byte-for-byte unchanged.

Which of triage's three options, and why

Option 1 — extract a shared formatter — carrying the smallest useful half of option 2.
Triage required this to be stated rather than defaulted, and the deciding input was a
measurement rather than a preference.

⭐ Option 3's supporting argument is falsified. Its case was that validate.ts folds
its copy into a warnings list --strict judges while the other two print directly, so
"the three call sites are not fully interchangeable, and forcing an extraction may need a
parameter for the difference." The first clause is true and I verified it; the second does
not follow. The asymmetry is entirely in the disposition of the string, never in the
string:

command	what it does with the sentence	the sentence itself
os build (compile.ts)	printWarning(...) behind !flags.json	identical
os lint (lint.ts)	printWarning(...) behind !flags.json	identical
os validate (validate.ts)	warnings.push(...), which --strict then judges	identical

Measured at the branch point d17f352b1b: extracting the template literal from each of the
three lines and hashing it gives one distinct value, 124 bytes, sha256 prefix
7197b905060762c3. A pure formatConversionNotice(notice) therefore serves all three and
costs no parameter for the difference — the extraction option's stated price does not
materialise.

Why not option 2 alone. A comparator locks today's three copies together and detects a
reword only after someone has written it; one source makes the divergence impossible to
write. It is also the disposition this file already reached for the same problem:
printTruncationNotice in the same module carries the note "ONE implementation of that
sentence, deliberately … nine copies of the wording would be nine chances for them to drift
apart." House precedent, not a new idea.

What option 2 still buys, and is kept. Extraction does not stop a copy coming back.
The rule added to validate-build-gate-parity.test.ts is therefore structural rather than
comparative: every authoring command renders through the one formatter, and none spells the
sentence out inline.

Re-derived the count — and the probe returned more than three

The release comment required a bound with a control that could have returned a fourth. It
did. A whole-repo git grep (no pathspec) for the prose fragment converted at load —
tuned to the sentence, not to the three known sites — finds a rendering the card does not
mention, in packages/spec/src/stack.zod.ts:

packages/cli/src/commands/compile.ts:238 the three the card counts
packages/cli/src/commands/lint.ts:580
packages/cli/src/commands/validate.ts:409
packages/spec/src/stack.zod.ts:2310 NOT in the card — defineStack's own face

and reading that seam turns up a fifth prose form on ConversionNotice.message
(packages/spec/src/conversions/apply.ts), which is what the --json payloads publish.

⇒ The card's "three" is correct as a count of the three authoring commands, and wrong as
a bound on the wording. Four renderings, three distinct sentences. The two in
packages/spec are fenced read-only on this card and cannot import the CLI's formatter
anyway (@objectstack/cli depends on @objectstack/spec, not the reverse), so they are
filed separately as #15095 and pinned here as a recorded fact rather than left for the next
reader to discover and "fix" in one command only.

The change

• packages/cli/src/utils/format.ts — formatConversionNotice(notice), a formatter and
  deliberately not a printer.
• compile.ts / lint.ts / validate.ts — render through it; the three inline literals
  are gone (grep -c for the prose in each command source: 0, 0, 0).
• packages/cli/test/validate-build-gate-parity.test.ts — the rule the old guard could not
  see, with a positive control that fails if the formatter stops carrying the sentence.
• packages/cli/src/utils/format.conversion-notice.test.ts — the value pin on the rendered
  sentence, plus the recorded form-1 / form-3 split.
• .changeset/cli-conversion-notice-one-source.md — patch. Measured from this package's
  own files field: @objectstack/cli publishes dist, compiled from the edited src, so
  the diff changes the published package even though it changes nothing an author can
  observe. skip-changeset would have been wrong.

Red-first — four arms, each naming a different assertion

Every mutation was committed-first, proved on disk by blob hash, and restored by blob-hash
equality against the HEAD blob under trap ... EXIT INT TERM on absolute paths. The guard
is a source-text scanner, so no build or dist step participates in any arm.

arm	mutation	expected	measured
A	reword lint.ts's copy, dropping the shared formatter	red on the "renders through ONE formatter" assertion	vitest exit 1 — lint.ts must render its ADR-0087 D2 conversion notices with formatConversionNotice(); 1 failed / 8 passed
B	keep the call, add a verbatim inline copy beside it	red on the "no inline copy" assertion	vitest exit 1 — lint.ts spells the ADR-0087 D2 conversion notice out inline; 1 failed / 8 passed
C	reword the ONE source in format.ts	red on the positive control AND on the value pin	vitest exit 1 — control fires, and the pin reports converted while loading where converted at load was expected; 2 failed / 10 passed
D	unmutated tree	green	vitest exit 0 — 2 files, 12 tests passed

Blob evidence, arm by arm: lint.ts HEAD blob 43ace89d…; mutated to 82ef231d… (A) and
a25e93f7… (B); restored to 43ace89d… with git diff HEAD empty each time. format.ts
HEAD blob 53d51fe1…; mutated to 80839a7e… (C); restored to 53d51fe1…. Final
git status --porcelain -- packages/cli was empty.

Arm A is precisely the check the dispatch asked for — reword one copy and show the guard
redden — and arms B and C exist because A alone would not have told you which assertion
fired.

Verification

At final HEAD 9fc66faf on a clean tree, after merging origin/main (which brought in
PR #15062, the armed sibling the dispatch warned about, plus four others):

• pnpm --filter @objectstack/cli typecheck — exit 0. Both halves: tsc --noEmit over
  src (which is where the new value pin lives, so it is type-checked), and
  check:test-typecheck over tsconfig.test.json, whose verdict line reads
  OK — @objectstack/cli's test layer compiles … 3 file(s) / 28 error(s) / 6 pinned signature(s) held — the pre-existing ledger, unmoved.
• Targeted vitest, 6 files / 53 tests passed: the two new/edited guards, the three
  conversion-notice e2e suites (lint-conversion-notices,
  validate-json-failure-conversions, build-json-failure-conversions — these drive the
  real CLI over a live conversion via tsx, so they are the behavioural proof the output
  did not move), and i18n-check-help-surface-parity from the merged sibling PR.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
  at that HEAD: 42 families (33 by path, 6 by change kind, 5 declared whole-tree).
  40 green. Two are NOT MEASURED and say so themselves: check-test-completeness.mjs
  grades a saved turbo run test log this box cannot produce ("the local reading for this
  gate is NOT MEASURED"), and check-half-states.mjs needs repo-scoped GitHub REST, which
  this container is refused (GET /repos/... returns 403 with no rate-limit headers while
  GET /rate_limit reports 15000 left). Five others first exited 3 on an unbuilt closure
  and went green after a full pnpm build: check:dual-build-cjs-loads, check:i18n,
  check:i18n-coverage, check:type-check-debt (which had also hit a local 300s cap), and
  the two named above stayed 3 for the reasons given.

Declared narrowing. The repo-wide pnpm lint sweep was not run locally; CI owns it and
runs it once regardless. Everything else in the derived union was run.

What this deliberately does not do

ConversionNotice.message and defineStack's warnConversionNotice are untouched. Whether
all of the renderings should descend from one source is a real question with a real cost on
either side, and it is #15095, not this card.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s).

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 22 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 ab47816914fd39709f4e9645370729ce1f4f9826 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 48aac740974ea994794664b7dce221ed4dfb15b1 — the merge of head 9fc66fafafab958e3ae03b0f43bf8989c9b72699 into base ab47816914fd39709f4e9645370729ce1f4f9826, 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 48aac740974ea994794664b7dce221ed4dfb15b1 && git checkout 48aac740974ea994794664b7dce221ed4dfb15b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ab47816914fd39709f4e9645370729ce1f4f9826 9fc66fafafab958e3ae03b0f43bf8989c9b72699 && git checkout -B drift-repro ab47816914fd39709f4e9645370729ce1f4f9826 && git merge --no-ff 9fc66fafafab958e3ae03b0f43bf8989c9b72699
node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826

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

[os-trump]

Fixes#13743

The ADR-0087 D2 conversion notice now has one source in packages/cli, and the parity
guard holds it there. Output is byte-for-byte unchanged.

Which of triage's three options, and why

Option 1 — extract a shared formatter — carrying the smallest useful half of option 2.
Triage required this to be stated rather than defaulted, and the deciding input was a
measurement rather than a preference.

⭐ Option 3's supporting argument is falsified. Its case was that validate.ts folds
its copy into a warnings list --strict judges while the other two print directly, so
"the three call sites are not fully interchangeable, and forcing an extraction may need a
parameter for the difference." The first clause is true and I verified it; the second does
not follow. The asymmetry is entirely in the disposition of the string, never in the
string:

command	what it does with the sentence	the sentence itself
os build (compile.ts)	printWarning(...) behind !flags.json	identical
os lint (lint.ts)	printWarning(...) behind !flags.json	identical
os validate (validate.ts)	warnings.push(...), which --strict then judges	identical

Measured at the branch point d17f352b1b: extracting the template literal from each of the
three lines and hashing it gives one distinct value, 124 bytes, sha256 prefix
7197b905060762c3. A pure formatConversionNotice(notice) therefore serves all three and
costs no parameter for the difference — the extraction option's stated price does not
materialise.

Why not option 2 alone. A comparator locks today's three copies together and detects a
reword only after someone has written it; one source makes the divergence impossible to
write. It is also the disposition this file already reached for the same problem:
printTruncationNotice in the same module carries the note "ONE implementation of that
sentence, deliberately … nine copies of the wording would be nine chances for them to drift
apart." House precedent, not a new idea.

What option 2 still buys, and is kept. Extraction does not stop a copy coming back.
The rule added to validate-build-gate-parity.test.ts is therefore structural rather than
comparative: every authoring command renders through the one formatter, and none spells the
sentence out inline.

Re-derived the count — and the probe returned more than three

The release comment required a bound with a control that could have returned a fourth. It
did. A whole-repo git grep (no pathspec) for the prose fragment converted at load —
tuned to the sentence, not to the three known sites — finds a rendering the card does not
mention, in packages/spec/src/stack.zod.ts:

packages/cli/src/commands/compile.ts:238 the three the card counts
packages/cli/src/commands/lint.ts:580
packages/cli/src/commands/validate.ts:409
packages/spec/src/stack.zod.ts:2310 NOT in the card — defineStack's own face

and reading that seam turns up a fifth prose form on ConversionNotice.message
(packages/spec/src/conversions/apply.ts), which is what the --json payloads publish.

⇒ The card's "three" is correct as a count of the three authoring commands, and wrong as
a bound on the wording. Four renderings, three distinct sentences. The two in
packages/spec are fenced read-only on this card and cannot import the CLI's formatter
anyway (@objectstack/cli depends on @objectstack/spec, not the reverse), so they are
filed separately as #15095 and pinned here as a recorded fact rather than left for the next
reader to discover and "fix" in one command only.

The change

• packages/cli/src/utils/format.ts — formatConversionNotice(notice), a formatter and
  deliberately not a printer.
• compile.ts / lint.ts / validate.ts — render through it; the three inline literals
  are gone (grep -c for the prose in each command source: 0, 0, 0).
• packages/cli/test/validate-build-gate-parity.test.ts — the rule the old guard could not
  see, with a positive control that fails if the formatter stops carrying the sentence.
• packages/cli/src/utils/format.conversion-notice.test.ts — the value pin on the rendered
  sentence, plus the recorded form-1 / form-3 split.
• .changeset/cli-conversion-notice-one-source.md — patch. Measured from this package's
  own files field: @objectstack/cli publishes dist, compiled from the edited src, so
  the diff changes the published package even though it changes nothing an author can
  observe. skip-changeset would have been wrong.

Red-first — four arms, each naming a different assertion

Every mutation was committed-first, proved on disk by blob hash, and restored by blob-hash
equality against the HEAD blob under trap ... EXIT INT TERM on absolute paths. The guard
is a source-text scanner, so no build or dist step participates in any arm.

arm	mutation	expected	measured
A	reword lint.ts's copy, dropping the shared formatter	red on the "renders through ONE formatter" assertion	vitest exit 1 — lint.ts must render its ADR-0087 D2 conversion notices with formatConversionNotice(); 1 failed / 8 passed
B	keep the call, add a verbatim inline copy beside it	red on the "no inline copy" assertion	vitest exit 1 — lint.ts spells the ADR-0087 D2 conversion notice out inline; 1 failed / 8 passed
C	reword the ONE source in format.ts	red on the positive control AND on the value pin	vitest exit 1 — control fires, and the pin reports converted while loading where converted at load was expected; 2 failed / 10 passed
D	unmutated tree	green	vitest exit 0 — 2 files, 12 tests passed

Blob evidence, arm by arm: lint.ts HEAD blob 43ace89d…; mutated to 82ef231d… (A) and
a25e93f7… (B); restored to 43ace89d… with git diff HEAD empty each time. format.ts
HEAD blob 53d51fe1…; mutated to 80839a7e… (C); restored to 53d51fe1…. Final
git status --porcelain -- packages/cli was empty.

Arm A is precisely the check the dispatch asked for — reword one copy and show the guard
redden — and arms B and C exist because A alone would not have told you which assertion
fired.

Verification

At final HEAD 9fc66faf on a clean tree, after merging origin/main (which brought in
PR #15062, the armed sibling the dispatch warned about, plus four others):

• pnpm --filter @objectstack/cli typecheck — exit 0. Both halves: tsc --noEmit over
  src (which is where the new value pin lives, so it is type-checked), and
  check:test-typecheck over tsconfig.test.json, whose verdict line reads
  OK — @objectstack/cli's test layer compiles … 3 file(s) / 28 error(s) / 6 pinned signature(s) held — the pre-existing ledger, unmoved.
• Targeted vitest, 6 files / 53 tests passed: the two new/edited guards, the three
  conversion-notice e2e suites (lint-conversion-notices,
  validate-json-failure-conversions, build-json-failure-conversions — these drive the
  real CLI over a live conversion via tsx, so they are the behavioural proof the output
  did not move), and i18n-check-help-surface-parity from the merged sibling PR.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
  at that HEAD: 42 families (33 by path, 6 by change kind, 5 declared whole-tree).
  40 green. Two are NOT MEASURED and say so themselves: check-test-completeness.mjs
  grades a saved turbo run test log this box cannot produce ("the local reading for this
  gate is NOT MEASURED"), and check-half-states.mjs needs repo-scoped GitHub REST, which
  this container is refused (GET /repos/... returns 403 with no rate-limit headers while
  GET /rate_limit reports 15000 left). Five others first exited 3 on an unbuilt closure
  and went green after a full pnpm build: check:dual-build-cjs-loads, check:i18n,
  check:i18n-coverage, check:type-check-debt (which had also hit a local 300s cap), and
  the two named above stayed 3 for the reasons given.

Declared narrowing. The repo-wide pnpm lint sweep was not run locally; CI owns it and
runs it once regardless. Everything else in the derived union was run.

What this deliberately does not do

ConversionNotice.message and defineStack's warnConversionNotice are untouched. Whether
all of the renderings should descend from one source is a real question with a real cost on
either side, and it is #15095, not this card.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s).

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 22 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 ab47816914fd39709f4e9645370729ce1f4f9826 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 48aac740974ea994794664b7dce221ed4dfb15b1 — the merge of head 9fc66fafafab958e3ae03b0f43bf8989c9b72699 into base ab47816914fd39709f4e9645370729ce1f4f9826, 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 48aac740974ea994794664b7dce221ed4dfb15b1 && git checkout 48aac740974ea994794664b7dce221ed4dfb15b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ab47816914fd39709f4e9645370729ce1f4f9826 9fc66fafafab958e3ae03b0f43bf8989c9b72699 && git checkout -B drift-repro ab47816914fd39709f4e9645370729ce1f4f9826 && git merge --no-ff 9fc66fafafab958e3ae03b0f43bf8989c9b72699
node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826

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

[os-trump]

Fixes#13743

The ADR-0087 D2 conversion notice now has one source in packages/cli, and the parity
guard holds it there. Output is byte-for-byte unchanged.

Which of triage's three options, and why

Option 1 — extract a shared formatter — carrying the smallest useful half of option 2.
Triage required this to be stated rather than defaulted, and the deciding input was a
measurement rather than a preference.

⭐ Option 3's supporting argument is falsified. Its case was that validate.ts folds
its copy into a warnings list --strict judges while the other two print directly, so
"the three call sites are not fully interchangeable, and forcing an extraction may need a
parameter for the difference." The first clause is true and I verified it; the second does
not follow. The asymmetry is entirely in the disposition of the string, never in the
string:

command	what it does with the sentence	the sentence itself
os build (compile.ts)	printWarning(...) behind !flags.json	identical
os lint (lint.ts)	printWarning(...) behind !flags.json	identical
os validate (validate.ts)	warnings.push(...), which --strict then judges	identical

Measured at the branch point d17f352b1b: extracting the template literal from each of the
three lines and hashing it gives one distinct value, 124 bytes, sha256 prefix
7197b905060762c3. A pure formatConversionNotice(notice) therefore serves all three and
costs no parameter for the difference — the extraction option's stated price does not
materialise.

Why not option 2 alone. A comparator locks today's three copies together and detects a
reword only after someone has written it; one source makes the divergence impossible to
write. It is also the disposition this file already reached for the same problem:
printTruncationNotice in the same module carries the note "ONE implementation of that
sentence, deliberately … nine copies of the wording would be nine chances for them to drift
apart." House precedent, not a new idea.

What option 2 still buys, and is kept. Extraction does not stop a copy coming back.
The rule added to validate-build-gate-parity.test.ts is therefore structural rather than
comparative: every authoring command renders through the one formatter, and none spells the
sentence out inline.

Re-derived the count — and the probe returned more than three

The release comment required a bound with a control that could have returned a fourth. It
did. A whole-repo git grep (no pathspec) for the prose fragment converted at load —
tuned to the sentence, not to the three known sites — finds a rendering the card does not
mention, in packages/spec/src/stack.zod.ts:

packages/cli/src/commands/compile.ts:238 the three the card counts
packages/cli/src/commands/lint.ts:580
packages/cli/src/commands/validate.ts:409
packages/spec/src/stack.zod.ts:2310 NOT in the card — defineStack's own face

and reading that seam turns up a fifth prose form on ConversionNotice.message
(packages/spec/src/conversions/apply.ts), which is what the --json payloads publish.

⇒ The card's "three" is correct as a count of the three authoring commands, and wrong as
a bound on the wording. Four renderings, three distinct sentences. The two in
packages/spec are fenced read-only on this card and cannot import the CLI's formatter
anyway (@objectstack/cli depends on @objectstack/spec, not the reverse), so they are
filed separately as #15095 and pinned here as a recorded fact rather than left for the next
reader to discover and "fix" in one command only.

The change

• packages/cli/src/utils/format.ts — formatConversionNotice(notice), a formatter and
  deliberately not a printer.
• compile.ts / lint.ts / validate.ts — render through it; the three inline literals
  are gone (grep -c for the prose in each command source: 0, 0, 0).
• packages/cli/test/validate-build-gate-parity.test.ts — the rule the old guard could not
  see, with a positive control that fails if the formatter stops carrying the sentence.
• packages/cli/src/utils/format.conversion-notice.test.ts — the value pin on the rendered
  sentence, plus the recorded form-1 / form-3 split.
• .changeset/cli-conversion-notice-one-source.md — patch. Measured from this package's
  own files field: @objectstack/cli publishes dist, compiled from the edited src, so
  the diff changes the published package even though it changes nothing an author can
  observe. skip-changeset would have been wrong.

Red-first — four arms, each naming a different assertion

Every mutation was committed-first, proved on disk by blob hash, and restored by blob-hash
equality against the HEAD blob under trap ... EXIT INT TERM on absolute paths. The guard
is a source-text scanner, so no build or dist step participates in any arm.

arm	mutation	expected	measured
A	reword lint.ts's copy, dropping the shared formatter	red on the "renders through ONE formatter" assertion	vitest exit 1 — lint.ts must render its ADR-0087 D2 conversion notices with formatConversionNotice(); 1 failed / 8 passed
B	keep the call, add a verbatim inline copy beside it	red on the "no inline copy" assertion	vitest exit 1 — lint.ts spells the ADR-0087 D2 conversion notice out inline; 1 failed / 8 passed
C	reword the ONE source in format.ts	red on the positive control AND on the value pin	vitest exit 1 — control fires, and the pin reports converted while loading where converted at load was expected; 2 failed / 10 passed
D	unmutated tree	green	vitest exit 0 — 2 files, 12 tests passed

Blob evidence, arm by arm: lint.ts HEAD blob 43ace89d…; mutated to 82ef231d… (A) and
a25e93f7… (B); restored to 43ace89d… with git diff HEAD empty each time. format.ts
HEAD blob 53d51fe1…; mutated to 80839a7e… (C); restored to 53d51fe1…. Final
git status --porcelain -- packages/cli was empty.

Arm A is precisely the check the dispatch asked for — reword one copy and show the guard
redden — and arms B and C exist because A alone would not have told you which assertion
fired.

Verification

At final HEAD 9fc66faf on a clean tree, after merging origin/main (which brought in
PR #15062, the armed sibling the dispatch warned about, plus four others):

• pnpm --filter @objectstack/cli typecheck — exit 0. Both halves: tsc --noEmit over
  src (which is where the new value pin lives, so it is type-checked), and
  check:test-typecheck over tsconfig.test.json, whose verdict line reads
  OK — @objectstack/cli's test layer compiles … 3 file(s) / 28 error(s) / 6 pinned signature(s) held — the pre-existing ledger, unmoved.
• Targeted vitest, 6 files / 53 tests passed: the two new/edited guards, the three
  conversion-notice e2e suites (lint-conversion-notices,
  validate-json-failure-conversions, build-json-failure-conversions — these drive the
  real CLI over a live conversion via tsx, so they are the behavioural proof the output
  did not move), and i18n-check-help-surface-parity from the merged sibling PR.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
  at that HEAD: 42 families (33 by path, 6 by change kind, 5 declared whole-tree).
  40 green. Two are NOT MEASURED and say so themselves: check-test-completeness.mjs
  grades a saved turbo run test log this box cannot produce ("the local reading for this
  gate is NOT MEASURED"), and check-half-states.mjs needs repo-scoped GitHub REST, which
  this container is refused (GET /repos/... returns 403 with no rate-limit headers while
  GET /rate_limit reports 15000 left). Five others first exited 3 on an unbuilt closure
  and went green after a full pnpm build: check:dual-build-cjs-loads, check:i18n,
  check:i18n-coverage, check:type-check-debt (which had also hit a local 300s cap), and
  the two named above stayed 3 for the reasons given.

Declared narrowing. The repo-wide pnpm lint sweep was not run locally; CI owns it and
runs it once regardless. Everything else in the derived union was run.

What this deliberately does not do

ConversionNotice.message and defineStack's warnConversionNotice are untouched. Whether
all of the renderings should descend from one source is a real question with a real cost on
either side, and it is #15095, not this card.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s).

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 22 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 ab47816914fd39709f4e9645370729ce1f4f9826 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 48aac740974ea994794664b7dce221ed4dfb15b1 — the merge of head 9fc66fafafab958e3ae03b0f43bf8989c9b72699 into base ab47816914fd39709f4e9645370729ce1f4f9826, 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 48aac740974ea994794664b7dce221ed4dfb15b1 && git checkout 48aac740974ea994794664b7dce221ed4dfb15b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ab47816914fd39709f4e9645370729ce1f4f9826 9fc66fafafab958e3ae03b0f43bf8989c9b72699 && git checkout -B drift-repro ab47816914fd39709f4e9645370729ce1f4f9826 && git merge --no-ff 9fc66fafafab958e3ae03b0f43bf8989c9b72699
node scripts/docs-audit/affected-docs.mjs --json ab47816914fd39709f4e9645370729ce1f4f9826

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