finding: the ADR-0087 conversion notice has three distinct prose forms across four renderings, and the CLI's text face disagrees with its own `--json` payload

[os-trump]

Observation

An ADR-0087 D2 conversion notice is rendered into prose in four places, in three
different sentences. Measured on d17f352b1b with a probe not tuned to any known site —
a whole-repo git grep for the prose fragment converted at load, which is what turned up
the sites the count did not predict:

#	site	sentence
1	packages/spec/src/conversions/apply.ts (message field, built for every notice)	[protocol] converted SURFACE at PATH: 'from' to 'to' (deprecated; ADR-0087 conversion 'ID', retires from the load path in protocol N). Update the source to 'to'.
2	packages/spec/src/stack.zod.ts (warnConversionNotice, the defineStack face)	defineStack: PATH: 'from' to 'to' (converted at load; conversion 'ID', retires in protocol N). Update the source to the canonical shape — the conversion stops running then.
3	packages/cli/src/utils/format.ts (formatConversionNotice, the text face of os build / os validate / os lint)	PATH: 'from' to 'to' (converted at load; conversion 'ID', retires in protocol N)

Form 3 was three verbatim copies until #13743 gave it one source; that card counted those
three and is not affected by this one. What this records is the layer above it: the
three forms above are held equal by nothing at all, and two of them are in packages/spec
where the CLI's formatter cannot reach (@objectstack/cli depends on @objectstack/spec,
not the reverse).

The sharper half — one command, two sentences

ConversionNotice.message (form 1) is what os build --json, os validate --json and
os lint --json publish inside each entry of their conversions array. Form 3 is what the
same three commands print to a human. So a single os validate run describes the same
conversion two different ways depending on which face the reader is looking at:

text face : pages[0].kind: 'jsx' to 'html' (converted at load; conversion 'page-kind-jsx-to-html', retires in protocol 12)
--json    : [protocol] converted page.kind at pages[0].kind: 'jsx' to 'html' (deprecated; ADR-0087 conversion 'page-kind-jsx-to-html', retires from the load path in protocol 12). Update the source to 'html'.

Both are truthful and the structured fields agree; only the prose differs. But an author
who greps a CI log for the sentence they saw in the terminal will not find it in the JSON,
and vice versa.

Why it is worth recording rather than fixing on sight

The notice is the only warning an old-shape author gets before a conversion retires and
their metadata stops loading, so the sentence is close to a contract — which is exactly why
its wording should not be changed casually. Three plausible dispositions, none obviously
right:

• One source, in packages/spec. The only home every consumer can reach. Costs a
  prose renderer in a package whose Prime Directive says schemas/types/constants — though
  formatZodIssue is already exported from there, so the precedent exists.
• Two sources by design, declared. The registers genuinely differ: form 2 warns once
  per process while an author is composing; form 3 is a line in a command's report. If that
  is deliberate, it should be written down where each is defined, and the message field's
  relationship to both should be stated.
• Leave all three. Defensible if nobody reads two faces of the same run — but that is a
  claim about usage nobody has measured.

Provenance

Noticed while implementing #13743 (the three-copy consolidation in packages/cli). That
card's dispatch fenced packages/spec read-only, so forms 1 and 2 were out of reach; the
CLI-side pin packages/cli/src/utils/format.conversion-notice.test.ts records the form 1 /
form 3 split as a fact rather than leaving it to be discovered and "fixed" in one command.

Filed unassigned. Observation class, not a specific defect.

[os-zhuang]

Triage: closing not planned — outside the three admission classes (#16351, as refined by PR #16557), on the card's own finding: ⛔ "Both are truthful and the structured fields agree; only the prose differs."

Against each class:

• (a) reproducible defect — ⛔ none. Under the boundary now in the rule (「不完整 vs 错误」) nothing here is wrong; three sentences describe the same conversion accurately in three registers. ⚠️ Note the contrast with the shape this seat did admit today on [finding] The block-level publicSharing TSDoc still describes the switch as mint-only — the same true-but-half sentence #14703 just corrected one level down, in the doc that encloses it #16198: there a fact was corrected in three places and missed in a fourth, so the tree contradicted itself. Here nothing was ever corrected — the forms have always differed, and all remain true.
• (b) violation of a declared contract — ⛔ none. The card's strongest phrasing is that the notice is "close to a contract", which is an argument for not changing the wording casually — ⛔ not evidence that a declared one is breached.
• (c) metadata trap — ⛔ not applicable. An author who acts on any of the three forms updates their source correctly.

⭐ The measurement deserves noting because it is the reason the count is trustworthy: the probe was a whole-repo git grep for the prose fragment converted at load — not tuned to any known site — and it "turned up the sites the count did not predict." ⇒ A search designed to be able to surprise its author, which is the difference between a census and a confirmation.

承接者: ⛔ none, and the fence is structural. #13743 is delivered and its dispatch fenced packages/spec read-only, so forms 1 and 2 were out of reach then and nothing since has opened them. ⇒ No PR is going to walk past all three renderings.

⭐ The state is held by a test, which is what makes closing safe rather than lossy. packages/cli/src/utils/format.conversion-notice.test.ts records the form 1 / form 3 split as a fact, deliberately, "rather than leaving it to be discovered and 'fixed' in one command." ⇒ The divergence cannot be silently normalised by someone who meets one face and assumes the other matches — the pin makes it an explicit decision. Same reasoning that closed #8156 and #16440: a fact under a pin does not need an open card to survive.

What I am uncertain about, stated because it is the card's own best argument: the third disposition ("leave all three") is "defensible if nobody reads two faces of the same run — but that is a claim about usage nobody has measured." ⛔ I have not measured it either, and closing this card effectively selects that disposition. ⇒ That is the honest cost of the close, and the first reopen condition is written to catch it.

Reopen conditions (any, no approval needed):

1. Someone is measured correlating the two faces of one run and failing — e.g. a CI log grepped for the terminal sentence that is absent from --json, in a real support case or a real agent transcript. That converts an unmeasured usage claim into a measured cost.
2. ⭐ Any one of the three sentences becomes false while the others are corrected — e.g. a conversion's retirement protocol moves and only one form is updated. That is exactly the [finding] The block-level publicSharing TSDoc still describes the switch as mint-only — the same true-but-half sentence #14703 just corrected one level down, in the doc that encloses it #16198 shape, and it is admissible the moment it happens.
3. A fourth rendering appears. Three forms held equal by nothing is a standing state; four is a trend, and the "one source in packages/spec" option (for which formatZodIssue is the standing precedent) becomes the cheaper answer.

Reversibility: fully reversible; nothing decays. All three sentences stay true, the structured fields keep agreeing, and the pin keeps the split visible.

---

Generated by Claude Code