Repository navigation
Commit de70e97
![objectstack-fleet[bot]](https://avatars.githubusercontent.com/u/254823548?v=4&size=40){kind=avatar}
fix(spec): the retirement sentence names
Fixes #9591
Clause-②: no (prescription text only; no input's accept or reject result
changes)
This is the spec-lane half of the card: the shared retirement sentence
names `--write`, and the class-wide pin moves in the same PR. The
codemod itself landed in PR #22108 (`a959493cdf`).
## The sentence
Before (the #9529 wording):
```text
Run `os migrate meta --from N` to list the mechanical edits for existing sources; apply them by hand.
```
After:
```text
Run `os migrate meta --from N` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.
```
The one allowed two-clause variant (a conversion that covers only part
of a value) carries the same clause: `… to list the mechanical edits for
the X case; --write applies the ones it can prove, and
WHAT-HAPPENS-TO-THE-REST.` Its two members are dashboard
`compareTo.offset` and the script node's `config.actionType`.
**Checked against the tool on `main` (`51290bca`).**
`packages/cli/src/commands/migrate/meta.ts` declares `write:
Flags.boolean({ … default: false, exclusive: ['stored'] })`. Its help
text says it rewrites the authored sources in place "for each mechanical
change traced to one literal in one project file; every other change is
listed with the reason it was not written". Without the flag the run
writes only the `--out` snapshot. The wording satisfies every ruling
that binds it:
- **Triage `6045697201`.** The sentence never says "rewrite existing
sources automatically" unqualified ("the ones it can prove"), and it
names `--write` because the default run still only lists.
- **"It must be TRUE of the tool."** Every clause is a property of the
command, read from `meta.ts`.
- **"One antecedent."** "existing sources" still names one thing. "The
ones" can only be edits, because an edit is what gets applied. The key's
fate stays in the body prose.
- **Vocabulary.** The wording matches PR #22122's skill text ("lists the
mechanical edits"; `--write` "rewrites in place each edit it can trace
to one literal in one project file, lists every other with the reason it
was not written").
## Where it moved (counted at `017761f0`; the merge of `main` added no
site)
- **161 sentences the pin judges.** `packages/spec/src`: 157 (155 house
form, 2 two-clause). `packages/lint/src`: 1.
`packages/drivers/driver-turso/src`: 3. Every one passes the new
anchors; `apply them by hand` survives only in the pin's own RED
fixtures.
- **Not judged by the pin, moved anyway:**
- `migrations/registry.ts`: 3 sentences, regenerated from the moved
`entries/semantic/18.*.ts` by `gen:migration-registry`.
- The lint `chartConfig.xAxis.field` hint in
`validate-widget-bindings.ts`: a template literal with interpolation
after the sentence, so the pin cannot see it (Acceptance notes).
- The `retiredKey()` docblock example.
- **Mechanical replacement.** A script replaced the tail `apply them by
hand` in 63 files (188 occurrences; old tail left: 0) and printed
per-file before/after counts. Two seams split mid-phrase
(`translation.zod.ts`) and the two two-clause sites were rewritten by
anchored edits that had to hit exactly once.
- **Pins in other test files.** 23 test files asserted the old sentence
verbatim, as string or regex. Each now asserts the new sentence
verbatim, so a revert reds them. The ones that assert only the unchanged
prefix (`form-layout-inline-grid-retired.test.ts`, the turso /
driver-memory `toContain('os migrate meta --from 17')`) are untouched,
because they stay true.
- **Changeset.** `.changeset/9591-retirement-sentence-write.md`: `patch`
for `@objectstack/spec`, `@objectstack/lint` and
`@objectstack/driver-turso`, the three packages whose shipped text
moves.
- **Generated.** `content/docs/references/**`: 32 files (+268/−268) from
`pnpm --filter @objectstack/spec check:generated --fix`; `check:docs`
was the only stale artifact. `check:generated` then exited 0.
## The class pin (`retired-key-migrate-sentence.test.ts`)
- **Anchors.** `HOUSE_AT_MARKER` and `MIXED_AT_MARKER`, and their
markdown twins, require the new clause. The #9529 sentence, which does
not name `--write`, is now RED. Two further spellings are RED: one that
names `--write` without the qualification, and one that qualifies it but
leaves the rest unowned.
- **Withdrawn claim.** `WITHDRAWN_CLAIM` is unchanged: the unqualified
automatic-rewrite claim stays a hard RED everywhere. A new non-vacuity
case proves neither legal shape trips it.
- **Truth anchor (new).** The pin reads `os migrate meta`'s own flag
table. A `write` boolean flag must exist and must have `default: false`,
the two facts the sentence rests on. The read is covered by
`@objectstack/spec`'s existing `packages/**/*.ts` cross-package
declaration.
- **Corpus widened by one root.** `packages/drivers/driver-turso/src`
joins, on #7030's terms. Its three `turso` config tombstones carry the
house sentence, and their docblock defers to `retired-key.ts`, but the
pin never walked them. Without this, a rewording leaves them behind with
every assertion green. The lint-only anti-vacuity case now covers each
widened corpus.
- **Header and docblock.** The pin header and the `retired-key.ts`
module docblock record the new sentence and why. The "the claim may be
restored" note is gone, replaced by what was restored and how far.
**Reverse verification**, run from committed HEAD `017761f0` through
`scripts/ablation-replace.mjs` (each anchor hit as declared and was
restored to a blob equal to HEAD with `git diff HEAD` empty). Expected
direction: red.
| Mutation | Result |
|:--|:--|
| A. the three `turso.zod.ts` sentences back to the #9529 wording
(anchor ×3→0, blob `e25cca4d5508`→`a05fe3f09733`) | 3 failed / 12
passed, naming `driver-turso:spec/turso.zod.ts:63`, `:75`, `:82` |
| B. `meta.ts` `write` flag `default: false` → `true` (blob
`c036012c63c9`→`71acff21ef8c`) | 1 failed / 14 passed: "the sentence is
TRUE of the command it names" |
| C. `meta.ts` flag renamed `write` → `inPlace` (blob
`c036012c63c9`→`29a8a9402284`) | 1 failed / 14 passed: "os migrate meta
declares no `write` boolean flag" |
Under the old corpora, mutation A would have stayed green, because
driver-turso was in no corpus.
## One bounded fix on the same sentences: `CHATTER_POSITION_RETIRED`
The three `record:chatter` / `record:discussion` `position` value
prescriptions (`'sidebar'`, `'inline'`, `'drawer'`, in
`ui/component.zod.ts`) told the author to run a bare `os migrate meta`.
The command refuses that with `Missing required flag --from` (`meta.ts`
`run()`, the `flags.from === undefined` branch). The conversion is
`record-chatter-position-vocabulary`, `toMajor: 18`, so they now name
`--from 17`. They therefore join the pin's judged set in house form, and
the "(registered under protocol major 18)" aside goes. The fix qualifies
as bounded: the same sentence class, a mechanical change to an
already-pinned form, a file inside this claim's surface, and the same
gate family. No test pinned the old text.
## Governed surface: `.claude/skills/spec-property-retirement/SKILL.md`
(Tier S)
The pin requires the retirement playbook to teach both shapes
(`SKILL_HOUSE_TEMPLATE` and `SKILL_MIXED_TEMPLATE` must match its
convention 5). So changing the sentence forces the playbook edit, and
this PR lands as Tier S. Convention 5 now carries the two new templates.
Its note that the command "never writes a source file" was made false by
PR #22108, so it is deleted. Line count 337 → 337 (ceiling 337), with
every line within the 120-byte budget: `node
scripts/pm/check-skill-line-ratchet.mjs` exits 0. ⛔ No published
`skills/**` file changes: PR #22122 owns
`skills/objectstack-upgrade/SKILL.md`, and no published skill carries
the sentence (`git grep` count 0).
## 维护者速读(草稿)
**改了什么**:所有退役键报错末尾那句统一提示,从「运行 `os migrate meta --from N`
列出机械修改,然后手工改」改为「……列出机械修改;`--write` 会写入它能证明的那些,其余你手工改」。共 161 处被 pin
判定的报错文案(含 2 处两从句变体),外加生成的 registry 3 处、lint 模板字符串 1 处;其中 3 处原先写成不带
`--from` 的命令(该命令会直接拒绝),一并改正。守这句话的 pin 同步更新,并新增一条断言:CLI 必须真有 `--write`
且默认不写。
**为什么改**:`--write` 已随 PR #22108 落地,旧句只说「手工改」,低估了工具;但 `--write`
只写能证明的站点,所以不能说「自动重写源文件」。新句两头都如实。
**风险与代价(含回滚)**:纯文案,不改任何 schema、键、类型、导出或错误码;解析结果不变。依赖旧整句原文匹配的调用方会失配(仓内 23
个测试已同步);前缀「…for existing sources;」不变。回滚即 revert 本 PR。在途的兄弟 PR
若新增处方仍用旧句,会被 pin 打红,后落地者改用新句。
**席位意见**:
**你要做的**:无需操作;本 PR 触 `.claude/**`(Tier S),由席位按合同审查记录落地。
## Verification (branch base `51290bca`; final head `f9ca14d548`)
- `pnpm --filter @objectstack/spec build`: VERDICT command-exit 0.
`check:generated --fix` regenerated the one stale artifact;
`check:generated` then exited 0 (15 of 15 current), and again in the
gate run at `f9ca14d548`.
- spec `vitest run --project local`: Test Files 623 passed (623), Tests
18613 passed, 1 todo, at `017761f0`.
- spec `vitest run --project repo` (53 files incl. the class pin): 53
passed (53), Tests 903 passed (903), at `017761f0`.
- `@objectstack/driver-turso` `vitest run`: Test Files 88 passed (88),
Tests 2373 passed, 33 skipped, at `017761f0` (after `pnpm
--workspace-concurrency=2 --filter '@objectstack/lint...' --filter
'@objectstack/driver-turso...' build`; the first run, before that build,
could not resolve unbuilt dependencies and is NOT MEASURED, not red).
- `typecheck` for spec (`tsc --noEmit` + `check:scripts-typecheck` +
`check:test-typecheck`), lint and driver-turso: exit 0 at `017761f0`.
- **After merging `main`** (`033e5c536d`: #22122, #22127, #22106) as
`f9ca14d548`, with no conflict (#22127 also edits
`validate-expressions.ts`): the class pin 15 passed (15);
`@objectstack/lint` `vitest run`: Test Files 123 passed (123), Tests
5688 passed (5688); lint `typecheck` exit 0.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` at `f9ca14d548` derives 124 commands (the
claim-time 79 plus 45). All 124 exit 0 at `f9ca14d548`. `--ran`
reconciliation: 124 derived, 124 run, 0 NOT-MEASURED, a zero derived
from the recorded exit codes. (At `017761f0`, five gates first answered
exit 3, PREREQUISITE NOT MET: one shallow-clone fixture and four that
need unbuilt dists. The clone was deepened as the gate asked, and all
five are green in the `f9ca14d548` run.)
- `node scripts/pm/check-skill-line-ratchet.mjs`: exit 0; the playbook
is 337 lines (ceiling 337), and no line is over 120 bytes.
- eslint, narrowed: `pnpm exec eslint --no-inline-config --format json`
over the 66 changed `.ts` files reports 66 files, 0 errors and 0
warnings. The population is `eslint.config.mjs`'s
`**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}` glob, which excludes the changed
`.md` / `.mdx` files. The config never enables type-aware linting (its
own comment at `:326`–`:328`), so this diff cannot move any untouched
file's verdict. The repo-wide `pnpm lint` is CI's.
## Siblings in flight
#21982, PR #22094 (#13458) and PR #22103 (#5082) each add prescriptions
with today's sentence. Whichever lands after this one carries the new
sentence; the class pin reds it at that merge otherwise. Whichever of
those lands first, this branch merges `main` before landing.
## Acceptance notes
- **Hand-written docs still use the old sentence**
(`content/docs/automation/flows.mdx` ×2,
`protocol/objectql/query-syntax.mdx`, `data-modeling/queries.mdx`,
`protocol/objectui/actions.mdx`, `ui/apps.mdx` ×2). Each is the page's
own advice, not a quoted error, and still true of the default run; each
undersells `--write`. They are `domain:devx` pages outside this claim,
so they are not touched here.
- **QA checklist item `cli.migrate-meta-codemod`**
(`docs/qa/platform-checklist/areas/cli.json`). Its RESTART CHECK fired
when PR #22108 added `--write`, and the item still asserts a print-only
command. Its step 1 greps for the #9529 sentence verbatim and now finds
none. Re-authoring the item belongs to the checklist author, not this
PR.
- **Comments that say the default run "lists the mechanical edits"**
stay as they are, because they are still true: the
`migrations/registry.ts` migration notes (outside the pin's scope by
design) and the `conversions/registry.ts` comments.
- **The lint `chartConfig.xAxis.field` hint**
(`validate-widget-bindings.ts`) moved, but it remains invisible to the
class pin: a template literal, with `suggestName(…)` and the suppress
hint interpolated after the sentence.
- **A published skill still claims an automatic strip.**
`skills/objectstack-data/rules/indexing.md:31` says "run `os migrate
meta --from 16` to strip them automatically", and
`skills/objectstack-data/SKILL.md:377` says the command "strips them".
The default run strips nothing from sources, and `--write` strips only
what it can prove. `WITHDRAWN_CLAIM` has no strip spelling, so the pin
cannot see this. Widening it here would red `main` on a Tier H file this
PR may not touch, so it is reported to the PM for the skills lane.
- **The `config.actionType` two-clause tail** ("the stub and marker
values are removed") is unchanged in substance; only the `--write`
clause was inserted before it.
## Patch round 1 (written by the PM seat from the dev's report
`6052088494`)
- **Merge:** `origin/main` `ef1fcb26a2` (PR #22103) was merged through
`os-regen-merge.sh` as `feca6b5ace`. The three reference pages both
sides had changed (`api/metadata`, `data/object`, `system/migration`)
were regenerated from the merged tree as `98e2f6e373`. That brings back
#22103's `unique?: false | 'global' | 'organization'` rows, which the
driver had dropped.
- **#22103's sites:** the merge brought two non-test sites with the old
tail and one test that asserts it verbatim. All three carry the new
sentence at `b9d6e82619`:
- `packages/spec/src/data/object.zod.ts`
(`DECLARED_INDEX_BARE_TRUE_RETIRED`);
- `packages/lint/src/data-model-rules.ts` (the
`unique-unscoped-declared-index` fix text);
- `unique-scope-message.test.ts`.
The pin now judges 163 sentences: `spec` 158 (156 house + 2 two-clause),
`lint` 2, `driver-turso` 3.
- **The pin's blind spot:** the `data-model-rules.ts` sentence sat in a
template literal, which the judge cannot read (escaped backticks), so it
was never judged. It is now plain-quoted, as in
`validate-expressions.ts`, and the pin's Mechanism paragraph records
that template literals are invisible to the scan. Ablation D (that
sentence back to the old tail) gives 3 failed / 12 passed, naming
`lint:data-model-rules.ts:463`. `validate-widget-bindings.ts` stays the
one template-literal site the pin cannot judge (an Acceptance note).
- **Verification at `b9d6e82619`:**
- spec `--project local`: 623 files / 18,619 tests;
- spec `--project repo`: 53 / 903;
- lint: 123 / 5,689;
- driver-turso: 88 / 2,373;
- typecheck: exit 0 for all three packages;
- `dispatch-gates --ran`: 124 derived / 124 run / 0 NOT-MEASURED;
- CI: 33 success, 2 expected skips.
## Patch round 2 (written by the PM seat from the dev's report
`6053397952`; claim revised `6052335087`)
- **Why:** PR #22094 (#13458, `fec87e7e07`) landed first with a
two-clause prescription lacking the `--write` clause, which this PR's
class pin refuses. The sibling rule here ("whichever lands later carries
the new sentence") puts the edit in this PR.
- **Merge:** `origin/main` `959c209d56` was merged through
`os-regen-merge.sh` as `3b6335b9be`, with no hand-written conflict.
`content/docs/references/api/protocol.mdx` was regenerated as
`c40b3babd7`.
- **The edit** (`fe3af5642c`, 4 files beyond the merge):
- `packages/spec/src/kernel/manifest.zod.ts`
`PLUGIN_PERMISSIONS_LIST_FORM` now closes with "Run `os migrate meta
--from 17` to list the mechanical edits for the package manifest case;
`--write` applies the ones it can prove, and a granted-permission record
is not a source it reads." It keeps #13458's own second clause and adds
the house `--write` clause, the seat's wording.
- Its verbatim pin `manifest-permissions-string-list.test.ts` moved with
it.
- The changeset's two-clause bullet now names three members and says
"before their second clause".
- **The two-clause variant now has three members:** dashboard
`compareTo.offset`, the script node's `config.actionType`, and the
package manifest `permissions` case. The pin judges 164 sentences (spec
159 = 156 house + 3 two-clause; lint 2; driver-turso 3) with 0 bad
sites.
- **Verification at `fe3af5642c`:**
- spec `--project local`: 625 files / 18,661 tests;
- spec `--project repo`: 53 / 903;
- class pin: 15 / 15, and the manifest pin: 17 / 17;
- `dispatch-gates --ran`: 124 / 124 / 0 NOT-MEASURED;
- CI: 33 success, 2 expected skips.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01LAi5BVvQNiYzepSAcsoFLK)_
---------
Co-authored-by: Claude <noreply@anthropic.com>--write: it applies the edits it can prove, you apply the rest (#22142)1 parent f4bed58 commit de70e97
104 files changed
Lines changed: 667 additions & 556 deletions
File tree
- .changeset
- .claude/skills/spec-property-retirement
- content/docs/references
- ai
- api
- automation
- data
- integration
- kernel
- security
- system
- ui
- packages
- drivers/driver-turso/src/spec
- lint/src
- spec/src
- ai
- api
- automation
- data
- driver
- integration
- kernel
- migrations
- entries/semantic
- security
- system
- ui
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
151 | 151 | | |
152 | 152 | | |
153 | 153 | | |
154 | | - | |
155 | | - | |
156 | | - | |
| 154 | + | |
| 155 | + | |
157 | 156 | | |
158 | 157 | | |
159 | | - | |
| 158 | + | |
| 159 | + | |
160 | 160 | | |
161 | 161 | | |
162 | 162 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
49 | 49 | | |
50 | 50 | | |
51 | 51 | | |
52 | | - | |
| 52 | + | |
53 | 53 | | |
54 | 54 | | |
55 | | - | |
56 | | - | |
| 55 | + | |
| 56 | + | |
57 | 57 | | |
58 | 58 | | |
59 | 59 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
39 | 39 | | |
40 | 40 | | |
41 | 41 | | |
42 | | - | |
| 42 | + | |
43 | 43 | | |
44 | 44 | | |
45 | 45 | | |
| |||
0 commit comments