Repository navigation
Commit ddd646d
feat(scenarios): a scenario card carries a tier (control | starter | delivery); starter and delivery cards meet the gallery floor (#31091)
Fixes #30970
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:每张场景卡新增必填字段 `tier`(`control`、`starter`、`delivery` 三选一)。三张简单对照卡标为
`control`,六张中等场景卡标为 `starter`。加载器拒收没有 `tier` 的卡,也拒收低于「图库下限」的 `starter` 或
`delivery` 卡,逐条指出差在哪个字段。
-
为什么改:按维护者裁决「我接受你的建议」,对照卡只做内部质量检查,永不导出或展示;中等卡作为图库的入门模板。此前卡片上没有任何字段区分两者,导出器将来可能把只有
2 个对象、8 行数据的对照应用当成产品发布。
- 风险与回滚:只改私有包 `@objectstack/scenarios`(不发布)和 `docs/qa/scenarios/`
下的九张卡与说明;不碰 `src/export/**` 与 `src/runner/**`,导出器今天仍不读这个字段。回滚即整体 revert
本 PR。
- 先看:① `packages/qa/scenarios/src/loader.ts` 的 `GALLERY_FLOOR` 与
`checkGalleryFloor`,以及 countsReason 规则对图库卡不再生效的那一处;②
`packages/qa/scenarios/src/schema.ts` 的 `tier` 字段;③
`packages/qa/scenarios/test/refusals.test.ts` 末尾的下限判别测试。
- 两分钟验证:`pnpm --filter @objectstack/scenarios exec vitest run
test/refusals.test.ts`,预期全部通过;其中 "the gallery floor" 一组 13 条:恰在下限的
starter 与 delivery 卡加载通过,任一条低一格的卡恰好得到一条拒收。
- 需要你做的:无,席位落地。
## What changes
**The field.** `tier` is a card-level key (outside `expect`, so the
scorer's shape is untouched), a closed enum `control | starter |
delivery`, required on every card. A card without one is refused at
`tier` with the closed set named; any other value is refused with zod's
"expected one of". `SCENARIO_TIERS`, `GALLERY_TIERS` (`starter`,
`delivery`) and `isGalleryTier` are exported from `src/schema.ts`, so
the exporter's filter can read the same set and does not need to spell
it again.
**The floor.** The loader holds a `starter` or `delivery` card to
`GALLERY_FLOOR` (`src/loader.ts`). Each line it falls short of is its
own refusal, at the field that falls short, and the refusal names the
floor, the card's count and the fix (raise the card, or declare it
`control`):
| Line | Floor | Refused at |
|:---|:---|:---|
| expected objects | at least 5 | `expect.objects` |
| expected dashboards | at least 1 | `expect.dashboards` |
| rows on the largest seeded object | at least 100 | `run.seed` |
| personas with a row `scope` | at least 2 | `run.personas` |
| questions | at least 8 | `run.questions` |
| operations | at least 4 | `run.operations` |
| agent actions | at least 3 | `run.agentActions` |
`delivery` holds the same floor until the delivery-grade list sets its
own. A `control` card has no floor. A `countsReason` does not lower the
floor on a gallery card. The default band's "state why in countsReason"
refusal is therefore not raised on a gallery card, because it would tell
the author to do something that cannot lift the refusal.
**Why these numbers, not the card's example.** The card's example floor
was at least 5 objects, 100 seed rows, 10 questions and 3 personas. The
ruling makes the mid-tier cards the `starter` tier, and
`docs/qa/scenarios/README.md` already states the mid-tier floor those
six cards meet. So the loader enforces the lines of that floor that can
be counted from the card, and the library states one floor rather than
two. The differences from the example:
- 8 questions, not 10: the README's band is 8 to 10.
- At least 2 row-scoped personas instead of 3 personas: the README asks
for 2 or 3 roles with a row scope.
- 100 rows on one object rather than 100 across the seed: the README
asks for 100 on the main object.
- Dashboard, operation and agent-action lines added, because the README
floor states them too.
Moving any number is one constant and one README line.
Measured at objectstack@719a502b, before this change (the floor's lines
per card):
| Card | Tier | Objects | Dashboards | Largest object | Scoped personas
| Questions | Operations | Agent actions |
|:---|:---|---:|---:|---:|---:|---:|---:|---:|
| `crm_account_with_contacts` | control | 2 | 0 | 5 | 1 | 8 | 5 | 3 |
| `invoice_with_line_items` | control | 3 | 0 | 5 | 1 | 9 | 5 | 3 |
| `project_with_tasks` | control | 2 | 0 | 6 | 1 | 8 | 5 | 3 |
| `asset_lifecycle` | starter | 8 | 1 | 297 | 2 | 10 | 6 | 6 |
| `leave_balances` | starter | 7 | 1 | 307 | 2 | 10 | 6 | 4 |
| `order_to_cash` | starter | 8 | 1 | 240 | 2 | 10 | 6 | 5 |
| `requisition_to_receipt` | starter | 8 | 1 | 184 | 2 | 10 | 6 | 5 |
| `service_desk` | starter | 8 | 1 | 249 | 3 | 10 | 6 | 4 |
| `travel_expense` | starter | 7 | 1 | 280 | 2 | 10 | 6 | 4 |
The card's own reading holds: the six measure 7 to 8 objects, 496 to 757
seed rows in total, 10 questions and 3 personas each.
**The cards and the READMEs.** The nine cards each gain one `"tier"`
line after `"code"` (a text insertion, so the compact seed rows keep
their layout). `docs/qa/scenarios/README.md` gains a Tiers section with
the floor, and states that the exporter does not read `tier` yet and
exports no card at all today (`src/export/generic.ts`). The package
README names the floor on the loader's line.
**Not in this PR.** The exporter's filter on `tier` (#30349 owns it).
The delivery-grade scenario list and any delivery-specific floor, which
go to the maintainer for review first. The Chinese-UI requirement, which
the maintainer withdrew: 「中文界面要求 不需要」.
## Tests
- `test/refusals.test.ts`: two shape cases (no `tier`; a tier outside
the closed set). A top-level `describe` for the floor raises the control
card to exactly the floor on all seven lines and checks that it loads
clean as `starter` and as `delivery`. Then one case per line lowers that
line by one step and gets exactly one refusal, at the field that falls
short. A `countsReason` case shows the floor is not lowered. A
`delivery` case shows the same floor applies. The motivating card (two
objects, eight rows) declared `starter` is refused at exactly its four
short lines.
- `test/library.test.ts`: the three controls, and only they, are
`control`.
- Each mid-tier card's "meets the mid-tier floor" test now also pins
`tier: starter`.
## Acceptance notes
- **Changeset: `skip-changeset`.** `@objectstack/scenarios` is `private:
true`, and `docs/qa/` ships in no package, so nothing publishes. Earlier
PRs on this package carried a `patch` changeset; this one follows
AGENTS.md's criterion instead.
- The README's mid-tier floor also says "an approval or automation
flow", "a seed spanning three months", a question and operation mix, and
"declarative first". None of these can be counted from the card. They
stay as authoring guidance, pinned in each card's own test.
- The README's line "at least one report or dashboard" is enforced as
one `expect.dashboards` entry, because the card format has no way to
state a report.
- The six per-card floor tests now overlap the loader's countable lines.
I kept them because they also pin the lines that cannot be counted.
- Existing wording slip, not touched: "How truth is computed" says the
computed truth "has one of three shapes", then lists five.
- `Clause-②: no` and `Metadata-protocol: none` are copied from the
claim. The card format is a private devx instrument with no
`packages/spec` obligation, and no published consumer reads it (the CLI
file that names the package only mentions it in a comment).
## Verification
All readings below are at head `58f8f32e`, in
objectstack-ai/objectstack. `origin/main` was still at the base
`719a502b` when the gates ran.
<details><summary>Package suite and typecheck</summary>
```text
pnpm --filter @objectstack/scenarios build && pnpm --filter @objectstack/scenarios test
check-dts-emitted: @objectstack/scenarios - 10/10 declared declaration file(s) present.
Test Files 23 passed (23)
Tests 357 passed (357)
os-verify-lock: VERDICT command-exit 0
pnpm --filter @objectstack/scenarios typecheck (tsc --noEmit) -> VERDICT command-exit 0
tsc --listFiles counts test/refusals.test.ts, test/library.test.ts, test/travel-expense.test.ts: 3 of 3
```
The first run, before this package's own `dist/` existed, failed one
suite (`test/build/built-consumer.test.ts`: "build
@objectstack/scenarios first"), which is a prerequisite and not a
regression. It went green after the package build above.
</details>
<details><summary>Ablations (three behaviours, each mutated on disk with
scripts/ablation-replace.mjs, then restored)</summary>
Tests import `../src/index.js`, so a `src/` mutation reaches the subject
with no rebuild.
```text
A1 loader.ts: `if (gallery) checkGalleryFloor(...)` -> `if (gallery && false) ...`
anchor 1 -> 0, blob 457c98e -> 2824a0caf452
test/refusals.test.ts: Tests 10 failed | 63 passed (73) -- every floor case red; the at-floor controls stay green
restored: blob == HEAD (457c98e), `git diff HEAD` empty
A2 schema.ts: `tier: ScenarioTierSchema,` -> `tier: ScenarioTierSchema.optional(),`
anchor 1 -> 0, blob c50b65e -> 89135e96ed87
Tests 1 failed | 72 passed (73) -- "refuses a card with no tier"
restored: blob == HEAD (c50b65e), `git diff HEAD` empty
A3 loader.ts: band rule no longer skipped for gallery cards
anchor 1 -> 0, blob 457c98e -> ca8f95cfa6b5
Tests 2 failed | 71 passed (73) -- "7 questions", "3 operations": expected length 1 but got 2 (more diagnostics, the predicted direction)
restored: blob == HEAD (457c98e), `git diff HEAD` empty
After all three: git status --porcelain is empty; both files hash to their HEAD blob.
```
</details>
<details><summary>Derived gates (node scripts/pm/dispatch-gates.mjs
--repo objectstack-ai/objectstack --commands)</summary>
```text
52 command(s) derived from 21 changed path(s), 289 changed lines (+280 / -9)
50 exit 0
2 exit 3 (PREREQUISITE NOT MET, read as NOT MEASURED):
node scripts/check-plugin-teardown-shape.mjs --self-test -- its positive control is pinned to a commit a shallow clone cannot reach (checker-health only)
pnpm check:dual-build-cjs-loads -- reads every package's dist/; this tree built only this package's closure
dispatch-gates --ran: 52 derived famil(ies) accounted for, 50 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3), 0 UNRUN
```
For the second, as a targeted reading only (not the gate):
`require('packages/qa/scenarios/dist/index.cjs')` loads, and it exports
`SCENARIO_TIERS`, `GALLERY_TIERS`, `GALLERY_FLOOR` and `isGalleryTier`.
CI runs both gates over a full build. CI check-runs had not concluded
when this PR was opened.
</details>
---
_Generated by [Claude
Code](https://claude.ai/code/session_012MmDsRzowAnXEmogPGSEKA)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 51992df commit ddd646d
21 files changed
Lines changed: 280 additions & 9 deletions
File tree
- docs/qa/scenarios
- packages/qa/scenarios
- src
- test
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
36 | 36 | | |
37 | 37 | | |
38 | 38 | | |
39 | | - | |
| 39 | + | |
| 40 | + | |
40 | 41 | | |
41 | 42 | | |
42 | 43 | | |
43 | 44 | | |
44 | 45 | | |
45 | 46 | | |
46 | | - | |
| 47 | + | |
| 48 | + | |
47 | 49 | | |
48 | 50 | | |
49 | 51 | | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
50 | 75 | | |
51 | 76 | | |
52 | 77 | | |
| |||
138 | 163 | | |
139 | 164 | | |
140 | 165 | | |
141 | | - | |
| 166 | + | |
142 | 167 | | |
143 | 168 | | |
144 | 169 | | |
145 | 170 | | |
146 | 171 | | |
147 | 172 | | |
148 | 173 | | |
149 | | - | |
150 | | - | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
151 | 177 | | |
152 | 178 | | |
153 | 179 | | |
| |||
164 | 190 | | |
165 | 191 | | |
166 | 192 | | |
167 | | - | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
168 | 196 | | |
169 | 197 | | |
170 | 198 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
| 5 | + | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
| 4 | + | |
4 | 5 | | |
5 | 6 | | |
6 | 7 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
| 4 | + | |
4 | 5 | | |
5 | 6 | | |
6 | 7 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
| 5 | + | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
| 5 | + | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
| 4 | + | |
4 | 5 | | |
5 | 6 | | |
6 | 7 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
| 5 | + | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
| 5 | + | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
| 5 | + | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
| |||
0 commit comments