Repository navigation
Commit 514a422
docs(adr): ADR-0146 amended in place — an upgrade plan may report a .custom override that hides a vendor change, as advice only (#30899)
Fixes #30881
Clause-②: no
Metadata-protocol: none
## 维护者速读
- **改了什么**:只改 ADR-0146 的文字(就地修订,状态行加一条 2026-11-06 的「Amended in
place」):允许基础包的升级预览(upgrade plan)给出一条**提示**,列出「这个 `.custom`
覆盖挡住了本次升级对同名项的修改」,以及 `basedOn` 与已安装版本不一致的覆盖。
- **为什么改**:执行你在 cloud#3652 上对 D2
的裁决「修订为允许只提示(推荐)」;原文写死了「不产出升级差异、`basedOn` 不被读取」,挡住了后续的漂移提示卡(#30886)。
- **风险与回滚**:零运行时风险,没有代码、spec 或文档站改动;`basedOn`
仍然「只记录、永不拦截」,不拒绝安装、不自动合并、不自动 rebase。回滚 = revert 这一个提交。
- **先看**:`docs/adr/0146-…md` 的 D2 段(`basedOn` 那一句,风险最高:它定义了提示的两种情形
a/b);其次 D6 的「Not done」一条和 Consequences 第三条。
- **两分钟验证**:`git diff origin/main -- docs/adr/0146-*` 应只见 7 处文字改动 + 1 条
Refs;`pnpm check:adr-index` 应打印 `docs/adr/README.md is current`。
- **需要你做的**:审阅后亲手合并(Tier H,草稿状态,席位不会转 ready、不入队、不开 auto-merge)。
## What changes
ADR-0146 is amended in place for decision D2 on epic
objectstack-ai/cloud#3652 (ruling record
[`6681380041`](objectstack-ai/cloud#3652 (comment)),
maintainer, verbatim: 「修订为允许只提示(推荐)」). A base's upgrade plan may list,
as advisory findings, (a) a `.custom` item whose declared override names
a base item the upgrade changes, and (b) an override whose `basedOn` is
not the installed base's `manifest.version`. `basedOn` stays recorded
and never gates: no refusal, no token, no automatic merge, rebase or
rewrite. Whole-document replace, ADR-0141 D3's deferral and merge
question 1's `^MAJOR` reasoning are unchanged.
The diff touches only
`docs/adr/0146-studio-designs-setup-administers-one-editor-per-item-paired-customize-package.md`.
`pnpm adr:index` was regenerated and wrote a byte-identical
`docs/adr/README.md` (the index shows a truncated status prefix, which
this amendment does not reach), so the README is not in the diff.
### Before / after of each amended sentence
| Passage (line on `d55acb78`) | Before | After |
|:---|:---|:---|
| Status line (`:23`, appended) | (no 2026-11-06 note) | "· **Amended in
place** (2026-11-06, decision D2 on epic objectstack-ai/cloud#3652,
ruling record `6681380041`, maintainer, verbatim: 「修订为允许只提示(推荐)」): a
base's upgrade plan may report, as advice, each `.custom` override that
hides a vendor change; `basedOn` still never gates, and nothing is
refused, merged or rebased on the finding (D2, D6, the Supersede table's
§9 row, Consequences, merge question 2). It lands by the maintainer's
hand-merge of the PR cut from #30881." |
| D2 (`:210-212`) | "**`basedOn` is recorded, not judged**: no door
compares it with the installed base's version, no upgrade diff is
produced, and nothing is refused on it (epic #28236, …recorded only)." |
"**`basedOn` is recorded and never gates** (epic #28236, …recorded
only). **One reader is admitted, as advice** (amended 2026-11-06, …): a
base's **upgrade plan** … may list as advisory findings (a) a `.custom`
item whose declared override names a base item the upgrade changes
between the installed and the new version ("this override hides a vendor
change"), and (b) an override whose `basedOn` is not the installed
base's `manifest.version`. On either finding no door refuses, no token
is asked, and nothing is merged, rebased or rewritten automatically; the
upgrade proceeds as it would without it, and re-basing stays the
customer's act. The plan carries both findings in an **advisory class**
that its refusal never reads and that no finding-set token covers, so
neither becomes a gate by sharing a response with a refusing finding.
The finding is not the base-upgrade interception ADR-0141 D3 defers,
because it refuses nothing, and D3's `^MAJOR` reasoning (merge question
1) is unchanged." |
| D2, §9 lift (`:262`) | "**Diff-vs-base and the upgrade skip-report
stay deferred**" | "**The advisory upgrade finding above is chartered; a
field-level diff-vs-base view and the upgrade skip-report as a merge
tool stay deferred** (amended 2026-11-06)" |
| D6 "Not done" (`:393`) — not named by the card | "**No clone lineage,
no upgrade diff, no `basedOn` judgement** (D2, D4)." | "**No clone
lineage, no field-level upgrade diff, no gate on `basedOn`** (D2, D4) —
the upgrade plan's advisory finding (D2, amended 2026-11-06) refuses,
merges and rebases nothing." |
| Supersede table, ADR-0126 §7.4/§9 row, *Rule now* (`:563`) | "badge,
customization list and revert are chartered on served facts,
diff-vs-base and the skip-report stay deferred (D2)." | "badge,
customization list and revert are chartered on served facts; the upgrade
plan's advisory finding is chartered (amended 2026-11-06); a field-level
diff-vs-base view and the skip-report as a merge tool stay deferred
(D2)." |
| Consequences, third bullet (`:600-601`) | "…until the customer
re-bases it, and the platform computes no diff to help (D6)." | "…until
the customer re-bases it. The base's upgrade plan names each override
that now hides a change, as advice (D2, amended 2026-11-06); re-basing
stays the customer's act, and the platform computes no field-level diff
and merges nothing (D6)." |
| Merge question 2 (`:679-681`) | "**`basedOn` is recorded and never
judged** — … no card reads `basedOn` as a gate (D2)." | "**`basedOn` is
recorded and never gates** — … no card reads `basedOn` as a gate (D2).
One reader is admitted, as advice (amended 2026-11-06, …): the upgrade
plan's finding of D2, which lists an override whose base item the
upgrade changes or whose `basedOn` is not the installed base version,
and refuses nothing." |
| Refs (appended) | — | a bullet naming card #30881, the ruling record,
and the finding's own card #30886 on the upgrade plan of #30884. |
Unchanged on purpose: D3's dependency-range bullet ("where `basedOn` is
read by a human") and merge question 1 (the `^MAJOR` reasoning), per the
card's item 6; the Supersede row's *Gate and pin* column (the finding's
code is card #30886's).
## Acceptance notes
- **D6's "Not done" bullet was amended although the card does not list
it.** Left as written ("no upgrade diff, no `basedOn` judgement") it
would contradict the amended D2 inside the same record; the change keeps
it as narrow as the ruling (no gate, no field-level diff).
- **`scripts/adr-index.mjs` reads header fields from a record's first 40
lines only (`HEADER_WINDOW = 40`).** A status note that pushes
`**Supersedes in part**` past line 40 makes the regenerated index
silently empty that record's Supersedes cell, and `pnpm check:adr-index`
still exits 0 because its `--report` never fails. This PR keeps the
status note to 3 lines: ADR-0146's Supersedes line sits at `:38` and its
index row is unchanged (zero `docs/adr/README.md` diff after `pnpm
adr:index`). The producer fix is #30916, a
separate non-governed card, not part of this Tier H PR.
- **Quotes of the old sentence elsewhere, listed and not edited:**
- Governed: `docs/adr/0126-packaged-metadata-customization-model.md:3`
(its status-line pointer: "diff-vs-base and the skip-report stay
deferred");
`skills/objectstack-platform/evals/config-plugins-ops.json:169`
("`basedOn` recorded and never judged").
- Not governed, and not the same sentence (they describe today's
runtime, where nothing reads `basedOn` yet — editing them before #30886
lands would advertise an undelivered capability):
`content/docs/api/metadata-api.mdx:105`,
`content/docs/concepts/metadata-lifecycle.mdx:121`.
- Generated / code (card #30886's surface):
`packages/spec/src/kernel/override-declaration.zod.ts:98`, `:137`,
`:141` and the `content/docs/references/**` pages generated from it;
`packages/metadata-protocol/src/served-override.ts:35`,
`protocol-packaged-base-refusal.ts:1016`.
- **Changeset:** none — `docs/adr/**` publishes nothing;
`skip-changeset` is declared with this PR.
- **Tier H — the maintainer merges.** `docs/adr/**` is a governed
surface (Prime Directive #14). This PR stays a draft; no seat readies
it, requests review, queues it or arms auto-merge.
## Verification
All on head `9647da16` (objectstack), gates from `node
scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--commands` (the same 21 families as at `561b3b2d`), exit codes captured
before any pipe.
<details><summary>Derived gate families — 21 of 21 run locally, all exit
0; plus check:pm-governed-prose</summary>
```text
0 | node scripts/check-adr-links.mjs (991 relative link destination(s) under docs/adr/ resolve)
0 | node scripts/check-adr-links.mjs --self-test
0 | node scripts/check-closing-keyword-parity.mjs
0 | node scripts/check-closing-keyword-parity.mjs --self-test
0 | node scripts/check-comment-mask-corpus.mjs
0 | node scripts/ci/plan-test-core-shards.mjs --self-test
0 | pnpm check:adr-anchors
0 | pnpm check:adr-index (docs/adr/README.md is current, every record parsed)
0 | pnpm check:adr-symbol-anchors (3163 anchors across 150 records resolve)
0 | pnpm check:ci-filter-parity
0 | pnpm check:closed-ceremony-text
0 | pnpm check:cross-package-test-inputs
0 | pnpm check:doc-authoring
0 | pnpm check:driver-memory-census
0 | pnpm check:gitlink-declared
0 | pnpm check:nul-bytes (no raw ASCII control bytes)
0 | pnpm check:pm-governed-merges
0 | pnpm check:pm-prior-rulings
0 | pnpm check:refd-timer-probe
0 | pnpm check:watch-hint-literal
0 | pnpm check:pm-governed-prose (card acceptance; 13 registered governed surfaces named)
0 | pnpm --filter @objectstack/lint run check:doc-formula-expressions
(first run exit 3, PREREQUISITE NOT MET; re-run after building @objectstack/formula and
@objectstack/lint under the verify lock: VERDICT command-exit 0, Tasks 4/4)
dispatch-gates --ran: 21 derived famil(ies) accounted for — 21 run, 0 NOT-MEASURED
(a DERIVED zero — all 21 recorded an exit code and none of them is 3).
```
</details>
No tests, typecheck or dogfood: the diff touches no package, and the
title carries no `!`.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01Q4EjjRhUZjdy8VXs6Kkur2)_
<!-- signed: repo:cloud#3 · hotlong · session_01Q4EjjRhUZjdy8VXs6Kkur2
-->
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 253eab0 commit 514a422
1 file changed
Lines changed: 33 additions & 10 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
21 | 21 | | |
22 | 22 | | |
23 | 23 | | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
24 | 27 | | |
25 | 28 | | |
26 | 29 | | |
| |||
207 | 210 | | |
208 | 211 | | |
209 | 212 | | |
210 | | - | |
211 | | - | |
212 | | - | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
213 | 224 | | |
214 | 225 | | |
215 | 226 | | |
| |||
259 | 270 | | |
260 | 271 | | |
261 | 272 | | |
262 | | - | |
| 273 | + | |
| 274 | + | |
263 | 275 | | |
264 | 276 | | |
265 | 277 | | |
| |||
390 | 402 | | |
391 | 403 | | |
392 | 404 | | |
393 | | - | |
| 405 | + | |
| 406 | + | |
394 | 407 | | |
395 | 408 | | |
396 | 409 | | |
| |||
560 | 573 | | |
561 | 574 | | |
562 | 575 | | |
563 | | - | |
| 576 | + | |
564 | 577 | | |
565 | 578 | | |
566 | 579 | | |
| |||
597 | 610 | | |
598 | 611 | | |
599 | 612 | | |
600 | | - | |
601 | | - | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
602 | 616 | | |
603 | 617 | | |
604 | 618 | | |
| |||
676 | 690 | | |
677 | 691 | | |
678 | 692 | | |
679 | | - | |
| 693 | + | |
680 | 694 | | |
681 | | - | |
| 695 | + | |
| 696 | + | |
| 697 | + | |
| 698 | + | |
682 | 699 | | |
683 | 700 | | |
684 | 701 | | |
| |||
718 | 735 | | |
719 | 736 | | |
720 | 737 | | |
| 738 | + | |
| 739 | + | |
| 740 | + | |
| 741 | + | |
| 742 | + | |
| 743 | + | |
721 | 744 | | |
722 | 745 | | |
723 | 746 | | |
| |||
0 commit comments